comisai 1.0.45 → 1.0.46

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-worker-backend-attach.js

@@ -2,8 +2,8 @@
 /**
  * terminal-worker-backend-attach -- the worker's PTY-vs-pipe backend-attach glue plus
  * its two exclusive ring/exit primitives, extracted from `terminal-worker-entry.ts` so
- * that file keeps headroom under the 800-line architecture cap before the P5 attention
- * wiring lands (the fd3 emitter call is added to the worker in Wave 2 / 124-05).
+ * that file keeps headroom under the 800-line architecture cap before the attention
+ * wiring lands (the fd3 emitter call is added to the worker later).
  *
  * BEHAVIOR-NEUTRAL: this is pure code movement. {@link attachBackend} performs the EXACT
  * same wiring `handleCreate` did inline (try `loadPty()` → on success wire the node-pty
@@ -29,7 +29,7 @@
  * subscribers. The emu write chains onto {@link SessionState.writeFlush} (serialized,
  * @xterm-PARSE-backed) so `handleRead` awaits it before serializing a settled frame.
  *
- * Exported so the worker can hand the SAME primitive to other call sites if needed; in P0 its
+ * Exported so the worker can hand the SAME primitive to other call sites if needed; today its
  * only callers are the backend stream handlers in {@link attachBackend}.
  */
 export function appendRing(state, chunk) {
@@ -41,15 +41,15 @@ export function appendRing(state, chunk) {
 /**
  * Flip a session to not-alive + notify the settle's exit subscribers (onExit half) so a pending
  * `wait`/settle resolves `exit`. ALSO disposes the `listed-hosts` egress materialization ONCE
- * (socket cleanup, 122-06) — nulling the handle first so a second exit signal (close AND error)
+ * (socket cleanup) — nulling the handle first so a second exit signal (close AND error)
  * cannot double-dispose. `logger` is passed in (the worker's injected structural logger) so this
  * module stays infra-free.
  */
 export function markExited(state, logger, exitCode) {
     state.alive = false;
-    // 124-06: capture the PTY exit code when the backend reported one (the pty `onExit`
+    // Capture the PTY exit code when the backend reported one (the pty `onExit`
     // payload). The pipe close/error path passes none → `exitCode` stays undefined. The
-    // `status` frame surfaces it as the spec §5 `exitCode`. Recorded once; a 2nd signal
+    // `status` frame surfaces it as the `exitCode`. Recorded once; a 2nd signal
     // (close AND error) does not clobber a captured code with undefined.
     if (exitCode !== undefined)
         state.exitCode = exitCode;
@@ -62,7 +62,7 @@ export function markExited(state, logger, exitCode) {
     }
     for (const cb of state.exitListeners)
         cb();
-    // The exit wake (124-05 gap-close, TR-11): push the exited transition on fd3 even when
+    // The exit wake: push the exited transition on fd3 even when
     // NO settle is pending (no wait/read in flight — the "finished while the agent sat idle"
     // shape). The hook is the worker's single-homed classify-and-emit seam; the edge-triggered
     // emitter dedups it against a settle the exit listeners just resolved, and a 2nd exit
@@ -82,12 +82,12 @@ export function markExited(state, logger, exitCode) {
  *     set `state.pipe`.
  *
  * Returns `true` when a backend was attached (the create path ALWAYS attaches one) and
- * `false` ONLY on the BL-01 `attachOnly` re-attach of a gone session (or no tmux backend)
+ * `false` ONLY on the `attachOnly` re-attach of a gone session (or no tmux backend)
  * — the caller (`handleReattach`) maps `false` to a worker `ok:false` reply.
  */
 export function attachBackend(args) {
     const { plan, cols, rows, state, loadPty, spawnPipe, logger, requestedBackend, loadTmux, sessionId, attachOnly, tmuxSocket } = args;
-    // BL-01 (165-REVIEW): the recover-on-boot RE-ATTACH path — attach to an EXISTING tmux
+    // The recover-on-boot RE-ATTACH path — attach to an EXISTING tmux
     // session by name, NEVER create. A GONE session (reattach → undefined) attaches NOTHING
     // and returns false (the worker replies ok:false → the registry flips lost); there is NO
     // pty/pipe fallback (a re-attach with no live session is a genuine death, not a degrade).
@@ -96,7 +96,7 @@ export function attachBackend(args) {
             return false; // cannot re-attach without the tmux backend.
         const handle = loadTmux.reattach({ sessionId, cols, rows, env: plan.env, tmuxSocket });
         if (handle === undefined)
-            return false; // the tmux session is gone — honest death (I10).
+            return false; // the tmux session is gone — honest death.
         handle.onData((d) => appendRing(state, d));
         handle.onExit((e) => {
             markExited(state, logger, e?.exitCode);
@@ -105,7 +105,7 @@ export function attachBackend(args) {
         state.backend = "tmux";
         return true;
     }
-    // 124-08 (OPS-05): the tmux named-session backend — selected ONLY when the create frame
+    // The tmux named-session backend — selected ONLY when the create frame
     // requested it AND the worker was built with the tmux loader. The handle is FakePtyLike-
     // shaped, so it wires EXACTLY like the pty branch (onData→ring, onExit→markExited, set
     // state.pty so writeToBackend uses it) — one seam, no worker-entry branching. The driven
@@ -132,7 +132,7 @@ export function attachBackend(args) {
         pty = loadPty();
     }
     catch (err) {
-        // TR-08: node-pty unavailable → the pipe backend, reported as degraded.
+        // node-pty unavailable → the pipe backend, reported as degraded.
         logger.warn({ err, hint: "node-pty unavailable; pipe fallback", errorKind: "dependency" }, "terminal worker degraded");
         state.backend = "degraded";
     }
@@ -142,8 +142,8 @@ export function attachBackend(args) {
         handle.onData((d) => appendRing(state, d));
         // Wire child exit -> markExited (the pty analog of the pipe close/error below).
         // WITHOUT it a real node-pty child that exits never notifies an in-flight
-        // wait({forExit:true}) (the VPS real-PTY gate). 124-06: the exit code rides
-        // through so the `status` frame can surface it (spec §5 `exitCode`).
+        // wait({forExit:true}) (the VPS real-PTY gate). The exit code rides
+        // through so the `status` frame can surface it (`exitCode`).
         handle.onExit((e) => {
             markExited(state, logger, e?.exitCode);
         });

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

@@ -1,18 +1,18 @@
 /**
- * terminal-worker-classify -- the worker's per-session classify-and-emit glue (spec
- * §4.3/§2.3; TR-11, OPS-04), extracted from `terminal-worker-entry.ts` so that file
+ * terminal-worker-classify -- the worker's per-session classify-and-emit glue,
+ * extracted from `terminal-worker-entry.ts` so that file
  * keeps headroom under the 800-line architecture cap.
  *
  * {@link observeSettledFrame} is the seam the worker drives AFTER each settle resolves:
  * it takes the session's current emulator snapshot, builds the {@link ClassifierFrame}
  * (alive + the settle's `settled` verdict + the screen-diff vs the previously-classified
- * snapshot), runs the pure {@link classifyFrame} (124-03), and hands the
- * {@link Classification} to the per-session {@link AttentionEmitter} (124-05 Task 1) —
+ * snapshot), runs the pure {@link classifyFrame}, and hands the
+ * {@link Classification} to the per-session {@link AttentionEmitter} —
  * which writes a {@link TerminalEventFrame} to fd3 ONLY on a state TRANSITION. This is
- * the no-poll mechanism (TR-11): the worker is driven by the settle it already runs,
+ * the no-poll mechanism: the worker is driven by the settle it already runs,
  * NEVER by a timer.
  *
- * PROGRESS tracking (OPS-04 stuck-by-progress, no clock inside the classifier): the
+ * PROGRESS tracking (stuck-by-progress, no clock inside the classifier): the
  * caller passes `nowMs`. When the snapshot differs from the previously-classified one,
  * progress was made — `state.lastProgressMs` is stamped to `nowMs`; otherwise
  * `noProgressMs = nowMs - lastProgressMs` is the elapsed no-progress window the classifier
@@ -35,18 +35,18 @@ export type { WorkerStatusPerception } from "./terminal-status-view.js";
 export interface ObserveSettledFrameArgs {
     /** The closure-local per-session record — its emulator, the diff anchors, the emitter. */
     state: SessionState;
-    /** The per-session attention emitter (124-05 Task 1) over the worker's injected `writeFd3`. */
+    /** The per-session attention emitter over the worker's injected `writeFd3`. */
     emitter: AttentionEmitter;
     /** The settle's idle verdict for THIS frame (`runSettle` resolved idle / matched / not). `false` ⇒ the classifier reads `working` (output still in flight). */
     settled: boolean;
     /** The worker's injected clock (epoch ms) — the SOLE clock source; the classifier reads none. */
     nowMs: () => number;
-    /** The operator stuck threshold in ms (`worker.stuckMs`, OPS-04). */
+    /** The operator stuck threshold in ms (`worker.stuckMs`). */
     stuckMs: number;
     /** Optional operator prompt cues (reinforce the cursor-parked gate only; never override structure). */
     hintPatterns?: readonly string[];
     /**
-     * LIVE-04 (#4): suppress the fd3 ATTENTION write for this frame while still updating the
+     * Suppress the fd3 ATTENTION write for this frame while still updating the
      * progress clock + the emitter's edge-state. The worker sets it when the settle was the
      * agent's explicit foreground `wait` — that wait's reply is the agent's attention signal, so a
      * fd3 woken turn would race it (the launch escalation). Default `false` (act-then-return settles
@@ -57,7 +57,7 @@ export interface ObserveSettledFrameArgs {
 /**
  * Classify the session's current settled frame and hand the verdict to the emitter
  * (which fires on fd3 only on a TRANSITION). Awaits the pending emulator write-parse
- * first (the §2.4 stability flush) so the snapshot reflects every emitted byte —
+ * first (the stability flush) so the snapshot reflects every emitted byte —
  * exactly as `handleRead` does. A session with no emulator (degraded ring-only) yields
  * no snapshot ⇒ no classification (the safe direction). Never throws.
  *
@@ -72,25 +72,25 @@ export interface StatusReplyArgs {
     settled: boolean;
     /** The worker's injected clock (epoch ms) — the SOLE clock source; the classifier reads none. */
     nowMs: () => number;
-    /** The operator stuck threshold in ms (`worker.stuckMs`, OPS-04). */
+    /** The operator stuck threshold in ms (`worker.stuckMs`). */
     stuckMs: number;
     /** Optional operator prompt cues (reinforce the cursor-parked gate only; never override structure). */
     hintPatterns?: readonly string[];
 }
 /**
  * Build the `status`-frame reply for a session — the classifier stays SINGLE-HOMED
- * in the worker (RESEARCH Open Q2; no daemon-side grid duplication). A point-in-time
+ * in the worker (no daemon-side grid duplication). A point-in-time
  * query, NOT a settle: it awaits the pending @xterm parse (so the snapshot reflects
  * every emitted byte, exactly like `handleRead`), runs the pure `classifyFrame` over
  * the CURRENT grid + the diff vs the previously-classified frame + the per-session
  * progress clock, and returns the structural perception subset.
  *
  * It does NOT mutate `state.lastClassifiedSnapshot` / `state.lastProgressMs`: those
- * are the attention emitter's edge-trigger anchors (124-05) — a read-only status
+ * are the attention emitter's edge-trigger anchors — a read-only status
  * query must never perturb the transition detection. A degraded ring-only session
  * (no emulator) reports `working` with an empty diff (the safe direction). Never throws.
  *
- * 163-03 (CLASS-02): the reply also carries the classifier's `confidence` + `reason`
+ * The reply also carries the classifier's `confidence` + `reason`
  * (the classification's own fields in the classified branch; a `high` liveness verdict
  * in the no-emulator branch) — content-free structural signals (an enum + a machine
  * tag, never screen text) that `composeStatusView` folds onto the status view.

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

@@ -1,19 +1,19 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * terminal-worker-classify -- the worker's per-session classify-and-emit glue (spec
- * §4.3/§2.3; TR-11, OPS-04), extracted from `terminal-worker-entry.ts` so that file
+ * terminal-worker-classify -- the worker's per-session classify-and-emit glue,
+ * extracted from `terminal-worker-entry.ts` so that file
  * keeps headroom under the 800-line architecture cap.
  *
  * {@link observeSettledFrame} is the seam the worker drives AFTER each settle resolves:
  * it takes the session's current emulator snapshot, builds the {@link ClassifierFrame}
  * (alive + the settle's `settled` verdict + the screen-diff vs the previously-classified
- * snapshot), runs the pure {@link classifyFrame} (124-03), and hands the
- * {@link Classification} to the per-session {@link AttentionEmitter} (124-05 Task 1) —
+ * snapshot), runs the pure {@link classifyFrame}, and hands the
+ * {@link Classification} to the per-session {@link AttentionEmitter} —
  * which writes a {@link TerminalEventFrame} to fd3 ONLY on a state TRANSITION. This is
- * the no-poll mechanism (TR-11): the worker is driven by the settle it already runs,
+ * the no-poll mechanism: the worker is driven by the settle it already runs,
  * NEVER by a timer.
  *
- * PROGRESS tracking (OPS-04 stuck-by-progress, no clock inside the classifier): the
+ * PROGRESS tracking (stuck-by-progress, no clock inside the classifier): the
  * caller passes `nowMs`. When the snapshot differs from the previously-classified one,
  * progress was made — `state.lastProgressMs` is stamped to `nowMs`; otherwise
  * `noProgressMs = nowMs - lastProgressMs` is the elapsed no-progress window the classifier
@@ -34,7 +34,7 @@ import { diffSnapshot } from "./terminal-render.js";
 /**
  * Classify the session's current settled frame and hand the verdict to the emitter
  * (which fires on fd3 only on a TRANSITION). Awaits the pending emulator write-parse
- * first (the §2.4 stability flush) so the snapshot reflects every emitted byte —
+ * first (the stability flush) so the snapshot reflects every emitted byte —
  * exactly as `handleRead` does. A session with no emulator (degraded ring-only) yields
  * no snapshot ⇒ no classification (the safe direction). Never throws.
  *
@@ -54,20 +54,20 @@ export async function observeSettledFrame(args) {
     const diff = diffSnapshot(state.lastClassifiedSnapshot, snapshot);
     const now = nowMs();
     // Progress = the screen changed since the last classified frame. On progress, restamp
-    // the progress clock; otherwise noProgressMs grows toward stuckMs (OPS-04). The very
+    // the progress clock; otherwise noProgressMs grows toward stuckMs. The very
     // first classification (no prior progress stamp) counts as progress (just rendered).
     if (diff.changed || state.lastProgressMs === undefined) {
         state.lastProgressMs = now;
     }
     const noProgressMs = now - state.lastProgressMs;
     state.lastClassifiedSnapshot = snapshot;
-    // CLASSIFY-01/DIALOG-01: the selected platform profile (by the session's operator-declared allowId
-    // — never content-sniffed; INV-3). The classifier stays the sole owner of `activity` (D4): it
-    // consumes the profile's perception + the dialog `detect` patterns. Absent ⇒ generic path (INV-1).
+    // The selected platform profile (by the session's operator-declared allowId
+    // — never content-sniffed). The classifier stays the sole owner of `activity`: it
+    // consumes the profile's perception + the dialog `detect` patterns. Absent ⇒ generic path.
     const profile = state.allowId !== undefined ? getPlatformProfile(state.allowId) : undefined;
     const perception = profile?.perception;
     const dialogDetects = profile?.dialogs?.map((d) => d.detect);
-    // `diffEmpty` (the spec §4.3 prerequisite for awaiting-input) means the SETTLED screen
+    // `diffEmpty` (the prerequisite for awaiting-input) means the SETTLED screen
     // is stable. This path runs only AFTER `runSettle` resolved, so on a non-timeout settle
     // the output already reached a quiet state. The FIRST classification has no prior frame
     // to diff against — but the settle proved quiescence, so it is diff-empty (the
@@ -83,25 +83,25 @@ export async function observeSettledFrame(args) {
         perception,
         dialogDetects,
     }, { noProgressMs, stuckMs });
-    // Edge-triggered fd3 emit (the emitter writes only on a state transition). LIVE-04 (#4): on a
+    // Edge-triggered fd3 emit (the emitter writes only on a state transition). On a
     // foreground `wait` settle, suppress the write (the wait reply is the agent's attention signal)
     // while the emitter still advances its edge-state so the transition never re-fires later.
     emitter.observe(classification, { noProgressMs, suppressEmit });
 }
 /**
  * Build the `status`-frame reply for a session — the classifier stays SINGLE-HOMED
- * in the worker (RESEARCH Open Q2; no daemon-side grid duplication). A point-in-time
+ * in the worker (no daemon-side grid duplication). A point-in-time
  * query, NOT a settle: it awaits the pending @xterm parse (so the snapshot reflects
  * every emitted byte, exactly like `handleRead`), runs the pure `classifyFrame` over
  * the CURRENT grid + the diff vs the previously-classified frame + the per-session
  * progress clock, and returns the structural perception subset.
  *
  * It does NOT mutate `state.lastClassifiedSnapshot` / `state.lastProgressMs`: those
- * are the attention emitter's edge-trigger anchors (124-05) — a read-only status
+ * are the attention emitter's edge-trigger anchors — a read-only status
  * query must never perturb the transition detection. A degraded ring-only session
  * (no emulator) reports `working` with an empty diff (the safe direction). Never throws.
  *
- * 163-03 (CLASS-02): the reply also carries the classifier's `confidence` + `reason`
+ * The reply also carries the classifier's `confidence` + `reason`
  * (the classification's own fields in the classified branch; a `high` liveness verdict
  * in the no-emulator branch) — content-free structural signals (an enum + a machine
  * tag, never screen text) that `composeStatusView` folds onto the status view.
@@ -134,8 +134,8 @@ export async function statusReplyFromState(args) {
     const diff = diffSnapshot(state.lastClassifiedSnapshot, snapshot);
     const screenDiffEmpty = isFirst ? true : !diff.changed;
     const noProgressMs = state.lastProgressMs === undefined ? 0 : nowMs() - state.lastProgressMs;
-    // CLASSIFY-01/DIALOG-01: the selected platform profile (by allowId; INV-3). Same generic fallback
-    // as the settle path — absent ⇒ unchanged (INV-1).
+    // The selected platform profile (by allowId). Same generic fallback
+    // as the settle path — absent ⇒ unchanged.
     const profile = state.allowId !== undefined ? getPlatformProfile(state.allowId) : undefined;
     const perception = profile?.perception;
     const dialogDetects = profile?.dialogs?.map((d) => d.detect);
@@ -146,9 +146,9 @@ export async function statusReplyFromState(args) {
         cursorParked,
         screenDiffEmpty,
         interactions: state.interactions,
-        // CLASS-02: surface the classifier's own confidence + reason (computed above at
+        // Surface the classifier's own confidence + reason (computed above at
         // `classification`) — never a hardcoded constant; this is the WHY/HOW-SURE the
-        // status tool + the autonomous policy (164-166) read.
+        // status tool + the autonomous policy read.
         confidence: classification.confidence,
         reason: classification.reason,
         ...(state.exitCode !== undefined ? { exitCode: state.exitCode } : {}),

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

@@ -1,7 +1,7 @@
 /**
  * terminal-worker-defaults -- the worker's production-default ports + the small
  * scrollback/stuck/bracketed-paste constants, extracted from
- * `terminal-worker-entry.ts` (165-REVIEW BL-01) so that file keeps headroom under the
+ * `terminal-worker-entry.ts` so that file keeps headroom under the
  * 800-line architecture cap once the `reattach` dispatch path lands.
  *
  * BEHAVIOR-NEUTRAL: pure code movement. The factory defaults (`defaultLoadPty`,
@@ -13,8 +13,8 @@
  *
  * INFRA-FREE (like every worker-side sibling): value-imports ONLY node builtins, and
  * type-imports the worker's structural contracts from the neutral leaf
- * `terminal-worker-types.ts`; never `@comis/infra` / `@comis/observability` (Shared
- * Pattern A; the worker MUST NOT cross into those layers).
+ * `terminal-worker-types.ts`; never `@comis/infra` / `@comis/observability` (the
+ * worker MUST NOT cross into those layers).
  *
  * @module
  */
@@ -25,7 +25,7 @@ import type { PipeChildLike, PtyModuleLike, WorkerFsPort } from "./terminal-work
  */
 export declare const SCROLLBACK_DEFAULT = 1000;
 /**
- * The default operator stuck threshold (OPS-04) the classifier compares to a session's
+ * The default operator stuck threshold the classifier compares to a session's
  * no-progress window when `deps.stuckMs` is omitted. The daemon threads the config
  * `worker.stuckMs`; this is the safety-net default.
  */

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

@@ -2,7 +2,7 @@
 /**
  * terminal-worker-defaults -- the worker's production-default ports + the small
  * scrollback/stuck/bracketed-paste constants, extracted from
- * `terminal-worker-entry.ts` (165-REVIEW BL-01) so that file keeps headroom under the
+ * `terminal-worker-entry.ts` so that file keeps headroom under the
  * 800-line architecture cap once the `reattach` dispatch path lands.
  *
  * BEHAVIOR-NEUTRAL: pure code movement. The factory defaults (`defaultLoadPty`,
@@ -14,8 +14,8 @@
  *
  * INFRA-FREE (like every worker-side sibling): value-imports ONLY node builtins, and
  * type-imports the worker's structural contracts from the neutral leaf
- * `terminal-worker-types.ts`; never `@comis/infra` / `@comis/observability` (Shared
- * Pattern A; the worker MUST NOT cross into those layers).
+ * `terminal-worker-types.ts`; never `@comis/infra` / `@comis/observability` (the
+ * worker MUST NOT cross into those layers).
  *
  * @module
  */
@@ -28,7 +28,7 @@ import { writeFileSync as fsWriteFileSync, renameSync as fsRenameSync, openSync
  */
 export const SCROLLBACK_DEFAULT = 1000;
 /**
- * The default operator stuck threshold (OPS-04) the classifier compares to a session's
+ * The default operator stuck threshold the classifier compares to a session's
  * no-progress window when `deps.stuckMs` is omitted. The daemon threads the config
  * `worker.stuckMs`; this is the safety-net default.
  */

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

@@ -1,5 +1,5 @@
 /**
- * The supervised Terminal Worker entry (spec §2.1/§2.2/§2.3).
+ * The supervised Terminal Worker entry.
  *
  * The worker is the one net-new process boundary: a daemon-supervised child that
  * owns the PTY (node-pty, optional) + the driven CLI. The registry spawns
@@ -32,7 +32,7 @@ import { type EmulatorSnapshot, type SessionEmulator } from "./terminal-render.j
 export interface TerminalWorkerDeps {
     /** Load node-pty. Default: a guarded `createRequire` load in a try — NEVER a top-level static import (crashes module load on a no-prebuild host); a throw → the pipe backend. */
     loadPty: () => PtyModuleLike;
-    /** 124-08 (OPS-05): the tmux named-session backend loader — the 3rd option behind the same FakePtyLike seam as node-pty | pipe. Used ONLY when a create frame requests `backend:"tmux"`; the daemon binds it (resolved tmux path + has-session probe + runTmux). Absent ⇒ a tmux request falls back to pty/pipe. */
+    /** The tmux named-session backend loader — the 3rd option behind the same FakePtyLike seam as node-pty | pipe. Used ONLY when a create frame requests `backend:"tmux"`; the daemon binds it (resolved tmux path + has-session probe + runTmux). Absent ⇒ a tmux request falls back to pty/pipe. */
     loadTmux?: TmuxBackendLike;
     /** Spawn the pipe-backend child. Default: `child_process.spawn` with stdio pipes. */
     spawnPipe?: (bin: string, argv: string[], opts: {
@@ -50,7 +50,7 @@ export interface TerminalWorkerDeps {
     setTimer?: (cb: () => void, ms: number) => unknown;
     /** Cancel a `setTimer` handle (default: `systemClearTimeout`). */
     clearTimer?: (handle: unknown) => void;
-    /** Construct a per-session @xterm emulator. Default: `createSessionEmulator`. Injectable so a test can assert the wiring (mirrors loadPty/spawnPipe). `transformSnapshot` is the selected platform profile's read-side render hook (RENDER-01), passed through verbatim. */
+    /** Construct a per-session @xterm emulator. Default: `createSessionEmulator`. Injectable so a test can assert the wiring (mirrors loadPty/spawnPipe). `transformSnapshot` is the selected platform profile's read-side render hook, passed through verbatim. */
     createEmulator?: (opts: {
         cols: number;
         rows: number;
@@ -58,20 +58,20 @@ export interface TerminalWorkerDeps {
         transformSnapshot?: (snap: EmulatorSnapshot) => EmulatorSnapshot;
     }) => SessionEmulator;
     /**
-     * Write a length-prefixed frame to fd3 — the no-poll attention push channel (124-05,
-     * TR-11). Production wraps `fs.writeSync(3, b)` (the worker spawns with fd3 reserved,
+     * Write a length-prefixed frame to fd3 — the no-poll attention push channel.
+     * Production wraps `fs.writeSync(3, b)` (the worker spawns with fd3 reserved,
      * `terminal-worker-launch.ts`); tests inject a capturing fake. ABSENT ⇒ the attention
      * emit is a no-op (the worker still settles normally — the emit is best-effort, never
      * required for correctness). The fd3 frame carries a redaction-safe summary ONLY.
      */
     writeFd3?: (b: Buffer) => void;
     /**
-     * The operator stuck threshold in ms (`worker.stuckMs`, OPS-04) the classifier compares
+     * The operator stuck threshold in ms (`worker.stuckMs`) the classifier compares
      * to a session's no-progress window. Default {@link STUCK_DEFAULT_MS}; the daemon threads
      * the config value. Stuck is by PROGRESS, never elapsed session wall-clock.
      */
     stuckMs?: number;
-    /** Scope->bwrap argv composer (122-03). Default: the module export. */
+    /** Scope->bwrap argv composer. Default: the module export. */
     buildScopeArgs?: typeof defaultBuildScopeArgs;
     /** Child-env blocklist scrubber. Default: the module export. */
     scrubChildEnv?: typeof defaultScrubChildEnv;

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // @allow-throw: the worker IS the frame error-mapping boundary — `dispatch` wraps every handler in a try/catch that maps a thrown error to an `ok:false` reply (the registry's error-reply path). The sole `throw` is `handleCreate` re-raising a fail-closed JailUnavailableError (after dropping the half-registered session) so it reaches that boundary; never an unjailed fallback.
 /**
- * The supervised Terminal Worker entry (spec §2.1/§2.2/§2.3).
+ * The supervised Terminal Worker entry.
  *
  * The worker is the one net-new process boundary: a daemon-supervised child that
  * owns the PTY (node-pty, optional) + the driven CLI. The registry spawns
@@ -39,8 +39,8 @@ import { buildReadResult, createSessionEmulator, diffSnapshot, perceptionScreen,
 import { getPlatformProfile } from "./platforms/index.js";
 import { runSettle, settleHint, SETTLE_DEFAULT_IDLE_MS, } from "./terminal-settle.js";
 // The production-default ports (defaultLoadPty / defaultSpawnPipe / defaultFsPort) +
-// the bracketed-paste delimiters moved to ./terminal-worker-defaults.ts (165-REVIEW
-// BL-01 cap headroom); imported above. defaultLoadPty is re-exported at the file tail.
+// the bracketed-paste delimiters live in ./terminal-worker-defaults.ts to keep this
+// file under the line cap; imported above. defaultLoadPty is re-exported at the file tail.
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -71,12 +71,12 @@ export function createTerminalWorker(deps) {
     // The per-session @xterm emulator factory. Default: the real pure-JS
     // wrapper; a test injects a recording emulator to assert the wiring.
     const createEmulator = deps.createEmulator ?? createSessionEmulator;
-    // 124-05: the no-poll attention plumbing. `writeFd3` is the push-channel sink (a
+    // The no-poll attention plumbing. `writeFd3` is the push-channel sink (a
     // production worker wraps `fs.writeSync(3, …)`; absent ⇒ the emit is a no-op). `stuckMs`
-    // is the operator stuck threshold (OPS-04) the classifier compares no-progress against.
+    // is the operator stuck threshold the classifier compares no-progress against.
     const { writeFd3 } = deps;
     const stuckMs = deps.stuckMs ?? STUCK_DEFAULT_MS;
-    // 122-06: the scope-jail composers, threaded into planSpawnFromCreateFrame at the
+    // The scope-jail composers, threaded into planSpawnFromCreateFrame at the
     // spawn seam. bwrapPath/egressControl have NO default — the daemon injects them.
     const spawnComposers = {
         buildScopeArgs: deps.buildScopeArgs ?? defaultBuildScopeArgs,
@@ -86,9 +86,9 @@ export function createTerminalWorker(deps) {
         bwrapPath: deps.bwrapPath,
     };
     // appendRing (ring + emulator feed + settle ring-change notify) and markExited (not-alive
-    // flip + once-only egress dispose + settle exit notify) moved to terminal-worker-backend-attach.ts
-    // (124-01) — their ONLY callers are the backend stream handlers there, so they ride with
-    // attachBackend; behavior is byte-for-byte identical.
+    // flip + once-only egress dispose + settle exit notify) live in terminal-worker-backend-attach.ts
+    // — their ONLY callers are the backend stream handlers there, so they ride with
+    // attachBackend.
     /** Resolve the backend write sink: pty.write for the pty backend, else pipe.stdin.write. */
     function writeToBackend(state, bytes) {
         if (state.pty !== undefined) {
@@ -123,7 +123,7 @@ export function createTerminalWorker(deps) {
             isSettleable: () => !(state.emu?.hasContentBelowFold() ?? false),
         };
         const result = await runSettle(settleDeps, params);
-        // 124-05 (TR-11, the no-poll mechanism): after the settle resolves, classify the
+        // The no-poll mechanism: after the settle resolves, classify the
         // settled frame and hand the verdict to the per-session emitter — which writes a fd3
         // attention frame ONLY on a state TRANSITION. EDGE-triggered (driven by the settle the
         // worker already runs), NEVER a poll. `settled` is true unless the settle timed out
@@ -136,7 +136,7 @@ export function createTerminalWorker(deps) {
                 settled: result.reason !== "timeout",
                 nowMs,
                 stuckMs,
-                // LIVE-04 (#4): a foreground `wait` settle suppresses the fd3 attention write (the wait
+                // A foreground `wait` settle suppresses the fd3 attention write (the wait
                 // reply is the agent's signal); act-then-return settles (create/send) emit normally.
                 suppressEmit: suppressAttentionEmit,
             });
@@ -171,7 +171,7 @@ export function createTerminalWorker(deps) {
         const workspace = typeof p["workspace"] === "string" ? p["workspace"] : undefined;
         const cwd = typeof p["cwd"] === "string" ? p["cwd"] : undefined;
         // The operator-declared allowId (registry-threaded from the create request). It selects the
-        // read-side platform profile (RENDER-01 / §5/INV-3) — by allowId ONLY, never content-sniffed,
+        // read-side platform profile — by allowId ONLY, never content-sniffed,
         // so the driven program cannot choose its own profile. `undefined` ⇒ the agnostic default.
         const allowId = typeof p["allowId"] === "string" ? p["allowId"] : undefined;
         const profile = allowId !== undefined ? getPlatformProfile(allowId) : undefined;
@@ -193,9 +193,9 @@ export function createTerminalWorker(deps) {
         // (so the first chunk is rendered). Built for BOTH backends; the
         // scrollback is threaded from the create frame (DEFAULT_SCROLLBACK / config, never agent input).
         // The selected profile's read-side `transformSnapshot` (e.g. the Claude ghost-strip) is injected
-        // as a GENERIC hook — the emulator stays platform-agnostic; identity when no profile (INV-1).
+        // as a GENERIC hook — the emulator stays platform-agnostic; identity when no profile.
         state.emu = createEmulator({ cols, rows, scrollback, transformSnapshot: profile?.transformSnapshot });
-        // 124-05 (TR-11): a per-session transition-only attention emitter over the injected
+        // A per-session transition-only attention emitter over the injected
         // fd3 push channel. Built only when `writeFd3` is wired (the production worker; tests
         // inject a fake). The worker hands each SETTLED frame's classification to
         // `emitter.observe` (in settleSession) — which writes a fd3 frame ONLY on a state
@@ -203,8 +203,8 @@ export function createTerminalWorker(deps) {
         if (writeFd3 !== undefined) {
             const emitter = createAttentionEmitter({ sessionId, writeFd3 });
             state.emitter = emitter;
-            // The exit wake (124-05 gap-close): `markExited` fires this so a child that exits
-            // with NO settle pending still pushes its exited transition on fd3 — TR-11's
+            // The exit wake: `markExited` fires this so a child that exits
+            // with NO settle pending still pushes its exited transition on fd3 — the
             // no-poll wake holds for completion, not just prompts (without it an event-driven
             // agent whose long command finished while it sat idle is NEVER woken; the
             // `claude --help` soak run is exactly that shape). Same single-homed classify
@@ -239,11 +239,11 @@ export function createTerminalWorker(deps) {
         state.egress = plan.egress; // disposed on teardown (markExited)
         // Attach the backend (PTY or the degraded pipe fallback) — the EXACT try-loadPty /
         // wire-onData/onExit / pipe-close-error block, lifted into a sibling so this file
-        // keeps headroom under the 800-line cap (124-01). appendRing/markExited moved with it
+        // keeps headroom under the 800-line cap. appendRing/markExited moved with it
         // (their only callers were those stream handlers); the rest ride in as explicit params.
-        // 124-08 (OPS-05): only an explicit create-frame `backend:"tmux"` (allow-entry,
-        // daemon-threaded in 124-09) + a wired `loadTmux` diverges to the tmux survival
-        // backend; everything else takes the node-pty → pipe path (attachBackend decides).
+        // Only an explicit create-frame `backend:"tmux"` (allow-entry, daemon-threaded) + a
+        // wired `loadTmux` diverges to the tmux survival backend; everything else takes the
+        // node-pty → pipe path (attachBackend decides).
         const requestedBackend = p["backend"] === "tmux" ? "tmux" : undefined;
         attachBackend({
             plan: { bin: plan.bin, argv: plan.argv, env: plan.env },
@@ -263,7 +263,7 @@ export function createTerminalWorker(deps) {
     }
     /**
      * Handle a `read` frame. AWAITS the pending emulator write-parse
-     * ({@link SessionState.writeFlush}, the §2.4 stability flush — resolves on the
+     * ({@link SessionState.writeFlush}, the stability flush — resolves on the
      * @xterm parse callback) so the snapshot reflects every emitted byte, then
      * serializes the @xterm grid (real cursor+alt) in the requested format/scrollback.
      * The emulator is the SOLE source when present; the raw ring is the emulator-absent
@@ -297,8 +297,8 @@ export function createTerminalWorker(deps) {
         return { screen: "", cursor: { x: 0, y: 0 } };
     }
     /**
-     * §2.7: one bounded INFO line per interaction handler (method + durationMs). ALSO
-     * the single chokepoint that advances the per-session interaction counter (124-06):
+     * One bounded INFO line per interaction handler (method + durationMs). ALSO
+     * the single chokepoint that advances the per-session interaction counter:
      * every send_text / send_key / wait / resize lands here (read/status are read-only
      * and do NOT call this), so `interactions` increments in exactly one place.
      */
@@ -384,7 +384,7 @@ export function createTerminalWorker(deps) {
     }
     /**
      * Handle a `wait` frame — the explicit parameterized settle. Runs {@link runSettle} and
-     * replies `{matched,isComplete,reason,producing,hint,screen,cursor}` (T1.1 adds producing/hint);
+     * replies `{matched,isComplete,reason,producing,hint,screen,cursor}`;
      * an absent session is gone (reason `exit`, not-complete). CRITICAL: `isComplete` passes from
      * runSettle VERBATIM — `false` on timeout (attention model resumes the turn), NEVER hard-coded true.
      */
@@ -402,7 +402,7 @@ export function createTerminalWorker(deps) {
             forExit: frame.params["forExit"] === true ? true : undefined,
             timeoutMs: typeof frame.params["timeoutMs"] === "number" ? frame.params["timeoutMs"] : undefined,
         };
-        // LIVE-04 (#4): suppress the fd3 attention emit for this foreground `wait` settle — the wait
+        // Suppress the fd3 attention emit for this foreground `wait` settle — the wait
         // reply below IS the agent's attention signal (it unblocks + drives), so a fd3 woken turn would
         // race it (the launch escalation). The progress clock + the emitter's edge-state still advance.
         const r = await settleSession(state, params, true);
@@ -412,20 +412,20 @@ export function createTerminalWorker(deps) {
             matched: r.matched,
             isComplete: r.isComplete, // VERBATIM from runSettle — false on timeout.
             reason: r.reason,
-            producing: r.producing, // T1.1: was output still arriving at a not-complete timeout?
-            hint: settleHint(r), // T1.1: branched, actionable not-complete-timeout hint
+            producing: r.producing, // was output still arriving at a not-complete timeout?
+            hint: settleHint(r), // branched, actionable not-complete-timeout hint
             ...perceptionScreen(state.emu?.snapshot(), state.ring),
         };
     }
     /**
-     * Handle a `status` frame (124-06, spec §5; TR-11 perception) — the classifier
-     * stays SINGLE-HOMED in the worker (RESEARCH Open Q2). Delegates to the read-only
+     * Handle a `status` frame (perception) — the classifier
+     * stays SINGLE-HOMED in the worker. Delegates to the read-only
      * {@link statusReplyFromState} (it classifies the CURRENT grid; see its doc). An
      * absent session is gone → `exited`. `settled:true` (a point-in-time snapshot).
      */
     async function handleStatus(frame) {
         const state = sessions.get(String(frame.params["sessionId"] ?? frame.sessionId));
-        // Absent session → gone (`exited`, the safe direction). CLASS-02 confidence+reason stay TOTAL here too (an absent session IS exited; mirrors notFoundStatus — never an undefined field). Else classify the live grid.
+        // Absent session → gone (`exited`, the safe direction). Confidence+reason stay TOTAL here too (an absent session IS exited; mirrors notFoundStatus — never an undefined field). Else classify the live grid.
         if (state === undefined)
             return { state: "exited", cursorParked: false, screenDiffEmpty: true, interactions: 0, confidence: "high", reason: "exited" };
         return statusReplyFromState({ state, settled: true, nowMs, stuckMs });
@@ -439,9 +439,9 @@ export function createTerminalWorker(deps) {
                     result = await handleCreate(frame); // awaits the scope-jail composition; fail-closed throw → ok:false
                     break;
                 case "reattach": {
-                    // BL-01 (165-REVIEW): recover-on-boot re-attach (sibling-owned for cap headroom) —
+                    // Recover-on-boot re-attach (sibling-owned for cap headroom) —
                     // ok:false when the tmux session is gone (the registry flips lost), so it rides the
-                    // reply.ok channel directly (the surviving pane is read, never re-spawned, I10).
+                    // reply.ok channel directly (the surviving pane is read, never re-spawned).
                     const r = await reattachWorkerSession({
                         frame, sessions, createEmulator, writeFd3, nowMs, stuckMs, logger,
                         loadPty: deps.loadPty, spawnPipe, loadTmux: deps.loadTmux, envSnapshot,