comisai 1.0.42 → 1.0.44

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

@@ -0,0 +1,80 @@
+/**
+ * The pure busy-vs-hung predicate (LIVE-01) — the single liveness/endurance signal
+ * the LIVE-01 backstop (165-07) and the ENDURE-01 reaper exclusion (165-08) both
+ * consume to unify on ONE definition of "still alive and making progress".
+ *
+ * `busyOrHung({ alive, noProgressMs, stuckMs })` answers ONE question over three
+ * content-free scalars: is this drive BUSY (legitimately working — recent progress,
+ * a CPU-busy / output-trickling compile) or HUNG (a dead backend, or genuinely idle
+ * with no transition past the stuck window)? It RE-EXPOSES the classifier's shipped
+ * stuck rule (`terminal-classifier.ts:281` — `noProgressMs > stuckMs`, by PROGRESS
+ * and NEVER by elapsed session wall-clock; OPS-04) as a free predicate, so:
+ *   - the backstop synthesizes a `stuck` `ClassifierState` (terminal-classifier.ts)
+ *     ONLY when this returns `"hung"` (never on a quiet-but-busy drive), and
+ *   - the reaper EXCLUDES a `"busy"` session from idle eviction — the load-bearing
+ *     fix for the documented pitfall that `lastActivity` does NOT advance for a
+ *     quiet, backgrounded compile (no tool round-trip lands), so a naive idle reaper
+ *     would evict a healthy 2h build.
+ *
+ * No new classifier state is invented (I8): this consumes the SAME progress kernel
+ * the classifier already uses; "busy"/"hung" are an internal verdict for the
+ * liveness/endurance layer, not a new session state.
+ *
+ * The doctrine encoded here is I9 — the worst outcome is a FALSE DEATH: a
+ * legitimately-busy long/quiet drive is NEVER declared hung. So the predicate biases
+ * to the SAFE direction on any uncertainty (a NaN / negative / non-finite
+ * `noProgressMs` is treated as recent progress ⇒ `"busy"`, keep waiting), and only an
+ * alive session whose finite `noProgressMs` STRICTLY exceeds `stuckMs` is `"hung"`.
+ *
+ * Architecture invariants (binding — AGENTS.md / 124 house style, mirrors
+ * `terminal-classifier.ts` / `terminal-dialog-detector.ts`):
+ *   - PURE: a free function, NOT a factory. NO clock/timer reads, NO module-global
+ *     mutable state, NO I/O. The caller passes the already-measured scalars.
+ *   - NO SCREEN (I2): the signature carries NO grid/cursor parameter and the module
+ *     imports nothing runtime — reading the rendered TUI per tick is structurally
+ *     impossible here (it consumes only `alive`/`noProgressMs`/`stuckMs`).
+ *   - NEVER throws: a degenerate input (NaN / negative / non-finite `noProgressMs`)
+ *     yields `"busy"` — the SAFE direction (never a false `"hung"`).
+ *   - Infra-free: value-imports NOTHING (no node builtins, no platform runtime
+ *     packages, no observability egress, no raw timer — the globals + infra-runtime
+ *     scope gates).
+ *
+ * @module
+ */
+/**
+ * The busy-vs-hung verdict the backstop + reaper consume.
+ *
+ * `"hung"` is the precondition the 165-07 backstop turns into a synthesized
+ * `ClassifierState` `"stuck"` (terminal-classifier.ts); `"busy"` is the keep-alive
+ * the 165-08 reaper uses to exclude a session from idle eviction.
+ */
+export type BusyVerdict = "busy" | "hung";
+/** The content-free inputs to {@link busyOrHung} — NO screen, NO cursor, NO clock. */
+export interface BusySignal {
+    /** Whether the backend (PTY/pipe/tmux) is still alive. `false` ⇒ `"hung"` (a dead
+     * backend — `tmux has-session` false — regardless of any timing). */
+    alive: boolean;
+    /** Milliseconds since the last observed screen change (the worker's
+     * `nowMs - lastProgressMs`, restamped on any diff). The SAME progress measure the
+     * classifier's `stuck` rule reads. */
+    noProgressMs: number;
+    /** The no-progress window past which a SETTLED drive is considered stuck (the
+     * classifier's `history.stuckMs`). Compared with a STRICT `>`. */
+    stuckMs: number;
+}
+/**
+ * Is this drive busy or hung? — LIVE-01.
+ *
+ * - A dead backend (`alive: false`) is `"hung"` regardless of timing.
+ * - A degenerate `noProgressMs` (NaN / negative / non-finite) biases to the SAFE
+ *   direction: `"busy"` (I9 — never a false death from a bad measurement).
+ * - Otherwise the SAME rule the classifier uses for `stuck`: a STRICT
+ *   `noProgressMs > stuckMs` is `"hung"`; recent progress (`<=`) is `"busy"`.
+ *
+ * Pure + total: reads no screen/clock, never throws.
+ *
+ * @param s - The content-free liveness signal ({@link BusySignal}).
+ * @returns `"busy"` if the drive is legitimately working, `"hung"` if it is dead or
+ *   genuinely idle past the stuck window.
+ */
+export declare function busyOrHung(s: BusySignal): BusyVerdict;

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

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The pure busy-vs-hung predicate (LIVE-01) — the single liveness/endurance signal
+ * the LIVE-01 backstop (165-07) and the ENDURE-01 reaper exclusion (165-08) both
+ * consume to unify on ONE definition of "still alive and making progress".
+ *
+ * `busyOrHung({ alive, noProgressMs, stuckMs })` answers ONE question over three
+ * content-free scalars: is this drive BUSY (legitimately working — recent progress,
+ * a CPU-busy / output-trickling compile) or HUNG (a dead backend, or genuinely idle
+ * with no transition past the stuck window)? It RE-EXPOSES the classifier's shipped
+ * stuck rule (`terminal-classifier.ts:281` — `noProgressMs > stuckMs`, by PROGRESS
+ * and NEVER by elapsed session wall-clock; OPS-04) as a free predicate, so:
+ *   - the backstop synthesizes a `stuck` `ClassifierState` (terminal-classifier.ts)
+ *     ONLY when this returns `"hung"` (never on a quiet-but-busy drive), and
+ *   - the reaper EXCLUDES a `"busy"` session from idle eviction — the load-bearing
+ *     fix for the documented pitfall that `lastActivity` does NOT advance for a
+ *     quiet, backgrounded compile (no tool round-trip lands), so a naive idle reaper
+ *     would evict a healthy 2h build.
+ *
+ * No new classifier state is invented (I8): this consumes the SAME progress kernel
+ * the classifier already uses; "busy"/"hung" are an internal verdict for the
+ * liveness/endurance layer, not a new session state.
+ *
+ * The doctrine encoded here is I9 — the worst outcome is a FALSE DEATH: a
+ * legitimately-busy long/quiet drive is NEVER declared hung. So the predicate biases
+ * to the SAFE direction on any uncertainty (a NaN / negative / non-finite
+ * `noProgressMs` is treated as recent progress ⇒ `"busy"`, keep waiting), and only an
+ * alive session whose finite `noProgressMs` STRICTLY exceeds `stuckMs` is `"hung"`.
+ *
+ * Architecture invariants (binding — AGENTS.md / 124 house style, mirrors
+ * `terminal-classifier.ts` / `terminal-dialog-detector.ts`):
+ *   - PURE: a free function, NOT a factory. NO clock/timer reads, NO module-global
+ *     mutable state, NO I/O. The caller passes the already-measured scalars.
+ *   - NO SCREEN (I2): the signature carries NO grid/cursor parameter and the module
+ *     imports nothing runtime — reading the rendered TUI per tick is structurally
+ *     impossible here (it consumes only `alive`/`noProgressMs`/`stuckMs`).
+ *   - NEVER throws: a degenerate input (NaN / negative / non-finite `noProgressMs`)
+ *     yields `"busy"` — the SAFE direction (never a false `"hung"`).
+ *   - Infra-free: value-imports NOTHING (no node builtins, no platform runtime
+ *     packages, no observability egress, no raw timer — the globals + infra-runtime
+ *     scope gates).
+ *
+ * @module
+ */
+/**
+ * Is this drive busy or hung? — LIVE-01.
+ *
+ * - A dead backend (`alive: false`) is `"hung"` regardless of timing.
+ * - A degenerate `noProgressMs` (NaN / negative / non-finite) biases to the SAFE
+ *   direction: `"busy"` (I9 — never a false death from a bad measurement).
+ * - Otherwise the SAME rule the classifier uses for `stuck`: a STRICT
+ *   `noProgressMs > stuckMs` is `"hung"`; recent progress (`<=`) is `"busy"`.
+ *
+ * Pure + total: reads no screen/clock, never throws.
+ *
+ * @param s - The content-free liveness signal ({@link BusySignal}).
+ * @returns `"busy"` if the drive is legitimately working, `"hung"` if it is dead or
+ *   genuinely idle past the stuck window.
+ */
+export function busyOrHung(s) {
+    // A dead backend is hung regardless of timing.
+    if (!s.alive)
+        return "hung";
+    // Bias to the SAFE direction (I9): a NaN / negative / non-finite measurement is
+    // treated as recent progress → busy. A bad clock must NEVER declare a healthy
+    // drive hung.
+    if (!Number.isFinite(s.noProgressMs) || s.noProgressMs < 0)
+        return "busy";
+    // The single load-bearing line — the SAME rule the classifier uses for `stuck`
+    // (terminal-classifier.ts:281). Strict `>`: AT the window the budget is not yet
+    // exceeded (mirrors checkWallClock), so recent progress (`<=`) is busy.
+    return s.noProgressMs > s.stuckMs ? "hung" : "busy";
+}

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

@@ -0,0 +1,84 @@
+/**
+ * Per-session usage caps for the terminal driver (spec §3.8, §4.6).
+ *
+ * `createSessionCaps(limits, nowMs)` is a pure, fully-injected primitive that enforces
+ * the per-entry operator caps from the closed config `limits`:
+ *
+ *   - `maxRequestsPerSession` — the entitlement-misuse control: bound how
+ *     many `send_*` calls a single session may make. A breach is the typed discriminant
+ *     `{ breach: "max_requests" }`; the tool layer maps it to a typed
+ *     `throwToolError` REJECT and the session SURVIVES (read/list/other sends still work).
+ *   - `maxInteractions` — the interaction budget. A breach
+ *     (`{ breach: "max_interactions" }`) drives an EVICT at the send_* tool layer
+ *     (`registry.evict(..., "max_interactions")`).
+ *   - `wallClockMs` — the wall-clock age budget. A breach
+ *     (`{ breach: "wall_clock" }`) drives an EVICT (the reaper sweep + the per-send
+ *     immediate guard route through the same eviction path).
+ *
+ * Design invariants (binding — AGENTS.md):
+ *   - NO module-global mutable state. ALL counters live in a CLOSURE-local
+ *     `Map<sessionId, CapState>` created inside the factory — two `createSessionCaps`
+ *     instances never share state, and two sessionIds never share a counter.
+ *   - The injected `nowMs: () => number` is the ONLY clock source — there is no raw
+ *     wall-clock global here (the `globals` architecture gate forbids it; the reaper/tool
+ *     pass `systemNowMs` in production and a fake clock in tests).
+ *   - This module NEVER throws and NEVER evicts. It returns a cap-state decision; the
+ *     tool/registry layer acts on it (REJECT vs EVICT per the EVICT-vs-REJECT split).
+ *   - Dependency-light: node + `@comis/core` type-only imports at most — NEVER
+ *     `@comis/infra` or `@comis/observability` (worker ↛ infra/observability).
+ *
+ * The structural `SessionLimits` shape mirrors the closed config
+ * `TerminalAllowEntrySchema.limits` (packages/core/src/config/schema-skills.ts) WITHOUT
+ * importing zod or the config module — this is a self-contained pure primitive (like
+ * the allowlist matcher), so it takes the limits shape structurally.
+ *
+ * Analog: packages/agent/src/background/background-task-manager.ts (closure-local counter
+ * Map + cap predicate + injected clock).
+ *
+ * @module
+ */
+/** A typed cap-breach discriminant. The tool/registry layer maps each to a reject/evict. */
+export type CapBreach = "max_requests" | "max_interactions" | "wall_clock";
+/**
+ * The per-entry limits shape this module enforces — a STRUCTURAL mirror of the closed
+ * config `limits` (schema-skills.ts). All fields optional; an undefined field ⇒ no cap.
+ * `maxSessions` is consumed by the reaper, not by the per-session caps.
+ */
+export interface SessionLimits {
+    maxSessions?: number;
+    /** Max `send_*` requests per session (REJECT on breach; session survives). */
+    maxRequestsPerSession?: number;
+    /** Max wall-clock age in ms (EVICT on breach). */
+    wallClockMs?: number;
+    /** Max interactions per session (EVICT on breach). */
+    maxInteractions?: number;
+}
+/** The injected wall-clock reader (epoch ms). Never a raw global. */
+export type NowMs = () => number;
+/** The cap primitive's surface — exactly what the tool layer consumes. */
+export interface SessionCaps {
+    /**
+     * Capture the session's wall-clock start. Idempotent — a re-call does NOT re-anchor
+     * `startedAtMs` (so a long-lived session cannot dodge the wall-clock cap by re-calling).
+     */
+    startSession(sessionId: string): void;
+    /** Returns `{ breach: "max_requests" }` on the Nth+1 request; increments only on ok. */
+    consumeRequest(sessionId: string): {
+        breach: CapBreach;
+    } | undefined;
+    /** Returns `{ breach: "max_interactions" }` on the Nth+1 interaction; increments only on ok. */
+    consumeInteraction(sessionId: string): {
+        breach: CapBreach;
+    } | undefined;
+    /** Returns `{ breach: "wall_clock" }` once `nowMs() - startedAtMs` EXCEEDS the cap. */
+    checkWallClock(sessionId: string): {
+        breach: CapBreach;
+    } | undefined;
+    /** Clear a session's counters on kill/evict so the map never leaks and a re-used id is fresh. */
+    forget(sessionId: string): void;
+}
+/**
+ * Create a per-session cap enforcer. All state is CLOSURE-local (no module-global); the
+ * injected `nowMs` is the only clock. The returned object's methods never throw.
+ */
+export declare function createSessionCaps(limits: SessionLimits | undefined, nowMs: NowMs): SessionCaps;

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

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Per-session usage caps for the terminal driver (spec §3.8, §4.6).
+ *
+ * `createSessionCaps(limits, nowMs)` is a pure, fully-injected primitive that enforces
+ * the per-entry operator caps from the closed config `limits`:
+ *
+ *   - `maxRequestsPerSession` — the entitlement-misuse control: bound how
+ *     many `send_*` calls a single session may make. A breach is the typed discriminant
+ *     `{ breach: "max_requests" }`; the tool layer maps it to a typed
+ *     `throwToolError` REJECT and the session SURVIVES (read/list/other sends still work).
+ *   - `maxInteractions` — the interaction budget. A breach
+ *     (`{ breach: "max_interactions" }`) drives an EVICT at the send_* tool layer
+ *     (`registry.evict(..., "max_interactions")`).
+ *   - `wallClockMs` — the wall-clock age budget. A breach
+ *     (`{ breach: "wall_clock" }`) drives an EVICT (the reaper sweep + the per-send
+ *     immediate guard route through the same eviction path).
+ *
+ * Design invariants (binding — AGENTS.md):
+ *   - NO module-global mutable state. ALL counters live in a CLOSURE-local
+ *     `Map<sessionId, CapState>` created inside the factory — two `createSessionCaps`
+ *     instances never share state, and two sessionIds never share a counter.
+ *   - The injected `nowMs: () => number` is the ONLY clock source — there is no raw
+ *     wall-clock global here (the `globals` architecture gate forbids it; the reaper/tool
+ *     pass `systemNowMs` in production and a fake clock in tests).
+ *   - This module NEVER throws and NEVER evicts. It returns a cap-state decision; the
+ *     tool/registry layer acts on it (REJECT vs EVICT per the EVICT-vs-REJECT split).
+ *   - Dependency-light: node + `@comis/core` type-only imports at most — NEVER
+ *     `@comis/infra` or `@comis/observability` (worker ↛ infra/observability).
+ *
+ * The structural `SessionLimits` shape mirrors the closed config
+ * `TerminalAllowEntrySchema.limits` (packages/core/src/config/schema-skills.ts) WITHOUT
+ * importing zod or the config module — this is a self-contained pure primitive (like
+ * the allowlist matcher), so it takes the limits shape structurally.
+ *
+ * Analog: packages/agent/src/background/background-task-manager.ts (closure-local counter
+ * Map + cap predicate + injected clock).
+ *
+ * @module
+ */
+/**
+ * Create a per-session cap enforcer. All state is CLOSURE-local (no module-global); the
+ * injected `nowMs` is the only clock. The returned object's methods never throw.
+ */
+export function createSessionCaps(limits, nowMs) {
+    // Closure-local — NOT module scope (no module-global mutable state). One CapState per
+    // sessionId; two distinct createSessionCaps instances each get their own Map.
+    const state = new Map();
+    /** Get-or-create the session's counter record, anchoring startedAt at first touch. */
+    function ensure(sessionId) {
+        let entry = state.get(sessionId);
+        if (entry === undefined) {
+            entry = { requests: 0, interactions: 0, startedAtMs: nowMs() };
+            state.set(sessionId, entry);
+        }
+        return entry;
+    }
+    return {
+        startSession(sessionId) {
+            // Idempotent: only anchor startedAt if the session is not already tracked, so a
+            // re-call never resets the wall clock.
+            if (!state.has(sessionId)) {
+                state.set(sessionId, {
+                    requests: 0,
+                    interactions: 0,
+                    startedAtMs: nowMs(),
+                });
+            }
+        },
+        consumeRequest(sessionId) {
+            const cap = limits?.maxRequestsPerSession;
+            const entry = ensure(sessionId);
+            // Check the cap FIRST; do NOT increment on a breach (the counter never leaks an
+            // extra allowance — a re-check keeps breaching).
+            if (cap !== undefined && entry.requests >= cap) {
+                return { breach: "max_requests" };
+            }
+            entry.requests += 1;
+            return undefined;
+        },
+        consumeInteraction(sessionId) {
+            const cap = limits?.maxInteractions;
+            const entry = ensure(sessionId);
+            if (cap !== undefined && entry.interactions >= cap) {
+                return { breach: "max_interactions" };
+            }
+            entry.interactions += 1;
+            return undefined;
+        },
+        checkWallClock(sessionId) {
+            const cap = limits?.wallClockMs;
+            if (cap === undefined) {
+                return undefined;
+            }
+            // Anchor startedAt on first touch so a checkWallClock before startSession does not
+            // spuriously breach (elapsed against `now` itself is 0).
+            const entry = ensure(sessionId);
+            // Strict `>`: at the exact cap boundary the budget is not yet spent.
+            if (nowMs() - entry.startedAtMs > cap) {
+                return { breach: "wall_clock" };
+            }
+            return undefined;
+        },
+        forget(sessionId) {
+            // No-op for an unknown id (never throws).
+            state.delete(sessionId);
+        },
+    };
+}

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

@@ -0,0 +1,176 @@
+/**
+ * The pure terminal state classifier (spec §4.3, the #1 milestone de-risk).
+ *
+ * `classifyFrame(frame, history)` labels a SETTLED frame
+ * `working | awaiting-input | exited | stuck` deterministically, from the render
+ * snapshot (grid + REAL cursor) + a caller-supplied progress history. It is the
+ * perception the worker (124-05/06) drives and the `session_status` tool surfaces.
+ *
+ * The §4.3 decision tree (in priority order):
+ *   1. `!alive`            → `exited`         (PTY exit — nothing more can render)
+ *   2. `!settled`          → `working`        (output still flowing / cursor advancing)
+ *   3. settled + diff∅ + CURSOR PARKED        → `awaiting-input`  (a real prompt, `high`)
+ *   3b. settled + diff∅ + DIALOG STRUCTURE    → `awaiting-input`  (CLASS-01 — a full-
+ *                                              screen dialog whose cursor sits on a blank
+ *                                              input line BELOW the prompt block, so the
+ *                                              parked gate missed it; `medium`,
+ *                                              `dialog_detected`)
+ *   4. settled + no-progress > stuckMs:
+ *        4a. + a DIALOG/PROMPT affordance (regardless of diff∅) → `awaiting-input` (LIVE-02 —
+ *            a settled prompt the STALE backgrounded-drive anchor mis-diffed as changing, so
+ *            diff∅ was false and 3/3b were skipped; `medium`, `dialog_detected`)
+ *        4b. else                                               → `stuck`  (by PROGRESS, OPS-04)
+ *   5. else                → `working`        (settled but cursor NOT parked = a
+ *                                              thinking/tool-use pause)
+ *
+ * The LOAD-BEARING gate (spec §4.3 risk table, severity HIGH): {@link isCursorParked}.
+ * During generation an AI CLI renders output mid-screen — the cursor is NOT in the
+ * input box, so a thinking/tool-use pause is read as `working`, NEVER as
+ * `awaiting-input`. A false `awaiting-input` would wake a turn that fires a spurious
+ * keystroke into a still-generating CLI. The classifier therefore biases to the SAFE
+ * direction: when in doubt (settled but unparked), it stays `working`. The structural
+ * gate (cursor position relative to the rendered content) is primary; the optional
+ * operator `hintPatterns` are a positive REINFORCEMENT only — they never OVERRIDE the
+ * structure, so a prompt-injecting CLI cannot render a fake "(y/n)" mid-screen and be
+ * read as a prompt (T-124-06).
+ *
+ * Architecture invariants (binding — AGENTS.md / 124 house style, mirrors
+ * `terminal-caps.ts`):
+ *   - PURE: a free function, NOT a factory. NO clock/timer reads (the debounce
+ *     timing lives in the settle the worker drives; the classifier receives an
+ *     already-`settled` flag + a caller-computed `noProgressMs`). NO module-global
+ *     mutable state.
+ *   - NEVER throws: returns a typed {@link Classification}; the worker/tool layer
+ *     acts on it. A degenerate frame yields a `working` default (the safe direction).
+ *   - Infra-free: value-imports ONLY node builtins + (type-only) `EmulatorSnapshot`
+ *     from `terminal-render.js` — no platform runtime packages, no observability
+ *     egress, no raw timer (the globals + infra-runtime-scope architecture gates).
+ *
+ * Determinism: a pure function of its inputs ⇒ the Task-3 fixture corpus pins it
+ * (a `claude` version bump that shifts a render is caught as a failing corpus case,
+ * spec §10.4).
+ *
+ * @module
+ */
+import type { EmulatorSnapshot } from "./terminal-render.js";
+import type { PlatformPerception } from "./platforms/index.js";
+/** The four mutually-exclusive session states (spec §4.3). */
+export type ClassifierState = "working" | "awaiting-input" | "exited" | "stuck";
+/**
+ * The frame the classifier reads — composes the render {@link EmulatorSnapshot}
+ * (grid + real cursor) with the worker-computed settle/diff signals. The worker
+ * builds this each settled frame; the classifier never touches the emulator or a
+ * clock directly.
+ */
+export interface ClassifierFrame {
+    /** Whether the backend (PTY/pipe/tmux) is still alive. `false` ⇒ `exited`. */
+    alive: boolean;
+    /**
+     * Whether the output has SETTLED (the adaptive N-stable-window settle resolved
+     * idle; see `terminal-settle.ts`). `false` ⇒ `working` (output still flowing).
+     */
+    settled: boolean;
+    /**
+     * Whether the screen-diff vs the previous read is empty (nothing changed). A
+     * prerequisite for `awaiting-input` — a changing screen is `working`. From
+     * `diffSnapshot(prev, next).changed === false`.
+     */
+    diffEmpty: boolean;
+    /** The rendered grid + REAL cursor the cursor-parked gate reads. */
+    snapshot: EmulatorSnapshot;
+    /**
+     * OPTIONAL operator-configured prompt cues (e.g. `"❯"`, `"(y/n)"`). A positive
+     * REINFORCEMENT for the parked gate only — never a hardcoded or screen-derived
+     * trust signal, and never enough to OVERRIDE the structural cursor-position test
+     * (T-124-06). Absent ⇒ the gate is purely structural.
+     */
+    hintPatterns?: readonly string[];
+    /**
+     * OPTIONAL selected-platform perception (the `TerminalPlatformProfile.perception` for the
+     * session's operator-declared allowId, fed by the worker — v2.26 CLASSIFY-01). The classifier
+     * stays the SOLE owner of `activity` (D4): these patterns FEED the generic decision —
+     * `workingLine` biases a settled-unparked frame WITH recent progress to `working` (the Codex
+     * `Working (Ns)` / Claude spinner case); `menuOrPicker` + `promptAffordance` feed the structural
+     * dialog detector (the D5 v2.11 menu fix + LIVE-02 idle-`❯`). `turnEnd` is populated but reserved
+     * for the §6-v2 structured-perception layer (NOT routed into the activity decision — it would
+     * over-fire on Claude's per-tool-action `⏺` bullet). Absent ⇒ the purely generic path,
+     * byte-identical to today (INV-1).
+     */
+    perception?: PlatformPerception;
+    /**
+     * OPTIONAL selected-platform dialog `detect` patterns (`profile.dialogs[].detect`, v2.26
+     * DIALOG-01) — the trust-gate / permission-prompt / approval-overlay signatures. The dialog
+     * detector consumes these as awaiting-input cues (a profile dialog IS awaiting-input), additive
+     * to the generic structural detection. Absent ⇒ the generic path (INV-1). Detection only; the
+     * safe-only auto-answer (`decideAutoAnswer`) makes the keystroke decision downstream.
+     */
+    dialogDetects?: readonly RegExp[];
+}
+/**
+ * The progress history the caller supplies (the classifier is pure — it does NOT
+ * read a clock). `noProgressMs` is how long the screen has shown no progress
+ * (output/cursor/diff), measured by the worker against its injected clock; `stuckMs`
+ * is the operator's stuck threshold (OPS-04). Stuck is by PROGRESS, never elapsed
+ * wall-clock of the session.
+ */
+export interface FrameHistory {
+    /** Milliseconds since the last observed progress (output/cursor/diff change). */
+    noProgressMs: number;
+    /** The operator stuck threshold in ms (`worker.stuckMs`). */
+    stuckMs: number;
+}
+/** The classifier verdict — a typed discriminant; the worker/tool layer acts on it. */
+export interface Classification {
+    /** The labelled state. */
+    state: ClassifierState;
+    /** Confidence in the label (`high` for the structural certainties, `medium` for the heuristics). */
+    confidence: "high" | "medium";
+    /** A stable machine-readable reason tag (for logs/events; never screen text). */
+    reason: string;
+}
+/**
+ * Is the cursor PARKED at a plausible input position? — the #1-de-risk gate.
+ *
+ * Parked iff ALL hold:
+ *   - the screen has at least one non-blank row (there is content to prompt at), AND
+ *   - the cursor sits at or just above the LAST non-blank row
+ *     (`cursor.y >= lastNonBlankRow - PARK_ROW_TOLERANCE`) — i.e. at the bottom of
+ *     the rendered content where a prompt lives, NOT mid-screen with output streaming
+ *     below it (the thinking-pause shape), AND
+ *   - the cursor's own line is non-blank (a prompt has text), OR an operator
+ *     `hintPattern` matches that line, AND
+ *   - the cursor column is plausible (at or just past the cursor line's content —
+ *     where one would type, not stranded far out in blank space), AND
+ *   - on a short screen where the lower-bound thinking-pause check is vacuous
+ *     (`lastNonBlankRow <= PARK_ROW_TOLERANCE`), a cursor sitting ABOVE the last
+ *     non-blank row (content still below it) parks ONLY if an operator `hintPattern`
+ *     matches — closing the no-op hole where a tiny mid-generation frame would
+ *     otherwise spuriously park (WR-04). A cursor genuinely at the bottom row is fine.
+ *
+ * `hintPatterns` can only REINFORCE the line-has-text leg; they cannot satisfy the
+ * row/column structure on their own, so a fake mid-screen "(y/n)" is rejected.
+ *
+ * Pure + total: any out-of-range cursor or empty grid yields `false` (the safe
+ * direction — not parked ⇒ never `awaiting-input`). Never throws.
+ *
+ * @param cursor - The real `{x,y}` cursor (0-based; `EmulatorSnapshot.cursor`).
+ * @param screen - The rendered grid text (newline-separated rows).
+ * @param _cols - The grid width (reserved; the predicate keys on content + cursor).
+ * @param _rows - The grid height (reserved).
+ * @param hintPatterns - Optional operator prompt cues (reinforcement only).
+ * @returns `true` iff the cursor is parked at a plausible prompt position.
+ */
+export declare function isCursorParked(cursor: {
+    x: number;
+    y: number;
+}, screen: string, _cols: number, _rows: number, hintPatterns?: readonly string[]): boolean;
+/**
+ * Classify a frame into `working | awaiting-input | exited | stuck` per the spec
+ * §4.3 decision tree. Pure, total, never throws — biases to the SAFE direction
+ * (`working`) whenever the prompt structure is not unambiguous.
+ *
+ * @param frame - The settle/diff signals + the render snapshot.
+ * @param history - The caller-computed progress history (no clock read inside).
+ * @returns The typed {@link Classification}.
+ */
+export declare function classifyFrame(frame: ClassifierFrame, history: FrameHistory): Classification;