comisai 1.0.45 → 1.0.46

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The terminal-driver reaper (spec §4.6).
+ * The terminal-driver reaper.
  *
  * Bounds the per-worker/cgroup session footprint with THREE caps, each evicting
  * with an audited reason:
@@ -49,7 +49,7 @@ export function createTerminalReaper(deps) {
      * One sweep pass: evict each session at most once, idle taking precedence over
      * wall-clock. A `0` cap is "disabled" so each cap can be exercised in isolation.
      *
-     * ENDURE-01 / I9: the idle branch is GATED on `!isBusy` — a session quiet past
+     * The idle branch is GATED on `!isBusy` — a session quiet past
      * `idleTtlMs` but alive-and-busy (recent worker progress) is EXCLUDED from idle
      * eviction (no death for quietness alone). The wall-clock branch is UNCHANGED: a
      * deliberate operator bound that fires even for a busy session, carrying its cap
@@ -60,8 +60,8 @@ export function createTerminalReaper(deps) {
     function sweep() {
         const now = deps.nowMs();
         for (const s of deps.listSessions()) {
-            // I9: skip idle eviction while the drive is alive-and-busy (a quiet compile is
-            // not idle). `isBusy` absent ⇒ `false` ⇒ today's quietness-only behavior (I1).
+            // Skip idle eviction while the drive is alive-and-busy (a quiet compile is
+            // not idle). `isBusy` absent ⇒ `false` ⇒ the quietness-only behavior.
             if (deps.idleTtlMs > 0 && now - s.lastActivity > deps.idleTtlMs && !(deps.isBusy?.(s) ?? false)) {
                 deps.onEvict(s.sessionId, "idle");
                 continue;
@@ -100,7 +100,8 @@ export function createTerminalReaper(deps) {
  * reuses the registry's `evictInternal` (the kill drop + `cleanupSessionWorkspace`,
  * never duplicated), FORGETS the per-session cap state via `onCapForget` (no
  * SessionCaps Map leak on the reap path), emits the audited reason via
- * `onEvict`, and logs a WARN (`hint` + `errorKind: "resource"`, §2.7). The
+ * `onEvict`, and logs a WARN (`hint` + `errorKind: "resource"`, per the AGENTS.md
+ * logging matrix). The
  * `max_interactions` eviction reuses this exact `evict`. The reaper is undefined when
  * `timers`/`maxSessions` are not both provided — `checkOverflow`/`stop` then no-op.
  */
@@ -132,8 +133,8 @@ export function wireRegistryReaper(w) {
                 startedAtMs: s.startedAt,
             })),
             onEvict: (sessionId, reason) => evict(sessionId, reason),
-            // ENDURE-01 / I9: thread the daemon-bound alive-busy predicate onto the
-            // sweep's idle gate (undefined ⇒ today's quietness-only eviction, I1).
+            // Thread the daemon-bound alive-busy predicate onto the
+            // sweep's idle gate (undefined ⇒ quietness-only eviction).
             isBusy: w.caps.isBusy,
         })
         : undefined;

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

@@ -1,8 +1,7 @@
 /**
- * The pure DUR-01 re-attach decision + the durable session descriptor (Phase 165;
- * CONTEXT §7.1.5 / design §4 Phase C / RESEARCH Pattern 1).
+ * The pure re-attach decision + the durable session descriptor.
  *
- * THE FRAMING CORRECTION (the load-bearing finding of this phase). The tmux re-attach
+ * THE FRAMING (why this module exists at this layer). The tmux re-attach
  * MECHANISM already ships: `terminal-tmux-backend.ts` derives the deterministic
  * `comis-<sessionId>` name ({@link tmuxSessionName}), `has-session`-gates create-vs-
  * reattach, and `terminal-tmux-backend.linux.test.ts` proves a detached named session
@@ -11,33 +10,33 @@
  * recover-on-boot — so on a daemon restart its `sessions` Map starts EMPTY, and a healthy
  * 38h drive whose `comis-<old-id>` is STILL alive under tmux is wrongly flipped `lost`.
  * This module is NOT a tmux rebuild; it is the missing IDENTITY ({@link SessionDescriptor})
- * + the pure DECISION ({@link reattachDecision}) the registry's recover-on-boot (165-06)
+ * + the pure DECISION ({@link reattachDecision}) the registry's recover-on-boot
  * consumes to turn "the tmux server survived" into "the registry knows to re-attach."
  *
  * Given a persisted descriptor + a live `has-session` probe, {@link reattachDecision}
  * decides ONE of three actions:
- *   - `reattach` — durable + the tmux session is LIVE: re-attach (I10 — a 40h drive
- *     crosses the daemon's lifetime and is never lost). The descriptor (carrying the I5
- *     identity) is returned VERBATIM for the caller to re-stamp.
+ *   - `reattach` — durable + the tmux session is LIVE: re-attach (a 40h drive
+ *     crosses the daemon's lifetime and is never lost). The descriptor (carrying the
+ *     authorization identity) is returned VERBATIM for the caller to re-stamp.
  *   - `failed`/`tmux_session_gone` — durable but the tmux session is GONE (or the probe is
  *     unanswerable): a genuine death surfaces. The JOURNAL is preserved SEPARATELY by the
- *     caller (NOT touched here, I10) — never a silent restart, never a double-drive.
- *   - `fallback_nondurable` — a `durable:false` (spawn) session: today's lost floor (I1).
+ *     caller (NOT touched here) — never a silent restart, never a double-drive.
+ *   - `fallback_nondurable` — a `durable:false` (spawn) session: the plain lost floor.
  *     The probe is NEVER consulted (a non-durable session is not re-attachable).
  *
- * The SAFE direction (I10 — the whole point). A false `reattach` would spawn a SECOND CLI
+ * The SAFE direction (the whole point). A false `reattach` would spawn a SECOND CLI
  * against a session whose liveness we could not confirm — a double-drive. So on ANY doubt
  * (a throwing probe, a falsy/missing `tmuxName`, a degenerate descriptor) the decision
  * fails to `failed`/`tmux_session_gone`, NEVER `reattach`. The decision NEVER issues a
  * create frame — it only SIGNALS re-attach; the worker's `has-session`-gated backend does
  * the no-double-create (terminal-tmux-backend.ts:194-201).
  *
- * The I5 identity passthrough (durability changes WHERE, never WHAT). The descriptor
+ * The identity passthrough (durability changes WHERE, never WHAT). The descriptor
  * carries `allowId`/`owner`/`scope`; the `reattach` action returns the SAME descriptor
  * object UNCHANGED — the decision never derives or widens the allow-entry/jail/uid. The
- * registry (165-06) re-applies the SAME owner-gate from these carried fields.
+ * registry re-applies the SAME owner-gate from these carried fields.
  *
- * Architecture invariants (binding — AGENTS.md / 124 house style, mirrors
+ * Architecture invariants (binding — AGENTS.md; mirrors
  * `terminal-drive-journal.ts` / `terminal-drive-promote.ts` / `terminal-dialog-detector.ts`):
  *   - PURE: free functions, NOT a factory. NO module-global mutable state, NO clock/timer
  *     reads, NO env read, NO I/O — the `has-session` liveness is an INJECTED probe
@@ -58,50 +57,50 @@ import type { SessionOwner } from "./terminal-session-owner.js";
 /**
  * The durable per-session record the registry persists for a `drive.durable:true`
  * session and recovers on boot. It carries exactly the identity the registry needs to
- * rebuild a running `SessionHandle` and re-attach to the SAME jail (I5) — never more.
+ * rebuild a running `SessionHandle` and re-attach to the SAME jail — never more.
  */
 export interface SessionDescriptor {
     /**
-     * The STABLE worker handle key. Today this is an ephemeral `randomUUID()` the registry
-     * never persists; persisting it (so it survives a restart) is the gap DUR-01 closes.
+     * The STABLE worker handle key. The registry mints it as `randomUUID()`; persisting it
+     * here (so it survives a restart) is what makes recover-on-boot possible.
      */
     sessionId: string;
     /**
-     * `tmuxSessionName(sessionId)` === `comis-<sessionId>` — the deterministic re-attach key
-     * (§7.1.5). The `has-session` probe is run against THIS name. Never a second naming
+     * `tmuxSessionName(sessionId)` === `comis-<sessionId>` — the deterministic re-attach key.
+     * The `has-session` probe is run against THIS name. Never a second naming
      * scheme: it must equal what `terminal-tmux-backend.ts:54` derives.
      */
     tmuxName: string;
     /**
-     * RECUR-03 (option A, per-generation tmux server): the explicit `-S` socket path the durable
+     * Per-generation tmux server: the explicit `-S` socket path the durable
      * session's tmux server is bound to — the PER-BOOT socket of the daemon generation that created
      * it (`<durableDir>/tmux-<gen>.sock`). Persisting it per-session is what lets a restart re-attach
      * the surviving session from its OWN server while NEW sessions get a fresh server (in the live
      * mount namespace) on the new boot's socket — so a stranded prior-generation ns never breaks new
-     * `bwrap` sessions (RECUR-02). OPTIONAL: absent on a pre-RECUR-03 / non-durable descriptor, where
-     * the caller falls back to the boot socket. Validated as a non-empty string when present.
+     * `bwrap` sessions. OPTIONAL: absent on a descriptor persisted without one (e.g. non-durable),
+     * where the caller falls back to the boot socket. Validated as a non-empty string when present.
      */
     tmuxSocket?: string;
-    /** The allow-entry id to re-stamp VERBATIM on re-attach (I5 — WHERE not WHAT). */
+    /** The allow-entry id to re-stamp VERBATIM on re-attach (WHERE not WHAT). */
     allowId: string;
-    /** The owning `(agentId, sessionKey)` to re-stamp VERBATIM (I5); type-only import. */
+    /** The owning `(agentId, sessionKey)` to re-stamp VERBATIM; type-only import. */
     owner: SessionOwner;
-    /** The SAME jail/uid/credentialPaths scope (I5 — never widened); type-only import. */
+    /** The SAME jail/uid/credentialPaths scope — never widened; type-only import. */
     scope?: TerminalScope;
     /** Terminal columns of the (resumed) session. */
     cols: number;
     /** Terminal rows of the (resumed) session. */
     rows: number;
     /**
-     * `false` ⇒ the {@link reattachDecision} `fallback_nondurable` short-circuit (I1 —
-     * today's lost floor for a non-durable spawn session; the probe is never consulted).
+     * `false` ⇒ the {@link reattachDecision} `fallback_nondurable` short-circuit (the
+     * plain lost floor for a non-durable spawn session; the probe is never consulted).
      */
     durable: boolean;
     /** Creation wall-clock (ms) — for the resumed session's wall-clock cap. */
     createdAt: number;
 }
 /**
- * The DUR-01 re-attach decision — a closed discriminated union the registry switches on.
+ * The re-attach decision — a closed discriminated union the registry switches on.
  * `reattach` carries the descriptor (verbatim, for re-stamping); `failed`/`fallback`
  * carry only the content-free `sessionId` (+ a reason on the genuine-death branch).
  */
@@ -118,20 +117,20 @@ export type ReattachDecision = {
 };
 /**
  * Decide whether a persisted durable session should be re-attached, failed, or skipped as
- * non-durable — PURE, TOTAL, never throws (RESEARCH Pattern 1 / plan 165-01).
+ * non-durable — PURE, TOTAL, never throws.
  *
  * The decision order:
  *   1. NOT durable (or a degenerate descriptor with no `durable:true`) → `fallback_nondurable`
- *      (I1 — the lost floor short-circuit; `isTmuxAlive` is NEVER consulted).
+ *      (the lost-floor short-circuit; `isTmuxAlive` is NEVER consulted).
  *   2. Durable but a falsy/missing `tmuxName` → `failed` (unrecoverable identity; we never
  *      probe a falsy name).
  *   3. Durable + a well-formed name → probe `isTmuxAlive(tmuxName)` inside try/catch:
  *      - the probe THROWS → `failed` (the SAFE direction — never re-attach on doubt).
- *      - the probe returns truthy → `reattach` (the session survived, I10).
- *      - the probe returns falsy → `failed`/`tmux_session_gone` (genuinely gone, I10 — the
+ *      - the probe returns truthy → `reattach` (the session survived).
+ *      - the probe returns falsy → `failed`/`tmux_session_gone` (genuinely gone — the
  *        caller preserves the journal SEPARATELY; nothing is deleted here).
  *
- * NEVER re-attaches on doubt: a false `reattach` double-drives (I10). The decision issues
+ * NEVER re-attaches on doubt: a false `reattach` double-drives. The decision issues
  * no create frame — it only signals re-attach; the worker backend does the no-double-create.
  *
  * @param d - The persisted descriptor recovered on boot (untrusted after a crash).
@@ -148,8 +147,8 @@ export declare function serializeDescriptor(d: SessionDescriptor): string;
  *
  * Unlike `deserializeJournal` (which DEFAULTS oddities to a safe resumable shape), this
  * REJECTS any descriptor missing a required identity field or carrying a wrong-typed one —
- * the descriptor's fields are load-bearing AUTHORIZATION identity (I5), not best-effort
+ * the descriptor's fields are load-bearing AUTHORIZATION identity, not best-effort
  * resumable counts; a half-trusted descriptor must never reach the re-attach decision
- * (T-165-03 — a corrupt descriptor is a corrupt-SKIP, like `recoverWakeStates`).
+ * (a corrupt descriptor is a corrupt-SKIP, like `recoverWakeStates`).
  */
 export declare function deserializeDescriptor(raw: unknown): SessionDescriptor | undefined;

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

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The pure DUR-01 re-attach decision + the durable session descriptor (Phase 165;
- * CONTEXT §7.1.5 / design §4 Phase C / RESEARCH Pattern 1).
+ * The pure re-attach decision + the durable session descriptor.
  *
- * THE FRAMING CORRECTION (the load-bearing finding of this phase). The tmux re-attach
+ * THE FRAMING (why this module exists at this layer). The tmux re-attach
  * MECHANISM already ships: `terminal-tmux-backend.ts` derives the deterministic
  * `comis-<sessionId>` name ({@link tmuxSessionName}), `has-session`-gates create-vs-
  * reattach, and `terminal-tmux-backend.linux.test.ts` proves a detached named session
@@ -12,33 +11,33 @@
  * recover-on-boot — so on a daemon restart its `sessions` Map starts EMPTY, and a healthy
  * 38h drive whose `comis-<old-id>` is STILL alive under tmux is wrongly flipped `lost`.
  * This module is NOT a tmux rebuild; it is the missing IDENTITY ({@link SessionDescriptor})
- * + the pure DECISION ({@link reattachDecision}) the registry's recover-on-boot (165-06)
+ * + the pure DECISION ({@link reattachDecision}) the registry's recover-on-boot
  * consumes to turn "the tmux server survived" into "the registry knows to re-attach."
  *
  * Given a persisted descriptor + a live `has-session` probe, {@link reattachDecision}
  * decides ONE of three actions:
- *   - `reattach` — durable + the tmux session is LIVE: re-attach (I10 — a 40h drive
- *     crosses the daemon's lifetime and is never lost). The descriptor (carrying the I5
- *     identity) is returned VERBATIM for the caller to re-stamp.
+ *   - `reattach` — durable + the tmux session is LIVE: re-attach (a 40h drive
+ *     crosses the daemon's lifetime and is never lost). The descriptor (carrying the
+ *     authorization identity) is returned VERBATIM for the caller to re-stamp.
  *   - `failed`/`tmux_session_gone` — durable but the tmux session is GONE (or the probe is
  *     unanswerable): a genuine death surfaces. The JOURNAL is preserved SEPARATELY by the
- *     caller (NOT touched here, I10) — never a silent restart, never a double-drive.
- *   - `fallback_nondurable` — a `durable:false` (spawn) session: today's lost floor (I1).
+ *     caller (NOT touched here) — never a silent restart, never a double-drive.
+ *   - `fallback_nondurable` — a `durable:false` (spawn) session: the plain lost floor.
  *     The probe is NEVER consulted (a non-durable session is not re-attachable).
  *
- * The SAFE direction (I10 — the whole point). A false `reattach` would spawn a SECOND CLI
+ * The SAFE direction (the whole point). A false `reattach` would spawn a SECOND CLI
  * against a session whose liveness we could not confirm — a double-drive. So on ANY doubt
  * (a throwing probe, a falsy/missing `tmuxName`, a degenerate descriptor) the decision
  * fails to `failed`/`tmux_session_gone`, NEVER `reattach`. The decision NEVER issues a
  * create frame — it only SIGNALS re-attach; the worker's `has-session`-gated backend does
  * the no-double-create (terminal-tmux-backend.ts:194-201).
  *
- * The I5 identity passthrough (durability changes WHERE, never WHAT). The descriptor
+ * The identity passthrough (durability changes WHERE, never WHAT). The descriptor
  * carries `allowId`/`owner`/`scope`; the `reattach` action returns the SAME descriptor
  * object UNCHANGED — the decision never derives or widens the allow-entry/jail/uid. The
- * registry (165-06) re-applies the SAME owner-gate from these carried fields.
+ * registry re-applies the SAME owner-gate from these carried fields.
  *
- * Architecture invariants (binding — AGENTS.md / 124 house style, mirrors
+ * Architecture invariants (binding — AGENTS.md; mirrors
  * `terminal-drive-journal.ts` / `terminal-drive-promote.ts` / `terminal-dialog-detector.ts`):
  *   - PURE: free functions, NOT a factory. NO module-global mutable state, NO clock/timer
  *     reads, NO env read, NO I/O — the `has-session` liveness is an INJECTED probe
@@ -60,20 +59,20 @@ function safeSessionId(d) {
 }
 /**
  * Decide whether a persisted durable session should be re-attached, failed, or skipped as
- * non-durable — PURE, TOTAL, never throws (RESEARCH Pattern 1 / plan 165-01).
+ * non-durable — PURE, TOTAL, never throws.
  *
  * The decision order:
  *   1. NOT durable (or a degenerate descriptor with no `durable:true`) → `fallback_nondurable`
- *      (I1 — the lost floor short-circuit; `isTmuxAlive` is NEVER consulted).
+ *      (the lost-floor short-circuit; `isTmuxAlive` is NEVER consulted).
  *   2. Durable but a falsy/missing `tmuxName` → `failed` (unrecoverable identity; we never
  *      probe a falsy name).
  *   3. Durable + a well-formed name → probe `isTmuxAlive(tmuxName)` inside try/catch:
  *      - the probe THROWS → `failed` (the SAFE direction — never re-attach on doubt).
- *      - the probe returns truthy → `reattach` (the session survived, I10).
- *      - the probe returns falsy → `failed`/`tmux_session_gone` (genuinely gone, I10 — the
+ *      - the probe returns truthy → `reattach` (the session survived).
+ *      - the probe returns falsy → `failed`/`tmux_session_gone` (genuinely gone — the
  *        caller preserves the journal SEPARATELY; nothing is deleted here).
  *
- * NEVER re-attaches on doubt: a false `reattach` double-drives (I10). The decision issues
+ * NEVER re-attaches on doubt: a false `reattach` double-drives. The decision issues
  * no create frame — it only signals re-attach; the worker backend does the no-double-create.
  *
  * @param d - The persisted descriptor recovered on boot (untrusted after a crash).
@@ -82,7 +81,7 @@ function safeSessionId(d) {
 export function reattachDecision(d, isTmuxAlive) {
     const sessionId = safeSessionId(d);
     // (1) Non-durable (or a descriptor that is not affirmatively durable) → the lost-floor
-    // short-circuit. The probe is irrelevant for a session that is not re-attachable (I1).
+    // short-circuit. The probe is irrelevant for a session that is not re-attachable.
     if (d?.durable !== true) {
         return { action: "fallback_nondurable", sessionId };
     }
@@ -93,18 +92,18 @@ export function reattachDecision(d, isTmuxAlive) {
         return { action: "failed", sessionId, reason: "tmux_session_gone" };
     }
     // (3) Probe liveness. A throwing probe is treated as "cannot confirm alive" → the SAFE
-    // direction is `failed`, NEVER `reattach` (a false re-attach would double-drive, I10).
+    // direction is `failed`, NEVER `reattach` (a false re-attach would double-drive).
     let alive;
     try {
-        // RECUR-03: probe the session's OWN per-boot server (`d.tmuxSocket`) — a survivor sits on its
-        // prior-boot socket, not this boot's. Absent (pre-RECUR-03 descriptor) ⇒ the probe's default.
+        // Probe the session's OWN per-boot server (`d.tmuxSocket`) — a survivor sits on its
+        // prior-boot socket, not this boot's. Absent socket ⇒ the probe's default.
         alive = isTmuxAlive(name, d.tmuxSocket) === true;
     }
     catch {
         return { action: "failed", sessionId, reason: "tmux_session_gone" };
     }
     return alive
-        ? { action: "reattach", descriptor: d } // survived the restart → re-attach (I10), identity verbatim
+        ? { action: "reattach", descriptor: d } // survived the restart → re-attach, identity verbatim
         : { action: "failed", sessionId, reason: "tmux_session_gone" }; // genuinely gone (journal kept by caller)
 }
 // ---------------------------------------------------------------------------
@@ -136,8 +135,8 @@ function isOwner(v) {
 }
 /**
  * The closed enum literals {@link TerminalScope} permits — validated structurally so a
- * smuggled-after-crash scope cannot inject an out-of-band filesystem/network/uid posture
- * (T-165-03). The optional `paths`/`hosts` arrays must be string[] when present.
+ * smuggled-after-crash scope cannot inject an out-of-band filesystem/network/uid posture.
+ * The optional `paths`/`hosts` arrays must be string[] when present.
  */
 function isScope(v) {
     if (v === null || typeof v !== "object")
@@ -164,9 +163,9 @@ function isScope(v) {
  *
  * Unlike `deserializeJournal` (which DEFAULTS oddities to a safe resumable shape), this
  * REJECTS any descriptor missing a required identity field or carrying a wrong-typed one —
- * the descriptor's fields are load-bearing AUTHORIZATION identity (I5), not best-effort
+ * the descriptor's fields are load-bearing AUTHORIZATION identity, not best-effort
  * resumable counts; a half-trusted descriptor must never reach the re-attach decision
- * (T-165-03 — a corrupt descriptor is a corrupt-SKIP, like `recoverWakeStates`).
+ * (a corrupt descriptor is a corrupt-SKIP, like `recoverWakeStates`).
  */
 export function deserializeDescriptor(raw) {
     let parsed = raw;
@@ -200,10 +199,10 @@ export function deserializeDescriptor(raw) {
     if (r.scope !== undefined && !isScope(r.scope)) {
         return undefined;
     }
-    // RECUR-03: `tmuxSocket` is optional, but if present it must be a non-empty string — a
+    // `tmuxSocket` is optional, but if present it must be a non-empty string — a
     // smuggled-after-crash non-string socket must never reach the per-session has-session probe /
-    // attach (it would target the wrong / a degenerate server). A missing one is a pre-RECUR-03 /
-    // non-durable descriptor (the caller falls back to the boot socket), NOT a rejection.
+    // attach (it would target the wrong / a degenerate server). A missing one means the caller
+    // falls back to the boot socket — it is NOT a rejection.
     if (r.tmuxSocket !== undefined && !isNonEmptyString(r.tmuxSocket)) {
         return undefined;
     }

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

@@ -1,23 +1,23 @@
 /**
- * The per-session terminal-emulator wrapper (spec §2.4 rendering).
+ * The per-session terminal-emulator wrapper (rendering).
  *
  * Wraps a REAL `@xterm/headless` `Terminal` into a small pluggable surface the
- * worker stores per session. This is the new source of truth for the `read`
+ * worker stores per session. This is the source of truth for the `read`
  * snapshot: a stable `cols×rows` character grid, the REAL cursor
  * (`buffer.active.cursorX/cursorY`), and the REAL alt-screen flag
- * (`buffer.active.type === "alternate"`) — REPLACING the earlier raw stdout-ring
- * snapshot. Full-screen TUIs (`vim`/`htop`) draw into a stable grid; the agent
- * must perceive that grid, not a raw byte log.
+ * (`buffer.active.type === "alternate"`) — the raw stdout-ring is only the
+ * emulator-absent fallback. Full-screen TUIs (`vim`/`htop`) draw into a stable
+ * grid; the agent must perceive that grid, not a raw byte log.
  *
  * The emulator is extracted into this module (not inlined in the worker) so the
  * worker stays under the 800-line architecture cap — the heavy @xterm
  * integration lives here.
  *
- * Render formats (§2.4): `snapshot({format})` returns the plain grid
+ * Render formats: `snapshot({format})` returns the plain grid
  * (`text`, default), the ansi-with-SGR serialization (`ansi` via the
  * SerializeAddon's `serialize()`), or an HTML fragment (`html` via
  * `serializeAsHTML()`). `snapshot({scrollback:N})` includes the N retained rows
- * ABOVE the viewport (perception beyond the fold). Per §11 the
+ * ABOVE the viewport (perception beyond the fold). The
  * addon-serialize dep is pinned (0.14.0) + golden-frame tested against
  * churn.
  *
@@ -27,7 +27,7 @@
  * screen-diff (a changed flag + changed-row range) so the agent / the
  * classifier can cheaply see what changed without re-diffing whole grids.
  *
- * §2.4 flush primitive: `@xterm`'s `term.write(data, cb)` is ASYNC-PARSED — the
+ * Flush primitive: `@xterm`'s `term.write(data, cb)` is ASYNC-PARSED — the
  * callback fires once the chunk is fully parsed into the buffer. `write` here
  * returns a Promise that resolves on that callback, so the worker can `await`
  * the parse before serializing a SETTLED frame (the "debounce → serialize once
@@ -56,16 +56,16 @@ export interface SessionEmulatorOptions {
      */
     scrollback: number;
     /**
-     * An OPTIONAL read-side render transform — a selected platform profile's `transformSnapshot`
-     * (RENDER-01). Applied to TEXT-format snapshots AFTER the agnostic grid is built; the emulator
+     * An OPTIONAL read-side render transform — a selected platform profile's `transformSnapshot`.
+     * Applied to TEXT-format snapshots AFTER the agnostic grid is built; the emulator
      * attaches the viewport cell `grid` so the transform can read cell-level attributes (e.g. `dim`).
      * GENERIC (the engine knows nothing of the profile) and identity by default — absent ⇒ the plain
-     * `translateToString` grid, byte-identical to today (INV-1). The Claude ghost-strip is one such
-     * transform, living in `platforms/claude-code/profile.ts` — never here.
+     * `translateToString` grid, byte-identical to the untransformed path. The Claude ghost-strip is
+     * one such transform, living in `platforms/claude-code/profile.ts` — never here.
      */
     transformSnapshot?: (snap: EmulatorSnapshot) => EmulatorSnapshot;
 }
-/** The render format for `snapshot().screen` (spec §2.4 / §5 `read` formats). */
+/** The render format for `snapshot().screen` (the `read` tool's format choices). */
 export type RenderFormat = "text" | "ansi" | "html";
 /**
  * Options for {@link SessionEmulator.snapshot}. `format` selects the `screen`
@@ -116,9 +116,9 @@ export interface EmulatorSnapshot {
     /**
      * The viewport cell grid (rows × cells, each `{chars,dim,width}`) — the structured input a
      * read-side platform-profile `transformSnapshot` needs for the cell-level attributes the
-     * flattened `screen` string has lost (e.g. SGR-2 `dim` for the Claude ghost-strip, RENDER-01).
+     * flattened `screen` string has lost (e.g. SGR-2 `dim` for the Claude ghost-strip).
      * Populated by the emulator ONLY for `format:"text"` snapshots AND only when a profile transform
-     * is wired (the agnostic path never builds it — zero added cost, INV-1). Absent ⇒ a transform
+     * is wired (the agnostic path never builds it — zero added cost). Absent ⇒ a transform
      * must no-op (it has no cell attributes to act on).
      */
     grid?: readonly (readonly RenderCell[])[];
@@ -130,7 +130,7 @@ export interface EmulatorSnapshot {
  */
 export interface SessionEmulator {
     /**
-     * Feed a chunk into the emulator. Resolves on the §2.4 parse-complete flush
+     * Feed a chunk into the emulator. Resolves on the parse-complete flush
      * (the `@xterm` `write(data, cb)` callback), so the worker can await the parse
      * before serializing a settled frame.
      */
@@ -144,7 +144,7 @@ export interface SessionEmulator {
     /** Resize the grid; reflows the buffer. */
     resize(cols: number, rows: number): void;
     /**
-     * True when buffer lines exist BELOW the displayed viewport bottom — the §2.4
+     * True when buffer lines exist BELOW the displayed viewport bottom — the
      * "more content below the fold" signal the settle composes (a below-fold
      * frame is NOT settled). False at the bottom, on short output, and on the
      * alternate buffer (alt apps own the full screen, no scrollback below).
@@ -227,7 +227,7 @@ export interface ReadResult {
  * validated to one of `text|ansi|html` (anything else → `text`); `scrollback` is
  * a non-negative number (anything else → `0`). Kept here so the worker stays
  * under the 800-line cap. `includeAltBuffer` is ignored for now — alt is captured
- * by default per §2.4; an explicit alt-exclude is out of scope.
+ * by default; an explicit alt-exclude is out of scope.
  *
  * @param params - The decoded read-frame params (`frame.params`).
  * @returns The validated `{format, scrollback}` snapshot options.

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

@@ -1,24 +1,24 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The per-session terminal-emulator wrapper (spec §2.4 rendering).
+ * The per-session terminal-emulator wrapper (rendering).
  *
  * Wraps a REAL `@xterm/headless` `Terminal` into a small pluggable surface the
- * worker stores per session. This is the new source of truth for the `read`
+ * worker stores per session. This is the source of truth for the `read`
  * snapshot: a stable `cols×rows` character grid, the REAL cursor
  * (`buffer.active.cursorX/cursorY`), and the REAL alt-screen flag
- * (`buffer.active.type === "alternate"`) — REPLACING the earlier raw stdout-ring
- * snapshot. Full-screen TUIs (`vim`/`htop`) draw into a stable grid; the agent
- * must perceive that grid, not a raw byte log.
+ * (`buffer.active.type === "alternate"`) — the raw stdout-ring is only the
+ * emulator-absent fallback. Full-screen TUIs (`vim`/`htop`) draw into a stable
+ * grid; the agent must perceive that grid, not a raw byte log.
  *
  * The emulator is extracted into this module (not inlined in the worker) so the
  * worker stays under the 800-line architecture cap — the heavy @xterm
  * integration lives here.
  *
- * Render formats (§2.4): `snapshot({format})` returns the plain grid
+ * Render formats: `snapshot({format})` returns the plain grid
  * (`text`, default), the ansi-with-SGR serialization (`ansi` via the
  * SerializeAddon's `serialize()`), or an HTML fragment (`html` via
  * `serializeAsHTML()`). `snapshot({scrollback:N})` includes the N retained rows
- * ABOVE the viewport (perception beyond the fold). Per §11 the
+ * ABOVE the viewport (perception beyond the fold). The
  * addon-serialize dep is pinned (0.14.0) + golden-frame tested against
  * churn.
  *
@@ -28,7 +28,7 @@
  * screen-diff (a changed flag + changed-row range) so the agent / the
  * classifier can cheaply see what changed without re-diffing whole grids.
  *
- * §2.4 flush primitive: `@xterm`'s `term.write(data, cb)` is ASYNC-PARSED — the
+ * Flush primitive: `@xterm`'s `term.write(data, cb)` is ASYNC-PARSED — the
  * callback fires once the chunk is fully parsed into the buffer. `write` here
  * returns a Promise that resolves on that callback, so the worker can `await`
  * the parse before serializing a SETTLED frame (the "debounce → serialize once
@@ -74,7 +74,7 @@ export function createSessionEmulator(opts) {
     });
     // The SerializeAddon backs the `ansi`/`html` formats. Loaded once at
     // construction; `serialize()`/`serializeAsHTML()` read the buffer on demand.
-    // Pinned 0.14.0 + golden-frame tested against addon churn (§11).
+    // Pinned 0.14.0 + golden-frame tested against addon churn.
     const serializeAddon = new SerializeAddon();
     term.loadAddon(serializeAddon);
     let disposed = false;
@@ -95,7 +95,7 @@ export function createSessionEmulator(opts) {
             }
         }
         // The AGNOSTIC grid: every viewport row is the plain `translateToString(true)` — no platform
-        // transforms (RENDER-01 / INV-1). A profile's read-side `transformSnapshot` (e.g. the Claude
+        // transforms. A profile's read-side `transformSnapshot` (e.g. the Claude
         // ghost-strip) is applied later, in `snapshot()`, using the cell `grid` — never woven in here.
         for (let y = 0; y < term.rows; y++) {
             lines.push(buf.getLine(buf.baseY + y)?.translateToString(true) ?? "");
@@ -104,7 +104,7 @@ export function createSessionEmulator(opts) {
     }
     /**
      * Build the viewport cell grid (rows × cells) for a read-side profile transform. Read on demand
-     * (text format + a wired transform only) so the agnostic path pays nothing (INV-1).
+     * (text format + a wired transform only) so the agnostic path pays nothing.
      */
     function readViewportGrid() {
         const buf = term.buffer.active;
@@ -132,7 +132,7 @@ export function createSessionEmulator(opts) {
     return {
         term,
         write(data) {
-            // The callback is the §2.4 parse-complete flush — resolve on it (NOT on
+            // The callback is the parse-complete flush — resolve on it (NOT on
             // write's synchronous return) so the worker's await genuinely waits for the
             // grid to reflect the bytes.
             return new Promise((resolve) => {
@@ -150,11 +150,11 @@ export function createSessionEmulator(opts) {
                 rows: term.rows,
                 alt: buf.type === "alternate",
             };
-            // Apply the selected profile's read-side transform (RENDER-01) AFTER the agnostic snapshot.
+            // Apply the selected profile's read-side transform AFTER the agnostic snapshot.
             // ONLY for `text` (the sole format whose `screen` is the plain row grid the transform rewrites)
             // and ONLY when a transform is wired — the engine attaches the viewport cell `grid` so the
             // transform can read cell attributes (`dim`) the flat `screen` lost. No transform / non-text ⇒
-            // the plain grid is returned untouched (INV-1). The engine stays platform-agnostic: it applies
+            // the plain grid is returned untouched. The engine stays platform-agnostic: it applies
             // a generic hook, never a Claude-specific branch.
             if (transformSnapshot !== undefined && format === "text") {
                 return transformSnapshot({ ...base, grid: readViewportGrid() });
@@ -223,7 +223,7 @@ export function diffSnapshot(prev, next) {
  * validated to one of `text|ansi|html` (anything else → `text`); `scrollback` is
  * a non-negative number (anything else → `0`). Kept here so the worker stays
  * under the 800-line cap. `includeAltBuffer` is ignored for now — alt is captured
- * by default per §2.4; an explicit alt-exclude is out of scope.
+ * by default; an explicit alt-exclude is out of scope.
  *
  * @param params - The decoded read-frame params (`frame.params`).
  * @returns The validated `{format, scrollback}` snapshot options.

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

@@ -71,7 +71,7 @@ export interface ScopeArgsInput {
      * gateway-token family / master key). bwrap `--unsetenv` is name-only, so a prefix
      * family (`GATEWAY_TOKEN_*`) must arrive here as enumerated concrete names; this is
      * what protects the DEFAULT tmux/durable backend, which inherits the tmux SERVER env
-     * and bypasses the `scrubChildEnv` object (TERM-ENV-GATEWAY-TOKEN-LEAK). Order- and
+     * and bypasses the `scrubChildEnv` object. Order- and
      * duplicate-insensitive (deduped against the fixed list before emit).
      */
     extraUnsetEnvKeys?: readonly string[];
@@ -89,6 +89,6 @@ export interface ScopeArgsInput {
  * explicitly for the controlling tty. The `<network>` refinement comes AFTER
  * `--unshare-all` — bwrap mutates its unshare set per flag IN ARG ORDER, so a
  * `--share-net` emitted before the unshare-all would be re-clobbered and the
- * jail would get NO network even at `network:"full"` (the live-VPS T5 bug).
+ * jail would get NO network even at `network:"full"` (a live-VPS-reproduced bug).
  */
 export declare function buildScopeArgs(input: ScopeArgsInput): string[];

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

@@ -136,7 +136,7 @@ function isUnderDir(child, parent) {
  * explicitly for the controlling tty. The `<network>` refinement comes AFTER
  * `--unshare-all` — bwrap mutates its unshare set per flag IN ARG ORDER, so a
  * `--share-net` emitted before the unshare-all would be re-clobbered and the
- * jail would get NO network even at `network:"full"` (the live-VPS T5 bug).
+ * jail would get NO network even at `network:"full"` (a live-VPS-reproduced bug).
  */
 export function buildScopeArgs(input) {
     const args = [input.bwrapPath];
@@ -191,19 +191,20 @@ export function buildScopeArgs(input) {
     //    `NODE_OPTIONS=--permission …` leaked into a driven claude AND CLAUDE_CODE_BUBBLEWRAP never
     //    reached it → its Bash/SessionStart hook EROFS'd on the default backend). `--unsetenv` strips
     //    the daemon's interpreter-control hardening (NODE_OPTIONS, BASH_ENV, …) + the CLAUDECODE
-    //    sentinel; `--setenv CLAUDE_CODE_BUBBLEWRAP=1` (EROFS-01) tells the driven CLI it is already
+    //    sentinel; `--setenv CLAUDE_CODE_BUBBLEWRAP=1` tells the driven CLI it is already
     //    bubblewrapped so it does NOT nest its own (nested-broken) sandbox. The PTY-path `env` scrub
     //    (`scrubChildEnv`) stays as defense-in-depth; this is the authoritative, backend-independent
     //    application.
     //    The fixed interpreter-control/CLAUDECODE names ALWAYS unset; the caller-supplied
-    //    daemon-secret names (the gateway-token family / master key present in the live env —
-    //    TERM-ENV-GATEWAY-TOKEN-LEAK) are deduped in so the tmux backend strips them too.
+    //    daemon-secret names (the gateway-token family / master key present in the live env,
+    //    which would otherwise leak into driven children) are deduped in so the tmux backend
+    //    strips them too.
     const unsetEnvKeys = new Set([...JAIL_UNSET_ENV_VARS, ...(input.extraUnsetEnvKeys ?? [])]);
     for (const key of unsetEnvKeys) {
         args.push("--unsetenv", key);
     }
     args.push("--setenv", "CLAUDE_CODE_BUBBLEWRAP", "1");
-    // -- claude session-env carve-out (EROFS-03) -- a writable tmpfs at <home>/.claude/session-env.
+    // -- claude session-env carve-out -- a writable tmpfs at <home>/.claude/session-env.
     //    claude's OWN bash sandbox remounts $HOME read-only IN-PLACE before `mkdir ~/.claude/
     //    session-env/<id>` (its per-bash-command state) → EROFS on the default durable backend in the
     //    prod seccomp'd daemon (CLAUDE_CODE_BUBBLEWRAP does NOT suppress that remount there — it only
@@ -245,8 +246,8 @@ export function buildScopeArgs(input) {
     //    which also shadows the session workspace when it IS the agent's OWN workspace
     //    (the default `<dataDir>/workspace/<agent>`, the same dir the agent's read/
     //    write/exec tools operate on). Re-bind ONLY that subpath RW on top of the
-    //    tmpfs so the workspace is writable + PERSISTENT in the jail (a driven GSD
-    //    milestone's work survives), while the secrets at sibling <dataDir> paths
+    //    tmpfs so the workspace is writable + PERSISTENT in the jail (a driven
+    //    long-running coding session's work survives), while the secrets at sibling <dataDir> paths
     //    (secret.db / .env / config.yaml / memory.db) stay shadowed. A workspace
     //    OUTSIDE <dataDir> (e.g. an operator-relocated dir) needs no re-bind — its
     //    earlier `pushFilesystemBinds` mount is never masked. `isUnderDir` is strict

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

@@ -88,7 +88,7 @@ export async function enforceSendCaps(deps, sessionId, owner, toolName) {
  */
 export function auditKeystroke(deps, sessionId, toolName, kind, payload, outcome) {
     const { text: redactedText, redactions } = scrubSecretsFromText(payload);
-    // DEBUG (not INFO): the keystroke audit is a §2.7 step-tagged intermediate-stage record;
+    // DEBUG (not INFO): the keystroke audit is a step-tagged intermediate-stage record;
     // the send completion INFO line (with durationMs) stays the one INFO per send. Keeping
     // the audit at DEBUG also avoids shadowing that completion line for log consumers.
     deps.logger.debug({ toolName, sessionId, redactedText, redactions, outcome, step: "keystroke_audit" }, "terminal keystroke");