apex-code 0.0.1-alpha.9 → 0.0.4

package/dist/core/agent-session.js

@@ -13,7 +13,7 @@
  * Modes use this class and add their own I/O layer on top.
  */
 import { readFileSync } from "node:fs";
-import { basename, dirname } from "node:path";
+import { basename, dirname, isAbsolute, relative } from "node:path";
 import { contentText } from "@earendil-works/pi-ai";
 import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, } from "@earendil-works/pi-ai/compat";
 import { getThemeByName, theme } from "../modes/interactive/theme/theme.js";
@@ -22,6 +22,7 @@ import { sleep } from "../utils/sleep.js";
 import { normalizeToolResultImages } from "../utils/tool-result-images.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
 import { executeBashWithOperations } from "./bash-executor.js";
+import { createSessionCheckpoints } from "./checkpoints/session-checkpoints.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { evictionBudget, installContextPipeline, isDefaultStreamFunction } from "./context/pipeline.js";
 import { DEFAULT_THINKING_LEVEL, THINKING_LEVEL_OPTIONS } from "./defaults.js";
@@ -30,10 +31,13 @@ import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
+import { runFormatterCommand } from "./formatter-lifecycle.js";
 import { ModelRegistry } from "./model-registry.js";
 import { evaluateToolCall } from "./permissions/gate.js";
+import { authorizeConfiguredCommand } from "./permissions/policy-command.js";
 import { createInteractiveResponder } from "./permissions/responder.js";
 import { resolveEffectiveModeWithOrigin } from "./permissions/startup.js";
+import { loadPolicyConfiguration } from "./policy-loader.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
 import { exportSessionToJsonl } from "./session-export.js";
 import { getLatestCompactionEntry, TODO_CUSTOM_ENTRY_TYPE } from "./session-manager.js";
@@ -41,12 +45,18 @@ import { slugifySkillCommandName } from "./skills.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
+import { buildToolContractSnapshot, isUnclassifiedTool, } from "./tools/contract-snapshot.js";
 import { createAllToolDefinitions } from "./tools/index.js";
 import { createSkillSearchToolDefinition } from "./tools/skill-search.js";
 import { createTodoWriteToolDefinition } from "./tools/todo-write.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { createToolSchemaToolDefinition } from "./tools/tool-schema.js";
 import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
+import { VerificationTracker, } from "./verification-lifecycle.js";
+import { buildWorkspaceComparison, compareWorkspaceObservations } from "./workspace/comparison.js";
+import { observeWorkspaceGit } from "./workspace/git-observer.js";
+import { formatWorkspaceProjection } from "./workspace/projection.js";
+import { appendWorkspaceComparison, appendWorkspaceObservation, findLatestWorkspaceObservation, hasWorkspaceObservationAwaitingComparison, } from "./workspace/state.js";
 /**
  * Parse a skill block from message text.
  * Returns null if the text doesn't contain a skill block.
@@ -77,12 +87,6 @@ function estimateMessagesTokens(messages) {
     }
     return tokens;
 }
-// ============================================================================
-// Constants
-// ============================================================================
-// ============================================================================
-// AgentSession Class
-// ============================================================================
 export class AgentSession {
     agent;
     sessionManager;
@@ -100,10 +104,13 @@ export class AgentSession {
     _followUpMessages = [];
     /** Messages queued to be included with the next user prompt as context ("asides"). */
     _pendingNextTurnMessages = [];
+    /** Context-only custom messages queued during a run, flushed once the current turn's tool results are in. */
+    _pendingCustomMessages = [];
     // Compaction state
     _compactionAbortController = undefined;
     _autoCompactionAbortController = undefined;
     _overflowRecoveryAttempted = false;
+    _midRunCompactionNeeded = false;
     // Branch summarization state
     _branchSummaryAbortController = undefined;
     // Retry state
@@ -119,6 +126,21 @@ export class AgentSession {
     _customTools;
     _baseToolDefinitions = new Map();
     _cwd;
+    /**
+     * Workspace observation adapter for compaction capture (WS.4). Injectable
+     * so tests can force capture outcomes without a real repository.
+     */
+    _workspaceObserver = observeWorkspaceGit;
+    /**
+     * WS.5: one workspace comparison is due at the next model-turn boundary.
+     * Set after a compaction stored an observation, or on construction when
+     * the session's latest observation has no later comparison (resume).
+     */
+    _workspaceComparePending = false;
+    /** VF.4: verification lifecycle state, built lazily from policy settings. */
+    _verificationTracker;
+    /** The workspace observation a verification result described, for staleness. */
+    _verificationBaseline;
     _extensionRunnerRef;
     _initialActiveToolNames;
     _allowedToolNames;
@@ -129,6 +151,19 @@ export class AgentSession {
     _evidenceSink;
     _diagnosticsOperations;
     _lspOperations;
+    _mcpRuntime;
+    /** Configured MCP subsystem, or undefined when no server is configured. */
+    get mcpRuntime() {
+        return this._mcpRuntime;
+    }
+    _checkpoints;
+    _hookRuntime;
+    _backgroundShellRegistry;
+    _permissionResponderFactory;
+    /** Worktree checkpoints for this session. Inert unless `checkpoints.enabled` is set. */
+    get checkpoints() {
+        return this._checkpoints;
+    }
     _webSearchOperations;
     _extensionUIContext;
     _extensionMode = "print";
@@ -167,13 +202,33 @@ export class AgentSession {
         this._evidenceSink = config.evidenceSink ?? new SessionEvidenceSink(this.sessionManager);
         this._diagnosticsOperations = config.diagnosticsOperations;
         this._lspOperations = config.lspOperations;
+        this._mcpRuntime = config.mcpRuntime;
         this._webSearchOperations = config.webSearchOperations;
+        this._checkpoints = createSessionCheckpoints({
+            workspace: this._cwd,
+            sessionId: this.sessionManager.getSessionId(),
+            settings: config.checkpointSettings,
+        });
+        this._hookRuntime = config.hookRuntime;
+        this._backgroundShellRegistry = config.backgroundShellRegistry;
+        this._permissionResponderFactory = config.permissionResponderFactory;
+        this._workspaceComparePending = hasWorkspaceObservationAwaitingComparison(this.sessionManager);
         // Always subscribe to agent events for internal handling
         // (session persistence, extensions, auto-compaction, retry logic)
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
         this._installAgentToolHooks();
         this._installAgentNextTurnRefresh();
+        this._installMidRunCompactionHook();
         this._installContextPipeline();
+        // Declarative hooks: session_start is observe-only and must neither delay
+        // nor fail construction, so it fires detached (emitObserve swallows
+        // handler failures already).
+        if (this._hookRuntime?.hasHandlers("session_start")) {
+            void this._hookRuntime.emitObserve("session_start", {
+                type: "session_start",
+                reason: this._sessionStartEvent.reason,
+            });
+        }
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
             includeAllExtensionTools: true,
@@ -264,6 +319,20 @@ export class AgentSession {
                 if (extensionResult?.block === true)
                     return extensionResult;
             }
+            // Declarative hooks (spec 2026-08-31-declarative-hooks) ride the same
+            // seam, after extensions and before the gate. Restriction-only: a block
+            // short-circuits, allow and ask fall through, and the gate below still
+            // evaluates the call, so a hook can narrow authority but never widen it.
+            if (this._hookRuntime?.hasHandlers("tool_call")) {
+                const hookBlock = await this._hookRuntime.decideToolCall(toolCall.name, {
+                    type: "tool_call",
+                    toolName: toolCall.name,
+                    toolCallId: toolCall.id,
+                    input: args,
+                });
+                if (hookBlock)
+                    return { block: true, reason: hookBlock.reason };
+            }
             // Permission gate (roadmap Phase 2a, ADR 0004). Off by default — see
             // AgentSessionConfig.permissionGate. When present, every registered tool
             // call passes through it (contracts.md invariant 2): this is the seam,
@@ -272,9 +341,10 @@ export class AgentSession {
                 const decision = await evaluateToolCall(toolCall.name, args, {
                     ...this._permissionGate,
                     getContract: (name) => this.getToolDefinition(name)?.contract,
-                    getResponder: () => this._extensionMode === "tui" && this._extensionUIContext
-                        ? createInteractiveResponder(this._extensionUIContext)
-                        : undefined,
+                    getResponder: () => this._permissionResponderFactory?.() ??
+                        (this._extensionMode === "tui" && this._extensionUIContext
+                            ? createInteractiveResponder(this._extensionUIContext)
+                            : undefined),
                 });
                 if (decision.block)
                     return { block: true, reason: decision.reason };
@@ -312,6 +382,16 @@ export class AgentSession {
                     usage: result.usage,
                 })
                 : undefined;
+            // Declarative hooks observe tool results after extension rewrites and
+            // before image normalization; no decision is read from them (spec).
+            if (this._hookRuntime?.hasHandlers("tool_result")) {
+                await this._hookRuntime.emitObserve("tool_result", {
+                    type: "tool_result",
+                    toolName: toolCall.name,
+                    toolCallId: toolCall.id,
+                    input: args,
+                });
+            }
             const content = hookResult?.content ?? result.content ?? [];
             // Runs after the extension hook so images injected or replaced by extensions are normalized too.
             const normalizedContent = await normalizeToolResultImages(content, {
@@ -328,18 +408,33 @@ export class AgentSession {
             };
         };
     }
+    async _compactBeforeNextAssistantResponse(context) {
+        const model = this.model;
+        const settings = this.settingsManager.getCompactionSettings();
+        if (!model ||
+            model.contextWindow <= 0 ||
+            !shouldCompact(estimateContextTokens(context.messages).tokens, model.contextWindow, settings)) {
+            return context;
+        }
+        await this._runAutoCompaction("threshold", false);
+        return {
+            ...context,
+            messages: this.agent.state.messages.slice(),
+        };
+    }
     _installAgentNextTurnRefresh() {
         const previousPrepareNextTurnWithContext = this.agent.prepareNextTurnWithContext ??
             (this.agent.prepareNextTurn
                 ? async (_turn, signal) => await this.agent.prepareNextTurn?.(signal)
                 : undefined);
         this.agent.prepareNextTurnWithContext = async (turn, signal) => {
-            const previousSnapshot = await previousPrepareNextTurnWithContext?.(turn, signal);
-            const previousContext = previousSnapshot?.context ?? turn.context;
+            const context = await this._compactBeforeNextAssistantResponse(turn.context);
+            const previousSnapshot = await previousPrepareNextTurnWithContext?.({ ...turn, context }, signal);
+            const nextContext = previousSnapshot?.context ?? context;
             return {
                 ...previousSnapshot,
                 context: {
-                    ...previousContext,
+                    ...nextContext,
                     systemPrompt: this._systemPromptOverride ?? this._baseSystemPrompt,
                     tools: this.agent.state.tools.slice(),
                 },
@@ -348,6 +443,35 @@ export class AgentSession {
             };
         };
     }
+    /** Stop an over-threshold tool loop before it sends another provider request. */
+    _installMidRunCompactionHook() {
+        const previousShouldStopAfterTurn = this.agent.shouldStopAfterTurn;
+        this.agent.shouldStopAfterTurn = async (turn, signal) => {
+            if (await previousShouldStopAfterTurn?.(turn, signal)) {
+                return true;
+            }
+            return this._shouldStopForMidRunCompaction(turn);
+        };
+    }
+    _shouldStopForMidRunCompaction(turn) {
+        if (!turn.hasMoreToolCalls || turn.toolResults.length === 0) {
+            return false;
+        }
+        const settings = this.settingsManager.getCompactionSettings();
+        if (!settings.enabled) {
+            return false;
+        }
+        const contextWindow = this.model?.contextWindow ?? 0;
+        if (contextWindow <= 0) {
+            return false;
+        }
+        const contextTokens = estimateContextTokens(turn.context.messages).tokens;
+        if (!shouldCompact(contextTokens, contextWindow, settings)) {
+            return false;
+        }
+        this._midRunCompactionNeeded = true;
+        return true;
+    }
     /**
      * Installs the context pipeline settled in `docs/architecture/contracts.md` § 2:
      * deferred-schema resolution → tool-result eviction → compaction. Compaction
@@ -499,6 +623,14 @@ export class AgentSession {
                 }
             }
         }
+        // A turn ends after its assistant message and every tool result has been appended,
+        // so this is the first point in the run where a context-only custom message can be
+        // inserted without landing between a tool call and its result. Flushing after the
+        // extension and listener dispatch above also picks up messages that turn_end
+        // handlers queued.
+        if (event.type === "turn_end") {
+            this._flushPendingCustomMessages();
+        }
     };
     _willRetryAfterAgentEnd(event) {
         const settings = this.settingsManager.getRetrySettings();
@@ -548,6 +680,18 @@ export class AgentSession {
             await this._extensionRunner.emit({ type: "agent_end", messages: event.messages });
         }
         else if (event.type === "turn_start") {
+            // Snapshot before the model gets to act, keyed to the entry `/tree` and `/fork`
+            // already navigate to, so the two agree about what an entry means.
+            //
+            // Awaited, despite the turn latency. Detached, the snapshot races the turn it is
+            // supposed to precede: a tool call can edit the worktree while `add -A` is still
+            // walking it, and the ref then holds mid-turn state that no `/fork` should ever
+            // restore. "The state before the model acted" is the whole guarantee, so paying
+            // for it here is the point. The engine's own timeout bounds the wait and a failed
+            // capture is never fatal.
+            const leafEntryId = this.sessionManager.getLeafEntry()?.id;
+            if (leafEntryId)
+                await this._checkpoints.capture(leafEntryId);
             const extensionEvent = {
                 type: "turn_start",
                 turnIndex: this._turnIndex,
@@ -563,6 +707,9 @@ export class AgentSession {
                 toolResults: event.toolResults,
             };
             await this._extensionRunner.emit(extensionEvent);
+            if (this._hookRuntime?.hasHandlers("turn_end")) {
+                await this._hookRuntime.emitObserve("turn_end", { type: "turn_end" });
+            }
             this._turnIndex++;
         }
         else if (event.type === "message_start") {
@@ -662,6 +809,9 @@ export class AgentSession {
             this.abortBranchSummary();
             this.abortBash();
             this.agent.abort();
+            // Background shell children (spec 2026-08-31-background-shell.md) must
+            // never outlive the session that launched them.
+            this._backgroundShellRegistry?.dispose();
         }
         catch {
             // Dispose must succeed even if an abort hook throws.
@@ -669,6 +819,9 @@ export class AgentSession {
         this._extensionRunner.invalidate("This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().");
         this._disconnectFromAgent();
         this._eventListeners = [];
+        // Every connected MCP server is a child process this session started. Without
+        // this, one leaks per server per session, because nothing else owns them.
+        this._mcpRuntime?.close().catch(() => undefined);
         cleanupSessionResources(this.sessionId);
     }
     // =========================================================================
@@ -712,6 +865,13 @@ export class AgentSession {
     /**
      * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
      */
+    /**
+     * The ADR 0010 projection over this session's registry: the one read every surface
+     * that *describes* the tool set consumes. Never an authorization input.
+     */
+    getToolContractSnapshot() {
+        return buildToolContractSnapshot(Array.from(this._toolDefinitions.values()).map(({ definition }) => definition));
+    }
     getAllTools() {
         const schemaToolActive = this.getActiveToolNames().includes("tool_schema");
         return Array.from(this._toolDefinitions.values())
@@ -722,7 +882,7 @@ export class AgentSession {
             parameters: definition.parameters,
             promptGuidelines: definition.promptGuidelines,
             sourceInfo,
-            unclassified: !("contract" in definition),
+            unclassified: isUnclassifiedTool(definition),
         }));
     }
     getToolDefinition(name) {
@@ -858,10 +1018,15 @@ export class AgentSession {
         finally {
             this._systemPromptOverride = undefined;
             this._flushPendingBashMessages();
+            this._flushPendingCustomMessages();
             await this._emitAgentSettled();
         }
     }
     async _handlePostAgentRun() {
+        if (this._midRunCompactionNeeded) {
+            this._midRunCompactionNeeded = false;
+            return await this._runAutoCompaction("threshold", true);
+        }
         const msg = this._lastAssistantMessage;
         this._lastAssistantMessage = undefined;
         if (!msg) {
@@ -947,8 +1112,9 @@ export class AgentSession {
                 preflightResult?.(true);
                 return;
             }
-            // Flush any pending bash messages before the new prompt
+            // Flush any pending bash and custom messages before the new prompt
             this._flushPendingBashMessages();
+            this._flushPendingCustomMessages();
             // Validate model
             if (!this.model) {
                 throw new Error(formatNoModelSelectedMessage());
@@ -1022,7 +1188,9 @@ export class AgentSession {
             return;
         }
         preflightResult?.(true);
+        await this._runWorkspaceComparisonBoundary();
         await this._runAgentPrompt(messages);
+        await this._runVerificationTurnBoundary();
     }
     /**
      * Try to execute an extension command. Returns true if command was found and executed.
@@ -1169,8 +1337,9 @@ export class AgentSession {
     /**
      * Send a custom message to the session. Creates a CustomMessageEntry.
      *
-     * Handles three cases:
+     * Handles four cases:
      * - Streaming: queues message, processed when loop pulls from queue
+     * - Streaming + triggerTurn false: appended to state/session once the current turn ends
      * - Not streaming + triggerTurn: appends to state/session, starts new turn
      * - Not streaming + no trigger: appends to state/session, no turn
      *
@@ -1202,11 +1371,34 @@ export class AgentSession {
         else if (options?.triggerTurn) {
             await this._runAgentPrompt(appMessage);
         }
+        else if (this.isStreaming) {
+            // Appending now would put the message between an assistant tool call and its
+            // result, which providers that validate message order reject on replay. Defer
+            // to the end of the turn. Nothing is emitted yet: message events must not
+            // describe messages the session tree does not contain.
+            this._pendingCustomMessages.push(appMessage);
+        }
         else {
-            this.agent.state.messages.push(appMessage);
-            this.sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
-            this._emit({ type: "message_start", message: appMessage });
-            this._emit({ type: "message_end", message: appMessage });
+            this._appendCustomMessage(appMessage);
+        }
+    }
+    _appendCustomMessage(appMessage) {
+        this.agent.state.messages.push(appMessage);
+        this.sessionManager.appendCustomMessageEntry(appMessage.customType, appMessage.content, appMessage.display, appMessage.details);
+        this._emit({ type: "message_start", message: appMessage });
+        this._emit({ type: "message_end", message: appMessage });
+    }
+    /**
+     * Append custom messages queued while the agent was running.
+     * Called once the current turn's tool results are in agent state and session history.
+     */
+    _flushPendingCustomMessages() {
+        if (this._pendingCustomMessages.length === 0)
+            return;
+        const pending = this._pendingCustomMessages;
+        this._pendingCustomMessages = [];
+        for (const appMessage of pending) {
+            this._appendCustomMessage(appMessage);
         }
     }
     /**
@@ -1345,6 +1537,7 @@ export class AgentSession {
         this.sessionManager.appendModelChange(model.provider, model.id);
         if (options.persist) {
             this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
+            this._addPersistedDefaultToNonEmptyScope(model);
         }
         // Apply thinking level for the new model.
         // Per-model thinking level overrides take priority over the global default.
@@ -1352,6 +1545,20 @@ export class AgentSession {
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(model, previousModel, "set");
     }
+    _addPersistedDefaultToNonEmptyScope(model) {
+        if (this._scopedModels.length === 0)
+            return;
+        if (this._scopedModels.some((scoped) => modelsAreEqual(scoped.model, model)))
+            return;
+        this._scopedModels = [...this._scopedModels, { model }];
+        const enabledModels = this.settingsManager.getEnabledModels();
+        if (!enabledModels?.length)
+            return;
+        const modelReference = `${model.provider}/${model.id}`;
+        if (enabledModels.some((pattern) => pattern.toLowerCase() === modelReference.toLowerCase()))
+            return;
+        this.settingsManager.setEnabledModels([...enabledModels, modelReference]);
+    }
     /**
      * Cycle to next/previous model.
      * Uses scoped models (from --models flag) if available, otherwise all available models.
@@ -1382,6 +1589,7 @@ export class AgentSession {
         this.sessionManager.appendModelChange(next.model.provider, next.model.id);
         if (options.persist) {
             this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
+            this._addPersistedDefaultToNonEmptyScope(next.model);
         }
         // Apply thinking level for the new model.
         // - Explicit scoped model thinking level overrides defaults
@@ -1408,6 +1616,7 @@ export class AgentSession {
         this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
         if (options.persist) {
             this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
+            this._addPersistedDefaultToNonEmptyScope(nextModel);
         }
         // Apply thinking level for the new model.
         // Model persistence does not implicitly rewrite the global thinking default.
@@ -1516,7 +1725,209 @@ export class AgentSession {
     // Compaction
     // =========================================================================
     /** Generate Pi's built-in compaction summary for manual and automatic compaction. */
+    /**
+     * Attempt exactly one workspace observation for a compaction (spec
+     * 2026-09-01-harness-correctness-and-workspace-state.md § 3 step 1).
+     * Returns undefined when observation is impossible; never throws and
+     * never fails the surrounding compaction.
+     */
+    async _captureWorkspaceObservation(signal) {
+        try {
+            return await this._workspaceObserver(this._cwd, {
+                signal,
+                // The session's own state directory is harness bookkeeping, not
+                // workspace content; observing it would report every turn as drift.
+                excludePaths: this._sessionExclusionPaths(),
+            });
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Session/artifact directories inside the workspace, relative paths. */
+    _sessionExclusionPaths() {
+        const exclusions = [];
+        const sessionDir = this.sessionManager.getSessionDir();
+        if (sessionDir) {
+            const rel = relative(this._cwd, sessionDir);
+            if (rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel))
+                exclusions.push(rel);
+        }
+        // Harness runtime bookkeeping (auth, model store, durable state) is
+        // not workspace content either: when the agent directory sits inside
+        // the workspace, its runtime files would report every turn as drift.
+        // Same rule and same name list the fork/workspace fingerprints use.
+        const agentDir = this.settingsManager.getAgentDir();
+        if (agentDir !== undefined) {
+            const rel = relative(this._cwd, agentDir);
+            if (rel === "") {
+                exclusions.push("auth.json", "models-store.json", "state.sqlite");
+            }
+            else if (rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel)) {
+                exclusions.push(rel);
+            }
+        }
+        return exclusions;
+    }
+    // ── VF.4: verification lifecycle (spec
+    // 2026-09-01-configured-verification-and-formatting.md § 4) ──────────
+    /**
+     * Build (once) and refresh the tracker from the raw per-source policy
+     * settings. ADR 0028: the loader consumes the sources separately and the
+     * trust gate decides whether the project source exists at all.
+     */
+    /**
+     * PS.1. Configured commands reach the same permission authority tool calls
+     * use. Undefined only when the session has no gate at all, which is the
+     * documented SDK default; a gated session always authorizes.
+     */
+    _authorizeConfiguredCommand() {
+        const gate = this._permissionGate;
+        if (gate === undefined)
+            return undefined;
+        return (operation) => authorizeConfiguredCommand(operation, {
+            getMode: gate.getMode,
+            getResponder: () => this._permissionResponderFactory?.() ??
+                (this._extensionMode === "tui" && this._extensionUIContext
+                    ? createInteractiveResponder(this._extensionUIContext)
+                    : undefined),
+        });
+    }
+    _ensureVerificationTracker() {
+        if (this._verificationTracker === undefined) {
+            this._verificationTracker = new VerificationTracker({
+                workspaceRoot: this._cwd,
+                ...(this._authorizeConfiguredCommand() !== undefined
+                    ? { authorize: this._authorizeConfiguredCommand() }
+                    : {}),
+            });
+        }
+        const snapshot = loadPolicyConfiguration({
+            globalSettings: this.settingsManager.getGlobalSettings().policies,
+            projectSettings: this.settingsManager.getProjectSettings().policies,
+            projectTrusted: this.settingsManager.isProjectTrusted(),
+        });
+        const boundary = this.settingsManager.getPolicySettings()?.boundary === "post-turn" ? "post-turn" : "explicit";
+        this._verificationTracker.configure(snapshot.verification, boundary);
+        return this._verificationTracker;
+    }
+    /**
+     * Run one configured verification policy now and report the resulting
+     * completion status. Unavailable when nothing is configured; the
+     * workspace observation after the run becomes the staleness baseline.
+     */
+    async requestVerification(options = {}) {
+        const tracker = this._ensureVerificationTracker();
+        if (tracker.policyIds().length === 0) {
+            return "unavailable";
+        }
+        const record = await tracker.runExplicit(options.policyId, { signal: options.signal });
+        if (record !== undefined) {
+            this._verificationBaseline = await this._captureWorkspaceObservation(options.signal);
+        }
+        return this.verificationStatus();
+    }
+    /**
+     * VF.5: run one configured formatter policy now and report what it
+     * actually mutated. Undefined when no formatter policy matches. Any real
+     * mutation retires a prior verification record: the workspace the
+     * verification described no longer exists.
+     */
+    async runConfiguredFormatter(options = {}) {
+        const snapshot = loadPolicyConfiguration({
+            globalSettings: this.settingsManager.getGlobalSettings().policies,
+            projectSettings: this.settingsManager.getProjectSettings().policies,
+            projectTrusted: this.settingsManager.isProjectTrusted(),
+        });
+        const policy = options.policyId === undefined
+            ? snapshot.formatter[0]
+            : snapshot.formatter.find((entry) => entry.id === options.policyId);
+        if (policy === undefined)
+            return undefined;
+        const authorize = this._authorizeConfiguredCommand();
+        const outcome = await runFormatterCommand(policy, {
+            workspaceRoot: this._cwd,
+            signal: options.signal,
+            ...(authorize !== undefined ? { authorize } : {}),
+        });
+        if (outcome.mutations.changedPaths.length > 0) {
+            this._verificationTracker?.noteWorkspaceChange(new Set(outcome.mutations.changedPaths));
+        }
+        return outcome;
+    }
+    /** The current completion status: verified, failed, unavailable, interrupted, or continued-unverified. */
+    verificationStatus() {
+        return this._verificationTracker?.completionStatus() ?? "unavailable";
+    }
+    /** The live verification record with its bounded evidence, if any. */
+    verificationRecord() {
+        return this._verificationTracker?.latest();
+    }
+    /** Record that the user chose to finish without verification. */
+    continueWithoutVerification() {
+        this._ensureVerificationTracker().recordContinuedWithoutVerification();
+    }
+    /**
+     * Turn boundary: retire a verification result the workspace has moved
+     * past (conservatively — anything not provably "same" retires it), then
+     * run the configured post-turn boundary. Never throws: verification is
+     * advisory and the turn already completed.
+     */
+    async _runVerificationTurnBoundary() {
+        let tracker = this._verificationTracker;
+        if (tracker === undefined) {
+            tracker = this._ensureVerificationTracker();
+        }
+        try {
+            if (tracker.latest() !== undefined) {
+                const fresh = await this._captureWorkspaceObservation(undefined);
+                if (this._verificationBaseline === undefined) {
+                    tracker.noteWorkspaceChange(new Set(["unbaseline"]));
+                }
+                else {
+                    const comparison = compareWorkspaceObservations(this._verificationBaseline, fresh);
+                    tracker.noteWorkspaceChange(comparison.result === "same" ? new Set() : new Set(["workspace-changed"]));
+                }
+            }
+            if (tracker.boundary === "post-turn" && tracker.policyIds().length > 0) {
+                await tracker.runExplicit();
+                this._verificationBaseline = await this._captureWorkspaceObservation(undefined);
+            }
+        }
+        catch {
+            // Verification is advisory; the turn already completed.
+        }
+    }
+    /**
+     * WS.5 (spec 2026-09-01-harness-correctness-and-workspace-state.md § 3):
+     * at the first model turn after a compaction, or after resume onto a
+     * session with an uncompared observation, compare fresh workspace state
+     * against the stored observation once and persist the outcome. The
+     * observation stays historical. Never throws: comparison problems must
+     * not fail the user's turn.
+     */
+    async _runWorkspaceComparisonBoundary() {
+        if (!this._workspaceComparePending)
+            return;
+        this._workspaceComparePending = false;
+        try {
+            const baseline = findLatestWorkspaceObservation(this.sessionManager);
+            if (!baseline)
+                return;
+            const fresh = await this._captureWorkspaceObservation(undefined);
+            const outcome = compareWorkspaceObservations(baseline.record, fresh);
+            appendWorkspaceComparison(this.sessionManager, buildWorkspaceComparison(baseline.record.observationId, outcome));
+        }
+        catch {
+            // Comparison is advisory; the turn proceeds.
+        }
+    }
     async _runDefaultCompaction(preparation, requestModel, apiKey, headers, customInstructions, signal, env, reason) {
+        // Maintenance budget (spec 2026-09-01-tool-reliability-and-execution-budgets.md):
+        // a compaction summarization is context maintenance, not task progress. It is
+        // recorded on the run's budget for observability and never consumes
+        // maxProviderRequests.
+        this.agent.recordMaintenanceRequest();
         return compact(preparation, requestModel, apiKey, headers, customInstructions, signal, this.thinkingLevel, this.agent.streamFunction, env, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }), undefined);
     }
     /**
@@ -1556,6 +1967,12 @@ export class AgentSession {
                 throw new Error("Nothing to compact (session too small)");
             }
             let extensionCompaction;
+            if (this._hookRuntime?.hasHandlers("session_before_compact")) {
+                await this._hookRuntime.emitObserve("session_before_compact", {
+                    type: "session_before_compact",
+                    reason: "manual",
+                });
+            }
             if (this._extensionRunner.hasHandlers("session_before_compact")) {
                 const result = (await this._extensionRunner.emit({
                     type: "session_before_compact",
@@ -1579,6 +1996,12 @@ export class AgentSession {
             let tokensBefore;
             let usage;
             let details;
+            // One workspace observation attempt per compaction (spec
+            // 2026-09-01-harness-correctness-and-workspace-state.md § 3),
+            // before summary generation so the bounded projection can join
+            // the model-facing summary. Capture problems never fail the
+            // compaction.
+            const workspaceRecord = await this._captureWorkspaceObservation(this._compactionAbortController?.signal ?? this._autoCompactionAbortController?.signal);
             if (extensionCompaction) {
                 // Extension provided compaction content
                 summary = extensionCompaction.summary;
@@ -1595,11 +2018,28 @@ export class AgentSession {
                 tokensBefore = result.tokensBefore;
                 usage = result.usage;
                 details = result.details;
+                if (workspaceRecord) {
+                    summary += `\n\n${formatWorkspaceProjection(workspaceRecord)}`;
+                }
             }
             if (this._compactionAbortController.signal.aborted) {
                 throw new Error("Compaction cancelled");
             }
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
+            if (workspaceRecord) {
+                try {
+                    // Historical record, child of the compaction entry; never in
+                    // the model context and never a rewrite of history.
+                    appendWorkspaceObservation(this.sessionManager, workspaceRecord);
+                    // WS.5: the next model turn compares fresh state against
+                    // this observation and records the drift outcome.
+                    this._workspaceComparePending = true;
+                }
+                catch {
+                    // Artifact/entry persistence problems downgrade the
+                    // workspace status; they never fail transcript compaction.
+                }
+            }
             const newEntries = this.sessionManager.getEntries();
             const sessionContext = this.sessionManager.buildSessionContext();
             this.agent.state.messages = sessionContext.messages;
@@ -1817,6 +2257,9 @@ export class AgentSession {
             this._autoCompactionAbortController = new AbortController();
             started = true;
             let extensionCompaction;
+            if (this._hookRuntime?.hasHandlers("session_before_compact")) {
+                await this._hookRuntime.emitObserve("session_before_compact", { type: "session_before_compact", reason });
+            }
             if (this._extensionRunner.hasHandlers("session_before_compact")) {
                 const extensionResult = (await this._extensionRunner.emit({
                     type: "session_before_compact",
@@ -1853,6 +2296,12 @@ export class AgentSession {
             let tokensBefore;
             let usage;
             let details;
+            // One workspace observation attempt per compaction (spec
+            // 2026-09-01-harness-correctness-and-workspace-state.md § 3),
+            // before summary generation so the bounded projection can join
+            // the model-facing summary. Capture problems never fail the
+            // compaction.
+            const workspaceRecord = await this._captureWorkspaceObservation(this._compactionAbortController?.signal ?? this._autoCompactionAbortController?.signal);
             if (extensionCompaction) {
                 // Extension provided compaction content
                 summary = extensionCompaction.summary;
@@ -1869,6 +2318,9 @@ export class AgentSession {
                 tokensBefore = compactResult.tokensBefore;
                 usage = compactResult.usage;
                 details = compactResult.details;
+                if (workspaceRecord) {
+                    summary += `\n\n${formatWorkspaceProjection(workspaceRecord)}`;
+                }
             }
             if (this._autoCompactionAbortController.signal.aborted) {
                 this._emit({
@@ -1887,6 +2339,20 @@ export class AgentSession {
                 return false;
             }
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension, usage);
+            if (workspaceRecord) {
+                try {
+                    // Historical record, child of the compaction entry; never in
+                    // the model context and never a rewrite of history.
+                    appendWorkspaceObservation(this.sessionManager, workspaceRecord);
+                    // WS.5: the next model turn compares fresh state against
+                    // this observation and records the drift outcome.
+                    this._workspaceComparePending = true;
+                }
+                catch {
+                    // Artifact/entry persistence problems downgrade the
+                    // workspace status; they never fail transcript compaction.
+                }
+            }
             const newEntries = this.sessionManager.getEntries();
             const sessionContext = this.sessionManager.buildSessionContext();
             this.agent.state.messages = sessionContext.messages;
@@ -2260,10 +2726,15 @@ export class AgentSession {
             ]))
             : createAllToolDefinitions(this._cwd, {
                 read: { autoResizeImages },
-                bash: { commandPrefix: shellCommandPrefix, shellPath },
+                bash: {
+                    commandPrefix: shellCommandPrefix,
+                    shellPath,
+                    backgroundRegistry: this._backgroundShellRegistry,
+                },
                 edit: { diagnosticsOperations: this._diagnosticsOperations },
                 write: { diagnosticsOperations: this._diagnosticsOperations },
                 ...(this._lspOperations ? { lsp: { operations: this._lspOperations } } : {}),
+                ...(this._mcpRuntime ? { mcp: this._mcpRuntime } : {}),
                 ...(this._webSearchOperations ? { web_search: { operations: this._webSearchOperations } } : {}),
             });
         baseToolDefinitions.tool_schema = createToolSchemaToolDefinition({
@@ -2575,6 +3046,13 @@ export class AgentSession {
         if (targetId === oldLeafId) {
             return { cancelled: false };
         }
+        // WS.6 (spec 2026-09-01-harness-correctness-and-workspace-state.md § 4):
+        // files move only under an explicit policy, and a refused or cancelled
+        // restore leaves the conversation untouched too.
+        const workspaceStep = await this._resolveTreeWorkspaceStep(targetId, options.workspacePolicy ?? "keep");
+        if (workspaceStep.cancelled) {
+            return { cancelled: true, workspace: workspaceStep.outcome };
+        }
         // Model required for summarization
         if (options.summarize && !this.model) {
             throw new Error("No model available for summarization");
@@ -2721,12 +3199,77 @@ export class AgentSession {
                 fromExtension: summaryText ? fromExtension : undefined,
             });
             // Emit to custom tools
-            return { editorText, cancelled: false, summaryEntry };
+            return { editorText, cancelled: false, summaryEntry, workspace: workspaceStep.outcome };
         }
         finally {
             this._branchSummaryAbortController = undefined;
         }
     }
+    /**
+     * WS.6: resolve what navigation may do to the workspace before the
+     * conversation moves. `keep` never touches files; `restore` overwrites
+     * only through the engine's pinned pre-restore checkpoint; `fail-if-
+     * drifted` and `cancel` refuse when the workspace moved; a missing
+     * checkpoint leaves the workspace unchanged and says so. Never throws.
+     */
+    async _resolveTreeWorkspaceStep(targetId, policy) {
+        const unchanged = { policy, outcome: "unchanged", warnings: [] };
+        if (policy === "keep")
+            return { outcome: unchanged };
+        try {
+            const engine = await this._checkpoints.engine();
+            if (!engine) {
+                return {
+                    outcome: {
+                        policy,
+                        outcome: "missing-checkpoint",
+                        warnings: ["checkpoints are unavailable; workspace left unchanged"],
+                    },
+                };
+            }
+            const checkpoint = await engine.lookup(targetId);
+            if (!checkpoint)
+                return { outcome: { policy, outcome: "missing-checkpoint", warnings: [] } };
+            const matches = await engine.matchesWorktree(checkpoint);
+            if (matches === undefined) {
+                return {
+                    outcome: {
+                        policy,
+                        outcome: "failed",
+                        warnings: ["could not compare the workspace against the checkpoint"],
+                    },
+                };
+            }
+            if (matches)
+                return { outcome: unchanged };
+            if (policy === "fail-if-drifted" || policy === "cancel") {
+                return { cancelled: true, outcome: { policy, outcome: "refused-drifted", warnings: [] } };
+            }
+            const preRestore = await engine.restore(checkpoint);
+            if (!preRestore) {
+                return {
+                    outcome: { policy, outcome: "failed", warnings: ["restore failed; workspace left unchanged"] },
+                };
+            }
+            return {
+                outcome: {
+                    policy,
+                    outcome: "restored",
+                    preRestoreCheckpoint: { entryId: preRestore.entryId, commit: preRestore.commit },
+                    warnings: [],
+                },
+            };
+        }
+        catch (error) {
+            return {
+                outcome: {
+                    policy,
+                    outcome: "failed",
+                    warnings: [`workspace policy check failed: ${error instanceof Error ? error.message : String(error)}`],
+                },
+            };
+        }
+    }
     /**
      * Get all user messages from session for fork selector.
      */