agent-from-zero 0.27.0 → 0.28.0

package/dist/markdown.js

@@ -0,0 +1,152 @@
+import { Marked } from "marked"; // the parser
+import { markedTerminal } from "marked-terminal"; // the ANSI renderer
+import Table from "cli-table3"; // box-drawing table (borders + padding)
+import wrapAnsi from "wrap-ansi"; // ANSI- and CJK-aware line wrapping
+import chalk from "chalk"; // our one color source — keep the theme consistent with ui.ts
+import { displayWidth } from "./editor.js"; // CJK-/ANSI-aware display width (shared with the line editor)
+// Why a library here, not hand-rolled? Markdown→terminal is a solved, fiddly
+// problem (CJK-aware table widths, nested lists, code fences, link rewriting).
+// The agent's *core* is hand-written on purpose; this is pure presentation, so
+// we lean on `marked` + `marked-terminal` and spend our effort on the streaming
+// glue instead. The model speaks markdown; without this the screen shows raw
+// `##`, `**`, and `|---|` — exactly the ugliness this module removes.
+// ---- responsive tables ------------------------------------------------------
+// marked-terminal's `width` does NOT size tables — a wide table overflows and the
+// terminal hard-wraps it into garbage. So we render tables ourselves: shrink the
+// columns to fit the window, wrap each cell (CJK-aware, no truncation), and let
+// cli-table3 draw the box. This is what makes a table adapt to the window size.
+// Per-column CONTENT widths that fit `maxWidth` once borders/padding are paid for.
+// Start from each column's natural width, then repeatedly shave the widest until
+// the row fits — so narrow columns keep their size and the roomy ones give first.
+function tableColumnWidths(header, rows, maxWidth) {
+    const n = header.length;
+    const natural = header.map((h, i) => Math.max(displayWidth(h), ...rows.map((r) => displayWidth(r[i] ?? ""))));
+    const budget = maxWidth - (n + 1) - 2 * n; // n+1 borders, 2 cols of padding per column
+    const widths = natural.slice();
+    const MIN = 4; // never shrink a column below this many content columns
+    while (widths.reduce((a, b) => a + b, 0) > budget) {
+        const widest = widths.indexOf(Math.max(...widths));
+        if (widths[widest] <= MIN)
+            break; // can't shrink further — let it overflow rather than vanish
+        widths[widest]--;
+    }
+    return widths;
+}
+// Draw one table, wrapped to fit `maxWidth`. Cells are pre-wrapped with wrap-ansi
+// (which counts CJK as 2 and keeps ANSI styles intact across line breaks), then
+// handed to cli-table3 with wordWrap OFF — cli-table3's own wrap mis-measures CJK.
+function renderTable(header, rows, maxWidth) {
+    const content = tableColumnWidths(header, rows, maxWidth);
+    const wrapRow = (cells) => cells.map((c, i) => wrapAnsi(c ?? "", content[i], { hard: true, trim: false }));
+    const t = new Table({
+        head: wrapRow(header),
+        colWidths: content.map((w) => w + 2), // cli-table3 widths include the 2 padding columns
+        wordWrap: false, // we already wrapped — cli-table3 would mis-wrap CJK
+        style: { head: [], border: [] }, // no extra colour; keep the dim theme from the caller
+    });
+    for (const r of rows)
+        t.push(wrapRow(r));
+    return t.toString();
+}
+// The terminal theme, matched to ui.ts (cyan headers, yellow code, dim borders).
+function renderer(width) {
+    return markedTerminal({
+        width, // wrap paragraphs/tables to this many columns
+        reflowText: true, // re-wrap long paragraphs to `width` instead of one long line
+        tab: 2, // list indentation
+        showSectionPrefix: false, // drop the literal "## " in front of headings
+        firstHeading: chalk.cyan.bold,
+        heading: chalk.cyan.bold,
+        code: chalk.yellow, // fenced code block
+        codespan: chalk.cyan, // `inline code`
+        blockquote: chalk.gray.italic,
+        strong: chalk.bold,
+        em: chalk.italic,
+        del: chalk.dim.strikethrough,
+        link: chalk.cyan.underline,
+        href: chalk.cyan.underline,
+        paragraph: (s) => s,
+    });
+}
+// Render a complete markdown string to ANSI. Pure (width injectable), so tests
+// can assert on the output without a real terminal. A fresh Marked per call
+// keeps width overridable and avoids leaking global parser state.
+export function renderMarkdown(md, width = termWidth()) {
+    const w = Math.max(20, width);
+    const m = new Marked();
+    m.use(renderer(w));
+    // Override the table renderer AFTER marked-terminal so ours wins: render each
+    // cell's inline markdown to ANSI (parseInline), then lay the table out to fit w.
+    m.use({
+        renderer: {
+            table(token) {
+                const header = token.header.map((c) => this.parser.parseInline(c.tokens));
+                const rows = token.rows.map((r) => r.map((c) => this.parser.parseInline(c.tokens)));
+                return renderTable(header, rows, w) + "\n";
+            },
+        },
+    });
+    const out = m.parse(md, { async: false });
+    return out.replace(/\s+$/g, ""); // trim the trailing blank lines marked-terminal adds
+}
+function termWidth() {
+    return (process.stdout.columns || 80) - 4; // leave room for our 2-col gutter + margin
+}
+// ---- streaming glue ---------------------------------------------------------
+// marked renders a WHOLE document; the model streams tokens. The bridge: buffer
+// text and flush one markdown *block* at a time, where a block ends at a blank
+// line that is NOT inside a ``` fence. So a paragraph, heading, list, or table
+// renders the moment it's complete — you keep the live "it's typing" feel, but
+// every block lands fully formatted (a table needs all its rows to align).
+export class MarkdownStream {
+    write;
+    opts;
+    buf = ""; // text not yet flushed
+    firstLine = true; // the very first printed line gets the ⏺ prefix
+    constructor(write, // where rendered lines go (stdout in prod)
+    opts = {}) {
+        this.write = write;
+        this.opts = opts;
+    }
+    // Feed streamed tokens; flushes any blocks that are now complete.
+    push(chunk) {
+        this.buf += chunk;
+        for (let i = this.boundary(); i >= 0; i = this.boundary()) {
+            const block = this.buf.slice(0, i);
+            this.buf = this.buf.slice(i).replace(/^\n+/, ""); // drop the blank-line separator
+            if (block.trim())
+                this.emit(block);
+        }
+    }
+    // End of answer: render whatever's left as the final block.
+    end() {
+        if (this.buf.trim())
+            this.emit(this.buf);
+        this.buf = "";
+    }
+    // Index of the first blank-line boundary that sits OUTSIDE a code fence, or -1.
+    // Counting fence markers before the candidate tells us if we're inside one.
+    boundary() {
+        for (let from = 0;;) {
+            const i = this.buf.indexOf("\n\n", from);
+            if (i < 0)
+                return -1;
+            const fences = (this.buf.slice(0, i).match(/^[ \t]*(```|~~~)/gm) || []).length;
+            if (fences % 2 === 0)
+                return i; // even number of fences → not inside one
+            from = i + 2; // this blank line is inside a fence; keep looking
+        }
+    }
+    // Render one block and print it, with a left gutter so wrapped lines align
+    // under the ⏺ marker (first physical line uses firstPrefix, the rest indent).
+    emit(md) {
+        const indent = this.opts.indent ?? "  ";
+        const rendered = renderMarkdown(md, (process.stdout.columns || 80) - indent.length - 1);
+        const out = rendered.split("\n").map((ln) => {
+            const prefix = this.firstLine ? (this.opts.firstPrefix ?? indent) : indent;
+            this.firstLine = false;
+            return prefix + ln;
+        });
+        this.write(out.join("\n") + "\n");
+    }
+}

package/dist/permissions.js

@@ -97,11 +97,24 @@ function planSafe(toolName, verdict) {
         case "read_file":
         case "search":
         case "task": // the sub-agent's own calls hit this same gate, still in plan mode
+        case "spawn_teammate": // a teammate's own calls hit this same gate (plan mode still blocks their writes)
+        case "send_message": // coordination only — changes nothing on disk
+        case "request_shutdown": // team protocol (Day 39): coordination, no side effects
+        case "request_plan":
+        case "review_plan":
+        case "submit_plan":
+        case "create_task": // task board (Day 40): touches the internal board, not the user's project
+        case "list_tasks":
+        case "claim_task":
+        case "complete_task":
         case "ask_user": // asking the user a question is safe in plan mode — it doesn't change anything
         case "skill": // loading a skill's instructions is read-only; what it does is gated per-call
+        case "todo_write": // planning is exactly what plan mode is FOR — never block it
+        case "bash_output": // reading a background task's output observes, never mutates
         case "exit_plan_mode": // the way OUT of plan mode must never be blocked by plan mode
             return true;
         case "run_bash":
+        case "run_bash_background":
             return verdict.decision === "allow"; // only the read-only commands the classifier cleared
         default:
             return false; // write_file, edit_file, MCP and unknown tools: all mutate-or-unknown
@@ -144,6 +157,29 @@ function basePermission(toolName, argsJson) {
             // Spawning a sub-agent is orchestration, not action: every tool the
             // sub-agent uses goes through this same gate individually.
             return { decision: "allow", reason: "sub-agent tools are gated individually", summary: "task" };
+        case "spawn_teammate":
+            // Same as task: spawning is orchestration. Each teammate's own tool calls
+            // pass through this gate; a teammate's non-interactive policy auto-proceeds
+            // on writes but a hard DENY here still stands (deny always wins).
+            return { decision: "allow", reason: "teammate tools are gated individually", summary: "spawn_teammate" };
+        case "send_message":
+            // Dropping a message in another agent's mailbox has no filesystem effect on
+            // the user's project — it is pure team coordination.
+            return { decision: "allow", reason: "team coordination, no side effects", summary: "send_message" };
+        case "request_shutdown":
+        case "request_plan":
+        case "review_plan":
+        case "submit_plan":
+            // Team protocol messages (Day 39) — request/response coordination over the
+            // mailbox. No filesystem effect; the work they gate still passes the gate.
+            return { decision: "allow", reason: "team protocol, no side effects", summary: toolName };
+        case "create_task":
+        case "list_tasks":
+        case "claim_task":
+        case "complete_task":
+            // Task board (Day 40) — bookkeeping on the internal board, not the user's
+            // project. The actual work a claimed task drives still passes this gate.
+            return { decision: "allow", reason: "task board, no project side effects", summary: toolName };
         case "ask_user":
             // Asking the user a question has no side effects — it's the safest thing
             // the model can do. Never gate it behind an approval prompt.
@@ -152,6 +188,9 @@ function basePermission(toolName, argsJson) {
             // Loading a skill just returns instructions; whatever the skill then DOES
             // goes through this same gate, call by call. Loading itself is free.
             return { decision: "allow", reason: "loads instructions, no side effects", summary: "skill" };
+        case "todo_write":
+            // Writing the plan touches nothing but in-memory state and the screen.
+            return { decision: "allow", reason: "updates the plan, no side effects", summary: "todo_write" };
         case "read_file": {
             const p = args.path ?? ""; // the file the model wants to read
             if (SECRET_FILE_RE.test(path.resolve(p))) {
@@ -173,16 +212,25 @@ function basePermission(toolName, argsJson) {
             }
             return { decision: "ask", reason: "writes to your filesystem", summary: p }; // normal writes need a human yes
         }
-        case "run_bash": {
+        case "run_bash":
+        case "run_bash_background": {
+            // Backgrounding changes WHEN output comes back, never WHAT runs — so a
+            // background command gets the exact same input-aware analysis as a
+            // foreground one. The danger is in the command, not the blocking.
             const verdict = checkBash(args.command ?? ""); // bash gets input-aware analysis
             // "Don't ask again for run_bash this session" (chosen in the approval menu)
             // upgrades an ASK to ALLOW — but a hard DENY (rm -rf /, .git, .env…) always
-            // stands. Convenience never overrides the no-fly rules.
-            if (verdict.decision === "ask" && CONFIG.permissions.allow.includes("tool:run_bash")) {
+            // stands. Convenience never overrides the no-fly rules. A grant for either
+            // shell tool covers the other: the command is what was vouched for.
+            if (verdict.decision === "ask" && (CONFIG.permissions.allow.includes(`tool:${toolName}`) || CONFIG.permissions.allow.includes("tool:run_bash"))) {
                 return { decision: "allow", reason: "bash pre-approved for this session", summary: verdict.summary };
             }
             return verdict;
         }
+        case "bash_output":
+            // Polling a background task only reads its captured output and status —
+            // it touches nothing on the user's filesystem. Always safe.
+            return { decision: "allow", reason: "reads background task output, no side effects", summary: args.task_id ?? "bash_output" };
         case "exit_plan_mode": {
             // Outside plan mode this tool does nothing — let it through silently. In
             // plan mode it is the approval gate: ask the human, showing the plan, and

package/dist/prompt.js

@@ -34,6 +34,22 @@ Rules:
 - Use your tools to do the work. Verify what you claim — do not guess.
 - Your FINAL message is returned to the parent verbatim. Make it a compact, factual report: findings, exact paths, numbers, code snippets. No greetings, no questions back.
 - You cannot talk to the user. If the task cannot be completed, report precisely what is missing.`;
+// The teammate constitution (Day 38, extended Day 39). Unlike a sub-agent, a
+// teammate is persistent and CONNECTED: it works across many rounds, talks to
+// the team through mailboxes, and coordinates through explicit PROTOCOLS rather
+// than guessing. Load-bearing rules: keep the lead informed; propose-before-act
+// on risky work (submit_plan); and don't exit on your own — report, then idle
+// until the lead shuts you down. {name}/{role} are filled in at spawn time.
+export const TEAMMATE_PROMPT = `You are {name}, a teammate on an agent team. Your role: {role}.
+
+How a team works:
+- You work alongside other teammates, coordinated by the "lead". You all run at the same time.
+- There is a shared TASK BOARD. When you're idle you're automatically offered the next ready task ("You claimed task ..."). Just do it, then call complete_task — you'll be offered the next one. You can also list_tasks to see the board, claim_task a specific one, or create_task to add work you discover.
+- Use send_message to coordinate: report progress or findings to "lead" as you go, or ask a specific teammate something. Messages you receive appear as "[message from X]" — read them and act.
+- Before any RISKY or far-reaching change (refactoring auth, migrating a schema, deleting/rewriting many files), call submit_plan FIRST and wait for the lead's approval. Only start once it's approved; if rejected, revise and submit again.
+- You CANNOT talk to the human and you CANNOT spawn teammates. Decide within your role; if you're blocked, message the lead and say precisely what you need.
+- Use your tools (read_file, edit_file, write_file, search, run_bash) to do real work. Verify what you claim — do not guess.
+- When your current task is done, complete_task it and report to the lead, then STOP. You'll idle and be offered more board work, or follow-up messages. Do NOT decide on your own that the whole job is over — the lead ends your run by requesting shutdown, and you'll exit cleanly then.`;
 // Project memory: an optional AGENT.md in the current directory — the
 // equivalent of Claude Code's CLAUDE.md. Loaded once per session: stable
 // within a session (cache-friendly), different across projects (by design).

package/dist/team.js

@@ -0,0 +1,214 @@
+// ============ Agent teams (Day 38) ============
+// The leap past the one-shot sub-agent (the `task` tool). A sub-agent is fire-
+// and-forget: fresh context, runs to completion, returns ONE final report, gone.
+// That breaks down on big work — a teammate restructuring the API can't tell the
+// teammate touching auth what it changed, because they never talk; each only
+// hands back a conclusion at the very end.
+//
+// A TEAM fixes that. A Lead spawns several PERSISTENT teammates that run
+// concurrently and coordinate through ASYNCHRONOUS MAILBOXES: any agent can drop
+// a message in any other agent's inbox at any time, and the recipient sees it on
+// its next round. The Lead injects its inbox into its own conversation, so it
+// reacts to teammate results as they arrive instead of blocking on a single
+// return value.
+//
+// Why mailboxes live ON DISK (落盘), not in a Map: OBSERVABILITY. While the team
+// runs you can `cat .mini-agent/team/<agent>.jsonl` and watch messages in flight
+// — the coordination is a thing you can inspect, not hidden process state. The
+// Python reference guards these files with proper-lockfile because it runs
+// teammates on OS threads; we run them as async tasks on ONE event loop, where a
+// single appendFileSync — or a readFileSync+rmSync pair — runs to completion
+// without yielding, so two agents can never interleave mid-operation. No lock
+// needed. (Cross-process is out of scope: one CLI instance per project.)
+import fs from "node:fs"; // mailboxes are real files
+import path from "node:path"; // path joining
+// The mailbox name of the coordinator. Teammates message "lead" to report back;
+// the Lead reads its own inbox under this name.
+export const LEAD = "lead";
+// At most this many teammates per Lead — a cost/runaway ceiling, like every
+// other loop in this codebase. A handful of specialists is the whole idea; a
+// swarm is a footgun.
+export const MAX_TEAMMATES = 4;
+const pendingRequests = new Map(); // requestId → state
+let reqSeq = 0; // increments per request — seeds the id
+const teammates = new Map(); // name → teammate, for this run
+// ---- The mailbox files ------------------------------------------------------
+// Resolved lazily (a function, not a const) so it tracks the cwd, exactly like
+// session.ts. The first touch this process run wipes any stale mailboxes left by
+// a crashed earlier run — a new team must start with empty inboxes.
+let wiped = false;
+function teamRoot() {
+    const root = path.resolve(".mini-agent", "team");
+    fs.mkdirSync(root, { recursive: true });
+    if (!wiped) {
+        for (const f of fs.readdirSync(root))
+            if (f.endsWith(".jsonl"))
+                fs.rmSync(path.join(root, f)); // fresh inboxes for this run
+        wiped = true;
+    }
+    return root;
+}
+function inboxPath(agent) {
+    // Keep file names filesystem-safe: agent names come from the model.
+    const safe = agent.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(teamRoot(), `${safe}.jsonl`);
+}
+// Drop a message in the recipient's inbox: one JSON object per line (JSONL), so
+// appends never have to rewrite the file and a half-written line can't corrupt
+// the earlier ones. Synchronous on purpose — see the no-lock note up top.
+export function sendMessage(from, to, content, type = "message") {
+    const msg = { from, to, content, type, ts: Date.now() };
+    fs.appendFileSync(inboxPath(to), JSON.stringify(msg) + "\n");
+}
+// Drop a PROTOCOL message in an inbox — same JSONL bus, but tagged with its
+// contract role, request_id, and (for responses) the decision. This is how a
+// request and its answer travel; the consume step on the other side routes by
+// `kind` and correlates by `requestId`.
+export function sendProtocol(from, to, kind, requestId, content, status) {
+    const msg = { from, to, content, type: "message", ts: Date.now(), kind, requestId, status };
+    fs.appendFileSync(inboxPath(to), JSON.stringify(msg) + "\n");
+}
+// ---- Protocol state (the pending_requests dict) -----------------------------
+// Open a request: store it pending and return its fresh id. The caller then
+// sends the matching *_request message carrying this id.
+export function createRequest(kind, from, to, payload) {
+    const requestId = `req_${String(++reqSeq).padStart(6, "0")}`; // req_000001
+    pendingRequests.set(requestId, { requestId, kind, from, to, status: "pending", payload, createdAt: Date.now() });
+    return requestId;
+}
+export function getRequest(requestId) {
+    return pendingRequests.get(requestId);
+}
+// Correlate a response to its request — the reference's match_response. The
+// guard that matters: the response's contract MUST match the request's kind, so
+// a shutdown_response can never accidentally approve a plan_approval. Returns the
+// updated state, or an error string the caller can hand back to the model.
+export function resolveResponse(requestId, kind, approved) {
+    const state = pendingRequests.get(requestId);
+    if (!state)
+        return { ok: false, error: `No pending request "${requestId}".` };
+    if (state.kind !== kind)
+        return { ok: false, error: `Request "${requestId}" is a ${state.kind} request, not ${kind} — wrong response type.` };
+    if (state.status !== "pending")
+        return { ok: false, error: `Request "${requestId}" was already ${state.status}.` };
+    state.status = approved ? "approved" : "rejected";
+    return { ok: true, state };
+}
+// Requests still awaiting an answer for a given recipient — used by the lead's
+// view and to surface "you still owe an answer" prompts.
+export function openRequestsFor(agent) {
+    return [...pendingRequests.values()].filter((r) => r.to === agent && r.status === "pending");
+}
+// Read and CONSUME an inbox: parse every message, then delete the file. The
+// consumptive pattern (read = remove) means a message is delivered exactly once
+// and the on-disk inbox always shows only what is still pending. Unreadable
+// lines are skipped, never fatal.
+export function readInbox(agent) {
+    const p = inboxPath(agent);
+    if (!fs.existsSync(p))
+        return []; // nothing waiting
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return [];
+    }
+    fs.rmSync(p, { force: true }); // consume: the read empties the mailbox
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            out.push(JSON.parse(t));
+        }
+        catch {
+            /* skip a corrupt line, keep the rest */
+        }
+    }
+    return out;
+}
+// Peek at how many messages are waiting WITHOUT consuming them. The loop uses
+// this to decide whether to keep going; reading would empty the inbox before the
+// agent's own turn got to see it.
+export function inboxCount(agent) {
+    const p = inboxPath(agent);
+    if (!fs.existsSync(p))
+        return 0;
+    try {
+        return fs.readFileSync(p, "utf8").split("\n").filter((l) => l.trim()).length;
+    }
+    catch {
+        return 0;
+    }
+}
+// ---- The registry -----------------------------------------------------------
+export function teammateExists(name) {
+    return teammates.has(name);
+}
+export function teammateCount() {
+    return teammates.size;
+}
+// Record a newly spawned teammate. The caller supplies the promise for its loop.
+export function registerTeammate(name, role, done) {
+    teammates.set(name, { name, role, status: "running", state: "active", startedAt: Date.now(), done });
+}
+// Mark a teammate finished. `ok=false` means its loop ended on a non-Done reason.
+export function finishTeammate(name, ok) {
+    const t = teammates.get(name);
+    if (t)
+        t.status = ok ? "done" : "failed";
+}
+// How many teammates are still running — at least one running teammate means the
+// team isn't disbanded yet.
+export function activeTeammateCount() {
+    return [...teammates.values()].filter((t) => t.status === "running").length;
+}
+// ---- Day 39: active/idle + shutdown plumbing --------------------------------
+// A running teammate flips between actively working a round and idling on its
+// inbox. The lead waits while ANY teammate is actively working; once they're all
+// idle (or done), the work has converged and the lead can wrap up the team.
+export function setTeammateState(name, state) {
+    const t = teammates.get(name);
+    if (t && t.status === "running")
+        t.state = state;
+}
+export function anyTeammateBusy() {
+    return [...teammates.values()].some((t) => t.status === "running" && t.state === "active");
+}
+export function runningTeammates() {
+    return [...teammates.values()].filter((t) => t.status === "running").map((t) => t.name);
+}
+// The shutdown handshake: the lead opens a shutdown request against a teammate,
+// stamping it with the request_id; the teammate sees the flag at its next
+// stop-point, replies shutdown_response(approved) with that id, and exits.
+export function markShutdown(name, requestId) {
+    const t = teammates.get(name);
+    if (t)
+        t.shutdownRequestId = requestId;
+}
+export function shutdownRequestId(name) {
+    return teammates.get(name)?.shutdownRequestId;
+}
+// A snapshot for the /team command: newest first, with live state + inbox depth.
+export function listTeam() {
+    return [...teammates.values()]
+        .sort((a, b) => b.startedAt - a.startedAt)
+        .map((t) => ({
+        name: t.name,
+        role: t.role,
+        // While running, show active vs idle (Day 39) — that's the interesting bit.
+        status: t.status === "running" ? t.state : t.status,
+        elapsed: Math.round((Date.now() - t.startedAt) / 1000),
+        pending: inboxCount(t.name),
+    }));
+}
+// Wipe the registry AND the in-flight requests (and let the next touch clear the
+// mailbox files). Called on /clear and /resume, and after the lead disbands the
+// team — a new conversation starts with no team and no dangling protocols.
+export function resetTeam() {
+    teammates.clear();
+    pendingRequests.clear();
+    wiped = false; // the next mailbox touch wipes stale files again
+}

package/dist/todos.js

@@ -0,0 +1,87 @@
+import chalk from "chalk"; // the one color source — match ui.ts's vocabulary
+const STATUSES = ["pending", "in_progress", "completed"];
+// ---- pure: validate the model's argument into a clean Todo[] ----------------
+// The model's arguments are probabilistic, so be strict and return a precise
+// repair message (errors are text the model can act on) rather than trusting it.
+// Rule worth enforcing: AT MOST ONE in_progress — "do one thing at a time" is the
+// whole discipline a plan buys you; many-in-progress is just a relabeled backlog.
+export function parseTodos(raw) {
+    if (!Array.isArray(raw))
+        return { error: "`todos` must be an array of { content, status }" };
+    const todos = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        if (typeof item !== "object" || item === null)
+            return { error: `todo #${i + 1} must be an object with content + status` };
+        const content = typeof item.content === "string" ? item.content.trim() : "";
+        if (!content)
+            return { error: `todo #${i + 1} is missing non-empty "content"` };
+        if (!STATUSES.includes(item.status))
+            return { error: `todo #${i + 1} has bad status "${String(item.status)}" — use pending | in_progress | completed` };
+        todos.push({ content, status: item.status });
+    }
+    if (todos.filter((t) => t.status === "in_progress").length > 1)
+        return { error: "only one todo may be in_progress at a time — finish or re-queue the others" };
+    return { todos };
+}
+// ---- pure: render the checklist for the terminal ----------------------------
+// Glyphs over words: a column of ✓ / ▶ / ○ scans at a glance. The in-progress
+// item is the loud one (that's where attention belongs); done items fade.
+export function renderTodos(todos) {
+    if (!todos.length)
+        return chalk.dim("  (no todos)");
+    return todos
+        .map((t) => {
+        if (t.status === "completed")
+            return chalk.green("  ✓ ") + chalk.dim.strikethrough(t.content);
+        if (t.status === "in_progress")
+            return chalk.cyan.bold("  ▶ ") + chalk.bold(t.content);
+        return chalk.dim("  ○ " + t.content);
+    })
+        .join("\n");
+}
+// ---- pure: a one-line confirmation for the MODEL (cheap, no ANSI) -----------
+// The pretty list goes to the screen; the model only needs the tally + what it
+// said it's doing now, so we don't burn tokens echoing its own plan back at it.
+export function summarizeTodos(todos) {
+    const done = todos.filter((t) => t.status === "completed").length;
+    const doing = todos.find((t) => t.status === "in_progress");
+    const pending = todos.filter((t) => t.status === "pending").length;
+    const head = `Plan saved — ${done} done, ${doing ? 1 : 0} in progress, ${pending} pending.`;
+    if (doing)
+        return `${head} Now: ${doing.content}`;
+    if (todos.length && done === todos.length)
+        return `${head} All items complete.`;
+    return head;
+}
+// ---- session state + the nag --------------------------------------------------
+// The current plan lives for the session (in process memory, like Claude Code's).
+let current = [];
+let staleRounds = 0; // tool-rounds since the plan was last touched
+export function setTodos(todos) {
+    current = todos;
+    staleRounds = 0; // an update is a fresh signal — restart the patience clock
+}
+export function getTodos() {
+    return current;
+}
+export function clearTodos() {
+    current = [];
+    staleRounds = 0; // /clear and session switches wipe the plan too
+}
+// Call once per tool-round. If there's an unfinished plan the model has stopped
+// touching, return a reminder to inject (else null). This is the "nag": without
+// it the model writes a plan once and never looks back — the list goes stale and
+// stops meaning anything. We re-arm after firing, so it nudges every N rounds,
+// not every round (which would be noise).
+export const NAG_AFTER_ROUNDS = 3;
+export function todoNag() {
+    const unfinished = current.some((t) => t.status !== "completed");
+    if (!current.length || !unfinished)
+        return null; // no plan, or all done → nothing to nag about
+    staleRounds++;
+    if (staleRounds < NAG_AFTER_ROUNDS)
+        return null;
+    staleRounds = 0; // re-arm
+    return "[plan reminder] Your todo list still has unfinished items but you haven't updated it in a few steps. If you've made progress, call todo_write to mark items completed / move the next one to in_progress; if the plan changed, rewrite it. Don't lose the original goal.";
+}