@mjasnikovs/pi-task 0.38.30 → 0.38.32

package/dist/task/failure-classifier.js

@@ -5,13 +5,36 @@
 import { updateTaskFrontMatter } from './task-io.js';
 import { flashTerminalWidget } from './widget.js';
 import { publishLifecycleNotice } from '../remote/bridge.js';
-import { LoopExhaustedError, LeakedToolCallError, ModelError, USER_CANCELLED } from './child-runner.js';
+import { BackendDownError, CommandTimeoutError, LoopExhaustedError, LeakedToolCallError, ModelError, USER_CANCELLED } from './child-runner.js';
 // ─── Classifier ──────────────────────────────────────────────────────────────
 export function classifyFailure(err, aborted) {
     const msg = err instanceof Error ? err.message : String(err);
     if (aborted || msg === USER_CANCELLED) {
         return { state: 'cancelled', notify: 'cancelled.', level: 'warning' };
     }
+    // Classified by TYPE, above the message-sniffing branch below: this is the one
+    // case where the probe positively established the endpoint did not answer, and
+    // its message names no errno for that branch to match.
+    if (err instanceof BackendDownError) {
+        return {
+            state: 'failed',
+            reason: `model_unreachable: ${err.message}`,
+            flash: 'model_unreachable',
+            notify: 'failed: model unreachable — restart the model, then resume.',
+            level: 'error'
+        };
+    }
+    // The fix is in the SPEC, not the model, so the notify says which command.
+    if (err instanceof CommandTimeoutError) {
+        return {
+            state: 'failed',
+            reason: err.message.slice(0, 200),
+            flash: 'command_timeout',
+            notify: `failed: \`${err.kill.toolName}\` never returned on any attempt. `
+                + `Resume to bound it in VERIFY.`,
+            level: 'error'
+        };
+    }
     if (err instanceof LoopExhaustedError) {
         return {
             state: 'failed',

package/dist/task/gate-child.d.ts

@@ -75,15 +75,26 @@ export interface GateChildDeps {
     /** Hung-stream bound; the probe-based stall guard cannot supply it. */
     streamInactivityMs: number;
     /**
-     * The resolved `['--thinking', level]` fragment for the `gate` reasoning
-     * group, or `[]` to inherit the session default.
+     * The resolved argv fragment for the `gate` group — its model and its
+     * thinking level — or `[]` to inherit both.
      *
      * REQUIRED, like its two neighbours above: gate-child takes resolved config
      * values and gate-deps supplies them. Optional-with-a-default would let a new
-     * gate wiring silently run at a level nobody chose, which is the failure the
+     * gate wiring silently run on a model nobody chose, which is the failure the
      * whole profile feature exists to end.
      */
-    thinking: readonly string[];
+    groupArgs: readonly string[];
+    /**
+     * The context window of the model THESE children run on, for the churn rule.
+     *
+     * Not `status.parentContextWindow`, which is a per-RUN value and a run spans
+     * several groups. The direction matters: a window smaller than the child's
+     * real one makes churn fire early and kill a healthy child, so this follows
+     * the `gate` group's model and falls back to the host's.
+     *
+     * REQUIRED, like its neighbours: gate-child takes resolved config values.
+     */
+    contextWindow: number;
     /**
      * The live widget state this child feeds and its loader reads. SHARED with
      * the caller — the verify gate's own loader reads the same status while this

package/dist/task/gate-child.js

@@ -98,7 +98,7 @@ export function makeGateChild(deps) {
                         commandTimeoutMs: deps.commandTimeoutMs,
                         streamInactivityMs: deps.streamInactivityMs
                     },
-                    thinking: deps.thinking,
+                    groupArgs: deps.groupArgs,
                     // A discarded attempt is otherwise invisible: the returned
                     // exitCode/text describe the FINAL attempt, so a child that
                     // burned two attempts reads exactly like one that ran clean.
@@ -125,7 +125,7 @@ export function makeGateChild(deps) {
                     // stream — what `--mode json` emits — carries token counts but
                     // no context window; `contextWindow` appears nowhere in
                     // agent-session.d.ts.
-                    contextWindow: deps.status.parentContextWindow
+                    contextWindow: deps.contextWindow
                 });
             }
             finally {

package/dist/task/gate-deps.js

@@ -48,7 +48,8 @@ import { assessRunnerGlobs, runnerGlobVerifyFindings } from './runner-globs.js';
 import { captureGitState, reconcileGitState } from './git-state-guard.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { getConfig } from '../config/config.js';
-import { groupThinkingArgs } from '../config/reasoning-args.js';
+import { groupChildArgs } from '../config/group-args.js';
+import { contextWindowForGroup } from './context-usage.js';
 import { makeDebugAppender } from './debug-log.js';
 import { startAutoLoader } from './widget.js';
 import { ChildStatus } from './child-status.js';
@@ -602,7 +603,11 @@ export function buildGateDeps(params) {
         streamInactivityMs: getConfig().streamInactivityMs,
         // Read per gateChild() call, like its two neighbours, so a
         // /task-config change lands on the next gate without a restart.
-        thinking: groupThinkingArgs('gate'),
+        groupArgs: groupChildArgs('gate'),
+        // `gateCtx` rather than the run's own window: a run spans several
+        // groups, and a window smaller than the child's real one makes the
+        // churn rule fire early and kill a healthy child.
+        contextWindow: contextWindowForGroup(gateCtx, 'gate'),
         status,
         runWorker,
         makeDebugAppender,

package/dist/task/implementation-guards.d.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/** `oneShot` mirrors the impl widget's split: fire-and-forget lets the settle
+ *  event disarm; an awaited run spans resume/steer turns and disarms in its finally. */
+export declare function armImplementationGuard(opts: {
+    oneShot: boolean;
+}): void;
+export declare function disarmImplementationGuard(): void;
+/** @internal Test seam: is a turn currently guarded? */
+export declare function implementationGuardArmed(): boolean;
+/**
+ * Present tense, unlike `formatLoopHint`, which addresses a re-spawned child
+ * about an attempt that does not exist here.
+ *
+ * It claims nothing about the call's RESULT, which this hook fires too early to
+ * see, and it does not offer "change the call" — that is an escape, not advice:
+ * one altered byte is a new key and a clean slate on both counters.
+ */
+export declare function blockedCallReason(toolName: string, count: number): string;
+/** The reason on the final block, which also ends the turn. */
+export declare function terminalCallReason(): string;
+export declare function consumeGuardTermination(): boolean;
+/**
+ * Inert until armed. Registering ANY `tool_call` handler switches on pi's
+ * `beforeToolCall` for every call in the session, so the armed check comes first.
+ */
+export declare function registerImplementationGuards(pi: ExtensionAPI): void;

package/dist/task/implementation-guards.js

@@ -0,0 +1,177 @@
+import { LoopDetector, loopKey, LOOP_THRESHOLD, LOOP_WINDOW, MAX_LOOP_RESTARTS } from './loop-detector.js';
+/**
+ * Runaway guard for the IMPLEMENTATION TURN — the one model surface with none.
+ *
+ * MEASURED: one turn ran 5h16m and 6,760 tool calls, alternating two
+ * byte-identical bash commands 3,300 times each with its output frozen and zero
+ * edits. The command watchdog is per call (each took ~2.5s), the stream was never
+ * silent, and MAX_COMPACTION_RESUMES counts only compactions that PARK at idle,
+ * while all 18 of these were inside the turn. The two detectors are built only in
+ * the CHILD spawn paths, and this turn runs in the user's own session.
+ *
+ * IT BLOCKS RATHER THAN KILLS because there is no re-spawn here — the argument
+ * single-read-extension.ts already makes: "detect-and-kill only re-spawns a model
+ * that deterministically re-thrashes". pi's ctx.abort() would also empty the
+ * queued-message list into the user's editor. That also raises the bar on false
+ * positives: a `gate` child killed by mistake costs one attempt of three, this
+ * costs the user their turn.
+ *
+ * WHY PROGRESS IS READ OFF THE CALL, NOT THE RESULT. The gate profile pairs its
+ * LoopDetector with a StallDetector, which judges results. That cannot work here:
+ * pi's edit tool returns the constant `Successfully replaced N block(s) in <path>.`
+ * and puts the diff in `details`, not `content`, so every real edit to one file is
+ * byte-identical result text and scores as dead ground. An edit's ARGUMENTS carry
+ * the progress its result throws away, so an edit is what resets the window.
+ *
+ * Known blind spots, all deliberate: a bash-driven mutation (`sed -i`, `>`,
+ * `git apply`) does not reset; one varying `write` per iteration buys unlimited
+ * immunity; a repeat cycle of LOOP_WINDOW/LOOP_THRESHOLD or longer never fills the
+ * window; polling a booting server with an identical curl trips at five; and
+ * schema-invalid calls never reach this hook at all, since pi validates first.
+ */
+/** Tool names that mutate the tree. pi ships exactly seven core tools, and
+ *  pi-task's own four (pi-worker, -search, -fetch, -docs) are all read-only. */
+const MUTATING_TOOLS = new Set(['edit', 'write']);
+/**
+ * Path-revisit is OFF for both detectors (that is the Infinity). MEASURED: at the
+ * default threshold, six DISTINCT edits to one file trip the path rule, because
+ * an edit names a `file_path` and no `limit`, so the first one sets the
+ * high-water mark and every later one scores as already-covered ground. Six edits
+ * to one file is the most ordinary thing an implementation turn does. mx5
+ * TASK_0002 is the same lesson from the other side: the rule killed an enforce
+ * child that was editing one file as its job.
+ */
+function freshDetector() {
+    return new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD, Number.POSITIVE_INFINITY);
+}
+/** The armed turn's state, or null outside one. One slot: one task runs at a time. */
+let armed = null;
+/** Built, never spread from the previous state: a leaked `terminating` would
+ *  block every call for the rest of an awaited run. */
+function freshArmedState(oneShot) {
+    return {
+        loop: freshDetector(),
+        edits: freshDetector(),
+        strikes: new Map(),
+        terminating: false,
+        oneShot
+    };
+}
+/** `oneShot` mirrors the impl widget's split: fire-and-forget lets the settle
+ *  event disarm; an awaited run spans resume/steer turns and disarms in its finally. */
+export function armImplementationGuard(opts) {
+    armed = freshArmedState(opts.oneShot);
+}
+export function disarmImplementationGuard() {
+    armed = null;
+}
+/** @internal Test seam: is a turn currently guarded? */
+export function implementationGuardArmed() {
+    return armed !== null;
+}
+/**
+ * Present tense, unlike `formatLoopHint`, which addresses a re-spawned child
+ * about an attempt that does not exist here.
+ *
+ * It claims nothing about the call's RESULT, which this hook fires too early to
+ * see, and it does not offer "change the call" — that is an escape, not advice:
+ * one altered byte is a new key and a clean slate on both counters.
+ */
+export function blockedCallReason(toolName, count) {
+    return (`Blocked: this is the ${count}th identical ${toolName} call in this turn. `
+        + `Use what you already have, or do something different, then continue the task.`);
+}
+/** The reason on the final block, which also ends the turn. */
+export function terminalCallReason() {
+    return (`Blocked: this turn repeated one call past every warning, so it is being stopped `
+        + `here. Nothing further will run.`);
+}
+/**
+ * One-shot: the guard ended a turn, and nothing in the session state says so.
+ *
+ * `terminate` lets the agent loop finish normally — the last assistant message
+ * keeps `stopReason: "toolUse"`, so `classifyTurnEnd` reads `'stop'` and the run
+ * reports a clean finish over work that was cut off mid-task. Verified against a
+ * live model: a real guard-terminated turn ends exactly that way. Same shape as
+ * `consumeWatchdogAbort`, and consumed for the same reason — one reader, then it
+ * is gone.
+ */
+let terminatedTurn = false;
+export function consumeGuardTermination() {
+    const hit = terminatedTurn;
+    terminatedTurn = false;
+    return hit;
+}
+/**
+ * Inert until armed. Registering ANY `tool_call` handler switches on pi's
+ * `beforeToolCall` for every call in the session, so the armed check comes first.
+ */
+export function registerImplementationGuards(pi) {
+    pi.on('tool_call', event => {
+        const state = armed;
+        if (!state)
+            return;
+        try {
+            // Every call, whatever it is: pi terminates only when EVERY finalized
+            // result in the batch carries the flag (agent-loop.js
+            // shouldTerminateToolBatch). The batch that trips it has already
+            // finalized its earlier calls without it and so survives; the next one
+            // ends. One batch, and it is the only bound this path has.
+            if (state.terminating) {
+                return { block: true, terminate: true, reason: terminalCallReason() };
+            }
+            const call = { name: event.toolName, args: event.input };
+            const mutating = MUTATING_TOOLS.has(event.toolName);
+            const hit = mutating ? state.edits.record(call) : state.loop.record(call);
+            if (!hit) {
+                if (mutating) {
+                    state.loop = freshDetector();
+                    // Strikes go with the window. Keeping them made a LATER episode
+                    // terminate on its first hit, skipping both warnings, because an
+                    // earlier one had part-spent the budget. MEASURED over 494 real
+                    // turns: this loses no catch — the incident still ends at call
+                    // 173 of 6,760, both live-model loops still end — and drops one
+                    // termination of a turn that was editing between episodes.
+                    // A determined model is still bounded: three hits inside ONE
+                    // episode terminate, which is the runaway shape (it makes no
+                    // edits at all).
+                    state.strikes.clear();
+                }
+                return;
+            }
+            const key = loopKey(call);
+            const strikes = (state.strikes.get(key) ?? 0) + 1;
+            state.strikes.set(key, strikes);
+            // Blocking alone does not stop a determined model: nothing prevents the
+            // next identical call.
+            if (strikes > MAX_LOOP_RESTARTS) {
+                state.terminating = true;
+                terminatedTurn = true;
+                return { block: true, terminate: true, reason: terminalCallReason() };
+            }
+            return { block: true, reason: blockedCallReason(event.toolName, hit.count) };
+        }
+        catch {
+            // pi does not guard this hook, and a throw here would block a
+            // legitimate call. A broken guard must cost nothing.
+            return;
+        }
+    });
+    // NOT `agent_end`, which fires again for every auto-retry, every threshold
+    // compaction and every queued message — pi drives those with `agent.continue()`,
+    // each a fresh agent loop. The measured runaway compacted 18 times INSIDE its
+    // turn, so a one-shot disarm on agent_end would have retired the guard after the
+    // first ~375 of its 6,760 calls. `agent_settled` is the boundary that means what
+    // this needs: no retry, compaction or queued continuation left to run.
+    pi.on('agent_settled', () => {
+        if (!armed)
+            return;
+        if (armed.oneShot)
+            disarmImplementationGuard();
+        // An awaited run spans resume and steer turns. Counters are per TURN, so a
+        // fresh one starts clean rather than inheriting the last one's strikes.
+        else
+            armed = freshArmedState(false);
+    });
+    pi.on('session_shutdown', disarmImplementationGuard);
+}

package/dist/task/implementation-hold.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Hold the host session on the `implementation` group's model AND thinking level
+ * for one implementation turn, then put both back.
+ *
+ * WHY THIS GROUP IS NOT LIKE THE OTHERS
+ * -------------------------------------
+ * Every other group runs in a child process, so its settings are two argv flags
+ * (`groupChildArgs` in config/group-args.ts) that die with the child. The
+ * implementation turn runs in the USER'S OWN session (orchestrator.ts `sendSpec`
+ * -> `sendUserMessage` -> `superviseImplementation`), so the only levers are
+ * `pi.setThinkingLevel` and `pi.setModel`, and both are session-global.
+ *
+ * WHAT pi DOES that this has to survive:
+ *
+ *  1. BOTH PERSIST. `setThinkingLevel` writes `defaultThinkingLevel` and
+ *     `setModel` writes `defaultProvider`/`defaultModel`, into pi's global
+ *     `~/.pi/agent/settings.json`. Without the restore, running one task would
+ *     silently rewrite the user's global defaults — and since children carry no
+ *     `-m` and resolve exactly those defaults, it would re-point every future
+ *     child in every project. That makes `release()` load-bearing, not tidy-up.
+ *  2. THEY CLAMP. A model with no reasoning support offers only `off`, so asking
+ *     for `medium` yields `off`. The restore writes back what was READ after
+ *     setting, never what was asked for, or a clamp would ratchet the stored
+ *     default further every run.
+ *  3. `setModel` RE-CLAMPS THINKING as part of switching. So the level must be
+ *     read before any model move, and written after the model is back.
+ *  4. THE USER CAN CHANGE EITHER MID-TURN — `shift+tab` cycles thinking. We
+ *     detect it by comparing the live value at release against what we applied:
+ *     if it has moved, somebody else moved it, and we leave it alone.
+ *
+ * We compare rather than subscribe because the extension API's `on(...)` returns
+ * `void` — there is no unsubscribe handle — so a per-turn listener could only
+ * ever be added, never removed.
+ *
+ * WHAT THIS COSTS, so nobody has to rediscover it
+ * -----------------------------------------------
+ * A model switch re-bills the whole prompt. pi counts that deliberately —
+ * `core/cache-stats.js` says "Model switches are NOT exempt: they re-bill the
+ * full prompt and should be counted" — and prints `Cache miss after model
+ * switch: N tokens re-billed` once the miss clears 20k tokens or $0.10, which an
+ * implementation prompt does. It happens twice: once acquiring, once releasing.
+ * On a local server that is a full prompt reprocess, not a bill. This is why the
+ * cell ships `inherit`, and why the target-equals-current degrade below is the
+ * main guard rather than an optimisation.
+ */
+import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
+import { type GroupSetting } from '../config/reasoning.js';
+import { type HoldStash } from './model-hold-stash.js';
+/**
+ * The slice of the extension API this needs, named so tests can drive the
+ * hold-and-restore with a fake object instead of a live pi session.
+ */
+export interface ThinkingControl {
+    get(): ThinkingLevel;
+    set(level: ThinkingLevel): void;
+}
+/**
+ * The model half, generic in the HANDLE so tests can use a literal.
+ *
+ * `current()` returns the spec AND the handle: the comparison is on a plain
+ * string, and the restore uses the handle captured at acquire rather than
+ * re-resolving against a registry that may have moved underneath us.
+ *
+ * `apply` may return `false` OR REJECT. pi's `setModel` returns false only when
+ * `hasConfiguredAuth` — a cached snapshot Set — is false; it then calls the
+ * session's own `setModel`, which awaits a live `checkAuth` and throws when the
+ * two disagree, as they do for an expired OAuth token. Callers here treat a
+ * throw and a `false` identically, because nothing useful differs between them.
+ */
+export interface ModelControl<H = unknown> {
+    current(): {
+        spec: string;
+        handle: H;
+    } | undefined;
+    resolve(spec: string): H | undefined;
+    apply(handle: H): Promise<boolean>;
+}
+export interface ImplementationControls<H = unknown> {
+    thinking: ThinkingControl;
+    model: ModelControl<H>;
+}
+/**
+ * The whole hold: model, then thinking. Returns the release, which is async and
+ * idempotent. Always call it from a `finally`, never the happy path.
+ *
+ * ONE function rather than two composable holds, because two independent holds
+ * acquired in the wrong order fail SILENTLY — `setModel` re-clamps thinking, so
+ * a thinking hold taken first is erased and a thinking restore taken last is
+ * clamped by the wrong model's ladder. A composition that can only be assembled
+ * one way belongs in one function.
+ */
+export declare function holdImplementation<H>(controls: ImplementationControls<H>, setting?: GroupSetting, spec?: string, stash?: HoldStash): Promise<() => Promise<void>>;
+/**
+ * Put back a model a crashed session left applied. Runs at `session_start`.
+ *
+ * THE GUARDS are the whole design, because this runs in a session that knows
+ * nothing about the one that crashed. Four cases, and only the last writes:
+ *
+ *  1. pi's saved default is still the note's `before` — the file is already
+ *     right. Either a live hold has written its note but not yet switched, or a
+ *     crash landed in that same gap. Decline, and KEEP the note: clearing here
+ *     is what would let an unrelated session start delete a live hold's only
+ *     crash record, in the millisecond before it applies.
+ *  2. the saved default is neither value — somebody moved on. Clear, decline.
+ *  3. the saved default matches, but THIS session is on a different model — it
+ *     was launched with an explicit `--model`, or resumed onto one. Restoring
+ *     would silently override a choice made on the command line. Decline, and
+ *     keep the note so a later ordinary start still repairs the file.
+ *  4. everything agrees. Restore, and clear.
+ *
+ * The note is also cleared on a failed restore: one that cannot happen must not
+ * re-fire on every subsequent startup.
+ *
+ * Thinking is deliberately NOT restored here. `setModel` re-clamps it to the
+ * model we are restoring TO, which is the level that model was running at
+ * before the crashed session touched anything.
+ */
+export declare function restoreHeldModel<H>(model: ModelControl<H>, savedDefaultSpec: () => string | undefined, stash?: HoldStash): Promise<'restored' | 'declined' | 'nothing'>;

package/dist/task/implementation-hold.js

@@ -0,0 +1,165 @@
+import { getConfig } from '../config/config.js';
+import { MODEL_INHERIT } from '../config/group-models.js';
+import { resolveReasoning } from '../config/reasoning.js';
+import { readHoldStash, writeHoldStash, clearHoldStash } from './model-hold-stash.js';
+/**
+ * `before` is the level read BEFORE any model move; `applied` is what is really
+ * in force after both moves.
+ *
+ * `inherit` writes nothing but still RECORDS, because the model switch may have
+ * moved the level on its own. `applied === before` means nothing moved, and then
+ * there is nothing to restore — a write there would be a settings.json write for
+ * no reason.
+ */
+function acquireThinking(control, setting, before) {
+    if (setting !== 'inherit')
+        control.set(setting);
+    // Post-clamp, so a model that cannot do `medium` does not leave us believing
+    // it is at `medium` and treating the user's later change as our own.
+    const applied = control.get();
+    return applied === before ? undefined : { before, applied };
+}
+const userMovedThinking = (control, hold) => control.get() !== hold.applied;
+/**
+ * The whole hold: model, then thinking. Returns the release, which is async and
+ * idempotent. Always call it from a `finally`, never the happy path.
+ *
+ * ONE function rather than two composable holds, because two independent holds
+ * acquired in the wrong order fail SILENTLY — `setModel` re-clamps thinking, so
+ * a thinking hold taken first is erased and a thinking restore taken last is
+ * clamped by the wrong model's ladder. A composition that can only be assembled
+ * one way belongs in one function.
+ */
+export async function holdImplementation(controls, setting = resolveReasoning('implementation', getConfig()), spec = getConfig().groupModels.implementation, stash = { read: readHoldStash, write: writeHoldStash, clear: clearHoldStash }) {
+    const { thinking, model } = controls;
+    // BEFORE any model move: `setModel` re-clamps, so this is the only moment
+    // the pre-hold level is readable.
+    const beforeThinking = thinking.get();
+    const modelHold = await acquireModel(model, spec, stash);
+    // A model move that was ASKED FOR and failed no-ops the whole hold. Running
+    // the implementation turn on the wrong model at the right level is worse
+    // than running it exactly as it ran last week.
+    if (modelHold === 'failed')
+        return async () => { };
+    // A MODEL move alone moves the level, even with the thinking cell on
+    // `inherit`: pi's `setModel` re-clamps to the target's ladder and PERSISTS
+    // the result. So the thinking hold is taken whenever either half moved
+    // something, not only when a level was asked for — otherwise a session at
+    // `high` switched onto an off/medium model is left globally at `medium`
+    // with nothing to put it back, which is the one thing release() exists for.
+    const thinkingHold = setting === 'inherit' && modelHold === undefined ?
+        undefined
+        : acquireThinking(thinking, setting, beforeThinking);
+    let released = false;
+    return async () => {
+        if (released)
+            return;
+        released = true;
+        // Read the thinking comparison BEFORE restoring the model. A read taken
+        // after it is post-clamp, and the mid-turn-change detector then answers
+        // wrongly in both directions.
+        const moved = thinkingHold !== undefined && userMovedThinking(thinking, thinkingHold);
+        if (modelHold !== undefined) {
+            try {
+                await model.apply(modelHold.before);
+            }
+            catch {
+                // A failed model restore is still followed by the thinking
+                // restore. Restoring what we can beats restoring nothing.
+            }
+            stash.clear();
+        }
+        // LAST. Writing `before` while still on the target model has pi clamp it
+        // to the TARGET's ladder, and the model restore then re-clamps from that
+        // already-wrong value.
+        if (thinkingHold !== undefined && !moved)
+            thinking.set(thinkingHold.before);
+    };
+}
+/**
+ * `undefined` = no move was needed or possible, and today's behaviour stands.
+ * `'failed'` = a move was asked for and did not happen, which voids the hold.
+ */
+async function acquireModel(model, spec, stash) {
+    if (spec === MODEL_INHERIT)
+        return undefined;
+    const cur = model.current();
+    if (!cur)
+        return undefined;
+    // Not an optimisation. `setDefaultModelAndProvider` runs unconditionally
+    // inside pi's `setModel`, so a redundant call rewrites the user's global
+    // default, appends a model change to their session and re-bills the whole
+    // prompt as a cache miss — all to arrive where we already were.
+    if (cur.spec === spec)
+        return undefined;
+    const handle = model.resolve(spec);
+    // Model gone, or its provider unauthed. The session hint names it; the turn
+    // runs where it already was.
+    if (handle === undefined)
+        return undefined;
+    // Written BEFORE the apply, so a crash between the two costs an unnecessary
+    // restore attempt rather than a missed one.
+    stash.write({ before: cur.spec, applied: spec });
+    try {
+        if (await model.apply(handle))
+            return { before: cur.handle, beforeSpec: cur.spec, appliedSpec: spec };
+    }
+    catch {
+        // Identical to `false`: see ModelControl.apply.
+    }
+    stash.clear();
+    return 'failed';
+}
+/**
+ * Put back a model a crashed session left applied. Runs at `session_start`.
+ *
+ * THE GUARDS are the whole design, because this runs in a session that knows
+ * nothing about the one that crashed. Four cases, and only the last writes:
+ *
+ *  1. pi's saved default is still the note's `before` — the file is already
+ *     right. Either a live hold has written its note but not yet switched, or a
+ *     crash landed in that same gap. Decline, and KEEP the note: clearing here
+ *     is what would let an unrelated session start delete a live hold's only
+ *     crash record, in the millisecond before it applies.
+ *  2. the saved default is neither value — somebody moved on. Clear, decline.
+ *  3. the saved default matches, but THIS session is on a different model — it
+ *     was launched with an explicit `--model`, or resumed onto one. Restoring
+ *     would silently override a choice made on the command line. Decline, and
+ *     keep the note so a later ordinary start still repairs the file.
+ *  4. everything agrees. Restore, and clear.
+ *
+ * The note is also cleared on a failed restore: one that cannot happen must not
+ * re-fire on every subsequent startup.
+ *
+ * Thinking is deliberately NOT restored here. `setModel` re-clamps it to the
+ * model we are restoring TO, which is the level that model was running at
+ * before the crashed session touched anything.
+ */
+export async function restoreHeldModel(model, savedDefaultSpec, stash = { read: readHoldStash, write: writeHoldStash, clear: clearHoldStash }) {
+    const note = stash.read();
+    if (!note)
+        return 'nothing';
+    const saved = savedDefaultSpec();
+    if (saved === note.before)
+        return 'declined';
+    if (saved !== note.applied) {
+        stash.clear();
+        return 'declined';
+    }
+    if (model.current()?.spec !== note.applied)
+        return 'declined';
+    const handle = model.resolve(note.before);
+    if (handle === undefined) {
+        stash.clear();
+        return 'declined';
+    }
+    try {
+        return (await model.apply(handle)) ? 'restored' : 'declined';
+    }
+    catch {
+        return 'declined';
+    }
+    finally {
+        stash.clear();
+    }
+}

package/dist/task/implementation-turn.d.ts

@@ -96,6 +96,8 @@ export interface SteerWatchdogDeps {
 export interface ImplementationTurnDeps {
     /** The live session entries — the only thing the classifier reads. */
     entries: () => ReadonlyArray<SessionEntryLike>;
+    /** Test seam over the module-level one-shot; the real reader is the default. */
+    consumeGuardTermination?: () => boolean;
     /** Queue a follow-up user turn on the (idle) session. */
     send: (text: string) => Promise<void>;
     /** Wait for the session to go idle again. */
@@ -139,6 +141,9 @@ export declare const CONTINUE_AFTER_COMPACTION: string;
  * lets the verify gate and `/task-auto-resume` catch any leftover incompleteness.
  */
 export declare const MAX_COMPACTION_RESUMES = 20;
+/** How a guard-stopped turn is reported. Named so a caller can tell it from a
+ *  provider error: the fix is a different task, not a retry of this one. */
+export declare const GUARD_TERMINATED = "the runaway guard stopped this turn: one tool call was repeated past every warning";
 /**
  * Resume an implementation turn that went idle at a threshold-compaction boundary.
  * The runtime compacts and parks at idle without auto-continuing; we send a

package/dist/task/implementation-turn.js

@@ -17,6 +17,7 @@
  */
 import { SessionUI } from '../remote/bridge.js';
 import { consumeWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js';
+import { consumeGuardTermination } from './implementation-guards.js';
 const isAssistant = (e) => e.message !== undefined && e.message.role === 'assistant';
 /** Index of the last assistant message and of the last compaction boundary. */
 function tailPositions(entries) {
@@ -160,6 +161,9 @@ export const CONTINUE_AFTER_COMPACTION = 'Your context was automatically compact
  * lets the verify gate and `/task-auto-resume` catch any leftover incompleteness.
  */
 export const MAX_COMPACTION_RESUMES = 20;
+/** How a guard-stopped turn is reported. Named so a caller can tell it from a
+ *  provider error: the fix is a different task, not a retry of this one. */
+export const GUARD_TERMINATED = 'the runaway guard stopped this turn: one tool call was repeated past every warning';
 /**
  * Resume an implementation turn that went idle at a threshold-compaction boundary.
  * The runtime compacts and parks at idle without auto-continuing; we send a
@@ -260,6 +264,13 @@ export async function superviseWith(deps) {
     const interrupted = await steerUntilDone(deps);
     // A user-declined steer (interrupted) is its own paused path; otherwise
     // inspect how the turn actually ended.
-    const error = interrupted ? undefined : turnErrorMessage(deps.entries());
+    // The runaway guard ends a turn WITHOUT an error stopReason, so classifyTurnEnd
+    // reads `'stop'` and the caller would verify a half-done implementation and
+    // re-deliver to a model that deterministically re-thrashes. Consumed here
+    // because this is the one place that reports how the turn really ended.
+    const guardEnded = deps.consumeGuardTermination?.() ?? consumeGuardTermination();
+    const error = interrupted ? undefined
+        : guardEnded ? GUARD_TERMINATED
+            : turnErrorMessage(deps.entries());
     return { interrupted, error, resumes };
 }