@yagni-app/code 0.3.0 → 0.3.1

package/dist/extension/pipeline/goCommand.js

@@ -77,7 +77,7 @@ import { registerGoStatusCommands } from "./goStatusCommands.js";
 import { runPipeline as defaultRunPipeline } from "./orchestrator.js";
 import { composeAbortSignal } from "./resilience.js";
 import { planResume } from "./resume.js";
-import { activeRunCount, beginRun, classifyRunLiveness, findActiveRunByTicket, isRunInFlight, isTerminalStatus, lastJournalTs, loadRegistryRows, MAX_CONCURRENT_RUNS, settleRun, trackRunAbort, trackRunPromise, worktreesDir, } from "./runRegistry.js";
+import { activeRunCount, beginRun, classifyRunLiveness, findActiveRunByTicket, isRunInFlight, isTerminalStatus, lastJournalTs, loadRegistryRows, resolveMaxConcurrentRuns, settleRun, trackRunAbort, trackRunPromise, worktreesDir, } from "./runRegistry.js";
 import { makeRunSession as defaultMakeRunSession } from "./runSession.js";
 import { recordSessionRun } from "../sessionRuns.js";
 import { resolveTicketBrief as defaultResolveTicketBrief } from "./ticketResolution.js";
@@ -460,13 +460,15 @@ export function registerGoCommand(pi, deps = {}) {
                 return;
             }
             // In-flight guards: the same ticket never runs twice at once in this
-            // process, and at most MAX_CONCURRENT_RUNS runs are in flight.
+            // process, and at most resolveMaxConcurrentRuns() runs are in flight
+            // (default 3; fleet operators raise it via YAGNI_MAX_CONCURRENT_RUNS).
             if (findActiveRunByTicket(ticket)) {
                 notify(`/go ${ticket} is already running - see /go-status.`, "warning");
                 return;
             }
-            if (activeRunCount() >= MAX_CONCURRENT_RUNS) {
-                notify(`${MAX_CONCURRENT_RUNS} /go runs are already in flight; wait for one to finish (see /go-status).`, "warning");
+            const maxConcurrentRuns = resolveMaxConcurrentRuns();
+            if (activeRunCount() >= maxConcurrentRuns) {
+                notify(`${maxConcurrentRuns} /go runs are already in flight; wait for one to finish (see /go-status) or raise YAGNI_MAX_CONCURRENT_RUNS.`, "warning");
                 return;
             }
             // --- Run tree resolution: worktree by default; --here = legacy in-place.

package/dist/extension/pipeline/personas.js

@@ -57,7 +57,7 @@ Budget discipline: you have a hard output budget, and a plan that gets cut off m
 Keep it concrete; the worker executes it verbatim.`;
 const WORKER_BODY = `You are a worker with full capabilities, operating in an isolated context to implement a plan. Work autonomously and use the tools as needed.
 
-You are grounded. Call ask_yagni before guessing about anything organization- or codebase-specific. Critically: for ANY product-intent call you are forced to make that the plan did not settle — a behavior choice, a tradeoff, an interpretation of intent — call record_decision so the company's decision corpus captures it and the next agent inherits the call instead of re-litigating it.
+You are grounded. Call ask_yagni before guessing about anything organization- or codebase-specific. Treat a confirmed answer as settled; when an answer is an unverified assumption or an inference and your change leans on it, say so in your Notes so the reviewer knows what to check. Critically: for ANY product-intent call you are forced to make that the plan did not settle — a behavior choice, a tradeoff, an interpretation of intent — call record_decision so the company's decision corpus captures it and the next agent inherits the call instead of re-litigating it. When ask_yagni reports no recorded position, follow its instruction and record the assumption you proceed on.
 
 You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code, calling record_decision for any intent you infer. Ending your turn with no write/edit is a failure.
 

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

@@ -4,7 +4,8 @@
  * `withResilience(runStage, policy)` is a composable higher-order function that
  * wraps the per-stage child spawn (`runner.ts#runStage`) with the one axis the
  * roadmap calls the whole competitive gap: a per-stage IDLE timeout (no NDJSON
- * event for N ms) and a total WALL-CLOCK timeout, both firing the runner's
+ * event for N ms, deferred while a tool is in flight — see the stall note at
+ * the timer wiring) and a total WALL-CLOCK timeout, both firing the runner's
  * existing SIGTERM -> SIGKILL abort; bounded exponential backoff with jitter; and
  * retry of CLASSIFIED-TRANSIENT outcomes only. One structured telemetry record is
  * emitted per attempt.

package/dist/extension/pipeline/resilience.js

@@ -4,7 +4,8 @@
  * `withResilience(runStage, policy)` is a composable higher-order function that
  * wraps the per-stage child spawn (`runner.ts#runStage`) with the one axis the
  * roadmap calls the whole competitive gap: a per-stage IDLE timeout (no NDJSON
- * event for N ms) and a total WALL-CLOCK timeout, both firing the runner's
+ * event for N ms, deferred while a tool is in flight — see the stall note at
+ * the timer wiring) and a total WALL-CLOCK timeout, both firing the runner's
  * existing SIGTERM -> SIGKILL abort; bounded exponential backoff with jitter; and
  * retry of CLASSIFIED-TRANSIENT outcomes only. One structured telemetry record is
  * emitted per attempt.
@@ -100,19 +101,37 @@ export function withResilience(base, policy, opts = {}) {
                 if (!timeoutController.signal.aborted)
                     timeoutController.abort();
             };
+            // Tools the child has started but not finished. The idle window measures
+            // STALL, not silence: a long quiet tool (a 6-minute test suite, a slow
+            // build) emits no NDJSON between its start and end events, and that is
+            // progress, not a hang. While a tool is in flight the idle expiry defers
+            // and re-arms instead of aborting; the wall-clock timer stays the
+            // backstop for a tool that is genuinely hung.
+            let inFlightTools = 0;
             let idleTimer;
             const armIdle = () => {
                 if (idleTimer)
                     clearTimeout(idleTimer);
-                idleTimer = setTimeout(fireTimeout, policy.idleTimeoutMs);
+                idleTimer = setTimeout(fireIdle, policy.idleTimeoutMs);
                 idleTimer.unref?.();
             };
+            const fireIdle = () => {
+                if (inFlightTools > 0) {
+                    armIdle();
+                    return;
+                }
+                fireTimeout();
+            };
             const wallTimer = setTimeout(fireTimeout, policy.wallTimeoutMs);
             wallTimer.unref?.();
             armIdle();
             const originalOnEvent = deps.onEvent;
             const onEvent = (ev) => {
                 sawAnyEvent = true;
+                if (ev.type === "tool_execution_start")
+                    inFlightTools += 1;
+                else if (ev.type === "tool_execution_end")
+                    inFlightTools = Math.max(0, inFlightTools - 1);
                 armIdle(); // reset the idle window on every live event
                 originalOnEvent?.(ev);
             };

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

@@ -22,8 +22,16 @@
  * candidate).
  */
 import type { CheckpointRecord, StopReason } from "./types.js";
-/** Bound on simultaneously in-flight /go runs in one process (spec §3b). */
+/** Default bound on simultaneously in-flight /go runs in one process (spec §3b). */
 export declare const MAX_CONCURRENT_RUNS = 3;
+/** Hard ceiling for the env override — a typo must not launch hundreds of runs. */
+export declare const MAX_CONCURRENT_RUNS_CEILING = 32;
+/**
+ * Resolve the in-flight /go cap from the environment. `YAGNI_MAX_CONCURRENT_RUNS`
+ * raises (or lowers) the default for fleet-scale operators; non-numeric or < 1
+ * falls back to the default, and anything above the ceiling clamps to it.
+ */
+export declare function resolveMaxConcurrentRuns(env?: Record<string, string | undefined>): number;
 /**
  * A non-terminal row whose journal has been quiet this long is treated as
  * INTERRUPTED (its process died) rather than still running elsewhere. Sits

package/dist/extension/pipeline/runRegistry.js

@@ -24,8 +24,22 @@
 import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { codeStateHome } from "../stateHome.js";
-/** Bound on simultaneously in-flight /go runs in one process (spec §3b). */
+/** Default bound on simultaneously in-flight /go runs in one process (spec §3b). */
 export const MAX_CONCURRENT_RUNS = 3;
+/** Hard ceiling for the env override — a typo must not launch hundreds of runs. */
+export const MAX_CONCURRENT_RUNS_CEILING = 32;
+/**
+ * Resolve the in-flight /go cap from the environment. `YAGNI_MAX_CONCURRENT_RUNS`
+ * raises (or lowers) the default for fleet-scale operators; non-numeric or < 1
+ * falls back to the default, and anything above the ceiling clamps to it.
+ */
+export function resolveMaxConcurrentRuns(env = process.env) {
+    const raw = env.YAGNI_MAX_CONCURRENT_RUNS?.trim();
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    if (!Number.isFinite(parsed) || parsed < 1)
+        return MAX_CONCURRENT_RUNS;
+    return Math.min(parsed, MAX_CONCURRENT_RUNS_CEILING);
+}
 /**
  * A non-terminal row whose journal has been quiet this long is treated as
  * INTERRUPTED (its process died) rather than still running elsewhere. Sits
@@ -106,6 +120,13 @@ const active = new Map();
 export function _resetRunRegistryForTest() {
     active.clear();
 }
+// NOTE on growth: the mirror is append-only and grows without bound on a
+// long-lived install. In-place compaction was reviewed and REMOVED (PR #1698):
+// a fold+rewrite without cross-process exclusion can permanently erase another
+// process's terminal settle (nothing ever re-appends a final row), which would
+// resurrect a finished run as "interrupted" and invite duplicate worktree
+// adoption. Compaction needs an inter-process lock + unique temp files —
+// tracked separately; until then, growth is the safe failure mode.
 /** Fail-soft append of one full row to the mirror (self-heals a torn previous write). */
 function appendRow(row) {
     try {

package/dist/extension/recordDecisionTool.d.ts

@@ -1,5 +1,6 @@
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { type FlywheelState } from "./flywheel.js";
 /** Options for {@link makeRecordDecisionTool}. */
 export interface MakeRecordDecisionToolOptions {
     baseUrl: string;
@@ -7,6 +8,13 @@ export interface MakeRecordDecisionToolOptions {
     fetchImpl?: typeof fetch;
     /** Idempotency-key source (default: crypto.randomUUID); injected in tests. */
     makeIdempotencyKey?: () => string;
+    /**
+     * Shared flywheel session state (Run 7). A record_decision that follows a
+     * surfaced no-position suggestion sends `dedupe: true` — a mid-run agent
+     * has no human to adjudicate a near-duplicate. A human `/decide` never
+     * rides this state.
+     */
+    flywheel?: FlywheelState;
 }
 /** The durable fields of a recorded product-intent decision. */
 export interface RecordDecisionParams {

package/dist/extension/recordDecisionTool.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
+import { consumeFlywheelAttribution } from "./flywheel.js";
 import { sendOrSpool } from "./spool.js";
 /**
  * POST a single decision to the token-scoped grounding endpoint and return its
@@ -67,12 +68,20 @@ export function makeRecordDecisionTool(opts) {
             // never bank the same decision twice. Transport failures and 5xx are
             // spooled durably instead of lost (R4 write half).
             const idempotencyKey = (opts.makeIdempotencyKey ?? randomUUID)();
+            // Run 7 flywheel attribution: a record answering the QUESTION a
+            // surfaced no-position suggestion asked about asks the backend to
+            // dedupe against active decisions first (decisive, not advisory — no
+            // human is present). An unrelated record never inherits the flag.
+            const flywheelAttributed = opts.flywheel
+                ? consumeFlywheelAttribution(opts.flywheel, params.question)
+                : false;
             const outcome = await sendOrSpool(opts, "record_decision", "/api/yagni-code/decisions", {
                 question: params.question,
                 decision: params.decision,
                 rationale: params.rationale,
                 repo: params.repo,
                 workItemId: params.workItemId,
+                ...(flywheelAttributed ? { dedupe: true } : {}),
             }, idempotencyKey, signal);
             if (outcome.kind === "rejected") {
                 throw new Error(outcome.message);
@@ -92,6 +101,21 @@ export function makeRecordDecisionTool(opts) {
                 };
             }
             const data = outcome.json;
+            if (data?.deduped) {
+                // The backend matched an existing active decision and inserted
+                // nothing; surface it so the agent leans on the recorded judgment.
+                const existing = data.existing;
+                const summary = existing?.decision ? ` ${existing.decision}` : "";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `An equivalent decision is already recorded; nothing new was banked.${summary}`,
+                        },
+                    ],
+                    details: { id: existing?.id ?? null, spooled: false },
+                };
+            }
             return {
                 content: [{ type: "text", text: "Recorded the decision in YAGNI." }],
                 details: { id: data?.id ?? null, spooled: false },

package/dist/extension/subagents.d.ts

@@ -20,11 +20,13 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { runStage } from "./pipeline/runner.js";
-import type { ModelTier, PipelineStage } from "./pipeline/types.js";
+import { type ModelTier, type PipelineStage } from "./pipeline/types.js";
 import { renderSubagentCall, renderSubagentResult } from "./subagentRender.js";
 export declare const SUBAGENT_TOOL_NAME = "subagent";
 export declare const GENERAL_AGENT_NAME = "general";
 export declare const MAX_PARALLEL_SUBAGENTS = 4;
+/** Wider fan-out ceiling while the session is in ultra mode (/ultra). */
+export declare 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
@@ -92,6 +94,8 @@ export interface MakeSubagentToolDeps {
     runStageImpl?: typeof runStage;
     discover?: (deps: DiscoverDeps) => SubagentDef[];
     homeDir?: string;
+    /** Live ultra-mode probe (/ultra): widens the per-call fan-out ceiling. */
+    isUltra?: () => boolean;
 }
 export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
     name: string;
@@ -135,6 +139,8 @@ export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
 export interface RegisterSubagentsDeps {
     discover?: (deps: DiscoverDeps) => SubagentDef[];
     homeDir?: string;
+    /** Live ultra-mode probe (/ultra): widens the per-call fan-out ceiling. */
+    isUltra?: () => boolean;
 }
 /** Wire the subagent tool and the /agents listing command. */
 export declare function registerSubagents(pi: ExtensionAPI, deps?: RegisterSubagentsDeps): void;

package/dist/extension/subagents.js

@@ -23,7 +23,9 @@ 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.
@@ -34,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
@@ -123,6 +127,50 @@ const IMPLEMENTER_AGENT = {
     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,
@@ -210,7 +258,7 @@ function loadAgentsFromDir(dir, source) {
 export function discoverSubagents(deps) {
     const home = deps.homeDir ?? homedir();
     const layers = [
-        [GENERAL_AGENT, SEARCHER_AGENT, IMPLEMENTER_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"),
@@ -261,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,
@@ -293,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 });

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/ultra.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Ultra mode (/ultra) — an explicit, session-scoped dial for aggressive
+ * multi-agent orchestration ("the diamond": fan out → reduce → synthesize).
+ *
+ * Off by default so the trial-default behavior is unchanged; toggling on swaps
+ * the driver's delegation paragraph for the diamond directive (branding.ts's
+ * YAGNI_IDENTITY_ULTRA) and widens the subagent tool's per-call fan-out
+ * ceiling (subagents.ts). The two halves take effect at different moments:
+ * the fan-out ceiling is probed live on every subagent call, but the identity
+ * is read in index.ts's before_agent_start handler, which pi fires only when
+ * a NEW user prompt is submitted — a toggle mid-run leaves the running task on
+ * its existing instructions until the next message (the handler notifies when
+ * that is the case). Ultra is a prompt + ceiling change only: it never touches
+ * the permission mode, the model tier, or the /go pipeline.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export interface UltraHolder {
+    get(): boolean;
+    set(on: boolean): void;
+}
+export declare function createUltraHolder(initial?: boolean): UltraHolder;
+/**
+ * Wire the /ultra command onto a shared holder. No argument toggles; `on` /
+ * `off` set explicitly; `status` reports without changing anything.
+ */
+export declare function registerUltraCommand(pi: ExtensionAPI, holder: UltraHolder): void;
+//# sourceMappingURL=ultra.d.ts.map

package/dist/extension/ultra.js

@@ -0,0 +1,76 @@
+/**
+ * Ultra mode (/ultra) — an explicit, session-scoped dial for aggressive
+ * multi-agent orchestration ("the diamond": fan out → reduce → synthesize).
+ *
+ * Off by default so the trial-default behavior is unchanged; toggling on swaps
+ * the driver's delegation paragraph for the diamond directive (branding.ts's
+ * YAGNI_IDENTITY_ULTRA) and widens the subagent tool's per-call fan-out
+ * ceiling (subagents.ts). The two halves take effect at different moments:
+ * the fan-out ceiling is probed live on every subagent call, but the identity
+ * is read in index.ts's before_agent_start handler, which pi fires only when
+ * a NEW user prompt is submitted — a toggle mid-run leaves the running task on
+ * its existing instructions until the next message (the handler notifies when
+ * that is the case). Ultra is a prompt + ceiling change only: it never touches
+ * the permission mode, the model tier, or the /go pipeline.
+ */
+export function createUltraHolder(initial = false) {
+    let on = initial;
+    return {
+        get: () => on,
+        set: (v) => {
+            on = v;
+        },
+    };
+}
+/** Status chip shown while ultra is on (same footer surface as the /mode chip). */
+const ULTRA_STATUS = "◆ ultra";
+const ULTRA_ON_COPY = "Ultra mode ON: meaningful work fans out to parallel subagents, adversarial " +
+    "verification agents try to break the result, then the agent synthesizes. " +
+    "Expect more subagent spend per task.";
+const ULTRA_OFF_COPY = "Ultra mode OFF: back to delegate-when-useful.";
+/**
+ * Appended when the toggle lands mid-run: the identity swap only applies when
+ * the next prompt is submitted (see the module docblock), so without this note
+ * the chip flips while the running task visibly keeps its old behavior — which
+ * reads as ultra mode being broken.
+ */
+const MID_RUN_NOTE = " The task currently running keeps its existing instructions; the change takes full effect on your next message.";
+/**
+ * Wire the /ultra command onto a shared holder. No argument toggles; `on` /
+ * `off` set explicitly; `status` reports without changing anything.
+ */
+export function registerUltraCommand(pi, holder) {
+    pi.registerCommand("ultra", {
+        description: "Toggle ultra mode: aggressive fan-out/verify/synthesize orchestration. /ultra on | off | status.",
+        handler: async (args, ctx) => {
+            const notify = (m, t) => {
+                if (ctx.hasUI)
+                    ctx.ui.notify(m, t);
+            };
+            const arg = args.trim().toLowerCase();
+            if (arg && arg !== "on" && arg !== "off" && arg !== "status") {
+                notify(`Unknown argument "${arg}". Use /ultra, /ultra on, /ultra off, or /ultra status.`, "warning");
+                return;
+            }
+            if (arg === "status") {
+                notify(holder.get() ? ULTRA_ON_COPY : ULTRA_OFF_COPY, "info");
+                return;
+            }
+            const next = arg === "on" ? true : arg === "off" ? false : !holder.get();
+            holder.set(next);
+            try {
+                if (ctx.hasUI)
+                    ctx.ui.setStatus?.("yagni-ultra", next ? ULTRA_STATUS : undefined);
+            }
+            catch {
+                // The chip is chrome; never let it break /ultra.
+            }
+            // Guarded probe: test fakes (and any minimal harness ctx) may not carry
+            // isIdle, and its absence must read as idle, never as busy.
+            const midRun = typeof ctx.isIdle === "function" && !ctx.isIdle();
+            const copy = next ? ULTRA_ON_COPY : ULTRA_OFF_COPY;
+            notify(midRun ? copy + MID_RUN_NOTE : copy, "info");
+        },
+    });
+}
+//# sourceMappingURL=ultra.js.map