Merge branch 'codex/simp-prune-tools-prompt-surface' into codex/simp-drop-assembled-section-order

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md

packages/cordis/tool-cordis/README.md

@@ -12,7 +12,7 @@ Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-cata
 
 ## Trust stance
 
-The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. These traps steer honest code onto the cordis services; they do not contain a mount that goes looking — the host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are reachable functions, so mount code can reach the host realm and Node through one of them, which is fine because `ctx` is fully privileged anyway. The `ctx` a mounted plugin's `apply` receives is a whitelist façade — register tools, observe events, provide/consume services, use timers; framework internals (`ctx.root`, `ctx.fiber`, `ctx.extend`, `ctx.plugin`, …) are withheld — but the capabilities it does expose reach the real runtime, so load this plugin as deliberately as you would grant a bash tool.
+The sandbox isolates globals but is not a security boundary. Node globals are absent or redirect to Cordis services such as `ctx.fs`, `ctx.web`, and `ctx.bash`, and writes to `globalThis` stay local, but host-realm helpers make escape possible. Mounted plugins receive a façade without framework internals, yet its allowed services affect the live runtime. Treat this toolset like bash access; see the [design and trust stance](../../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
 
 ## Config
 

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -77,14 +77,14 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'approval',
-    summary: 'The `ctx.approval` service: dispatches ApprovalRequests to the `approval/request` waterfall and audits every ask/outcome pair to the requesting agent\'s session log.',
+    summary: 'Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session.',
     methods: [
       'async request(req: ApprovalRequest): Promise<ApprovalOutcome>',
     ],
   },
   {
     key: 'bash',
-    summary: 'Abstract bash execution service.',
+    summary: 'Registers one `ctx.bash` implementation.',
     methods: [
       'abstract resolve(request: BashExecRequest): BashExecSpec',
       'abstract run(spec: BashExecSpec): Promise<BashRunResult>',
@@ -99,7 +99,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'codeRuntime',
-    summary: 'Abstract code-execution service.',
+    summary: 'Registers one `ctx.codeRuntime` implementation.',
     methods: [
       'abstract run(request: CodeRunRequest): Promise<CodeRunResult>',
     ],
@@ -114,7 +114,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'fs',
-    summary: 'Abstract filesystem provider service.',
+    summary: 'Abstract filesystem provider.',
     methods: [
       'abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>',
       'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
@@ -136,7 +136,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'permission',
-    summary: 'The permission service (`ctx.permission`).',
+    summary: 'Owns the deployment\'s permission presets and their write path.',
     methods: [
       'current(events: readonly SessionEvent[]): string',
       'resolve(name: string): PresetSpec',
@@ -153,7 +153,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'sessionPersistence',
-    summary: 'Abstract durable session-persistence service.',
+    summary: 'Durable append-only session storage.',
     methods: [
       'abstract create(meta: SessionHeader): Promise<void>',
       'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>',
@@ -206,7 +206,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'systemPrompt',
-    summary: 'Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, and named prompt variables; the agent loop calls `assemble(context)` once per step.',
+    summary: 'Registry service for the prompt inputs assembled before each model step.',
     methods: [
       'section(section: PromptSection): () => void',
       'tools(provider: (context: AssembleContext) => ToolProviderResult): () => void',
@@ -216,7 +216,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'tools',
-    summary: 'Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → guards → `tools/execute` → `tools/post-execute` → `tools/result` pipeline.',
+    summary: 'Tool registry and execution pipeline.',
     methods: [
       'register(definition: ToolDefinition): () => void',
       'restrict(filter: ToolRestriction): () => void',
@@ -246,7 +246,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'workflows',
-    summary: 'Abstract workflow execution service.',
+    summary: 'Workflow execution seam.',
     methods: [
       'abstract start(request: WorkflowStartRequest): WorkflowRun',
     ],
@@ -259,13 +259,13 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/created',
     mode: 'emit',
     signature: '\'agent/created\'(this: Scoped<Agent>, agent: Agent): void',
-    summary: 'An agent\'s fully composed scoped world was published in the AgentRegistry.',
+    summary: 'A fully configured agent and live session were published.',
   },
   {
     name: 'agent/disposed',
     mode: 'emit',
     signature: '\'agent/disposed\'(this: Scoped<Agent>, agent: Agent): void',
-    summary: 'An agent was removed from the registry.',
+    summary: 'An agent left the registry; AgentLoop emits this after driver quiescence but before session detachment and scoped-registration unwind.',
   },
   {
     name: 'agent/error',
@@ -277,37 +277,37 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/pre-step',
     mode: 'serial',
     signature: '\'agent/pre-step\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void',
-    summary: 'Awaited pre-step surface-mutation checkpoint, fired once per step AFTER `turn/start` (and after the prior step closed) but BEFORE this step\'s `step/start` — so anything a listener appends lands OUTSIDE the step, between `turn/start`/`step/end` and the upcoming `step/start`.',
+    summary: 'Awaited serial checkpoint for session-surface mutation after prompt assembly and before `step/start`; appends land outside the pending step.',
   },
   {
     name: 'agent/prompt-submit',
     mode: 'waterfall',
     signature: '\'agent/prompt-submit\'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise<PromptDecision>): Promise<PromptDecision>',
-    summary: 'Waterfall: decide what happens to ONE drained queued message before it becomes a `user/message` — allow (optionally rewriting the prompt bytes or attaching `additionalContext`) or block it.',
+    summary: 'Allow, rewrite, or block one drained prompt before it becomes a user message.',
   },
   {
     name: 'agent/queued',
     mode: 'emit',
     signature: '\'agent/queued\'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void',
-    summary: 'A message entered the agent\'s inbox (queued or steering).',
+    summary: 'Detached, frozen content entered the agent\'s inbox.',
   },
   {
     name: 'agent/request',
     mode: 'waterfall',
     signature: '\'agent/request\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>',
-    summary: 'Waterfall: shape the step\'s call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use).',
+    summary: 'Replace the frozen call configuration.',
   },
   {
     name: 'agent/session-prefix',
     mode: 'waterfall',
     signature: '\'agent/session-prefix\'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>',
-    summary: 'Waterfall: compose the SESSION PREFIX — request-only messages placed in front of the ENTIRE derived history (directly after the provider\'s system slot) on every request this loop instance sends.',
+    summary: 'Compose request-only messages placed before derived history.',
   },
   {
     name: 'agent/session-start',
     mode: 'emit',
     signature: '\'agent/session-start\'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void',
-    summary: 'The agent\'s session lifecycle began, fired once before its first turn.',
+    summary: 'The session lifecycle began, once before the first turn.',
   },
   {
     name: 'agent/status',
@@ -325,37 +325,37 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/turn-continuation',
     mode: 'waterfall',
     signature: '\'agent/turn-continuation\'(this: Scoped<Agent>, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>',
-    summary: 'Waterfall: override the turn-continuation decision via a typed ContinuationDecision.',
+    summary: 'Override whether the turn continues.',
   },
   {
     name: 'agent/turn-stop',
     mode: 'serial',
     signature: '\'agent/turn-stop\'(this: Scoped<Agent>, agent: Agent, turn: number): ContinuationStop | undefined',
-    summary: 'Serial terminal-stop checkpoint after the ordinary `agent/turn-continuation` waterfall, any `continue.reason`, and the pending-steering continuation override have been folded.',
+    summary: 'Monotonic terminal-stop checkpoint after continuation and steering are folded; a stop remains authoritative through turn close and flush: steering queued in that window is discarded, while ordinary sends survive.',
   },
   {
     name: 'approval/request',
     mode: 'waterfall',
     signature: '\'approval/request\'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>',
-    summary: 'Waterfall asking the composed answerers to decide one approval request.',
+    summary: 'Ask composed answerers for one decision.',
   },
   {
     name: 'fs/edit-intent',
     mode: 'waterfall',
     signature: '\'fs/edit-intent\'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>',
-    summary: 'Single-slot decision: produce the optional version guard for the next FileSystem.editText.',
+    summary: 'Single-slot decision for the next FileSystem.editText.',
   },
   {
     name: 'fs/observed',
     mode: 'emit',
     signature: '\'fs/observed\'(target: FsTarget, version: FsVersion, actor: object | undefined): void',
-    summary: 'Record that an actor observed a target at a version, after a successful read/write/edit.',
+    summary: 'Record a successful observation.',
   },
   {
     name: 'fs/write-intent',
     mode: 'waterfall',
     signature: '\'fs/write-intent\'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>',
-    summary: 'Single-slot decision: produce the write intent for the next FileSystem.writeText.',
+    summary: 'Single-slot decision for the next FileSystem.writeText.',
   },
   {
     name: 'llm/stream',
@@ -367,25 +367,25 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'session/created',
     mode: 'emit',
     signature: '\'session/created\'(this: Scoped<Session>, session: Session): void',
-    summary: 'A session was created in the store.',
+    summary: 'Creation announcement during session publication.',
   },
   {
     name: 'session/disposed',
     mode: 'emit',
     signature: '\'session/disposed\'(this: Scoped<Session>, session: Session): void',
-    summary: 'A previously announced session left the store.',
+    summary: 'Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin.',
   },
   {
     name: 'session/event',
     mode: 'emit',
     signature: '\'session/event\'(this: Scoped<Session>, session: Session, event: SessionEvent): void',
-    summary: 'An event was appended to a session log (sync, fire-and-forget).',
+    summary: 'Post-commit, fire-and-forget append feed.',
   },
   {
     name: 'session/flush',
     mode: 'parallel',
     signature: '\'session/flush\'(this: Scoped<Session>, session: Session): Promise<void> | void',
-    summary: 'Awaited durability checkpoint.',
+    summary: 'Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto.',
   },
   {
     name: 'skill/provider-added',
@@ -427,13 +427,13 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'system-prompt/assemble',
     mode: 'waterfall',
     signature: '\'system-prompt/assemble\'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>',
-    summary: 'Waterfall around prompt assembly — mutate or extend the PromptAssembly (sections + tools + variables) before it is rendered.',
+    summary: 'Expert waterfall over the assembled sections, tools, and variables.',
   },
   {
     name: 'system-prompt/change',
     mode: 'emit',
     signature: '\'system-prompt/change\'(): void',
-    summary: 'A section, tool provider, or variable provider was registered or unregistered (the assembly inputs changed — possibly for one scope only).',
+    summary: 'Emitted when any prompt provider changes.',
   },
   {
     name: 'tools/change',
@@ -445,25 +445,25 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'tools/execute',
     mode: 'waterfall',
     signature: '\'tools/execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>',
-    summary: 'Around-dispatch waterfall wrapping the registry\'s core tool dispatch, between the `tools/pre-execute` gate and the `tools/post-execute` seam.',
+    summary: 'Around-dispatch waterfall for timeout, retry, or metrics.',
   },
   {
     name: 'tools/post-execute',
     mode: 'waterfall',
     signature: '\'tools/post-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>',
-    summary: 'Waterfall AFTER a tool runs — where hook plugins inspect the result and accept it (optionally REPLACING the model-facing content, and/or attaching `additionalContext` for the next request) or block it with corrective `feedback` (Claude Code\'s `PostToolUse`).',
+    summary: 'Accept, replace, enrich, or block a normalized dispatch result.',
   },
   {
     name: 'tools/pre-execute',
     mode: 'waterfall',
     signature: '\'tools/pre-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>',
-    summary: 'Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook plugins allow or deny a call (Claude Code\'s `PreToolUse`).',
+    summary: 'Allow, deny, or ask before dispatch.',
   },
   {
     name: 'tools/result',
     mode: 'emit',
     signature: '\'tools/result\'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined',
-    summary: 'Synchronous notification of the authoritative FINAL tool outcome, after the complete pre/execute/post pipeline, final lossless-JSON validation, and outer error normalization.',
+    summary: 'Observe the frozen, lossless-JSON final outcome.',
   },
   {
     name: 'workflow/agent-end',

packages/cordis/tool-cordis/src/fiber-state.ts

@@ -1,15 +1,7 @@
 /**
- * Runtime mirror of the cordis `FiberState` const enum plus human-readable
- * labels, shared by the mount lifecycle (state reporting) and the inspect
- * renderers (plugin-list and mount-table labels).
- *
- * Cordis exposes `FiberState` as a `const enum`: there is no runtime object for
- * Node's type-stripping runner to import, so the members are mirrored here as
- * values — each typed (via the type-only import) as the cordis enum member it
- * mirrors, so enum-typed reads like `fiber.state` compare against them under a
- * shared enum type. Source of truth: vendor/cordis/src/fiber.ts (pinned; drift
- * only happens through a deliberate vendor sync).
- *
+ * Runtime mirror and labels for Cordis's `FiberState` const enum. A const enum has no runtime
+ * object to import, so these values mirror the pinned vendored definition while retaining its
+ * type.
  * @module @deepseek-ai/dsh-tool-cordis/fiber-state
  */
 

packages/cordis/tool-cordis/src/guard.ts

@@ -1,50 +1,14 @@
 /**
- * The registration boundary between sandboxed mount code and the real runtime:
- * SchemaSpec normalization + validation with teaching errors, the
- * marker-guarded `harness.defineTool` / `harness.registerTool` pair, the
- * SANDBOX CONTEXT FAÇADE a mounted plugin's `apply` receives in place of the
- * real `ctx`, and the plugin-shape helpers the mount lifecycle narrows sandbox
- * return values with.
- *
- * The façade is a WHITELIST, not a pass-through proxy. Mount code needs to do
- * exactly four things — register a tool, listen to an event, provide a service,
- * call an injected service (timers included) — so the façade exposes only those
- * verbs and the injected services, each object-valued service individually
- * wrapped (a primitive provided value passes through as-is — see
- * {@link sandboxContext}). Every framework plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`,
- * `events`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) is
- * DENIED with a teaching error rather than passed through. This closes an
- * entire escape class at once: a pass-through proxy that only special-cased
- * `ctx.tools` still handed back the raw context through `ctx.root`,
- * `ctx.extend()`, or a service instance's `.ctx`, and mount code could then
- * `ctx.root.tools.register({…})` to bypass the marker check and host-realm
- * normalization — a raw vm-realm result then errors a real agent turn at the
- * session-log plainness check. The whitelist has no such hole: there is no
- * context-valued member to reach, and any injected-service method that returns
- * a `Context` is rejected (harness services never do — see {@link denyContext}).
- *
- * Two realm facts drive the tool path. Objects built inside the vm carry the vm
- * realm's `Object.prototype`, and the session log's append-time plainness check
- * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects
- * foreign-realm data — so every dynamic tool's `execute` return is JSON
- * round-tripped into the host realm and shape-checked against the two
- * `ToolExecuteReturn` forms before it reaches the registry (the registry
- * trusts the shape blindly — it spreads `result.content`, so an unvalidated
- * `{ content: 'ok' }` would enter the session log as `['o','k']` and silently
- * corrupt the next model request), and the schema itself is rebuilt as fresh
- * host-realm objects. And a malformed tool
- * schema must fail at REGISTRATION, not when a later request assembles it — so
- * dynamic tool registration accepts only definitions produced by the sandbox's
- * `harness.defineTool`, which normalizes `parameters` up front.
- *
- * Normalize, don't lecture, where the input has exactly one meaning: models
- * write the JSON-Schema dialect by strong prior (the `{ type: 'object',
- * properties, required: […] }` wrapper, `type: 'integer'`, `required: false`),
- * and each rejection costs a model turn — so those convert to the SchemaSpec
- * DSL silently, and only genuinely meaningless input (an unknown type, a
- * non-boolean `required`) is rejected, with the error enumerating the valid
- * vocabulary.
+ * The registration boundary between sandboxed mount code and the real runtime: SchemaSpec
+ * normalization + validation with teaching errors, the marker-guarded `harness.defineTool` /
+ * `harness.registerTool` pair, the SANDBOX CONTEXT FAÇADE a mounted plugin's `apply` receives
+ * in place of the real `ctx`, and the plugin-shape helpers the mount lifecycle narrows sandbox
+ * return values with. The façade is a whitelist of lifecycle-safe verbs and declared services;
+ * framework internals and context-valued service returns are denied.
  *
+ * VM-realm schemas are rebuilt as host objects, and tool results are JSON-round-tripped and
+ * shape-checked before session logging. Common JSON-Schema spellings are normalized when they
+ * have one meaning; invalid vocabulary fails during registration with a teaching error.
  * @module @deepseek-ai/dsh-tool-cordis/guard
  */
 
@@ -102,7 +66,7 @@ function normalizeSchemaProp(value: unknown, path: string, forceRequired = false
   }
   // On an object property a JSON-Schema-style `required` ARRAY names required
   // children (handled by the nested unwrap below); everywhere else `required`
-  // must be a boolean, and `false` simply reads as optional.
+  // must be a boolean, and `false` means optional.
   const nestedRequiredArray = type === 'object' && Array.isArray(value.required)
   if (value.required !== undefined && typeof value.required !== 'boolean' && !nestedRequiredArray) {
     throw new Error(`harness.defineTool ${path}.required must be a boolean when present`)
@@ -195,14 +159,11 @@ function assertExecuteReturn(value: unknown): ToolExecuteReturn {
 }
 
 /**
- * The `harness.defineTool` handed into the sandbox: the real DSL, with
- * `parameters` normalized into a fresh host-realm SchemaSpec (JSON-Schema
- * wrapper unwrapped, `integer` mapped, `required: false` dropped) and the
- * tool's `execute` return normalized into the host realm via a JSON round-trip
- * (see the module doc). The round-trip projects the return onto exactly what
- * the log would durably store, and {@link assertExecuteReturn} then vets that
- * projection — so a non-JSON-serializable OR wrong-shape return surfaces as
- * that one call's teaching error instead of poisoning the turn.
+ * The `harness.defineTool` handed into the sandbox: the real DSL, with `parameters` normalized
+ * into a fresh host-realm SchemaSpec (JSON-Schema wrapper unwrapped, `integer` mapped,
+ * `required: false` dropped) and the tool's `execute` return normalized into the host realm
+ * via a JSON round-trip. Non-JSON or wrong-shape output fails that call instead of poisoning
+ * the session log.
  * @param options - the standard `defineTool` options; `parameters` may be the SchemaSpec DSL or a JSON-Schema-style wrapper.
  * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts.
  */
@@ -236,15 +197,9 @@ export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void {
 }
 
 /**
- * The verbs a mounted plugin may reach through the sandbox `ctx` façade,
- * beyond its injected services. `on`/`once` observe events, `provide` exposes
- * a service to other mounts, and the timer helpers schedule work — each a
- * fiber effect that unwinds on unmount. Everything else on a real cordis `ctx`
- * is framework plumbing and is denied. Forwarded LAZILY: the timer helpers are
- * mixin accessors that throw `without inject` when read on a plugin that did
- * not inject `timer`, so the façade reads `ctx[verb]` only at call time — the
- * plugin that never touches a timer never trips that, and one that does gets
- * cordis's own inject error at the call site.
+ * The verbs a mounted plugin may reach through the sandbox `ctx` façade, beyond its injected
+ * services. `on`/`once` observe events, `provide` exposes a service to other mounts, and the
+ * timer helpers schedule work — each a fiber effect that unwinds on unmount.
  */
 const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce'])
 
@@ -258,11 +213,7 @@ const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setT
  * name/description/parameters view as `schemas()`, and nothing invocable.
  */
 function sandboxTools(ctx: Context): Record<string, unknown> {
-  // Reads resolve through the MOUNT's own scope (`scopeOf(ctx)`), mirroring
-  // where the façade's `register` lands its writes (the calling context's
-  // layer): mount code always sees the tools its own world sees — the global
-  // view for today's global mounts, its agent's view if a mount ever runs
-  // under an agent scope.
+  // Resolve reads and writes through the mount's own scope.
   return {
     register: (tool: unknown): (() => void) => sandboxRegisterTool(ctx, tool),
     schemas: () => ctx.tools.schemas(scopeOf(ctx)),
@@ -320,15 +271,8 @@ function declaredInjects(ctx: Context): Set<string> {
 }
 
 /**
- * The sandbox context façade handed to a mounted plugin's `apply` in place of
- * the real `ctx`. A whitelist (see the module doc): the registration/eventing
- * verbs, the timer helpers, a guarded `tools`, and injected services resolved
- * through a guarded `get` / property access. A service is reachable only if the
- * plugin DECLARED it in `inject` — an undeclared service is denied even when a
- * global provider exists, so cordis's activation/unload semantics (park the
- * mount when a declared provider goes away) actually bind. Every
- * framework-plumbing member is denied with a teaching error; there is no
- * context-valued member to reach.
+ * Whitelist context for mounted plugins: lifecycle-safe verbs, guarded tools, and only declared
+ * injected services. Framework plumbing is denied, and service methods cannot return a Context.
  */
 function sandboxContext(ctx: Context): Context {
   const tools = sandboxTools(ctx)
@@ -348,16 +292,8 @@ function sandboxContext(ctx: Context): Context {
       + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.',
     )
   }
-  // Read a service for either access path (property or `get`). `tools` is the
-  // façade's own surface. An UNDECLARED name is denied with the teaching
-  // error; a DECLARED one resolves to the guarded service. A declared inject
-  // is required in cordis (the fiber only activates once every declared
-  // service is live), so at `apply`/`execute` time `ctx.get(name)` is present
-  // for a declared name — no undefined case to handle here. `provide()`
-  // accepts ANY value though (cross-mount composition advertises
-  // `ctx.provide('name', value)`), so a primitive or null value passes
-  // through unwrapped: Proxy throws on a non-object target, and only an
-  // object can carry a method that hands back a Context.
+  // Read a service for either access path (property or `get`). `tools` is the façade's own
+  // surface.
   const readService = (name: string): unknown => {
     if (name === 'tools') return tools
     if (!declared.has(name)) return denyRead(name)
@@ -408,20 +344,11 @@ export function isPlugin(value: unknown): value is Plugin {
 }
 
 /**
- * Wrap a plugin so its `apply` receives the sandbox context façade instead of
- * the real `ctx` (see {@link sandboxContext} and the module doc). Both
- * function-form and object-form plugins go through the same wrap; the plugin's
- * own `inject` declaration is preserved (cordis reads it from the plugin
- * object, and pending/active gating happens on the real fiber before `apply`
- * runs), so cross-mount provide/inject works unmodified.
- *
- * `ctx.effect(customCleanup)` is deliberately absent from the façade for now —
- * `on` / `provide` / `tools.register` cover every mount seen so far, and each
- * is already a fiber effect. FIXME(sandbox-effect): expose a guarded `effect`
- * once a real mount needs a bespoke disposer.
+ * Wrap a plugin so `apply` receives the sandbox context while preserving injection metadata.
  * @param plugin - the plugin the mount code returned.
  * @returns an equivalent plugin whose `apply` sees the sandbox context façade.
  */
+// FIXME(sandbox-effect): expose guarded custom effects when a mount needs bespoke cleanup.
 export function guardedPlugin(plugin: Plugin): Plugin {
   if (typeof plugin === 'function') {
     const functionPlugin = plugin as (ctx: Context, config?: unknown) => unknown

packages/cordis/tool-cordis/src/index.ts

@@ -1,37 +1,9 @@
 /**
- * The self-referential cordis toolset: three model-facing tools that let the
- * agent inspect and MODIFY the live cordis runtime it is running inside.
- *
- * - `cordis_inspect` — read-only: provided services, the flat plugin list
- *   with lifecycle states, registered tools, the dynamic mounts, and the
- *   catalog-backed `api` / `events` references.
- * - `cordis_mount` — evaluate model-written code in a `node:vm` sandbox; the
- *   code returns a cordis plugin, which is mounted as a child of a dedicated
- *   `cordis-dynamic` group fiber and tracked under an id (`dyn-1`, `dyn-2`, …).
- * - `cordis_unmount` — dispose one dynamic mount by id, awaiting quiescence.
- *
- * Everything the model's plugin registers (listeners via `ctx.on`, tools via
- * `harness.registerTool`, services via `ctx.provide`) is an effect on the
- * dynamic fiber, so unmounting — or disposing this plugin itself (HMR) — cleans
- * it all up through the ordinary cordis lifecycle. The group fiber exists
- * exactly so the dynamic mounts form ONE subtree, disposed as a unit with
- * this plugin. Design home:
- * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
- *
- * The vm sandbox guards against ACCIDENTAL global pollution only, and the `ctx`
- * a mounted plugin's `apply` receives is a WHITELIST façade (register a tool,
- * observe events, provide/consume services, use timers — framework internals
- * withheld; see the guard module). Neither is a security boundary: the verbs
- * the façade DOES expose reach the real runtime unsandboxed (a mounted tool can
- * shell out through `ctx.bash`), so a deployment loads this plugin as
- * deliberately as it grants a bash tool. Design home:
- * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
- *
- * Plugin export shape: named exports, NO default. The cordis Loader's
- * `unwrapExports` does `exports.default ?? exports`, so a stray default would
- * collapse the module to the bare `apply` and drop `inject`, crashing at load
- * (see docs/postmortem/0001).
- *
+ * Self-referential runtime tools: inspect live services/plugins/tools, mount a returned plugin
+ * under an owned dynamic fiber, and unmount it to quiescence. Registrations are fiber effects,
+ * so plugin disposal removes the entire dynamic subtree. The VM and context façade prevent
+ * accidental misuse, not hostile code: an allowed service such as `ctx.bash` reaches the real
+ * runtime. Named exports preserve loader injection metadata.
  * @module @deepseek-ai/dsh-tool-cordis
  */
 
@@ -75,9 +47,7 @@ type ResolvedConfig = Required<Config>
  */
 export function apply(ctx: Context, config: Config): void {
   const { vmTimeoutMs } = config as ResolvedConfig
-  // The one group fiber every dynamic mount hangs under. Mounted here (a child
-  // of this plugin's fiber) so disposing tool-cordis cascades over the whole
-  // dynamic subtree — the ordinary parent→child fiber lifecycle, nothing extra.
+  // The one group fiber every dynamic mount hangs under.
   const group = ctx.plugin({ name: 'cordis-dynamic', apply: () => {} })
 
   const mounts = new Map<string, DynamicMount>()

packages/cordis/tool-cordis/src/inspect.ts

@@ -1,11 +1,7 @@
 /**
- * Read-only renderers over the live runtime for `cordis_inspect`: the service
- * list, the flat plugin list, the registered tools, the dynamic-mount
- * table (with per-mount provides/waits), and the catalog-backed `api` /
- * `events` sections. Every renderer is a pure function of the runtime handles
- * it receives — no session state, no clock — so inspect output is exactly the
- * runtime it describes.
- *
+ * Read-only renderers over the live runtime for `cordis_inspect`: the service list, the flat
+ * plugin list, the registered tools, the dynamic-mount table (with per-mount provides/waits),
+ * and the catalog-backed `api` / `events` sections.
  * @module @deepseek-ai/dsh-tool-cordis/inspect
  */
 
@@ -131,16 +127,13 @@ function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEn
 }
 
 /**
- * The `api` section: the generated service catalog intersected with the LIVE
- * runtime — catalogued live services render summary + method signatures, live
- * services without a catalog entry (e.g. ones another mount provides) render
- * name + owning fiber, catalog services that are not running are listed
- * tersely, the type shapes the live signatures reference follow, and the
- * inherited `ctx` surface closes the section.
+ * Render the generated catalog against the live runtime: live catalogued services with methods,
+ * uncatalogued live services with owners, absent loadable services, referenced type shapes, and
+ * inherited Context APIs.
  * @param ctx - the runtime to intersect the catalog with.
- * @param api - the service catalog (the generated one by default; injectable for tests).
- * @param inherited - the inherited `ctx` surface lines (generated by default; injectable for tests).
- * @param types - the type-shape catalog (generated by default; injectable for tests).
+ * @param api - generated service entries, replaceable in tests.
+ * @param inherited - inherited `ctx` entries, replaceable in tests.
+ * @param types - public type shapes, replaceable in tests.
  * @returns the section lines.
  */
 export function describeApi(

packages/cordis/tool-cordis/src/mount.ts

@@ -21,11 +21,8 @@ export interface DynamicMount {
 }
 
 /**
- * Mount a plugin under the group fiber and settle it. The group fiber loads
- * asynchronously right after the owning plugin's `apply`, so it is awaited
- * before hanging a child off its context. The child fiber's `await()` settles
- * its lifecycle work and rethrows a startup error (e.g. a throwing `apply`);
- * on error the fiber is disposed first — a failed mount never lingers.
+ * Await the group, mount and settle one guarded child, and dispose it before rethrowing any
+ * startup failure so a failed mount never lingers. A valid unresolved inject may remain pending.
  * @param group - the `cordis-dynamic` group fiber every mount hangs under.
  * @param plugin - the plugin the sandbox returned; wrapped with the registration guard before mounting.
  * @returns the settled child fiber (possibly pending on unsatisfied `inject`).

packages/cordis/tool-cordis/src/sandbox.ts

@@ -1,20 +1,10 @@
 /**
- * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose
- * globals are a tagged write-through console, the `harness` registration
- * helpers, the encoding primitives a bare vm context lacks, and callable traps
- * over the Node APIs the sandbox deliberately withholds. Capability access is
- * routed through cordis services, never Node built-ins: filesystem work goes
- * through `ctx.fs`, network through `ctx.web`, processes through `ctx.bash`,
- * timers through the `ctx.timer` helpers (fiber effects, unwound on unmount)
- * — so a well-behaved mount stays inspectable and disposable. That routing is
- * STEERING toward the cordis services, not containment: the sandbox guards
- * against ACCIDENTAL global pollution, and it is not a security boundary. The
- * host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are
- * reachable functions, so a mount that goes looking — e.g. through such a
- * helper's `.constructor` — can still reach the host realm; that is accepted,
- * because the `ctx` a mounted plugin's `apply` later receives is the real,
- * fully privileged runtime handle, and that is the point of the toolset.
- *
+ * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose globals are a
+ * tagged write-through console, the `harness` registration helpers, the encoding primitives a
+ * bare vm context lacks, and callable traps over the Node APIs the sandbox deliberately
+ * withholds. Traps steer filesystem, network, process, and timer work to `ctx.fs`, `ctx.web`,
+ * `ctx.bash`, and Cordis timers. This keeps cooperative mounts inspectable and disposable but
+ * is not containment: host-realm helper functions remain an escape route.
  * @module @deepseek-ai/dsh-tool-cordis/sandbox
  */
 
@@ -35,17 +25,8 @@ function taggedConsole(id: string): Record<'log' | 'info' | 'warn' | 'error' | '
 }
 
 /**
- * Per-sandbox prelude: give the vm realm's own constructors a
- * `Symbol.hasInstance` that checks BOTH realms. Model code runs against a
- * fresh vm realm, but most objects it touches are HOST-realm (the `args` a
- * tool's `execute` receives, event payloads a listener observes, service
- * return values), so a plain `x instanceof Array` / `instanceof Object` in
- * sandbox code would silently be false. The patch replaces each vm
- * constructor's own `[Symbol.hasInstance]` with "ordinary check against the
- * vm constructor OR the host counterpart" — the ordinary algorithm is a pure
- * prototype-chain walk, so calling it with the host constructor as receiver
- * needs no host-side change. ONLY vm-realm globals are modified; host
- * intrinsics are passed in as values and never touched.
+ * Patch only VM constructors so `instanceof` accepts both VM values and host values passed as
+ * arguments, events, or service results; host intrinsics remain untouched.
  */
 const DUAL_REALM_INSTANCEOF_PRELUDE = `
 (hostIntrinsics) => {
@@ -156,13 +137,10 @@ export function syntaxErrorContext(error: Error): string {
 }
 
 /**
- * Evaluate mount code as the body of an async function inside the sandbox.
- * `vmTimeoutMs` only bounds the SYNCHRONOUS portion; an async body escapes it
- * — acceptable under the module's trust stance. A parse failure is answered
- * with the offending line + caret and a teaching hint: TypeScript syntax on
- * the failing line gets the remove-annotations fix, anything else gets the
- * function-body/bracket-balance reminder (models habitually close the returned
- * plugin object with `});` as if it were a callback argument).
+ * Evaluate mount code as the body of an async function inside the sandbox. `vmTimeoutMs` only
+ * bounds the SYNCHRONOUS portion; an async body escapes it — acceptable under the module's
+ * trust stance. Parse errors include the offending line and a TypeScript-removal or bracket-
+ * balance hint.
  * @param sandbox - the contextified object from {@link createSandbox}.
  * @param code - the model-written function body; must `return` a plugin.
  * @param id - the mount id, used as the vm filename (`cordis-mount-<id>.js`).

packages/cordis/tool-cordis/tests/mount.spec.ts

@@ -48,12 +48,7 @@ describe('cordis_mount', () => {
   })
 
   it('normalizes a self-made tool\'s result into the host realm, so the session log accepts it', async () => {
-    // The model's execute builds its content blocks INSIDE the vm, where
-    // Object.prototype is a different object — dsh-session's isJsonValue (the
-    // gate every `tool/result` append runs through) compares prototype
-    // IDENTITY, so a raw foreign-realm result would error the whole turn the
-    // first time the self-made tool runs. harness.defineTool round-trips the
-    // return into host-realm JSON before it reaches the registry.
+    // VM-realm objects fail the session prototype-identity check; normalize them into host JSON.
     const ctx = await setup()
     await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE })
     const reversed = await call(ctx, 'reverse_text', { text: 'harness' })
@@ -94,11 +89,8 @@ describe('cordis_mount', () => {
     ['object-form blocks missing the type tag', 'return { content: [{ text: \'hi\' }] }', '{"content":[{"text":"hi"}]}'],
     ['undefined — a forgotten return', 'return undefined', 'undefined'],
   ])('rejects an execute return of %s as that one call\'s teaching error', async (_label, returnStatement, preview) => {
-    // The failure this prevents: the registry trusts the return shape
-    // (postExecute spreads result.content), so an unvalidated { content: 'ok' }
-    // would enter the session log as ['o','k'] and silently corrupt the next
-    // model request. The shape check turns it into THIS call's error instead —
-    // one well-formed text block the log and the model can digest.
+    // The registry spreads result.content, so { content: 'ok' } would become ['o','k']; reject
+    // it as this call's error before it corrupts the next request.
     const ctx = await setup()
     await call(ctx, 'cordis_mount', {
       code: `
@@ -150,10 +142,8 @@ describe('cordis_mount', () => {
   })
 
   it('accepts a JSON-Schema-style parameters wrapper and normalizes it to the DSL', async () => {
-    // The dialect models write by strong prior: the { type:'object',
-    // properties, required: […] } wrapper, `type: 'integer'`, and
-    // `required: false`. All of it has exactly one meaning — normalize instead
-    // of burning a model turn on a lecture.
+    // These common JSON-Schema spellings each have one DSL meaning, so normalize rather than
+    // consume another model turn with a rejection.
     const ctx = await setup()
     const result = await call(ctx, 'cordis_mount', {
       code: `
@@ -535,10 +525,9 @@ describe('cordis_mount', () => {
   })
 
   it('makes instanceof inside the sandbox see BOTH realms (patched vm constructors, host untouched)', async () => {
-    // The args a tool's execute receives are HOST-realm objects; without the
-    // dual-realm Symbol.hasInstance prelude, `args.items instanceof Array` in
-    // sandbox code is silently false. The patch lives on the vm realm's own
-    // constructors only — the host realm's must stay pristine.
+    // The args a tool's execute receives are HOST-realm objects; without the dual-realm
+    // Symbol.hasInstance prelude, `args.items instanceof Array` in sandbox code is silently
+    // false.
     const ctx = await setup()
     await call(ctx, 'cordis_mount', {
       code: `

packages/cordis/tool-cordis/tests/sandbox-context.spec.ts

@@ -2,13 +2,10 @@ import { describe, expect, it } from 'vitest'
 import { call, setup, text } from './helpers.ts'
 
 /**
- * The sandbox context façade is a whitelist, not a pass-through proxy: mount
- * code reaches only the registration/eventing verbs, the timer helpers, a
- * guarded `tools`, and its injected services. Every framework-plumbing member
- * that could hand back an UNGUARDED context — through which a plugin could
- * `ctx.<escape>.tools.register({…})` to bypass the marker check and host-realm
- * normalization — is denied. These are the regression guards for that escape
- * class (the review finding on the original pass-through proxy).
+ * The sandbox context façade is a whitelist, not a pass-through proxy. Mounted code reaches only
+ * registration/eventing verbs, timer helpers, guarded tools, and injected services. Framework
+ * members that expose an unguarded context are denied because they could bypass marker checks and
+ * host-realm normalization; these tests pin that escape class.
  */
 
 /** Mount a plugin whose `apply` touches one framework member, and report the error text. */
@@ -77,10 +74,8 @@ describe('sandbox context façade — escape surface is closed', () => {
 
   it('denies a service whose method returns a Context (the .ctx escape), registering nothing', async () => {
     // A cordis Service instance carries `.ctx` (a real Context), so
-    // `ctx.systemPrompt.ctx.root.tools.register(…)` would be a fresh unguarded
-    // handle. The service wrapper's return-value guard rejects any Context on
-    // the way back to sandbox code, so the escape never lands. (`systemPrompt`
-    // is in the setup harness, so the plugin activates and its apply runs.)
+    // `ctx.systemPrompt.ctx.root.tools.register(…)` would escape the façade; service-return
+    // guards reject that Context before the registration lands.
     const ctx = await setup()
     const result = await call(ctx, 'cordis_mount', {
       code: `
@@ -104,10 +99,8 @@ describe('sandbox context façade — escape surface is closed', () => {
   })
 
   it('guards an async injected-service method: a host-realm Promise resolves through the guard', async () => {
-    // The return guard's Promise arm only fires for a HOST-realm Promise
-    // (a vm-realm one is not `instanceof` the host `Promise`). Provide a
-    // host-realm service from the test, then inject + await it from a mount:
-    // the resolved value is non-Context data and passes through.
+    // The return guard's Promise arm only fires for a HOST-realm Promise (a vm-realm one is not
+    // `instanceof` the host `Promise`).
     const ctx = await setup()
     ctx.plugin({
       name: 'host-async-svc',
@@ -194,11 +187,8 @@ describe('sandbox context façade — inject gate on services', () => {
   })
 
   it('a cross-mount consumer must declare the provider — the undeclared path is refused, not left as a zombie tool', async () => {
-    // The finding's scenario: a consumer registers a tool built on a provider's
-    // service WITHOUT declaring inject. cordis would then never park the
-    // consumer when the provider unmounts, leaving a tool that fails only at
-    // execution. The gate refuses the undeclared access up front, so the
-    // dependency is always visible to cordis.
+    // Without declared inject, Cordis cannot park the consumer when its provider unmounts. The
+    // façade refuses access up front instead of leaving a zombie tool.
     const ctx = await setup()
     await call(ctx, 'cordis_mount', {
       code: 'return { name: \'greeter-provider\', apply(ctx) { ctx.provide(\'greeter\', { greet: (n) => \'hi \' + n }) } }',
@@ -231,11 +221,9 @@ describe('sandbox context façade — inject gate on services', () => {
 
 describe('sandbox tools façade — get is a read-only schema view', () => {
   it('ctx.tools.get returns a schema, not the live ToolDefinition with execute', async () => {
-    // The finding: returning the raw ToolDefinition hands mount code the
-    // tool's execute function, letting it bypass ToolRegistry.execute (and its
-    // pre/post hooks). get now returns the same name/description/parameters
-    // view as schemas(), with no execute. Asserted via a self-made tool that
-    // reports the shape it saw — world-checked, not self-reported.
+    // The finding: returning the raw ToolDefinition hands mount code the tool's execute
+    // function, letting it bypass ToolRegistry.execute (and its pre/post hooks). get now
+    // returns the same name/description/parameters view as schemas(), with no execute.
     const ctx = await setup()
     await call(ctx, 'cordis_mount', {
       code: `