comisai 1.0.42 → 1.0.45

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

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The pure NOTIFY-02 heartbeat line (design §4 Phase D; CONTEXT I3).
+ *
+ * `heartbeatLine(j)` builds the user-facing periodic progress one-liner for a PROMOTED
+ * (long) drive — `"still working — elapsed Xh, last activity <digest>, N interactions,
+ * ~$Y"` — assembled PURELY from the {@link DriveJournal}'s content-free fields
+ * (`elapsedMs`, `lastScreenDigest`, `interactions`, `costUsd`). This is NOTIFY-02's
+ * spam-free "the 40h drive is still alive" signal, distinct from LIVE-01's INTERNAL
+ * liveness tick (which is never a user message).
+ *
+ * CONTENT-FREE BY CONSTRUCTION (I3): the ONLY screen-derived text in the output is
+ * `lastScreenDigest`, which the woken-turn driver ALREADY ran through `scrubSecretsFromText`
+ * + bounded to `DIGEST_EXCERPT_MAX` before it landed on the journal (terminal-wake-turn.ts).
+ * This function FORMATS, it does NOT redact and NEVER re-expands or re-reads the screen —
+ * the same FORMAT-not-redact layer split `screenDigestLine` documents (terminal-read-digest.ts).
+ * Everything else in the line is structural (counts/durations/labels).
+ *
+ * Architecture invariants (binding — AGENTS.md / 124 house style, mirrors
+ * `terminal-read-digest.ts` `screenDigestLine` / `terminal-spend-ceiling.ts`):
+ *   - PURE: a free function, NOT a factory. NO clock/timer reads (`elapsedMs` is the
+ *     content-free number the CALLER derived from its own injected clock), NO module-global
+ *     mutable state, NO I/O.
+ *   - TOTAL / NEVER throws: a degenerate journal (NaN/negative/Infinity elapsedMs/
+ *     interactions/costUsd, or an empty digest) yields a SAFE string — never a "NaNh" or a
+ *     throw. The SAFE direction for an unreadable field is `0` / `"(no activity yet)"`.
+ *   - Infra-free: value-imports NOTHING at runtime + a type-only `DriveJournal` — no
+ *     platform runtime packages, no observability egress (the globals + infra-runtime-scope
+ *     gates; this file names none, and worker ↛ infra/observability).
+ *
+ * @module
+ */
+/** A non-finite/negative number coerced to the SAFE `0` (a degenerate journal never yields "NaNh"). */
+function safeNonNegative(n) {
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+/**
+ * The content-free NOTIFY-02 heartbeat one-liner for a promoted drive (I3).
+ *
+ * Pure + total: a degenerate journal yields a safe string (`0` hours/interactions/cost, an
+ * empty digest → `"(no activity yet)"`); never throws. The line is content-free BY
+ * CONSTRUCTION — counts/durations + the (already-redacted) `lastScreenDigest`, never raw TUI
+ * bytes (the digest is FORMATTED here, not redacted — that happened upstream).
+ *
+ * @param j - The content-free journal fields the line reads (a {@link DriveJournal} subset).
+ * @returns A single-line, content-free heartbeat string.
+ */
+export function heartbeatLine(j) {
+    const hours = (safeNonNegative(j.elapsedMs) / 3_600_000).toFixed(1);
+    // interactions is a count: a non-finite/negative value is degenerate → 0 (floor any fraction).
+    const interactions = Math.floor(safeNonNegative(j.interactions));
+    // costUsd is money: a non-finite/negative value is degenerate → 0; two-decimal money format.
+    const cost = safeNonNegative(j.costUsd).toFixed(2);
+    // The (already-redacted, already-bounded) digest, VERBATIM — never re-expanded (I3 layer split).
+    const activity = typeof j.lastScreenDigest === "string" && j.lastScreenDigest.length > 0
+        ? j.lastScreenDigest
+        : "(no activity yet)";
+    return `Terminal drive still working — elapsed ${hours}h, last activity ${activity}, ${interactions} interactions, ~$${cost}.`;
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Length-prefixed JSON IPC framing for the Terminal Worker boundary (spec §2.3).
+ *
+ * The worker and the daemon-side registry exchange JSON frames over a pipe.
+ * Each frame is `[uint32-BE body-length][utf8 JSON body]`. Requests correlate
+ * by `(sessionId, requestId)` — NEVER by arrival order (a busy session may
+ * reply out of order). A separate push channel carries `terminal:*` event
+ * frames; consumers route a decoded frame by the presence of `requestId`
+ * (request/reply) vs `event` (push). Each request frame carries `traceId` so
+ * the worker can re-establish the originating ALS context.
+ *
+ * Pure JS — no `node-pty` / `@comis/infra` import. The decoder holds its
+ * accumulation buffer in CLOSURE scope (no module-global mutable state, as
+ * enforced by the `globals.test.ts` architecture gate). No raw
+ * wall-clock or timer globals — this module is a pure transform.
+ *
+ * @module
+ */
+/** A request: daemon → worker. Carries the method + params and the trace context. */
+export interface TerminalRequestFrame {
+    sessionId: string;
+    requestId: string;
+    traceId: string;
+    method: string;
+    params: Record<string, unknown>;
+}
+/** A reply: worker → daemon. Correlates back to a request by `(sessionId,requestId)`. */
+export interface TerminalReplyFrame {
+    sessionId: string;
+    requestId: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+/** A push-channel event: worker → daemon. Has no `requestId` — it is unsolicited. */
+export interface TerminalEventFrame {
+    sessionId: string;
+    event: string;
+    payload: unknown;
+}
+/** The discriminated union of every frame shape on the IPC wire. */
+export type TerminalFrame = TerminalRequestFrame | TerminalReplyFrame | TerminalEventFrame;
+/**
+ * Hard ceiling on a single frame's declared body length.
+ *
+ * The length prefix is an attacker/garbage-controlled `uint32` (0 …
+ * 4 294 967 295). Without a ceiling, one corrupt/hostile prefix (e.g.
+ * `0xFFFFFFFF`) drives the streaming decoder to buffer every subsequent byte
+ * forever, waiting for a ~4 GiB body that never completes — an unbounded
+ * `Buffer.concat` growth (memory DoS) that also permanently desyncs the stream.
+ *
+ * 16 MiB is ample for the worker↔daemon traffic (a screen grid + JSON envelope
+ * is kilobytes; even a large scrollback dump is well under this). Anything
+ * larger is treated as corrupt/hostile: the decoder REFUSES to buffer toward it
+ * and throws {@link FrameTooLargeError} so the caller can drop the frame, log
+ * `errorKind:"validation"`, and — at the registry — treat the worker as corrupt
+ * and re-spawn it. The load-bearing property is the bound itself.
+ */
+export declare const MAX_FRAME_BYTES: number;
+/**
+ * Thrown by the decoder when a frame's declared body length exceeds
+ * {@link MAX_FRAME_BYTES}. Carries the offending `declaredBytes` and the
+ * `maxBytes` ceiling so the caller can log a precise `errorKind:"validation"`
+ * diagnostic and resync/re-spawn rather than grow the buffer toward a hostile
+ * length. A typed error (not a bare `Error`) so the registry's stdout handler
+ * can branch on `instanceof` if it ever needs frame-specific recovery.
+ */
+export declare class FrameTooLargeError extends Error {
+    readonly declaredBytes: number;
+    readonly maxBytes: number;
+    constructor(declaredBytes: number, maxBytes: number);
+}
+/**
+ * Encode a frame as `[uint32-BE body-length][utf8 JSON body]`.
+ *
+ * The length prefix lets the decoder reassemble a frame from arbitrary chunk
+ * boundaries on the underlying pipe (a single `write` is not a single `read`).
+ */
+export declare function encodeFrame(frame: TerminalFrame): Buffer;
+/**
+ * Decode all complete frames present in a single, fully-buffered input.
+ *
+ * Convenience for callers that already hold the whole buffer (e.g. tests, or a
+ * synchronous read of a complete message). For a streaming pipe use
+ * {@link createFrameDecoder}, which carries partial state across chunks.
+ */
+export declare function decodeFrames(buf: Buffer): TerminalFrame[];
+/**
+ * A stateful streaming decoder. Feed it raw chunks from a pipe via `push`; it
+ * returns the frames that became complete on that chunk (possibly zero, after
+ * appending to its CLOSURE-scoped accumulation buffer). A frame is emitted
+ * exactly once, only after its full body has arrived — never prematurely on a
+ * partial prefix/body, never twice.
+ */
+export declare function createFrameDecoder(): {
+    push(chunk: Buffer): TerminalFrame[];
+};
+/**
+ * The daemon-side reply router. Resolve a pending request by the
+ * `(sessionId,requestId)` key — independent of the order replies arrive in
+ * (the framing half of out-of-order correlation). Returns `true` if a pending
+ * resolver matched (and was invoked + removed), `false` for an orphan/duplicate
+ * reply with no waiter.
+ *
+ * The worker uses {@link encodeFrame}/{@link createFrameDecoder} symmetrically
+ * on its side; this helper is the correlation gate on the daemon side.
+ */
+export declare function correlate(pending: Map<string, (f: TerminalReplyFrame) => void>, frame: TerminalReplyFrame): boolean;

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

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Length-prefixed JSON IPC framing for the Terminal Worker boundary (spec §2.3).
+ *
+ * The worker and the daemon-side registry exchange JSON frames over a pipe.
+ * Each frame is `[uint32-BE body-length][utf8 JSON body]`. Requests correlate
+ * by `(sessionId, requestId)` — NEVER by arrival order (a busy session may
+ * reply out of order). A separate push channel carries `terminal:*` event
+ * frames; consumers route a decoded frame by the presence of `requestId`
+ * (request/reply) vs `event` (push). Each request frame carries `traceId` so
+ * the worker can re-establish the originating ALS context.
+ *
+ * Pure JS — no `node-pty` / `@comis/infra` import. The decoder holds its
+ * accumulation buffer in CLOSURE scope (no module-global mutable state, as
+ * enforced by the `globals.test.ts` architecture gate). No raw
+ * wall-clock or timer globals — this module is a pure transform.
+ *
+ * @module
+ */
+/** The 4-byte big-endian length prefix that precedes every JSON body. */
+const LENGTH_PREFIX_BYTES = 4;
+/**
+ * Hard ceiling on a single frame's declared body length.
+ *
+ * The length prefix is an attacker/garbage-controlled `uint32` (0 …
+ * 4 294 967 295). Without a ceiling, one corrupt/hostile prefix (e.g.
+ * `0xFFFFFFFF`) drives the streaming decoder to buffer every subsequent byte
+ * forever, waiting for a ~4 GiB body that never completes — an unbounded
+ * `Buffer.concat` growth (memory DoS) that also permanently desyncs the stream.
+ *
+ * 16 MiB is ample for the worker↔daemon traffic (a screen grid + JSON envelope
+ * is kilobytes; even a large scrollback dump is well under this). Anything
+ * larger is treated as corrupt/hostile: the decoder REFUSES to buffer toward it
+ * and throws {@link FrameTooLargeError} so the caller can drop the frame, log
+ * `errorKind:"validation"`, and — at the registry — treat the worker as corrupt
+ * and re-spawn it. The load-bearing property is the bound itself.
+ */
+export const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+/**
+ * Thrown by the decoder when a frame's declared body length exceeds
+ * {@link MAX_FRAME_BYTES}. Carries the offending `declaredBytes` and the
+ * `maxBytes` ceiling so the caller can log a precise `errorKind:"validation"`
+ * diagnostic and resync/re-spawn rather than grow the buffer toward a hostile
+ * length. A typed error (not a bare `Error`) so the registry's stdout handler
+ * can branch on `instanceof` if it ever needs frame-specific recovery.
+ */
+export class FrameTooLargeError extends Error {
+    declaredBytes;
+    maxBytes;
+    constructor(declaredBytes, maxBytes) {
+        super(`terminal IPC frame body length ${declaredBytes} exceeds the ${maxBytes}-byte cap (corrupt/hostile length prefix)`);
+        this.name = "FrameTooLargeError";
+        this.declaredBytes = declaredBytes;
+        this.maxBytes = maxBytes;
+    }
+}
+/**
+ * Encode a frame as `[uint32-BE body-length][utf8 JSON body]`.
+ *
+ * The length prefix lets the decoder reassemble a frame from arbitrary chunk
+ * boundaries on the underlying pipe (a single `write` is not a single `read`).
+ */
+export function encodeFrame(frame) {
+    const body = Buffer.from(JSON.stringify(frame), "utf8");
+    const len = Buffer.alloc(LENGTH_PREFIX_BYTES);
+    len.writeUInt32BE(body.length, 0);
+    return Buffer.concat([len, body]);
+}
+/**
+ * Decode all complete frames present in a single, fully-buffered input.
+ *
+ * Convenience for callers that already hold the whole buffer (e.g. tests, or a
+ * synchronous read of a complete message). For a streaming pipe use
+ * {@link createFrameDecoder}, which carries partial state across chunks.
+ */
+export function decodeFrames(buf) {
+    const decoder = createFrameDecoder();
+    return decoder.push(buf);
+}
+/**
+ * A stateful streaming decoder. Feed it raw chunks from a pipe via `push`; it
+ * returns the frames that became complete on that chunk (possibly zero, after
+ * appending to its CLOSURE-scoped accumulation buffer). A frame is emitted
+ * exactly once, only after its full body has arrived — never prematurely on a
+ * partial prefix/body, never twice.
+ */
+export function createFrameDecoder() {
+    // Closure-local accumulation buffer — NOT module scope (no module-global state).
+    let buffered = Buffer.alloc(0);
+    function push(chunk) {
+        if (chunk.length > 0) {
+            buffered = buffered.length === 0 ? chunk : Buffer.concat([buffered, chunk]);
+        }
+        const out = [];
+        // Drain every complete frame currently in the buffer.
+        for (;;) {
+            if (buffered.length < LENGTH_PREFIX_BYTES)
+                break; // not even a full length prefix yet
+            const bodyLen = buffered.readUInt32BE(0);
+            // Refuse a corrupt/hostile length before reserving toward it. Never
+            // grow `buffered` toward a multi-GiB body — that is the DoS primitive. The
+            // caller (registry stdout handler) catches this, drops the worker as
+            // corrupt, and re-spawns. The buffer is left intact (not consumed): a 2nd
+            // push re-reads the same oversized prefix and re-throws — it never silently
+            // accumulates the follow-on bytes.
+            //
+            // @allow-throw: the framer is a decode-protocol boundary — a typed decode
+            // error IS the contract here (symmetric with the built-in JSON.parse throw
+            // on the very next decode step). The sole caller (registry stdout 'data'
+            // handler) wraps decoder.push in try/catch, logs errorKind:
+            // "validation", and drops/re-spawns the worker; it never reaches
+            // uncaughtException. Returning a Result here would force every push() caller
+            // (incl. the tests' in-process bridge) to branch on a discriminated union on
+            // the hot decode path for a condition that only fires on corrupt/hostile
+            // input — the throw + single guarded catch is the cleaner boundary.
+            if (bodyLen > MAX_FRAME_BYTES) {
+                throw new FrameTooLargeError(bodyLen, MAX_FRAME_BYTES);
+            }
+            const frameEnd = LENGTH_PREFIX_BYTES + bodyLen;
+            if (buffered.length < frameEnd)
+                break; // body not fully arrived yet
+            const body = buffered.subarray(LENGTH_PREFIX_BYTES, frameEnd);
+            out.push(JSON.parse(body.toString("utf8")));
+            buffered = buffered.subarray(frameEnd); // consume the frame; keep any trailing bytes
+        }
+        return out;
+    }
+    return { push };
+}
+/**
+ * The daemon-side reply router. Resolve a pending request by the
+ * `(sessionId,requestId)` key — independent of the order replies arrive in
+ * (the framing half of out-of-order correlation). Returns `true` if a pending
+ * resolver matched (and was invoked + removed), `false` for an orphan/duplicate
+ * reply with no waiter.
+ *
+ * The worker uses {@link encodeFrame}/{@link createFrameDecoder} symmetrically
+ * on its side; this helper is the correlation gate on the daemon side.
+ */
+export function correlate(pending, frame) {
+    const key = `${frame.sessionId}:${frame.requestId}`;
+    const resolve = pending.get(key);
+    if (!resolve)
+        return false;
+    pending.delete(key);
+    resolve(frame);
+    return true;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * The pure named-key grammar (spec §5 send_key).
+ *
+ * Turns a `send_key` chord (`"C-c"`, `"Up"`, `"S-Tab"`, `"M-x"`) into the exact
+ * control/escape byte sequence a PTY consumes. This is a standalone,
+ * host-independent, fully unit-testable module with ZERO runtime dependencies —
+ * the worker imports it to encode the `send_key` frame.
+ *
+ * A wrong byte for a key is an invisible, load-bearing bug (the agent thinks it
+ * pressed Ctrl-C; the program sees garbage). The mapping is encoded once, here,
+ * with the exact-byte RED test asserting every sequence.
+ *
+ * Non-obvious sequences (xterm defaults):
+ *   - `S-Tab` = CSI Z (back-tab, `ESC [ Z`).
+ *   - `C-{a..z}` = `0x01..0x1a` (the ASCII control range: lowercased letter code
+ *     minus `0x60`); `C-[` = ESC (`0x1b`, the canonical ESC alias).
+ *   - `F1`-`F4` = SS3 (`ESC O P..S`); `F5`+ = `CSI n ~` (e.g. `ESC [ 15 ~`).
+ *   - `M-`/`A-` (Alt/Meta) prefixes ESC (`0x1b`) before the base key's bytes.
+ *
+ * Purity: no timers, no wall-clock, no env, no `@comis/infra`. The only runtime
+ * surface is `throwToolError("invalid_value", …)` for the unknown-key rejection
+ * — parity with the rest of the tool layer.
+ *
+ * @module
+ */
+/**
+ * Encode one named key (or chord component) to its byte sequence.
+ *
+ * Resolution order:
+ *   1. An exact entry in the literal table.
+ *   2. A control chord `C-<letter>` / `C-[` → the ASCII control byte
+ *      (`String.fromCharCode(lower - 0x60)`; `C-[` → ESC).
+ *   3. An Alt/Meta chord `M-<rest>` / `A-<rest>` → `ESC` + `encodeNamedKey(rest)`
+ *      (recurse so `M-Up`, `M-c`, `M-C-c` work; the remainder must itself resolve
+ *      to a known key or a single printable — a multi-char unknown remainder
+ *      throws, blocking arbitrary multi-byte sequence crafting).
+ *   4. A single printable ASCII char → itself.
+ *   5. Otherwise → a typed `invalid_value` rejection — NEVER a silent
+ *      empty-string no-op.
+ *
+ * @param key - The named key or chord component.
+ * @returns The exact byte string the PTY consumes.
+ * @throws via `throwToolError("invalid_value", …)` for an unrecognized key name.
+ */
+export declare function encodeNamedKey(key: string): string;
+/**
+ * Encode a `keys[]` chord array to the concatenation of each key's bytes, in
+ * array order (e.g. `["Up","Enter"]` → `"\x1b[A\r"`). An unknown key inside the
+ * array propagates the `invalid_value` throw.
+ *
+ * @param keys - The chord array from `SendKeyParams.keys`.
+ * @returns The concatenated byte string.
+ */
+export declare function encodeKeyChord(keys: string[]): string;

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

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The pure named-key grammar (spec §5 send_key).
+ *
+ * Turns a `send_key` chord (`"C-c"`, `"Up"`, `"S-Tab"`, `"M-x"`) into the exact
+ * control/escape byte sequence a PTY consumes. This is a standalone,
+ * host-independent, fully unit-testable module with ZERO runtime dependencies —
+ * the worker imports it to encode the `send_key` frame.
+ *
+ * A wrong byte for a key is an invisible, load-bearing bug (the agent thinks it
+ * pressed Ctrl-C; the program sees garbage). The mapping is encoded once, here,
+ * with the exact-byte RED test asserting every sequence.
+ *
+ * Non-obvious sequences (xterm defaults):
+ *   - `S-Tab` = CSI Z (back-tab, `ESC [ Z`).
+ *   - `C-{a..z}` = `0x01..0x1a` (the ASCII control range: lowercased letter code
+ *     minus `0x60`); `C-[` = ESC (`0x1b`, the canonical ESC alias).
+ *   - `F1`-`F4` = SS3 (`ESC O P..S`); `F5`+ = `CSI n ~` (e.g. `ESC [ 15 ~`).
+ *   - `M-`/`A-` (Alt/Meta) prefixes ESC (`0x1b`) before the base key's bytes.
+ *
+ * Purity: no timers, no wall-clock, no env, no `@comis/infra`. The only runtime
+ * surface is `throwToolError("invalid_value", …)` for the unknown-key rejection
+ * — parity with the rest of the tool layer.
+ *
+ * @module
+ */
+import { throwToolError } from "../../../platform-tools/tool-helpers.js";
+// ---------------------------------------------------------------------------
+// The literal named-key -> byte table (frozen const; no module-global mutable state)
+// ---------------------------------------------------------------------------
+/**
+ * Exact-case named keys mapped to their xterm-default byte string. A frozen
+ * literal const — there is no runtime mutation path (wrong bytes are caught by
+ * the exact-byte RED test, not a runtime threat).
+ */
+const NAMED_KEY_BYTES = Object.freeze({
+    // Literals.
+    Enter: "\r", // \x0d
+    Tab: "\t", // \x09
+    Escape: "\x1b",
+    Esc: "\x1b",
+    Backspace: "\x7f",
+    Space: " ", // \x20
+    // Arrows (CSI) + back-tab (CSI Z).
+    Up: "\x1b[A",
+    Down: "\x1b[B",
+    Right: "\x1b[C",
+    Left: "\x1b[D",
+    "S-Tab": "\x1b[Z",
+    // Navigation.
+    Home: "\x1b[H",
+    End: "\x1b[F",
+    PageUp: "\x1b[5~",
+    PageDown: "\x1b[6~",
+    Delete: "\x1b[3~",
+    Insert: "\x1b[2~",
+    // Function keys: F1-F4 = SS3 (ESC O P..S); F5+ = CSI n ~.
+    F1: "\x1bOP",
+    F2: "\x1bOQ",
+    F3: "\x1bOR",
+    F4: "\x1bOS",
+    F5: "\x1b[15~",
+    F6: "\x1b[17~",
+    F7: "\x1b[18~",
+    F8: "\x1b[19~",
+    F9: "\x1b[20~",
+    F10: "\x1b[21~",
+    F11: "\x1b[23~",
+    F12: "\x1b[24~",
+});
+// ---------------------------------------------------------------------------
+// Encoders
+// ---------------------------------------------------------------------------
+/** Matches a control chord `C-<letter>` or `C-[` (the ESC alias). */
+const CONTROL_RE = /^C-([a-zA-Z[])$/;
+/** Matches an Alt/Meta-prefixed chord `M-<rest>` or `A-<rest>` (rest is recursed). */
+const ALT_RE = /^(?:M|A)-(.+)$/;
+/** A single printable ASCII char (0x20..0x7e) — passes through verbatim. */
+function isSinglePrintable(key) {
+    if (key.length !== 1)
+        return false;
+    const code = key.charCodeAt(0);
+    return code >= 0x20 && code <= 0x7e;
+}
+/**
+ * Encode one named key (or chord component) to its byte sequence.
+ *
+ * Resolution order:
+ *   1. An exact entry in the literal table.
+ *   2. A control chord `C-<letter>` / `C-[` → the ASCII control byte
+ *      (`String.fromCharCode(lower - 0x60)`; `C-[` → ESC).
+ *   3. An Alt/Meta chord `M-<rest>` / `A-<rest>` → `ESC` + `encodeNamedKey(rest)`
+ *      (recurse so `M-Up`, `M-c`, `M-C-c` work; the remainder must itself resolve
+ *      to a known key or a single printable — a multi-char unknown remainder
+ *      throws, blocking arbitrary multi-byte sequence crafting).
+ *   4. A single printable ASCII char → itself.
+ *   5. Otherwise → a typed `invalid_value` rejection — NEVER a silent
+ *      empty-string no-op.
+ *
+ * @param key - The named key or chord component.
+ * @returns The exact byte string the PTY consumes.
+ * @throws via `throwToolError("invalid_value", …)` for an unrecognized key name.
+ */
+export function encodeNamedKey(key) {
+    const literal = NAMED_KEY_BYTES[key];
+    if (literal !== undefined)
+        return literal;
+    const control = CONTROL_RE.exec(key);
+    if (control !== null) {
+        const ch = control[1];
+        if (ch === "[")
+            return "\x1b"; // C-[ is the canonical ESC alias.
+        const lower = ch.toLowerCase();
+        return String.fromCharCode(lower.charCodeAt(0) - 0x60); // C-a..C-z -> 0x01..0x1a
+    }
+    const alt = ALT_RE.exec(key);
+    if (alt !== null) {
+        // Prefix ESC, then recurse on the remainder (which must itself resolve).
+        return "\x1b" + encodeNamedKey(alt[1]);
+    }
+    if (isSinglePrintable(key))
+        return key;
+    throwToolError("invalid_value", `unknown key name: ${key}`, {
+        hint: "use a named key (Up, C-c, S-Tab, F1...) or a single printable character",
+    });
+}
+/**
+ * Encode a `keys[]` chord array to the concatenation of each key's bytes, in
+ * array order (e.g. `["Up","Enter"]` → `"\x1b[A\r"`). An unknown key inside the
+ * array propagates the `invalid_value` throw.
+ *
+ * @param keys - The chord array from `SendKeyParams.keys`.
+ * @returns The concatenated byte string.
+ */
+export function encodeKeyChord(keys) {
+    return keys.map(encodeNamedKey).join("");
+}

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

@@ -0,0 +1,75 @@
+/**
+ * The normalized region-scoped loop/stuck guard (spec §4.6; SEC-11).
+ *
+ * `createLoopGuard({ nowMs, windowMs?, maxRepeats? })` detects an auto-answer loop on a
+ * RE-RENDERED prompt: the same *logical* prompt presented again is caught even when its
+ * bytes differ only by a volatile region (a spinner glyph, a timestamp, an
+ * elapsed/progress counter). `observe(sessionId, promptRegion)` normalizes the region
+ * (strip the volatile bits, collapse whitespace), hashes the stable remainder, tracks
+ * recent (hash, ts) per session in a window, and returns a typed
+ * `{ repeat: true, reason: "loop_detected" }` once a normalized hash recurs within the
+ * window — otherwise `{ repeat: false }`. The caller (124-09) escalates on a repeat
+ * (`terminal:escalated`, reason `loop_detected`).
+ *
+ * COMPOSES WITH (does NOT duplicate) the P4 `maxInteractions` cap (terminal-caps.ts):
+ * the cap EVICTs the session independently when its interaction budget is spent (via the
+ * single audited `registry.evict(..., "max_interactions")` path); this guard is the
+ * ADDITIVE detector that catches a tight re-render loop BEFORE the budget runs out, and
+ * escalates to a human rather than evicting. Two independent defenses, no shared state.
+ *
+ * Architecture invariants (binding — AGENTS.md / 124 house style, mirrors
+ * `terminal-caps.ts` / `terminal-ipc.ts`):
+ *   - NO module-global mutable state. The recent-hash ring is a CLOSURE-local
+ *     `Map<sessionId, RecentHash[]>` created inside the factory — two `createLoopGuard`
+ *     instances never share state, two sessionIds never share a ring.
+ *   - The injected `nowMs: () => number` is the ONLY clock source (no wall-clock global;
+ *     the `globals` architecture gate forbids it — production passes `systemNowMs`, tests
+ *     a fake clock). NO raw timer.
+ *   - NEVER throws: `observe` returns a typed discriminant; the caller acts on it. A
+ *     degenerate region hashes like any other (total).
+ *   - Infra-free: value-imports ONLY node builtins (`node:crypto` for the stable hash)
+ *     — no platform runtime packages, no observability egress (the infra-runtime-scope
+ *     architecture gate; this file names none of them).
+ *
+ * @module
+ */
+/** The dependencies + tunables. `nowMs` is required (injected clock); the rest default. */
+export interface LoopGuardDeps {
+    /** The injected wall-clock reader (epoch ms). Never a raw global. */
+    nowMs: () => number;
+    /**
+     * The sliding window in ms within which a recurring normalized hash counts as a loop.
+     * A sighting older than this decays out and never triggers a false repeat. Default 30s
+     * — long enough to catch a tight re-render loop, short enough that a legitimately
+     * re-visited prompt minutes later is not mistaken for a loop.
+     */
+    windowMs?: number;
+    /**
+     * How many PRIOR sightings of the same normalized hash (within the window) trip the
+     * repeat. Default 1: the SECOND time a logical prompt is seen within the window is a
+     * loop (the first primed the ring). Raising it tolerates N benign re-renders first.
+     */
+    maxRepeats?: number;
+}
+/** The loop guard's surface — exactly what the woken turn (124-09) consumes. */
+export interface LoopGuard {
+    /**
+     * Record a settled prompt region and report whether it is a (normalized) repeat
+     * within the window. Never throws, never sends. On a repeat the caller escalates
+     * (`terminal:escalated`, reason `loop_detected`).
+     */
+    observe(sessionId: string, promptRegion: string): {
+        repeat: boolean;
+        reason?: "loop_detected";
+    };
+    /** Clear a session's ring on kill/evict so the map never leaks and a re-used id is fresh. */
+    forget(sessionId: string): void;
+}
+/**
+ * Create a normalized region-scoped loop guard. All state is CLOSURE-local (no
+ * module-global); the injected `nowMs` is the only clock. `observe` never throws.
+ *
+ * @param deps - The injected clock + the optional window / repeat-count tunables.
+ * @returns The {@link LoopGuard} surface.
+ */
+export declare function createLoopGuard(deps: LoopGuardDeps): LoopGuard;