@superblocksteam/gateway 2.0.0-SNAPSHOT.1d4c72c0ab174c21

package/dist/capabilities/lifecycle.js

@@ -0,0 +1,3450 @@
+import { randomUUID } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { detectAttachmentArchiveType, getAttachmentMimeTypeFromFileName, getTextAttachmentType, isSupportedAttachmentUploadType, } from "@superblocksteam/shared";
+import { buildBrowserDriverContract, needsBrowserDriverError, } from "../capture/browser-contract.js";
+import { resolveCaptureMode } from "../capture/mode.js";
+import { gatewayDebug } from "../debug.js";
+import { playwrightChromiumPresent } from "../playwright/ensure-chromium.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 { 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.";
+/**
+ * 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, 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(/\/$/, "");
+}
+async function gatewayChromiumIsPresent(ctx) {
+    if (typeof ctx.config.gatewayChromiumPresent === "boolean") {
+        return ctx.config.gatewayChromiumPresent;
+    }
+    return playwrightChromiumPresent();
+}
+async function captureModeOf(ctx) {
+    return resolveCaptureMode({
+        gatewayChromium: await gatewayChromiumIsPresent(ctx),
+        hostMcpConfigured: ctx.config.captureHostMcp,
+    });
+}
+function libraryCaptureInput(ctx, applicationId, branch) {
+    const context = ctx.sessionPeer.libraryBrowserContext(applicationId, branch);
+    if (!context) {
+        return undefined;
+    }
+    const auth = context.initData.devServerAuthorization;
+    if (!auth) {
+        console.error("gateway live canvas skipped: missing_dev_server_authorization", { applicationId });
+        return undefined;
+    }
+    return {
+        bootstrapData: {
+            accessToken: context.bootstrapData.accessToken,
+            agents: context.bootstrapData.agents ?? [],
+            ...(context.bootstrapData.agentUrls
+                ? { agentUrls: context.bootstrapData.agentUrls }
+                : {}),
+            appId: context.bootstrapData.appId,
+            devServerAuthorization: auth,
+            ...(context.bootstrapData.featureFlags
+                ? { featureFlags: context.bootstrapData.featureFlags }
+                : {}),
+            ...(context.bootstrapData.orgId
+                ? { orgId: context.bootstrapData.orgId }
+                : {}),
+            ...(context.bootstrapData.profiles
+                ? { profiles: context.bootstrapData.profiles }
+                : {}),
+            token: context.bootstrapData.token,
+            ...(context.bootstrapData.userEmail
+                ? { userEmail: context.bootstrapData.userEmail }
+                : {}),
+            userId: context.bootstrapData.userId,
+            ...(context.bootstrapData.windowOriginUrl
+                ? { windowOriginUrl: context.bootstrapData.windowOriginUrl }
+                : {}),
+        },
+        iframeBaseUrl: context.iframeBaseUrl,
+        initData: {
+            appId: context.initData.appId,
+            devServerAuthorization: auth,
+            peerId: context.initData.peerId,
+            ...(context.initData.userId ? { userId: context.initData.userId } : {}),
+            ...(context.initData.windowOriginUrl
+                ? { windowOriginUrl: context.initData.windowOriginUrl }
+                : {}),
+        },
+    };
+}
+/**
+ * Live-library capture input for get_app: reuse a held session, or re-open
+ * 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, branch);
+    if (existing) {
+        return existing;
+    }
+    if (ctx.appState.pendingStart({
+        applicationId,
+        ...(branch ? { branch } : {}),
+        organizationId: principal.organizationId,
+        userId: principal.userId,
+    })) {
+        return undefined;
+    }
+    if (!(await gatewayChromiumIsPresent(ctx))) {
+        console.error("gateway live canvas skipped: chromium_absent_no_rehold", {
+            applicationId,
+        });
+        return undefined;
+    }
+    try {
+        const session = await openLiveEdit(ctx, {
+            apiKey: principal.apiKey,
+            applicationId,
+            branch,
+            organizationId: principal.organizationId,
+        });
+        const sessionToken = await ctx.server.issueScopedToken({
+            apiKey: principal.apiKey,
+            applicationId,
+        });
+        await ctx.sessionPeer.holdLiveEdit({
+            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,
+                    applicationId,
+                    branch,
+                });
+            },
+            liveEditId: session.liveEditId,
+            liveEditUrl: session.liveEditUrl,
+            organizationId: principal.organizationId,
+            sessionToken,
+            userId: principal.userId,
+        });
+    }
+    catch (error) {
+        console.error("gateway live canvas skipped: rehold_failed", {
+            applicationId,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+    const live = libraryCaptureInput(ctx, applicationId, branch);
+    if (!live) {
+        console.error("gateway live canvas skipped: context_incomplete_after_rehold", { applicationId });
+    }
+    return live;
+}
+async function captureLiveLibraryIfNeeded(ctx, applicationId, live) {
+    if (!live) {
+        return {};
+    }
+    if (!ctx.captureLibraryScreenshot) {
+        console.error("gateway live canvas skipped: no_capture_function", {
+            applicationId,
+        });
+        return { needsBrowserDriver: true };
+    }
+    if (!(await gatewayChromiumIsPresent(ctx))) {
+        console.error("gateway live canvas skipped: chromium_absent", {
+            applicationId,
+        });
+        return {
+            needsBrowserDriver: true,
+        };
+    }
+    console.error("Capturing a live canvas screenshot", { applicationId });
+    ctx.onProgress?.({
+        message: "Capturing a live canvas screenshot",
+        type: "progress",
+    });
+    try {
+        const shot = await ctx.captureLibraryScreenshot(live);
+        return { screenshotBase64: shot?.dataBase64 };
+    }
+    catch (error) {
+        console.warn("gateway library screenshot threw; continuing with URLs", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return { needsBrowserDriver: true };
+    }
+}
+async function browserContractFor(ctx, directEditUrl) {
+    return buildBrowserDriverContract({
+        captureMode: await captureModeOf(ctx),
+        editUrl: directEditUrl,
+        ...(ctx.hostBrowserTools ? { hostBrowserTools: ctx.hostBrowserTools } : {}),
+        isolated: ctx.config.captureHostIsolated,
+        uiOrigin: uiOrigin(ctx.config),
+    });
+}
+async function withBrowser(ctx, value) {
+    return {
+        ...value,
+        browser: await browserContractFor(ctx, value.editUrl),
+    };
+}
+/**
+ * Where the deployed app is served; `/deployments` is an API path, not a page.
+ * Needs the same `/code-mode` prefix as {@link editUrl}: the bare
+ * `/applications/:id` route is proxied to the legacy SPA, which 404s.
+ */
+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
+ * specific commit and needs nothing deployed.
+ */
+function previewUrl(config, applicationId, commitId) {
+    return `${config.uiBaseUrl.replace(/\/$/, "")}/code-mode/applications/preview/${applicationId}?commitId=${encodeURIComponent(commitId)}`;
+}
+function defaultAppName(prompt) {
+    const trimmed = prompt.trim().replace(/\s+/g, " ");
+    if (!trimmed) {
+        return "Untitled Gateway App";
+    }
+    return trimmed.length > 80 ? `${trimmed.slice(0, 77)}...` : trimmed;
+}
+/**
+ * Resolves the Superblocks user behind the CLI session this Gateway was
+ * started with.
+ *
+ * Identity is the already-logged-in Superblocks CLI user. A rejection here
+ * means that personal API key is bad, not that the user needs a second login,
+ * so it surfaces as an error rather than an interactive-auth elicitation.
+ */
+export async function ensurePrincipal(ctx) {
+    const { principal } = ctx;
+    // MCP already has the CLI session key. Looking it up again would spend a
+    // second round trip on `/users/me`, the slowest endpoint the Superblocks
+    // API has, when the principal is already resolved (ENG-5806).
+    if (principal.organizationId && principal.userId) {
+        const resolved = {
+            ...principal,
+            organizationId: principal.organizationId,
+            userId: principal.userId,
+        };
+        ctx.onPrincipalResolved?.(resolved);
+        return {
+            kind: "ok",
+            value: resolved,
+        };
+    }
+    let validated;
+    try {
+        validated = await ctx.server.validateApiKey(principal.apiKey);
+    }
+    catch (error) {
+        // A 5xx says nothing about the credential. Reporting it as an auth problem
+        // would send the user off to re-link an account that is perfectly fine.
+        if (error instanceof ServerHttpError && error.status >= 500) {
+            return {
+                kind: "error",
+                code: "downstream_unavailable",
+                message: `The Superblocks API could not confirm who this caller is: ${error.message}. This is usually transient — try again.`,
+            };
+        }
+        // The identity endpoint stopped answering. Same class of outage as the 5xx
+        // above, and it must not fall through to `capability_failed`: that told the
+        // caller its progress poll had failed on an identity route it never asked
+        // about, which reads as a broken gateway rather than a slow dependency.
+        if (error instanceof IdentityUnavailableError) {
+            return {
+                kind: "error",
+                code: "downstream_unavailable",
+                message: error.message,
+            };
+        }
+        throw error;
+    }
+    if (!validated) {
+        return {
+            kind: "error",
+            code: "downstream_unauthorized",
+            message: "The Superblocks API rejected the credential issued for this caller.",
+        };
+    }
+    const resolved = {
+        ...principal,
+        email: validated.email,
+        organizationId: validated.organizationId,
+        userId: validated.userId,
+    };
+    ctx.onPrincipalResolved?.(resolved);
+    return {
+        kind: "ok",
+        value: resolved,
+    };
+}
+/**
+ * Names a freshly created app the way the editor does: create it under a
+ * placeholder, then let Clark propose something readable.
+ *
+ * Best-effort by design. The AI endpoint is behind an org kill switch and is a
+ * network call like any other; a working application is not worth discarding
+ * over a cosmetic name.
+ */
+async function nameWithClark(ctx, input) {
+    try {
+        const name = await ctx.server.generateAppName({
+            apiKey: input.apiKey,
+            applicationId: input.applicationId,
+            prompt: input.prompt,
+        });
+        await ctx.server.renameApplication({
+            apiKey: input.apiKey,
+            applicationId: input.applicationId,
+            name,
+        });
+        return name;
+    }
+    catch (error) {
+        console.warn("gateway could not name the application with Superblocks", error);
+        return undefined;
+    }
+}
+/**
+ * The name the app ends up with: whatever the caller asked for, or Clark's
+ * suggestion. Asked for only after the prompt is on its way so Clark starts
+ * building immediately.
+ */
+async function finalAppName(ctx, input) {
+    if (input.explicitName) {
+        return input.name;
+    }
+    ctx.onProgress?.({ message: "Naming application", type: "progress" });
+    return ((await nameWithClark(ctx, {
+        apiKey: input.apiKey,
+        applicationId: input.applicationId,
+        prompt: input.prompt,
+    })) ?? input.name);
+}
+async function elicitStepUp(ctx, idempotencyKey, applicationId, branch) {
+    if (!ctx.config.captureHostMcp) {
+        return needsBrowserDriverError();
+    }
+    const existing = ctx.stepUpTurns.getByIdempotencyKey(idempotencyKey);
+    if (existing?.status === "ready") {
+        return {
+            kind: "error",
+            code: "reinvoke_required",
+            message: "Step-up authentication completed. Re-invoke the capability to continue.",
+        };
+    }
+    const browser = await browserContractFor(ctx, editUrl(ctx.config, applicationId, branch));
+    if (existing?.status === "pending") {
+        return {
+            kind: "auth_required",
+            elicitation: {
+                authUrl: existing.authUrl,
+                browser,
+                reason: existing.reason,
+                turnId: existing.turnId,
+            },
+        };
+    }
+    const turnId = randomUUID();
+    const callbackToken = randomUUID();
+    const authUrl = uiOrigin(ctx.config);
+    const turn = ctx.stepUpTurns.create({
+        authUrl,
+        callbackToken,
+        idempotencyKey,
+        reason: "idp_step_up",
+        ttlMs: ctx.config.turnTtlMs,
+        turnId,
+    });
+    ctx.onProgress?.({
+        message: `Authorize in browser: ${turn.authUrl}`,
+        type: "auth_required",
+    });
+    return {
+        kind: "auth_required",
+        elicitation: {
+            authUrl: turn.authUrl,
+            browser,
+            reason: "idp_step_up",
+            turnId: turn.turnId,
+        },
+    };
+}
+export async function resolveApplicationId(ctx, principal, applicationId) {
+    if (applicationId?.trim()) {
+        return { kind: "ok", value: applicationId.trim() };
+    }
+    const recent = ctx.recentApps.get({
+        organizationId: principal.organizationId,
+        userId: principal.userId,
+    });
+    if (!recent) {
+        return {
+            kind: "error",
+            code: "application_context_required",
+            message: APPLICATION_CONTEXT_REQUIRED,
+        };
+    }
+    return { kind: "ok", value: recent };
+}
+function rememberApplication(ctx, principal, applicationId) {
+    ctx.recentApps.set({
+        applicationId,
+        organizationId: principal.organizationId,
+        userId: principal.userId,
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Sleeps between polls, and gives up the moment the caller does.
+ *
+ * A plain sleep here would have a cancelled call sit out the rest of the gap
+ * before anything looked at the signal, holding a timer on behalf of a
+ * request that nobody is waiting for any more. Both the timer and the
+ * listener are released on the way out, whichever of the two arrives first.
+ */
+function sleepUntilAbort(ms, signal) {
+    if (signal === undefined) {
+        return sleep(ms);
+    }
+    if (signal.aborted) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        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) {
+    let lastStatus = "queued";
+    while (nowMs(ctx) < input.deadlineAtMs) {
+        if (ctx.signal?.aborted) {
+            return {
+                kind: "ok",
+                value: {
+                    lastStatus: lastStatus === "none" ? "queued" : lastStatus,
+                    settled: false,
+                },
+            };
+        }
+        let status;
+        try {
+            status = await ctx.server.getDeployStatus({
+                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",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        lastStatus = status.status;
+        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 (outcome.kind === "deployed") {
+            ctx.onProgress?.({ message: "App is live", type: "progress" });
+            return { kind: "ok", value: { lastStatus, settled: true } };
+        }
+        if (outcome.kind !== "running") {
+            ctx.appState.clearPublishInFlight(input.applicationId, input.publishClaim);
+            return deployFailure(outcome, outcome.message);
+        }
+        ctx.onProgress?.({
+            message: `Waiting for deploy (${outcome.status})…`,
+            type: "progress",
+        });
+        await sleepUntilAbort(Math.min(ctx.config.publishPollIntervalMs, Math.max(0, input.deadlineAtMs - nowMs(ctx))), ctx.signal);
+    }
+    return { kind: "ok", value: { lastStatus, settled: false } };
+}
+/**
+ * Both ways to look at a finished app, in the summary rather than only in the
+ * server instructions — clients follow a tool's own output more closely, and a
+ * user who is never offered the preview deploys to their whole organization to
+ * see what they built.
+ */
+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 replaceWedgedAppGuidance(applicationId) {
+    return `Superblocks could not start this application's live-edit session. Retrying the build cannot recover application ${applicationId}.`;
+}
+function exhaustedReplacementGuidance(replacesApplicationId) {
+    return `Superblocks could not start the replacement application's live-edit session. One fresh application has already been tried for ${replacesApplicationId}.`;
+}
+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 decisionSummary(turn.decision);
+    }
+    if (turn.generationStatus === "no_changes") {
+        return "The Superblocks job ended without building anything — read its reply";
+    }
+    if (turn.generationStatus === "detached") {
+        return "Superblocks is still working, but only the editor can show it — open the edit URL";
+    }
+    if (turn.generationStatus === "live_edit_terminated") {
+        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}`;
+    }
+    if (turn.viewStatus === "ready") {
+        return `Application ready. ${NEXT_STEPS}`;
+    }
+    return "Superblocks finished generating; the app may still be building in the editor";
+}
+async function promptInput(ctx, input) {
+    return {
+        apiKey: ctx.principal.apiKey,
+        applicationId: input.applicationId,
+        ...(input.attachments ? { attachments: input.attachments } : {}),
+        ...(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,
+                applicationId: input.applicationId,
+                branch: input.branch,
+            });
+        },
+        ...(input.liveEditId ? { liveEditId: input.liveEditId } : {}),
+        liveEditUrl: input.liveEditUrl,
+        mode: input.mode ?? "PLAN",
+        // Asked for only if the host above turns out not to serve the session any
+        // more. Going back through openLiveEdit rather than connectLiveEdit
+        // directly keeps the resume pointer honest: a session that moved is a
+        // different stream, and a caller polling by application id has to be sent
+        // to the new one.
+        resolveLiveEdit: () => openLiveEdit(ctx, {
+            apiKey: ctx.principal.apiKey,
+            applicationId: input.applicationId,
+            ...(input.branch ? { branch: input.branch } : {}),
+            organizationId: input.organizationId,
+        }),
+        onProgress: (message) => {
+            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 }
+            : {}),
+        sessionToken: await ctx.server.issueScopedToken({
+            apiKey: ctx.principal.apiKey,
+            applicationId: input.applicationId,
+        }),
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        userId: input.userId,
+    };
+}
+/**
+ * Opens the live-edit session a prompt will run on, and records which one it
+ * is against the application.
+ *
+ * The pointer is what makes resume reachable at all. A caller polling after a
+ * restart, from another replica, or from a channel that never started the
+ * build has an application id and nothing else; the event streams are keyed by
+ * live edit. Without this, every such caller finds no stream to read and falls
+ * back to "unknown" forever.
+ *
+ * Written before the prompt rather than after it, because the events this
+ * points at start arriving as soon as the turn does. A failure to record it is
+ * swallowed: it costs resume, and failing the prompt over it would trade a
+ * degraded poll for no build at all.
+ */
+async function openLiveEdit(ctx, input) {
+    const session = await ctx.server.connectLiveEdit({
+        apiKey: input.apiKey,
+        applicationId: input.applicationId,
+        branch: input.branch,
+    });
+    return session;
+}
+/**
+ * Hands the prompt to Clark and returns as soon as it is accepted, leaving the
+ * turn running on the held session for `check_app_progress` to follow.
+ */
+async function startClarkPrompt(ctx, input) {
+    let prepared;
+    try {
+        prepared = await promptInput(ctx, input);
+    }
+    catch (error) {
+        throw new PromptNotSentError(error instanceof Error ? error.message : String(error), error);
+    }
+    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",
+        value: {
+            activity: started.activity,
+            // Carried through because the peer may have followed the session to a
+            // host this call never named, and the result has to send the caller to
+            // the live edit the turn is actually on.
+            ...(started.liveEditId ? { liveEditId: started.liveEditId } : {}),
+        },
+    };
+}
+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, input.branch);
+    }
+    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, input.branch)}.`,
+            pendingAction: "retry_build",
+        };
+    }
+    return {
+        kind: "ok",
+        value: {
+            ...(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,
+            ...(forward.liveEditId ? { liveEditId: forward.liveEditId } : {}),
+            ...(forward.recentRuns && forward.recentRuns.length > 0
+                ? { recentRuns: forward.recentRuns }
+                : {}),
+            ...(forward.retryAction ? { retryAction: forward.retryAction } : {}),
+            viewStatus: forward.viewStatus,
+        },
+    };
+}
+/**
+ * Waits between create attempts after a dev-env rejection. Short enough that
+ * `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.
+ *
+ * The server gates code-mode apps on a LaunchDarkly flag. A server that can tell
+ * an unreadable flag from one that is off answers 503 and means "ask again". An
+ * older one answers 400 "Dev Env is not enabled" for both, because the SDK hands
+ * back the gate's `false` default whenever its stream is down without saying so —
+ * which locally, where the stream drops constantly, greeted most first prompts.
+ */
+function isRetryableCreateFailure(error) {
+    if (!(error instanceof ServerHttpError)) {
+        return false;
+    }
+    return (error.status === 503 ||
+        (error.status === 400 && /dev env is not enabled/i.test(error.message)));
+}
+/**
+ * Creates the application, absorbing a dev-env rejection that is really a
+ * momentarily unreadable feature flag. Retrying here keeps the flap away from
+ * the user; only a rejection that outlives every attempt reaches them, and it
+ * 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({
+                    ...createInput,
+                    ...(ctx.signal ? { signal: ctx.signal } : {}),
+                    timeoutMs: Math.max(1, deadline - nowMs(ctx)),
+                }),
+            };
+        }
+        catch (error) {
+            if (!isRetryableCreateFailure(error)) {
+                throw error;
+            }
+            const delayMs = DEV_ENV_RETRY_DELAYS_MS[attempt];
+            if (delayMs !== undefined) {
+                await sleep(Math.min(delayMs, Math.max(0, deadline - nowMs(ctx))));
+            }
+        }
+    }
+    return {
+        kind: "error",
+        code: "dev_env_unavailable",
+        message: `Superblocks refused to create a code-mode app: it read the dev-env feature flag as off for this organization. The gateway already retried ${DEV_ENV_RETRY_DELAYS_MS.length + 1} times over a few seconds, so this is more than a momentary flag-store blip. What failed is the flag read, not the user's account: do not tell the user to contact support or an organization admin, and do not say their account lacks access. Say the build could not be started, that one more attempt is worth trying, and that if it persists the Superblocks deployment's flag delivery needs looking at.`,
+    };
+}
+/**
+ * Names the application a failed call was working on.
+ *
+ * Every failure past the point where an application exists has to carry its id,
+ * because that id is the caller's only handle on a resource the call already
+ * persisted. `start_app` creates the row before it reaches live edit, so a
+ * connect that times out leaves an app the caller owns and never saw; and every
+ * app-scoped entry point may have resolved the id from the recent-app default
+ * rather than from its arguments, so the failure is the one place a caller can
+ * learn which app it actually drove.
+ */
+function namingApplication(applicationId, result) {
+    return result.kind === "error" ? { ...result, applicationId } : result;
+}
+/**
+ * Names the application `start_app` created, and says on the way out that it
+ * is still there.
+ *
+ * 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") {
+        console.warn("gateway left an application behind", {
+            applicationId,
+            capability,
+            code: result.code,
+        });
+    }
+    return namingApplication(applicationId, result);
+}
+function liveEditOpenFailureVerdict(error, appDisposition) {
+    const message = error instanceof Error ? error.message : String(error);
+    const normalized = message.toLowerCase();
+    if (normalized.includes("live-edit session for this application did not start in time") ||
+        /^Live edit .+ did not become active within \d+ms$/i.test(message)) {
+        if (appDisposition.kind === "existing_app") {
+            return {
+                message: PRESERVE_WEDGED_APP_GUIDANCE,
+                retryable: false,
+            };
+        }
+        return appDisposition.replacesApplicationId
+            ? {
+                message: exhaustedReplacementGuidance(appDisposition.replacesApplicationId),
+                retryable: false,
+            }
+            : {
+                message: replaceWedgedAppGuidance(appDisposition.applicationId),
+                pendingAction: "start_new_app",
+                recoveryAction: "start_new_app",
+                retryable: false,
+            };
+    }
+    return {
+        message,
+        pendingAction: "retry_build",
+        retryAction: "retry_build",
+    };
+}
+/** A live edit that would not open, before Clark saw the prompt. */
+function liveEditUnavailable(verdict) {
+    return {
+        kind: "error",
+        code: "live_edit_unavailable",
+        message: verdict.message,
+        ...(verdict.pendingAction ? { pendingAction: verdict.pendingAction } : {}),
+    };
+}
+/**
+ * Tell the peer that a turn for this application died before Superblocks ever
+ * saw it.
+ *
+ * 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` 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
+ * unanswered acknowledgement does not say which; telling the caller "nothing is
+ * running, send it again" would be the same overclaim this fixes, and acting on
+ * it can build the app twice.
+ */
+function rememberFailedStart(ctx, input) {
+    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({
+            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. ${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,
+        });
+    }
+    catch (error) {
+        // Swallowed: the failure the caller is actually being told about must not be
+        // replaced by a failure to write it down. Logged with the principal it was
+        // for, because the symptom is the one this record exists to prevent.
+        console.warn("gateway failed-start record on the session peer failed", {
+            applicationId: input.applicationId,
+            message: error instanceof Error ? error.message : String(error),
+            organizationId: input.principal.organizationId,
+            userId: input.principal.userId,
+        });
+    }
+}
+/**
+ * Whether Superblocks turned this caller away rather than failing to answer.
+ *
+ * A refusal is about the caller, not about the application. `connectLiveEdit`
+ * is where Superblocks authorizes them and it authorizes per application, while
+ * `resolveApplicationId` takes whatever application id it is handed - so
+ * recording a refusal would let anyone naming an app they cannot open author the
+ * status read by the people who can, and occupy a slot in a bounded store by
+ * naming one.
+ *
+ * 404 counts. Superblocks' existence checks are organization scoped, so an
+ * application belonging to another tenant reads as missing rather than as
+ * forbidden - and a caller who cannot see an app has no business authoring a
+ * 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: 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",
+    });
+    let session;
+    try {
+        session = await openLiveEdit(ctx, {
+            apiKey: principal.apiKey,
+            applicationId,
+            branch,
+            organizationId: principal.organizationId,
+        });
+    }
+    catch (error) {
+        const verdict = liveEditOpenFailureVerdict(error, {
+            applicationId,
+            kind: "new_app",
+            ...(input.replacesApplicationId
+                ? { replacesApplicationId: input.replacesApplicationId }
+                : {}),
+        });
+        rememberFailedStart(ctx, {
+            applicationId,
+            branch,
+            error,
+            idempotencyKey: input.idempotencyKey,
+            pendingStartRequired: args.pendingStartToken !== undefined,
+            pendingStartToken: args.pendingStartToken,
+            principal,
+            revision,
+            ...(verdict.pendingAction === "retry_build"
+                ? { retryAction: verdict.retryAction }
+                : {
+                    reason: verdict.message,
+                    ...(verdict.recoveryAction
+                        ? { recoveryAction: verdict.recoveryAction }
+                        : {}),
+                    retryable: false,
+                }),
+        });
+        return liveEditUnavailable(verdict);
+    }
+    ctx.onProgress?.({
+        message: "Forwarding prompt to Superblocks",
+        type: "progress",
+    });
+    const promptArgs = {
+        applicationId,
+        ...(args.attachments ? { attachments: args.attachments } : {}),
+        ...(branch ? { branch } : {}),
+        idempotencyKey: input.idempotencyKey,
+        liveEditId: session.liveEditId,
+        liveEditUrl: session.liveEditUrl,
+        mode: input.mode ?? "PLAN",
+        organizationId: principal.organizationId,
+        ...(args.pendingStartToken === undefined
+            ? {}
+            : {
+                pendingStartRequired: true,
+                pendingStartToken: args.pendingStartToken,
+            }),
+        prompt: promptForAttachedSource(prompt, args.attachments),
+        revision,
+        userId: principal.userId,
+    };
+    const named = () => finalAppName(ctx, {
+        apiKey: principal.apiKey,
+        applicationId,
+        explicitName: args.explicitName,
+        name: args.name,
+        prompt,
+    });
+    if (input.wait === "ack") {
+        const started = await startClarkPrompt(ctx, promptArgs);
+        if (started.kind !== "ok") {
+            return started;
+        }
+        return {
+            kind: "ok",
+            value: await withBrowser(ctx, {
+                activity: started.value.activity,
+                applicationId,
+                ...(branch ? { branch } : {}),
+                editUrl: editUrl(ctx.config, applicationId, branch),
+                liveEditId: started.value.liveEditId ?? session.liveEditId,
+                mode: promptArgs.mode,
+                name: await named(),
+                status: "building",
+            }),
+        };
+    }
+    const forward = await forwardClarkPrompt(ctx, promptArgs);
+    if (forward.kind !== "ok") {
+        return forward;
+    }
+    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, branch),
+        generationStatus: forward.value.generationStatus,
+        liveEditId: forward.value.liveEditId ?? session.liveEditId,
+        mode: promptArgs.mode,
+        name: await named(),
+        ...(forward.value.recentRuns && forward.value.recentRuns.length > 0
+            ? { recentRuns: forward.value.recentRuns }
+            : {}),
+        ...(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, 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" });
+    let created;
+    try {
+        created = await createApplicationForPrompt(ctx, {
+            apiKey: principal.apiKey,
+            deadlineAtMs: createDeadlineAtMs,
+            name,
+            organizationId: principal.organizationId,
+            ...(attachments ? { templateName: "app-fullstack" } : {}),
+        });
+    }
+    catch (error) {
+        releaseReplacementClaim?.();
+        throw error;
+    }
+    if (created.kind !== "ok") {
+        releaseReplacementClaim?.();
+        return created;
+    }
+    const app = created.value;
+    // The row is persisted from here on, so it is this caller's most recent app
+    // 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);
+    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,
+        principal,
+        prompt: input.prompt,
+    }));
+}
+/** Resolves symlinks where possible so containment is checked on real paths. */
+async function realPath(candidate) {
+    try {
+        return await realpath(candidate);
+    }
+    catch {
+        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;
+    }
+}
+/**
+ * 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);
+    for (const dir of searchDirs) {
+        const root = await realPath(dir);
+        // The separator matters: `~/downloads-evil` is not inside `~/downloads`.
+        if (file !== root && !file.startsWith(root + path.sep)) {
+            continue;
+        }
+        return readHostFile(file);
+    }
+    return undefined;
+}
+/**
+ * Reads the file by name from one of the configured search directories.
+ *
+ * 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.
+ */
+async function readFromSearchDirs(fileName, searchDirs) {
+    for (const dir of searchDirs) {
+        const found = await readWithinSearchDirs(path.join(dir, fileName), [dir]);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+function isLikelyModelSandboxPath(filePath) {
+    return (/^\/tmp\/claude-\d+\//.test(filePath) ||
+        filePath.includes("/-home-claude/") ||
+        filePath.startsWith("/mnt/user-data/"));
+}
+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 (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 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 hasFiles = Boolean(input.files?.length);
+    const hasPath = Boolean(input.filePath?.trim());
+    const hasBase64 = Boolean(input.zipBase64?.trim());
+    if (Number(hasFiles) + Number(hasPath) + Number(hasBase64) !== 1) {
+        return {
+            kind: "error",
+            code: "import_zip_required",
+            message: "Provide exactly one of files, filePath (a path or file name on the gateway host), or zipBase64.",
+        };
+    }
+    if (hasPath) {
+        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_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.`,
+            };
+        }
+        const archive = archiveSourceFiles(input.files);
+        if (archive.kind === "error") {
+            return {
+                kind: "error",
+                code: "import_files_invalid",
+                message: archive.message,
+            };
+        }
+        bytes = archive.bytes;
+    }
+    else {
+        try {
+            bytes = Buffer.from(input.zipBase64.trim(), "base64");
+        }
+        catch {
+            return {
+                kind: "error",
+                code: "import_zip_invalid",
+                message: "zipBase64 is not valid base64.",
+            };
+        }
+        if (bytes.byteLength === 0) {
+            return {
+                kind: "error",
+                code: "import_zip_invalid",
+                message: "zipBase64 decoded to an empty payload.",
+            };
+        }
+    }
+    if (bytes.byteLength > IMPORT_ZIP_MAX_BYTES) {
+        return tooLargeError(bytes.byteLength);
+    }
+    return {
+        kind: "ok",
+        value: {
+            bytes,
+            fileName: "import.zip",
+            mimeType: mimeTypeForArchiveType("zip"),
+        },
+    };
+}
+/** Reads a named file from the search dirs and names the type it uploads as. */
+async function resolveFileByPath(filePath, searchDirs) {
+    const fileName = path.basename(filePath);
+    let read;
+    if (path.isAbsolute(filePath)) {
+        read = await readHostFile(filePath);
+    }
+    read ??= await readFromSearchDirs(fileName, searchDirs);
+    if (read && "oversizeBytes" in read) {
+        return tooLargeError(read.oversizeBytes);
+    }
+    if (!read) {
+        const sandboxHint = isLikelyModelSandboxPath(filePath)
+            ? " 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.`,
+        };
+    }
+    if (read.bytes.byteLength > IMPORT_ZIP_MAX_BYTES) {
+        return tooLargeError(read.bytes.byteLength);
+    }
+    const archiveType = detectAttachmentArchiveType({ fileName });
+    if (archiveType !== null) {
+        return {
+            kind: "ok",
+            value: {
+                bytes: read.bytes,
+                fileName,
+                mimeType: mimeTypeForArchiveType(archiveType),
+            },
+        };
+    }
+    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 } };
+}
+/**
+ * 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.
+ */
+function isTextSourceFileName(sourcePath) {
+    const fileName = path.basename(sourcePath);
+    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;
+    ctx.onProgress?.({ message: "Uploading artifact", type: "progress" });
+    try {
+        const upload = await ctx.server.uploadAttachment({
+            apiKey: principalResult.value.apiKey,
+            bytes: archive.bytes,
+            fileName: archive.fileName,
+            mimeType: archive.mimeType,
+        });
+        return {
+            kind: "ok",
+            value: {
+                artifact: {
+                    fileName: upload.fileName,
+                    id: upload.attachmentId,
+                    mediaType: archive.mimeType,
+                    storageKey: upload.storageKey,
+                },
+            },
+        };
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            code: "artifact_upload_failed",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+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.
+ *
+ * Callers name the application alongside it. A cancelled wait says nothing
+ * about the work, which carries on: a caller asked to resume it has to be able
+ * to point at the application rather than start a second one.
+ */
+function cancelled(capability) {
+    return {
+        kind: "error",
+        code: "cancelled",
+        message: `${capability} was cancelled by the caller.`,
+    };
+}
+function nowMs(ctx) {
+    return (ctx.now ?? Date.now)();
+}
+/**
+ * The longest any single host-facing call may block.
+ *
+ * Independent of whether the host supports progress notifications, and
+ * 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 its
+ * current status instead of holding the line open.
+ */
+function hostCallBudgetMs(ctx, requestedMs) {
+    return Math.max(0, Math.min(requestedMs, ctx.config.hostCallCeilingMs));
+}
+/**
+ * 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 {
+        ...observed,
+        "turn.checkpoint_failed": Boolean(update.checkpointFailure),
+        ...(update.decision ? { "turn.decision_kind": update.decision.kind } : {}),
+        "turn.generation_status": update.generationStatus,
+    };
+}
+/**
+ * The last running update this poll saw, with `elapsedMs` advanced to now.
+ *
+ * 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 budget and stall hint.
+ */
+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 = {
+        "application.id": applicationId,
+        ...(requestedBranch ? { "turn.requested_branch": requestedBranch } : {}),
+    };
+    gatewayDebug("progress poll started", {
+        ...scope,
+        "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;
+    }
+    const principal = principalResult.value;
+    const resolved = await resolveApplicationId(ctx, principal, input.applicationId);
+    if (resolved.kind !== "ok") {
+        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 updateResult = await awaitTurns(ctx, requestedBranch, principal, applicationId, hostDeadlineAtMs);
+    if (updateResult.kind !== "ok") {
+        return updateResult;
+    }
+    const update = updateResult.value;
+    const elapsedSeconds = Math.round(update.elapsedMs / 1000);
+    const saidSomething = update.activity.length > 0;
+    const activity = update.status === "running" && !saidSomething
+        ? [`Superblocks is still generating`]
+        : update.activity;
+    for (const message of activity) {
+        ctx.onProgress?.({ message, type: "progress" });
+    }
+    const status = progressStatusOf(update);
+    const terminal = status !== "building";
+    const turnSignals = await recordTurnSignals(ctx, {
+        appScope: { applicationId, organizationId: principal.organizationId },
+        elapsedMs: update.elapsedMs,
+        // What Superblocks itself said, not what this poll is returning. The
+        // 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,
+        terminal,
+        turnRunning: update.status === "running",
+    });
+    const branch = update.branch ?? requestedBranch;
+    const base = {
+        ...turnSignals,
+        activity,
+        applicationId,
+        ...(branch ? { branch } : {}),
+        editUrl: editUrl(ctx.config, applicationId, branch),
+        elapsedSeconds,
+        ...(update.viewStatus ? { viewStatus: update.viewStatus } : {}),
+        ...("recentRuns" in update &&
+            Array.isArray(update.recentRuns) &&
+            update.recentRuns.length > 0
+            ? { recentRuns: update.recentRuns }
+            : {}),
+    };
+    if (update.status !== "finished") {
+        return {
+            kind: "ok",
+            value: {
+                ...base,
+                status,
+            },
+        };
+    }
+    ctx.onProgress?.({ message: turnSummary(update), type: "completed" });
+    return {
+        kind: "ok",
+        value: {
+            ...base,
+            ...(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.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,
+        },
+    };
+}
+/**
+ * When this build last said anything, as far as this turn is concerned.
+ *
+ * Read app-scoped rather than per-caller so two readers of one build cannot
+ * disagree about whether it has gone quiet, and never earlier than the turn
+ * started: the stored value outlives the turn that wrote it, so the gap
+ * between two turns — a user reading a plan before approving it — would
+ * otherwise be counted as this turn having gone quiet.
+ *
+ * A store that cannot answer costs a stall hint, not the poll, so it reads as
+ * "nothing heard since this turn began".
+ */
+async function lastActivityWithinTurn(ctx, input) {
+    try {
+        const observedAtMs = ctx.progress?.lastActivityAtMs(input.appScope);
+        return Math.max(observedAtMs ?? input.turnStartedAtMs, input.turnStartedAtMs);
+    }
+    catch (error) {
+        console.warn("gateway could not read when the build last spoke", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return input.turnStartedAtMs;
+    }
+}
+/**
+ * Records when the build last spoke, for every reader of it rather than the
+ * one that happened to hear it.
+ *
+ * Swallowed on failure for the same reason the live-edit pointer is: it costs
+ * a stall hint, and failing a progress poll over stall bookkeeping would trade
+ * a degraded answer for no answer at all.
+ */
+async function rememberLastActivity(ctx, input) {
+    try {
+        ctx.progress?.recordActivity(input);
+    }
+    catch (error) {
+        console.warn("gateway could not record when the build last spoke", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Derives the turn budget and stall hint, and records what this poll heard.
+ */
+async function recordTurnSignals(ctx, input) {
+    const quiet = !input.saidSomething && !input.terminal;
+    const currentTimeMs = nowMs(ctx);
+    const turnStartedAtMs = currentTimeMs - input.elapsedMs;
+    const lastActivityAtMs = input.saidSomething
+        ? currentTimeMs
+        : await lastActivityWithinTurn(ctx, {
+            appScope: input.appScope,
+            turnStartedAtMs,
+        });
+    const quietMs = Math.max(0, currentTimeMs - lastActivityAtMs);
+    const alreadyHinted = ctx.progress?.stallHintedAtMs(input.appScope) !== undefined;
+    const stallHint = quiet && !alreadyHinted && quietMs >= ctx.config.clarkStallHintAfterMs
+        ? { quietMs, reason: "long_quiet" }
+        : undefined;
+    if (input.saidSomething) {
+        await rememberLastActivity(ctx, {
+            ...input.appScope,
+            atMs: currentTimeMs,
+        });
+    }
+    // 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,
+        });
+    }
+    else if (!quiet) {
+        ctx.progress?.recordStallHint({
+            ...input.appScope,
+            atMs: undefined,
+        });
+    }
+    return {
+        ...(input.turnRunning
+            ? {
+                remainingTurnBudgetMs: Math.max(0, ctx.config.clarkTurnTimeoutMs - input.elapsedMs),
+            }
+            : {}),
+        ...(stallHint ? { stallHint } : {}),
+    };
+}
+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);
+    if (resolved.kind !== "ok") {
+        return resolved;
+    }
+    const applicationId = resolved.value;
+    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, 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. 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",
+            code: "prompt_required",
+            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);
+        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,
+            organizationId: principal.organizationId,
+        });
+    }
+    catch (error) {
+        const verdict = liveEditOpenFailureVerdict(error, {
+            kind: "existing_app",
+        });
+        rememberFailedStart(ctx, {
+            applicationId,
+            branch,
+            error,
+            idempotencyKey: input.idempotencyKey,
+            ...(args.pendingStartToken === undefined || refusedCaller(error)
+                ? {}
+                : {
+                    pendingStartRequired: true,
+                    pendingStartToken: args.pendingStartToken,
+                }),
+            principal,
+            revision,
+            ...(verdict.pendingAction === "retry_build"
+                ? { retryAction: verdict.retryAction }
+                : { reason: verdict.message, retryable: false }),
+        });
+        return liveEditUnavailable(verdict);
+    }
+    ctx.onProgress?.({
+        message: "Forwarding prompt to Superblocks",
+        type: "progress",
+    });
+    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, 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,
+        ...(attachments ? { attachments } : {}),
+        branch,
+        idempotencyKey: input.idempotencyKey,
+        liveEditId: session.liveEditId,
+        liveEditUrl: session.liveEditUrl,
+        mode: editTurnMode(input, answeringQuestion),
+        organizationId: principal.organizationId,
+        ...(args.pendingStartToken === undefined
+            ? {}
+            : {
+                pendingStartRequired: true,
+                pendingStartToken: args.pendingStartToken,
+            }),
+        prompt: promptForAttachedSource(input.prompt ?? "", attachments),
+        revision,
+        userId: principal.userId,
+    };
+    if (effectiveAction === "approve") {
+        if (pending?.plan) {
+            promptArgs = {
+                ...promptArgs,
+                mode: "BUILD",
+                planContext: {
+                    approved: true,
+                    plan: pending.plan,
+                    ...(pending.title ? { title: pending.title } : {}),
+                },
+                prompt: pending.plan,
+                // 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 (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
+            // its own context, so the caller's words (or a plain go-ahead) suffice.
+            promptArgs = {
+                ...promptArgs,
+                mode: "BUILD",
+                planContext: { approved: true },
+                prompt: input.prompt?.trim() ||
+                    "The plan is approved. Build it as described.",
+                // 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 {
+            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.",
+            };
+        }
+    }
+    else if (effectiveAction === "refine" && pending?.plan) {
+        promptArgs = {
+            ...promptArgs,
+            mode: "PLAN",
+            planContext: {
+                approved: false,
+                plan: pending.plan,
+                ...(pending.title ? { title: pending.title } : {}),
+            },
+            ...(pending.messageId
+                ? {
+                    responseMetadata: {
+                        approved: false,
+                        responseToMessageId: pending.messageId,
+                        type: "plan_response",
+                    },
+                }
+                : {}),
+        };
+    }
+    if (input.wait === "ack") {
+        const started = await startClarkPrompt(ctx, promptArgs);
+        if (started.kind !== "ok") {
+            return started;
+        }
+        await rememberApplication(ctx, principal, applicationId);
+        return {
+            kind: "ok",
+            value: await withBrowser(ctx, {
+                activity: started.value.activity,
+                applicationId,
+                ...(branch ? { branch } : {}),
+                editUrl: editUrl(ctx.config, applicationId, branch),
+                mode: promptArgs.mode,
+                status: "building",
+            }),
+        };
+    }
+    const forward = await forwardClarkPrompt(ctx, promptArgs);
+    if (forward.kind !== "ok") {
+        return forward;
+    }
+    await rememberApplication(ctx, principal, applicationId);
+    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, branch),
+        generationStatus: forward.value.generationStatus,
+        mode: promptArgs.mode,
+        ...(forward.value.recentRuns && forward.value.recentRuns.length > 0
+            ? { recentRuns: forward.value.recentRuns }
+            : {}),
+        ...(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, result),
+    };
+}
+/**
+ * Shows the app's current work on a real URL without deploying it - the
+ * editor's Preview button, driven from here.
+ *
+ * Three steps, the same ones and in the same order as the editor: snapshot the
+ * live-edit state as a commit, make sure a build exists for that commit's
+ * content, and hand back the URL that serves it. Builds are keyed on content
+ * rather than on the commit, so previewing work that was already built (by an
+ * earlier preview, or by a publish) waits on that build instead of starting a
+ * second one.
+ */
+export async function previewApp(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;
+    // Not "Committing current work": a preview commits whether or not Superblocks
+    // wrote anything, and saying there is work to commit before finding out is the
+    // gateway narrating an intention as a fact (ENG-5808).
+    ctx.onProgress?.({ message: "Preparing a preview", type: "progress" });
+    let commit;
+    try {
+        commit = await ctx.server.createCommit({
+            apiKey: principal.apiKey,
+            applicationId,
+            branch: input.branch,
+            message: "Preview",
+        });
+    }
+    catch (error) {
+        if (error instanceof ServerHttpError &&
+            (error.status === 401 || error.status === 403)) {
+            return elicitStepUp(ctx, `stepup:preview:${applicationId}`, applicationId, input.branch);
+        }
+        return {
+            kind: "error",
+            code: "commit_failed",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const directoryHash = commit.directoryHash;
+    if (!directoryHash) {
+        return {
+            kind: "error",
+            code: "preview_unavailable",
+            message: "This application has no directory contents to build, so it cannot be previewed. Only code-mode applications — the kind start_app creates — can be.",
+        };
+    }
+    const url = previewUrl(ctx.config, applicationId, commit.commitId);
+    const ready = await waitForBuild(ctx, {
+        apiKey: principal.apiKey,
+        applicationId,
+        commitId: commit.commitId,
+        directoryHash,
+        wait: input.wait !== false,
+    });
+    if (ready.kind !== "ok") {
+        return ready;
+    }
+    const gatewayChromium = await gatewayChromiumIsPresent(ctx);
+    const includeScreenshot = input.includeScreenshot !== false;
+    let jwt;
+    if (ctx.config.deployedShellBaseUrl ||
+        (includeScreenshot && ctx.capturePreviewScreenshot && gatewayChromium)) {
+        try {
+            jwt = await ctx.server.issueScopedToken({
+                apiKey: principal.apiKey,
+                applicationId,
+                commitId: commit.commitId,
+                scope: "apps:preview",
+            });
+        }
+        catch (error) {
+            console.warn("gateway preview scoped token failed; using UI preview URL", {
+                applicationId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const openable = buildOpenablePreviewUrls({
+        applicationId,
+        commitId: commit.commitId,
+        deployedShellBaseUrl: ctx.config.deployedShellBaseUrl,
+        jwt,
+        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;
+    // Always capture when the preview is ready and Gateway Chromium is present.
+    // urls_only must not wait on chromium.launch() (ENG-5858).
+    if (!includeScreenshot) {
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "live library capture will run instead",
+        });
+    }
+    else if (!ready.value.built) {
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "build not finished",
+        });
+    }
+    else if (!ctx.capturePreviewScreenshot) {
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "no capture backend configured",
+        });
+        needsBrowserDriver = true;
+    }
+    else if (!gatewayChromium) {
+        console.error("gateway preview screenshot skipped", {
+            applicationId,
+            reason: "no gateway chromium",
+        });
+        needsBrowserDriver = true;
+    }
+    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: jwt,
+                trustedOrigin: ctx.config.serverUrl,
+                url: captureUrl,
+            });
+            screenshotBase64 = shot?.dataBase64;
+            // A capture that soft-fails looks exactly like one that was never asked
+            // for, which is what made a missing demo screenshot undiagnosable.
+            console.error("gateway preview screenshot captured", {
+                applicationId,
+                base64Length: screenshotBase64?.length ?? 0,
+            });
+        }
+        catch (error) {
+            // Screenshot is optional; never fail get_app / preview_app for it.
+            console.warn("gateway preview screenshot threw; continuing with URLs", {
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const name = await applicationName(ctx, principal, applicationId);
+    await rememberApplication(ctx, principal, applicationId);
+    ctx.onProgress?.({
+        message: ready.value.built
+            ? `Preview ready: ${openable.previewUrl}`
+            : "Preview is still building",
+        type: "completed",
+    });
+    return {
+        kind: "ok",
+        value: await withBrowser(ctx, {
+            applicationId,
+            ...(input.branch ? { branch: input.branch } : {}),
+            commitId: commit.commitId,
+            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;
+    }
+    let progress;
+    try {
+        progress = await ctx.server.getBuildProgress({
+            apiKey: principalResult.value.apiKey,
+            applicationId: input.applicationId,
+            directoryHash: input.directoryHash,
+        });
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            code: "preview_build_failed",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const status = progress === "success"
+        ? "ready"
+        : progress === "failed" || progress === "timed_out"
+            ? "failed"
+            : "building";
+    return {
+        kind: "ok",
+        value: {
+            ...input,
+            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.
+ */
+async function applicationName(ctx, principal, applicationId) {
+    try {
+        return await ctx.server.getApplicationName({
+            apiKey: principal.apiKey,
+            applicationId,
+        });
+    }
+    catch (error) {
+        console.warn("gateway application name lookup failed", {
+            applicationId,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        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
+ * text), so approve and get_app can treat a decision-less needs_decision the
+ * same as a plan card instead of dead-ending or previewing the template.
+ */
+function awaitingDecision(ctx, 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":
+            return status;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Why the app cannot be previewed, read from the turn this process is holding.
+ */
+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" };
+    }
+    if (turn?.phase !== "finished") {
+        return undefined;
+    }
+    // Clark can end a turn awaiting the user having streamed its plan or question
+    // as ordinary chat text, so the collector captured no structured decision.
+    // The turn is still a decision - previewing here is what commits and builds
+    // the untouched template into a blank card.
+    if (turn.generationStatus === "needs_decision") {
+        return { kind: "awaiting_decision" };
+    }
+    // A turn that ended without a checkpoint wrote nothing, so the only thing
+    // left to preview is the template the app was created from - the blank card
+    // this gate exists to prevent.
+    if (turn.checkpointCommitId) {
+        return undefined;
+    }
+    const status = emptyTurnStatus(turn.generationStatus);
+    return status
+        ? {
+            kind: "empty_turn",
+            ...(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;
+}
+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 actualBranch = turn ? turn.branch : (pending?.branch ?? branch);
+    return { ...(actualBranch ? { branch: actualBranch } : {}), reason };
+}
+function currentTurnBranch(ctx, principal, applicationId, requestedBranch) {
+    const branch = normalizeBranch(requestedBranch);
+    const turn = ctx.sessionPeer.turnState({
+        applicationId,
+        branch,
+        organizationId: principal.organizationId,
+        userId: principal.userId,
+    });
+    if (turn) {
+        return turn.branch;
+    }
+    return ctx.appState.pendingDecision(applicationId, branch)?.branch ?? branch;
+}
+/**
+ * The answer `get_app` owes a caller while the app has nothing worth showing.
+ *
+ * Clark's headless default is PLAN, so a first prompt commonly ends on a plan
+ * or a question rather than on code. Previewing that state commits and builds
+ * 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, 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,
+        ...(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,
+                ...(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.pendingAction
+                    ? { pendingAction: reason.pendingAction }
+                    : {}),
+                ...(reason.reply ? { reply: reason.reply } : {}),
+                status: reason.status,
+            },
+        };
+    }
+    return {
+        kind: "ok",
+        value: {
+            ...app,
+            pendingAction: "wait_for_build",
+            status: "building",
+        },
+    };
+}
+/**
+ * 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);
+    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 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 = 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 (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: {
+                ...currentUnbuilt.value,
+                ...(liveShot.needsBrowserDriver ? { needsBrowserDriver: true } : {}),
+                ...(liveShot.screenshotBase64
+                    ? { screenshotBase64: liveShot.screenshotBase64 }
+                    : {}),
+            },
+        };
+    }
+    const name = await applicationName(ctx, principal, applicationId);
+    await rememberApplication(ctx, principal, applicationId);
+    const liveShot = await captureLiveLibraryIfNeeded(ctx, applicationId, live);
+    const previewUrl = fullscreenPreviewUrl(ctx.config, applicationId, branch);
+    return {
+        kind: "ok",
+        value: await withBrowser(ctx, {
+            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: "ready",
+        }),
+    };
+}
+/**
+ * Sees a build of this content through, starting one if none exists.
+ *
+ * `built: false` is not a failure: the build is still going and the caller has
+ * a URL that will work once it lands. Bounded by the publish wait budget — the
+ * same SABS build a publish waits on, so the same patience applies.
+ */
+async function waitForBuild(ctx, input) {
+    // Clamped to the host ceiling even though the build's own budget is far
+    // longer. A wait that outlives the host's tool-call timeout is not patience,
+    // it is a call nobody is left to read the answer of.
+    const deadline = nowMs(ctx) + hostCallBudgetMs(ctx, ctx.config.publishWaitTimeoutMs);
+    let started = false;
+    for (;;) {
+        if (ctx.signal?.aborted) {
+            return namingApplication(input.applicationId, cancelled("get_app"));
+        }
+        // Checked before the network call, not only after it: a budget already
+        // exhausted when this loop begins (or used up by the previous
+        // iteration's own round trip) should not pay for a poll whose answer is
+        // discarded the moment it arrives.
+        if (nowMs(ctx) >= deadline) {
+            return { kind: "ok", value: { built: false } };
+        }
+        let progress;
+        try {
+            progress = await ctx.server.getBuildProgress({
+                apiKey: input.apiKey,
+                applicationId: input.applicationId,
+                directoryHash: input.directoryHash,
+            });
+        }
+        catch (error) {
+            return {
+                kind: "error",
+                code: "preview_build_failed",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        if (progress === "success") {
+            return { kind: "ok", value: { built: true } };
+        }
+        // A build this call started and that then reported failure is a real
+        // failure. One that was already failed when we arrived is a stale result
+        // for the same content, and starting a fresh build is what the editor does.
+        if ((progress === "failed" || progress === "timed_out") && started) {
+            return {
+                kind: "error",
+                code: "preview_build_failed",
+                message: `The build for this application ${progress === "timed_out" ? "timed out" : "failed"}. Open the app in the editor to see why.`,
+            };
+        }
+        if (progress !== "running" && !started) {
+            ctx.onProgress?.({ message: "Building a preview", type: "progress" });
+            try {
+                await ctx.server.createBuild({
+                    apiKey: input.apiKey,
+                    applicationId: input.applicationId,
+                    commitId: input.commitId,
+                    directoryHash: input.directoryHash,
+                });
+            }
+            catch (error) {
+                return {
+                    kind: "error",
+                    code: "preview_build_failed",
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+            started = true;
+        }
+        // The caller asked to be told where the build stands, not to be held here
+        // until it lands. Starting it above is the whole of the work; a second
+        // look would be the first iteration of a wait it declined.
+        if (!input.wait || nowMs(ctx) >= deadline) {
+            return { kind: "ok", value: { built: false } };
+        }
+        ctx.onProgress?.({
+            message: "Waiting for the preview build…",
+            type: "progress",
+        });
+        // Never sleep past the deadline: the ceiling reserves the tail of the
+        // host's patience for the answer to be written and read, and a full poll
+        // interval spent past it comes out of that reserve.
+        await sleepUntilAbort(Math.min(ctx.config.publishPollIntervalMs, deadline - nowMs(ctx)), ctx.signal);
+    }
+}
+export async function publishApp(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;
+    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.publishClaim),
+        publishDetailsUrl: publishDetailsUrl(ctx.config, input.applicationId, input.commitId),
+        publishUrl: publishUrl(ctx.config, input.applicationId),
+        status: "publishing",
+    };
+}
+function publishElapsedSeconds(ctx, applicationId, publishClaim) {
+    const startedAtMs = publishClaim === undefined
+        ? undefined
+        : ctx.appState.publishStartedAtMs(applicationId, publishClaim);
+    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 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, publishClaim);
+                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,
+                    publishClaim,
+                }),
+            };
+        }
+        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 = requestedCommitId;
+    if (!commitId) {
+        ctx.onProgress?.({ message: "Committing current work", type: "progress" });
+        try {
+            const commit = await ctx.server.createCommit({
+                apiKey: principal.apiKey,
+                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",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    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.appState.clearPublishInFlight(applicationId, publishClaim);
+            ctx.sessionPeer.release(applicationId);
+            return {
+                kind: "error",
+                code: "publish_failed",
+                message: deployment.message ?? "The Superblocks API could not deploy the app.",
+            };
+        }
+        if (deployment.status === "awaiting_ack") {
+            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.`,
+            };
+        }
+        if (deployment.status === "queued") {
+            ctx.onProgress?.({
+                message: "Waiting for deploy…",
+                type: "progress",
+            });
+            const waited = await waitForDeployLive(ctx, {
+                apiKey: principal.apiKey,
+                applicationId,
+                commitId,
+                deadlineAtMs,
+                publishClaim,
+            });
+            if (waited.kind !== "ok") {
+                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,
+                        publishClaim,
+                    }),
+                };
+            }
+        }
+        await rememberApplication(ctx, principal, applicationId);
+        // Deploy finished — the held editor socket is no longer needed.
+        ctx.sessionPeer.release(applicationId);
+        const elapsed = publishElapsedSeconds(ctx, applicationId, publishClaim);
+        ctx.appState.clearPublishInFlight(applicationId, publishClaim);
+        const result = {
+            applicationId,
+            commitId,
+            ...elapsed,
+            publishDetailsUrl: publishDetailsUrl(ctx.config, applicationId, commitId),
+            publishUrl: publishUrl(ctx.config, applicationId),
+            status: "deployed",
+        };
+        ctx.onProgress?.({
+            message: "Publish complete — app is live",
+            type: "completed",
+        });
+        return { kind: "ok", value: result };
+    }
+    catch (error) {
+        // Step up on the status the server actually returned. Matching words in the
+        // message instead would send a "token count exceeded" 500 or anything
+        // mentioning an author through a re-auth flow and bury the real failure.
+        if (error instanceof ServerHttpError &&
+            (error.status === 401 || error.status === 403)) {
+            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: "ok",
+            value: stillPublishing(ctx, {
+                applicationId,
+                commitId,
+                publishClaim,
+            }),
+        };
+    }
+}
+//# sourceMappingURL=lifecycle.js.map