@superblocksteam/gateway 2.0.161-next.0 → 2.0.162-next.0

package/dist/capabilities/lifecycle.js

@@ -1,27 +1,47 @@
 import { randomUUID } from "node:crypto";
 import { readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
-import { detectAttachmentArchiveType } from "@superblocksteam/shared";
+import { detectAttachmentArchiveType, getAttachmentMimeTypeFromFileName, getTextAttachmentType, isSupportedAttachmentUploadType, } from "@superblocksteam/shared";
 import { buildBrowserDriverContract, needsBrowserDriverError, } from "../capture/browser-contract.js";
 import { resolveCaptureMode } from "../capture/mode.js";
-import { EMPTY_EVENT_CURSOR, parseEventCursor } from "../events/cursor.js";
+import { gatewayDebug } from "../debug.js";
 import { playwrightChromiumPresent } from "../playwright/ensure-chromium.js";
-import { buildEmbedShellPreviewUrl, buildOpenablePreviewUrls, } from "../preview/viewer-url.js";
+import { isTrustedEmbedOrigin, } from "../preview/capture-screenshot.js";
+import { buildEmbedShellPreviewUrl, buildOpenablePreviewUrls, isHttpsUrl, } from "../preview/viewer-url.js";
+import { PromptNotSentError, } from "../sabs/session-peer.js";
 import { ServerHttpError } from "../server/client.js";
 import { IdentityUnavailableError } from "../server/identity-reads.js";
-import { buildImportPrompt } from "./import-prompt.js";
-import { readPersistedProgress } from "./persisted-progress.js";
-import { buildStatusOf } from "./types.js";
+import { archiveSourceFiles } from "./source-files-archive.js";
+import { buildStatusOf, progressStatusOf } from "./types.js";
 import { IMPORT_ZIP_MAX_BYTES } from "./types.js";
 export { IMPORT_ZIP_MAX_BYTES } from "./types.js";
 const APPLICATION_CONTEXT_REQUIRED = "No applicationId provided and no recent application is available. Call start_app first or pass applicationId.";
+const APPLICATION_CONTEXT_AMBIGUOUS = "No applicationId provided and more than one application was worked on recently. Pass the applicationId of the application this conversation is building.";
+/**
+ * How long an application stays eligible to stand in for one a call did not
+ * name. A default argument is only useful while it is still plausibly what the
+ * caller meant: this process is shared by every chat in the client, so an
+ * unbounded fallback hands one conversation an application another one left
+ * behind.
+ */
+const RECENT_APP_FALLBACK_WINDOW_MS = 30 * 60 * 1000;
 /**
  * Every app the gateway starts is a code-mode app (`createUsingReact`), which
  * the UI serves from `/code-mode` — the legacy `/applications/:id/edit` route
  * does not open it.
  */
-function editUrl(config, applicationId) {
-    return `${config.uiBaseUrl.replace(/\/$/, "")}/code-mode/applications/edit/${applicationId}`;
+function editUrl(config, applicationId, branch) {
+    const base = `${config.uiBaseUrl.replace(/\/$/, "")}/code-mode/applications/edit/${applicationId}`;
+    return branch
+        ? `${base}?${new URLSearchParams({ branch }).toString()}`
+        : base;
+}
+function fullscreenPreviewUrl(config, applicationId, branch) {
+    const params = new URLSearchParams({ fullscreen: "true" });
+    if (branch) {
+        params.set("branch", branch);
+    }
+    return `${editUrl(config, applicationId)}?${params.toString()}`;
 }
 function uiOrigin(config) {
     return config.uiBaseUrl.replace(/\/$/, "");
@@ -38,8 +58,8 @@ async function captureModeOf(ctx) {
         hostMcpConfigured: ctx.config.captureHostMcp,
     });
 }
-function libraryCaptureInput(ctx, applicationId) {
-    const context = ctx.sessionPeer.libraryBrowserContext?.(applicationId);
+function libraryCaptureInput(ctx, applicationId, branch) {
+    const context = ctx.sessionPeer.libraryBrowserContext(applicationId, branch);
     if (!context) {
         return undefined;
     }
@@ -92,14 +112,16 @@ function libraryCaptureInput(ctx, applicationId) {
  * live-edit when the in-memory hold is empty (MCP respawn / tool timeout).
  */
 async function ensureLibraryCaptureInput(ctx, principal, applicationId, branch) {
-    const existing = libraryCaptureInput(ctx, applicationId);
+    const existing = libraryCaptureInput(ctx, applicationId, branch);
     if (existing) {
         return existing;
     }
-    if (!ctx.sessionPeer.holdLiveEdit) {
-        console.error("gateway live canvas skipped: hold_live_edit_unavailable", {
-            applicationId,
-        });
+    if (ctx.appState.pendingStart({
+        applicationId,
+        ...(branch ? { branch } : {}),
+        organizationId: principal.organizationId,
+        userId: principal.userId,
+    })) {
         return undefined;
     }
     if (!(await gatewayChromiumIsPresent(ctx))) {
@@ -123,6 +145,13 @@ async function ensureLibraryCaptureInput(ctx, principal, applicationId, branch)
             apiKey: principal.apiKey,
             applicationId,
             branch,
+            getLiveEditStatus: ({ liveEditId, signal }) => ctx.server.getLiveEditStatus({
+                apiKey: principal.apiKey,
+                applicationId,
+                branch,
+                liveEditId,
+                signal,
+            }),
             keepalive: async () => {
                 await ctx.server.connectLiveEdit({
                     apiKey: principal.apiKey,
@@ -130,6 +159,7 @@ async function ensureLibraryCaptureInput(ctx, principal, applicationId, branch)
                     branch,
                 });
             },
+            liveEditId: session.liveEditId,
             liveEditUrl: session.liveEditUrl,
             organizationId: principal.organizationId,
             sessionToken,
@@ -143,7 +173,7 @@ async function ensureLibraryCaptureInput(ctx, principal, applicationId, branch)
         });
         return undefined;
     }
-    const live = libraryCaptureInput(ctx, applicationId);
+    const live = libraryCaptureInput(ctx, applicationId, branch);
     if (!live) {
         console.error("gateway live canvas skipped: context_incomplete_after_rehold", { applicationId });
     }
@@ -183,18 +213,19 @@ async function captureLiveLibraryIfNeeded(ctx, applicationId, live) {
         return { needsBrowserDriver: true };
     }
 }
-async function browserContractFor(ctx, applicationId) {
+async function browserContractFor(ctx, directEditUrl) {
     return buildBrowserDriverContract({
         captureMode: await captureModeOf(ctx),
-        editUrl: editUrl(ctx.config, applicationId),
+        editUrl: directEditUrl,
+        ...(ctx.hostBrowserTools ? { hostBrowserTools: ctx.hostBrowserTools } : {}),
         isolated: ctx.config.captureHostIsolated,
         uiOrigin: uiOrigin(ctx.config),
     });
 }
-async function withBrowser(ctx, applicationId, value) {
+async function withBrowser(ctx, value) {
     return {
         ...value,
-        browser: await browserContractFor(ctx, applicationId),
+        browser: await browserContractFor(ctx, value.editUrl),
     };
 }
 /**
@@ -205,6 +236,9 @@ async function withBrowser(ctx, applicationId, value) {
 function publishUrl(config, applicationId) {
     return `${config.uiBaseUrl.replace(/\/$/, "")}/code-mode/applications/${applicationId}`;
 }
+function publishDetailsUrl(config, applicationId, commitId) {
+    return `${editUrl(config, applicationId)}?${new URLSearchParams({ commitId }).toString()}`;
+}
 /**
  * Where a built, undeployed commit can be opened — what the editor's Preview
  * button hands the browser. Distinct from {@link publishUrl}: this serves a
@@ -334,11 +368,11 @@ async function finalAppName(ctx, input) {
         prompt: input.prompt,
     })) ?? input.name);
 }
-async function elicitStepUp(ctx, idempotencyKey, applicationId) {
+async function elicitStepUp(ctx, idempotencyKey, applicationId, branch) {
     if (!ctx.config.captureHostMcp) {
         return needsBrowserDriverError();
     }
-    const existing = await ctx.turns.getByIdempotencyKey(idempotencyKey);
+    const existing = ctx.stepUpTurns.getByIdempotencyKey(idempotencyKey);
     if (existing?.status === "ready") {
         return {
             kind: "error",
@@ -346,7 +380,7 @@ async function elicitStepUp(ctx, idempotencyKey, applicationId) {
             message: "Step-up authentication completed. Re-invoke the capability to continue.",
         };
     }
-    const browser = await browserContractFor(ctx, applicationId);
+    const browser = await browserContractFor(ctx, editUrl(ctx.config, applicationId, branch));
     if (existing?.status === "pending") {
         return {
             kind: "auth_required",
@@ -361,7 +395,7 @@ async function elicitStepUp(ctx, idempotencyKey, applicationId) {
     const turnId = randomUUID();
     const callbackToken = randomUUID();
     const authUrl = uiOrigin(ctx.config);
-    const turn = await ctx.turns.create({
+    const turn = ctx.stepUpTurns.create({
         authUrl,
         callbackToken,
         idempotencyKey,
@@ -383,28 +417,47 @@ async function elicitStepUp(ctx, idempotencyKey, applicationId) {
         },
     };
 }
-export async function resolveApplicationId(ctx, principal, applicationId) {
+export async function resolveApplicationId(ctx, principal, applicationId, 
+/**
+ * `unambiguous` declines to guess while a second application is also in
+ * play. Reserved for calls that write: acting on the wrong application is
+ * cheap to undo for a status poll and not cheap at all for an edit.
+ */
+options = {}) {
     if (applicationId?.trim()) {
         return { kind: "ok", value: applicationId.trim() };
     }
-    const recent = await ctx.recentApps.get({
+    const key = {
         organizationId: principal.organizationId,
         userId: principal.userId,
-    });
-    if (!recent?.applicationId) {
+    };
+    const recent = options.unambiguous
+        ? ctx.recentApps.recentUnambiguous(key, RECENT_APP_FALLBACK_WINDOW_MS)
+        : ctx.recentApps.recent(key, RECENT_APP_FALLBACK_WINDOW_MS);
+    if (!recent) {
+        const ambiguous = options.unambiguous === true &&
+            ctx.recentApps.recent(key, RECENT_APP_FALLBACK_WINDOW_MS) !== undefined;
         return {
             kind: "error",
             code: "application_context_required",
-            message: APPLICATION_CONTEXT_REQUIRED,
+            message: ambiguous
+                ? APPLICATION_CONTEXT_AMBIGUOUS
+                : APPLICATION_CONTEXT_REQUIRED,
         };
     }
+    // Leaning on the fallback is itself working on the application. Without this
+    // a build polled for longer than the window would age out mid-poll, and the
+    // progress call that had been answering all along would start reporting no
+    // application context. `set` keeps the branch already recorded for it.
+    ctx.recentApps.set({ ...key, applicationId: recent.applicationId });
     return { kind: "ok", value: recent.applicationId };
 }
-async function rememberApplication(ctx, principal, applicationId) {
-    await ctx.recentApps.set({
+function rememberApplication(ctx, principal, applicationId, branch) {
+    ctx.recentApps.set({
         applicationId,
         organizationId: principal.organizationId,
         userId: principal.userId,
+        ...(branch ? { branch } : {}),
     });
 }
 function sleep(ms) {
@@ -435,15 +488,60 @@ function sleepUntilAbort(ms, signal) {
         signal.addEventListener("abort", done, { once: true });
     });
 }
+function readDeployOutcome(status) {
+    if (status.status === "DEPLOYED") {
+        return { kind: "deployed" };
+    }
+    if (status.status === "FAILED") {
+        return {
+            kind: "failed",
+            message: status.error ?? "The Superblocks API could not deploy the app.",
+        };
+    }
+    if (status.status === "AWAITING_ACK") {
+        return {
+            kind: "needs_acknowledgement",
+            message: `${status.error ?? "Policy checks passed with advisory findings."} Publishing is on hold until they are reviewed in Superblocks, or until this is published again with the findings acknowledged.`,
+        };
+    }
+    // "none" is not evidence of a successful deploy: the queue row may be
+    // missing, cleaned up after failure, or the deploy path may be unavailable.
+    // It counts as still running, and never as live.
+    return { kind: "running", status: status.status };
+}
+function deployStatusReadIsTransient(error) {
+    return (!(error instanceof ServerHttpError) ||
+        error.status === 429 ||
+        error.status >= 500);
+}
+/** The two outcomes that end a publish, as the error the caller reads. */
+function deployFailure(outcome, message) {
+    return {
+        kind: "error",
+        code: outcome.kind === "failed"
+            ? "publish_failed"
+            : "publish_needs_acknowledgement",
+        message,
+    };
+}
+/**
+ * Follows a queued deploy until it lands, fails, or the call runs out of the
+ * time a host allows it.
+ *
+ * Running out is not a failure: `settled` false means the deploy is still
+ * going and the caller should hand it back with pacing rather than report a
+ * publish that worked as a timeout (ENG-6172).
+ */
 async function waitForDeployLive(ctx, input) {
-    const deadline = Date.now() + ctx.config.publishWaitTimeoutMs;
     let lastStatus = "queued";
-    while (Date.now() < deadline) {
-        if (input.signal?.aborted) {
+    while (nowMs(ctx) < input.deadlineAtMs) {
+        if (ctx.signal?.aborted) {
             return {
-                kind: "error",
-                code: "publish_aborted",
-                message: "Publish wait was cancelled.",
+                kind: "ok",
+                value: {
+                    lastStatus: lastStatus === "none" ? "queued" : lastStatus,
+                    settled: false,
+                },
             };
         }
         let status;
@@ -452,9 +550,32 @@ async function waitForDeployLive(ctx, input) {
                 apiKey: input.apiKey,
                 applicationId: input.applicationId,
                 commitId: input.commitId,
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+                timeoutMs: Math.max(1, input.deadlineAtMs - nowMs(ctx)),
             });
         }
         catch (error) {
+            if (ctx.signal?.aborted) {
+                return {
+                    kind: "ok",
+                    value: {
+                        lastStatus: lastStatus === "none" ? "queued" : lastStatus,
+                        settled: false,
+                    },
+                };
+            }
+            if (nowMs(ctx) >= input.deadlineAtMs) {
+                return {
+                    kind: "ok",
+                    value: { lastStatus: "queued", settled: false },
+                };
+            }
+            if (deployStatusReadIsTransient(error)) {
+                return {
+                    kind: "ok",
+                    value: { lastStatus: "queued", settled: false },
+                };
+            }
             return {
                 kind: "error",
                 code: "publish_failed",
@@ -462,38 +583,30 @@ async function waitForDeployLive(ctx, input) {
             };
         }
         lastStatus = status.status;
-        if (status.status === "DEPLOYED") {
-            ctx.onProgress?.({ message: "App is live", type: "progress" });
-            return { kind: "ok", value: {} };
+        const outcome = readDeployOutcome(status);
+        if (outcome.kind === "running") {
+            if (outcome.status === "none") {
+                ctx.appState.noteMissingPublishStatus(input.applicationId, input.publishClaim, nowMs(ctx));
+            }
+            else {
+                ctx.appState.noteVisiblePublishStatus(input.applicationId, input.publishClaim);
+            }
         }
-        if (status.status === "FAILED") {
-            return {
-                kind: "error",
-                code: "publish_failed",
-                message: status.error ?? "The Superblocks API could not deploy the app.",
-            };
+        if (outcome.kind === "deployed") {
+            ctx.onProgress?.({ message: "App is live", type: "progress" });
+            return { kind: "ok", value: { lastStatus, settled: true } };
         }
-        if (status.status === "AWAITING_ACK") {
-            return {
-                kind: "error",
-                code: "publish_needs_acknowledgement",
-                message: `${status.error ?? "Policy checks passed with advisory findings."} Publishing is on hold until they are reviewed in Superblocks, or until this is published again with the findings acknowledged.`,
-            };
+        if (outcome.kind !== "running") {
+            ctx.appState.clearPublishInFlight(input.applicationId, input.publishClaim);
+            return deployFailure(outcome, outcome.message);
         }
-        // "none" is not evidence of a successful deploy: the queue row may be
-        // missing, cleaned up after failure, or the deploy path may be unavailable.
-        // Keep waiting until DEPLOYED, FAILED, AWAITING_ACK, or timeout.
         ctx.onProgress?.({
-            message: `Waiting for deploy (${status.status})…`,
+            message: `Waiting for deploy (${outcome.status})…`,
             type: "progress",
         });
-        await sleep(ctx.config.publishPollIntervalMs);
+        await sleepUntilAbort(Math.min(ctx.config.publishPollIntervalMs, Math.max(0, input.deadlineAtMs - nowMs(ctx))), ctx.signal);
     }
-    return {
-        kind: "error",
-        code: "publish_timeout",
-        message: `Timed out waiting for the app to go live (last status: ${lastStatus}). Open ${publishUrl(ctx.config, input.applicationId)} to check progress.`,
-    };
+    return { kind: "ok", value: { lastStatus, settled: false } };
 }
 /**
  * Both ways to look at a finished app, in the summary rather than only in the
@@ -501,14 +614,75 @@ async function waitForDeployLive(ctx, input) {
  * user who is never offered the preview deploys to their whole organization to
  * see what they built.
  */
-const NEXT_STEPS = "Preview it with preview_app, or publish it with publish_app";
+const NEXT_STEPS = "Inspect it with get_app, or publish it with publish_app";
+/**
+ * Which side of a waiting turn owes the next move.
+ *
+ * A stream hiccup can deliver the plan as chat text instead of a plan card,
+ * leaving needs_decision with no structured decision. The turn is waiting on a
+ * human either way, so the absence of a plan reads as a question, never as
+ * nothing to answer.
+ */
+function pendingActionForDecision(decision) {
+    if (!decision) {
+        return "decide_in_editor";
+    }
+    switch (decision.kind) {
+        case "missing_integrations":
+            return "create_integration";
+        case "multi_choice":
+            return "answer_question";
+        case "plan":
+            return "approve_plan";
+        default: {
+            const unhandled = decision;
+            return unhandled;
+        }
+    }
+}
+/**
+ * What a waiting turn owes, in the tool result's own closing line.
+ *
+ * A host without form elicitation (Claude Desktop) has only this line and the
+ * server instructions to go on, and it follows the tool's own output more
+ * closely. Naming the call before the person - "call edit_app with the answer"
+ * - reads as an instruction to answer now, which is how a host ends up
+ * approving a plan the user was never shown.
+ */
+function decisionSummary(decision) {
+    if (!decision) {
+        return "Superblocks stopped and is waiting on the user - open the editor to review and decide.";
+    }
+    if (decision.kind === "missing_integrations") {
+        return "Superblocks needs integrations - call create_integration once for every entry in decision.integrations.";
+    }
+    if (decision.kind === "plan") {
+        return "Superblocks proposed a plan and is waiting for the user's decision.";
+    }
+    if (decision.kind === "multi_choice") {
+        return "Superblocks asked the user a question and stopped.";
+    }
+    const unhandled = decision;
+    return unhandled;
+}
+const REPLACE_WEDGED_APP_GUIDANCE = "Superblocks could not start this application's live-edit session. Retrying the build cannot recover this application.";
+const PRESERVE_WEDGED_APP_GUIDANCE = "Superblocks could not open this existing application's live-edit session. Retrying the build cannot recover it.";
+function unavailableReplacementGuidance(applicationId) {
+    return `No unused fresh-application replacement is available for ${applicationId}.`;
+}
 /**
  * Closing progress line, so the client's last word says whether the app is
  * committed and openable or still needs something from Claude.
  */
 function turnSummary(turn) {
+    if (turn.checkpointFailure) {
+        return "Superblocks finished building, but its checkpoint could not be saved - open the editor to inspect or recover it";
+    }
+    if (turn.decision?.kind === "missing_integrations") {
+        return decisionSummary(turn.decision);
+    }
     if (turn.generationStatus === "needs_decision") {
-        return "Superblocks needs a decision — call edit_app with the answer";
+        return decisionSummary(turn.decision);
     }
     if (turn.generationStatus === "no_changes") {
         return "The Superblocks job ended without building anything — read its reply";
@@ -517,40 +691,38 @@ function turnSummary(turn) {
         return "Superblocks is still working, but only the editor can show it — open the edit URL";
     }
     if (turn.generationStatus === "live_edit_terminated") {
-        return turn.retryAction === "retry_import"
-            ? "The Superblocks live-edit session terminated before anything was built — send the archive again with import_app"
-            : "The Superblocks live-edit session terminated before anything was built — send the prompt again with edit_app";
+        if (turn.retryable === false) {
+            return turn.recoveryAction === "start_new_app"
+                ? (turn.reply ?? REPLACE_WEDGED_APP_GUIDANCE)
+                : (turn.reply ?? PRESERVE_WEDGED_APP_GUIDANCE);
+        }
+        return "The Superblocks live-edit session terminated before anything was built — send the prompt again with edit_app";
+    }
+    if (turn.checkpointWarning) {
+        return turn.checkpointWarning.message;
     }
     if (turn.checkpointCommitId) {
-        return `Application ready — checkpoint saved. ${NEXT_STEPS}`;
+        return `Application ready - checkpoint saved. ${NEXT_STEPS}`;
     }
     if (turn.viewStatus === "ready") {
         return `Application ready. ${NEXT_STEPS}`;
     }
     return "Superblocks finished generating; the app may still be building in the editor";
 }
-/**
- * Combines local turn activity with durable Redis lines, oldest-first, without
- * repeating the same message when both sources saw it.
- */
-function mergeActivity(live, persisted) {
-    const seen = new Set();
-    const merged = [];
-    for (const line of [...persisted, ...live]) {
-        if (!line || seen.has(line)) {
-            continue;
-        }
-        seen.add(line);
-        merged.push(line);
-    }
-    return merged;
-}
 async function promptInput(ctx, input) {
     return {
         apiKey: ctx.principal.apiKey,
         applicationId: input.applicationId,
         ...(input.attachments ? { attachments: input.attachments } : {}),
-        ...(input.importSource ? { importSource: input.importSource } : {}),
+        ...(input.branch ? { branch: input.branch } : {}),
+        getLiveEditStatus: ({ liveEditId, signal, }) => ctx.server.getLiveEditStatus({
+            apiKey: ctx.principal.apiKey,
+            applicationId: input.applicationId,
+            branch: input.branch,
+            liveEditId,
+            signal,
+        }),
+        idempotencyKey: input.idempotencyKey,
         keepalive: async () => {
             await ctx.server.connectLiveEdit({
                 apiKey: ctx.principal.apiKey,
@@ -576,8 +748,13 @@ async function promptInput(ctx, input) {
             ctx.onProgress?.({ message, type: "progress" });
         },
         organizationId: input.organizationId,
+        ...(input.pendingStartRequired ? { pendingStartRequired: true } : {}),
+        ...(input.pendingStartToken === undefined
+            ? {}
+            : { pendingStartToken: input.pendingStartToken }),
         ...(input.planContext ? { planContext: input.planContext } : {}),
         prompt: input.prompt,
+        revision: input.revision,
         ...(input.responseMetadata
             ? { responseMetadata: input.responseMetadata }
             : {}),
@@ -585,6 +762,7 @@ async function promptInput(ctx, input) {
             apiKey: ctx.principal.apiKey,
             applicationId: input.applicationId,
         }),
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
         userId: input.userId,
     };
 }
@@ -609,18 +787,6 @@ async function openLiveEdit(ctx, input) {
         applicationId: input.applicationId,
         branch: input.branch,
     });
-    try {
-        await ctx.progressCursors?.setLiveEditId({
-            applicationId: input.applicationId,
-            liveEditId: session.liveEditId,
-            organizationId: input.organizationId,
-        });
-    }
-    catch (error) {
-        console.warn("gateway could not record the live edit for resume", {
-            message: error instanceof Error ? error.message : String(error),
-        });
-    }
     return session;
 }
 /**
@@ -628,12 +794,16 @@ async function openLiveEdit(ctx, input) {
  * turn running on the held session for `check_app_progress` to follow.
  */
 async function startClarkPrompt(ctx, input) {
-    const started = await ctx.sessionPeer.startPrompt(await promptInput(ctx, input));
-    if (started.status === "auth_required") {
-        return elicitStepUp(ctx, `stepup:${input.idempotencyKey}`, input.applicationId);
+    let prepared;
+    try {
+        prepared = await promptInput(ctx, input);
+    }
+    catch (error) {
+        throw new PromptNotSentError(error instanceof Error ? error.message : String(error), error);
     }
-    if (input.mode === "BUILD") {
-        ctx.sessionPeer.markBuildMode?.(input.applicationId);
+    const started = await ctx.sessionPeer.startPrompt(prepared);
+    if (started.status === "auth_required") {
+        return elicitStepUp(ctx, `stepup:${input.idempotencyKey}`, input.applicationId, input.branch);
     }
     return {
         kind: "ok",
@@ -649,17 +819,27 @@ async function startClarkPrompt(ctx, input) {
 async function forwardClarkPrompt(ctx, input) {
     const forward = await ctx.sessionPeer.forwardPrompt(await promptInput(ctx, input));
     if (forward.status === "auth_required") {
-        return elicitStepUp(ctx, `stepup:${input.idempotencyKey}`, input.applicationId);
+        return elicitStepUp(ctx, `stepup:${input.idempotencyKey}`, input.applicationId, input.branch);
     }
-    if (input.mode === "BUILD") {
-        ctx.sessionPeer.markBuildMode?.(input.applicationId);
+    if (forward.generationStatus === "live_edit_terminated") {
+        return {
+            kind: "error",
+            code: "live_edit_unavailable",
+            message: forward.reply.trim() ||
+                "The Superblocks live-edit session is unavailable, so nothing was built. Send the prompt again to start it over.",
+            ...(forward.recoveryAction === "start_new_app"
+                ? { pendingAction: "start_new_app" }
+                : forward.retryable === false
+                    ? {}
+                    : { pendingAction: "retry_build" }),
+        };
     }
     if (forward.generationStatus === "timeout") {
         return {
             kind: "error",
             code: "superblocks_turn_timeout",
-            message: `Superblocks did not finish within the turn budget.${forward.reply ? ` Partial reply: ${forward.reply.slice(0, 500)}` : ""} Continue in the editor at ${editUrl(ctx.config, input.applicationId)}.`,
-            ...retryIfReplayable(input.attachments),
+            message: `Superblocks reported that the turn timed out.${forward.reply ? ` Partial reply: ${forward.reply.slice(0, 500)}` : ""} Continue in the editor at ${editUrl(ctx.config, input.applicationId, input.branch)}.`,
+            pendingAction: "retry_build",
         };
     }
     return {
@@ -668,6 +848,12 @@ async function forwardClarkPrompt(ctx, input) {
             ...(forward.checkpointCommitId
                 ? { checkpointCommitId: forward.checkpointCommitId }
                 : {}),
+            ...(forward.checkpointFailure
+                ? { checkpointFailure: forward.checkpointFailure }
+                : {}),
+            ...(forward.checkpointWarning
+                ? { checkpointWarning: forward.checkpointWarning }
+                : {}),
             reply: forward.reply,
             ...(forward.decision ? { decision: forward.decision } : {}),
             generationStatus: forward.generationStatus,
@@ -685,6 +871,7 @@ async function forwardClarkPrompt(ctx, input) {
  * `start_app` still returns in the seconds its callers expect.
  */
 const DEV_ENV_RETRY_DELAYS_MS = [400, 1200];
+const START_APP_RESPONSE_RESERVE_MS = 5_000;
 /**
  * Whether a failed create is worth repeating.
  *
@@ -708,9 +895,25 @@ function isRetryableCreateFailure(error) {
  * says the flag read failed rather than blaming their account.
  */
 async function createApplicationForPrompt(ctx, args) {
+    const { deadlineAtMs: deadline } = args;
+    const { deadlineAtMs: _deadlineAtMs, ...createInput } = args;
     for (let attempt = 0; attempt <= DEV_ENV_RETRY_DELAYS_MS.length; attempt += 1) {
+        if (nowMs(ctx) >= deadline) {
+            return {
+                kind: "error",
+                code: "create_application_timeout",
+                message: "Superblocks did not finish application creation before the tool-call deadline. No application ID was returned, so retry start_app.",
+            };
+        }
         try {
-            return { kind: "ok", value: await ctx.server.createApplication(args) };
+            return {
+                kind: "ok",
+                value: await ctx.server.createApplication({
+                    ...createInput,
+                    ...(ctx.signal ? { signal: ctx.signal } : {}),
+                    timeoutMs: Math.max(1, deadline - nowMs(ctx)),
+                }),
+            };
         }
         catch (error) {
             if (!isRetryableCreateFailure(error)) {
@@ -718,7 +921,7 @@ async function createApplicationForPrompt(ctx, args) {
             }
             const delayMs = DEV_ENV_RETRY_DELAYS_MS[attempt];
             if (delayMs !== undefined) {
-                await sleep(delayMs);
+                await sleep(Math.min(delayMs, Math.max(0, deadline - nowMs(ctx))));
             }
         }
     }
@@ -743,13 +946,13 @@ function namingApplication(applicationId, result) {
     return result.kind === "error" ? { ...result, applicationId } : result;
 }
 /**
- * Names the application `start_app` or `import_app` created, and says on the
- * way out that it is still there.
+ * Names the application `start_app` created, and says on the way out that it
+ * is still there.
  *
- * These two are the entry points that persist an application before the build
- * can start, so their failures are the ones that leave a resource behind. Until
- * every caller reads `applicationId` and retries rather than starting over,
- * this line is how an operator finds the applications they abandoned.
+ * This entry point persists an application before the build can start, so its
+ * failures can leave a resource behind. Until every caller reads
+ * `applicationId` and retries rather than starting over, this line is how an
+ * operator finds applications they abandoned.
  */
 function namingCreatedApplication(applicationId, capability, result) {
     if (result.kind === "error") {
@@ -761,30 +964,13 @@ function namingCreatedApplication(applicationId, capability, result) {
     }
     return namingApplication(applicationId, result);
 }
-/**
- * The recovery to advertise when the machinery around a turn fails: `edit_app`
- * with the same prompt, which is what `retry_build` means.
- *
- * A regular prompt is retried with `edit_app`. An import prompt carries an
- * attachment, so it must be retried with `import_app` to upload the archive
- * again and obtain a fresh signed URL.
- */
-function retryIfReplayable(attachments) {
-    return attachments && attachments.length > 0
-        ? { pendingAction: "retry_import" }
-        : { pendingAction: "retry_build" };
-}
-/**
- * A live edit that would not open. The app itself is intact and Clark never ran,
- * so where the prompt can be replayed the caller's way out is to send it again
- * rather than start over on a second app.
- */
-function liveEditUnavailable(error, attachments) {
+/** A live edit that would not open, before Clark saw the prompt. */
+function liveEditUnavailable(error) {
     return {
         kind: "error",
         code: "live_edit_unavailable",
         message: error instanceof Error ? error.message : String(error),
-        ...retryIfReplayable(attachments),
+        pendingAction: "retry_build",
     };
 }
 /**
@@ -793,8 +979,8 @@ function liveEditUnavailable(error, attachments) {
  *
  * Nothing else holds that: no turn was ever started, so without this the gateway
  * forgets the attempt entirely and every later read answers "nothing in flight"
- * - `check_app_progress` reports `unknown` while `get_app` commits and previews
- * the untouched starter template as though a build were running (ENG-5808).
+ * - `check_app_progress` reports `unknown` while `get_app` reports the untouched
+ * starter template as ready (ENG-5808).
  *
  * Deliberately not called when the prompt itself failed on an open session. The
  * prompt may well have reached Superblocks and be running now, and an
@@ -803,19 +989,37 @@ function liveEditUnavailable(error, attachments) {
  * it can build the app twice.
  */
 function rememberFailedStart(ctx, input) {
-    if (refusedCaller(input.error)) {
+    if (refusedCaller(input.error) && !input.pendingStartRequired) {
         return;
     }
     const cause = input.error instanceof Error ? input.error.message : String(input.error);
+    const recovery = input.retryable === false
+        ? "Gateway cannot safely recover that application by retrying the build."
+        : "Nothing is running for that application; send the same instruction again to retry it.";
     try {
-        ctx.sessionPeer.recordFailedStart?.({
+        ctx.sessionPeer.recordFailedStart({
             applicationId: input.applicationId,
+            ...(input.branch ? { branch: input.branch } : {}),
+            ...(input.idempotencyKey !== undefined
+                ? { idempotencyKey: input.idempotencyKey }
+                : {}),
+            ...(input.generationStatus
+                ? { generationStatus: input.generationStatus }
+                : {}),
+            ...(input.decision ? { decision: input.decision } : {}),
             organizationId: input.principal.organizationId,
+            ...(input.pendingStartRequired ? { pendingStartRequired: true } : {}),
+            ...(input.pendingStartToken === undefined
+                ? {}
+                : { pendingStartToken: input.pendingStartToken }),
             // Reaches the caller as the dead start's reply on its next poll, so it
             // has to stand on its own there rather than lean on this call's error.
             reason: input.reason ??
-                `The Superblocks live-edit session for application ${input.applicationId} never opened, so the prompt never reached Superblocks and nothing was built. Nothing is running for that application; send the same instruction again to retry it. (${cause})`,
+                `The Superblocks live-edit session for application ${input.applicationId} never opened, so the prompt never reached Superblocks and nothing was built. ${recovery} (${cause})`,
+            ...(input.revision === undefined ? {} : { revision: input.revision }),
+            ...(input.recoveryAction ? { recoveryAction: input.recoveryAction } : {}),
             ...(input.retryAction ? { retryAction: input.retryAction } : {}),
+            ...(input.retryable === false ? { retryable: false } : {}),
             userId: input.principal.userId,
         });
     }
@@ -847,16 +1051,57 @@ function rememberFailedStart(ctx, input) {
  * status for it. A genuinely missing app is the same answer for the same reason.
  */
 function refusedCaller(error) {
+    if (error instanceof PromptNotSentError) {
+        return refusedCaller(error.cause);
+    }
     return (error instanceof ServerHttpError &&
         (error.status === 401 || error.status === 403 || error.status === 404));
 }
+function normalizeBranch(branch) {
+    return branch?.trim() || undefined;
+}
+/**
+ * Clark's own skillset resolves a missing integration by asking, which works
+ * in the editor and strands a headless turn: the question reaches an MCP host
+ * that cannot answer it, and the integration the project declared never gets
+ * created. Say so on the turn rather than hoping the in-sandbox skill is
+ * loaded.
+ *
+ * Scoped by what the attachment declares, not by the fact that something was
+ * attached. An archive can just as easily hold spreadsheets or PDFs to build
+ * from, and for those "which datasource?" is a fair question with no answer
+ * hiding in the files.
+ */
+const MISSING_INTEGRATION_INSTRUCTION = `When the attached project declares its own data source connection, that declaration is the answer to which integration it needs. This turn's context lists the org's integrations: reuse one only when it is that same connection - for a database the same host, port, and database, for a REST API the same base URL. A similar name is not a match. When nothing matches, do not ask the caller which one to use, do not ask whether to create one, and do not leave placeholder integration IDs or call the work finished. Call openIntegrationSetup with the exact integration name, plugin ID, and non-secret configuration the project declares. Nobody is watching this session in a browser, so that call answers that the request was recorded for the MCP host: that is success, not failure - the host creates the integration and returns its ID on a follow-up turn. Never ask the caller for a password, API token, or other secret. Continue every part of the work that does not need the live integration, and leave the affected APIs pending until that follow-up supplies the ID. Attached files that declare no connection of their own - data, images, or documents to build from rather than an app to migrate - are outside this: choose or ask about a datasource as you normally would.`;
+/**
+ * Only attached files can declare a connection, so only those turns carry the
+ * rule. A prompt with nothing attached reaches Clark verbatim.
+ */
+function promptForAttachedSource(prompt, attachments) {
+    return attachments?.length
+        ? `${prompt}\n\n${MISSING_INTEGRATION_INSTRUCTION}`
+        : prompt;
+}
+function artifactAttachments(artifacts) {
+    return artifacts?.length
+        ? artifacts.map((artifact) => ({
+            fileName: artifact.fileName,
+            mediaType: artifact.mediaType,
+            scopeType: "org",
+            storageKey: artifact.storageKey,
+            type: "uploaded",
+            url: `/api/v1/files/content/${encodeURIComponent(artifact.id)}`,
+        }))
+        : undefined;
+}
 /**
- * The first prompt on an application that was just created, for both
- * `start_app` and `import_app`: connect a live-edit session, hand Clark the
- * prompt, and shape the turn it ran.
+ * The first prompt on an application that was just created: connect a live-edit
+ * session, hand Clark the prompt, and shape the turn it ran.
  */
 async function promptNewApplication(ctx, args) {
     const { applicationId, input, principal, prompt } = args;
+    const branch = normalizeBranch(input.branch);
+    const revision = args.pendingStartToken ?? ctx.appState.markTurnStarted();
     ctx.onProgress?.({
         message: "Connecting live-edit session",
         type: "progress",
@@ -866,36 +1111,45 @@ async function promptNewApplication(ctx, args) {
         session = await openLiveEdit(ctx, {
             apiKey: principal.apiKey,
             applicationId,
-            branch: input.branch,
+            branch,
             organizationId: principal.organizationId,
         });
     }
     catch (error) {
         rememberFailedStart(ctx, {
             applicationId,
+            branch,
             error,
+            idempotencyKey: input.idempotencyKey,
+            pendingStartRequired: args.pendingStartToken !== undefined,
+            pendingStartToken: args.pendingStartToken,
             principal,
-            ...(args.attachments?.length ? { retryAction: "retry_import" } : {}),
+            revision,
+            retryAction: "retry_build",
         });
-        return liveEditUnavailable(error, args.attachments);
+        return liveEditUnavailable(error);
     }
     ctx.onProgress?.({
-        message: args.importSource
-            ? "Forwarding import prompt to Superblocks"
-            : "Forwarding prompt to Superblocks",
+        message: "Forwarding prompt to Superblocks",
         type: "progress",
     });
     const promptArgs = {
         applicationId,
         ...(args.attachments ? { attachments: args.attachments } : {}),
-        branch: input.branch,
+        ...(branch ? { branch } : {}),
         idempotencyKey: input.idempotencyKey,
-        ...(args.importSource ? { importSource: args.importSource } : {}),
         liveEditId: session.liveEditId,
         liveEditUrl: session.liveEditUrl,
         mode: input.mode ?? "PLAN",
         organizationId: principal.organizationId,
-        prompt,
+        ...(args.pendingStartToken === undefined
+            ? {}
+            : {
+                pendingStartRequired: true,
+                pendingStartToken: args.pendingStartToken,
+            }),
+        prompt: promptForAttachedSource(prompt, args.attachments),
+        revision,
         userId: principal.userId,
     };
     const named = () => finalAppName(ctx, {
@@ -912,10 +1166,11 @@ async function promptNewApplication(ctx, args) {
         }
         return {
             kind: "ok",
-            value: await withBrowser(ctx, applicationId, {
+            value: await withBrowser(ctx, {
                 activity: started.value.activity,
                 applicationId,
-                editUrl: editUrl(ctx.config, applicationId),
+                ...(branch ? { branch } : {}),
+                editUrl: editUrl(ctx.config, applicationId, branch),
                 liveEditId: started.value.liveEditId ?? session.liveEditId,
                 mode: promptArgs.mode,
                 name: await named(),
@@ -929,12 +1184,19 @@ async function promptNewApplication(ctx, args) {
     }
     const result = {
         applicationId,
+        ...(branch ? { branch } : {}),
         ...(forward.value.checkpointCommitId
             ? { checkpointCommitId: forward.value.checkpointCommitId }
             : {}),
+        ...(forward.value.checkpointFailure
+            ? { checkpointFailure: forward.value.checkpointFailure }
+            : {}),
+        ...(forward.value.checkpointWarning
+            ? { checkpointWarning: forward.value.checkpointWarning }
+            : {}),
         reply: forward.value.reply,
         ...(forward.value.decision ? { decision: forward.value.decision } : {}),
-        editUrl: editUrl(ctx.config, applicationId),
+        editUrl: editUrl(ctx.config, applicationId, branch),
         generationStatus: forward.value.generationStatus,
         liveEditId: forward.value.liveEditId ?? session.liveEditId,
         mode: promptArgs.mode,
@@ -942,30 +1204,117 @@ async function promptNewApplication(ctx, args) {
         ...(forward.value.recentRuns && forward.value.recentRuns.length > 0
             ? { recentRuns: forward.value.recentRuns }
             : {}),
-        status: buildStatusOf(forward.value.generationStatus),
+        ...(forward.value.checkpointFailure
+            ? { pendingAction: "open_editor" }
+            : {}),
+        status: buildStatusOf(forward.value.generationStatus, forward.value.checkpointFailure),
         viewStatus: forward.value.viewStatus,
     };
     ctx.onProgress?.({
         message: turnSummary(forward.value),
         type: "completed",
     });
-    return { kind: "ok", value: await withBrowser(ctx, applicationId, result) };
+    return { kind: "ok", value: await withBrowser(ctx, result) };
+}
+async function runAcknowledgedStart(ctx, args) {
+    const scope = {
+        applicationId: args.applicationId,
+        ...(args.branch ? { branch: args.branch } : {}),
+        organizationId: args.principal.organizationId,
+        userId: args.principal.userId,
+    };
+    const stopLease = ctx.appState.keepPendingStartAlive(scope, args.pendingStartToken);
+    const failed = (error, reason, generationStatus, retryAction, retryable, recoveryAction) => rememberFailedStart(ctx, {
+        applicationId: args.applicationId,
+        branch: args.branch,
+        error,
+        generationStatus,
+        idempotencyKey: args.idempotencyKey,
+        pendingStartRequired: true,
+        pendingStartToken: args.pendingStartToken,
+        principal: args.principal,
+        reason,
+        revision: args.pendingStartToken,
+        ...(recoveryAction ? { recoveryAction } : {}),
+        ...(retryAction ? { retryAction } : {}),
+        ...(retryable === false ? { retryable } : {}),
+    });
+    try {
+        const result = await args.start();
+        if (result.kind === "error" && result.code === "reinvoke_required") {
+            failed(new Error(result.message), `Authentication completed before Superblocks accepted the prompt for application ${args.applicationId}. Call edit_app with that applicationId and the same prompt to continue.`, "live_edit_terminated", "retry_build");
+        }
+        else if (result.kind === "auth_required" ||
+            (result.kind === "error" && result.code === "needs_browser_driver")) {
+            failed(new Error("authentication required"), `Authentication is required before the prompt can continue. Open ${editUrl(ctx.config, args.applicationId, args.branch)} and authenticate, then call edit_app with that applicationId and the same prompt.`, "live_edit_terminated", "retry_build");
+        }
+    }
+    catch (error) {
+        if (error instanceof PromptNotSentError) {
+            const retryable = error.retryable !== false;
+            failed(error, retryable
+                ? `The prompt was not sent, so nothing was built. Call edit_app for application ${args.applicationId} with the same instruction to retry. (${error.message})`
+                : `The replacement live-edit session also stopped responding, so Gateway cannot safely retry this build. Start a new application instead. (${error.message})`, "live_edit_terminated", retryable ? "retry_build" : undefined, error.retryable, error.recoveryAction);
+        }
+        else {
+            failed(error, `The prompt acknowledgement was lost and the prompt may have reached Superblocks. Do not resend it; open ${editUrl(ctx.config, args.applicationId, args.branch)} to check the existing application. (${error instanceof Error ? error.message : String(error)})`, "detached");
+        }
+    }
+    finally {
+        stopLease();
+        ctx.sessionPeer.clearPendingStart({
+            ...scope,
+            idempotencyKey: args.idempotencyKey,
+            pendingStartToken: args.pendingStartToken,
+        });
+    }
 }
 export async function startApp(ctx, input) {
+    const createDeadlineAtMs = nowMs(ctx) +
+        Math.max(1, ctx.config.hostCallCeilingMs - START_APP_RESPONSE_RESERVE_MS);
     const principalResult = await ensurePrincipal(ctx);
     if (principalResult.kind !== "ok") {
         return principalResult;
     }
     const principal = principalResult.value;
+    const branch = normalizeBranch(input.branch);
+    let releaseReplacementClaim;
+    if (input.replacesApplicationId) {
+        const guidance = unavailableReplacementGuidance(input.replacesApplicationId);
+        releaseReplacementClaim = ctx.appState.claimReplacementEntitlement({
+            applicationId: input.replacesApplicationId,
+            organizationId: principal.organizationId,
+            userId: principal.userId,
+        }, guidance);
+        if (!releaseReplacementClaim) {
+            return {
+                applicationId: input.replacesApplicationId,
+                code: "replacement_not_allowed",
+                kind: "error",
+                message: guidance,
+            };
+        }
+    }
     const explicitName = input.name?.trim();
     const name = explicitName || defaultAppName(input.prompt);
+    const attachments = artifactAttachments(input.artifacts);
     ctx.onProgress?.({ message: "Creating application", type: "progress" });
-    const created = await createApplicationForPrompt(ctx, {
-        apiKey: principal.apiKey,
-        name,
-        organizationId: principal.organizationId,
-    });
+    let created;
+    try {
+        created = await createApplicationForPrompt(ctx, {
+            apiKey: principal.apiKey,
+            deadlineAtMs: createDeadlineAtMs,
+            name,
+            organizationId: principal.organizationId,
+            templateName: "app-fullstack",
+        });
+    }
+    catch (error) {
+        releaseReplacementClaim?.();
+        throw error;
+    }
     if (created.kind !== "ok") {
+        releaseReplacementClaim?.();
         return created;
     }
     const app = created.value;
@@ -973,9 +1322,49 @@ export async function startApp(ctx, input) {
     // whether or not the turn ever runs. Waiting for the turn to be accepted left
     // the recent-app default pointing at the previous app, and a caller retrying
     // after a failure drove that one instead of the app it had just created.
-    await rememberApplication(ctx, principal, app.id);
+    await rememberApplication(ctx, principal, app.id, branch);
+    if (input.wait === "ack") {
+        const pendingStartToken = ctx.sessionPeer.recordPendingStart({
+            applicationId: app.id,
+            ...(branch ? { branch } : {}),
+            idempotencyKey: input.idempotencyKey,
+            organizationId: principal.organizationId,
+            retryAction: "retry_build",
+            userId: principal.userId,
+        });
+        const { signal: _requestSignal, ...backgroundContext } = ctx;
+        void runAcknowledgedStart(backgroundContext, {
+            applicationId: app.id,
+            branch,
+            idempotencyKey: input.idempotencyKey,
+            pendingStartToken,
+            principal,
+            start: () => promptNewApplication(backgroundContext, {
+                applicationId: app.id,
+                ...(attachments ? { attachments } : {}),
+                explicitName,
+                input,
+                name,
+                pendingStartToken,
+                principal,
+                prompt: input.prompt,
+            }),
+        });
+        return {
+            kind: "ok",
+            value: await withBrowser(ctx, {
+                applicationId: app.id,
+                ...(branch ? { branch } : {}),
+                editUrl: editUrl(ctx.config, app.id, branch),
+                mode: input.mode ?? "PLAN",
+                name,
+                status: "building",
+            }),
+        };
+    }
     return namingCreatedApplication(app.id, "start_app", await promptNewApplication(ctx, {
         applicationId: app.id,
+        ...(attachments ? { attachments } : {}),
         explicitName,
         input,
         name,
@@ -992,16 +1381,25 @@ async function realPath(candidate) {
         return path.resolve(candidate);
     }
 }
+async function readHostFile(candidate) {
+    const file = await realPath(candidate);
+    try {
+        const info = await stat(file);
+        if (!info.isFile()) {
+            return undefined;
+        }
+        if (info.size > IMPORT_ZIP_MAX_BYTES) {
+            return { oversizeBytes: info.size };
+        }
+        return { bytes: await readFile(file) };
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
- * Reads a candidate path only when it truly sits in one of the configured
- * search directories.
- *
- * The caller is remote and holds nothing but a token, so a path it names must
- * never widen what the gateway will read. Comparison happens after resolving
- * symlinks on both sides: a link planted in a search directory is otherwise
- * enough to walk straight back out of it, and on macOS the directories
- * themselves (`/tmp`) are often links. The resolved path is also what gets
- * read, so re-pointing the link afterwards changes nothing.
+ * Keeps bare-name fallback inside its search directory after resolving
+ * symlinks. Exact absolute paths do not use this fallback boundary.
  */
 async function readWithinSearchDirs(candidate, searchDirs) {
     const file = await realPath(candidate);
@@ -1011,28 +1409,14 @@ async function readWithinSearchDirs(candidate, searchDirs) {
         if (file !== root && !file.startsWith(root + path.sep)) {
             continue;
         }
-        try {
-            const info = await stat(file);
-            if (!info.isFile()) {
-                return undefined;
-            }
-            // Sizing from the file rather than from bytes already read keeps a caller
-            // from spending the gateway's heap on a file it merely named.
-            if (info.size > IMPORT_ZIP_MAX_BYTES) {
-                return { oversizeBytes: info.size };
-            }
-            return { bytes: await readFile(file) };
-        }
-        catch {
-            return undefined;
-        }
+        return readHostFile(file);
     }
     return undefined;
 }
 /**
- * Reads the archive by name from one of the configured search directories.
+ * Reads the file by name from one of the configured search directories.
  *
- * Only the file name of `zipPath` is used. The directory part is thrown away
+ * Only the file name of `filePath` is used. The directory part is thrown away
  * before joining, so neither a sandbox path the model quotes nor a `../` in it
  * can reach a file the operator did not put in one of these folders.
  */
@@ -1045,51 +1429,60 @@ async function readFromSearchDirs(fileName, searchDirs) {
     }
     return undefined;
 }
+function isLikelyModelSandboxPath(filePath) {
+    return (/^\/tmp\/claude-\d+\//.test(filePath) ||
+        filePath.includes("/-home-claude/") ||
+        filePath.startsWith("/mnt/user-data/") ||
+        filePath.startsWith("/root/.claude/uploads/"));
+}
 function tooLargeError(size) {
     return {
         kind: "error",
         code: "import_zip_too_large",
-        message: `Archive is ${size} bytes; the gateway import limit is ${IMPORT_ZIP_MAX_BYTES} bytes (1 MB). Larger archives almost certainly include node_modules or other install artifacts — re-export without those; dependencies are installed on or after import.`,
+        message: `Archive is ${size} bytes; the gateway import limit is ${IMPORT_ZIP_MAX_BYTES} bytes (50 MB), matching Superblocks archive attachments. Larger archives often include node_modules or other install artifacts — re-export without those; dependencies are installed on or after import.`,
     };
 }
 /**
- * Reads the ZIP (or tarball) from a host path or base64 payload and enforces
- * the gateway's 1 MB cap before any Superblocks API call.
+ * Reads the upload from a host path, inline source files, or a base64 payload,
+ * and enforces the gateway's 50 MB cap before any Superblocks API call.
+ *
+ * A path is the only route that carries bytes the model never has to write
+ * out, so it accepts anything attachments support rather than archives alone.
+ * The other two routes are text channels and stay archive-shaped.
  */
 async function resolveImportArchive(input, searchDirs) {
-    const hasPath = Boolean(input.zipPath?.trim());
+    const hasFiles = Boolean(input.files?.length);
+    const hasPath = Boolean(input.filePath?.trim());
     const hasBase64 = Boolean(input.zipBase64?.trim());
-    if (hasPath === hasBase64) {
+    if (Number(hasFiles) + Number(hasPath) + Number(hasBase64) !== 1) {
         return {
             kind: "error",
             code: "import_zip_required",
-            message: "Provide exactly one of zipPath (a path or file name on the gateway host) or zipBase64.",
+            message: "Provide exactly one of files, filePath (a path or file name on the gateway host), or zipBase64.",
         };
     }
-    let bytes;
-    let fileName;
     if (hasPath) {
-        const zipPath = input.zipPath.trim();
-        fileName = path.basename(zipPath);
-        let read;
-        if (path.isAbsolute(zipPath)) {
-            // A path the caller can see is often one this host cannot — a chat
-            // attachment lives in the model's sandbox — and a path this host can see
-            // is only read when it is in a folder the operator opened up.
-            read = await readWithinSearchDirs(zipPath, searchDirs);
-        }
-        read ??= await readFromSearchDirs(fileName, searchDirs);
-        if (read && "oversizeBytes" in read) {
-            return tooLargeError(read.oversizeBytes);
-        }
-        if (!read) {
+        return resolveFileByPath(input.filePath.trim(), searchDirs);
+    }
+    let bytes;
+    if (hasFiles) {
+        const binaryFile = input.files.find((file) => !isTextSourceFileName(file.path));
+        if (binaryFile) {
             return {
                 kind: "error",
-                code: "import_zip_unreadable",
-                message: `No file named "${fileName}" that this gateway will read: "${zipPath}" is not in ${searchDirs.join(" or ")}, and those are the only folders it opens archives from. Ask the user to move the archive into one of them, or to say where it is so the operator can allow that folder. Do not encode the file as base64 — a real archive takes minutes to write out and arrives corrupted.`,
+                code: "import_files_invalid",
+                message: `"${binaryFile.path}" is not a text file, and files entries are archived as the text they contain: base64 in there uploads as base64 characters wearing a "${path.extname(binaryFile.path)}" name. Pass filePath with the file's name instead, so the gateway reads its real bytes.`,
             };
         }
-        bytes = read.bytes;
+        const archive = archiveSourceFiles(input.files);
+        if (archive.kind === "error") {
+            return {
+                kind: "error",
+                code: "import_files_invalid",
+                message: archive.message,
+            };
+        }
+        bytes = archive.bytes;
     }
     else {
         try {
@@ -1109,171 +1502,149 @@ async function resolveImportArchive(input, searchDirs) {
                 message: "zipBase64 decoded to an empty payload.",
             };
         }
-        fileName = "import.zip";
     }
     if (bytes.byteLength > IMPORT_ZIP_MAX_BYTES) {
         return tooLargeError(bytes.byteLength);
     }
-    const archiveType = detectAttachmentArchiveType({ fileName });
-    if (archiveType === null) {
-        return {
-            kind: "error",
-            code: "import_zip_not_archive",
-            message: `Expected a .zip, .tgz, or .gz archive; got "${fileName}".`,
-        };
-    }
     return {
         kind: "ok",
         value: {
             bytes,
-            fileName,
-            mimeType: mimeTypeForArchiveType(archiveType),
+            fileName: "import.zip",
+            mimeType: mimeTypeForArchiveType("zip"),
         },
     };
 }
-function mimeTypeForArchiveType(archiveType) {
-    switch (archiveType) {
-        case "gz":
-        case "tgz":
-            return "application/gzip";
-        case "zip":
-            return "application/zip";
+/** Reads a named file from the search dirs and names the type it uploads as. */
+async function resolveFileByPath(filePath, searchDirs) {
+    let fileName = path.basename(filePath);
+    let read;
+    if (path.isAbsolute(filePath)) {
+        read = await readHostFile(filePath);
+    }
+    read ??= await readFromSearchDirs(fileName, searchDirs);
+    const originalFileName = fileName.replace(/^[0-9a-f]{8}-/i, "");
+    if (!read &&
+        isLikelyModelSandboxPath(filePath) &&
+        originalFileName !== fileName) {
+        read = await readFromSearchDirs(originalFileName, searchDirs);
+        if (read) {
+            fileName = originalFileName;
+        }
     }
-}
-function normalizeImportSource(source) {
-    switch (source) {
-        case "chatgpt":
-        case "claude":
-        case "claude-design":
-        case "lovable":
-        case "replit":
-        case "streamlit":
-        case "v0":
-        case "zip":
-            return source;
-        default:
-            return "zip";
+    if (read && "oversizeBytes" in read) {
+        return tooLargeError(read.oversizeBytes);
     }
-}
-/**
- * Creates a fullstack app, uploads the caller's archive as an app attachment,
- * and hands Clark a migration prompt — the same path as the browser import
- * wizard, without the sessionStorage hop.
- */
-export async function importApp(ctx, input) {
-    const resumedApplicationId = input.applicationId?.trim();
-    const archiveResult = await resolveImportArchive(input, ctx.config.importSearchDirs);
-    if (archiveResult.kind !== "ok") {
-        return resumedApplicationId
-            ? namingApplication(resumedApplicationId, archiveResult)
-            : archiveResult;
+    if (!read) {
+        const sandboxHint = isLikelyModelSandboxPath(filePath) && isTextSourceFileName(fileName)
+            ? " That path appears to be in the model sandbox rather than on this gateway host. If the file was created in chat, pass it through files: [{ path, content }] instead of filePath."
+            : "";
+        return {
+            kind: "error",
+            code: "import_zip_unreadable",
+            message: `The gateway could not read "${filePath}" or find "${fileName}" in its fallback search folders (${searchDirs.join(" or ")}). Check that the host path exists and is readable.${sandboxHint} Do not encode the file as base64 - a real file takes minutes to write out and arrives corrupted.`,
+        };
     }
-    const archive = archiveResult.value;
-    const principalResult = await ensurePrincipal(ctx);
-    if (principalResult.kind !== "ok") {
-        return resumedApplicationId
-            ? namingApplication(resumedApplicationId, principalResult)
-            : principalResult;
+    if (read.bytes.byteLength > IMPORT_ZIP_MAX_BYTES) {
+        return tooLargeError(read.bytes.byteLength);
     }
-    const principal = principalResult.value;
-    const source = normalizeImportSource(input.source);
-    const migrationPrompt = buildImportPrompt({
-        extraPrompt: input.prompt,
-        source,
-        zipFileName: archive.fileName,
-    });
-    const explicitName = input.name?.trim();
-    const name = explicitName || defaultAppName(migrationPrompt);
-    let applicationId = resumedApplicationId;
-    if (!applicationId) {
-        ctx.onProgress?.({
-            message: "Creating application for import",
-            type: "progress",
-        });
-        const created = await createApplicationForPrompt(ctx, {
-            apiKey: principal.apiKey,
-            name,
-            organizationId: principal.organizationId,
-            templateName: "app-fullstack",
-        });
-        if (created.kind !== "ok") {
-            return created;
-        }
-        applicationId = created.value.id;
+    const archiveType = detectAttachmentArchiveType({ fileName });
+    if (archiveType !== null) {
+        return {
+            kind: "ok",
+            value: {
+                bytes: read.bytes,
+                fileName,
+                mimeType: mimeTypeForArchiveType(archiveType),
+            },
+        };
     }
-    await rememberApplication(ctx, principal, applicationId);
-    const result = await migrateArchiveIntoApplication(ctx, {
-        applicationId,
-        archive,
-        explicitName,
-        input,
-        migrationPrompt,
-        name,
-        principal,
-        source,
-    });
-    return resumedApplicationId
-        ? namingApplication(applicationId, result)
-        : namingCreatedApplication(applicationId, "import_app", result);
+    const mimeType = getAttachmentMimeTypeFromFileName(fileName);
+    if (!mimeType || !isSupportedAttachmentUploadType({ fileName, mimeType })) {
+        return {
+            kind: "error",
+            code: "import_file_unsupported",
+            message: `Superblocks attachments cannot carry "${fileName}". Upload an archive (.zip, .tgz, .gz), an image (.png, .jpg, .gif, .webp), a PDF, or a text file such as .log, .csv, .json, or .md.`,
+        };
+    }
+    return { kind: "ok", value: { bytes: read.bytes, fileName, mimeType } };
 }
 /**
- * Uploads the archive onto an application that already exists and hands
- * Superblocks the migration prompt that reads it.
+ * Whether a `files` entry is something a zip built from strings represents
+ * faithfully. Binary content has no text form, so it would be stored as
+ * whatever encoding the model chose rather than as the file itself.
  */
-async function migrateArchiveIntoApplication(ctx, args) {
-    const { applicationId, archive, principal } = args;
+function isTextSourceFileName(sourcePath) {
+    const fileName = path.basename(sourcePath);
+    if (detectAttachmentArchiveType({ fileName }) !== null) {
+        return false;
+    }
+    if (!path.extname(fileName)) {
+        return true;
+    }
+    const mimeType = getAttachmentMimeTypeFromFileName(fileName);
+    // An unknown extension is source code the archive carries as text; a known
+    // non-text type (image, PDF) is the case this rejects.
+    return !mimeType || getTextAttachmentType({ fileName, mimeType }) !== null;
+}
+export async function uploadArtifact(ctx, input) {
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const archiveResult = await resolveImportArchive(input, ctx.config.importSearchDirs);
+    if (archiveResult.kind !== "ok") {
+        return archiveResult;
+    }
+    const archive = archiveResult.value;
+    const uploadDescription = input.files?.length
+        ? `${input.files.length} source file${input.files.length === 1 ? "" : "s"} (${archive.bytes.byteLength}-byte archive)`
+        : `file (${archive.bytes.byteLength} bytes)`;
     ctx.onProgress?.({
-        message: "Uploading archive attachment",
+        message: `Uploading ${uploadDescription}`,
         type: "progress",
     });
-    let upload;
     try {
-        upload = await ctx.server.uploadAttachment({
-            apiKey: principal.apiKey,
-            applicationId,
+        const upload = await ctx.server.uploadAttachment({
+            apiKey: principalResult.value.apiKey,
             bytes: archive.bytes,
             fileName: archive.fileName,
             mimeType: archive.mimeType,
         });
+        const summary = `Uploaded ${uploadDescription}.`;
+        ctx.onProgress?.({
+            message: summary,
+            type: "completed",
+        });
+        return {
+            kind: "ok",
+            value: {
+                artifact: {
+                    fileName: upload.fileName,
+                    id: upload.attachmentId,
+                    mediaType: archive.mimeType,
+                    storageKey: upload.storageKey,
+                },
+                summary,
+            },
+        };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        rememberFailedStart(ctx, {
-            applicationId,
-            error,
-            principal,
-            reason: `The archive for application ${applicationId} could not be uploaded, so the migration never started and nothing was built. Send the same archive again with import_app to retry it. (${message})`,
-            retryAction: "retry_import",
-        });
         return {
             kind: "error",
-            code: "import_upload_failed",
-            message,
-            pendingAction: "retry_import",
+            code: "artifact_upload_failed",
+            message: error instanceof Error ? error.message : String(error),
         };
     }
-    return promptNewApplication(ctx, {
-        applicationId,
-        attachments: [
-            {
-                applicationId,
-                fileName: upload.fileName,
-                mediaType: upload.mimeType ?? archive.mimeType,
-                scopeType: "app",
-                signedUrl: upload.signedUrl,
-                signedUrlExpiresAt: upload.signedUrlExpiresAt,
-                storageKey: upload.storageKey,
-                type: "uploaded",
-                url: upload.contentUrl,
-            },
-        ],
-        explicitName: args.explicitName,
-        importSource: args.source,
-        input: args.input,
-        name: args.name,
-        principal,
-        prompt: args.migrationPrompt,
-    });
+}
+function mimeTypeForArchiveType(archiveType) {
+    switch (archiveType) {
+        case "gz":
+        case "tgz":
+            return "application/gzip";
+        case "zip":
+            return "application/zip";
+    }
 }
 /**
  * Machine-readable shape a cancelled wait answers with.
@@ -1299,63 +1670,177 @@ function nowMs(ctx) {
  * deliberately so: a progress notification is a courtesy the host may ignore,
  * and a call that outlives the host's tool-call ceiling is a hung request
  * whether or not notifications were sent along the way. Every wait in this
- * file is clamped to it, and a call that hits the clamp answers with pacing
- * and a cursor instead of holding the line open.
+ * file is clamped to it, and a call that hits the clamp answers with its
+ * current status instead of holding the line open.
  */
 function hostCallBudgetMs(ctx, requestedMs) {
     return Math.max(0, Math.min(requestedMs, ctx.config.hostCallCeilingMs));
 }
-/** Where a caller's cursor for one application lives. */
-function cursorKeyFor(ctx, principal, applicationId) {
-    if (!ctx.caller || !ctx.progressCursors) {
-        return undefined;
+/**
+ * How long the next turn must collect activity for before it may answer.
+ *
+ * Every turn gets its own floor rather than a share of one. The floor is what
+ * makes a talkative build answer in whole thoughts, so a floor that decayed
+ * across turns would leave the later ones nothing to block on, and the poll
+ * would spin against the peer - re-collecting the same activity - instead of
+ * waiting. Clamped to what is left of the poll so a turn is never asked to
+ * wait past the deadline it is measured against.
+ */
+function turnFloorMs(ctx, remainingWaitMs) {
+    return Math.max(0, Math.min(ctx.config.clarkProgressFloorMs, remainingWaitMs));
+}
+/**
+ * Whether this poll may wait out another turn, and what ended it if not.
+ *
+ * The deadlines are reported apart because they fail for different reasons:
+ * the host ceiling means the call itself ran out of room, while the poll
+ * budget means only this poll did and the caller may simply ask again.
+ */
+function pollStop(ctx, input) {
+    if (ctx.signal?.aborted) {
+        return "cancelled";
+    }
+    // The gateway lost the turn record mid-poll - a dropped socket, a superseded
+    // turn - rather than the turn having ended: this same poll already watched it
+    // run. Named apart from `turn_terminal` because the poll answers with what it
+    // saw rather than with "nothing is running", and because a wait that finds no
+    // turn returns at once, so another one would spin rather than wait.
+    if (input.status === "unknown" && input.sawRunningTurn) {
+        return "turn_record_lost";
+    }
+    if (input.status !== "building") {
+        return "turn_terminal";
+    }
+    const currentMs = nowMs(ctx);
+    if (currentMs >= input.hostDeadlineAtMs) {
+        return "host_deadline_reached";
+    }
+    if (currentMs >= input.deadlineAtMs) {
+        return "poll_budget_spent";
+    }
+    // A gateway configured with no floor answers on the first line, so another
+    // turn would return without having waited for anything.
+    return turnFloorMs(ctx, input.deadlineAtMs - currentMs) === 0
+        ? "floor_spent"
+        : undefined;
+}
+/**
+ * What a turn update says about the build, for {@link gatewayDebug}.
+ *
+ * Carries no line Superblocks wrote: a trace of a build is a diagnostic, and
+ * the reply and activity text belong to the user who prompted it. Counting
+ * the activity lines answers the question a trace is read for - whether this
+ * turn said anything at all - without repeating what was said.
+ */
+function turnTrace(update) {
+    const observed = {
+        "turn.activity_line_count": update.activity.length,
+        "turn.elapsed_ms": update.elapsedMs,
+        ...(update.branch ? { "turn.reported_branch": update.branch } : {}),
+        "turn.status": update.status,
+        ...(update.viewStatus ? { "turn.view_status": update.viewStatus } : {}),
+    };
+    if (update.status !== "finished") {
+        return observed;
     }
     return {
-        applicationId,
-        caller: ctx.caller,
-        organizationId: principal.organizationId,
+        ...observed,
+        "turn.checkpoint_failed": Boolean(update.checkpointFailure),
+        ...(update.decision ? { "turn.decision_kind": update.decision.kind } : {}),
+        "turn.generation_status": update.generationStatus,
     };
 }
 /**
- * Reads the durable stream for this caller without consuming it.
+ * The last running update this poll saw, with `elapsedMs` advanced to now.
  *
- * Returns nothing when resume is not wired (no store, or no live edit known
- * for this application yet), which is what keeps one-shot callers and tests
- * of the live path on exactly the behavior they had.
+ * Used when the turn record goes missing mid-poll. Nothing new was heard, so
+ * the update is reused as-is, but the turn has kept running since it was
+ * observed. Advancing `elapsedMs` keeps {@link recordTurnSignals} measuring the
+ * turn's real age instead of resetting its stall hint.
  */
-async function readSnapshot(ctx, input) {
-    const store = ctx.events;
-    if (!store || !ctx.progressCursors) {
-        return undefined;
-    }
-    const liveEditId = await ctx.progressCursors.getLiveEditId({
-        applicationId: input.applicationId,
-        organizationId: input.organizationId,
-    });
-    if (!liveEditId) {
-        return undefined;
-    }
+function carriedForward(ctx, running) {
+    return {
+        ...running.update,
+        elapsedMs: running.update.elapsedMs + Math.max(0, nowMs(ctx) - running.observedAtMs),
+    };
+}
+/**
+ * Collects turn updates until the build becomes terminal or this host call
+ * reaches its deadline. Each wait receives only the remaining floor and
+ * ceiling, so an activity wake-up cannot restart either budget.
+ */
+async function awaitTurns(ctx, requestedBranch, principal, applicationId, hostDeadlineAtMs) {
+    const startedAtMs = nowMs(ctx);
+    const deadlineAtMs = Math.min(hostDeadlineAtMs, startedAtMs + Math.max(0, ctx.config.clarkProgressWaitMs));
+    const waitBudgetMs = Math.max(0, deadlineAtMs - startedAtMs);
+    const activity = [];
     const scope = {
-        applicationId: input.applicationId,
-        liveEditId,
-        organizationId: input.organizationId,
+        "application.id": applicationId,
+        ...(requestedBranch ? { "turn.requested_branch": requestedBranch } : {}),
     };
-    // A cursor a caller handed back gets the same validation a stored one does.
-    // Anything unreadable falls back to that caller's own stored position: a
-    // position this contract cannot vouch for would otherwise skip the caller
-    // past unread events, and a corrupt one compares false against every
-    // sequence and hides the whole stream for as long as the caller keeps
-    // handing it back.
-    const supplied = input.overrideCursor === undefined
-        ? undefined
-        : parseEventCursor(input.overrideCursor);
-    return await store.snapshot({
+    gatewayDebug("progress poll started", {
         ...scope,
-        cursor: supplied ?? input.cursor?.cursor,
-        ...(input.limit === undefined ? {} : { limit: input.limit }),
+        "poll.host_budget_ms": Math.max(0, hostDeadlineAtMs - startedAtMs),
+        "poll.turn_floor_ms": turnFloorMs(ctx, waitBudgetMs),
+        "poll.wait_budget_ms": waitBudgetMs,
     });
+    let running;
+    let turnCount = 0;
+    while (true) {
+        const remainingWaitMs = Math.max(0, deadlineAtMs - nowMs(ctx));
+        const update = await ctx.sessionPeer.awaitTurn({
+            applicationId,
+            branch: requestedBranch,
+            organizationId: principal.organizationId,
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+            userId: principal.userId,
+            floorMs: turnFloorMs(ctx, remainingWaitMs),
+            waitMs: remainingWaitMs,
+        });
+        turnCount += 1;
+        activity.push(...update.activity);
+        if (update.status === "running") {
+            running = { observedAtMs: nowMs(ctx), update };
+        }
+        const status = progressStatusOf(update);
+        gatewayDebug("progress poll turn observed", {
+            ...scope,
+            ...turnTrace(update),
+            "build.status": status,
+            "poll.turn": turnCount,
+            "poll.wait_remaining_ms": Math.max(0, deadlineAtMs - nowMs(ctx)),
+        });
+        const stop = pollStop(ctx, {
+            deadlineAtMs,
+            hostDeadlineAtMs,
+            sawRunningTurn: running !== undefined,
+            status,
+        });
+        if (!stop) {
+            continue;
+        }
+        // What the poll answers with, which is not always the last wait's update.
+        const answer = stop === "turn_record_lost" && running
+            ? carriedForward(ctx, running)
+            : update;
+        gatewayDebug("progress poll finished", {
+            ...scope,
+            "build.status": progressStatusOf(answer),
+            "poll.elapsed_ms": nowMs(ctx) - startedAtMs,
+            "poll.stopped_because": stop,
+            "poll.turn_count": turnCount,
+        });
+        if (stop === "cancelled") {
+            return namingApplication(applicationId, cancelled("check_app_progress"));
+        }
+        return {
+            kind: "ok",
+            value: { ...answer, activity },
+        };
+    }
 }
 export async function checkAppProgress(ctx, input) {
+    const hostDeadlineAtMs = nowMs(ctx) + Math.max(0, ctx.config.hostCallCeilingMs);
     const principalResult = await ensurePrincipal(ctx);
     if (principalResult.kind !== "ok") {
         return principalResult;
@@ -1366,131 +1851,62 @@ export async function checkAppProgress(ctx, input) {
         return resolved;
     }
     const applicationId = resolved.value;
+    const requestedBranch = normalizeBranch(input.branch);
     // Checked before the wait as well as after it. A caller that cancelled
     // while the credential was being resolved should never reach the point of
     // registering a waiter it will not read.
     if (ctx.signal?.aborted) {
         return namingApplication(applicationId, cancelled("check_app_progress"));
     }
-    const cursorKey = cursorKeyFor(ctx, principal, applicationId);
-    const stored = cursorKey
-        ? await ctx.progressCursors?.getCursor(cursorKey)
-        : undefined;
-    const update = await ctx.sessionPeer.awaitTurn({
-        applicationId,
-        organizationId: principal.organizationId,
-        ...(ctx.signal ? { signal: ctx.signal } : {}),
-        userId: principal.userId,
-        waitMs: hostCallBudgetMs(ctx, ctx.config.clarkProgressWaitMs),
-    });
-    if (ctx.signal?.aborted) {
-        return namingApplication(applicationId, cancelled("check_app_progress"));
+    const updateResult = await awaitTurns(ctx, requestedBranch, principal, applicationId, hostDeadlineAtMs);
+    if (updateResult.kind !== "ok") {
+        return updateResult;
     }
-    const snapshot = await readSnapshot(ctx, {
-        applicationId,
-        cursor: stored,
-        organizationId: principal.organizationId,
-        ...(input.cursor ? { overrideCursor: input.cursor } : {}),
-    });
-    // The local turn is an accelerator, not the record. When this process is
-    // not holding the turn (restart, another replica), the persisted stream is
-    // all there is. When it is holding a still-running turn, Redis may still
-    // carry durable progress from another path that the local collector missed
-    // — merge that activity so a quiet local turn does not look hung.
-    const streamProgress = snapshot
-        ? readPersistedProgress(snapshot, streamLiveness(ctx), ctx.config.clarkSettleMs)
-        : undefined;
-    const resumeFromStream = update.status === "unknown" ? streamProgress : undefined;
+    const update = updateResult.value;
     const elapsedSeconds = Math.round(update.elapsedMs / 1000);
-    const liveActivity = update.status === "running" && update.activity.length === 0
-        ? []
+    const saidSomething = update.activity.length > 0;
+    const activity = update.status === "running" && !saidSomething
+        ? [`Superblocks is still generating`]
         : update.activity;
-    const mergedWhileRunning = update.status === "running" && streamProgress
-        ? mergeActivity(liveActivity, streamProgress.activity)
-        : undefined;
-    const activity = resumeFromStream
-        ? resumeFromStream.activity
-        : mergedWhileRunning && mergedWhileRunning.length > 0
-            ? mergedWhileRunning
-            : update.status === "running" && update.activity.length === 0
-                ? [`Superblocks is still generating (${elapsedSeconds}s)`]
-                : liveActivity;
-    // Live lines were already shown on earlier polls for this turn. When Redis
-    // actually contributed durable lines, only stream those that are new relative
-    // to live so the same progress is not re-emitted. An empty/lagging store must
-    // still notify the live activity — otherwise a quiet Redis snapshot silences
-    // the turn.
-    const progressMessages = mergedWhileRunning !== undefined &&
-        (streamProgress?.activity.length ?? 0) > 0
-        ? mergedWhileRunning.filter((line) => !liveActivity.includes(line))
-        : activity;
-    for (const message of progressMessages) {
+    for (const message of activity) {
         ctx.onProgress?.({ message, type: "progress" });
     }
-    const status = resumeFromStream
-        ? resumeFromStream.status
-        : update.status === "finished"
-            ? buildStatusOf(update.generationStatus)
-            : update.status === "running"
-                ? "building"
-                : "unknown";
+    const status = progressStatusOf(update);
     const terminal = status !== "building";
-    const pacing = await recordPacing(ctx, {
-        applicationId,
+    const turnSignals = await recordTurnSignals(ctx, {
         appScope: { applicationId, organizationId: principal.organizationId },
-        cursorKey,
         elapsedMs: update.elapsedMs,
-        // Only advance the Redis cursor when this poll actually answered from
-        // persisted events. Advancing while answering from the live socket alone
-        // skips unread durable events after a restart.
-        advanceCursor: resumeFromStream !== undefined ||
-            (update.status === "running" &&
-                (streamProgress?.activity.length ?? 0) > 0),
         // What Superblocks itself said, not what this poll is returning. The
-        // heartbeat below is the gateway's own words, added so a quiet poll has
+        // heartbeat above is the gateway's own words, added so a quiet poll has
         // something to show; counting it as news would mean a build can never be
         // detected as quiet, because every quiet poll manufactures a line.
-        saidSomething: resumeFromStream
-            ? resumeFromStream.activity.length > 0
-            : update.activity.length > 0 ||
-                (mergedWhileRunning !== undefined && mergedWhileRunning.length > 0),
-        snapshot,
-        stored,
+        saidSomething,
         terminal,
-        // Only the local turn carries a clock. A build read out of the persisted
-        // stream is running somewhere else and this process cannot say how long
-        // for, so it reports no budget rather than inventing a full one.
-        turnRunning: update.status === "running",
     });
+    const branch = update.branch ?? requestedBranch;
     const base = {
-        ...pacing.pacing,
+        ...turnSignals,
         activity,
         applicationId,
-        editUrl: editUrl(ctx.config, applicationId),
+        ...(branch ? { branch } : {}),
+        editUrl: editUrl(ctx.config, applicationId, branch),
         elapsedSeconds,
-        ...(pacing.stallHint ? { stallHint: pacing.stallHint } : {}),
+        ...(update.viewStatus ? { viewStatus: update.viewStatus } : {}),
         ...("recentRuns" in update &&
             Array.isArray(update.recentRuns) &&
             update.recentRuns.length > 0
             ? { recentRuns: update.recentRuns }
             : {}),
     };
-    if (resumeFromStream) {
+    if (update.status !== "finished") {
         return {
             kind: "ok",
             value: {
                 ...base,
-                ...(resumeFromStream.generationStatus
-                    ? { generationStatus: resumeFromStream.generationStatus }
-                    : {}),
-                ...(resumeFromStream.reply ? { reply: resumeFromStream.reply } : {}),
                 status,
             },
         };
     }
-    if (update.status !== "finished") {
-        return { kind: "ok", value: { ...base, status } };
-    }
     ctx.onProgress?.({ message: turnSummary(update), type: "completed" });
     return {
         kind: "ok",
@@ -1499,12 +1915,27 @@ export async function checkAppProgress(ctx, input) {
             ...(update.checkpointCommitId
                 ? { checkpointCommitId: update.checkpointCommitId }
                 : {}),
+            ...(update.checkpointFailure
+                ? { checkpointFailure: update.checkpointFailure }
+                : {}),
+            ...(update.checkpointWarning
+                ? { checkpointWarning: update.checkpointWarning }
+                : {}),
             reply: update.reply,
             ...(update.decision ? { decision: update.decision } : {}),
             generationStatus: update.generationStatus,
-            ...(update.retryAction && emptyTurnStatus(update.generationStatus)
-                ? { pendingAction: update.retryAction }
-                : {}),
+            ...(update.checkpointFailure
+                ? { pendingAction: "open_editor" }
+                : status === "needs_decision"
+                    ? { pendingAction: pendingActionForDecision(update.decision) }
+                    : update.retryAction && emptyTurnStatus(update.generationStatus)
+                        ? { pendingAction: update.retryAction }
+                        : update.retryable === false &&
+                            emptyTurnStatus(update.generationStatus)
+                            ? update.recoveryAction
+                                ? { pendingAction: update.recoveryAction }
+                                : {}
+                            : {}),
             status,
             viewStatus: update.viewStatus,
         },
@@ -1524,7 +1955,7 @@ export async function checkAppProgress(ctx, input) {
  */
 async function lastActivityWithinTurn(ctx, input) {
     try {
-        const observedAtMs = await ctx.progressCursors?.getLastActivityAtMs(input.appScope);
+        const observedAtMs = ctx.progress?.lastActivityAtMs(input.appScope);
         return Math.max(observedAtMs ?? input.turnStartedAtMs, input.turnStartedAtMs);
     }
     catch (error) {
@@ -1544,7 +1975,7 @@ async function lastActivityWithinTurn(ctx, input) {
  */
 async function rememberLastActivity(ctx, input) {
     try {
-        await ctx.progressCursors?.setLastActivityAtMs(input);
+        ctx.progress?.recordActivity(input);
     }
     catch (error) {
         console.warn("gateway could not record when the build last spoke", {
@@ -1552,16 +1983,8 @@ async function rememberLastActivity(ctx, input) {
         });
     }
 }
-/**
- * Works out what to tell the caller about coming back, and persists its new
- * position.
- *
- * The cursor is written only here, and only after the response it describes
- * has been assembled: advancing it earlier would lose events for a call that
- * then failed. It advances only this caller's key, so a second reader of the
- * same build is unaffected.
- */
-async function recordPacing(ctx, input) {
+/** Records what this poll heard and derives a nonterminal stall hint. */
+async function recordTurnSignals(ctx, input) {
     const quiet = !input.saidSomething && !input.terminal;
     const currentTimeMs = nowMs(ctx);
     const turnStartedAtMs = currentTimeMs - input.elapsedMs;
@@ -1572,124 +1995,70 @@ async function recordPacing(ctx, input) {
             turnStartedAtMs,
         });
     const quietMs = Math.max(0, currentTimeMs - lastActivityAtMs);
-    const alreadyHinted = input.stored?.stallHintedAtMs !== undefined;
+    const alreadyHinted = ctx.progress?.stallHintedAtMs(input.appScope) !== undefined;
     const stallHint = quiet && !alreadyHinted && quietMs >= ctx.config.clarkStallHintAfterMs
         ? { quietMs, reason: "long_quiet" }
         : undefined;
-    // Only what this poll actually heard, and whether or not this caller has a
-    // cursor, so a reader that never had one still measures silence from when
-    // the build last spoke. A quiet poll writing its own read back would clobber
-    // activity a concurrent reader heard between that read and this write.
     if (input.saidSomething) {
         await rememberLastActivity(ctx, {
             ...input.appScope,
             atMs: currentTimeMs,
         });
     }
-    if (input.cursorKey && ctx.progressCursors) {
-        const advanceCursor = input.advanceCursor !== false;
-        const cursor = advanceCursor
-            ? (input.snapshot?.cursor ?? input.stored?.cursor ?? EMPTY_EVENT_CURSOR)
-            : (input.stored?.cursor ?? EMPTY_EVENT_CURSOR);
-        // Hearing anything closes the quiet spell, so the next silence gets its
-        // own hint rather than being suppressed by the previous one.
-        const hintedAtMs = stallHint
-            ? currentTimeMs
-            : quiet
-                ? input.stored?.stallHintedAtMs
-                : undefined;
-        await ctx.progressCursors.setCursor({
-            ...input.cursorKey,
-            record: {
-                cursor,
-                ...(hintedAtMs === undefined ? {} : { stallHintedAtMs: hintedAtMs }),
-            },
+    // Hearing anything closes the quiet spell, so the next silence gets its own
+    // hint rather than being suppressed by the previous one.
+    if (stallHint) {
+        ctx.progress?.recordStallHint({
+            ...input.appScope,
+            atMs: currentTimeMs,
         });
     }
-    return {
-        pacing: {
-            ...(input.snapshot && input.advanceCursor !== false
-                ? { cursor: input.snapshot.cursor }
-                : input.stored
-                    ? { cursor: input.stored.cursor }
-                    : {}),
-            nextPollAfterMs: input.terminal
-                ? 0
-                : nextPollAfterMs(ctx, input.applicationId),
-            ...(input.turnRunning
-                ? {
-                    remainingTurnBudgetMs: Math.max(0, ctx.config.clarkTurnTimeoutMs - input.elapsedMs),
-                }
-                : {}),
-            ...(input.snapshot && input.snapshot.lost.length > 0
-                ? { staleStreams: input.snapshot.lost }
-                : {}),
-        },
-        ...(stallHint ? { stallHint } : {}),
-    };
-}
-/**
- * Pacing for a caller that is being handed a starting point rather than a
- * batch of activity.
- *
- * Reads the caller's stored cursor and hands it straight back without
- * advancing it. `get_app` reports no activity, so moving the cursor here would
- * mark events as read that nobody has read — the caller's next
- * `check_app_progress` would silently skip them.
- *
- * Carries no `remainingTurnBudgetMs`. `get_app` is not the tool that follows a
- * turn and never has the turn's own clock, so any number it put there would be
- * the full budget regardless of how long the turn had been running - or
- * regardless of whether one was running at all, which is what it used to send
- * alongside a preview build (ENG-5808). `check_app_progress` is where a caller
- * following a turn reads what is left of it.
- */
-async function buildPacing(ctx, input) {
-    const stored = ctx.caller
-        ? await ctx.progressCursors?.getCursor({
-            applicationId: input.applicationId,
-            caller: ctx.caller,
-            organizationId: input.organizationId,
-        })
-        : undefined;
-    return {
-        cursor: stored?.cursor ?? EMPTY_EVENT_CURSOR,
-        nextPollAfterMs: input.terminal
-            ? 0
-            : nextPollAfterMs(ctx, input.applicationId),
-    };
-}
-/**
- * How soon the caller should poll again. Once the app is building it runs for
- * minutes, so pace at clarkBuildPollAfterMs (~30s) to stay inside a host's
- * tool-call budget; while it is still planning, keep the shorter progress wait
- * so a plan or question surfaces quickly.
- */
-function nextPollAfterMs(ctx, applicationId) {
-    const cadenceMs = ctx.sessionPeer.buildMode?.(applicationId)
-        ? ctx.config.clarkBuildPollAfterMs
-        : ctx.config.clarkProgressWaitMs;
-    return hostCallBudgetMs(ctx, cadenceMs);
+    else if (!quiet) {
+        ctx.progress?.recordStallHint({
+            ...input.appScope,
+            atMs: undefined,
+        });
+    }
+    return stallHint ? { stallHint } : {};
 }
-export async function editApp(ctx, input) {
+export async function editApp(ctx, input, approvedPlan) {
     const principalResult = await ensurePrincipal(ctx);
     if (principalResult.kind !== "ok") {
         return principalResult;
     }
     const principal = principalResult.value;
-    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId, { unambiguous: true });
     if (resolved.kind !== "ok") {
         return resolved;
     }
     const applicationId = resolved.value;
-    return namingApplication(applicationId, await promptExistingApplication(ctx, { applicationId, input, principal }));
+    return namingApplication(applicationId, await promptExistingApplication(ctx, {
+        applicationId,
+        approvedPlan,
+        input,
+        principal,
+    }));
+}
+function stalePlanApproval(applicationId) {
+    return {
+        applicationId,
+        kind: "error",
+        code: "plan_approval_stale",
+        message: "The plan changed after it was approved. Show the current plan to the user before building it.",
+    };
+}
+function planApprovalChanged(approvedPlan, pendingPlan) {
+    return approvedPlan !== undefined && pendingPlan !== approvedPlan;
 }
 async function promptExistingApplication(ctx, args) {
-    const { applicationId, input, principal } = args;
+    const { applicationId, approvedPlan, input, principal } = args;
+    const branch = currentTurnBranch(ctx, principal, applicationId, input.branch);
+    const answeringQuestion = pendingQuestion(ctx, applicationId, branch);
     // Approve reuses the pending plan as the prompt. Every other path needs the
-    // caller's words — an empty or missing prompt would otherwise forward
-    // undefined into Clark.
-    if (input.planAction !== "approve" &&
+    // caller's words - an empty or missing prompt would otherwise forward
+    // undefined into Clark. Answering a question is not a plan approval, even if
+    // the caller sent planAction "approve".
+    if ((input.planAction !== "approve" || answeringQuestion) &&
         !(typeof input.prompt === "string" && input.prompt.trim().length > 0)) {
         return {
             kind: "error",
@@ -1697,43 +2066,158 @@ async function promptExistingApplication(ctx, args) {
             message: 'edit_app needs a prompt, unless planAction is "approve" (Build it) for a pending plan.',
         };
     }
+    const pendingBeforeOpen = ctx.appState.pendingPlan(applicationId, branch);
+    if (planApprovalChanged(approvedPlan, pendingBeforeOpen)) {
+        return stalePlanApproval(applicationId);
+    }
+    const approvingUncapturedPlan = args.approvingUncapturedPlan === true ||
+        (input.planAction === "approve" &&
+            !pendingBeforeOpen &&
+            !answeringQuestion &&
+            awaitingDecision(ctx, {
+                applicationId,
+                branch,
+                organizationId: principal.organizationId,
+                userId: principal.userId,
+            }));
+    if (input.planAction === "approve" &&
+        !pendingBeforeOpen &&
+        !approvingUncapturedPlan &&
+        !answeringQuestion) {
+        return {
+            kind: "error",
+            code: "plan_required",
+            message: "No pending Superblocks plan to approve for this application. Start or edit in Plan mode first, then approve after needs_decision.",
+        };
+    }
+    if (input.wait === "ack" && args.pendingStartToken === undefined) {
+        const mode = editTurnMode(input, answeringQuestion);
+        const pendingStartToken = ctx.sessionPeer.recordPendingStart({
+            applicationId,
+            ...(branch ? { branch } : {}),
+            idempotencyKey: input.idempotencyKey,
+            organizationId: principal.organizationId,
+            retryAction: "retry_build",
+            userId: principal.userId,
+        });
+        const { signal: _requestSignal, ...backgroundContext } = ctx;
+        void runAcknowledgedStart(backgroundContext, {
+            applicationId,
+            branch,
+            idempotencyKey: input.idempotencyKey,
+            pendingStartToken,
+            principal,
+            start: () => promptExistingApplication(backgroundContext, {
+                ...args,
+                ...(approvingUncapturedPlan ? { approvingUncapturedPlan } : {}),
+                input: { ...input, ...(branch ? { branch } : {}) },
+                pendingStartToken,
+            }),
+        });
+        if (planApprovalChanged(approvedPlan, ctx.appState.pendingPlan(applicationId, branch))) {
+            return stalePlanApproval(applicationId);
+        }
+        rememberApplication(ctx, principal, applicationId, branch);
+        return {
+            kind: "ok",
+            value: await withBrowser(ctx, {
+                applicationId,
+                ...(branch ? { branch } : {}),
+                editUrl: editUrl(ctx.config, applicationId, branch),
+                mode,
+                status: "building",
+            }),
+        };
+    }
+    const revision = args.pendingStartToken ?? ctx.appState.markTurnStarted();
     ctx.onProgress?.({ message: "Ensuring live-edit session", type: "progress" });
     let session;
     try {
         session = await openLiveEdit(ctx, {
             apiKey: principal.apiKey,
             applicationId,
-            branch: input.branch,
+            branch,
             organizationId: principal.organizationId,
         });
     }
     catch (error) {
-        rememberFailedStart(ctx, { applicationId, error, principal });
+        const pendingDecision = ctx.appState.pendingDecision(applicationId, branch);
+        rememberFailedStart(ctx, {
+            applicationId,
+            branch,
+            error,
+            ...(pendingDecision ? { decision: pendingDecision.decision } : {}),
+            ...(pendingDecision || approvingUncapturedPlan
+                ? { generationStatus: "needs_decision" }
+                : {}),
+            idempotencyKey: input.idempotencyKey,
+            ...(args.pendingStartToken === undefined || refusedCaller(error)
+                ? {}
+                : {
+                    pendingStartRequired: true,
+                    pendingStartToken: args.pendingStartToken,
+                }),
+            principal,
+            revision,
+            retryAction: "retry_build",
+        });
         return liveEditUnavailable(error);
     }
     ctx.onProgress?.({
         message: "Forwarding prompt to Superblocks",
         type: "progress",
     });
-    const pending = ctx.sessionPeer.pendingPlan?.(applicationId);
+    const pending = ctx.appState.pendingPlan(applicationId, branch);
+    if (planApprovalChanged(approvedPlan, pending)) {
+        const stale = stalePlanApproval(applicationId);
+        if (args.pendingStartToken !== undefined) {
+            const currentDecision = ctx.appState.pendingDecision(applicationId, branch);
+            rememberFailedStart(ctx, {
+                applicationId,
+                branch,
+                ...(currentDecision ? { decision: currentDecision.decision } : {}),
+                error: new Error(stale.message),
+                generationStatus: "needs_decision",
+                idempotencyKey: input.idempotencyKey,
+                pendingStartRequired: true,
+                pendingStartToken: args.pendingStartToken,
+                principal,
+                reason: stale.message,
+                revision,
+            });
+        }
+        return stale;
+    }
     // Approve / refine a pending plan the way the editor's "Build it" / chat
-    // refine path does. A bare prompt while a plan is pending is refine feedback.
-    const effectiveAction = input.planAction ?? (pending ? "refine" : undefined);
-    // Clark's headless default is PLAN, so a follow-up prompt after a BUILD turn
-    // used to propose a plan instead of continuing the build. Preserve BUILD
-    // until the caller explicitly asks to plan, regardless of how BUILD began.
-    const defaultMode = ctx.sessionPeer.buildMode?.(applicationId)
-        ? "BUILD"
-        : "PLAN";
+    // refine path does. A bare prompt while a plan is pending is refine
+    // feedback, unless the caller passed BUILD to skip that plan.
+    const effectiveAction = answeringQuestion
+        ? undefined
+        : (input.planAction ??
+            (pending && input.mode !== "BUILD" ? "refine" : undefined));
+    const attachments = artifactAttachments(input.artifacts);
+    // Every edit starts in Plan mode, exactly like start_app:
+    // writing code is something the caller opts into with mode "BUILD", never a
+    // mode the app latched onto from an earlier build. Approving a pending plan
+    // still forces BUILD below, which is what carries a plan into code.
+    // Answering a question stays in Plan even if the caller passed BUILD.
     let promptArgs = {
         applicationId,
-        branch: input.branch,
+        ...(attachments ? { attachments } : {}),
+        branch,
         idempotencyKey: input.idempotencyKey,
         liveEditId: session.liveEditId,
         liveEditUrl: session.liveEditUrl,
-        mode: input.mode ?? defaultMode,
+        mode: editTurnMode(input, answeringQuestion),
         organizationId: principal.organizationId,
-        prompt: input.prompt ?? "",
+        ...(args.pendingStartToken === undefined
+            ? {}
+            : {
+                pendingStartRequired: true,
+                pendingStartToken: args.pendingStartToken,
+            }),
+        prompt: promptForAttachedSource(input.prompt ?? "", attachments),
+        revision,
         userId: principal.userId,
     };
     if (effectiveAction === "approve") {
@@ -1747,20 +2231,27 @@ async function promptExistingApplication(ctx, args) {
                     ...(pending.title ? { title: pending.title } : {}),
                 },
                 prompt: pending.plan,
-                responseMetadata: {
-                    approved: true,
-                    ...(pending.messageId
-                        ? { responseToMessageId: pending.messageId }
-                        : {}),
-                    type: "plan_response",
-                },
+                // Only when there is a card to answer: `responseToMessageId` is what
+                // the ai-service resolves the plan by, so a `plan_response` without
+                // one answers nothing.
+                ...(pending.messageId
+                    ? {
+                        responseMetadata: {
+                            approved: true,
+                            responseToMessageId: pending.messageId,
+                            type: "plan_response",
+                        },
+                    }
+                    : {}),
             };
         }
-        else if (awaitingDecision(ctx, {
-            applicationId,
-            organizationId: principal.organizationId,
-            userId: principal.userId,
-        })) {
+        else if (approvingUncapturedPlan ||
+            awaitingDecision(ctx, {
+                applicationId,
+                branch,
+                organizationId: principal.organizationId,
+                userId: principal.userId,
+            })) {
             // Clark is waiting on the user but streamed its plan as chat text, so no
             // plan card was captured. "Build it" still means build: forward a build
             // turn the way the editor's Build-it does. Clark still holds the plan in
@@ -1771,7 +2262,9 @@ async function promptExistingApplication(ctx, args) {
                 planContext: { approved: true },
                 prompt: input.prompt?.trim() ||
                     "The plan is approved. Build it as described.",
-                responseMetadata: { approved: true, type: "plan_response" },
+                // No `responseMetadata`: there is no plan card to answer. The approval
+                // travels in `planContext`, which is what the ai-service reads to gate
+                // its write tools.
             };
         }
         else {
@@ -1791,13 +2284,15 @@ async function promptExistingApplication(ctx, args) {
                 plan: pending.plan,
                 ...(pending.title ? { title: pending.title } : {}),
             },
-            responseMetadata: {
-                approved: false,
-                ...(pending.messageId
-                    ? { responseToMessageId: pending.messageId }
-                    : {}),
-                type: "plan_response",
-            },
+            ...(pending.messageId
+                ? {
+                    responseMetadata: {
+                        approved: false,
+                        responseToMessageId: pending.messageId,
+                        type: "plan_response",
+                    },
+                }
+                : {}),
         };
     }
     if (input.wait === "ack") {
@@ -1805,13 +2300,14 @@ async function promptExistingApplication(ctx, args) {
         if (started.kind !== "ok") {
             return started;
         }
-        await rememberApplication(ctx, principal, applicationId);
+        await rememberApplication(ctx, principal, applicationId, branch);
         return {
             kind: "ok",
-            value: await withBrowser(ctx, applicationId, {
+            value: await withBrowser(ctx, {
                 activity: started.value.activity,
                 applicationId,
-                editUrl: editUrl(ctx.config, applicationId),
+                ...(branch ? { branch } : {}),
+                editUrl: editUrl(ctx.config, applicationId, branch),
                 mode: promptArgs.mode,
                 status: "building",
             }),
@@ -1821,21 +2317,31 @@ async function promptExistingApplication(ctx, args) {
     if (forward.kind !== "ok") {
         return forward;
     }
-    await rememberApplication(ctx, principal, applicationId);
+    await rememberApplication(ctx, principal, applicationId, branch);
     const result = {
         applicationId,
+        ...(branch ? { branch } : {}),
         ...(forward.value.checkpointCommitId
             ? { checkpointCommitId: forward.value.checkpointCommitId }
             : {}),
+        ...(forward.value.checkpointFailure
+            ? { checkpointFailure: forward.value.checkpointFailure }
+            : {}),
+        ...(forward.value.checkpointWarning
+            ? { checkpointWarning: forward.value.checkpointWarning }
+            : {}),
         reply: forward.value.reply,
         ...(forward.value.decision ? { decision: forward.value.decision } : {}),
-        editUrl: editUrl(ctx.config, applicationId),
+        editUrl: editUrl(ctx.config, applicationId, branch),
         generationStatus: forward.value.generationStatus,
         mode: promptArgs.mode,
         ...(forward.value.recentRuns && forward.value.recentRuns.length > 0
             ? { recentRuns: forward.value.recentRuns }
             : {}),
-        status: buildStatusOf(forward.value.generationStatus),
+        ...(forward.value.checkpointFailure
+            ? { pendingAction: "open_editor" }
+            : {}),
+        status: buildStatusOf(forward.value.generationStatus, forward.value.checkpointFailure),
         viewStatus: forward.value.viewStatus,
     };
     ctx.onProgress?.({
@@ -1844,7 +2350,7 @@ async function promptExistingApplication(ctx, args) {
     });
     return {
         kind: "ok",
-        value: await withBrowser(ctx, applicationId, result),
+        value: await withBrowser(ctx, result),
     };
 }
 /**
@@ -1864,7 +2370,7 @@ export async function previewApp(ctx, input) {
         return principalResult;
     }
     const principal = principalResult.value;
-    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId, { unambiguous: true });
     if (resolved.kind !== "ok") {
         return resolved;
     }
@@ -1885,7 +2391,7 @@ export async function previewApp(ctx, input) {
     catch (error) {
         if (error instanceof ServerHttpError &&
             (error.status === 401 || error.status === 403)) {
-            return elicitStepUp(ctx, `stepup:preview:${applicationId}`, applicationId);
+            return elicitStepUp(ctx, `stepup:preview:${applicationId}`, applicationId, input.branch);
         }
         return {
             kind: "error",
@@ -1912,8 +2418,11 @@ export async function previewApp(ctx, input) {
     if (ready.kind !== "ok") {
         return ready;
     }
+    const gatewayChromium = await gatewayChromiumIsPresent(ctx);
+    const includeScreenshot = input.includeScreenshot !== false;
     let jwt;
-    if (ctx.config.deployedShellBaseUrl) {
+    if (ctx.config.deployedShellBaseUrl ||
+        (includeScreenshot && ctx.capturePreviewScreenshot && gatewayChromium)) {
         try {
             jwt = await ctx.server.issueScopedToken({
                 apiKey: principal.apiKey,
@@ -1937,10 +2446,14 @@ export async function previewApp(ctx, input) {
         publicViewerBaseUrl: ctx.config.publicViewerBaseUrl,
         uiPreviewUrl: url,
     });
+    const captureUrl = buildEmbedShellPreviewUrl({
+        applicationId,
+        deployedShellBaseUrl: ctx.config.deployedShellBaseUrl,
+        uiBaseUrl: ctx.config.uiBaseUrl,
+    });
     let screenshotBase64;
+    let screenshotUnavailableReason;
     let needsBrowserDriver = false;
-    const gatewayChromium = await gatewayChromiumIsPresent(ctx);
-    const includeScreenshot = input.includeScreenshot !== false;
     // Always capture when the preview is ready and Gateway Chromium is present.
     // urls_only must not wait on chromium.launch() (ENG-5858).
     if (!includeScreenshot) {
@@ -1969,19 +2482,35 @@ export async function previewApp(ctx, input) {
         });
         needsBrowserDriver = true;
     }
-    else {
+    else if (!jwt) {
+        screenshotUnavailableReason =
+            "Preview screenshot unavailable because its scoped credential could not be created.";
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "no scoped preview token",
+        });
+    }
+    else if (!isTrustedEmbedOrigin(captureUrl, ctx.config.serverUrl)) {
+        // Capturing anyway would photograph the shell's unauthenticated error page
+        // and report it as the app.
+        screenshotUnavailableReason =
+            "Preview screenshots run only against a local stack or the Superblocks origin this session is signed in to.";
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "shell origin is not the signed-in control plane",
+            url: captureUrl,
+        });
+    }
+    else {
         ctx.onProgress?.({
             message: "Capturing a preview screenshot",
             type: "progress",
         });
         try {
             const shot = await ctx.capturePreviewScreenshot({
-                embedToken: principal.apiKey,
-                url: buildEmbedShellPreviewUrl({
-                    applicationId,
-                    deployedShellBaseUrl: ctx.config.deployedShellBaseUrl,
-                    uiBaseUrl: ctx.config.uiBaseUrl,
-                }),
+                embedToken: jwt,
+                trustedOrigin: ctx.config.serverUrl,
+                url: captureUrl,
             });
             screenshotBase64 = shot?.dataBase64;
             // A capture that soft-fails looks exactly like one that was never asked
@@ -1992,7 +2521,7 @@ export async function previewApp(ctx, input) {
             });
         }
         catch (error) {
-            // Screenshot is optional; never fail get_app / preview_app for it.
+            // Screenshot is optional; never fail the commit preview for it.
             console.warn("gateway preview screenshot threw; continuing with URLs", {
                 message: error instanceof Error ? error.message : String(error),
             });
@@ -2008,20 +2537,87 @@ export async function previewApp(ctx, input) {
     });
     return {
         kind: "ok",
-        value: await withBrowser(ctx, applicationId, {
+        value: await withBrowser(ctx, {
             applicationId,
+            ...(input.branch ? { branch: input.branch } : {}),
             commitId: commit.commitId,
-            editUrl: editUrl(ctx.config, applicationId),
+            directoryHash,
+            editUrl: editUrl(ctx.config, applicationId, input.branch),
             ...(name ? { name } : {}),
             ...(needsBrowserDriver ? { needsBrowserDriver: true } : {}),
             openableViaHttps: openable.openableViaHttps,
             previewUrl: openable.previewUrl,
             ...(screenshotBase64 ? { screenshotBase64 } : {}),
+            ...(screenshotUnavailableReason ? { screenshotUnavailableReason } : {}),
             status: ready.value.built ? "ready" : "building",
             viewerUrl: openable.viewerUrl,
         }),
     };
 }
+/** Read the build backing an existing commit preview without creating work. */
+export async function getPreviewStatus(ctx, input) {
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const { wait, ...preview } = input;
+    const deadline = nowMs(ctx) + hostCallBudgetMs(ctx, ctx.config.publishWaitTimeoutMs);
+    let status = "building";
+    for (;;) {
+        if (ctx.signal?.aborted) {
+            return namingApplication(input.applicationId, cancelled("get_preview_status"));
+        }
+        if (wait && nowMs(ctx) >= deadline) {
+            break;
+        }
+        let progress;
+        try {
+            progress = await ctx.server.getBuildProgress({
+                apiKey: principalResult.value.apiKey,
+                applicationId: input.applicationId,
+                directoryHash: input.directoryHash,
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+                ...(wait ? { timeoutMs: Math.max(1, deadline - nowMs(ctx)) } : {}),
+            });
+        }
+        catch (error) {
+            if (ctx.signal?.aborted) {
+                return namingApplication(input.applicationId, cancelled("get_preview_status"));
+            }
+            if (wait &&
+                nowMs(ctx) >= deadline &&
+                !(error instanceof ServerHttpError)) {
+                break;
+            }
+            return {
+                kind: "error",
+                code: "preview_build_failed",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        if (ctx.signal?.aborted) {
+            return namingApplication(input.applicationId, cancelled("get_preview_status"));
+        }
+        status =
+            progress === "success"
+                ? "ready"
+                : progress === "failed" || progress === "timed_out"
+                    ? "failed"
+                    : "building";
+        if (!wait || status !== "building" || nowMs(ctx) >= deadline) {
+            break;
+        }
+        await sleepUntilAbort(Math.min(ctx.config.publishPollIntervalMs, deadline - nowMs(ctx)), ctx.signal);
+    }
+    return {
+        kind: "ok",
+        value: {
+            ...preview,
+            editUrl: editUrl(ctx.config, input.applicationId, input.branch),
+            status,
+        },
+    };
+}
 /**
  * The app's display name, or undefined when it cannot be read. A label is
  * never worth failing a preview over, so every failure here is swallowed.
@@ -2041,6 +2637,19 @@ async function applicationName(ctx, principal, applicationId) {
         return undefined;
     }
 }
+function pendingQuestion(ctx, applicationId, branch) {
+    return (ctx.appState.pendingDecision(applicationId, branch)?.decision.kind ===
+        "multi_choice");
+}
+function editTurnMode(input, pendingQuestion) {
+    if (pendingQuestion) {
+        return "PLAN";
+    }
+    if (input.planAction === "approve") {
+        return "BUILD";
+    }
+    return input.mode ?? "PLAN";
+}
 /**
  * Whether the app's last turn finished waiting on the user. True even when the
  * collector captured no structured plan/question (Clark streamed it as chat
@@ -2048,12 +2657,13 @@ async function applicationName(ctx, principal, applicationId) {
  * same as a plan card instead of dead-ending or previewing the template.
  */
 function awaitingDecision(ctx, scope) {
-    const turn = ctx.sessionPeer.turnState?.(scope);
+    const turn = ctx.sessionPeer.turnState(scope);
     return (turn?.phase === "finished" && turn.generationStatus === "needs_decision");
 }
 function emptyTurnStatus(status) {
     switch (status) {
         case "cancelled":
+        case "detached":
         case "live_edit_terminated":
         case "no_changes":
         case "timeout":
@@ -2069,6 +2679,9 @@ function localUnbuiltReason(turn, pending) {
     if (turn?.phase === "running") {
         return { kind: "running" };
     }
+    if (turn?.phase === "finished" && turn.checkpointFailure) {
+        return { failure: turn.checkpointFailure, kind: "checkpoint_failed" };
+    }
     if (pending) {
         return { decision: pending.decision, kind: "awaiting_decision" };
     }
@@ -2092,135 +2705,49 @@ function localUnbuiltReason(turn, pending) {
     return status
         ? {
             kind: "empty_turn",
-            retryAction: turn.retryAction ?? "retry_build",
+            ...(turn.retryAction
+                ? { pendingAction: turn.retryAction }
+                : turn.retryable === false
+                    ? turn.recoveryAction
+                        ? { pendingAction: turn.recoveryAction }
+                        : {}
+                    : turn.generationStatus === "detached"
+                        ? {}
+                        : { pendingAction: "retry_build" }),
+            ...(turn.reply ? { reply: turn.reply } : {}),
             status,
         }
         : undefined;
 }
-/**
- * The same question asked of what was persisted, for a caller with no live turn
- * to ask.
- *
- * Only a status that cannot coexist with committed work is read from here. The
- * gateway checkpoints a turn that *completed*, and the stream carries no record
- * of whether that landed, so a `cancelled` in the tail may well have a real app
- * behind it and withholding its preview would hide one. A live edit that died
- * and a turn still waiting on the user both certainly never reached completed.
- *
- * A stream with no terminal state at all is a build still running as far as it
- * knows, and so is one this gateway timed out - a gateway budget is not
- * something the dev server records. Neither is grounds to withhold a preview.
- */
-async function persistedUnbuiltReason(ctx, principal, applicationId) {
-    let snapshot;
-    try {
-        snapshot = await readSnapshot(ctx, {
-            applicationId,
-            // get_app is not a poll: it reads the tail, which is cursor-independent,
-            // and must not move any caller's place in the stream.
-            cursor: undefined,
-            // Only the tail is read below, and the tail does not depend on this. It
-            // keeps the call from dragging back the whole retained stream to answer
-            // one question about the end of it.
-            limit: 1,
-            organizationId: principal.organizationId,
-        });
-    }
-    catch (error) {
-        // This is the only I/O on a path that had none. An event store having a
-        // bad moment is not a reason for get_app to fail: fall back to what the
-        // call answered before there was a stream to ask.
-        console.warn("gateway get_app persisted state unreadable", {
-            applicationId,
-            error: error instanceof Error ? error.message : String(error),
-        });
-        return undefined;
-    }
-    if (!snapshot) {
+async function unbuiltReason(ctx, principal, applicationId, requestedBranch) {
+    const branch = normalizeBranch(requestedBranch);
+    const turn = ctx.sessionPeer.turnState({
+        applicationId,
+        branch,
+        organizationId: principal.organizationId,
+        userId: principal.userId,
+    });
+    const candidate = ctx.appState.pendingDecision(applicationId, branch);
+    const pending = turn && candidate?.branch !== turn.branch ? undefined : candidate;
+    const reason = localUnbuiltReason(turn, pending);
+    if (!reason) {
         return undefined;
     }
-    const { generationStatus } = readPersistedProgress(snapshot, streamLiveness(ctx), ctx.config.clarkSettleMs);
-    return generationStatus ? persistedTurnEnd(generationStatus) : undefined;
-}
-/**
- * When to stop believing what the stream last said. A turn cannot outlive its
- * own budget, so work silent for longer than that has ended whatever the tail
- * still holds.
- *
- * Shared by both readers so one rule governs every status read out of a stream,
- * even where a caller happens not to use the part it governs: this reader takes
- * only `generationStatus`, which never expires, while `check_app_progress` reads
- * the status the rule applies to.
- */
-function streamLiveness(ctx) {
-    return {
-        nowMs: nowMs(ctx),
-        staleAfterMs: ctx.config.clarkTurnTimeoutMs,
-    };
-}
-/**
- * What a terminal status read from the stream says about previewing the app.
- *
- * Exhaustive on purpose: the live reader answers this same question from a
- * `TurnState`, and the two are only guaranteed to agree while every status has
- * been given an answer on both. A new one fails to compile here rather than
- * quietly defaulting to buildable.
- *
- * `no_changes` never appears. Which of `completed` and `no_changes` a turn
- * reached is decided by counting the work signals the collector saw, and the
- * stream carries no such signal - the dev server reports the state, not the
- * files. A no-work turn therefore reads as `completed` here and is previewed.
- *
- * TODO(ENG-5911): close that by persisting the gateway's own account of the
- * turn - the settled status and whether a checkpoint landed - rather than
- * adding another rule over the states the stream already has.
- */
-function persistedTurnEnd(status) {
-    switch (status) {
-        // TODO(ENG-5912): carry the decision itself. The stream has the plan - it
-        // is an assistant `chat_message` with a `messageType` - but nothing reads
-        // it back into a `TurnDecision`, so a plan resumed from here renders as a
-        // plain question and cannot be approved.
-        case "needs_decision":
-            return { kind: "awaiting_decision" };
-        // The stream never recorded whether the prompt carried an archive, so
-        // this path cannot pick retry_build vs retry_import. Omit rather than guess.
-        case "live_edit_terminated":
-            return { kind: "empty_turn", status };
-        // A `cancelled` in the tail may still have a real app behind it: the
-        // gateway checkpoints a turn that completed and the stream carries no
-        // record of whether that landed, so withholding the preview would hide
-        // one. `detached` and `timeout` are the gateway's own verdicts, which the
-        // dev server never records, and `completed` is the case this gate exists
-        // to let through.
-        case "cancelled":
-        case "completed":
-        case "detached":
-        case "no_changes":
-        case "timeout":
-            return undefined;
-        default: {
-            const exhaustive = status;
-            return exhaustive;
-        }
-    }
+    const actualBranch = turn ? turn.branch : (pending?.branch ?? branch);
+    return { ...(actualBranch ? { branch: actualBranch } : {}), reason };
 }
-async function unbuiltReason(ctx, principal, applicationId) {
-    const turn = ctx.sessionPeer.turnState?.({
+function currentTurnBranch(ctx, principal, applicationId, requestedBranch) {
+    const branch = normalizeBranch(requestedBranch);
+    const turn = ctx.sessionPeer.turnState({
         applicationId,
+        branch,
         organizationId: principal.organizationId,
         userId: principal.userId,
     });
-    const pending = ctx.sessionPeer.pendingDecision?.(applicationId);
-    if (turn || pending) {
-        return localUnbuiltReason(turn, pending);
+    if (turn) {
+        return turn.branch;
     }
-    // The local turn is an accelerator, not the record. With nothing held here -
-    // after a restart, on another replica, or once a finished turn was released -
-    // the persisted stream is the only account of the turn that is left, and
-    // falling through without asking it is how the untouched starter template
-    // gets built and shown as a finished app.
-    return await persistedUnbuiltReason(ctx, principal, applicationId);
+    return ctx.appState.pendingDecision(applicationId, branch)?.branch ?? branch;
 }
 /**
  * The answer `get_app` owes a caller while the app has nothing worth showing.
@@ -2230,35 +2757,57 @@ async function unbuiltReason(ctx, principal, applicationId) {
  * the untouched template, and the caller shows the blank result as if the app
  * were ready. Undefined once Clark's turn is over and a preview means something.
  */
-async function unbuiltApp(ctx, principal, applicationId) {
-    const reason = await unbuiltReason(ctx, principal, applicationId);
-    if (!reason) {
+async function unbuiltApp(ctx, principal, applicationId, requestedBranch) {
+    const branch = normalizeBranch(requestedBranch);
+    const state = await unbuiltReason(ctx, principal, applicationId, branch);
+    if (!state) {
         return undefined;
     }
+    const { reason } = state;
+    const actualBranch = state.branch ?? branch;
     const name = await applicationName(ctx, principal, applicationId);
-    await rememberApplication(ctx, principal, applicationId);
-    const app = await withBrowser(ctx, applicationId, {
+    await rememberApplication(ctx, principal, applicationId, actualBranch);
+    const app = await withBrowser(ctx, {
         applicationId,
-        editUrl: editUrl(ctx.config, applicationId),
+        ...(actualBranch ? { branch: actualBranch } : {}),
+        editUrl: editUrl(ctx.config, applicationId, actualBranch),
         ...(name ? { name } : {}),
     });
     if (reason.kind === "awaiting_decision") {
+        // The remembered plan counts: a plan the caller can show the user beats
+        // sending them to the editor, and it can only be a plan, so reading it
+        // back cannot mislabel a question as one (ENG-5910).
+        const decision = decisionToPutToTheUser(ctx, applicationId, actualBranch, reason.decision);
         return {
             kind: "ok",
             value: {
                 ...app,
-                ...(reason.decision ? { decision: reason.decision } : {}),
-                pendingAction: reason.decision?.kind === "plan" ? "approve_plan" : "answer_question",
+                ...(decision ? { decision } : {}),
+                pendingAction: pendingActionForDecision(decision),
                 status: "needs_decision",
             },
         };
     }
+    if (reason.kind === "checkpoint_failed") {
+        return {
+            kind: "ok",
+            value: {
+                ...app,
+                checkpointFailure: reason.failure,
+                pendingAction: "open_editor",
+                status: "checkpoint_failed",
+            },
+        };
+    }
     if (reason.kind === "empty_turn") {
         return {
             kind: "ok",
             value: {
                 ...app,
-                ...(reason.retryAction ? { pendingAction: reason.retryAction } : {}),
+                ...(reason.pendingAction
+                    ? { pendingAction: reason.pendingAction }
+                    : {}),
+                ...(reason.reply ? { reply: reason.reply } : {}),
                 status: reason.status,
             },
         };
@@ -2266,11 +2815,6 @@ async function unbuiltApp(ctx, principal, applicationId) {
     return {
         kind: "ok",
         value: {
-            ...(await buildPacing(ctx, {
-                applicationId,
-                organizationId: principal.organizationId,
-                terminal: false,
-            })),
             ...app,
             pendingAction: "wait_for_build",
             status: "building",
@@ -2278,8 +2822,86 @@ async function unbuiltApp(ctx, principal, applicationId) {
     };
 }
 /**
- * Lovable-style lookup: editor URL always, preview URLs when a build can be
- * ensured (default). Captures a screenshot whenever the preview is ready.
+ * The plan or question this app is waiting on, in full.
+ *
+ * `unbuiltReason` answers whether the turn is waiting; it does not always
+ * carry what it is waiting on, because Superblocks can stream a plan as chat
+ * text and leave the collector no plan card to capture. The plan itself is
+ * remembered either way, so the form is built from that rather than from
+ * nothing.
+ */
+function decisionToPutToTheUser(ctx, applicationId, branch, decision) {
+    if (decision) {
+        return decision;
+    }
+    const plan = ctx.appState.pendingPlan(applicationId, branch);
+    return plan && plan.branch === branch
+        ? {
+            kind: "plan",
+            ...(plan.messageId ? { messageId: plan.messageId } : {}),
+            plan: plan.plan,
+            ...(plan.title ? { title: plan.title } : {}),
+        }
+        : undefined;
+}
+/**
+ * Opens the decision card: what Superblocks asked, for the user to answer as a
+ * form rather than by typing an approval the host has to interpret.
+ *
+ * Its own tool because an MCP App is bound to one, and `check_app_progress`
+ * must stay text-only - a card tool reopens its card on every poll, so putting
+ * this on the poll loop would flash a blank form through a whole build.
+ */
+export async function askUser(ctx, input) {
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const principal = principalResult.value;
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    if (resolved.kind !== "ok") {
+        return resolved;
+    }
+    const applicationId = resolved.value;
+    const unbuilt = await unbuiltApp(ctx, principal, applicationId, input.branch);
+    const branch = unbuilt?.value.branch ??
+        currentTurnBranch(ctx, principal, applicationId, input.branch);
+    const app = {
+        applicationId,
+        ...(branch ? { branch } : {}),
+        editUrl: editUrl(ctx.config, applicationId, branch),
+        ...(unbuilt?.value.name ? { name: unbuilt.value.name } : {}),
+    };
+    if (!unbuilt || unbuilt.value.status !== "needs_decision") {
+        // Nothing to ask. Saying which status it is instead is what stops the
+        // caller reopening an empty form rather than following the build.
+        return {
+            kind: "ok",
+            value: {
+                ...app,
+                ...(unbuilt?.value.pendingAction
+                    ? { pendingAction: unbuilt.value.pendingAction }
+                    : {}),
+                status: unbuilt ? unbuilt.value.status : "ready",
+            },
+        };
+    }
+    const decision = decisionToPutToTheUser(ctx, applicationId, unbuilt.value.branch ?? normalizeBranch(input.branch), unbuilt.value.decision);
+    const candidate = ctx.appState.pendingDecision(applicationId, branch);
+    const pending = candidate?.branch === branch ? candidate : undefined;
+    return {
+        kind: "ok",
+        value: {
+            ...app,
+            ...(decision ? { decision } : {}),
+            pendingAction: pendingActionForDecision(decision),
+            ...(pending?.reply ? { reply: pending.reply } : {}),
+            status: "needs_decision",
+        },
+    };
+}
+/**
+ * Read the app's current live editor view without committing or building it.
  */
 export async function getApp(ctx, input) {
     const principalResult = await ensurePrincipal(ctx);
@@ -2292,25 +2914,32 @@ export async function getApp(ctx, input) {
         return resolved;
     }
     const applicationId = resolved.value;
-    const ensurePreview = input.ensurePreview !== false;
-    const unbuilt = await unbuiltApp(ctx, principal, applicationId);
+    const includeScreenshot = input.includeScreenshot !== false;
+    const unbuilt = await unbuiltApp(ctx, principal, applicationId, input.branch);
+    const branch = unbuilt?.value.branch ??
+        currentTurnBranch(ctx, principal, applicationId, input.branch);
     const mayCapture = !unbuilt || unbuilt.value.status === "building";
-    const live = mayCapture
-        ? await ensureLibraryCaptureInput(ctx, principal, applicationId, input.branch)
-        : libraryCaptureInput(ctx, applicationId);
-    if (unbuilt) {
+    const live = includeScreenshot && mayCapture
+        ? await ensureLibraryCaptureInput(ctx, principal, applicationId, branch)
+        : undefined;
+    const currentUnbuilt = includeScreenshot && mayCapture
+        ? await unbuiltApp(ctx, principal, applicationId, input.branch)
+        : unbuilt;
+    if (currentUnbuilt) {
         // Plan, question, and empty-starter stays fail-closed: photographing the
         // untouched template is the bug unbuiltApp exists to prevent. A running
         // turn is different: the held canvas is the thing being written, so a
         // live shot is worth returning alongside wait_for_build.
-        if (unbuilt.value.status !== "building" || !live) {
-            return unbuilt;
+        if (currentUnbuilt.value.status !== "building" ||
+            !live ||
+            (currentUnbuilt.value.branch ?? normalizeBranch(input.branch)) !== branch) {
+            return currentUnbuilt;
         }
         const liveShot = await captureLiveLibraryIfNeeded(ctx, applicationId, live);
         return {
             kind: "ok",
             value: {
-                ...unbuilt.value,
+                ...currentUnbuilt.value,
                 ...(liveShot.needsBrowserDriver ? { needsBrowserDriver: true } : {}),
                 ...(liveShot.screenshotBase64
                     ? { screenshotBase64: liveShot.screenshotBase64 }
@@ -2318,64 +2947,24 @@ export async function getApp(ctx, input) {
             },
         };
     }
-    if (ensurePreview) {
-        const preview = await previewApp(ctx, {
-            applicationId,
-            branch: input.branch,
-            includeScreenshot: live === undefined,
-            ...(input.wait === undefined ? {} : { wait: input.wait }),
-        });
-        if (preview.kind !== "ok") {
-            return preview;
-        }
-        // A build still running is the case this pacing exists for: the caller
-        // has usable URLs and needs to know when to look again. A finished one
-        // gets it too, with a zero interval, so a caller does not have to treat
-        // the fields' absence as a third state.
-        const pacing = await buildPacing(ctx, {
-            applicationId,
-            organizationId: principal.organizationId,
-            terminal: preview.value.status === "ready",
-        });
-        const liveShot = await captureLiveLibraryIfNeeded(ctx, applicationId, live);
-        const screenshotBase64 = live
-            ? liveShot.screenshotBase64
-            : preview.value.screenshotBase64;
-        const needsBrowserDriver = live
-            ? liveShot.needsBrowserDriver
-            : preview.value.needsBrowserDriver;
-        return {
-            kind: "ok",
-            value: {
-                ...pacing,
-                applicationId,
-                ...(preview.value.browser ? { browser: preview.value.browser } : {}),
-                commitId: preview.value.commitId,
-                editUrl: preview.value.editUrl,
-                ...(preview.value.name ? { name: preview.value.name } : {}),
-                ...(needsBrowserDriver ? { needsBrowserDriver: true } : {}),
-                openableViaHttps: preview.value.openableViaHttps,
-                previewUrl: preview.value.previewUrl,
-                ...(screenshotBase64 ? { screenshotBase64 } : {}),
-                status: preview.value.status,
-                viewerUrl: preview.value.viewerUrl,
-            },
-        };
-    }
     const name = await applicationName(ctx, principal, applicationId);
-    await rememberApplication(ctx, principal, applicationId);
+    await rememberApplication(ctx, principal, applicationId, branch);
     const liveShot = await captureLiveLibraryIfNeeded(ctx, applicationId, live);
+    const previewUrl = fullscreenPreviewUrl(ctx.config, applicationId, branch);
     return {
         kind: "ok",
-        value: await withBrowser(ctx, applicationId, {
+        value: await withBrowser(ctx, {
             applicationId,
-            editUrl: editUrl(ctx.config, applicationId),
+            ...(branch ? { branch } : {}),
+            editUrl: editUrl(ctx.config, applicationId, branch),
             ...(name ? { name } : {}),
             ...(liveShot.needsBrowserDriver ? { needsBrowserDriver: true } : {}),
+            openableViaHttps: isHttpsUrl(previewUrl),
+            previewUrl,
             ...(liveShot.screenshotBase64
                 ? { screenshotBase64: liveShot.screenshotBase64 }
                 : {}),
-            status: "unknown",
+            status: "ready",
         }),
     };
 }
@@ -2394,7 +2983,7 @@ async function waitForBuild(ctx, input) {
     let started = false;
     for (;;) {
         if (ctx.signal?.aborted) {
-            return namingApplication(input.applicationId, cancelled("get_app"));
+            return namingApplication(input.applicationId, cancelled("build_app"));
         }
         // Checked before the network call, not only after it: a budget already
         // exhausted when this loop begins (or used up by the previous
@@ -2472,20 +3061,258 @@ export async function publishApp(ctx, input) {
         return principalResult;
     }
     const principal = principalResult.value;
-    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId, { unambiguous: true });
     if (resolved.kind !== "ok") {
         return resolved;
     }
     const applicationId = resolved.value;
     return namingApplication(applicationId, await publishResolvedApp(ctx, { applicationId, input, principal }));
 }
+/**
+ * The publish that was accepted and is still rolling out.
+ *
+ * Reported as a success rather than an error, because it is one: the commit is
+ * made, the policy gates passed and Superblocks took the deploy. Only the
+ * rollout is outstanding, and `check_publish_progress` follows it.
+ */
+function stillPublishing(ctx, input) {
+    ctx.onProgress?.({
+        message: "Publish accepted — the deploy is still rolling out",
+        type: "completed",
+    });
+    return {
+        applicationId: input.applicationId,
+        commitId: input.commitId,
+        ...publishElapsedSeconds(ctx, input.applicationId, input.commitId, input.startedAtMs),
+        publishDetailsUrl: publishDetailsUrl(ctx.config, input.applicationId, input.commitId),
+        publishUrl: publishUrl(ctx.config, input.applicationId),
+        status: "publishing",
+    };
+}
+function publishElapsedSeconds(ctx, applicationId, commitId, startedAtMs = ctx.appState.publishStartedAtMs(applicationId, commitId)) {
+    return startedAtMs === undefined
+        ? {}
+        : {
+            elapsedSeconds: Math.floor(Math.max(0, nowMs(ctx) - startedAtMs) / 1000),
+        };
+}
+/**
+ * A deploy that was accepted but never appeared in the queue.
+ *
+ * Distinct from a rollout still running: there is nothing to follow, so the
+ * caller is told to look rather than sent into a poll loop over a deploy that
+ * may not exist.
+ */
+function publishNeverQueued(ctx, applicationId) {
+    return {
+        kind: "error",
+        code: "publish_timeout",
+        message: `Timed out waiting for the app to go live (last status: none). Open ${publishUrl(ctx.config, applicationId)} to check progress.`,
+    };
+}
+/**
+ * Where a publish handed back as `publishing` has got to.
+ *
+ * Each call watches for a bounded slice of the rollout, then hands back a
+ * changing clock so repeated calls remain useful without outliving the host.
+ */
+export async function checkPublishProgress(ctx, input) {
+    const pollStartedAtMs = nowMs(ctx);
+    const hostDeadlineAtMs = pollStartedAtMs + Math.max(0, ctx.config.hostCallCeilingMs);
+    const waitDeadlineAtMs = nowMs(ctx) + hostCallBudgetMs(ctx, ctx.config.publishProgressWaitMs);
+    const principalResult = await ensurePrincipal(ctx);
+    if (principalResult.kind !== "ok") {
+        return principalResult;
+    }
+    const principal = principalResult.value;
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    if (resolved.kind !== "ok") {
+        return resolved;
+    }
+    const applicationId = resolved.value;
+    const storedCommitId = ctx.appState.publishInFlight(applicationId);
+    const commitId = input.commitId?.trim() || storedCommitId;
+    if (!commitId) {
+        return namingApplication(applicationId, {
+            kind: "error",
+            code: "publish_not_started",
+            message: "No publish is in flight for this application. Call publish_app to deploy it, or name the commitId to follow.",
+        });
+    }
+    const claimedCommit = storedCommitId === undefined;
+    const publishClaim = claimedCommit || storedCommitId === commitId
+        ? ctx.appState.claimPublishInFlight(applicationId, commitId, nowMs(ctx))
+        : undefined;
+    const publishStartedAtMs = ctx.appState.publishStartedAtMs(applicationId, commitId);
+    const traceScope = {
+        "application.id": applicationId,
+        "publish.commit_id": commitId,
+    };
+    gatewayDebug("publish poll started", {
+        ...traceScope,
+        "poll.host_budget_ms": Math.max(0, hostDeadlineAtMs - pollStartedAtMs),
+        "poll.wait_budget_ms": Math.max(0, waitDeadlineAtMs - pollStartedAtMs),
+    });
+    let readCount = 0;
+    let lastStatus = "unread";
+    const traceFinished = (stoppedBecause) => {
+        gatewayDebug("publish poll finished", {
+            ...traceScope,
+            "poll.elapsed_ms": nowMs(ctx) - pollStartedAtMs,
+            "poll.read_count": readCount,
+            "poll.stopped_because": stoppedBecause,
+            "publish.deploy_status": lastStatus,
+        });
+    };
+    const aborted = () => {
+        if (claimedCommit && publishClaim !== undefined) {
+            ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+        }
+        traceFinished("cancelled");
+        return namingApplication(applicationId, {
+            kind: "error",
+            code: "publish_aborted",
+            message: "Publish wait was cancelled.",
+        });
+    };
+    for (;;) {
+        let status;
+        try {
+            const remainingHostMs = Math.max(1, hostDeadlineAtMs - nowMs(ctx));
+            const timeoutMs = readCount === 0
+                ? remainingHostMs
+                : Math.max(1, Math.min(remainingHostMs, waitDeadlineAtMs - nowMs(ctx)));
+            status = await ctx.server.getDeployStatus({
+                apiKey: principal.apiKey,
+                applicationId,
+                commitId,
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+                timeoutMs,
+            });
+            readCount += 1;
+            lastStatus = status.status;
+            gatewayDebug("publish poll status observed", {
+                ...traceScope,
+                "poll.read": readCount,
+                "poll.wait_remaining_ms": Math.max(0, waitDeadlineAtMs - nowMs(ctx)),
+                "publish.deploy_status": lastStatus,
+            });
+        }
+        catch (error) {
+            readCount += 1;
+            if (ctx.signal?.aborted) {
+                return aborted();
+            }
+            if (!deployStatusReadIsTransient(error)) {
+                if (claimedCommit && publishClaim !== undefined) {
+                    ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+                }
+                lastStatus = "read_failed";
+                traceFinished("deploy_status_read_failed");
+                return namingApplication(applicationId, {
+                    kind: "error",
+                    code: "publish_failed",
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            lastStatus = "transient_read_error";
+            gatewayDebug("publish poll status observed", {
+                ...traceScope,
+                "poll.read": readCount,
+                "poll.wait_remaining_ms": Math.max(0, waitDeadlineAtMs - nowMs(ctx)),
+                "publish.deploy_status": lastStatus,
+            });
+        }
+        if (status !== undefined) {
+            const outcome = readDeployOutcome(status);
+            if (outcome.kind === "failed" ||
+                outcome.kind === "needs_acknowledgement") {
+                if (publishClaim !== undefined) {
+                    ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+                }
+                traceFinished(outcome.kind);
+                return namingApplication(applicationId, deployFailure(outcome, outcome.message));
+            }
+            if (outcome.kind === "deployed") {
+                const elapsed = publishElapsedSeconds(ctx, applicationId, commitId, publishStartedAtMs);
+                if (publishClaim !== undefined) {
+                    ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+                }
+                traceFinished("deployed");
+                return {
+                    kind: "ok",
+                    value: {
+                        applicationId,
+                        commitId,
+                        ...elapsed,
+                        publishDetailsUrl: publishDetailsUrl(ctx.config, applicationId, commitId),
+                        publishUrl: publishUrl(ctx.config, applicationId),
+                        status: "deployed",
+                    },
+                };
+            }
+            if (outcome.status === "none") {
+                if (publishClaim === undefined) {
+                    traceFinished("publish_not_queued");
+                    return namingApplication(applicationId, publishNeverQueued(ctx, applicationId));
+                }
+                const missingForMs = ctx.appState.noteMissingPublishStatus(applicationId, publishClaim, nowMs(ctx));
+                if (missingForMs !== undefined &&
+                    missingForMs >= ctx.config.publishWaitTimeoutMs) {
+                    ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+                    traceFinished("publish_not_queued");
+                    return namingApplication(applicationId, publishNeverQueued(ctx, applicationId));
+                }
+            }
+            else if (publishClaim !== undefined) {
+                ctx.appState.noteVisiblePublishStatus(applicationId, publishClaim);
+            }
+        }
+        if (ctx.signal?.aborted) {
+            return aborted();
+        }
+        if (nowMs(ctx) >= waitDeadlineAtMs) {
+            traceFinished("poll_budget_spent");
+            return {
+                kind: "ok",
+                value: stillPublishing(ctx, {
+                    applicationId,
+                    commitId,
+                    startedAtMs: publishStartedAtMs,
+                }),
+            };
+        }
+        await sleepUntilAbort(Math.min(ctx.config.publishPollIntervalMs, Math.max(0, waitDeadlineAtMs - nowMs(ctx))), ctx.signal);
+        if (ctx.signal?.aborted) {
+            return aborted();
+        }
+    }
+}
 async function publishResolvedApp(ctx, args) {
     const { applicationId, input, principal } = args;
+    const requestedCommitId = input.commitId?.trim();
+    // One budget for the whole call, not just the rollout wait: committing and
+    // queueing the deploy spend the host's tool-call time too.
+    const deadlineAtMs = nowMs(ctx) + hostCallBudgetMs(ctx, ctx.config.publishWaitTimeoutMs);
+    if (ctx.signal?.aborted) {
+        return {
+            kind: "error",
+            code: "publish_aborted",
+            message: "Publish was cancelled before it started.",
+        };
+    }
+    if (nowMs(ctx) >= deadlineAtMs) {
+        return {
+            kind: "error",
+            code: "publish_timeout",
+            message: "Publish could not start within the host call budget.",
+        };
+    }
     // Deploys address a commit and never fall back to the branch head, while
     // Clark's work sits uncommitted in the live-edit session. Committing here is
     // what the editor's own publish flow does, and without it a caller who has
     // never committed could not publish at all.
-    let commitId = input.commitId?.trim();
+    let commitId = requestedCommitId;
     if (!commitId) {
         ctx.onProgress?.({ message: "Committing current work", type: "progress" });
         try {
@@ -2494,10 +3321,19 @@ async function publishResolvedApp(ctx, args) {
                 applicationId,
                 branch: input.branch,
                 message: input.prompt,
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+                timeoutMs: Math.max(1, deadlineAtMs - nowMs(ctx)),
             });
             commitId = commit.commitId;
         }
         catch (error) {
+            if (ctx.signal?.aborted) {
+                return {
+                    kind: "error",
+                    code: "publish_aborted",
+                    message: "Publish was cancelled while committing the app.",
+                };
+            }
             return {
                 kind: "error",
                 code: "commit_failed",
@@ -2505,17 +3341,35 @@ async function publishResolvedApp(ctx, args) {
             };
         }
     }
+    if (ctx.signal?.aborted) {
+        return {
+            kind: "error",
+            code: "publish_aborted",
+            message: `Commit ${commitId} was created, but deployment was cancelled before it started. Retry publish_app with that commitId.`,
+        };
+    }
+    if (nowMs(ctx) >= deadlineAtMs) {
+        return {
+            kind: "error",
+            code: "publish_timeout",
+            message: `Commit ${commitId} was created, but deployment could not start within the host call budget. Retry publish_app with that commitId.`,
+        };
+    }
     ctx.onProgress?.({ message: "Publishing application", type: "progress" });
+    const publishClaim = ctx.appState.setPublishInFlight(applicationId, commitId, nowMs(ctx));
     try {
         const deployment = await ctx.server.deployApplication({
             apiKey: principal.apiKey,
             applicationId,
             commitId,
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+            timeoutMs: Math.max(1, deadlineAtMs - nowMs(ctx)),
         });
         // Nothing is published on these two paths and nothing will be without
         // someone acting, so neither can report as success.
         if (deployment.status === "failed") {
-            ctx.sessionPeer.release?.(applicationId);
+            ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+            ctx.sessionPeer.release(applicationId);
             return {
                 kind: "error",
                 code: "publish_failed",
@@ -2523,14 +3377,14 @@ async function publishResolvedApp(ctx, args) {
             };
         }
         if (deployment.status === "awaiting_ack") {
-            ctx.sessionPeer.release?.(applicationId);
+            ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+            ctx.sessionPeer.release(applicationId);
             return {
                 kind: "error",
                 code: "publish_needs_acknowledgement",
                 message: `${deployment.message ?? "Policy checks passed with advisory findings."} Publishing is on hold until they are reviewed in Superblocks, or until this is published again with the findings acknowledged.`,
             };
         }
-        const deploymentId = deployment.deploymentId;
         if (deployment.status === "queued") {
             ctx.onProgress?.({
                 message: "Waiting for deploy…",
@@ -2540,19 +3394,41 @@ async function publishResolvedApp(ctx, args) {
                 apiKey: principal.apiKey,
                 applicationId,
                 commitId,
+                deadlineAtMs,
+                publishClaim,
             });
             if (waited.kind !== "ok") {
-                ctx.sessionPeer.release?.(applicationId);
+                ctx.sessionPeer.release(applicationId);
                 return waited;
             }
+            if (!waited.value.settled) {
+                ctx.sessionPeer.release(applicationId);
+                // Nothing ever appeared in the deploy queue, so there is no rollout to
+                // follow and telling the caller to keep polling would be inventing one.
+                if (waited.value.lastStatus === "none") {
+                    ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+                    return publishNeverQueued(ctx, applicationId);
+                }
+                await rememberApplication(ctx, principal, applicationId);
+                return {
+                    kind: "ok",
+                    value: stillPublishing(ctx, {
+                        applicationId,
+                        commitId,
+                    }),
+                };
+            }
         }
         await rememberApplication(ctx, principal, applicationId);
         // Deploy finished — the held editor socket is no longer needed.
-        ctx.sessionPeer.release?.(applicationId);
+        ctx.sessionPeer.release(applicationId);
+        const elapsed = publishElapsedSeconds(ctx, applicationId, commitId);
+        ctx.appState.clearPublishInFlight(applicationId, publishClaim);
         const result = {
             applicationId,
             commitId,
-            deploymentId,
+            ...elapsed,
+            publishDetailsUrl: publishDetailsUrl(ctx.config, applicationId, commitId),
             publishUrl: publishUrl(ctx.config, applicationId),
             status: "deployed",
         };
@@ -2568,12 +3444,24 @@ async function publishResolvedApp(ctx, args) {
         // mentioning an author through a re-auth flow and bury the real failure.
         if (error instanceof ServerHttpError &&
             (error.status === 401 || error.status === 403)) {
-            return elicitStepUp(ctx, `stepup:${input.idempotencyKey}`, applicationId);
+            ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+            return elicitStepUp(ctx, `stepup:${input.idempotencyKey}`, applicationId, input.branch);
+        }
+        if (error instanceof ServerHttpError) {
+            ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+            return {
+                kind: "error",
+                code: "publish_failed",
+                message: error.message,
+            };
         }
+        ctx.sessionPeer.release(applicationId);
         return {
-            kind: "error",
-            code: "publish_failed",
-            message: error instanceof Error ? error.message : String(error),
+            kind: "ok",
+            value: stillPublishing(ctx, {
+                applicationId,
+                commitId,
+            }),
         };
     }
 }