@yagni-app/code 0.2.1 → 0.3.1

package/dist/extension/subagents.js

@@ -23,7 +23,10 @@ import { delimiter, join } from "node:path";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { sanitizeCallerSegment } from "./config.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";
 /**
  * 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
@@ -33,6 +36,8 @@ const SUBAGENT_CALLER_PREFIX = "subagent:";
 export const SUBAGENT_TOOL_NAME = "subagent";
 export const GENERAL_AGENT_NAME = "general";
 export const MAX_PARALLEL_SUBAGENTS = 4;
+/** Wider fan-out ceiling while the session is in ultra mode (/ultra). */
+export const MAX_PARALLEL_SUBAGENTS_ULTRA = 8;
 /**
  * The default tool surface a subagent gets when its definition declares none:
  * the full working set plus grounded answers, mirroring what a Claude Code
@@ -75,6 +80,97 @@ const GENERAL_AGENT = {
     body: GENERAL_BODY,
     source: "builtin",
 };
+const SEARCHER_BODY = `You are a repo scout. Your job is wide, mechanical reconnaissance:
+find files, map structure, trace usages, and summarize what is there. You do
+not write code and you do not run commands; you read and report.
+
+You are grounded in how THIS company works: call ask_yagni before inferring a
+convention, an ownership rule, or anything organization-specific.
+
+Your final message is your report back to the driving agent, which has NOT
+seen what you read. Make it compressed and complete: exact file paths, the
+key excerpts, and a one-paragraph map of how the pieces relate. Say what you
+did NOT find as plainly as what you found.`;
+/** Wide search and repo mapping on the cheapest tier: read-only by
+ * construction, so a wrong answer costs a re-ask, never a bad edit. */
+const SEARCHER_AGENT = {
+    name: "searcher",
+    description: "Fast repo reconnaissance: wide searches, structure mapping, usage tracing, " +
+        "summarizing files. Read-only. Use for any broad look-around you would " +
+        "otherwise do with a chain of grep/read calls.",
+    model: "efficient",
+    tools: ["read", "grep", "find", "ls", "ask_yagni"],
+    body: SEARCHER_BODY,
+    source: "builtin",
+};
+const IMPLEMENTER_BODY = `You are a mechanical implementer. You execute a
+well-specified change: apply an edit across files, fix a failing test, rename
+carefully, wire a defined seam. The judgment calls were made before you were
+spawned; if the task turns out to require one, STOP and report the fork in
+your final message instead of guessing.
+
+You are grounded in how THIS company works: call ask_yagni before inferring a
+convention, an ownership rule, or anything organization-specific.
+
+Your final message is your report back to the driving agent, which has NOT
+seen what you did. List every file you touched, what changed in each, the
+commands you ran with their outcomes, and anything you deliberately left
+undone.`;
+/** Mechanical multi-file execution on the mid tier: the task arrives fully
+ * specified, so the premium tiers' judgment is not being paid for. */
+const IMPLEMENTER_AGENT = {
+    name: "implementer",
+    description: "Mechanical execution of a fully-specified change: multi-file edits, " +
+        "test-fix grinds, careful renames. Spawn it with the decision already " +
+        "made; it stops and reports rather than improvising.",
+    model: "standard",
+    body: IMPLEMENTER_BODY,
+    source: "builtin",
+};
+const VERIFICATION_BODY = `You are an adversarial verifier. Another agent
+produced work — a change, a plan, or a claim — and your job is to try to
+BREAK it, not to summarize it. Default to skepticism: hunt for the concrete
+failure scenario (the inputs, state, or sequence that makes it wrong). Bash
+is read-only here (\`git diff\`, \`git log\`, \`git show\`); do NOT modify files
+or run builds.
+
+If your task names a lens (correctness, edge cases, codebase fit, security,
+…), judge ONLY through that lens and leave the rest to your sibling
+verifiers.
+
+You are grounded in how THIS company works: call ask_yagni before inferring
+a convention, an ownership rule, or anything organization-specific.
+
+Your final message is your verdict back to the driving agent, which has NOT
+seen what you read. Format:
+## Verdict
+BROKEN or HOLDS, with one sentence why.
+## Findings
+Each real problem: file:line, the concrete failure scenario, severity. No
+style nits.
+## Not verified
+What you could not check, and why.
+
+A HOLDS after real digging is valuable; a rubber stamp is not. If you found
+nothing, say exactly what you tried to break and how.`;
+/** The diamond's reduce layer: refute-first review of completed work on the
+ * advanced tier (judgment is the whole job, so the premium is worth paying —
+ * the server clamps subagent children at advanced anyway). It has no
+ * edit/write tools; bash is included for `git diff`-style inspection and is
+ * restricted to read-only USE by the persona, the same prompt-level stance as
+ * /go's reviewer — not a technical guarantee. */
+const VERIFICATION_AGENT = {
+    name: "verification",
+    description: "Adversarial verification of completed work: tries to refute a change, " +
+        "plan, or claim and reports concrete failure scenarios. Does not edit " +
+        "files. Fan out 2-3 with different lenses (correctness, edge cases, " +
+        "codebase fit) for anything significant and treat agreement as " +
+        "confirmation.",
+    model: "advanced",
+    tools: ["read", "grep", "find", "ls", "bash", "ask_yagni"],
+    body: VERIFICATION_BODY,
+    source: "builtin",
+};
 // Concrete tiers a subagent can actually run on. `balanced` is deliberately NOT
 // a member here even though it is a member of `ModelTier`: a subagent needs
 // ONE model for its whole run, and balanced is a session-level routing policy,
@@ -162,7 +258,7 @@ function loadAgentsFromDir(dir, source) {
 export function discoverSubagents(deps) {
     const home = deps.homeDir ?? homedir();
     const layers = [
-        [GENERAL_AGENT],
+        [GENERAL_AGENT, SEARCHER_AGENT, IMPLEMENTER_AGENT, VERIFICATION_AGENT],
         ...pluginAgentDirs(deps.env ?? process.env).map((dir) => loadAgentsFromDir(dir, "plugin")),
         loadAgentsFromDir(join(home, ".claude", "agents"), "user-claude"),
         loadAgentsFromDir(join(deps.cwd, ".pi", "agents"), "project-pi"),
@@ -213,11 +309,17 @@ const parameters = Type.Object({
         task: Type.String(),
         agent: Type.Optional(Type.String()),
     }), {
-        description: `Run several independent tasks in parallel (max ${MAX_PARALLEL_SUBAGENTS}). 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.`,
     })),
 });
 export function makeSubagentTool(deps = {}) {
-    const run = deps.runStageImpl ?? runStage;
+    // 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);
     const discover = deps.discover ?? discoverSubagents;
     return {
         name: SUBAGENT_TOOL_NAME,
@@ -229,6 +331,8 @@ export function makeSubagentTool(deps = {}) {
             "(list them with /agents); omit `agent` for the general-purpose one.",
         promptSnippet: "subagent: delegate a self-contained task (or parallel tasks) to a fresh-context agent; returns its report.",
         parameters,
+        renderCall: renderSubagentCall,
+        renderResult: renderSubagentResult,
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
             const fail = (text) => ({
                 content: [{ type: "text", text }],
@@ -243,8 +347,9 @@ export function makeSubagentTool(deps = {}) {
             if (requested.length === 0) {
                 return fail("Error: pass `task` (or a `tasks` array) describing what to do.");
             }
-            if (requested.length > MAX_PARALLEL_SUBAGENTS) {
-                return fail(`Error: at most ${MAX_PARALLEL_SUBAGENTS} parallel tasks per call.`);
+            const maxParallel = deps.isUltra?.() ? MAX_PARALLEL_SUBAGENTS_ULTRA : MAX_PARALLEL_SUBAGENTS;
+            if (requested.length > maxParallel) {
+                return fail(`Error: at most ${maxParallel} parallel tasks per call.`);
             }
             const cwd = ctx?.cwd ?? process.cwd();
             const agents = discover({ cwd, homeDir: deps.homeDir });
@@ -257,31 +362,56 @@ export function makeSubagentTool(deps = {}) {
                 }
                 resolved.push({ def, task: req.task });
             }
-            onUpdate?.({
-                content: [
-                    {
-                        type: "text",
-                        text: resolved.length === 1
-                            ? `Running ${resolved[0].def.name} subagent…`
-                            : `Running ${resolved.length} subagents in parallel…`,
+            // Live progress: one folded record per task rides every partial update's
+            // `details` (rendered by renderSubagentResult), the plain-text summary
+            // rides `content` (pi's fallback renderer and headless consumers), and
+            // the harness "Working…" line mirrors the aggregate while children run.
+            const progresses = resolved.map(({ def, task }) => newTaskProgress(def.name, task, Date.now()));
+            const ui = ctx?.hasUI ? ctx.ui : undefined;
+            let lastWorking;
+            const emit = () => {
+                const now = Date.now();
+                onUpdate?.({
+                    content: [{ type: "text", text: progressSummaryText(progresses, now) }],
+                    details: {
+                        tasks: progresses.map((p) => ({ ...p, actions: [...p.actions], usage: { ...p.usage } })),
                     },
-                ],
-                details: {},
-            });
-            const outcomes = await Promise.all(resolved.map(async ({ def, task }) => {
-                const { stage, ctx: stageCtx } = buildSubagentStage(def, task);
-                const result = await run(stage, stageCtx, {
-                    cwd,
-                    signal,
-                    personaBody: () => def.body,
-                    // YAG-471: attribute this child's completions to the specific
-                    // subagent, not the generic /go stage label the runner would
-                    // otherwise derive from stage.id ("implement", reused as the
-                    // synthetic subagent stage — see buildSubagentStage).
-                    callerLabel: `${SUBAGENT_CALLER_PREFIX}${sanitizeCallerSegment(def.name, 64 - SUBAGENT_CALLER_PREFIX.length)}`,
                 });
-                return { agent: def.name, task, result };
-            }));
+                const working = formatWorkingMessage(progresses, now);
+                if (ui && working !== lastWorking) {
+                    lastWorking = working;
+                    ui.setWorkingMessage?.(working);
+                }
+            };
+            emit();
+            let outcomes;
+            try {
+                outcomes = await Promise.all(resolved.map(async ({ def, task }, index) => {
+                    const progress = progresses[index];
+                    const { stage, ctx: stageCtx } = buildSubagentStage(def, task);
+                    const result = await run(stage, stageCtx, {
+                        cwd,
+                        signal,
+                        personaBody: () => def.body,
+                        // YAG-471: attribute this child's completions to the specific
+                        // subagent, not the generic /go stage label the runner would
+                        // otherwise derive from stage.id ("implement", reused as the
+                        // synthetic subagent stage — see buildSubagentStage).
+                        callerLabel: `${SUBAGENT_CALLER_PREFIX}${sanitizeCallerSegment(def.name, 64 - SUBAGENT_CALLER_PREFIX.length)}`,
+                        onEvent: (ev) => {
+                            if (applyChildEvent(progress, ev))
+                                emit();
+                        },
+                    });
+                    finalizeTask(progress, result, Date.now());
+                    emit();
+                    return { agent: def.name, task, result };
+                }));
+            }
+            finally {
+                // Restore the default "Working…" text whether we resolved or threw.
+                ui?.setWorkingMessage?.();
+            }
             const allFailed = outcomes.every((o) => o.result.exitCode !== 0);
             const sections = outcomes.map((o) => {
                 const output = o.result.finalOutput.trim();
@@ -295,15 +425,10 @@ export function makeSubagentTool(deps = {}) {
             });
             return {
                 content: [{ type: "text", text: sections.join("\n\n") }],
-                details: {
-                    tasks: outcomes.map((o) => ({
-                        agent: o.agent,
-                        task: o.task,
-                        exitCode: o.result.exitCode,
-                        usage: o.result.usage,
-                        toolCalls: o.result.toolCalls,
-                    })),
-                },
+                // 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 } : {}),
             };
         },

package/dist/extension/ticketTools.d.ts

@@ -0,0 +1,37 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+/**
+ * Ticket write-back tools (spec 2026-08-09): file a ticket, move a ticket.
+ *
+ * Both are EXPLICIT user-intent actions — the guidelines pin the agent to
+ * calling them only when the developer asked. Writes execute server-side as
+ * the developer's own tracker account (per-user write identity); when no
+ * personal connection exists the backend answers 412 `connect_required` and
+ * the tool renders the one-time connect prompt instead of failing opaquely.
+ */
+export interface MakeTicketToolOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+}
+declare const fileTicketParams: Type.TObject<{
+    title: Type.TString;
+    description: Type.TOptional<Type.TString>;
+    tracker: Type.TOptional<Type.TUnion<[Type.TLiteral<"jira">, Type.TLiteral<"linear">]>>;
+    target_key: Type.TOptional<Type.TString>;
+}>;
+export declare function makeFileTicketTool(opts: MakeTicketToolOptions): ToolDefinition<typeof fileTicketParams, {
+    identifier?: string;
+    url?: string | null;
+}>;
+declare const updateTicketStatusParams: Type.TObject<{
+    ref: Type.TString;
+    status: Type.TString;
+    tracker: Type.TOptional<Type.TUnion<[Type.TLiteral<"jira">, Type.TLiteral<"linear">]>>;
+}>;
+export declare function makeUpdateTicketStatusTool(opts: MakeTicketToolOptions): ToolDefinition<typeof updateTicketStatusParams, {
+    identifier?: string;
+    state?: string;
+}>;
+export {};
+//# sourceMappingURL=ticketTools.d.ts.map

package/dist/extension/ticketTools.js

@@ -0,0 +1,117 @@
+import { Type } from "typebox";
+import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch, } from "./resilientFetch.js";
+/** Render backend problem responses (412/404/422) as agent-relayable text. */
+async function renderProblem(toolName, res) {
+    let body = null;
+    try {
+        body = (await res.clone().json());
+    }
+    catch {
+        body = null;
+    }
+    if (res.status === 412 && body?.error === "connect_required") {
+        return [
+            `A personal ${body.service ?? "tracker"} connection is needed to write as you.`,
+            `Connect here (one time): ${body.connect_url ?? "(ask your admin for the connect link)"}`,
+            "Then ask me again and I'll retry.",
+        ].join("\n");
+    }
+    if ((res.status === 404 || res.status === 422) && body?.error) {
+        const options = body.options?.length
+            ? `\nAvailable options: ${body.options.join(", ")}`
+            : "";
+        return `${body.message ?? body.error}${options}`;
+    }
+    throw new Error(await friendlyFetchError(toolName, res));
+}
+const fileTicketParams = Type.Object({
+    title: Type.String(),
+    description: Type.Optional(Type.String()),
+    tracker: Type.Optional(Type.Union([Type.Literal("jira"), Type.Literal("linear")])),
+    target_key: Type.Optional(Type.String()),
+});
+export function makeFileTicketTool(opts) {
+    return {
+        name: "file_ticket",
+        label: "File Ticket",
+        description: "File a ticket in the workspace's tracker (Jira or Linear), attributed to the developer's " +
+            "own account. ONLY call when the user explicitly asks to file/create a ticket — never " +
+            "speculatively, never as a side effect of other work. Pass target_key (Jira project key or " +
+            "Linear team key) when the workspace has more than one.",
+        promptSnippet: "file_ticket: file a ticket in the workspace tracker as the developer (explicit request only).",
+        promptGuidelines: [
+            "Call file_ticket ONLY when the user explicitly asks to file, create, or capture a ticket.",
+            "If the tool reports a connect prompt or asks for a target/tracker, relay it verbatim and wait for the user.",
+        ],
+        parameters: fileTicketParams,
+        async execute(toolCallId, params, signal) {
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/tickets`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${opts.getToken() ?? ""}`,
+                },
+                body: JSON.stringify({ ...params, idempotencyKey: toolCallId }),
+            }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+            if (!res.ok) {
+                const text = await renderProblem("file_ticket", res);
+                return { content: [{ type: "text", text }], details: {} };
+            }
+            const data = (await res.json());
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Filed ${data.identifier}${data.url ? `: ${data.url}` : ""}`,
+                    },
+                ],
+                details: { identifier: data.identifier, url: data.url },
+            };
+        },
+    };
+}
+const updateTicketStatusParams = Type.Object({
+    ref: Type.String(),
+    status: Type.String(),
+    tracker: Type.Optional(Type.Union([Type.Literal("jira"), Type.Literal("linear")])),
+});
+export function makeUpdateTicketStatusTool(opts) {
+    return {
+        name: "update_ticket_status",
+        label: "Update Ticket Status",
+        description: "Move a ticket to a new status by name (e.g. mark YAG-123 In Progress), attributed to the " +
+            "developer's own tracker account. ONLY call on the user's explicit request — never as an " +
+            "automatic side effect of starting or finishing work.",
+        promptSnippet: "update_ticket_status: move a tracker ticket to a named status as the developer (explicit request only).",
+        promptGuidelines: [
+            "Call update_ticket_status ONLY when the user explicitly asks to move/mark a ticket's status.",
+            "If the requested status is not available, relay the offered options and let the user pick.",
+        ],
+        parameters: updateTicketStatusParams,
+        async execute(toolCallId, params, signal) {
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/tickets/transition`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${opts.getToken() ?? ""}`,
+                },
+                body: JSON.stringify({ ...params, idempotencyKey: toolCallId }),
+            }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+            if (!res.ok) {
+                const text = await renderProblem("update_ticket_status", res);
+                return { content: [{ type: "text", text }], details: {} };
+            }
+            const data = (await res.json());
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${data.identifier} → ${data.state ?? params.status}`,
+                    },
+                ],
+                details: { identifier: data.identifier, state: data.state },
+            };
+        },
+    };
+}
+//# sourceMappingURL=ticketTools.js.map

package/dist/extension/todos.d.ts

@@ -17,6 +17,16 @@ import { Type } from "typebox";
 export declare const TODO_TOOL_NAME = "todo_write";
 export declare const MAX_TODOS = 50;
 export declare const MAX_TODO_TEXT = 300;
+/**
+ * Staleness-reminder throttle (both counters must trip): a reminder is
+ * eligible only after this many assistant turns since the last todo_write AND
+ * this many since the last reminder. The two-counter shape (staleness gate +
+ * anti-spam gate) mirrors what Claude Code ships for its own todo tool; the
+ * driver model routinely stops updating the board mid-grind (the frozen
+ * "Todos 0/8" report), and a bare description-level instruction does not
+ * survive a long run.
+ */
+export declare const TODO_REMINDER_TURNS = 10;
 /**
  * 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
@@ -61,6 +71,23 @@ export interface TodoTheme {
 export declare function renderTodoWidget(todos: TodoItem[], theme: TodoTheme): string[];
 /** The desktop state record: exactly one JSON line under TODO_STATE_KEY. */
 export declare function todoStateLine(todos: TodoItem[]): string;
+/**
+ * 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
+ * reached {@link TODO_REMINDER_TURNS}.
+ */
+export declare function shouldRemindTodos(input: {
+    todos: TodoItem[];
+    turnsSinceWrite: number;
+    turnsSinceReminder: number;
+}): boolean;
+/**
+ * PURE: the hedged reminder block appended to a tool result when the board has
+ * gone stale. Carries the CURRENT list so the model can reconcile without a
+ * read, and explicitly licenses ignoring it, so an accurate board costs one
+ * glance rather than a spurious todo_write.
+ */
+export declare function formatTodoReminder(todos: TodoItem[]): string;
 /** Replay the branch: the last todo_write result is the canonical list. */
 export declare function reconstructTodos(entries: unknown[]): TodoItem[];
 type TodoParams = {
@@ -104,7 +131,7 @@ export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoIte
         isError?: undefined;
     }>;
 };
-/** Wire the tool, the branch-replay events, and the /todos command. */
+/** Wire the tool, the branch-replay events, the staleness reminder, and /todos. */
 export declare function registerTodos(pi: ExtensionAPI): void;
 export {};
 //# sourceMappingURL=todos.d.ts.map

package/dist/extension/todos.js

@@ -17,6 +17,16 @@ import { isDesktopSurface } from "./surface.js";
 export const TODO_TOOL_NAME = "todo_write";
 export const MAX_TODOS = 50;
 export const MAX_TODO_TEXT = 300;
+/**
+ * Staleness-reminder throttle (both counters must trip): a reminder is
+ * eligible only after this many assistant turns since the last todo_write AND
+ * this many since the last reminder. The two-counter shape (staleness gate +
+ * anti-spam gate) mirrors what Claude Code ships for its own todo tool; the
+ * driver model routinely stops updating the board mid-grind (the frozen
+ * "Todos 0/8" report), and a bare description-level instruction does not
+ * survive a long run.
+ */
+export const TODO_REMINDER_TURNS = 10;
 const WIDGET_KEY = "yagni-todos";
 /**
  * The desktop's structured state record rides its own widget key, like the
@@ -101,6 +111,33 @@ export function renderTodoWidget(todos, theme) {
 export function todoStateLine(todos) {
     return JSON.stringify({ v: 1, todos });
 }
+/**
+ * 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
+ * reached {@link TODO_REMINDER_TURNS}.
+ */
+export function shouldRemindTodos(input) {
+    const { todos, turnsSinceWrite, turnsSinceReminder } = input;
+    if (todos.length === 0)
+        return false;
+    const { done, total } = todoSummary(todos);
+    if (done === total)
+        return false;
+    return turnsSinceWrite >= TODO_REMINDER_TURNS && turnsSinceReminder >= TODO_REMINDER_TURNS;
+}
+/**
+ * PURE: the hedged reminder block appended to a tool result when the board has
+ * gone stale. Carries the CURRENT list so the model can reconcile without a
+ * read, and explicitly licenses ignoring it, so an accurate board costs one
+ * glance rather than a spurious todo_write.
+ */
+export function formatTodoReminder(todos) {
+    return ("⟦YAGNI todos⟧ The todo_write 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. " +
+        "If the list is already accurate, ignore this.\n" +
+        formatTodoList(todos));
+}
 /** Replay the branch: the last todo_write result is the canonical list. */
 export function reconstructTodos(entries) {
     let todos = [];
@@ -186,9 +223,14 @@ export function makeTodoTool(get, set) {
         },
     };
 }
-/** Wire the tool, the branch-replay events, and the /todos command. */
+/** Wire the tool, the branch-replay events, the staleness reminder, and /todos. */
 export function registerTodos(pi) {
     let todos = [];
+    // Staleness-reminder counters (see TODO_REMINDER_TURNS). Session-local like
+    // the list cache itself; branch replay resets them so a resume/fork never
+    // opens with an instantly-due reminder.
+    let turnsSinceWrite = 0;
+    let turnsSinceReminder = 0;
     const reconstruct = (ctx) => {
         try {
             todos = reconstructTodos(ctx.sessionManager.getBranch());
@@ -196,12 +238,45 @@ export function registerTodos(pi) {
         catch {
             todos = [];
         }
+        turnsSinceWrite = 0;
+        turnsSinceReminder = 0;
         paintWidget(ctx, todos);
     };
     pi.on("session_start", async (_event, ctx) => reconstruct(ctx));
     pi.on("session_tree", async (_event, ctx) => reconstruct(ctx));
+    // Turn counting: one tick per finalized assistant message, the same "turn"
+    // the model experiences between opportunities to call todo_write.
+    pi.on("message_end", async (event) => {
+        if (event.message?.role === "assistant") {
+            turnsSinceWrite += 1;
+            turnsSinceReminder += 1;
+        }
+    });
+    // The reminder rides an existing tool result (the same result-modification
+    // seam ambient recall uses), so it reaches the model mid-run without
+    // spending a turn. Never appended to todo_write's own result, and fail-soft:
+    // a reminder must never break a tool call.
+    pi.on("tool_result", async (event) => {
+        try {
+            if (event.toolName === TODO_TOOL_NAME)
+                return;
+            if (!shouldRemindTodos({ todos, turnsSinceWrite, turnsSinceReminder }))
+                return;
+            turnsSinceReminder = 0;
+            return {
+                content: [
+                    ...event.content,
+                    { type: "text", text: `\n\n${formatTodoReminder(todos)}` },
+                ],
+            };
+        }
+        catch {
+            return;
+        }
+    });
     pi.registerTool(makeTodoTool(() => todos, (next) => {
         todos = next;
+        turnsSinceWrite = 0;
     }));
     pi.registerCommand("todos", {
         description: "Show the agent's current task list for this session.",

package/dist/extension/tokenProvider.js

@@ -130,7 +130,7 @@ export function makeTokenProvider(deps) {
             });
         }, delay);
     }
-    function applyRotation(rotation) {
+    function applyRotation(rotation, skipPersist = false) {
         token = rotation.token;
         if (rotation.expiresAt)
             expiresAt = rotation.expiresAt;
@@ -139,13 +139,45 @@ export function makeTokenProvider(deps) {
         env.YAGNI_TOKEN = rotation.token;
         if (rotation.expiresAt)
             env.YAGNI_TOKEN_EXPIRES_AT = rotation.expiresAt;
+        if (!skipPersist) {
+            try {
+                persistProfile(rotation);
+            }
+            catch {
+                /* fail-soft */
+            }
+        }
+        armProactiveTimer();
+    }
+    /**
+     * Read the token from the launcher's profile file on disk. Used as a fallback
+     * when the server-side refresh fails (the old token is also invalid for
+     * /auth/refresh): an external `yagni login` writes a fresh token to the same
+     * file, so re-reading it can recover a session that the server refresh cannot.
+     * Returns null when the file is missing, unreadable, or carries the same token
+     * already in memory.
+     */
+    function readTokenFromDisk() {
+        const profilePath = env.YAGNI_PROFILE_PATH?.trim();
+        if (!profilePath)
+            return null;
         try {
-            persistProfile(rotation);
+            const parsed = JSON.parse(readFileSync(profilePath, "utf8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return null;
+            const obj = parsed;
+            const diskToken = typeof obj.token === "string" ? obj.token : undefined;
+            if (!diskToken || diskToken === token)
+                return null;
+            return {
+                token: diskToken,
+                expiresAt: typeof obj.expiresAt === "string" ? obj.expiresAt : undefined,
+                workspaceId: typeof obj.workspaceId === "string" ? obj.workspaceId : undefined,
+            };
         }
         catch {
-            /* fail-soft */
+            return null;
         }
-        armProactiveTimer();
     }
     async function doRefresh() {
         const current = token;
@@ -161,8 +193,17 @@ export function makeTokenProvider(deps) {
                 body: "{}",
                 signal: AbortSignal.timeout(REFRESH_REQUEST_TIMEOUT_MS),
             });
-            if (!res.ok)
+            if (!res.ok) {
+                // Server refresh failed (the old token is also invalid for /auth/refresh).
+                // Fall back to the profile file on disk: an external `yagni login` may
+                // have written a fresh token there that this running session hasn't seen.
+                const disk = readTokenFromDisk();
+                if (disk) {
+                    applyRotation(disk, true);
+                    return true;
+                }
                 return false;
+            }
             const data = (await res.json());
             if (!data || typeof data.token !== "string" || data.token.length === 0)
                 return false;