@yagni-app/code-staging 1.1.1-staging.1347.1 → 1.1.1-staging.1355.1

package/README.md

@@ -23,6 +23,9 @@ correct, autonomous work than a coding agent that starts blank.
 npm install -g @yagni-app/code
 ```
 
+Requires Node.js 22.19 or newer (`node --version`); an older Node stops at
+launch with an upgrade message instead of crashing mid-session.
+
 The command it installs is `yagni`:
 
 ```bash

package/dist/bin.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * yagni — the published bin entry.
+ *
+ * Deliberately tiny: the only static imports are the dependency-free Node
+ * version gate and the (equally dependency-free) distribution record that
+ * names the installed channel. Everything else (`cli.js` and the module graph
+ * behind it) is loaded dynamically AFTER the check passes, so an old Node
+ * prints one clear message and exits instead of blowing up inside a
+ * dependency — or failing to parse one. `cli.js` stays directly runnable
+ * (`node dist/cli.js`) for the e2e lanes; its own entrypoint guard is false
+ * when this shim is argv[1], so the shim calls `runAsEntrypoint()` explicitly.
+ *
+ * Both failure paths set `process.exitCode` and return instead of calling
+ * `process.exit()`: stderr on a pipe is asynchronous on Windows, and an
+ * immediate exit can truncate the very diagnostic this shim exists to print.
+ * Letting the event loop drain flushes it.
+ *
+ * Behavioral coverage lives in `test/bin.test.ts`, which spawns this file
+ * under a faked-old `process.versions.node` and against a stub launcher that
+ * fails to load.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * yagni — the published bin entry.
+ *
+ * Deliberately tiny: the only static imports are the dependency-free Node
+ * version gate and the (equally dependency-free) distribution record that
+ * names the installed channel. Everything else (`cli.js` and the module graph
+ * behind it) is loaded dynamically AFTER the check passes, so an old Node
+ * prints one clear message and exits instead of blowing up inside a
+ * dependency — or failing to parse one. `cli.js` stays directly runnable
+ * (`node dist/cli.js`) for the e2e lanes; its own entrypoint guard is false
+ * when this shim is argv[1], so the shim calls `runAsEntrypoint()` explicitly.
+ *
+ * Both failure paths set `process.exitCode` and return instead of calling
+ * `process.exit()`: stderr on a pipe is asynchronous on Windows, and an
+ * immediate exit can truncate the very diagnostic this shim exists to print.
+ * Letting the event loop drain flushes it.
+ *
+ * Behavioral coverage lives in `test/bin.test.ts`, which spawns this file
+ * under a faked-old `process.versions.node` and against a stub launcher that
+ * fails to load.
+ */
+import { DISTRIBUTION } from "./distribution.js";
+import { nodeCheckSkipped, nodeVersionProblem } from "./nodeVersion.js";
+function debugEnabled() {
+    const value = process.env.YAGNI_DEBUG;
+    return value !== undefined && value !== "" && value !== "0";
+}
+async function main() {
+    const problem = nodeCheckSkipped() ? null : nodeVersionProblem(process.versions.node, DISTRIBUTION);
+    if (problem !== null) {
+        process.stderr.write(`${problem}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // A launcher that fails to LOAD (corrupt or partial install, a dependency
+    // missing from node_modules) would otherwise die as a raw unhandled
+    // rejection before the launcher's crash handlers exist — the same opaque
+    // failure this shim is here to prevent. No crash report is possible at this
+    // point (the reporter is part of what failed to load), so say what to do
+    // instead. The message carries the error class and message; YAGNI_DEBUG=1
+    // adds the full stack (resolution chain, parse location) for a support thread.
+    let launcher;
+    try {
+        launcher = await import("./cli.js");
+    }
+    catch (err) {
+        const name = err instanceof Error && err.name ? err.name : "Error";
+        const message = err instanceof Error ? err.message : String(err);
+        const lines = [
+            `${DISTRIBUTION.displayName} failed to load: ${name}: ${message}`,
+            "",
+            "The install looks incomplete or corrupt. Reinstall it:",
+            "",
+            `  npm install -g ${DISTRIBUTION.packageName}`,
+            "",
+        ];
+        if (debugEnabled()) {
+            const stack = err instanceof Error && err.stack ? err.stack : "(no stack)";
+            const cause = err instanceof Error && err.cause !== undefined ? `\ncause: ${String(err.cause)}` : "";
+            lines.push(`${stack}${cause}`, "");
+        }
+        else {
+            lines.push("(YAGNI_DEBUG=1 prints the full stack.)", "");
+        }
+        process.stderr.write(lines.join("\n"));
+        process.exitCode = 1;
+        return;
+    }
+    launcher.runAsEntrypoint();
+}
+await main();
+//# sourceMappingURL=bin.js.map

package/dist/cli.d.ts

@@ -166,5 +166,11 @@ export declare function main(argv: string[]): Promise<number>;
  * test import (argv[1] points at the test runner) does not.
  */
 export declare function isEntrypoint(argv1: string | undefined, moduleUrl: string): boolean;
+/**
+ * Run the launcher as the process entrypoint. Called by the published bin
+ * shim (`bin.js`, after the Node version gate) and by the guard below when
+ * this module is executed directly (`node dist/cli.js`, the e2e lanes).
+ */
+export declare function runAsEntrypoint(): void;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -889,9 +889,12 @@ export function isEntrypoint(argv1, moduleUrl) {
     };
     return resolve(argv1) === resolve(fileURLToPath(moduleUrl));
 }
-// Only auto-run when invoked as the CLI entry, so tests can import this module
-// (e.g. to exercise wantsHelp) without spawning the agent.
-if (isEntrypoint(process.argv[1], import.meta.url)) {
+/**
+ * Run the launcher as the process entrypoint. Called by the published bin
+ * shim (`bin.js`, after the Node version gate) and by the guard below when
+ * this module is executed directly (`node dist/cli.js`, the e2e lanes).
+ */
+export function runAsEntrypoint() {
     // Crash reporting for the LAUNCHER process only (pi runs as a child and the
     // extension covers the session side). Fire-and-forget, sanitized, bounded;
     // YAGNI_DISABLE_CRASH_REPORTS=1 turns it off. Registered before main() so a
@@ -904,4 +907,9 @@ if (isEntrypoint(process.argv[1], import.meta.url)) {
         process.exit(1);
     });
 }
+// Only auto-run when invoked as the CLI entry, so tests can import this module
+// (e.g. to exercise wantsHelp) without spawning the agent.
+if (isEntrypoint(process.argv[1], import.meta.url)) {
+    runAsEntrypoint();
+}
 //# sourceMappingURL=cli.js.map

package/dist/crashReport.d.ts

@@ -77,6 +77,13 @@ export interface SanitizedCrash {
  * payloads…) are never touched.
  */
 export declare function sanitizeCrashError(err: unknown, opts?: SanitizeCrashOptions): SanitizedCrash;
+/**
+ * OS, arch AND the Node version. The runtime is a first-class crash cause
+ * (an old Node dies inside undici on `zlib.createZstdDecompress`), and it
+ * rides the existing `platform` field so the backend and its Sentry tag need
+ * no change. Mirrored in `pi-extension-yagni/src/crashReport.ts`.
+ */
+export declare function platformLabel(): string;
 export type CrashClient = "cli" | "desktop" | "desktop-driver";
 export interface CrashReportInput {
     client: CrashClient;

package/dist/crashReport.js

@@ -177,6 +177,15 @@ export function sanitizeCrashError(err, opts = {}) {
         ...(cappedStack !== undefined ? { stack: cappedStack } : {}),
     };
 }
+/**
+ * OS, arch AND the Node version. The runtime is a first-class crash cause
+ * (an old Node dies inside undici on `zlib.createZstdDecompress`), and it
+ * rides the existing `platform` field so the backend and its Sentry tag need
+ * no change. Mirrored in `pi-extension-yagni/src/crashReport.ts`.
+ */
+export function platformLabel() {
+    return `${process.platform} ${process.arch} node ${process.version}`;
+}
 /**
  * Sanitize + POST one crash report from pre-extracted fields. Resolves on
  * every outcome — timeout, network error, non-2xx, disabled — and never
@@ -199,7 +208,7 @@ export async function sendCrashReport(input) {
         const payload = {
             client: input.client,
             clientVersion: input.clientVersion,
-            platform: `${process.platform} ${process.arch}`,
+            platform: platformLabel(),
             errorClass: sanitizeCrashText(input.errorClass, opts).slice(0, MAX_CRASH_ERROR_CLASS),
             message: sanitizeCrashText(input.message, opts).slice(0, MAX_CRASH_MESSAGE),
             ...(stack !== undefined ? { stack } : {}),

package/dist/doctor.d.ts

@@ -50,6 +50,13 @@ export type BackendProbe = {
 } | {
     kind: "network";
 };
+/**
+ * The Node floor, first in the list because every other check is moot
+ * without it: an old Node dies inside pi's HTTP client mid-request (Sentry
+ * YAGNI-BACKEND-4S: `zlib.createZstdDecompress is not a function`). The bin
+ * shim refuses to launch below the floor; doctor explains it in the same terms.
+ */
+export declare function checkNodeVersion(version: string): CheckResult;
 export declare function checkPiEngine(probe: PiEngineProbe): CheckResult;
 export declare function checkExtension(probe: ExtensionProbe): CheckResult;
 export declare function checkProfileToken(profile: Pick<Profile, "name" | "token">): CheckResult;
@@ -115,6 +122,8 @@ export declare function buildDoctorReport(checks: CheckResult[]): DoctorReport;
 export declare function formatDoctorReport(report: DoctorReport): string;
 export interface DoctorDeps {
     now?: () => number;
+    /** Running Node version (defaults to process.versions.node). */
+    nodeVersion?: string;
     probePiEngine?: () => PiEngineProbe;
     probeExtension?: () => ExtensionProbe;
     readActiveProfile?: () => Promise<Profile>;

package/dist/doctor.js

@@ -21,7 +21,27 @@ import { otelChildEnv, resolveOtelLaunchWithWorkspace } from "./otel.js";
 import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir, resolveTelemetryProbePath } from "./paths.js";
 import { readActiveProfile } from "./profiles.js";
 import { resolveMcpConfigPath } from "./mcpCommand.js";
+import { MIN_NODE_VERSION, nodeVersionSatisfies } from "./nodeVersion.js";
 // ── Pure check builders ─────────────────────────────────────────────────────
+/**
+ * The Node floor, first in the list because every other check is moot
+ * without it: an old Node dies inside pi's HTTP client mid-request (Sentry
+ * YAGNI-BACKEND-4S: `zlib.createZstdDecompress is not a function`). The bin
+ * shim refuses to launch below the floor; doctor explains it in the same terms.
+ */
+export function checkNodeVersion(version) {
+    const shown = version.startsWith("v") ? version : `v${version}`;
+    if (!nodeVersionSatisfies(version, MIN_NODE_VERSION)) {
+        return {
+            name: "node",
+            status: "fail",
+            detail: `${shown} is older than the ${MIN_NODE_VERSION} floor`,
+            hint: "upgrade Node.js (https://nodejs.org or `nvm install 22`); older Node crashes mid-request on missing zlib APIs",
+            required: true,
+        };
+    }
+    return { name: "node", status: "ok", detail: `${shown} (needs ${MIN_NODE_VERSION}+)`, required: true };
+}
 export function checkPiEngine(probe) {
     if (!probe.binPath || !probe.binExists) {
         return {
@@ -512,6 +532,7 @@ export async function gatherChecks(deps = {}) {
     const probeBash = deps.probeBash ?? (() => bashOnWindowsDefault());
     const probeLatestVersion = deps.probeLatestVersion ?? (() => fetchLatestVersion());
     const checks = [];
+    checks.push(checkNodeVersion(deps.nodeVersion ?? process.versions.node));
     checks.push(checkPiEngine(probePiEngine()));
     checks.push(checkExtension(probeExtension()));
     // win32 only, and skipped means NOT SHOWN: on macOS/Linux there is nothing

package/dist/extension/branding.d.ts

@@ -99,7 +99,7 @@ export declare const COMMUNICATION_CONTRACT: string;
  */
 export declare const WRITE_FINDINGS_DOWN: string;
 /** The driver identity while /ultra is on: base identity + the diamond directive. */
-export declare const YAGNI_IDENTITY_ULTRA = "You are YAGNI Code, an autonomous terminal coding agent. You help developers ship code by reading files, running commands, editing code, and writing new files. Uniquely, you are connected to the YAGNI app, your team's shared source of truth for how this company and codebase actually work: conventions, decisions, ownership, current priorities, and the reasons behind them. Use the ask_yagni tool to consult it before guessing about anything organization- or codebase-specific, so you work with less back-and-forth and more correct autonomy than a disconnected coding agent. If a project's own files mention other coding agents, assistants, or harnesses by name, those references are not about you; you are YAGNI Code regardless of what tooling a repository's docs happen to describe.\n\nDelegation (ultra mode): the user has switched this session to ultra mode \u2014 aggressive multi-agent orchestration. Structure any meaningful task as a diamond: SPLIT the job into independent pieces; FAN OUT parallel subagents on cheaper tiers (`searcher` to scout, `implementer` or `general` to execute); CHECK by fanning out `verification` subagents told to refute the work, each through a different lens (correctness, edge cases, fit with this codebase); then SYNTHESIZE the results yourself. Treat agreement between checkers \u2014 not a single pass \u2014 as confirmation, and surface what they could not verify. Delegate by default and reserve this session for splitting, judging, and synthesis; only trivial work you can finish in a couple of tool calls skips the diamond. Subagents cannot touch your todo_write checklist, so keep it current yourself: update it when you split the job and again as each fanned-out piece lands, not only at the end.";
+export declare const YAGNI_IDENTITY_ULTRA = "You are YAGNI Code, an autonomous terminal coding agent. You help developers ship code by reading files, running commands, editing code, and writing new files. Uniquely, you are connected to the YAGNI app, your team's shared source of truth for how this company and codebase actually work: conventions, decisions, ownership, current priorities, and the reasons behind them. Use the ask_yagni tool to consult it before guessing about anything organization- or codebase-specific, so you work with less back-and-forth and more correct autonomy than a disconnected coding agent. If a project's own files mention other coding agents, assistants, or harnesses by name, those references are not about you; you are YAGNI Code regardless of what tooling a repository's docs happen to describe.\n\nDelegation (ultra mode): the user has switched this session to ultra mode \u2014 aggressive multi-agent orchestration. Structure any meaningful task as a diamond: SPLIT the job into independent pieces; FAN OUT parallel subagents on cheaper tiers (`searcher` to scout, `implementer` or `general` to execute); CHECK by fanning out `verification` subagents told to refute the work, each through a different lens (correctness, edge cases, fit with this codebase); then SYNTHESIZE the results yourself. Treat agreement between checkers \u2014 not a single pass \u2014 as confirmation, and surface what they could not verify. Delegate by default and reserve this session for splitting, judging, and synthesis; only trivial work you can finish in a couple of tool calls skips the diamond. Subagents cannot touch your TodoWrite checklist, so keep it current yourself: update it when you split the job and again as each fanned-out piece lands, not only at the end.";
 export declare const PI_IDENTITY_RE: RegExp;
 /**
  * Env switch that bypasses the system-prompt rewrite entirely, so pi's

package/dist/extension/branding.js

@@ -65,7 +65,7 @@ export const ULTRA_DELEGATION_PARAGRAPH = "Delegation (ultra mode): the user has
     "surface what they could not verify. Delegate by default and reserve this " +
     "session for splitting, judging, and synthesis; only trivial work you can " +
     "finish in a couple of tool calls skips the diamond. Subagents cannot touch " +
-    "your todo_write checklist, so keep it current yourself: update it when you " +
+    "your TodoWrite checklist, so keep it current yourself: update it when you " +
     "split the job and again as each fanned-out piece lands, not only at the end.";
 /**
  * The identity used for the interactive DRIVER session ONLY: {@link

package/dist/extension/crashReport.d.ts

@@ -72,6 +72,13 @@ export interface CrashReporterOpts {
     timeoutMs?: number;
 }
 export type CrashReporter = (error: unknown, context?: string, repoRoot?: string) => Promise<void>;
+/**
+ * OS, arch AND the Node version: the runtime is a first-class crash cause (an
+ * old Node dies inside undici on `zlib.createZstdDecompress`), and it rides
+ * the existing `platform` field so the backend and its Sentry tag need no
+ * change. Mirrored in `yagni-code-cli/src/crashReport.ts`.
+ */
+export declare function platformLabel(): string;
 /**
  * Build the fail-soft reporter. The extension runs inside pi's process, so
  * the client label follows the surface: `desktop` under the desktop shell

package/dist/extension/crashReport.js

@@ -145,6 +145,15 @@ export function sanitizeCrashError(err, opts = {}) {
         ...(cappedStack !== undefined ? { stack: cappedStack } : {}),
     };
 }
+/**
+ * OS, arch AND the Node version: the runtime is a first-class crash cause (an
+ * old Node dies inside undici on `zlib.createZstdDecompress`), and it rides
+ * the existing `platform` field so the backend and its Sentry tag need no
+ * change. Mirrored in `yagni-code-cli/src/crashReport.ts`.
+ */
+export function platformLabel() {
+    return `${process.platform} ${process.arch} node ${process.version}`;
+}
 /**
  * Build the fail-soft reporter. The extension runs inside pi's process, so
  * the client label follows the surface: `desktop` under the desktop shell
@@ -163,7 +172,7 @@ export function makeCrashReporter(opts) {
             const payload = {
                 client: isDesktopSurface() ? "desktop" : "cli",
                 clientVersion: env.YAGNI_CODE_VERSION?.trim() || "unknown",
-                platform: `${process.platform} ${process.arch}`,
+                platform: platformLabel(),
                 ...sanitized,
                 ...(context !== undefined ? { context } : {}),
                 timestamp: new Date().toISOString(),
@@ -234,7 +243,7 @@ export function reportFatalCrash(error, opts, context) {
         const payload = {
             client: isDesktopSurface() ? "desktop" : "cli",
             clientVersion: env.YAGNI_CODE_VERSION?.trim() || "unknown",
-            platform: `${process.platform} ${process.arch}`,
+            platform: platformLabel(),
             ...sanitized,
             ...(context !== undefined ? { context } : {}),
             timestamp: new Date().toISOString(),

package/dist/extension/index.js

@@ -208,11 +208,18 @@ export async function registerYagni(pi, deps = {}) {
     // no-position record suggestions reach the model) and record_decision
     // (flywheel-attributed records send dedupe: true). Run 7.
     const flywheelState = makeFlywheelState();
+    // The session todo checklist: TodoWrite tool (Claude-parity surface), the
+    // above-editor widget, and /todos. Branch-replayed, so forks and resumes
+    // show the list as it stood at that point. Registered BEFORE the working
+    // line so the board's in_progress activeForm can drive the spinner verb.
+    const todosHandle = registerTodos(pi);
     // The composed streaming status line ("Shaping… (12m 54s · ↓ 47.5k tokens)").
     // Registered before the subagent/advisor tools: they publish their live
     // progress through this handle so the elapsed/token suffix survives their
-    // overrides. TUI-gated internally (agent_start checks ctx.mode).
-    const workingLine = registerWorkingLine(pi);
+    // overrides. The verb mirrors the todo board's live step when one is
+    // in_progress (Claude's currentTodo?.activeForm pattern). TUI-gated
+    // internally (agent_start checks ctx.mode).
+    const workingLine = registerWorkingLine(pi, { todoVerb: todosHandle.activeVerb });
     pi.registerTool(makeAskYagniTool({ ...toolOpts, flywheel: flywheelState, getRepo: () => sessionRepo }));
     // WebFetch (YAG-578): read an arbitrary URL as clean markdown + a
     // standard-tier extraction, replacing the bash + curl + python dance.
@@ -253,10 +260,6 @@ export async function registerYagni(pi, deps = {}) {
         // ask_yagni answers the same question next time instead of interrupting a human.
         pi.registerTool(makeRecordDecisionTool({ ...toolOpts, flywheel: flywheelState }));
     }
-    // The visible checklist for multi-step work: the todo_write tool, its
-    // above-editor widget, and /todos. Branch-replayed, so forks and resumes
-    // show the list as it stood at that point.
-    registerTodos(pi);
     // YAG-574: the silent-turn reminder, driver-only. A child/subagent/advisor
     // process has no direct user to answer, so it is never nudged (same gating
     // as the delegation identity in branding.ts); eval mode is untouched so its
@@ -1480,7 +1483,7 @@ export { blindStages, reportOnlyStages, makeGroundedVsBlindEval, formatCompariso
 export { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
 // The general subagent tool: Claude Code-format agent discovery + fan-out.
 export { registerSubagents, makeSubagentTool, discoverSubagents, parseAgentMarkdown, buildSubagentStage, formatAgentList, mapModelTier, SUBAGENT_TOOL_NAME, GENERAL_AGENT_NAME, MAX_PARALLEL_SUBAGENTS, MAX_PARALLEL_SUBAGENTS_ULTRA, DEFAULT_SUBAGENT_TOOLS, } from "./subagents.js";
-// The session todo checklist: todo_write tool, widget renderer, /todos.
+// The session todo checklist: TodoWrite tool, widget renderer, /todos.
 export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, formatTodoReminder, shouldRemindTodos, todoSummary, TODO_TOOL_NAME, TODO_REMINDER_TURNS, MAX_TODOS, } from "./todos.js";
 // P3 + W4: the permission gate seam (decideGate is pure; policy injectable) plus
 // the session bless-with-remember capture hook.

package/dist/extension/permission/gate.d.ts

@@ -309,7 +309,7 @@ export interface RegisterPermissionDeps {
 export declare const MODE_CONTEXT_TYPE = "yagni-mode-context";
 /** Legacy alias — the original plan-mode tag, kept for backward compat. */
 export declare const PLAN_CONTEXT_TYPE = "yagni-mode-context";
-export declare const PLAN_CONTEXT_MESSAGE = "[PLAN MODE ACTIVE]\nYou are in plan mode: explore and design, change nothing.\n- Read-only bash commands (ls, grep, git status, gh pr view, etc.) run freely to help you explore.\n- Ambiguous bash commands are reviewed by the Guardian; if non-mutating they run, if potentially mutating you will be asked.\n- write, edit, file_ticket, and update_ticket_status are held by the permission gate; do not attempt them.\n- Read, search, and ask_yagni freely to ground the plan in how this company works.\n- Produce a concrete numbered plan of the steps you would take, with the files involved.\n- End by asking the user to review the plan; they run /mode auto (or /mode review) to execute it.\n- Once executing, track the plan's steps with todo_write.";
+export declare const PLAN_CONTEXT_MESSAGE = "[PLAN MODE ACTIVE]\nYou are in plan mode: explore and design, change nothing.\n- Read-only bash commands (ls, grep, git status, gh pr view, etc.) run freely to help you explore.\n- Ambiguous bash commands are reviewed by the Guardian; if non-mutating they run, if potentially mutating you will be asked.\n- write, edit, file_ticket, and update_ticket_status are held by the permission gate; do not attempt them.\n- Read, search, and ask_yagni freely to ground the plan in how this company works.\n- Produce a concrete numbered plan of the steps you would take, with the files involved.\n- End by asking the user to review the plan; they run /mode auto (or /mode review) to execute it.\n- Once executing, track the plan's steps with TodoWrite.";
 /** Build the mode-awareness context message for the current permission mode. */
 export declare function buildModeContextMessage(mode: PermissionMode): string;
 /**

package/dist/extension/permission/gate.js

@@ -215,7 +215,7 @@ You are in plan mode: explore and design, change nothing.
 - Read, search, and ask_yagni freely to ground the plan in how this company works.
 - Produce a concrete numbered plan of the steps you would take, with the files involved.
 - End by asking the user to review the plan; they run /mode auto (or /mode review) to execute it.
-- Once executing, track the plan's steps with todo_write.`;
+- Once executing, track the plan's steps with TodoWrite.`;
 const AUTO_CONTEXT_MESSAGE = `${AUTO_MARKER}
 You are in auto mode. Coding commands run directly.
 - Proactively verify your work: run tests, lint, and typecheck after changes.

package/dist/extension/silentTurnReminder.js

@@ -43,6 +43,7 @@ export const MIN_SILENT_TURNS = 2;
  * utterance even when the assistant emitted no visible text block.
  */
 export const USER_FACING_TOOLS = new Set([
+    "TodoWrite",
     "todo_write",
     "file_ticket",
     "update_ticket_status",

package/dist/extension/todos.d.ts

@@ -1,25 +1,48 @@
 /**
  * The session todo list — the visible checklist for multi-step work.
  *
- * A `todo_write` tool the model calls with the FULL list every time (replace,
+ * A `TodoWrite` tool the model calls with the FULL list every time (replace,
  * not patch: replacement is idempotent under retries and always renders a
  * coherent board), a persistent above-editor widget while steps remain open,
  * and a `/todos` command to pull the list on demand.
  *
+ * The model-facing surface (name, item schema, description, result echo)
+ * matches Claude Code's shipped TodoWrite v1 exactly: the tick-immediately /
+ * don't-batch habits are trained behavior attached to that shape, and the
+ * custom `todo_write` surface was getting weak attachment (lists created at
+ * round start, entire rounds ground through unticked, one batch
+ * complete-at-end — the frozen-board report). Claude's TodoV2 per-task tools
+ * are a feature-flagged experiment there and are deliberately NOT adopted.
+ *
+ * The UI mirrors Claude Code too: TodoWrite leaves ZERO transcript rows
+ * (their renderToolUseMessage() => null; here, zero-line renderCall /
+ * renderResult renderers under renderShell "self" — pi removes the row
+ * entirely), and the board lives in the above-editor widget. The widget
+ * borrows Claude's TaskList details: the "N tasks (X done, Y in progress,
+ * Z open)" header, ✔/◼/◻ glyphs with a bold active row, activeForm as the
+ * live verb, and prioritized truncation (recently-completed tasks linger
+ * ~30s so a fresh tick is still visible, then older completions fall behind
+ * open work) with a "… +N in progress, M completed" overflow summary. One
+ * deliberate deviation: the list is always pinned above the editor, not
+ * behind Claude's ctrl+t toggle.
+ *
  * State follows pi's branching model the same way the session does: the
- * canonical list is the LAST `todo_write` tool result on the current branch,
+ * canonical list is the LAST todo tool result on the current branch,
  * reconstructed on session_start/session_tree, so forking or rewinding a
  * session automatically shows the list as it stood at that point. The
  * in-memory copy is just a cache of that.
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type Component } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-export declare const TODO_TOOL_NAME = "todo_write";
+export declare const TODO_TOOL_NAME = "TodoWrite";
+/** The pre-parity tool name. Recorded sessions carry it in tool results. */
+export declare const TODO_LEGACY_TOOL_NAME = "todo_write";
 export declare const MAX_TODOS = 50;
 export declare const MAX_TODO_TEXT = 300;
 /**
  * Staleness-reminder throttle (both counters must trip): a reminder is
- * eligible only after this many assistant turns since the last todo_write AND
+ * eligible only after this many assistant turns since the last TodoWrite AND
  * this many since the last reminder. The two-counter shape (staleness gate +
  * anti-spam gate) mirrors what Claude Code ships for its own todo tool; the
  * driver model routinely stops updating the board mid-grind (the frozen
@@ -27,6 +50,11 @@ export declare const MAX_TODO_TEXT = 300;
  * survive a long run.
  */
 export declare const TODO_REMINDER_TURNS = 10;
+/**
+ * How long a freshly-completed task lingers at the top of the widget before
+ * dropping behind open work — Claude Code's TaskList RECENT_COMPLETED_TTL.
+ */
+export declare const TODO_COMPLETED_LINGER_MS = 30000;
 /**
  * The desktop's structured state record rides its own widget key, like the
  * `/go` run state: one JSON line the app parses and renders itself, never
@@ -37,12 +65,17 @@ export declare const TODO_REMINDER_TURNS = 10;
 export declare const TODO_STATE_KEY = "yagni-todos:state";
 export type TodoStatus = "pending" | "in_progress" | "completed";
 export interface TodoItem {
-    text: string;
+    /** Imperative form: what needs to be done ("Run tests"). */
+    content: string;
+    /** Present continuous form, shown while in_progress ("Running tests"). */
+    activeForm: string;
     status: TodoStatus;
 }
 /**
  * Validate a full replacement list. Strict: this is model input rendered
  * straight into the terminal. An empty list is valid (it clears the board).
+ * Accepts both the current shape ({content, activeForm}) and the legacy
+ * {text} shape so old sessions replay cleanly.
  */
 export declare function normalizeTodos(raw: unknown): {
     ok: true;
@@ -58,17 +91,46 @@ export declare function todoSummary(todos: TodoItem[]): {
 };
 /** Plain-text checklist (tool results, /todos in headless contexts). */
 export declare function formatTodoList(todos: TodoItem[]): string;
+/** One count for the whole board — header and overflow always agree. */
+export declare function todoCounts(todos: TodoItem[]): {
+    total: number;
+    done: number;
+    inProgress: number;
+    open: number;
+};
+/** Claude Code's widget header: `3 tasks (1 done, 1 in progress, 6 open)`. */
+export declare function formatTodoHeader(todos: TodoItem[]): string;
+/**
+ * The every-write result echo — Claude Code's exact reinforcer. The tick
+ * habit decays over a long run; this lands on every TodoWrite result
+ * (including the create-at-start write, right before the model enters its
+ * grind) so the board stays current in the model's attention.
+ */
+export declare const TODO_RESULT_ECHO: string;
 /** The slice of pi's Theme the widget styles with (matches the feed's pattern). */
 export interface TodoTheme {
     fg(color: string, s: string): string;
+    bold?(s: string): string;
     strikethrough?(s: string): string;
 }
+/**
+ * Claude Code's task truncation priority: recently-completed first (a fresh
+ * tick lingers {@link TODO_COMPLETED_LINGER_MS} so the user sees it land),
+ * then in_progress, then pending, then older completed — everything else
+ * falls behind the cap and is summarized.
+ */
+export declare function prioritizeTodos(todos: TodoItem[], completedAt: (content: string) => number | undefined, nowMs: number): TodoItem[];
+/** Claude Code's overflow summary: `… +2 in progress, 3 completed`. */
+export declare function formatTodoOverflow(hidden: TodoItem[]): string | null;
 /**
  * The above-editor checklist. Empty (paint nothing) when there is no list or
- * every step is completed — a finished board should leave the screen. Capped
+ * every step is completed — a finished board should leave the screen. Rows
+ * past the cap are truncated with Claude's prioritization + overflow summary
  * so header + items + overflow stays under pi's 10-line widget truncation.
+ * The in-progress row shows the active form in bold (the live "what am I
+ * doing" signal); pending and completed rows show the imperative content.
  */
-export declare function renderTodoWidget(todos: TodoItem[], theme: TodoTheme): string[];
+export declare function renderTodoWidget(todos: TodoItem[], theme: TodoTheme, completedAtCache?: Map<string, number>, nowMs?: number): string[];
 /** The desktop state record: exactly one JSON line under TODO_STATE_KEY. */
 export declare function todoStateLine(todos: TodoItem[]): string;
 /**
@@ -85,22 +147,23 @@ export declare function shouldRemindTodos(input: {
  * PURE: the hedged reminder block appended to a tool result when the board has
  * gone stale. Carries the CURRENT list so the model can reconcile without a
  * read, and explicitly licenses ignoring it, so an accurate board costs one
- * glance rather than a spurious todo_write.
+ * glance rather than a spurious TodoWrite.
  */
 export declare function formatTodoReminder(todos: TodoItem[]): string;
-/** Replay the branch: the last todo_write result is the canonical list. */
+/** Replay the branch: the last todo-tool result is the canonical list. */
 export declare function reconstructTodos(entries: unknown[]): TodoItem[];
 type TodoParams = {
     todos: Array<{
-        text: string;
+        content: string;
+        activeForm: string;
         status: string;
     }>;
 };
 /**
- * Build the todo_write tool definition around a shared store. Separated from
+ * Build the TodoWrite tool definition around a shared store. Separated from
  * registration so tests can drive execute directly.
  */
-export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoItem[]) => void): {
+export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoItem[]) => void, completedAt?: Map<string, number>): {
     name: string;
     label: string;
     description: string;
@@ -108,10 +171,21 @@ export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoIte
     promptGuidelines: string[];
     parameters: Type.TObject<{
         todos: Type.TArray<Type.TObject<{
-            text: Type.TString;
+            content: Type.TString;
+            activeForm: Type.TString;
             status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"in_progress">, Type.TLiteral<"completed">]>;
         }>>;
     }>;
+    renderShell: "self";
+    renderCall: () => Component;
+    renderResult: (result: {
+        content?: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }, options: {
+        isError?: boolean;
+    }, theme: TodoTheme) => Component;
     execute(_toolCallId: string, params: TodoParams, _signal?: AbortSignal, _onUpdate?: unknown, ctx?: ExtensionContext): Promise<{
         content: {
             type: "text";
@@ -132,7 +206,15 @@ export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoIte
         isError?: undefined;
     }>;
 };
-/** Wire the tool, the branch-replay events, the staleness reminder, and /todos. */
-export declare function registerTodos(pi: ExtensionAPI): void;
+/**
+ * Wire the tool, the branch-replay events, the staleness reminder, the
+ * widget refresh loop, and /todos.
+ */
+/** What registerTodos hands back: the live spinner-verb override. */
+export interface TodosHandle {
+    /** The in_progress item's activeForm, or undefined with no active step. */
+    activeVerb(): string | undefined;
+}
+export declare function registerTodos(pi: ExtensionAPI): TodosHandle;
 export {};
 //# sourceMappingURL=todos.d.ts.map