jeo-code 0.6.41 → 0.7.0

package/src/commands/approve.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { createHash } from "node:crypto";
 import {
   readGlobalConfig,
   readWorkflowState,
@@ -75,8 +76,10 @@ export async function runApproveCommand(args: string[] = []): Promise<void> {
   // rubber stamp — validate the plan against the exact contract `jeo team`
   // enforces, so a schema-invalid/unknown-role plan is refused HERE instead of
   // aborting later at execution time.
+  let planContent = "";
   try {
-    const parsed = PlanSchema.safeParse(normalizePlanShape(parseYaml(await fs.readFile(resolvedInputPath, "utf-8"))));
+    planContent = await fs.readFile(resolvedInputPath, "utf-8");
+    const parsed = PlanSchema.safeParse(normalizePlanShape(parseYaml(planContent)));
     if (!parsed.success) {
       console.log(
         `[ERROR] Refusing to approve: the plan is not in the shape 'jeo team' executes (top-level 'steps:' list of { name, role? }).\n` +
@@ -114,6 +117,19 @@ export async function runApproveCommand(args: string[] = []): Promise<void> {
     return;
   }
 
+  // Round-13: verify the plan's hash matches the consensus hash to prevent silent edits
+  if (ralplanState.consensus_hash) {
+    const currentHash = createHash("sha256").update(planContent).digest("hex");
+    if (currentHash !== ralplanState.consensus_hash) {
+      console.log(
+        `[ERROR] Refusing to approve: the plan file has been modified since the consensus critic reviewed it.\n` +
+        `  Re-run 'jeo ralplan' to let the critic review the updated plan, then approve again.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   // Update ralplan-state.json to approved: true
   ralplanState.approved = true;
   await writeWorkflowState("ralplan", ralplanState, cwd);

package/src/commands/computer.ts

@@ -0,0 +1,334 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { computerSupervisor } from "../agent/computer-supervisor";
+import { readGlobalConfig } from "../agent/state";
+
+export interface ComputerAction {
+  action: "screenshot" | "click" | "double_click" | "move" | "drag" | "scroll" | "type" | "keypress" | "wait" | "batch";
+  x?: number;
+  y?: number;
+  text?: string;
+  key?: string;
+  deltaX?: number;
+  deltaY?: number;
+  duration?: number;
+  actions?: ComputerAction[];
+}
+
+async function logAudit(action: ComputerAction, success: boolean, error?: string) {
+  try {
+    const auditDir = path.join(process.cwd(), ".jeo");
+    await fs.mkdir(auditDir, { recursive: true });
+    const auditPath = path.join(auditDir, "computer-audit.jsonl");
+    const logEntry = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      action,
+      success,
+      error,
+    }) + "\n";
+    await fs.appendFile(auditPath, logEntry, "utf-8");
+  } catch {
+    // best-effort
+  }
+}
+
+async function runCommand(cmd: string[]): Promise<{ success: boolean; stdout: string; stderr: string }> {
+  try {
+    const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+    await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    return {
+      success: proc.exitCode === 0,
+      stdout,
+      stderr,
+    };
+  } catch (err: any) {
+    return {
+      success: false,
+      stdout: "",
+      stderr: err.message || String(err),
+    };
+  }
+}
+
+export async function executeComputerAction(action: ComputerAction): Promise<{ success: boolean; output: string; error?: string }> {
+  const config = await readGlobalConfig().catch(() => null);
+  if (!config?.computer?.enabled) {
+    return {
+      success: false,
+      output: "",
+      error: "Computer use is disabled. Enable it by setting 'computer.enabled: true' in ~/.jeo/config.json",
+    };
+  }
+
+  // Read-only actions don't need supervisor inputAllowed check
+  const isReadOnly = action.action === "screenshot" || action.action === "wait";
+  if (!isReadOnly) {
+    if (!computerSupervisor.inputAllowed) {
+      const err = "Action blocked by fail-closed supervisor (kill switch not live, heartbeat stale, or suspended).";
+      await logAudit(action, false, err);
+      return { success: false, output: "", error: err };
+    }
+  }
+
+  const isMac = os.platform() === "darwin";
+
+  switch (action.action) {
+    case "screenshot": {
+      const tmpDir = os.tmpdir();
+      const screenPath = path.join(tmpDir, `jeo-screen-${Date.now()}.png`);
+      let cmd: string[];
+      if (isMac) {
+        cmd = ["screencapture", "-x", screenPath];
+      } else {
+        cmd = ["scrot", "-z", screenPath];
+      }
+      const res = await runCommand(cmd);
+      if (!res.success) {
+        await logAudit(action, false, res.stderr);
+        return { success: false, output: "", error: `Failed to capture screenshot: ${res.stderr}` };
+      }
+      try {
+        const bytes = await fs.readFile(screenPath);
+        const base64 = bytes.toString("base64");
+        await fs.unlink(screenPath).catch(() => {});
+        await logAudit(action, true);
+        return { success: true, output: base64 };
+      } catch (err: any) {
+        await logAudit(action, false, err.message);
+        return { success: false, output: "", error: `Failed to read screenshot file: ${err.message}` };
+      }
+    }
+
+    case "click": {
+      if (action.x === undefined || action.y === undefined) {
+        return { success: false, output: "", error: "Missing coordinates x and y for click action." };
+      }
+      let cmd: string[];
+      if (isMac) {
+        cmd = ["cliclick", `c:${action.x},${action.y}`];
+      } else {
+        cmd = ["xdotool", "mousemove", String(action.x), String(action.y), "click", "1"];
+      }
+      const res = await runCommand(cmd);
+      await logAudit(action, res.success, res.success ? undefined : res.stderr);
+      return res.success
+        ? { success: true, output: `Clicked at (${action.x}, ${action.y})` }
+        : { success: false, output: "", error: `Click failed: ${res.stderr}` };
+    }
+
+    case "double_click": {
+      if (action.x === undefined || action.y === undefined) {
+        return { success: false, output: "", error: "Missing coordinates x and y for double_click action." };
+      }
+      let cmd: string[];
+      if (isMac) {
+        cmd = ["cliclick", `dc:${action.x},${action.y}`];
+      } else {
+        cmd = ["xdotool", "mousemove", String(action.x), String(action.y), "click", "--repeat", "2", "--delay", "100", "1"];
+      }
+      const res = await runCommand(cmd);
+      await logAudit(action, res.success, res.success ? undefined : res.stderr);
+      return res.success
+        ? { success: true, output: `Double clicked at (${action.x}, ${action.y})` }
+        : { success: false, output: "", error: `Double click failed: ${res.stderr}` };
+    }
+
+    case "move": {
+      if (action.x === undefined || action.y === undefined) {
+        return { success: false, output: "", error: "Missing coordinates x and y for move action." };
+      }
+      let cmd: string[];
+      if (isMac) {
+        cmd = ["cliclick", `m:${action.x},${action.y}`];
+      } else {
+        cmd = ["xdotool", "mousemove", String(action.x), String(action.y)];
+      }
+      const res = await runCommand(cmd);
+      await logAudit(action, res.success, res.success ? undefined : res.stderr);
+      return res.success
+        ? { success: true, output: `Moved cursor to (${action.x}, ${action.y})` }
+        : { success: false, output: "", error: `Move failed: ${res.stderr}` };
+    }
+
+    case "drag": {
+      if (action.x === undefined || action.y === undefined) {
+        return { success: false, output: "", error: "Missing coordinates x and y for drag action." };
+      }
+      let cmd: string[];
+      if (isMac) {
+        cmd = ["cliclick", `dd:${action.x},${action.y}`];
+      } else {
+        cmd = ["xdotool", "mousemove", String(action.x), String(action.y), "mousedown", "1"];
+      }
+      const res = await runCommand(cmd);
+      await logAudit(action, res.success, res.success ? undefined : res.stderr);
+      return res.success
+        ? { success: true, output: `Dragged to (${action.x}, ${action.y})` }
+        : { success: false, output: "", error: `Drag failed: ${res.stderr}` };
+    }
+
+    case "scroll": {
+      let cmd: string[];
+      const dx = action.deltaX ?? 0;
+      const dy = action.deltaY ?? 0;
+      if (isMac) {
+        // cliclick scroll deltaY deltaX
+        cmd = ["cliclick", `w:${dy},${dx}`];
+      } else {
+        // xdotool click 4 (scroll up), 5 (scroll down), 6 (scroll left), 7 (scroll right)
+        const actions: string[] = [];
+        if (dy > 0) {
+          for (let i = 0; i < dy; i++) actions.push("click", "4");
+        } else if (dy < 0) {
+          for (let i = 0; i < -dy; i++) actions.push("click", "5");
+        }
+        if (dx > 0) {
+          for (let i = 0; i < dx; i++) actions.push("click", "7");
+        } else if (dx < 0) {
+          for (let i = 0; i < -dx; i++) actions.push("click", "6");
+        }
+        cmd = ["xdotool", ...actions];
+      }
+      const res = await runCommand(cmd);
+      await logAudit(action, res.success, res.success ? undefined : res.stderr);
+      return res.success
+        ? { success: true, output: `Scrolled by deltaX=${dx}, deltaY=${dy}` }
+        : { success: false, output: "", error: `Scroll failed: ${res.stderr}` };
+    }
+
+    case "type": {
+      if (action.text === undefined) {
+        return { success: false, output: "", error: "Missing text for type action." };
+      }
+      let cmd: string[];
+      if (isMac) {
+        cmd = ["cliclick", `t:${action.text}`];
+      } else {
+        cmd = ["xdotool", "type", action.text];
+      }
+      const res = await runCommand(cmd);
+      await logAudit(action, res.success, res.success ? undefined : res.stderr);
+      return res.success
+        ? { success: true, output: `Typed text: ${action.text}` }
+        : { success: false, output: "", error: `Type failed: ${res.stderr}` };
+    }
+
+    case "keypress": {
+      if (action.key === undefined) {
+        return { success: false, output: "", error: "Missing key for keypress action." };
+      }
+      let cmd: string[];
+      if (isMac) {
+        cmd = ["cliclick", `kp:${action.key}`];
+      } else {
+        cmd = ["xdotool", "key", action.key];
+      }
+      const res = await runCommand(cmd);
+      await logAudit(action, res.success, res.success ? undefined : res.stderr);
+      return res.success
+        ? { success: true, output: `Pressed key: ${action.key}` }
+        : { success: false, output: "", error: `Keypress failed: ${res.stderr}` };
+    }
+
+    case "wait": {
+      const ms = (action.duration ?? 1) * 1000;
+      await new Promise((resolve) => setTimeout(resolve, ms));
+      await logAudit(action, true);
+      return { success: true, output: `Waited for ${action.duration ?? 1} seconds` };
+    }
+
+    case "batch": {
+      if (!action.actions || !Array.isArray(action.actions)) {
+        return { success: false, output: "", error: "Missing actions array for batch action." };
+      }
+      const results: string[] = [];
+      for (let i = 0; i < action.actions.length; i++) {
+        const subAction = action.actions[i];
+        const res = await executeComputerAction(subAction);
+        if (!res.success) {
+          const err = `Batch failed at step ${i}: ${res.error}`;
+          await logAudit(action, false, err);
+          return { success: false, output: results.join("\n"), error: err };
+        }
+        results.push(`Step ${i}: ${res.output}`);
+      }
+      await logAudit(action, true);
+      return { success: true, output: results.join("\n") };
+    }
+
+    default:
+      return { success: false, output: "", error: `Unknown computer action: ${(action as any).action}` };
+  }
+}
+
+export async function runComputerCommand(args: string[]): Promise<void> {
+  const actionName = args[0];
+  if (!actionName) {
+    console.log("Usage: jeo computer <action> [args]");
+    console.log("Actions: screenshot, click, double_click, move, drag, scroll, type, keypress, wait, batch");
+    return;
+  }
+
+  const action: ComputerAction = { action: actionName as any };
+
+  // Parse arguments based on action
+  if (actionName === "click" || actionName === "double_click" || actionName === "move" || actionName === "drag") {
+    const x = parseInt(args[1] ?? "");
+    const y = parseInt(args[2] ?? "");
+    if (isNaN(x) || isNaN(y)) {
+      console.error(`Error: ${actionName} requires x and y coordinates.`);
+      process.exit(1);
+    }
+    action.x = x;
+    action.y = y;
+  } else if (actionName === "type") {
+    const text = args.slice(1).join(" ");
+    if (!text) {
+      console.error("Error: type requires text.");
+      process.exit(1);
+    }
+    action.text = text;
+  } else if (actionName === "keypress") {
+    const key = args[1];
+    if (!key) {
+      console.error("Error: keypress requires a key name.");
+      process.exit(1);
+    }
+    action.key = key;
+  } else if (actionName === "scroll") {
+    const dx = parseInt(args[1] ?? "0");
+    const dy = parseInt(args[2] ?? "0");
+    action.deltaX = dx;
+    action.deltaY = dy;
+  } else if (actionName === "wait") {
+    const duration = parseFloat(args[1] ?? "1");
+    action.duration = duration;
+  } else if (actionName === "batch") {
+    const jsonStr = args.slice(1).join(" ");
+    try {
+      action.actions = JSON.parse(jsonStr);
+    } catch (err: any) {
+      console.error(`Error: batch requires a valid JSON array of actions. ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Heartbeat to supervisor for CLI execution
+  computerSupervisor.setKillSwitchLive(true);
+  computerSupervisor.heartbeat();
+
+  const res = await executeComputerAction(action);
+  if (res.success) {
+    if (actionName === "screenshot") {
+      console.log(res.output); // base64 output
+    } else {
+      console.log(res.output);
+    }
+  } else {
+    console.error(`Error: ${res.error}`);
+    process.exit(1);
+  }
+}

package/src/commands/launch/input.ts

@@ -24,6 +24,8 @@ interface AbortHarnessOptions {
    *  Without this hook the byte would be swallowed into the buffered input queue,
    *  which is why Ctrl+O historically "did nothing" while the TUI owned stdin. */
   onDetailKey?: () => void;
+  /** Invoked when Ctrl+\\ (\u001c) is pressed mid-turn — the safety kill-switch binding. */
+  onKillSwitch?: () => void;
   /** Invoked when an arrow / PageUp / PageDown key arrives mid-turn — scrolls the
    *  open Ctrl+O detail panel. dir -1 = up/back, +1 = down/forward; page = full jump. */
   onScrollKey?: (dir: -1 | 1, page: boolean) => void;
@@ -65,16 +67,23 @@ export function isGenuineMultilineDraft(line: string): boolean {
   return line.includes(MULTILINE_SENTINEL);
 }
 
-/** Whether an Up/Down keystroke should move the caret BETWEEN the box's visual rows
- *  (textarea feel) instead of falling through to readline's input-history recall. True
- *  only for a genuinely multi-line draft with no slash dropdown or history panel owning
- *  the arrows. A soft-wrapped one-liner returns false, so ↑ recalls the previous prompt
- *  rather than dragging the wrapped tail up a visual row. */
+/** Whether an Up/Down keystroke should be CONSIDERED for moving the caret between the
+ *  box's visual rows (textarea feel) instead of going straight to readline. True for any
+ *  non-empty draft when no slash dropdown or Ctrl+O history panel owns the arrows.
+ *
+ *  This is a gate, NOT the final decision: the caller still consults
+ *  `verticalCursorOffset`, which returns a target offset only when there is a visual row
+ *  to move to. So ↑/↓ edit a MULTI-ROW draft — whether it spans rows via explicit
+ *  Shift+Enter breaks OR a long line the box soft-wraps — yet still fall through to
+ *  input-history recall at the boundaries: ↑ on the TOP visual row, ↓ on the BOTTOM row,
+ *  and any single-visual-row draft (where `verticalCursorOffset` yields null). That
+ *  boundary-aware split gives full arrow-key cursor movement for editing multi-row input
+ *  while preserving "↑ recalls the previous prompt" once the caret can climb no higher. */
 export function shouldBoxVerticalNav(
   line: string,
   opts: { slashMatchCount: number; historyPanelOpen: boolean },
 ): boolean {
-  return isGenuineMultilineDraft(line) && opts.slashMatchCount === 0 && !opts.historyPanelOpen;
+  return line.length > 0 && opts.slashMatchCount === 0 && !opts.historyPanelOpen;
 }
 
 
@@ -372,6 +381,10 @@ export function createInFlightAbortHarness(opts: AbortHarnessOptions = {}): InFl
       opts.onDetailKey?.();
       return;
     }
+    if (text === "\u001c") {
+      opts.onKillSwitch?.();
+      return;
+    }
     if (text === "\u001b[A") { opts.onScrollKey?.(-1, false); return; }
     if (text === "\u001b[B") { opts.onScrollKey?.(1, false); return; }
     if (text === "\u001b[5~") { opts.onScrollKey?.(-1, true); return; }

package/src/commands/launch.ts

@@ -1469,14 +1469,14 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
         // Option/Cmd+Backspace) into the canonical control bytes it DOES act on.
         const combo = matchCursorCombo(data, i);
         if (combo) { out += combo[1]; i += combo[0].length; continue; }
-        // Up/Down inside a GENUINELY multi-line draft (explicit Shift+Enter breaks →
-        // SENTINEL) move the caret between the box's visual rows (textarea feel). A
-        // single line that merely SOFT-WRAPS is NOT treated as multi-line: ↑/↓ fall
-        // through to readline so they recall input history — the dominant REPL
-        // expectation. (Without this gate, ↑ on a wrapped one-liner jumped the caret up
-        // a visual row instead of recalling the previous prompt, so the last wrapped
-        // word appeared to "follow the caret up".) Skipped when a slash list or history
-        // panel owns ↑/↓, and at the top/bottom edge the keys still reach history.
+        // Up/Down move the caret BETWEEN the box's visual rows (textarea feel) for any
+        // MULTI-ROW draft — explicit Shift+Enter breaks (→ SENTINEL) OR a long line the
+        // box soft-wraps. The decision is boundary-aware: verticalCursorOffset returns a
+        // target only when a visual row exists to move to, so ↑ on the TOP row, ↓ on the
+        // BOTTOM row, and any single-visual-row draft fall through to readline and recall
+        // input history — the dominant REPL expectation once the caret can climb no
+        // higher. Skipped when a slash list or Ctrl+O history panel owns ↑/↓.
+
         if ((data.startsWith("\u001b[", i) || data.startsWith("\u001bO", i)) && (data[i + 2] === "A" || data[i + 2] === "B")) {
           const dir = data[i + 2] === "A" ? "up" : "down";
           const line = activeRl?.line ?? "";

package/src/commands/ralplan.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { createHash } from "node:crypto";
 import { callLlm, type Message } from "../agent/loop";
 import {
   readWorkflowState,
@@ -268,6 +269,9 @@ export async function runRalplanEngine(opts: RalplanEngineOptions = {}): Promise
     ralplanState.plan_path = planPath;
     ralplanState.consensus = gate.verdict;
     ralplanState.consensus_detail = gate.detail.slice(0, 600);
+    if (gate.verdict === "okay") {
+      ralplanState.consensus_hash = createHash("sha256").update(cleanPlan).digest("hex");
+    }
     if (gate.verdict !== "okay") {
       ralplanState.approved = false;
       await writeWorkflowState("ralplan", ralplanState, cwd);

package/src/commands/team.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs/promises";
+import { createHash } from "node:crypto";
 import chalk from "chalk";
 import { PlanSchema, normalizePlanShape, parseYaml } from "../agent/plan";
 import {
@@ -221,6 +222,18 @@ export async function runTeamEngine(opts: TeamEngineOptions = {}): Promise<{ ok:
     return { ok: false, reason: err.message };
   }
 
+  // Round-13: verify the plan's hash matches the consensus hash to prevent silent edits after approval
+  if (planState.consensus_hash) {
+    const currentHash = createHash("sha256").update(planContent).digest("hex");
+    if (currentHash !== planState.consensus_hash) {
+      log(
+        `[ERROR] Plan file has been modified since it was reviewed by the consensus critic.\n` +
+        `  Re-run 'jeo ralplan' to let the critic review the updated plan, then approve and execute again.`
+      );
+      return { ok: false, reason: "Plan file modified since consensus review" };
+    }
+  }
+
   let rawPlan: any;
   try {
     rawPlan = parseYaml(planContent);

package/src/index.ts

@@ -29,3 +29,4 @@ export * from "./commands/deep-interview";
 export * from "./commands/ralplan";
 export * from "./commands/team";
 export * from "./commands/ultragoal";
+export * from "./commands/computer";

package/src/prompts/agents/executor.md

@@ -16,10 +16,12 @@ Turn a bounded task into a working, verified outcome with the smallest correct c
 
 <execution_loop>
 1. Inspect the relevant files and conventions.
-2. Make the minimum change that satisfies the assigned task.
-3. Run focused verification with the available tools.
-4. Remove debug leftovers.
-5. Call `done` only after verification evidence is available.
+2. Decompose a large task into ordered subgoals; finish and verify one before starting the next.
+3. Make the minimum change that satisfies the current subgoal.
+4. Run focused verification with the available tools.
+5. When a step fails, extract the lesson, feed it into the next attempt, and split a stuck subgoal into a smaller one rather than retrying unchanged.
+6. Remove debug leftovers.
+7. Call `done` only after verification evidence is available.
 </execution_loop>
 
 <tool_protocol>

package/src/prompts/skills/ralplan/SKILL.md

@@ -9,3 +9,8 @@ when: When requirements are clear (e.g. from deep-interview) and you need a robu
 Executes a multi-agent critique and planning process to generate a structured implementation plan.
 Combines views from a Planner, an Architect, and a Critic to identify risks, define tasks, and specify files.
 Saves the blueprint for execution.
+
+When the roles disagree, do not collapse the split to a single verdict: record each
+contested decision with the competing options and their rationale, and flag the points
+that need a human judgment call rather than auto-resolving them.
+

package/src/prompts/skills/team/SKILL.md

@@ -9,3 +9,8 @@ when: When you have a blueprint/plan and need to execute the concrete implementa
 Coordinates execution of individual tasks defined in the blueprint.
 Spawns per-task executor subagents or loops to implement code changes.
 Ensures task-level isolation and tracks implementation status.
+
+Each task is a bounded subgoal: decompose large work into ordered subgoals, verify
+one before starting the next, and feed the facts a failed task exposes into the
+inputs of the following task instead of retrying the same approach unchanged.
+

package/src/tui/components/slash.ts

@@ -29,6 +29,7 @@ export const SLASH_COMMAND_DETAILS: readonly SlashCommandInfo[] = [
   { command: "/rename", usage: "/rename <title>", description: "Rename the current session", group: "session" },
   { command: "/resume", usage: "/resume [id]", description: "Resume a saved session in this REPL", group: "session" },
   { command: "/retry", usage: "/retry", description: "Retry the last request", group: "session" },
+  { command: "/undo", usage: "/undo", description: "Undo the last jeo auto-commit and restore the working tree", group: "session" },
   { command: "/history", usage: "/history [n|all]", description: "Re-print the worked turn history (prompts, tool steps, replies) into scrollback", group: "session" },
   { command: "/export", usage: "/export [path] [json]", description: "Export the session transcript to a file", group: "session" },
   { command: "/dump", usage: "/dump", description: "Copy the session transcript to the clipboard", group: "session" },

package/src/util/terminal-restore.ts

@@ -0,0 +1,41 @@
+import { writeSync } from "node:fs";
+
+// Restoring the terminal on an ABNORMAL exit (uncaught exception, unhandled
+// rejection, fatal error) is what keeps the user's shell usable afterwards. The
+// failure mode this guards against: a background `fetch()` stream rejects after a
+// turn ends, Bun reports it as an unhandled rejection and tears the process down
+// WITHOUT running the readline cleanup — leaving stdin in raw mode and bracketed
+// paste enabled, so the shell echoes nothing and never submits a line (the
+// "prints an error and then input is dead" bug).
+//
+// `process.stdout.write` is async/buffered and is NOT guaranteed to flush from an
+// `exit` handler or a crashing tick, so the escape sequences are emitted with the
+// SYNCHRONOUS `writeSync(1, …)` — the only reliable way to hand the terminal back
+// in a sane line-discipline before the process disappears. `setRawMode(false)` is
+// a synchronous ioctl and is safe to call in the same context.
+
+type RawCapableStdin = NodeJS.ReadStream & { isRaw?: boolean; setRawMode?(raw: boolean): void };
+
+let restored = false;
+
+/**
+ * Synchronously return the terminal to cooked input, a visible cursor, and
+ * bracketed-paste OFF. Idempotent and safe to call from crash/exit paths.
+ */
+export function restoreTerminalState(): void {
+  if (restored) return;
+  restored = true;
+  const stdin = process.stdin as RawCapableStdin;
+  try {
+    if (stdin.isTTY && stdin.isRaw && typeof stdin.setRawMode === "function") stdin.setRawMode(false);
+  } catch { /* terminal already gone */ }
+  try {
+    // \x1b[?2004l = disable bracketed paste, \x1b[?25h = show cursor.
+    if (process.stdout.isTTY) writeSync(1, "\x1b[?2004l\x1b[?25h");
+  } catch { /* terminal already gone */ }
+}
+
+/** Test-only: reset the idempotency latch so a fresh restore can be observed. */
+export function resetTerminalRestoreLatch(): void {
+  restored = false;
+}