faberwright 0.3.0

package/dist/markdown.js

@@ -0,0 +1,197 @@
+/**
+ * Terminal markdown renderer — full inline and block set.
+ * Inline: **bold**, *italic* or _italic_, ~~strike~~, `code`, [links](url) as
+ * real OSC 8 hyperlinks. Block: headers, rules, blockquotes, bullet restyle,
+ * box-drawn tables, fenced code with SYNTAX HIGHLIGHTING (small built-in
+ * tokenizer, zero deps). A stateful LineRenderer powers both whole-text
+ * rendering and live line-buffered streaming.
+ */
+const BOLD = "\x1b[1m", NOBOLD = "\x1b[22m";
+const ITAL = "\x1b[3m", NOITAL = "\x1b[23m";
+const STRIKE = "\x1b[9m", NOSTRIKE = "\x1b[29m";
+const UNDER = "\x1b[4m", NOUNDER = "\x1b[24m";
+const DIM = "\x1b[2m", NODIM = "\x1b[22m";
+const CYAN = "\x1b[36m", GREEN = "\x1b[32m", YELLOW = "\x1b[33m", MAGENTA = "\x1b[35m", RESET_FG = "\x1b[39m";
+const stripCodes = (s) => s.replace(/\x1b\[[0-9;]*m/g, "").replace(/\x1b\]8;;[^\x07]*\x07/g, "");
+function inline(s) {
+    s = s.replace(/\*\*([^*]+)\*\*/g, `${BOLD}$1${NOBOLD}`);
+    s = s.replace(/(^|[\s(])\*([^*\s][^*]*)\*(?=[\s).,;:!?]|$)/g, `$1${ITAL}$2${NOITAL}`);
+    s = s.replace(/(^|[\s(])_([^_\s][^_]*)_(?=[\s).,;:!?]|$)/g, `$1${ITAL}$2${NOITAL}`);
+    s = s.replace(/~~([^~]+)~~/g, `${STRIKE}$1${NOSTRIKE}`);
+    s = s.replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, (_m, text, url) => `\x1b]8;;${url}\x07${UNDER}${CYAN}${text}${RESET_FG}${NOUNDER}\x1b]8;;\x07`);
+    s = s.replace(/`([^`]+)`/g, `${CYAN}$1${RESET_FG}`);
+    return s;
+}
+// ------------------------------------------------------ syntax highlighting
+const KEYWORDS = {
+    common: ["if", "else", "for", "while", "return", "break", "continue", "true", "false", "null", "new", "try", "catch", "finally", "throw", "switch", "case", "default", "in", "of", "do"],
+    js: ["function", "const", "let", "var", "class", "extends", "import", "export", "from", "async", "await", "this", "typeof", "interface", "type", "enum", "implements", "undefined", "yield", "static", "readonly", "public", "private", "protected"],
+    py: ["def", "class", "import", "from", "as", "with", "lambda", "None", "True", "False", "and", "or", "not", "is", "elif", "except", "raise", "pass", "yield", "self", "async", "await", "global", "assert", "del"],
+    go: ["func", "package", "import", "type", "struct", "interface", "map", "chan", "go", "defer", "select", "range", "var", "const", "nil"],
+    rs: ["fn", "let", "mut", "pub", "struct", "enum", "impl", "trait", "use", "mod", "match", "Some", "None", "Ok", "Err", "self", "crate", "async", "await"],
+    sh: ["echo", "export", "cd", "then", "fi", "done", "local", "function", "source", "exit"],
+};
+const kwSet = new Set([...KEYWORDS.common, ...KEYWORDS.js, ...KEYWORDS.py, ...KEYWORDS.go, ...KEYWORDS.rs, ...KEYWORDS.sh]);
+/** Line-based highlighter: strings green, comments dim, numbers yellow, keywords magenta. */
+export function highlightLine(line) {
+    let out = "";
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        // comments (rest of line)
+        if (ch === "#" || (ch === "/" && line[i + 1] === "/")) {
+            out += `${DIM}${line.slice(i)}${NODIM}`;
+            return out;
+        }
+        // strings
+        if (ch === '"' || ch === "'" || ch === "`") {
+            let j = i + 1;
+            while (j < line.length && line[j] !== ch)
+                j += line[j] === "\\" ? 2 : 1;
+            out += `${GREEN}${line.slice(i, Math.min(j + 1, line.length))}${RESET_FG}`;
+            i = j + 1;
+            continue;
+        }
+        // words: keywords / numbers / identifiers
+        if (/[A-Za-z0-9_]/.test(ch)) {
+            let j = i;
+            while (j < line.length && /[A-Za-z0-9_]/.test(line[j]))
+                j++;
+            const word = line.slice(i, j);
+            if (kwSet.has(word))
+                out += `${MAGENTA}${word}${RESET_FG}`;
+            else if (/^\d[\d_.]*$/.test(word))
+                out += `${YELLOW}${word}${RESET_FG}`;
+            else
+                out += word;
+            i = j;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+// ------------------------------------------------------------------ tables
+function renderTable(rows) {
+    const CAP = 40;
+    const parsed = [];
+    let headerRows = 1;
+    for (const row of rows) {
+        const cells = row.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+        if (cells.every((c) => /^:?-{2,}:?$/.test(c) || c === "")) {
+            headerRows = parsed.length;
+            continue;
+        }
+        parsed.push(cells);
+    }
+    if (!parsed.length)
+        return rows;
+    const nCols = Math.max(...parsed.map((r) => r.length));
+    const widths = Array.from({ length: nCols }, (_, i) => Math.min(CAP, Math.max(1, ...parsed.map((r) => stripCodes(inline(r[i] ?? "")).length))));
+    const cell = (raw, i, bold) => {
+        let text = inline(raw ?? "");
+        let plain = stripCodes(text);
+        if (plain.length > widths[i]) {
+            text = plain.slice(0, widths[i] - 1) + "…";
+            plain = text;
+        }
+        const pad = " ".repeat(widths[i] - plain.length);
+        return bold ? `${BOLD}${text}${NOBOLD}${pad}` : `${text}${pad}`;
+    };
+    const rule = (l, m, r) => `${DIM}${l}${widths.map((w) => "─".repeat(w + 2)).join(m)}${r}${NODIM}`;
+    const out = [rule("┌", "┬", "┐")];
+    parsed.forEach((r, idx) => {
+        out.push(`${DIM}│${NODIM} ` +
+            widths.map((_, i) => cell(r[i] ?? "", i, idx < headerRows)).join(` ${DIM}│${NODIM} `) +
+            ` ${DIM}│${NODIM}`);
+        if (idx === headerRows - 1 && parsed.length > headerRows)
+            out.push(rule("├", "┼", "┤"));
+    });
+    out.push(rule("└", "┴", "┘"));
+    return out;
+}
+// ------------------------------------------------------------ line renderer
+/**
+ * Stateful renderer: feed complete lines, get rendered lines. Tracks fence
+ * state across lines; buffers table rows until the table ends. Used for both
+ * whole-document rendering and live streaming.
+ */
+export class LineRenderer {
+    inFence = false;
+    tableBuf = [];
+    renderLine(line) {
+        if (/^\s*```/.test(line)) {
+            const flushed = this.flushTable();
+            this.inFence = !this.inFence;
+            return flushed; // fence markers dropped
+        }
+        if (this.inFence)
+            return [...this.flushTable(), `  ${highlightLine(line)}`];
+        if (/^\s*\|.*\|\s*$/.test(line)) {
+            this.tableBuf.push(line);
+            return [];
+        }
+        const pre = this.flushTable();
+        const header = /^(#{1,4})\s+(.*)$/.exec(line);
+        if (header)
+            return [...pre, `${BOLD}${inline(header[2])}${NOBOLD}`];
+        if (/^\s*(---|___|\*\*\*)\s*$/.test(line))
+            return [...pre, `${DIM}${"─".repeat(30)}${NODIM}`];
+        const quote = /^\s*>\s?(.*)$/.exec(line);
+        if (quote)
+            return [...pre, `${DIM}▌ ${NODIM}${ITAL}${inline(quote[1])}${NOITAL}`];
+        const bullet = /^(\s*)[-*]\s+(.*)$/.exec(line);
+        if (bullet)
+            return [...pre, `${bullet[1]}${CYAN}•${RESET_FG} ${inline(bullet[2])}`];
+        return [...pre, inline(line)];
+    }
+    flushTable() {
+        if (!this.tableBuf.length)
+            return [];
+        const t = renderTable(this.tableBuf);
+        this.tableBuf = [];
+        return t;
+    }
+    end() { return this.flushTable(); }
+}
+export function renderMarkdown(text) {
+    const lr = new LineRenderer();
+    const out = [];
+    for (const line of text.split("\n"))
+        out.push(...lr.renderLine(line));
+    out.push(...lr.end());
+    return out.join("\n");
+}
+/**
+ * Streaming renderer: feed arbitrary deltas; emits rendered COMPLETE lines
+ * as they finish (line-buffered — inline markers never split across a line).
+ * flush() renders any trailing partial line at end of turn.
+ */
+export class StreamRenderer {
+    partial = "";
+    lr = new LineRenderer();
+    feed(delta) {
+        this.partial += delta;
+        let out = "";
+        let nl;
+        while ((nl = this.partial.indexOf("\n")) !== -1) {
+            const line = this.partial.slice(0, nl);
+            this.partial = this.partial.slice(nl + 1);
+            for (const r of this.lr.renderLine(line))
+                out += r + "\n";
+        }
+        return out;
+    }
+    flush() {
+        let out = "";
+        if (this.partial) {
+            for (const r of this.lr.renderLine(this.partial))
+                out += r + "\n";
+            this.partial = "";
+        }
+        for (const r of this.lr.end())
+            out += r + "\n";
+        return out;
+    }
+}

package/dist/memory/longTerm.js

@@ -0,0 +1,105 @@
+/**
+ * Long-term memory (persistent, per-project) at .faber/memory.db.
+ *  - memories: fact|decision|preference|gotcha, FTS5 recall (LIKE fallback),
+ *    archive/unarchive/prune lifecycle so growth never poisons recall.
+ *  - file_notes: one evolving summary per file.
+ * Built on node:sqlite -> zero native dependencies.
+ */
+import { DatabaseSync } from "node:sqlite";
+const VALID_KINDS = new Set(["fact", "decision", "preference", "gotcha"]);
+export class LongTermMemory {
+    db;
+    fts = true;
+    constructor(dbPath) {
+        this.db = new DatabaseSync(dbPath);
+        this.db.exec(`CREATE TABLE IF NOT EXISTS memories (
+      id INTEGER PRIMARY KEY, kind TEXT NOT NULL, content TEXT NOT NULL,
+      tags TEXT DEFAULT '', created REAL NOT NULL, archived INTEGER NOT NULL DEFAULT 0)`);
+        try {
+            this.db.exec("ALTER TABLE memories ADD COLUMN archived INTEGER NOT NULL DEFAULT 0");
+        }
+        catch { /* column exists */ }
+        this.db.exec(`CREATE TABLE IF NOT EXISTS file_notes (
+      path TEXT PRIMARY KEY, summary TEXT NOT NULL, updated REAL NOT NULL)`);
+        try {
+            this.db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts
+        USING fts5(content, tags, content='memories', content_rowid='id')`);
+            this.db.exec(`CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+        INSERT INTO memories_fts(rowid, content, tags) VALUES (new.id, new.content, new.tags); END`);
+            this.db.exec(`CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+        INSERT INTO memories_fts(memories_fts, rowid, content, tags)
+        VALUES ('delete', old.id, old.content, old.tags); END`);
+        }
+        catch {
+            this.fts = false;
+        }
+    }
+    remember(kind, content, tags = "") {
+        const k = VALID_KINDS.has(kind) ? kind : "fact";
+        const res = this.db.prepare("INSERT INTO memories (kind, content, tags, created) VALUES (?, ?, ?, ?)").run(k, content.trim(), tags.trim(), Date.now() / 1000);
+        return Number(res.lastInsertRowid);
+    }
+    forget(id) {
+        return this.db.prepare("DELETE FROM memories WHERE id = ?").run(id).changes > 0;
+    }
+    archive(id, archived = true) {
+        return this.db.prepare("UPDATE memories SET archived = ? WHERE id = ?")
+            .run(archived ? 1 : 0, id).changes > 0;
+    }
+    archiveOlderThan(days) {
+        const cutoff = Date.now() / 1000 - days * 86_400;
+        return Number(this.db.prepare("UPDATE memories SET archived = 1 WHERE archived = 0 AND created < ?").run(cutoff).changes);
+    }
+    recall(query, limit = 8) {
+        const terms = (query.match(/[A-Za-z0-9_]{3,}/g) ?? []).slice(0, 12);
+        let rows = [];
+        if (terms.length && this.fts) {
+            try {
+                rows = this.db.prepare(`SELECT m.* FROM memories_fts f JOIN memories m ON m.id = f.rowid
+           WHERE memories_fts MATCH ? AND m.archived = 0 ORDER BY rank LIMIT ?`).all(terms.join(" OR "), limit);
+            }
+            catch {
+                rows = [];
+            }
+        }
+        if (!rows.length && terms.length) {
+            const like = terms.map(() => "content LIKE ?").join(" OR ");
+            rows = this.db.prepare(`SELECT * FROM memories WHERE archived = 0 AND (${like}) ORDER BY created DESC LIMIT ?`).all(...terms.map((t) => `%${t}%`), limit);
+        }
+        if (!rows.length) {
+            rows = this.db.prepare("SELECT * FROM memories WHERE archived = 0 ORDER BY created DESC LIMIT ?").all(limit);
+        }
+        return rows;
+    }
+    allMemories(includeArchived = false) {
+        const where = includeArchived ? "" : "WHERE archived = 0";
+        return this.db.prepare(`SELECT * FROM memories ${where} ORDER BY id`).all();
+    }
+    archivedMemories() {
+        return this.db.prepare("SELECT * FROM memories WHERE archived = 1 ORDER BY id").all();
+    }
+    noteFile(path, summary) {
+        this.db.prepare(`INSERT INTO file_notes (path, summary, updated) VALUES (?, ?, ?)
+       ON CONFLICT(path) DO UPDATE SET summary=excluded.summary, updated=excluded.updated`).run(path, summary.trim(), Date.now() / 1000);
+    }
+    fileNotes(limit = 20) {
+        return this.db.prepare("SELECT * FROM file_notes ORDER BY updated DESC LIMIT ?").all(limit);
+    }
+    renderForPrompt(task) {
+        const parts = [];
+        const memories = this.recall(task);
+        if (memories.length) {
+            parts.push("Relevant long-term memory from previous sessions:");
+            for (const m of memories)
+                parts.push(`- [${m.kind}#${m.id}] ${m.content}`);
+        }
+        const notes = this.fileNotes(10);
+        if (notes.length) {
+            parts.push("", "Known files:");
+            for (const n of notes)
+                parts.push(`- ${n.path}: ${n.summary}`);
+        }
+        return parts.join("\n");
+    }
+    close() { this.db.close(); }
+}

package/dist/memory/sessions.js

@@ -0,0 +1,128 @@
+/**
+ * Session persistence — closes the biggest gap from v0.1.
+ *
+ * Every message is appended to .faber/sessions/<id>.jsonl AS IT HAPPENS
+ * (append-only JSONL = crash-safe: a killed process loses at most the final
+ * partial line, which is skipped on load). `faber --resume` or /resume
+ * reloads the latest session's messages into short-term memory.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export class SessionStore {
+    dir;
+    file;
+    id;
+    constructor(dir, resumeId) {
+        this.dir = dir;
+        this.id = resumeId ?? new Date().toISOString().replace(/[:.]/g, "-");
+        this.file = path.join(dir, `${this.id}.jsonl`);
+    }
+    append(message) {
+        try {
+            fs.appendFileSync(this.file, JSON.stringify(message) + "\n");
+        }
+        catch { /* persistence is best-effort; never break the task over it */ }
+    }
+    load() {
+        if (!fs.existsSync(this.file))
+            return [];
+        const out = [];
+        for (const line of fs.readFileSync(this.file, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* skip torn final line */ }
+        }
+        return out;
+    }
+    static latestId(dir) {
+        if (!fs.existsSync(dir))
+            return undefined;
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl")).sort();
+        const last = files.at(-1);
+        return last?.replace(/\.jsonl$/, "");
+    }
+    static list(dir) {
+        if (!fs.existsSync(dir))
+            return [];
+        return fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl")).sort().map((f) => {
+            const p = path.join(dir, f);
+            const text = fs.readFileSync(p, "utf8");
+            return {
+                id: f.replace(/\.jsonl$/, ""),
+                messages: text.split("\n").filter((l) => l.trim()).length,
+                bytes: fs.statSync(p).size,
+            };
+        });
+    }
+    /** Cheap digest of the most recent session (no LLM call): first ask + last answer. */
+    static lastSessionInfo(dir, excludeId) {
+        const files = fs.existsSync(dir)
+            ? fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl")).sort()
+            : [];
+        const file = files.reverse().find((f) => f.replace(/\.jsonl$/, "") !== excludeId);
+        if (!file)
+            return undefined;
+        const p = path.join(dir, file);
+        const messages = new SessionStore(dir, file.replace(/\.jsonl$/, "")).load();
+        if (!messages.length)
+            return undefined;
+        const textOf = (m) => m.content.filter((b) => b.type === "text").map((b) => b.text).join(" ").trim();
+        const firstUser = messages.find((m) => m.role === "user" && textOf(m));
+        const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant" && textOf(m));
+        const digest = [
+            firstUser ? `asked: "${textOf(firstUser).slice(0, 140)}"` : "",
+            lastAssistant ? `ended: "${textOf(lastAssistant).slice(0, 140)}"` : "",
+        ].filter(Boolean).join(" — ");
+        return {
+            id: file.replace(/\.jsonl$/, ""),
+            messages: messages.length,
+            ageMs: Date.now() - fs.statSync(p).mtimeMs,
+            digest,
+        };
+    }
+    /**
+     * Keyword search across past session transcripts. Scores each message by
+     * term overlap (rarer/longer terms weigh more), returns the best snippets
+     * with surrounding context. Zero dependencies; embeddings can replace the
+     * scorer later behind the same signature.
+     */
+    static search(dir, query, limit = 5, excludeId) {
+        const STOP = new Set([
+            "the", "and", "for", "you", "did", "what", "when", "where", "who", "how",
+            "about", "with", "that", "this", "was", "were", "our", "your", "have",
+            "has", "had", "can", "could", "should", "would", "tell", "last", "time",
+            "conversation", "session", "discuss", "discussed", "talk", "talked",
+            "remember", "ask", "asked", "say", "said", "previous", "earlier",
+        ]);
+        const terms = (query.toLowerCase().match(/[a-z0-9_]{3,}/g) ?? []).filter((t) => !STOP.has(t));
+        if (!terms.length || !fs.existsSync(dir))
+            return [];
+        const hits = [];
+        for (const f of fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl"))) {
+            const id = f.replace(/\.jsonl$/, "");
+            if (id === excludeId)
+                continue;
+            const when = new Date(fs.statSync(path.join(dir, f)).mtimeMs).toISOString().slice(0, 16).replace("T", " ");
+            for (const m of new SessionStore(dir, id).load()) {
+                const text = m.content
+                    .map((b) => b.type === "text" ? b.text : b.type === "tool_result" ? String(b.content) : "")
+                    .join(" ");
+                const lower = text.toLowerCase();
+                let score = 0;
+                for (const t of terms) {
+                    if (lower.includes(t))
+                        score += Math.min(t.length, 10); // longer terms weigh more
+                }
+                if (score > 0) {
+                    // snippet centered on the first matching term
+                    const idx = Math.max(0, lower.indexOf(terms.find((t) => lower.includes(t))) - 80);
+                    hits.push({ session: id, when, role: m.role, snippet: text.slice(idx, idx + 300).trim(), score });
+                }
+            }
+        }
+        return hits.sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+}

package/dist/memory/shortTerm.js

@@ -0,0 +1,56 @@
+export const SUMMARY_MARKER = "[COMPRESSED HISTORY]";
+export function estimateTokens(obj) {
+    try {
+        return Math.max(1, JSON.stringify(obj).length >> 2);
+    }
+    catch {
+        return Math.max(1, String(obj).length >> 2);
+    }
+}
+export class ShortTermMemory {
+    tokenBudget;
+    keepRecent;
+    messages = [];
+    constructor(tokenBudget = 60_000, keepRecent = 12) {
+        this.tokenBudget = tokenBudget;
+        this.keepRecent = keepRecent;
+    }
+    add(m) { this.messages.push(m); }
+    clear() { this.messages = []; }
+    tokens() { return estimateTokens(this.messages); }
+    async maybeCompact(llm, force = false) {
+        if (!force && this.tokens() <= this.tokenBudget)
+            return false;
+        if (this.messages.length <= this.keepRecent)
+            return false;
+        let cut = this.messages.length - this.keepRecent;
+        while (cut > 0 && this.messages[cut].content[0]?.type === "tool_result")
+            cut--;
+        if (cut <= 0)
+            return false;
+        const old = this.messages.slice(0, cut);
+        const recent = this.messages.slice(cut);
+        const summary = await llm.summarize(render(old), "Summarize this coding-agent conversation history. Preserve: the user's goals, " +
+            "decisions made, files created/modified and why, key facts learned about the " +
+            "codebase, and any unresolved problems. Be dense; max 400 words.");
+        this.messages = [
+            { role: "user", content: [{ type: "text", text: `${SUMMARY_MARKER} Earlier context, compressed:\n${summary}` }] },
+            ...recent,
+        ];
+        return true;
+    }
+}
+function render(messages, maxBlock = 1500) {
+    const lines = [];
+    for (const m of messages) {
+        for (const b of m.content) {
+            if (b.type === "text")
+                lines.push(`${m.role}: ${b.text.slice(0, maxBlock)}`);
+            else if (b.type === "tool_use")
+                lines.push(`${m.role} -> tool ${b.name}(${JSON.stringify(b.input).slice(0, 400)})`);
+            else
+                lines.push(`tool result: ${b.content.slice(0, maxBlock)}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/prompt.js

@@ -0,0 +1,80 @@
+import pc from "picocolors";
+let guardFn;
+/** Wired by the CLI: pauses the composed-input pipe while the selector owns stdin. */
+export function setSelectGuard(fn) { guardFn = fn; }
+export async function select(rl, question, options, defaultIndex = 0) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        const menu = options.map((o, i) => `  ${i + 1}) ${o}`).join("\n");
+        const ans = (await rl.question(`${question}\n${menu}\nChoose [1-${options.length}] (default ${defaultIndex + 1}): `)).trim();
+        const n = Number.parseInt(ans, 10);
+        return Number.isInteger(n) && n >= 1 && n <= options.length ? n - 1 : defaultIndex;
+    }
+    console.log(pc.bold(question) + pc.dim("   ↑/↓ then Enter, or 1-9"));
+    return new Promise((resolve) => {
+        let idx = defaultIndex;
+        let firstRender = true;
+        const render = () => {
+            if (!firstRender)
+                process.stdout.write(`\x1b[${options.length}A`);
+            firstRender = false;
+            for (let i = 0; i < options.length; i++) {
+                process.stdout.write("\x1b[2K");
+                process.stdout.write((i === idx ? pc.cyan(`❯ ${options[i]}`) : pc.dim(`  ${options[i]}`)) + "\n");
+            }
+        };
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw ?? false;
+        guardFn?.(true);
+        rl.pause();
+        stdin.setRawMode(true);
+        stdin.resume();
+        const finish = (result) => {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(wasRaw);
+            guardFn?.(false);
+            rl.resume();
+            resolve(result);
+        };
+        const onData = (buf) => {
+            // A chunk may carry several keys (key repeat, paste, piped input) —
+            // tokenize into individual sequences instead of comparing whole-chunk.
+            const s = buf.toString();
+            let done = false;
+            for (let i = 0; i < s.length && !done;) {
+                let key;
+                if (s[i] === "\x1b" && s[i + 1] === "[") {
+                    key = s.slice(i, i + 3);
+                    i += 3;
+                }
+                else {
+                    key = s[i];
+                    i += 1;
+                }
+                if (key === "\x1b[A" || key === "k") {
+                    idx = (idx - 1 + options.length) % options.length;
+                    render();
+                }
+                else if (key === "\x1b[B" || key === "j") {
+                    idx = (idx + 1) % options.length;
+                    render();
+                }
+                else if (key >= "1" && key <= "9" && Number(key) <= options.length) {
+                    idx = Number(key) - 1;
+                    render();
+                    finish(idx);
+                    done = true;
+                }
+                else if (key === "\r" || key === "\n") {
+                    finish(idx);
+                    done = true;
+                }
+                else if (key === "\x03" || key === "\x1b") {
+                    finish(-1);
+                    done = true;
+                }
+            }
+        };
+        render();
+        stdin.on("data", onData);
+    });
+}

package/dist/status.js

@@ -0,0 +1,63 @@
+/**
+ * Live status line: "✳ Working… 14s" while the agent runs (a
+ * heartbeat), finishing with "✳ Worked for 14s". Suspends itself while text
+ * is streaming so it never interleaves with model output. TTY only.
+ */
+import pc from "picocolors";
+const FRAMES = ["✳", "✢", "✳", "✻"];
+export function formatElapsed(ms) {
+    const s = Math.round(ms / 1000);
+    if (s < 90)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    return `${m}m ${s - m * 60}s`;
+}
+export class StatusLine {
+    out;
+    enabled;
+    timer;
+    startedAt = 0;
+    frame = 0;
+    suspended = false;
+    visible = false;
+    constructor(out, enabled) {
+        this.out = out;
+        this.enabled = enabled;
+    }
+    start() {
+        if (!this.enabled)
+            return;
+        this.startedAt = Date.now();
+        this.timer = setInterval(() => this.tick(), 250);
+        this.timer.unref?.();
+    }
+    tick() {
+        if (this.suspended)
+            return;
+        this.frame = (this.frame + 1) % FRAMES.length;
+        this.out.write(`\r\x1b[2K` +
+            pc.dim(`${FRAMES[this.frame]} Working… ${formatElapsed(Date.now() - this.startedAt)}  (ctrl-c to cancel, type to steer)`));
+        this.visible = true;
+    }
+    /** Clear the line before printing real output (tool lines, prompts). */
+    clear() {
+        if (this.visible) {
+            this.out.write("\r\x1b[2K");
+            this.visible = false;
+        }
+    }
+    /** Streaming text owns the terminal; stop redrawing until it finishes. */
+    suspend() { this.clear(); this.suspended = true; }
+    resume() { this.suspended = false; }
+    /** Stop and print the final elapsed summary. */
+    stop() {
+        if (!this.enabled)
+            return;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.clear();
+        if (this.startedAt) {
+            this.out.write(pc.dim(`✳ Worked for ${formatElapsed(Date.now() - this.startedAt)}\n`));
+        }
+    }
+}