agent-nuvira 3.3.10 → 3.3.12

package/dist/tools/tool-loop.js

@@ -33,15 +33,24 @@ import { stepDigest } from '../learning/step-checkpoint.js';
 // process declared no fault (`NUVIRA_INJECT_FAULT`), so an ordinary turn is
 // unaffected.
 import { faultAt } from '../runtime/fault-injection.js';
-import { detectPermissionSeeking, isAffirmativeReply, replyAsksTheReader, requestAuthorizesWrites, stripTrailingPermissionSeek, } from '../learning/autonomy-policy.js';
+import { detectPermissionSeeking, isAffirmativeReply, replyAsksTheReader, requestAuthorizesWrites, requestForbidsWrites, stripTrailingPermissionSeek, } from '../learning/autonomy-policy.js';
 import { envelopeFromPlan, envelopeFromRequest, getEnvelope, grantEnvelope, isEnvelopeKey, } from '../learning/intent-envelope.js';
-import { detectProcessComplaint, isTraceKey, repeatNudge, runTraceFor, RunTrace, } from '../learning/run-trace.js';
+import { detectProcessComplaint, isTraceKey, noProgressNudge, repeatNudge, repeatedFailureNudge, runTraceFor, RunTrace, } from '../learning/run-trace.js';
 import { wantsAuthoredArtifact } from '../learning/deliverable-class.js';
 import { normalizeFollowups } from './followup-utils.js';
+// The capability mode (balanced | max) — `max` widens the loop's own reasoning
+// budget as well as routing, so "cost is not a concern" means the agent may
+// keep working through a long build instead of stopping at the default bound.
+import { isMaxCapability } from '../config/capability-mode.js';
+// The digest's scope (all | max | off) — a user-facing control over whether the
+// compaction digest is injected in every mode, only under `max`, or never.
+import { isWorkDigestEnabled } from '../config/work-digest.js';
 import { assessEditActivity, detectUnverifiedEditClaim, isVerificationTool, verificationNudgeFor, THINK_ONLY_ESCALATION, AUTHORIZED_WORK_NUDGE, deliverableNudge, } from './edit-verification.js';
 import { effectiveToolJsonSchemas, coreToolJsonSchemas, isToolEnabled, toolsetForTool } from './toolsets.js';
 import { deliverablesNamedIn, recordStepHandoff } from '../agents/step-handoff.js';
 import { fenceUntrustedToolOutput } from './untrusted-content.js';
+import { installableToolsFromFailure, resolveInstallCommand, toolTakeoverInstruction, } from '../cli/tool-install-prompt.js';
+import { matchPrerequisiteSignatures, prerequisiteTakeoverInstruction, checkProjectPrerequisites, createNodePrereqFs, formatPreflightFindings, } from '../learning/build-prerequisites.js';
 /**
  * Tools that MUTATE the workspace. A refusal of one of these is the only
  * refusal that leaves work undone — a declined `read_file` costs a step, a
@@ -54,12 +63,41 @@ const MUTATING_TOOL_NAMES = new Set([
     'run_terminal',
     'run_cli',
 ]);
+/**
+ * The subset of mutating tools the PLAN gate HARD-BLOCKS on the first call —
+ * the ones that change the workspace's FILES. `run_terminal` / `run_cli` are
+ * deliberately excluded from the BLOCK (they still trigger the nudge): a
+ * terminal command is as often a test, a build or an inspection as it is an
+ * edit, and refusing it outright would stop the very step a plan is meant to
+ * reach. The nudge still tells the model to plan first.
+ */
+const PLAN_GATED_TOOL_NAMES = new Set([
+    'write_file',
+    'edit_file',
+    'propose_change',
+]);
 /** The path a mutating call was aimed at, when it named one. */
 function mutatedPathOf(args) {
     const a = args;
     const p = a?.path ?? a?.file_path ?? a?.file;
     return typeof p === 'string' && p.trim() ? p.trim() : undefined;
 }
+/**
+ * The ACTION signature of a failed call — what it tried to do, so the identical
+ * retry is recognizable. Prefers the shell `command`, then the file `path`,
+ * then the tool name (a call that named neither still repeats as the same tool).
+ * Used by the self-diagnosis gate (see RunTrace.repeatedFailure).
+ */
+function failureActionOf(call) {
+    const a = call.arguments;
+    const command = typeof a?.command === 'string' && a.command.trim() ? a.command.trim() : undefined;
+    if (command)
+        return command;
+    const path = mutatedPathOf(call.arguments);
+    if (path)
+        return path;
+    return call.name;
+}
 /**
  * Append what a tool call actually did to the turn's provenance ledger.
  *
@@ -396,10 +434,47 @@ const MAX_PARALLEL_READS = 4;
  * were well able to do (see `THINK_ONLY_ESCALATION`).
  */
 export const MAX_THINK_CONTINUES = 3;
+/**
+ * Consecutive steps that RAN tools and had NO success before the loop asks the
+ * model to diagnose the stall. This generalises {@link RunTrace.repeatedFailure}
+ * (the identical action retried): a weak model also loops by substituting a
+ * different command each step, every one failing the same underlying way — none
+ * of them repeats exactly, so the same-action gate never fires.
+ *
+ * The threshold is deliberately ABOVE the handful of distinct checks ordinary
+ * iteration tries (`npm test` → `npm run build` → `npm run lint`), so a short run
+ * of unrelated failures is left alone; only a sustained all-fail streak is a stall.
+ */
+export const NO_PROGRESS_STALL_STEPS = 4;
+/**
+ * How substantial a turn must be before the SELF-REVIEW gate may fire (see
+ * `selfReviewNudge`). Short, single-edit turns already end with an obvious
+ * result the model just looked at; a long turn is where scope drift hides, and
+ * where an extra pass earns its latency.
+ */
+export const SELF_REVIEW_MIN_STEPS = 6;
+/**
+ * S5 — how many `plan_todo` UPDATE calls one turn may make. The guard refuses
+ * repeated CREATES (the observed planner loop) but must allow updates, because
+ * an update is how the user's checklist advances; this cap only stops a model
+ * that replaces doing the work with spamming status changes. It sits well above
+ * a genuine multi-step job (the largest real plans in the tree are single
+ * digits) and far below a loop.
+ */
+export const PLAN_TODO_UPDATE_CAP = 64;
 /** Default continuations granted per turn when the option is omitted. */
 export const DEFAULT_MAX_CONTINUATIONS = 2;
 /** Default extra steps granted per continuation. */
 export const DEFAULT_CONTINUATION_STEPS = 8;
+/**
+ * `max` capability mode — the loop's longest bounded reasoning budget. The
+ * defaults above are sized to keep an ordinary turn responsive; under `max` the
+ * user has said cost is not a concern, so the same session is allowed to run a
+ * long build / many-file edit to completion instead of stopping at the default
+ * bound. Still finite: the hard cap is `maxSteps + 4 * 16` extra steps.
+ */
+export const MAX_CAPABILITY_MAX_CONTINUATIONS = 4;
+export const MAX_CAPABILITY_CONTINUATION_STEPS = 16;
 /** Pause before re-attempting a failed step (lets a transient outage clear). */
 export const CONTINUATION_DELAY_MS = 1_500;
 /**
@@ -425,8 +500,12 @@ function sleep(ms) {
 async function runToolLoopInner(opts, progress) {
     const { messages, tools: toolNames, maxSteps = 16, context, deps } = opts;
     // Bounded auto-continuation state (see ToolLoopOptions.maxContinuations).
-    const maxContinuations = Math.max(0, opts.maxContinuations ?? DEFAULT_MAX_CONTINUATIONS);
-    const continuationSteps = Math.max(1, opts.continuationSteps ?? DEFAULT_CONTINUATION_STEPS);
+    // `max` capability mode raises the DEFAULT budget (an explicit option still
+    // wins, so callers that pin a bound keep it). Read once per turn from the
+    // config, exactly like routing, so a mode change applies to the next turn.
+    const maxCapability = isMaxCapability(context.configManager);
+    const maxContinuations = Math.max(0, opts.maxContinuations ?? (maxCapability ? MAX_CAPABILITY_MAX_CONTINUATIONS : DEFAULT_MAX_CONTINUATIONS));
+    const continuationSteps = Math.max(1, opts.continuationSteps ?? (maxCapability ? MAX_CAPABILITY_CONTINUATION_STEPS : DEFAULT_CONTINUATION_STEPS));
     let continuations = 0;
     // Bounded dangling-promise nudges spent this turn (see INTENT_PROMISE_RE).
     let intentNudges = 0;
@@ -440,12 +519,26 @@ async function runToolLoopInner(opts, progress) {
     // asks the model to PROCEED, this one asks it to stop REPEATING, and the two
     // fire on independent evidence.
     let repeatNudges = 0;
+    // The loop's SELF-DIAGNOSIS nudge: bounded once per turn, fired when the SAME
+    // action has failed more than once (see RunTrace.repeatedFailure). This is the
+    // capability that turns "retry the identical failing command 10 times" into
+    // "state the root cause and change the approach" — the live macOS-build turn
+    // re-issued `npx tauri build` again and again against the same missing Cargo.
+    let diagnosisNudges = 0;
+    // Stage 2 — consecutive tool-running steps with NO success (the generalized
+    // stall signal, see NO_PROGRESS_STALL_STEPS). Reset by any successful tool.
+    let failedToolSteps = 0;
+    // Stage 4 — bounded SELF-REVIEW nudge (see requireSelfReview / selfReviewNudge).
+    let selfReviewNudges = 0;
     // Bounded think-only continuation (see THINK_ONLY_ESCALATION). Counts the
     // consecutive reasoning-only steps so the loop cannot spin on them.
     let thinkContinues = 0;
     // G13b — bounded "the request asked for a file and none was written" nudges
     // (see wantsAuthoredArtifact).
     let deliverableNudges = 0;
+    // ZERO-ACTION — bounded "the request directed work and NOTHING was done"
+    // nudges (see requireAction / zeroActionGateApplies).
+    let actionNudges = 0;
     /**
      * G18 — the sink, wrapped so an observability failure can never become a
      * turn failure (a recorder that throws is a bug in the instrument, not in
@@ -468,6 +561,12 @@ async function runToolLoopInner(opts, progress) {
     const maxParallelReads = Math.max(1, opts.maxParallelReads ?? MAX_PARALLEL_READS);
     const followups = [];
     const toolCallsRun = [];
+    // S5 — the plan_todo loop guard is split by ACTION (see the guard below):
+    // repeated CREATES were the observed planner loop; UPDATES are the tracking
+    // that keeps the user's checklist honest. Counted across the whole turn, like
+    // `toolCallsRun`, because a multi-step job runs many steps in one turn.
+    let planTodoCreates = 0;
+    let planTodoUpdates = 0;
     // Every collected suggestion passes through the shared normalizer, so the
     // loop's output is ALWAYS clean + structured (1–3 items, deduped, no leaked
     // tool JSON, capped prompt/label) regardless of what the model emitted —
@@ -646,6 +745,39 @@ async function runToolLoopInner(opts, progress) {
     // with an empty/bounded response (the "where is the essay?" bug).
     let lastContent = '';
     let bounded = false;
+    // D2.2 — has this turn already pre-flighted the project's build prerequisites?
+    // Checked once, before the FIRST build command the turn plans to run.
+    let prerequisitesPreflighted = false;
+    // E2 — has this turn already spent its one bounded "declare a plan first"
+    // nudge? Bounded once, like every other gate.
+    let planNudged = false;
+    // E2 (hard) — has this turn already spent its one bounded BLOCK of the first
+    // mutation? The plan gate is a hard requirement the first time it fires and a
+    // pure nudge after that: the first mutating batch is refused (see the gate
+    // below), and the second attempt runs even without a plan — a bounded block,
+    // never a wall.
+    let planBlocked = false;
+    /**
+     * Should the SELF-REVIEW gate fire now? Returns the correction to inject, or
+     * null. Extracted so the two end-of-turn exits ask the question identically —
+     * nothing here is a function of which branch is ending.
+     */
+    const selfReviewCorrection = () => {
+        if (selfReviewNudges >= 1)
+            return null;
+        if (opts.requireSelfReview === false)
+            return null;
+        if (steps < SELF_REVIEW_MIN_STEPS)
+            return null;
+        if (progress.mutatedPaths.length === 0)
+            return null;
+        // The verification gate owns "did you check it"; self-review only runs once
+        // that question is settled, so the two can never both fire in one turn.
+        const activity = assessEditActivity(progress.successfulToolCalls, progress.verificationEvidence, progress.mutatedPaths);
+        if (activity.needsVerification)
+            return null;
+        return selfReviewNudge(currentAsk(opts));
+    };
     for (;;) {
         // ── Bounded auto-continuation on the STEP BOUND ────────────────────────
         // The model still wanted to act when the budget ran out (a long build, a
@@ -675,6 +807,19 @@ async function runToolLoopInner(opts, progress) {
             if (trimmedResult.trimmed > 0) {
                 thread.length = 0;
                 thread.push(...trimmedResult.thread);
+                // Keep a memory of what the turn DID after its raw outputs are gone:
+                // without this, a long turn loses the VERDICTS (did the build pass?) and
+                // re-runs work it already finished. Deterministic and bounded — the same
+                // philosophy as trimThreadBudget itself (facts, no summarizer, no drift).
+                if (isWorkDigestEnabled(context.configManager)) {
+                    const digest = buildWorkDigest({
+                        successfulTools: progress.successfulToolCalls,
+                        mutatedPaths: progress.mutatedPaths,
+                        executedActions: progress.executedActions,
+                    });
+                    if (digest)
+                        upsertWorkDigest(thread, digest);
+                }
                 deps.onEvent?.(`   ✂️ ${trimmedResult.trimmed} old tool result(s) trimmed to fit the ${Math.round(budgetChars / 1000)}K-char context budget.`);
             }
         }
@@ -999,6 +1144,32 @@ async function runToolLoopInner(opts, progress) {
                 thread.push({ role: 'user', content: repeatNudge(closing, runTrace.priorAnswer(closing)) });
                 continue;
             }
+            // ── ZERO-ACTION gate (bounded, once) ────────────────────────────────
+            // The request DIRECTED work on the workspace and the turn is ending
+            // without having run a single tool: not a dropped promise, not a
+            // permission question, not an authored file — just prose where the work
+            // should be. The gates above all key on a positive shape in the reply and
+            // so miss a plain non-answer; this one keys on the REQUEST and the
+            // ABSENCE of action, which is exactly the shape that ended a fully
+            // specified four-part coding ask with nothing done. Bounded once; the
+            // residual is reported by `noActionTaken` below, whether or not the nudge
+            // is enabled.
+            if (actionNudges < 1 &&
+                zeroActionGateApplies(opts, progress, schemas.length, requestText, authorization.authorized)) {
+                actionNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.('   🛠️ The request asked for work and nothing was done — telling the model to do it now.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'action',
+                    summary: 'the request directed work on the workspace and the turn performed none — one bounded nudge to carry it out',
+                });
+                // The non-answer must not become the delivered answer either way.
+                lastContent = '';
+                thread.push({ role: 'assistant', content: response.content });
+                thread.push({ role: 'user', content: zeroActionNudge(currentAsk(opts)) });
+                continue;
+            }
             // S1 (both exits): the MOST SUBSTANTIVE content seen wins here too —
             // a short closing step ("Sent it to her! ✅") with no tool calls must
             // not clobber the deliverable (poem/essay) the model composed in an
@@ -1055,6 +1226,22 @@ async function runToolLoopInner(opts, progress) {
                 });
                 continue;
             }
+            // SELF-REVIEW (no-tools exit) — a substantial, already-verified turn is
+            // ending; spend ONE bounded pass to check the result against the ask.
+            const review = selfReviewCorrection();
+            if (review) {
+                selfReviewNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.('   🧭 Substantial turn ending — asking the model to review the result against the original ask.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'self-review',
+                    summary: 'a substantial turn that changed files reached its end — one bounded nudge to check the result against the original ask',
+                });
+                thread.push({ role: 'assistant', content: response.content });
+                thread.push({ role: 'user', content: review });
+                continue;
+            }
             return {
                 content: response.content.length >= lastContent.length ? response.content : lastContent,
                 followups,
@@ -1085,14 +1272,47 @@ async function runToolLoopInner(opts, progress) {
             const tool = getTool(call.name);
             const priorSameTool = toolCallsRun.filter((t) => t === call.name).length;
             toolCallsRun.push(call.name);
-            // S5 — PLANNER LOOP GUARD: allow the first plan of the turn, refuse
-            // repeats (the 6x planner loop observed in
-            // trace-1788059239352-k7zl03: 15.6K tokens, 2m25s, FAILED).
-            if (call.name === 'plan_todo' && priorSameTool >= 1) {
-                return {
-                    call,
-                    refuse: 'Error: plan_todo already called. You have a plan — now execute it. Do NOT call plan_todo again. Use write_file, run_terminal, or other execution tools to complete the work.',
-                };
+            // S5 — PLANNER LOOP GUARD, now split by ACTION.
+            //
+            // The guard exists because of a real failure: the model called plan_todo
+            // six times in one turn (trace-1788059239352-k7zl03 — 15.6K tokens,
+            // 2m25s, FAILED) instead of doing the work. But `create` and `update` are
+            // the SAME tool, and the original `priorSameTool >= 1` check refused BOTH
+            // — so a plan could be declared once and then never advanced, and the
+            // checklist the user watches went stale the moment the first step closed.
+            // Only repeated CREATES are the loop; updates ARE the tracking. Anything
+            // that is not an explicit update (absent/malformed action) is counted as
+            // a create, so the original protection is unchanged for the loop case.
+            if (call.name === 'plan_todo') {
+                const action = (() => {
+                    try {
+                        const raw = call.arguments;
+                        const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                        return obj && typeof obj === 'object'
+                            ? String(obj.action ?? '')
+                            : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                })();
+                const isUpdate = action === 'update';
+                if (!isUpdate && planTodoCreates >= 1) {
+                    return {
+                        call,
+                        refuse: 'Error: a plan already exists for this turn — do NOT declare it again. Advance it instead: call plan_todo with action "update", the step id and its status, then keep doing the work.',
+                    };
+                }
+                if (isUpdate && planTodoUpdates >= PLAN_TODO_UPDATE_CAP) {
+                    return {
+                        call,
+                        refuse: `Error: plan_todo has been updated ${PLAN_TODO_UPDATE_CAP} times this turn — stop updating the plan and finish the remaining work.`,
+                    };
+                }
+                if (isUpdate)
+                    planTodoUpdates += 1;
+                else
+                    planTodoCreates += 1;
             }
             if (tool?.category === 'pipeline' && priorSameTool >= 1) {
                 // The guard this replaces tested the literal name `pipeline`, which is
@@ -1286,6 +1506,118 @@ async function runToolLoopInner(opts, progress) {
                 toolSpan?.end({ ok: false, message: 'tool outcome was never reported' });
             }
         };
+        // ── PROJECT PREREQUISITE PRE-FLIGHT (D2.2) ──────────────────────────
+        // Before the FIRST build of the turn, check the project's markers so a
+        // missing prerequisite (build.rs, a Cargo feature, an icon) is handed over
+        // BEFORE a failed build — not after ten identical retries. Best-effort and
+        // bounded: once per turn, only when a build is actually planned.
+        if (!prerequisitesPreflighted) {
+            const buildPlan = plans.find((p) => {
+                if (p.refuse !== undefined)
+                    return false;
+                if (p.call.name !== 'run_terminal' && p.call.name !== 'terminal')
+                    return false;
+                try {
+                    const raw = p.call.arguments;
+                    const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                    const cmd = String(obj?.command ?? '');
+                    return isBuildCommand(cmd);
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (buildPlan) {
+                prerequisitesPreflighted = true;
+                try {
+                    const findings = checkProjectPrerequisites(createNodePrereqFs(opts.context?.cwd || process.cwd()));
+                    if (findings.length > 0) {
+                        thread.push({ role: 'user', content: formatPreflightFindings(findings) });
+                        deps.onEvent?.(`   🧱 pre-flight: ${findings.length} missing project prerequisite(s) — handed the exact fix before building.`);
+                        traceEvent({
+                            kind: 'gate',
+                            gate: 'prerequisite',
+                            summary: `pre-flight found ${findings.length} missing project prerequisite(s) before the build: ` +
+                                findings.map((f) => f.id).join(', '),
+                        });
+                    }
+                }
+                catch {
+                    // A pre-flight must never break the turn.
+                }
+            }
+        }
+        // ── PLAN GATE (E2) ──────────────────────────────────────────────────
+        // A workspace-directing turn about to MUTATE without having declared a plan
+        // is stopped ONCE: its first FILE mutation is refused and the model is told
+        // to plan first (`plan_todo`). Terminal commands still trigger the nudge but
+        // are not blocked (see PLAN_GATED_TOOL_NAMES) — a build or a test is a step
+        // a plan is meant to reach, not a change to gate. Bounded by design: the
+        // SECOND attempt runs even without a plan (see `planBlocked`), so this guides
+        // the model into the plan → track → verify contract instead of walling the
+        // turn off. A batch that DECLARES a plan itself is never blocked (the model
+        // is already doing the right thing), and `requirePlan:false` leaves the gate
+        // byte-identical to not existing.
+        const declaresPlan = !opts.context?.planStore?.snapshot?.() && plans.some((p) => {
+            if (p.call.name !== 'plan_todo')
+                return false;
+            try {
+                const raw = p.call.arguments;
+                const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                const action = obj && typeof obj === 'object' ? String(obj.action ?? '') : '';
+                return action !== 'update';
+            }
+            catch {
+                // Malformed args still count as a create attempt — the plan_todo guard
+                // above already handles a repeated create, and a first one is honored.
+                return true;
+            }
+        });
+        if (!planNudged &&
+            !declaresPlan &&
+            opts.requirePlan !== false &&
+            schemas.length > 0 &&
+            !opts.context?.planStore?.snapshot?.() &&
+            plans.some((p) => p.refuse === undefined && MUTATING_TOOL_NAMES.has(p.call.name)) &&
+            requestRequiresWorkspaceAction(requestText, authorization.authorized)) {
+            planNudged = true;
+            // Hard requirement, spent ONCE: refuse the first batch's FILE mutations
+            // so nothing is written before a plan exists. It bumps the step budget by
+            // one because it forces a genuine re-answer (the model must declare the
+            // plan and retry), exactly like the zero-action nudge.
+            const blocked = [];
+            if (!planBlocked) {
+                planBlocked = true;
+                for (const p of plans) {
+                    if (p.refuse === undefined && PLAN_GATED_TOOL_NAMES.has(p.call.name)) {
+                        p.refuse =
+                            'Error: declare a plan first via plan_todo — call it with 2–6 ordered steps (action "create"), then retry this change. The plan is how the turn is tracked and verified.';
+                        blocked.push(p.call.name);
+                    }
+                }
+                if (blocked.length > 0)
+                    stepLimit += 1;
+                for (const name of blocked) {
+                    traceEvent({
+                        kind: 'refusal',
+                        gate: 'plan',
+                        tool: name,
+                        summary: `refused ${name}: no plan declared — the first mutation is blocked once so the model plans before it changes files`,
+                    });
+                }
+            }
+            deps.onEvent?.(blocked.length > 0
+                ? '   🗺️ No plan declared — blocking the first change until the model plans.'
+                : '   🗺️ No plan declared — asking the model to plan before it changes files.');
+            traceEvent({
+                kind: 'gate',
+                gate: 'plan',
+                summary: blocked.length > 0
+                    ? `a workspace-directing turn was about to mutate without a plan — the first mutation batch (${blocked.join(', ')}) was refused once and the model asked to declare a plan first`
+                    : 'a workspace-directing turn was about to mutate without a plan — one bounded nudge to declare one first',
+            });
+            thread.push({ role: 'user', content: planRequiredNudge(currentAsk(opts)) });
+        }
         const executed = new Array(plans.length).fill('');
         for (let i = 0; i < plans.length;) {
             // A run of consecutive read-only calls is ONE bounded fan-out; any
@@ -1323,6 +1655,7 @@ async function runToolLoopInner(opts, progress) {
         // What each call actually delivered (post hint/tip decoration), kept in
         // call order for the endsAgentStep exit below.
         const delivered = new Array(plans.length).fill('');
+        let stepAnySuccess = false;
         for (let i = 0; i < plans.length; i += 1) {
             const call = plans[i].call;
             const rawResult = executed[i];
@@ -1342,8 +1675,10 @@ async function runToolLoopInner(opts, progress) {
             const ranOk = refusal === null &&
                 !rawResult.startsWith('Error:') &&
                 (!DELIVERY_TOOL_NAMES.has(call.name) || deliveryResultSucceeded(rawResult));
-            if (ranOk)
+            if (ranOk) {
                 progress.successfulToolCalls.push(call.name);
+                stepAnySuccess = true;
+            }
             if (call.name === 'gateway_send' && deliveryResultSucceeded(rawResult)) {
                 progress.deliveryConfirmed = true;
             }
@@ -1367,6 +1702,17 @@ async function runToolLoopInner(opts, progress) {
                 }
             }
             else if (refusal !== null || rawResult.startsWith('Error:')) {
+                // SELF-DIAGNOSIS — record an action that RAN and FAILED (a non-zero
+                // exit, a timeout, a tool error), keyed by the action itself (the
+                // command / path). The gate below fires when the SAME action repeats:
+                // a refusal was already remembered across runs (step-handoff), but a
+                // command that RUNS and FAILS was not, so the live macOS-build turn
+                // re-issued `npx tauri build` ~10 times against the same missing Cargo
+                // and never once stopped to diagnose. Refusals are the other record
+                // below; this one is for the calls that actually executed.
+                if (refusal === null) {
+                    runTrace.recordFailure(call.name, failureActionOf(call), rawResult);
+                }
                 // Stage 2 — the other half of noticing a loop: the SAME refusal, twice.
                 // The run records it with its reason, so a later step (or a self-report)
                 // can see "blocked twice, identically" instead of rediscovering it — and
@@ -1422,6 +1768,54 @@ async function runToolLoopInner(opts, progress) {
             const parallelTip = parallel.note(call.name, !resultText.startsWith('Error:'));
             if (parallelTip)
                 resultText = `${resultText}\n\n${parallelTip}`;
+            // ── MISSING-PREREQUISITE TAKEOVER ──────────────────────────────────
+            // A `command not found` (exit 127) for a KNOWN, installable system tool
+            // is a STEP, not a wall — but a model can read it as an environment
+            // limit and stop: "I cannot install system-level software on your host
+            // machine — I am physically unable" (live: trace-1791127992452-qzgodi,
+            // where a user who had explicitly granted terminal permission was handed
+            // a manual `curl … | sh` step instead of the install being done). Inject
+            // the exact install command and forbid the refusal, deterministically, so
+            // the NEXT model step acts. Advisory text only — the loop never runs the
+            // install itself; that stays the model's governed `run_terminal` call.
+            if (!ranOk && (call.name === 'run_terminal' || call.name === 'terminal')) {
+                const failedCommand = String(call.arguments?.command ?? '');
+                // EVERY installable tool the failing line needs, not just the first —
+                // a `cd app && cargo build && cmake .` turn should hand the model all
+                // the prerequisites in one takeover instead of one per round-trip.
+                const missing = installableToolsFromFailure(failedCommand, rawResult);
+                if (missing.length > 0) {
+                    const installCommands = missing.map((t) => resolveInstallCommand(t));
+                    resultText = `${resultText}\n\n${toolTakeoverInstruction(missing, installCommands)}`;
+                    deps.onEvent?.(`   🛠️ ${missing.map((t) => `'${t}'`).join(', ')} missing and installable — handing the model the install command(s) to run.`);
+                    traceEvent({
+                        kind: 'gate',
+                        gate: 'tool-takeover',
+                        summary: `${missing.join(', ')} missing (command not found) and installable — the model is ` +
+                            'told to install them itself instead of declaring itself unable',
+                    });
+                }
+                // ── PROJECT PREREQUISITE BACKSTOP (D2.3) ──────────────────────────
+                // No missing BINARY, but this failure may be a missing project FILE/
+                // FEATURE (the other half of the same wall): `src-tauri/build.rs`, a
+                // Cargo `custom-protocol` feature, an icon — none of which is a tool to
+                // install, so the takeover above never fired and the live macOS turn
+                // re-ran `npx tauri build` ~10 times. Match the OUTPUT SIGNATURE, hand
+                // the model the exact fix on the FIRST failure, and record it.
+                if (missing.length === 0) {
+                    const rules = matchPrerequisiteSignatures(rawResult);
+                    if (rules.length > 0) {
+                        resultText = `${resultText}\n\n${prerequisiteTakeoverInstruction(rules)}`;
+                        deps.onEvent?.(`   🧱 build prerequisite signature matched (${rules.map((r) => r.id).join(', ')}) — handing the model the exact fix.`);
+                        traceEvent({
+                            kind: 'gate',
+                            gate: 'prerequisite',
+                            summary: `build failed on a missing PROJECT prerequisite (${rules.map((r) => r.id).join(', ')}) — ` +
+                                'the model is given the exact fix instead of retrying the identical command',
+                        });
+                    }
+                }
+            }
             delivered[i] = resultText;
             // G18 — record what this call DID, in the model's own call order, with the
             // evidence a later reader needs: the args the gate saw, the first line of
@@ -1443,6 +1837,52 @@ async function runToolLoopInner(opts, progress) {
             });
             thread.push({ role: 'tool', toolCallId: call.id, content: resultText });
         }
+        // Track the generalized stall: a step that RAN tools but succeeded at none
+        // of them extends the streak; any success clears it. A text-only step (no
+        // tools) leaves it as it was — the model is thinking, not failing.
+        if (plans.length > 0)
+            failedToolSteps = stepAnySuccess ? 0 : failedToolSteps + 1;
+        // ── SELF-DIAGNOSIS nudge (bounded, once) ──────────────────────────────
+        // The loop's missing introspection: when the SAME action has failed more
+        // than once, re-issuing it is a loop, not progress. This is the exact
+        // shape of the live macOS-build turn — `npx tauri build` was retried ~10
+        // times against the same missing Rust/Cargo, each attempt rediscovering
+        // the same wall, and the run never stopped to ask WHY. Unlike the
+        // end-of-turn gates (permission/repeat/deliverable), which fire only when
+        // the model stops calling tools, this one must fire MID-TURN while the
+        // model is still looping on the failing call — so it is injected here,
+        // right after the step's results are in the thread, and the next model
+        // step sees it. Bounded once per turn and keyed on the action so the same
+        // repeat cannot trigger it twice.
+        if (diagnosisNudges < 1) {
+            const repeated = runTrace.repeatedFailure();
+            if (repeated && repeated.times >= 2) {
+                diagnosisNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.(`   🩺 Same action failed ${repeated.times}× — asking the model to diagnose the cause instead of retrying.`);
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'diagnosis',
+                    summary: `the same action failed ${repeated.times} times (${repeated.tool}: ${repeated.action.slice(0, 120)}) — ` +
+                        'one bounded nudge to diagnose the root cause and change the approach',
+                });
+                thread.push({ role: 'user', content: repeatedFailureNudge(repeated) });
+            }
+            else if (failedToolSteps >= NO_PROGRESS_STALL_STEPS) {
+                // Stage 2 — no SINGLE action repeated, but the last N steps each ran
+                // tools and none succeeded. Same diagnosis demanded, different evidence.
+                diagnosisNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.(`   🩺 ${failedToolSteps} steps with no successful action — asking the model to diagnose the stall.`);
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'diagnosis',
+                    summary: `${failedToolSteps} consecutive steps ran tools and none succeeded — ` +
+                        'one bounded nudge to diagnose the shared cause and change the approach',
+                });
+                thread.push({ role: 'user', content: noProgressNudge(runTrace.recentFailures(3), failedToolSteps) });
+            }
+        }
         // Tiered exposure: after EVERY executed tool call, union any newly
         // loaded toolset schemas into the live set so the NEXT model step can
         // call them natively (tool_search load → loadedExtraTools → here).
@@ -1571,6 +2011,40 @@ async function runToolLoopInner(opts, progress) {
                 thread.push({ role: 'user', content: deliverableNudge(authorization.requestedPath) });
                 continue;
             }
+            // ZERO-ACTION gate (concluding exit) — the same bounded pass as the
+            // no-tools exit, for a turn that concluded (suggest_followups) without
+            // ever touching the workspace a directed request asked it to change.
+            if (actionNudges < 1 &&
+                zeroActionGateApplies(opts, progress, schemas.length, requestText, authorization.authorized)) {
+                actionNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.('   🛠️ The request asked for work and nothing was done — telling the model to do it now.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'action',
+                    summary: 'the request directed work on the workspace and the turn performed none — one bounded nudge to carry it out',
+                });
+                lastContent = '';
+                thread.push({ role: 'assistant', content: response.content });
+                thread.push({ role: 'user', content: zeroActionNudge(currentAsk(opts)) });
+                continue;
+            }
+            // SELF-REVIEW (concluding exit) — same bounded pass, placed AFTER the
+            // verification/deliverable gates so those settle their questions first.
+            const review = selfReviewCorrection();
+            if (review) {
+                selfReviewNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.('   🧭 Substantial turn ending — asking the model to review the result against the original ask.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'self-review',
+                    summary: 'a substantial turn that changed files reached its end — one bounded nudge to check the result against the original ask',
+                });
+                thread.push({ role: 'assistant', content: response.content });
+                thread.push({ role: 'user', content: review });
+                continue;
+            }
             const content = response.content.length >= lastContent.length ? response.content : lastContent;
             return {
                 content,
@@ -1921,9 +2395,23 @@ export async function runToolLoop(opts) {
         if (!result.cancelled &&
             progress.mutatedPaths.length === 0 &&
             !replyAsksTheReader(result.content) &&
+            // A request that forbade writes cannot have "failed to deliver" a file.
+            !requestForbidsWrites(lastUserText(opts.messages)) &&
             wantsAuthoredArtifact(lastUserText(opts.messages))) {
             result.undeliveredArtifact = true;
         }
+        // ZERO-ACTION honesty — a request that DIRECTED work on the workspace was
+        // answered with nothing at all: no tool succeeded, nothing was written. The
+        // flag is a function of what the turn DID, never of configuration, so a
+        // caller can never read "completed" from a turn whose request it never
+        // touched. Authored-artifact asks are left to `undeliveredArtifact` above so
+        // one turn is never reported under two names.
+        const askText = lastUserText(opts.messages);
+        if (!hasProductiveAction(progress) &&
+            progress.mutatedPaths.length === 0 &&
+            requestRequiresWorkspaceAction(askText, requestAuthorizesWrites(askText).authorized)) {
+            result.noActionTaken = true;
+        }
     }
     return result;
 }
@@ -1961,8 +2449,125 @@ function deliverableGateApplies(opts, content, progress, schemaCount, requestTex
         return false;
     if (replyAsksTheReader(content))
         return false;
+    // A negative instruction outranks every positive signal. "Do not write any
+    // files — answer in chat" contains a creation verb and a file-shaped noun, so
+    // without this the gate read it as an authored-artifact ask and wrote a file
+    // against the user's explicit instruction.
+    if (requestForbidsWrites(requestText))
+        return false;
     return wantsAuthoredArtifact(requestText);
 }
+/**
+ * Tools that do not count as having DONE anything on their own. `suggest_followups`
+ * concludes a turn; it produces no work, so a turn that only called it has still
+ * performed nothing the request asked for. Every other successful tool counts as
+ * an action (a read is an action), which keeps the zero-action gate conservative.
+ */
+/**
+ * A token that NAMES a file (a real source/config extension). The strongest
+ * signal that the request is about the WORKSPACE, not a chat answer.
+ */
+const REQUEST_FILE_TOKEN_RE = /\b[\w./~-]+\.(?:js|mjs|cjs|ts|tsx|jsx|py|rb|go|rs|java|kt|cs|cpp|cxx|cc|c|h|hpp|json|ya?ml|toml|ini|cfg|conf|md|markdown|txt|csv|tsv|html?|css|scss|sass|less|sql|sh|bash|zsh|fish|env|lock|xml|gradle|properties|vue|svelte|php|lua|pl|swift|dart|scala)\b/i;
+/** A verb that asks for a change to the workspace. */
+const WORK_EDIT_VERB_RE = /\b(?:fix|repair|refactor|edit|modify|updat|chang|add|implement|creat|writ|delet|remov|renam|rewrit|migrat|correct|debug|patch|tweak|scaffold)\w*/i;
+/** A code/workspace noun that pairs with the verb above. */
+const CODE_NOUN_RE = /\b(?:file|files|function|functions|method|methods|class|classes|module|modules|script|scripts|component|components|test|tests|suite|api|endpoint|endpoints|route|routes|schema|schemas|migration|migrations|package|dependency|dependencies|import|imports|config|configuration|type|types|interface|interfaces|bug|bugs|repo|repository|codebase|project|source)\b/i;
+/**
+ * Does this request DIRECT work on the workspace — the precondition for the
+ * ZERO-ACTION gate?
+ *
+ * Deliberately narrower than "the request authorizes writes": the gate spends a
+ * model step, so it must only fire on an ask that genuinely needs the tools.
+ * `requestAuthorizesWrites` is true for a prose deliverable ("draft an
+ * itinerary") or a review ("assess this project"), which are correctly answered
+ * in chat — nudging those would turn one turn into two for no reason (found by
+ * the existing suite). The workspace signal is therefore explicit: the request
+ * either names a FILE, or pairs an edit verb with a code noun.
+ */
+function requestRequiresWorkspaceAction(requestText, authorized) {
+    const text = (requestText || '').trim();
+    if (!text)
+        return false;
+    if (!authorized)
+        return false;
+    if (requestForbidsWrites(text))
+        return false;
+    if (wantsAuthoredArtifact(text))
+        return false;
+    if (REQUEST_FILE_TOKEN_RE.test(text))
+        return true;
+    return WORK_EDIT_VERB_RE.test(text) && CODE_NOUN_RE.test(text);
+}
+const NON_PRODUCTIVE_TOOLS = new Set(['suggest_followups']);
+/** True when the turn performed at least one action beyond merely concluding. */
+function hasProductiveAction(progress) {
+    return progress.successfulToolCalls.some((name) => !NON_PRODUCTIVE_TOOLS.has(name));
+}
+/**
+ * Does the ZERO-ACTION gate apply to this turn?
+ *
+ * Every term is an independent, checkable fact — the conjunction is what keeps
+ * the gate from firing on turns that are legitimately answer-only:
+ *
+ *   - the request AUTHORIZES writes (`authorized`) — a create/maintenance ask,
+ *     not a question (`requestAuthorizesWrites` already vetoes pure questions);
+ *   - NO tool call succeeded this turn (a turn that gathered context and then
+ *     answered is out of scope — it did something, even if it then stalled);
+ *   - NOTHING was written (`mutatedPaths` is the loop's own proof a write
+ *     landed, so a heredoc through `run_terminal` is not nudged);
+ *   - tools are actually available (a caller that exposed none cannot comply);
+ *   - the request did NOT forbid writes (a negative instruction outranks every
+ *     positive signal — see `requestForbidsWrites`);
+ *   - it is NOT an authored-artifact ask: `wantsAuthoredArtifact` requests are
+ *     the DELIVERABLE gate's job, with their own narrower message, and running
+ *     both would spend two nudges on one ask.
+ */
+function zeroActionGateApplies(opts, progress, schemaCount, requestText, authorized) {
+    if (opts.requireAction === false)
+        return false;
+    if (schemaCount === 0)
+        return false;
+    if (hasProductiveAction(progress))
+        return false;
+    if (progress.mutatedPaths.length > 0)
+        return false;
+    return requestRequiresWorkspaceAction(requestText, authorized);
+}
+/**
+ * The bounded PLAN-REQUIRED nudge (E2) — one advisory step telling the model to
+ * declare a short plan before it mutates.
+ *
+ * Names the ask, states the contract (plan first, then work), and closes the
+ * failure mode the nudge exists for: planning that REPLACES the work; the last
+ * line forbids exactly that dormancy.
+ */
+export function planRequiredNudge(ask) {
+    const quoted = (ask || '').trim().replace(/\s+/g, ' ').slice(0, 300);
+    return ('Before you change anything, declare a short PLAN for this turn — call `plan_todo` with 2–6 ordered steps' +
+        ' (create the plan once, then advance it with action "update" as you go).' +
+        (quoted ? ` The request: "${quoted}".` : '') +
+        '\nA plan is how the user can follow along and how the turn is verified — keep it accurate, do not pad it,' +
+        ' and do NOT let planning replace the work: declare it, then do the first step now.');
+}
+/**
+ * The bounded ZERO-ACTION correction — the loop telling the model, in one step,
+ * that a directed request has not been touched yet.
+ *
+ * Names the ask (so the model cannot claim it did not know what was wanted),
+ * states plainly that nothing ran and nothing changed, and closes the two escape
+ * hatches that produced the observed non-actions: do not re-ask a request that is
+ * already specified, and do not answer a work request with a plan, an apology or
+ * a question. It still leaves a REAL blocker as a legitimate way out — the goal
+ * is the work, not compliance theatre.
+ */
+export function zeroActionNudge(ask) {
+    const quoted = (ask || '').trim().replace(/\s+/g, ' ').slice(0, 300);
+    return ('Nothing has been done yet: you have not called a single tool this turn, so no file was changed and nothing was checked.' +
+        (quoted ? ` The request already asked for this work: "${quoted}".` : '') +
+        '\nYou have the tools to do it — read what you need, make the change, and run the check NOW.' +
+        ' Do NOT reply with a plan, a summary of what you would do, an apology, or a request for the user to restate or confirm' +
+        ' a request that is already complete. If something genuinely blocks you, say exactly what it is and why; otherwise do the work.');
+}
 /**
  * The text of the LAST user message in the thread — what the user is actually
  * asking for right now, as opposed to the history above it. Used to derive
@@ -2148,4 +2753,92 @@ export function trimThreadBudget(thread, maxChars = DEFAULT_THREAD_BUDGET_CHARS)
     }
     return { thread: out, trimmed };
 }
+// ─── Within-turn work digest (the memory a trimmed thread keeps) ────────────
+// `trimThreadBudget` keeps the first 500 chars of each old tool result, but past
+// that the model loses the VERDICT of what it ran and can re-run finished work.
+// `working-state` solves this ACROSS turns; this solves it WITHIN one. It is
+// deliberately deterministic and LLM-free (facts: what changed, what commands
+// ran and whether they passed, which tools were used) — no summarizer, no
+// latency, no drift, exactly like the ledger and the budget it complements.
+/** Marker prefix identifying the loop's within-turn work digest message. */
+export const WORK_DIGEST_MARKER = '[work digest — your actions so far this turn]';
+/**
+ * Format the turn's actions so far as a bounded, model-readable digest. Returns
+ * '' when there is nothing worth saying, so a pristine turn adds no noise.
+ */
+export function buildWorkDigest(input) {
+    const lines = [];
+    const changed = [...new Set(input.mutatedPaths.filter(Boolean))];
+    if (changed.length > 0) {
+        const shown = changed.slice(-12);
+        lines.push(`• Files changed (${changed.length}): ${shown.join(', ')}${changed.length > shown.length ? ', …' : ''}`);
+    }
+    // Commands with their verdict, newest first, deduped by command+verdict — the
+    // single most valuable thing to retain (did the build/test pass?).
+    const cmds = input.executedActions.filter((a) => typeof a.command === 'string' && a.command.trim());
+    if (cmds.length > 0) {
+        const seen = new Set();
+        const shown = [];
+        for (let i = cmds.length - 1; i >= 0 && shown.length < 8; i -= 1) {
+            const a = cmds[i];
+            const key = `${a.ok ? 'ok' : 'fail'}:${a.command}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            shown.unshift(`${a.ok ? '✅' : '❌'} ${a.command}`);
+        }
+        lines.push('• Commands run:');
+        for (const s of shown)
+            lines.push(`  ${s}`);
+    }
+    const tools = [...new Set(input.successfulTools)];
+    if (tools.length > 0)
+        lines.push(`• Tools used: ${tools.join(', ')}`);
+    if (lines.length === 0)
+        return '';
+    return `${WORK_DIGEST_MARKER}\n${lines.join('\n')}`;
+}
+/**
+ * Insert or refresh the single work-digest message. Idempotent: a digest already
+ * in the thread is UPDATED in place, never stacked, so repeated compaction in a
+ * long turn keeps one current digest rather than accumulating stale ones. Placed
+ * just after the system prompt + first user message so it sits with the ask and
+ * survives the NEXT compaction (the tail is never trimmed).
+ */
+export function upsertWorkDigest(thread, digest) {
+    const existing = thread.findIndex((m) => m.content.startsWith(WORK_DIGEST_MARKER));
+    if (existing !== -1) {
+        thread[existing] = { ...thread[existing], content: digest };
+        return;
+    }
+    let at = 0;
+    while (at < thread.length && thread[at].role === 'system')
+        at += 1;
+    const firstUser = thread.findIndex((m) => m.role === 'user');
+    const insertAt = Math.min(thread.length, firstUser === -1 ? at : Math.max(at, firstUser + 1));
+    thread.splice(insertAt, 0, { role: 'user', content: digest });
+}
+/**
+ * The bounded SELF-REVIEW correction — the loop's stand-in for a reviewer who
+ * asks "is this actually what was asked for?".
+ *
+ * Fired once, only for a substantial turn that changed files and has already
+ * been verified (the verification gate owns "did you check"). Its job is
+ * orthogonal: catch a result that is verified but does not satisfy the WHOLE
+ * original ask. It demands evidence from THIS turn and forbids padding the
+ * answer with more prose — the failure mode it targets is a confident, verified
+ * answer to a slightly wrong question.
+ */
+export function selfReviewNudge(ask) {
+    const quoted = (ask || '').trim().replace(/\s+/g, ' ').slice(0, 300);
+    return ('Before you finish, REVIEW your result against the ORIGINAL request' +
+        (quoted ? `: "${quoted}".` : '.') +
+        '\nAnswer these to yourself in one short pass, and fix anything that is not true:' +
+        '\n  1. Does what you produced satisfy EVERY part of that request — not just the part you found easiest?' +
+        '\n  2. Is each claim in your answer backed by a tool result from THIS turn — or is it an assumption you did not check?' +
+        '\n  3. Is anything the request asked for still missing, half-done, or done for the wrong target?' +
+        '\nIf everything is satisfied and evidenced, reply with a brief confirmation and stop.' +
+        ' If something is missing, do it NOW — or state plainly and specifically what is not done and why.' +
+        ' Do NOT restate the work in more words — verify it.');
+}
 //# sourceMappingURL=tool-loop.js.map