@yagni-app/code-staging 1.1.3-staging.1377.1 → 1.1.3-staging.1380.1

package/dist/extension/crashReport.d.ts

@@ -24,6 +24,7 @@
  * `backend/src/yagniCode/crashReports.ts`. Spec:
  * docs/superpowers/specs/2026-08-08-crash-reporting-design.md
  */
+import { type SinkEvent } from "./errorSink.js";
 export declare const CRASH_REPORT_DISABLE_ENV = "YAGNI_DISABLE_CRASH_REPORTS";
 export declare const CRASH_REPORT_TIMEOUT_MS = 1500;
 export declare const MAX_CRASH_MESSAGE = 512;
@@ -97,13 +98,30 @@ export type SpawnLike = (command: string, args: string[], options: {
 export interface FatalCrashOpts extends CrashReporterOpts {
     /** Spawn seam for tests (defaults to node:child_process spawn). */
     spawnImpl?: SpawnLike;
+    /** Local error-trail seam for tests (defaults to errorSink's logEvent). */
+    trail?: (event: SinkEvent) => void;
 }
+/** Test seam: forget that a fatal report went out, and that a reporter is installed. */
+export declare function resetFatalReportedForTests(): void;
 /**
  * Deliver a crash report from a process that is about to die: build the
  * sanitized payload in-process (cheap, synchronous), then spawn a detached
  * one-shot sender that outlives the crash. Never throws.
  */
 export declare function reportFatalCrash(error: unknown, opts: FatalCrashOpts, context?: string): void;
+/**
+ * Report a pi process that ends with a non-zero code WITHOUT an uncaught
+ * exception. pi's own fatal paths print to stderr and `process.exit(1)`, which
+ * the exception monitor never sees, so until now those deaths were invisible
+ * unless the user pasted their terminal. An `exit` listener observes only: it
+ * cannot keep the process alive or change the code, and the detached sender
+ * is spawned synchronously, which is all an `exit` handler is allowed to do.
+ *
+ * Skipped on the desktop surface, where the shell files a richer report built
+ * from the driver's stderr tail (one incident, one report), and for the two
+ * "stopped on purpose" codes.
+ */
+export declare function installNonZeroExitReporter(opts: FatalCrashOpts, proc?: Pick<NodeJS.Process, "on">): void;
 /**
  * Observe (never alter) a fatal crash in pi's process. Uses
  * `uncaughtExceptionMonitor`, which fires before the process dies without

package/dist/extension/crashReport.js

@@ -170,7 +170,7 @@ export function makeCrashReporter(opts) {
             const token = opts.getToken();
             const sanitized = sanitizeCrashError(error, { env, repoRoot });
             const payload = {
-                client: isDesktopSurface() ? "desktop" : "cli",
+                client: isDesktopSurface(env) ? "desktop" : "cli",
                 clientVersion: env.YAGNI_CODE_VERSION?.trim() || "unknown",
                 platform: platformLabel(),
                 ...sanitized,
@@ -226,6 +226,19 @@ const DETACHED_SENDER_SRC = [
     "  signal: AbortSignal.timeout(4000),",
     "}).catch(() => {}).finally(done);",
 ].join("\n");
+/**
+ * Set once a fatal report has been handed to a sender, so the exit reporter
+ * never files a second report for the same death (an uncaught exception is
+ * followed by an exit-1, and both hooks would otherwise fire).
+ */
+let fatalReported = false;
+/** The exit reporter is per process, not per extension load (a reload re-runs the factory). */
+let exitReporterInstalled = false;
+/** Test seam: forget that a fatal report went out, and that a reporter is installed. */
+export function resetFatalReportedForTests() {
+    fatalReported = false;
+    exitReporterInstalled = false;
+}
 /**
  * Deliver a crash report from a process that is about to die: build the
  * sanitized payload in-process (cheap, synchronous), then spawn a detached
@@ -241,7 +254,7 @@ export function reportFatalCrash(error, opts, context) {
             return;
         const sanitized = sanitizeCrashError(error, { env });
         const payload = {
-            client: isDesktopSurface() ? "desktop" : "cli",
+            client: isDesktopSurface(env) ? "desktop" : "cli",
             clientVersion: env.YAGNI_CODE_VERSION?.trim() || "unknown",
             platform: platformLabel(),
             ...sanitized,
@@ -263,11 +276,62 @@ export function reportFatalCrash(error, opts, context) {
             },
         });
         child.unref();
+        fatalReported = true;
     }
     catch {
         // a crash reporter must never add its own crash
     }
 }
+/** Exit codes that mean "someone stopped it" (Ctrl+C, SIGTERM), not "it broke". */
+const STOPPED_EXIT_CODES = new Set([130, 143]);
+/**
+ * Report a pi process that ends with a non-zero code WITHOUT an uncaught
+ * exception. pi's own fatal paths print to stderr and `process.exit(1)`, which
+ * the exception monitor never sees, so until now those deaths were invisible
+ * unless the user pasted their terminal. An `exit` listener observes only: it
+ * cannot keep the process alive or change the code, and the detached sender
+ * is spawned synchronously, which is all an `exit` handler is allowed to do.
+ *
+ * Skipped on the desktop surface, where the shell files a richer report built
+ * from the driver's stderr tail (one incident, one report), and for the two
+ * "stopped on purpose" codes.
+ */
+export function installNonZeroExitReporter(opts, proc = process) {
+    // Once per process: pi re-runs the extension factory on every reload, and
+    // a listener per reload would both pile up and race each other on exit.
+    if (exitReporterInstalled)
+        return;
+    exitReporterInstalled = true;
+    proc.on("exit", (code) => {
+        try {
+            if (code === 0 || STOPPED_EXIT_CODES.has(code) || fatalReported)
+                return;
+            const env = opts.env ?? process.env;
+            // The same source the payload's client label reads, so the skip and the
+            // label can never disagree about which surface this is.
+            if (isDesktopSurface(env))
+                return;
+            const error = new Error(`pi exited with code ${code}`);
+            error.name = "ProcessExit";
+            // The listener's own frames say nothing about why pi exited.
+            error.stack = undefined;
+            reportFatalCrash(error, opts, `process-exit:${code}`);
+            // The local trail too, so a logged-out user (no token, nothing sent)
+            // still has a record /feedback can bind next session.
+            (opts.trail ?? logEvent)({
+                source: "tool",
+                level: "error",
+                event: "process_exit",
+                sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                flush: "sync",
+                fields: { code },
+            });
+        }
+        catch {
+            // an exit hook must never throw
+        }
+    });
+}
 /**
  * Observe (never alter) a fatal crash in pi's process. Uses
  * `uncaughtExceptionMonitor`, which fires before the process dies without

package/dist/extension/index.d.ts

@@ -199,7 +199,7 @@ export type { ComparisonReport, LaneFit, LaneOutcome } from "./pipeline/eval.js"
 export { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
 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";
 export type { SubagentDef, SubagentSource } from "./subagents.js";
-export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, formatTodoReminder, shouldRemindTodos, todoSummary, TODO_TOOL_NAME, TODO_REMINDER_TURNS, MAX_TODOS, } from "./todos.js";
+export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, formatTodoReminder, shouldRemindTodos, clampSingleInProgress, formatAgeMs, oldestInProgress, todoSummary, TODO_TOOL_NAME, TODO_REMINDER_TURNS, TODO_STALE_MS, MAX_TODOS, } from "./todos.js";
 export type { TodoItem, TodoStatus, TodoTheme } from "./todos.js";
 export { decideGate, registerPermissionGate, filterStaleModeContext, filterStalePlanContext, buildModeContextMessage, DEFAULT_PERMISSION_POLICY, MODE_CONTEXT_TYPE, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission/gate.js";
 export { classifyCommand, DEFAULT_EXEC_POLICY, } from "./permission/execPolicy.js";
@@ -225,6 +225,6 @@ export { ToolRunTracker, summarizeRun, isQuiet, kindForTool } from "./toolRuns.j
 export type { RowKind, ToolRow, ToolRowPatch } from "./toolRuns.js";
 export { registerWorkingLine, composeWorkingMessage, NULL_WORKING_LINE, WORKING_INDICATOR_FRAMES, WORKING_VERBS, } from "./workingLine.js";
 export type { WorkingLineHandle, RegisterWorkingLineDeps } from "./workingLine.js";
-export { crashReportsDisabled, installUncaughtExceptionMonitor, makeCrashReporter, reportFatalCrash, sanitizeCrashError, sanitizeCrashText, } from "./crashReport.js";
+export { crashReportsDisabled, installNonZeroExitReporter, installUncaughtExceptionMonitor, makeCrashReporter, reportFatalCrash, sanitizeCrashError, sanitizeCrashText, } from "./crashReport.js";
 export type { CrashReporter, CrashReporterOpts, FatalCrashOpts, SanitizedCrash } from "./crashReport.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/extension/index.js

@@ -53,7 +53,7 @@ import { loadGroundingEnabled } from "./grounding.js";
 import { attributionPromptSection, loadAttributionSettings, } from "./attribution.js";
 import { registerAmbientRecall } from "./recall.js";
 import { resilientFetch } from "./resilientFetch.js";
-import { installUncaughtExceptionMonitor, makeCrashReporter, runningUnderTest } from "./crashReport.js";
+import { installNonZeroExitReporter, installUncaughtExceptionMonitor, makeCrashReporter, runningUnderTest, } from "./crashReport.js";
 import { createToolOutcomeBatcher } from "./toolOutcomes.js";
 import { flushSpool as defaultFlushSpool } from "./spool.js";
 import { makeAuthedFetch, makeTokenProvider } from "./tokenProvider.js";
@@ -252,7 +252,12 @@ export async function registerYagni(pi, deps = {}) {
     // soft, opt-out via YAGNI_DISABLE_CRASH_REPORTS=1; off in eval mode like
     // every other external side effect.
     if (!evalMode) {
-        installUncaughtExceptionMonitor({ baseUrl, getToken: getTokenFn, env: deps.env });
+        const fatalOpts = { baseUrl, getToken: getTokenFn, env: deps.env };
+        installUncaughtExceptionMonitor(fatalOpts);
+        // A pi that exits non-zero without throwing (its own fatal paths) is a
+        // death the monitor never sees; report it too, so a terminal user's
+        // "it just quit" reaches Sentry without a pasted transcript.
+        installNonZeroExitReporter(fatalOpts);
     }
     // YAG-500 Fix E: non-fatal auth-event reporter for 401s on the model path.
     // Reuses the crash endpoint (/api/yagni-code/crash) with a distinct context
@@ -1844,7 +1849,7 @@ 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: 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";
+export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, formatTodoReminder, shouldRemindTodos, clampSingleInProgress, formatAgeMs, oldestInProgress, todoSummary, TODO_TOOL_NAME, TODO_REMINDER_TURNS, TODO_STALE_MS, MAX_TODOS, } from "./todos.js";
 // P3 + W4: the permission gate seam (decideGate is pure; policy injectable) plus
 // the session bless-with-remember capture hook.
 export { decideGate, registerPermissionGate, filterStaleModeContext, filterStalePlanContext, buildModeContextMessage, DEFAULT_PERMISSION_POLICY, MODE_CONTEXT_TYPE, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission/gate.js";
@@ -1870,5 +1875,5 @@ export { appendToSpool, loadSpool, flushSpool, sendOrSpool, spoolFile, MAX_SPOOL
 export { registerCondensedTools, displayPath, isScratchpadPath, primaryArg, formatRowTitle, formatWriteBody, formatEditBody, formatBashErrorBody, formatBashPartialBody, formatExpandedOutput, splitBashError, countPatchAdditions, WRITE_PREVIEW_LINES, DIFF_PREVIEW_LINES, } from "./condensedTools.js";
 export { ToolRunTracker, summarizeRun, isQuiet, kindForTool } from "./toolRuns.js";
 export { registerWorkingLine, composeWorkingMessage, NULL_WORKING_LINE, WORKING_INDICATOR_FRAMES, WORKING_VERBS, } from "./workingLine.js";
-export { crashReportsDisabled, installUncaughtExceptionMonitor, makeCrashReporter, reportFatalCrash, sanitizeCrashError, sanitizeCrashText, } from "./crashReport.js";
+export { crashReportsDisabled, installNonZeroExitReporter, installUncaughtExceptionMonitor, makeCrashReporter, reportFatalCrash, sanitizeCrashError, sanitizeCrashText, } from "./crashReport.js";
 //# sourceMappingURL=index.js.map

package/dist/extension/surface.d.ts

@@ -6,5 +6,5 @@
  * Desktop-facing widgets are structured single-line JSON records the app
  * parses, not themed terminal lines.
  */
-export declare function isDesktopSurface(): boolean;
+export declare function isDesktopSurface(env?: NodeJS.ProcessEnv): boolean;
 //# sourceMappingURL=surface.d.ts.map

package/dist/extension/surface.js

@@ -6,7 +6,7 @@
  * Desktop-facing widgets are structured single-line JSON records the app
  * parses, not themed terminal lines.
  */
-export function isDesktopSurface() {
-    return process.env.YAGNI_SURFACE === "desktop";
+export function isDesktopSurface(env = process.env) {
+    return env.YAGNI_SURFACE === "desktop";
 }
 //# sourceMappingURL=surface.js.map

package/dist/extension/todos.d.ts

@@ -55,6 +55,19 @@ export declare const TODO_REMINDER_TURNS = 10;
  * dropping behind open work — Claude Code's TaskList RECENT_COMPLETED_TTL.
  */
 export declare const TODO_COMPLETED_LINGER_MS = 30000;
+/**
+ * Age at which an in-progress step is treated as possibly stale: the aged
+ * reminder names the item and its age instead of the generic nudge, and the
+ * widget row picks up a dim `(23m)` suffix. Below this the board reads as
+ * normal active work.
+ */
+export declare const TODO_STALE_MS: number;
+/**
+ * The board repaints at this cadence while an active step can age, so the
+ * `(23m)` suffix stays live. Under the staleness threshold the suffix is
+ * hidden entirely, so a slow tick costs nothing.
+ */
+export declare const TODO_REPAINT_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
@@ -75,15 +88,31 @@ export interface TodoItem {
  * 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.
+ * {text} shape so old sessions replay cleanly. The single-active clamp runs
+ * here so every path (tool writes, branch replay, legacy sessions) enforces
+ * it; `demoted` reports what the clamp changed so callers can tell the model.
  */
 export declare function normalizeTodos(raw: unknown): {
     ok: true;
     todos: TodoItem[];
+    demoted: string[];
 } | {
     ok: false;
     error: string;
 };
+/**
+ * PURE: enforce the single-active invariant on an already-valid list. The
+ * model occasionally marks several steps in_progress at once (parallel
+ * sub-parts of one block, recorded 4-at-a-time in real sessions); tools
+ * execute sequentially so only one can be truthfully "being worked on".
+ * Keep the FIRST in list order, demote the rest to pending — quieter than
+ * rejecting the write, and the model self-corrects on the next pass since
+ * the result echoes the normalized list.
+ */
+export declare function clampSingleInProgress(todos: TodoItem[]): {
+    todos: TodoItem[];
+    demoted: string[];
+};
 export declare function todoSummary(todos: TodoItem[]): {
     done: number;
     total: number;
@@ -130,9 +159,26 @@ export declare function formatTodoOverflow(hidden: TodoItem[]): string | null;
  * 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, completedAtCache?: Map<string, number>, nowMs?: number): string[];
+export declare function renderTodoWidget(todos: TodoItem[], theme: TodoTheme, completedAtCache?: Map<string, number>, nowMs?: number, opts?: {
+    idle?: boolean;
+    startedAt?: (content: string) => number | undefined;
+}): string[];
 /** The desktop state record: exactly one JSON line under TODO_STATE_KEY. */
 export declare function todoStateLine(todos: TodoItem[]): string;
+/**
+ * PURE: render an in-progress step's age as a dim suffix, empty while the
+ * step is younger than {@link TODO_STALE_MS}. `47m` under an hour, `1h 47m`
+ * after — the "is it stuck?" signal the board owes the user at a glance.
+ */
+export declare function formatAgeMs(ms: number): string;
+/**
+ * PURE: the oldest in-progress step past the staleness threshold, if any —
+ * the concrete anchor the aged reminder names instead of the generic nudge.
+ */
+export declare function oldestInProgress(todos: TodoItem[], startedAt: ((content: string) => number | undefined) | undefined, nowMs: number): {
+    todo: TodoItem;
+    age: string;
+} | null;
 /**
  * PURE: is a staleness reminder due? Only when the board has open work (an
  * empty or fully-completed list never nags) and BOTH throttle counters have
@@ -149,7 +195,20 @@ export declare function shouldRemindTodos(input: {
  * read, and explicitly licenses ignoring it, so an accurate board costs one
  * glance rather than a spurious TodoWrite.
  */
-export declare function formatTodoReminder(todos: TodoItem[]): string;
+export declare function formatTodoReminder(todos: TodoItem[], opts?: {
+    startedAt?: (content: string) => number | undefined;
+    nowMs?: number;
+}): string;
+/**
+ * PURE: reconcile the two timestamp caches against the next board. Both
+ * share the eviction contract — a stamp leaves when its content leaves the
+ * board — but startedAt is stricter: a step that stops being in_progress
+ * (completed, or demoted to pending by the single-active clamp) drops its
+ * stamp, so a later re-activation counts as a NEW active span. Otherwise an
+ * in_progress → pending → in_progress gap would bill the idle time between
+ * spans to the second one's age.
+ */
+export declare function observeTimestamps(next: TodoItem[], completedAt: Map<string, number>, startedAt: Map<string, number>, now: number): void;
 /** Replay the branch: the last todo-tool result is the canonical list. */
 export declare function reconstructTodos(entries: unknown[]): TodoItem[];
 type TodoParams = {

package/dist/extension/todos.js

@@ -56,6 +56,19 @@ export const TODO_REMINDER_TURNS = 10;
  * dropping behind open work — Claude Code's TaskList RECENT_COMPLETED_TTL.
  */
 export const TODO_COMPLETED_LINGER_MS = 30_000;
+/**
+ * Age at which an in-progress step is treated as possibly stale: the aged
+ * reminder names the item and its age instead of the generic nudge, and the
+ * widget row picks up a dim `(23m)` suffix. Below this the board reads as
+ * normal active work.
+ */
+export const TODO_STALE_MS = 10 * 60 * 1000;
+/**
+ * The board repaints at this cadence while an active step can age, so the
+ * `(23m)` suffix stays live. Under the staleness threshold the suffix is
+ * hidden entirely, so a slow tick costs nothing.
+ */
+export const TODO_REPAINT_MS = 30_000;
 const WIDGET_KEY = "yagni-todos";
 /**
  * The desktop's structured state record rides its own widget key, like the
@@ -92,7 +105,9 @@ function coerceItem(raw) {
  * 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.
+ * {text} shape so old sessions replay cleanly. The single-active clamp runs
+ * here so every path (tool writes, branch replay, legacy sessions) enforces
+ * it; `demoted` reports what the clamp changed so callers can tell the model.
  */
 export function normalizeTodos(raw) {
     if (!Array.isArray(raw))
@@ -108,7 +123,32 @@ export function normalizeTodos(raw) {
             return { ok: false, error: coerced.error };
         todos.push(coerced);
     }
-    return { ok: true, todos };
+    const clamped = clampSingleInProgress(todos);
+    return { ok: true, todos: clamped.todos, demoted: clamped.demoted };
+}
+/**
+ * PURE: enforce the single-active invariant on an already-valid list. The
+ * model occasionally marks several steps in_progress at once (parallel
+ * sub-parts of one block, recorded 4-at-a-time in real sessions); tools
+ * execute sequentially so only one can be truthfully "being worked on".
+ * Keep the FIRST in list order, demote the rest to pending — quieter than
+ * rejecting the write, and the model self-corrects on the next pass since
+ * the result echoes the normalized list.
+ */
+export function clampSingleInProgress(todos) {
+    const demoted = [];
+    let keptActive = false;
+    const next = todos.map((t) => {
+        if (t.status !== "in_progress")
+            return t;
+        if (keptActive) {
+            demoted.push(t.content);
+            return { ...t, status: "pending" };
+        }
+        keptActive = true;
+        return t;
+    });
+    return demoted.length > 0 ? { todos: next, demoted } : { todos, demoted };
 }
 export function todoSummary(todos) {
     return {
@@ -191,7 +231,8 @@ export function formatTodoOverflow(hidden) {
  * 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 function renderTodoWidget(todos, theme, completedAtCache = new Map(), nowMs = Date.now()) {
+export function renderTodoWidget(todos, theme, completedAtCache = new Map(), nowMs = Date.now(), opts = {}) {
+    const { idle, startedAt } = opts;
     const { total, done } = todoCounts(todos);
     if (total === 0 || done === total)
         return [];
@@ -204,8 +245,16 @@ export function renderTodoWidget(todos, theme, completedAtCache = new Map(), now
             lines.push(`${theme.fg("success", "✔ ")}${theme.fg("dim", text)}`);
         }
         else if (todo.status === "in_progress") {
-            const active = theme.bold ? theme.bold(`${todo.activeForm}…`) : `${todo.activeForm}…`;
-            lines.push(`${theme.fg("accent", "◼ ")}${theme.fg("text", active)}`);
+            const age = staleAgeSuffix(todo, startedAt, nowMs);
+            if (idle) {
+                // An idle agent has no "actively doing" claim; keep the row but
+                // drop the live-work styling so the board stops pretending.
+                lines.push(theme.fg("dim", `◼ ${todo.activeForm}…${age}`));
+            }
+            else {
+                const active = theme.bold ? theme.bold(`${todo.activeForm}…`) : `${todo.activeForm}…`;
+                lines.push(`${theme.fg("accent", "◼ ")}${theme.fg("text", active)}${theme.fg("dim", age)}`);
+            }
         }
         else {
             lines.push(`${theme.fg("dim", "◻ ")}${theme.fg("muted", todo.content)}`);
@@ -220,6 +269,50 @@ export function renderTodoWidget(todos, theme, completedAtCache = new Map(), now
 export function todoStateLine(todos) {
     return JSON.stringify({ v: TODO_STATE_VERSION, todos });
 }
+/**
+ * PURE: render an in-progress step's age as a dim suffix, empty while the
+ * step is younger than {@link TODO_STALE_MS}. `47m` under an hour, `1h 47m`
+ * after — the "is it stuck?" signal the board owes the user at a glance.
+ */
+export function formatAgeMs(ms) {
+    const totalMinutes = Math.floor(ms / 60_000);
+    if (totalMinutes < 1)
+        return "";
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    return hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`;
+}
+function staleAgeSuffix(todo, startedAt, nowMs) {
+    const at = startedAt?.(todo.content);
+    if (at === undefined)
+        return "";
+    const age = nowMs - at;
+    if (age < TODO_STALE_MS)
+        return "";
+    const text = formatAgeMs(age);
+    return text ? ` (${text})` : "";
+}
+/**
+ * PURE: the oldest in-progress step past the staleness threshold, if any —
+ * the concrete anchor the aged reminder names instead of the generic nudge.
+ */
+export function oldestInProgress(todos, startedAt, nowMs) {
+    let worst = null;
+    for (const t of todos) {
+        if (t.status !== "in_progress")
+            continue;
+        const at = startedAt?.(t.content);
+        if (at === undefined)
+            continue;
+        const ageMs = nowMs - at;
+        if (ageMs >= TODO_STALE_MS && (!worst || ageMs > worst.ageMs))
+            worst = { todo: t, ageMs };
+    }
+    if (!worst)
+        return null;
+    const age = formatAgeMs(worst.ageMs);
+    return age ? { todo: worst.todo, age } : null;
+}
 /**
  * PURE: is a staleness reminder due? Only when the board has open work (an
  * empty or fully-completed list never nags) and BOTH throttle counters have
@@ -240,13 +333,54 @@ export function shouldRemindTodos(input) {
  * read, and explicitly licenses ignoring it, so an accurate board costs one
  * glance rather than a spurious TodoWrite.
  */
-export function formatTodoReminder(todos) {
+export function formatTodoReminder(todos, opts = {}) {
+    const stale = oldestInProgress(todos, opts.startedAt, opts.nowMs ?? Date.now());
+    if (stale) {
+        // A concrete, named accusation with a number on it — the generic nudge
+        // lost 20 times in a row to a busy context in the recorded session that
+        // motivated this.
+        return (`⟦YAGNI todos⟧ "${stale.todo.content}" has been in_progress for ${stale.age} — if it is ` +
+            "done or superseded, mark it completed or remove it; if you are still working on it, " +
+            "ignore this and keep the board current as you go.\n" +
+            formatTodoList(todos));
+    }
     return ("⟦YAGNI todos⟧ The TodoWrite checklist has not been updated for a while. " +
         "If the work has moved on, bring it current now: mark finished steps completed, " +
-        "set the step you are on to in_progress, and add newly discovered steps. " +
+        "set the step you are on to in_progress, and add newly discovered follow-up steps. " +
         "If the list is already accurate, ignore this.\n" +
         formatTodoList(todos));
 }
+/**
+ * PURE: reconcile the two timestamp caches against the next board. Both
+ * share the eviction contract — a stamp leaves when its content leaves the
+ * board — but startedAt is stricter: a step that stops being in_progress
+ * (completed, or demoted to pending by the single-active clamp) drops its
+ * stamp, so a later re-activation counts as a NEW active span. Otherwise an
+ * in_progress → pending → in_progress gap would bill the idle time between
+ * spans to the second one's age.
+ */
+export function observeTimestamps(next, completedAt, startedAt, now) {
+    const seen = new Set(next.map((t) => t.content));
+    for (const [content] of completedAt) {
+        if (!seen.has(content))
+            completedAt.delete(content);
+    }
+    for (const [content] of startedAt) {
+        if (!seen.has(content))
+            startedAt.delete(content);
+    }
+    const activeNow = new Set(next.filter((t) => t.status === "in_progress").map((t) => t.content));
+    for (const [content] of startedAt) {
+        if (!activeNow.has(content))
+            startedAt.delete(content);
+    }
+    for (const t of next) {
+        if (t.status === "completed" && !completedAt.has(t.content))
+            completedAt.set(t.content, now);
+        if (t.status === "in_progress" && !startedAt.has(t.content))
+            startedAt.set(t.content, now);
+    }
+}
 /** Replay the branch: the last todo-tool result is the canonical list. */
 export function reconstructTodos(entries) {
     let todos = [];
@@ -303,7 +437,7 @@ function todoRenderers() {
         },
     };
 }
-function paintWidget(ctx, todos, completedAt) {
+function paintWidget(ctx, todos, completedAt, opts = {}) {
     if (!ctx?.hasUI)
         return;
     try {
@@ -318,7 +452,10 @@ function paintWidget(ctx, todos, completedAt) {
             return;
         }
         const theme = ctx.ui.theme;
-        const lines = renderTodoWidget(todos, theme, completedAt);
+        const lines = renderTodoWidget(todos, theme, completedAt, Date.now(), {
+            idle: opts.idle,
+            startedAt: opts.startedAt ? (c) => opts.startedAt.get(c) : undefined,
+        });
         ctx.ui.setWidget?.(WIDGET_KEY, lines.length > 0 ? lines : undefined, {
             placement: "aboveEditor",
         });
@@ -373,10 +510,24 @@ export function makeTodoTool(get, set, completedAt) {
                 // error.
                 throw new Error(`Error: ${normalized.error}`);
             }
+            if (normalized.demoted.length > 0) {
+                logEvent({
+                    source: "todos",
+                    level: "info",
+                    event: "multi_in_progress_clamped",
+                    fields: { demoted: normalized.demoted, count: normalized.demoted.length },
+                });
+            }
             set(normalized.todos);
             paintWidget(ctx, normalized.todos, completedAt);
+            const note = normalized.demoted.length > 0
+                ? `Normalized: kept "${normalized.todos.find((t) => t.status === "in_progress")?.content}" ` +
+                    `as the single in_progress task; demoted ${normalized.demoted
+                        .map((c) => `"${c}"`)
+                        .join(", ")} to pending.\n\n`
+                : "";
             return {
-                content: [{ type: "text", text: `${formatTodoList(normalized.todos)}\n\n${TODO_RESULT_ECHO}` }],
+                content: [{ type: "text", text: `${formatTodoList(normalized.todos)}\n\n${note}${TODO_RESULT_ECHO}` }],
                 details: { todos: normalized.todos },
             };
         },
@@ -397,18 +548,49 @@ export function registerTodos(pi) {
     // passes), re-floating it every few minutes. prioritizeTodos already treats
     // an aged-out stamp as "older"; the cache never needs a sweeper.
     const completedAt = new Map();
-    const observe = (next, now = Date.now()) => {
-        const seen = new Set(next.map((t) => t.content));
-        for (const [content] of completedAt) {
-            if (!seen.has(content))
-                completedAt.delete(content);
-        }
-        for (const t of next) {
-            if (t.status === "completed" && !completedAt.has(t.content))
-                completedAt.set(t.content, now);
+    // When each open step entered in_progress — the aged reminder and the
+    // widget's `(23m)` suffix key off this. Same eviction contract as
+    // completedAt: entries leave when the content leaves the board; a
+    // re-entering item gets a fresh stamp (a restart of the same work is
+    // genuinely a new active span).
+    const startedAt = new Map();
+    // True while the agent is NOT running (between turns, awaiting input) —
+    // an idle board must not style its active row as live work.
+    let idle = true;
+    let repaintTimer;
+    const hasActive = () => todos.some((t) => t.status === "in_progress");
+    // Repaint while an active step can age: the (23m) suffix and idle styling
+    // would otherwise freeze at the last write. TUI only (desktop gets a
+    // paint on every state change and renders its own board); unref'd so a
+    // batched test process never lingers on it, and torn down whenever the
+    // board empties or the session restarts.
+    const ensureRepaintTimer = (ctx) => {
+        if (!ctx.hasUI || isDesktopSurface() || repaintTimer || !hasActive())
+            return;
+        repaintTimer = setInterval(() => {
+            // hasUI is captured at registration; ctx here is the tool/refresh ctx.
+            paintWidget(latestCtx ?? undefined, todos, completedAt, { idle, startedAt });
+        }, TODO_REPAINT_MS);
+        repaintTimer.unref?.();
+    };
+    const clearRepaintTimer = () => {
+        if (repaintTimer) {
+            clearInterval(repaintTimer);
+            repaintTimer = undefined;
         }
     };
+    let latestCtx;
+    const rememberCtx = (ctx) => {
+        latestCtx = ctx;
+    };
+    const observe = (next, now = Date.now()) => {
+        observeTimestamps(next, completedAt, startedAt, now);
+    };
     const reconstruct = (ctx) => {
+        // Clear-then-ensure: a session switch/fork must never inherit the
+        // previous session's repaint interval — an empty replayed board would
+        // otherwise leave the old 30s timer firing at a dead pane forever.
+        clearRepaintTimer();
         try {
             todos = reconstructTodos(ctx.sessionManager.getBranch());
         }
@@ -427,17 +609,48 @@ export function registerTodos(pi) {
         // completed items from history rank as "older" (outside the linger
         // window), exactly like a live item whose tick has aged out.
         completedAt.clear();
+        startedAt.clear();
         for (const t of todos) {
             if (t.status === "completed") {
                 completedAt.set(t.content, Date.now() - TODO_COMPLETED_LINGER_MS - 1);
             }
+            if (t.status === "in_progress") {
+                // Age counts from resume — the true start time is unknowable
+                // post-hoc, and stamping fresh keeps the suffix from instantly
+                // showing a fabricated age.
+                startedAt.set(t.content, Date.now());
+            }
         }
         turnsSinceWrite = 0;
         turnsSinceReminder = 0;
-        paintWidget(ctx, todos);
+        rememberCtx(ctx);
+        idle = true;
+        paintWidget(ctx, todos, completedAt, { idle, startedAt });
+        if (hasActive())
+            ensureRepaintTimer(ctx);
     };
     pi.on("session_start", async (_event, ctx) => reconstruct(ctx));
     pi.on("session_tree", async (_event, ctx) => reconstruct(ctx));
+    // The live-work signal: an idle agent's active row dims. Fires on every
+    // agent loop, cheap on both sides, and repaints immediately so the dim
+    // lands without waiting for the next paint-on-write.
+    pi.on("agent_start", async (_event, ctx) => {
+        idle = false;
+        rememberCtx(ctx);
+        if (hasActive())
+            ensureRepaintTimer(ctx);
+        paintWidget(ctx, todos, completedAt, { idle, startedAt });
+    });
+    // Idle keeps the timer alive on purpose: the aging suffix on a dimmed row
+    // is exactly the "is it stuck?" signal the user watches while the agent
+    // waits for input. The timer dies when the board empties, not here.
+    pi.on("agent_end", async (_event, ctx) => {
+        idle = true;
+        rememberCtx(ctx);
+        if (hasActive())
+            ensureRepaintTimer(ctx);
+        paintWidget(ctx, todos, completedAt, { idle, startedAt });
+    });
     // Turn counting: one tick per finalized assistant message, the same "turn"
     // the model experiences between opportunities to call TodoWrite.
     pi.on("message_end", async (event) => {
@@ -460,7 +673,10 @@ export function registerTodos(pi) {
             return {
                 content: [
                     ...event.content,
-                    { type: "text", text: `\n\n${formatTodoReminder(todos)}` },
+                    {
+                        type: "text",
+                        text: `\n\n${formatTodoReminder(todos, { startedAt: (c) => startedAt.get(c) })}`,
+                    },
                 ],
             };
         }
@@ -472,6 +688,18 @@ export function registerTodos(pi) {
         todos = next;
         observe(next);
         turnsSinceWrite = 0;
+        if (!hasActive())
+            clearRepaintTimer();
+        // Repaint here with the full live opts (idle state, startedAt ages)
+        // — the tool's own paint is ctx-bound but opts-less, so the age
+        // suffix and idle dimming land through this pass. Also (re)arm the
+        // repaint timer: a write that introduces the first active step
+        // shouldn't wait for the next agent event to start ticking.
+        if (latestCtx) {
+            paintWidget(latestCtx, todos, completedAt, { idle, startedAt });
+            if (hasActive())
+                ensureRepaintTimer(latestCtx);
+        }
     }, completedAt));
     pi.registerCommand("todos", {
         description: "Show the agent's current task list for this session.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.1.3-staging.1377.1",
+  "version": "1.1.3-staging.1380.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "2d36b38964c6959ed433421c6eb2502d5d351423"
+  "yagniSourceSha": "2924db07168a415885dd5ac2ae552e9b121f4736"
 }