@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/migration/migration-verification.js

@@ -0,0 +1,1246 @@
+import crypto from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import yaml from "yaml";
+import z from "zod";
+import { AiEntityType, AiPermissionType, } from "@superblocksteam/library-shared/types";
+import { LanguagePluginID } from "@superblocksteam/shared";
+import { extractIntegrationIdsFromSource, extractMutations, } from "../ai-service/agent/tools/apis/analysis.js";
+import { compareApiResults, } from "../ai-service/agent/tools/apis/api-comparator.js";
+import { ApiExecutor, } from "../ai-service/agent/tools/apis/api-executor.js";
+import { markSdkApiAsVerified } from "../ai-service/agent/tools/apis/api-testing-state.js";
+import { createToolFactory, PermissionLevel, ToolCategory, } from "../ai-service/agent/tools2/types.js";
+import { updateChecklistItem } from "../ai-service/checklist/persisted-checklist-store.js";
+import { isPeerUnavailableError, } from "../ai-service/state-machine/helpers/stable-peer.js";
+import { sanitizeLogMessage } from "../util/log-sanitizer.js";
+import { getLogger } from "../util/logger.js";
+import { OperationQueue } from "../util/operation-queue.js";
+import { inlineV2BackupSourceFiles } from "./inline-v2-backup-source-files.js";
+import { readIntegrationWritePolicyForEnforcement } from "./integration-write-policy.js";
+import { classifyYamlStepMutation } from "./migration-classifier.js";
+import { recordMigrationVerification } from "./migration-metrics.js";
+import { resolveV2BackupYamlPath } from "./resolve-v2-backup-path.js";
+import { forEachYamlStep } from "./yaml-walk.js";
+const SCRATCH_DIR = "scratch";
+const VERIFICATION_DIR = "migration-verification";
+const DIFF_SIZE_CAP = 1024 * 1024; // 1 MB
+const PIPELINE_TIMEOUT_MS = 30_000;
+/**
+ * Hard cap on verification attempts per API per migration. The agent does NOT
+ * decide when to stop iterating — this counter is computed from on-disk
+ * history and enforced inside `runMigrationVerification`. An LLM agent asked
+ * to self-assess "am I converging?" reliably picks the socially acceptable
+ * answer ("yes"); the cap removes that judgment from the loop.
+ */
+export const MAX_VERIFICATION_ATTEMPTS = 10;
+/**
+ * Verification outcomes caused by editor-peer / environment state rather
+ * than by the API under test. These do NOT consume `MAX_VERIFICATION_ATTEMPTS`
+ * — burning real attempts on a backgrounded tab or dropped socket pushed APIs
+ * toward `exhausted` -> `failed`. They are still recorded in history for
+ * diagnostics and for the consecutive-transient backstop below.
+ *
+ * `transient_exhausted` is itself included: it IS a transient outcome (the
+ * backstop tripping), so it keeps the consecutive streak alive while the peer
+ * stays down (each subsequent transient re-trips the backstop) and never
+ * counts as a real attempt.
+ */
+const TRANSIENT_OUTCOME_KINDS = new Set(["timeout", "disconnected", "transient_exhausted"]);
+/**
+ * Runaway backstop: cap on *consecutive* transient (timeout/disconnected)
+ * outcomes for an API. Deliberately generous — transient outcomes don't
+ * consume real attempts, so this exists only to stop an unattended retry loop
+ * from spinning forever against a dead editor peer.
+ *
+ * Counted as a trailing streak that resets on any real (non-transient)
+ * outcome, and checked AFTER the pipeline runs — so a peer that recovers
+ * always gets a fresh real attempt and the API self-heals. Crucially, tripping
+ * it yields `transient_exhausted`, NOT `exhausted`: the environment failing is
+ * never the API's fault, so it must never mark the checklist item `failed`
+ * (that was the Foundever failure mode). Sustained disconnects will get a
+ * durable pause/resume as a follow-up; here the backstop just tells the agent
+ * to stop auto-retrying and escalate to the user.
+ */
+export const MAX_TRANSIENT_VERIFICATION_ATTEMPTS = 30;
+const LANGUAGE_PLUGIN_IDS = new Set(Object.values(LanguagePluginID));
+/**
+ * Verify a single API by running both the v2 YAML and v3 TS versions with the
+ * supplied inputs and comparing their outputs.
+ *
+ * Wraps `computeVerificationOutcome` with on-disk history bookkeeping:
+ * - Reads `scratch/migration-verification/<apiName>.history.json` and refuses
+ *   to run beyond `MAX_VERIFICATION_ATTEMPTS`, returning `kind: "exhausted"`.
+ * - For `diverged` outcomes, computes `progress` (`first_attempt` |
+ *   `converging` | `stalled`) by hashing (path, kind) tuples and comparing to
+ *   the prior diverged attempt's hash.
+ * - Appends a history entry on every run so the next call has accurate state.
+ *
+ * History persistence is best-effort: bookkeeping I/O failures are logged but
+ * do not surface as verification errors.
+ */
+export async function runMigrationVerification(params) {
+    // Serialize the entire read-cap-check + pipeline + append for a given API
+    // through the per-API queue. Two concurrent calls for the same API used to
+    // both observe `attempts.length = MAX-1`, both pass the cap check, and
+    // both run the pipeline + append — silently exceeding the documented hard
+    // cap by N. Wrapping end-to-end (rather than serializing only the append)
+    // costs us same-API parallelism — but parallel verifications for the same
+    // API are wasteful work anyway (the second result clobbers the first or
+    // hits the cap), so the cost is purely on a degenerate path. Different
+    // APIs use different queues and remain fully parallel.
+    return getVerificationHistoryQueue(params.appRootDir, params.apiName).enqueue(async () => {
+        const history = await readHistory(params.appRootDir, params.apiName);
+        // Real (non-transient) attempts count over the whole migration: a
+        // genuinely non-converging API must still hit MAX_VERIFICATION_ATTEMPTS
+        // and fail, regardless of transients sprinkled in between.
+        const effectiveAttempts = history.attempts.filter((a) => !TRANSIENT_OUTCOME_KINDS.has(a.kind)).length;
+        // Transient backstop counts only the CONSECUTIVE trailing transients —
+        // it resets on any real outcome. A lifetime total would let unrelated
+        // disconnect episodes across a long migration accumulate and, worse,
+        // brick an API that is verifying fine between episodes.
+        const trailingTransientAttempts = countTrailingTransientAttempts(history);
+        // Only the real-attempt cap short-circuits before running: that API
+        // genuinely isn't converging. The transient backstop deliberately does
+        // NOT short-circuit here — we run the pipeline so a peer that has
+        // recovered gets a fresh real attempt and the API self-heals.
+        if (effectiveAttempts >= MAX_VERIFICATION_ATTEMPTS) {
+            recordMigrationVerification({ kind: "exhausted" });
+            return {
+                kind: "exhausted",
+                attempts: effectiveAttempts,
+                lastDivergence: await readLastDivergedDiff(params.appRootDir, params.apiName),
+            };
+        }
+        const raw = await computeVerificationOutcome(params);
+        let outcome;
+        let divergenceHashForHistory;
+        if (raw.kind === "diverged") {
+            const currentHash = divergenceShapeHash(raw.diff.summaryForAgent);
+            divergenceHashForHistory = currentHash;
+            const lastDivergedHash = findLastDivergedShapeHash(history);
+            const progress = lastDivergedHash === undefined
+                ? "first_attempt"
+                : lastDivergedHash === currentHash
+                    ? "stalled"
+                    : "converging";
+            outcome = {
+                kind: "diverged",
+                diff: raw.diff,
+                attempt: effectiveAttempts + 1,
+                progress,
+            };
+        }
+        else if ((raw.kind === "timeout" || raw.kind === "disconnected") &&
+            trailingTransientAttempts + 1 >= MAX_TRANSIENT_VERIFICATION_ATTEMPTS) {
+            // This transient outcome pushes the consecutive streak to the backstop.
+            // Escalate to `transient_exhausted` (retryable, never marks failed)
+            // instead of returning yet another plain transient the agent would
+            // keep retrying forever.
+            outcome = {
+                kind: "transient_exhausted",
+                side: raw.side,
+                reason: raw.reason,
+                transientAttempts: trailingTransientAttempts + 1,
+            };
+        }
+        else {
+            outcome = raw;
+        }
+        // Single decision-point log so an operator chasing "Clark says diverged
+        // but I see passed" has a stdout breadcrumb to correlate. Logged here at
+        // the single return path of `runMigrationVerification` rather than in
+        // each tool-side branch — wraps every outcome (passed, diverged,
+        // both_failed, exhausted, skipped_mutation, v2_unrunnable, error) with a
+        // consistent shape. Apply name only; raw failure strings stay scrubbed.
+        getLogger().info(`[migration-verify] outcome`, {
+            apiName: params.apiName,
+            attempt: effectiveAttempts + 1,
+            maxAttempts: MAX_VERIFICATION_ATTEMPTS,
+            // `attempt` counts only real (non-transient) attempts — it is the value
+            // the `maxAttempts` cap is enforced against. `totalCalls` is the raw
+            // ordinal across every call including transients
+            // (timeout/disconnected/transient_exhausted), preserving the pre-ENG-4674
+            // total-call semantics of `attempt` as an explicit field rather than a
+            // silently-changed one.
+            totalCalls: history.attempts.length + 1,
+            // Consecutive transient streak *including* this outcome when it is
+            // itself transient (timeout/disconnected/transient_exhausted); the
+            // just-broken prior streak length when a real outcome ends the run.
+            // `countTrailingTransientAttempts` reads history only, so it excludes
+            // the current outcome — add it back here so a plain transient reports
+            // the same streak length that `transient_exhausted` does
+            // (`outcome.transientAttempts` === trailingTransientAttempts + 1).
+            trailingTransientAttempts: TRANSIENT_OUTCOME_KINDS.has(outcome.kind)
+                ? trailingTransientAttempts + 1
+                : trailingTransientAttempts,
+            kind: outcome.kind,
+            progress: outcome.kind === "diverged" ? outcome.progress : undefined,
+            divergenceCount: outcome.kind === "diverged"
+                ? outcome.diff.summaryForAgent.length
+                : undefined,
+        });
+        recordMigrationVerification(outcome);
+        // Direct (non-enqueued) write — we already hold this API's queue, so
+        // re-entering it would deadlock.
+        await writeHistoryEntry(params.appRootDir, params.apiName, {
+            ts: new Date().toISOString(),
+            kind: outcome.kind,
+            divergenceShapeHash: divergenceHashForHistory,
+            divergenceCount: outcome.kind === "diverged"
+                ? outcome.diff.summaryForAgent.length
+                : undefined,
+        });
+        return outcome;
+    });
+}
+/**
+ * Extract a human-readable message from a thrown value. Transport-close
+ * rejections from `ISocket` (the plain-object `{code: 8}` path — see
+ * `isTransportCloseError`) are NOT `Error` instances, so a bare `instanceof
+ * Error` check falls through to `String(error)` = "[object Object]", discarding
+ * the "[internal] Connection closed" message on exactly the disconnect path we
+ * surface for on-call diagnosis. Read `.message` off any object that carries a
+ * string one before giving up on `String()`.
+ */
+function errorReason(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "object" &&
+        error !== null &&
+        "message" in error &&
+        typeof error.message === "string") {
+        return error.message;
+    }
+    return String(error);
+}
+async function computeVerificationOutcome({ apiName, appRootDir, inputs, runV2Pipeline, runV3Sdk, }) {
+    const verificationInputs = inputs ?? {};
+    // 1. Detect mutations in the v3 TS source before running anything.
+    const apiTsPath = join(appRootDir, "server", "apis", apiName, "api.ts");
+    let source;
+    try {
+        source = await readFile(apiTsPath, "utf-8");
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            reason: `Cannot read v3 source at ${apiTsPath}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // Extract integration IDs up-front so they can be passed to runV3Sdk for
+    // the auth preflight (matching test-api.ts). Falls back to undefined on AST
+    // parse failure — runV3Sdk will then rely on the Redux store as before.
+    let integrationIds;
+    try {
+        const ids = extractIntegrationIdsFromSource(source);
+        if (ids.length > 0)
+            integrationIds = ids;
+    }
+    catch {
+        // AST parse failure: leave undefined.
+    }
+    let mutations;
+    try {
+        mutations = extractMutations(source);
+    }
+    catch (error) {
+        // AST parse failure: we cannot prove the source is mutation-free, so fall
+        // back to the same policy gate as if mutations were detected. The user
+        // can still get the API verified manually.
+        return {
+            kind: "skipped_mutation",
+            mutationDetails: [
+                `unable to analyze source for mutations: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+        };
+    }
+    const v2BackupPath = await resolveV2BackupYamlPath(appRootDir, apiName);
+    // Also check the v2 backup for writes — a half-migrated API where v3 looks
+    // read-only but the original v2 still mutates would otherwise bypass the
+    // policy gate and run the v2 pipeline against real integrations.
+    const v2Analysis = await analyzeV2BackupMutations(v2BackupPath);
+    const mutationDetails = [
+        ...mutations.map((m) => `v3 ${m.type} "${m.name}": ${m.details}`),
+        ...v2Analysis.mutationDetails,
+    ];
+    if (mutationDetails.length > 0) {
+        const { effective } = await getEffectiveMigrationWritePolicy({
+            appRootDir,
+            apiName,
+            integrationIds,
+        });
+        if (effective === "deny") {
+            return {
+                kind: "skipped_mutation",
+                mutationDetails,
+            };
+        }
+        // effective === "allow": fall through to run both pipelines
+    }
+    // 2. Run v2 YAML pipeline.
+    let v2Result;
+    try {
+        const pipelineResult = await withTimeout(runV2Pipeline(v2BackupPath, verificationInputs), PIPELINE_TIMEOUT_MS, "v2 pipeline");
+        if (!pipelineResult.executionResult) {
+            return {
+                kind: "v2_unrunnable",
+                reason: "v2 pipeline returned no execution result",
+            };
+        }
+        v2Result = pipelineResult.executionResult;
+    }
+    catch (error) {
+        if (error instanceof PipelineTimeoutError) {
+            return { kind: "timeout", side: "v2", reason: error.message };
+        }
+        // The editor peer dying while the RPC was in flight (transport close) OR
+        // while it sat queued waiting to reconnect (StablePeer's `peer_closed:` /
+        // `peer_queue_overflow`) is the same diagnosis as the pre-flight gate, so
+        // the same outcome. It must never fall through to `v2_unrunnable`, which
+        // auto-completes the checklist item on a dead editor tab.
+        if (error instanceof EditorClientUnavailableError ||
+            isPeerUnavailableError(error)) {
+            return {
+                kind: "disconnected",
+                side: "v2",
+                reason: errorReason(error),
+            };
+        }
+        return {
+            kind: "v2_unrunnable",
+            reason: formatV2UnrunnableReason(error),
+        };
+    }
+    // 3. Run v3 SDK.
+    let v3Result;
+    try {
+        v3Result = await withTimeout(runV3Sdk(integrationIds, verificationInputs), PIPELINE_TIMEOUT_MS, "v3 SDK");
+    }
+    catch (error) {
+        if (error instanceof PipelineTimeoutError) {
+            return { kind: "timeout", side: "v3", reason: error.message };
+        }
+        if (error instanceof EditorClientUnavailableError ||
+            isPeerUnavailableError(error)) {
+            return {
+                kind: "disconnected",
+                side: "v3",
+                reason: errorReason(error),
+            };
+        }
+        return {
+            kind: "error",
+            reason: errorReason(error),
+        };
+    }
+    // 3.5. If both executions returned failure, surface that explicitly rather
+    //      than letting compareApiResults produce a vacuous "diff.empty" pass.
+    if (!v2Result.success && !v3Result.success) {
+        return {
+            kind: "both_failed",
+            v2Error: extractFailureMessage(v2Result, "v2"),
+            v3Error: extractFailureMessage(v3Result, "v3"),
+        };
+    }
+    // 3.6. One-sided failure: if one side succeeded and the other failed, that is
+    //      a divergence regardless of what the output diff says.  Without this
+    //      guard, a v3 that returns `success: false` with empty `outputs` would
+    //      compare equal to a v2 with empty `outputs`, producing a false "passed".
+    if (v2Result.success !== v3Result.success) {
+        const failedSide = v2Result.success ? "v3" : "v2";
+        const failureMessage = extractFailureMessage(v2Result.success ? v3Result : v2Result, failedSide);
+        // Server-side log so divergence shows up in the dev-server log stream
+        // (and DataDog when the EE forwards stdout). The actual failure text is
+        // intentionally NOT logged here — extractFailureMessage may include
+        // upstream response bodies, query strings, or credentials echoed back by
+        // the integration. The agent already gets failureMessage via
+        // summaryForAgent, and the user sees full detail in the verification UI.
+        // What we want from the server log is a "this happened" marker:
+        // apiName, which side failed, and the error type/source classification.
+        // Logger.warn accepts free-form key/value pairs; .error has a stricter
+        // ErrorMeta shape that doesn't fit this diagnostic record.
+        getLogger().warn(`Migration verification diverged for ${apiName}`, {
+            apiName,
+            failedSide,
+            v2: {
+                success: v2Result.success,
+                hasSystemError: Boolean(v2Result.systemError),
+                firstErrorType: v2Result.errors?.[0]?.type,
+            },
+            v3: { success: v3Result.success },
+        });
+        // The agent-facing `failureMessage` is scrubbed via `redactForAgent`
+        // because it ends up in LLM context (and from there into chat
+        // transcripts persisted by the client). The UI-facing `valuesForUi.reason`
+        // intentionally keeps the raw text — that channel renders to the
+        // user's own browser, not into the model context.
+        return {
+            kind: "diverged",
+            diff: {
+                empty: false,
+                summaryForAgent: [
+                    {
+                        path: "success",
+                        kind: "value_mismatch",
+                        expectedHash: String(v2Result.success),
+                        actualHash: String(v3Result.success),
+                        failureMessage: redactForAgent(failureMessage),
+                    },
+                ],
+                valuesForUi: [
+                    {
+                        path: "success",
+                        expected: v2Result.success,
+                        actual: v3Result.success,
+                        reason: `${failedSide} execution failed while the other succeeded: ${failureMessage}`,
+                    },
+                ],
+            },
+        };
+    }
+    // 4. Compare.
+    const diff = compareApiResults(v2Result, v3Result);
+    if (diff.empty) {
+        return { kind: "passed" };
+    }
+    // 5. Persist the diff to disk for the UI to render (valuesForUi only).
+    const verificationDir = join(appRootDir, SCRATCH_DIR, VERIFICATION_DIR);
+    await mkdir(verificationDir, { recursive: true });
+    const diffPath = join(verificationDir, `${apiName}.diff.json`);
+    const diffJson = JSON.stringify({ valuesForUi: diff.valuesForUi }, null, 2);
+    const payload = diffJson.length > DIFF_SIZE_CAP
+        ? JSON.stringify({ valuesForUi: diff.valuesForUi.slice(0, 50), truncated: true }, null, 2)
+        : diffJson;
+    await writeFile(diffPath, payload, "utf-8");
+    return { kind: "diverged", diff };
+}
+/** Relative path (from appRootDir) for a diff JSON file. */
+function diffRelativePath(apiName) {
+    return `${SCRATCH_DIR}/${VERIFICATION_DIR}/${apiName}.diff.json`;
+}
+function assertNever(value) {
+    throw new Error(`Unexpected verification outcome: ${JSON.stringify(value)}`);
+}
+async function clearTransientVerificationFields(params) {
+    const { apiName, appRootDirPath } = params;
+    // Transient outcomes (`error`, `timeout`, `disconnected`,
+    // `transient_exhausted`) must never mark the checklist item complete or stamp
+    // a skip reason — the agent should retry once the environment recovers. Clear
+    // stale fields from a prior run so the UI does not show outdated pass/skip
+    // metadata.
+    await updateChecklistItem({
+        appRootDirPath,
+        itemId: `api_${apiName}`,
+        verificationOutcome: null,
+        verificationSkippedReason: null,
+        lastVerificationAt: new Date().toISOString(),
+    });
+}
+export async function syncVerificationOutcomeToChecklist(params) {
+    const { apiName, appRootDirPath, clark, outcome } = params;
+    if (outcome.kind === "passed") {
+        markSdkApiAsVerified(clark, apiName);
+        await updateChecklistItem({
+            appRootDirPath,
+            itemId: `api_${apiName}`,
+            verificationOutcome: "auto_passed",
+            verificationSkippedReason: null,
+            lastVerificationAt: new Date().toISOString(),
+        });
+        return;
+    }
+    if (outcome.kind === "skipped_mutation") {
+        // Deliberate behavior change (ENG-4484): mutation-skipped APIs are marked
+        // `completed` immediately so the user can verify them manually at finalize
+        // time instead of leaving rows stuck `in_progress`.
+        await updateChecklistItem({
+            appRootDirPath,
+            itemId: `api_${apiName}`,
+            status: "completed",
+            verificationSkippedReason: "mutation",
+            verificationOutcome: null,
+            lastVerificationAt: new Date().toISOString(),
+        });
+        return;
+    }
+    if (outcome.kind === "v2_unrunnable") {
+        await updateChecklistItem({
+            appRootDirPath,
+            itemId: `api_${apiName}`,
+            verificationSkippedReason: "v2_unrunnable",
+            verificationOutcome: null,
+            lastVerificationAt: new Date().toISOString(),
+        });
+        return;
+    }
+    if (outcome.kind === "both_failed") {
+        // Deliberately do NOT mark `status: completed` — the agent should retry
+        // with synthesized inputs rather than treat this as terminal.
+        await updateChecklistItem({
+            appRootDirPath,
+            itemId: `api_${apiName}`,
+            verificationSkippedReason: "both_failed",
+            verificationOutcome: null,
+            lastVerificationAt: new Date().toISOString(),
+        });
+        return;
+    }
+    if (outcome.kind === "diverged") {
+        await updateChecklistItem({
+            appRootDirPath,
+            itemId: `api_${apiName}`,
+            verificationOutcome: null,
+            verificationSkippedReason: null,
+            lastVerificationAt: new Date().toISOString(),
+            lastVerificationDiffPath: diffRelativePath(apiName),
+        });
+        return;
+    }
+    if (outcome.kind === "exhausted") {
+        // Terminal failure: the hard attempt cap was reached without convergence.
+        await updateChecklistItem({
+            appRootDirPath,
+            itemId: `api_${apiName}`,
+            status: "failed",
+            failureReason: `verification_exhausted: hit MAX_VERIFICATION_ATTEMPTS (${MAX_VERIFICATION_ATTEMPTS}) without converging. See scratch/migration-verification/${apiName}.history.json for the per-attempt log.`,
+            verificationOutcome: null,
+            verificationSkippedReason: null,
+            lastVerificationAt: new Date().toISOString(),
+            ...(outcome.lastDivergence
+                ? { lastVerificationDiffPath: diffRelativePath(apiName) }
+                : {}),
+        });
+        return;
+    }
+    if (outcome.kind === "error" ||
+        outcome.kind === "timeout" ||
+        outcome.kind === "disconnected" ||
+        outcome.kind === "transient_exhausted") {
+        // `transient_exhausted` (the consecutive-transient backstop) belongs here,
+        // NOT with `exhausted`: the environment being unreachable is never the
+        // API's fault, so the item must stay retryable and must never be marked
+        // failed. It self-heals once the editor peer reconnects.
+        await clearTransientVerificationFields({
+            apiName,
+            appRootDirPath,
+        });
+        return;
+    }
+    return assertNever(outcome);
+}
+export function verificationCountsAsApiTest(kind) {
+    return kind === "passed" || kind === "diverged" || kind === "both_failed";
+}
+export const migrationVerificationToolFactory = createToolFactory("runMigrationVerification", ({ clark, services, }) => ({
+    category: ToolCategory.DEBUG,
+    timeoutMs: 300_000, // 5 minutes — verification runs both v2+v3 pipelines which regularly exceed 60s
+    getRequiredPermissions: async (input) => {
+        const apiName = input?.apiName;
+        if (!apiName)
+            return [];
+        let source;
+        try {
+            source = await services.appShell.readFile(`server/apis/${apiName}/api.ts`);
+        }
+        catch {
+            return [];
+        }
+        let mutations;
+        try {
+            mutations = extractMutations(source);
+        }
+        catch {
+            return [];
+        }
+        if (mutations.length === 0)
+            return [];
+        let integrationIds;
+        try {
+            const ids = extractIntegrationIdsFromSource(source);
+            if (ids.length > 0)
+                integrationIds = ids;
+        }
+        catch {
+            integrationIds = undefined;
+        }
+        const { effective, sourceIds } = await getEffectiveMigrationWritePolicy({
+            appRootDir: services.appRootDirPath,
+            apiName,
+            integrationIds,
+        });
+        // Deny short-circuits to skipped_mutation without writes; allow runs
+        // pipelines under the migration-wide policy — neither needs per-entity WRITE.
+        if (effective === "deny" ||
+            effective === "allow" ||
+            sourceIds.length === 0) {
+            return [];
+        }
+        return sourceIds.map((entityId) => ({
+            entityType: AiEntityType.INTEGRATION,
+            entityId,
+            permissionType: AiPermissionType.WRITE,
+        }));
+    },
+    getActionName: (input) => {
+        const name = input?.apiName ?? "API";
+        return {
+            future: `verify ${name}`,
+            present: `verifying ${name}`,
+            past: `verified ${name}`,
+        };
+    },
+    description: "Verify a migrated API by running both the v2 YAML and v3 TS versions " +
+        "and comparing their outputs. Pass `inputs` to inject test parameters " +
+        "for any bindings the API references (the same way `testApi` does — " +
+        "`Input1.value`, `Table1.selectedRow`, etc.); both v2 and v3 receive " +
+        "the same inputs so the comparison is apples-to-apples. Omit `inputs` " +
+        "(or pass `{}`) only when the API takes no inputs. Each pipeline has a " +
+        `${PIPELINE_TIMEOUT_MS / 1000}s reporting timeout (reject-only — the ` +
+        "underlying execution can't be cancelled, so allow-policy mutations " +
+        "may continue server-side after this returns). Returns a structured outcome: " +
+        "'passed', 'diverged' (with summaryForAgent), 'both_failed' (both " +
+        "executions errored — cannot determine correctness), " +
+        "'skipped_mutation', 'v2_unrunnable', 'timeout' (transient stall — " +
+        "retry, do NOT mark complete), 'disconnected' (editor connection down " +
+        "— have the user focus the app tab, retry, do NOT mark complete), or " +
+        "'error'. On 'diverged' use " +
+        "`summaryForAgent` to revise `server/apis/<apiName>/api.ts` and re-run " +
+        "the tool — the attempt counter is tracked server-side from on-disk " +
+        "history; the response always includes the current `attempt` and " +
+        "`maxAttempts` so the agent doesn't have to thread it.",
+    inputSchema: z.object({
+        apiName: z
+            .string()
+            .describe("The API name to verify (must match the directory under " +
+            "server/apis/, may contain only letters, digits, hyphens, or " +
+            "underscores). Bare .string() — `.regex()` emits a JSON Schema " +
+            "`pattern` keyword that Snowflake Cortex rejects; the format is " +
+            "validated below at runtime.")
+            .refine((v) => /^[a-zA-Z0-9_-]+$/.test(v), {
+            message: "apiName must contain only letters, digits, hyphens, or underscores",
+        }),
+        inputs: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Test input values for the API's bindings, applied to BOTH the " +
+            "v2 YAML and v3 TS executions so the diff is meaningful. Use the " +
+            "same approach as `testApi`: a key per binding the API references " +
+            "(component values like `Input1.value`, table selections like " +
+            "`Table1.selectedRow`, state variables, workflow params, etc.) " +
+            "with realistic mock values that match the binding's expected " +
+            "type. Omit (defaults to `{}`) only when the API takes no inputs " +
+            "— passing `{}` for an API that needs inputs typically produces " +
+            "a vacuous 'both_failed' result."),
+        // `attemptCount` was previously declared here for the agent to thread
+        // through retries, but `execute` never read it — the real attempt
+        // count is computed from on-disk history inside
+        // `runMigrationVerification` so an agent that lies about its attempt
+        // index can't bypass `MAX_VERIFICATION_ATTEMPTS`. The field is dropped
+        // to match what the tool actually uses; Zod's default object policy
+        // strips unknown keys so any agent still passing it in-flight is a
+        // no-op rather than an error.
+    }),
+    async execute({ apiName, inputs }) {
+        const appRootDir = services.appRootDirPath;
+        const outcome = await runMigrationVerification({
+            apiName,
+            appRootDir,
+            inputs,
+            runV2Pipeline: async (sourcePath, pipelineInputs) => {
+                // runApiValidationPipeline's sourcePath only controls metadata
+                // loading (validateMetadata: false here), not execution — it always
+                // calls aiExecuteV2Api({ type: "fetch", apiName }) which resolves the
+                // API by name in the editor. After migration that name points to the
+                // v3 TS version, so the v2 backup YAML was never actually run.
+                // Load the backup YAML directly and execute inline instead.
+                const yamlContent = await readFile(sourcePath, "utf-8");
+                const apiDefinition = yaml.parse(yamlContent);
+                await inlineV2BackupSourceFiles(apiDefinition, sourcePath);
+                const editorClient = clark.context.peer;
+                // `peer` is a StablePeer proxy: always truthy, queues calls while
+                // disconnected. Gate on real connection state so a dead tab yields
+                // `disconnected` immediately instead of a 30s `timeout`, and so no
+                // stale execution enters the reconnect replay queue.
+                await assertEditorClientConnected(editorClient, "v2 pipeline");
+                const executor = new ApiExecutor(editorClient, services.integrationStore);
+                const executionResult = await executor.execute({ type: "inline", definition: apiDefinition }, pipelineInputs, { includeStepOutputs: false });
+                return { success: executionResult.success, executionResult };
+            },
+            runV3Sdk: async (integrationIds, sdkInputs) => {
+                const editorClient = clark.context.peer;
+                await assertEditorClientConnected(editorClient, "v3 SDK");
+                const sdkResult = await editorClient.call.aiExecuteSdkApi({
+                    apiName,
+                    input: sdkInputs,
+                    entryPoint: `server/apis/${apiName}/api.ts`,
+                    integrationIds,
+                });
+                // SdkApiExecutionResult uses `output` (singular) while
+                // ApiExecutionResult uses `outputs` (plural) — normalize here.
+                // Also forward the SDK error so divergence diagnostics can show the
+                // real reason instead of a bare success: false.
+                const errors = sdkResult.error
+                    ? [
+                        {
+                            type: "execution",
+                            message: sdkResult.error.message,
+                        },
+                    ]
+                    : undefined;
+                return {
+                    success: sdkResult.success,
+                    outputs: sdkResult.output,
+                    errors,
+                };
+            },
+        });
+        if (verificationCountsAsApiTest(outcome.kind)) {
+            markSdkApiAsVerified(clark, apiName);
+        }
+        // Update checklist with verification metadata. Each branch explicitly
+        // clears fields from the previous run that no longer apply (null = clear).
+        await syncVerificationOutcomeToChecklist({
+            apiName,
+            appRootDirPath: appRootDir,
+            clark,
+            outcome,
+        });
+        if (outcome.kind === "diverged") {
+            return {
+                kind: "diverged",
+                summaryForAgent: outcome.diff.summaryForAgent,
+                diffPath: diffRelativePath(apiName),
+                attempt: outcome.attempt,
+                maxAttempts: MAX_VERIFICATION_ATTEMPTS,
+                progress: outcome.progress,
+                guidance: progressGuidance(outcome.progress, outcome.attempt),
+            };
+        }
+        if (outcome.kind === "exhausted") {
+            // Deliberately do NOT include the persisted diff payload (which holds
+            // raw response values) in the agent-facing tool result — those values
+            // belong to the user's data plane and stay scoped to local scratch
+            // and the UI render path. The checklist item already carries
+            // `lastVerificationDiffPath` for the UI to read directly from disk.
+            return {
+                kind: "exhausted",
+                attempts: outcome.attempts,
+                summary: `\`${apiName}\` hit the hard cap of ${MAX_VERIFICATION_ATTEMPTS} verification attempts without converging. ` +
+                    `The checklist item has been marked failed; do NOT call runMigrationVerification again for this API in this migration run. ` +
+                    `Continue to the next API.`,
+            };
+        }
+        if (outcome.kind === "skipped_mutation") {
+            return {
+                kind: "skipped_mutation",
+                mutationDetails: outcome.mutationDetails,
+                summary: `\`${apiName}\` makes writes — skipped automatic verification (write policy: deny). Mark as manually verified once you have confirmed the API behaves correctly.`,
+            };
+        }
+        if (outcome.kind === "passed") {
+            return {
+                kind: "passed",
+                summary: `\`${apiName}\` verified — v2 and v3 outputs matched exactly.`,
+            };
+        }
+        if (outcome.kind === "v2_unrunnable") {
+            return {
+                kind: "v2_unrunnable",
+                summary: `The original pre-migration version of \`${apiName}\` couldn't be run for comparison (${outcome.reason}), ` +
+                    `so automatic verification was skipped. The API has been marked complete — ` +
+                    `test it in the app to confirm it works as expected.`,
+            };
+        }
+        if (outcome.kind === "both_failed") {
+            // Scrub raw upstream error strings before surfacing them to the
+            // model — same threat model as the diverged branch's
+            // `redactForAgent(failureMessage)`. The persisted server log already
+            // omits the raw message; the agent-facing channel must too.
+            return {
+                kind: "both_failed",
+                summary: `Both the original and migrated versions of \`${apiName}\` returned errors ` +
+                    `(typically because the API reads bindings — Input1.value, Table1.selectedRow, ` +
+                    `workflow params, etc. — that the verification call did not supply). The item ` +
+                    `is NOT marked complete; per the migration skill, synthesize realistic mock ` +
+                    `inputs that satisfy the bindings the API references and call ` +
+                    `runMigrationVerification again. Only treat this as terminal if the failure is ` +
+                    `clearly environmental (auth/credentials/integration unavailable). ` +
+                    `Original error: ${redactForAgent(outcome.v2Error)}. ` +
+                    `Migrated error: ${redactForAgent(outcome.v3Error)}.`,
+            };
+        }
+        if (outcome.kind === "timeout") {
+            return {
+                kind: "timeout",
+                side: outcome.side,
+                summary: `Verification of \`${apiName}\` hit the ${PIPELINE_TIMEOUT_MS / 1000}s reporting timeout on the ` +
+                    `${outcome.side === "v2" ? "original (v2)" : "migrated (v3)"} execution (${outcome.reason}). ` +
+                    `This is a transient environment stall (editor connection, network), NOT evidence the API is broken ` +
+                    `or that its baseline can't run. Do NOT mark the item completed. Call runMigrationVerification again; ` +
+                    `if it times out repeatedly, tell the user verification is stalling — likely because the app tab is ` +
+                    `backgrounded or the connection dropped — and ask them to keep the tab focused, then retry.`,
+            };
+        }
+        if (outcome.kind === "disconnected") {
+            return {
+                kind: "disconnected",
+                side: outcome.side,
+                summary: `Verification of \`${apiName}\` could not run the ` +
+                    `${outcome.side === "v2" ? "original (v2)" : "migrated (v3)"} execution because the editor ` +
+                    `connection is down (${outcome.reason}) — the app tab is closed, backgrounded, or reconnecting. ` +
+                    `This says nothing about the API itself. Do NOT mark the item completed. Tell the user the app tab ` +
+                    `needs to stay open and focused for verification, then call runMigrationVerification again.`,
+            };
+        }
+        if (outcome.kind === "transient_exhausted") {
+            return {
+                kind: "transient_exhausted",
+                side: outcome.side,
+                summary: `Verification of \`${apiName}\` has failed to reach the editor ${outcome.transientAttempts} times in a row ` +
+                    `without it becoming runnable (most recent: ${outcome.side === "v2" ? "original (v2)" : "migrated (v3)"} — ${outcome.reason}). ` +
+                    `This is a persistent environment problem — the app tab is closed/backgrounded or the connection keeps dropping — ` +
+                    `NOT a problem with the API, and the item has NOT been marked complete or failed. STOP calling ` +
+                    `runMigrationVerification for this API now: tell the user verification is blocked because the editor/app tab ` +
+                    `is disconnected, ask them to reopen it and keep it focused, and only retry once they confirm. Verification ` +
+                    `resumes automatically for this API the moment the connection is restored.`,
+            };
+        }
+        // outcome.kind === "error" — the only remaining case
+        return {
+            kind: "error",
+            reason: outcome.reason,
+        };
+    },
+}));
+/**
+ * Soft UX timeout for the verification pipeline.
+ *
+ * IMPORTANT: this is a *reporting* timeout, not an execution boundary. The
+ * underlying work — `aiExecuteV2Api` and `aiExecuteSdkApi` editor-client RPCs —
+ * has no cancellation channel (the socket `MethodSchema` is a plain
+ * `(params) => Promise<Response>`; there is no AbortSignal plumbed through
+ * the RPC, the browser-side handler, or the SDK runtime). When this rejects,
+ * the in-flight execution keeps running until the server completes or the
+ * socket disconnects.
+ *
+ * What this does protect: the verification UI doesn't stall indefinitely on a
+ * slow API; the agent gets a deterministic outcome to act on.
+ *
+ * What this does NOT protect: write-capable side effects already in flight.
+ * Mutation safety is provided by the `integrationWritePolicy` check that runs
+ * BEFORE this timeout race ever fires — `runMigrationVerification` inspects
+ * BOTH the v3 source (via `extractMutations`) and the v2 backup YAML (via
+ * `analyzeV2BackupMutations`); if either side has any write or unclassified
+ * step, the pipelines are skipped entirely unless the user has explicitly
+ * marked every involved integration as "allow". By the time this `withTimeout`
+ * runs, any side effects in flight have already been opted into. Verification
+ * is not a sandbox; it relies on the policy gate, not on cancellation.
+ *
+ * Adding real cancellation would require extending `MethodSchema` with abort
+ * signaling and propagating it through the editorClient RPC layer. Tracked
+ * separately; out of scope for this verification helper.
+ */
+function withTimeout(promise, ms, label) {
+    let timer;
+    return Promise.race([
+        promise.finally(() => clearTimeout(timer)),
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new PipelineTimeoutError(`${label} timed out after ${ms / 1000}s`)), ms);
+        }),
+    ]);
+}
+/**
+ * Typed rejection for `withTimeout` so the outcome classifier can tell "the
+ * pipeline stalled past the reporting timeout" (transient — retryable) apart
+ * from "the pipeline itself threw" (e.g. unreadable v2 backup — a real
+ * `v2_unrunnable`). String-matching the message would break silently on
+ * rewording; the class is the contract.
+ */
+class PipelineTimeoutError extends Error {
+}
+/**
+ * Thrown by the pipeline runners when the editor client (the user's browser
+ * tab, `clark.context.peer`) is not connected at call time. Exported because
+ * the runners are injected: the tool factory's closures throw it and the
+ * classifier in this module catches it via `instanceof`. Unlike a timeout
+ * this is an unambiguous diagnosis — the connection is known to be down —
+ * but the action contract is the same: retryable, never mark complete.
+ */
+export class EditorClientUnavailableError extends Error {
+}
+const FILE_REFERENCE_PROTO_DECODE_PATTERN = /plugins\.javascript\.v1\.Plugin\.body from JSON: object|plugins\.python\.v1\.Plugin\.body from JSON: object/;
+function formatV2UnrunnableReason(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (FILE_REFERENCE_PROTO_DECODE_PATTERN.test(message)) {
+        return ("v2 backup uses file-referenced JS/Python blocks but migration verification " +
+            "failed to inline their source files before proto validation. " +
+            `Original error: ${message}`);
+    }
+    return message;
+}
+/**
+ * How long a pipeline runner waits for the editor peer to (re)connect before
+ * failing with `disconnected`. This is a pre-flight gate, not a retry budget:
+ * long enough to ride out a heartbeat flap mid-reconnect, short enough that a
+ * genuinely-gone tab fails fast instead of burning the full 30s reporting
+ * timeout.
+ */
+export const EDITOR_CONNECT_GRACE_MS = 5_000;
+/**
+ * Pre-flight connectivity gate for the pipeline runners. The editor peer
+ * (`clark.context.peer`) is a StablePeer proxy — always truthy even when the
+ * underlying socket is gone, and it silently queues calls while disconnected
+ * (replayed on reconnect). A bare truthiness check therefore never fires and
+ * a dead tab surfaces as a 30s `timeout` instead of `disconnected`. Gate on
+ * real connection state instead, tolerating a brief reconnect window.
+ * Exported for direct unit testing.
+ */
+export async function assertEditorClientConnected(peer, label) {
+    if (await peer.whenConnected(EDITOR_CONNECT_GRACE_MS))
+        return;
+    throw new EditorClientUnavailableError(`editor peer disconnected (${label}): no reconnect within ${EDITOR_CONNECT_GRACE_MS / 1000}s`);
+}
+/**
+ * Inspect a v2 backup YAML for mutating steps and the integrations they touch.
+ *
+ * Returns empty results when the backup is missing or unparseable — the
+ * verification flow handles that downstream as `v2_unrunnable`. The goal here
+ * is only to feed the policy gate so v2-only writes don't bypass it.
+ *
+ * Walks the whole tree via `forEachYamlStep` so writes nested inside
+ * control-flow blocks (`tryCatch`, `conditional`, `foreach`, `parallel`) are
+ * caught — a flat scan over `parsed.blocks` would let nested v2 writes bypass
+ * the policy gate, especially now that the language-plugin filter has removed
+ * the accidental safety net where javascript's missing policy used to block
+ * all verification.
+ *
+ * Treats `unknown` step classifications (dynamic SQL bodies, plugins we don't
+ * recognize) as mutations: better to ask the user than silently run a write.
+ */
+async function analyzeV2BackupMutations(v2BackupPath) {
+    let raw;
+    try {
+        raw = await readFile(v2BackupPath, "utf-8");
+    }
+    catch {
+        return { mutationDetails: [], integrationIds: [] };
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        return { mutationDetails: [], integrationIds: [] };
+    }
+    const integrationIds = new Set();
+    const mutationDetails = [];
+    forEachYamlStep(parsed, (step) => {
+        const integrationId = step["integration"];
+        if (typeof integrationId === "string" && integrationId.length > 0) {
+            integrationIds.add(integrationId);
+        }
+        const classification = classifyYamlStepMutation(step);
+        if (classification === "write" || classification === "unknown") {
+            const stepName = typeof step["name"] === "string" ? step["name"] : "<unnamed>";
+            mutationDetails.push(`v2 step "${stepName}" classified as ${classification}`);
+        }
+    });
+    return {
+        mutationDetails,
+        integrationIds: Array.from(integrationIds),
+    };
+}
+function mostRestrictivePolicy(policies) {
+    if (policies.includes("deny"))
+        return "deny";
+    return "allow";
+}
+async function getEffectiveMigrationWritePolicy({ appRootDir, apiName, integrationIds, }) {
+    const policy = await readIntegrationWritePolicyForEnforcement(appRootDir);
+    const v2BackupPath = await resolveV2BackupYamlPath(appRootDir, apiName);
+    // Use IDs from source — not Object.keys(policy) — so a UUID present in
+    // source but absent from the policy map gets a real "deny" vote rather
+    // than being ignored. Otherwise an "allow" on one integration would be
+    // taken as blanket allow for everything the API touches. Union v2 and v3
+    // integrations so the gate sees every integration the verification will
+    // touch, not just the ones still referenced by v3.
+    //
+    // Language-runtime "integrations" (`javascript`, `python`) are inline
+    // user code, not data integrations; the modal hides them and they have
+    // no real write-policy decision attached. Excluding them here keeps a
+    // mixed API (e.g. postgres + javascript) from being blocked just because
+    // javascript has no policy entry.
+    const v2Analysis = await analyzeV2BackupMutations(v2BackupPath);
+    const sourceIds = Array.from(new Set([...(integrationIds ?? []), ...v2Analysis.integrationIds])).filter((id) => !LANGUAGE_PLUGIN_IDS.has(id));
+    const effective = sourceIds.length > 0
+        ? mostRestrictivePolicy(sourceIds.map((id) => policy[id] ?? "deny"))
+        : "deny";
+    return { effective, sourceIds };
+}
+export const checkRunMigrationVerificationPermissions = async (services, input) => {
+    if (!input || !input.apiName)
+        return PermissionLevel.PROMPT;
+    const apiName = input.apiName;
+    let source;
+    try {
+        source = await services.appShell.readFile(`server/apis/${apiName}/api.ts`);
+    }
+    catch {
+        return PermissionLevel.PROMPT;
+    }
+    try {
+        extractMutations(source);
+    }
+    catch {
+        return PermissionLevel.PROMPT;
+    }
+    // Non-mutating APIs are safe to verify; mutating APIs short-circuit to
+    // skipped_mutation when write policy is deny, so the tool must be callable.
+    return PermissionLevel.ALLOW;
+};
+/**
+ * Extract the most specific failure message from a Pick<ApiExecutionResult>.
+ * Tries errors[0].message first, then systemError, then a placeholder.
+ */
+function extractFailureMessage(result, side) {
+    return (result.errors?.[0]?.message ??
+        result.systemError ??
+        `${side} execution returned success: false with no error details`);
+}
+const REDACTED_AGENT_FAILURE_MAX_LEN = 512;
+/**
+ * Scrub raw upstream-error strings before they enter LLM context. Upstream
+ * integrations can echo back bearer tokens, JWTs, or `api_key=...` query
+ * strings in error messages — the existing `sanitizeLogMessage` helper in
+ * `util/log-sanitizer.ts` is the canonical scrubber for those patterns and
+ * is what the rest of the vite plugin already uses for log lines. We
+ * additionally cap the length so a single misbehaving upstream can't crowd
+ * out the rest of the LLM context window.
+ *
+ * Used on the agent-facing channels (`summaryForAgent.failureMessage` for
+ * diverged outcomes, the `summary` string for `both_failed`) — the
+ * comment at the `getLogger().warn` call site for "Migration verification
+ * diverged" already keeps the server log clean of these strings; this
+ * applies the same treatment to the durable LLM channel.
+ */
+function redactForAgent(msg, maxLen = REDACTED_AGENT_FAILURE_MAX_LEN) {
+    if (msg === undefined || msg === null)
+        return "";
+    const sanitized = sanitizeLogMessage(String(msg));
+    if (sanitized.length <= maxLen)
+        return sanitized;
+    return sanitized.slice(0, maxLen) + "… [truncated]";
+}
+/**
+ * Count the consecutive transient outcomes at the tail of the history (the
+ * current run's streak), stopping at the first real outcome. This resets the
+ * transient backstop on any real progress, so separate disconnect episodes
+ * across a long migration never accumulate — only an unbroken run of
+ * transient failures trips it.
+ */
+function countTrailingTransientAttempts(history) {
+    let count = 0;
+    for (let i = history.attempts.length - 1; i >= 0; i--) {
+        const entry = history.attempts[i];
+        if (!entry || !TRANSIENT_OUTCOME_KINDS.has(entry.kind))
+            break;
+        count++;
+    }
+    return count;
+}
+/**
+ * Reject any `apiName` that could escape `scratch/migration-verification/`.
+ * Checklist items are persisted to disk and parsed back in without a strict
+ * shape guard, so a poisoned `apiName` containing path separators or `..`
+ * segments would let `historyPath`/`diffPath` (and therefore the `rm` calls
+ * in `clearVerificationHistory`) target arbitrary files.
+ *
+ * v2 → v3 migration API names are derived from server YAML/SDK identifiers
+ * which are restricted to `[A-Za-z0-9_-]`, so this check is conservative
+ * for legitimate inputs.
+ */
+function assertSafeApiName(apiName) {
+    if (!/^[A-Za-z0-9_-]+$/.test(apiName)) {
+        throw new Error(`Refusing to operate on verification artifacts for unsafe apiName: ${JSON.stringify(apiName)}`);
+    }
+}
+function historyPath(appRootDir, apiName) {
+    assertSafeApiName(apiName);
+    return join(appRootDir, SCRATCH_DIR, VERIFICATION_DIR, `${apiName}.history.json`);
+}
+function diffPath(appRootDir, apiName) {
+    assertSafeApiName(apiName);
+    return join(appRootDir, SCRATCH_DIR, VERIFICATION_DIR, `${apiName}.diff.json`);
+}
+/**
+ * Delete the per-API verification history (and stale diff snapshot) so the
+ * next `runMigrationVerification` call starts from a clean slate. Called by
+ * the "Fix with Clark" retry endpoints — without this, an item that hit the
+ * `MAX_VERIFICATION_ATTEMPTS` cap on the first run would immediately return
+ * `kind: "exhausted"` on retry, making the retry a no-op.
+ *
+ * Routed through the same per-API `verificationHistoryQueues` queue used by
+ * `runMigrationVerification`. Without this, a clear could race with an
+ * in-flight verification: the verification reads history, runs the pipeline,
+ * the clear `rm()`s the file, then the verification's append re-creates the
+ * file with a stale attempt count — defeating the clear and immediately
+ * returning `exhausted` on the user's next retry.
+ *
+ * Best-effort: missing files are not an error. The safety check on
+ * `apiName` (via `historyPath`/`diffPath`) runs *before* enqueueing so a
+ * poisoned name throws synchronously, never holding the queue.
+ */
+export async function clearVerificationHistory(appRootDir, apiName) {
+    const histPath = historyPath(appRootDir, apiName);
+    const dPath = diffPath(appRootDir, apiName);
+    await getVerificationHistoryQueue(appRootDir, apiName).enqueue(async () => {
+        await Promise.all([
+            rm(histPath, { force: true }),
+            rm(dPath, { force: true }),
+        ]);
+    });
+}
+/**
+ * Static guidance string keyed off the deterministic `progress` signal — the
+ * agent doesn't have to decide whether to keep iterating, the tool tells it.
+ */
+function progressGuidance(progress, attempt) {
+    if (progress === "first_attempt") {
+        return `First diverged attempt for this API. Use the summaryForAgent entries to revise server/apis/<apiName>/api.ts and call runMigrationVerification again.`;
+    }
+    if (progress === "converging") {
+        return `Converging — the set of diverging (path, kind) pairs changed since the last attempt (#${attempt - 1}). Your previous edit had structural effect. Keep iterating: pick the next summaryForAgent entry, fix it, re-run.`;
+    }
+    // stalled
+    return `STALLED — the set of diverging (path, kind) pairs is identical to attempt #${attempt - 1}. Your last edit had no structural effect on the divergence. Either you edited the wrong block, the edit was a no-op, or this divergence is structurally irreconcilable (v2 uses a YAML construct with no v3 equivalent; v2 reads runtime state v3 can't observe). On your next attempt: try a different fix, or — if you are confident the divergence cannot be reconciled — mark the item failed with failureReason starting with "verification_diverged_irreconcilable:" and continue. Do NOT submit the identical edit again.`;
+}
+function divergenceShapeHash(entries) {
+    // Sort tuples so the hash is order-independent — the comparator's emit
+    // order is structural-walk based, but small refactors to compareApiResults
+    // shouldn't accidentally invalidate the convergence signal.
+    const tuples = entries
+        .map((e) => `${e.path}::${e.kind}`)
+        .sort()
+        .join("\n");
+    return crypto.createHash("sha256").update(tuples).digest("hex").slice(0, 16);
+}
+function findLastDivergedShapeHash(history) {
+    for (let i = history.attempts.length - 1; i >= 0; i--) {
+        const entry = history.attempts[i];
+        if (entry && entry.kind === "diverged" && entry.divergenceShapeHash) {
+            return entry.divergenceShapeHash;
+        }
+    }
+    return undefined;
+}
+async function readHistory(appRootDir, apiName) {
+    let raw;
+    try {
+        raw = await readFile(historyPath(appRootDir, apiName), "utf-8");
+    }
+    catch {
+        // Missing — fresh API, no history yet. Distinct from "present but
+        // unparseable", which we want to surface as a warning so an operator
+        // chasing a stuck migration can tell amnesia apart from no-prior-run.
+        return { attempts: [] };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === "object" &&
+            "attempts" in parsed &&
+            Array.isArray(parsed.attempts)) {
+            return parsed;
+        }
+        getLogger().warn(`Verification history for ${apiName} parsed but had unexpected shape; treating as empty`, { apiName });
+    }
+    catch (error) {
+        getLogger().warn(`Verification history for ${apiName} was unreadable JSON (likely a partial-write crash); treating as empty`, {
+            apiName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return { attempts: [] };
+}
+/**
+ * Per-(appRootDir, apiName) serialization of the read-modify-write on the
+ * `<apiName>.history.json` file. Without this, two parallel
+ * `runMigrationVerification` calls for the same API can both observe
+ * `attempts.length = MAX-1`, both pass the cap check, and both write — the
+ * later clobbers the earlier and the cap is silently bypassed. We re-use the
+ * same `OperationQueue` primitive `migration-checklist.ts` uses for the
+ * shared checklist mutations.
+ */
+const verificationHistoryQueues = new Map();
+function getVerificationHistoryQueue(appRootDir, apiName) {
+    const key = `${appRootDir}\0${apiName}`;
+    let queue = verificationHistoryQueues.get(key);
+    if (!queue) {
+        queue = new OperationQueue();
+        verificationHistoryQueues.set(key, queue);
+    }
+    return queue;
+}
+/**
+ * Append a history entry without enqueueing — caller MUST already hold the
+ * per-API verification queue. Used from `runMigrationVerification`'s queued
+ * body, where re-entering the same queue would deadlock.
+ */
+async function writeHistoryEntry(appRootDir, apiName, entry) {
+    try {
+        const history = await readHistory(appRootDir, apiName);
+        history.attempts.push(entry);
+        const dir = join(appRootDir, SCRATCH_DIR, VERIFICATION_DIR);
+        await mkdir(dir, { recursive: true });
+        // Atomic write via tmp + rename: a crash mid-write would otherwise
+        // leave the file truncated, and `readHistory`'s catch would silently
+        // amnesia-reset the cap to zero. POSIX `rename` is atomic on the same
+        // filesystem, so a reader either sees the full prior file or the full
+        // new file — never a partial write.
+        const finalPath = historyPath(appRootDir, apiName);
+        const tmpPath = `${finalPath}.tmp`;
+        await writeFile(tmpPath, JSON.stringify(history, null, 2), "utf-8");
+        await rename(tmpPath, finalPath);
+    }
+    catch (error) {
+        // History persistence is best-effort: a write failure here should not
+        // surface as a verification error to the agent (the verification
+        // result itself is still valid). Worst case: the next attempt sees
+        // stale history and computes `progress: "first_attempt"`, which is a
+        // softer failure mode than throwing here.
+        getLogger().warn(`Failed to persist verification history for ${apiName}`, {
+            apiName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Read the on-disk diff JSON written by the most recent diverged run, if any.
+ * Used by the `exhausted` outcome to surface "what did we get stuck on" to
+ * the agent without re-running the pipeline.
+ */
+async function readLastDivergedDiff(appRootDir, apiName) {
+    try {
+        const raw = await readFile(diffPath(appRootDir, apiName), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === "object" &&
+            "valuesForUi" in parsed &&
+            Array.isArray(parsed.valuesForUi)) {
+            // We only persist `valuesForUi` (see writeFile call in
+            // computeVerificationOutcome), not summaryForAgent — synthesize a
+            // minimal ApiComparisonDiff so the exhausted outcome carries
+            // something the UI/agent can render.
+            return {
+                empty: false,
+                valuesForUi: parsed.valuesForUi,
+                summaryForAgent: [],
+            };
+        }
+    }
+    catch {
+        // No prior diff or unreadable — fine, return undefined.
+    }
+    return undefined;
+}
+//# sourceMappingURL=migration-verification.js.map