@yagni-app/code-staging 1.1.3-staging.1376.1 → 1.1.3-staging.1378.1

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";

package/dist/extension/index.js

@@ -285,15 +285,23 @@ export async function registerYagni(pi, deps = {}) {
     }
     // Lock the interactive session to the `advanced` tier only. The backend
     // catalog returns all tiers, but only `advanced` is registered with the
-    // `yagni` provider, so /model and Ctrl+P show a single entry. Child
-    // processes (/go, subagents, advisor) fetch their own catalog and register
-    // their own provider, so they are unaffected by this filter.
+    // `yagni` provider, so /model and Ctrl+P show a single entry.
     //
-    // Eval mode is exempt: a headless harness (scoping sessions, code evals)
-    // names its tier explicitly — the backend's scoping sessions run `--model
-    // standard` — and there is no /model picker to keep tidy. Filtering there
-    // turns a valid tier request into "no models match".
-    const catalog = evalMode ? fullCatalog : fullCatalog.filter((m) => m.id === "advanced");
+    // Two exemptions:
+    // - CHILD processes: the runner stamps YAGNI_CALLER on every /go, subagent,
+    //   and advisor spawn (`isDriverCaller` false). A child names its tier on
+    //   the command line (`--model standard` for a general subagent, `--model
+    //   efficient` for a searcher) and must resolve it EXACTLY against its own
+    //   catalog — the advanced-only filter used to leave those tier names
+    //   unresolved, so pi fell back to its custom-model-id path (a stderr
+    //   warning on every non-advanced child and default-shaped capability
+    //   metadata instead of the real context-window/token caps).
+    // - Eval mode: a headless harness (scoping sessions, code evals) names its
+    //   tier explicitly — the backend's scoping sessions run `--model standard`
+    //   — and there is no /model picker to keep tidy. Filtering there turns a
+    //   valid tier request into "no models match".
+    const driver = isDriverCaller(env);
+    const catalog = evalMode || !driver ? fullCatalog : fullCatalog.filter((m) => m.id === "advanced");
     // YAG-471: the driver's own completions carry attribution headers read from
     // this process's env (YAGNI_SESSION_ID minted by the launcher; YAGNI_CALLER
     // defaults to "driver" when unset, i.e. every session that is not a /go
@@ -1836,7 +1844,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";

package/dist/extension/pipeline/resilience.d.ts

@@ -41,9 +41,19 @@ export type RunStageFn = (stage: PipelineStage, ctx: {
 export interface ResilienceAttemptRecord {
     stageId: string;
     lens?: ReviewLens;
+    /** The stage's agent name (a subagent child's agent, or the /go stage id). */
+    agent?: string;
+    /**
+     * Which task of a multi-task subagent call this attempt belongs to
+     * (0-based). Content-free — an index, never task text — so parallel
+     * same-agent failures are attributable without leaking content.
+     */
+    taskIndex?: number;
     /** 1-based attempt number. */
     attempt: number;
     outcome: "ok" | "transient" | "fatal" | "timeout" | "aborted";
+    /** Which timer fired, when the attempt timed out. */
+    timeoutKind?: "idle" | "wall";
     exitCode: number;
     stopReason?: string;
     elapsedMs: number;

package/dist/extension/pipeline/resilience.js

@@ -31,6 +31,8 @@
 const WRITE_STAGE_IDS = ["implement", "fix"];
 /** Honest message stamped on a stage we aborted for exceeding its time budget. */
 const TIMEOUT_MESSAGE = "stage exceeded its idle or wall-clock timeout";
+const WALL_TIMEOUT_MESSAGE = "stage exceeded its wall-clock timeout";
+const IDLE_TIMEOUT_MESSAGE = "stage exceeded its idle timeout";
 /** stderr fingerprints of a transient transport/provider blip worth retrying. */
 const TRANSIENT_STDERR = /\b429\b|\b5\d\d\b|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket hang up/i;
 /**
@@ -86,7 +88,12 @@ export function withResilience(base, policy, opts = {}) {
     const telemetry = opts.telemetry;
     return async (stage, ctx, deps) => {
         const callerSignal = deps.signal;
-        const isWriteStage = WRITE_STAGE_IDS.includes(stage.id);
+        // The write-gate keys on what the child can DO, not on the stage id: a
+        // subagent stage carries the synthetic id "implement" for /go-compat, so
+        // the subagent tool passes an explicit per-agent flag (a read-only
+        // verifier is retried freely; an edit-capable child keeps the no-re-run
+        // discipline). Absent, the /go stage-id vocabulary decides as before.
+        const isWriteStage = deps.stageWriteCapable ?? WRITE_STAGE_IDS.includes(stage.id);
         let last;
         for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
             // A caller abort during a backoff window: stop before spending another attempt.
@@ -95,9 +102,11 @@ export function withResilience(base, policy, opts = {}) {
             const timeoutController = new AbortController();
             const composed = composeAbortSignal(callerSignal, timeoutController.signal);
             let timedOut = false;
+            let timeoutKind;
             let sawAnyEvent = false;
-            const fireTimeout = () => {
+            const fireTimeout = (kind) => {
                 timedOut = true;
+                timeoutKind = kind;
                 if (!timeoutController.signal.aborted)
                     timeoutController.abort();
             };
@@ -120,9 +129,9 @@ export function withResilience(base, policy, opts = {}) {
                     armIdle();
                     return;
                 }
-                fireTimeout();
+                fireTimeout("idle");
             };
-            const wallTimer = setTimeout(fireTimeout, policy.wallTimeoutMs);
+            const wallTimer = setTimeout(() => fireTimeout("wall"), policy.wallTimeoutMs);
             wallTimer.unref?.();
             armIdle();
             const originalOnEvent = deps.onEvent;
@@ -150,8 +159,11 @@ export function withResilience(base, policy, opts = {}) {
                 telemetry?.({
                     stageId: stage.id,
                     ...(ctx.lens ? { lens: ctx.lens } : {}),
+                    ...(stage.agent ? { agent: stage.agent } : {}),
+                    ...(deps.taskIndex !== undefined ? { taskIndex: deps.taskIndex } : {}),
                     attempt,
                     outcome,
+                    ...(timedOut && timeoutKind ? { timeoutKind } : {}),
                     exitCode: last.exitCode,
                     ...(last.stopReason ? { stopReason: last.stopReason } : {}),
                     elapsedMs,
@@ -167,12 +179,17 @@ export function withResilience(base, policy, opts = {}) {
                 record("ok", false);
                 return last;
             }
-            if (timedOut)
-                last.errorMessage = TIMEOUT_MESSAGE;
+            if (timedOut) {
+                last.errorMessage = timeoutKind === "wall" ? WALL_TIMEOUT_MESSAGE : timeoutKind === "idle" ? IDLE_TIMEOUT_MESSAGE : TIMEOUT_MESSAGE;
+            }
             const transient = classifyTransient(last, timedOut);
+            // A wall-clock exhaustion is a "task too big" signal, not a stall: a
+            // lane that opts out (subagents) fails honestly instead of re-burning
+            // the same 20 minutes per attempt. Idle stalls stay retryable.
+            const wallNotRetryable = timedOut && timeoutKind === "wall" && policy.retryWallTimeout === false;
             // No double-apply: a write stage that already started working is never re-run.
             const blockedByWriteGate = isWriteStage && sawAnyEvent;
-            const willRetry = transient && !blockedByWriteGate && attempt < policy.maxAttempts;
+            const willRetry = transient && !wallNotRetryable && !blockedByWriteGate && attempt < policy.maxAttempts;
             record(timedOut ? "timeout" : transient ? "transient" : "fatal", willRetry);
             if (!willRetry)
                 return last;

package/dist/extension/pipeline/runner.d.ts

@@ -54,6 +54,20 @@ export interface RunStageDeps {
      * subagent tool and the advisor pass their own label through this seam.
      */
     callerLabel?: string;
+    /**
+     * Write-gate override for the resilience wrapper: whether THIS child's tool
+     * list can mutate the workspace (edit/write). The subagent tool sets it per
+     * agent (read-only verifiers retry; edit-capable children do not); the /go
+     * pipeline leaves it absent so the stage-id vocabulary decides as before.
+     */
+    stageWriteCapable?: boolean;
+    /**
+     * Which task of a multi-task subagent call this child runs (0-based). Rides
+     * the resilience attempt record only — content-free attribution so parallel
+     * same-agent failures stay distinguishable in the telemetry. Absent for
+     * single-task /go stages.
+     */
+    taskIndex?: number;
     /**
      * Additive live tap: invoked once per parsed NDJSON event, in stream order,
      * right after it is buffered for the reducers. PURE side-channel for the

package/dist/extension/pipeline/types.d.ts

@@ -524,6 +524,14 @@ export interface ResiliencePolicy {
     backoffMaxMs: number;
     /** Jitter as a fraction of the computed delay, applied as +/- (0 = none). */
     jitterRatio: number;
+    /**
+     * Whether a WALL-clock exhaustion is retryable. Default true (the /go
+     * doctrine: a wedged stage is worth another attempt). A lane whose children
+     * run read-only, fast work (subagents) sets false: a 20-minute burn means
+     * the task is too big, and re-running it just multiplies the spend before
+     * the same honest fail. Idle-stall timeouts stay retryable either way.
+     */
+    retryWallTimeout?: boolean;
 }
 /**
  * Default resilience policy. Generous timeouts so a legitimately long but live

package/dist/extension/pipeline/types.js

@@ -29,6 +29,7 @@ export const DEFAULT_RESILIENCE_POLICY = {
     backoffBaseMs: 1_000,
     backoffMaxMs: 30_000,
     jitterRatio: 0.25,
+    retryWallTimeout: true,
 };
 /**
  * R3-a tool-failure health gate. A WRITE stage (implement / fix) that exits 0 is

package/dist/extension/subagentRender.d.ts

@@ -53,6 +53,8 @@ export interface SubagentTaskProgress {
 }
 export interface SubagentDetails {
     tasks: SubagentTaskProgress[];
+    /** True when every task in the call failed — keys the tool_result handler's isError override. */
+    allFailed?: boolean;
 }
 /** Bound on the retained action log so a chatty child cannot grow details unbounded. */
 export declare const ACTION_LOG_MAX = 120;

package/dist/extension/subagents.d.ts

@@ -21,9 +21,22 @@ import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-cod
 import { Type } from "typebox";
 import type { ChildUsageHandle } from "./childUsage.js";
 import type { WorkingLineHandle } from "./workingLine.js";
+import { type ResilienceAttemptRecord } from "./pipeline/resilience.js";
 import { runStage } from "./pipeline/runner.js";
-import { type ModelTier, type PipelineStage } from "./pipeline/types.js";
+import { type ModelTier, type PipelineStage, type ResiliencePolicy } from "./pipeline/types.js";
 import { renderSubagentCall, renderSubagentResult } from "./subagentRender.js";
+/**
+ * pi's tool contract signals an error by THROWING, and a normally-returned
+ * result is always isError=false — the `isError` field on an AgentToolResult
+ * is never read by the agent loop. But the `tool_result` EXTENSION event CAN
+ * override the flag (`{ isError: true }` from a handler is merged by
+ * agent-session's afterToolCall). A completed subagent call that failed ALL
+ * its tasks must keep the partial child output in the content (so throwing
+ * is wrong there), and this handler is the one seam that marks it as an
+ * error in session history. Registered by registerSubagents; fail-soft —
+ * a throw inside is swallowed by the runner anyway, but never rely on it.
+ */
+export declare function registerSubagentFailureFlag(pi: ExtensionAPI): void;
 export declare const SUBAGENT_TOOL_NAME = "subagent";
 export declare const GENERAL_AGENT_NAME = "general";
 export declare const MAX_PARALLEL_SUBAGENTS = 4;
@@ -93,6 +106,8 @@ export interface MakeSubagentToolDeps {
     runStageImpl?: typeof runStage;
     discover?: (deps: DiscoverDeps) => SubagentDef[];
     homeDir?: string;
+    /** Env seam for the telemetry sessionId read (defaults to process.env). */
+    env?: NodeJS.ProcessEnv;
     /** Live ultra-mode probe (/ultra): widens the per-call fan-out ceiling. */
     isUltra?: () => boolean;
     /**
@@ -116,6 +131,22 @@ export interface MakeSubagentToolDeps {
      */
     childUsage?: ChildUsageHandle;
 }
+/**
+ * The subagent lane's resilience policy: the /go defaults, except a wall-
+ * clock exhaustion is NOT retried (a 20-minute burn means the task is too
+ * big — fail honestly instead of re-burning it per attempt; idle stalls stay
+ * retryable). Exported so a test can pin the composed policy the production
+ * path actually runs (every unit test injects runStageImpl instead).
+ */
+export declare function subagentRunPolicy(): ResiliencePolicy;
+/**
+ * The per-attempt telemetry adapter: one content-free error-sink row per
+ * resilience attempt (agent, taskIndex, outcome, timeoutKind, exit code,
+ * elapsed, willRetry — never task text or stderr). Exported for the same
+ * reason as subagentRunPolicy: the default `run` composes it, and a test
+ * drives the exact production adapter rather than a parallel re-statement.
+ */
+export declare function subagentTelemetry(env: NodeJS.ProcessEnv): (rec: ResilienceAttemptRecord) => void;
 export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
     name: string;
     label: string;
@@ -139,20 +170,13 @@ export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
         }>;
         details: unknown;
     }) => void, ctx?: ExtensionContext): Promise<{
-        content: {
-            type: "text";
-            text: string;
-        }[];
-        details: {};
-        isError: boolean;
-    } | {
-        isError?: boolean | undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: {
             tasks: import("./subagentRender.js").SubagentTaskProgress[];
+            allFailed: boolean;
         };
     }>;
 };
@@ -168,7 +192,7 @@ export interface RegisterSubagentsDeps {
     /** Session child-usage accumulator; see MakeSubagentToolDeps.childUsage. */
     childUsage?: ChildUsageHandle;
 }
-/** Wire the subagent tool and the /agents listing command. */
+/** Wire the subagent tool, the failure flag handler, and the /agents listing command. */
 export declare function registerSubagents(pi: ExtensionAPI, deps?: RegisterSubagentsDeps): void;
 export {};
 //# sourceMappingURL=subagents.d.ts.map

package/dist/extension/subagents.js

@@ -23,10 +23,39 @@ import { delimiter, join } from "node:path";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { sanitizeCallerSegment } from "./config.js";
+import { logEvent } from "./errorSink.js";
 import { withResilience } from "./pipeline/resilience.js";
 import { runStage } from "./pipeline/runner.js";
 import { DEFAULT_RESILIENCE_POLICY } from "./pipeline/types.js";
 import { applyChildEvent, finalizeTask, formatWorkingMessage, newTaskProgress, progressSummaryText, renderSubagentCall, renderSubagentResult, } from "./subagentRender.js";
+/**
+ * pi's tool contract signals an error by THROWING, and a normally-returned
+ * result is always isError=false — the `isError` field on an AgentToolResult
+ * is never read by the agent loop. But the `tool_result` EXTENSION event CAN
+ * override the flag (`{ isError: true }` from a handler is merged by
+ * agent-session's afterToolCall). A completed subagent call that failed ALL
+ * its tasks must keep the partial child output in the content (so throwing
+ * is wrong there), and this handler is the one seam that marks it as an
+ * error in session history. Registered by registerSubagents; fail-soft —
+ * a throw inside is swallowed by the runner anyway, but never rely on it.
+ */
+export function registerSubagentFailureFlag(pi) {
+    pi.on("tool_result", async (event) => {
+        try {
+            if (event.toolName !== SUBAGENT_TOOL_NAME || event.isError)
+                return undefined;
+            const details = event.details;
+            if (!details || typeof details !== "object" || !Array.isArray(details.tasks))
+                return undefined;
+            if (!details.allFailed)
+                return undefined;
+            return { isError: true };
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
 /**
  * YAG-471 attribution: the `x-yagni-caller` prefix for a subagent invocation.
  * The sanitized agent name is capped so the WHOLE label (prefix + name) stays
@@ -274,6 +303,15 @@ function loadAgentsFromDir(dir, source) {
                 agents.push(def);
         }
         catch {
+            // A malformed file used to vanish silently — now it leaves a warn row in
+            // the sink so a broken definition is diagnosable. Content-free: dir +
+            // file name only, never the parse error text (unknown shape).
+            logEvent({
+                source: "subagent",
+                level: "warn",
+                event: "agent_file_unparseable",
+                fields: { dir, file: entry.name },
+            });
             continue;
         }
     }
@@ -419,19 +457,61 @@ const parameters = Type.Object({
     agent: Type.Optional(Type.String({ description: "Agent name (see /agents). Defaults to general." })),
     tasks: Type.Optional(Type.Array(Type.Object({
         task: Type.String(),
-        agent: Type.Optional(Type.String()),
+        agent: Type.Optional(Type.String({ description: "Agent name; defaults to the top-level `agent`, then general." })),
     }), {
-        description: `Run several independent tasks in parallel (max ${MAX_PARALLEL_SUBAGENTS}; ${MAX_PARALLEL_SUBAGENTS_ULTRA} in ultra mode). Use INSTEAD of task.`,
+        description: `Run several independent tasks in parallel (max ${MAX_PARALLEL_SUBAGENTS}; ${MAX_PARALLEL_SUBAGENTS_ULTRA} in ultra mode). Use INSTEAD of task. Entries without their own agent run as the top-level agent.`,
     })),
 });
+/**
+ * The subagent lane's resilience policy: the /go defaults, except a wall-
+ * clock exhaustion is NOT retried (a 20-minute burn means the task is too
+ * big — fail honestly instead of re-burning it per attempt; idle stalls stay
+ * retryable). Exported so a test can pin the composed policy the production
+ * path actually runs (every unit test injects runStageImpl instead).
+ */
+export function subagentRunPolicy() {
+    return { ...DEFAULT_RESILIENCE_POLICY, retryWallTimeout: false };
+}
+/**
+ * The per-attempt telemetry adapter: one content-free error-sink row per
+ * resilience attempt (agent, taskIndex, outcome, timeoutKind, exit code,
+ * elapsed, willRetry — never task text or stderr). Exported for the same
+ * reason as subagentRunPolicy: the default `run` composes it, and a test
+ * drives the exact production adapter rather than a parallel re-statement.
+ */
+export function subagentTelemetry(env) {
+    return (rec) => logEvent({
+        source: "subagent",
+        level: rec.outcome === "ok" ? "info" : rec.outcome === "timeout" || rec.outcome === "fatal" ? "error" : "warn",
+        event: `attempt_${rec.outcome}`,
+        sessionId: env.YAGNI_SESSION_ID,
+        fields: {
+            ...(rec.agent ? { agent: rec.agent } : {}),
+            ...(rec.taskIndex !== undefined ? { taskIndex: rec.taskIndex } : {}),
+            attempt: rec.attempt,
+            ...(rec.timeoutKind ? { timeoutKind: rec.timeoutKind } : {}),
+            exitCode: rec.exitCode,
+            ...(rec.stopReason ? { stopReason: rec.stopReason } : {}),
+            elapsedMs: rec.elapsedMs,
+            willRetry: rec.willRetry,
+        },
+    });
+}
 export function makeSubagentTool(deps = {}) {
     // The default runner rides the /go pipeline's resilience wrapper, so a chat
     // subagent gets the same idle + wall-clock ceilings and transient-only retry
     // as a /go stage child (previously a hung subagent hung the tool call until
-    // the user pressed Esc). The synthetic stage id is "implement", so the
-    // wrapper's write-gate already refuses to re-run a child that may have
-    // landed a partial edit.
-    const run = deps.runStageImpl ?? withResilience(runStage, DEFAULT_RESILIENCE_POLICY);
+    // the user pressed Esc). Two subagent-specific knobs ride the wrapper:
+    // retryWallTimeout=false (a 20-minute burn means the task is too big — fail
+    // honestly instead of re-burning it per attempt) and per-attempt telemetry
+    // into the error sink (a subagent failure previously left NO trace outside
+    // the tool result text). The write-gate keys on the resolved agent's tools,
+    // passed per task below — the synthetic stage id is "implement" and would
+    // otherwise block retry of a read-only verifier forever.
+    const run = deps.runStageImpl ??
+        withResilience(runStage, subagentRunPolicy(), {
+            telemetry: subagentTelemetry(deps.env ?? process.env),
+        });
     const discover = deps.discover ?? discoverSubagents;
     const grounded = deps.grounded !== false;
     // Resolve the effective body for a spawned subagent: the grounding-free
@@ -442,6 +522,29 @@ export function makeSubagentTool(deps = {}) {
             return def.body;
         return BUILTIN_BLIND_BODIES[def.name] ?? def.body;
     };
+    // One-line-per-agent listing so the model never guesses a name (a
+    // hallucinated agent name is a hard error). Built at registration time —
+    // the list is current as of session launch; /agents shows the live set.
+    // Fails soft: discovery problems never block the tool.
+    let agentListBlock = "";
+    try {
+        const discovered = discover({ cwd: process.cwd(), homeDir: deps.homeDir });
+        if (discovered.length > 0) {
+            agentListBlock =
+                " Available agents (first sentence only; /agents lists them in full):\n" +
+                    discovered
+                        .map((a) => `- ${a.name}: ${a.description.split(/[.!?]/)[0]?.trim() || a.description}`)
+                        .join("\n");
+        }
+    }
+    catch {
+        // A discovery failure here silently ships the tool without the name
+        // enumeration — the model is back to guessing names (the failure class
+        // this listing exists to prevent) — so it must leave a trace. Content-
+        // free: no dir list, no error text (unknown shape).
+        logEvent({ source: "subagent", level: "warn", event: "agent_list_discovery_failed" });
+        agentListBlock = "";
+    }
     return {
         name: SUBAGENT_TOOL_NAME,
         label: "Subagent",
@@ -449,7 +552,9 @@ export function makeSubagentTool(deps = {}) {
             "a compressed report. Use it for context-heavy exploration you don't need blow-by-blow, or to " +
             "run independent tasks in parallel via `tasks`. The subagent shares NONE of your conversation: " +
             "spell out the task completely. Agents come from this repo's .claude/agents and .pi/agents " +
-            "(list them with /agents); omit `agent` for the general-purpose one.",
+            "(list them with /agents); omit `agent` for the general-purpose one. The list below was " +
+            "captured at session launch — if the session's cwd differs from the launch cwd it may be " +
+            "stale; an unknown name is a hard error, so trust /agents over this list when they differ." + agentListBlock,
         promptSnippet: "subagent: delegate a self-contained task (or parallel tasks) to a fresh-context agent; returns its report.",
         parameters,
         // Self-framed: the condensed transcript look has no tinted tool boxes.
@@ -457,11 +562,15 @@ export function makeSubagentTool(deps = {}) {
         renderCall: renderSubagentCall,
         renderResult: renderSubagentResult,
         async execute(toolCallId, params, signal, onUpdate, ctx) {
-            const fail = (text) => ({
-                content: [{ type: "text", text }],
-                details: {},
-                isError: true,
-            });
+            // pi's tool contract signals an error by THROWING: a normally-returned
+            // result is always isError=false (agent-loop.js stamps it), and the
+            // `isError` field on a returned AgentToolResult was never read — the
+            // old `fail()` helper's flag was inert, so the driver model saw these
+            // as normal text. Thrown Error messages become the tool result content
+            // verbatim with isError=true, which is exactly the old intent.
+            const fail = (text) => {
+                throw new Error(text);
+            };
             const requested = params.tasks && params.tasks.length > 0
                 ? params.tasks
                 : params.task
@@ -478,7 +587,10 @@ export function makeSubagentTool(deps = {}) {
             const agents = discover({ cwd, homeDir: deps.homeDir });
             const resolved = [];
             for (const req of requested) {
-                const name = (req.agent ?? GENERAL_AGENT_NAME).toLowerCase();
+                // A tasks[] entry names its own agent first; absent that, it inherits
+                // the call's top-level `agent` (previously silently dropped here, so
+                // `{agent: "verification", tasks: [{task}]}` ran as general).
+                const name = (req.agent ?? params.agent ?? GENERAL_AGENT_NAME).toLowerCase();
                 const def = agents.find((a) => a.name === name);
                 if (!def) {
                     return fail(`Error: unknown agent "${name}". Available agents:\n${formatAgentList(agents)}`);
@@ -518,6 +630,21 @@ export function makeSubagentTool(deps = {}) {
                     const result = await run(stage, stageCtx, {
                         cwd,
                         signal,
+                        // Write-gate input: whether the agent's DECLARED tool list has
+                        // edit/write. This is a retry-discipline heuristic, not a
+                        // capability claim — bash can still mutate, but it runs behind
+                        // the same sandbox + permission stack as the driver's, and the
+                        // gate's purpose is only to refuse re-running a child that may
+                        // have landed a partial edit. Read-only-by-declaration verifiers
+                        // retry freely; edit-capable children keep the discipline.
+                        // Computed from the tools the runner will actually pass the
+                        // child (`--tools`), so a custom definition cannot opt out by
+                        // name.
+                        stageWriteCapable: (stage.tools).some((t) => t === "edit" || t === "write"),
+                        // Content-free task discriminator: which entry of THIS call's
+                        // task list the attempt belongs to (parallel same-agent
+                        // failures stay attributable without leaking task text).
+                        taskIndex: index,
                         personaBody: () => bodyFor(def),
                         // YAG-471: attribute this child's completions to the specific
                         // subagent, not the generic /go stage label the runner would
@@ -535,7 +662,7 @@ export function makeSubagentTool(deps = {}) {
                     // identity — per invocation, so parallel tasks never collide).
                     deps.childUsage?.record("subagent", progressKey(toolCallId, progress, index), result.usage);
                     emit();
-                    return { agent: def.name, task, result };
+                    return { agent: def.name, task, result, def };
                 }));
             }
             finally {
@@ -548,29 +675,46 @@ export function makeSubagentTool(deps = {}) {
             const allFailed = outcomes.every((o) => o.result.exitCode !== 0);
             const sections = outcomes.map((o) => {
                 const output = o.result.finalOutput.trim();
+                // Honest failure framing: the child's partial text must never read as
+                // a completed report. The prefix says what happened; the failed note
+                // keeps the exit code + stderr tail for diagnosis. Plain text only
+                // (no emojis — this reaches the driver model's context).
+                const failureBanner = o.result.exitCode !== 0
+                    ? `SUBAGENT FAILED (exit ${o.result.exitCode}${o.result.errorMessage ? `, ${o.result.errorMessage}` : ""}) — the text below is PARTIAL output, not a completed report.`
+                    : "";
                 const failedNote = o.result.exitCode !== 0
                     ? `\n\n(subagent failed, exit ${o.result.exitCode}${o.result.stderr.trim() ? `: ${o.result.stderr.trim().slice(-500)}` : ""})`
                     : "";
                 const bodyText = output || (o.result.exitCode === 0 ? "(no output)" : "");
+                // The verification agent's contract is a `## Verdict` header; an
+                // output without it is not a verdict, and the driver must not treat
+                // a truncated probe log as "HOLDS".
+                const missingVerdict = o.def.source === "builtin" && o.agent === "verification" && o.result.exitCode === 0 && !output.includes("## Verdict")
+                    ? "\n\n(no verdict — the verification run did not produce its verdict section)"
+                    : "";
                 return outcomes.length === 1
-                    ? `${bodyText}${failedNote}`
-                    : `## ${o.agent}: ${o.task}\n\n${bodyText}${failedNote}`;
+                    ? `${failureBanner ? failureBanner + "\n\n" : ""}${bodyText}${missingVerdict}${failedNote}`
+                    : `## ${o.agent}: ${o.task}\n\n${failureBanner ? failureBanner + "\n\n" : ""}${bodyText}${missingVerdict}${failedNote}`;
             });
             return {
                 content: [{ type: "text", text: sections.join("\n\n") }],
                 // The folded progress records ARE the final details: a superset of the
                 // old {agent, task, exitCode, usage, toolCalls} shape, plus the action
-                // log and report that renderSubagentResult paints.
-                details: { tasks: progresses },
-                ...(allFailed ? { isError: true } : {}),
+                // log and report that renderSubagentResult paints. `allFailed` keys
+                // the tool_result handler's isError override (see
+                // registerSubagentFailureFlag) — the returned field itself is inert
+                // in pi's contract (errors are signaled by throwing, and here we keep
+                // the partial child output in the result instead).
+                details: { tasks: progresses, allFailed },
             };
         },
     };
 }
-/** Wire the subagent tool and the /agents listing command. */
+/** Wire the subagent tool, the failure flag handler, and the /agents listing command. */
 export function registerSubagents(pi, deps = {}) {
     const discover = deps.discover ?? discoverSubagents;
     pi.registerTool(makeSubagentTool(deps));
+    registerSubagentFailureFlag(pi);
     pi.registerCommand("agents", {
         description: "List the subagents available in this repo (.claude/agents, .pi/agents).",
         handler: async (_args, ctx) => {

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 = {
@@ -194,16 +253,6 @@ export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoIte
         details: {
             todos: TodoItem[];
         };
-        isError: boolean;
-    } | {
-        content: {
-            type: "text";
-            text: string;
-        }[];
-        details: {
-            todos: TodoItem[];
-        };
-        isError?: undefined;
     }>;
 };
 /**

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",
         });
@@ -367,16 +504,30 @@ export function makeTodoTool(get, set, completedAt) {
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const normalized = normalizeTodos(params.todos);
             if (!normalized.ok) {
-                return {
-                    content: [{ type: "text", text: `Error: ${normalized.error}` }],
-                    details: { todos: get() },
-                    isError: true,
-                };
+                // pi signals tool errors by THROWING (a returned result is always
+                // isError=false; the returned `isError` field was never read), so the
+                // error text must ride the thrown message to reach the model as an
+                // 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.1376.1",
+  "version": "1.1.3-staging.1378.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": "ad5363e506fdbfaa52dc79d778d3488661659426"
+  "yagniSourceSha": "cc4bcf38093fc70fc51ed4b712777566307a1e72"
 }