comisai 1.0.41 → 1.0.44

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

@@ -0,0 +1,121 @@
+/**
+ * The send-path guards for `terminal_session_send_text` / `_send_key` PLUS the
+ * resize geometry validator ({@link readDimension})
+ * — extracted from `terminal-tools.ts` so that file stays under the 800-line
+ * architecture cap (the same discipline that produced
+ * `terminal-worker-launch.ts` / `terminal-workspace.ts` / `terminal-reaper.ts`).
+ *
+ * The two send tools call {@link enforceSendCapsThenAudit} (which composes the two
+ * primitives below in the canonical order — enforce caps, then audit EVERY invocation
+ * tagged with its outcome, INCLUDING a cap-rejected one) BEFORE
+ * forwarding to the registry:
+ *
+ *   1. {@link enforceSendCaps} — the binding EVICT-vs-REJECT cap split:
+ *      - `maxRequestsPerSession` (rate cap) → REJECT only; the session
+ *        SURVIVES (read/list/other sends still work).
+ *      - `maxInteractions` (interaction budget spent) → EVICT via
+ *        `registry.evict(sessionId, owner, "max_interactions")` (the single audited
+ *        eviction path: drop + workspace cleanup + `terminal:session_evicted` + the
+ *        registry `onCapForget` → `caps.forget`) THEN reject.
+ *      - `wallClockMs` → EVICT likewise (reason `wall_clock`) THEN reject;
+ *        the reaper sweep also evicts on age — this is the immediate per-send guard
+ *        routing through the SAME eviction path.
+ *      The tool does NOT call `caps.forget` in the evict branches — the registry's
+ *      `onCapForget` owns that (no double-forget).
+ *
+ *   2. {@link auditKeystroke} — the per-send keystroke audit: scrub the raw payload via
+ *      `scrubSecretsFromText` (the @comis/core primitive the read tool uses — NEVER
+ *      `redactSecretsInText`, which is the skills-forbidden @comis/observability),
+ *      put the REDACTED payload in the structured LOG (DEBUG, step `keystroke_audit`),
+ *      and emit the `terminal:keystroke` bus event carrying ONLY the redaction-safe
+ *      summary (`redactions` + `byteLength`; never the payload). The raw payload NEVER
+ *      reaches a log or the bus.
+ *
+ * The guards take a NARROW structural `SendGuardDeps` (the exact subset of
+ * `TerminalToolDeps` they use), defined HERE rather than importing `TerminalToolDeps`
+ * from `terminal-tools.ts` — that inverts the dependency so there is NO
+ * `terminal-tools ↔ terminal-send-guards` import cycle (madge counts type-only edges).
+ * `TerminalToolDeps` is a structural superset, so the tools pass `deps` verbatim.
+ *
+ * Architecture: this is daemon-side `@comis/skills` code — it value-imports only
+ * `@comis/core` (`scrubSecretsFromText`) + the local `tool-helpers` (`throwToolError`)
+ * and TYPE-ONLY the leaf registry/caps shapes; NEVER `@comis/infra`/`@comis/observability`.
+ *
+ * @module
+ */
+import type { SessionCaps } from "./terminal-caps.js";
+import type { SessionOwner, TerminalSessionRegistry } from "./terminal-session-registry.js";
+/** The redaction-safe keystroke-audit event payload (mirrors core `terminal:keystroke`). */
+interface KeystrokeAuditEvent {
+    sessionId: string;
+    agentId: string;
+    kind: "text" | "key";
+    redactions: number;
+    byteLength: number;
+    /** Attempt outcome: `attempted` = forwarded; `rejected` = blocked by a cap breach. */
+    outcome: "attempted" | "rejected";
+    timestamp: number;
+}
+/**
+ * The NARROW deps the send guards use — a structural subset of `TerminalToolDeps`
+ * (defined here, NOT imported, to keep the dependency one-directional / cycle-free).
+ * The registry surface is narrowed to just `evict` (the only method the guards drive).
+ */
+export interface SendGuardDeps {
+    readonly caps: SessionCaps;
+    readonly registry: Pick<TerminalSessionRegistry, "evict">;
+    readonly logger: {
+        debug(obj: Record<string, unknown>, msg: string): void;
+        warn(obj: Record<string, unknown>, msg: string): void;
+    };
+    readonly eventBus: {
+        emit(event: "terminal:keystroke", payload: KeystrokeAuditEvent): unknown;
+    };
+    readonly agentId: string;
+    readonly nowMs: () => number;
+}
+/**
+ * Enforce the per-session caps BEFORE forwarding a `send_*` to the registry — throws
+ * `permission_denied` on ANY breach (never returns on breach). See the module doc for
+ * the EVICT-vs-REJECT split. Every breach WARNs with `errorKind: "resource"` +
+ * `step: "cap_breach"` (§2.7).
+ */
+export declare function enforceSendCaps(deps: SendGuardDeps, sessionId: string, owner: SessionOwner, toolName: string): Promise<void>;
+/**
+ * Emit the keystroke audit for one `send_*` INVOCATION. See the module doc.
+ * The raw `payload` NEVER reaches a log or the bus — only the scrubbed payload (LOG)
+ * and the redaction-safe summary (EVENT). `outcome` tags the attempt: `attempted`
+ * (passed the caps, forwarded) or `rejected` (a cap breach blocked the forward) —
+ * an ATTEMPT signal, never proof of delivery (the event doc spells this out).
+ */
+export declare function auditKeystroke(deps: SendGuardDeps, sessionId: string, toolName: string, kind: "text" | "key", payload: string, outcome: "attempted" | "rejected"): void;
+/**
+ * Enforce the per-session caps THEN audit the send — the single canonical order
+ * the two send tools call. EVERY invocation is audited exactly once:
+ *   - a cap breach → audit `outcome:"rejected"` (the redacted attempt is still
+ *     recorded — what the agent TRIED to type before it was rate-capped/evicted),
+ *     then the `enforceSendCaps` rejection re-propagates (the forward is skipped);
+ *   - no breach → audit `outcome:"attempted"`, then the caller forwards to the
+ *     registry.
+ * Auditing on the breach path is safe: `auditKeystroke` only LOGs the redacted form
+ * + emits the redaction-safe summary — it writes nothing to the PTY. Centralizing the
+ * try/audit/rethrow here (vs inlining it in both tools) keeps terminal-tools.ts lean.
+ */
+export declare function enforceSendCapsThenAudit(deps: SendGuardDeps, sessionId: string, owner: SessionOwner, toolName: string, kind: "text" | "key", payload: string): Promise<void>;
+/**
+ * The upper bound on a terminal dimension. A real terminal is never this
+ * wide/tall; the cap blocks an agent from inflating the worker's emulator buffer /
+ * PTY winsize with an absurd value. The schema types cols/rows as integers; this is
+ * the value-range guard the schema does not express.
+ */
+export declare const MAX_TERMINAL_DIMENSION = 10000;
+/**
+ * Read + VALIDATE a terminal dimension (cols/rows) from agent params. The
+ * geometry is not a trust boundary, but the tool layer must not forward a degenerate
+ * value (0/negative/non-integer/absurd) into the worker's `Terminal({cols,rows})` /
+ * PTY winsize. Throws a typed `invalid_value` (never returns on a bad value) so the
+ * resize tool rejects BEFORE the registry forward. Lives here (not terminal-tools.ts)
+ * to keep that file under the 800-line architecture cap.
+ */
+export declare function readDimension(p: Record<string, unknown>, key: string): number;
+export {};

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

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The send-path guards for `terminal_session_send_text` / `_send_key` PLUS the
+ * resize geometry validator ({@link readDimension})
+ * — extracted from `terminal-tools.ts` so that file stays under the 800-line
+ * architecture cap (the same discipline that produced
+ * `terminal-worker-launch.ts` / `terminal-workspace.ts` / `terminal-reaper.ts`).
+ *
+ * The two send tools call {@link enforceSendCapsThenAudit} (which composes the two
+ * primitives below in the canonical order — enforce caps, then audit EVERY invocation
+ * tagged with its outcome, INCLUDING a cap-rejected one) BEFORE
+ * forwarding to the registry:
+ *
+ *   1. {@link enforceSendCaps} — the binding EVICT-vs-REJECT cap split:
+ *      - `maxRequestsPerSession` (rate cap) → REJECT only; the session
+ *        SURVIVES (read/list/other sends still work).
+ *      - `maxInteractions` (interaction budget spent) → EVICT via
+ *        `registry.evict(sessionId, owner, "max_interactions")` (the single audited
+ *        eviction path: drop + workspace cleanup + `terminal:session_evicted` + the
+ *        registry `onCapForget` → `caps.forget`) THEN reject.
+ *      - `wallClockMs` → EVICT likewise (reason `wall_clock`) THEN reject;
+ *        the reaper sweep also evicts on age — this is the immediate per-send guard
+ *        routing through the SAME eviction path.
+ *      The tool does NOT call `caps.forget` in the evict branches — the registry's
+ *      `onCapForget` owns that (no double-forget).
+ *
+ *   2. {@link auditKeystroke} — the per-send keystroke audit: scrub the raw payload via
+ *      `scrubSecretsFromText` (the @comis/core primitive the read tool uses — NEVER
+ *      `redactSecretsInText`, which is the skills-forbidden @comis/observability),
+ *      put the REDACTED payload in the structured LOG (DEBUG, step `keystroke_audit`),
+ *      and emit the `terminal:keystroke` bus event carrying ONLY the redaction-safe
+ *      summary (`redactions` + `byteLength`; never the payload). The raw payload NEVER
+ *      reaches a log or the bus.
+ *
+ * The guards take a NARROW structural `SendGuardDeps` (the exact subset of
+ * `TerminalToolDeps` they use), defined HERE rather than importing `TerminalToolDeps`
+ * from `terminal-tools.ts` — that inverts the dependency so there is NO
+ * `terminal-tools ↔ terminal-send-guards` import cycle (madge counts type-only edges).
+ * `TerminalToolDeps` is a structural superset, so the tools pass `deps` verbatim.
+ *
+ * Architecture: this is daemon-side `@comis/skills` code — it value-imports only
+ * `@comis/core` (`scrubSecretsFromText`) + the local `tool-helpers` (`throwToolError`)
+ * and TYPE-ONLY the leaf registry/caps shapes; NEVER `@comis/infra`/`@comis/observability`.
+ *
+ * @module
+ */
+import { scrubSecretsFromText } from "@comis/core";
+import { throwToolError } from "../../../platform-tools/tool-helpers.js";
+/**
+ * Enforce the per-session caps BEFORE forwarding a `send_*` to the registry — throws
+ * `permission_denied` on ANY breach (never returns on breach). See the module doc for
+ * the EVICT-vs-REJECT split. Every breach WARNs with `errorKind: "resource"` +
+ * `step: "cap_breach"` (§2.7).
+ */
+export async function enforceSendCaps(deps, sessionId, owner, toolName) {
+    const reqBreach = deps.caps.consumeRequest(sessionId);
+    if (reqBreach) {
+        deps.logger.warn({ toolName, sessionId, errorKind: "resource", step: "cap_breach", hint: "per-session request rate cap reached" }, "terminal session request cap exceeded");
+        throwToolError("permission_denied", `cap exceeded: ${reqBreach.breach}`, {
+            hint: "this session reached its per-session request rate cap (operator limits.maxRequestsPerSession) — the session stays usable for read/list/other sends",
+        });
+    }
+    const intBreach = deps.caps.consumeInteraction(sessionId);
+    if (intBreach) {
+        deps.logger.warn({ toolName, sessionId, errorKind: "resource", step: "cap_breach", hint: "interaction budget spent — evicting" }, "terminal session interaction budget exceeded");
+        // EVICT (not just reject) — the interaction budget is spent. The registry path drops
+        // + cleans + emits + onCapForget; do NOT also call caps.forget here (no double-forget).
+        await deps.registry.evict(sessionId, owner, "max_interactions");
+        throwToolError("permission_denied", "cap exceeded: max_interactions", {
+            hint: "this session spent its interaction budget (operator limits.maxInteractions) and was evicted",
+        });
+    }
+    const wcBreach = deps.caps.checkWallClock(sessionId);
+    if (wcBreach) {
+        deps.logger.warn({ toolName, sessionId, errorKind: "resource", step: "cap_breach", hint: "wall-clock budget exceeded — evicting" }, "terminal session wall-clock budget exceeded");
+        await deps.registry.evict(sessionId, owner, "wall_clock");
+        throwToolError("permission_denied", "cap exceeded: wall_clock", {
+            hint: "this session exceeded its wall-clock budget (operator limits.wallClockMs) and was evicted",
+        });
+    }
+}
+/**
+ * Emit the keystroke audit for one `send_*` INVOCATION. See the module doc.
+ * The raw `payload` NEVER reaches a log or the bus — only the scrubbed payload (LOG)
+ * and the redaction-safe summary (EVENT). `outcome` tags the attempt: `attempted`
+ * (passed the caps, forwarded) or `rejected` (a cap breach blocked the forward) —
+ * an ATTEMPT signal, never proof of delivery (the event doc spells this out).
+ */
+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;
+    // 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");
+    deps.eventBus.emit("terminal:keystroke", {
+        sessionId,
+        agentId: deps.agentId,
+        kind,
+        redactions,
+        byteLength: Buffer.byteLength(redactedText),
+        outcome,
+        timestamp: deps.nowMs(),
+    });
+}
+/**
+ * Enforce the per-session caps THEN audit the send — the single canonical order
+ * the two send tools call. EVERY invocation is audited exactly once:
+ *   - a cap breach → audit `outcome:"rejected"` (the redacted attempt is still
+ *     recorded — what the agent TRIED to type before it was rate-capped/evicted),
+ *     then the `enforceSendCaps` rejection re-propagates (the forward is skipped);
+ *   - no breach → audit `outcome:"attempted"`, then the caller forwards to the
+ *     registry.
+ * Auditing on the breach path is safe: `auditKeystroke` only LOGs the redacted form
+ * + emits the redaction-safe summary — it writes nothing to the PTY. Centralizing the
+ * try/audit/rethrow here (vs inlining it in both tools) keeps terminal-tools.ts lean.
+ */
+export async function enforceSendCapsThenAudit(deps, sessionId, owner, toolName, kind, payload) {
+    try {
+        await enforceSendCaps(deps, sessionId, owner, toolName);
+    }
+    catch (err) {
+        // A capped/evicted send is STILL audited (tagged rejected) before the
+        // typed permission_denied propagates — the attempt must not vanish from the trail.
+        auditKeystroke(deps, sessionId, toolName, kind, payload, "rejected");
+        // @allow-throw: re-propagate the enforceSendCaps rejection after recording the
+        // keystroke audit; the forward is intentionally skipped on a cap breach.
+        throw err;
+    }
+    auditKeystroke(deps, sessionId, toolName, kind, payload, "attempted");
+}
+/**
+ * The upper bound on a terminal dimension. A real terminal is never this
+ * wide/tall; the cap blocks an agent from inflating the worker's emulator buffer /
+ * PTY winsize with an absurd value. The schema types cols/rows as integers; this is
+ * the value-range guard the schema does not express.
+ */
+export const MAX_TERMINAL_DIMENSION = 10_000;
+/**
+ * Read + VALIDATE a terminal dimension (cols/rows) from agent params. The
+ * geometry is not a trust boundary, but the tool layer must not forward a degenerate
+ * value (0/negative/non-integer/absurd) into the worker's `Terminal({cols,rows})` /
+ * PTY winsize. Throws a typed `invalid_value` (never returns on a bad value) so the
+ * resize tool rejects BEFORE the registry forward. Lives here (not terminal-tools.ts)
+ * to keep that file under the 800-line architecture cap.
+ */
+export function readDimension(p, key) {
+    const v = p[key];
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 1 || v > MAX_TERMINAL_DIMENSION) {
+        throwToolError("invalid_value", `Invalid ${key}: must be an integer in 1..${MAX_TERMINAL_DIMENSION}.`, {
+            param: key,
+            hint: `pass a positive ${key} no larger than ${MAX_TERMINAL_DIMENSION}`,
+        });
+    }
+    return v;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * The origin key that scopes a terminal session's visibility (spec §2.1, §4.7).
+ *
+ * A `SessionOwner` is the pair `(agentId, sessionKey)`. The `sessionId` stays the
+ * opaque worker handle; OWNERSHIP — not the handle — is the authorization gate the
+ * registry filters `list`/`read`/`get`/`kill`/`send*` by. Two SUBAGENT runs of the
+ * same parent share an `agentId` but differ on `sessionKey` (a subagent's
+ * `channelId` is `"sub-agent:<uuid>"`, so `formatSessionKey()` yields a distinct
+ * string per run — `packages/core/src/domain/session-key.ts:78-79`), so they are
+ * 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
+ * registry stays under the 800-line architecture cap; the worker is owner-agnostic
+ * (it only knows `sessionId`).
+ *
+ * @module
+ */
+/** The origin key scoping a session's visibility — `(agentId, sessionKey)`. */
+export interface SessionOwner {
+    /** The owning agent id (the tool derives it from `tryGetContext().userId`, fallback `deps.agentId`). */
+    agentId: string;
+    /**
+     * The per-origin session key (the tool derives it from `tryGetContext().sessionKey`,
+     * fallback `""`). Distinguishes subagent runs of the same `agentId` (each subagent
+     * `channelId` is `"sub-agent:<uuid>"`), making sibling subagents mutually invisible.
+     */
+    sessionKey: string;
+}
+/**
+ * True iff two owners are the SAME origin — both `agentId` AND `sessionKey` match.
+ * The registry treats an owner mismatch EXACTLY as not-found (no information leak):
+ * a cross-owner read returns the empty minimal view, a cross-owner get returns
+ * `undefined`, and a cross-owner kill / send* is a no-op / degraded snapshot.
+ */
+export declare function sameOwner(a: SessionOwner, b: SessionOwner): boolean;

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

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The origin key that scopes a terminal session's visibility (spec §2.1, §4.7).
+ *
+ * A `SessionOwner` is the pair `(agentId, sessionKey)`. The `sessionId` stays the
+ * opaque worker handle; OWNERSHIP — not the handle — is the authorization gate the
+ * registry filters `list`/`read`/`get`/`kill`/`send*` by. Two SUBAGENT runs of the
+ * same parent share an `agentId` but differ on `sessionKey` (a subagent's
+ * `channelId` is `"sub-agent:<uuid>"`, so `formatSessionKey()` yields a distinct
+ * string per run — `packages/core/src/domain/session-key.ts:78-79`), so they are
+ * 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
+ * registry stays under the 800-line architecture cap; the worker is owner-agnostic
+ * (it only knows `sessionId`).
+ *
+ * @module
+ */
+/**
+ * True iff two owners are the SAME origin — both `agentId` AND `sessionKey` match.
+ * The registry treats an owner mismatch EXACTLY as not-found (no information leak):
+ * a cross-owner read returns the empty minimal view, a cross-owner get returns
+ * `undefined`, and a cross-owner kill / send* is a no-op / degraded snapshot.
+ */
+export function sameOwner(a, b) {
+    return a.agentId === b.agentId && a.sessionKey === b.sessionKey;
+}

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

@@ -0,0 +1,254 @@
+/**
+ * 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.
+ *
+ * WHY THIS EXISTS (the load-bearing DUR-01 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
+ * {@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}:
+ *   - `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.
+ *   - `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
+ *     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).
+ *
+ * Architecture invariants (binding — AGENTS.md / 124 house style; 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
+ *     is forbidden (it is allowed; this module simply needs no I/O).
+ *   - TOTAL / NEVER throws: a corrupt descriptor (165-01's `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.
+ *   - Infra-free: value-imports NOTHING but the sibling pure decision. {@link
+ *     SessionDescriptor} / {@link SessionHandle} / {@link SessionOwner} are TYPE-only.
+ *
+ * @module
+ */
+import { type SessionDescriptor } from "./terminal-reattach-match.js";
+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
+ * 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
+ * ENOENT-tolerant (a double-remove on a gone session is a no-op, never a throw).
+ */
+export interface SessionDescriptorStorePort {
+    /** Persist (or overwrite) the descriptor for a durable session. Best-effort; never throws. */
+    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`).
+     * The daemon impl swallows fs faults; this module ALSO defends a throwing impl.
+     */
+    recover(): SessionDescriptor[];
+    /** Remove a descriptor by sessionId. ENOENT-tolerant; never throws. */
+    remove(sessionId: string): void;
+}
+/**
+ * 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`.
+ *
+ * The `failed` arm carries the `owner` (NOT just the sessionId from 165-01's 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.
+ */
+export type RecoveredAction = {
+    action: "reattach";
+    descriptor: SessionDescriptor;
+} | {
+    action: "failed";
+    sessionId: string;
+    owner: SessionOwner;
+    reason: "tmux_session_gone";
+};
+/** 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). */
+    store: SessionDescriptorStorePort;
+    /** The `has-session` liveness probe (the worker's `has-session`), injected per 165-01. */
+    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).
+ *
+ * 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.
+ *   - `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).
+ *
+ * @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
+ * 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
+ * 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).
+ *
+ * `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
+ * the SURVIVING pane, so the original command string is neither needed nor re-spawned.
+ * `startedAt` is the descriptor's `createdAt` (the resumed session's wall-clock cap is
+ * measured from the ORIGINAL start, so a 40h cap is honored across the restart);
+ * `lastActivity` is stamped at recover-time (`nowMs`) so the reaper does not
+ * immediately idle-evict a freshly-recovered-but-quiet session.
+ *
+ * @param d - The recovered descriptor (durable + tmux-live, the `reattach` arm).
+ * @param nowMs - The recover-time clock (the registry's injected `nowMs()`).
+ */
+export declare function rehydrateHandleFromDescriptor(d: SessionDescriptor, nowMs: number): SessionHandle;
+/**
+ * DUR-01 / Q4 — 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).
+ * 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
+ * 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).
+ */
+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
+     *  so a restart re-attaches it from its OWN server while new sessions get a fresh per-boot one). */
+    tmuxSocket?: string;
+    allowId: string;
+    owner: SessionOwner;
+    cols: number;
+    rows: number;
+    createdAt: number;
+    scope?: SessionDescriptor["scope"];
+}
+/**
+ * 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
+ * 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
+ * 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)
+ * 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).
+ *   - `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).
+ */
+export interface TerminalDurabilityDeps {
+    descriptorStore?: SessionDescriptorStorePort;
+    isTmuxAlive?: (name: string, socket?: string) => boolean;
+    /**
+     * Deterministically terminate a DURABLE session's detached tmux by name (`tmux -S <socket>
+     * 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).
+     * Absent ⇒ no-op (the worker-IPC kill is the only teardown, today's behavior).
+     */
+    killTmuxSession?: (name: string, socket?: string) => void;
+    onReattached?: (info: {
+        sessionId: string;
+        agentId: string;
+    }) => void;
+    onUnrecoverable?: (info: {
+        sessionId: string;
+        agentId: string;
+        reason: string;
+        errorKind: string;
+    }) => void;
+}
+/**
+ * The minimal worker round-trip the recover-on-boot re-attach drives (BL-01, 165-REVIEW):
+ * 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
+ * onReattached at recover-time without a worker confirmation) — not used in production.
+ */
+export type ReattachWorkerFn = (sessionId: string, cols: number, rows: number, allowId: string, tmuxSocket?: string) => Promise<{
+    ok: boolean;
+}>;
+/**
+ * The DUR-01 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
+ * 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.
+ *
+ * @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.
+ *   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 declare function applyRecoveredSessions(deps: TerminalDurabilityDeps, sessions: Map<string, SessionHandle>, nowMs: () => number, reattachWorker?: ReattachWorkerFn): void;