@superblocksteam/vite-plugin-file-sync 2.0.141-next.2 → 2.0.142-next.0

package/dist/migration/migration-verification.js

@@ -11,15 +11,18 @@ 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 V2_BACKUP_DIR = "v2-backup";
 const DIFF_SIZE_CAP = 1024 * 1024; // 1 MB
 const PIPELINE_TIMEOUT_MS = 30_000;
 /**
@@ -30,6 +33,35 @@ const PIPELINE_TIMEOUT_MS = 30_000;
  * 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
@@ -58,11 +90,24 @@ export async function runMigrationVerification(params) {
     // APIs use different queues and remain fully parallel.
     return getVerificationHistoryQueue(params.appRootDir, params.apiName).enqueue(async () => {
         const history = await readHistory(params.appRootDir, params.apiName);
-        if (history.attempts.length >= MAX_VERIFICATION_ATTEMPTS) {
+        // 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: history.attempts.length,
+                attempts: effectiveAttempts,
                 lastDivergence: await readLastDivergedDiff(params.appRootDir, params.apiName),
             };
         }
@@ -81,10 +126,23 @@ export async function runMigrationVerification(params) {
             outcome = {
                 kind: "diverged",
                 diff: raw.diff,
-                attempt: history.attempts.length + 1,
+                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;
         }
@@ -96,8 +154,25 @@ export async function runMigrationVerification(params) {
         // consistent shape. Apply name only; raw failure strings stay scrubbed.
         getLogger().info(`[migration-verify] outcome`, {
             apiName: params.apiName,
-            attempt: history.attempts.length + 1,
+            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"
@@ -118,6 +193,26 @@ export async function runMigrationVerification(params) {
         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.
@@ -159,7 +254,7 @@ async function computeVerificationOutcome({ apiName, appRootDir, inputs, runV2Pi
             ],
         };
     }
-    const v2BackupPath = join(appRootDir, SCRATCH_DIR, V2_BACKUP_DIR, "apis", apiName, "api.yaml");
+    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.
@@ -198,12 +293,22 @@ async function computeVerificationOutcome({ apiName, appRootDir, inputs, runV2Pi
         if (error instanceof PipelineTimeoutError) {
             return { kind: "timeout", side: "v2", reason: error.message };
         }
-        if (error instanceof EditorClientUnavailableError) {
-            return { kind: "disconnected", 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: error instanceof Error ? error.message : String(error),
+            reason: formatV2UnrunnableReason(error),
         };
     }
     // 3. Run v3 SDK.
@@ -215,12 +320,17 @@ async function computeVerificationOutcome({ apiName, appRootDir, inputs, runV2Pi
         if (error instanceof PipelineTimeoutError) {
             return { kind: "timeout", side: "v3", reason: error.message };
         }
-        if (error instanceof EditorClientUnavailableError) {
-            return { kind: "disconnected", side: "v3", reason: error.message };
+        if (error instanceof EditorClientUnavailableError ||
+            isPeerUnavailableError(error)) {
+            return {
+                kind: "disconnected",
+                side: "v3",
+                reason: errorReason(error),
+            };
         }
         return {
             kind: "error",
-            reason: error instanceof Error ? error.message : String(error),
+            reason: errorReason(error),
         };
     }
     // 3.5. If both executions returned failure, surface that explicitly rather
@@ -305,9 +415,122 @@ async function computeVerificationOutcome({ apiName, appRootDir, inputs, runV2Pi
     return { kind: "diverged", diff };
 }
 /** Relative path (from appRootDir) for a diff JSON file. */
-export function diffRelativePath(apiName) {
+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
@@ -345,7 +568,11 @@ export const migrationVerificationToolFactory = createToolFactory("runMigrationV
             apiName,
             integrationIds,
         });
-        if (effective === "allow" || sourceIds.length === 0) {
+        // 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) => ({
@@ -428,19 +655,20 @@ export const migrationVerificationToolFactory = createToolFactory("runMigrationV
                 // 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;
-                if (!editorClient) {
-                    throw new EditorClientUnavailableError("No editor client available");
-                }
+                // `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;
-                if (!editorClient) {
-                    throw new EditorClientUnavailableError("No editor client available");
-                }
+                await assertEditorClientConnected(editorClient, "v3 SDK");
                 const sdkResult = await editorClient.call.aiExecuteSdkApi({
                     apiName,
                     input: sdkInputs,
@@ -466,97 +694,17 @@ export const migrationVerificationToolFactory = createToolFactory("runMigrationV
                 };
             },
         });
-        // Update checklist with verification metadata. Each branch explicitly
-        // clears fields from the previous run that no longer apply (null = clear).
-        if (outcome.kind === "passed") {
+        if (verificationCountsAsApiTest(outcome.kind)) {
             markSdkApiAsVerified(clark, apiName);
-            await updateChecklistItem({
-                appRootDirPath: appRootDir,
-                itemId: `api_${apiName}`,
-                verificationOutcome: "auto_passed",
-                verificationSkippedReason: null,
-                lastVerificationAt: new Date().toISOString(),
-            });
-        }
-        else if (outcome.kind === "skipped_mutation") {
-            await updateChecklistItem({
-                appRootDirPath: appRootDir,
-                itemId: `api_${apiName}`,
-                verificationSkippedReason: "mutation",
-                verificationOutcome: null,
-                lastVerificationAt: new Date().toISOString(),
-            });
-        }
-        else if (outcome.kind === "v2_unrunnable") {
-            await updateChecklistItem({
-                appRootDirPath: appRootDir,
-                itemId: `api_${apiName}`,
-                verificationSkippedReason: "v2_unrunnable",
-                verificationOutcome: null,
-                lastVerificationAt: new Date().toISOString(),
-            });
-        }
-        else if (outcome.kind === "both_failed") {
-            // Both v2 and v3 errored — most often because the API reads bindings
-            // we didn't supply. Per the migration skill, the agent should
-            // synthesize realistic inputs and retry rather than treat this as a
-            // terminal outcome, so we deliberately do NOT mark `status: completed`
-            // here (a previous version did, which contradicted the skill and left
-            // the item stuck `completed` even after the agent kept iterating).
-            // We still record `verificationSkippedReason: "both_failed"` so the
-            // UI can surface the transient state; subsequent diverged/passed
-            // attempts clear it via `verificationSkippedReason: null`.
-            await updateChecklistItem({
-                appRootDirPath: appRootDir,
-                itemId: `api_${apiName}`,
-                verificationSkippedReason: "both_failed",
-                verificationOutcome: null,
-                lastVerificationAt: new Date().toISOString(),
-            });
-        }
-        else if (outcome.kind === "diverged") {
-            await updateChecklistItem({
-                appRootDirPath: appRootDir,
-                itemId: `api_${apiName}`,
-                verificationOutcome: null,
-                verificationSkippedReason: null,
-                lastVerificationAt: new Date().toISOString(),
-                lastVerificationDiffPath: diffRelativePath(apiName),
-            });
-        }
-        else if (outcome.kind === "exhausted") {
-            // Hard cap reached. Mark the item failed so classifyItem routes it to
-            // the manual-verification lane and the user knows automatic
-            // reconciliation gave up. The agent must NOT keep calling
-            // runMigrationVerification for this API in this migration run; the
-            // tool will return `exhausted` again until the migration is reset.
-            await updateChecklistItem({
-                appRootDirPath: appRootDir,
-                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) }
-                    : {}),
-            });
-        }
-        else {
-            // outcome.kind === "error" | "timeout" | "disconnected": clear stale
-            // fields so classifyItem doesn't misclassify this item as verified or
-            // skipped. Timeout and disconnected deliberately share this branch —
-            // they must NOT set a verificationSkippedReason or mark the item
-            // complete; the agent is told to retry via the tool result below.
-            await updateChecklistItem({
-                appRootDirPath: appRootDir,
-                itemId: `api_${apiName}`,
-                verificationOutcome: null,
-                verificationSkippedReason: null,
-                lastVerificationAt: new Date().toISOString(),
-            });
         }
+        // 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",
@@ -644,6 +792,19 @@ export const migrationVerificationToolFactory = createToolFactory("runMigrationV
                     `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",
@@ -707,6 +868,38 @@ class PipelineTimeoutError extends Error {
  */
 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.
  *
@@ -724,7 +917,7 @@ export class EditorClientUnavailableError extends Error {
  * Treats `unknown` step classifications (dynamic SQL bodies, plugins we don't
  * recognize) as mutations: better to ask the user than silently run a write.
  */
-export async function analyzeV2BackupMutations(v2BackupPath) {
+async function analyzeV2BackupMutations(v2BackupPath) {
     let raw;
     try {
         raw = await readFile(v2BackupPath, "utf-8");
@@ -757,34 +950,14 @@ export async function analyzeV2BackupMutations(v2BackupPath) {
         integrationIds: Array.from(integrationIds),
     };
 }
-async function readIntegrationWritePolicy(appRootDir) {
-    try {
-        const raw = await readFile(join(appRootDir, SCRATCH_DIR, "migration-state.json"), "utf-8");
-        const parsed = JSON.parse(raw);
-        const pol = parsed.integrationWritePolicy;
-        if (pol !== null && typeof pol === "object" && !Array.isArray(pol)) {
-            // Coerce any legacy persisted "ask" values to "deny" — the modal no
-            // longer offers "ask", and "deny" preserves the "don't auto-run writes"
-            // behavior it used to imply during verification.
-            return Object.fromEntries(Object.entries(pol).map(([id, value]) => [
-                id,
-                value === "allow" ? "allow" : "deny",
-            ]));
-        }
-    }
-    catch {
-        // missing or unreadable — default to deny
-    }
-    return {};
-}
 function mostRestrictivePolicy(policies) {
     if (policies.includes("deny"))
         return "deny";
     return "allow";
 }
 async function getEffectiveMigrationWritePolicy({ appRootDir, apiName, integrationIds, }) {
-    const policy = await readIntegrationWritePolicy(appRootDir);
-    const v2BackupPath = join(appRootDir, SCRATCH_DIR, V2_BACKUP_DIR, "apis", apiName, "api.yaml");
+    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
@@ -815,30 +988,15 @@ export const checkRunMigrationVerificationPermissions = async (services, input)
     catch {
         return PermissionLevel.PROMPT;
     }
-    let mutations;
     try {
-        mutations = extractMutations(source);
+        extractMutations(source);
     }
     catch {
         return PermissionLevel.PROMPT;
     }
-    if (mutations.length === 0)
-        return PermissionLevel.ALLOW;
-    let integrationIds;
-    try {
-        const ids = extractIntegrationIdsFromSource(source);
-        if (ids.length > 0)
-            integrationIds = ids;
-    }
-    catch {
-        integrationIds = undefined;
-    }
-    const { effective } = await getEffectiveMigrationWritePolicy({
-        appRootDir: services.appRootDirPath,
-        apiName,
-        integrationIds,
-    });
-    return effective === "allow" ? PermissionLevel.ALLOW : PermissionLevel.BLOCK;
+    // 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>.
@@ -873,6 +1031,23 @@ function redactForAgent(msg, maxLen = REDACTED_AGENT_FAILURE_MAX_LEN) {
         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