@superblocksteam/gateway 2.0.167-next.0 → 2.0.169-next.0

package/dist/capabilities/lifecycle.js

@@ -5,6 +5,7 @@ import { detectAttachmentArchiveType, getAttachmentMimeTypeFromFileName, getText
 import { buildBrowserDriverContract, HOST_BROWSER_TOOLS_COWORK, needsBrowserDriverError, } from "../capture/browser-contract.js";
 import { withCoworkEditorHost } from "../capture/cowork-editor-url.js";
 import { resolveCaptureMode } from "../capture/mode.js";
+import { withDeadline } from "../deadline.js";
 import { gatewayDebug } from "../debug.js";
 import { playwrightChromiumPresent } from "../playwright/ensure-chromium.js";
 import { isTrustedEmbedOrigin, } from "../preview/capture-screenshot.js";
@@ -13,6 +14,7 @@ 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 { TOOL_PERMISSION_ANSWERS, ToolPermissionReply, } from "./tool-permission-reply.js";
 import { buildStatusOf, progressStatusOf } from "./types.js";
 import { IMPORT_ZIP_MAX_BYTES } from "./types.js";
 export { IMPORT_ZIP_MAX_BYTES } from "./types.js";
@@ -66,8 +68,8 @@ async function captureModeOf(ctx) {
         hostMcpConfigured: ctx.config.captureHostMcp,
     });
 }
-function libraryCaptureInput(ctx, applicationId, branch) {
-    const context = ctx.sessionPeer.libraryBrowserContext(applicationId, branch);
+async function libraryCaptureInput(ctx, applicationId, branch) {
+    const context = await ctx.sessionPeer.libraryBrowserContext(applicationId, branch);
     if (!context) {
         return undefined;
     }
@@ -115,30 +117,71 @@ function libraryCaptureInput(ctx, applicationId, branch) {
         },
     };
 }
+function heldSocketFor(ctx, applicationId, branch) {
+    const held = ctx.sessionPeer.heldContext(applicationId);
+    if (!held) {
+        return "none";
+    }
+    return held.branch === branch ? "this_branch" : "other_branch";
+}
 /**
- * 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).
+ * `branch` is the branch the read resolved to, undefined for the default
+ * branch: a socket held for any other branch cannot answer for this read.
+ *
+ * A cold live edit can take minutes to attach. Past `deadlineAtMs` the read
+ * answers from what the gateway already knows, and the attach carries on so
+ * the next read finds the session held.
  */
-async function ensureLibraryCaptureInput(ctx, principal, applicationId, branch) {
-    const existing = libraryCaptureInput(ctx, applicationId, branch);
-    if (existing) {
-        return existing;
-    }
-    if (ctx.appState.pendingStart({
+async function ensureLiveState(ctx, principal, applicationId, branch, deadlineAtMs) {
+    const scope = {
         applicationId,
-        ...(branch ? { branch } : {}),
+        branch,
         organizationId: principal.organizationId,
         userId: principal.userId,
-    })) {
-        return undefined;
-    }
-    if (!(await gatewayChromiumIsPresent(ctx))) {
-        console.error("gateway live canvas skipped: chromium_absent_no_rehold", {
+    };
+    const held = ctx.sessionPeer.heldContext(applicationId);
+    if ((held &&
+        held.branch === branch &&
+        !ctx.liveStateAttaches.isAttaching(scope)) ||
+        ctx.appState.pendingStart(scope) ||
+        ctx.sessionPeer.turnState(scope)?.phase === "running") {
+        return { kind: "ok", value: undefined };
+    }
+    const activeTurn = ctx.sessionPeer.turnState({ ...scope, branch: undefined });
+    if (activeTurn?.phase === "running" ||
+        ctx.appState.pendingStart({ ...scope, branch: undefined })) {
+        return {
             applicationId,
-        });
-        return undefined;
+            code: "live_edit_unavailable",
+            kind: "error",
+            message: "Another branch is building. Wait for it to finish before reading this branch.",
+        };
+    }
+    return await withDeadline(ctx.liveStateAttaches.run(scope, () => attachLiveState(ctx, principal, scope)), Math.max(0, deadlineAtMs - nowMs(ctx)), () => ({ kind: "ok", value: undefined }));
+}
+/**
+ * Whether a read may answer from what this process knows when the editor
+ * state could not be refreshed. A running turn is followed on its own socket
+ * and a recorded dead start is this process's own account. Beyond those, only
+ * a decision or a finished turn can have been overtaken in the editor. With
+ * neither there is nothing a refresh could correct, and failing the read
+ * would turn another user's edit or a full sandbox pool into an error on an
+ * app that is simply ready.
+ */
+function knownStateAnswersWithoutRefresh(ctx, scope) {
+    const turn = ctx.sessionPeer.turnState(scope);
+    if (turn?.phase === "running" || ctx.appState.failedStart(scope)) {
+        return true;
     }
+    return (turn === undefined &&
+        !ctx.appState.pendingDecision(scope.applicationId, scope.branch) &&
+        !ctx.appState.pendingPlan(scope.applicationId, scope.branch));
+}
+async function attachLiveState(ctx, principal, scope) {
+    const { applicationId, branch } = scope;
     try {
+        // TODO(AR-593): read-only tools reach this attach, which can start the
+        // caller's sandbox and take a free editor lock for the read hold.
         const session = await openLiveEdit(ctx, {
             apiKey: principal.apiKey,
             applicationId,
@@ -175,17 +218,24 @@ async function ensureLibraryCaptureInput(ctx, principal, applicationId, branch)
         });
     }
     catch (error) {
-        console.error("gateway live canvas skipped: rehold_failed", {
+        const message = error instanceof Error ? error.message : String(error);
+        const answeredWithoutRefresh = knownStateAnswersWithoutRefresh(ctx, scope);
+        console.error("gateway live state refresh failed", {
+            answeredWithoutRefresh,
             applicationId,
-            message: error instanceof Error ? error.message : String(error),
+            message,
         });
-        return undefined;
-    }
-    const live = libraryCaptureInput(ctx, applicationId, branch);
-    if (!live) {
-        console.error("gateway live canvas skipped: context_incomplete_after_rehold", { applicationId });
+        if (answeredWithoutRefresh) {
+            return { kind: "ok", value: undefined };
+        }
+        return {
+            applicationId,
+            code: "live_edit_unavailable",
+            kind: "error",
+            message: `Could not refresh the editor state: ${message}`,
+        };
     }
-    return live;
+    return { kind: "ok", value: undefined };
 }
 async function captureLiveLibraryIfNeeded(ctx, applicationId, live) {
     if (!live) {
@@ -623,14 +673,6 @@ async function waitForDeployLive(ctx, input) {
  * 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";
@@ -639,6 +681,7 @@ function pendingActionForDecision(decision) {
         case "missing_integrations":
             return "create_integration";
         case "multi_choice":
+        case "tool_permission":
             return "answer_question";
         case "plan":
             return "approve_plan";
@@ -670,6 +713,9 @@ function decisionSummary(decision) {
     if (decision.kind === "multi_choice") {
         return "Superblocks asked the user a question and stopped.";
     }
+    if (decision.kind === "tool_permission") {
+        return "Superblocks needs a user approval decision before it can continue.";
+    }
     const unhandled = decision;
     return unhandled;
 }
@@ -1265,7 +1311,30 @@ async function runAcknowledgedStart(ctx, args) {
             // prompt went out.
             args.approvalSettlement?.onNotSent();
         }
-        if (result.kind === "error" && result.code === "reinvoke_required") {
+        if (result.kind === "error" &&
+            (result.code === "plan_approval_stale" ||
+                result.code === "tool_permission_pending" ||
+                result.code === "tool_permission_stale")) {
+            const currentDecision = ctx.appState.pendingDecision(args.applicationId, args.branch);
+            // A cleared decision leaves the live edit healthy: only the approval
+            // target went away, so the turn reads as ended, not terminal.
+            rememberFailedStart(ctx, {
+                applicationId: args.applicationId,
+                branch: args.branch,
+                ...(currentDecision ? { decision: currentDecision.decision } : {}),
+                error: new Error(result.message),
+                generationStatus: currentDecision ? "needs_decision" : "no_changes",
+                idempotencyKey: args.idempotencyKey,
+                pendingStartRequired: true,
+                pendingStartToken: args.pendingStartToken,
+                principal: args.principal,
+                reason: currentDecision
+                    ? result.message
+                    : "The approval request is no longer pending, so this response was not sent to Superblocks.",
+                revision: args.pendingStartToken,
+            });
+        }
+        else 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" ||
@@ -1704,6 +1773,10 @@ function nowMs(ctx) {
 function hostCallBudgetMs(ctx, requestedMs) {
     return Math.max(0, Math.min(requestedMs, ctx.config.hostCallCeilingMs));
 }
+/** When a call that starts now has to have answered by. */
+function hostCallDeadlineAtMs(ctx) {
+    return nowMs(ctx) + Math.max(0, ctx.config.hostCallCeilingMs);
+}
 /**
  * How long the next turn must collect activity for before it may answer.
  *
@@ -1868,7 +1941,7 @@ async function awaitTurns(ctx, requestedBranch, principal, applicationId, hostDe
     }
 }
 export async function checkAppProgress(ctx, input) {
-    const hostDeadlineAtMs = nowMs(ctx) + Math.max(0, ctx.config.hostCallCeilingMs);
+    const hostDeadlineAtMs = hostCallDeadlineAtMs(ctx);
     const principalResult = await ensurePrincipal(ctx);
     if (principalResult.kind !== "ok") {
         return principalResult;
@@ -1886,11 +1959,18 @@ export async function checkAppProgress(ctx, input) {
     if (ctx.signal?.aborted) {
         return namingApplication(applicationId, cancelled("check_app_progress"));
     }
+    const refreshed = await ensureLiveState(ctx, principal, applicationId, currentTurnBranch(ctx, principal, applicationId, requestedBranch), hostDeadlineAtMs);
+    if (refreshed.kind !== "ok") {
+        return refreshed;
+    }
     const updateResult = await awaitTurns(ctx, requestedBranch, principal, applicationId, hostDeadlineAtMs);
     if (updateResult.kind !== "ok") {
         return updateResult;
     }
     const update = updateResult.value;
+    const untracked = update.status === "unknown"
+        ? await untrackedStatus(ctx, principal, applicationId, requestedBranch)
+        : undefined;
     const elapsedSeconds = Math.round(update.elapsedMs / 1000);
     const saidSomething = update.activity.length > 0;
     const activity = update.status === "running" && !saidSomething
@@ -1899,7 +1979,7 @@ export async function checkAppProgress(ctx, input) {
     for (const message of activity) {
         ctx.onProgress?.({ message, type: "progress" });
     }
-    const status = progressStatusOf(update);
+    const status = untracked?.status ?? progressStatusOf(update);
     const terminal = status !== "building";
     const turnSignals = await recordTurnSignals(ctx, {
         appScope: { applicationId, organizationId: principal.organizationId },
@@ -1911,7 +1991,7 @@ export async function checkAppProgress(ctx, input) {
         saidSomething,
         terminal,
     });
-    const branch = update.branch ?? requestedBranch;
+    const branch = update.branch ?? untracked?.branch ?? requestedBranch;
     const base = {
         ...turnSignals,
         activity,
@@ -1931,6 +2011,7 @@ export async function checkAppProgress(ctx, input) {
             kind: "ok",
             value: {
                 ...base,
+                ...untracked,
                 status,
             },
         };
@@ -1949,21 +2030,16 @@ export async function checkAppProgress(ctx, input) {
             ...(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 }
-                                : {}
-                            : {}),
+            ...(planQuestionOutcome(update) ?? {
+                reply: update.reply,
+                ...(update.checkpointFailure
+                    ? { pendingAction: "open_editor" }
+                    : status === "needs_decision"
+                        ? { pendingAction: pendingActionForDecision(update.decision) }
+                        : emptyTurnRecovery(update)),
+            }),
             status,
             viewStatus: update.viewStatus,
         },
@@ -2079,10 +2155,55 @@ function stalePlanApproval(applicationId) {
 function planApprovalChanged(approvedPlan, pendingPlan) {
     return approvedPlan !== undefined && pendingPlan !== approvedPlan;
 }
+// These messages stay host-neutral: the host-specific way to answer comes from
+// the tool's agentInstructions, which know whether the host can collect an
+// approval at all.
+function ambiguousToolPermissionReply(applicationId) {
+    return {
+        applicationId,
+        kind: "error",
+        code: "tool_permission_reply_ambiguous",
+        message: `This reply to the pending permission is neither an approval nor a decline, so nothing was sent to Superblocks. Answer with permissionMessageId set to decision.messageId and ${TOOL_PERMISSION_ANSWERS}.`,
+    };
+}
+function pendingToolPermission(applicationId) {
+    return {
+        applicationId,
+        kind: "error",
+        code: "tool_permission_pending",
+        message: `Superblocks is waiting on a permission request, so it cannot take a new prompt yet. Answer it with permissionMessageId set to decision.messageId: \`Decline: <the new instruction>\` to replace it with a new instruction, or ${TOOL_PERMISSION_ANSWERS}.`,
+    };
+}
+function staleToolPermissionResponse(applicationId) {
+    return {
+        applicationId,
+        kind: "error",
+        code: "tool_permission_stale",
+        message: "This permission request is no longer current, so nothing was sent to Superblocks. Get the current request from check_app_progress and follow its instructions.",
+    };
+}
 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);
+    const pendingInteractive = pendingInteractiveDecision(ctx, applicationId, branch);
+    const answeringQuestion = Boolean(pendingInteractive);
+    const answeringToolPermission = pendingInteractive?.kind === "tool_permission";
+    const permissionMismatch = () => {
+        const current = pendingInteractiveDecision(ctx, applicationId, branch);
+        const pendingPermission = current?.kind === "tool_permission" ? current : undefined;
+        if (input.permissionMessageId === undefined) {
+            return pendingPermission
+                ? pendingToolPermission(applicationId)
+                : undefined;
+        }
+        return pendingPermission?.messageId === input.permissionMessageId
+            ? undefined
+            : staleToolPermissionResponse(applicationId);
+    };
+    const mismatchBeforeOpen = permissionMismatch();
+    if (mismatchBeforeOpen) {
+        return mismatchBeforeOpen;
+    }
     // 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
@@ -2095,6 +2216,12 @@ async function promptExistingApplication(ctx, args) {
             message: 'edit_app needs a prompt, unless planAction is "approve" (Build it) for a pending plan.',
         };
     }
+    const permissionReply = answeringToolPermission
+        ? ToolPermissionReply.parse(input.prompt ?? "")
+        : undefined;
+    if (permissionReply?.isAmbiguous) {
+        return ambiguousToolPermissionReply(applicationId);
+    }
     const pendingBeforeOpen = ctx.appState.pendingPlan(applicationId, branch);
     if (planApprovalChanged(approvedPlan, pendingBeforeOpen)) {
         return stalePlanApproval(applicationId);
@@ -2157,7 +2284,7 @@ async function promptExistingApplication(ctx, args) {
                 applicationId,
                 ...(branch ? { branch } : {}),
                 editUrl: editUrl(ctx, applicationId, branch),
-                mode,
+                ...(answeringToolPermission ? {} : { mode }),
                 status: "building",
             }),
         };
@@ -2201,25 +2328,12 @@ async function promptExistingApplication(ctx, args) {
         type: "progress",
     });
     const pending = ctx.appState.pendingPlan(applicationId, branch);
+    const mismatchAfterOpen = permissionMismatch();
+    if (mismatchAfterOpen) {
+        return mismatchAfterOpen;
+    }
     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;
+        return stalePlanApproval(applicationId);
     }
     // 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
@@ -2253,6 +2367,12 @@ async function promptExistingApplication(ctx, args) {
         revision,
         userId: principal.userId,
     };
+    if (permissionReply && pendingInteractive?.kind === "tool_permission") {
+        promptArgs = {
+            ...promptArgs,
+            responseMetadata: permissionReply.responseMetadata(pendingInteractive.messageId),
+        };
+    }
     if (effectiveAction === "approve") {
         if (pending?.plan) {
             promptArgs = {
@@ -2341,7 +2461,7 @@ async function promptExistingApplication(ctx, args) {
                 applicationId,
                 ...(branch ? { branch } : {}),
                 editUrl: editUrl(ctx, applicationId, branch),
-                mode: promptArgs.mode,
+                ...(answeringToolPermission ? {} : { mode: promptArgs.mode }),
                 status: "building",
             }),
         };
@@ -2384,7 +2504,7 @@ async function promptExistingApplication(ctx, args) {
         ...(forward.value.decision ? { decision: forward.value.decision } : {}),
         editUrl: editUrl(ctx, applicationId, branch),
         generationStatus: forward.value.generationStatus,
-        mode: promptArgs.mode,
+        ...(answeringToolPermission ? {} : { mode: promptArgs.mode }),
         ...(forward.value.recentRuns && forward.value.recentRuns.length > 0
             ? { recentRuns: forward.value.recentRuns }
             : {}),
@@ -2687,9 +2807,12 @@ async function applicationName(ctx, principal, applicationId) {
         return undefined;
     }
 }
-function pendingQuestion(ctx, applicationId, branch) {
-    return (ctx.appState.pendingDecision(applicationId, branch)?.decision.kind ===
-        "multi_choice");
+function pendingInteractiveDecision(ctx, applicationId, branch) {
+    const pending = ctx.appState.pendingDecision(applicationId, branch)?.decision;
+    if (pending?.kind === "multi_choice" || pending?.kind === "tool_permission") {
+        return pending;
+    }
+    return undefined;
 }
 function editTurnMode(input, pendingQuestion) {
     if (pendingQuestion) {
@@ -2710,6 +2833,66 @@ function awaitingDecision(ctx, scope) {
     const turn = ctx.sessionPeer.turnState(scope);
     return (turn?.phase === "finished" && turn.generationStatus === "needs_decision");
 }
+/**
+ * How a finished Plan turn that changed nothing and owes the host no other step
+ * reads on both `check_app_progress` and `get_app`, or undefined for any other
+ * turn.
+ *
+ * Plan turns cannot write, so one that answered has nothing to retry: its reply
+ * is the answer. One that ended on status labels, reasoning, or silence
+ * answered nothing, so it offers no reply to relay and asks to be run again. A
+ * turn that carries a decision, such as integrations to create, or a failed
+ * checkpoint keeps the step that decision or failure calls for.
+ */
+function planQuestionOutcome(turn) {
+    if (turn.generationStatus !== "no_changes" ||
+        turn.mode !== "PLAN" ||
+        turn.decision ||
+        turn.checkpointFailure) {
+        return undefined;
+    }
+    if (!turn.answered) {
+        return { pendingAction: turn.retryAction ?? "retry_build" };
+    }
+    return turn.reply ? { reply: turn.reply } : {};
+}
+/**
+ * What a turn that wrote nothing asks the host to do next, read the same way
+ * by `check_app_progress` and `get_app`, or undefined for any other turn.
+ *
+ * A turn a newer prompt replaced is never sent again: that would replace the
+ * newer turn in turn. Otherwise an explicit retry wins, a turn that cannot be
+ * retried offers its recovery, if any, a start that never reached Superblocks
+ * offers only the retry it names, and a turn that has nothing to send again
+ * offers no retry (see {@link settledWithoutRetry}). Every other empty turn is
+ * sent again.
+ */
+function emptyTurnRecovery(turn) {
+    if (turn.checkpointCommitId || !emptyTurnStatus(turn.generationStatus)) {
+        return undefined;
+    }
+    if (turn.replaced) {
+        return {};
+    }
+    if (turn.retryAction) {
+        return { pendingAction: turn.retryAction };
+    }
+    if (turn.retryable === false) {
+        return turn.recoveryAction ? { pendingAction: turn.recoveryAction } : {};
+    }
+    return turn.startFailed || settledWithoutRetry(turn)
+        ? {}
+        : { pendingAction: "retry_build" };
+}
+/**
+ * Whether sending an empty turn's prompt again would do no good: the turn may
+ * still be running elsewhere (detached), or it answered in text without
+ * writing, so the same prompt would most likely get the same answer.
+ */
+function settledWithoutRetry(turn) {
+    return (turn.generationStatus === "detached" ||
+        (turn.answered === true && turn.generationStatus === "no_changes"));
+}
 function emptyTurnStatus(status) {
     switch (status) {
         case "cancelled":
@@ -2755,16 +2938,10 @@ function localUnbuiltReason(turn, pending) {
     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 } : {}),
+            ...(planQuestionOutcome(turn) ?? {
+                ...emptyTurnRecovery(turn),
+                ...(turn.reply ? { reply: turn.reply } : {}),
+            }),
             status,
         }
         : undefined;
@@ -2823,52 +3000,64 @@ async function unbuiltApp(ctx, principal, applicationId, requestedBranch) {
         editUrl: editUrl(ctx, 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,
+    return {
+        kind: "ok",
+        value: {
+            ...app,
+            ...unbuiltStatus(ctx, applicationId, actualBranch, reason),
+        },
+    };
+}
+/**
+ * How an app that cannot be previewed reads as a status. `get_app` reports
+ * this, and so does a `check_app_progress` that has no turn to follow, so the
+ * two reads cannot disagree about the same editor state.
+ */
+function unbuiltStatus(ctx, applicationId, branch, reason) {
+    switch (reason.kind) {
+        case "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, branch, reason.decision);
+            return {
                 ...(decision ? { decision } : {}),
                 pendingAction: pendingActionForDecision(decision),
                 status: "needs_decision",
-            },
-        };
-    }
-    if (reason.kind === "checkpoint_failed") {
-        return {
-            kind: "ok",
-            value: {
-                ...app,
+            };
+        }
+        case "checkpoint_failed":
+            return {
                 checkpointFailure: reason.failure,
                 pendingAction: "open_editor",
                 status: "checkpoint_failed",
-            },
-        };
-    }
-    if (reason.kind === "empty_turn") {
-        return {
-            kind: "ok",
-            value: {
-                ...app,
+            };
+        case "empty_turn":
+            return {
                 ...(reason.pendingAction
                     ? { pendingAction: reason.pendingAction }
                     : {}),
                 ...(reason.reply ? { reply: reason.reply } : {}),
                 status: reason.status,
-            },
-        };
+            };
+        case "running":
+            return { pendingAction: "wait_for_build", status: "building" };
+    }
+}
+/**
+ * What `check_app_progress` reports when this process has no turn to follow:
+ * the editor state the read just refreshed, read as `get_app` reads it. An app
+ * with nothing to follow and nothing unbuilt is ready.
+ */
+async function untrackedStatus(ctx, principal, applicationId, requestedBranch) {
+    const state = await unbuiltReason(ctx, principal, applicationId, requestedBranch);
+    if (!state) {
+        return { status: "ready" };
     }
+    const branch = state.branch ?? requestedBranch;
     return {
-        kind: "ok",
-        value: {
-            ...app,
-            pendingAction: "wait_for_build",
-            status: "building",
-        },
+        ...(branch ? { branch } : {}),
+        ...unbuiltStatus(ctx, applicationId, branch, state.reason),
     };
 }
 /**
@@ -2903,6 +3092,7 @@ function decisionToPutToTheUser(ctx, applicationId, branch, decision) {
  * this on the poll loop would flash a blank form through a whole build.
  */
 export async function askUser(ctx, input) {
+    const hostDeadlineAtMs = hostCallDeadlineAtMs(ctx);
     const principalResult = await ensurePrincipal(ctx);
     if (principalResult.kind !== "ok") {
         return principalResult;
@@ -2913,6 +3103,10 @@ export async function askUser(ctx, input) {
         return resolved;
     }
     const applicationId = resolved.value;
+    const refreshed = await ensureLiveState(ctx, principal, applicationId, currentTurnBranch(ctx, principal, applicationId, input.branch), hostDeadlineAtMs);
+    if (refreshed.kind !== "ok") {
+        return refreshed;
+    }
     const unbuilt = await unbuiltApp(ctx, principal, applicationId, input.branch);
     const branch = unbuilt?.value.branch ??
         currentTurnBranch(ctx, principal, applicationId, input.branch);
@@ -2954,6 +3148,7 @@ export async function askUser(ctx, input) {
  * Read the app's current live editor view without committing or building it.
  */
 export async function getApp(ctx, input) {
+    const hostDeadlineAtMs = hostCallDeadlineAtMs(ctx);
     const principalResult = await ensurePrincipal(ctx);
     if (principalResult.kind !== "ok") {
         return principalResult;
@@ -2965,31 +3160,38 @@ export async function getApp(ctx, input) {
     }
     const applicationId = resolved.value;
     const includeScreenshot = input.includeScreenshot !== false;
+    const refreshed = await ensureLiveState(ctx, principal, applicationId, currentTurnBranch(ctx, principal, applicationId, input.branch), hostDeadlineAtMs);
+    if (refreshed.kind !== "ok") {
+        return refreshed;
+    }
     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)
+        ? await libraryCaptureInput(ctx, applicationId, branch)
         : undefined;
-    const currentUnbuilt = includeScreenshot && mayCapture
-        ? await unbuiltApp(ctx, principal, applicationId, input.branch)
-        : unbuilt;
-    if (currentUnbuilt) {
+    if (includeScreenshot && mayCapture && !live) {
+        console.error("gateway live canvas skipped: no_live_context", {
+            applicationId,
+            held: heldSocketFor(ctx, applicationId, branch),
+        });
+    }
+    if (unbuilt) {
         // 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" ||
+        if (unbuilt.value.status !== "building" ||
             !live ||
-            (currentUnbuilt.value.branch ?? normalizeBranch(input.branch)) !== branch) {
-            return currentUnbuilt;
+            (unbuilt.value.branch ?? normalizeBranch(input.branch)) !== branch) {
+            return unbuilt;
         }
         const liveShot = await captureLiveLibraryIfNeeded(ctx, applicationId, live);
         return {
             kind: "ok",
             value: {
-                ...currentUnbuilt.value,
+                ...unbuilt.value,
                 ...(liveShot.needsBrowserDriver ? { needsBrowserDriver: true } : {}),
                 ...(liveShot.screenshotBase64
                     ? { screenshotBase64: liveShot.screenshotBase64 }