@synqa/cli 0.0.0-stage → 1.1.1

package/dist/paths.js

@@ -0,0 +1,243 @@
+import { closeSync, constants, lstatSync, openSync, realpathSync, writeSync } from "node:fs";
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { configDir } from "./config.js";
+
+export class ConfineError extends Error {}
+
+function realOfExisting(p        )         {
+  // Resolve symlinks on the nearest existing ancestor, then re-append the missing tail.
+  // A missing component that is itself a symlink is a dangling link: refuse it, because a
+  // write would follow it to wherever it points.
+  let cur = p;
+  const tail           = [];
+  for (;;) {
+    try {
+      const real = realpathSync(cur);
+      return tail.length ? join(real, ...tail.reverse()) : real;
+    } catch {
+      let isLink = false;
+      try {
+        isLink = lstatSync(cur).isSymbolicLink();
+      } catch {
+        isLink = false;
+      }
+      if (isLink) throw new ConfineError(`path goes through a dangling symlink: ${p}`);
+      const parent = dirname(cur);
+      if (parent === cur) return p;
+      tail.push(cur.slice(parent.length).replace(/^[\\/]+/, ""));
+      cur = parent;
+    }
+  }
+}
+
+// Returns the absolute path if it stays inside root (after ".." and symlink resolution), else throws.
+export function confine(root        , requested        )         {
+  const realRoot = realpathSync(root);
+  const abs = isAbsolute(requested) ? resolve(requested) : resolve(realRoot, requested);
+  const real = realOfExisting(abs);
+  const rel = relative(realRoot, real);
+  if (rel === "") return real;
+  if (rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) {
+    throw new ConfineError(`path escapes the working directory: ${requested}`);
+  }
+  return real;
+}
+
+// Re-confines right before writing and refuses to follow a symlink as the last component.
+export function writeConfined(root        , requested        , content                 )         {
+  const p = confine(root, requested);
+  const fd = openSync(p, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o644);
+  try {
+    writeSync(fd, content);
+  } finally {
+    closeSync(fd);
+  }
+  return p;
+}
+
+// One form for every comparison: NFKC (full-width and compatibility characters become plain ones)
+// and lower case, because a client Mac's file system is case-insensitive: ".ENV" is ".env".
+export function fold(s        )         {
+  return s.normalize("NFKC").toLowerCase();
+}
+
+// The protected tables. isSensitivePath (file tools) and commandTouchesSecrets (shell) are both
+// built from these, so a name added here is protected everywhere at once.
+// Folders whose contents are credentials, matched as any one path segment.
+export const SENSITIVE_DIRS                    = [".ssh", ".aws", ".gnupg", ".kube", ".password-store", ".mozilla", ".azure", "keychains"];
+// Runs of path segments that hold credentials, browser profiles or tokens, matched anywhere in the
+// path (folded). Inside the home folder every dot entry and Library is protected anyway (see
+// homeHidden); these runs also protect copies of such folders elsewhere.
+export const SENSITIVE_RUNS                                   = [
+  [".config", "synqa"], [".config", "gh"], [".config", "hub"], [".config", "gcloud"], [".config", "op"], [".config", "heroku"],
+  [".config", "google-chrome"], [".config", "chromium"], [".config", "bravesoftware"], [".config", "microsoft-edge"],
+  [".docker", "config.json"], [".local", "share", "keyrings"], [".cargo", "credentials.toml"], [".gem", "credentials"],
+  [".terraform.d", "credentials.tfrc.json"], [".m2", "settings.xml"], [".oci", "config"],
+  ["library", "cookies"], ["library", "safari"], ["library", "mail"], ["library", "messages"],
+  ["library", "application support", "google", "chrome"], ["library", "application support", "chromium"],
+  ["library", "application support", "bravesoftware"], ["library", "application support", "microsoft edge"],
+  ["library", "application support", "arc"], ["library", "application support", "firefox"],
+  ["library", "application support", "1password"], ["library", "group containers"],
+];
+// Exact file names that hold secrets (compared folded).
+export const SENSITIVE_NAMES                    = [
+  ".env", ".envrc", ".netrc", ".npmrc", ".pypirc", ".git-credentials", ".dev.vars", "keys.json", "credentials.json", ".yarnrc.yml", ".pgpass", ".my.cnf",
+  "_netrc", ".boto", ".s3cfg", ".vault-token", ".terraformrc", "login data", "cookies", "cookies.binarycookies", "key4.db", "logins.json",
+  ".zsh_history", ".bash_history", ".python_history", ".node_repl_history", ".psql_history", ".mysql_history", ".lesshst",
+  ".yarnrc",
+];
+// File extensions of private keys, certificates with keys, key stores and infrastructure state.
+export const SENSITIVE_EXTENSIONS                    = [
+  "pem", "key", "p12", "p8", "pfx", "jks", "keystore", "ppk", "tfvars", "tfstate", "keychain", "keychain-db", "kdbx",
+];
+// Name patterns, each with the looser form a shell command is checked with. One table for both.
+// `word` rules guess from a word in the name, so they skip source code (src/auth/credentials.ts is
+// code about credentials, not credentials).
+export const SENSITIVE_PATTERNS                                                              = [
+  { name: /^\.env\.|\.env$/, shell: /\.env/ }, // .env.local, prod.env, config.env
+  { name: /\.tfstate(\.|$)/, shell: /\.tfstate/ }, // terraform.tfstate, terraform.tfstate.backup
+  { name: /service[-_]?account.*\.json$/, shell: /service[-_]?account/ },
+  // credential(s) or secret(s) as a word ("client_secret.json", "aws-secrets.yaml"; not "secretary.ts")
+  { name: /(^|[^a-z])(credential|secret)s?([^a-z]|$)/, shell: /credential|secret/, word: true },
+  // shell and REPL histories (.zsh_history, .python_history, history): the name ends in "history"
+  { name: /history$/, shell: /history/ }, // only a name that ends in "history": history.md and chat_history.ts never match
+  { name: /^id_[a-z0-9_]+$/, shell: /\bid_[a-z0-9]/ }, // id_rsa, id_ed25519; id_rsa.pub is not matched
+];
+// Source files: a word rule never applies to these (named secret files still do).
+export const SOURCE_EXTENSIONS                    = [
+  "ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "go", "rs", "rb", "java", "kt", "swift", "c", "cc", "cpp", "h", "cs", "php", "vue", "svelte",
+];
+const SOURCE_RE = new RegExp(`\\.(${SOURCE_EXTENSIONS.join("|")})$`);
+// Source files whose whole stem says secret (secrets.py, credentials.js, client_secret.ts) often
+// hold real keys: the word rules let them through, so read_file asks first and grep and glob skip
+// them. A longer name (secret_manager.go, credentials_form.ts) is ordinary code.
+export const SECRET_STEMS                    = ["secret", "secrets", "credential", "credentials", "client_secret", "client_secrets"];
+
+export function isSecretStemSource(abs        )          {
+  const name = fold(abs.split(sep).join("/")).split("/").pop() ?? "";
+  if (!SOURCE_RE.test(name)) return false;
+  return SECRET_STEMS.includes(name.slice(0, name.lastIndexOf(".")));
+}
+// First segments of SENSITIVE_RUNS that are credential folders in their own right, so a shell
+// command that names the folder (ls .docker, cat ~/.docker/*) asks too. .config and .local hold
+// much else and are covered by the home rule.
+const RUN_FOLDERS = [...new Set(SENSITIVE_RUNS.map((r) => r[0]          ))].filter((f) => f.startsWith(".") && f !== ".config" && f !== ".local");
+const NAME_SET = new Set(SENSITIVE_NAMES);
+const DIR_SET = new Set(SENSITIVE_DIRS);
+const EXAMPLE_SUFFIX = /\.(example|sample|template|dist)$/;
+const EXT_RE = new RegExp(`\\.(${SENSITIVE_EXTENSIONS.map((e) => e.replace(/[.-]/g, "\\$&")).join("|")})$`);
+
+function hasRun(parts          , run                   )          {
+  for (let i = 0; i + run.length <= parts.length; i++) {
+    if (run.every((seg, j) => parts[i + j] === seg)) return true;
+  }
+  return false;
+}
+
+const slashed = (p        ) => fold(p.split(sep).join("/")).replace(/\/+$/, "");
+
+// The home folder, as given and with symlinks resolved, folded.
+function homeForms(home        )           {
+  const out = [slashed(home)];
+  try {
+    out.push(slashed(realpathSync(home)));
+  } catch {
+    // a home that does not exist is compared as given
+  }
+  return out.filter((h) => h !== "" && h !== "/");
+}
+
+// Inside the home folder, everything under a dot entry at its top (~/.zsh_history, ~/.config/**,
+// ~/.cargo/**, any tool's credential store, known or not) and everything under
+// ~/Library is protected. This is the structural rule: it does not depend on naming each store.
+// A project's own dot files (~/proj/.github, ~/proj/.eslintrc) are below a normal folder and stay usable.
+export function homeHidden(abs        , home         = homedir())          {
+  const norm = slashed(abs);
+  for (const h of homeForms(home)) {
+    if (!norm.startsWith(h + "/")) continue;
+    const first = norm.slice(h.length + 1).split("/")[0] ?? "";
+    if (first.startsWith(".") || first === "library") return true;
+  }
+  return false;
+}
+
+// True when `cwd` is the home folder itself.
+export function isHomeDir(cwd        , home         = homedir())          {
+  let real = slashed(cwd);
+  try {
+    real = slashed(realpathSync(cwd));
+  } catch {
+    // compared as given
+  }
+  return homeForms(home).includes(real) || homeForms(home).includes(slashed(cwd));
+}
+
+// Files and folders that hold secrets: the home folder's dot entries and Library (homeHidden),
+// env files, private keys, cloud, package manager and container credentials, keychains, browser
+// profiles, histories, and this CLI's own config (which holds the API key). Names only, no file is
+// opened. Every segment is folded first (see fold). read_file, write_file and edit_file refuse
+// these outright; grep and glob skip them.
+export function isSensitivePath(abs        , cfg         = configDir(), home         = homedir())          {
+  if (homeHidden(abs, home)) return true;
+  const norm = slashed(abs);
+  const parts = norm.split("/").filter(Boolean);
+  if (parts.some((d) => DIR_SET.has(d))) return true;
+  if (SENSITIVE_RUNS.some((run) => hasRun(parts, run))) return true;
+  const c = slashed(cfg);
+  if (c && (norm === c || norm.startsWith(c + "/"))) return true;
+  const name = parts[parts.length - 1] ?? "";
+  // Remotes can hold tokens: .git/config, .git/config.worktree, .git/worktrees/<name>/config, at any depth.
+  if (parts.slice(0, -1).includes(".git") && (name === "config" || name.startsWith("config."))) return true;
+  if (NAME_SET.has(name)) return true;
+  if (EXAMPLE_SUFFIX.test(name)) return false;
+  if (EXT_RE.test(name)) return true;
+  const source = SOURCE_RE.test(name);
+  return SENSITIVE_PATTERNS.some((x) => x.name.test(name) && !(x.word && source));
+}
+
+const escRe = (s        ) => s.replace(/[.*+?^${}()|[\]\\/-]/g, "\\$&");
+
+// Names a shell command can use to reach a secret, including globs that expand to them, built from
+// the same tables as isSensitivePath. Heuristic: it makes an unattended (--yes) command ask when it
+// looks at secrets, it does not make bash safe.
+const SECRET_WORDS                    = [
+  ...SENSITIVE_DIRS.map((d) => new RegExp(escRe(d))),
+  ...SENSITIVE_RUNS.map((r) => new RegExp(r.map(escRe).join("/"))),
+  ...SENSITIVE_NAMES.map((n) => new RegExp(escRe(n))),
+  ...RUN_FOLDERS.map((f) => new RegExp(`${escRe(f)}\\b`)),
+  new RegExp(`\\.(${SENSITIVE_EXTENSIONS.map(escRe).join("|")})\\b`),
+  ...SENSITIVE_PATTERNS.map((x) => x.shell),
+  /\.git\/config/,
+  // Dumping the environment (where tokens live): printenv, env or export -p or set with no arguments.
+  /\bprintenv\b/, /(^|[;&|(]\s*)env\s*($|[;&|)>])/, /\bexport\s+-p\b/, /(^|[;&|(]\s*)(set|declare\s+-x)\s*($|[;&|)>])/,
+  /\.config\/synqa/, /synqa\/config/,
+  /(^|[\s/])\.[\w.-]*[*?[]/, // a dot glob such as .e* or .*
+  /~\/?\./, /\$\{?home\}?\/?\./, /~\/library/, /\$\{?home\}?\/library/, // the home folder's dot entries and Library
+  /\bsecurity\s+(find|dump|export)-/, /\.binarycookies/,
+];
+
+export function commandTouchesSecrets(command        , cfg         = configDir())          {
+  // Escapes that can spell any name ($'\x2eenv', \056, printf '\x2e'): always ask.
+  if (/\$'|\\x[0-9a-f]{2}|\\[0-7]{3}|\\u[0-9a-f]{4}/i.test(command)) return true;
+  // Quotes and backslashes are dropped first so .e""nv and .\env read as .env.
+  const c = fold(command).replace(/["'\\`]/g, "");
+  if (SECRET_WORDS.some((re) => re.test(c))) return true;
+  const dir = fold(cfg);
+  return dir !== "" && c.includes(dir);
+}
+
+// The one start folder this CLI refuses: the filesystem root, where the working directory would be
+// the whole disk. Anywhere else, the home folder included, it starts like any other coding CLI;
+// secrets there are protected by isSensitivePath, not by refusing to start. Returns the reason,
+// or undefined when the folder is fine.
+export function unsafeStartDir(cwd        )                     {
+  let real        ;
+  try {
+    real = realpathSync(cwd);
+  } catch {
+    return undefined;
+  }
+  if (real === parse(real).root) return "the filesystem root";
+  return undefined;
+}

package/dist/prompt.js

@@ -0,0 +1,330 @@
+// The interactive prompt: the slash command table, the inline command menu, /help, and the frame
+// drawn around the input line (a rule above, a rule, the status line and key hints below).
+//
+// The frame and menu use only node:readline keypress events, no extra package. Keys from the
+// terminal are read here and forwarded to readline through a PassThrough, so the menu can take the
+// arrow keys, Tab, Enter and Esc for itself while it is open. The only control sequences written
+// are the fixed strings in this file (cursor up and column, erase line); every piece of text is our
+// own table or the user's own typing, already shown by readline.
+import { PassThrough } from "node:stream";
+import { emitKeypressEvents } from "node:readline";
+                                                        
+import { bold, dim, stone, terracottaBold } from "./theme.js";
+import { fit, oneLine, pad, PLACEHOLDER, rule, styleOf, textWidth } from "./ui.js";
+                                  
+
+                                                                                                                   
+
+export const SLASH_COMMANDS                          = [
+  { name: "/model", args: "blink|sonata|aeon", desc: "Switch tier", group: "Session" },
+  { name: "/effort", args: "default|low|medium", desc: "Set reasoning effort", group: "Session" },
+  { name: "/status", desc: "Tier, routing, tokens, credit and weekly pool", group: "Session" },
+  { name: "/compact", desc: "Summarize the conversation to save context", group: "Session" },
+  { name: "/clear", desc: "Start a fresh conversation", group: "Session" },
+  { name: "/init", desc: "Write a starter AGENTS.md for this project", group: "Project" },
+  { name: "/undo", desc: "Revert the last file the agent wrote", group: "Project" },
+  { name: "/help", desc: "Show commands and keys", group: "General" },
+  { name: "/exit", desc: "Leave Synqa", group: "General" },
+];
+
+// Commands whose name starts with what was typed, then those that contain it.
+export function matchCommands(typed        )                 {
+  const t = typed.toLowerCase();
+  if (!t.startsWith("/")) return [];
+  const starts = SLASH_COMMANDS.filter((c) => c.name.startsWith(t));
+  const contains = SLASH_COMMANDS.filter((c) => !c.name.startsWith(t) && c.name.includes(t.slice(1)));
+  return [...starts, ...contains];
+}
+
+function distance(a        , b        )         {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array        (b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) (d[0]            )[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const row = d[i]            ;
+      const prev = d[i - 1]            ;
+      row[j] = Math.min((prev[j]          ) + 1, (row[j - 1]          ) + 1, (prev[j - 1]          ) + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+  }
+  return (d[a.length]            )[b.length]          ;
+}
+
+// One line for an unknown command, with the nearest name when one is close.
+export function unknownCommandHint(word        )         {
+  const w = oneLine(word).toLowerCase().slice(0, 40);
+  const near = matchCommands(w)[0] ?? SLASH_COMMANDS
+    .map((c) => ({ c, d: distance(w, c.name) }))
+    .filter((x) => x.d <= 2)
+    .sort((a, b) => a.d - b.d)[0]?.c;
+  return near ? `Unknown command ${w}. Did you mean ${near.name}? Type / to see all commands.` : `Unknown command ${w}. Type / to see all commands.`;
+}
+
+const usage = (c              ) => (c.args ? `${c.name} ${c.args}` : c.name);
+
+// /help: grouped, aligned, names bold and descriptions dim.
+export function renderHelp(ui    )           {
+  const s = styleOf(ui);
+  const room = ui.columns - 1;
+  const w = Math.max(...SLASH_COMMANDS.map((c) => usage(c).length)) + 3;
+  const out           = [];
+  for (const group of ["Session", "Project", "General"]         ) {
+    out.push(stone(s, group));
+    for (const c of SLASH_COMMANDS.filter((x) => x.group === group)) {
+      const u = usage(c);
+      if (4 + w >= room) { out.push("  " + bold(s, fit(u, room - 2, ui))); continue; }
+      out.push("  " + bold(s, c.name) + (c.args ? dim(s, " " + c.args) : "") + " ".repeat(w - u.length) + dim(s, fit(c.desc, room - 2 - w, ui)));
+    }
+  }
+  out.push(dim(s, fit("Type / for the command menu: arrows move, Tab or Enter completes, Esc closes.", room, ui)));
+  return out;
+}
+
+export const SLASH_HELP = renderHelp({ color: false, unicode: true, tty: false, columns: 100 }).join("\n");
+
+const MENU_MAX = 8;
+
+// The menu under the input: the selected row has a terracotta pointer and a bold name.
+export function renderMenu(items                         , selected        , ui    )           {
+  const s = styleOf(ui);
+  const room = ui.columns - 1;
+  const pointer = ui.unicode ? "❯" : ">";
+  const nameW = Math.max(...SLASH_COMMANDS.map((c) => c.name.length)) + 2;
+  const start = Math.max(0, Math.min(selected - MENU_MAX + 1, items.length - MENU_MAX));
+  return items.slice(start, start + MENU_MAX).map((c, i) => {
+    const on = start + i === selected;
+    const lead = on ? terracottaBold(s, pointer) + " " : "  ";
+    const name = pad(c.name, nameW);
+    const descRoom = room - 2 - nameW;
+    const desc = descRoom > 4 ? fit(c.desc, descRoom, ui) : "";
+    if (descRoom <= 4) return lead + (on ? terracottaBold(s, fit(c.name, room - 2, ui)) : fit(c.name, room - 2, ui));
+    return lead + (on ? terracottaBold(s, name) + stone(s, desc) : name + dim(s, desc));
+  });
+}
+
+// ---------------------------------------------------------------- the frame
+
+                                                                                                 
+                                                                                                           
+                                                                       
+
+const ESC = "\x1b";
+
+// Draws below the input line and routes keys. One per session, TTY only.
+export class PromptFrame {
+           input                                                                     ;
+          rl                       ;
+          shown = 0; // rows drawn below the input line
+          active = false; // the main prompt is being answered (not a y/N question, not a turn)
+          selected = 0;
+          dismissed = false;
+          placeholder = false;
+          lastLine = "";
+          started = false;
+          pasting = false; // between the terminal's paste-start and paste-end marks
+          ctrlC = false; // Ctrl+C was pressed (typed, not pasted)
+
+  // True once the person pressed Ctrl+C. An end of input is not an interrupt.
+  get interrupted()          {
+    return this.ctrlC;
+  }
+          onKey = (s                    , key                 ) => this.key(s, key);
+
+          stdin           ;
+          out          ;
+          ui    ;
+          below                ; // the status lines
+          promptWidth        ;
+
+          paste         ; // bracketed paste is switched on (stdout is the terminal)
+          pasteOk = false; // a prompt that takes typed text is open: pasted text is typed in
+
+  // `opts.paste` false when stdout is not the terminal (a piped one-shot): the escape that switches
+  // bracketed paste on would land in the output instead.
+  constructor(stdin           , out          , ui    , below                , promptWidth        , opts                      = {}) {
+    this.paste = opts.paste ?? true;
+    this.stdin = stdin;
+    this.out = out;
+    this.ui = ui;
+    this.below = below;
+    this.promptWidth = promptWidth;
+    const pass = new PassThrough()                                                                       ;
+    pass.isTTY = true;
+    pass.setRawMode = () => {};
+    this.input = pass;
+  }
+
+  start(rl           )       {
+    this.rl = rl;
+    emitKeypressEvents(this.stdin);
+    this.stdin.setRawMode?.(true);
+    this.stdin.on("keypress", this.onKey);
+    this.stdin.resume();
+    // Bracketed paste: the terminal marks pasted text, so a pasted newline is not an Enter.
+    if (this.paste) this.out.write(`${ESC}[?2004h`);
+    this.started = true;
+    rl.on("close", () => this.stop());
+  }
+
+  // Gives the terminal back: raw mode and bracketed paste off. Safe to call any number of times.
+  stop()       {
+    if (!this.started) return;
+    this.started = false;
+    this.stdin.off("keypress", this.onKey);
+    if (this.paste) this.out.write(`${ESC}[?2004l`);
+    this.stdin.setRawMode?.(false);
+    this.stdin.pause();
+    this.input.end();
+  }
+
+          line()         {
+    return (this.rl                                            )?.line ?? "";
+  }
+
+          menuItems()                 {
+    const l = this.line();
+    if (!this.active || this.dismissed || !l.startsWith("/") || /\s/.test(l)) return [];
+    return matchCommands(l);
+  }
+
+  // The rule above the prompt; then the prompt itself is asked by the caller.
+  async ask(promptText        )                  {
+    const rl = this.rl             ;
+    this.out.write(rule(this.ui) + "\n");
+    this.active = true;
+    this.pasteOk = true;
+    this.selected = 0;
+    this.dismissed = false;
+    this.lastLine = "";
+    const answer = rl.question(promptText);
+    this.draw();
+    try {
+      return await answer;
+    } finally {
+      this.active = false;
+      this.pasteOk = false;
+    }
+  }
+
+  // A plain prompt with no frame or menu (an ASCII terminal): pasted text is typed in, nothing drawn.
+  async askPlain(promptText        )                  {
+    this.pasteOk = true;
+    try {
+      return await (this.rl             ).question(promptText);
+    } finally {
+      this.pasteOk = false;
+    }
+  }
+
+  // Erases what is drawn below the input line (before Enter, so the transcript stays clean).
+  clear()       {
+    if (this.shown === 0) return;
+    let s = "";
+    for (let i = 0; i < this.shown; i++) s += `\r\n${ESC}[2K`;
+    s += `${ESC}[${this.shown}A${ESC}[${this.cursorCol()}G`;
+    this.out.write(s);
+    this.shown = 0;
+  }
+
+          cursorCol()         {
+    const pos = (this.rl                                                                                  )?.getCursorPos?.();
+    return (pos?.cols ?? this.promptWidth + textWidth(this.line())) + 1;
+  }
+
+          cols()         {
+    return this.ui.columns;
+  }
+
+  // What goes under the input: the rule, then the menu or the status lines.
+  belowLines()           {
+    const items = this.menuItems();
+    if (this.selected >= items.length) this.selected = 0;
+    const body = items.length ? renderMenu(items, this.selected, this.ui) : this.below();
+    return [rule(this.ui), ...body];
+  }
+
+  draw()       {
+    if (!this.active) return;
+    const l = this.line();
+    // A line that wraps would put the frame in the wrong place: draw nothing until it is short.
+    if (this.promptWidth + textWidth(l) >= this.cols() - 1) { this.clear(); return; }
+    const lines = this.belowLines();
+    const n = Math.max(lines.length, this.shown);
+    let s = "";
+    for (let i = 0; i < n; i++) s += `\r\n${ESC}[2K` + (lines[i] ?? "");
+    const col = this.cursorCol();
+    s += `${ESC}[${n}A${ESC}[${col}G`;
+    if (l === "") {
+      s += dim(styleOf(this.ui), fit(PLACEHOLDER, this.cols() - 1 - col, this.ui)) + `${ESC}[${col}G`;
+      this.placeholder = true;
+    } else if (this.placeholder) {
+      s = `${ESC}[K` + s;
+      this.placeholder = false;
+    }
+    this.out.write(s);
+    this.shown = lines.length;
+  }
+
+          forward(seq        )       {
+    this.input.write(seq);
+  }
+
+          replaceLine(text        )       {
+    // ctrl+e (end of line), ctrl+u (delete to the start), then the new text.
+    this.forward("\x05\x15" + text);
+  }
+
+          key(s                    , key                 )       {
+    const seq = key?.sequence ?? s ?? "";
+    if (key?.name === "paste-start") { this.pasting = true; return; }
+    if (key?.name === "paste-end") { this.pasting = false; this.after(); return; }
+    if (!this.pasting && seq === "\x03") this.ctrlC = true;
+    if (this.pasting) {
+      // Pasted text is never a key press. While a y/N question (or a turn) holds the input it is
+      // dropped, so a pasted "y" and newline cannot approve anything. At the prompt it is typed
+      // as text, with each newline as a space so a paste never sends the line.
+      if (!this.pasteOk) return;
+      const name = key?.name;
+      this.forward(name === "return" || name === "enter" || seq === "\r" || seq === "\n" ? " " : seq);
+      return;
+    }
+    if (!this.active) { this.forward(seq); return; }
+    const items = this.menuItems();
+    const name = key?.name;
+    // A lone Esc closes the menu (node reports it with meta set on some versions).
+    if (items.length && name === "escape") { this.dismissed = true; this.draw(); return; }
+    if (items.length && !key?.ctrl && !key?.meta) {
+      if (name === "up" || name === "down") {
+        this.selected = (this.selected + (name === "up" ? -1 : 1) + items.length) % items.length;
+        this.draw();
+        return;
+      }
+      const pick = items[this.selected]                ;
+      if (name === "tab") { this.replaceLine(pick.args ? pick.name + " " : pick.name); this.after(); return; }
+      if (name === "return" || name === "enter") {
+        if (pick.args && this.line().toLowerCase() !== pick.name) { this.replaceLine(pick.name + " "); this.after(); return; }
+        this.clear();
+        this.replaceLine(pick.name);
+        this.forward("\r");
+        return;
+      }
+    }
+    if (name === "return" || name === "enter") { this.clear(); this.forward(seq); return; }
+    if (name === "escape" && this.line() === "") return; // nothing to dismiss; a lone Esc is ignored
+    this.forward(seq);
+    this.after();
+  }
+
+  // Readline handles the forwarded keys on the next tick; redraw after it has.
+          after()       {
+    setImmediate(() => {
+      const l = this.line();
+      if (l !== this.lastLine) { this.dismissed = false; this.selected = 0; }
+      this.lastLine = l;
+      this.draw();
+    });
+  }
+
+  redraw()       {
+    this.draw();
+  }
+}

package/dist/sanitize.js

@@ -0,0 +1,53 @@
+// Model-controlled text must never reach the terminal as control sequences.
+
+// OSC (ESC ] ... BEL or ST), CSI (ESC [ ... final byte), and any other two-byte ESC sequence.
+const ESC_SEQ = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?|\x1b\[[0-?]*[ -/]*[@-~]?|\x1b[@-_]?/g;
+// C0 except \n and \t, DEL, and C1.
+const CONTROL = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+// Bidi controls and invisible characters that can reorder or hide text, as inclusive code point
+// ranges: U+061C, U+200B-200F, U+2028-2029, U+202A-202E, U+2060-2064, U+2066-2069, U+FEFF. Built from numbers so this
+// source file itself holds none of them.
+const INVISIBLE_RANGES                                           = [
+  [0x061c, 0x061c],
+  [0x200b, 0x200f],
+  [0x2028, 0x2029],
+  [0x202a, 0x202e],
+  [0x2060, 0x2064],
+  [0x2066, 0x2069],
+  [0xfeff, 0xfeff],
+];
+const hex4 = (n        ) => n.toString(16).padStart(4, "0");
+const INVISIBLE = new RegExp(
+  "[" + INVISIBLE_RANGES.map(([a, b]) => `\\u${hex4(a)}-\\u${hex4(b)}`).join("") + "]",
+  "g",
+);
+
+export function sanitize(s        )         {
+  return s.replace(ESC_SEQ, "").replace(CONTROL, "").replace(INVISIBLE, "");
+}
+
+// For text the user must judge before approving (shell commands, paths): show escapes literally.
+export function visibleEscapes(s        )         {
+  return s
+    .replace(/[\x00-\x08\x0a-\x1f\x7f-\x9f]/g, (c) => {
+      if (c === "\n") return "\\n";
+      if (c === "\r") return "\\r";
+      return "\\x" + c.charCodeAt(0).toString(16).padStart(2, "0");
+    })
+    .replace(INVISIBLE, (c) => "\\u" + hex4(c.charCodeAt(0)));
+}
+
+// Untrusted text that goes inside a fenced block of the prompt (AGENTS.md, the compact summary).
+// Order matters: NFKC first (full-width and compatibility forms become plain ones), then every
+// format and default-ignorable character is removed (soft hyphen, zero-width and bidi marks, the
+// word joiner range, BOM: they could split a tag so a match misses it), then the cap, so the
+// normalization cannot grow the text past it, and last every "<" becomes "\u2039" so no tag, in any
+// spelling, can open or close the fence.
+export function fenceText(s        , max        )         {
+  return s
+    .normalize("NFKC")
+    .replace(/[\p{Cf}\u00ad\u034f\u115f\u1160\u17b4\u17b5\u180b-\u180f\u2060-\u206f\u3164\ufe00-\ufe0f\uffa0]/gu, "")
+    .trim()
+    .slice(0, max)
+    .replace(/</g, "\u2039");
+}