@prestyj/cli 5.16.2 → 5.19.0

package/dist/core/agent-session.js

@@ -1,5 +1,5 @@
 import { agentLoop, isAbortError, isUsageLimitError, } from "@prestyj/agent";
-import { ProviderError, } from "@prestyj/ai";
+import { ProviderError, stream, } from "@prestyj/ai";
 import { EventBus } from "./event-bus.js";
 import { SlashCommandRegistry, createBuiltinCommands, } from "./slash-commands.js";
 import { PROMPT_COMMANDS, getPromptCommand } from "./prompt-commands.js";
@@ -22,7 +22,7 @@ import { buildSubAgentSystemPrompt, buildSystemPrompt, } from "../system-prompt.
 import { createTools, createWebSearchTool, } from "../tools/index.js";
 import { partitionToolsByTier } from "../tools/tool-tiers.js";
 import { buildProcessCompletionFollowUp } from "./process-gate.js";
-import { buildSubAgentCompletionFollowUp } from "./subagent-manager.js";
+import { buildSubAgentCompletionFollowUp, } from "./subagent-manager.js";
 import { applyAsyncSubagentPolicy } from "./subagent-policy.js";
 import { z } from "zod";
 import { MCPClientManager, getAllMcpServers } from "./mcp/index.js";
@@ -31,6 +31,8 @@ import { CONTEXT_LIMITS, resolveContextLimits } from "./context-limits.js";
 import { McpCatalogCache } from "./mcp/catalog-cache.js";
 import { describeDropped, importForeignSession, } from "./foreign-session-import.js";
 import { createToolSearchTool } from "../tools/tool-search.js";
+import { createSessionStatsTool } from "../tools/session-stats.js";
+import { createDiagnoseCommand, isInternalDiagnosticsEnabled, SessionDiagnosticsRecorder, } from "./internal-diagnostics.js";
 import { log } from "./logger.js";
 import { setEstimatorModel, calibrateEstimatorFromUsage } from "./compaction/token-estimator.js";
 import { calculateActiveContextTokens } from "./compaction/active-context.js";
@@ -42,10 +44,14 @@ import { detectProjectStack } from "./language-detector.js";
 import { evaluateIdealReview, buildIdealReviewMessage, buildReviewCoverageEscalationMessage, buildReviewCoverageMessage, MAX_REVIEW_COVERAGE_INJECTIONS, withReviewCoverageRequirements, detectTestDrift, ReviewCoverageTracker, } from "./ideal-review.js";
 import { evaluateLoopBreak, buildLoopBreakMessage, CycleDetector, ToolCallProgressTracker, detectTextRepetition, } from "./loop-breaker.js";
 import { buildRegroundingMessage } from "./regrounding.js";
+import { buildSemanticLoopJudgePrompt, buildSemanticLoopMessage, MAX_SEMANTIC_LOOP_CALLS, parseSemanticLoopVerdict, shouldRunSemanticLoopCheck, SEMANTIC_LOOP_JUDGE_TIMEOUT_MS, withJudgeTimeout, } from "./semantic-loop-check.js";
+import { buildIndependentReviewMessage, buildReviewerTask, INDEPENDENT_REVIEW_SCORE_THRESHOLD, parseReviewerFindings, REVIEWER_TOOLS, REVIEWER_WAIT_MS, } from "./ideal-review-subagent.js";
 import { buildEnvDeltaMessage } from "./env-delta.js";
 import { wrapSteeringText, buildNotificationSteeringText, STEERING_PREFIX } from "./steering.js";
 import { AgentNotificationQueue } from "./agent-notifications.js";
-import { VerificationGate, extractAddedLines, isCheckOwnFile, isCodeFilePath, isVerificationCommand, } from "./verification-gate.js";
+import { VerificationGate, extractAddedLines, isCheckOwnFile, isCodeFilePath, VERIFICATION_STATE_KIND, isVerificationCommand, } from "./verification-gate.js";
+import { classifyVerificationCommand } from "./verification-evidence.js";
+import { captureVerificationSnapshot } from "./verification-snapshot.js";
 import { findUserSessionPrompt, getUserSessionPrompt } from "./session-preview.js";
 import { normalizeMessageImages } from "./message-images.js";
 import crypto from "node:crypto";
@@ -57,6 +63,14 @@ import path from "node:path";
  * progressing — refuse to extend its turn budget.
  */
 const TURN_EXTENSION_MAX_FAILURE_RATIO = 0.5;
+/** Terminal subagent states — mirrors SubAgentManager's private isTerminal. */
+function isTerminalSubAgentState(state) {
+    return (state === "completed" ||
+        state === "failed" ||
+        state === "interrupted" ||
+        state === "closed" ||
+        state === "reaped");
+}
 // ── Tool-result policy ─────────────────────────────────────
 /** Resolve the per-result cap passed to the agent loop for the active transport. */
 export function resolveSessionToolResultCharLimit(model, provider, accountId) {
@@ -113,6 +127,9 @@ export class AgentSession {
     // transcript rows the live run showed.
     appMarkers = [];
     turnMetrics = [];
+    /** Internal-only (EZ_INTERNAL): live per-session cost/reliability recorder.
+     * Absent entirely in public builds — see core/internal-diagnostics.ts. */
+    diagnosticsRecorder;
     tools = [];
     /** Rebuilds the read tool for a new model (video byte cap is baked in at
      *  creation). Called from switchModel so video-capable models get the
@@ -140,6 +157,7 @@ export class AgentSession {
     hookCyclicPattern = null;
     hookFileEditCounts = new Map();
     hookToolCalls = new Map();
+    backgroundVerification = new Map();
     idealReviewPhase = "idle";
     /** Runtime-only suppression while Nolan owns verification in autopilot mode. */
     idealReviewSuppressed = false;
@@ -157,6 +175,14 @@ export class AgentSession {
     /** 0 = none; 1 = first nudge sent; 2 = final stop-and-report injected. */
     loopBreakInjected = 0;
     regroundingInjected = false;
+    /** Recent tool-call digests for the semantic loop judge — bounded ring. */
+    hookRecentCalls = [];
+    /** LLM-judged loop detection state. `verdict` holds a LOOP verdict awaiting
+     *  injection at the next steering poll; judge failures fail open (no
+     *  injection) and still consume budget + cooldown. */
+    semanticLoop = { checksUsed: 0, lastCheckTurn: 0, pending: false, verdict: null, injected: false };
+    /** Independent Ideal reviewer spawned once per run (score-gated). */
+    independentReviewStarted = false;
     /**
      * The environment as the cached system prompt currently describes it.
      * Re-recorded on every prompt build, so a rebuild (e.g. `/add-dir`) needs no
@@ -201,6 +227,7 @@ export class AgentSession {
     notifications = new AgentNotificationQueue();
     managerAbortSignal;
     managerAbortHandler = () => {
+        this.lspManager?.clearPendingDiagnostics();
         void this.subAgentManager?.interruptAll();
     };
     mcpManager;
@@ -355,6 +382,7 @@ export class AgentSession {
             provider: this.provider,
             model: this.model,
             lspDiagnostics: this.settingsManager.get("lspDiagnostics"),
+            deferLspDiagnostics: true,
             getWriteGuardSettings: () => ({
                 allowOutsideWorkspaceWrites: this.settingsManager.get("allowOutsideWorkspaceWrites"),
                 additionalRoots: this.additionalRoots,
@@ -409,6 +437,11 @@ export class AgentSession {
                 : {}),
         });
         const tools = [...builtInTools, ...(this.opts.additionalTools ?? [])];
+        // Internal-only tool, appended last so public sessions keep a
+        // byte-identical tool block (prefix-cache stability).
+        if (isInternalDiagnosticsEnabled()) {
+            tools.push(createSessionStatsTool(() => this.diagnosticsRecorder));
+        }
         // Apply the optional tool allow-list (read-only advisory sessions). Filtering
         // here means the excluded tools are never registered with the agent loop, so
         // a hallucinated call can't mutate the repo — and buildSystemPrompt below is
@@ -508,6 +541,20 @@ export class AgentSession {
             const builtins = createBuiltinCommands();
             for (const cmd of builtins)
                 this.slashCommands.register(cmd);
+            // Internal-only diagnostics: recorder + /diagnose exist exclusively when
+            // the internal flag is on. Public sessions never see either, so the
+            // command list and prompt stay identical to a build without this code.
+            if (isInternalDiagnosticsEnabled()) {
+                this.diagnosticsRecorder = new SessionDiagnosticsRecorder({
+                    // Lazy: the session id is assigned at first prompt, not init.
+                    sessionId: () => this.sessionId,
+                    cwd: this.cwd,
+                    provider: this.provider,
+                    model: this.model,
+                });
+                this.diagnosticsRecorder.attach(this.eventBus);
+                this.slashCommands.register(createDiagnoseCommand());
+            }
             // Wire up /help to show all registered + prompt + custom commands.
             const helpCmd = this.slashCommands.get("help");
             if (helpCmd) {
@@ -971,6 +1018,7 @@ export class AgentSession {
      * is the verbatim user ask, pinned for post-compaction re-grounding.
      */
     resetHookState(originalRequest) {
+        this.lspManager?.clearPendingDiagnostics();
         this.hookStats = {
             changedLines: 0,
             toolCalls: 0,
@@ -997,9 +1045,23 @@ export class AgentSession {
         this.idealDriftProbe = null;
         this.loopBreakInjected = 0;
         this.regroundingInjected = false;
+        this.hookRecentCalls = [];
+        this.semanticLoop = {
+            checksUsed: 0,
+            lastCheckTurn: 0,
+            pending: false,
+            verdict: null,
+            injected: false,
+        };
+        this.independentReviewStarted = false;
         this.runStartedAt = Date.now();
         this.processGateInjected = 0;
-        this.verificationGate.reset();
+        this.verificationGate.beginRun();
+        const processes = new Set(this.processManager?.list().map((p) => p.id) ?? []);
+        for (const id of this.backgroundVerification.keys()) {
+            if (!processes.has(id))
+                this.backgroundVerification.delete(id);
+        }
         this.compactionOccurred = false;
         this.originalRequest = originalRequest;
     }
@@ -1014,7 +1076,35 @@ export class AgentSession {
                 this.hookText += event.text;
                 break;
             case "tool_call_start":
-                this.hookToolCalls.set(event.toolCallId, { name: event.name, args: event.args ?? {} });
+                this.hookToolCalls.set(event.toolCallId, {
+                    name: event.name,
+                    args: event.args ?? {},
+                    revision: this.verificationGate.revision,
+                });
+                if (event.name === "bash" &&
+                    typeof event.args?.command === "string" &&
+                    (isVerificationCommand(event.args.command) ||
+                        classifyVerificationCommand(event.args.command).accepted)) {
+                    // A check that can rewrite files (--fix, build scripts, emitters)
+                    // invalidates earlier in-flight evidence AND marks the run as
+                    // touched. A check that is merely UNRECOGNIZED (`make test`, `deno
+                    // test`) rewrites nothing we can point to: bumping the revision for
+                    // it poisoned the gate on green output and re-armed the hook into
+                    // every later question turn.
+                    const classification = classifyVerificationCommand(event.args.command);
+                    if (classification.snapshotEligible && event.args.persist !== true) {
+                        const call = this.hookToolCalls.get(event.toolCallId);
+                        call.sourceSnapshot = await captureVerificationSnapshot(this.opts.cwd, [
+                            ...this.hookFileEditCounts.keys(),
+                        ]);
+                        if (call.sourceSnapshot === null)
+                            this.verificationGate.requireFreshVerification(true, event.args.command);
+                    }
+                    else {
+                        this.verificationGate.requireFreshVerification(!classification.accepted && classification.mayMutate, event.args.command);
+                    }
+                    await this.persistVerificationState();
+                }
                 break;
             case "tool_call_end": {
                 const call = this.hookToolCalls.get(event.toolCallId);
@@ -1032,14 +1122,28 @@ export class AgentSession {
                 this.hookConsecutiveFailures = event.isError ? this.hookConsecutiveFailures + 1 : 0;
                 this.hookRepeatedNoProgressCalls = this.hookProgressTracker.record(name, args, event.result, event.isError);
                 this.hookCyclicPattern = this.hookCycleDetector.record(name, args, event.result, event.isError);
+                // Semantic-loop judge input: a bounded digest of WHAT was attempted and
+                // HOW it came out. Args/results are sliced AT RECORD TIME — a write with
+                // a 50 KiB payload or a bash dump must never inflate the ring, and the
+                // judge needs shapes, not payloads.
+                this.hookRecentCalls.push({
+                    tool: name,
+                    args: args === undefined ? "" : JSON.stringify(args).slice(0, 300),
+                    ok: !event.isError,
+                    result: event.result.slice(0, 400),
+                });
+                if (this.hookRecentCalls.length > MAX_SEMANTIC_LOOP_CALLS) {
+                    this.hookRecentCalls.splice(0, this.hookRecentCalls.length - MAX_SEMANTIC_LOOP_CALLS);
+                }
                 if (name === "edit" && !event.isError) {
                     const diff = event.details?.diff ?? event.result;
                     const added = (diff.match(/^\+[^+]/gm) ?? []).length;
                     const removed = (diff.match(/^-[^-]/gm) ?? []).length;
                     this.hookStats.changedLines += added + removed;
                 }
-                // Verification-gate bookkeeping: successful code mutations and completed
-                // foreground verification commands, in occurrence order.
+                // Only host-observed successful mutations and trustworthy check results
+                // affect approval. The model's text is never evidence.
+                let verificationChanged = false;
                 if (!event.isError && args) {
                     if (name === "edit" || name === "write") {
                         const filePath = String(args.file_path ?? "");
@@ -1051,26 +1155,62 @@ export class AgentSession {
                                 ? String(args.content ?? "")
                                 : extractAddedLines(event.details?.diff ?? event.result);
                             this.verificationGate.recordMutation(filePath, addedText);
+                            verificationChanged = true;
                         }
                     }
-                    if (name === "bash" &&
-                        !args.run_in_background &&
-                        isVerificationCommand(String(args.command ?? ""))) {
-                        this.verificationGate.recordVerification();
-                    }
-                    // Reading the final output of an EXITED background verification run
-                    // counts: the process gate forces this read anyway, so without it the
-                    // gate would demand a redundant foreground re-run of tests the agent
-                    // already watched finish.
-                    if (name === "task_output") {
-                        const proc = this.processManager
-                            ?.list()
-                            .find((p) => p.id === args.id);
-                        if (proc && proc.exitCode !== null && isVerificationCommand(proc.command)) {
-                            this.verificationGate.recordVerification();
+                }
+                if (args && call && name === "bash") {
+                    const command = typeof args.command === "string" ? args.command : "";
+                    const classification = classifyVerificationCommand(command);
+                    if (classification.accepted || classification.snapshotEligible) {
+                        if (args.run_in_background === true && !event.isError && args.persist !== true) {
+                            const id = /^ID:\s*(\S+)/m.exec(event.result)?.[1];
+                            // No parseable ID means the check cannot be tracked to a real exit
+                            // code — no evidence either way. Recording a FAILURE here made
+                            // every later green run of a different spelling look owed.
+                            if (id)
+                                this.backgroundVerification.set(id, {
+                                    revision: call.revision,
+                                    command,
+                                    ...(classification.snapshotEligible
+                                        ? { sourceSnapshot: call.sourceSnapshot ?? null }
+                                        : {}),
+                                });
+                            else if (classification.snapshotEligible)
+                                this.verificationGate.requireFreshVerification(true, command);
                         }
+                        else if (args.persist === true) {
+                            // Persistent-shell checks are not bounded evidence (steering can
+                            // interleave): neither a pass nor a failure. A recorded failure
+                            // here blocked approval for sessions that prefer the shell.
+                        }
+                        else if (classification.snapshotEligible) {
+                            await this.finishSnapshotVerification({ command, revision: call.revision, sourceSnapshot: call.sourceSnapshot ?? null }, !event.isError && /^Exit code:\s*0(?:\s|$)/i.test(event.result.trim()));
+                            verificationChanged = true;
+                        }
+                        else {
+                            if (!event.isError && /^Exit code:\s*0(?:\s|$)/i.test(event.result.trim())) {
+                                this.verificationGate.recordVerification(call.revision, command);
+                            }
+                            else {
+                                this.verificationGate.recordFailedVerification(command, call.revision);
+                            }
+                            verificationChanged = true;
+                        }
+                        delete call.sourceSnapshot;
                     }
+                    else if (classification.candidate) {
+                        // Green but untrusted: remember WHY so the demand can tell the
+                        // agent which command shape actually clears the gate.
+                        this.verificationGate.recordRejectedCheck(command, classification.reason);
+                    }
+                }
+                if (!event.isError && args && name === "task_output" && typeof args.id === "string") {
+                    verificationChanged =
+                        (await this.recordFinishedBackgroundVerification(args.id)) || verificationChanged;
                 }
+                if (verificationChanged)
+                    await this.persistVerificationState();
                 // Tool results are what push the run over the review gate, and they all
                 // land before the model writes its candidate final answer — so this is
                 // the point where arming still beats the draft's first token.
@@ -1158,11 +1298,18 @@ export class AgentSession {
         // it in the very next turn instead of discovering it at the pre-stop
         // completion gate — but it never displaces user steering, which rides out
         // in the same batch when both are pending.
+        const diagnosticText = this.lspManager?.drainDiagnostics(this.getVerificationProblem() !== null, { deferUnverified: true });
+        if (diagnosticText)
+            this.eventBus.emit("diagnostics", { text: diagnosticText });
+        this.refreshVerificationArmed();
         const notified = this.notifications.drain();
-        const notificationMessage = notified.length > 0
+        const notificationMessage = notified.length > 0 || diagnosticText
             ? {
                 role: "user",
-                content: buildNotificationSteeringText(notified.map((entry) => entry.text)),
+                content: buildNotificationSteeringText([
+                    ...notified.map((entry) => entry.text),
+                    ...(diagnosticText ? [diagnosticText] : []),
+                ]),
                 provenance: { source: "runtime", kind: "notification", visibility: "hidden" },
             }
             : null;
@@ -1219,16 +1366,21 @@ export class AgentSession {
             return null;
         if (!this.settingsManager.get("idealReviewEnabled"))
             return null;
+        // Deterministic stuck verdict, computed once and shared: the semantic
+        // judge must not spend tokens on a burst the deterministic breaker is
+        // about to correct itself.
+        const deterministicDecision = evaluateLoopBreak({
+            consecutiveFailures: this.hookConsecutiveFailures,
+            repeatedNoProgressCalls: this.hookRepeatedNoProgressCalls,
+            textRepetitionDetected: detectTextRepetition(this.hookText),
+            ...(this.hookCyclicPattern ? { cyclicPattern: this.hookCyclicPattern } : {}),
+        });
+        this.maybeStartSemanticLoopCheck(deterministicDecision.shouldBreak);
         // Two-stage loop-breaker: stage 1 nudges; a FRESH detection after that
         // injects the harsher final stop-and-report prompt. Signals reset after
         // each injection so stage 2 only fires on new evidence.
         if (this.loopBreakInjected < 2) {
-            const decision = evaluateLoopBreak({
-                consecutiveFailures: this.hookConsecutiveFailures,
-                repeatedNoProgressCalls: this.hookRepeatedNoProgressCalls,
-                textRepetitionDetected: detectTextRepetition(this.hookText),
-                ...(this.hookCyclicPattern ? { cyclicPattern: this.hookCyclicPattern } : {}),
-            });
+            const decision = deterministicDecision;
             if (decision.shouldBreak) {
                 const stage = this.loopBreakInjected === 0 ? 1 : 2;
                 this.loopBreakInjected = stage;
@@ -1237,6 +1389,9 @@ export class AgentSession {
                 this.hookCyclicPattern = null;
                 this.hookConsecutiveFailures = 0;
                 this.hookRepeatedNoProgressCalls = 0;
+                // The deterministic breaker owns this burst — a semantic verdict from
+                // the same burst must not double-correct on the next poll.
+                this.semanticLoop.verdict = null;
                 // Clear the text buffer too — otherwise a stage-1 text-repetition
                 // trigger still sees the same repeated tail on the next check and
                 // escalates to stage 2 on stale evidence.
@@ -1249,6 +1404,22 @@ export class AgentSession {
                 return [buildLoopBreakMessage(decision.reasons, stage === 2)];
             }
         }
+        // Semantic loop-break: an LLM verdict (started by maybeStartSemanticLoopCheck
+        // on a suspicious-but-syntactically-quiet burst) is consumed here, exactly
+        // once, with the deterministic breaker getting priority above. Fail-open:
+        // no verdict or no-loop verdict injects nothing.
+        if (this.semanticLoop.verdict && !this.semanticLoop.injected) {
+            const verdict = this.semanticLoop.verdict;
+            this.semanticLoop.injected = true;
+            this.semanticLoop.verdict = null;
+            // The judged burst has been addressed; a fresh burst must re-accumulate.
+            this.hookConsecutiveFailures = 0;
+            log("INFO", "loop-break", "Injecting semantic loop-break steering", {
+                reason: verdict.reason,
+            });
+            this.eventBus.emit("hook", { kind: "loop_break" });
+            return [buildSemanticLoopMessage(verdict)];
+        }
         if (!this.regroundingInjected && this.compactionOccurred) {
             this.regroundingInjected = true;
             this.eventBus.emit("hook", { kind: "regrounding" });
@@ -1256,6 +1427,159 @@ export class AgentSession {
         }
         return null;
     }
+    /** Fire the semantic loop judge when deterministic evidence is suspicious but
+     *  the deterministic breaker stayed quiet — the syntactic blind spot where
+     *  every retry differs slightly and the run still makes no progress.
+     *  Fire-and-forget: the call runs while the next turn streams, and a finished
+     *  verdict is consumed by the NEXT steering poll — never blocking a turn. */
+    maybeStartSemanticLoopCheck(deterministicBreak) {
+        if (!shouldRunSemanticLoopCheck({
+            consecutiveFailures: this.hookConsecutiveFailures,
+            totalFailures: this.hookStats.toolFailures,
+            turns: this.hookStats.turns,
+            lastCheckTurn: this.semanticLoop.lastCheckTurn,
+            checksUsed: this.semanticLoop.checksUsed,
+            checkPending: this.semanticLoop.pending,
+            deterministicBreak,
+        })) {
+            return;
+        }
+        // resetHookState replaces this object on every prompt. A late judge must
+        // not publish a verdict or consume the next run's budget/cooldown.
+        const runState = this.semanticLoop;
+        runState.pending = true;
+        log("INFO", "loop-break", "Starting semantic loop judge", {
+            turn: String(this.hookStats.turns),
+            consecutiveFailures: String(this.hookConsecutiveFailures),
+            recentCalls: String(this.hookRecentCalls.length),
+        });
+        void (async () => {
+            try {
+                const prompt = buildSemanticLoopJudgePrompt(this.hookRecentCalls, this.originalRequest);
+                const raw = await (this.opts.semanticLoopJudge?.(prompt) ??
+                    this.callSemanticLoopJudge(prompt));
+                const verdict = parseSemanticLoopVerdict(raw);
+                if (this.semanticLoop === runState && verdict?.loop)
+                    runState.verdict = verdict;
+            }
+            catch (error) {
+                // Fail open: judge errors never stop a run. Budget and cooldown are
+                // still consumed in `finally` so a flaky judge cannot retry-loop.
+                log("WARN", "loop-break", "Semantic loop judge failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                if (this.semanticLoop === runState) {
+                    runState.pending = false;
+                    runState.checksUsed += 1;
+                    runState.lastCheckTurn = this.hookStats.turns;
+                }
+            }
+        })();
+    }
+    /** One-shot judge call on the session's ACTIVE model — deliberately not a
+     *  cheaper routing: judging a model's own failure patterns with a weaker
+     *  model swaps false negatives for false positives. */
+    async callSemanticLoopJudge(prompt) {
+        const creds = await this.authStorage.resolveCredentials(this.provider, {
+            storageKeys: this.currentAuthStorageKeys(),
+        });
+        const result = stream({
+            provider: this.provider,
+            model: this.model,
+            messages: [{ role: "user", content: prompt }],
+            maxTokens: 500,
+            apiKey: creds.accessToken,
+            accountId: creds.accountId,
+            projectId: creds.projectId,
+            baseUrl: this.baseUrl ?? creds.baseUrl,
+            signal: this.opts.signal,
+        });
+        const response = await withJudgeTimeout(result.response, SEMANTIC_LOOP_JUDGE_TIMEOUT_MS);
+        // Providers differ in reply shape: some return a bare string, others an
+        // array of parts (glm-5.3 among them) — joining text parts covers both,
+        // where the string-only branch silently dropped the whole verdict.
+        const content = response.message.content;
+        if (typeof content === "string")
+            return content;
+        return Array.isArray(content)
+            ? content
+                .filter((part) => part.type === "text")
+                .map((part) => part.text)
+                .join("\n")
+            : "";
+    }
+    /** Independent fresh-context review of the finished work (Codex Guardian
+     *  pattern). Spawns a READ-ONLY child on the ACTIVE model, waits bounded,
+     * and returns findings for the acting agent to address — or nothing when
+     *  the review passes, is unavailable, or fails (in-thread review remains the
+     *  fallback; the feature degrades, never blocks).
+     *
+     *  Runs inside the pre-stop poll, so the candidate final answer is already
+     *  held by arming and this wait cannot race a streamed answer. */
+    async runIndependentReview(decision) {
+        if (!this.subAgentManager)
+            return [];
+        if (this.independentReviewStarted)
+            return [];
+        // An allow-listed session (a subagent worker itself) must not spawn
+        // harness-owned grandchildren the tool policy never granted.
+        if (this.opts.allowedTools && !this.opts.allowedTools.includes("spawn_agent"))
+            return [];
+        if (decision.score < INDEPENDENT_REVIEW_SCORE_THRESHOLD)
+            return [];
+        this.independentReviewStarted = true;
+        const taskName = `ideal-reviewer-${Math.random().toString(36).slice(2, 8)}`;
+        let agentId;
+        try {
+            const task = buildReviewerTask({
+                originalRequest: this.originalRequest,
+                changedFiles: [...this.hookFileEditCounts.keys()],
+                stats: this.hookStats,
+                triggerReasons: decision.reasons,
+            });
+            // Active model forced at spawn time — never routed to a fast/review model.
+            const snapshot = await this.subAgentManager.spawn(taskName, task, undefined, {
+                model: this.model,
+                tools: REVIEWER_TOOLS,
+            });
+            agentId = snapshot.agent_id;
+            const waited = await this.subAgentManager.wait([agentId], "all", REVIEWER_WAIT_MS);
+            const agent = waited.agents[0];
+            if (!agent || !isTerminalSubAgentState(agent.state)) {
+                // Timeout: collect the straggler so the completion gate cannot fire on
+                // it later, then fall back to the in-thread review.
+                await this.subAgentManager.interrupt(agentId, true).catch(() => { });
+                log("WARN", "ideal", "Independent reviewer timed out; falling back to in-thread review", {
+                    agentId,
+                });
+                return [];
+            }
+            const findings = parseReviewerFindings(agent.output ?? "");
+            if (!findings) {
+                log("WARN", "ideal", "Independent reviewer output unparseable; falling back", { agentId });
+                return [];
+            }
+            if (findings.clean) {
+                log("INFO", "ideal", "Independent reviewer verdict: clean", { agentId });
+                return [];
+            }
+            log("INFO", "ideal", "Independent reviewer flagged findings", {
+                agentId,
+                count: String(findings.findings.length),
+            });
+            return [buildIndependentReviewMessage(findings.findings)];
+        }
+        catch (error) {
+            if (agentId)
+                await this.subAgentManager.interrupt(agentId, true).catch(() => { });
+            log("WARN", "ideal", "Independent reviewer failed; falling back to in-thread review", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
     /**
      * Turn-budget extension gate. The loop consults this instead of stopping
      * mid-task when it exhausts `maxTurns`. Grant ONLY on evidence of progress —
@@ -1335,6 +1659,8 @@ export class AgentSession {
     /** Would a stop right now inject the verification gate? Same conditions as
      *  the pre-stop branch below, so arming and injection cannot disagree. */
     wouldInjectVerification() {
+        if (this.lspManager?.hasQueuedDiagnostics())
+            return true;
         if (this.opts.selfCorrectionHooks === false)
             return false;
         if (!this.settingsManager.get("verificationGateEnabled"))
@@ -1356,6 +1682,11 @@ export class AgentSession {
         if (!this.settingsManager)
             return;
         this.refreshIdealReviewArmed();
+        this.refreshVerificationArmed();
+    }
+    refreshVerificationArmed() {
+        if (!this.settingsManager)
+            return;
         const armed = this.wouldInjectVerification();
         if (armed === this.verificationArmed)
             return;
@@ -1373,10 +1704,37 @@ export class AgentSession {
      * Pre-stop Ideal review phase machine. Once review starts, completion is
      * blocked until harness-owned post-injection reads cover every changed file.
      */
-    getHookFollowUpMessages() {
+    async getHookFollowUpMessages() {
+        // Exit notifications and task_output refer to the same host process record.
+        // Do not force an extra polling tool/turn merely to acknowledge a known exit.
+        let backgroundChanged = false;
+        for (const id of this.backgroundVerification.keys()) {
+            backgroundChanged =
+                (await this.recordFinishedBackgroundVerification(id)) || backgroundChanged;
+        }
+        if (backgroundChanged)
+            await this.persistVerificationState();
+        // Edits return immediately; only the completion boundary waits for remaining
+        // checks. Queued timeouts stay explicitly unverified, never a false all-clear.
+        await this.lspManager?.flushDiagnostics(this.opts.signal);
+        if (this.opts.signal?.aborted)
+            return null;
+        const diagnosticText = this.lspManager?.drainDiagnostics(this.getVerificationProblem() !== null);
+        if (diagnosticText)
+            this.eventBus.emit("diagnostics", { text: diagnosticText });
+        this.refreshVerificationArmed();
+        const diagnosticMessages = diagnosticText
+            ? [
+                {
+                    role: "user",
+                    content: buildNotificationSteeringText([diagnosticText]),
+                    provenance: { source: "runtime", kind: "notification", visibility: "hidden" },
+                },
+            ]
+            : [];
         const childCompletionFollowUp = buildSubAgentCompletionFollowUp(this.subAgentManager);
         if (childCompletionFollowUp)
-            return childCompletionFollowUp;
+            return [...diagnosticMessages, ...childCompletionFollowUp];
         // Background processes started this run and never read block completion:
         // their progress/exit checkpoints only land on the steering path, which an
         // agent about to stop never reaches.
@@ -1386,7 +1744,7 @@ export class AgentSession {
             log("INFO", "process-gate", "Injecting background-process completion gate", {
                 injected: String(this.processGateInjected),
             });
-            return processFollowUp;
+            return [...diagnosticMessages, ...processFollowUp];
         }
         // Verification gate: code was edited but nothing verified since the last
         // edit. Above the Ideal review so checks RUN before the read-based review
@@ -1394,17 +1752,29 @@ export class AgentSession {
         if (this.opts.selfCorrectionHooks !== false &&
             this.settingsManager.get("verificationGateEnabled") &&
             (!this.opts.allowedTools || this.opts.allowedTools.includes("bash"))) {
+            const verificationReason = this.verificationGate.pendingReason();
             const verificationFollowUp = this.verificationGate.followUp();
             if (verificationFollowUp) {
                 log("INFO", "verification-gate", "Injecting verification follow-up", {});
                 // Announce, THEN disarm: clients release held text on disarm, so the
                 // reverse order paints the draft and immediately deletes it — the exact
                 // flash arming exists to prevent.
-                this.eventBus.emit("hook", { kind: "verification" });
+                this.eventBus.emit("hook", {
+                    kind: "verification",
+                    ...(verificationReason === "tamper"
+                        ? { verificationReason: "check_review" }
+                        : verificationReason === "recheck"
+                            ? { verificationReason }
+                            : {}),
+                });
                 this.refreshHookArming();
-                return verificationFollowUp;
+                return [...diagnosticMessages, ...verificationFollowUp];
             }
         }
+        // Address real errors before review; unavailable checks share the existing
+        // verification demand above instead of manufacturing a separate hook.
+        if (diagnosticMessages.length > 0)
+            return diagnosticMessages;
         if (this.opts.selfCorrectionHooks === false || this.idealReviewSuppressed)
             return null;
         if (this.idealReviewPhase === "reviewing") {
@@ -1460,6 +1830,9 @@ export class AgentSession {
         const driftedFiles = detectTestDrift(this.hookFileEditCounts.keys(), this.cwd).slice(0, 5);
         if (!decision.shouldReview && driftedFiles.length === 0)
             return null;
+        // Independent reviewer first (async, bounded): its findings ride in the
+        // SAME follow-up batch as the in-thread review + coverage requirements, so
+        // addressing everything still costs one extra turn.
         this.reviewCoverage.start(this.hookFileEditCounts.keys());
         this.idealReviewPhase = "reviewing";
         const coverage = this.reviewCoverage.evidence();
@@ -1476,6 +1849,8 @@ export class AgentSession {
         // coverage is outstanding injects again. Disarm lands later, on the read
         // that closes the last gap (or when the retry budget escalates).
         this.refreshIdealReviewArmed();
+        // Announce the phase before the reviewer starts, not after its bounded wait.
+        const independentMessages = await this.runIndependentReview(decision);
         log("INFO", "ideal", "Injecting ideal review before final response", {
             coverageExpected: coverage.expected,
             coverageMissing: coverage.missing,
@@ -1483,6 +1858,7 @@ export class AgentSession {
             lspMissing: lspEvidence.missing,
         });
         return [
+            ...independentMessages,
             this.withReviewLspEvidence(withReviewCoverageRequirements(buildIdealReviewMessage(decision.reasons, driftedFiles), coverage.missing), lspEvidence),
         ];
     }
@@ -2083,12 +2459,15 @@ export class AgentSession {
         await this.rePersistNolanTurns();
         await this.rePersistAutopilotMarkers();
         await this.rePersistAppMarkers();
+        await this.persistVerificationState();
         await this.persistAppMarker("compaction", {
             originalCount: result.originalCount,
             newCount: result.newCount,
         });
     }
-    async compact(existingCredentials, mode = "manual") {
+    async compact(existingCredentials, mode = "manual", 
+    /** User-stated focus (`/compact <focus>`): what must survive verbatim. */
+    focus) {
         this.lastCompactionCompacted = false;
         const creds = existingCredentials ??
             (await this.authStorage.resolveCredentials(this.provider, {
@@ -2121,6 +2500,7 @@ export class AgentSession {
                 targetTokens: policy.targetTokens,
                 signal: this.opts.signal,
                 approvedPlanPath: this.approvedPlanPath,
+                focus,
             });
             contextSelection = output.result.contextSelection;
             return output;
@@ -2239,6 +2619,8 @@ export class AgentSession {
         // Approved-plan execution is a clean checkpoint of the same conversation;
         // explicit new sessions reset the conversation identity.
         if (!preserveConversation) {
+            this.verificationGate.reset();
+            this.backgroundVerification.clear();
             this.conversationId = "";
             this.checkpointGeneration = 0;
             this.sessionPreview = "";
@@ -2680,6 +3062,9 @@ export class AgentSession {
             },
         };
         this.turnMetrics.push(payload);
+        // Internal diagnostics piggyback on the authoritative per-turn metric —
+        // one source of truth, and the record flushes to disk every turn.
+        this.diagnosticsRecorder?.recordTurnMetric(payload);
         if (this.sessionPath)
             await this.sessionManager.appendTurnMetric(this.sessionPath, payload);
     }
@@ -2778,6 +3163,76 @@ export class AgentSession {
      * instead of dropping the marker or falling back to a raw verdict string.
      * No-op persistence for transient sessions (kept in memory only).
      */
+    async recordFinishedBackgroundVerification(id) {
+        const started = this.backgroundVerification.get(id);
+        const proc = this.processManager?.list().find((entry) => entry.id === id);
+        if (!started || !proc || proc.exitCode === null)
+            return false;
+        if (started.sourceSnapshot !== undefined) {
+            await this.finishSnapshotVerification(started, proc.exitCode === 0);
+        }
+        else if (proc.exitCode === 0) {
+            this.verificationGate.recordVerification(started.revision, started.command);
+        }
+        else {
+            this.verificationGate.recordFailedVerification(started.command, started.revision);
+        }
+        this.backgroundVerification.delete(id);
+        return true;
+    }
+    getVerificationEvidence() {
+        return this.verificationGate.evidence();
+    }
+    async finishSnapshotVerification(check, passed) {
+        const after = check.sourceSnapshot
+            ? await captureVerificationSnapshot(this.opts.cwd, [...this.hookFileEditCounts.keys()])
+            : null;
+        if (after === null || after !== check.sourceSnapshot) {
+            this.verificationGate.requireFreshVerification(true, check.command);
+            this.verificationGate.recordRejectedCheck(check.command, after === null
+                ? "Workspace inputs could not be compared; run a read-only check after the command"
+                : "Command changed workspace inputs; run checks against the changed source");
+            if (!passed)
+                this.verificationGate.recordFailedVerification(check.command);
+        }
+        else if (passed) {
+            const classification = classifyVerificationCommand(check.command);
+            if (classification.snapshotPreserveOnly) {
+                this.verificationGate.recordRejectedCheck(check.command, classification.reason);
+            }
+            else {
+                this.verificationGate.recordVerification(check.revision, check.command);
+            }
+        }
+        else {
+            this.verificationGate.recordFailedVerification(check.command, check.revision);
+        }
+    }
+    getVerificationProblem() {
+        if ([...this.hookToolCalls.values()].some((call) => call.sourceSnapshot !== undefined)) {
+            return "Unverified: a build is still running or its workspace comparison is pending.";
+        }
+        return (this.verificationGate.verificationProblem() ??
+            (this.backgroundVerification.size > 0
+                ? "Unverified: a background check is still running or its result has not been confirmed."
+                : null));
+    }
+    async persistVerificationState() {
+        if (!this.sessionPath)
+            return;
+        const entry = {
+            type: "custom",
+            kind: VERIFICATION_STATE_KIND,
+            id: crypto.randomUUID(),
+            parentId: null,
+            timestamp: new Date().toISOString(),
+            data: {
+                ...this.verificationGate.snapshot(),
+                unknown: this.getVerificationProblem() !== null,
+            },
+        };
+        await this.sessionManager.appendEntry(this.sessionPath, entry);
+    }
     async persistAutopilotMarker(phase, extra) {
         const afterMessageCount = this.persistedTranscriptCount();
         const payload = {
@@ -2904,7 +3359,10 @@ export class AgentSession {
     async enhancePrompt(text) {
         if (!text.trim())
             return { enhanced: text, segments: [{ kind: "text", text }] };
-        const creds = await this.authStorage.resolveCredentials(this.provider, {
+        // Keep credentials and settings on the model selected at click time, even
+        // if the user switches models while credential resolution is pending.
+        const { provider, model, thinkingLevel, maxTokens, baseUrl } = this;
+        const creds = await this.authStorage.resolveCredentials(provider, {
             storageKeys: this.currentAuthStorageKeys(),
         });
         // Cheap, best-effort stack detection from the project root so terminology is
@@ -2917,12 +3375,16 @@ export class AgentSession {
             /* detection is best-effort — fall back to no stack hint */
         }
         return enhancePrompt({
-            provider: this.provider,
-            model: this.model,
+            provider,
+            model,
+            thinking: thinkingLevel,
+            maxTokens,
+            userAgent: provider === "anthropic" ? await getClaudeCliUserAgent() : undefined,
+            projectId: creds.projectId,
             prompt: text,
             stack,
             apiKey: creds.accessToken,
-            baseUrl: this.baseUrl ?? creds.baseUrl,
+            baseUrl: baseUrl ?? creds.baseUrl,
             accountId: creds.accountId,
             signal: this.opts.signal,
         });
@@ -2977,6 +3439,7 @@ export class AgentSession {
         return this.getPromptCacheKey();
     }
     async dispose() {
+        this.diagnosticsRecorder?.finalize();
         this.managerAbortSignal?.removeEventListener("abort", this.managerAbortHandler);
         this.processManager?.shutdownAll();
         this.lspManager?.shutdownAll();
@@ -3019,6 +3482,23 @@ export class AgentSession {
         const loaded = await this.sessionManager.load(canonicalPath);
         // Use the leaf from the header to walk the correct branch
         const loadedMessages = this.sessionManager.getMessages(loaded.entries, loaded.header.leafId);
+        this.backgroundVerification.clear();
+        const savedVerification = [...loaded.entries]
+            .reverse()
+            .find((entry) => entry.type === "custom" && entry.kind === VERIFICATION_STATE_KIND);
+        if (savedVerification?.type === "custom") {
+            this.verificationGate.restore(savedVerification.data);
+        }
+        else {
+            this.verificationGate.reset();
+            // Legacy sessions have no host checkpoint. Tool-authored code history is
+            // not proof of today's files; require fresh evidence before approval.
+            if (loadedMessages.some((message) => message.role === "assistant" &&
+                Array.isArray(message.content) &&
+                message.content.some((part) => part.type === "tool_call" && (part.name === "edit" || part.name === "write")))) {
+                this.verificationGate.requireFreshVerification();
+            }
+        }
         this.checkpointGeneration = loaded.header.generation ?? 0;
         this.conversationId = loaded.header.conversationId ?? loaded.header.id;
         const legacyLabel = [...loaded.entries]
@@ -3162,7 +3642,7 @@ export class AgentSession {
     createSlashCommandContext() {
         return {
             switchModel: (provider, model) => this.switchModel(provider, model),
-            compact: () => this.compact(undefined, "manual"),
+            compact: (focus) => this.compact(undefined, "manual", focus),
             newSession: () => this.newSession(),
             listSessions: async () => {
                 const sessions = await this.sessionManager.list(this.cwd);