comisai 1.0.44 → 1.0.46

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

@@ -1,5 +1,5 @@
 /**
- * The origin key that scopes a terminal session's visibility (spec §2.1, §4.7).
+ * The origin key that scopes a terminal session's visibility.
  *
  * A `SessionOwner` is the pair `(agentId, sessionKey)`. The `sessionId` stays the
  * opaque worker handle; OWNERSHIP — not the handle — is the authorization gate the
@@ -10,8 +10,8 @@
  * MUTUALLY INVISIBLE: a cross-owner read/get returns the not-found minimal view /
  * `undefined`, never the other owner's bytes.
  *
- * Net-new vs `ProcessRegistry` (which keys per-`agentId` only) — the spec §2.1
- * calls the origin key net-new. Extracted to its OWN module (zero imports) so the
+ * Net-new vs `ProcessRegistry` (which keys per-`agentId` only). Extracted to its OWN
+ * module (zero imports) so the
  * registry stays under the 800-line architecture cap; the worker is owner-agnostic
  * (it only knows `sessionId`).
  *

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The origin key that scopes a terminal session's visibility (spec §2.1, §4.7).
+ * The origin key that scopes a terminal session's visibility.
  *
  * A `SessionOwner` is the pair `(agentId, sessionKey)`. The `sessionId` stays the
  * opaque worker handle; OWNERSHIP — not the handle — is the authorization gate the
@@ -11,8 +11,8 @@
  * MUTUALLY INVISIBLE: a cross-owner read/get returns the not-found minimal view /
  * `undefined`, never the other owner's bytes.
  *
- * Net-new vs `ProcessRegistry` (which keys per-`agentId` only) — the spec §2.1
- * calls the origin key net-new. Extracted to its OWN module (zero imports) so the
+ * Net-new vs `ProcessRegistry` (which keys per-`agentId` only). Extracted to its OWN
+ * module (zero imports) so the
  * registry stays under the 800-line architecture cap; the worker is owner-agnostic
  * (it only knows `sessionId`).
  *

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

@@ -1,46 +1,46 @@
 /**
- * The DUR-01 recover-on-boot SCAN orchestrator + the injected descriptor-store port
- * (Phase 165, plan 06; RESEARCH Pattern 1, Pitfall 5). This is the SIBLING that keeps
- * the 772-line registry under the 800-line cap: the registry's recover-on-boot is a
- * thin call into {@link recoverSessionDescriptors}, never an inlined scan loop.
+ * The recover-on-boot SCAN orchestrator + the injected descriptor-store port. This is
+ * the SIBLING that keeps the registry under the 800-line cap: the registry's
+ * recover-on-boot is a thin call into {@link recoverSessionDescriptors}, never an
+ * inlined scan loop.
  *
- * WHY THIS EXISTS (the load-bearing DUR-01 gap, framed in terminal-reattach-match.ts).
+ * WHY THIS EXISTS (the load-bearing gap, framed in terminal-reattach-match.ts).
  * The tmux re-attach MECHANISM already ships (deterministic `comis-<id>` name +
  * `has-session`-gated create-vs-reattach + a linux survival test). The genuine gap is
  * one layer UP: the registry's `sessionId` is an ephemeral `randomUUID()` it never
  * persists, and there is NO recover-on-boot — so on a daemon restart its `sessions`
  * Map starts EMPTY and a healthy 40h drive whose `comis-<old-id>` is STILL alive under
  * tmux is wrongly flipped `lost`. This module is the missing RECONCILIATION: scan the
- * persisted {@link SessionDescriptor}s, run each through 165-01's pure
+ * persisted {@link SessionDescriptor}s, run each through the pure
  * {@link reattachDecision}, and yield a typed list the registry switches on.
  *
- * THE DECISION VOCABULARY (mirrors 165-01, NOT a second copy). Each recovered
- * descriptor maps to exactly one {@link RecoveredAction}:
+ * THE DECISION VOCABULARY (mirrors {@link reattachDecision}, NOT a second copy). Each
+ * recovered descriptor maps to exactly one {@link RecoveredAction}:
  *   - `reattach` — durable + the tmux session is LIVE: the registry rehydrates a
  *     `running` handle ({@link rehydrateHandleFromDescriptor}) and issues NO create
- *     frame (I10 — the worker's `has-session`-gated backend re-attaches the surviving
- *     pane on the NEXT read; a fresh create would double-drive). The descriptor's I5
- *     identity (allowId/owner/scope) is carried VERBATIM.
+ *     frame (the worker's `has-session`-gated backend re-attaches the surviving
+ *     pane on the NEXT read; a fresh create would double-drive). The descriptor's
+ *     persisted identity (allowId/owner/scope) is carried VERBATIM.
  *   - `failed` — durable but the tmux session is GONE (or the probe was unanswerable):
  *     the registry maps this to the EXISTING `terminal:session_state(state:"lost")` +
  *     a content-free unrecoverable reason and PRESERVES the journal. NOTE the
- *     discriminant keeps 165-01's internal name `failed`, but there is NO `failed`
- *     session_state member — the registry EMITS `lost`; the user-facing `failed`
- *     OUTCOME is layered downstream in Phase 166 NOTIFY-01. This module NEVER touches
+ *     discriminant keeps {@link reattachDecision}'s internal name `failed`, but there
+ *     is NO `failed` session_state member — the registry EMITS `lost`; the user-facing
+ *     `failed` OUTCOME is layered downstream. This module NEVER touches
  *     the journal (the preserve-on-gone contract is the caller's).
  *   - `fallback_nondurable` — a `durable:false` (spawn) session: SKIPPED here (filtered
- *     out of the result) so the registry's existing lost floor stands unchanged (I1).
+ *     out of the result) so the registry's existing lost floor stands unchanged.
  *
- * Architecture invariants (binding — AGENTS.md / 124 house style; mirrors
+ * Architecture invariants (binding — AGENTS.md; mirrors
  * `terminal-reattach-match.ts` / `terminal-drive-journal.ts`):
  *   - PURE via the INJECTED port: free functions, NOT a factory. NO module-global
  *     mutable state, NO clock/timer/env read, NO direct fs. The descriptor STORE
  *     ({@link SessionDescriptorStorePort}) and the `has-session` liveness
  *     (`isTmuxAlive`) are INJECTED — so the scan is provable without a live tmux
  *     server and without any disk. The actual fs write lives in the DAEMON impl of the
- *     port (165-07), NOT here — a testability seam, NOT because skills→observability
+ *     port, NOT here — a testability seam, NOT because skills→observability
  *     is forbidden (it is allowed; this module simply needs no I/O).
- *   - TOTAL / NEVER throws: a corrupt descriptor (165-01's `deserializeDescriptor`
+ *   - TOTAL / NEVER throws: a corrupt descriptor (`deserializeDescriptor`
  *     already returns `undefined`, but the store does the deserialize) or a throwing
  *     probe / throwing `store.recover()` yields the SAFE shape (skip + continue),
  *     never an exception — a recover-on-boot scan must never crash daemon startup.
@@ -54,13 +54,13 @@ import type { SessionOwner } from "./terminal-session-owner.js";
 import type { SessionHandle } from "./terminal-session-types.js";
 /**
  * The durable descriptor store the registry's recover-on-boot consults. DEFINED here
- * (the consumer side); the DAEMON (165-07) IMPLEMENTS it as a sibling of the DUR-02
- * journal store (the fs-safe write + recover-on-boot scan over the confined durable
+ * (the consumer side); the DAEMON IMPLEMENTS it as a sibling of the drive-journal
+ * store (the fs-safe write + recover-on-boot scan over the confined durable
  * dir) and INJECTS it onto the registry deps. Unit tests pass a fake (in-memory) port
  * so the scan + decision are provable without any disk.
  *
- * `persist` is callable at create-time BEFORE the tmux session could exist (Pitfall 6
- * — a SIGKILL mid-create must not orphan tmux without a descriptor); `remove` is
+ * `persist` is callable at create-time BEFORE the tmux session could exist (a SIGKILL
+ * mid-create must not orphan tmux without a descriptor); `remove` is
  * ENOENT-tolerant (a double-remove on a gone session is a no-op, never a throw).
  */
 export interface SessionDescriptorStorePort {
@@ -68,7 +68,7 @@ export interface SessionDescriptorStorePort {
     persist(descriptor: SessionDescriptor): void;
     /**
      * Scan the durable dir and return every well-formed persisted descriptor (a
-     * corrupt-after-crash file is a corrupt-SKIP via 165-01's `deserializeDescriptor`).
+     * corrupt-after-crash file is a corrupt-SKIP via `deserializeDescriptor`).
      * The daemon impl swallows fs faults; this module ALSO defends a throwing impl.
      */
     recover(): SessionDescriptor[];
@@ -79,12 +79,12 @@ export interface SessionDescriptorStorePort {
  * One recovered descriptor's resolved action — the closed union the registry switches
  * on. The `fallback_nondurable` arm of {@link reattachDecision} is NOT surfaced here:
  * a non-durable session is filtered out of the scan result (the registry's existing
- * lost floor handles it, I1), so the registry only ever sees `reattach`/`failed`.
+ * lost floor handles it), so the registry only ever sees `reattach`/`failed`.
  *
- * The `failed` arm carries the `owner` (NOT just the sessionId from 165-01's decision)
+ * The `failed` arm carries the `owner` (NOT just the sessionId from the decision)
  * so the registry can fire its content-free unrecoverable hook with the `agentId`
- * (§2.7 — a failure branch is reconstructable per-agent from the bus alone) WITHOUT a
- * second descriptor lookup. The owner is the persisted I5 identity, never widened.
+ * (a failure branch is reconstructable per-agent from the bus alone) WITHOUT a
+ * second descriptor lookup. The owner is the persisted identity, never widened.
  */
 export type RecoveredAction = {
     action: "reattach";
@@ -97,42 +97,42 @@ export type RecoveredAction = {
 };
 /** Dependencies for {@link recoverSessionDescriptors} — the injected store + liveness probe. */
 export interface RecoverSessionDescriptorsDeps {
-    /** The durable descriptor store (daemon impl in 165-07; a fake in unit tests). */
+    /** The durable descriptor store (daemon impl in production; a fake in unit tests). */
     store: SessionDescriptorStorePort;
-    /** The `has-session` liveness probe (the worker's `has-session`), injected per 165-01. */
+    /** The `has-session` liveness probe (the worker's `has-session`), injected. */
     isTmuxAlive: (name: string, socket?: string) => boolean;
 }
 /**
  * Scan the persisted descriptors and resolve each to a recover-on-boot action via
- * 165-01's pure {@link reattachDecision}. PURE (through the injected port), TOTAL,
- * NEVER throws (RESEARCH Pattern 1).
+ * the pure {@link reattachDecision}. PURE (through the injected port), TOTAL,
+ * NEVER throws.
  *
  * For each descriptor `store.recover()` returns:
  *   - `reattach` (durable + live) → surfaced VERBATIM for the registry to rehydrate.
  *   - `failed` (durable + gone / unanswerable) → surfaced as the genuinely-gone action
  *     (the registry emits `lost` + keeps the journal). The decision's `tmux_session_gone`
- *     reason is carried for the §2.7 content-free hint/errorKind.
+ *     reason is carried for the content-free hint/errorKind.
  *   - `fallback_nondurable` (non-durable) → SKIPPED (filtered out; today's lost floor).
  *
  * A throwing `store.recover()` (a disk read fault on boot) yields an EMPTY list — a
  * recover scan must never crash daemon startup; the worst case is "no session
- * recovered", identical to today's empty-Map-on-boot behavior (I1).
+ * recovered", identical to today's empty-Map-on-boot behavior.
  *
  * @param deps - The injected descriptor store + the `has-session` liveness probe.
  * @returns The reattach/failed actions, in `store.recover()` order; non-durable skipped.
  */
 export declare function recoverSessionDescriptors(deps: RecoverSessionDescriptorsDeps): RecoveredAction[];
 /**
- * Rebuild a `running` {@link SessionHandle} from a recovered descriptor (I5 — WHERE
+ * Rebuild a `running` {@link SessionHandle} from a recovered descriptor (WHERE
  * not WHAT). The bulk lives HERE (not the registry) to protect the 800-line cap: the
  * registry's recover-on-boot just `sessions.set(d.sessionId, rehydrateHandleFromDescriptor(d, nowMs()))`.
  *
  * Identity is carried VERBATIM: `allowId`/`owner`/`cols`/`rows` from the descriptor,
- * plus the two DUR-01 handle fields `durable`/`tmuxName` (the durable marker the
+ * plus the two durability handle fields `durable`/`tmuxName` (the durable marker the
  * durable-aware `markRunningSessionsLost` consults + the re-attach key it probes). The
  * status is `running` (a recovered live session is NOT lost) and NO create frame is
  * issued — the worker's `has-session`-gated backend re-attaches the surviving pane on
- * the next read (I10 — never double-drive).
+ * the next read (never double-drive).
  *
  * `command` is the descriptor's `allowId` (a display/audit label for `list`): the
  * descriptor persists IDENTITY, not the original `bin` argv — and the re-attach reads
@@ -147,29 +147,29 @@ export declare function recoverSessionDescriptors(deps: RecoverSessionDescriptor
  */
 export declare function rehydrateHandleFromDescriptor(d: SessionDescriptor, nowMs: number): SessionHandle;
 /**
- * DUR-01 / Q4 — the durable-aware lost gate (pure). `true` iff `handle` must NOT be
+ * The durable-aware lost gate (pure). `true` iff `handle` must NOT be
  * flipped `lost` on a worker close/crash: a DURABLE drive whose detached tmux server is
- * still alive outlives the worker (the lazy respawn re-attaches the surviving pane, I10).
+ * still alive outlives the worker (the lazy respawn re-attaches the surviving pane).
  * The `isTmuxAlive(name)===true` gate is the SAFE direction — non-durable / no `tmuxName`
- * / falsy probe ⇒ `false`, falling through to today's lost flip (the documented floor,
- * I1). The registry consults it at BOTH lost sites (the worker-close flip + the
+ * / falsy probe ⇒ `false`, falling through to today's lost flip (the documented floor).
+ * The registry consults it at BOTH lost sites (the worker-close flip + the
  * crash-flushed create-reply waiter), so a crash cannot re-flip a live durable session.
  */
 export declare function staysRecoverable(handle: Pick<SessionHandle, "durable" | "tmuxName" | "tmuxSocket">, isTmuxAlive: (name: string, socket?: string) => boolean): boolean;
 /**
  * Flip every still-`running` session in `sessions` to `lost` on a worker close/crash —
- * EXCEPT a durable session whose tmux is still alive ({@link staysRecoverable}, DUR-01 /
- * Q4 — its detached server outlives the worker; the lazy respawn re-attaches the surviving
- * pane on the next read, I10). The registry passes its map + injected probe; the loop body
- * lives here (cap headroom — Pitfall 5). The non-durable / no-probe case keeps today's
- * blanket lost flip (I1).
+ * EXCEPT a durable session whose tmux is still alive ({@link staysRecoverable} — its
+ * detached server outlives the worker; the lazy respawn re-attaches the surviving
+ * pane on the next read). The registry passes its map + injected probe; the loop body
+ * lives here (cap headroom). The non-durable / no-probe case keeps today's
+ * blanket lost flip.
  */
 export declare function markRunningSessionsLost(sessions: Map<string, SessionHandle>, isTmuxAlive: (name: string, socket?: string) => boolean): void;
 /** The inputs the registry's `create` has for a durable session (the descriptor source). */
 export interface DurableCreateInputs {
     sessionId: string;
     tmuxName?: string;
-    /** RECUR-03: the per-boot `-S` socket this durable session's tmux server is bound to (persisted
+    /** The per-boot `-S` socket this durable session's tmux server is bound to (persisted
      *  so a restart re-attaches it from its OWN server while new sessions get a fresh per-boot one). */
     tmuxSocket?: string;
     allowId: string;
@@ -181,22 +181,22 @@ export interface DurableCreateInputs {
 }
 /**
  * Build the durable {@link SessionDescriptor} the registry persists at create-time
- * (Pitfall 6 — persist BEFORE the create frame so a SIGKILL mid-create cannot orphan
+ * (persist BEFORE the create frame so a SIGKILL mid-create cannot orphan
  * tmux without a record). The tmux name defaults to the deterministic `comis-<id>` the
  * worker derives. Pure; the registry calls `store.persist(buildSessionDescriptor(...))`.
  */
 export declare function buildSessionDescriptor(i: DurableCreateInputs): SessionDescriptor;
 /**
- * The DUR-01 durability seams the registry bundles as one nested `durability?` dep (so the
+ * The durability seams the registry bundles as one nested `durability?` dep (so the
  * registry stays under the optional-field-bloat cap) + hands to {@link applyRecoveredSessions}
  * (so its recover-on-boot is a single delegated call). All optional: ABSENT `descriptorStore`
- * ⇒ a no-op (today's empty-Map-on-boot, I1). The hooks are injected (NOT a value-imported bus)
+ * ⇒ a no-op (today's empty-Map-on-boot). The hooks are injected (NOT a value-imported bus)
  * so the registry stays infra-decoupled; the fs-safe descriptor write lives in the daemon impl.
- *   - `descriptorStore` — persist-at-create + recover-on-boot (165-07's fs impl).
+ *   - `descriptorStore` — persist-at-create + recover-on-boot (the daemon's fs impl).
  *   - `isTmuxAlive` — the `has-session` probe the recover decision + the durable-aware lost gate use.
  *   - `onReattached` — fired ONCE per re-attach → the daemon's content-free `terminal:drive_reattached`.
  *   - `onUnrecoverable` — fired per genuinely-gone session → the daemon's EXISTING
- *     `terminal:session_state(state:"lost")` + a content-free reason (NO `failed` member, Phase-166).
+ *     `terminal:session_state(state:"lost")` + a content-free reason (NO `failed` member).
  */
 export interface TerminalDurabilityDeps {
     descriptorStore?: SessionDescriptorStorePort;
@@ -206,7 +206,7 @@ export interface TerminalDurabilityDeps {
      * kill-session -t <name>`), the sibling of {@link isTmuxAlive}. The registry calls it on evict
      * of a durable session because the worker-IPC "kill" does NOT reliably terminate a durable
      * (detached, per-boot-socket) tmux — a never-tasked webhook drive lingered as an idle `claude`
-     * after `kill` fired, while a manual kill-session by name reaped it (webhook-claude-cli-tdd-20260701).
+     * after `kill` fired, while a manual kill-session by name reaped it.
      * Absent ⇒ no-op (the worker-IPC kill is the only teardown, today's behavior).
      */
     killTmuxSession?: (name: string, socket?: string) => void;
@@ -222,7 +222,7 @@ export interface TerminalDurabilityDeps {
     }) => void;
 }
 /**
- * The minimal worker round-trip the recover-on-boot re-attach drives (BL-01, 165-REVIEW):
+ * The minimal worker round-trip the recover-on-boot re-attach drives:
  * send a `reattach` frame to the worker and resolve whether it re-attached (`ok:true`).
  * The registry binds it to its `request(...)` closure (typed down to `{ ok }`); a fake in
  * unit tests resolves `true`/`false`. ABSENT ⇒ the legacy synchronous behavior (fire
@@ -232,21 +232,21 @@ export type ReattachWorkerFn = (sessionId: string, cols: number, rows: number, a
     ok: boolean;
 }>;
 /**
- * The DUR-01 recover-on-boot APPLICATION: scan the persisted descriptors and, for each,
+ * The recover-on-boot APPLICATION: scan the persisted descriptors and, for each,
  * either rehydrate a `running` handle into the registry's `sessions` map (a live tmux,
- * NO create frame — I10) and DRIVE the worker re-attach (gating the obs hooks on the
- * worker's confirmation, BL-01), or — for a session gone at the boot probe — fire the
- * content-free unrecoverable hook + remove the dead DESCRIPTOR (BL-03; the daemon maps the
+ * NO create frame) and DRIVE the worker re-attach (gating the obs hooks on the
+ * worker's confirmation), or — for a session gone at the boot probe — fire the
+ * content-free unrecoverable hook + remove the dead DESCRIPTOR (the daemon maps the
  * hook to the EXISTING `terminal:session_state(state:"lost")` + the reason; the JOURNAL is
  * PRESERVED by the daemon holder, only the dead descriptor is dropped). A non-durable
- * descriptor is skipped (today's lost floor, I1). The `descriptorStore`-absent case is a
- * no-op (I1). The BULK lives here (not the registry) to protect the 800-line cap (Pitfall
- * 5); the registry's recover-on-boot is ONE call.
+ * descriptor is skipped (today's lost floor). The `descriptorStore`-absent case is a
+ * no-op. The BULK lives here (not the registry) to protect the 800-line cap;
+ * the registry's recover-on-boot is ONE call.
  *
  * @param deps - The durability seams (descriptorStore + isTmuxAlive + the two hooks).
  * @param sessions - The registry's live session map (a recovered live session is set here).
  * @param nowMs - The registry's injected clock (stamps the rehydrated handle's lastActivity).
- * @param reattachWorker - BL-01 (165-REVIEW): the registry's `reattach` worker round-trip.
+ * @param reattachWorker - The registry's `reattach` worker round-trip.
  *   When provided, a recovered live session is re-attached in the worker + the obs hooks are
  *   gated on the worker's `ok` (fire-and-forget; recover-on-boot does not block). ABSENT ⇒
  *   the legacy synchronous fire (no worker confirmation) — kept for unit-test ergonomics.

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

@@ -1,47 +1,47 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The DUR-01 recover-on-boot SCAN orchestrator + the injected descriptor-store port
- * (Phase 165, plan 06; RESEARCH Pattern 1, Pitfall 5). This is the SIBLING that keeps
- * the 772-line registry under the 800-line cap: the registry's recover-on-boot is a
- * thin call into {@link recoverSessionDescriptors}, never an inlined scan loop.
+ * The recover-on-boot SCAN orchestrator + the injected descriptor-store port. This is
+ * the SIBLING that keeps the registry under the 800-line cap: the registry's
+ * recover-on-boot is a thin call into {@link recoverSessionDescriptors}, never an
+ * inlined scan loop.
  *
- * WHY THIS EXISTS (the load-bearing DUR-01 gap, framed in terminal-reattach-match.ts).
+ * WHY THIS EXISTS (the load-bearing gap, framed in terminal-reattach-match.ts).
  * The tmux re-attach MECHANISM already ships (deterministic `comis-<id>` name +
  * `has-session`-gated create-vs-reattach + a linux survival test). The genuine gap is
  * one layer UP: the registry's `sessionId` is an ephemeral `randomUUID()` it never
  * persists, and there is NO recover-on-boot — so on a daemon restart its `sessions`
  * Map starts EMPTY and a healthy 40h drive whose `comis-<old-id>` is STILL alive under
  * tmux is wrongly flipped `lost`. This module is the missing RECONCILIATION: scan the
- * persisted {@link SessionDescriptor}s, run each through 165-01's pure
+ * persisted {@link SessionDescriptor}s, run each through the pure
  * {@link reattachDecision}, and yield a typed list the registry switches on.
  *
- * THE DECISION VOCABULARY (mirrors 165-01, NOT a second copy). Each recovered
- * descriptor maps to exactly one {@link RecoveredAction}:
+ * THE DECISION VOCABULARY (mirrors {@link reattachDecision}, NOT a second copy). Each
+ * recovered descriptor maps to exactly one {@link RecoveredAction}:
  *   - `reattach` — durable + the tmux session is LIVE: the registry rehydrates a
  *     `running` handle ({@link rehydrateHandleFromDescriptor}) and issues NO create
- *     frame (I10 — the worker's `has-session`-gated backend re-attaches the surviving
- *     pane on the NEXT read; a fresh create would double-drive). The descriptor's I5
- *     identity (allowId/owner/scope) is carried VERBATIM.
+ *     frame (the worker's `has-session`-gated backend re-attaches the surviving
+ *     pane on the NEXT read; a fresh create would double-drive). The descriptor's
+ *     persisted identity (allowId/owner/scope) is carried VERBATIM.
  *   - `failed` — durable but the tmux session is GONE (or the probe was unanswerable):
  *     the registry maps this to the EXISTING `terminal:session_state(state:"lost")` +
  *     a content-free unrecoverable reason and PRESERVES the journal. NOTE the
- *     discriminant keeps 165-01's internal name `failed`, but there is NO `failed`
- *     session_state member — the registry EMITS `lost`; the user-facing `failed`
- *     OUTCOME is layered downstream in Phase 166 NOTIFY-01. This module NEVER touches
+ *     discriminant keeps {@link reattachDecision}'s internal name `failed`, but there
+ *     is NO `failed` session_state member — the registry EMITS `lost`; the user-facing
+ *     `failed` OUTCOME is layered downstream. This module NEVER touches
  *     the journal (the preserve-on-gone contract is the caller's).
  *   - `fallback_nondurable` — a `durable:false` (spawn) session: SKIPPED here (filtered
- *     out of the result) so the registry's existing lost floor stands unchanged (I1).
+ *     out of the result) so the registry's existing lost floor stands unchanged.
  *
- * Architecture invariants (binding — AGENTS.md / 124 house style; mirrors
+ * Architecture invariants (binding — AGENTS.md; mirrors
  * `terminal-reattach-match.ts` / `terminal-drive-journal.ts`):
  *   - PURE via the INJECTED port: free functions, NOT a factory. NO module-global
  *     mutable state, NO clock/timer/env read, NO direct fs. The descriptor STORE
  *     ({@link SessionDescriptorStorePort}) and the `has-session` liveness
  *     (`isTmuxAlive`) are INJECTED — so the scan is provable without a live tmux
  *     server and without any disk. The actual fs write lives in the DAEMON impl of the
- *     port (165-07), NOT here — a testability seam, NOT because skills→observability
+ *     port, NOT here — a testability seam, NOT because skills→observability
  *     is forbidden (it is allowed; this module simply needs no I/O).
- *   - TOTAL / NEVER throws: a corrupt descriptor (165-01's `deserializeDescriptor`
+ *   - TOTAL / NEVER throws: a corrupt descriptor (`deserializeDescriptor`
  *     already returns `undefined`, but the store does the deserialize) or a throwing
  *     probe / throwing `store.recover()` yields the SAFE shape (skip + continue),
  *     never an exception — a recover-on-boot scan must never crash daemon startup.
@@ -53,19 +53,19 @@
 import { reattachDecision } from "./terminal-reattach-match.js";
 /**
  * Scan the persisted descriptors and resolve each to a recover-on-boot action via
- * 165-01's pure {@link reattachDecision}. PURE (through the injected port), TOTAL,
- * NEVER throws (RESEARCH Pattern 1).
+ * the pure {@link reattachDecision}. PURE (through the injected port), TOTAL,
+ * NEVER throws.
  *
  * For each descriptor `store.recover()` returns:
  *   - `reattach` (durable + live) → surfaced VERBATIM for the registry to rehydrate.
  *   - `failed` (durable + gone / unanswerable) → surfaced as the genuinely-gone action
  *     (the registry emits `lost` + keeps the journal). The decision's `tmux_session_gone`
- *     reason is carried for the §2.7 content-free hint/errorKind.
+ *     reason is carried for the content-free hint/errorKind.
  *   - `fallback_nondurable` (non-durable) → SKIPPED (filtered out; today's lost floor).
  *
  * A throwing `store.recover()` (a disk read fault on boot) yields an EMPTY list — a
  * recover scan must never crash daemon startup; the worst case is "no session
- * recovered", identical to today's empty-Map-on-boot behavior (I1).
+ * recovered", identical to today's empty-Map-on-boot behavior.
  *
  * @param deps - The injected descriptor store + the `has-session` liveness probe.
  * @returns The reattach/failed actions, in `store.recover()` order; non-durable skipped.
@@ -78,7 +78,7 @@ export function recoverSessionDescriptors(deps) {
     catch {
         // A throwing store on boot → recover NOTHING (never crash startup). Same end-state
         // as today's empty `sessions` Map; the genuinely-alive tmux servers become orphans
-        // the reaper/operator reaps by name (Pitfall 6), never a daemon-boot crash.
+        // the reaper/operator reaps by name, never a daemon-boot crash.
         return [];
     }
     if (!Array.isArray(descriptors))
@@ -92,25 +92,25 @@ export function recoverSessionDescriptors(deps) {
             out.push({ action: "reattach", descriptor: decision.descriptor });
         }
         else if (decision.action === "failed") {
-            // Carry the descriptor's owner (the persisted I5 identity) so the registry's
+            // Carry the descriptor's owner (the persisted identity) so the registry's
             // content-free unrecoverable hook gets the agentId without a second lookup.
             out.push({ action: "failed", sessionId: decision.sessionId, owner: descriptor.owner, reason: decision.reason });
         }
-        // fallback_nondurable → skip (the registry's existing lost floor handles it, I1).
+        // fallback_nondurable → skip (the registry's existing lost floor handles it).
     }
     return out;
 }
 /**
- * Rebuild a `running` {@link SessionHandle} from a recovered descriptor (I5 — WHERE
+ * Rebuild a `running` {@link SessionHandle} from a recovered descriptor (WHERE
  * not WHAT). The bulk lives HERE (not the registry) to protect the 800-line cap: the
  * registry's recover-on-boot just `sessions.set(d.sessionId, rehydrateHandleFromDescriptor(d, nowMs()))`.
  *
  * Identity is carried VERBATIM: `allowId`/`owner`/`cols`/`rows` from the descriptor,
- * plus the two DUR-01 handle fields `durable`/`tmuxName` (the durable marker the
+ * plus the two durability handle fields `durable`/`tmuxName` (the durable marker the
  * durable-aware `markRunningSessionsLost` consults + the re-attach key it probes). The
  * status is `running` (a recovered live session is NOT lost) and NO create frame is
  * issued — the worker's `has-session`-gated backend re-attaches the surviving pane on
- * the next read (I10 — never double-drive).
+ * the next read (never double-drive).
  *
  * `command` is the descriptor's `allowId` (a display/audit label for `list`): the
  * descriptor persists IDENTITY, not the original `bin` argv — and the re-attach reads
@@ -135,23 +135,23 @@ export function rehydrateHandleFromDescriptor(d, nowMs) {
         lastActivity: nowMs,
         startedAt: d.createdAt,
         owner: d.owner,
-        // The two DUR-01 handle fields: the durable marker + the re-attach key the
+        // The two durability handle fields: the durable marker + the re-attach key the
         // durable-aware markRunningSessionsLost consults (a durable + tmux-alive session
-        // is NOT flipped lost on a worker close, Q4).
+        // is NOT flipped lost on a worker close).
         durable: true,
         tmuxName: d.tmuxName,
-        // RECUR-03: rehydrate the per-boot socket so the daemon probe / reaper target the session's
+        // Rehydrate the per-boot socket so the daemon probe / reaper target the session's
         // OWN (prior-boot) server, and the worker re-attaches there (not this boot's fresh server).
         tmuxSocket: d.tmuxSocket,
     };
 }
 /**
- * DUR-01 / Q4 — the durable-aware lost gate (pure). `true` iff `handle` must NOT be
+ * The durable-aware lost gate (pure). `true` iff `handle` must NOT be
  * flipped `lost` on a worker close/crash: a DURABLE drive whose detached tmux server is
- * still alive outlives the worker (the lazy respawn re-attaches the surviving pane, I10).
+ * still alive outlives the worker (the lazy respawn re-attaches the surviving pane).
  * The `isTmuxAlive(name)===true` gate is the SAFE direction — non-durable / no `tmuxName`
- * / falsy probe ⇒ `false`, falling through to today's lost flip (the documented floor,
- * I1). The registry consults it at BOTH lost sites (the worker-close flip + the
+ * / falsy probe ⇒ `false`, falling through to today's lost flip (the documented floor).
+ * The registry consults it at BOTH lost sites (the worker-close flip + the
  * crash-flushed create-reply waiter), so a crash cannot re-flip a live durable session.
  */
 export function staysRecoverable(handle, isTmuxAlive) {
@@ -159,11 +159,11 @@ export function staysRecoverable(handle, isTmuxAlive) {
 }
 /**
  * Flip every still-`running` session in `sessions` to `lost` on a worker close/crash —
- * EXCEPT a durable session whose tmux is still alive ({@link staysRecoverable}, DUR-01 /
- * Q4 — its detached server outlives the worker; the lazy respawn re-attaches the surviving
- * pane on the next read, I10). The registry passes its map + injected probe; the loop body
- * lives here (cap headroom — Pitfall 5). The non-durable / no-probe case keeps today's
- * blanket lost flip (I1).
+ * EXCEPT a durable session whose tmux is still alive ({@link staysRecoverable} — its
+ * detached server outlives the worker; the lazy respawn re-attaches the surviving
+ * pane on the next read). The registry passes its map + injected probe; the loop body
+ * lives here (cap headroom). The non-durable / no-probe case keeps today's
+ * blanket lost flip.
  */
 export function markRunningSessionsLost(sessions, isTmuxAlive) {
     for (const handle of sessions.values()) {
@@ -173,7 +173,7 @@ export function markRunningSessionsLost(sessions, isTmuxAlive) {
 }
 /**
  * Build the durable {@link SessionDescriptor} the registry persists at create-time
- * (Pitfall 6 — persist BEFORE the create frame so a SIGKILL mid-create cannot orphan
+ * (persist BEFORE the create frame so a SIGKILL mid-create cannot orphan
  * tmux without a record). The tmux name defaults to the deterministic `comis-<id>` the
  * worker derives. Pure; the registry calls `store.persist(buildSessionDescriptor(...))`.
  */
@@ -195,14 +195,14 @@ export function buildSessionDescriptor(i) {
     return descriptor;
 }
 /**
- * BL-01 (165-REVIEW): drive ONE recovered session's worker re-attach + gate the obs hooks
+ * Drive ONE recovered session's worker re-attach + gate the obs hooks
  * on the WORKER's confirmation (not the boot has-session probe alone). The registry already
  * rehydrated the handle `running`; here we ask the freshly-spawned worker to re-attach the
- * surviving tmux pane (the worker's `reattach` is `has-session`-gated, NEVER a new-session —
- * I10). On `ok:true` → fire `onReattached` (the confirmed re-attach is the obs record). On
+ * surviving tmux pane (the worker's `reattach` is `has-session`-gated, NEVER a new-session).
+ * On `ok:true` → fire `onReattached` (the confirmed re-attach is the obs record). On
  * `ok:false` (the tmux died between the boot probe and the worker spawn, or no tmux backend)
  * → flip the handle `lost` + fire `onUnrecoverable` (honest death; the JOURNAL is preserved
- * by the daemon holder, I10). Best-effort/never-throws (a faulting round-trip resolves the
+ * by the daemon holder). Best-effort/never-throws (a faulting round-trip resolves the
  * safe `lost` direction).
  */
 async function driveWorkerReattach(deps, sessions, descriptor, reattachWorker) {
@@ -214,8 +214,8 @@ async function driveWorkerReattach(deps, sessions, descriptor, reattachWorker) {
         deps.onReattached?.({ sessionId: descriptor.sessionId, agentId: descriptor.owner.agentId });
         return;
     }
-    // The worker could not re-attach — honest death (I10). Flip lost + fire the unrecoverable
-    // hook + drop the now-dead DESCRIPTOR (BL-03 — its tmuxName no longer resolves, so keeping
+    // The worker could not re-attach — honest death. Flip lost + fire the unrecoverable
+    // hook + drop the now-dead DESCRIPTOR (its tmuxName no longer resolves, so keeping
     // it re-scans/re-probes/re-emits lost every boot). The JOURNAL is preserved by the daemon
     // holder (the descriptor store is distinct from the journal store).
     const handle = sessions.get(descriptor.sessionId);
@@ -225,34 +225,34 @@ async function driveWorkerReattach(deps, sessions, descriptor, reattachWorker) {
     deps.descriptorStore?.remove(descriptor.sessionId);
 }
 /**
- * The DUR-01 recover-on-boot APPLICATION: scan the persisted descriptors and, for each,
+ * The recover-on-boot APPLICATION: scan the persisted descriptors and, for each,
  * either rehydrate a `running` handle into the registry's `sessions` map (a live tmux,
- * NO create frame — I10) and DRIVE the worker re-attach (gating the obs hooks on the
- * worker's confirmation, BL-01), or — for a session gone at the boot probe — fire the
- * content-free unrecoverable hook + remove the dead DESCRIPTOR (BL-03; the daemon maps the
+ * NO create frame) and DRIVE the worker re-attach (gating the obs hooks on the
+ * worker's confirmation), or — for a session gone at the boot probe — fire the
+ * content-free unrecoverable hook + remove the dead DESCRIPTOR (the daemon maps the
  * hook to the EXISTING `terminal:session_state(state:"lost")` + the reason; the JOURNAL is
  * PRESERVED by the daemon holder, only the dead descriptor is dropped). A non-durable
- * descriptor is skipped (today's lost floor, I1). The `descriptorStore`-absent case is a
- * no-op (I1). The BULK lives here (not the registry) to protect the 800-line cap (Pitfall
- * 5); the registry's recover-on-boot is ONE call.
+ * descriptor is skipped (today's lost floor). The `descriptorStore`-absent case is a
+ * no-op. The BULK lives here (not the registry) to protect the 800-line cap;
+ * the registry's recover-on-boot is ONE call.
  *
  * @param deps - The durability seams (descriptorStore + isTmuxAlive + the two hooks).
  * @param sessions - The registry's live session map (a recovered live session is set here).
  * @param nowMs - The registry's injected clock (stamps the rehydrated handle's lastActivity).
- * @param reattachWorker - BL-01 (165-REVIEW): the registry's `reattach` worker round-trip.
+ * @param reattachWorker - The registry's `reattach` worker round-trip.
  *   When provided, a recovered live session is re-attached in the worker + the obs hooks are
  *   gated on the worker's `ok` (fire-and-forget; recover-on-boot does not block). ABSENT ⇒
  *   the legacy synchronous fire (no worker confirmation) — kept for unit-test ergonomics.
  */
 export function applyRecoveredSessions(deps, sessions, nowMs, reattachWorker) {
     if (deps.descriptorStore === undefined)
-        return; // today's wiring — no recover (I1).
+        return; // today's wiring — no recover.
     const isTmuxAlive = deps.isTmuxAlive ?? (() => false);
     for (const r of recoverSessionDescriptors({ store: deps.descriptorStore, isTmuxAlive })) {
         if (r.action === "reattach") {
             sessions.set(r.descriptor.sessionId, rehydrateHandleFromDescriptor(r.descriptor, nowMs()));
             if (reattachWorker !== undefined) {
-                // BL-01: ask the worker to re-attach the surviving pane; gate the obs hooks on its
+                // Ask the worker to re-attach the surviving pane; gate the obs hooks on its
                 // confirmation. Fire-and-forget — recover-on-boot must not block daemon startup.
                 void driveWorkerReattach(deps, sessions, r.descriptor, reattachWorker);
             }
@@ -263,9 +263,9 @@ export function applyRecoveredSessions(deps, sessions, nowMs, reattachWorker) {
         }
         else {
             // Genuinely gone at the boot probe: fire the unrecoverable hook + drop the dead
-            // DESCRIPTOR (BL-03 — a stale descriptor with a dead tmuxName re-scans/re-probes/
-            // re-emits lost every boot). The JOURNAL is preserved by the daemon holder (I10 —
-            // the descriptor store is distinct from the journal store).
+            // DESCRIPTOR (a stale descriptor with a dead tmuxName re-scans/re-probes/
+            // re-emits lost every boot). The JOURNAL is preserved by the daemon holder
+            // (the descriptor store is distinct from the journal store).
             deps.onUnrecoverable?.({ sessionId: r.sessionId, agentId: r.owner.agentId, reason: r.reason, errorKind: "dependency" });
             deps.descriptorStore.remove(r.sessionId);
         }