comisai 1.0.44 → 1.0.46

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-session-registry.d.ts

@@ -1,5 +1,5 @@
 /**
- * The daemon-side TerminalSessionRegistry (spec §2.1, crash isolation).
+ * The daemon-side TerminalSessionRegistry (crash isolation).
  *
  * Owns the `Map<sessionId,SessionHandle>` + the single supervised worker handle.
  * Spawns the Terminal Worker (`terminal-worker-entry.ts`) under the proven
@@ -59,20 +59,20 @@ export interface TerminalSessionRegistryDeps extends ReaperCaps {
     onSpawnFailed?: (info: SpawnFailureInfo) => void;
     /**
      * Called for each decoded {@link TerminalEventFrame} the worker pushes on fd3 (the
-     * no-poll attention channel, 124-05/TR-11) — the seam the daemon (124-09) binds to
+     * no-poll attention channel) — the seam the daemon binds to
      * RE-PUBLISH onto its TypedEventBus (adding `agentId`/`timestamp` the worker is
      * agnostic to). Mirrors {@link onSpawnFailed}: daemon-bound, injected (NOT a
-     * value-imported bus) so the registry stays infra-decoupled. The fd3 reader's HR-02
+     * value-imported bus) so the registry stays infra-decoupled. The fd3 reader's crash
      * guard runs BEFORE this — a corrupt frame drops the worker and never reaches the hook.
      */
     onTerminalEvent?: (frame: TerminalEventFrame) => void;
-    /** Schedule a one-shot timer for the MR-01 reply timeout. Default `systemSetTimeout` from `@comis/core` (the sanctioned indirection — no raw `setTimeout` global); the production default `.unref()`s it so a pending timeout never holds the loop open. */
+    /** Schedule a one-shot timer for the reply timeout. Default `systemSetTimeout` from `@comis/core` (the sanctioned indirection — no raw `setTimeout` global); the production default `.unref()`s it so a pending timeout never holds the loop open. */
     setTimer?: (cb: () => void, ms: number) => unknown;
     /** Cancel a `setTimer` handle (default: `systemClearTimeout`). */
     clearTimer?: (handle: unknown) => void;
     /** Daemon-resolved bwrap path (the jail seam): a STRING, forwarded onto the create frame for the worker's fail-closed branch (undefined ⇒ the worker rejects). */
     bwrapPath?: string;
-    /** RECUR-03 (option A): this daemon generation's PER-BOOT tmux `-S` socket — stamped on a durable
+    /** This daemon generation's PER-BOOT tmux `-S` socket — stamped on a durable
      *  session's handle + descriptor at create so a restart re-attaches it from its OWN server while
      *  new sessions get a fresh per-boot server in the live mount namespace. MUST equal the worker's
      *  `COMIS_TERMINAL_TMUX_SOCKET` env (both daemon-supplied from the same source). Absent ⇒ the
@@ -80,15 +80,15 @@ export interface TerminalSessionRegistryDeps extends ReaperCaps {
     currentTmuxSocket?: string;
     /** Daemon-injected no-secret egress port — the daemon->worker-main seam for `listed-hosts`; a live `net` server, so (unlike bwrapPath) NOT frame-serialized. Type-only from @comis/core. */
     egressControl?: EgressControlPort;
-    /** Allocate a real per-session jail workspace dir (gap 2); default {@link allocateSessionWorkspace} (world-rwx mkdtemp under os.tmpdir()). `create` threads it onto the frame as workspace+cwd so the jail binds RW + --chdirs in (else it defaults to HOME, which uid 65534 cannot use). Injectable for a data-dir-rooted daemon allocator; cleanup is the paired {@link cleanupWorkspace}. */
+    /** Allocate a real per-session jail workspace dir; default {@link allocateSessionWorkspace} (world-rwx mkdtemp under os.tmpdir()). `create` threads it onto the frame as workspace+cwd so the jail binds RW + --chdirs in (else it defaults to HOME, which uid 65534 cannot use). Injectable for a data-dir-rooted daemon allocator; cleanup is the paired {@link cleanupWorkspace}. */
     allocateWorkspace?: (sessionId: string) => string;
     /** Teardown paired with {@link allocateWorkspace}; default {@link cleanupSessionWorkspace} (`rm -rf` the throwaway mkdtemp dir on kill/evict/reap). A daemon rooting the workspace in the agent's OWN persistent workspace MUST inject a NO-OP so the agent's workspace (skills/memory/milestone work) is NOT deleted on session end. */
     cleanupWorkspace?: (workspace: string) => void;
     /**
-     * DUR-01 (165-06): the durability seams (descriptor store + `has-session` probe + the two
+     * The durability seams (descriptor store + `has-session` probe + the two
      * content-free obs hooks), bundled as ONE nested object so the registry deps stay under the
-     * optional-field-bloat cap + the DUR-01 wiring is cohesive. ABSENT (or absent `descriptorStore`)
-     * ⇒ today's wiring (no recover/persist — byte-identical, I1). See {@link TerminalDurabilityDeps}.
+     * optional-field-bloat cap + the durability wiring is cohesive. ABSENT (or absent `descriptorStore`)
+     * ⇒ today's wiring (no recover/persist — byte-identical). See {@link TerminalDurabilityDeps}.
      */
     durability?: TerminalDurabilityDeps;
 }
@@ -116,9 +116,9 @@ export interface CreateRequest {
     /** Project name → the session opens in its own auto-created folder `<agent-workspace>/projects/
      *  <sanitized-slug>` (the session workspace IS the agent's projects root). Takes precedence over `cwd`. */
     project?: string;
-    /** DUR-01 (165-06): `true` for a `drive.durable:true` session — persist a descriptor at create-time (Pitfall 6) + stamp the handle `durable` so the durable-aware {@link markRunningSessionsLost} keeps it recoverable while its tmux is alive (Q4). Absent ⇒ today's spawn session (I1). */
+    /** `true` for a `drive.durable:true` session — persist a descriptor at create-time + stamp the handle `durable` so the durable-aware {@link markRunningSessionsLost} keeps it recoverable while its tmux is alive. Absent ⇒ today's spawn session. */
     durable?: boolean;
-    /** DUR-01 (165-06): the deterministic `comis-<sessionId>` tmux name — the re-attach key persisted in the descriptor + stamped on the handle for the liveness probe (the daemon supplies it with `durable:true`). */
+    /** The deterministic `comis-<sessionId>` tmux name — the re-attach key persisted in the descriptor + stamped on the handle for the liveness probe (the daemon supplies it with `durable:true`). */
     tmuxName?: string;
 }
 export type { TerminalStatusView };
@@ -134,9 +134,9 @@ export interface TerminalSessionRegistry {
     create(req: CreateRequest, owner: SessionOwner): Promise<CreateResult>;
     /** Round-trip a `read` (render opts + screen diff). Owner-scoped: absent/cross-owner → not-found view (alive false), never the other owner's bytes. */
     read(sessionId: string, owner: SessionOwner, opts?: ReadOptions): Promise<TerminalView>;
-    /** Round-trip a `status` (124-06, spec §5) — the worker's classifier perception composed with `handle.lastActivity`. Owner-scoped (T-124-15): absent/cross-owner/killed → the not-found minimal view (`exited`, not parked) WITHOUT a round-trip, never the other owner's state. The classifier stays single-homed in the worker. */
+    /** Round-trip a `status` — the worker's classifier perception composed with `handle.lastActivity`. Owner-scoped: absent/cross-owner/killed → the not-found minimal view (`exited`, not parked) WITHOUT a round-trip, never the other owner's state. The classifier stays single-homed in the worker. */
     status(sessionId: string, owner: SessionOwner): Promise<TerminalStatusView>;
-    /** Forward `send_text` (TR-03) → `{screen,cursor}`. Owner-scoped (defense-in-depth): absent/cross-owner/not-running/wedged → `{screen:"",cursor:{0,0}}`; never hangs. */
+    /** Forward `send_text` → `{screen,cursor}`. Owner-scoped (defense-in-depth): absent/cross-owner/not-running/wedged → `{screen:"",cursor:{0,0}}`; never hangs. */
     sendText(sessionId: string, owner: SessionOwner, args: {
         text: string;
         submit?: boolean;

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-session-registry.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The daemon-side TerminalSessionRegistry (spec §2.1, crash isolation).
+ * The daemon-side TerminalSessionRegistry (crash isolation).
  *
  * Owns the `Map<sessionId,SessionHandle>` + the single supervised worker handle.
  * Spawns the Terminal Worker (`terminal-worker-entry.ts`) under the proven
@@ -34,7 +34,7 @@ import { sameOwner } from "./terminal-session-owner.js";
 import { wireRegistryReaper } from "./terminal-reaper.js";
 import { tmuxSessionName } from "./terminal-tmux-backend.js";
 import { 
-// DUR-01 (165-06): recover-on-boot scan + rehydrate + durable-lost gate (sibling-owned, cap headroom — Pitfall 5).
+// Recover-on-boot scan + rehydrate + durable-lost gate (sibling-owned, cap headroom).
 applyRecoveredSessions, buildSessionDescriptor, markRunningSessionsLost as durableMarkLost, staysRecoverable as durableStaysRecoverable, } from "./terminal-session-reattach.js";
 import { waitReplyTimeoutMs } from "./terminal-settle.js";
 import { mapWaitReply, degradedWaitResult } from "./terminal-wait-reply.js";
@@ -47,7 +47,7 @@ export const DEFAULT_SCROLLBACK = 1000;
 // Injected dependency contracts
 //
 // RegistryLogger + FakeWorkerChild moved to the neutral leaf terminal-session-types.ts
-// (124-01) to break the worker-supervisor import cycle; type-imported above and
+// to break the worker-supervisor import cycle; type-imported above and
 // re-exported so the public surface is unchanged.
 /**
  * Default reply timeout: a `request()` with no correlated reply in this window
@@ -88,7 +88,7 @@ export function createTerminalSessionRegistry(deps) {
             return h;
         });
     const clearTimer = deps.clearTimer ?? ((handle) => systemClearTimeout(handle));
-    // gap 2: per-session jail workspace allocator (default = the real mkdtemp helper).
+    // Per-session jail workspace allocator (default = the real mkdtemp helper).
     const allocateWorkspace = deps.allocateWorkspace ?? ((id) => allocateSessionWorkspace(id).workspace);
     // The paired teardown for `allocateWorkspace` (default = `rm -rf` the throwaway mkdtemp).
     // A daemon rooting the workspace in the agent's OWN persistent dir MUST inject a no-op here.
@@ -107,7 +107,7 @@ export function createTerminalSessionRegistry(deps) {
      * Clear the worker handle and flush its pending waiters (on crash / close). Each synthetic
      * termination reply carries the waiter's REAL `(sessionId,requestId)` from its pending key
      * (not blanked) so an identity-keyed caller cannot mis-handle it; a per-waiter DEBUG records
-     * the flush (the §2.7-observable transition).
+     * the flush (the observable transition).
      */
     function clearWorker() {
         worker = undefined;
@@ -118,7 +118,7 @@ export function createTerminalSessionRegistry(deps) {
             resolve({ sessionId, requestId, ok: false, error: "worker terminated" });
         }
     }
-    // DUR-01 / Q4 — bind the sibling's durable-lost gate (BOTH lost sites: the worker-close flip + the crash-flushed create waiter) to the probe (SAFE default "lost" if unconfirmable, I1).
+    // Bind the sibling's durable-lost gate (BOTH lost sites: the worker-close flip + the crash-flushed create waiter) to the probe (SAFE default "lost" if unconfirmable).
     const isTmuxAliveOrDead = deps.durability?.isTmuxAlive ?? (() => false);
     const staysRecoverable = (handle) => durableStaysRecoverable(handle, isTmuxAliveOrDead);
     const markRunningSessionsLost = () => durableMarkLost(sessions, isTmuxAliveOrDead);
@@ -133,8 +133,8 @@ export function createTerminalSessionRegistry(deps) {
             return worker;
         const child = deps.spawnWorker();
         worker = child;
-        // OPS-01 crash-isolation listeners (HR-02-guarded stdout decoder + error + close) + the
-        // 124-05/TR-11 guarded fd3 events-push reader live in terminal-worker-supervisor.ts (cap
+        // The crash-isolation listeners (guarded stdout decoder + error + close) + the
+        // guarded fd3 events-push reader live in terminal-worker-supervisor.ts (cap
         // headroom); the closure locals + the onTerminalEvent hook ride in as explicit params.
         wireWorkerSupervision({
             child,
@@ -202,7 +202,7 @@ export function createTerminalSessionRegistry(deps) {
     async function create(req, owner) {
         const child = ensureWorker();
         const sessionId = generateSessionId();
-        // gap 2: a REAL per-session jail workspace threaded onto the frame as workspace+cwd
+        // A REAL per-session jail workspace threaded onto the frame as workspace+cwd
         // (see terminal-workspace.ts); ownedWorkspace is set only when WE allocated it (a
         // caller override is theirs) so kill rm's exactly what the registry owns.
         const { workspace, cwd, ownedWorkspace } = resolveCreateWorkspace(req, allocateWorkspace, sessionId);
@@ -220,19 +220,19 @@ export function createTerminalSessionRegistry(deps) {
             // Stamp the origin (owner-scoped list/read/get/kill/send*). The owner rides
             // the HANDLE only — NEVER the worker frame (the worker is owner-agnostic).
             owner,
-            // DUR-01: stamp the durable marker + re-attach key (the durable-aware lost gate, Q4); absent for a spawn session (I1). FINDING-B: the registry DERIVES the deterministic comis-<sessionId> name (the tool cannot — sessionId is generated HERE), so durable engages without the caller supplying tmuxName.
+            // Stamp the durable marker + re-attach key (the durable-aware lost gate); absent for a spawn session. The registry DERIVES the deterministic comis-<sessionId> name (the tool cannot — sessionId is generated HERE), so durable engages without the caller supplying tmuxName.
             ...(req.durable
                 ? {
                     durable: true,
                     tmuxName: req.tmuxName ?? tmuxSessionName(sessionId),
-                    // RECUR-03: stamp this boot's per-boot socket so the daemon probe / reaper target THIS
+                    // Stamp this boot's per-boot socket so the daemon probe / reaper target THIS
                     // session's server, and a future restart re-attaches it from this (now prior-boot) socket.
                     ...(deps.currentTmuxSocket !== undefined ? { tmuxSocket: deps.currentTmuxSocket } : {}),
                 }
                 : {}),
         };
         sessions.set(sessionId, handle);
-        // DUR-01: persist the durable descriptor at CREATE-time, BEFORE the create frame (Pitfall 6 — no orphan window); non-durable persists nothing (I1).
+        // Persist the durable descriptor at CREATE-time, BEFORE the create frame (no orphan window); non-durable persists nothing.
         if (req.durable && deps.durability?.descriptorStore !== undefined) {
             deps.durability.descriptorStore.persist(buildSessionDescriptor({ sessionId, tmuxName: req.tmuxName ?? tmuxSessionName(sessionId), tmuxSocket: deps.currentTmuxSocket, allowId: req.allowId, owner, cols: req.cols, rows: req.rows, createdAt, scope: req.scope }));
         }
@@ -245,7 +245,7 @@ export function createTerminalSessionRegistry(deps) {
             bin: req.bin,
             argv: req.argv,
             // The operator-declared allowId — selects the read-side platform profile in the worker
-            // (RENDER-01 / §5/INV-3: by allowId only). Already on the descriptor; threaded to the worker
+            // (by allowId only). Already on the descriptor; threaded to the worker
             // so the emulator's render transform + the classifier's perception pick the right profile.
             allowId: req.allowId,
             cols: req.cols,
@@ -260,14 +260,14 @@ export function createTerminalSessionRegistry(deps) {
             cwd,
             // The daemon-resolved bwrap path rides the frame for the worker's fail-closed branch (undefined ⇒ no spawn, lost).
             bwrapPath: deps.bwrapPath,
-            ...(req.durable ? { backend: "tmux" } : {}), // FINDING-B: a durable drive selects the tmux backend (terminal-worker-entry.ts reads p["backend"]).
+            ...(req.durable ? { backend: "tmux" } : {}), // A durable drive selects the tmux backend (terminal-worker-entry.ts reads p["backend"]).
         });
         pending.set(`${sessionId}:${createFrame.requestId}`, (reply) => {
             if (reply.ok)
                 return; // backend spawned — leave the session running.
             const h = sessions.get(sessionId);
-            // DUR-01 / Q4: a worker CRASH flushes this waiter with a synthetic `ok:false`; a durable session
-            // whose tmux is STILL alive is NOT a spawn failure → stays recoverable (I10). A real spawn
+            // A worker CRASH flushes this waiter with a synthetic `ok:false`; a durable session
+            // whose tmux is STILL alive is NOT a spawn failure → stays recoverable. A real spawn
             // failure leaves tmux dead ⇒ probe false ⇒ DO flip + fire onSpawnFailed.
             if (h !== undefined && h.status === "running" && staysRecoverable(h))
                 return;
@@ -318,7 +318,7 @@ export function createTerminalSessionRegistry(deps) {
     }
     async function status(sessionId, owner) {
         const handle = ownedHandle(sessionId, owner);
-        // Owner-scoped (T-124-15): a cross-owner / absent / not-running session degrades
+        // Owner-scoped: a cross-owner / absent / not-running session degrades
         // to the not-found view WITHOUT round-tripping a `status` frame — a probe with a
         // guessed sessionId never reaches the worker and never sees another owner's state.
         if (handle === undefined || handle.status !== "running") {
@@ -326,7 +326,7 @@ export function createTerminalSessionRegistry(deps) {
         }
         const reply = await request(sessionId, "status", { sessionId });
         handle.lastActivity = nowMs();
-        // A wedged worker (MR-01 reply timeout) degrades to the not-found view, never hangs.
+        // A wedged worker (reply timeout) degrades to the not-found view, never hangs.
         if (!reply.ok || reply.result === undefined) {
             return notFoundStatus(handle);
         }
@@ -334,7 +334,7 @@ export function createTerminalSessionRegistry(deps) {
         // daemon-side lastActivity (the leaf helper folds the two — keeps this file lean).
         // The `as WorkerStatusPerception` cast is of an UNTRUSTED cross-process reply, so
         // composeStatusView DEFENSIVELY narrows confidence/reason against a malformed /
-        // version-skewed worker before they reach the status surface (LR-03) — the cast is
+        // version-skewed worker before they reach the status surface — the cast is
         // the happy-path type, the fold is the runtime safety net.
         return composeStatusView(reply.result, handle);
     }
@@ -359,12 +359,12 @@ export function createTerminalSessionRegistry(deps) {
      */
     function mapSendReply(handle, reply) {
         if (!reply.ok || reply.result === undefined) {
-            // Not-delivered (WR-05): a wedged worker (the MR-01 reply timeout) — the send
+            // Not-delivered: a wedged worker (the reply timeout) — the send
             // reached no live pane. delivered is left falsy so the audit records "rejected".
             return { screen: "", cursor: { x: 0, y: 0 } };
         }
         handle.lastActivity = nowMs();
-        // The worker round-tripped an ok reply ⇒ the keystroke WAS forwarded (WR-05).
+        // The worker round-tripped an ok reply ⇒ the keystroke WAS forwarded.
         return { ...toSendResult(reply.result), delivered: true };
     }
     async function sendText(sessionId, owner, args) {
@@ -424,7 +424,7 @@ export function createTerminalSessionRegistry(deps) {
             return degradedWaitResult();
         }
         handle.lastActivity = nowMs();
-        // Defensive worker→daemon map (preserves isComplete verbatim; passes T1.1 producing/hint).
+        // Defensive worker→daemon map (preserves isComplete verbatim; passes producing/hint).
         return mapWaitReply(reply.result);
     }
     function get(sessionId, owner) {
@@ -444,7 +444,7 @@ export function createTerminalSessionRegistry(deps) {
     /**
      * Drop a session WITHOUT an owner check — the shared end-of-life path: kill frame (if
      * running), delete the handle, rm the registry-allocated workspace, and drop a durable
-     * session's DESCRIPTOR (BL-03 — a cleanly-killed/evicted durable session is no longer
+     * session's DESCRIPTOR (a cleanly-killed/evicted durable session is no longer
      * re-attachable; the journal is preserved by the daemon holder). `kill` gates on ownership.
      */
     function evictInternal(handle) {
@@ -455,7 +455,7 @@ export function createTerminalSessionRegistry(deps) {
         }
         // A DURABLE session's tmux is DETACHED on a per-boot socket; the worker-IPC "kill" above does
         // NOT reliably terminate it (a never-tasked webhook drive lingered as an idle `claude` after
-        // kill fired — webhook-claude-cli-tdd-20260701), so deterministically kill-session it by name
+        // kill fired), so deterministically kill-session it by name
         // (the path proven to reap it). Best-effort + belt-and-suspenders alongside the worker kill.
         if (handle.durable === true && handle.tmuxName !== undefined) {
             deps.durability?.killTmuxSession?.(handle.tmuxName, handle.tmuxSocket);
@@ -464,7 +464,7 @@ export function createTerminalSessionRegistry(deps) {
         if (handle.workspace !== undefined)
             cleanupWorkspace(handle.workspace);
         if (handle.durable === true)
-            deps.durability?.descriptorStore?.remove(sessionId); // BL-03
+            deps.durability?.descriptorStore?.remove(sessionId);
         logger.info({ sessionId }, "terminal session killed");
     }
     async function kill(sessionId, owner) {
@@ -496,7 +496,7 @@ export function createTerminalSessionRegistry(deps) {
         // Owner-AGNOSTIC: tears down the per-agent registry, dropping every session (the worker is shared across owners).
         for (const handle of Array.from(sessions.values())) {
             if (handle.durable === true)
-                continue; // FINDING-C: PRESERVE a durable session (detached tmux + descriptor) for recover-on-boot re-attach; never kill it on a graceful shutdown.
+                continue; // PRESERVE a durable session (detached tmux + descriptor) for recover-on-boot re-attach; never kill it on a graceful shutdown.
             evictInternal(handle);
         }
         if (worker !== undefined) {
@@ -504,14 +504,14 @@ export function createTerminalSessionRegistry(deps) {
             clearWorker();
         }
     }
-    // DUR-01 recover-on-boot (sibling-owned; no-op without a store, I1). BL-01 (165-REVIEW):
-    // the 4th arg is the worker `reattach` round-trip the sibling drives (worker re-attaches
+    // Recover-on-boot (sibling-owned; no-op without a store).
+    // The 4th arg is the worker `reattach` round-trip the sibling drives (worker re-attaches
     // the surviving pane, NEVER a create; running status + obs hooks gated on its ok).
     if (deps.durability !== undefined)
         applyRecoveredSessions(deps.durability, sessions, nowMs, (id, cols, rows, allowId, tmuxSocket) => 
-        // v2.26: thread the recovered session's allowId so the worker re-resolves its platform profile
+        // Thread the recovered session's allowId so the worker re-resolves its platform profile
         // (render transform + perception) on reattach — without it a durable claude drive reverts to the
-        // agnostic path after a restart (FINDING-3 ghost-strip + perception silently lost).
+        // agnostic path after a restart (ghost-strip + perception silently lost).
         request(id, "reattach", { sessionId: id, cols, rows, allowId, ...(tmuxSocket !== undefined ? { tmuxSocket } : {}) }));
     return { create, read, status, sendText, sendKey, resize, wait, get, list, kill, evict, getOwner: (sessionId) => sessions.get(sessionId)?.owner, size, cleanup };
 }

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-session-types.d.ts

@@ -2,7 +2,7 @@
  * terminal-session-types -- the neutral LEAF type-module for the daemon-side
  * registry's shared structural contracts.
  *
- * Extracted from `terminal-session-registry.ts` (124-01) to break the source-level
+ * Extracted from `terminal-session-registry.ts` to break the source-level
  * import cycle the worker-supervisor extraction introduced: the registry value-imports
  * `wireWorkerSupervision` FROM `terminal-worker-supervisor.ts`, while the supervisor
  * needed `FakeWorkerChild`/`RegistryLogger`/`SessionHandle` back FROM the registry —
@@ -53,9 +53,9 @@ export interface FakeWorkerChild {
     } | null;
     /**
      * The 4-fd stdio array (`["pipe","pipe","pipe","pipe"]`, terminal-worker-launch.ts):
-     * fd0=stdin, fd1=stdout, fd2=stderr, fd3=the events PUSH channel (124-05). The
-     * supervisor reads `stdio[3]` for `TerminalEventFrame`s (the no-poll attention seam,
-     * TR-11). Optional + per-slot-nullable so a fake worker without fd3 (or stderr) is valid
+     * fd0=stdin, fd1=stdout, fd2=stderr, fd3=the events PUSH channel. The
+     * supervisor reads `stdio[3]` for `TerminalEventFrame`s (the no-poll attention seam).
+     * Optional + per-slot-nullable so a fake worker without fd3 (or stderr) is valid
      * — the reader is optional-chained.
      */
     stdio?: ReadonlyArray<WorkerStdioStream | null | undefined>;
@@ -74,39 +74,39 @@ export interface SessionHandle {
     cols: number;
     rows: number;
     lastActivity: number;
-    /** Session start epoch ms (stamped at `create`) — the reaper's wall-clock-age signal (OPS-06). */
+    /** Session start epoch ms (stamped at `create`) — the reaper's wall-clock-age signal. */
     startedAt: number;
     exitCode?: number;
-    /** The registry-allocated per-session jail workspace dir (gap 2), removed best-effort on kill so the throwaway dir does not leak. Set ONLY when the registry allocated it (a caller-supplied workspace is the caller's to clean). */
+    /** The registry-allocated per-session jail workspace dir, removed best-effort on kill so the throwaway dir does not leak. Set ONLY when the registry allocated it (a caller-supplied workspace is the caller's to clean). */
     workspace?: string;
-    /** The origin that owns this session — `(agentId, sessionKey)` (TR-13/TR-09). Stamped at `create`; `list`/`read`/`get`/`kill`/`send*` filter on it (two subagents are mutually invisible). */
+    /** The origin that owns this session — `(agentId, sessionKey)`. Stamped at `create`; `list`/`read`/`get`/`kill`/`send*` filter on it (two subagents are mutually invisible). */
     owner: SessionOwner;
     /**
-     * DUR-01 (165-06): `true` iff this is a `drive.durable:true` session backed by a
+     * `true` iff this is a `drive.durable:true` session backed by a
      * detached tmux server that outlives a worker/daemon close. The durable-aware
      * `markRunningSessionsLost` does NOT flip such a session `lost` while its tmux is
-     * alive (Q4); recover-on-boot rehydrates it `running`. ABSENT/false ⇒ today's
-     * non-durable spawn session (the documented lost floor on a worker close, I1).
+     * alive; recover-on-boot rehydrates it `running`. ABSENT/false ⇒ today's
+     * non-durable spawn session (the documented lost floor on a worker close).
      */
     durable?: boolean;
     /**
-     * DUR-01 (165-06): the deterministic `comis-<sessionId>` tmux session name — the
+     * The deterministic `comis-<sessionId>` tmux session name — the
      * re-attach key the durable-aware `markRunningSessionsLost` probes via the injected
      * `isTmuxAlive` (a durable handle with a live tmux name stays recoverable, not
      * `lost`). Present only for a durable session (set at create-time + on rehydrate).
      */
     tmuxName?: string;
     /**
-     * RECUR-03 (option A): the explicit `-S` socket path this durable session's tmux server is bound
+     * The explicit `-S` socket path this durable session's tmux server is bound
      * to — the PER-BOOT socket of the daemon generation that created it. The daemon's per-session
      * `isTmuxAlive` probe + the worker's re-attach target THIS socket, so a restart re-attaches the
      * surviving session from its OWN (prior-boot) server while new sessions get a fresh per-boot
-     * server in the live mount namespace (RECUR-02). Set at create-time + rehydrated on recover;
+     * server in the live mount namespace. Set at create-time + rehydrated on recover;
      * absent ⇒ the boot socket fallback. Present only for a durable tmux session.
      */
     tmuxSocket?: string;
     /**
-     * LOOP-CLOSURE (webhook-claude-cli-tdd, 2026-06-30): `true` once the agent has DELIVERED a task
+     * `true` once the agent has DELIVERED a task
      * to this drive — set on the first delivered `send_text` (NOT `send_key`, which is gate/menu
      * navigation, not a task). The wait tool feeds it to `shouldPromoteDrive` as `everTasked`: a
      * never-tasked `detached` durable drive must NOT background at its first (gate/idle) wait, which
@@ -143,7 +143,7 @@ export interface TerminalView {
     /** The per-read screen-diff vs the prior read. ADDITIVE: present when an emulator snapshot exists; the not-found/degraded early returns omit it. */
     diff?: SnapshotDiff;
 }
-/** The post-action snapshot subset returned by `sendText`/`sendKey` (spec §5) — `{screen,cursor}`, a strict subset of {@link TerminalView}. */
+/** The post-action snapshot subset returned by `sendText`/`sendKey` — `{screen,cursor}`, a strict subset of {@link TerminalView}. */
 export interface SendResult {
     screen: string;
     cursor: {
@@ -151,12 +151,12 @@ export interface SendResult {
         y: number;
     };
     /**
-     * Whether the send was actually FORWARDED to a live worker (WR-05). `true` only
+     * Whether the send was actually FORWARDED to a live worker. `true` only
      * when the owned, running session round-tripped an `ok` reply; absent/falsy on the
      * degraded path (absent/cross-owner/not-running session OR a wedged worker — the
      * `{screen:"",cursor:{0,0}}` not-delivered shape). The woken-turn audit reads this
      * so a keystroke that reached nothing is recorded `outcome:"rejected"`, never
-     * `attempted` — keeping the §2.7 audit trail honest about delivery.
+     * `attempted` — keeping the audit trail honest about delivery.
      */
     delivered?: boolean;
 }

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-session-types.js

@@ -3,7 +3,7 @@
  * terminal-session-types -- the neutral LEAF type-module for the daemon-side
  * registry's shared structural contracts.
  *
- * Extracted from `terminal-session-registry.ts` (124-01) to break the source-level
+ * Extracted from `terminal-session-registry.ts` to break the source-level
  * import cycle the worker-supervisor extraction introduced: the registry value-imports
  * `wireWorkerSupervision` FROM `terminal-worker-supervisor.ts`, while the supervisor
  * needed `FakeWorkerChild`/`RegistryLogger`/`SessionHandle` back FROM the registry —

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-settle.d.ts

@@ -1,5 +1,5 @@
 /**
- * The settle engine (spec §5 wait, §4.3 attention model).
+ * The settle engine (the wait tool + the attention model).
  *
  * The bounded, injected-clock debounce that powers every mutating tool's "act
  * then return the SETTLED snapshot" contract and the explicit `wait` tool.
@@ -43,11 +43,11 @@ export declare const SETTLE_DEFAULT_IDLE_MS = 120;
  */
 export declare const SETTLE_DEFAULT_TIMEOUT_MS = 15000;
 /**
- * The hard upper bound on the overall settle (spec §5 cap). `runSettle` clamps any
- * requested `timeoutMs` to this. Sized for INTERACTIVE AI-CLI DRIVING (the v2.11 use
- * case): a driven `claude`/`codex` task routinely runs 60-90s+ (model latency +
- * multi-file writes), so the prior 15s cap made the headline use case impossible —
- * `wait` always timed out before the CLI finished, stranding the agent with a
+ * The hard upper bound on the overall settle. `runSettle` clamps any
+ * requested `timeoutMs` to this. Sized for INTERACTIVE AI-CLI DRIVING: a driven
+ * `claude`/`codex` task routinely runs 60-90s+ (model latency + multi-file writes),
+ * so a tight cap would make the headline use case impossible —
+ * `wait` would time out before the CLI finished, stranding the agent with a
  * not-complete result. The idle debounce (`forIdleMs`) still returns the instant the
  * CLI goes quiet, so this is only the worst-case ceiling for a never-idle stream, not
  * the common wait length. (The settle is timer-driven and does NOT block the worker's
@@ -98,7 +98,7 @@ export interface SettleDeps {
      */
     isSettleable?: () => boolean;
 }
-/** The settle parameters (the `wait` tool's body, spec §5). All conditions are opt-in. */
+/** The settle parameters (the `wait` tool's body). All conditions are opt-in. */
 export interface SettleParams {
     /**
      * The idle debounce window in ms. When set, the idle condition is ARMED at this
@@ -110,8 +110,8 @@ export interface SettleParams {
     forIdleMs?: number;
     /**
      * The number of CONSECUTIVE quiet idle windows the ring must stay unchanged for
-     * before the idle condition resolves (spec §4.3). Defaults to `1` — the
-     * single-window 120-02 behavior. A value `> 1` is the adaptive debounce for an
+     * before the idle condition resolves. Defaults to `1` — the
+     * single-window behavior. A value `> 1` is the adaptive debounce for an
      * AI CLI that emits in bursts with sub-`idleMs` gaps mid-generation: a ring
      * change part-way through the sequence RE-ARMS and RESETS the count, so idle
      * resolves only after N windows of UNINTERRUPTED quiet. SAFE-direction only —
@@ -137,7 +137,7 @@ export interface SettleResult {
      * program was actively producing output (it has NOT finished — keep waiting); `false`
      * ⇒ the screen was idle with no match (maybe done, awaiting input, or stuck). Absent
      * for the complete reasons (idle/text/exit), whose `isComplete:true` is unambiguous.
-     * (T1.1: the live friction was a wait returning not-complete with no "why".)
+     * (The live friction was a wait returning not-complete with no "why".)
      */
     producing?: boolean;
 }

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-settle.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The settle engine (spec §5 wait, §4.3 attention model).
+ * The settle engine (the wait tool + the attention model).
  *
  * The bounded, injected-clock debounce that powers every mutating tool's "act
  * then return the SETTLED snapshot" contract and the explicit `wait` tool.
@@ -47,11 +47,11 @@ export const SETTLE_DEFAULT_IDLE_MS = 120;
  */
 export const SETTLE_DEFAULT_TIMEOUT_MS = 15_000;
 /**
- * The hard upper bound on the overall settle (spec §5 cap). `runSettle` clamps any
- * requested `timeoutMs` to this. Sized for INTERACTIVE AI-CLI DRIVING (the v2.11 use
- * case): a driven `claude`/`codex` task routinely runs 60-90s+ (model latency +
- * multi-file writes), so the prior 15s cap made the headline use case impossible —
- * `wait` always timed out before the CLI finished, stranding the agent with a
+ * The hard upper bound on the overall settle. `runSettle` clamps any
+ * requested `timeoutMs` to this. Sized for INTERACTIVE AI-CLI DRIVING: a driven
+ * `claude`/`codex` task routinely runs 60-90s+ (model latency + multi-file writes),
+ * so a tight cap would make the headline use case impossible —
+ * `wait` would time out before the CLI finished, stranding the agent with a
  * not-complete result. The idle debounce (`forIdleMs`) still returns the instant the
  * CLI goes quiet, so this is only the worst-case ceiling for a never-idle stream, not
  * the common wait length. (The settle is timer-driven and does NOT block the worker's
@@ -105,12 +105,12 @@ export function settleHint(result) {
 export function runSettle(deps, params) {
     const cap = Math.min(params.timeoutMs ?? SETTLE_DEFAULT_TIMEOUT_MS, SETTLE_MAX_TIMEOUT_MS);
     const idleMs = params.forIdleMs ?? SETTLE_DEFAULT_IDLE_MS;
-    // N CONSECUTIVE quiet idle windows before idle resolves (spec §4.3). Floored at
-    // 1 (the single-window 120-02 default); a non-finite/<1 request collapses to 1.
+    // N CONSECUTIVE quiet idle windows before idle resolves. Floored at
+    // 1 (the single-window default); a non-finite/<1 request collapses to 1.
     // Only the idle path consults it — exit/text/timeout are UNCHANGED.
     const stableWindows = Math.max(1, Math.floor(params.stableWindows ?? 1) || 1);
     const { forText } = params;
-    // The wait conditions are OPT-IN (spec §5). The idle debounce is armed IFF the
+    // The wait conditions are OPT-IN. The idle debounce is armed IFF the
     // caller explicitly asked for it (`forIdleMs`) OR asked for NOTHING specific
     // (idle is the sensible DEFAULT only when no forText/forExit is requested). When
     // the caller asked for forExit (or forText), a quiet output window must NOT fire
@@ -129,7 +129,7 @@ export function runSettle(deps, params) {
         // on any ring change (the windows must be CONSECUTIVE). Idle resolves only when
         // it reaches `stableWindows`.
         let stableCount = 0;
-        // T1.1 diagnostic: did the ring change within the last (unfinished) idle window?
+        // Diagnostic: did the ring change within the last (unfinished) idle window?
         // Set on every ring change, CLEARED when a full quiet window elapses — so at the
         // overall-timeout it tells whether the program was still producing output.
         let sawChange = false;
@@ -165,7 +165,7 @@ export function runSettle(deps, params) {
          * idle-settle (bounded by the overall timeout), never force one — exit/text
          * /timeout are unaffected.
          *
-         * Adaptive N-stable-window (spec §4.3): a settleable idle window does not
+         * Adaptive N-stable-window: a settleable idle window does not
          * resolve immediately — it INCREMENTS the consecutive-quiet count and re-arms
          * until the count reaches `stableWindows` (default 1 ⇒ the unchanged
          * single-window behavior). The count is RESET to 0 by any ring change (see the
@@ -183,7 +183,7 @@ export function runSettle(deps, params) {
                     restartIdle(); // content below the fold ⇒ keep waiting, don't settle idle
                     return;
                 }
-                sawChange = false; // a full quiet idle window elapsed with no ring change (T1.1)
+                sawChange = false; // a full quiet idle window elapsed with no ring change
                 stableCount += 1;
                 if (stableCount >= stableWindows) {
                     settle({ matched: true, isComplete: true, reason: "idle" });
@@ -207,10 +207,10 @@ export function runSettle(deps, params) {
             settle({ matched: false, isComplete: false, reason: "timeout", producing: sawChange });
         }, cap);
         // Ring-change: a forText hit resolves text immediately; otherwise RESET the
-        // consecutive-quiet count (the windows must be uninterrupted, spec §4.3) and
+        // consecutive-quiet count (the windows must be uninterrupted) and
         // (re)start the idle debounce so quiet for idleMs resolves idle.
         unsubs.push(deps.onRingChange(() => {
-            sawChange = true; // output is arriving — the program is producing (T1.1 diagnostic)
+            sawChange = true; // output is arriving — the program is producing (diagnostic)
             if (forText !== undefined && deps.getRing().includes(forText)) {
                 settle({ matched: true, isComplete: true, reason: "text" });
                 return;

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-spawn-plan.d.ts

@@ -141,7 +141,7 @@ export declare class CwdOutsideScopeError extends Error {
  * @throws JailUnavailableError when `bwrapPath` is undefined (never an unjailed
  * fallback) or when `network: listed-hosts` has no injected egress port.
  * @throws CwdOutsideScopeError when the resolved `cwd` is not contained by the scope's
- * bound paths (fail-clean before any spawn — §4.8), instead of an opaque chdir crash.
+ * bound paths (fail-clean before any spawn), instead of an opaque chdir crash.
  */
 export declare function buildSpawnPlan(input: SpawnPlanInput, composers: SpawnPlanComposers): Promise<SpawnPlan>;
 /** The create-frame fields {@link planSpawnFromCreateFrame} reads. */

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-spawn-plan.js

@@ -153,7 +153,7 @@ function assertCwdWithinScope(cwd, scope, workspace, home) {
  * @throws JailUnavailableError when `bwrapPath` is undefined (never an unjailed
  * fallback) or when `network: listed-hosts` has no injected egress port.
  * @throws CwdOutsideScopeError when the resolved `cwd` is not contained by the scope's
- * bound paths (fail-clean before any spawn — §4.8), instead of an opaque chdir crash.
+ * bound paths (fail-clean before any spawn), instead of an opaque chdir crash.
  */
 export async function buildSpawnPlan(input, composers) {
     // No provider => no jail => no spawn. Reject BEFORE any materialization.
@@ -164,7 +164,7 @@ export async function buildSpawnPlan(input, composers) {
     const scrubChildEnv = composers.scrubChildEnv ?? defaultScrubChildEnv;
     const buildEgressRelayLaunch = composers.buildEgressRelayLaunch ?? defaultBuildEgressRelayLaunch;
     const { scope } = input;
-    // §4.8 fail-closed: the agent-supplied cwd (the jail --chdir target) MUST sit within a
+    // Fail-closed: the agent-supplied cwd (the jail --chdir target) MUST sit within a
     // path the scope binds — reject typed + EARLY (before any egress socket / spawn), not
     // as an opaque `bwrap: Can't chdir`. filesystem:full binds everything → no check.
     assertCwdWithinScope(input.cwd, scope, input.workspace, input.home);