comisai 1.0.44 → 1.0.46

package/node_modules/@comis/agent/dist/spawn/sub-agent-runner.js

@@ -16,7 +16,7 @@ import { createCoordinatorProgressFork, } from "./coordinator-progress-fork.js";
 import { sanitizeAssistantResponse } from "../provider/response/sanitize-pipeline.js";
 import { randomUUID } from "node:crypto";
 import { classifyAbortReason, buildAnnouncementMessage, deliverAnnouncement, deliverFailureNotification, validateOutputs, sweepResultFiles, persistFailureRecord, } from "./sub-agent-result-processor.js";
-import { comparePosture } from "./sandbox-posture.js";
+import { comparePosture, SandboxDowngradeError } from "./sandbox-posture.js";
 import { steerRun as steerRunHelper } from "./steer-run.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -48,14 +48,15 @@ export const ANNOUNCE_PARENT_TIMEOUT_MS = 300_000;
  *                   last-resort raw key keeps the resolver's empty-field guard
  *                   from tripping)
  *
- * WR-01 (175-REVIEW.md): the prior formula used "sub-agent" for channelType and
- * `run.announceChannelId ?? parsed?.channelId` for channelId, which DIVERGED
- * from the registration key. For steer (steer-run.ts) that miss was FATAL
+ * PITFALL: a formula using "sub-agent" for channelType or
+ * `run.announceChannelId ?? parsed?.channelId` for channelId DIVERGES
+ * from the registration key. For steer (steer-run.ts) that miss is FATAL
  * (the inject's whole purpose is to reach the live handle); for the kill /
- * ghost-sweep / watchdog aborts below it was a silent best-effort no-op
- * (latent). Aligning the formula fixes steer AND makes those aborts actually
- * reach the handle. Keep this BYTE-IDENTICAL to steer-run.ts:deriveCompositeForRun
- * -- the 175-00 spike fails loudly on drift.
+ * ghost-sweep / watchdog aborts below it is a silent best-effort no-op
+ * (latent). Keeping the formula aligned makes steer work AND lets those aborts
+ * actually reach the handle. Keep this BYTE-IDENTICAL to
+ * steer-run.ts:deriveCompositeForRun — the resolution spike
+ * (sub-agent-runner.steer-resolve.spike.test.ts) fails loudly on drift.
  */
 function deriveCompositeForRun(run) {
     const parsed = parseFormattedSessionKey(run.sessionKey);
@@ -98,7 +99,7 @@ export function createSubAgentRunner(deps) {
     const runs = new Map();
     const activePromises = new Set();
     // -------------------------------------------------------------------------
-    // Phase 216 (DUR-01 / HB-01): durable checkpoint + keep-alive heartbeat.
+    // Durable checkpoint + keep-alive heartbeat.
     // Inert when `deps.durableRuns` is absent (the default install). The
     // heartbeat timer is tracked per runId so the terminal `finally` clears it
     // (no leaked interval). Store calls are best-effort — a write error is
@@ -107,17 +108,17 @@ export function createSubAgentRunner(deps) {
     const heartbeatTimers = new Map();
     const DURABLE_KEEPALIVE_MS = deps.durability?.keepAliveMs ?? 30_000;
     /**
-     * Derive the MED-4 `cronOrigin` from the REAL cron signal threaded onto the
+     * Derive the `cronOrigin` from the REAL cron signal threaded onto the
      * spawn params (`isCronAgentTurn` + `jobId`/`jobName`). A cron-fired turn's
      * sub-agent records the firing job's id; a non-cron spawn records null. There
-     * is NO `cronOrigin` string at HEAD — this IS the derivation.
+     * is NO `cronOrigin` string parameter — this IS the derivation.
      */
     function deriveCronOrigin(params) {
         return params.isCronAgentTurn === true ? (params.jobId ?? params.jobName ?? "cron") : null;
     }
     /**
-     * Write the initial durable checkpoint at the SPAWN BOUNDARY (DUR-01) and start
-     * the keep-alive heartbeat (HB-01). `stepIndex` starts at -1 (the never-sent
+     * Write the initial durable checkpoint at the SPAWN BOUNDARY and start
+     * the keep-alive heartbeat. `stepIndex` starts at -1 (the never-sent
      * sentinel — the outward counter is owned by allocateOutwardStep, NOT here).
      * Inert when no store is wired. Never throws.
      */
@@ -157,8 +158,8 @@ export function createSubAgentRunner(deps) {
             .catch((err) => {
             deps.logger?.warn({ rootRunId, err, hint: "durable checkpoint upsert threw — the run still proceeds", errorKind: "internal" }, "Durable checkpoint: upsert threw (run continues)");
         });
-        // HB-01: a keep-alive that fires INDEPENDENT of step/spawn completion so a
-        // long-running child never trips the watchdog's stale threshold (Pitfall 4).
+        // A keep-alive that fires INDEPENDENT of step/spawn completion so a
+        // long-running child never trips the watchdog's stale threshold.
         // One interval per run, cleared on terminal settle (no leaked timer).
         if (!heartbeatTimers.has(run.runId)) {
             const handle = timers.setInterval(() => {
@@ -175,7 +176,7 @@ export function createSubAgentRunner(deps) {
         }
     }
     /**
-     * Terminal seam (DUR-01): mark the run completed + clear its keep-alive
+     * Terminal seam: mark the run completed + clear its keep-alive
      * heartbeat. Fires on EVERY terminal settle of a started run (completion,
      * failure, kill/ghost/watchdog — the underlying executeAgent promise still
      * settles), so the interval is reclaimed and the durable record stops being
@@ -199,7 +200,7 @@ export function createSubAgentRunner(deps) {
         }), "durable terminal markCompleted (best-effort)");
     }
     // -------------------------------------------------------------------------
-    // COORD-03: the ~30s read-only progress fork (coordinator-progress-fork.ts).
+    // The ~30s read-only progress fork (coordinator-progress-fork.ts).
     // One fork per running child, tracked by runId so the terminal `finally`
     // stops it (no leaked timer — the fork's interval is .unref()'d). The fork is
     // a READ-ONLY summary of the in-flight child's advance — it never re-executes,
@@ -213,7 +214,7 @@ export function createSubAgentRunner(deps) {
      * is a thin read of the run's live step counter — `run.result` is only
      * populated on completion (by which point the fork is already stopped), so an
      * in-flight tick reports `stepsExecuted: 0` and the elapsed wall-clock is the
-     * advance signal (RESEARCH: a count-only advance is still NOT a re-execution).
+     * advance signal (a count-only advance is still NOT a re-execution).
      * Idempotent per runId. No model call, no tool, no spawn.
      */
     function startProgressFork(run, params) {
@@ -235,7 +236,7 @@ export function createSubAgentRunner(deps) {
      * Stop + reclaim a child's progress fork on its terminal settle. Idempotent +
      * inert when none was started (e.g. a queued run that never ran). Mirrors
      * finishDurableCheckpoint's terminal-seam discipline — the fork never outlives
-     * the child (T-218-15).
+     * the child.
      */
     function stopProgressFork(run) {
         const fork = progressForks.get(run.runId);
@@ -244,8 +245,8 @@ export function createSubAgentRunner(deps) {
         fork.stop();
         progressForks.delete(run.runId);
     }
-    // WR-02: make the fail-OPEN observable. The sandbox no-downgrade gate (below)
-    // silently no-ops when `resolvePosture` is absent — a P0 security control that
+    // Make the fail-OPEN observable. The sandbox no-downgrade gate (below)
+    // silently no-ops when `resolvePosture` is absent — a critical security control that
     // does nothing. Production composition (setup-cross-session-runtime.ts) ALWAYS
     // injects the resolver (a daemon-wiring test pins this), but a future second
     // construction path could omit it and ship an inert gate. Emit a one-time
@@ -320,8 +321,8 @@ export function createSubAgentRunner(deps) {
     // Proxy typing stop helper (avoids repeating guard+emit in 5 paths)
     // -------------------------------------------------------------------------
     /**
-     * Release a run's reserved tree-wide ceiling slot EXACTLY ONCE (Phase 213
-     * CR-02). Pairs 1:1 with the `checkSpawnCeiling` acquire recorded on the run.
+     * Release a run's reserved tree-wide ceiling slot EXACTLY ONCE.
+     * Pairs 1:1 with the `checkSpawnCeiling` acquire recorded on the run.
      * Clearing `ceilingSlotAcquired` first makes this idempotent across the several
      * terminal paths a single run can traverse (kill marks failed, then the
      * underlying executeAgent promise later settles and fires `execPromise.finally`
@@ -351,7 +352,7 @@ export function createSubAgentRunner(deps) {
     // -------------------------------------------------------------------------
     const SWEEP_INTERVAL_MS = 300_000;
     const MAX_RUNS = 1000;
-    // WR-01: DLQ recovery sink — when a dead-lettered announcement is finally
+    // DLQ recovery sink — when a dead-lettered announcement is finally
     // re-delivered on drain(), record its idempotency key in the shared
     // deliveredKeys set so a later failure sweep (deliverFailureNotification)
     // does not double-notify the same run. No-op when no shared dedup is wired.
@@ -501,7 +502,7 @@ export function createSubAgentRunner(deps) {
                     task: run.task,
                     runtimeMs: runningDurationMs,
                     runId,
-                    callerSessionKey: run.callerSessionKey, // DELIVERY-03: shared dedup key
+                    callerSessionKey: run.callerSessionKey, // shared dedup key
                     // eslint-disable-next-line no-restricted-syntax -- intentional fire-and-forget
                 }, deps).catch(() => { });
             }
@@ -548,11 +549,11 @@ export function createSubAgentRunner(deps) {
         const currentDepth = params.depth ?? 0;
         const maxDepth = params.maxDepth ?? deps.config.subagentContext?.maxSpawnDepth ?? 3;
         const isGraphSpawn = params.callerType === "graph";
-        // Establish the tree-stable rootRunId (CEIL-01/REVOKE-03 foundation). The root
+        // Establish the tree-stable rootRunId. The root
         // (the first caller with no rootRunId) mints one; every descendant MUST pass its
         // parent's id down via params.rootRunId. We mint whenever it is absent — regardless
         // of depth — so a missing id never silently splits a tree into per-spawn ids that
-        // each escape the parent's ceiling (RESEARCH Pitfall 1). Uses the injected
+        // each escape the parent's ceiling. Uses the injected
         // ClockPort (never the wall-clock global — the globals.test.ts arch-gate).
         const rootRunId = params.rootRunId ?? `root-${params.agentId}-${clock.now().toString(36)}`;
         // Depth check (applies to ALL spawns including graph)
@@ -649,7 +650,7 @@ export function createSubAgentRunner(deps) {
                 throw new RequiredToolsUnreachableError(unreachable);
             }
         }
-        // Sandbox no-downgrade gate (SANDBOX-02). The single fail-closed posture
+        // Sandbox no-downgrade gate. The single fail-closed posture
         // check at the spawn chokepoint: a spawned child may never be LESS confined
         // than its spawner. Placed AFTER the required_tools gate and BEFORE the
         // children/queue branch, so ONE check fires before any `runs.set` / runId /
@@ -661,9 +662,9 @@ export function createSubAgentRunner(deps) {
         // state). Inert when `resolvePosture` is absent (older test wiring) or for a
         // top-level spawn (no parent posture to compare against). Posture is resolved
         // via the INJECTED `deps.resolvePosture` dep — the runner never reaches
-        // `config.agents[...]` (D-RESOLVEDEP).
+        // `config.agents[...]`.
         //
-        // ORDERING (IN-02, intentional): this fail-closed gate runs BEFORE the
+        // ORDERING (intentional): this fail-closed gate runs BEFORE the
         // children/queue branch and the allowlist check (line ~1051). A spawn that is
         // BOTH a downgrade AND not-allowlisted is therefore attributed to the
         // downgrade refusal. We keep this order on purpose: both branches refuse the
@@ -683,15 +684,15 @@ export function createSubAgentRunner(deps) {
                     agentId: params.agentId,
                     parentAgentId: params.callerAgentId,
                     childAgentId: params.agentId,
-                    // Enum labels only — never posture values/paths/hosts (§2.7).
+                    // Enum labels only — never posture values/paths/hosts in log fields.
                     violatedDimensions: cmp.violatedDimensions,
                     hint: `Spawn refused: child sandbox posture is less confined than its spawner on ${violated}; ` +
                         "align the child's skills sandbox config or set security.agentToAgent.sandboxNoDowngrade:false to disable",
                     errorKind: "precondition",
                 }, "Sub-agent spawn refused: sandbox downgrade");
-                // Typed refusal event (SANDBOX-03): both postures as enum TUPLES + the
+                // Typed refusal event: both postures as enum TUPLES + the
                 // violated dimension labels + the two agent ids — labels only, NO
-                // paths/hosts/uid-numbers/credential values (§2.7 / T-172-01f). Fires
+                // paths/hosts/uid-numbers/credential values. Fires
                 // here, before the throw, at the exact point a run/session would
                 // otherwise be created. comparePosture's violatedDimensions feeds it.
                 deps.eventBus.emit("security:sandbox_downgrade_refused", {
@@ -703,7 +704,10 @@ export function createSubAgentRunner(deps) {
                     childPosture,
                 });
                 // @allow-throw: spawn() consumed exclusively by daemon RPC handlers; @allow-throw boundary.
-                throw new Error(`Spawn refused: child "${params.agentId}" sandbox posture is less confined than parent "${params.callerAgentId}" on: ${violated}.`);
+                // Typed: classifyRpcError maps SandboxDowngradeError to
+                // precondition/warn — this fail-closed SECURITY refusal must NOT read as an
+                // internal/error handler fault in an operator's ERROR-level health sweep.
+                throw new SandboxDowngradeError(`Spawn refused: child "${params.agentId}" sandbox posture is less confined than parent "${params.callerAgentId}" on: ${violated}.`, cmp.violatedDimensions);
             }
         }
         // Children check (bypassed for graph spawns)
@@ -821,11 +825,11 @@ export function createSubAgentRunner(deps) {
             }
         }
         // 1. Allowlist check.
-        // WR-03 (213-REVIEW): hoisted ABOVE the ceiling acquire below. The allowlist
+        // Deliberately hoisted ABOVE the ceiling acquire below. The allowlist
         // check has NO side effects and can throw; if it ran AFTER the ceiling
-        // reserve (the prior order), a not-allowlisted spawn would reserve a slot and
+        // reserve, a not-allowlisted spawn would reserve a slot and
         // then throw with no run ever created — so no completion `finally` would ever
-        // release it (a slot leak the instant CR-02's release landed). Refusing here,
+        // release it (a slot leak). Refusing here,
         // before any reserve, keeps the acquire the LAST gate before run creation so
         // every successful acquire is paired 1:1 with a run that will release it.
         if (deps.config.allowAgents.length > 0 &&
@@ -838,11 +842,11 @@ export function createSubAgentRunner(deps) {
             // @allow-throw: spawn() consumed exclusively by daemon RPC handlers.
             throw new Error(`Agent "${callerLabel}" is not allowed to spawn "${params.agentId}". Allowed: ${deps.config.allowAgents.join(", ")}`);
         }
-        // Tree-wide spawn ceiling (CEIL-01). The SINGLE consult both session.spawn
+        // Tree-wide spawn ceiling. The SINGLE consult both session.spawn
         // AND graph.* AND the in-process agent loop hit (they all reach here via
         // runner.spawn), keyed on the tree-stable rootRunId — so a for(;;) spawn()
         // is bounded across the whole tree, not just one caller. Placed AFTER the
-        // per-caller depth/children/queue gates AND the allowlist (WR-03) and BEFORE
+        // per-caller depth/children/queue gates AND the allowlist and BEFORE
         // any runId/session is created, so it rejects with the SAME shape as the
         // depth/children gates (event + WARN + no run/session) and is the LAST gate
         // before run creation (every acquire pairs 1:1 with a releasing run). The
@@ -855,7 +859,7 @@ export function createSubAgentRunner(deps) {
             const ceiling = deps.checkSpawnCeiling(rootRunId, currentDepth, ceilingFanout);
             if (ceiling.ok) {
                 // The consult RESERVED a slot (tryAcquireSpawn increments on ok). Record
-                // it so the run's terminal transition releases it 1:1 (CR-02). This is the
+                // it so the run's terminal transition releases it 1:1. This is the
                 // last gate before run creation, so a successful acquire is always paired
                 // with a run that will release.
                 ceilingSlotAcquired = true;
@@ -994,7 +998,7 @@ export function createSubAgentRunner(deps) {
                 graphToolNames: params.graphToolNames ?? [],
                 graphNodeDepth: params.graphNodeDepth,
                 isLeafNode: params.isLeafNode ?? false,
-                // WT-01: carry the worktree request onto the child session metadata so
+                // Carry the worktree request onto the child session metadata so
                 // executeSubAgent (the only place that holds the GitExec seam + the
                 // workspace resolver) can run the child in an isolated git worktree.
                 // Defaults to false so the no-worktree path stays byte-identical.
@@ -1005,12 +1009,12 @@ export function createSubAgentRunner(deps) {
         run.sessionKey = formattedKey;
         run.status = "running";
         run.startedAt = clock.now();
-        // Phase 216 (DUR-01 / HB-01): the SPAWN BOUNDARY — the run is now registered
+        // The SPAWN BOUNDARY — the run is now registered
         // + running, so write the initial durable checkpoint (stepIndex -1) + start
         // the keep-alive heartbeat. Inert when no durable store is wired. The keep-
         // alive is cleared + the record marked completed in the terminal `finally`.
         startDurableCheckpoint(run, params);
-        // COORD-03: start the ~30s read-only progress fork so a long-running child
+        // Start the ~30s read-only progress fork so a long-running child
         // surfaces its advance (a content-free session:sub_agent_progress) WITHOUT
         // completing. Stopped in the terminal `finally` (no leaked timer). Runs
         // independent of the durable store.
@@ -1174,18 +1178,18 @@ export function createSubAgentRunner(deps) {
                         }, "ResultCondenser failed");
                     }
                 }
-                // Phase 218 (SUMREF-02): materialize the child's FULL output to its OWN
+                // Materialize the child's FULL output to its OWN
                 // jailed workspace as a structured ResultRef, so the lead's announcement
                 // grows by a bounded summary + a HANDLE, never the megabyte body (the
-                // longevity invariant). The condenser (SUMREF-01 summary) and the store
-                // (SUMREF-02 handle) are complementary — both run. The drill-in line that
+                // longevity invariant). The condenser (summary) and the store
+                // (handle) are complementary — both run. The drill-in line that
                 // follows the summary defaults to the condenser's diskPath: the genuine
                 // "no store wired / no handle produced" path (no store to materialize
                 // through, so the on-disk condensed result IS the handle — NOT a shim).
                 let fullResultLine = condensedResult ? `\n\nFull result: ${condensedResult.diskPath}` : "";
                 // The successful handle (when produced) — threaded into the NarrativeCaster
                 // path too, so the production-default tagged announcement also carries the
-                // handle, not the diskPath (SUMREF-02 longevity invariant on every path).
+                // handle, not the diskPath (the longevity invariant on every path).
                 let materializedRef;
                 if (condensedResult && deps.materializeFullOutput) {
                     const materialized = await deps.materializeFullOutput(result.response, { runId, nowMs: clock.now(), agentId: params.agentId });
@@ -1354,7 +1358,7 @@ export function createSubAgentRunner(deps) {
                             task: params.task,
                             runtimeMs,
                             runId,
-                            callerSessionKey: params.callerSessionKey, // DELIVERY-03: shared dedup key
+                            callerSessionKey: params.callerSessionKey, // shared dedup key
                         }, deps);
                     }
                 }
@@ -1375,7 +1379,7 @@ export function createSubAgentRunner(deps) {
                                 tokensUsed: result.tokensUsed.total,
                                 cost: result.cost.total,
                                 sessionKey: formattedKey,
-                                // SUMREF-02: the materialized handle (when produced) so the tagged
+                                // The materialized handle (when produced) so the tagged
                                 // announcement carries the drill-in handle, not the diskPath.
                                 resultRef: materializedRef,
                             });
@@ -1521,7 +1525,7 @@ export function createSubAgentRunner(deps) {
                         task: params.task,
                         runtimeMs,
                         runId,
-                        callerSessionKey: params.callerSessionKey, // DELIVERY-03: shared dedup key
+                        callerSessionKey: params.callerSessionKey, // shared dedup key
                     }, deps);
                 }
                 else {
@@ -1618,7 +1622,7 @@ export function createSubAgentRunner(deps) {
                     task: params.task,
                     runtimeMs,
                     runId,
-                    callerSessionKey: params.callerSessionKey, // DELIVERY-03: shared dedup key
+                    callerSessionKey: params.callerSessionKey, // shared dedup key
                     // eslint-disable-next-line no-restricted-syntax -- intentional fire-and-forget
                 }, deps).catch(() => { });
             }
@@ -1647,19 +1651,19 @@ export function createSubAgentRunner(deps) {
         activePromises.add(execPromise);
         execPromise.finally(() => {
             activePromises.delete(execPromise);
-            // CR-02: release the tree-wide ceiling slot this run reserved (idempotent;
+            // Release the tree-wide ceiling slot this run reserved (idempotent;
             // a no-op for promoted queued runs, which never acquired). This fires for
             // EVERY started run on its terminal settle — completion, failure, AND a
             // kill/ghost/watchdog (those mark the run failed but the underlying
             // executeAgent promise still settles here), so a long-running tree's slots
             // are reclaimed rather than monotonically leaking.
             releaseCeilingSlotOnce(run);
-            // Phase 216 (DUR-01 / HB-01): the SAME universal terminal seam — mark the
+            // The SAME universal terminal seam — mark the
             // durable record completed + clear its keep-alive heartbeat (no leaked
             // interval). Inert + idempotent when no durable store is wired.
             finishDurableCheckpoint(run);
-            // COORD-03: stop the read-only progress fork on the same universal terminal
-            // seam so it never outlives the child (no leaked timer; T-218-15).
+            // Stop the read-only progress fork on the same universal terminal
+            // seam so it never outlives the child (no leaked timer).
             stopProgressFork(run);
             // Drain queue when a slot opens (use abortGroup for graph-scoped draining)
             const drainKey = run.abortGroup ?? run.callerSessionKey;
@@ -1699,7 +1703,7 @@ export function createSubAgentRunner(deps) {
     }
     /**
      * Resolve the running/queued sub-agent run whose child session key equals
-     * `sessionKey` (Phase 213 CR-01). When a sub-agent itself calls
+     * `sessionKey`. When a sub-agent itself calls
      * `sessions_spawn`, the dispatcher injects ITS session key as the spawn's
      * `_callerSessionKey`; that key is exactly the spawning run's `run.sessionKey`.
      * The daemon spawn handler uses this to make a descendant INHERIT its parent
@@ -1827,15 +1831,15 @@ export function createSubAgentRunner(deps) {
         return { killed: true };
     }
     /**
-     * REVOKE-03: hard-stop a whole spawn tree. Fans the per-run {@link killRun}
+     * Hard-stop a whole spawn tree. Fans the per-run {@link killRun}
      * (which marks the run failed and aborts its in-flight SDK session) over every
      * running/queued run sharing `rootRunId`, and returns the count killed.
      *
-     * Filters STRICTLY on `run.rootRunId === rootRunId` (threat T-213-01-02 — a
+     * Filters STRICTLY on `run.rootRunId === rootRunId` (a
      * different tree must be untouched) and on the same status guard killRun uses,
      * so already-terminal runs are skipped. An unknown root is a clean no-op
      * (`{ killed: 0 }`), never a throw — the count return is the contract the
-     * daemon-side `run.kill` RPC handler (the @allow-throw boundary, Plan 06)
+     * daemon-side `run.kill` RPC handler (the @allow-throw boundary)
      * drives; this helper itself raises nothing (the raw-throw.test.ts gate).
      */
     function killByRootRun(rootRunId) {
@@ -1850,17 +1854,18 @@ export function createSubAgentRunner(deps) {
         return { killed };
     }
     /**
-     * STEER-01: inject a steer message into a RUNNING child's live SDK session
+     * Inject a steer message into a RUNNING child's live SDK session
      * (mid-flight steering), distinct from killRun. Delegates to the steer-run.ts
      * helper to keep the mechanism OUT of this (already large) file.
      *
-     * L2 — widen the resolver/registry surface at the delegation boundary: this
+     * Widen the resolver/registry surface at the delegation boundary: this
      * runner's `deps.sessionResolver`/`deps.activeRunRegistry` are typed to the
      * narrowed `{ abort(): Promise<void> }` (the kill path only needs abort, and
      * the narrow type avoids a daemon→agent import cycle in those Deps). steerRun
      * needs the FULL RunHandle (steer/followUp/isStreaming/isCompacting). The
      * RUNTIME handle is complete — pi-executor.ts:1161 builds all five and
-     * registers it under the SAME key the resolver composes (175-00 spike). So
+     * registers it under the SAME key the resolver composes (pinned by
+     * sub-agent-runner.steer-resolve.spike.test.ts). So
      * we re-type the lookups to the full RunHandle at this boundary; this is a
      * pure TS surface widening over an object that already has the methods, not
      * a behavior change.

package/node_modules/@comis/agent/dist/workspace/templates.d.ts

@@ -10,9 +10,9 @@ export type WorkspaceFileName = (typeof WORKSPACE_FILE_NAMES)[number];
  * Platform-owned workspace files — content-hash-refreshed by `ensureWorkspace`
  * on every invocation when the on-disk sha256 differs from `DEFAULT_TEMPLATES`.
  *
- * 2026-05-20 lineage: the prior `wx`-only seed flow let stale pre-fix templates
- * persist forever, so a sub-agent's inherited workspace kept promising a
- * pre-warmed venv that no code provisioned. These three files declare themselves
+ * A `wx`-only seed flow would let stale templates persist forever, so a
+ * sub-agent's inherited workspace could keep promising behavior no code
+ * provisions. These three files declare themselves
  * read-only platform contract in their own prose — this partition makes that
  * contract real.
  */

package/node_modules/@comis/agent/dist/workspace/templates.js

@@ -20,9 +20,9 @@ export const WORKSPACE_FILE_NAMES = [
  * Platform-owned workspace files — content-hash-refreshed by `ensureWorkspace`
  * on every invocation when the on-disk sha256 differs from `DEFAULT_TEMPLATES`.
  *
- * 2026-05-20 lineage: the prior `wx`-only seed flow let stale pre-fix templates
- * persist forever, so a sub-agent's inherited workspace kept promising a
- * pre-warmed venv that no code provisioned. These three files declare themselves
+ * A `wx`-only seed flow would let stale templates persist forever, so a
+ * sub-agent's inherited workspace could keep promising behavior no code
+ * provisions. These three files declare themselves
  * read-only platform contract in their own prose — this partition makes that
  * contract real.
  */

package/node_modules/@comis/agent/dist/workspace/workspace-manager.d.ts

@@ -39,7 +39,7 @@ export interface EnsureWorkspaceOptions {
      * (`[not_read]`) gate.
      *
      * Left undefined at daemon startup (no session yet) — the seeded files will
-     * be registered lazily on first read, same as before.
+     * be registered lazily on first read.
      */
     tracker?: WorkspaceSeedTracker;
 }
@@ -87,9 +87,8 @@ export interface RegisterWorkspaceResult {
  * (before any session tracker exists) and seeds the agent's own workspace
  * files. Every subsequent session's first `write` to those paths would
  * otherwise hit a read-before-write gate. Call this right after the
- * per-session tracker is created (or per-turn, before the session-lifetime
- * registry existed) so the agent's first `write` to its own workspace
- * passes the gate.
+ * per-session tracker is created so the agent's first `write` to its own
+ * workspace passes the gate.
  *
  * Idempotency: when the tracker already records a matching-mtime entry
  * for a path (via the optional `getReadState` method), the helper skips

package/node_modules/@comis/agent/dist/workspace/workspace-manager.js

@@ -51,10 +51,10 @@ function sha256Hex(input) {
  * supplied, the post-rename `tracker.recordRead` call is sufficient observability
  * for the session-aware path (the tracker is consumed by `write` tools).
  *
- * 2026-05-20 lineage: prior to this helper, `ensureWorkspace` only wrote files
- * with the `wx` (exclusive-create) flag. Every existing install kept its
- * pre-fix template forever, including the false-promise venv prose in AGENTS.md
- * that triggered the 06:18-06:25 sub-agent exec cascade. The codebase's own
+ * Without this helper, `ensureWorkspace` would only write files with the `wx`
+ * (exclusive-create) flag, so every existing install would keep its stale
+ * template forever — including drifted prose that promises behavior no code
+ * provides. The workspace's own
  * AGENTS.md prose declares "This file is read-only" -- this helper makes that
  * contract real for the three platform-owned files.
  *
@@ -89,7 +89,7 @@ async function refreshPlatformFiles(dir, tracker) {
             throw err;
         }
         // BOOTSTRAP.md empty-guard: preserve the post-onboarding cleared state.
-        // 2026-05-20 lineage: the agent clears BOOTSTRAP.md via `write` once
+        // The agent clears BOOTSTRAP.md via `write` once
         // onboarding completes; resurrecting it would re-run onboarding on the
         // next ensureWorkspace call.
         if (name === "BOOTSTRAP.md" && onDiskContent.length === 0) {
@@ -181,8 +181,8 @@ export async function ensureWorkspace(options) {
                     tracker.recordRead(filePath, stat.mtimeMs, 0, undefined, Buffer.from(template, "utf-8"));
                 }
                 catch {
-                    // stat failure is non-fatal: skip registration, fall back to
-                    // pre-fix behavior (caller will need to read before overwriting).
+                    // stat failure is non-fatal: skip registration -- the caller will
+                    // need to read the file before overwriting it.
                 }
             }
         }
@@ -192,8 +192,8 @@ export async function ensureWorkspace(options) {
         // Heal stale platform-owned files (SOUL.md, AGENTS.md, non-empty stale
         // BOOTSTRAP.md) whose on-disk sha256 differs from the canonical template.
         // No-op on first-run (writeIfMissing just seeded them at canonical hash).
-        // 2026-05-20: closes the architectural gap where wx-only seeding let stale
-        // pre-fix templates persist forever.
+        // Closes the architectural gap where wx-only seeding would let stale
+        // templates persist forever.
         await refreshPlatformFiles(dir, tracker);
     }
     if (initGit) {
@@ -209,9 +209,8 @@ export async function ensureWorkspace(options) {
  * (before any session tracker exists) and seeds the agent's own workspace
  * files. Every subsequent session's first `write` to those paths would
  * otherwise hit a read-before-write gate. Call this right after the
- * per-session tracker is created (or per-turn, before the session-lifetime
- * registry existed) so the agent's first `write` to its own workspace
- * passes the gate.
+ * per-session tracker is created so the agent's first `write` to its own
+ * workspace passes the gate.
  *
  * Idempotency: when the tracker already records a matching-mtime entry
  * for a path (via the optional `getReadState` method), the helper skips

package/node_modules/@comis/agent/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/agent",
   "private": true,
-  "version": "1.0.44",
+  "version": "1.0.46",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "AI agent executor, budget control, and session management for Comis",

package/node_modules/@comis/channels/dist/__tests__/fakes/discord-fake.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * FakeDiscordAdapter — a deterministic, clock-free `ChannelPort` test double for
- * the Discord EditPlace renderer (§18.1 "fake adapter records every method call").
+ * the Discord EditPlace renderer; it records every method call.
  *
  * Mirrors `createFakeTelegramAdapter` (the canonical fake) but:
  *   - mints `dc-msg-N` ids (Discord's determinism source for byte-stable
- *     fixtures — Pitfall 2),
+ *     fixtures),
  *   - records a `threadCreate` call when `send` is given `{ threadReply: true }`
  *     so a fixture can pin the S7 subagent-expand affordance SHELL (the parent
  *     line + the thread-create), and
@@ -20,7 +20,7 @@
  *
  * The affordance is a SHELL only: this fake records the thread-create egress, but
  * NO interaction handler is registered and NO signed callback_data is produced —
- * the InteractiveCallbackRouter is delivered later (§17.3).
+ * the InteractiveCallbackRouter lives in a separate component.
  */
 import { ok, err } from "@comis/shared";
 /**

package/node_modules/@comis/channels/dist/__tests__/fakes/echo-fake.d.ts

@@ -29,7 +29,7 @@ export interface FakeEchoAdapter extends ChannelPort {
     /**
      * One-shot platform-error injection seam. When set, the NEXT recording call
      * returns `err(nextError)` (the raw platform-shaped object, e.g. a GrammyError
-     * `{error_code,parameters}`) and clears the seam. Lets Wave-2 fakes drive
+     * `{error_code,parameters}`) and clears the seam. Lets the platform fakes drive
      * `classify<Ch>Error`. Echo's own fixtures never set it.
      */
     nextError: unknown;

package/node_modules/@comis/channels/dist/__tests__/fakes/echo-fake.js

@@ -1,16 +1,16 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * FakeEchoAdapter — a deterministic, clock-free `ChannelPort` test double
- * (§18.1 "fake adapter records every method call").
+ * FakeEchoAdapter — a deterministic, clock-free `ChannelPort` test double;
+ * it records every method call.
  *
  * Distinct from the production `EchoChannelAdapter`: the
  * production adapter stamps `systemNowMs()` timestamps (echo-adapter.ts:92),
- * which would make golden fixtures flap (Pitfall 2). This fake records call
+ * which would make golden fixtures flap. This fake records call
  * ORDER only — an ordered, discriminated call-log with deterministic
  * `echo-msg-N` ids and NO timestamps.
  *
- * The `nextError` injection seam is the load-bearing piece Wave-2 channel fakes
- * (Telegram/Discord/Slack/WhatsApp) mirror to exercise their `classify<Ch>Error`
+ * The `nextError` injection seam is the load-bearing piece the platform channel
+ * fakes (Telegram/Discord/Slack/WhatsApp) mirror to exercise their `classify<Ch>Error`
  * functions: set `fake.nextError = <platform-error-shaped object>` and the next
  * adapter call returns it through the `Result` err branch (one-shot). All
  * methods return `Result` — they NEVER throw across the port boundary
@@ -26,7 +26,7 @@ export function createFakeEchoAdapter(channelId = "echo-test") {
     let messageCounter = 0;
     const handlers = [];
     // Consume the one-shot error seam, if armed. Returns the raw platform-shaped
-    // object as an Error-typed err() (cast at the boundary — Wave-2 classifiers
+    // object as an Error-typed err() (cast at the boundary — the platform classifiers
     // read platform fields off it; the port's Result<_, Error> is the contract).
     function takeInjectedError(self) {
         if (self.nextError === undefined || self.nextError === null)

package/node_modules/@comis/channels/dist/__tests__/fakes/email-fake.js

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * FakeEmailAdapter — a deterministic, clock-free `ChannelPort` test double for
- * the Email DigestOnly renderer (§18.3 "fake adapter records every method call").
+ * the Email DigestOnly renderer; it records every method call.
  *
  * Mirrors `createFakeIMessageAdapter` (the send-only template) but for the
  * DigestOnly shape:
  *   - mints `email-msg-N` ids (Email's determinism source for byte-stable
- *     fixtures — Pitfall 2; clock-free, no wall-time call that would flap),
+ *     fixtures; clock-free, no wall-time call that would flap),
  *   - records NO `silent` flag on `send` (Email does not send a silent effect —
  *     DigestOnly emits at most one plain end-of-turn digest body), and
  *   - OMITS `editMessage` / `deleteMessage` entirely. Email is send-only; the

package/node_modules/@comis/channels/dist/__tests__/fakes/imessage-fake.js

@@ -1,13 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * FakeIMessageAdapter — a deterministic, clock-free `ChannelPort` test double for
- * the iMessage AppendOnly renderer (§18.1 "fake adapter records every method
- * call").
+ * the iMessage AppendOnly renderer; it records every method call.
  *
  * Mirrors `createFakeSignalAdapter` (the non-EditPlace template) but for the
  * AppendOnly shape:
  *   - mints `imsg-msg-N` ids (iMessage's determinism source for byte-stable
- *     fixtures — Pitfall 2; clock-free, no wall-time call that would flap),
+ *     fixtures; clock-free, no wall-time call that would flap),
  *   - records NO `silent` flag on `send` (iMessage does not send the silent
  *     effect — AppendOnly posts a single plain opening status), and
  *   - OMITS `editMessage` / `deleteMessage` entirely. iMessage is send-only; the