comisai 1.0.44 → 1.0.46

package/node_modules/@comis/daemon/dist/wiring/terminal-wake-dispatch.d.ts

@@ -4,9 +4,9 @@ import { type PersistedWakeOwner } from "./terminal-wake-persistence.js";
 export type WakeEscalationReason = "hop_limit";
 /**
  * The escalation callback (NotifyFn-shaped, the completion-dispatcher
- * `fireFallback` precedent). 124-09 binds this to emit `terminal:escalated`
- * + drive the subagent→parent→human chain (spec §4.7). Returns a promise so
- * the FSM can await it inside its in-flight tracking.
+ * `fireFallback` precedent). The daemon setup layer binds this to emit
+ * `terminal:escalated` + drive the subagent→parent→human chain. Returns a
+ * promise so the FSM can await it inside its in-flight tracking.
  */
 export type WakeEscalateFn = (opts: {
     sessionId: string;
@@ -15,11 +15,11 @@ export type WakeEscalateFn = (opts: {
 }) => Promise<unknown>;
 /**
  * The narrow structural event the FSM consumes. It carries `requestId` (the
- * `(sessionId, requestId)` dedupe correlation, reusing the P0 framer key
- * shape) — the daemon hook in 124-09 maps the fd3 frame's requestId in. The
- * core `terminal:input_needed` bus payload omits requestId (it is a
- * redaction-safe summary); the FSM's correlation needs it, so the daemon
- * threads it from the frame.
+ * `(sessionId, requestId)` dedupe correlation, reusing the framer key shape) —
+ * the daemon hook maps the fd3 frame's requestId in. The core
+ * `terminal:input_needed` bus payload omits requestId (it is a redaction-safe
+ * summary); the FSM's correlation needs it, so the daemon threads it from the
+ * frame.
  */
 export interface TerminalInputNeededWake {
     sessionId: string;
@@ -40,8 +40,8 @@ export interface WakeDispatcherBus {
 /** Public-facing handle on the wake dispatcher. */
 export interface TerminalWakeDispatcher {
     /**
-     * Drop the in-memory FSM state for a session that has ended (killed/evicted/exited)
-     * — IN-03/WR-02. The `states` map is otherwise only pruned when a NEW wake arrives
+     * Drop the in-memory FSM state for a session that has ended (killed/evicted/exited).
+     * The `states` map is otherwise only pruned when a NEW wake arrives
      * for an already-dead session (the active-check), so a session that goes quiet then
      * dies would leak its `WakeState` for the daemon's lifetime. The end-of-life hook in
      * `setupTerminalWake` calls this (alongside the loop-guard + wake-file cleanup). Total
@@ -55,12 +55,12 @@ export interface TerminalWakeDispatcher {
 export interface TerminalWakeDispatcherDeps {
     /** The typed bus (structurally a `WakeDispatcherBus`). */
     eventBus: WakeDispatcherBus;
-    /** Active-session check — owner-scoped (the P4 registry). A wake for a session
+    /** Active-session check — owner-scoped (the registry). A wake for a session
      *  this reports false (killed/evicted/cross-owner) is dropped + audited. */
     isSessionActive: (sessionId: string, owner: PersistedWakeOwner) => boolean;
-    /** The woken-turn driver (124-09 wires it to the agent turn). */
+    /** The woken-turn driver (the daemon setup layer wires it to the agent turn). */
     wakeOneTurn: (sessionId: string, owner: PersistedWakeOwner) => Promise<void>;
-    /** Hop-limit / drop escalation (124-09 binds it to terminal:escalated). */
+    /** Hop-limit / drop escalation (bound to terminal:escalated at daemon setup). */
     escalate: WakeEscalateFn;
     /** Data dir for the durable wake-state. */
     dataDir: string;
@@ -76,7 +76,7 @@ export interface TerminalWakeDispatcherDeps {
  * Wire the recurring wake-dispatch FSM against an event bus. Subscriptions are
  * installed synchronously; call `shutdown()` to remove them + drain.
  *
- * Recovers persisted dispatch state on construction (OPS-09) so a session
- * mid-wake before a daemon restart is not re-woken spuriously.
+ * Recovers persisted dispatch state on construction so a session mid-wake
+ * before a daemon restart is not re-woken spuriously.
  */
 export declare function createTerminalWakeDispatcher(deps: TerminalWakeDispatcherDeps): TerminalWakeDispatcher;

package/node_modules/@comis/daemon/dist/wiring/terminal-wake-dispatch.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Recurring wake-dispatch FSM (OPS-08/OPS-09) — the daemon-side module that
- * turns a `terminal:input_needed` event into AT MOST ONE woken agent turn.
+ * Recurring wake-dispatch FSM — the daemon-side module that turns a
+ * `terminal:input_needed` event into AT MOST ONE woken agent turn.
  *
  * Modeled on `packages/agent/src/background/completion-dispatcher.ts`, but
  * RECURRING/mid-session: the completion-dispatcher fires once per task
@@ -20,18 +20,17 @@
  *   | suppressError failure isolation      | suppressError on the woken turn           |
  *   | shutdown() = off + await inflight    | shutdown() = off + await inflight (drain) |
  *
- * **Daemon-side placement (binding — RESEARCH Open Q1 + Pitfall 3):** the FSM
- * persists via `@comis/observability` (terminal-wake-persistence.ts), which
- * `@comis/skills` must NOT value-import — so the recurring FSM + its
- * persistence live in the daemon layer (spec §4.4 "@comis/core/daemon"), not
- * in the skills worker.
+ * **Daemon-side placement (binding constraint):** the FSM persists via
+ * `@comis/observability` (terminal-wake-persistence.ts), which `@comis/skills`
+ * must NOT value-import — so the recurring FSM + its persistence live in the
+ * daemon layer, not in the skills worker.
  *
- * **Separability (124-09 is the keystone):** this module is the FSM UNIT. The
- * daemon SUBSCRIBE wiring — binding the fd3 hook → this FSM → a woken turn
- * that runs the auto-answer / loop-guard, and binding `escalate` to emit the
- * `terminal:escalated` event + the subagent→parent→human chain — lands in
- * 124-09. Here, `escalate` is an injected NotifyFn-shaped callback and
- * `wakeOneTurn` is the injected woken-turn driver.
+ * **Separability:** this module is the FSM UNIT. The daemon SUBSCRIBE wiring —
+ * binding the fd3 hook → this FSM → a woken turn that runs the auto-answer /
+ * loop-guard, and binding `escalate` to emit the `terminal:escalated` event +
+ * the subagent→parent→human chain — lives in the daemon setup layer. Here,
+ * `escalate` is an injected NotifyFn-shaped callback and `wakeOneTurn` is the
+ * injected woken-turn driver.
  *
  * Injected clock (`nowMs`), closure-local state ONLY (no module-global),
  * never-throw isolation (a wake handler error must not crash the dispatcher).
@@ -47,8 +46,8 @@ import { persistWakeStateSync, recoverWakeStates, } from "./terminal-wake-persis
  * Wire the recurring wake-dispatch FSM against an event bus. Subscriptions are
  * installed synchronously; call `shutdown()` to remove them + drain.
  *
- * Recovers persisted dispatch state on construction (OPS-09) so a session
- * mid-wake before a daemon restart is not re-woken spuriously.
+ * Recovers persisted dispatch state on construction so a session mid-wake
+ * before a daemon restart is not re-woken spuriously.
  */
 export function createTerminalWakeDispatcher(deps) {
     const log = deps.logger.child({ submodule: "terminal-wake-dispatch" });
@@ -58,7 +57,7 @@ export function createTerminalWakeDispatcher(deps) {
     let inFlightWokenTurns = 0;
     let stopped = false;
     let inflight = Promise.resolve();
-    // Recover persisted dispatch state on boot (OPS-09).
+    // Recover persisted dispatch state on boot.
     for (const persisted of recoverWakeStates(deps.dataDir)) {
         states.set(persisted.sessionId, {
             owner: persisted.owner,
@@ -106,9 +105,9 @@ export function createTerminalWakeDispatcher(deps) {
             log.debug({ sessionId: ev.sessionId, requestId: ev.requestId, step: "wake_dedupe" }, "Wake dispatch: duplicate input_needed coalesced");
             return;
         }
-        // (2) ACTIVE-CHECK — drop wakes for genuinely-gone sessions. ISSUE-3: isSessionActive now
-        // recovers the STAMPED owner (registry.getOwner), so a LIVE channel/API session is NOT dropped
-        // cross-owner; a drop here means the session is truly absent (killed/evicted/never-registered).
+        // (2) ACTIVE-CHECK — drop wakes for genuinely-gone sessions. isSessionActive recovers the
+        // STAMPED owner (registry.getOwner), so a LIVE channel/API session is NOT dropped cross-owner;
+        // a drop here means the session is truly absent (killed/evicted/never-registered).
         if (!deps.isSessionActive(ev.sessionId, ev.owner)) {
             log.warn({
                 sessionId: ev.sessionId,
@@ -178,10 +177,10 @@ export function createTerminalWakeDispatcher(deps) {
             // Clear the pending flag so a FRESH frame can wake again; back to idle.
             st.pendingFrame = undefined;
             st.dispatchState = "idle";
-            // WR-01: a turn that settled SUCCESSFULLY ends the consecutive wake run, so
-            // reset hopCount. `maxHops` is the CONSECUTIVE-wakes-without-progress cap (the
+            // A turn that settled SUCCESSFULLY ends the consecutive wake run, so reset
+            // hopCount. `maxHops` is the CONSECUTIVE-wakes-without-progress cap (the
             // loop/recursion guard the "consecutive" docstrings promise) — NOT a lifetime
-            // budget (that is the P4 maxInteractions cap). A long-lived session driven
+            // budget (that is the maxInteractions cap). A long-lived session driven
             // through many safe answered prompts must never permanently over-escalate;
             // only an unbroken run of un-settled wakes climbs to the cap. A REJECTED turn
             // (err !== undefined) is NOT progress — leave hopCount climbing so a wedged
@@ -241,7 +240,7 @@ export function createTerminalWakeDispatcher(deps) {
     }
     return {
         forgetSession(sessionId) {
-            // IN-03/WR-02: reclaim the in-memory FSM state for an ended session. Total +
+            // Reclaim the in-memory FSM state for an ended session. Total +
             // never-throws (Map.delete is a no-op for an unknown id). The durable wake-file
             // + loop-guard ring are reclaimed by the setupTerminalWake end-of-life hook.
             states.delete(sessionId);

package/node_modules/@comis/daemon/dist/wiring/terminal-wake-notify.d.ts

@@ -1,10 +1,10 @@
 /**
- * The NOTIFY-01 / NOTIFY-02 user-facing outcome+heartbeat EMIT helpers (166-03) — the thin
- * side-effecting glue between the wake holder's content-free signals and the user's channel.
+ * The user-facing outcome+heartbeat EMIT helpers — the thin side-effecting glue between the
+ * wake holder's content-free signals and the user's channel.
  *
  * Extracted from `setup-terminal-wake.ts` so that file stays well under the 800-line
  * architecture cap (it is at the TIGHT end of the band; `terminal-tools.ts` /
- * `terminal-session-registry.ts` are AT the cap). The PURE decisions live in 166-01's skills
+ * `terminal-session-registry.ts` are AT the cap). The PURE decisions live in the skills
  * siblings (`mapTerminalOutcome` / `shouldNotifyOutcome` / `heartbeatLine`); this module
  * performs the already-decided emit through INJECTED seams — mirroring the
  * `terminal-drive-promote.ts` `emitDrivePromoted` precedent (a STRUCTURAL deps interface, not
@@ -13,21 +13,21 @@
  * Two helpers:
  *   - {@link emitTerminalOutcome} — derive (via `mapTerminalOutcome`) and emit ONE user-facing
  *     terminal outcome (`done` / `failed`; `needs-you` is emitted by the existing escalate()
- *     path, NEVER routed here — I4), gated by `shouldNotifyOutcome(outcome, policy)`, with the
+ *     path, NEVER routed here), gated by `shouldNotifyOutcome(outcome, policy)`, with the
  *     §2.7 record (INFO for `done`, WARN + hint + errorKind for `failed`). The message is
  *     STRUCTURAL only (sessionId + outcome enum + durationMs + interactions + capName) —
- *     NEVER the screen (I3).
- *   - {@link runHeartbeatTick} — the NOTIFY-02 per-tick heartbeat loop body the holder's coarse
- *     timer calls: for each PROMOTED session due at the cadence, emit the content-free
+ *     NEVER the screen.
+ *   - {@link runHeartbeatTick} — the per-tick heartbeat loop body the holder's coarse timer
+ *     calls: for each PROMOTED session due at the cadence, emit the content-free
  *     `heartbeatLine` digest + an INFO record, stamping `lastHeartbeatSentMs`. Kept here (not
- *     inlined in the holder) per the extraction directive.
+ *     inlined in the holder) to keep that holder under the line cap.
  *
- * Architecture invariants (binding — AGENTS.md / 124 house style, mirrors `emitDrivePromoted`):
+ * Architecture invariants (binding — AGENTS.md house style, mirrors `emitDrivePromoted`):
  *   - The I/O rides EXCLUSIVELY through the injected `notify` / `info` / `warn` / `nowMs` seams
  *     — no value-imported bus/logger, no raw clock (the globals + infra-runtime-scope gates).
  *   - TOTAL / fire-and-forget: a `notify` rejection is swallowed to a WARN (a notify fault on a
  *     synchronous bus listener must never become an uncaughtException that crashes the daemon).
- *   - CONTENT-FREE (I3): every message is structural counts/durations + the already-redacted
+ *   - CONTENT-FREE: every message is structural counts/durations + the already-redacted
  *     `lastScreenDigest` (formatted by `heartbeatLine`, never re-expanded) — never raw TUI bytes.
  *
  * @module
@@ -40,10 +40,10 @@ import type { LivenessSignal } from "./terminal-wake-types.js";
  * their I/O to (a `Pick`-style contract, not the full `SetupTerminalWakeDeps`). The holder
  * binds these to its injected `notify` chain + the bound child logger + its clock + the
  * resolved `drive.notify` policy. `notify` is optional (a sync-API channel with no notify
- * callback → the outcome rides the turn result as today, I1).
+ * callback → the outcome rides the turn result).
  */
 export interface TerminalNotifyDeps {
-    /** The §4.7 channel notify chain (`bgNotifyFn` → NotificationService). Absent ⇒ bus-only (I1). */
+    /** The channel notify chain (`bgNotifyFn` → NotificationService). Absent ⇒ bus-only. */
     notify?: WokenTurnNotify;
     /** A pino-compatible INFO sink (the content-free §2.7 record for `done` / a heartbeat). */
     info(obj: Record<string, unknown>, msg: string): void;
@@ -55,9 +55,9 @@ export interface TerminalNotifyDeps {
     policy: NotifyPolicy;
 }
 /**
- * CR-01 (Phase 166): the GENUINE-DEATH discriminator for a `lost` transition — the pure
- * decision the wake holder's `onStateChange` consumes so the holder stays under the 800-line
- * cap (IN-02) and the I9/I10 invariant is RED-pinnable without a live CLI.
+ * The GENUINE-DEATH discriminator for a `lost` transition — the pure decision the wake holder's
+ * `onStateChange` consumes so the holder stays under the 800-line cap and the fire-`failed`-only-
+ * on-genuine-death invariant is unit-pinnable without a live CLI.
  *
  * `terminal:session_state{state:"lost"}` has TWO indistinguishable-on-the-bus sources: a
  * genuinely unrecoverable death (terminal-durable-wiring.ts `onUnrecoverable` — the durable
@@ -67,32 +67,32 @@ export interface TerminalNotifyDeps {
  *
  * Pure + total — never throws. The SAFE direction is `false` (do NOT fail): an absent /
  * `undefined` / `false` marker is a transient/recoverable lost (a promoted long drive whose
- * worker briefly crashes, or a re-attaching durable drive, is NEVER reported failed — I9/I10).
+ * worker briefly crashes, or a re-attaching durable drive, is NEVER reported failed).
  * ONLY an explicit `true` is a genuine death.
  *
  * @param unrecoverable - The genuine-death discriminator off the `terminal:session_state` event.
  * @returns `true` iff the `lost` is a genuine death (→ map to `failed`); `false` otherwise.
  */
 export declare function shouldFailOnLost(unrecoverable: boolean | undefined): boolean;
-/** The content-free outcome the holder derived from a state transition (DUR-02 / NOTIFY-01). */
+/** The content-free outcome the holder derived from a state transition. */
 export interface TerminalOutcomeArgs {
     readonly sessionId: string;
     readonly agentId: string;
     /**
      * The transition the holder observed — `exited` (clean PTY exit → done) or a genuine death:
      * `lost` (durable + unrecoverable → failed) / `evicted` (a NAMED cap → failed naming the cap).
-     * `needs-you` is NEVER passed here (the existing escalate() path owns it — I4). A
+     * `needs-you` is NEVER passed here (the existing escalate() path owns it). A
      * transient/recoverable `lost` never reaches here (the holder gates it via {@link shouldFailOnLost}).
      */
     readonly transition: "exited" | "lost" | "evicted";
     /** Present ONLY for `evicted` — the named cap the reaper tripped (the dropped-reason fix). */
     readonly capName?: EvictReason | undefined;
     /**
-     * WR-03 (Phase 166): present ONLY for a genuine-death `lost` — the content-free unrecoverable
-     * reason (a closed structural tag, e.g. `"tmux_session_gone"`) threaded from the
-     * `terminal:session_state` event so the `failed` message + the §2.7 WARN name the actual cause
-     * (`comis explain` reads it) rather than a generic "session_lost". Absent ⇒ fall back to the
-     * generic reason. Content-free (I3 — a machine tag, never screen bytes).
+     * Present ONLY for a genuine-death `lost` — the content-free unrecoverable reason (a closed
+     * structural tag, e.g. `"tmux_session_gone"`) threaded from the `terminal:session_state` event
+     * so the `failed` message + the §2.7 WARN name the actual cause (`comis explain` reads it)
+     * rather than a generic "session_lost". Absent ⇒ fall back to the generic reason. Content-free
+     * (a machine tag, never screen bytes).
      */
     readonly lostReason?: string | undefined;
     /** The captured cumulative drive duration (`nowMs - driveStartedAtMs`), captured before clear. */
@@ -101,15 +101,14 @@ export interface TerminalOutcomeArgs {
     readonly interactions?: number | undefined;
 }
 /**
- * Derive + emit ONE user-facing terminal outcome (`done` / `failed`) for a PROMOTED drive —
- * NOTIFY-01. Lands the `failed` outcome deferred from Phase 165.
+ * Derive + emit ONE user-facing terminal outcome (`done` / `failed`) for a PROMOTED drive.
  *
- * The outcome is derived via the pure {@link mapTerminalOutcome} (the I9-safe map): `exited` →
- * `done`; `lost`/`evicted` set `failure` → `failed`. The notify is gated by
+ * The outcome is derived via the pure {@link mapTerminalOutcome}: `exited` → `done`;
+ * `lost`/`evicted` set `failure` → `failed`. The notify is gated by
  * {@link shouldNotifyOutcome} (so `done`/`failed` are suppressed under `drive.notify:"none"`).
  * The §2.7 record fires REGARDLESS of the gate (an operator who silenced the channel still gets
  * the log) — INFO for `done`, WARN + hint + errorKind for `failed`. The channel message is
- * STRUCTURAL only (I3): sessionId + the outcome enum + durationMs + interactions + capName,
+ * STRUCTURAL only: sessionId + the outcome enum + durationMs + interactions + capName,
  * NEVER the screen.
  *
  * Fire-and-forget + total: a `notify` rejection is swallowed to a WARN; never throws.
@@ -120,7 +119,7 @@ export interface TerminalOutcomeArgs {
 export declare function emitTerminalOutcome(deps: TerminalNotifyDeps, args: TerminalOutcomeArgs): void;
 /** The per-session read-only views + the dedupe-stamp Map the heartbeat tick reads/writes. */
 export interface HeartbeatTickArgs {
-    /** The promoted-session set (I1 — only promoted drives are heartbeated). */
+    /** The promoted-session set (only promoted drives are heartbeated). */
     readonly promotedSessions: ReadonlySet<string>;
     /** The per-session content-free journal holder (the digest source). */
     readonly driveJournals: ReadonlyMap<string, DriveJournal>;
@@ -140,8 +139,8 @@ export interface HeartbeatTickArgs {
     readonly heartbeatNotifyMs: number;
 }
 /**
- * The NOTIFY-02 per-tick heartbeat loop body — the holder's coarse timer calls this each tick.
- * For each PROMOTED session (I1 — only long drives) that is DUE at the cadence (`now -
+ * The per-tick heartbeat loop body — the holder's coarse timer calls this each tick.
+ * For each PROMOTED session (only long drives) that is DUE at the cadence (`now -
  * lastHeartbeatSentMs >= heartbeatNotifyMs`), emit the content-free {@link heartbeatLine}
  * digest + an INFO §2.7 record, then stamp `lastHeartbeatSentMs`. A just-promoted drive with
  * no journal yet yields a safe "(no activity yet)" line (heartbeatLine is total). Fire-and-
@@ -151,21 +150,21 @@ export interface HeartbeatTickArgs {
  */
 export declare function runHeartbeatTick(args: HeartbeatTickArgs): void;
 /**
- * The LIVE-01 backstop's per-session check — extracted from `setup-terminal-wake.ts` (the timer +
+ * The liveness backstop's per-session check — extracted from `setup-terminal-wake.ts` (the timer +
  * the `promotedSessions` loop stay there) to keep that holder under the 800-line cap. It runs the
- * single injected liveness probe for ONE promoted session (NO screen read, I2) and acts on the
+ * single injected liveness probe for ONE promoted session (NO screen read) and acts on the
  * verdict:
- *   - a wake within the heartbeat window (a normally-progressing drive) → SKIP (Pitfall 7).
+ *   - a wake within the heartbeat window (a normally-progressing drive) → SKIP (no probe needed).
  *   - `hung` → synthesize a `state:"stuck"` wake through the EXISTING terminal:input_needed seam
  *     (NOT a new event) + a §2.7 WARN — at-most-once per silent stretch (the onWakeTransition
  *     listener re-stamps `lastTransitionMs` off the synth).
- *   - DELIVER-01 (#2): `busy` + `awaitingInput` (the drive FINISHED its current work + is idle at
- *     its prompt) → deliver a ONE-TIME completion notification (a backgrounded drive emits no fd3
- *     attention, so the backstop is the only place this is observed), de-duped via
- *     `completionNotified`; the latch is CLEARED when the drive resumes working so a fresh idle
- *     after the user replies re-notifies.
- *   - `busy` + working (still producing) → nothing (the ENDURE-01 unify: the `checkLiveness` status
- *     round-trip already refreshed `lastActivity`, LO-03).
+ *   - `busy` + `awaitingInput` (the drive FINISHED its current work + is idle at its prompt) →
+ *     deliver a ONE-TIME completion notification (a backgrounded drive emits no fd3 attention, so
+ *     the backstop is the only place this is observed), de-duped via `completionNotified`; the
+ *     latch is CLEARED when the drive resumes working so a fresh idle after the user replies
+ *     re-notifies.
+ *   - `busy` + working (still producing) → nothing (the idle-reaper unify: the `checkLiveness`
+ *     status round-trip already refreshed `lastActivity`).
  * Fire-and-forget + total: the caller isolates a per-session fault.
  */
 export interface BackstopSessionCheckArgs {
@@ -173,7 +172,7 @@ export interface BackstopSessionCheckArgs {
     agentId: string;
     now: number;
     heartbeatMs: number;
-    /** `lastTransitionMs.get(sessionId)` — the I2 "a wake landed within the window" skip. */
+    /** `lastTransitionMs.get(sessionId)` — the "a wake landed within the window" skip. */
     lastWakeMs: number | undefined;
     checkLiveness: (sessionId: string, agentId: string) => Promise<LivenessSignal | undefined> | LivenessSignal | undefined;
     /** Synthesize a stuck through the EXISTING `terminal:input_needed` seam (the caller wraps the typed bus). */
@@ -185,7 +184,7 @@ export interface BackstopSessionCheckArgs {
         confidence: "high";
         timestamp: number;
     }) => void;
-    /** The DELIVER-01 once-per-idle-stretch latch (caller-owned; reclaimed on session end). */
+    /** The once-per-idle-stretch completion latch (caller-owned; reclaimed on session end). */
     completionNotified: Set<string>;
     notify?: WokenTurnNotify;
     notifyPolicy: NotifyPolicy;

package/node_modules/@comis/daemon/dist/wiring/terminal-wake-notify.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The NOTIFY-01 / NOTIFY-02 user-facing outcome+heartbeat EMIT helpers (166-03) — the thin
- * side-effecting glue between the wake holder's content-free signals and the user's channel.
+ * The user-facing outcome+heartbeat EMIT helpers — the thin side-effecting glue between the
+ * wake holder's content-free signals and the user's channel.
  *
  * Extracted from `setup-terminal-wake.ts` so that file stays well under the 800-line
  * architecture cap (it is at the TIGHT end of the band; `terminal-tools.ts` /
- * `terminal-session-registry.ts` are AT the cap). The PURE decisions live in 166-01's skills
+ * `terminal-session-registry.ts` are AT the cap). The PURE decisions live in the skills
  * siblings (`mapTerminalOutcome` / `shouldNotifyOutcome` / `heartbeatLine`); this module
  * performs the already-decided emit through INJECTED seams — mirroring the
  * `terminal-drive-promote.ts` `emitDrivePromoted` precedent (a STRUCTURAL deps interface, not
@@ -14,39 +14,39 @@
  * Two helpers:
  *   - {@link emitTerminalOutcome} — derive (via `mapTerminalOutcome`) and emit ONE user-facing
  *     terminal outcome (`done` / `failed`; `needs-you` is emitted by the existing escalate()
- *     path, NEVER routed here — I4), gated by `shouldNotifyOutcome(outcome, policy)`, with the
+ *     path, NEVER routed here), gated by `shouldNotifyOutcome(outcome, policy)`, with the
  *     §2.7 record (INFO for `done`, WARN + hint + errorKind for `failed`). The message is
  *     STRUCTURAL only (sessionId + outcome enum + durationMs + interactions + capName) —
- *     NEVER the screen (I3).
- *   - {@link runHeartbeatTick} — the NOTIFY-02 per-tick heartbeat loop body the holder's coarse
- *     timer calls: for each PROMOTED session due at the cadence, emit the content-free
+ *     NEVER the screen.
+ *   - {@link runHeartbeatTick} — the per-tick heartbeat loop body the holder's coarse timer
+ *     calls: for each PROMOTED session due at the cadence, emit the content-free
  *     `heartbeatLine` digest + an INFO record, stamping `lastHeartbeatSentMs`. Kept here (not
- *     inlined in the holder) per the extraction directive.
+ *     inlined in the holder) to keep that holder under the line cap.
  *
- * Architecture invariants (binding — AGENTS.md / 124 house style, mirrors `emitDrivePromoted`):
+ * Architecture invariants (binding — AGENTS.md house style, mirrors `emitDrivePromoted`):
  *   - The I/O rides EXCLUSIVELY through the injected `notify` / `info` / `warn` / `nowMs` seams
  *     — no value-imported bus/logger, no raw clock (the globals + infra-runtime-scope gates).
  *   - TOTAL / fire-and-forget: a `notify` rejection is swallowed to a WARN (a notify fault on a
  *     synchronous bus listener must never become an uncaughtException that crashes the daemon).
- *   - CONTENT-FREE (I3): every message is structural counts/durations + the already-redacted
+ *   - CONTENT-FREE: every message is structural counts/durations + the already-redacted
  *     `lastScreenDigest` (formatted by `heartbeatLine`, never re-expanded) — never raw TUI bytes.
  *
  * @module
  */
 import { busyOrHung, mapTerminalOutcome, shouldNotifyOutcome, heartbeatLine } from "@comis/skills/tools";
 /**
- * WR-04 (Phase 166): the explicit "unknown cap" sentinel for an `evicted` outcome that arrives
- * WITHOUT a cap name. Used in place of a fabricated plausible cap (`max_sessions`) so a missing
- * cap reads honestly as "(cap unknown)" in the user message + the `failed` outcome — naming the
- * WRONG cap would violate I9 ("name the cap so it reads as a choice, not a mystery"). In practice
- * the reaper always supplies a cap (events-terminal.ts), so this is a defensive floor, not a hot
- * path. It is a closed structural tag (matches the pure `OutcomeInputs.failure` `cap` widening).
+ * The explicit "unknown cap" sentinel for an `evicted` outcome that arrives WITHOUT a cap name.
+ * Used in place of a fabricated plausible cap (`max_sessions`) so a missing cap reads honestly as
+ * "(cap unknown)" in the user message + the `failed` outcome — naming the WRONG cap would mislead
+ * the user (the cap must read as a deliberate choice, not a mystery). In practice the reaper
+ * always supplies a cap (events-terminal.ts), so this is a defensive floor, not a hot path. It is
+ * a closed structural tag (matches the pure `OutcomeInputs.failure` `cap` widening).
  */
 const CAP_UNKNOWN = "unknown";
 /**
- * CR-01 (Phase 166): the GENUINE-DEATH discriminator for a `lost` transition — the pure
- * decision the wake holder's `onStateChange` consumes so the holder stays under the 800-line
- * cap (IN-02) and the I9/I10 invariant is RED-pinnable without a live CLI.
+ * The GENUINE-DEATH discriminator for a `lost` transition — the pure decision the wake holder's
+ * `onStateChange` consumes so the holder stays under the 800-line cap and the fire-`failed`-only-
+ * on-genuine-death invariant is unit-pinnable without a live CLI.
  *
  * `terminal:session_state{state:"lost"}` has TWO indistinguishable-on-the-bus sources: a
  * genuinely unrecoverable death (terminal-durable-wiring.ts `onUnrecoverable` — the durable
@@ -56,7 +56,7 @@ const CAP_UNKNOWN = "unknown";
  *
  * Pure + total — never throws. The SAFE direction is `false` (do NOT fail): an absent /
  * `undefined` / `false` marker is a transient/recoverable lost (a promoted long drive whose
- * worker briefly crashes, or a re-attaching durable drive, is NEVER reported failed — I9/I10).
+ * worker briefly crashes, or a re-attaching durable drive, is NEVER reported failed).
  * ONLY an explicit `true` is a genuine death.
  *
  * @param unrecoverable - The genuine-death discriminator off the `terminal:session_state` event.
@@ -66,15 +66,14 @@ export function shouldFailOnLost(unrecoverable) {
     return unrecoverable === true;
 }
 /**
- * Derive + emit ONE user-facing terminal outcome (`done` / `failed`) for a PROMOTED drive —
- * NOTIFY-01. Lands the `failed` outcome deferred from Phase 165.
+ * Derive + emit ONE user-facing terminal outcome (`done` / `failed`) for a PROMOTED drive.
  *
- * The outcome is derived via the pure {@link mapTerminalOutcome} (the I9-safe map): `exited` →
- * `done`; `lost`/`evicted` set `failure` → `failed`. The notify is gated by
+ * The outcome is derived via the pure {@link mapTerminalOutcome}: `exited` → `done`;
+ * `lost`/`evicted` set `failure` → `failed`. The notify is gated by
  * {@link shouldNotifyOutcome} (so `done`/`failed` are suppressed under `drive.notify:"none"`).
  * The §2.7 record fires REGARDLESS of the gate (an operator who silenced the channel still gets
  * the log) — INFO for `done`, WARN + hint + errorKind for `failed`. The channel message is
- * STRUCTURAL only (I3): sessionId + the outcome enum + durationMs + interactions + capName,
+ * STRUCTURAL only: sessionId + the outcome enum + durationMs + interactions + capName,
  * NEVER the screen.
  *
  * Fire-and-forget + total: a `notify` rejection is swallowed to a WARN; never throws.
@@ -83,13 +82,13 @@ export function shouldFailOnLost(unrecoverable) {
  * @param args - The content-free outcome the holder captured before onSessionGone.
  */
 export function emitTerminalOutcome(deps, args) {
-    // Build the I9-safe outcome inputs: a clean exit → done; a genuine death → failed.
+    // Build the outcome inputs: a clean exit → done; a genuine death → failed.
     // An `evicted` transition ⇒ a cap-eviction (errorKind resource); a `lost` ⇒ unrecoverable
-    // (errorKind dependency). `needs-you` never reaches here (the escalate() path owns it — I4).
+    // (errorKind dependency). `needs-you` never reaches here (the escalate() path owns it).
     //
-    // WR-03: a `lost` failure threads the REAL unrecoverable reason (args.lostReason, e.g.
+    // A `lost` failure threads the REAL unrecoverable reason (args.lostReason, e.g.
     // "tmux_session_gone") so the user message + the §2.7 WARN name the actual cause; absent ⇒ the
-    // generic "session_lost" fallback. WR-04: an `evicted` failure NEVER fabricates a cap name —
+    // generic "session_lost" fallback. An `evicted` failure NEVER fabricates a cap name —
     // the failure's `cap` carries the real capName when present, else an explicit unknown sentinel
     // (CAP_UNKNOWN) so a missing cap reads as "(cap unknown)", not a plausible-but-false cap.
     const failure = args.transition === "lost"
@@ -102,12 +101,12 @@ export function emitTerminalOutcome(deps, args) {
     // (it is invoked solely on a terminal transition). Defensive: nothing to emit ⇒ return.
     if (outcome === undefined)
         return;
-    // needs-you must never be routed through this gate (I4). This caller never passes it, but
+    // needs-you must never be routed through this gate. This caller never passes it, but
     // guard defensively so a future caller cannot regress the escalate-always invariant here.
     if (outcome === "needs-you")
         return;
     const errorKind = failure?.kind === "cap" ? "resource" : "dependency";
-    // WR-04: the honest cap label — the real cap name, or an explicit unknown sentinel. NEVER a
+    // The honest cap label — the real cap name, or an explicit unknown sentinel. NEVER a
     // fabricated `max_sessions`. Drives both the §2.7 hint and the user message.
     const capLabel = args.capName ?? CAP_UNKNOWN;
     // The §2.7 record — fires regardless of the channel gate (the log is the operator's floor).
@@ -120,9 +119,9 @@ export function emitTerminalOutcome(deps, args) {
             agentId: args.agentId,
             outcome,
             errorKind,
-            // WR-04: record the cap ONLY when it is a real cap name (never the unknown sentinel).
+            // Record the cap ONLY when it is a real cap name (never the unknown sentinel).
             ...(args.capName !== undefined ? { capName: args.capName } : {}),
-            // WR-03: record the real unrecoverable reason on a lost failure (a closed structural tag).
+            // Record the real unrecoverable reason on a lost failure (a closed structural tag).
             ...(failure?.kind === "unrecoverable" ? { reason: failure.reason } : {}),
             durationMs: args.durationMs,
             interactions: args.interactions,
@@ -133,12 +132,12 @@ export function emitTerminalOutcome(deps, args) {
         }, "terminal drive failed");
     }
     // The user-facing channel notify — gated by drive.notify (done/failed suppressed under
-    // "none"; needs-you would always pass but never reaches here). STRUCTURAL message only (I3).
+    // "none"; needs-you would always pass but never reaches here). STRUCTURAL message only.
     if (!deps.notify)
-        return; // bus-only channel (no notify callback) → the log above is the record (I1).
+        return; // bus-only channel (no notify callback) → the log above is the record.
     if (!shouldNotifyOutcome(outcome, deps.policy))
         return;
-    // WR-04: on an evicted failure name the cap honestly — the real cap, or "(cap unknown)" — never
+    // On an evicted failure name the cap honestly — the real cap, or "(cap unknown)" — never
     // a fabricated one. A lost failure carries no cap suffix.
     const failedSuffix = args.transition === "evicted" ? ` (${capLabel})` : "";
     const message = outcome === "done"
@@ -150,7 +149,7 @@ export function emitTerminalOutcome(deps, args) {
         deps.warn({ sessionId: args.sessionId, agentId: args.agentId, err, outcome, hint: "drive-outcome notification failed; the drive lifecycle is unaffected (bus-only)", errorKind: "resource", step: "drive_outcome_notify_failed" }, "terminal drive-outcome notification failed");
     });
 }
-/** A content-free tail for the outcome message — durations/counts only, never the screen (I3). */
+/** A content-free tail for the outcome message — durations/counts only, never the screen. */
 function describeTail(args) {
     const parts = [];
     if (typeof args.durationMs === "number" && Number.isFinite(args.durationMs) && args.durationMs > 0) {
@@ -162,8 +161,8 @@ function describeTail(args) {
     return parts.length > 0 ? ` — ${parts.join(", ")}` : "";
 }
 /**
- * The NOTIFY-02 per-tick heartbeat loop body — the holder's coarse timer calls this each tick.
- * For each PROMOTED session (I1 — only long drives) that is DUE at the cadence (`now -
+ * The per-tick heartbeat loop body — the holder's coarse timer calls this each tick.
+ * For each PROMOTED session (only long drives) that is DUE at the cadence (`now -
  * lastHeartbeatSentMs >= heartbeatNotifyMs`), emit the content-free {@link heartbeatLine}
  * digest + an INFO §2.7 record, then stamp `lastHeartbeatSentMs`. A just-promoted drive with
  * no journal yet yields a safe "(no activity yet)" line (heartbeatLine is total). Fire-and-
@@ -180,7 +179,7 @@ export function runHeartbeatTick(args) {
             continue; // not due yet (coarse cadence + dedupe).
         const agentId = args.sessionAgent.get(sessionId) ?? "";
         const j = args.driveJournals.get(sessionId);
-        // The content-free digest — heartbeatLine is total (a missing journal → a safe line, I3).
+        // The content-free digest — heartbeatLine is total (a missing journal → a safe line).
         const message = heartbeatLine(j ?? { elapsedMs: 0, lastScreenDigest: "", interactions: 0, costUsd: 0 });
         // Stamp BEFORE the async notify so a fault does not cause a re-fire storm next tick.
         args.lastHeartbeatSentMs.set(sessionId, now);
@@ -193,7 +192,7 @@ export function runHeartbeatTick(args) {
     }
 }
 export async function runBackstopSessionCheck(a) {
-    // I2: a wake landed within the heartbeat window → a normally-progressing drive; SKIP (no probe).
+    // A wake landed within the heartbeat window → a normally-progressing drive; SKIP (no probe).
     if (a.lastWakeMs !== undefined && a.now - a.lastWakeMs < a.heartbeatMs)
         return;
     const signal = await a.checkLiveness(a.sessionId, a.agentId);
@@ -201,7 +200,7 @@ export async function runBackstopSessionCheck(a) {
         return; // a gone session → skip.
     if (busyOrHung(signal) === "busy") {
         if (signal.awaitingInput === true) {
-            // DELIVER-01 (#2): the drive finished its current work + is idle at its prompt → deliver ONCE.
+            // The drive finished its current work + is idle at its prompt → deliver ONCE.
             if (!a.completionNotified.has(a.sessionId)) {
                 a.completionNotified.add(a.sessionId);
                 if (a.notify && a.notifyPolicy !== "none") {
@@ -221,7 +220,7 @@ export async function runBackstopSessionCheck(a) {
             return;
         }
         // Still working (not at a prompt) — clear the completion latch so the NEXT idle re-notifies.
-        // ENDURE-01 unify (I9): lastActivity is already refreshed by the checkLiveness status stamp (LO-03).
+        // The idle-reaper unify: lastActivity is already refreshed by the checkLiveness status stamp.
         a.completionNotified.delete(a.sessionId);
         return;
     }

package/node_modules/@comis/daemon/dist/wiring/terminal-wake-persistence.d.ts

@@ -1,6 +1,6 @@
 /** Directory name under the data dir for per-session wake-state files. */
 export declare const WAKE_DIR_NAME = "terminal-wake";
-/** The owning origin of a terminal session — `(agentId, sessionKey)` (TR-13). */
+/** The owning origin of a terminal session — `(agentId, sessionKey)`. */
 export interface PersistedWakeOwner {
     agentId: string;
     sessionKey: string;

package/node_modules/@comis/daemon/dist/wiring/terminal-wake-persistence.js

@@ -4,8 +4,8 @@
  * Durable per-session wake-state for the recurring wake-dispatch FSM
  * (terminal-wake-dispatch.ts).
  *
- * This is the OPS-09 "survives daemon restart" substrate: the FSM persists
- * its per-session dispatch state on every transition and re-hydrates it on
+ * This is the "survives daemon restart" substrate: the FSM persists its
+ * per-session dispatch state on every transition and re-hydrates it on
  * construction (recover-on-boot), so a session mid-wake before a daemon
  * restart is not spuriously re-woken.
  *
@@ -17,10 +17,10 @@
  * `terminal-wake/{sessionId}.json` subdir (the analogue of
  * `background-tasks/{agentId}/{taskId}.json`).
  *
- * **Daemon-side placement (binding — RESEARCH Open Q1 + Pitfall 3):** the
- * persistence imports `@comis/observability`, which `@comis/skills` MUST NOT
- * value-import. The FSM + this substrate therefore live in the daemon layer
- * (composition-root's to use observability), not in the skills worker.
+ * **Daemon-side placement (binding constraint):** the persistence imports
+ * `@comis/observability`, which `@comis/skills` MUST NOT value-import. The FSM
+ * + this substrate therefore live in the daemon layer (the composition root's
+ * to use observability), not in the skills worker.
  *
  * **Best-effort contract:** a persist failure is swallowed (it must not
  * propagate to the caller, which has already acted on the in-memory state);
@@ -94,7 +94,7 @@ export function recoverWakeStates(dataDir) {
     const recovered = [];
     // Best-effort: a degenerate dataDir (e.g. a relative "." from a bootstrap/test config)
     // makes safePath throw PathTraversalError — recovery must NOT crash the FSM constructor
-    // (124-07 recovers on construction). Swallow + return [] (mirrors persistWakeStateSync).
+    // (the FSM recovers on construction). Swallow + return [] (mirrors persistWakeStateSync).
     let dir;
     try {
         dir = wakeDir(dataDir);