infinity-harness 2.8.9 → 2.8.11

package/dist/extensions/infinity-harness/index.js

@@ -0,0 +1,3614 @@
+/**
+ * infinity-harness — the pi extension.
+ *
+ * This file is deliberately thin. It owns pi's lifecycle and nothing else:
+ * every decision about phases, gates, plans and looping lives in `src/`, where
+ * it is typed and unit-tested. An earlier version inlined copies of the plan
+ * engine and the widget here, which meant the tested code and the shipped code
+ * were two different implementations that drifted apart. There is one
+ * implementation now, and this adapter calls it.
+ *
+ * What the adapter is responsible for:
+ *   - injecting the brief when a session starts
+ *   - running the gate when the agent goes quiet, and advancing or re-briefing
+ *   - keeping the plan widget truthful
+ *   - surviving compaction without losing the plan
+ *   - refusing tool calls that would skip a phase
+ */
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { isHarnessProject, loadConfig, saveConfig } from "../../src/core/config.js";
+import { loadFeatureList, computeProgress, nextActionableTask } from "../../src/core/featureList.js";
+import { buildBrief, renderBrief } from "../../src/core/brief.js";
+import { runChecks } from "../../src/core/gates.js";
+import { advancePhase } from "../../src/core/phases.js";
+import { configPath } from "../../src/core/paths.js";
+import { readJsonSafe } from "../../src/core/fsx.js";
+import { resolve as resolvePath, dirname } from "node:path";
+import { deriveViewState as deriveViewStateSync } from "../../src/ui/viewState.js";
+import { runStatePath as runStatePathSync } from "../../src/core/paths.js";
+import { withLock } from "../../src/core/lock.js";
+import { ValidationError, } from "../../src/core/types.js";
+import { writeTaskList, summarizeApply } from "../../src/taskList.js";
+import { renderWidget, renderStatusLine } from "../../src/ui/widget.js";
+import { createStyler, detectGlyphs } from "../../src/ui/theme.js";
+import { decideNext, fingerprint, stopFilePath, loopStatePath } from "../../src/loop.js";
+import { runConfigMenu, renderSettings } from "../../src/ui/config.js";
+import { SETTINGS, readAll, readSetting, formatValue } from "../../src/core/settings.js";
+import { detectStack, describeInit, initHarness } from "../../src/core/init.js";
+import { startRework, loadRework, clearRework } from "../../src/rework.js";
+import { amendPlan } from "../../src/replan.js";
+import { chooseUnstuckStrategy } from "../../src/unstuck.js";
+import { escalationSummary } from "../../src/escalate.js";
+import { spawnIsolatedWorker } from "../../src/worker.js";
+import { executionPolicyOf } from "../../src/scheduler.js";
+import { isWorkerProcess } from "../../src/exec/piWorker.js";
+import { currentUnit, describeUnit, loadActivity, loadSupervisorState, isRefusal, startSupervisor, } from "../../src/supervisor.js";
+import { startGoal, loadGoal, reviewGoal, cancelGoal, viewOf, describeGoal, } from "../../src/goal.js";
+import { flattenTasks } from "../../src/core/featureList.js";
+import { armRun, countSession, disarmRun, loadRunState, runIdFor, } from "../../src/runState.js";
+import { clearHandoff, composeKickoff, describeHandoff, hasPendingHandoff, requestHandoff, shouldHandoff, takeHandoff, } from "../../src/handoff.js";
+import { resolveApproval, approvedPhases } from "../../src/approval.js";
+import { pickDisplay, pickWorkflow, runIntakeWizard, unattendedIntake, } from "../../src/ui/wizard.js";
+import { applyWorkflow, findWorkflow, listWorkflows, matchWorkflow, renderWorkflow, signedPhases, summarizeWorkflow, } from "../../src/workflow.js";
+import { findDisplay, listDisplays, normalizeDisplay, summarizeDisplay, } from "../../src/ui/display.js";
+import { defaultView, scrollView, SCROLL_STEP, TASK_WINDOW, EXPANDED_WINDOW } from "../../src/ui/widget.js";
+import { buildPlanRows } from "../../src/ui/planTree.js";
+/**
+ * This file's own path.
+ *
+ * A background worker normally discovers the harness the same way this
+ * session did, because the harness is an installed pi package. When it was
+ * loaded from an explicit `-e` instead — a dev checkout, and every e2e run —
+ * discovery finds nothing, and the supervisor restarts the worker with this
+ * path so it still has the plan tools.
+ */
+const SELF_PATH = (() => {
+    try {
+        return fileURLToPath(import.meta.url);
+    }
+    catch {
+        return null;
+    }
+})();
+const CHECKPOINT = "infinity:checkpoint";
+const WIDGET_KEY = "infinity-harness";
+const STATUS_KEY = "infinity";
+/** Reminder cadence, in LLM calls, when the plan still has open tasks. */
+const REMINDER_INTERVAL = 4;
+function projectDir(ctx) {
+    const c = ctx;
+    return c?.cwd ?? c?.projectDir ?? process.cwd();
+}
+function notify(ctx, message, level = "info") {
+    try {
+        ctx.ui?.notify?.(message, level);
+    }
+    catch {
+        /* headless mode has no UI */
+    }
+}
+export default function (pi) {
+    // -- session-scoped state -------------------------------------------------
+    //
+    // Everything a *run* needs outlives this session and lives in `harness/`.
+    // What is left here is genuinely per-session: this session's own id, and
+    // where the human has scrolled the widget.
+    const sessionId = randomUUID();
+    let llmCalls = 0;
+    let loopBusy = false;
+    let handingOff = false;
+    let lastBriefPhase = null;
+    let remoteServer = null;
+    let remoteDir = null;
+    let view = defaultView();
+    /**
+     * The background orchestrator, when one is running in this session.
+     *
+     * It is a plain async loop in this process — no LLM, no tokens — that keeps
+     * one `pi` child working on the current unit. Only one session drives a run
+     * at a time; a second pi window on the same project shows the widget and
+     * the log, and leaves the driving alone.
+     */
+    let supervisor = null;
+    /** This session is a background worker, not the human's control panel. */
+    const workerProcess = isWorkerProcess();
+    /** Ring of activity lines mirrored into the widget. */
+    let activity = [];
+    let supState = null;
+    /**
+     * Is this instance's session still the live one?
+     *
+     * After `ctx.newSession()` pi tears the old runtime down and rebinds
+     * extensions, but this closure and its registered handlers still exist. Any
+     * of them that touches `pi` or a captured `ctx` afterwards gets
+     * "This extension ctx is stale after session replacement" — which is what a
+     * handoff produced on every single turn until this flag existed.
+     */
+    let sessionLive = true;
+    /**
+     * Is a continuous run armed?
+     *
+     * Read from disk, not from a closure variable. The old `let loopEnabled`
+     * died with the pi session that held it, which meant the first session
+     * handoff — the whole point of the fresh-session policy — silently ended
+     * the run it was supposed to continue.
+     */
+    const loopArmed = (dir) => loadRunState(dir)?.armed === true;
+    /** The run this session belongs to, or this session, when nothing is armed. */
+    const runFor = (dir) => runIdFor(dir, sessionId);
+    const styler = createStyler();
+    const glyphs = detectGlyphs();
+    // -- widget ---------------------------------------------------------------
+    const handoffNoteFor = (h, hasDefaultIdle, defaultRef) => {
+        const map = {
+            off: "Model per run (off/goal) — the whole run shares its hardest model; finer per-task routing requires task/subtask handoff",
+            goal: "Model per run (off/goal) — the whole run shares its hardest model; finer per-task routing requires task/subtask handoff",
+            phase: "Model per phase — tasks & subtasks in a phase share the hardest model in that phase",
+            sprint: "Model per sprint — tasks & subtasks in a sprint share the hardest model in that sprint",
+            feature: "Model per feature — tasks & subtasks in a feature share the hardest model in that feature",
+            task: "Model per task — subtasks share their parent task's model",
+            subtask: "Model per subtask — each subtask may use its own model (needs subtask difficulty)",
+        };
+        return map[h] ?? null;
+    };
+    const widgetStateFor = (dir) => {
+        try {
+            const { list } = loadFeatureList(dir);
+            const { config } = loadConfig(dir);
+            const _routerForWidget = (() => { try {
+                const { loadRouterConfig: _lrc } = require("../../src/modelRouter.ts");
+                return _lrc(dir);
+            }
+            catch {
+                return null;
+            } })();
+            const hasIdle = (() => { try {
+                if (!_routerForWidget?.default?.trim())
+                    return false;
+                const h = config.session?.handoff ?? "task";
+                if (h !== "task" && h !== "subtask")
+                    return false;
+                let lanes = [];
+                try {
+                    lanes = flattenTasks(list);
+                }
+                catch {
+                    lanes = [];
+                }
+                if (!lanes.length)
+                    return false;
+                return lanes.every(x => { const d = x.difficulty; return d === "easy" || d === "moderate" || d === "difficult"; });
+            }
+            catch {
+                return false;
+            } })();
+            const handoffModelNote = handoffNoteFor(config.session?.handoff ?? "task", hasIdle, _routerForWidget?.default ?? null);
+            const spent = escalationSummary(dir);
+            // v3 viewState: widget must read daemon.json before rendering — deriveViewState is that check.
+            let viewState = null;
+            try {
+                viewState = deriveViewStateSync(dir);
+            }
+            catch { }
+            let pilotTag2 = config.pilot ?? null;
+            let phaseModes2 = config.phaseModes ?? null;
+            if (!pilotTag2)
+                pilotTag2 = config.mode === "copilot" ? "copilot" : config.mode === "autopilot" ? "autopilot" : null;
+            let tierSpend2 = null;
+            let reworkDepth2 = null;
+            try {
+                const rs = readJsonSafe(runStatePathSync(dir), null);
+                tierSpend2 = rs?.budget?.byTier ?? null;
+            }
+            catch { }
+            try {
+                const rw = readJsonSafe(resolvePath(dir, "harness/rework.json"), null);
+                if (Array.isArray(rw?.queue))
+                    reworkDepth2 = rw.queue.length;
+                else if (typeof rw?.impactedCount === "number")
+                    reworkDepth2 = Number(rw.impactedCount);
+            }
+            catch { }
+            const loop = readJsonSafe(loopStatePath(dir), null);
+            const lastRung = loop?.escalations?.[loop.escalations.length - 1]?.strategy ?? null;
+            const pass = typeof config.goalPass === "number" ? config.goalPass : null;
+            const maxPasses = typeof config.goalMaxPasses === "number" ? config.goalMaxPasses : null;
+            const run = loadRunState(dir);
+            const sup = supState ?? loadSupervisorState(dir);
+            const worker = sup?.worker ?? null;
+            return {
+                list,
+                viewState,
+                pilot: pilotTag2,
+                phaseModes: phaseModes2,
+                tierSpend: tierSpend2,
+                reworkDepth: reworkDepth2,
+                view,
+                engine: executionPolicyOf(config).engine,
+                workers: worker
+                    ? [
+                        {
+                            name: worker.name,
+                            unit: worker.unitLabel,
+                            level: worker.level,
+                            model: worker.servedModel ?? worker.model,
+                            difficulty: worker.difficulty,
+                            state: worker.state,
+                            doing: worker.doing,
+                            tokens: worker.tokens.inputTokens + worker.tokens.outputTokens,
+                            contextRatio: worker.contextRatio,
+                        },
+                    ]
+                    : [],
+                activity: (activity.length ? activity : loadActivity(dir)).slice(-40).map((l) => ({
+                    at: l.at,
+                    level: l.level,
+                    worker: l.worker,
+                    text: l.text,
+                })),
+                dashboardUrl: (() => {
+                    if (remoteServer?.url)
+                        return remoteServer.url;
+                    try {
+                        const d = readJsonSafe(resolvePath(dir, "harness/daemon.json"), null);
+                        const port = d?.port;
+                        if (typeof port === "number" && port > 0)
+                            return `http://127.0.0.1:${port}/dashboard`;
+                    }
+                    catch { }
+                    return null;
+                })(),
+                handoffModelNote,
+                sessions: run?.sessions ?? null,
+                intake: typeof config.intake?.brief === "string" ? config.intake.brief : null,
+                awaitingApproval: config.awaitingApproval ?? null,
+                display: normalizeDisplay(config.display),
+                phase: config.currentPhase,
+                enabledPhases: config.phases?.enabled,
+                gateHistory: Array.isArray(config.gateHistory) ? config.gateHistory : null,
+                paused: Boolean(config.paused),
+                revision: list.baseRevision,
+                retries: { task: config.taskRetryCount ?? 0, max: config.maxRetries ?? 10 },
+                goalPass: pass && maxPasses ? { current: pass, max: maxPasses } : null,
+                escalation: lastRung || spent.reworks || spent.replans
+                    ? { strategy: lastRung, reworks: spent.reworks, replans: spent.replans }
+                    : null,
+            };
+        }
+        catch {
+            return null;
+        }
+    };
+    let widgetCtx = null;
+    // A+C: live widget — re-render from disk even when hooks' ctx is stale.
+    // Pi's factory variant has no external trigger: invalidate() is only called
+    // when pi decides to (theme change / focus). The panel therefore freezes
+    // until *some* event re-calls setWidget. Own a (tui,theme) capture so we
+    // can re-render in place and poll the on-disk state.
+    let liveWidget = null;
+    let liveCtx = null;
+    let widgetPoll = null;
+    const refreshWidget = (ctx) => {
+        if (ctx)
+            widgetCtx = ctx;
+        const useCtx = ctx ?? widgetCtx;
+        if (!useCtx)
+            return;
+        try {
+            const dir = projectDir(useCtx);
+            const state = widgetStateFor(dir);
+            if (!state)
+                return;
+            const lines = renderWidget(state, { width: 76, styler, glyphs });
+            // Preserve the captured tui/theme so a background tick can request a
+            // redraw without needing a fresh ctx (command ctx dies after return).
+            let capturedTui = null;
+            let capturedTheme = null;
+            const factory = (tui, theme) => {
+                capturedTui = tui;
+                capturedTheme = theme;
+                const comp = {
+                    render: () => lines,
+                    invalidate() {
+                        // Pi may call this on theme change — re-compute lines from disk.
+                        try {
+                            const fresh = widgetStateFor(dir);
+                            if (fresh) {
+                                const nl = renderWidget(fresh, { width: 76, styler, glyphs });
+                                comp.render = () => nl;
+                                tui?.requestRender?.();
+                            }
+                        }
+                        catch { }
+                    },
+                    handleInput() { },
+                };
+                liveWidget = comp;
+                liveCtx = useCtx;
+                // Keep the URL honest: daemon picked port 0 on start.
+                // No extra tick needed — invalidate() + polling covers it.
+                return comp;
+            };
+            useCtx.ui.setWidget(WIDGET_KEY, factory);
+            // Explicitly clear any stale belowEditor instance from a prior install.
+            try {
+                useCtx.ui.setWidget(WIDGET_KEY, undefined, { placement: "belowEditor" });
+            }
+            catch { }
+            useCtx.ui.setStatus(STATUS_KEY, renderStatusLine(state, glyphs));
+        }
+        catch {
+            /* the widget is never worth breaking a turn over */
+        }
+    };
+    const pokeWidget = () => {
+        try {
+            const ctx = liveCtx ?? widgetCtx;
+            if (!ctx || workerProcess)
+                return;
+            const dir = projectDir(ctx);
+            // Only poll when there is a panel (harness project and we opened one)
+            if (!liveWidget)
+                return;
+            const fresh = widgetStateFor(dir);
+            if (!fresh)
+                return;
+            const nl = renderWidget(fresh, { width: 76, styler, glyphs });
+            // Swap render in place then ask tui to paint.
+            liveWidget.render = () => nl;
+            try {
+                // The captured tui is the authority; fall back to ctx.ui if needed.
+                // We do not have direct tui ref here — use the widget invalidate path
+                // via re-setting the factory once, then rely on invalidate for rest.
+                // Cheap: re-set factory re-captures tui.
+                const useCtx = ctx;
+                if (useCtx) {
+                    const fac = (_tui, _theme) => liveWidget;
+                    // Do not thrash every tick — only when content changed.
+                    // renderWidget is deterministic; compare joined.
+                    // If equal, skip setWidget to avoid flicker.
+                }
+            }
+            catch { }
+            // Best effort: if the factory captured a tui with requestRender, call it.
+            // liveWidget was built inside factory with closure over tui variable;
+            // we saved it via capturedTui but it is scoped inside refreshWidget.
+            // So instead, re-install once and let the next tick be no-op.
+            try {
+                // Re-install factory to force pi to re-render the widget placement.
+                // This is idempotent and 0-cost when lines unchanged — we guard above.
+                const cur = renderWidget(widgetStateFor(dir), { width: 76, styler, glyphs }).join('\n');
+                const prev = nl.join('\n');
+                if (cur !== prev) {
+                    // content drifted between our two reads — re-render again next tick
+                }
+            }
+            catch { }
+        }
+        catch { }
+    };
+    const startWidgetPoll = (ctx) => {
+        if (widgetPoll)
+            return;
+        if (workerProcess)
+            return;
+        liveCtx = ctx;
+        // 2s is enough to track supervisor (background pi) and daemon (detached).
+        widgetPoll = setInterval(() => {
+            try {
+                const c = liveCtx ?? widgetCtx;
+                if (!c || workerProcess)
+                    return;
+                // Only while a harness exists in this dir.
+                const dir = projectDir(c);
+                if (!isHarnessProject(dir))
+                    return;
+                // Only when armed or when daemon/supervisor state exists — avoid
+                // spinning on every non-harness project.
+                const armed = (() => { try {
+                    return loadRunState(dir)?.armed === true;
+                }
+                catch {
+                    return false;
+                } })();
+                const hasSup = (() => { try {
+                    return !!loadSupervisorState(dir)?.worker || !!loadSupervisorState(dir)?.history?.length;
+                }
+                catch {
+                    return false;
+                } })();
+                const hasDaemon = (() => { try {
+                    const d = readJsonSafe(resolvePath(dir, "harness/daemon.json"), null);
+                    return !!d?.heartbeatAt;
+                }
+                catch {
+                    return false;
+                } })();
+                if (!armed && !hasSup && !hasDaemon)
+                    return;
+                // Rebuild lines and invalidate live widget, then requestRender via tui if captured.
+                try {
+                    const fresh = widgetStateFor(dir);
+                    if (!fresh || !liveWidget) {
+                        // No live widget yet — do a full refresh so factory captures tui.
+                        refreshWidget(c);
+                        return;
+                    }
+                    const nl = renderWidget(fresh, { width: 76, styler, glyphs });
+                    liveWidget.render = () => nl;
+                    try {
+                        liveWidget.invalidate();
+                    }
+                    catch { }
+                    // Also keep status line honest.
+                    try {
+                        c.ui.setStatus(STATUS_KEY, renderStatusLine(fresh, glyphs));
+                    }
+                    catch { }
+                }
+                catch { }
+            }
+            catch { }
+        }, 2000);
+        // Not keeping process alive for widget poll.
+        widgetPoll?.unref?.();
+    };
+    const stopWidgetPoll = () => {
+        if (widgetPoll) {
+            try {
+                clearInterval(widgetPoll);
+            }
+            catch { }
+            widgetPoll = null;
+        }
+    };
+    /** How many rows the plan currently has — the bound for scrolling. */
+    const planRowCount = (dir) => {
+        try {
+            const { list } = loadFeatureList(dir);
+            // Count the same domain the widget scrolls: the flattened task lanes.
+            // buildPlanRows includes grouping rows that the lane view does not, so
+            // using it made maxScroll disagree with what you see.
+            try {
+                const lanes = flattenTasks(list);
+                if (Array.isArray(lanes) && lanes.length > 0)
+                    return lanes.length;
+            }
+            catch { }
+            return buildPlanRows(list, null, { expandSubtasks: view.expanded }).length;
+        }
+        catch {
+            return 0;
+        }
+    };
+    /**
+     * The widget is a window onto the plan, and the window has to move.
+     *
+     * A fixed nine-row slice of a sixty-row plan is a widget that is *truncated*,
+     * which is exactly how it read: the rows outside the window may as well not
+     * exist. They exist; these keys reach them.
+     */
+    const moveView = (ctx, delta) => {
+        const dir = projectDir(ctx);
+        const rows = planRowCount(dir);
+        // Match widget.ts taskWindow so scroll limits agree with what you see.
+        let windowRows = view.expanded ? EXPANDED_WINDOW : TASK_WINDOW;
+        try {
+            const { config } = loadConfig(dir);
+            const disp = normalizeDisplay(config.display);
+            windowRows = view.expanded ? Math.max(EXPANDED_WINDOW, disp.taskWindow * 2) : disp.taskWindow;
+        }
+        catch { }
+        const before = view.scroll;
+        view = scrollView(view, delta, rows, windowRows);
+        // Null means "follow the run"; the first manual scroll leaves follow-mode.
+        // Pinning top with delta 0 must keep 0, not flick back to null.
+        if (before === null && view.scroll === 0 && delta === 0)
+            view = { ...view, scroll: 0 };
+        refreshWidget(ctx);
+        // Confirm it moved — otherwise the human thinks the keys do nothing.
+        try {
+            const state = widgetStateFor(dir);
+            const total = state ? flattenTasks(state.list).length : rows;
+            const atTop = (view.scroll ?? 0) <= 0;
+            const atBottom = (view.scroll ?? 0) >= Math.max(0, total - windowRows);
+            if (delta > 0 && atBottom)
+                notify(ctx, "infinity-harness: already at the bottom \u00b7 /infinity:scroll expand for more rows", "info");
+            else if (delta < 0 && atTop && before !== null)
+                notify(ctx, "infinity-harness: at the top \u00b7 /infinity:scroll follow to track the run", "info");
+        }
+        catch { }
+    };
+    // -- brief ----------------------------------------------------------------
+    const briefText = async (dir, includeGate = false) => {
+        const { config } = loadConfig(dir);
+        const brief = await buildBrief(dir, { includeGate });
+        const routed = await routingSummaryForBrief(dir).catch(() => null);
+        const text = renderBrief(brief, config);
+        return routed ? `${text}\n\n${routed}` : text;
+    };
+    // -- configuration --------------------------------------------------------
+    /**
+     * The models this session can actually use.
+     *
+     * Prefers `scopedModels` when the user has scoped the session, because those
+     * are the models they deliberately chose; otherwise every model pi holds
+     * working credentials for. Models without auth are excluded — offering one
+     * would produce a tier that fails at the first task rather than at setup.
+     */
+    const availableModels = (ctx) => {
+        // Helper: get pi-default thinking levels for a model (the truth — not our THINKING_LEVELS)
+        const supportedOf = (m) => {
+            try {
+                const mod = m;
+                if (!mod)
+                    return null;
+                // pi-ai getSupportedThinkingLevels: reasoning false => ["off"]
+                if (mod.reasoning === false)
+                    return ["off"];
+                if (mod.reasoning === true) {
+                    const map = mod.thinkingLevelMap ?? {};
+                    const all = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+                    const supported = all.filter(l => {
+                        const v = map[l];
+                        if (v === null)
+                            return false;
+                        if ((l === "xhigh" || l === "max") && v === undefined)
+                            return false;
+                        return true;
+                    });
+                    return supported.length ? supported : ["off"];
+                }
+                return null;
+            }
+            catch {
+                return null;
+            }
+        };
+        try {
+            const scoped = ctx.scopedModels ?? [];
+            const models = scoped.length > 0
+                ? scoped.map((s) => s.model)
+                : (ctx.modelRegistry?.getAvailable?.() ?? []);
+            const seen = new Set();
+            const out = [];
+            for (const m of models) {
+                if (!m?.id || !m?.provider)
+                    continue;
+                const ref = `${m.provider}/${m.id}`;
+                if (seen.has(ref))
+                    continue;
+                seen.add(ref);
+                const bits = [ref];
+                if (m.name && m.name !== m.id)
+                    bits.push(`· ${m.name}`);
+                if (m.contextWindow)
+                    bits.push(`· ${Math.round(m.contextWindow / 1000)}k ctx`);
+                if (m.reasoning)
+                    bits.push("· reasoning");
+                const levels = supportedOf(m);
+                out.push({ ref, label: bits.join(" "), ...(levels ? { supportedThinkingLevels: levels } : {}) });
+            }
+            out.sort((a, b) => a.ref.localeCompare(b.ref));
+            return out;
+        }
+        catch {
+            return [];
+        }
+    };
+    /** Adapt pi's UI to the prompter the config flow expects. */
+    const prompterFor = (ctx) => ({
+        select: (title, opts) => ctx.ui.select(title, opts),
+        input: (title, placeholder) => ctx.ui.input(title, placeholder),
+        notify: (message, level) => notify(ctx, message, level ?? "info"),
+    });
+    // -- model + thinking routing (live session) --------------------------------
+    const applyRouting = async (ctx, dir, source) => {
+        try {
+            const { resolveModel, resolveThinking } = await import("../../src/modelRouter.js");
+            const { effectiveDifficultyForTask } = await import("../../src/scheduler.js");
+            const { nextActionableTask, findFeature } = await import("../../src/core/featureList.js");
+            const { loadFeatureList: loadList } = await import("../../src/core/featureList.js");
+            const list = loadList(dir).list;
+            const task = nextActionableTask(list);
+            const cfg = loadConfig(dir).config;
+            const handoff = (cfg.session?.handoff ?? "task");
+            // Effective difficulty honors handoff bucket: phase/feature/sprint tasks share hardest in that bucket.
+            const effDiff = task && list ? (effectiveDifficultyForTask(task, handoff, list) ?? task.difficulty) : task?.difficulty;
+            // Resolve against task/parent feature/sprint difficulty; fall through to default when no actionable.
+            const feature = task ? findFeature(list, task.featureId) ?? undefined : undefined;
+            const sprint = feature?.sprintId ? (list.sprints ?? []).find((s) => s.id === feature.sprintId) ?? undefined : undefined;
+            const routedModel = resolveModel({
+                projectDir: dir,
+                task: effDiff || feature?.difficulty ? { difficulty: effDiff, modelHint: task?.modelHint, id: task?.id, key: task?.compositeKey ?? task?.key } : undefined,
+                feature: feature,
+                sprint: sprint,
+                phase: loadConfig(dir).config.currentPhase ?? undefined,
+                role: loadConfig(dir).config.currentRole ?? undefined,
+            });
+            const routedThinking = resolveThinking({
+                projectDir: dir,
+                task: effDiff ? { difficulty: effDiff } : task ? { difficulty: task?.difficulty, id: task?.id, key: task?.compositeKey ?? task?.key } : undefined,
+                feature: feature,
+                sprint: sprint,
+            });
+            if (routedModel && routedModel.trim()) {
+                // Map "provider/id" -> Model via registry.
+                const ref = routedModel.trim();
+                const slash = ref.indexOf("/");
+                const provider = slash > 0 ? ref.slice(0, slash) : undefined;
+                const modelId = slash > 0 ? ref.slice(slash + 1) : ref;
+                const available = (() => { try {
+                    return (ctx.modelRegistry?.getAvailable?.() ?? []);
+                }
+                catch {
+                    return [];
+                } })();
+                const found = (() => {
+                    if (!provider)
+                        return undefined;
+                    try {
+                        return ctx.modelRegistry.find(provider, modelId);
+                    }
+                    catch {
+                        return undefined;
+                    }
+                })();
+                const candidate = found ?? available.find((m) => {
+                    const id = m?.id;
+                    const prov = m?.provider;
+                    return id && (prov ? `${prov}/${id}` === ref : id === ref || id === modelId);
+                });
+                const modelObj = found ?? candidate;
+                if (modelObj && routedModel) {
+                    try {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const ok = await ctx.setModel(modelObj);
+                        ctx.ui?.setStatus?.("infinity-model", routedModel);
+                        if (!ok) {
+                            notify(ctx, `infinity-harness: routed model ${ref} not available (no auth) — staying on current model.`, "warning");
+                        }
+                        else if (source) {
+                            notify(ctx, `infinity-harness: routed to ${ref}${routedThinking ? ` (${routedThinking})` : ""} for ${task?.compositeKey ?? task?.id ?? "next task"} [${source}]`, "info");
+                        }
+                    }
+                    catch (e) {
+                        notify(ctx, `infinity-harness: setModel(${ref}) — ${e?.message ?? String(e)}`, "warning");
+                    }
+                }
+                else {
+                    // Model id present but not in registry — surface once per session, and in widget.
+                    ;
+                    ctx.ui?.setStatus?.("infinity-model", routedModel);
+                    notify(ctx, `infinity-harness routing wants ${ref} for ${task?.compositeKey ?? "next task"} but that model is not in pi's registry (check auth / --models) [${source}]`, "warning");
+                }
+            }
+            else {
+                // No routed model → show inherited; do not call setModel.
+                ;
+                ctx.ui?.setStatus?.("infinity-model", undefined);
+            }
+            if (routedThinking && routedThinking.trim()) {
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    ctx.setThinkingLevel(routedThinking);
+                }
+                catch { }
+            }
+        }
+        catch { }
+    };
+    const routingSummaryForBrief = async (dir) => {
+        try {
+            const { nextActionableTask, findFeature } = await import("../../src/core/featureList.js");
+            const { resolveModel, resolveThinking } = await import("../../src/modelRouter.js");
+            const { effectiveDifficultyForTask } = await import("../../src/scheduler.js");
+            const { list } = loadFeatureList(dir);
+            const task = nextActionableTask(list);
+            if (!task)
+                return null;
+            const cfg = loadConfig(dir).config;
+            const handoff = (cfg.session?.handoff ?? "task");
+            const effDiff = effectiveDifficultyForTask(task, handoff, list) ?? task.difficulty;
+            const feature = findFeature(list, task.featureId) ?? undefined;
+            const sprint = feature?.sprintId ? (list.sprints ?? []).find((s) => s.id === feature.sprintId) ?? undefined : undefined;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const m = resolveModel({ projectDir: dir, task: { difficulty: effDiff, modelHint: task.modelHint, id: task.id, key: task.compositeKey ?? task.key }, feature: feature, sprint: sprint, phase: loadConfig(dir).config.currentPhase ?? undefined });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const th = resolveThinking({ projectDir: dir, task: { difficulty: effDiff }, feature: feature, sprint: sprint });
+            if (!m || !m.trim())
+                return null;
+            return `Routing: ${task.compositeKey} → ${m}${th ? ` · thinking ${th}` : ""}`;
+        }
+        catch {
+            return null;
+        }
+    };
+    // -- the background engine -------------------------------------------------
+    /** Where work runs for this project, honouring the legacy escape hatch. */
+    const engineFor = (dir) => {
+        try {
+            return executionPolicyOf(loadConfig(dir).config).engine;
+        }
+        catch {
+            return "background";
+        }
+    };
+    /**
+     * The model this session is on, as `provider/id`.
+     *
+     * A router slot left empty means "whatever pi is already configured with",
+     * and a *child* process does not inherit that: it would fall back to pi's
+     * default provider, which is not necessarily what the human is looking at.
+     * So we read it here and hand it to the worker explicitly.
+     */
+    const baseModelOf = (ctx) => {
+        try {
+            const m = ctx.model;
+            if (m?.id)
+                return m.provider ? `${m.provider}/${m.id}` : m.id;
+        }
+        catch {
+            /* pi without a model is a pi that cannot run anything anyway */
+        }
+        return null;
+    };
+    /**
+     * Start the background orchestrator for this project.
+     *
+     * Everything it does happens in this process, in plain JavaScript. It costs
+     * no tokens in this session: the only LLM calls a run makes are made by the
+     * `pi` children it spawns, on the models the router chose for them.
+     */
+    const startEngine = async (ctx, dir) => {
+        if (supervisor?.isRunning())
+            return true;
+        if (ctx.mode !== "tui" && ctx.mode !== "rpc") {
+            // `pi -p` has no future in which to watch anything. Arming the run is
+            // still right — the next interactive session picks it up.
+            notify(ctx, "infinity-harness: run armed. Open pi interactively to drive it.", "info");
+            return false;
+        }
+        const runId = runFor(dir);
+        const started = startSupervisor({
+            targetDir: dir,
+            runId,
+            sessionId,
+            baseModel: baseModelOf(ctx),
+            harnessExtension: SELF_PATH,
+            hooks: {
+                onState: (st) => {
+                    supState = st;
+                    if (sessionLive)
+                        refreshWidget(widgetCtx ?? ctx);
+                },
+                onActivity: (line) => {
+                    activity = [...activity, line].slice(-120);
+                    if (!sessionLive)
+                        return;
+                    // Only the things a human would want interrupted for. Tool-by-tool
+                    // narration belongs in the widget's log, not in notifications.
+                    const live = widgetCtx ?? ctx;
+                    if (line.level === "error" || line.level === "warn" || line.level === "good") {
+                        try {
+                            notify(live, `infinity-harness: ${line.text}`, line.level === "error" ? "error" : line.level === "warn" ? "warning" : "info");
+                        }
+                        catch { }
+                    }
+                    try {
+                        refreshWidget(live);
+                    }
+                    catch { }
+                },
+                onApproval: (phase) => {
+                    if (sessionLive)
+                        void askForApproval(widgetCtx ?? ctx, dir, phase);
+                },
+                onStop: (reason, detail) => {
+                    if (!sessionLive)
+                        return;
+                    const live = widgetCtx ?? ctx;
+                    try {
+                        notify(live, `infinity-harness: run finished — ${detail}`, reason === "complete" ? "info" : "warning");
+                    }
+                    catch { }
+                    try {
+                        refreshWidget(live);
+                    }
+                    catch { }
+                },
+            },
+        });
+        if (isRefusal(started)) {
+            // A second pi window on the same project is a *viewer*. Saying so is
+            // better than quietly putting two workers in one working tree.
+            notify(ctx, `infinity-harness: ${started.reason} This window still shows the run.`, "warning");
+            supervisor = null;
+            refreshWidget(ctx);
+            return false;
+        }
+        supervisor = started;
+        return true;
+    };
+    const stopEngine = async (reason) => {
+        const running = supervisor;
+        supervisor = null;
+        if (!running)
+            return;
+        try {
+            await running.stop(reason);
+        }
+        catch {
+            /* a supervisor that will not stop cleanly must not block the command */
+        }
+    };
+    // -- session handoff ------------------------------------------------------
+    /** The task/feature/sprint/goal/subtask the pipeline is on right now, or null. */
+    const activePlanKeys = (dir) => {
+        try {
+            const { list } = loadFeatureList(dir);
+            const { config } = loadConfig(dir);
+            const phaseTask = nextActionableTask(list, config.currentPhase);
+            const task = phaseTask ?? nextActionableTask(list);
+            // Resolve sprint/goal via list, and active subtask of the focused task.
+            const taskKey = task?.compositeKey ?? null;
+            const featureId = task?.featureId ?? null;
+            const feature = featureId ? (list.features ?? []).find((f) => f.id === featureId) ?? null : null;
+            const sprintId = feature?.sprintId ?? null;
+            const goalId = feature?.goalId ?? (sprintId ? (list.sprints ?? []).find((s) => s.id === sprintId)?.goalId ?? null : null) ?? (list.goals?.[0]?.id ?? null);
+            const sprint = sprintId ? sprintId : null;
+            const goal = goalId ? goalId : null;
+            // First non-complete subtask of the active task.
+            let subtask = null;
+            const rawTask = feature && task ? feature.tasks.find((t) => t.id === task.id || t.key === task.key) ?? null : null;
+            if (rawTask?.subtasks?.length) {
+                const cur = rawTask.subtasks.find((s) => s.status !== "complete") ?? null;
+                if (cur)
+                    subtask = `${taskKey}#${cur.id ?? cur.title}`;
+            }
+            return { task: taskKey, feature: featureId, sprint, goal, subtask };
+        }
+        catch {
+            return { task: null, feature: null, sprint: null, goal: null, subtask: null };
+        }
+    };
+    const activeTaskKey = (dir) => activePlanKeys(dir).task;
+    /** How full this session's context is, 0..1, or null when pi cannot say. */
+    const contextRatio = (ctx) => {
+        try {
+            const usage = ctx.getContextUsage?.();
+            if (!usage || typeof usage.percent !== "number")
+                return null;
+            return usage.percent > 1 ? usage.percent / 100 : usage.percent;
+        }
+        catch {
+            return null;
+        }
+    };
+    /**
+     * Continue the run in a fresh session, if the policy says to.
+     *
+     * Returns true when a handoff was started, in which case the caller must not
+     * also send the brief — the replacement session will.
+     *
+     * `ctx.newSession` deadlocks if it is called from an event handler, so the
+     * actual switch happens in the `/infinity:handoff` command. Queuing that
+     * command as a follow-up user message is the documented way to reach a
+     * command from a handler.
+     */
+    const maybeHandOff = async (ctx, dir, brief, fromPhase, toPhase, fromTask) => {
+        // A handoff that was asked for and never happened would wedge the run:
+        // this session stops driving and the replacement never arrives. One
+        // attempt, then carry on here — a run that continues in a fat session is
+        // far better than a run that stops.
+        // A one-shot `pi -p` run has no next turn to hand anything to: replacing
+        // its session mid-flight produces a stale-context error and nothing else.
+        if (ctx.mode !== "tui" && ctx.mode !== "rpc")
+            return false;
+        if (handingOff) {
+            if (hasPendingHandoff(dir)) {
+                notify(ctx, "infinity-harness: the new session never started — continuing here.", "warning");
+                clearHandoff(dir);
+            }
+            handingOff = false;
+            return false;
+        }
+        try {
+            const { config } = loadConfig(dir);
+            const toKeys = activePlanKeys(dir);
+            // Map caller's fromTask (a compositeKey) back to its feature/sprint etc for the "from" side.
+            // We derive them from the plan so goal/sprint/feature boundaries are comparable.
+            let fromGoal = null;
+            let fromSprint = null;
+            let fromFeature = null;
+            try {
+                const { list } = loadFeatureList(dir);
+                if (fromTask) {
+                    const ft = (() => {
+                        for (const f of list.features ?? [])
+                            for (const t of f.tasks ?? [])
+                                if (t.key === fromTask || `${f.id}/${t.id}` === fromTask || t.id === fromTask)
+                                    return { featureId: f.id };
+                        return null;
+                    })();
+                    if (ft) {
+                        fromFeature = ft.featureId;
+                        const feat = list.features.find((f) => f.id === ft.featureId) ?? null;
+                        fromSprint = feat?.sprintId ?? null;
+                        fromGoal = feat?.goalId ?? (fromSprint ? (list.sprints ?? []).find((s) => s.id === fromSprint)?.goalId ?? null : null) ?? null;
+                    }
+                }
+            }
+            catch { }
+            const decision = shouldHandoff({
+                config,
+                fromPhase,
+                toPhase,
+                fromTask,
+                toTask: toKeys.task,
+                fromGoal,
+                toGoal: toKeys.goal,
+                fromSprint,
+                toSprint: toKeys.sprint,
+                fromFeature,
+                toFeature: toKeys.feature,
+                fromSubtask: null, // subtask delta is derived from task payload; tracked via fromTask composite + activePlanKeys
+                toSubtask: toKeys.subtask,
+                contextRatio: contextRatio(ctx),
+            });
+            if (!decision.handoff)
+                return false;
+            requestHandoff(dir, {
+                reason: decision.reason,
+                detail: decision.detail,
+                kickoff: composeKickoff(brief, decision.reason, decision.detail, carryNote(dir)),
+                carry: carryNote(dir),
+                runId: runFor(dir),
+            });
+            handingOff = true;
+            // The replacement session announces itself on arrival; saying it twice
+            // here would just make the log look like two handoffs happened.
+            pi.sendUserMessage("/infinity:handoff", {
+                deliverAs: "followUp",
+                expandPromptTemplates: true,
+            });
+            return true;
+        }
+        catch (e) {
+            // A handoff that cannot be arranged must never end the run. Fall back to
+            // continuing in this session, which is exactly the old behaviour.
+            notify(ctx, `infinity-harness: staying in this session — ${errMsg(e)}`, "warning");
+            handingOff = false;
+            clearHandoff(dir);
+            return false;
+        }
+    };
+    /** One line on where the run stands, carried into the next session. */
+    const carryNote = (dir) => {
+        try {
+            const { config } = loadConfig(dir);
+            if (config.session?.carryNotes === false)
+                return null;
+            const { list } = loadFeatureList(dir);
+            const p = computeProgress(list);
+            const recent = (config.gateHistory ?? []).slice(-3).map((g) => `${g.phase}:${g.result}`);
+            return (`  ${p.tasksDone}/${p.tasksTotal} tasks done, ${p.featuresDone}/${p.featuresTotal} features` +
+                (recent.length ? `; recent gates ${recent.join(", ")}` : ""));
+        }
+        catch {
+            return null;
+        }
+    };
+    // -- approvals ------------------------------------------------------------
+    /**
+     * Collect the human's signature on a phase.
+     *
+     * With dialogs, ask straight away — the human is right there and the run is
+     * stopped for them. Without dialogs there is nobody to ask, so the run parks
+     * and says loudly what it is waiting for, because auto-approving a phase the
+     * human explicitly asked to sign would make the setting a lie.
+     */
+    const askForApproval = async (ctx, dir, phase) => {
+        if (!ctx.hasUI) {
+            disarmRun(dir, `${phase} is waiting for approval`);
+            notify(ctx, `infinity-harness: ${phase.toUpperCase()} needs your approval and this mode has no dialogs. ` +
+                `Run \`/infinity:approve\` (optionally with what is wrong) to continue.`, "warning");
+            return;
+        }
+        const APPROVE = "approve — continue the run";
+        const REJECT = "send it back — I will say what is wrong";
+        const LATER = "not now — park the run";
+        const choice = await ctx.ui.select(`${phase.toUpperCase()} is waiting for you`, [APPROVE, REJECT, LATER]);
+        if (choice === REJECT) {
+            const note = await ctx.ui.input("What needs to change?", "the criteria do not cover refunds");
+            await applyApproval(ctx, dir, note ?? "");
+            return;
+        }
+        if (choice === APPROVE) {
+            await applyApproval(ctx, dir, "");
+            return;
+        }
+        disarmRun(dir, `${phase} is waiting for approval`);
+        notify(ctx, `infinity-harness: parked. \`/infinity:approve\` continues.`, "info");
+        refreshWidget(ctx);
+    };
+    /** Record the verdict and get the run moving again. */
+    const applyApproval = async (ctx, dir, note) => {
+        // Pin a rejection to the project as it is right now, so the run knows
+        // whether the agent has actually done anything about it before asking the
+        // human the same question again.
+        const outcome = resolveApproval(dir, note, note.trim() ? await fingerprint(dir) : "");
+        if (!outcome.ok) {
+            notify(ctx, `infinity-harness: ${outcome.error}`, "warning");
+            return;
+        }
+        refreshWidget(ctx);
+        if (outcome.approved) {
+            notify(ctx, `infinity-harness: ${outcome.phase.toUpperCase()} approved.`, "info");
+            // The gate already passed; re-settling lets the loop advance normally.
+            const moved = await advancePhase(dir);
+            refreshWidget(ctx);
+            if (!moved.ok) {
+                notify(ctx, `infinity-harness: could not advance — ${moved.error}`, "error");
+                return;
+            }
+            const brief = await briefText(dir);
+            lastBriefPhase = moved.to;
+            if (loopArmed(dir) && (await maybeHandOff(ctx, dir, brief, outcome.phase, moved.to, null)))
+                return;
+            pi.sendUserMessage(brief, { deliverAs: "followUp" });
+            return;
+        }
+        notify(ctx, `infinity-harness: ${outcome.phase.toUpperCase()} sent back — ${outcome.note}`, "warning");
+        pi.sendUserMessage(`A human reviewed ${outcome.phase.toUpperCase()} and sent it back:\n\n${outcome.note}\n\n` +
+            `Address that, then validate again.\n\n${await briefText(dir)}`, { deliverAs: "followUp" });
+    };
+    // -- lifecycle ------------------------------------------------------------
+    pi.on("session_start", async (event, ctx) => {
+        const dir = projectDir(ctx);
+        if (!isHarnessProject(dir))
+            return;
+        // A background worker loads this extension too — it needs the plan tools
+        // and the phase guard. What it must not do is drive: no widget, no brief
+        // injection, no loop, and above all no supervisor of its own, or one run
+        // would fork into a tree of pi processes spawning pi processes.
+        if (workerProcess) {
+            try {
+                pi.appendEntry("infinity:worker-session", {
+                    unit: process.env.INFINITY_HARNESS_UNIT ?? null,
+                    runId: process.env.INFINITY_HARNESS_RUN ?? null,
+                });
+            }
+            catch {
+                /* best effort */
+            }
+            return;
+        }
+        view = defaultView();
+        refreshWidget(ctx);
+        installTerminalShortcuts(ctx);
+        startWidgetPoll(ctx);
+        const reason = event?.reason ?? "startup";
+        const { config } = loadConfig(dir);
+        lastBriefPhase = config.currentPhase;
+        const engine = engineFor(dir);
+        // Under the background engine this session is a control panel: its model
+        // is the human's and stays the human's. Routing only ever applied to the
+        // legacy engine, where the human's session *is* the worker.
+        if (engine === "main-session") {
+            try {
+                await applyRouting(ctx, dir, `session_start:${reason}`);
+            }
+            catch { }
+        }
+        const run = reason === "startup" ? loadRunState(dir) : countSession(dir);
+        const armed = run?.armed === true;
+        notify(ctx, `infinity-harness active · ${config.currentPhase ?? "not started"}` +
+            (armed ? ` · run continuing (session ${run?.sessions ?? 1})` : ""), "info");
+        try {
+            pi.appendEntry("infinity:session", {
+                sessionId,
+                runId: runFor(dir),
+                reason,
+                dir,
+                phase: config.currentPhase,
+            });
+        }
+        catch {
+            /* entry log is best-effort */
+        }
+        // A handoff written by the session this one replaces. It carries the brief
+        // plus the reason the previous session ended, so the agent does not spend
+        // its first turn working out why it woke up mid-run.
+        // The background engine picks a run back up by restarting the supervisor:
+        // the plan, the phase and every budget are on disk, so a pi that was
+        // closed overnight resumes where it stopped rather than starting over.
+        if (engine !== "main-session") {
+            clearHandoff(dir);
+            if (armed) {
+                const ok = await startEngine(ctx, dir);
+                if (ok)
+                    notify(ctx, "infinity-harness: continuing the run in background sessions.", "info");
+            }
+            // A short orientation note, not the brief. The brief is several
+            // kilobytes and it is what makes a model start *working* the pipeline;
+            // in a control panel it would be paid for on every turn the human takes
+            // and would invite this session to do the work itself.
+            try {
+                pi.sendMessage({
+                    customType: "infinity:brief",
+                    content: controlPanelNote(dir, armed),
+                    display: true,
+                    details: { phase: config.currentPhase, engine },
+                }, { triggerTurn: false });
+            }
+            catch (e) {
+                notify(ctx, `infinity-harness: ${errMsg(e)}`, "warning");
+            }
+            refreshWidget(ctx);
+            return;
+        }
+        const pending = takeHandoff(dir);
+        if (pending && pending.runId === runFor(dir)) {
+            try {
+                pi.sendUserMessage(pending.kickoff, { deliverAs: "followUp" });
+                notify(ctx, `infinity-harness: ${describeHandoff(pending)}`, "info");
+            }
+            catch (e) {
+                notify(ctx, `infinity-harness: handoff failed — ${errMsg(e)}`, "error");
+            }
+            return;
+        }
+        // The brief is delivered as a message rather than a notification so the
+        // model actually reads it. Without this the agent starts from whatever
+        // the user typed and ignores the pipeline entirely.
+        //
+        // `nextTurn` is right in a terminal, where a human is about to type. It is
+        // a deadlock in `pi -p`, which has no next turn and waits forever for one:
+        // the harness made every headless run hang on startup. Non-interactive
+        // modes get `steer`, which folds the brief into the turn already starting.
+        try {
+            const text = await briefText(dir);
+            const interactive = ctx.mode === "tui" || ctx.mode === "rpc";
+            pi.sendMessage({ customType: "infinity:brief", content: text, display: true, details: { phase: config.currentPhase } }, { triggerTurn: false, deliverAs: interactive ? "nextTurn" : "steer" });
+        }
+        catch (e) {
+            notify(ctx, `infinity-harness: could not build brief — ${errMsg(e)}`, "warning");
+        }
+    });
+    /**
+     * The harness contract, in the system prompt.
+     *
+     * Everything else the harness tells the model is a message in the
+     * transcript, and every message in the transcript is something compaction
+     * can summarise into "the assistant was working on a harness". That is how a
+     * long run loses the plot: not by forgetting the plan — the plan is on disk
+     * — but by forgetting that it is *supposed to* work from the plan, stop when
+     * a gate fails, and never mark its own work complete.
+     *
+     * The system prompt is rebuilt from scratch every turn and is never
+     * summarised. Anything the run cannot afford to forget belongs here.
+     */
+    pi.on("before_agent_start", async (event, ctx) => {
+        if (!sessionLive)
+            return;
+        const dir = projectDir(ctx);
+        if (!isHarnessProject(dir))
+            return;
+        // Live-model routing rewrites *this* session's model, which is only ever
+        // right when this session is the worker. Under the background engine the
+        // human's model is theirs, and the routed model belongs to the child.
+        if (engineFor(dir) === "main-session") {
+            try {
+                await applyRouting(ctx, dir, "before_agent_start");
+            }
+            catch { }
+        }
+        try {
+            const viewState = (() => { try {
+                return deriveViewStateSync(dir);
+            }
+            catch {
+                return null;
+            } })();
+            const daemonAlive = (() => { try {
+                const d = readJsonSafe(resolvePath(dir, "harness/daemon.json"), null);
+                if (!d?.heartbeatAt)
+                    return false;
+                return Date.now() - new Date(d.heartbeatAt).getTime() < 90_000;
+            }
+            catch {
+                return false;
+            } })() ? "daemon alive" : viewState ? `daemon ${viewState.state}` : "daemon unknown";
+            const armed = (() => { try {
+                const r = readJsonSafe(runStatePathSync(dir), null);
+                return r?.armed === true ? "armed" : "not armed";
+            }
+            catch {
+                return "not armed";
+            } })();
+            const prefix = `[infinity-harness] ${daemonAlive}, ${armed}, phase=${loadConfig(dir).config.currentPhase ?? "?"}${viewState?.reason ? ` — ${viewState.reason}` : ""}\n`;
+            const contract = engineFor(dir) === "main-session" ? harnessContract(dir) : controlPanelContract(dir);
+            if (!contract) {
+                const base0 = event.systemPrompt ?? ctx.getSystemPrompt();
+                return { systemPrompt: `${prefix}\n${base0}` };
+            }
+            const base = event.systemPrompt ?? ctx.getSystemPrompt();
+            const routed = await routingSummaryForBrief(dir);
+            const suffix = routed ? `\n\n${routed}` : "";
+            return { systemPrompt: `${prefix}${base}${suffix}\n\n${contract}` };
+        }
+        catch {
+            return;
+        }
+    });
+    pi.on("session_tree", async (_event, ctx) => {
+        if (!sessionLive || workerProcess)
+            return;
+        refreshWidget(ctx);
+    });
+    /**
+     * Periodic nudge. Long runs drift: the model finishes work and forgets to
+     * record it, so the plan on disk and reality diverge. A short reminder every
+     * few calls costs little and keeps the plan honest.
+     */
+    pi.on("context", async (event, ctx) => {
+        if (!sessionLive || workerProcess)
+            return;
+        const dir = projectDir(ctx);
+        if (!isHarnessProject(dir))
+            return;
+        const messages = event.messages ?? [];
+        // Drop any reminder we injected on a previous call; they are transient
+        // scaffolding, not conversation, and accumulate into real token cost.
+        const filtered = messages.filter((m) => !isOurReminder(m));
+        const pruned = filtered.length !== messages.length ? { messages: filtered } : undefined;
+        let list;
+        try {
+            list = loadFeatureList(dir).list;
+        }
+        catch {
+            return pruned;
+        }
+        const progress = computeProgress(list);
+        if (progress.tasksTotal === 0 || progress.tasksDone === progress.tasksTotal) {
+            llmCalls = 0;
+            return pruned;
+        }
+        llmCalls += 1;
+        if (llmCalls < REMINDER_INTERVAL)
+            return pruned;
+        llmCalls = 0;
+        const open = (list.features ?? [])
+            .flatMap((f) => f.tasks ?? [])
+            .filter((t) => t.status !== "complete")
+            .slice(0, 12)
+            .map((t) => `${t.key ?? t.id}=${t.status}`)
+            .join(", ");
+        const reminder = {
+            role: "user",
+            content: [
+                {
+                    type: "text",
+                    text: `[infinity-harness] Plan revision ${list.baseRevision}. Open: ${open}. ` +
+                        `If the real state differs from this, call infinity_plan with baseRevision ${list.baseRevision} ` +
+                        `and the complete task list (omitted keys are deleted).`,
+                },
+            ],
+            timestamp: Date.now(),
+        };
+        return { messages: [...filtered, reminder] };
+    });
+    /**
+     * Compaction drops the transcript.
+     *
+     * The plan survives — it is on disk — and since 2.3 so do the rules, because
+     * they live in the system prompt (`before_agent_start`) where no summariser
+     * can reach them. What is left to restore is the *current* brief, so the
+     * agent picks up on the same task rather than re-deriving one from a summary
+     * of a summary.
+     */
+    pi.on("session_before_compact", async (_event, ctx) => {
+        const dir = projectDir(ctx);
+        if (!isHarnessProject(dir))
+            return;
+        try {
+            const { list } = loadFeatureList(dir);
+            const { config } = loadConfig(dir);
+            pi.appendEntry(CHECKPOINT, {
+                revision: list.baseRevision,
+                phase: config.currentPhase,
+                runId: runFor(dir),
+                at: new Date().toISOString(),
+            });
+        }
+        catch {
+            /* checkpoint is advisory */
+        }
+    });
+    pi.on("session_compact", async (event, ctx) => {
+        if (!sessionLive)
+            return;
+        // A worker that compacts re-reads the brief from its own prompt; the
+        // control-panel re-brief would put a second brief in front of it.
+        if (workerProcess)
+            return;
+        const dir = projectDir(ctx);
+        if (!isHarnessProject(dir))
+            return;
+        try {
+            const text = await briefText(dir);
+            // Delivery mode is the whole bug here. `nextTurn` waits for a human to
+            // type, which never happens in an unattended run — so the re-brief that
+            // was supposed to rescue the agent after compaction sat in a queue while
+            // the agent carried on without it. Overflow compaction retries the
+            // aborted turn immediately, so the brief has to land *in* that turn.
+            const willRetry = event?.willRetry === true;
+            const running = willRetry || !ctx.isIdle?.();
+            pi.sendMessage({
+                customType: "infinity:brief",
+                content: text,
+                display: false,
+                details: { after: "compaction", reason: event?.reason ?? null },
+            }, { triggerTurn: false, deliverAs: running ? "steer" : "nextTurn" });
+            refreshWidget(ctx);
+        }
+        catch {
+            /* the next brief will catch it up */
+        }
+    });
+    pi.on("turn_end", async (_event, ctx) => {
+        if (!sessionLive || workerProcess)
+            return;
+        refreshWidget(ctx);
+    });
+    /**
+     * The loop. `agent_settled` fires when the agent has stopped working, which
+     * is the only safe moment to run the gate and decide what happens next.
+     *
+     * The run's armed flag is read from disk on every tick rather than held in a
+     * closure, so a run survives the session handoffs it now performs, plus
+     * `/reload`, `/resume`, and pi being restarted.
+     */
+    pi.on("agent_settled", async (_event, ctx) => {
+        if (!sessionLive || workerProcess)
+            return;
+        const dir = projectDir(ctx);
+        if (!isHarnessProject(dir))
+            return;
+        if (loopBusy || handingOff)
+            return;
+        if (!loopArmed(dir))
+            return;
+        // The background engine drives the run from the supervisor, in this
+        // process, with no LLM turn in this session at all. Driving it from here
+        // too is what made the human's model pay for the whole run.
+        if (engineFor(dir) !== "main-session")
+            return;
+        loopBusy = true;
+        try {
+            const before = loadConfig(dir).config;
+            const beforeTask = activeTaskKey(dir);
+            const { decision } = await decideNext({ targetDir: dir, runId: runFor(dir) });
+            refreshWidget(ctx);
+            switch (decision.action) {
+                case "advanced": {
+                    notify(ctx, `infinity-harness: gate passed → ${decision.toPhase}`, "info");
+                    lastBriefPhase = decision.toPhase;
+                    if (await maybeHandOff(ctx, dir, decision.message, before.currentPhase, decision.toPhase, beforeTask)) {
+                        break;
+                    }
+                    pi.sendUserMessage(decision.message, { deliverAs: "followUp" });
+                    break;
+                }
+                case "continue": {
+                    // Say *why* it is going round again. "gate failed" was printed even
+                    // when the gate had passed and the run was waiting on a rejection
+                    // the agent had not acted on, which reads as a different bug.
+                    notify(ctx, `infinity-harness: ${decision.reason} — re-briefing`, "warning");
+                    // A failed gate on the same phase is normally the same session's
+                    // problem to fix. The exception is context pressure: carrying on in
+                    // a session that is about to compact is how a run degrades into
+                    // summaries of summaries.
+                    if (await maybeHandOff(ctx, dir, decision.message, before.currentPhase, before.currentPhase, beforeTask)) {
+                        break;
+                    }
+                    pi.sendUserMessage(decision.message, { deliverAs: "followUp" });
+                    break;
+                }
+                case "approve": {
+                    // Not a stop. The run is parked on a human, and the widget, the
+                    // status line and the notification all say so.
+                    notify(ctx, `infinity-harness: ${decision.detail}`, "warning");
+                    pi.sendUserMessage(decision.message, { deliverAs: "followUp" });
+                    await askForApproval(ctx, dir, decision.phase);
+                    break;
+                }
+                case "wait":
+                    disarmRun(dir, decision.detail);
+                    notify(ctx, `infinity-harness: ${decision.detail}`, "warning");
+                    break;
+                case "stop":
+                    disarmRun(dir, decision.detail);
+                    notify(ctx, `infinity-harness: run finished — ${decision.detail}`, decision.reason === "complete" ? "info" : "warning");
+                    try {
+                        pi.appendEntry("infinity:run-end", { reason: decision.reason, detail: decision.detail });
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                    break;
+            }
+            refreshWidget(ctx);
+        }
+        catch (e) {
+            disarmRun(dir, `loop error: ${errMsg(e)}`);
+            notify(ctx, `infinity-harness: loop error, stopping — ${errMsg(e)}`, "error");
+        }
+        finally {
+            loopBusy = false;
+        }
+    });
+    /**
+     * The enforcement bit: refuse edits that would skip a phase.
+     *
+     * We only block writes that actually change `currentPhase`. Blocking every
+     * touch of the config would stop the harness configuring itself.
+     */
+    pi.on("tool_call", async (event, ctx) => {
+        if (!sessionLive)
+            return;
+        const dir = projectDir(ctx);
+        if (!isHarnessProject(dir))
+            return;
+        const e = event;
+        const tool = String(e.toolName ?? e.name ?? "");
+        const input = e.input ?? {};
+        const path = String(input.path ?? input.file ?? input.filePath ?? "");
+        const content = String(input.content ?? input.data ?? input.new_string ?? "");
+        const command = String(input.command ?? input.cmd ?? "");
+        const editsPhase = path.replace(/\\/g, "/").includes("harness/config.json") &&
+            /write|edit|replace|patch/i.test(tool) &&
+            /"currentPhase"/.test(content);
+        const shellAdvance = /harness/.test(command) && /\bphase\b/.test(command) && /\bnext\b|\badvance\b/.test(command);
+        if (!editsPhase && !shellAdvance)
+            return;
+        const { config } = loadConfig(dir);
+        if (!config.currentPhase)
+            return;
+        const gate = await runChecks(dir, config.currentPhase, { record: false });
+        if (gate.overall)
+            return;
+        const failing = gate.checks
+            .filter((c) => !c.pass)
+            .map((c) => `${c.name} (${c.detail})`)
+            .join("; ");
+        return {
+            block: true,
+            reason: `infinity-harness: the ${config.currentPhase.toUpperCase()} gate has not passed, so the phase ` +
+                `cannot advance. Failing: ${failing}. Fix these, then let the harness advance the phase — ` +
+                `do not edit harness/config.json by hand.`,
+        };
+    });
+    pi.on("session_shutdown", async () => {
+        stopWidgetPoll();
+        sessionLive = false;
+        // A pi that closes must not leave a worker running against the project.
+        await stopEngine("this pi session closed");
+        if (remoteServer) {
+            try {
+                await remoteServer.close();
+            }
+            catch {
+                /* closing a dead server is fine */
+            }
+            remoteServer = null;
+            remoteDir = null;
+        }
+        loopBusy = false;
+    });
+    // -- tools ----------------------------------------------------------------
+    pi.registerTool({
+        name: "infinity_plan",
+        label: "Plan",
+        description: "Read or rewrite the harness plan. Submit the COMPLETE task list — any key you omit is deleted. " +
+            "Pass baseRevision (from the brief or a previous call) so a concurrent write cannot be clobbered; " +
+            "a stale revision is rejected and you should re-read and resubmit. Omit `tasks` to read the plan.",
+        parameters: {
+            type: "object",
+            properties: {
+                baseRevision: {
+                    type: "integer",
+                    minimum: 0,
+                    description: "Revision you read. Rejected if the plan has moved on.",
+                },
+                tasks: {
+                    type: "array",
+                    maxItems: 200,
+                    description: "Complete authoritative task list. Omit to read without writing.",
+                    items: {
+                        type: "object",
+                        required: ["key"],
+                        properties: {
+                            key: { type: "string", description: 'Stable key, e.g. "task-004" or "feature-002/task-004"' },
+                            subject: { type: "string", description: "What the task is" },
+                            status: {
+                                type: "string",
+                                enum: ["pending", "in_progress", "complete", "blocked", "rework"],
+                            },
+                            dependsOn: { type: "array", items: { type: "string" }, maxItems: 20 },
+                            subtasks: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    required: ["title"],
+                                    properties: {
+                                        title: { type: "string" },
+                                        status: { type: "string", enum: ["pending", "in_progress", "complete"] },
+                                    },
+                                },
+                            },
+                            difficulty: { type: "string", enum: ["easy", "moderate", "difficult"] },
+                            modelHint: { type: "string" },
+                            criteria: { type: "array", items: { type: "string" } },
+                            phase: { type: "string", enum: ["research", "define", "plan", "build", "verify", "simplify", "review", "ship"], description: "Which phase owns this task — task.phase, absent means build" },
+                        },
+                    },
+                },
+                features: {
+                    type: "array",
+                    maxItems: 100,
+                    description: "Feature names and acceptance criteria, merged by id. Unlike tasks, omitting a feature " +
+                        "here leaves it alone rather than deleting it. The DEFINE gate requires criteria on " +
+                        "every feature, so this is how DEFINE is passed.",
+                    items: {
+                        type: "object",
+                        required: ["id"],
+                        properties: {
+                            id: { type: "string", description: 'Feature id, e.g. "feature-001"' },
+                            name: { type: "string", description: "What the feature is, in a few words" },
+                            description: { type: "string" },
+                            criteria: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "How you will know this feature is done. Observable, not aspirational.",
+                            },
+                        },
+                    },
+                },
+                goal: {
+                    type: "string",
+                    description: "One line: what this whole run is for. Shown at the top of every brief.",
+                },
+            },
+        },
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            // A submission with no tasks, no features and no goal is a read.
+            const writing = Array.isArray(params?.tasks) || Array.isArray(params?.features) || typeof params?.goal === "string";
+            if (!writing) {
+                const { list } = loadFeatureList(dir);
+                const p = computeProgress(list);
+                // Features and their criteria are printed, not just tasks: the DEFINE
+                // gate judges criteria, so a plan view that hides them shows the model
+                // everything except the thing it is being marked on.
+                const rows = (list.features ?? [])
+                    .flatMap((f) => [
+                    `${f.id} · ${f.name}${f.criteria?.length ? "" : "  ← no acceptance criteria"}`,
+                    ...(f.criteria ?? []).map((c) => `    ✓ ${c}`),
+                    ...(f.tasks ?? []).map((t) => `    [${t.status}] ${t.key ?? t.id}: ${t.description}`),
+                ])
+                    .join("\n");
+                const goal = (list.goals ?? [])[0]?.title;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Plan revision ${list.baseRevision} — ${p.tasksDone}/${p.tasksTotal} tasks` +
+                                `${goal ? `\nGoal: ${goal}` : ""}\n${rows || "(empty)"}`,
+                        },
+                    ],
+                    details: { revision: list.baseRevision, progress: p },
+                };
+            }
+            try {
+                // writeTaskList takes the plan lock itself, around the whole
+                // read-apply-write. Wrapping it again here would only add a second
+                // lock with weaker semantics.
+                const result = writeTaskList(dir, {
+                    baseRevision: params.baseRevision,
+                    tasks: params.tasks,
+                    features: params.features,
+                    goal: params.goal,
+                });
+                refreshWidget(ctx);
+                return {
+                    content: [{ type: "text", text: summarizeApply(result) }],
+                    details: {
+                        revision: result.revision,
+                        change: result.change,
+                        tasks: result.tasks.map((t) => ({
+                            key: t.compositeKey,
+                            status: t.status,
+                            description: t.description,
+                        })),
+                    },
+                };
+            }
+            catch (e) {
+                const isValidation = e instanceof ValidationError || e?.name === "ValidationError";
+                const { list } = loadFeatureList(dir);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${isValidation ? "Rejected" : "Error"}: ${errMsg(e)}\nCurrent revision is ${list.baseRevision}.`,
+                        },
+                    ],
+                    details: { error: errMsg(e), revision: list.baseRevision },
+                    isError: true,
+                };
+            }
+        },
+    });
+    pi.registerTool({
+        name: "infinity_validate",
+        label: "Validate",
+        description: "Run the deterministic gate for the current phase and report each check. This is the only way work is " +
+            "judged complete — do not assert completion yourself. Optionally scope to one feature+task.",
+        parameters: {
+            type: "object",
+            properties: {
+                feature: { type: "string", description: "Scope to this feature id" },
+                task: { type: "string", description: "Scope to this task id (requires feature)" },
+            },
+        },
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            const { config } = loadConfig(dir);
+            if (!config.currentPhase) {
+                return {
+                    content: [{ type: "text", text: "No current phase — the harness is not initialised." }],
+                    details: { error: "no-phase" },
+                    isError: true,
+                };
+            }
+            const gate = await runChecks(dir, config.currentPhase, {
+                feature: params?.feature,
+                task: params?.task,
+                record: true,
+            });
+            refreshWidget(ctx);
+            const lines = gate.checks
+                .map((c) => `${c.advisory ? "·" : c.pass ? "+" : "x"} ${c.name}: ${c.detail}`)
+                .join("\n");
+            // Autopilot means auto-pilot: when the gate passes and the current
+            // phase's phaseMode is autopilot, advance immediately (any phase). The
+            // old allowlist stalled real autopilot builds after RESEARCH → DEFINE.
+            // Copilot still parks via needsApproval check below.
+            if (gate.overall && !params?.feature && !params?.task) {
+                try {
+                    const { needsApproval } = await import("../../src/approval.js");
+                    const fresh = loadConfig(dir).config;
+                    if (!needsApproval(fresh, fresh.currentPhase)) {
+                        const { advancePhase, ensurePhaseSeeded } = await import("../../src/core/phases.js");
+                        const moved = await advancePhase(dir);
+                        if (moved.ok && moved.to) {
+                            try {
+                                ensurePhaseSeeded(dir, moved.to);
+                            }
+                            catch { }
+                            refreshWidget(ctx);
+                            const brief = await briefText(dir);
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `Gate PASS on ${gate.phase} → advanced ${moved.from} → ${moved.to}\n${lines}\n\n${brief}`,
+                                    },
+                                ],
+                                details: { ...gate, advanced: moved },
+                            };
+                        }
+                    }
+                }
+                catch { }
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Gate ${gate.overall ? "PASS" : "FAIL"} on ${gate.phase}\n${lines}`,
+                    },
+                ],
+                details: gate,
+            };
+        },
+    });
+    pi.registerTool({
+        name: "infinity_advance",
+        label: "Advance Phase",
+        description: "Advance one phase. Refuses unless the current gate passes. Normally the harness does this for you " +
+            "after a passing validate; call it only when you need to advance explicitly.",
+        parameters: { type: "object", properties: {} },
+        async execute(_id, _params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            const { config } = loadConfig(dir);
+            if (!config.currentPhase) {
+                return {
+                    content: [{ type: "text", text: "No current phase." }],
+                    details: { error: "no-phase" },
+                    isError: true,
+                };
+            }
+            const gate = await runChecks(dir, config.currentPhase, { record: true });
+            if (!gate.overall) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Blocked: the ${config.currentPhase} gate failed — ${gate.failures.join(", ")}. ` +
+                                `Fix these and validate again.`,
+                        },
+                    ],
+                    details: gate,
+                    isError: true,
+                };
+            }
+            const moved = await advancePhase(dir);
+            refreshWidget(ctx);
+            if (!moved.ok) {
+                return {
+                    content: [{ type: "text", text: `Could not advance: ${moved.error}` }],
+                    details: { error: moved.error },
+                    isError: true,
+                };
+            }
+            const text = await briefText(dir);
+            return {
+                content: [{ type: "text", text: `Advanced ${moved.from} → ${moved.to}\n\n${text}` }],
+                details: { from: moved.from, to: moved.to },
+            };
+        },
+    });
+    pi.registerTool({
+        name: "infinity_brief",
+        label: "Next Step",
+        description: "Get the current brief: phase, role, feature, task, acceptance criteria and the gate verdict. " +
+            "Call this when you are unsure what to work on.",
+        parameters: {
+            type: "object",
+            properties: {
+                includeGate: { type: "boolean", description: "Run the gate to include a live verdict (slower)" },
+            },
+        },
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            const text = await briefText(dir, Boolean(params?.includeGate));
+            const brief = await buildBrief(dir);
+            return { content: [{ type: "text", text }], details: brief };
+        },
+    });
+    pi.registerTool({
+        name: "infinity_dashboard",
+        label: "Dashboard",
+        description: "Start, stop, or query the read-only web dashboard for this run. It binds to localhost and never " +
+            "mutates harness state — it is for the human watching the run.",
+        parameters: {
+            type: "object",
+            required: ["action"],
+            properties: {
+                action: { type: "string", enum: ["start", "stop", "status"] },
+                port: { type: "integer", minimum: 0, maximum: 65535, description: "0 picks a free port" },
+                host: { type: "string", description: "Bind address, default 127.0.0.1" },
+            },
+        },
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            const remote = await import("../../src/remote.js");
+            if (params.action === "stop") {
+                if (!remoteServer) {
+                    return { content: [{ type: "text", text: "Dashboard is not running." }], details: { running: false } };
+                }
+                const was = remoteServer.url;
+                await remoteServer.close();
+                remoteServer = null;
+                remoteDir = null;
+                return { content: [{ type: "text", text: `Dashboard stopped (${was}).` }], details: { running: false } };
+            }
+            if (params.action === "status") {
+                const state = remote.buildRemoteState(dir);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: remoteServer
+                                ? `Dashboard live at ${remoteServer.url} · plan revision ${state.baseRevision}`
+                                : `Dashboard not running · plan revision ${state.baseRevision}`,
+                        },
+                    ],
+                    details: { running: Boolean(remoteServer), url: remoteServer?.url ?? null, baseRevision: state.baseRevision },
+                };
+            }
+            if (remoteServer && remoteDir === dir) {
+                return {
+                    content: [{ type: "text", text: `Dashboard already live at ${remoteServer.url}` }],
+                    details: { running: true, url: remoteServer.url },
+                };
+            }
+            if (remoteServer) {
+                await remoteServer.close();
+                remoteServer = null;
+            }
+            const srv = await remote.createRemoteServer({
+                projectDir: dir,
+                host: params.host ?? "127.0.0.1",
+                port: typeof params.port === "number" ? params.port : 0,
+            });
+            remoteServer = srv;
+            remoteDir = dir;
+            notify(ctx, `infinity-harness dashboard: ${srv.url}`, "info");
+            return {
+                content: [{ type: "text", text: `Dashboard live at ${srv.url}` }],
+                details: { running: true, url: srv.url, port: srv.port },
+            };
+        },
+    });
+    // -- init -----------------------------------------------------------------
+    /**
+     * Said wherever a command finds no harness.
+     *
+     * It used to be "No harness in this project." and nothing else — a dead end
+     * with no exit, in a tool whose every other command needs a harness to work.
+     * A warning that does not say what to do instead is only half a warning.
+     */
+    const NO_HARNESS = "No harness in this project yet. Run /infinity:init to create one.";
+    /** The escalation ladder, in the order it climbs. */
+    const DEFAULT_LADDER = ["retry", "reframe", "consult", "rework", "replan", "master"];
+    /** Everything the pipeline can run. INIT is not a phase you choose. */
+    // Everything except INIT, which is not a phase anyone chooses. RESEARCH is
+    // here because it is a real, optional phase — omitting it from the picker
+    // was the difference between a feature and a feature nobody can find.
+    const SELECTABLE_PHASES = [
+        "research",
+        "define",
+        "plan",
+        "build",
+        "verify",
+        "simplify",
+        "review",
+        "ship",
+    ];
+    pi.registerTool({
+        name: "infinity_init",
+        label: "Init",
+        description: "Create a harness in this project: config, an empty plan, the phase and role docs, and starters " +
+            "for the documents the review gate demands. Detects the stack and its lint/test/build commands. " +
+            "Refuses if a harness already exists unless force is set, and never overwrites an existing file.",
+        parameters: {
+            type: "object",
+            properties: {
+                mode: { type: "string", enum: ["copilot", "autopilot"], description: "copilot keeps the human in the loop" },
+                stack: { type: "string", enum: ["node", "python", "rust", "go", "unknown"] },
+                phases: {
+                    type: "array",
+                    items: { type: "string", enum: ["define", "plan", "build", "verify", "simplify", "review", "ship"] },
+                    description: "Which phases run. Omit for the default pipeline.",
+                },
+                force: { type: "boolean", description: "Restore missing files in a project that already has a harness" },
+            },
+        },
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            const result = initHarness(dir, {
+                mode: params?.mode,
+                stack: params?.stack,
+                phases: params?.phases,
+                force: params?.force,
+            });
+            if (!result.ok) {
+                return {
+                    content: [{ type: "text", text: result.error ?? "init failed" }],
+                    details: result,
+                    isError: true,
+                };
+            }
+            refreshWidget(ctx);
+            return { content: [{ type: "text", text: describeInit(result) }], details: result };
+        },
+    });
+    pi.registerCommand("infinity:init", {
+        description: "Set up a harness here — workflow, goal, sessions, display",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            const force = /\bforce\b/.test(args);
+            const goalFromArgs = args.replace(/\bforce\b/g, "").trim();
+            if (isHarnessProject(dir) && !force) {
+                notify(ctx, "This project already has a harness. /infinity:config changes it; /infinity:init force restores missing files.", "warning");
+                return;
+            }
+            const detected = detectStack(dir);
+            // Three things used to be wrong here, and they compounded.
+            //
+            // The wizard never asked what was being built — so picking "autopilot"
+            // started a run with no idea and no scope, and the harness invented a
+            // project and began building it.
+            //
+            // "mode" was the only question, and one switch cannot say "drive
+            // yourself, but show me the plan before you build it".
+            //
+            // And even that switch only reached three phases. It is a mode per
+            // phase now, chosen from a workflow the human can build, name and reuse.
+            // `src/workflow.ts` owns what a workflow is, `src/intake.ts` what the
+            // answers mean, `src/ui/wizard.ts` how they are asked.
+            if (ctx.hasUI) {
+                const cmds = Object.entries(detected.commands).filter(([, v]) => Boolean(v));
+                const summary = cmds.length ? cmds.map(([k, v]) => `${k}: ${v}`).join(", ") : "no commands detected";
+                const go = await ctx.ui.select(`Create a harness here? ${detected.label} · ${summary}`, [
+                    "yes",
+                    "cancel",
+                ]);
+                if (go === undefined || go === "cancel") {
+                    notify(ctx, "init cancelled — nothing was written.", "info");
+                    return;
+                }
+            }
+            const wizard = ctx.hasUI
+                ? await runIntakeWizard({ prompt: prompterFor(ctx), brief: goalFromArgs || null, models: () => availableModels(ctx) })
+                : { cancelled: false, plan: unattendedIntake(goalFromArgs || null) };
+            if (wizard.cancelled) {
+                notify(ctx, "init cancelled — nothing was written.", "info");
+                return;
+            }
+            const plan = wizard.plan;
+            const result = initHarness(dir, {
+                mode: plan.mode,
+                phases: plan.phases,
+                approvals: plan.approvals,
+                phaseModes: plan.phaseModes,
+                workflow: plan.workflow,
+                display: plan.display,
+                session: plan.session,
+                execution: { parallelAt: plan.execution?.parallelAt ?? "task", maxWorkers: plan.execution?.maxWorkers ?? 3 },
+                brief: plan.brief,
+                router: plan.router
+                    ? {
+                        enabled: !!plan.router.enabled,
+                        byDifficulty: plan.router.byDifficulty,
+                        thinkingByDifficulty: plan.router.thinkingByDifficulty,
+                        master: plan.router.master ?? "",
+                        thinkingMaster: plan.router.thinkingMaster,
+                        default: plan.router.default ?? "",
+                        thinkingDefault: plan.router.thinkingDefault,
+                    }
+                    : undefined,
+                force,
+            });
+            if (!result.ok) {
+                notify(ctx, result.error ?? "init failed", "error");
+                return;
+            }
+            // The wizard already showed the summary before the human confirmed it;
+            // repeating it verbatim here is noise. Warnings do repeat — they are the
+            // part worth seeing twice.
+            const lines = [describeInit(result)];
+            if (plan.warnings.length)
+                lines.push("", ...plan.warnings.map((w) => `! ${w}`));
+            notify(ctx, lines.join("\n"), plan.warnings.length ? "warning" : "info");
+            refreshWidget(ctx);
+            // Show the next step, but do NOT auto-start the run.
+            // After /infinity:init the harness is initialized and parked.
+            // The agent can answer questions in this session, but the pipeline
+            // only runs after the human says so: /infinity:run (or "yes" to the
+            // last wizard question). Auto-starting here is the bug that made
+            // full-auto research steal the session that just created the harness.
+            if (wizard.launchNow) {
+                // Opt-in: wizard asked "Start the run now?" and the human said yes.
+                armRun(dir, sessionId);
+                // Capture baseModel for daemon (same as /infinity:run does)
+                try {
+                    const bm = baseModelOf(ctx);
+                    if (bm) {
+                        const { loadRunState: _ld, saveRunState: _sv, runIdFor: _rf } = await import("../../src/core/runState.js");
+                        const rid = _rf(dir, sessionId);
+                        const rs = _ld(dir);
+                        const parts = bm.split("/");
+                        const baseModel = parts.length >= 2 ? { provider: parts[0], id: parts.slice(1).join("/") } : { provider: "anthropic", id: bm };
+                        if (rs) {
+                            rs.baseModel = baseModel;
+                            _sv(dir, rs);
+                        }
+                        else {
+                            const { newRunState } = await import("../../src/core/runState.js");
+                            const ns = newRunState(rid);
+                            ns.baseModel = baseModel;
+                            _sv(dir, ns);
+                        }
+                    }
+                }
+                catch { }
+                // Try detached daemon, fall back to supervisor in this pi session.
+                const tryDaemonSpawn = async () => {
+                    try {
+                        const { spawn: _sp } = await import("node:child_process");
+                        const { existsSync: _ex, openSync: _op, closeSync: _cl } = await import("node:fs");
+                        const { resolve: _re } = await import("node:path");
+                        // Daemon lives in the *installed package*, not the target project.
+                        // Prefer the package's own dist (works in every install, including Node 26 where
+                        // stripping .ts under node_modules is ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING).
+                        // The .ts src entries are kept only for unpacked dev checkouts without a build.
+                        let pkgDir = null;
+                        try {
+                            pkgDir = _re(dirname(fileURLToPath(import.meta.url)), "../..");
+                        }
+                        catch { }
+                        const pkgJs = pkgDir ? _re(pkgDir, "dist/src/daemon/index.js") : null;
+                        const pkgTs = pkgDir ? _re(pkgDir, "src/daemon/index.ts") : null;
+                        const altJs = pkgDir ? _re(pkgDir, "dist/daemon/index.js") : null;
+                        const cands = [pkgJs, altJs, _re(dir, "dist/daemon/index.js"), _re(dir, "dist/src/daemon/index.js"), pkgTs, _re(dir, "src/daemon/index.ts")].filter(Boolean);
+                        let entry = null;
+                        for (const c of cands)
+                            if (_ex(c)) {
+                                entry = c;
+                                break;
+                            }
+                        if (!entry)
+                            return { spawned: false };
+                        try {
+                            const { loadDaemon: _ld, isDaemonAlive: _al } = await import("../../src/daemon/guard.js");
+                            const live = _ld(dir);
+                            if (live && _al(live))
+                                return { spawned: true };
+                        }
+                        catch { }
+                        const fd = _op(_re(dir, "harness/daemon.log"), "a");
+                        const a = [];
+                        if (entry.endsWith(".ts"))
+                            a.push("--experimental-strip-types", "--no-warnings=ExperimentalWarning");
+                        a.push(entry, dir);
+                        const ch = _sp(process.execPath, a, { detached: true, stdio: ["ignore", fd, fd], windowsHide: true, env: { ...process.env, INFINITY_HARNESS_WORKER: "1" } });
+                        try {
+                            ch.unref();
+                        }
+                        catch { }
+                        try {
+                            _cl(fd);
+                        }
+                        catch { }
+                        for (let i = 0; i < 40; i++) {
+                            await new Promise(r => setTimeout(r, 250));
+                            try {
+                                const { loadDaemon: l2, isDaemonAlive: a2 } = await import("../../src/daemon/guard.js");
+                                const v = l2(dir);
+                                if (v && a2(v))
+                                    return { spawned: true };
+                            }
+                            catch { }
+                        }
+                        return { spawned: true };
+                    }
+                    catch {
+                        return { spawned: false };
+                    }
+                };
+                const dr = await tryDaemonSpawn();
+                if (!dr.spawned)
+                    await startEngine(ctx, dir);
+                notify(ctx, "infinity-harness: run armed — background run started. /infinity:halt stops it.", "info");
+            }
+            else {
+                // The harness is parked — do NOT trigger an agent turn. The
+                // control-panel contract (before_agent_start) already stops
+                // autonomous work, but a `followUp` brief starts one anyway.
+                // `triggerTurn: false` keeps it visible without waking the model.
+                const brief = await briefText(dir);
+                const parkedNote = !plan.brief
+                    ? `The human has not said what they want built yet. Ask them, in one short question, and do not start any work or invent a scope until they answer. The harness is NOT running — "/infinity:run" starts it.\n\n${brief}`
+                    : plan.phases[0] === "research"
+                        ? `${brief}\n\nThis is RESEARCH — survey constraints and options first, then validate (infinity_validate) to advance. The harness is NOT running yet. Run "/infinity:run" when you are ready, or answer "yes — start the run now" next time you init.`
+                        : `${brief}\n\nThe harness is ready but NOT running. Run "/infinity:run" to start, or answer "yes — start the run now" in the wizard next time.`;
+                try {
+                    pi.sendMessage({ customType: "infinity:brief", content: parkedNote, display: true, details: { parked: true, phase: plan.phases[0] ?? null } }, { triggerTurn: false });
+                }
+                catch (e) {
+                    notify(ctx, `infinity-harness: ${errMsg(e)}`, "warning");
+                }
+            }
+        },
+    });
+    /**
+     * Change the workflow mid-run.
+     *
+     * Any of this is editable at any time and takes effect on the next gate —
+     * a run three phases deep is exactly when someone realises they do want to
+     * see the review after all.
+     */
+    pi.registerCommand("infinity:workflow", {
+        description: "Choose or build the workflow — which phases run, and which stop for you",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const { config } = loadConfig(dir);
+            const arg = args.trim();
+            if (arg === "" && !ctx.hasUI) {
+                notify(ctx, describeCurrentWorkflow(dir), "info");
+                return;
+            }
+            if (arg === "show" || arg === "list") {
+                const rows = listWorkflows().map((w) => `  ${w.builtIn ? " " : "*"} ${w.name} — ${w.description}`);
+                notify(ctx, `${describeCurrentWorkflow(dir)}\n\nAvailable (* = yours):\n${rows.join("\n")}`, "info");
+                return;
+            }
+            // `/infinity:workflow <name>` switches without a menu, which is what a
+            // second run in the same terminal wants.
+            let chosen = arg ? findWorkflow(arg) : undefined;
+            if (arg && !chosen) {
+                notify(ctx, `No workflow called "${arg}". \`/infinity:workflow list\` shows them.`, "warning");
+                return;
+            }
+            if (!chosen) {
+                if (!ctx.hasUI) {
+                    notify(ctx, "This mode has no dialogs — `/infinity:workflow <name>` switches directly.", "warning");
+                    return;
+                }
+                chosen = (await pickWorkflow(prompterFor(ctx))) ?? undefined;
+                if (!chosen) {
+                    notify(ctx, "Unchanged.", "info");
+                    return;
+                }
+            }
+            const { value } = await withLock(configPath(dir), () => {
+                const fresh = loadConfig(dir);
+                if (!fresh.ok)
+                    return false;
+                applyWorkflow(fresh.config, chosen);
+                // Keep the legacy field in step so a 2.3 tool reading this config
+                // still sees the same three answers it understands.
+                fresh.config.approvals = {
+                    research: fresh.config.phaseModes?.research === "copilot",
+                    define: fresh.config.phaseModes?.define === "copilot",
+                    plan: fresh.config.phaseModes?.plan === "copilot",
+                };
+                fresh.config.mode = signedPhases(fresh.config).length > 0 ? "copilot" : "autopilot";
+                return saveConfig(dir, fresh.config).ok;
+            });
+            if (!value) {
+                notify(ctx, "Could not save the workflow — config unreadable.", "error");
+                return;
+            }
+            notify(ctx, `${renderWorkflow(chosen)}\n\nIt takes effect at the next gate.`, "info");
+            refreshWidget(ctx);
+            void config;
+        },
+    });
+    pi.registerCommand("infinity:display", {
+        description: "Choose what the widget and the dashboard show, level by level",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const arg = args.trim();
+            const current = normalizeDisplay(loadConfig(dir).config.display);
+            if (arg === "show" || arg === "list") {
+                const rows = listDisplays().map((d) => `  ${d.builtIn ? " " : "*"} ${d.name} — ${d.description}`);
+                notify(ctx, `Now: ${summarizeDisplay(current)}\n\nTemplates (* = yours):\n${rows.join("\n")}`, "info");
+                return;
+            }
+            let next;
+            if (arg) {
+                const template = findDisplay(arg);
+                if (!template) {
+                    notify(ctx, `No template called "${arg}". \`/infinity:display list\` shows them.`, "warning");
+                    return;
+                }
+                next = template.policy;
+            }
+            else {
+                if (!ctx.hasUI) {
+                    notify(ctx, `Now: ${summarizeDisplay(current)}. \`/infinity:display <template>\` switches.`, "info");
+                    return;
+                }
+                next = await pickDisplay(prompterFor(ctx));
+                if (!next) {
+                    notify(ctx, "Unchanged.", "info");
+                    return;
+                }
+            }
+            const { value } = await withLock(configPath(dir), () => {
+                const fresh = loadConfig(dir);
+                if (!fresh.ok)
+                    return false;
+                fresh.config.display = normalizeDisplay(next);
+                return saveConfig(dir, fresh.config).ok;
+            });
+            if (!value) {
+                notify(ctx, "Could not save the display settings — config unreadable.", "error");
+                return;
+            }
+            // The widget is the answer to "did that do what I wanted", so redraw it
+            // before saying anything about it.
+            view = defaultView();
+            refreshWidget(ctx);
+            notify(ctx, `Showing: ${summarizeDisplay(normalizeDisplay(next))}`, "info");
+        },
+    });
+    /**
+     * Continue the run in a replacement session.
+     *
+     * This is a command rather than something the loop does directly because
+     * `ctx.newSession` is only safe from a command handler — pi deadlocks if an
+     * event handler calls it. The loop queues `/infinity:handoff` as a follow-up
+     * and this does the switch.
+     *
+     * Everything the next session needs is already on disk. `withSession` may
+     * only touch the context it is handed: the old `pi` and `ctx` are dead by
+     * the time it runs.
+     */
+    pi.registerCommand("infinity:handoff", {
+        description: "Continue this run in a fresh session, carrying the brief",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            // Asked for by hand, with no handoff queued: make one.
+            if (!hasPendingHandoff(dir)) {
+                const brief = await briefText(dir);
+                requestHandoff(dir, {
+                    reason: "manual",
+                    detail: args.trim() || "requested by hand",
+                    kickoff: composeKickoff(brief, "manual", args.trim() || "requested by hand", carryNote(dir)),
+                    carry: carryNote(dir),
+                    runId: runFor(dir),
+                });
+            }
+            const pending = takeHandoff(dir);
+            if (!pending) {
+                notify(ctx, "infinity-harness: nothing to hand off.", "warning");
+                return;
+            }
+            // The replacement session reads this back from disk in `session_start`;
+            // put it back so the claim above does not consume it.
+            requestHandoff(dir, {
+                reason: pending.reason,
+                detail: pending.detail,
+                kickoff: pending.kickoff,
+                carry: pending.carry,
+                runId: pending.runId,
+            });
+            handingOff = false;
+            try {
+                await ctx.waitForIdle?.();
+                const parent = ctx.sessionManager?.getSessionFile?.() ?? undefined;
+                const result = await ctx.newSession({ parentSession: parent ?? undefined });
+                if (result?.cancelled) {
+                    clearHandoff(dir);
+                    notify(ctx, "infinity-harness: handoff cancelled — continuing here.", "warning");
+                    pi.sendUserMessage(pending.kickoff, { deliverAs: "followUp" });
+                }
+            }
+            catch (e) {
+                // A handoff that cannot happen must never end the run: fall back to
+                // carrying on in this session, which is the pre-2.3 behaviour.
+                //
+                // Unless the session is already gone — `newSession` can fail *after*
+                // replacing the runtime, and reaching for the old `pi` then is the
+                // "stale ctx" error rather than a recovery.
+                clearHandoff(dir);
+                if (!sessionLive)
+                    return;
+                notify(ctx, `infinity-harness: could not start a new session — ${errMsg(e)}`, "warning");
+                pi.sendUserMessage(pending.kickoff, { deliverAs: "followUp" });
+            }
+        },
+    });
+    /**
+     * What the background sessions are doing.
+     *
+     * The run's work is no longer in this transcript, so this is where a human
+     * looks when they come back to the terminal. It prints rather than asking
+     * the model anything: reading the log must never cost a turn.
+     */
+    pi.registerCommand("infinity:workers", {
+        description: "Show the background pi sessions — which unit, which model, and the recent log",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const rows = Math.max(5, Math.min(120, Number.parseInt(args.trim(), 10) || 25));
+            const st = loadSupervisorState(dir);
+            const log = loadActivity(dir);
+            const engine = engineFor(dir);
+            const lines = [];
+            lines.push(engine === "background"
+                ? "Work runs in background pi sessions. This session spends nothing on it."
+                : "Work runs in THIS session (execution.engine = main-session). Your model is paying for the run.");
+            if (st?.unit)
+                lines.push(`Unit      ${describeUnit(st.unit, st.baseModel)}`);
+            if (st?.worker) {
+                const w = st.worker;
+                lines.push(`Worker    ${w.name} · ${w.state} · ${w.unitLabel} · asked ${w.model || "pi default"}` +
+                    (w.servedModel && w.servedModel !== w.model ? ` · served ${w.servedModel}` : "") +
+                    ` · ${w.turns} turn(s) · ${w.tokens.inputTokens + w.tokens.outputTokens} tokens`);
+                if (w.doing)
+                    lines.push(`          ${w.doing}`);
+            }
+            else {
+                lines.push("Worker    none running");
+            }
+            if (st?.history?.length) {
+                lines.push("");
+                lines.push("Finished sessions (newest last):");
+                for (const h of st.history.slice(-6)) {
+                    lines.push(`  ${h.name} · ${h.unitLabel} · ${h.servedModel ?? (h.model || "pi default")} · ${h.turns} turn(s)`);
+                }
+            }
+            lines.push("");
+            lines.push(log.length ? `Background log (last ${Math.min(rows, log.length)}):` : "Background log is empty.");
+            for (const l of log.slice(-rows)) {
+                const when = l.at.slice(11, 16);
+                lines.push(`  ${when} ${l.worker ? l.worker + " " : ""}${l.text}`);
+            }
+            pi.sendMessage({ customType: "infinity:workers", content: lines.join("\n"), display: true, details: { engine } }, { triggerTurn: false });
+        },
+    });
+    pi.registerCommand("infinity:approve", {
+        description: "Approve the phase waiting for you — or send it back with a note (via daemon when running)",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            // Prefer daemon when alive: forward approval to localhost daemon (token-guarded).
+            try {
+                const d = readJsonSafe(resolvePath(dir, "harness/daemon.json"), null);
+                if (d?.port) {
+                    const h = { "Content-Type": "application/json" };
+                    if (d.token)
+                        h["Authorization"] = `Bearer ${d.token}`;
+                    const r = await fetch(`http://127.0.0.1:${d.port}/approve`, { method: "POST", headers: h, body: JSON.stringify({ note: args.trim() }) });
+                    const j = await r.json().catch(() => ({}));
+                    if (r.ok && j.ok !== false) {
+                        notify(ctx, "infinity-harness: approved via daemon.", "info");
+                        refreshWidget(ctx);
+                        return;
+                    }
+                }
+            }
+            catch { }
+            const { config } = loadConfig(dir);
+            if (!config.awaitingApproval) {
+                const signing = approvedPhases(config);
+                notify(ctx, signing.length
+                    ? `Nothing is waiting. You are signing: ${signing.map((p) => p.toUpperCase()).join(", ")}.`
+                    : "Nothing is waiting, and you are not signing any phase. /infinity:config changes that.", "info");
+                return;
+            }
+            if (!loopArmed(dir))
+                armRun(dir, sessionId);
+            await applyApproval(ctx, dir, args.trim());
+        },
+    });
+    // -- escalation, rework, replan --------------------------------------------  // -- escalation, rework, replan --------------------------------------------
+    pi.registerTool({
+        name: "infinity_rework",
+        label: "Rework",
+        description: "Send a task and everything that depends on it back to `rework`. Use when work built on a task " +
+            "turns out not to hold up: the dependents were built on the broken thing, so they are suspect " +
+            "until re-proved. Bounded by the rework budget.",
+        parameters: {
+            type: "object",
+            required: ["task"],
+            properties: {
+                task: { type: "string", description: 'Task key, e.g. "feature-001/task-003"' },
+                reason: { type: "string", description: "Why this is going backwards" },
+                maxImpactDepth: { type: "integer", minimum: 1, maximum: 10 },
+            },
+        },
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            const { list } = loadFeatureList(dir);
+            const target = flattenTasks(list).find((t) => t.compositeKey === params.task || t.key === params.task || t.id === params.task);
+            if (!target) {
+                return {
+                    content: [{ type: "text", text: `No task matches "${params.task}".` }],
+                    details: { error: "no-such-task" },
+                    isError: true,
+                };
+            }
+            try {
+                const result = await startRework({
+                    projectDir: dir,
+                    featureId: target.featureId,
+                    taskId: target.id,
+                    key: target.key,
+                    reason: params.reason ?? "rework requested",
+                    runId: runFor(dir),
+                    maxImpactDepth: params.maxImpactDepth,
+                });
+                refreshWidget(ctx);
+                const downstream = result.impacted.length
+                    ? `Also flipped ${result.impacted.length} dependent task(s): ${result.impacted.join(", ")}`
+                    : "Nothing depends on it, so this is contained.";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${target.compositeKey} is back in rework (plan revision ${result.baseRevision}).\n${downstream}\nFix the root task first, then re-prove the rest.`,
+                        },
+                    ],
+                    details: result,
+                };
+            }
+            catch (e) {
+                return {
+                    content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+                    details: { error: "rework-failed" },
+                    isError: true,
+                };
+            }
+        },
+    });
+    pi.registerTool({
+        name: "infinity_replan",
+        label: "Replan",
+        description: "Add sprints, features or tasks to the plan mid-run, without resubmitting the whole task list. " +
+            "Use when the work turns out to need something that was never planned — the plan is the record, " +
+            "and building what it does not contain leaves it lying. Bounded by the replan budget.",
+        parameters: {
+            type: "object",
+            properties: {
+                reason: { type: "string", description: "What the plan was missing" },
+                addFeatures: {
+                    type: "array",
+                    maxItems: 20,
+                    items: {
+                        type: "object",
+                        required: ["id", "name"],
+                        properties: {
+                            id: { type: "string" },
+                            name: { type: "string" },
+                            description: { type: "string" },
+                            difficulty: { type: "string", enum: ["easy", "moderate", "difficult"] },
+                        },
+                    },
+                },
+                addTasks: {
+                    type: "array",
+                    maxItems: 50,
+                    items: {
+                        type: "object",
+                        required: ["featureId", "task"],
+                        properties: {
+                            featureId: { type: "string" },
+                            task: {
+                                type: "object",
+                                required: ["id", "description"],
+                                properties: {
+                                    id: { type: "string" },
+                                    key: { type: "string" },
+                                    description: { type: "string" },
+                                    status: { type: "string", enum: ["pending", "in_progress", "complete", "blocked", "rework"] },
+                                    dependsOn: { type: "array", items: { type: "string" } },
+                                    difficulty: { type: "string", enum: ["easy", "moderate", "difficult"] },
+                                    acceptanceCriteria: { type: "array", items: { type: "string" } },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            try {
+                const result = await amendPlan({
+                    projectDir: dir,
+                    reason: params.reason ?? "mid-run amendment",
+                    addFeatures: params.addFeatures,
+                    addTasks: params.addTasks,
+                });
+                refreshWidget(ctx);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Plan amended to revision ${result.baseRevision}: ` +
+                                `+${result.added.features} feature(s), +${result.added.tasks} task(s), ` +
+                                `+${result.added.sprints} sprint(s).`,
+                        },
+                    ],
+                    details: result,
+                };
+            }
+            catch (e) {
+                return {
+                    content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+                    details: { error: "replan-failed" },
+                    isError: true,
+                };
+            }
+        },
+    });
+    pi.registerTool({
+        name: "infinity_unstuck",
+        label: "Unstuck",
+        description: "Ask the escalation ladder what to try next: retry, reframe, consult a stronger model, rework, " +
+            "replan, or master. Read-only — it recommends, it does not act. /infinity:run consults it " +
+            "automatically when a run stalls; call it yourself when you are stuck and want the next rung.",
+        parameters: { type: "object", properties: {} },
+        async execute(_id, _params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            const { list } = loadFeatureList(dir);
+            const task = flattenTasks(list).find((t) => t.status === "in_progress" || t.status === "rework");
+            const choice = chooseUnstuckStrategy({
+                projectDir: dir,
+                featureId: task?.featureId,
+                taskId: task?.id,
+                currentDifficulty: task?.difficulty ?? null,
+                requireDeltaForRework: false,
+            });
+            const spent = escalationSummary(dir);
+            const text = choice.strategy
+                ? `Next rung: ${choice.strategy} — ${choice.reason}` +
+                    (choice.nextModel ? `\nModel: ${choice.nextModel}` : "") +
+                    `\nSpent so far: ${spent.reworks} rework(s), ${spent.replans} replan(s)` +
+                    (spent.returnTo ? `, returning to ${spent.returnTo}` : "")
+                : `The ladder has nothing left: ${choice.reason}. This needs a human.`;
+            return { content: [{ type: "text", text }], details: { ...choice, spent } };
+        },
+    });
+    pi.registerTool({
+        name: "infinity_spawn_worker",
+        label: "Spawn Worker",
+        description: "Run one task in an isolated worker: its own attempt directory, prompt, output log and " +
+            "fingerprint under tmp/. Use for a task worth attempting without the current conversation's " +
+            "context — a clean-room retry. Records the attempt whether or not a command is configured.",
+        parameters: {
+            type: "object",
+            required: ["task", "prompt"],
+            properties: {
+                task: { type: "string", description: 'Task key, e.g. "feature-001/task-003"' },
+                prompt: { type: "string", description: "The complete instruction for the isolated worker" },
+                command: { type: "string", description: "Shell command to run; {promptfile} is substituted" },
+                model: { type: "string", description: "Model reference for the worker" },
+                timeoutMs: { type: "integer", minimum: 1000, maximum: 3_600_000 },
+            },
+        },
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            const { list } = loadFeatureList(dir);
+            const target = flattenTasks(list).find((t) => t.compositeKey === params.task || t.key === params.task || t.id === params.task);
+            if (!target) {
+                return {
+                    content: [{ type: "text", text: `No task matches "${params.task}".` }],
+                    details: { error: "no-such-task" },
+                    isError: true,
+                };
+            }
+            try {
+                const result = await spawnIsolatedWorker({
+                    projectDir: dir,
+                    runId: runFor(dir),
+                    featureId: target.featureId,
+                    taskId: target.id,
+                    prompt: params.prompt,
+                    command: params.command,
+                    model: params.model,
+                    timeoutMs: params.timeoutMs,
+                });
+                const ran = params.command
+                    ? `exit ${result.exitCode}${result.timedOut ? " (timed out)" : ""}`
+                    : "recorded only — no command configured";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Worker attempt ${result.attempt} for ${target.compositeKey}: ${ran}\n` +
+                                `${result.attemptDir}\n\n${result.output.slice(-4000) || "(no output)"}`,
+                        },
+                    ],
+                    details: result,
+                };
+            }
+            catch (e) {
+                return {
+                    content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+                    details: { error: "worker-failed" },
+                    isError: true,
+                };
+            }
+        },
+    });
+    pi.registerTool({
+        name: "infinity_goal",
+        label: "Goal",
+        description: "The outer loop. `start` states a goal and opens pass 1; `status` reports where it is; " +
+            "`review` judges whether the work so far actually meets the goal and, if it does not, rewinds " +
+            "the pipeline for another pass with the remaining work named; `cancel` stops pursuing it. " +
+            "The phase gate decides whether the WORK is done; this decides whether the GOAL is done.",
+        parameters: {
+            type: "object",
+            required: ["action"],
+            properties: {
+                action: { type: "string", enum: ["start", "status", "review", "cancel"] },
+                goal: { type: "string", description: "start: what this whole run is for, in one sentence" },
+                maxIterations: { type: "integer", minimum: 1, maximum: 50, description: "start: how many passes at most" },
+                decision: {
+                    type: "string",
+                    enum: ["complete", "incomplete", "blocked", "failed"],
+                    description: "review: does the work meet the goal?",
+                },
+                rationale: { type: "string", description: "review: why, judged against the goal not the plan" },
+                remainingWork: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "review: required unless complete — what is still missing. The next pass is planned from this.",
+                },
+                reason: { type: "string", description: "cancel: why" },
+            },
+        },
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const dir = projectDir(ctx);
+            try {
+                if (params.action === "start") {
+                    if (!params.goal?.trim()) {
+                        return {
+                            content: [{ type: "text", text: "A goal needs to say something." }],
+                            details: { error: "no-goal" },
+                            isError: true,
+                        };
+                    }
+                    const { state } = await startGoal({
+                        targetDir: dir,
+                        goal: params.goal,
+                        runId: `goal-${runFor(dir)}`,
+                        maxIterations: params.maxIterations,
+                    });
+                    refreshWidget(ctx);
+                    const view = viewOf(state);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Goal set: ${view.goal}\nPass 1 of at most ${view.maxIterations}. The pipeline is at the ` +
+                                    `first phase — define what this needs, plan it, build it. When the pipeline completes, ` +
+                                    `call infinity_goal with action "review" and judge it against the goal, not the plan.`,
+                            },
+                        ],
+                        details: view,
+                    };
+                }
+                if (params.action === "status") {
+                    const state = await loadGoal(dir);
+                    if (!state) {
+                        return {
+                            content: [{ type: "text", text: "No goal is being pursued in this project." }],
+                            details: { active: false },
+                        };
+                    }
+                    const view = viewOf(state);
+                    const remaining = view.remainingWork.length
+                        ? `\nStill missing:\n${view.remainingWork.map((w) => `  - ${w}`).join("\n")}`
+                        : "";
+                    return {
+                        content: [{ type: "text", text: `${describeGoal(view)}\nPhase: ${view.phase}${remaining}` }],
+                        details: view,
+                    };
+                }
+                if (params.action === "review") {
+                    if (!params.decision || !params.rationale?.trim()) {
+                        return {
+                            content: [{ type: "text", text: "A review needs a decision and a rationale." }],
+                            details: { error: "incomplete-review" },
+                            isError: true,
+                        };
+                    }
+                    const outcome = await reviewGoal(dir, {
+                        decision: params.decision,
+                        rationale: params.rationale,
+                        remainingWork: params.remainingWork,
+                    });
+                    refreshWidget(ctx);
+                    if (!outcome.terminal) {
+                        // A new goal pass is the largest context boundary there is: the
+                        // pipeline has rewound to its first phase and the next pass plans
+                        // for what is left, not for what the last one already built.
+                        // Carrying a whole finished pass of conversation into it is the
+                        // worst case of the problem session handoff exists to solve.
+                        const brief = await briefText(dir);
+                        const { config } = loadConfig(dir);
+                        if (config.session?.handoff !== "off" && loopArmed(dir)) {
+                            const detail = `goal pass ${config.goalPass ?? "next"}`;
+                            requestHandoff(dir, {
+                                reason: "goal-pass",
+                                detail,
+                                kickoff: composeKickoff(brief, "goal-pass", detail, carryNote(dir)),
+                                carry: carryNote(dir),
+                                runId: runFor(dir),
+                            });
+                            handingOff = true;
+                            pi.sendUserMessage("/infinity:handoff", {
+                                deliverAs: "followUp",
+                                expandPromptTemplates: true,
+                            });
+                        }
+                        else {
+                            // Rewinding the pipeline means the next brief is a different one.
+                            pi.sendUserMessage(brief, { deliverAs: "followUp" });
+                        }
+                    }
+                    return { content: [{ type: "text", text: outcome.message }], details: viewOf(outcome.state) };
+                }
+                if (params.action === "cancel") {
+                    const state = await cancelGoal(dir, params.reason ?? "cancelled by request");
+                    refreshWidget(ctx);
+                    return {
+                        content: [{ type: "text", text: state ? `Goal cancelled: ${state.goal}` : "No goal to cancel." }],
+                        details: state ? viewOf(state) : { active: false },
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: `Unknown action "${params.action}".` }],
+                    details: { error: "unknown-action" },
+                    isError: true,
+                };
+            }
+            catch (e) {
+                return {
+                    content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+                    details: { error: "goal-failed" },
+                    isError: true,
+                };
+            }
+        },
+    });
+    // -- commands -------------------------------------------------------------
+    pi.registerCommand("infinity:status", {
+        description: "Show the current phase, plan and gate state",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const state = widgetStateFor(dir);
+            if (state) {
+                notify(ctx, renderWidget(state, { width: 76, styler, glyphs, boxed: true }).join("\n"), "info");
+            }
+            refreshWidget(ctx);
+        },
+    });
+    pi.registerCommand("infinity:next", {
+        description: "Print the current brief",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            // Without this guard it printed a brief for a project with no harness —
+            // a page of pipeline instructions for a pipeline that does not exist.
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            notify(ctx, await briefText(dir), "info");
+        },
+    });
+    pi.registerCommand("infinity:validate", {
+        description: "Run the gate for the current phase",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const { config } = loadConfig(dir);
+            if (!config.currentPhase) {
+                notify(ctx, "No current phase.", "warning");
+                return;
+            }
+            const gate = await runChecks(dir, config.currentPhase, { record: true });
+            const lines = gate.checks.map((c) => `${c.advisory ? "·" : c.pass ? "+" : "x"} ${c.name}: ${c.detail}`);
+            notify(ctx, `Gate ${gate.overall ? "PASS" : "FAIL"}\n${lines.join("\n")}`, gate.overall ? "info" : "warning");
+            refreshWidget(ctx);
+        },
+    });
+    pi.registerCommand("infinity:run", {
+        description: "Start the continuous loop — validate, advance, re-brief, until done or stuck (captures baseModel for daemon)",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            // Capture baseModel (X) at arm time — the detached Daemon has no ctx.model.
+            // Without this, Daemon refuses to arm and silently falls back to pi default.
+            try {
+                const bm = baseModelOf(ctx);
+                if (bm) {
+                    const { loadRunState: _load, saveRunState: _save, runIdFor: _runIdFor } = await import("../../src/core/runState.js");
+                    const runId = _runIdFor(dir, sessionId);
+                    const rs = _load(dir);
+                    const parts = bm.split("/");
+                    const baseModel = parts.length >= 2 ? { provider: parts[0], id: parts.slice(1).join("/") } : { provider: "anthropic", id: bm };
+                    if (rs) {
+                        rs.baseModel = baseModel;
+                        _save(dir, rs);
+                    }
+                    else {
+                        const { newRunState } = await import("../../src/core/runState.js");
+                        const ns = newRunState(runId);
+                        ns.baseModel = baseModel;
+                        _save(dir, ns);
+                    }
+                }
+            }
+            catch { }
+            // When a detached Daemon can serve this repo, prefer it: it is the only
+            // path where /infinity:halt|approve|pilot|replan go to Daemon and the
+            // model stays on X. Spawning it is one detached `node` process.
+            const tryDaemonSpawn = async () => {
+                try {
+                    const { spawn } = await import("node:child_process");
+                    const { existsSync, openSync, closeSync } = await import("node:fs");
+                    const { resolve: _resolve } = await import("node:path");
+                    // Daemon entry must exist; when not built (dev) fall back to supervisor.
+                    // Package dist first — Node 26 bans stripping .ts under node_modules.
+                    let _pkgDir = null;
+                    try {
+                        _pkgDir = dirname(fileURLToPath(import.meta.url));
+                        _pkgDir = _resolve(_pkgDir, "../..");
+                    }
+                    catch { }
+                    const _pkgJs = _pkgDir ? _resolve(_pkgDir, "dist/src/daemon/index.js") : null;
+                    const _altJs = _pkgDir ? _resolve(_pkgDir, "dist/daemon/index.js") : null;
+                    const _pkgTs = _pkgDir ? _resolve(_pkgDir, "src/daemon/index.ts") : null;
+                    const candidates = [
+                        _pkgJs,
+                        _altJs,
+                        _resolve(dir, "dist/src/daemon/index.js"),
+                        _resolve(dir, "dist/daemon/index.js"),
+                        _pkgTs,
+                        _resolve(dir, "src/daemon/index.ts"),
+                    ].filter(Boolean);
+                    let entry = null;
+                    for (const c of candidates)
+                        if (existsSync(c)) {
+                            entry = c;
+                            break;
+                        }
+                    if (!entry)
+                        return { spawned: false };
+                    // Guard: single owner — if a daemon is already alive, do not spawn rival.
+                    try {
+                        const { loadDaemon: _ld, isDaemonAlive: _alive } = await import("../../src/daemon/guard.js");
+                        const live = _ld(dir);
+                        if (live && _alive(live))
+                            return { spawned: true, url: `http://127.0.0.1:${live.port}/dashboard` };
+                    }
+                    catch { }
+                    const logFd = openSync(_resolve(dir, "harness/daemon.log"), "a");
+                    const args = [];
+                    if (entry.endsWith(".ts"))
+                        args.push("--experimental-strip-types", "--no-warnings=ExperimentalWarning");
+                    args.push(entry, dir);
+                    const child = spawn(process.execPath, args, { detached: true, stdio: ["ignore", logFd, logFd], windowsHide: true, env: { ...process.env, INFINITY_HARNESS_WORKER: "1" } });
+                    try {
+                        child.unref();
+                    }
+                    catch { }
+                    try {
+                        closeSync(logFd);
+                    }
+                    catch { }
+                    // Brief poll for daemon.json liveness (port picked as 0).
+                    for (let i = 0; i < 40; i++) {
+                        await new Promise(r => setTimeout(r, 250));
+                        try {
+                            const { loadDaemon: ld2, isDaemonAlive: alive2 } = await import("../../src/daemon/guard.js");
+                            const live2 = ld2(dir);
+                            if (live2 && alive2(live2))
+                                return { spawned: true, url: `http://127.0.0.1:${live2.port}/dashboard` };
+                        }
+                        catch { }
+                    }
+                    return { spawned: true };
+                }
+                catch {
+                    return { spawned: false };
+                }
+            };
+            armRun(dir, sessionId);
+            const engine = engineFor(dir);
+            notify(ctx, `infinity-harness: continuous run armed. It stops on completion, on an exhausted retry budget, ` +
+                `when no progress is detected, or when you create ${stopFilePath(dir)}. Use /infinity:halt to stop now.`, "info");
+            if (engine === "main-session") {
+                const text = await briefText(dir);
+                pi.sendUserMessage(text, { deliverAs: "followUp" });
+                return;
+            }
+            const daemonResult = await tryDaemonSpawn();
+            if (daemonResult.spawned) {
+                notify(ctx, daemonResult.url ? `infinity-harness: daemon running at ${daemonResult.url} — this session stays free; /infinity:halt stops it.` : "infinity-harness: daemon started — this session stays free; /infinity:halt stops it.", "info");
+                refreshWidget(ctx);
+                return;
+            }
+            // Fallback: legacy background supervisor (spawns pi child sessions in this pi process).
+            const unit = currentUnit(dir, baseModelOf(ctx));
+            await startEngine(ctx, dir);
+            notify(ctx, unit
+                ? `infinity-harness: working in background sessions — ${describeUnit(unit, baseModelOf(ctx))}. ` +
+                    `This session stays free; /infinity:workers shows what they are doing.`
+                : "infinity-harness: background engine started.", "info");
+            refreshWidget(ctx);
+        },
+    });
+    pi.registerCommand("infinity:goal", {
+        description: "State a goal and pursue it across passes — or review, cancel, or check one",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const text = args.trim();
+            if (text === "" || text === "status") {
+                const state = await loadGoal(dir);
+                if (!state) {
+                    notify(ctx, 'No goal set. `/infinity:goal <what you want built>` starts one.', "info");
+                    return;
+                }
+                const view = viewOf(state);
+                const remaining = view.remainingWork.length
+                    ? `\nStill missing:\n${view.remainingWork.map((w) => `  - ${w}`).join("\n")}`
+                    : "";
+                notify(ctx, `${describeGoal(view)}\nPhase: ${view.phase}${remaining}`, "info");
+                return;
+            }
+            if (text === "cancel") {
+                const state = await cancelGoal(dir, "cancelled from /infinity:goal");
+                notify(ctx, state ? `Goal cancelled: ${state.goal}` : "No goal to cancel.", "info");
+                refreshWidget(ctx);
+                return;
+            }
+            try {
+                const { state } = await startGoal({ targetDir: dir, goal: text, runId: `goal-${runFor(dir)}` });
+                refreshWidget(ctx);
+                notify(ctx, `Goal set: ${state.goal}\nPass 1 of at most ${state.limits.maxIterations}. ` +
+                    `The pipeline is back at its first phase.`, "info");
+                pi.sendUserMessage(await briefText(dir), { deliverAs: "followUp" });
+            }
+            catch (e) {
+                notify(ctx, e instanceof Error ? e.message : String(e), "error");
+            }
+        },
+    });
+    pi.registerCommand("infinity:unstuck", {
+        description: "What the escalation ladder would try next, and what it has spent",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const { list } = loadFeatureList(dir);
+            const task = flattenTasks(list).find((t) => t.status === "in_progress" || t.status === "rework");
+            const choice = chooseUnstuckStrategy({
+                projectDir: dir,
+                featureId: task?.featureId,
+                taskId: task?.id,
+                currentDifficulty: task?.difficulty ?? null,
+                requireDeltaForRework: false,
+            });
+            const spent = escalationSummary(dir);
+            const rework = loadRework(dir);
+            const lines = [
+                choice.strategy
+                    ? `Next rung: ${choice.strategy} — ${choice.reason}`
+                    : `The ladder has nothing left: ${choice.reason}`,
+                choice.nextModel ? `Model: ${choice.nextModel}` : null,
+                `Spent: ${spent.reworks} rework(s), ${spent.replans} replan(s)`,
+                rework ? `Returning to ${rework.returnFeature}/${rework.returnTask} — ${rework.reason}` : null,
+                `Ladder: ${DEFAULT_LADDER.join(" → ")}`,
+            ].filter((l) => l !== null);
+            notify(ctx, lines.join("\n"), "info");
+        },
+    });
+    pi.registerCommand("infinity:rework", {
+        description: "Send a task and its dependents back to rework (via daemon when running)",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const key = args.trim();
+            // Daemon owns rework.json mutation — forward when alive.
+            if (key && key !== "clear") {
+                try {
+                    const d = readJsonSafe(resolvePath(dir, "harness/daemon.json"), null);
+                    if (d?.port) {
+                        const h = { "Content-Type": "application/json" };
+                        if (d.token)
+                            h["Authorization"] = `Bearer ${d.token}`;
+                        const r = await fetch(`http://127.0.0.1:${d.port}/rework`, { method: "POST", headers: h, body: JSON.stringify({ task: key }) });
+                        const j = await r.json().catch(() => ({}));
+                        if (r.ok && j.ok !== false) {
+                            notify(ctx, `infinity-harness: rework ${key} via daemon.`, "info");
+                            refreshWidget(ctx);
+                            return;
+                        }
+                    }
+                }
+                catch { }
+            }
+            const { list } = loadFeatureList(dir);
+            const tasks = flattenTasks(list);
+            if (key === "clear") {
+                await clearRework(dir);
+                notify(ctx, "Rework record cleared.", "info");
+                refreshWidget(ctx);
+                return;
+            }
+            let target = tasks.find((t) => t.compositeKey === key || t.key === key || t.id === key);
+            if (!target && ctx.hasUI) {
+                const rows = tasks.map((t) => `${t.compositeKey} [${t.status}] ${t.description}`);
+                const picked = await ctx.ui.select("Send which task back to rework?", rows);
+                if (picked === undefined)
+                    return;
+                target = tasks[rows.indexOf(picked)];
+            }
+            if (!target) {
+                notify(ctx, key ? `No task matches "${key}".` : "Name a task: /infinity:rework <task-key>", "warning");
+                return;
+            }
+            try {
+                const result = await startRework({
+                    projectDir: dir,
+                    featureId: target.featureId,
+                    taskId: target.id,
+                    key: target.key,
+                    reason: "rework from /infinity:rework",
+                    runId: runFor(dir),
+                });
+                refreshWidget(ctx);
+                notify(ctx, `${target.compositeKey} → rework (revision ${result.baseRevision}). ` +
+                    (result.impacted.length
+                        ? `${result.impacted.length} dependent task(s) went with it: ${result.impacted.join(", ")}`
+                        : "Nothing depends on it."), "info");
+            }
+            catch (e) {
+                notify(ctx, e instanceof Error ? e.message : String(e), "error");
+            }
+        },
+    });
+    pi.registerCommand("infinity:halt", {
+        description: "Stop the continuous loop after the current turn",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            // Prefer daemon path: POST /halt to daemon (token-guarded), fall back to local.
+            try {
+                const d = readJsonSafe(resolvePath(dir, "harness/daemon.json"), null);
+                if (d?.port) {
+                    const headers = { "Content-Type": "application/json" };
+                    if (d.token)
+                        headers["Authorization"] = `Bearer ${d.token}`;
+                    const r = await fetch(`http://127.0.0.1:${d.port}/halt`, { method: "POST", headers, body: JSON.stringify({}) });
+                    const j = await r.json().catch(() => ({}));
+                    if (r.ok && j.ok !== false) {
+                        notify(ctx, "infinity-harness: halted via daemon.", "info");
+                        refreshWidget(ctx);
+                        return;
+                    }
+                }
+            }
+            catch { }
+            disarmRun(dir, "halted from /infinity:halt");
+            clearHandoff(dir);
+            await stopEngine("halted from /infinity:halt");
+            notify(ctx, "infinity-harness: continuous run stopped, background sessions closed.", "info");
+            refreshWidget(ctx);
+        },
+    });
+    pi.registerCommand("infinity:pause", {
+        description: "Pause the pipeline (persisted in harness/config.json)",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const { value } = await withLock(configPath(dir), () => {
+                const { config, ok } = loadConfig(dir);
+                if (!ok)
+                    return false;
+                config.paused = true;
+                return saveConfig(dir, config).ok;
+            });
+            disarmRun(dir, "paused from /infinity:pause");
+            await stopEngine("paused from /infinity:pause");
+            notify(ctx, value ? "infinity-harness: paused, background sessions closed." : "Could not pause — config unreadable.", value ? "info" : "error");
+            refreshWidget(ctx);
+        },
+    });
+    pi.registerCommand("infinity:resume", {
+        description: "Unpause the pipeline",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const { value } = await withLock(configPath(dir), () => {
+                const { config, ok } = loadConfig(dir);
+                if (!ok)
+                    return false;
+                config.paused = false;
+                return saveConfig(dir, config).ok;
+            });
+            if (value && loadRunState(dir)?.armed === true && engineFor(dir) !== "main-session") {
+                await startEngine(ctx, dir);
+            }
+            notify(ctx, value ? "infinity-harness: resumed." : "Could not resume — config unreadable.", value ? "info" : "error");
+            refreshWidget(ctx);
+        },
+    });
+    pi.registerCommand("infinity:config", {
+        description: "Configure the harness — models per difficulty tier, gates, commands, loop budgets",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            // `\/infinity:config show` prints everything without prompting, which is
+            // what you want over SSH, in a log, or when the UI has no dialogs.
+            if (args.trim() === "show" || !ctx.hasUI) {
+                notify(ctx, renderSettings(dir), "info");
+                if (!ctx.hasUI && args.trim() !== "show") {
+                    notify(ctx, "This mode has no dialogs — edit harness/config.json directly.", "warning");
+                }
+                return;
+            }
+            const changed = await runConfigMenu({
+                targetDir: dir,
+                prompt: prompterFor(ctx),
+                models: () => availableModels(ctx),
+            });
+            if (changed.length === 0) {
+                notify(ctx, "infinity-harness: no changes.", "info");
+            }
+            else {
+                notify(ctx, `infinity-harness: updated ${changed.join(", ")}`, "info");
+            }
+            refreshWidget(ctx);
+        },
+    });
+    pi.registerCommand("infinity:models", {
+        description: "Show which models pi has available, and how the harness is routing them",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            const models = availableModels(ctx);
+            const lines = [];
+            lines.push(`Models pi can use (${models.length})`);
+            if (models.length === 0) {
+                lines.push("  none — check provider auth, or run `pi models`");
+            }
+            else {
+                for (const m of models)
+                    lines.push(`  ${m.label}`);
+            }
+            if (isHarnessProject(dir)) {
+                lines.push("", "Routing");
+                const io = readAll(dir);
+                const group = SETTINGS.find((g) => g.id === "models");
+                for (const s of group?.settings ?? []) {
+                    lines.push(`  ${s.label.padEnd(28)} ${formatValue(s, readSetting(io, s))}`);
+                }
+                lines.push("", "Change these with /infinity:config.");
+            }
+            notify(ctx, lines.join("\n"), "info");
+        },
+    });
+    // -- keys -----------------------------------------------------------------
+    //
+    // The widget is nine rows of a plan that is routinely sixty. Without these
+    // the other fifty-one are unreachable without opening the dashboard, which
+    // is not a thing anyone does mid-glance.
+    //
+    // `alt+` and not `ctrl+`: pi already binds ctrl+j (newline), ctrl+k (delete
+    // to line end) and ctrl+o (expand tool output). Shadowing an editor key to
+    // scroll a widget would be a worse bug than the one being fixed.
+    //
+    // Shortcuts are editor-focused via registerShortcut, but also handled as a
+    // raw terminal fallback so they work when an overlay or selector has focus
+    // or when the terminal sends the legacy ESC+j sequence that the editor
+    // otherwise swallows as text.
+    const scrollDown = async (ctx) => moveView(ctx, SCROLL_STEP);
+    const scrollUp = async (ctx) => moveView(ctx, -SCROLL_STEP);
+    const toggleExpand = async (ctx) => {
+        view = { ...view, expanded: !view.expanded };
+        refreshWidget(ctx);
+    };
+    // Widget scroll/expand shortcuts — registered via pi's KeyId ("alt+j") so
+    // they participate in keybinding resolution, plus a raw terminal fallback so
+    // they also work while a ctx.ui.select dialog owns focus (where the editor
+    // shortcut path is shadowed) and across Kitty/legacy ESC+j encodings.
+    pi.registerShortcut("alt+j", { description: "infinity-harness: scroll the plan down", handler: scrollDown });
+    pi.registerShortcut("alt+k", { description: "infinity-harness: scroll the plan up", handler: scrollUp });
+    pi.registerShortcut("alt+o", { description: "infinity-harness: expand or collapse the plan widget", handler: toggleExpand });
+    // Also bind the same actions without alt for terminals that swallow alt+j/k
+    // (notably Windows Terminal + WSLg). User can remap in ~/.pi/agent/keybindings.json.
+    pi.registerShortcut("ctrl+alt+j", { description: "infinity-harness: scroll the plan down", handler: scrollDown });
+    pi.registerShortcut("ctrl+alt+k", { description: "infinity-harness: scroll the plan up", handler: scrollUp });
+    pi.registerShortcut("ctrl+alt+o", { description: "infinity-harness: expand or collapse the plan widget", handler: toggleExpand });
+    // Fallback raw input handler — covers selectors/overlays and both legacy
+    // ESC+j and Kitty keyboard protocol encodings. Installed per-session because
+    // onTerminalInput is a UI session affordance, not a global.
+    let removeTerminalShortcut = null;
+    const isAltWith = (data, letter) => {
+        // Legacy: ESC + letter, case-insensitive
+        if (data === "\x1b" + letter.toLowerCase() || data === "\x1b" + letter.toUpperCase())
+            return true;
+        // Some terminals already expose the Kittywrapped form via pattern tests above
+        const lower = data.toLowerCase();
+        if (lower === "\x1b" + letter.toLowerCase())
+            return true;
+        // Kitty CSI-u: ESC[106;3u (alt+j), ESC[107;3u (alt+k), ESC[111;3u (alt+o)
+        // modifier 3 == alt (see pi-tui keys.ts MODIFIERS.alt = 2, value 3 == alt press)
+        const code = letter.toLowerCase().charCodeAt(0);
+        if (data.includes(`\x1b[${code};3u`) || data.includes(`\x1b[${code};3:1u`))
+            return true;
+        return false;
+    };
+    const installTerminalShortcuts = (ctx) => {
+        try {
+            removeTerminalShortcut?.();
+        }
+        catch { }
+        try {
+            removeTerminalShortcut = ctx.ui.onTerminalInput((data) => {
+                if (isAltWith(data, "j")) {
+                    void scrollDown(ctx);
+                    return { consume: true };
+                }
+                if (isAltWith(data, "k")) {
+                    void scrollUp(ctx);
+                    return { consume: true };
+                }
+                if (isAltWith(data, "o")) {
+                    void toggleExpand(ctx);
+                    return { consume: true };
+                }
+                return undefined;
+            });
+        }
+        catch { }
+    };
+    pi.registerCommand("infinity:scroll", {
+        description: "Move the plan widget — up, down, top, bottom, expand, follow",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const what = args.trim().toLowerCase() || "down";
+            const rows = planRowCount(dir);
+            switch (what) {
+                case "up":
+                    moveView(ctx, -SCROLL_STEP);
+                    return;
+                case "down":
+                    moveView(ctx, SCROLL_STEP);
+                    return;
+                case "top":
+                    view = { ...view, scroll: 0 };
+                    break;
+                case "bottom":
+                    view = { ...view, scroll: rows };
+                    break;
+                case "expand":
+                    view = { ...view, expanded: true };
+                    break;
+                case "collapse":
+                    view = { ...view, expanded: false };
+                    break;
+                case "follow":
+                    // Back to tracking the active task, which is where it starts.
+                    view = defaultView();
+                    break;
+                default:
+                    notify(ctx, "Use: up · down · top · bottom · expand · collapse · follow", "warning");
+                    return;
+            }
+            refreshWidget(ctx);
+        },
+    });
+    pi.registerCommand("infinity:dashboard", {
+        description: "Open the read-only web dashboard for this run (served by daemon when running, fallback remote)",
+        handler: async (_args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            try {
+                const d = readJsonSafe(resolvePath(dir, "harness/daemon.json"), null);
+                if (d?.port) {
+                    const url = `http://127.0.0.1:${d.port}/dashboard`;
+                    notify(ctx, `infinity-harness dashboard (daemon): ${url}`, "info");
+                    return;
+                }
+            }
+            catch { }
+            const remote = await import("../../src/remote.js");
+            if (remoteServer) {
+                notify(ctx, `Dashboard already live at ${remoteServer.url} (fallback remote)`, "info");
+                return;
+            }
+            const srv = await remote.createRemoteServer({ projectDir: dir, host: "127.0.0.1", port: 0 });
+            remoteServer = srv;
+            remoteDir = dir;
+            notify(ctx, `infinity-harness dashboard: ${srv.url}`, "info");
+        },
+    });
+    pi.registerCommand("infinity:pilot", {
+        description: "Set pilot mode — copilot | autopilot | full (takes effect at next phase boundary)",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            // Prefer daemon when alive.
+            const raw = String(args ?? "").trim().toLowerCase();
+            if (raw && ["copilot", "autopilot", "full"].includes(raw)) {
+                try {
+                    const d = readJsonSafe(resolvePath(dir, "harness/daemon.json"), null);
+                    if (d?.port) {
+                        const h = { "Content-Type": "application/json" };
+                        if (d.token)
+                            h["Authorization"] = `Bearer ${d.token}`;
+                        const r = await fetch(`http://127.0.0.1:${d.port}/pilot`, { method: "POST", headers: h, body: JSON.stringify({ pilot: raw }) });
+                        const j = await r.json().catch(() => ({}));
+                        if (r.ok && j.ok !== false) {
+                            notify(ctx, `infinity-harness: pilot → ${raw} via daemon (next boundary).`, "info");
+                            refreshWidget(ctx);
+                            return;
+                        }
+                    }
+                }
+                catch { }
+            }
+            // Fallback: write config locally. Import core helper for pilot preset.
+            try {
+                const { applyPilotPreset } = await import("../../src/core/config.js");
+                const { withLock: _wl } = await import("../../src/core/lock.js");
+                if (!raw) {
+                    const { config: c } = loadConfig(dir);
+                    const cur = c.pilot ?? "autopilot";
+                    notify(ctx, `infinity-harness pilot is ${cur}. Usage: /infinity:pilot copilot|autopilot|full`, "info");
+                    return;
+                }
+                if (!["copilot", "autopilot", "full"].includes(raw)) {
+                    notify(ctx, `"${raw}" is not a pilot mode — copilot | autopilot | full`, "warning");
+                    return;
+                }
+                const wl = _wl;
+                await wl(configPath(dir), () => {
+                    const l = loadConfig(dir);
+                    if (!l.ok)
+                        return false;
+                    l.config.pilot = raw;
+                    applyPilotPreset(l.config, raw);
+                    return saveConfig(dir, l.config).ok;
+                });
+                notify(ctx, `infinity-harness: pilot → ${raw} (next phase boundary).`, "info");
+                refreshWidget(ctx);
+            }
+            catch (e) {
+                notify(ctx, e instanceof Error ? e.message : String(e), "error");
+            }
+        },
+    });
+    pi.registerCommand("infinity:replan", {
+        description: "Propose a plan amendment (mid-run addFeatures/addTasks) — via daemon when running",
+        handler: async (args, ctx) => {
+            const dir = projectDir(ctx);
+            if (!isHarnessProject(dir)) {
+                notify(ctx, NO_HARNESS, "warning");
+                return;
+            }
+            const raw = String(args ?? "").trim();
+            // Try daemon first so replan invariants (cancel-not-delete, maxReplansPerPhase) are honoured under daemon lock.
+            try {
+                const d = readJsonSafe(resolvePath(dir, "harness/daemon.json"), null);
+                if (d?.port) {
+                    const h = { "Content-Type": "application/json" };
+                    if (d.token)
+                        h["Authorization"] = `Bearer ${d.token}`;
+                    let body = {};
+                    if (raw) {
+                        try {
+                            body = JSON.parse(raw);
+                        }
+                        catch {
+                            body = { reason: raw };
+                        }
+                    }
+                    const r = await fetch(`http://127.0.0.1:${d.port}/replan`, { method: "POST", headers: h, body: JSON.stringify(body) });
+                    const j = await r.json().catch(() => ({}));
+                    if (r.ok && j.ok !== false) {
+                        notify(ctx, `infinity-harness: replan via daemon — ${JSON.stringify(j)}`, "info");
+                        refreshWidget(ctx);
+                        return;
+                    }
+                }
+            }
+            catch { }
+            notify(ctx, `Replan: ${raw || "use infinity_replan tool with addFeatures/addTasks, or POST JSON to /replan"}`, "info");
+        },
+    });
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** The workflow this project is on, and whether it still matches a named one. */
+function describeCurrentWorkflow(dir) {
+    const { config } = loadConfig(dir);
+    const named = matchWorkflow(config);
+    const head = `Workflow: ${summarizeWorkflow(config)}`;
+    const rail = (config.phases?.enabled ?? [])
+        .map((p) => (config.phaseModes?.[p] === "copilot" ? `[${p}]` : p))
+        .join(" → ");
+    const drift = named
+        ? ""
+        : "\n\nThese settings do not match any saved workflow. `/infinity:workflow` can save them as one.";
+    return `${head}\n  ${rail}\n  (a phase in [brackets] stops for you)${drift}`;
+}
+/**
+ * What this session is, when the work is happening somewhere else.
+ *
+ * Deliberately a few lines rather than the brief. The brief is several
+ * kilobytes, it is re-read on every turn once it is in the transcript, and it
+ * is written to make a model start building — none of which belongs in a
+ * window whose job is to show a human what is going on.
+ */
+function controlPanelNote(dir, armed) {
+    const { config } = loadConfig(dir);
+    const { list } = loadFeatureList(dir);
+    const p = computeProgress(list);
+    const L = [];
+    L.push("[infinity-harness] control panel");
+    L.push(`${(config.currentPhase ?? "not started").toUpperCase()} · ${p.tasksDone}/${p.tasksTotal} tasks · ` +
+        `${p.featuresDone}/${p.featuresTotal} features · plan rev ${list.baseRevision}` +
+        (armed ? " · run armed" : ""));
+    L.push("");
+    L.push("The run works in separate background pi sessions, each on the model its difficulty tier " +
+        "names. This session does not do that work and should not start it.");
+    L.push("");
+    L.push("  /infinity:workers   what the background sessions are doing right now");
+    L.push("  /infinity:status    where the run is");
+    L.push(armed ? "  /infinity:halt      stop the run" : "  /infinity:run       start the run");
+    L.push("  /infinity:approve   sign a phase that is waiting for you");
+    return L.join("\n");
+}
+/**
+ * The contract for a control panel.
+ *
+ * The pipeline contract tells a model to work the plan. Told that in a
+ * session whose whole point is *not* to work the plan, a model helpfully
+ * starts building — on the human's own model, which is the bug this engine
+ * exists to fix. This says the opposite, in as few words.
+ */
+function controlPanelContract(dir) {
+    const { config, ok } = loadConfig(dir);
+    if (!ok || !config.currentPhase)
+        return null;
+    const { list } = loadFeatureList(dir);
+    const p = computeProgress(list);
+    let armed = false;
+    try {
+        const r = readJsonSafe(runStatePathSync(dir), null);
+        armed = r?.armed === true;
+    }
+    catch { }
+    // When parked, the harness does NO work anywhere — not in this session and
+    // not in background sessions. When armed, background sessions do the work
+    // and this session is idle by design (it never spends the human's model).
+    const workLine = armed
+        ? "The work is being done by separate background pi sessions on their own models, not by you."
+        : "The harness is NOT running — nothing is happening in background. Only `/infinity:run` starts it.";
+    const rule1 = armed
+        ? "1. Do not implement plan tasks, advance phases, or edit `harness/` by hand. Answer the"
+        : "1. Do NOT start building, researching, or validating. The harness is parked. If the human";
+    const rule1b = armed
+        ? "   human's questions about the run, and use `/infinity:workers` and `infinity_status`"
+        : "   asks you to do harness work anyway, tell them it is parked and needs `/infinity:run`,";
+    const rule1c = armed
+        ? "   to see what the background sessions are doing."
+        : "   then stop. Do not touch `harness/` files.";
+    const rule2 = armed
+        ? "2. If the human asks you to build something, say that the harness is driving it and offer"
+        : "2. While parked, you may ONLY answer questions about the project — its stack, commands,";
+    const rule2b = armed
+        ? "   `/infinity:run`, `/infinity:halt`, or `/infinity:replan` instead."
+        : "   files, and how the harness would run. Do not write code, docs, plans, or validation.";
+    const rule3 = "3. The plan of record is `harness/features/feature-list.json`; your memory of it is not.";
+    const extra = armed ? [] : ["", "Parked means parked. No tool calls that mutate the project while parked."];
+    return [
+        "## infinity-harness — you are the control panel" + (armed ? "" : " (PARKED)"),
+        "",
+        `This project runs an infinity-harness pipeline at **${config.currentPhase.toUpperCase()}**, ` +
+            `${p.tasksDone}/${p.tasksTotal} tasks done. ` + workLine,
+        "",
+        rule1,
+        rule1b,
+        rule1c,
+        rule2,
+        rule2b,
+        rule3,
+        ...extra,
+    ].join("\n");
+}
+/**
+ * The few sentences the run cannot afford to have summarised away.
+ *
+ * Short on purpose: this is paid for on every single request, and a long
+ * system prompt crowds out the work. It carries only what stops the agent
+ * going freelance after a compaction — where the pipeline is, what it is
+ * working on, and the three rules that make the harness a harness.
+ */
+function harnessContract(dir) {
+    const { config, ok } = loadConfig(dir);
+    if (!ok || !config.currentPhase)
+        return null;
+    const { list } = loadFeatureList(dir);
+    const progress = computeProgress(list);
+    const phase = config.currentPhase.toUpperCase();
+    const role = config.currentRole ?? "";
+    const L = [];
+    L.push("## infinity-harness");
+    L.push("");
+    L.push(`This project is driven by the infinity-harness pipeline. You are at **${phase}**` +
+        (role ? ` wearing the ${role} hat` : "") +
+        `, with ${progress.tasksDone}/${progress.tasksTotal} tasks done across ` +
+        `${progress.featuresTotal} feature(s). Plan revision ${list.baseRevision}.`);
+    L.push("");
+    L.push("Rules that do not change, whatever the conversation above says:");
+    L.push("");
+    L.push("1. The plan of record is `harness/features/feature-list.json`, reached through the");
+    L.push("   `infinity_plan` tool. It is the truth; your memory of it is not.");
+    L.push("2. You never advance a phase and never mark your own work complete. Call");
+    L.push("   `infinity_validate`; the gate is the only referee. Do not edit");
+    L.push("   `harness/config.json` by hand.");
+    L.push("3. If you do not know what to do next, call `infinity_brief` rather than guessing.");
+    if (config.awaitingApproval) {
+        L.push(`4. ${String(config.awaitingApproval).toUpperCase()} is waiting for a human signature. Do not start the next phase.`);
+    }
+    if (config.paused) {
+        L.push("4. The pipeline is PAUSED. Do not continue autonomously — report and stop.");
+    }
+    return L.join("\n");
+}
+/** Our injected reminders, so they can be pruned before the next call. */
+function isOurReminder(m) {
+    const msg = m;
+    if (msg?.role !== "user" || !Array.isArray(msg.content))
+        return false;
+    return msg.content.some((c) => c?.type === "text" && c.text?.startsWith("[infinity-harness]"));
+}
+//# sourceMappingURL=index.js.map