@lucascouts/claude-agent-tui 0.1.0

package/dist/engine-lifecycle.js

@@ -0,0 +1,236 @@
+// === §2/§5 MOTOR box — managed lifecycle around the story 013 PTY engine (story 014) ===
+//
+// Story 013 spawns the interactive `claude` TUI in a real PTY with a sanitized, subscription
+// -billing environment, and RETURNS the handle for someone else to manage. This module is
+// that someone: it makes the PTY a *managed* process for the lifetime of an ACP session.
+//
+// Per the §2 process model a single Node process hosts BOTH the PTY and the JSONL watcher for
+// each session — there is no out-of-process supervisor. Per the §2 ordering rule the JSONL
+// tail (story 015's watcher) is the single source of truth for session state; `p.onData` is a
+// cosmetic live-mirror only (story 034) and MUST NOT drive state transitions.
+//
+// Spec is PINNED by IMPLEMENTACAO-FORK-ACP.md §5 (Lifecycle/resume):
+//   `p.onExit(({exitCode,signal}) => cleanup)` · `p.resize(cols,rows)` with debounce ·
+//   Cancel `p.write('\x03')`/`p.write('\x1b')`/`p.kill()` · Resume `bash -c 'claude --resume
+//   "<id>" || claude'`.
+//
+// Degrau-1 stays READ-ONLY: the cancel primitives are EXPOSED but not wired to any ACP
+// `session/cancel` handler here (that is story 030). This module imports NO SDK.
+//
+// Scope grows task-by-task in this story: Task 1 owns onExit→cleanup (this commit); the
+// debounced resize, the cancel primitives, the robust resume, and the single-process binding
+// land in Tasks 2–5.
+import pty from "node-pty";
+import { assertSpawnEnvUntainted, buildSanitizedEnv, resolveShell, spawnClaudePty, } from "./engine-pty.js";
+import { attachAnsiMirror } from "./ansi-mirror.js";
+/**
+ * Default PTY geometry applied when Zed supplies no terminal size (§5 Spawn defaults). Mirrors
+ * the story 013 spawn dimensions so a no-size resize matches a freshly-spawned PTY.
+ */
+export const DEFAULT_COLS = 120;
+export const DEFAULT_ROWS = 40;
+/**
+ * Resize debounce window (ms). Rapid resize requests (e.g. a window drag) are coalesced and
+ * only the last size is applied after this window elapses, so the TUI is not thrashed (§5).
+ */
+export const RESIZE_DEBOUNCE_MS = 100;
+/**
+ * Per-session managed engine: ONE Node process owns the PTY (§2). Task 1 wires the PTY's
+ * `onExit` to a single, idempotent `cleanup` that tears down the watcher and releases the
+ * per-session connection state exactly once (R1.1–R1.3).
+ *
+ * `onExit` is only ONE of the possible teardown triggers — an explicit kill (Task 3) routes
+ * through the same `cleanup`, so the per-session `disposed` guard makes the second trigger a
+ * no-op rather than double-freeing the watcher/session-map handles.
+ */
+export class SessionEngine {
+    constructor(opts) {
+        this.disposed = false;
+        this.sessionId = opts.handle.sessionId;
+        this.pty = opts.handle.pty;
+        this.watcher = opts.watcher;
+        this.sessions = opts.sessions;
+        this.onCleanup = opts.onCleanup;
+        this.setTimeoutFn = opts.setTimeoutFn ?? setTimeout;
+        this.clearTimeoutFn = opts.clearTimeoutFn ?? clearTimeout;
+        this.debounceMs = opts.resizeDebounceMs ?? RESIZE_DEBOUNCE_MS;
+        this.sessions?.set(this.sessionId, this);
+        // §5: process exit tears the session down. onExit is NOT assumed to be the only teardown
+        // trigger (an explicit kill also calls cleanup) — idempotency is enforced in cleanup().
+        this.pty.onExit(({ exitCode, signal }) => this.cleanup({ exitCode, signal }));
+        // Story 035: OPTIONAL cosmetic live ANSI mirror (§5). attachAnsiMirror is a no-op that does NOT
+        // touch `p.onData` when the flag is OFF (the default) — so the OFF path is byte-for-byte the
+        // read-only Degrau-1 behaviour (no listener attached). When ON it returns the tap's IDisposable.
+        // The mirror is cosmetic and one-way: it never drives session state (§2 — structure comes only
+        // from the JSONL tail). UNWIRED §7: no `content_block_delta`→`SessionUpdate` path is layered here.
+        this.ansiMirror = attachAnsiMirror(this.pty, opts.ansiMirror);
+    }
+    /**
+     * Debounced terminal resize (R2.1–R2.3). Stores the latest (cols, rows) and (re)arms a short
+     * debounce timer; when it fires, applies ONLY the last size via `p.resize`. Falls back to the
+     * 120×40 default when no size is supplied. A resize requested after the PTY has exited is
+     * dropped without throwing (the `disposed` guard) rather than writing to a dead handle.
+     */
+    requestResize(cols = DEFAULT_COLS, rows = DEFAULT_ROWS) {
+        if (this.disposed)
+            return; // drop post-exit resize, no throw (R2.3)
+        this.pendingSize = { cols, rows };
+        if (this.resizeTimer !== undefined)
+            this.clearTimeoutFn(this.resizeTimer);
+        this.resizeTimer = this.setTimeoutFn(() => {
+            this.resizeTimer = undefined;
+            if (this.disposed || !this.pendingSize)
+                return;
+            const { cols: c, rows: r } = this.pendingSize;
+            this.pendingSize = undefined;
+            this.pty.resize(c, r);
+        }, this.debounceMs);
+    }
+    /**
+     * Ctrl+C — write the interrupt byte `\x03` to the PTY to cancel the current turn (R3.1).
+     * No-op after the PTY has exited (R3.4) rather than writing to a dead handle.
+     *
+     * EXPOSED but deliberately NOT wired to any ACP `session/cancel` handler here — the Degrau-1
+     * path is read-only; the `session/cancel`→Ctrl+C wiring is story 030.
+     */
+    interrupt() {
+        if (this.disposed)
+            return;
+        this.pty.write("\x03");
+    }
+    /** Esc — write the escape byte `\x1b` to the PTY (R3.2). No-op after exit (R3.4). */
+    escape() {
+        if (this.disposed)
+            return;
+        this.pty.write("\x1b");
+    }
+    /**
+     * Kill the PTY process (R3.3). No-op after exit (R3.4). In production the subsequent `onExit`
+     * routes through the idempotent {@link cleanup}, so no explicit teardown call is needed here.
+     */
+    kill() {
+        if (this.disposed)
+            return;
+        this.pty.kill();
+    }
+    /**
+     * Idempotent teardown (R1.1–R1.3): runs the body exactly once per session. Clears any armed
+     * resize timer, stops the watcher, releases the session-map entry, and fires the diagnostics
+     * hook. A second call (e.g. explicit kill followed by `onExit`) is a no-op — it leaves no
+     * residual timer, watcher subscription, or session-map entry to free again.
+     */
+    cleanup(info) {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Story 028 (sub-task 3.1): cancel the BACKGROUND fresh-path discovery poll (the unbounded
+        // `watchdogMs: Infinity` glob loop whose AbortController 2.1 stored via setPendingDiscovery).
+        // A session torn down before its first interaction never produced a transcript, so abort the
+        // dangling poll here — BEFORE stopping the watcher — so it leaks no poll. No-op when no
+        // discovery was pending (a resumed session, or one already past discovery: optional chaining).
+        // Idempotent via the `disposed` guard above.
+        this.pendingDiscovery?.abort();
+        this.pendingDiscovery = undefined;
+        // Story 035: detach the cosmetic live ANSI mirror's `p.onData` tap so it does not outlive the
+        // session. No-op when the mirror was never enabled (the default OFF path leaves this undefined).
+        this.ansiMirror?.dispose();
+        this.ansiMirror = undefined;
+        if (this.resizeTimer !== undefined) {
+            this.clearTimeoutFn(this.resizeTimer);
+            this.resizeTimer = undefined;
+        }
+        this.pendingSize = undefined;
+        if (this.watcher) {
+            this.watcher.stop();
+            this.watcher = undefined;
+        }
+        this.sessions?.delete(this.sessionId);
+        this.onCleanup?.({ sessionId: this.sessionId, exitCode: info?.exitCode, signal: info?.signal });
+    }
+    /**
+     * Store the AbortController for the background fresh-path discovery poll (story 028, sub-task 2.1).
+     * `cleanup()` aborts it (sub-task 3.1) so a session torn down before its first interaction cancels
+     * the dangling `watchdogMs: Infinity` poll instead of leaking it. The engine owns the handle.
+     */
+    setPendingDiscovery(ac) {
+        this.pendingDiscovery = ac;
+    }
+    /** Whether {@link cleanup} has already run for this session. */
+    get isDisposed() {
+        return this.disposed;
+    }
+}
+/** PTY name pinned by §5 — mirrors the story 013 spawn allocation. */
+const RESUME_PTY_NAME = "xterm-256color";
+/**
+ * Build the robust resume argv (§5, R4.1): `bash -c 'claude --resume "<id>" || claude'`. The
+ * `|| claude` makes a FAILED `--resume` fall back to a fresh interactive session rather than
+ * hanging. The id is double-quoted so it survives shell word-splitting. There is deliberately
+ * NO `-p`/`--print`/`stream-json` — those select the SDK/credit non-interactive path.
+ */
+export function buildResumeArgv(sessionId) {
+    return ["-c", `claude --resume "${sessionId}" || claude`];
+}
+/**
+ * Spawn the resume PTY, reusing story 013's sanitized env (R4.2) so the resumed turn keeps the
+ * `entrypoint='cli'` subscription posture. Same env-sanitize ({@link buildSanitizedEnv}),
+ * refuse-to-spawn taint guard ({@link assertSpawnEnvUntainted}), shell resolution
+ * ({@link resolveShell}), and §5 PTY geometry as the story 013 spawn path — ONLY the argv
+ * differs (robust resume vs the fresh `--session-id` launch). Returns the same
+ * {@link PtyEngineHandle} shape so a {@link SessionEngine} manages a resumed PTY identically.
+ */
+export function spawnResumePty(opts) {
+    const { sessionId, cwd, baseEnv = process.env, spawn = pty.spawn } = opts;
+    const shell = resolveShell(baseEnv);
+    const argv = buildResumeArgv(sessionId);
+    const env = buildSanitizedEnv(baseEnv);
+    // §10 refuse-to-spawn guard (R4.2): abort if any forbidden billing var survived sanitization,
+    // rather than resume a credit-billed run. Checks the SPAWN env, not process.env.
+    assertSpawnEnvUntainted(env);
+    const p = spawn(shell, argv, {
+        name: RESUME_PTY_NAME,
+        cols: DEFAULT_COLS,
+        rows: DEFAULT_ROWS,
+        cwd,
+        env: env,
+    });
+    return { sessionId, pty: p };
+}
+/**
+ * Bind ONE PTY and ONE JSONL watcher into a single per-session {@link SessionEngine}, hosted by
+ * THIS one Node process (§2 — no out-of-process supervisor, no `child_process.fork`). The PTY is
+ * spawned via story 013's sanitized path; the watcher is started by the injected story-015
+ * factory; the returned engine record owns both (PTY handle + watcher handle + resize timer +
+ * disposed flag).
+ *
+ * ── tail-as-source-of-truth fence (§2 ordering) ───────────────────────────────────────────────
+ * Session state derives SOLELY from the watcher's JSONL tail. The live ANSI mirror (story 035) is
+ * cosmetic and OFF by default: with no `ansiMirror` option, `p.onData` is NEVER subscribed and this
+ * binding is byte-for-byte the read-only Degrau-1 path. Even when enabled, the mirror is one-way
+ * (bytes → live-view sink) and MUST NOT mutate session state or drive turn transitions. Do not add
+ * an `onData`→state path in this binding: structure comes only from the JSONL tail.
+ * ──────────────────────────────────────────────────────────────────────────────────────────────
+ */
+export function createSessionEngine(opts) {
+    // ONE PTY, via the story 013 sanitized spawn path. `settingsFile` (story 034) injects the
+    // per-session gate hook via `--settings` — already written by the caller BEFORE this spawn.
+    const handle = spawnClaudePty({
+        cwd: opts.cwd,
+        baseEnv: opts.baseEnv,
+        spawn: opts.spawn,
+        settingsFile: opts.settingsFile,
+    });
+    // ONE watcher, started by the story 015 factory and bound to that same PTY.
+    const watcher = opts.startWatcher?.(handle.sessionId, handle.pty);
+    return new SessionEngine({
+        handle,
+        watcher,
+        sessions: opts.sessions,
+        resizeDebounceMs: opts.resizeDebounceMs,
+        onCleanup: opts.onCleanup,
+        setTimeoutFn: opts.setTimeoutFn,
+        clearTimeoutFn: opts.clearTimeoutFn,
+        // Story 035: forward the OPTIONAL cosmetic mirror config (OFF by default — no tap when absent).
+        ansiMirror: opts.ansiMirror,
+    });
+}

package/dist/engine-pty.d.ts

@@ -0,0 +1,143 @@
+import pty from "node-pty";
+import type { IPty } from "node-pty";
+/**
+ * The four billing/SDK env vars that must never reach the spawned TUI (§10). Inheriting
+ * any of `CLAUDE_CODE_ENTRYPOINT` / `CLAUDE_AGENT_SDK_VERSION` / `CLAUDE_AGENT_SDK_CLIENT_APP`
+ * from the parent Node/ACP process would silently bill the run as credit; `CLAUDECODE`
+ * additionally makes the nested `claude` TUI refuse to start (anti-nesting guard).
+ */
+export declare const FORBIDDEN_BILLING_VARS: readonly ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_AGENT_SDK_VERSION", "CLAUDE_AGENT_SDK_CLIENT_APP"];
+/**
+ * Build the sanitized spawn env (§5/§10): spread the base env, set the three terminal vars
+ * (`TERM`/`COLORTERM`/`FORCE_COLOR`), then delete the four {@link FORBIDDEN_BILLING_VARS}.
+ *
+ * This is the SINGLE shared definition every spawn path reuses — this story's spawn and
+ * story 014's `--resume` — so the deletions never drift across two hand-copied blocks
+ * (R2.1-R2.4). Unrelated keys (PATH, HOME, …) pass through untouched.
+ */
+export declare function buildSanitizedEnv(baseEnv?: Record<string, string | undefined>): Record<string, string | undefined>;
+/**
+ * Refuse-to-spawn taint guard (R4.1/R4.2). Throws — naming EVERY offending key and the
+ * inherited-taint hazard — if any of the four {@link FORBIDDEN_BILLING_VARS} is still
+ * present in the spawn env. Defense-in-depth: a future env-build regression that
+ * re-introduces a deleted var must abort the spawn loudly rather than launch a run that
+ * is silently billed as credit (§10, IMPLEMENTACAO-FORK-ACP.md §13 R1).
+ */
+export declare function assertSpawnEnvUntainted(env: Record<string, string | undefined>): void;
+/** Resolve the login shell: `process.env.SHELL` when set, else `/bin/bash` (§5, R1.2). */
+export declare function resolveShell(baseEnv?: Record<string, string | undefined>): string;
+/**
+ * The interactive-TUI command (§5, R1.1). NO `-p`/`--print`, NO `stream-json` — those
+ * select the SDK/credit non-interactive path. The pre-generated `sessionId` is embedded
+ * verbatim so the JSONL transcript can be correlated by basename.
+ *
+ * When `planMode` is true, `--permission-mode plan` is appended (story 029 / R4.1).
+ * This is the DETERMINISTIC plan-mode entry: the spawn flag is preferred over the
+ * interactive Shift+Tab cycle (`\x1b[Z`), which is the §5-appendix UNTESTED fallback
+ * (documented in IMPLEMENTACAO-FORK-ACP.md §5, not wired here as primary — R4.2/R4.3).
+ *
+ * When `settingsFile` is set, `--settings "<file>"` is appended (story 034 / §9 hybrid
+ * gate wiring): the per-session SCRATCH settings file carrying the fork's `PreToolUse`
+ * type:http hook (story 032 `injectHook`). Injecting via `--settings` from a trusted cwd
+ * is the BINDING Degrau-0 recipe (GATE_FINDINGS blocker c) — never a project-local
+ * `.claude/` (trust dialog) and never `CLAUDE_CONFIG_DIR` (relocates auth, breaks
+ * billing). The path is double-quoted so it survives the `-lc` shell word-splitting.
+ * Like `--permission-mode plan`, this flag changes only TUI behavior — it adds no
+ * `-p`/`stream-json`, so billing stays subscription `cli` (§10).
+ */
+export declare function buildClaudeCmd(sessionId: string, planMode?: boolean, settingsFile?: string): string;
+/**
+ * Login-shell argv (§5, R1.3). The `-lc` flag is MANDATORY: node-pty's `posix_spawnp`
+ * does not execute the `claude` npm launcher's `#!/usr/bin/env node` shebang, so the
+ * launcher must run *through* a login shell. (The compiled native-binary is the only
+ * thing that could be spawned directly — §5 / IMPLEMENTACAO-FORK-ACP.md §17.)
+ */
+export declare function buildSpawnArgv(sessionId: string, planMode?: boolean, settingsFile?: string): [string, string];
+/** Options for {@link spawnClaudePty}. */
+export interface SpawnPtyOptions {
+    /** Host working directory the TUI runs in; passed straight through to the PTY (§5). */
+    cwd: string;
+    /** Base environment to sanitize; defaults to the parent process env. */
+    baseEnv?: Record<string, string | undefined>;
+    /**
+     * Injectable spawn function (defaults to node-pty's `spawn`). Unit tests pass a fake
+     * so they exercise the spawn spec without launching a real process.
+     */
+    spawn?: typeof pty.spawn;
+    /**
+     * When true, adds `--permission-mode plan` to the spawn command (story 029 / R4.1).
+     * Prefer this over the interactive Shift+Tab cycle (`\x1b[Z`), which is the §5-appendix
+     * UNTESTED fallback and is documented, not wired as primary (R4.2/R4.3).
+     */
+    planMode?: boolean;
+    /**
+     * Story 034 (§9 hybrid gate): absolute path of the per-session SCRATCH settings file
+     * carrying the fork's `PreToolUse` hook; appended as `--settings "<file>"`. The file
+     * MUST be written (story 032 `injectHook`) BEFORE this spawn — claude reads settings
+     * only at startup (GATE_FINDINGS blocker c), so a late write misses the first tool call.
+     * Absent → no flag (the ungated/`FORK_GATE=off` spawn is byte-for-byte pre-034).
+     */
+    settingsFile?: string;
+}
+/** Handle returned by {@link spawnClaudePty}; story 014 manages its lifecycle. */
+export interface PtyEngineHandle {
+    /** Pre-generated v4 `sessionId`, reused verbatim in the argv (R1.1). */
+    sessionId: string;
+    /** The live PTY handle. */
+    pty: IPty;
+}
+/**
+ * Spawn the interactive `claude` TUI under a real PTY with the §5 dimensions and a
+ * sanitized, subscription-billing environment.
+ *
+ * A real PTY (allocated by `pty.spawn`) is MANDATORY: the binary checks `isTTY` (12× in
+ * the binary) and a plain pipe yields non-interactive mode (§5, R1.4). The stdio is NOT
+ * piped — the PTY is what makes `isTTY` true.
+ *
+ * Prior art (§4/§5): the login-shell command form, the `xterm-256color` PTY allocation,
+ * and the exit-code/signal capture *shape* are borrowed from siteboon/claudecodeui
+ * (`shell-websocket.service.ts`) and markes76/claude-code-gui (`pty-bridge.ts`) rather
+ * than hand-rolled — adapting only the sanitized env and `--session-id` correlation
+ * specific to this fork. The actual `onExit`→cleanup wiring is story 014; here only the
+ * spawn/exit shape is borrowed (the handle is returned for 014 to manage). No bespoke
+ * process-supervisor or non-PTY spawn variant is introduced.
+ */
+export declare function spawnClaudePty(opts: SpawnPtyOptions): PtyEngineHandle;
+/** Submission delay (ms) between the payload write and the `\r` (§8 / R1.2). */
+export declare const SUBMISSION_DELAY_MS = 60;
+/**
+ * The input-clearing keystroke that leads every submission (story 034 G2 fix): Ctrl+U (`\x15`,
+ * kill-line). PROVED by `experiments/e-clear.ts` against the real TUI: Ctrl+U empties a non-empty
+ * input box (the question submits alone), as does Ctrl+C — but Ctrl+C is unsafe as a universal
+ * prefix (a second \x03 in close succession EXITS the TUI). Esc was the first candidate and was
+ * REFUTED live twice (sessions 76fbf771 and 78e56a85 still merged the residue). Known limit: a
+ * RESTORED MULTI-LINE residue may need one kill-line per line; the common case (a single-line
+ * cancelled prompt) is covered.
+ */
+export declare const CLEAR_INPUT_KEY = "\u0015";
+/**
+ * Delay (ms) between the input-clearing keystroke and the payload write (story 034 G2 fix) —
+ * gives the TUI its own event-loop tick to process the clear before new bytes arrive.
+ */
+export declare const CLEAR_INPUT_DELAY_MS = 60;
+/**
+ * Write `text` to the PTY and submit with a delayed carriage return (§8 / R1.1–R1.4).
+ *
+ * Sequence (story-034 G2 live fix prepended the clear): `\x15` (Ctrl+U — clear residual input) →
+ * delay → write(payload) → delay → `\r`. The G2 acceptance run (session 76fbf771) proved the TUI
+ * RESTORES a cancelled prompt into its input box, so a fresh submission would concatenate the
+ * residue with the new payload into one turn ("Conte de 1 a 100…Qual o nome…"). Ctrl+U kills the
+ * residue and is a no-op on an empty box — idempotent for every submission, whatever left the
+ * residue. (The permission allow-keystroke does NOT route through here — `allow-inject` writes
+ * raw bytes precisely so no clearing byte can touch a pending native dialog.)
+ *
+ * For single-line `text`: writes the body verbatim then `\r` after the delay.
+ * Multi-line handling (bracketed-paste) is added in story 029 task 2.1.
+ *
+ * The `schedule` parameter defaults to `setTimeout` and is injectable for unit tests
+ * so timing can be verified synchronously (the same pattern as `createEndOfTurnDetector`).
+ * Only the leading clear write is synchronous (a dead-PTY failure surfaces there, in the caller's
+ * try/catch); the payload and `\r` writes are scheduled and post-exit-safe.
+ */
+export declare function sendPrompt(p: IPty, text: string, schedule?: (fn: () => void, ms: number) => void): void;
+//# sourceMappingURL=engine-pty.d.ts.map

package/dist/engine-pty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-pty.d.ts","sourceRoot":"","sources":["../src/engine-pty.ts"],"names":[],"mappings":"AAiBA,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAQrC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,8GAKzB,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAWpC;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,CASrF;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAAC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAE9F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAKnG;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,OAAO,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,CAAC,MAAM,EAAE,MAAM,CAAC,CAElB;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,CAAC,KAAK,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,GAAG,EAAE,IAAI,CAAC;CACX;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,CA+BrE;AA6BD,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,WAAS,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,IAAI,EACP,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,IAAqC,GAC9E,IAAI,CAON"}

package/dist/engine-pty.js

@@ -0,0 +1,222 @@
+// === §2 MOTOR box — node-pty spawn of the real interactive `claude` TUI (story 013) ===
+//
+// Spawns the user's *subscription* `claude` TUI under a REAL pseudo-terminal with a
+// sanitized, subscription-billing environment, so the JSONL transcript self-labels its
+// message events with entrypoint='cli' (subscription) rather than an SDK/credit signal.
+// Degrau 0 proved the premise empirically: a clean-env PTY run yields the distinct
+// entrypoint set {cli}; the negative control (inherited SDK env) flips it to {sdk-ts}
+// (experiments/DEGRAU0-RESULTS.md, E1 = PASS — the keystone gate).
+//
+// Spec is PINNED by IMPLEMENTACAO-FORK-ACP.md §5 (Spawn — mantém assinatura) and §10
+// (billing audit). This module imports NO SDK — no credit-billing `query()` path is
+// reachable through it (the engine seam stays read-only in Degrau 1).
+//
+// Scope: this module owns ONLY the spawn moment (argv, sanitized env, taint guard,
+// launch). Process lifecycle/resume is story 014; the JSONL tail watcher is story 015;
+// the ACP createSession rewrite that wires this engine in is story 023.
+import pty from "node-pty";
+import { randomUUID } from "node:crypto";
+// PTY geometry pinned by §5.
+const PTY_NAME = "xterm-256color";
+const PTY_COLS = 120;
+const PTY_ROWS = 40;
+/**
+ * The four billing/SDK env vars that must never reach the spawned TUI (§10). Inheriting
+ * any of `CLAUDE_CODE_ENTRYPOINT` / `CLAUDE_AGENT_SDK_VERSION` / `CLAUDE_AGENT_SDK_CLIENT_APP`
+ * from the parent Node/ACP process would silently bill the run as credit; `CLAUDECODE`
+ * additionally makes the nested `claude` TUI refuse to start (anti-nesting guard).
+ */
+export const FORBIDDEN_BILLING_VARS = [
+    "CLAUDECODE",
+    "CLAUDE_CODE_ENTRYPOINT",
+    "CLAUDE_AGENT_SDK_VERSION",
+    "CLAUDE_AGENT_SDK_CLIENT_APP",
+];
+/**
+ * Build the sanitized spawn env (§5/§10): spread the base env, set the three terminal vars
+ * (`TERM`/`COLORTERM`/`FORCE_COLOR`), then delete the four {@link FORBIDDEN_BILLING_VARS}.
+ *
+ * This is the SINGLE shared definition every spawn path reuses — this story's spawn and
+ * story 014's `--resume` — so the deletions never drift across two hand-copied blocks
+ * (R2.1-R2.4). Unrelated keys (PATH, HOME, …) pass through untouched.
+ */
+export function buildSanitizedEnv(baseEnv = process.env) {
+    const env = {
+        ...baseEnv,
+        TERM: PTY_NAME,
+        COLORTERM: "truecolor",
+        FORCE_COLOR: "3",
+    };
+    for (const key of FORBIDDEN_BILLING_VARS) {
+        delete env[key];
+    }
+    return env;
+}
+/**
+ * Refuse-to-spawn taint guard (R4.1/R4.2). Throws — naming EVERY offending key and the
+ * inherited-taint hazard — if any of the four {@link FORBIDDEN_BILLING_VARS} is still
+ * present in the spawn env. Defense-in-depth: a future env-build regression that
+ * re-introduces a deleted var must abort the spawn loudly rather than launch a run that
+ * is silently billed as credit (§10, IMPLEMENTACAO-FORK-ACP.md §13 R1).
+ */
+export function assertSpawnEnvUntainted(env) {
+    const present = FORBIDDEN_BILLING_VARS.filter((key) => env[key] !== undefined);
+    if (present.length > 0) {
+        throw new Error(`engine-pty: refusing to spawn — forbidden billing var(s) survived sanitization: ` +
+            `${present.join(", ")}. Inheriting these from the parent Node/ACP process would ` +
+            `silently bill the run as credit instead of subscription (§10, R4).`);
+    }
+}
+/** Resolve the login shell: `process.env.SHELL` when set, else `/bin/bash` (§5, R1.2). */
+export function resolveShell(baseEnv = process.env) {
+    return baseEnv.SHELL || "/bin/bash";
+}
+/**
+ * The interactive-TUI command (§5, R1.1). NO `-p`/`--print`, NO `stream-json` — those
+ * select the SDK/credit non-interactive path. The pre-generated `sessionId` is embedded
+ * verbatim so the JSONL transcript can be correlated by basename.
+ *
+ * When `planMode` is true, `--permission-mode plan` is appended (story 029 / R4.1).
+ * This is the DETERMINISTIC plan-mode entry: the spawn flag is preferred over the
+ * interactive Shift+Tab cycle (`\x1b[Z`), which is the §5-appendix UNTESTED fallback
+ * (documented in IMPLEMENTACAO-FORK-ACP.md §5, not wired here as primary — R4.2/R4.3).
+ *
+ * When `settingsFile` is set, `--settings "<file>"` is appended (story 034 / §9 hybrid
+ * gate wiring): the per-session SCRATCH settings file carrying the fork's `PreToolUse`
+ * type:http hook (story 032 `injectHook`). Injecting via `--settings` from a trusted cwd
+ * is the BINDING Degrau-0 recipe (GATE_FINDINGS blocker c) — never a project-local
+ * `.claude/` (trust dialog) and never `CLAUDE_CONFIG_DIR` (relocates auth, breaks
+ * billing). The path is double-quoted so it survives the `-lc` shell word-splitting.
+ * Like `--permission-mode plan`, this flag changes only TUI behavior — it adds no
+ * `-p`/`stream-json`, so billing stays subscription `cli` (§10).
+ */
+export function buildClaudeCmd(sessionId, planMode, settingsFile) {
+    let cmd = `claude --session-id ${sessionId}`;
+    if (planMode)
+        cmd += " --permission-mode plan";
+    if (settingsFile)
+        cmd += ` --settings "${settingsFile}"`;
+    return cmd;
+}
+/**
+ * Login-shell argv (§5, R1.3). The `-lc` flag is MANDATORY: node-pty's `posix_spawnp`
+ * does not execute the `claude` npm launcher's `#!/usr/bin/env node` shebang, so the
+ * launcher must run *through* a login shell. (The compiled native-binary is the only
+ * thing that could be spawned directly — §5 / IMPLEMENTACAO-FORK-ACP.md §17.)
+ */
+export function buildSpawnArgv(sessionId, planMode, settingsFile) {
+    return ["-lc", buildClaudeCmd(sessionId, planMode, settingsFile)];
+}
+/**
+ * Spawn the interactive `claude` TUI under a real PTY with the §5 dimensions and a
+ * sanitized, subscription-billing environment.
+ *
+ * A real PTY (allocated by `pty.spawn`) is MANDATORY: the binary checks `isTTY` (12× in
+ * the binary) and a plain pipe yields non-interactive mode (§5, R1.4). The stdio is NOT
+ * piped — the PTY is what makes `isTTY` true.
+ *
+ * Prior art (§4/§5): the login-shell command form, the `xterm-256color` PTY allocation,
+ * and the exit-code/signal capture *shape* are borrowed from siteboon/claudecodeui
+ * (`shell-websocket.service.ts`) and markes76/claude-code-gui (`pty-bridge.ts`) rather
+ * than hand-rolled — adapting only the sanitized env and `--session-id` correlation
+ * specific to this fork. The actual `onExit`→cleanup wiring is story 014; here only the
+ * spawn/exit shape is borrowed (the handle is returned for 014 to manage). No bespoke
+ * process-supervisor or non-PTY spawn variant is introduced.
+ */
+export function spawnClaudePty(opts) {
+    const { cwd, baseEnv = process.env, spawn = pty.spawn, planMode, settingsFile } = opts;
+    const sessionId = randomUUID(); // pre-generated → correlates to the JSONL transcript
+    const shell = resolveShell(baseEnv);
+    const argv = buildSpawnArgv(sessionId, planMode, settingsFile);
+    // Sanitized, subscription-billing env (§5/§10) via the single shared definition.
+    const env = buildSanitizedEnv(baseEnv);
+    // §10 no-spoof contract (R3.1/R3.3): the 'cli' entrypoint label MUST be produced
+    // ORGANICALLY by running the real TUI — it is NEVER forged. CLAUDE_CODE_ENTRYPOINT is
+    // assigned nowhere on this path; after sanitization it must be absent, and nothing below
+    // re-introduces it. Forcing the field would be spoofing-with-enforcement (the OpenClaw
+    // evasion case). The argv is interactive-only — buildClaudeCmd() carries no -p/stream-json.
+    //
+    // Refuse-to-spawn taint guard (R4): abort loudly if ANY of the four forbidden billing
+    // vars (incl. CLAUDE_CODE_ENTRYPOINT) survived sanitization, rather than launch a
+    // credit-billed run. Checks the SPAWN env, not process.env.
+    assertSpawnEnvUntainted(env);
+    // Real PTY (not a pipe) so the binary's isTTY check passes → interactive mode (R1.4).
+    const p = spawn(shell, argv, {
+        name: PTY_NAME,
+        cols: PTY_COLS,
+        rows: PTY_ROWS,
+        cwd,
+        env: env,
+    });
+    return { sessionId, pty: p };
+}
+// === §8 Fluxo reverso — sendPrompt (story 029) ===
+//
+// Submission shape pinned by IMPLEMENTACAO-FORK-ACP.md §8 (Submissão):
+//   write(payload) → delay (~60 ms) → write('\r')
+// Multi-line text MUST use bracketed-paste (the branch in sendPrompt below).
+// All writes go directly through `p.write` — no xterm.js interposed.
+//
+// --- Empirical validation (task 4.2 / R3.3 / R5.3 — live run 2026-06-09, claude 2.1.170) ---
+// The previously-UNTESTED bracketed-paste multi-line path is CONFIRMED: a 3-line and a
+// 5-line prompt each submitted as EXACTLY ONE `user` event over the wire (R2.3 / R5.2) —
+// the TUI treats the `\x1b[200~…\x1b[201~` envelope as a single paste, not one turn per
+// embedded newline. The ~60 ms write→`\r` delay commits both single-line and multi-line
+// submissions; on long input the `\r` is NOT absorbed into the paste body (R3.2).
+//
+// Flakiness observed (R3.3): single-line submission is reliable in isolation (3/3 live
+// runs), but one transient MISS occurred when the engine was spawned back-to-back with
+// other live engines in the same batch — that run created NO transcript at all (the
+// submission never committed: no first interaction → no JSONL, per story 028). The miss
+// correlates with TUI input-readiness right after a rapid re-spawn, NOT with the 60 ms
+// constant (raising the delay would not help a not-yet-ready TUI). The bracketed-paste
+// envelope proved the more robust path (atomic paste finalization). Resolving guidance:
+// let the TUI reach input-readiness (the BOOT settle) before the first submission; the
+// 60 ms submit delay itself needs no change.
+//
+// Shift+Tab plan-mode entry (`\x1b[Z`) remains the UNTESTED, unwired fallback — see
+// buildClaudeCmd above; `--permission-mode plan` is the wired deterministic path (R4).
+/** Submission delay (ms) between the payload write and the `\r` (§8 / R1.2). */
+export const SUBMISSION_DELAY_MS = 60;
+/**
+ * The input-clearing keystroke that leads every submission (story 034 G2 fix): Ctrl+U (`\x15`,
+ * kill-line). PROVED by `experiments/e-clear.ts` against the real TUI: Ctrl+U empties a non-empty
+ * input box (the question submits alone), as does Ctrl+C — but Ctrl+C is unsafe as a universal
+ * prefix (a second \x03 in close succession EXITS the TUI). Esc was the first candidate and was
+ * REFUTED live twice (sessions 76fbf771 and 78e56a85 still merged the residue). Known limit: a
+ * RESTORED MULTI-LINE residue may need one kill-line per line; the common case (a single-line
+ * cancelled prompt) is covered.
+ */
+export const CLEAR_INPUT_KEY = "\x15";
+/**
+ * Delay (ms) between the input-clearing keystroke and the payload write (story 034 G2 fix) —
+ * gives the TUI its own event-loop tick to process the clear before new bytes arrive.
+ */
+export const CLEAR_INPUT_DELAY_MS = 60;
+/**
+ * Write `text` to the PTY and submit with a delayed carriage return (§8 / R1.1–R1.4).
+ *
+ * Sequence (story-034 G2 live fix prepended the clear): `\x15` (Ctrl+U — clear residual input) →
+ * delay → write(payload) → delay → `\r`. The G2 acceptance run (session 76fbf771) proved the TUI
+ * RESTORES a cancelled prompt into its input box, so a fresh submission would concatenate the
+ * residue with the new payload into one turn ("Conte de 1 a 100…Qual o nome…"). Ctrl+U kills the
+ * residue and is a no-op on an empty box — idempotent for every submission, whatever left the
+ * residue. (The permission allow-keystroke does NOT route through here — `allow-inject` writes
+ * raw bytes precisely so no clearing byte can touch a pending native dialog.)
+ *
+ * For single-line `text`: writes the body verbatim then `\r` after the delay.
+ * Multi-line handling (bracketed-paste) is added in story 029 task 2.1.
+ *
+ * The `schedule` parameter defaults to `setTimeout` and is injectable for unit tests
+ * so timing can be verified synchronously (the same pattern as `createEndOfTurnDetector`).
+ * Only the leading clear write is synchronous (a dead-PTY failure surfaces there, in the caller's
+ * try/catch); the payload and `\r` writes are scheduled and post-exit-safe.
+ */
+export function sendPrompt(p, text, schedule = (fn, ms) => setTimeout(fn, ms)) {
+    // Multi-line: wrap in bracketed-paste so the TUI treats the whole block as ONE turn
+    // rather than submitting on each embedded newline (§5 Input / R2.1-R2.4).
+    const payload = text.includes("\n") ? `\x1b[200~${text}\x1b[201~` : text;
+    p.write(CLEAR_INPUT_KEY); // clear any residual input-box text (e.g. a cancelled prompt the TUI restored)
+    schedule(() => p.write(payload), CLEAR_INPUT_DELAY_MS);
+    schedule(() => p.write("\r"), CLEAR_INPUT_DELAY_MS + SUBMISSION_DELAY_MS);
+}