@superblocksteam/vite-plugin-file-sync 2.0.166 → 2.0.168-next.0

package/dist/ai-service/index.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
-import { context as otelContext, propagation, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { context as otelContext, metrics, propagation, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
 import { hasToolCall, stepCountIs, } from "ai";
 import { z } from "zod";
 import { AiGenerationState, AiMode, resolveAttachmentFileName, } from "@superblocksteam/library-shared/types";
@@ -12,10 +12,12 @@ import { applyTestApiDenialSideEffects, buildMigrationTestApiDenialContinuationP
 import { buildTranslationPrompt } from "../migration/translation-prompt.js";
 import { POLICY_GATE_RUN_IN_PROGRESS_ERROR, policyGateRunRegistry, } from "../policy-gate-run-registry.js";
 import { getErrorMeta, getLogger, setDefaultLogger } from "../util/logger.js";
+import { OperationQueue } from "../util/operation-queue.js";
 import { composeSecurityAgentPrompt, } from "./agent/prompts/build-security-scan-prompt.js";
 import { getToolCallArguments, getToolErrorCode, getToolErrorMessage, getToolOutput, } from "./agent/tool-message-utils.js";
 import { recordToolPermissionDeliveryOutcome } from "./agent/tool-permission-delivery-metrics.js";
 import { createExpiredPermissionPromptDeliveryError, flushPendingToolPermissionPrompt, inFlightToolPermissionReplay, } from "./agent/tool-permission-delivery.js";
+import { recordToolPermissionLateOutcome } from "./agent/tool-permission-outcome-metrics.js";
 import { buildSecurityScanTools, isBackgroundTaskFrameworkEnabled, } from "./agent/tools.js";
 import { hasPendingEscalations, flushPendingEscalations, } from "./agent/tools/apis/api-validation-orchestrator.js";
 import { safeSampleJson } from "./agent/tools/apis/sample-json.js";
@@ -37,7 +39,8 @@ import { isUploadedAttachment, toUploadedAttachmentContentPart, } from "./attach
 import { recordChatSessionIdLookup } from "./chat/chat-session-store-metrics.js";
 import { ChatSessionStore } from "./chat/chat-session-store.js";
 import { normalizeTextAttachmentForModel } from "./chat/utils.js";
-import { API_MIGRATION_ORIGINS, isApiMigrationOrigin, readPersistedChecklist, updateChecklistItem, } from "./checklist/persisted-checklist-store.js";
+import { API_MIGRATION_ORIGINS, cancelPolicyRemediation, seedPolicyRemediationChecklist, isApiMigrationOrigin, readPersistedChecklist, readRemediationRun, updateChecklistItem, advancePolicyRemediationTurn, MAX_REMEDIATION_TURNS, failPolicyRemediationDispatch, } from "./checklist/persisted-checklist-store.js";
+import { fetchRemediationFindings } from "./checklist/remediation-findings-client.js";
 import { downloadContextFromBucketeer, downloadLatestContextFromBucketeer, restoreContextFromCheckpoint, } from "./context-download.js";
 import { restoreConversationToCheckpoint, } from "./context-restore.js";
 import { uploadContextToBucketeer } from "./context-upload.js";
@@ -63,6 +66,8 @@ import { ContextManagerV2 } from "./llm/context-v2/manager.js";
 import { JsonlEventStore } from "./llm/context-v2/storage/jsonl-event-store.js";
 import { adoptLegacyPerUserContextDirs } from "./llm/context-v2/storage/legacy-context-adoption.js";
 import { LocalContextStorageV2 } from "./llm/context-v2/storage/local.js";
+import { buildRestoredContextUsageSnapshot } from "./llm/context-v2/token-tracker.js";
+import { toJsonValue, } from "./llm/context-v2/types.js";
 import { createLLMProvider, setSpanError } from "./llm/provider.js";
 import { createAbortReason } from "./llm/stream/abort-reason.js";
 import { getJwtTraceTags, traceLLM } from "./llmobs/helpers.js";
@@ -86,7 +91,7 @@ import { RequestDeduplicator } from "./request-deduplicator.js";
 import { resolveGenerationStateForUi } from "./resolve-generation-state-for-ui.js";
 import { scanContentForSecrets } from "./security/secret-scanner-service.js";
 import { SecretRedactor } from "./security/secret-scanner.js";
-import { ClarkStateNames, Clark, SERVICE_STARTED_WITH_DRAFT, USER_ACCEPTED_DRAFT, USER_REJECTED_DRAFT, USER_SENT_PROMPT, USER_CANCELED, AGENT_CANCELED, } from "./state-machine/clark-fsm.js";
+import { ClarkStateNames, Clark, SERVICE_STARTED_WITH_DRAFT, USER_ACCEPTED_DRAFT, USER_REJECTED_DRAFT, USER_SENT_PROMPT, USER_CANCELED, AGENT_CANCELED, APP_RUNTIME_UPDATED_WITHOUT_EDITS, RUNTIME_REVIEW_FINISHED, V3_AGENT_FINISHED, } from "./state-machine/clark-fsm.js";
 import { doAgentPlanning } from "./state-machine/handlers/agent-planning.js";
 import { doAwaitingUser } from "./state-machine/handlers/awaiting-user.js";
 import { doIdle } from "./state-machine/handlers/idle.js";
@@ -106,6 +111,8 @@ import { paywallStopAdvice } from "./state-machine/helpers/prompt-failure.js";
 import { CLARK_USAGE_ORIGIN, promptFailureFromStreamAbort, promptFailurePaywall, promptFailurePlatform, promptFailureUserCanceled, PROMPT_ATTEMPT_ENTRYPOINT, recordBaseCommitResolutionFailed, recordPromptAttempt, recordPromptEntryRejection, recordPromptOutcome, recordAwaitingUserHandoffDismissed, resolvePromptMetricLabels, resolvePromptOutcomeDedupeKey, resolvePromptRequestDedupeKey, setPromptRequestMetricIdentity, } from "./state-machine/helpers/prompt-request-metrics.js";
 import { catchBackgroundPeerDisconnect, StablePeer, } from "./state-machine/helpers/stable-peer.js";
 import { transitionFrom } from "./state-machine/helpers/transition.js";
+import { resolveUserPreferences } from "./state-machine/helpers/user-preferences.js";
+import { createUserResponseMessage } from "./state-machine/helpers/user-response-message.js";
 import { isTaskAccessibleTo, registerBackgroundTaskTypes, resyncActiveTaskStatusesToPeer, TaskStore, wireTaskStatusPushToPeer, } from "./tasks/index.js";
 import { TemplateRenderer } from "./template-renderer.js";
 import { describeMigrationInferenceJwt, isUsableMigrationInferenceJwt, } from "./util/inference-jwt.js";
@@ -439,11 +446,46 @@ const POLICY_GATE_USAGE_METADATA = {
 const ERROR_JSON_OUTPUT_TYPE = "error-json";
 const TOOL_MESSAGE_ROLE = "tool";
 const TOOL_RESULT_CONTENT_TYPE = "tool-result";
+const TOOL_PERMISSION_CONTEXT_ATTEMPTS = 3;
+const TOOL_PERMISSION_CONTEXT_RETRY_MS = 200;
+const CLARIFICATION_DENY_REASON = "The user answered with the message that follows instead of approving.";
+const TOOL_PERMISSION_PLACEHOLDER_USAGE = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    inputTokenDetails: {
+        noCacheTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+    },
+    outputTokenDetails: {
+        textTokens: 0,
+        reasoningTokens: 0,
+    },
+};
+/**
+ * Provider-facing context expects tool failures to be encoded as errored tool
+ * results so they still satisfy the preceding tool call.
+ */
+function toolErrorResult(toolCallId, toolName, error) {
+    return {
+        role: TOOL_MESSAGE_ROLE,
+        content: [
+            {
+                type: TOOL_RESULT_CONTENT_TYPE,
+                toolCallId,
+                toolName,
+                output: { type: ERROR_JSON_OUTPUT_TYPE, value: { error } },
+            },
+        ],
+    };
+}
 export class AiService extends TracedEventEmitter {
     config;
     templateRenderer;
     appShell;
     fileSystemInterface;
+    fileSystemManager;
     integrationStore;
     knowledgeManager;
     _appContext;
@@ -468,6 +510,8 @@ export class AiService extends TracedEventEmitter {
     entityPermissionStore = new SessionEntityPermissionStore();
     generationCompleteWaiters = new Set();
     activeGenerationTrace;
+    currentGenerationId;
+    generationStarting = false;
     /** JWT-derived userId of the currently-authenticated peer, set by
      * `notifyAuthenticatedRpc` and cleared on disconnect / peer swap.
      * Only trusted while `authenticatedPeerId` still matches the bound
@@ -656,7 +700,11 @@ export class AiService extends TracedEventEmitter {
             return false;
         }
         getLogger().info("[ai-service] Accepted a new inference JWT");
+        const hadUser = this.getContextId() !== null;
         this.clark.updateContext({ jwt });
+        if (!hadUser) {
+            void this.pushRestoredContextUsage();
+        }
         const llmConfig = this.lastMigrationTurnCredentials?.llmConfig ??
             this.clark.context.llmConfig ??
             buildServerMigrationLlmConfig(this.config.flagBootstrap);
@@ -1066,7 +1114,9 @@ export class AiService extends TracedEventEmitter {
         this.config.draftInterface
             .hasLocalDraftChanges()
             .then((hasDraft) => {
-            if (hasDraft) {
+            if (hasDraft &&
+                this.currentGenerationId === undefined &&
+                this.clark.state === ClarkStateNames.Idle) {
                 this.clark.updateContext({
                     hasSuggestions: true,
                 });
@@ -1123,14 +1173,17 @@ export class AiService extends TracedEventEmitter {
         this.getLogger().info("[ai-service] Initialized");
     }
     async hydrateChecklistFromDisk() {
-        const checklist = await readPersistedChecklist(this.appRootDirPath);
+        let checklist = await readPersistedChecklist(this.appRootDirPath);
+        this.remediationRequestId = (await readRemediationRun(this.appRootDirPath))?.requestId;
         if (!checklist) {
             return;
         }
         // Reset stale in_progress items to pending. After a dev-server restart,
         // items left in_progress are not truly running — resetting them allows
         // the UI polling trigger and backend handler to re-dispatch Clark.
-        const staleInProgressItems = checklist.items.filter((item) => API_MIGRATION_ORIGINS.has(item.origin) && item.status === "in_progress");
+        const staleInProgressItems = checklist.items.filter((item) => (API_MIGRATION_ORIGINS.has(item.origin) ||
+            item.source === "policy_remediation") &&
+            item.status === "in_progress");
         for (const item of staleInProgressItems) {
             await updateChecklistItem({
                 appRootDirPath: this.appRootDirPath,
@@ -1139,6 +1192,8 @@ export class AiService extends TracedEventEmitter {
             });
             this.getLogger().info(`[ai-service] Reset stale in_progress item "${item.id}" to pending after restart`);
         }
+        checklist =
+            (await readPersistedChecklist(this.appRootDirPath)) ?? checklist;
         const hasPendingSeedApi = checklist.items.some((item) => API_MIGRATION_ORIGINS.has(item.origin) &&
             (item.status === "pending" || item.status === "in_progress"));
         if (hasPendingSeedApi) {
@@ -1395,6 +1450,7 @@ export class AiService extends TracedEventEmitter {
         return (fsm) => {
             const clark = fsm;
             return async (transition) => {
+                const generationId = this.currentGenerationId;
                 const params = {
                     ...this.config,
                     logger: this.getLogger(),
@@ -1427,6 +1483,7 @@ export class AiService extends TracedEventEmitter {
                     toolRegistry: this.toolRegistry,
                     entityPermissionStore: this.entityPermissionStore,
                     onToolPermissionParked: (messageId) => this.scheduleToolPermissionReplayWindow(messageId),
+                    resolveToolPermissionResponse: (request) => this.resolveToolPermissionResponse(request),
                     mcpServerManager: this.mcpServerManager,
                     viteServer: this.viteServer,
                     recordingManager: this.recordingManager,
@@ -1449,6 +1506,9 @@ export class AiService extends TracedEventEmitter {
                 };
                 const clarkStateHandlers = Object.fromEntries(Object.entries(clarkStateHandlerFactories).map(([state, handlerFactory]) => [state, handlerFactory(clark, params)]));
                 const { from, to, event } = transition;
+                const remediationTurnId = clark.context.promptOutcomeDedupeKey ?? clark.context.promptId;
+                const remediationLlmConfig = clark.context.llmConfig;
+                const remediationRequestId = this.remediationRequestId;
                 this.clarkProfiler.onStateTransition(from, to, event);
                 if (clark.context.runTimestamp) {
                     this.clarkProfiler.initialize(this.appShell, clark.context.runTimestamp);
@@ -1459,12 +1519,74 @@ export class AiService extends TracedEventEmitter {
                     throw new Error(`No handler for state ${to}`);
                 }
                 this.getLogger().info(`[ai-service] Transitioned from ${from} to ${to} with event ${event.type}`);
+                const { promptId, promptOutcomeDedupeKey } = clark.context;
+                let handlerCompleted = false;
                 try {
+                    if (event.type === USER_SENT_PROMPT &&
+                        remediationRequestId &&
+                        (event.request.policyGateRemediation ||
+                            event.request.responseMetadata)) {
+                        const turnId = event.request.requestId ?? randomUUID();
+                        clark.updateContext({ promptOutcomeDedupeKey: turnId });
+                        const result = await this.remediationChecklistQueue.enqueue(async () => {
+                            const result = await advancePolicyRemediationTurn({
+                                appRootDirPath: this.appRootDirPath,
+                                applicationId: this.config.applicationId,
+                                turnId,
+                                phase: event.request.responseMetadata ? "resume" : "start",
+                                requestId: remediationRequestId,
+                            });
+                            await this.publishRemediationTurnResult(result);
+                            return result;
+                        });
+                        if (result.outcome === "turn_limit") {
+                            if (!event.internal)
+                                await this.persistRejectedUserInput(event.request, event.inputSource);
+                            await clark.send({
+                                type: AGENT_CANCELED,
+                                advice: `Security remediation stopped after ${MAX_REMEDIATION_TURNS} turns. Retry to continue the remaining groups.`,
+                                failure: promptFailurePlatform("retries_exhausted"),
+                            });
+                            return;
+                        }
+                        if (clark.state !== to || clark.context.userInitiatedPromptAbort)
+                            return;
+                        clark.updateContext({
+                            usageMetadata: buildPolicyGateRemediationUsageMetadata(result.state?.policyGateRemediation),
+                        });
+                    }
                     await handler(transition);
+                    handlerCompleted = true;
+                    if (event.type === USER_SENT_PROMPT &&
+                        event.internal &&
+                        event.request.policyGateRemediation &&
+                        remediationRequestId &&
+                        this.ownsRemediationRun(remediationRequestId)) {
+                        this.recordRemediationDispatch("started", "dispatched");
+                    }
                 }
                 catch (error) {
+                    if (event.type === USER_SENT_PROMPT &&
+                        event.executeToolPermissionResponse &&
+                        (clark.context.promptId !== promptId ||
+                            clark.context.promptOutcomeDedupeKey !== promptOutcomeDedupeKey)) {
+                        // A newer turn owns Clark now, so this failure must not cancel it.
+                        this.getLogger().warn("[ai-service] A superseded tool permission turn failed after a newer turn took over", {
+                            ...getErrorMeta(error),
+                            currentPromptId: clark.context.promptId,
+                            supersededPromptId: promptId,
+                        });
+                        return;
+                    }
                     const errorMeta = getErrorMeta(error);
                     this.getLogger().error(`[ai-service] Error in handler for state ${to} with event ${event.type}: ${errorMeta.error.message}`, errorMeta);
+                    if (event.type === USER_SENT_PROMPT &&
+                        remediationRequestId &&
+                        (event.request.policyGateRemediation ||
+                            event.request.responseMetadata) &&
+                        !clark.context.abortController?.signal.aborted) {
+                        await this.failRemediationDispatch(remediationRequestId, event.request.requestId ?? remediationTurnId ?? "", "dispatch_failed", undefined, error);
+                    }
                     if (clark.context.abortController?.signal.aborted &&
                         event.type !== USER_CANCELED &&
                         event.type !== AGENT_CANCELED) {
@@ -1488,14 +1610,26 @@ export class AiService extends TracedEventEmitter {
                         to === ClarkStateNames.Dead) {
                         // The turn is over: drop per-turn billing attribution so stray
                         // LLM calls before the next prompt bill as default generation.
-                        if (clark.context.usageMetadata || clark.context.baseCommitId) {
+                        if (generationId === this.currentGenerationId &&
+                            (clark.context.usageMetadata || clark.context.baseCommitId)) {
                             clark.updateContext((context) => ({
                                 ...context,
                                 usageMetadata: undefined,
                                 baseCommitId: undefined,
                             }));
                         }
-                        this.triggerGenerationComplete();
+                        this.triggerGenerationComplete(generationId);
+                        if (handlerCompleted &&
+                            remediationRequestId &&
+                            this.ownsRemediationRun(remediationRequestId) &&
+                            remediationTurnId &&
+                            remediationLlmConfig &&
+                            (event.type === APP_RUNTIME_UPDATED_WITHOUT_EDITS ||
+                                event.type === V3_AGENT_FINISHED ||
+                                event.type === RUNTIME_REVIEW_FINISHED ||
+                                event.type === USER_ACCEPTED_DRAFT)) {
+                            void this.tryContinuePolicyRemediation(remediationTurnId, remediationLlmConfig);
+                        }
                     }
                 }
             };
@@ -1540,7 +1674,9 @@ export class AiService extends TracedEventEmitter {
      */
     async remoteRestoreFallback(id) {
         const jwt = this.getInferenceJwt();
-        const branchName = this._syncContextProvider?.getBranchName();
+        const branchName = jwt
+            ? await this._syncContextProvider?.getBranchName()
+            : undefined;
         if (!jwt || !branchName) {
             // A missing JWT is expected startup churn on a fresh pod (this runs
             // before auth is ready), so stay quiet there. Warn on the authed case
@@ -1865,132 +2001,147 @@ export class AiService extends TracedEventEmitter {
             recordAutoDispatchOutcome("dead");
             return { dispatched: false, reason: "dead" };
         }
-        if (this.clark.state !== ClarkStateNames.Idle &&
-            this.clark.state !== ClarkStateNames.AwaitingUser) {
-            const reason = `busy:${this.clark.state}`;
-            recordAutoDispatchOutcome(reason);
-            return { dispatched: false, reason };
-        }
-        if (this.isAwaitingInteractiveResponse()) {
-            const reason = this.clark.context.pendingToolPermissionRequest
-                ? "pending-tool-permission"
-                : "awaiting-interactive-response";
+        const blocked = this.autoDispatchBlockReason();
+        if (blocked) {
+            const reason = blocked === "busy"
+                ? `busy:${this.clark.state}`
+                : blocked === "tool_permission"
+                    ? "pending-tool-permission"
+                    : "awaiting-interactive-response";
             recordAutoDispatchOutcome(reason);
             return { dispatched: false, reason };
         }
         this.migrationTurnTriggered = true;
-        const checklist = await readPersistedChecklist(this.appRootDirPath);
-        if (!checklist) {
-            this.migrationTurnTriggered = false;
-            this.getLogger().warn("[ai-service] Migration checklist not found or unreadable; skipping translation turn");
-            recordAutoDispatchOutcome("checklist-unavailable");
-            return { dispatched: false, reason: "checklist-unavailable" };
-        }
-        const pendingSeedApiItems = checklist.items.filter((item) => API_MIGRATION_ORIGINS.has(item.origin) &&
-            (item.status === "pending" || item.status === "in_progress"));
-        const pendingSeedApiCount = pendingSeedApiItems.length;
-        if (pendingSeedApiCount === 0) {
-            this.migrationTurnTriggered = false;
-            recordAutoDispatchOutcome("no-pending-items");
-            return { dispatched: false, reason: "no-pending-items" };
-        }
-        // Pre-flight quota gate. The migration turn drives LLM inference (which
-        // doesn't enforce quota) followed by tool calls that hit quota-protected
-        // endpoints (e.g. attachment uploads via /api/v1/files). Without this gate
-        // an over-limit org burns more credits on the migration turn, then fails
-        // mid-turn with a generic "inference error" when a downstream tool call
-        // 429s. Fail fast with a clear reason before consuming any credits, the
-        // same pre-flight check handleAiGenerate already runs.
-        const quota = await this.checkAiQuota(this.config.inferenceAuthToken ?? request.jwt);
-        if (!quota.allowed) {
-            this.migrationTurnTriggered = false;
-            this.getLogger().warn("[ai-service] Skipping v2→v3 migration turn — AI quota exceeded", { reason: quota.reason });
-            recordAutoDispatchOutcome("quota-exceeded");
-            return { dispatched: false, reason: "quota-exceeded" };
-        }
-        this.appShell.setApiHandlerEnabled(false);
-        this.getLogger().info(`[ai-service] Dispatching internal v2→v3 migration turn for ${pendingSeedApiCount} API(s) (API VFS projection disabled, retryMode=${request.retryMode ?? "none"})`);
-        const prompt = buildTranslationPrompt({
-            focusedDebug: request.retryMode === "focused-debug",
-        });
-        const migrationLlmConfig = this.getMigrationSafeLlmConfig(request.llmConfig);
-        const generateRequest = {
-            prompt,
-            jwt: request.jwt,
-            llmConfig: migrationLlmConfig,
-            mode: AiMode.BUILD,
-        };
+        this.generationStarting = true;
         const promptId = randomUUID();
-        const retryMode = request.retryMode === "focused-debug" ? "focused-debug" : "none";
-        const triggeredBy = request.triggeredBy ??
-            (request.retryMode === "focused-debug" ? "focused-debug" : "ui-rpc");
-        const branchName = this._syncContextProvider?.getBranchName();
-        const migrationUsageMetadata = {
-            applicationId: this.config.applicationId,
-            branchName,
-            migrationSource: "superblocks_2_0",
-            origin: CLARK_USAGE_ORIGIN.app_migration,
-            pendingSeedApiCount,
-            retryMode,
-            surface: "app",
-            triggeredBy,
-        };
-        const [baseCommitId] = await Promise.all([
-            this.resolveBaseCommitId(promptId),
-            this.resolveChatSessionId(),
-        ]);
-        this.clark.updateContext((context) => ({
-            ...context,
-            promptId,
-            promptOutcomeDedupeKey: promptId,
-            baseCommitId,
-            usageMetadata: migrationUsageMetadata,
-            llmConfig: migrationLlmConfig,
-        }));
-        const transitionTo = transitionFrom(this.clark);
-        // Promise is intentionally not awaited — the translation turn runs in the
-        // background. We reset the guard + re-enable the API handler when the
-        // turn *settles* (success or failure) so any remaining pending items
-        // (from auto-retry budget flips or genuine agent exits) can trigger
-        // another sweep without a dev-server restart.
-        let settleOutcome = "success";
-        transitionTo({
-            type: USER_SENT_PROMPT,
-            request: generateRequest,
-            internal: true,
-            visibleInChatHistory: true,
-        })
-            .catch((error) => {
-            settleOutcome = "error";
-            this.getLogger().error("[ai-service] Migration translation turn failed", getErrorMeta(error));
-        })
-            .finally(async () => {
+        let generationStarted = false;
+        try {
+            const checklist = await readPersistedChecklist(this.appRootDirPath);
+            if (!checklist) {
+                this.migrationTurnTriggered = false;
+                this.getLogger().warn("[ai-service] Migration checklist not found or unreadable; skipping translation turn");
+                recordAutoDispatchOutcome("checklist-unavailable");
+                return { dispatched: false, reason: "checklist-unavailable" };
+            }
+            const pendingSeedApiItems = checklist.items.filter((item) => API_MIGRATION_ORIGINS.has(item.origin) &&
+                (item.status === "pending" || item.status === "in_progress"));
+            const pendingSeedApiCount = pendingSeedApiItems.length;
+            if (pendingSeedApiCount === 0) {
+                this.migrationTurnTriggered = false;
+                recordAutoDispatchOutcome("no-pending-items");
+                return { dispatched: false, reason: "no-pending-items" };
+            }
+            // Pre-flight quota gate. The migration turn drives LLM inference (which
+            // doesn't enforce quota) followed by tool calls that hit quota-protected
+            // endpoints (e.g. attachment uploads via /api/v1/files). Without this gate
+            // an over-limit org burns more credits on the migration turn, then fails
+            // mid-turn with a generic "inference error" when a downstream tool call
+            // 429s. Fail fast with a clear reason before consuming any credits, the
+            // same pre-flight check handleAiGenerate already runs.
+            const quota = await this.checkAiQuota(this.config.inferenceAuthToken ?? request.jwt);
+            if (!quota.allowed) {
+                this.migrationTurnTriggered = false;
+                this.getLogger().warn("[ai-service] Skipping v2→v3 migration turn — AI quota exceeded", { reason: quota.reason });
+                recordAutoDispatchOutcome("quota-exceeded");
+                return { dispatched: false, reason: "quota-exceeded" };
+            }
+            await this.config.waitForAppFiles?.(promptId);
+            this.currentGenerationId = promptId;
+            this.appShell.setApiHandlerEnabled(false);
+            this.getLogger().info(`[ai-service] Dispatching internal v2→v3 migration turn for ${pendingSeedApiCount} API(s) (API VFS projection disabled, retryMode=${request.retryMode ?? "none"})`);
+            const prompt = buildTranslationPrompt({
+                focusedDebug: request.retryMode === "focused-debug",
+            });
+            const migrationLlmConfig = this.getMigrationSafeLlmConfig(request.llmConfig);
+            const generateRequest = {
+                prompt,
+                jwt: request.jwt,
+                llmConfig: migrationLlmConfig,
+                mode: AiMode.BUILD,
+            };
+            const retryMode = request.retryMode === "focused-debug" ? "focused-debug" : "none";
+            const triggeredBy = request.triggeredBy ??
+                (request.retryMode === "focused-debug" ? "focused-debug" : "ui-rpc");
+            const branchName = await this._syncContextProvider?.getBranchName();
+            const migrationUsageMetadata = {
+                applicationId: this.config.applicationId,
+                branchName,
+                migrationSource: "superblocks_2_0",
+                origin: CLARK_USAGE_ORIGIN.app_migration,
+                pendingSeedApiCount,
+                retryMode,
+                surface: "app",
+                triggeredBy,
+            };
+            const [baseCommitId] = await Promise.all([
+                this.resolveBaseCommitId(promptId),
+                this.resolveChatSessionId(),
+            ]);
+            this.clark.updateContext((context) => ({
+                ...context,
+                promptId,
+                promptOutcomeDedupeKey: promptId,
+                baseCommitId,
+                usageMetadata: migrationUsageMetadata,
+                llmConfig: migrationLlmConfig,
+            }));
+            const transitionTo = transitionFrom(this.clark);
+            // Promise is intentionally not awaited — the translation turn runs in the
+            // background. We reset the guard + re-enable the API handler when the
+            // turn *settles* (success or failure) so any remaining pending items
+            // (from auto-retry budget flips or genuine agent exits) can trigger
+            // another sweep without a dev-server restart.
+            let settleOutcome = "success";
+            transitionTo({
+                type: USER_SENT_PROMPT,
+                request: generateRequest,
+                internal: true,
+                visibleInChatHistory: true,
+            })
+                .catch((error) => {
+                settleOutcome = "error";
+                this.getLogger().error("[ai-service] Migration translation turn failed", getErrorMeta(error));
+            })
+                .finally(async () => {
+                this.emit("generationSettled", promptId);
+                try {
+                    await recordMigrationTurnSettled(this.appRootDirPath, {
+                        outcome: settleOutcome,
+                        promptId,
+                        retryMode,
+                    });
+                }
+                catch (error) {
+                    this.getLogger().error(`[ai-service] Failed to record migration turn settlement (promptId=${promptId})`, getErrorMeta(error));
+                }
+                this.migrationTurnTriggered = false;
+                this.appShell.setApiHandlerEnabled(true);
+            });
+            generationStarted = true;
             try {
-                await recordMigrationTurnSettled(this.appRootDirPath, {
-                    outcome: settleOutcome,
+                await recordMigrationTurnDispatched(this.appRootDirPath, {
+                    pendingSeedApiCount,
                     promptId,
                     retryMode,
+                    triggeredBy,
                 });
             }
             catch (error) {
-                this.getLogger().error(`[ai-service] Failed to record migration turn settlement (promptId=${promptId})`, getErrorMeta(error));
+                this.getLogger().error(`[ai-service] Failed to record migration turn dispatch (promptId=${promptId})`, getErrorMeta(error));
             }
-            this.migrationTurnTriggered = false;
-            this.appShell.setApiHandlerEnabled(true);
-        });
-        try {
-            await recordMigrationTurnDispatched(this.appRootDirPath, {
-                pendingSeedApiCount,
-                promptId,
-                retryMode,
-                triggeredBy,
-            });
+            recordAutoDispatchOutcome("dispatched");
+            return { dispatched: true };
         }
-        catch (error) {
-            this.getLogger().error(`[ai-service] Failed to record migration turn dispatch (promptId=${promptId})`, getErrorMeta(error));
+        finally {
+            this.generationStarting = false;
+            if (!generationStarted) {
+                this.migrationTurnTriggered = false;
+                if (this.currentGenerationId === promptId) {
+                    this.appShell.setApiHandlerEnabled(true);
+                }
+                this.emit("generationSettled", promptId);
+            }
         }
-        recordAutoDispatchOutcome("dispatched");
-        return { dispatched: true };
     }
     getMigrationSafeLlmConfig(llmConfig) {
         const result = filterDisabledToolsForMigration(llmConfig);
@@ -2024,16 +2175,17 @@ export class AiService extends TracedEventEmitter {
      * chat record + modal — instead of the interrupt path silently rejecting
      * with no UI state. (APPS-4080)
      */
-    async tryHandlePaywallForRequest(request, inputSource) {
+    async tryHandlePaywallForRequest(request, inputSource, internalSignal) {
         try {
             await this.ensureAiQuotaAvailable(this.config.inferenceAuthToken ?? request.jwt);
             return undefined;
         }
         catch (error) {
+            internalSignal?.throwIfAborted();
             if (error instanceof Error) {
                 const reason = getAiQuotaPaywallReasonFromMessage(error.message);
                 if (reason) {
-                    await this.handlePreCallPaywall(request, reason, inputSource);
+                    await this.handlePreCallPaywall(request, reason, inputSource, !!internalSignal);
                     return reason;
                 }
             }
@@ -2055,48 +2207,8 @@ export class AiService extends TracedEventEmitter {
             this.getLogger().warn("[ai-service] Failed to publish user input", getErrorMeta(err));
         });
     }
-    /**
-     * Persist the user's prompt + the "credits ran out" advice and open the
-     * paywall modal when the pre-call quota check denies the request. Mirrors
-     * what `idle.ts:AGENT_CANCELED` does for the mid-stream paywall path so
-     * both paths leave an identical chat record. Used only when
-     * `ensureAiQuotaAvailable` throws a paywall error in `handleAiGenerate`.
-     *
-     * - For organic user prompts (no `responseMetadata`), persists via
-     *   `recordUser`.
-     * - For widget responses (`multi_choice_response`, `plan_response`,
-     *   `confirm_response`, `searchable_dropdown_response`,
-     *   `remember_knowledge_draft_response`), persists via
-     *   `recordUserResponse` with the full metadata — without this, the
-     *   user's exact choice is silently dropped (they lose their selection
-     *   from chat history AND the resume turn's LLM has no record of what
-     *   they picked). Mirrors `agent-planning.ts:USER_SENT_PROMPT`.
-     * - `tool_permission_response` is intentionally NOT persisted — those
-     *   responses don't have a chat representation; the approval is just
-     *   side-effect state. On resume the user will see the permission
-     *   prompt again, which is acceptable UX.
-     * - Uses fire-and-forget peer pushes after each `await` on the store so
-     *   the chat is durable across refresh even if the live peer push drops.
-     */
-    async handlePreCallPaywall(request, paywallReason, inputSource) {
-        this.getLogger().info(`[ai-service] Pre-call paywall denial; persisting prompt + advice for chat history`, { paywallReason });
-        // APPS-4080: pre-cache the CANCELLED + paywallReason snapshot into
-        // `lastGenerationState` BEFORE any chat-persistence await. Without
-        // this, a socket reconnect during the awaits in steps 1-2 below
-        // would replay the stale IDLE snapshot held over from before the
-        // request, and the UI saga (`paywallReason && state === CANCELLED`
-        // -> openAiQuotaPaywallModal) would never see the paywall payload —
-        // so the modal would not reopen on refresh. The full
-        // `sendUserGenerationStateChannel({...})` in step 3 below re-caches
-        // and pushes to the peer so the LIVE modal opens AFTER the advice
-        // is in chat. (Cursor PR-19341 review.)
-        this.clark.updateContext({
-            lastGenerationState: {
-                state: AiGenerationState.CANCELLED,
-                hasError: true,
-                paywallReason,
-            },
-        });
+    /** Record a rejected request before emitting a terminal response, without starting generation. */
+    async persistRejectedUserInput(request, inputSource) {
         // 1. Persist + echo the user's prompt so the chat doesn't lose it.
         const responseMetadata = request.responseMetadata;
         if (!responseMetadata) {
@@ -2116,7 +2228,7 @@ export class AiService extends TracedEventEmitter {
                 });
             }
             catch (err) {
-                this.getLogger().warn("[ai-service] Failed to persist pre-call paywall user prompt", getErrorMeta(err));
+                this.getLogger().warn("[ai-service] Failed to persist rejected user prompt", getErrorMeta(err));
             }
         }
         else if (responseMetadata.type !== "tool_permission_response") {
@@ -2134,27 +2246,7 @@ export class AiService extends TracedEventEmitter {
                 responseMetadata.selectedChoiceIndices.length === 0) ||
                 (responseMetadata.type === "plan_response" &&
                     !responseMetadata.approved);
-            const responseMessage = responseMetadata.type === "multi_choice_response" &&
-                responseMetadata.selectedChoiceIndices.length > 0
-                ? {
-                    content: request.prompt,
-                    id: randomUUID(),
-                    responseToMessageId: responseMetadata.responseToMessageId,
-                    role: "user",
-                    selectedChoiceIndices: responseMetadata.selectedChoiceIndices,
-                    selectedScopes: responseMetadata.selectedScopes,
-                    timestamp: Date.now(),
-                    type: "multi_choice_response",
-                }
-                : isTypedOverride
-                    ? {
-                        content: request.prompt,
-                        id: randomUUID(),
-                        role: "user",
-                        timestamp: Date.now(),
-                        type: "text",
-                    }
-                    : undefined;
+            const responseMessage = createUserResponseMessage(request.prompt, responseMetadata, inputSource);
             if (responseMessage) {
                 this.publishUserInput(responseMessage, inputSource, isTypedOverride);
             }
@@ -2207,14 +2299,59 @@ export class AiService extends TracedEventEmitter {
                         responseToMessageId: responseMetadata.responseToMessageId,
                     })
                         .catch((err) => {
-                        this.getLogger().warn("[ai-service] Failed to echo pre-call paywall widget response", getErrorMeta(err));
+                        this.getLogger().warn("[ai-service] Failed to echo rejected widget response", getErrorMeta(err));
                     });
                 }
             }
             catch (err) {
-                this.getLogger().warn("[ai-service] Failed to persist pre-call paywall widget response", getErrorMeta(err));
+                this.getLogger().warn("[ai-service] Failed to persist rejected widget response", getErrorMeta(err));
             }
         }
+    }
+    /**
+     * Persist the user's prompt + the "credits ran out" advice and open the
+     * paywall modal when the pre-call quota check denies the request. Mirrors
+     * what `idle.ts:AGENT_CANCELED` does for the mid-stream paywall path so
+     * both paths leave an identical chat record. Used only when
+     * `ensureAiQuotaAvailable` throws a paywall error in `handleAiGenerate`.
+     *
+     * - For organic user prompts (no `responseMetadata`), persists via
+     *   `recordUser`.
+     * - For widget responses (`multi_choice_response`, `plan_response`,
+     *   `confirm_response`, `searchable_dropdown_response`,
+     *   `remember_knowledge_draft_response`), persists via
+     *   `recordUserResponse` with the full metadata — without this, the
+     *   user's exact choice is silently dropped (they lose their selection
+     *   from chat history AND the resume turn's LLM has no record of what
+     *   they picked). Mirrors `agent-planning.ts:USER_SENT_PROMPT`.
+     * - `tool_permission_response` is intentionally NOT persisted — those
+     *   responses don't have a chat representation; the approval is just
+     *   side-effect state. On resume the user will see the permission
+     *   prompt again, which is acceptable UX.
+     * - Uses fire-and-forget peer pushes after each `await` on the store so
+     *   the chat is durable across refresh even if the live peer push drops.
+     */
+    async handlePreCallPaywall(request, paywallReason, inputSource, internal = false) {
+        this.getLogger().info(`[ai-service] Pre-call paywall denial; persisting prompt + advice for chat history`, { paywallReason });
+        // APPS-4080: pre-cache the CANCELLED + paywallReason snapshot into
+        // `lastGenerationState` BEFORE any chat-persistence await. Without
+        // this, a socket reconnect during the awaits in steps 1-2 below
+        // would replay the stale IDLE snapshot held over from before the
+        // request, and the UI saga (`paywallReason && state === CANCELLED`
+        // -> openAiQuotaPaywallModal) would never see the paywall payload —
+        // so the modal would not reopen on refresh. The full
+        // `sendUserGenerationStateChannel({...})` in step 3 below re-caches
+        // and pushes to the peer so the LIVE modal opens AFTER the advice
+        // is in chat. (Cursor PR-19341 review.)
+        this.clark.updateContext({
+            lastGenerationState: {
+                state: AiGenerationState.CANCELLED,
+                hasError: true,
+                paywallReason,
+            },
+        });
+        if (!internal)
+            await this.persistRejectedUserInput(request, inputSource);
         // 2. Persist + echo the credit advice. Same reason-aware copy as
         //    `agent-planning.ts:LLM_ERRORED` so users see consistent guidance
         //    across pre-call and mid-stream paywall paths.
@@ -2284,7 +2421,8 @@ export class AiService extends TracedEventEmitter {
         // tool_permission_response — those have no persisted chat
         // representation; the approval is just side-effect state that gets
         // re-prompted on resume.
-        if (request.responseMetadata?.type !== "tool_permission_response") {
+        if (!internal &&
+            request.responseMetadata?.type !== "tool_permission_response") {
             try {
                 // `getContextId` reads `clark.context.jwt` for the userId, but the
                 // JWT is normally only stored into clark context by the
@@ -2347,7 +2485,198 @@ export class AiService extends TracedEventEmitter {
             }
         }
     }
-    async handleAiGenerate(request, inputSource) {
+    remediationPreparation;
+    remediationAutoDispatch;
+    // Identifies the run owned by the live turn; run data stays on disk.
+    remediationRequestId;
+    ownsRemediationRun(requestId, signal) {
+        return (!signal?.aborted &&
+            !this.clark.context.userInitiatedPromptAbort &&
+            this.remediationRequestId === requestId);
+    }
+    remediationCancellation;
+    remediationChecklistQueue = new OperationQueue();
+    async publishRemediationTurnResult(result) {
+        this.remediationRequestId = result.state?.policyGateRemediation?.requestId;
+        for (const item of result.failedItems) {
+            await this.appShell.sendMessage({
+                type: "checklist_item_updated",
+                payload: { item, totalItems: result.state?.items.length },
+            });
+        }
+    }
+    recordRemediationDispatch(outcome, reason) {
+        metrics
+            .getMeter("superblocks.clark")
+            .createCounter("policy_remediation_dispatch_total", {
+            description: "Automatic remediation dispatch decisions",
+            unit: "1",
+        })
+            .add(1, { outcome, "remediation.reason": reason });
+    }
+    async failRemediationDispatch(requestId, turnId, failureReason = "dispatch_failed", signal, error) {
+        if (!this.ownsRemediationRun(requestId, signal))
+            return;
+        this.recordRemediationDispatch("failed", failureReason);
+        this.getLogger().warnStructured?.("Policy remediation continuation failed", {
+            "application.id": this.config.applicationId,
+            "remediation.request_id": requestId,
+            "remediation.turn_id": turnId,
+            "remediation.failure_reason": failureReason,
+            "error.type": getErrorMeta(error).error.kind,
+            "error.message": getErrorMeta(error).error.message,
+        });
+        const maxAttempts = 3;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            if (attempt > 1)
+                await new Promise((resolve) => setTimeout(resolve, 100 * (attempt - 1)));
+            if (!this.ownsRemediationRun(requestId, signal))
+                return;
+            try {
+                await this.remediationChecklistQueue.enqueue(async () => {
+                    if (!this.ownsRemediationRun(requestId, signal))
+                        return;
+                    const failed = await failPolicyRemediationDispatch({
+                        appRootDirPath: this.appRootDirPath,
+                        requestId,
+                    });
+                    await this.publishRemediationTurnResult(failed);
+                });
+                return;
+            }
+            catch (persistenceError) {
+                this.recordRemediationDispatch("failed", "failure_persistence_failed");
+                this.getLogger().warnStructured?.("Could not persist remediation dispatch failure", {
+                    "application.id": this.config.applicationId,
+                    "remediation.request_id": requestId,
+                    "remediation.turn_id": turnId,
+                    "remediation.failure_reason": "failure_persistence_failed",
+                    "remediation.persistence_attempt": attempt,
+                    "error.type": getErrorMeta(persistenceError).error.kind,
+                    "error.message": getErrorMeta(persistenceError).error.message,
+                });
+            }
+        }
+        if (!this.ownsRemediationRun(requestId, signal))
+            return;
+        // Keep the durable owner available for Stop/retry. Never pretend a failed
+        // write committed; notify the live peer even if chat persistence also fails.
+        const message = {
+            id: randomUUID(),
+            role: "assistant",
+            type: "error",
+            timestamp: Date.now(),
+            content: "Security remediation stopped because its progress could not be saved. Restore access to project storage, then stop and retry security remediation.",
+        };
+        const notifications = await Promise.allSettled([
+            this.chatSessionStore.recordAssistant(message),
+            this.clark.context.peer?.call.aiPushMessage(message),
+        ]);
+        for (const notification of notifications) {
+            if (notification.status === "rejected")
+                this.getLogger().warn("Could not publish remediation persistence failure", getErrorMeta(notification.reason));
+        }
+    }
+    async tryContinuePolicyRemediation(turnId, llmConfig) {
+        if (this.remediationAutoDispatch &&
+            !this.remediationAutoDispatch.signal.aborted) {
+            this.recordRemediationDispatch("skipped", "already_dispatching");
+            return;
+        }
+        const requestId = this.remediationRequestId;
+        if (!requestId) {
+            this.recordRemediationDispatch("skipped", "unowned_turn");
+            return;
+        }
+        const controller = new AbortController();
+        this.remediationAutoDispatch = controller;
+        const skipReason = () => {
+            if (controller.signal.aborted ||
+                this.clark.context.userInitiatedPromptAbort)
+                return "cancelled";
+            // Terminal settlement clears the owner; only a replacement invalidates it.
+            if (this.remediationRequestId && !this.ownsRemediationRun(requestId))
+                return "turn_changed";
+            return this.autoDispatchBlockReason();
+        };
+        const shouldSkip = () => {
+            const reason = skipReason();
+            if (reason)
+                this.recordRemediationDispatch("skipped", reason);
+            return reason !== undefined;
+        };
+        let failureReason = "dispatch_failed";
+        try {
+            if (shouldSkip())
+                return;
+            const result = await this.remediationChecklistQueue.enqueue(async () => {
+                if (shouldSkip())
+                    return undefined;
+                const result = await advancePolicyRemediationTurn({
+                    appRootDirPath: this.appRootDirPath,
+                    applicationId: this.config.applicationId,
+                    turnId,
+                    phase: "settle",
+                    requestId,
+                });
+                await this.publishRemediationTurnResult(result);
+                return result;
+            });
+            if (!result || shouldSkip())
+                return;
+            if (result.outcome !== "continue") {
+                // started cannot result from settle, but keep the signal bounded.
+                this.recordRemediationDispatch("skipped", result.outcome === "started" ? "duplicate" : result.outcome);
+                return;
+            }
+            const run = result.state?.policyGateRemediation;
+            if (!run || run.requestId !== requestId) {
+                this.recordRemediationDispatch("skipped", "inactive");
+                return;
+            }
+            if (!this.clark.context.jwt) {
+                failureReason = "missing_auth";
+                throw new Error("Authentication is required to continue remediation");
+            }
+            const nextTurnId = randomUUID();
+            await this.handleAiGenerate({
+                prompt: "Continue the security fixes. Call getSecurityFindings for the next group.",
+                requestId: nextTurnId,
+                jwt: this.clark.context.jwt,
+                llmConfig,
+                mode: this.clark.context.currentMode,
+                userPreferences: resolveUserPreferences(this.clark.context.userPreferences),
+                policyGateRemediation: {
+                    batched: true,
+                    reviewFindingIds: run.reviewFindingIds,
+                    reviewRunIds: run.reviewRunIds,
+                },
+            }, undefined, controller.signal);
+            if (!this.ownsRemediationRun(requestId, controller.signal)) {
+                this.recordRemediationDispatch("skipped", "cancelled");
+            }
+            else if (this.clark.context.promptOutcomeDedupeKey !== nextTurnId) {
+                if (this.clark.context.pausedForCreditsReason) {
+                    this.recordRemediationDispatch("skipped", "paywall");
+                }
+                else {
+                    throw new Error("Automatic remediation dispatch was not accepted");
+                }
+            }
+        }
+        catch (error) {
+            if (!this.ownsRemediationRun(requestId, controller.signal)) {
+                this.recordRemediationDispatch("skipped", "cancelled");
+                return;
+            }
+            await this.failRemediationDispatch(requestId, turnId, failureReason, controller.signal, error);
+        }
+        finally {
+            if (this.remediationAutoDispatch === controller)
+                this.remediationAutoDispatch = undefined;
+        }
+    }
+    async handleAiGenerate(request, inputSource, remediationContinuationSignal) {
         this.getLogger().info(`[ai-service] handleAiGenerate: peerId=${this.stablePeer.peerId ?? "unknown"}`);
         this.storeMigrationTurnCredentials(request.jwt, request.llmConfig);
         if (this.clark.state === ClarkStateNames.Dead) {
@@ -2364,7 +2693,9 @@ export class AiService extends TracedEventEmitter {
             return;
         }
         this.assertNoActivePolicyGateRun();
-        if (this.isBusy()) {
+        if (this.isBusy() ||
+            this.remediationPreparation ||
+            this.remediationCancellation) {
             this.getLogger().warn("[ai-service] Service is busy. State:", this.clark.state);
             recordPromptEntryRejection({
                 dedupeKey: resolvePromptRequestDedupeKey(request),
@@ -2373,34 +2704,19 @@ export class AiService extends TracedEventEmitter {
             });
             throw new Error("Service is busy");
         }
-        // Pre-call quota check. When denied, `ensureAiQuotaAvailable` throws so
-        // the UI gets a paywall reason and opens the modal. Without intervention
-        // the throw means we never reach `transitionTo<$AgentPlanning>` below,
-        // so `agent-planning.ts:USER_SENT_PROMPT` never records the user prompt
-        // and `idle.ts:AGENT_CANCELED` never persists the credit advice — the UI
-        // ends up with the optimistic user message removed (thunks.ts catch path)
-        // and no record of what the user tried. Catch it here, persist prompt +
-        // advice + open modal via the same `aiSetGenerationState(CANCELLED,
-        // paywallReason)` saga path the mid-stream paywall uses, then resolve
-        // the socket call so the UI's catch doesn't run. (APPS-4080)
-        const paywallReason = await this.tryHandlePaywallForRequest(request, inputSource);
-        if (paywallReason) {
-            recordPromptEntryRejection({
-                dedupeKey: resolvePromptRequestDedupeKey(request),
-                failure: promptFailurePaywall(paywallReason),
-                coreModel: request.llmConfig?.coreModel,
-            });
-            return;
-        }
-        if (request.requestId &&
-            !this.requestDeduplicator.markIfNew(request.requestId)) {
-            this.getLogger().warn("[ai-service] Ignoring duplicate aiGenerate re-send (lost dedup race)", { requestId: request.requestId });
-            return;
-        }
-        recordPromptAttempt({
-            outcomeDedupeKey: resolvePromptRequestDedupeKey(request),
-            coreModel: request.llmConfig?.coreModel,
-        });
+        if (request.responseMetadata?.type === "tool_permission_response") {
+            this.getPendingToolPermissionRequest(request.responseMetadata.responseToMessageId);
+        }
+        remediationContinuationSignal?.throwIfAborted();
+        if (!remediationContinuationSignal)
+            this.remediationAutoDispatch?.abort();
+        // Remediation needs a stable identity for its durable owner and budget.
+        // Preserve the existing identity behavior for unrelated legacy requests.
+        if (!request.requestId &&
+            (request.policyGateRemediation ||
+                (request.responseMetadata && this.remediationRequestId)))
+            request = { ...request, requestId: randomUUID() };
+        const promptId = randomUUID();
         const requestUsageMetadata = request.importSource
             ? {
                 origin: CLARK_USAGE_ORIGIN.app_migration,
@@ -2411,15 +2727,127 @@ export class AiService extends TracedEventEmitter {
         const generateStreakEligible = resolvePromptMetricLabels({
             usageMetadata: requestUsageMetadata,
         }).streakEligible;
-        // The id is now recorded. If anything below throws before generation is
-        // actually kicked off (the `transitionTo` USER_SENT_PROMPT), evict it so a
-        // legitimate reconnect re-send of this same prompt is not swallowed as a
-        // duplicate while nothing is running. (APPS-4663)
         let generationTrace;
+        let remediationPreparation;
+        let generationStarted = false;
+        let requestMarked = false;
+        this.generationStarting = true;
         try {
-            // Generate prompt_id for this user interaction. It doubles as the
-            // generation id on terminal events, so the trace needs it up front.
-            const promptId = randomUUID();
+            if (request.requestId) {
+                requestMarked = this.requestDeduplicator.markIfNew(request.requestId);
+                if (!requestMarked) {
+                    this.getLogger().warn("[ai-service] Ignoring duplicate aiGenerate re-send (lost dedup race)", { requestId: request.requestId });
+                    return;
+                }
+            }
+            const remediation = request.policyGateRemediation?.batched === true
+                ? request.policyGateRemediation
+                : undefined;
+            if (!remediation &&
+                !request.responseMetadata &&
+                !remediationContinuationSignal) {
+                this.remediationRequestId = undefined;
+            }
+            if (remediation && !remediationContinuationSignal) {
+                // Stop must also cancel preparation while file sync or quota is pending.
+                remediationPreparation = new AbortController();
+                this.remediationPreparation = remediationPreparation;
+            }
+            await this.config.waitForAppFiles?.(promptId);
+            remediationPreparation?.signal.throwIfAborted();
+            remediationContinuationSignal?.throwIfAborted();
+            // Pre-call quota check. When denied, `ensureAiQuotaAvailable` throws so
+            // the UI gets a paywall reason and opens the modal. Without intervention
+            // the throw means we never reach `transitionTo<$AgentPlanning>` below,
+            // so `agent-planning.ts:USER_SENT_PROMPT` never records the user prompt
+            // and `idle.ts:AGENT_CANCELED` never persists the credit advice — the UI
+            // ends up with the optimistic user message removed (thunks.ts catch path)
+            // and no record of what the user tried. Catch it here, persist prompt +
+            // advice + open modal via the same `aiSetGenerationState(CANCELLED,
+            // paywallReason)` saga path the mid-stream paywall uses, then resolve
+            // the socket call so the UI's catch doesn't run. (APPS-4080)
+            const paywallReason = await this.tryHandlePaywallForRequest(request, inputSource, remediationContinuationSignal);
+            remediationPreparation?.signal.throwIfAborted();
+            remediationContinuationSignal?.throwIfAborted();
+            if (paywallReason) {
+                recordPromptEntryRejection({
+                    dedupeKey: resolvePromptRequestDedupeKey(request),
+                    failure: promptFailurePaywall(paywallReason),
+                    coreModel: request.llmConfig?.coreModel,
+                });
+                if (request.responseMetadata?.type === "tool_permission_response") {
+                    throw new Error(`${paywallStopAdvice(paywallReason)} [reason:${paywallReason}]`);
+                }
+                return;
+            }
+            recordPromptAttempt({
+                outcomeDedupeKey: resolvePromptRequestDedupeKey(request),
+                coreModel: request.llmConfig?.coreModel,
+            });
+            if (remediation && remediationPreparation) {
+                const preparation = remediationPreparation;
+                const existing = await readPersistedChecklist(this.appRootDirPath);
+                if (request.requestId &&
+                    existing?.items.some((item) => item.remediationRequestId === request.requestId)) {
+                    // A restart or failed generation start may leave a persisted run.
+                    // Resume pending work without reseeding or cancelling its groups.
+                    if (!existing.items.some((item) => item.remediationRequestId === request.requestId &&
+                        (item.status === "pending" || item.status === "in_progress"))) {
+                        this.getLogger().info("[ai-service] Ignoring finished remediation request replay", { requestId: request.requestId });
+                        recordPromptEntryRejection({
+                            dedupeKey: resolvePromptRequestDedupeKey(request),
+                            failure: promptFailurePlatform("request_already_finished"),
+                            coreModel: request.llmConfig?.coreModel,
+                        });
+                        await sendUserGenerationStateChannel(this.clark)({
+                            state: AiGenerationState.CANCELLED,
+                        });
+                        return;
+                    }
+                    preparation.signal.throwIfAborted();
+                    this.remediationRequestId = existing.policyGateRemediation?.requestId;
+                }
+                else {
+                    preparation.signal.throwIfAborted();
+                    const findings = await fetchRemediationFindings({
+                        rpcClient: this.config.rpcClient,
+                        applicationId: this.config.applicationId,
+                        reviewFindingIds: remediation.reviewFindingIds,
+                        signal: preparation.signal,
+                    });
+                    preparation.signal.throwIfAborted();
+                    await this.remediationChecklistQueue.enqueue(async () => {
+                        preparation.signal.throwIfAborted();
+                        const seeded = await seedPolicyRemediationChecklist({
+                            appRootDirPath: this.appRootDirPath,
+                            requestId: request.requestId ?? promptId,
+                            remediation,
+                            findings,
+                        });
+                        // Transfer ownership only after the replacement is durable. Stop
+                        // reads it from this same queue, including during the seed write.
+                        this.remediationRequestId = request.requestId ?? promptId;
+                        for (const item of seeded.cancelledItems) {
+                            await this.appShell.sendMessage({
+                                type: "checklist_item_updated",
+                                payload: { item, totalItems: seeded.state.items.length },
+                            });
+                        }
+                        for (const item of seeded.addedItems) {
+                            // Stop publishes these rows as cancelled from the same queue.
+                            // Still publish the prior run's cancelledItems above.
+                            if (preparation.signal.aborted)
+                                break;
+                            await this.appShell.sendMessage({
+                                type: "checklist_item_added",
+                                payload: { item, totalItems: seeded.state.items.length },
+                            });
+                        }
+                    });
+                }
+                preparation.signal.throwIfAborted();
+            }
+            this.currentGenerationId = promptId;
             generationTrace = this.startGenerationTrace(request, promptId);
             const activeGenerationTrace = generationTrace;
             this.clarkProfiler.startSession();
@@ -2442,6 +2870,14 @@ export class AiService extends TracedEventEmitter {
                 this.resolveBaseCommitId(promptId),
                 this.resolveChatSessionId(),
             ]);
+            if (request.responseMetadata?.type === "tool_permission_response") {
+                if (this.isClarkMidTurn()) {
+                    throw new Error("Service is busy");
+                }
+                this.getPendingToolPermissionRequest(request.responseMetadata.responseToMessageId);
+            }
+            this.remediationPreparation?.signal.throwIfAborted();
+            remediationContinuationSignal?.throwIfAborted();
             this.clark.updateContext((context) => {
                 return {
                     ...context,
@@ -2473,15 +2909,19 @@ export class AiService extends TracedEventEmitter {
                     userPreferences: request.userPreferences,
                 };
             });
+            const generationRemediationRequestId = this.remediationRequestId;
             const transitionTo = transitionFrom(this.clark);
             void otelContext
                 .with(activeGenerationTrace.context, () => Promise.resolve(transitionTo({
                 type: USER_SENT_PROMPT,
                 request,
                 inputSource,
+                executeToolPermissionResponse: request.responseMetadata?.type === "tool_permission_response",
+                internal: remediationContinuationSignal ? true : undefined,
             })))
-                .catch((error) => {
+                .catch(async (error) => {
                 activeGenerationTrace.finish(error);
+                this.emit("generationSettled", promptId);
                 if (request.requestId) {
                     this.requestDeduplicator.forget(request.requestId);
                 }
@@ -2496,23 +2936,35 @@ export class AiService extends TracedEventEmitter {
                 this.getLogger().error("[ai-service] Failed to start generation", {
                     error,
                 });
+                if (generationRemediationRequestId) {
+                    await this.failRemediationDispatch(generationRemediationRequestId, promptOutcomeDedupeKey, "dispatch_failed", undefined, error);
+                }
             });
+            generationStarted = true;
         }
         catch (error) {
             generationTrace?.finish(error);
-            if (request.requestId) {
-                this.requestDeduplicator.forget(request.requestId);
-            }
             recordPromptOutcome({
                 dedupeKey: resolvePromptRequestDedupeKey(request),
                 outcome: "failure",
                 failure: promptFailurePlatform("handler_error"),
                 coreModel: request.llmConfig?.coreModel,
-                promptId: this.clark.context.promptId,
+                promptId,
                 streakEligible: generateStreakEligible,
             });
             throw error;
         }
+        finally {
+            if (this.remediationPreparation === remediationPreparation)
+                this.remediationPreparation = undefined;
+            this.generationStarting = false;
+            if (!generationStarted) {
+                if (requestMarked && request.requestId) {
+                    this.requestDeduplicator.forget(request.requestId);
+                }
+                this.emit("generationSettled", promptId);
+            }
+        }
     }
     async handleAiSummarizeApiUsage(request) {
         if (this.clark.state === ClarkStateNames.Dead) {
@@ -3066,67 +3518,103 @@ export class AiService extends TracedEventEmitter {
             : "User closed the integration setup form. The integration setup might not have been completed successfully.");
     }
     async handleUserCanceled(reason) {
+        if (this.remediationCancellation)
+            return this.remediationCancellation;
+        const busy = this.isBusy();
+        const awaitingUser = this.isAwaitingUser();
+        const cancelledContext = { ...this.clark.context };
+        const cancelRemediation = this.remediationRequestId || this.remediationPreparation;
+        this.remediationAutoDispatch?.abort(createAbortReason("user-cancel"));
         if (reason === "stop")
             this.reportAbandonTurn(reason);
         // Drop parked/in-flight permission prompts first so interval replay and
         // grace expiry cannot keep pushing the dialog or inject a continuation
         // after the user has already stopped the turn.
         clearPendingToolPermissionRequest(this.clark, "user-canceled");
-        const awaitingUser = this.isAwaitingUser();
-        if (!this.isBusy() && !awaitingUser) {
-            return;
-        }
-        this.clark.updateContext((context) => ({
-            ...context,
-            userInitiatedPromptAbort: true,
-        }));
-        this.clark.context.abortController?.abort(createAbortReason("user-cancel"));
-        if (this.isBusy()) {
-            const { promptId, workflowMetrics } = this.clark.context;
-            const labels = resolvePromptMetricLabels(this.clark.context);
-            // Fire-and-forget: calculatePromptCost has no timeout and reconnect can
-            // sleep for seconds. Cancel teardown must not wait on a billing RPC —
-            // the in-flight map already dedupes a racing Idle handler, and locals
-            // above survive the context clear below.
-            void finalizePromptBillingMetrics({
-                chatSessionStore: this.chatSessionStore,
-                labels,
-                logger: this.getLogger(),
-                promptId,
-                promptUsageAlarmThreshold: this.config.features?.promptUsageAlarmThreshold,
-                workflowMetrics,
+        this.remediationPreparation?.abort(createAbortReason("user-cancel"));
+        if (busy || awaitingUser) {
+            this.clark.updateContext({ userInitiatedPromptAbort: true });
+            this.clark.context.abortController?.abort(createAbortReason("user-cancel"));
+        }
+        if (cancelRemediation) {
+            this.remediationCancellation = this.remediationChecklistQueue.enqueue(async () => {
+                const remediationRequestId = this.remediationRequestId;
+                if (!remediationRequestId)
+                    return;
+                const cancelledItems = await cancelPolicyRemediation(this.appRootDirPath, remediationRequestId);
+                this.remediationRequestId = undefined;
+                for (const item of cancelledItems) {
+                    try {
+                        await this.appShell.sendMessage({
+                            type: "checklist_item_updated",
+                            payload: { item },
+                        });
+                    }
+                    catch (error) {
+                        this.getLogger().error("[ai-service] Failed to publish remediation cancellation", getErrorMeta(error));
+                    }
+                }
             });
-            recordPromptOutcome({
-                dedupeKey: resolvePromptOutcomeDedupeKey(this.clark.context),
-                outcome: "failure",
+        }
+        try {
+            if (!busy && !awaitingUser) {
+                return;
+            }
+            if (busy) {
+                const { promptId, workflowMetrics } = cancelledContext;
+                const labels = resolvePromptMetricLabels(cancelledContext);
+                // Fire-and-forget: calculatePromptCost has no timeout and reconnect can
+                // sleep for seconds. Cancel teardown must not wait on a billing RPC —
+                // the in-flight map already dedupes a racing Idle handler, and locals
+                // above survive the context clear below.
+                void finalizePromptBillingMetrics({
+                    chatSessionStore: this.chatSessionStore,
+                    labels,
+                    logger: this.getLogger(),
+                    promptId,
+                    promptUsageAlarmThreshold: this.config.features?.promptUsageAlarmThreshold,
+                    workflowMetrics,
+                });
+                recordPromptOutcome({
+                    dedupeKey: resolvePromptOutcomeDedupeKey(cancelledContext),
+                    outcome: "failure",
+                    failure: promptFailureUserCanceled(),
+                    promptId: cancelledContext.promptId,
+                    ...labels,
+                });
+            }
+            if (awaitingUser && cancelledContext.awaitingUserHandoffRecorded) {
+                recordAwaitingUserHandoffDismissed({
+                    awaitingUserHandoffPromptId: cancelledContext.awaitingUserHandoffPromptId,
+                    awaitingUserHandoffRecorded: cancelledContext.awaitingUserHandoffRecorded,
+                    promptId: cancelledContext.promptId,
+                    promptOutcomeDedupeKey: cancelledContext.promptOutcomeDedupeKey,
+                    reason: "cancel",
+                });
+            }
+            // Clear the prompt_id since this prompt was abandoned
+            this.clark.updateContext((context) => ({
+                ...context,
+                promptId: undefined,
+                promptOutcomeDedupeKey: undefined,
+                usageMetadata: undefined,
+                baseCommitId: undefined,
+                awaitingUserHandoffPromptId: undefined,
+                awaitingUserHandoffRecorded: undefined,
+            }));
+            void this.clark.send({
+                type: USER_CANCELED,
                 failure: promptFailureUserCanceled(),
-                promptId: this.clark.context.promptId,
-                ...labels,
             });
         }
-        if (awaitingUser && this.clark.context.awaitingUserHandoffRecorded) {
-            recordAwaitingUserHandoffDismissed({
-                awaitingUserHandoffPromptId: this.clark.context.awaitingUserHandoffPromptId,
-                awaitingUserHandoffRecorded: this.clark.context.awaitingUserHandoffRecorded,
-                promptId: this.clark.context.promptId,
-                promptOutcomeDedupeKey: this.clark.context.promptOutcomeDedupeKey,
-                reason: "cancel",
-            });
+        finally {
+            try {
+                await this.remediationCancellation;
+            }
+            finally {
+                this.remediationCancellation = undefined;
+            }
         }
-        // Clear the prompt_id since this prompt was abandoned
-        this.clark.updateContext((context) => ({
-            ...context,
-            promptId: undefined,
-            promptOutcomeDedupeKey: undefined,
-            usageMetadata: undefined,
-            baseCommitId: undefined,
-            awaitingUserHandoffPromptId: undefined,
-            awaitingUserHandoffRecorded: undefined,
-        }));
-        void this.clark.send({
-            type: USER_CANCELED,
-            failure: promptFailureUserCanceled(),
-        });
     }
     /**
      * UI-initiated cancellation of a background task. Delegates to
@@ -3201,6 +3689,9 @@ export class AiService extends TracedEventEmitter {
             await this.handleAiGenerate(request, inputSource);
             return { generationId: this.clark.context.promptId, status: "started" };
         }
+        if (request.responseMetadata?.type === "tool_permission_response") {
+            throw new Error("Service is busy");
+        }
         await this.interruptAndContinue(request, inputSource);
         return {
             generationId: this.clark.context.promptId,
@@ -3392,11 +3883,19 @@ export class AiService extends TracedEventEmitter {
                 if (!(await this.waitUntilToolPermissionContinuationAllowed(messageId))) {
                     return;
                 }
+                // A reconnect during the wait above moves the deadline and may still
+                // be replaying this prompt. Expiring from the old timer would write a
+                // delivery error for the message id that replay is delivering.
+                await inFlightToolPermissionReplay(this.clark);
                 const expired = this.clark.context.pendingToolPermissionRequest;
                 if (expired?.messageId !== messageId ||
                     expired.delivery.status !== "parked") {
                     return;
                 }
+                if (Date.now() < expired.delivery.expiresAtMs) {
+                    this.scheduleToolPermissionExpiry(messageId);
+                    return;
+                }
                 const error = createExpiredPermissionPromptDeliveryError(expired.toolName, expired.delivery);
                 recordToolPermissionDeliveryOutcome("expired");
                 await this.handleToolPermissionOutcome({
@@ -3409,17 +3908,12 @@ export class AiService extends TracedEventEmitter {
             });
         }, expiresInMs);
     }
-    /**
-     * `userSentPrompt` is only valid from Idle or AwaitingUser. A parked
-     * permission can expire while a sibling tool is still generating; wait
-     * until the continuation can actually run, or abort if the request is gone.
-     */
+    /** Wait for a pending permission decision to become a valid continuation. */
     async waitUntilToolPermissionContinuationAllowed(messageId) {
         const TOOL_PERMISSION_CONTINUATION_POLL_MS = 250;
         for (;;) {
             const current = this.clark.context.pendingToolPermissionRequest;
-            if (current?.messageId !== messageId ||
-                current.delivery.status !== "parked") {
+            if (current?.messageId !== messageId) {
                 return false;
             }
             switch (this.clark.state) {
@@ -3449,12 +3943,18 @@ export class AiService extends TracedEventEmitter {
             const pending = this.clark.context.pendingToolPermissionRequest;
             if (pending?.messageId !== messageId ||
                 pending.delivery.status !== "parked" ||
-                Date.now() >= pending.delivery.expiresAtMs) {
+                this.clark.state === ClarkStateNames.Dead) {
+                return;
+            }
+            if (Date.now() >= pending.delivery.expiresAtMs) {
+                // Expiry can wait for Clark to become idle. Keep this retry loop armed
+                // so a reconnect that renews the deadline can resume delivery.
+                this.scheduleToolPermissionReplay(messageId);
                 return;
             }
-            const replay = this.stablePeer.isConnected
-                ? flushPendingToolPermissionPrompt(this.clark, { source: "retry" })
-                : Promise.resolve();
+            const replay = flushPendingToolPermissionPrompt(this.clark, {
+                source: "retry",
+            });
             void replay.finally(() => {
                 const current = this.clark.context.pendingToolPermissionRequest;
                 if (current?.messageId === messageId &&
@@ -3487,26 +3987,97 @@ export class AiService extends TracedEventEmitter {
             });
             return;
         }
+        const pendingRequest = this.getPendingToolPermissionRequest(request.messageId);
+        if (this.clark.state === ClarkStateNames.Dead) {
+            throw new Error("Service is unavailable");
+        }
+        // Only yield while Clark is mid-generation: awaiting in the common case
+        // would let a concurrent continuation pass the busy check below before
+        // this one claims `generationStarting`.
+        if (this.clark.state !== ClarkStateNames.Idle &&
+            this.clark.state !== ClarkStateNames.AwaitingUser &&
+            !(await this.waitUntilToolPermissionContinuationAllowed(request.messageId))) {
+            return;
+        }
+        if (this.isBusy()) {
+            throw new Error("Service is busy");
+        }
+        const promptOutcomeDedupeKey = randomUUID();
+        let generationStarted = false;
+        this.generationStarting = true;
+        try {
+            await this.config.waitForAppFiles?.(promptOutcomeDedupeKey);
+            this.currentGenerationId = promptOutcomeDedupeKey;
+            // The response is now accepted (matches the pending request). Record its id
+            // and honor the result so a re-send dropped here can't be applied twice. A
+            // duplicate that loses the atomic `markIfNew` bails before the tool runs.
+            // (APPS-4663)
+            if (request.kind === "response" &&
+                request.requestId &&
+                !this.requestDeduplicator.markIfNew(request.requestId)) {
+                logger.warn("[ai-service] Ignoring duplicate tool-permission re-send (lost dedup race)", { requestId: request.requestId });
+                return;
+            }
+            const continueRequest = await this.resolveToolPermissionOutcome(request, pendingRequest);
+            if (!continueRequest) {
+                return;
+            }
+            this.clark.updateContext({ promptOutcomeDedupeKey });
+            recordPromptAttempt({
+                coreModel: this.clark.context.llmConfig?.coreModel,
+                entrypoint: PROMPT_ATTEMPT_ENTRYPOINT.tool_permission_continuation,
+                outcomeDedupeKey: promptOutcomeDedupeKey,
+            });
+            const transitionTo = transitionFrom(this.clark);
+            void Promise.resolve(transitionTo({
+                type: USER_SENT_PROMPT,
+                request: { ...continueRequest, requestId: promptOutcomeDedupeKey },
+            })).catch((error) => {
+                this.emit("generationSettled", promptOutcomeDedupeKey);
+                logger.error("[ai-service] Failed to continue after tool permission", {
+                    error,
+                });
+            });
+            generationStarted = true;
+        }
+        finally {
+            this.generationStarting = false;
+            if (!generationStarted) {
+                this.emit("generationSettled", promptOutcomeDedupeKey);
+            }
+        }
+    }
+    getPendingToolPermissionRequest(messageId) {
         const pendingRequest = this.clark.context.pendingToolPermissionRequest;
-        logger.info(`[ai-service] Pending request: ${JSON.stringify(pendingRequest)}`);
         if (!pendingRequest) {
-            logger.warn(`[ai-service] No pending tool permission request found for messageId=${request.messageId}`);
             throw new Error("No pending tool permission request");
         }
-        if (pendingRequest.messageId !== request.messageId) {
-            logger.warn(`[ai-service] Message ID mismatch: expected=${pendingRequest.messageId}, got=${request.messageId}`);
+        if (pendingRequest.messageId !== messageId) {
             throw new Error("Message ID mismatch");
         }
-        // The response is now accepted (matches the pending request). Record its id
-        // and honor the result so a re-send dropped here can't be applied twice. A
-        // duplicate that loses the atomic `markIfNew` bails before the tool runs.
-        // (APPS-4663)
-        if (request.kind === "response" &&
-            request.requestId &&
-            !this.requestDeduplicator.markIfNew(request.requestId)) {
-            logger.warn("[ai-service] Ignoring duplicate tool-permission re-send (lost dedup race)", { requestId: request.requestId });
-            return;
+        return pendingRequest;
+    }
+    async resolveToolPermissionResponse(request) {
+        const metadata = request.responseMetadata;
+        if (metadata?.type !== "tool_permission_response") {
+            throw new Error("Expected a tool permission response");
         }
+        const pendingRequest = this.getPendingToolPermissionRequest(metadata.responseToMessageId);
+        return this.resolveToolPermissionOutcome({
+            kind: "response",
+            messageId: metadata.responseToMessageId,
+            approved: metadata.approved === true,
+            alwaysAllowPermissions: metadata.alwaysAllowPermissions,
+            denyMessage: metadata.approved ? undefined : request.prompt,
+        }, pendingRequest, metadata.clarification === true);
+    }
+    async resolveToolPermissionOutcome(request, pendingRequest, clarification) {
+        const logger = this.getLogger();
+        const approved = request.kind === "response" && request.approved;
+        const { promptId, promptOutcomeDedupeKey, abortController } = this.clark.context;
+        const isCurrentResponse = () => !abortController?.signal.aborted &&
+            this.clark.context.promptId === promptId &&
+            this.clark.context.promptOutcomeDedupeKey === promptOutcomeDedupeKey;
         logger.info(`[ai-service] Clearing pending request`);
         // Clear the pending request and notify UI
         clearPendingToolPermissionRequest(this.clark, request.kind === "delivery_error"
@@ -3530,12 +4101,21 @@ export class AiService extends TracedEventEmitter {
                 },
             ],
         };
-        let toolResultMessage;
+        const chatSessionId = this.chatSessionStore.getChatSessionId();
+        const isClarification = clarification ??
+            isToolPermissionClarification(approved, request.kind === "response" ? request.denyMessage : undefined);
+        let outcome;
         if (approved) {
-            // Approve in entity permission store
-            this.entityPermissionStore.approveToolCall(toolName, rawInput);
             const signature = getToolCallSignature(toolName, rawInput);
             const formattedArgs = await getToolCallArguments(toolName, rawInput, this.clark);
+            // The answer stays consumed: whatever superseded it (a cancel or a
+            // newer prompt) also retires the request it answered.
+            if (!isCurrentResponse()) {
+                recordToolPermissionLateOutcome("skipped");
+                logger.warn("[ai-service] An approved tool permission was superseded before its tool ran", { toolCallId, toolName });
+                return;
+            }
+            this.entityPermissionStore.approveToolCall(toolName, rawInput);
             logger.info(`[ai-service] Sending tool call message: tool=${toolName}, toolCallId=${toolCallId}, signature=${signature}`);
             void sendUserMessage({
                 role: "assistant",
@@ -3552,116 +4132,19 @@ export class AiService extends TracedEventEmitter {
                     void this.entityPermissionStore.approve(permission.entityType, permission.entityId, permission.permissionType);
                 });
             }
-            // Execute the tool with proper access control context from Clark
-            const accessControlContext = this.clark.getAccessControl(this.config.features);
-            logger.info(`[ai-service] Executing approved tool: ${toolName}`);
-            logger.info(`[ai-service] Access control context: mode=${accessControlContext.mode}`);
-            try {
-                const result = await this.toolRegistry.execute(toolName, rawInput, accessControlContext, { toolCallId, messages: [] });
-                if (result.type === "success") {
-                    toolResultMessage = {
-                        role: "tool",
-                        content: [
-                            {
-                                type: "tool-result",
-                                toolCallId,
-                                toolName,
-                                output: { type: "json", value: result.data },
-                            },
-                        ],
-                    };
-                    // Use getToolOutput for consistent formatting with processStreamChunk
-                    const output = getToolOutput(toolName, result.data);
-                    void sendUserMessage({
-                        role: "assistant",
-                        content: "",
-                        type: "tool-result",
-                        toolCallId,
-                        toolName,
-                        output,
-                    });
-                }
-                else {
-                    logger.warn(`[ai-service] Tool ${toolName} execution failed: ${result.error.message}`);
-                    toolResultMessage = {
-                        role: "tool",
-                        content: [
-                            {
-                                type: "tool-result",
-                                toolCallId,
-                                toolName,
-                                output: {
-                                    type: "error-json",
-                                    value: { error: result.error.message },
-                                },
-                                isError: true,
-                            },
-                        ],
-                    };
-                    // Use getToolErrorCode for consistent formatting with processStreamChunk
-                    const errorCode = getToolErrorCode(result.error);
-                    void sendUserMessage({
-                        role: "assistant",
-                        content: "",
-                        type: "tool-error",
-                        toolCallId,
-                        toolName,
-                        error: getToolErrorMessage(result.error.cause ?? result.error),
-                        errorCode,
-                    });
-                }
-            }
-            catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                // Provider-facing context expects tool failures to be encoded as
-                // errored tool results so they still satisfy the preceding tool call.
-                toolResultMessage = {
-                    role: "tool",
-                    content: [
-                        {
-                            type: "tool-result",
-                            toolCallId,
-                            toolName,
-                            output: {
-                                type: "error-json",
-                                value: { error: errorMessage },
-                            },
-                            isError: true,
-                        },
-                    ],
-                };
-                // Use getToolErrorCode for consistent formatting with processStreamChunk
-                const errorCode = getToolErrorCode(error);
-                void sendUserMessage({
-                    role: "assistant",
-                    content: "",
-                    type: "tool-error",
-                    toolCallId,
-                    toolName,
-                    error: errorMessage,
-                    errorCode,
-                });
-            }
+            outcome = await this.executeApprovedTool(toolName, rawInput, toolCallId, abortController?.signal);
         }
         else if (request.kind === "delivery_error") {
-            toolResultMessage = {
-                role: TOOL_MESSAGE_ROLE,
-                content: [
-                    {
-                        type: TOOL_RESULT_CONTENT_TYPE,
-                        toolCallId,
-                        toolName,
-                        output: {
-                            type: ERROR_JSON_OUTPUT_TYPE,
-                            value: { error: request.error.message },
-                        },
-                        isError: true,
-                    },
-                ],
+            outcome = {
+                toolResultMessage: toolErrorResult(toolCallId, toolName, request.error.message),
             };
         }
         else {
-            const denyReason = request.denyMessage || "User denied permission for this tool call";
+            // A clarification reaches Clark as the user's next message, where the
+            // prompt safety checks see it. Repeating it here would leak it past them.
+            const denyReason = isClarification
+                ? CLARIFICATION_DENY_REASON
+                : request.denyMessage || "User denied permission for this tool call";
             if (toolName === "testApi") {
                 const apiName = rawInput?.apiName;
                 if (apiName) {
@@ -3675,56 +4158,51 @@ export class AiService extends TracedEventEmitter {
                     });
                 }
             }
-            toolResultMessage = {
-                role: "tool",
-                content: [
-                    {
-                        type: "tool-result",
-                        toolCallId,
-                        toolName,
-                        output: {
-                            type: "error-json",
-                            value: { error: `Permission denied: ${denyReason}` },
-                        },
-                        isError: true,
-                    },
-                ],
+            outcome = {
+                toolResultMessage: toolErrorResult(toolCallId, toolName, `Permission denied: ${denyReason}`),
             };
             logger.info(`[ai-service] Tool ${toolName} permission denied, error injected into context`);
         }
-        const contextManagement = this.buildContextManagementForCurrentClark(llmConfig);
-        const context = await this.contextManagerV2.getOrCreateContext(contextId, llmConfig?.contextOptionsV2, undefined, contextManagement);
-        const placeholderUsage = {
-            inputTokens: 0,
-            outputTokens: 0,
-            totalTokens: 0,
-            inputTokenDetails: {
-                noCacheTokens: 0,
-                cacheReadTokens: 0,
-                cacheWriteTokens: 0,
-            },
-            outputTokenDetails: {
-                textTokens: 0,
-                reasoningTokens: 0,
-            },
-        };
-        await context.addResponse(assistantMessage, placeholderUsage);
-        await context.addResponse(toolResultMessage, placeholderUsage);
-        // Check for pending escalations that were deferred during tool execution
-        // (because Clark was in AwaitingUser state for the permission request)
+        // The tool or its denial has already taken effect, so the outcome is
+        // recorded even when a cancel or a newer prompt superseded this response.
+        // Otherwise Clark cannot know the tool ran and may run it again. Only a
+        // chat reset discards it: the conversation it belonged to is gone.
+        if (this.chatSessionStore.getChatSessionId() !== chatSessionId) {
+            recordToolPermissionLateOutcome("discarded");
+            logger.warn("[ai-service] Discarded a tool permission outcome from a reset chat", { toolCallId, toolName });
+            return;
+        }
+        const currentBeforeRecording = isCurrentResponse();
+        try {
+            await this.recordToolPermissionOutcome(contextId, llmConfig, assistantMessage, outcome, sendUserMessage);
+        }
+        catch (error) {
+            if (currentBeforeRecording) {
+                throw error;
+            }
+            recordToolPermissionLateOutcome("discarded");
+            logger.warn("[ai-service] Could not record a superseded tool permission outcome", { toolCallId, toolName, ...getErrorMeta(error) });
+            return;
+        }
+        if (!isCurrentResponse()) {
+            recordToolPermissionLateOutcome("recorded");
+            logger.info("[ai-service] Recorded a superseded tool permission outcome without continuing", { toolCallId, toolName });
+            return;
+        }
         if (hasPendingEscalations()) {
             logger.info(`[ai-service] Found pending escalation(s) after tool execution, flushing...`);
             const escalationSent = await flushPendingEscalations({
                 clark: this.clark,
                 services: { chatSessionStore: this.chatSessionStore },
                 logger,
-                force: true, // Bypass the AwaitingUser check since we're handling it here
-                skipStateTransition: true, // Clark is already in AwaitingUser
+                force: true,
+                skipStateTransition: true,
             });
+            if (!isCurrentResponse()) {
+                return;
+            }
             if (escalationSent) {
-                logger.info(`[ai-service] Sent escalation multi_choice to user, staying in AwaitingUser`);
-                // Stay in AwaitingUser state - don't transition to AgentPlanning
-                // The user needs to respond to the escalation
+                logger.info(`[ai-service] Sent escalation multi_choice to user`);
                 return;
             }
         }
@@ -3734,7 +4212,6 @@ export class AiService extends TracedEventEmitter {
         if (!this.clark.context.llmConfig) {
             throw new Error("Cannot continue after tool permission: llmConfig is missing from context");
         }
-        const isClarification = isToolPermissionClarification(approved, request.kind === "response" ? request.denyMessage : undefined);
         logger.info("[ai-service] tool_permission_response continuation", {
             approved,
             clarification: isClarification,
@@ -3743,21 +4220,6 @@ export class AiService extends TracedEventEmitter {
         trace
             .getActiveSpan()
             ?.setAttribute("clark.tool_permission.clarification", isClarification);
-        const promptOutcomeDedupeKey = randomUUID();
-        this.clark.updateContext((context) => ({
-            ...context,
-            promptOutcomeDedupeKey,
-        }));
-        // The continuation is a genuine new turn on a fresh key (the handoff
-        // already recorded an outcome on the original). Pair it with an attempt
-        // so attempts_total and outcomes_total stay aligned (ENG-5477 review).
-        // Tag the entrypoint so dashboards can separate ~server-driven volume
-        // from user aiGenerate (ENG-5477 scout review).
-        recordPromptAttempt({
-            coreModel: this.clark.context.llmConfig?.coreModel,
-            entrypoint: PROMPT_ATTEMPT_ENTRYPOINT.tool_permission_continuation,
-            outcomeDedupeKey: promptOutcomeDedupeKey,
-        });
         const continueRequest = {
             prompt: approved || request.kind === "delivery_error"
                 ? ``
@@ -3772,7 +4234,7 @@ export class AiService extends TracedEventEmitter {
             llmConfig: this.clark.context.llmConfig,
             mode: this.clark.context.currentMode,
             browserContext: this.clark.context.browserContext,
-            requestId: promptOutcomeDedupeKey,
+            requestId: this.clark.context.promptOutcomeDedupeKey,
             responseMetadata: {
                 type: "tool_permission_response",
                 responseToMessageId: request.messageId,
@@ -3786,11 +4248,101 @@ export class AiService extends TracedEventEmitter {
                 ...(isClarification ? { clarification: true } : {}),
             },
         };
-        const transitionTo = transitionFrom(this.clark);
-        void transitionTo({
-            type: USER_SENT_PROMPT,
-            request: continueRequest,
-        });
+        return continueRequest;
+    }
+    /**
+     * Run a user-approved tool with the turn's abort signal, so a cancel stops
+     * it instead of leaving it running unobserved.
+     */
+    async executeApprovedTool(toolName, rawInput, toolCallId, abortSignal) {
+        const logger = this.getLogger();
+        const accessControlContext = this.clark.getAccessControl(this.config.features);
+        logger.info(`[ai-service] Executing approved tool: ${toolName}`);
+        logger.info(`[ai-service] Access control context: mode=${accessControlContext.mode}`);
+        try {
+            const result = await this.toolRegistry.execute(toolName, rawInput, accessControlContext, { abortSignal, messages: [], toolCallId });
+            if (result.type === "success") {
+                return {
+                    chatMessage: {
+                        role: "assistant",
+                        content: "",
+                        type: "tool-result",
+                        toolCallId,
+                        toolName,
+                        // Use getToolOutput for consistent formatting with processStreamChunk
+                        output: getToolOutput(toolName, result.data),
+                    },
+                    toolResultMessage: {
+                        role: TOOL_MESSAGE_ROLE,
+                        content: [
+                            {
+                                type: TOOL_RESULT_CONTENT_TYPE,
+                                toolCallId,
+                                toolName,
+                                output: { type: "json", value: toJsonValue(result.data) },
+                            },
+                        ],
+                    },
+                };
+            }
+            logger.warn(`[ai-service] Tool ${toolName} execution failed: ${result.error.message}`);
+            return {
+                chatMessage: {
+                    role: "assistant",
+                    content: "",
+                    type: "tool-error",
+                    toolCallId,
+                    toolName,
+                    error: getToolErrorMessage(result.error.cause ?? result.error),
+                    // Use getToolErrorCode for consistent formatting with processStreamChunk
+                    errorCode: getToolErrorCode(result.error),
+                },
+                toolResultMessage: toolErrorResult(toolCallId, toolName, result.error.message),
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                chatMessage: {
+                    role: "assistant",
+                    content: "",
+                    type: "tool-error",
+                    toolCallId,
+                    toolName,
+                    error: errorMessage,
+                    errorCode: getToolErrorCode(error),
+                },
+                toolResultMessage: toolErrorResult(toolCallId, toolName, errorMessage),
+            };
+        }
+    }
+    async recordToolPermissionOutcome(contextId, llmConfig, toolCall, outcome, sendUserMessage) {
+        if (outcome.chatMessage) {
+            void sendUserMessage(outcome.chatMessage);
+        }
+        const context = await this.toolPermissionOutcomeContext(contextId, llmConfig);
+        await context.addResponses([toolCall, outcome.toolResultMessage], TOOL_PERMISSION_PLACEHOLDER_USAGE);
+    }
+    /**
+     * The context a tool permission outcome is written to, retried a bounded
+     * number of times so a transient store failure does not drop the record of a
+     * tool that already ran. Only acquisition is retried: addResponses ingests
+     * each message before persisting it, so repeating it could duplicate the
+     * tool call.
+     */
+    async toolPermissionOutcomeContext(contextId, llmConfig) {
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                const contextManagement = this.buildContextManagementForCurrentClark(llmConfig);
+                return await this.contextManagerV2.getOrCreateContext(contextId, llmConfig?.contextOptionsV2, undefined, contextManagement);
+            }
+            catch (error) {
+                if (attempt >= TOOL_PERMISSION_CONTEXT_ATTEMPTS) {
+                    throw error;
+                }
+                await new Promise((resolve) => setTimeout(resolve, TOOL_PERMISSION_CONTEXT_RETRY_MS * attempt));
+            }
+        }
     }
     /**
      * Builds a continuation prompt when a tool permission is denied.
@@ -3849,6 +4401,15 @@ export class AiService extends TracedEventEmitter {
             lastGenerationState: this.clark.context.lastGenerationState,
         });
     }
+    getChatStateSnapshot() {
+        const generationState = this.resolveGenerationStateForUi();
+        return {
+            generationState,
+            activeInteractiveMessage: generationState?.state === AiGenerationState.AWAITING_USER_INPUT
+                ? this.clark.context.activeInteractiveMessage?.payload
+                : undefined,
+        };
+    }
     /**
      * A gateway peer asked for a turn. Clark's pushes and tool callbacks for it
      * are routed to that peer for as long as it is attached, without giving it
@@ -3995,6 +4556,103 @@ export class AiService extends TracedEventEmitter {
         //    push retries on a later bind.
         void this.chatSessionStore.reconcileAbandonedToolCalls();
         this.tryAutoDispatchMigrationTurnIfReady();
+        void this.pushRestoredContextUsage();
+    }
+    /** Occupancy-ring flags only. Do not pass into getOrCreateContext. */
+    editorContextOptionsV2;
+    applyEditorContextOptions(contextOptionsV2) {
+        // Assigned even when empty. The editor is authoritative for the ring, so
+        // keeping the previous value here would outlive an override it cleared.
+        this.editorContextOptionsV2 = contextOptionsV2;
+        if (this.isBusy()) {
+            return;
+        }
+        void this.pushRestoredContextUsageFromDisk();
+    }
+    /**
+     * Fill the chat occupancy ring from the last completed step, or from the
+     * restored conversation on disk when this process has not streamed yet.
+     */
+    async pushRestoredContextUsage() {
+        if (this.clark.replayLastContextUsage?.()) {
+            return;
+        }
+        if (this.isBusy()) {
+            return;
+        }
+        await this.pushRestoredContextUsageFromDisk();
+    }
+    restoredContextUsageRead;
+    restoredContextUsageRerun = false;
+    /**
+     * One read at a time: parallel getOrCreateContext calls on a cold cache each
+     * build their own ContextV2. A caller that arrives mid-read reruns it once.
+     */
+    pushRestoredContextUsageFromDisk() {
+        if (this.restoredContextUsageRead) {
+            this.restoredContextUsageRerun = true;
+            return this.restoredContextUsageRead;
+        }
+        this.restoredContextUsageRead = (async () => {
+            try {
+                do {
+                    this.restoredContextUsageRerun = false;
+                    await this.readRestoredContextUsageFromDisk();
+                } while (this.restoredContextUsageRerun);
+            }
+            finally {
+                this.restoredContextUsageRead = undefined;
+            }
+        })();
+        return this.restoredContextUsageRead;
+    }
+    async readRestoredContextUsageFromDisk() {
+        const generation = this.clark.getContextUsageGeneration?.();
+        // No JWT yet means no user; updateClarkJwt retries once it arrives.
+        const contextId = this.getContextId();
+        if (!contextId) {
+            return;
+        }
+        try {
+            const displayOptions = this.editorContextOptionsV2 ??
+                this.clark.context.llmConfig?.contextOptionsV2;
+            if (typeof displayOptions?.contextLimit !== "number") {
+                return;
+            }
+            const context = await this.contextManagerV2.getOrCreateContext(contextId);
+            const lastKnownInputTokens = context.getLastKnownInputTokens();
+            const messages = await context.getMessages();
+            const storedBreakdown = context.getLastContextUsage()?.breakdown;
+            if (lastKnownInputTokens <= 0 &&
+                messages.length === 0 &&
+                !storedBreakdown) {
+                return;
+            }
+            const snapshot = buildRestoredContextUsageSnapshot({
+                contextOptions: displayOptions,
+                lastKnownInputTokens,
+                messages,
+                storedBreakdown,
+            });
+            if (snapshot.contextUsed <= 0) {
+                return;
+            }
+            // A New Chat, restore or live step during the reads above makes this stale.
+            if (this.isBusy() ||
+                this.clark.getContextUsageGeneration?.() !== generation) {
+                return;
+            }
+            const { breakdown } = snapshot;
+            if (breakdown.systemPrompt > 0 ||
+                breakdown.tools > 0 ||
+                breakdown.summarizedConversation > 0) {
+                this.clark.rememberContextUsage(snapshot);
+            }
+            catchBackgroundPeerDisconnect(this.stablePeer.call.aiPushContextUsed(snapshot), "restored context usage push");
+        }
+        catch (error) {
+            this.getLogger().warn("[ai-service] Failed to restore context usage before the next step", getErrorMeta(error));
+        }
     }
     /**
      * Per-session set of peer IDs that connected since their last task
@@ -4062,6 +4720,9 @@ export class AiService extends TracedEventEmitter {
                 logger: this.getLogger(),
             }, callerUserId);
         }
+        if (this.stablePeer.peerId === peerId) {
+            void this.pushRestoredContextUsage();
+        }
     }
     /**
      * @param replacement An editor socket that is still attached. Clark's RPCs
@@ -4928,6 +5589,13 @@ export class AiService extends TracedEventEmitter {
             pendingToolPermissionRequest: undefined,
             resumeAfterAuthFailure: undefined,
         });
+        this.clark.clearLastContextUsage?.();
+        if (!this.isBusy()) {
+            catchBackgroundPeerDisconnect(sendUserGenerationStateChannel(this.clark)({
+                state: AiGenerationState.IDLE,
+                chatSessionReset: true,
+            }), "new chat generation state push");
+        }
     }
     reportAbandonTurn(action) {
         if (!isAiAbandonTurnState(this.clark.state))
@@ -4963,6 +5631,7 @@ export class AiService extends TracedEventEmitter {
     /** Clears local LLM context so migration-era memory does not survive abort. */
     async clearMigrationAbortLocalContext() {
         this.clark.updateContext({ resumeAfterAuthFailure: undefined });
+        this.clark.clearLastContextUsage?.();
         const contextId = getContextId(this.clark, this.config);
         await this.contextManagerV2.clearAllContexts();
         if (contextId) {
@@ -4976,11 +5645,13 @@ export class AiService extends TracedEventEmitter {
      */
     async uploadEmptyContextToBucketeer(commitId) {
         const jwt = this.getInferenceJwt();
-        const branchName = this._syncContextProvider?.getBranchName();
-        if (!jwt || !commitId || !branchName) {
+        if (!jwt || !commitId) {
             return;
         }
         try {
+            const branchName = await this._syncContextProvider?.getBranchName();
+            if (!branchName)
+                return;
             await uploadContextToBucketeer({
                 applicationId: this.config.applicationId,
                 commitId,
@@ -5086,6 +5757,15 @@ export class AiService extends TracedEventEmitter {
         };
     }
     async handleRestoreToCommit(sinceTimestamp, commitId, applicationId, branchName) {
+        try {
+            await this.restoreToCommit(sinceTimestamp, commitId, applicationId, branchName);
+        }
+        finally {
+            // The editor empties its ring when a restore starts; refill it before replying.
+            await this.pushRestoredContextUsage();
+        }
+    }
+    async restoreToCommit(sinceTimestamp, commitId, applicationId, branchName) {
         // Note: clark.context.jwt should be set by the socket handler (socket-manager.ts) before
         // this method is called. The socket handler updates it from peerAuthorization if missing.
         const jwt = this.clark?.context?.jwt;
@@ -5162,6 +5842,7 @@ export class AiService extends TracedEventEmitter {
             this.getLogger().info(`[handleRestoreToCommit] No context restored (${outcome}) for commitId=${commitId}; leaving chat intact`, { applicationId, branchName });
             return;
         }
+        this.clark.clearLastContextUsage?.();
         // 2. Context is rolled back — truncate the server chat to match. This is a
         // cross-service RPC and is NOT transactional with the context rollback
         // above, so a failure here leaves the context rolled back while the chat
@@ -5209,6 +5890,10 @@ export class AiService extends TracedEventEmitter {
         // timestamps and regenerating from YAML on-demand when YAML is newer.
     }
     isBusy() {
+        return this.generationStarting || this.isClarkMidTurn();
+    }
+    /** Whether Clark's own state machine is running a turn, ignoring a turn still being started. */
+    isClarkMidTurn() {
         return (this.clark.state !== ClarkStateNames.Idle &&
             this.clark.state !== ClarkStateNames.AwaitingUser &&
             this.clark.state !== ClarkStateNames.Dead);
@@ -5216,6 +5901,17 @@ export class AiService extends TracedEventEmitter {
     isAwaitingUser() {
         return this.clark.state === ClarkStateNames.AwaitingUser;
     }
+    autoDispatchBlockReason() {
+        if (this.generationStarting ||
+            (this.clark.state !== ClarkStateNames.Idle &&
+                this.clark.state !== ClarkStateNames.AwaitingUser))
+            return "busy";
+        if (this.clark.context.pendingToolPermissionRequest)
+            return "tool_permission";
+        if (this.isAwaitingInteractiveResponse())
+            return "interactive";
+        return undefined;
+    }
     /**
      * True when finalize (or similar) must wait for the user to resolve an
      * interactive prompt or tool-permission widget. Unlike {@link isAwaitingUser},
@@ -5280,13 +5976,21 @@ export class AiService extends TracedEventEmitter {
     /**
      * Resolve generation waiters when Clark reaches a terminal state.
      */
-    triggerGenerationComplete() {
+    triggerGenerationComplete(generationId) {
+        if (generationId !== this.currentGenerationId) {
+            if (generationId !== undefined) {
+                this.emit("generationSettled", generationId);
+            }
+            return;
+        }
         // The FSM parked, so any still-open generation span is over. Runs that
         // completed or failed already ended it via the generation events; this
         // ends it on the paths that emit neither (user/agent cancel,
         // runtime-updated-without-edits, planning errors that park in Idle).
         this.activeGenerationTrace?.finish();
-        this.emit("generationSettled");
+        if (generationId !== undefined) {
+            this.emit("generationSettled", generationId);
+        }
         const waiters = Array.from(this.generationCompleteWaiters);
         this.generationCompleteWaiters.clear();
         for (const resolve of waiters) {
@@ -5307,10 +6011,18 @@ export class AiService extends TracedEventEmitter {
         this.fileSystemInterface.setSourceTracker(sourceTracker);
     }
     setFileSystemManager(fileSystemManager) {
+        this.fileSystemManager = fileSystemManager;
         this.fileSystemInterface.setFileSystemManager(fileSystemManager);
         // Also set the template renderer for YAML→TS sync
         fileSystemManager.setTemplateRenderer(this.templateRenderer);
     }
+    async refreshFileModel() {
+        if (!this.fileSystemManager) {
+            throw new Error("File model is not available");
+        }
+        await this.fileSystemManager.initialize(this.config.appRootDirPath);
+        this.setSourceTracker(this.fileSystemManager.getSourceTracker());
+    }
     setViteServer(server) {
         this.viteServer = server;
     }