@bivy/bivy 0.17.2 → 0.17.3-staging.10

package/dist/controllers/app-commands.js

@@ -1,16 +1,29 @@
 export function createAppCommands(service, workspaceFor, published = () => { }) {
+    const workspaceOf = (sessionId) => {
+        const workspace = workspaceFor(sessionId);
+        if (!workspace)
+            throw new Error("Open the session on this machine before publishing an app.");
+        return workspace;
+    };
     const operations = {
         "apps.list": (msg) => service.list(String(msg.sessionId)),
         "apps.publish": (msg) => {
             const sessionId = String(msg.sessionId);
-            const workspace = workspaceFor(sessionId);
-            if (!workspace)
-                throw new Error("Open the session on this machine before publishing an app.");
-            const app = service.publish(sessionId, workspace, msg.manifest);
+            const app = service.publish(sessionId, workspaceOf(sessionId), msg.manifest);
+            published(app);
+            return { app };
+        },
+        "apps.offers": (msg) => service.offers(String(msg.sessionId), workspaceOf(String(msg.sessionId))),
+        "apps.adopt": async (msg) => {
+            const sessionId = String(msg.sessionId);
+            const app = await service.adopt(sessionId, workspaceOf(sessionId), Number(msg.port));
             published(app);
             return { app };
         },
-        "apps.open": (msg) => service.open(String(msg.sessionId), String(msg.appId), String(msg.viewId), typeof msg.returnTo === "string" ? msg.returnTo : undefined),
+        "apps.open": (msg) => service.open(String(msg.sessionId), String(msg.appId), String(msg.viewId), typeof msg.returnTo === "string" ? msg.returnTo : undefined, msg.direct === true, typeof msg.scale === "number" ? msg.scale : undefined),
+        "apps.shot": (msg) => service.shot(String(msg.sessionId), typeof msg.appId === "string" ? msg.appId : undefined, { widths: msg.widths, themes: msg.themes, path: typeof msg.path === "string" ? msg.path : undefined }),
+        "apps.clearNotes": (msg) => service.clearNotes(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
+        "apps.logs": (msg) => service.logs(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
         "apps.share": (msg) => service.share(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
         "apps.revoke": (msg) => service.revoke(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
         "apps.remove": (msg) => { service.remove(String(msg.sessionId), String(msg.appId)); return { ok: true }; },
@@ -18,7 +31,7 @@ export function createAppCommands(service, workspaceFor, published = () => { })
     return Object.fromEntries(Object.entries(operations).map(([kind, execute]) => [kind, async (msg, ctx) => {
             try {
                 ctx.reply({ type: `${kind}.ok`, requestId: msg.requestId, ...await execute(msg) });
-                if (kind === "apps.publish" || kind === "apps.remove")
+                if (kind === "apps.publish" || kind === "apps.adopt" || kind === "apps.remove")
                     ctx.broadcast({ type: "apps.changed", sessionId: msg.sessionId });
             }
             catch (error) {

package/dist/node-config.js

@@ -74,7 +74,7 @@ export function validateNodeConfig(value) {
     const node = section(root, "node", ["workspace", "port", "maxConcurrentAutomations", "capabilities"], errors);
     const defaults = section(root, "defaults", ["agent", "model", "sandbox", "approval"], errors);
     const safety = section(root, "safety", ["maxSandbox", "approvalFloor"], errors);
-    const sessions = section(root, "sessions", ["sync", "worktreeSync", "standbyNodeId", "resume", "autoAttachToolImages", "forkWorkspaceMaxBytes", "wedgedTurnMinutes"], errors);
+    const sessions = section(root, "sessions", ["sync", "worktreeSync", "standbyNodeId", "resume", "autoAttachToolImages", "appScreenshots", "forkWorkspaceMaxBytes", "wedgedTurnMinutes"], errors);
     const github = section(root, "github", ["issuePrompt"], errors);
     const automation = section(root, "automation", ["checks", "checkTimeoutMinutes"], errors);
     const agentsRaw = section(root, "agents", Object.keys(record(root.agents) ?? {}), errors);
@@ -133,6 +133,7 @@ export function validateNodeConfig(value) {
     if (resume !== undefined && resume !== "auto" && resume !== "manual")
         errors.push("sessions.resume must be auto or manual");
     const autoAttachToolImages = optionalBoolean(sessions.autoAttachToolImages, "sessions.autoAttachToolImages", errors);
+    const appScreenshots = optionalBoolean(sessions.appScreenshots, "sessions.appScreenshots", errors);
     const forkWorkspaceMaxBytes = optionalInteger(sessions.forkWorkspaceMaxBytes, "sessions.forkWorkspaceMaxBytes", errors, 1_048_576, 1_073_741_824);
     // Upper bound is the wall-clock turn cap (60 min): a wedged window at/above it
     // would never fire before the cap. 0 disables the band.
@@ -216,7 +217,7 @@ export function validateNodeConfig(value) {
         ...(Object.keys(node).length ? { node: { workspace, port, maxConcurrentAutomations, capabilities } } : {}),
         ...(Object.keys(defaults).length ? { defaults: { agent, model, sandbox, approval } } : {}),
         ...(Object.keys(safety).length ? { safety: { maxSandbox, approvalFloor } } : {}),
-        ...(Object.keys(sessions).length ? { sessions: { sync, worktreeSync, standbyNodeId, resume, autoAttachToolImages, forkWorkspaceMaxBytes, wedgedTurnMinutes } } : {}),
+        ...(Object.keys(sessions).length ? { sessions: { sync, worktreeSync, standbyNodeId, resume, autoAttachToolImages, appScreenshots, forkWorkspaceMaxBytes, wedgedTurnMinutes } } : {}),
         ...(Object.keys(github).length ? { github: { issuePrompt } } : {}),
         ...(Object.keys(automation).length ? { automation: { checks, checkTimeoutMinutes } } : {}),
         ...(Object.keys(agents).length ? { agents } : {}),
@@ -272,6 +273,7 @@ export function configToLegacySettings(config) {
         ...(config.sessions?.standbyNodeId ? { syncStandbyNodeId: config.sessions.standbyNodeId } : {}),
         ...(config.sessions?.resume ? { sessionResumeMode: config.sessions.resume } : {}),
         ...(config.sessions?.autoAttachToolImages !== undefined ? { autoAttachToolImages: config.sessions.autoAttachToolImages } : {}),
+        ...(config.sessions?.appScreenshots !== undefined ? { appScreenshots: config.sessions.appScreenshots } : {}),
         ...(config.sessions?.forkWorkspaceMaxBytes !== undefined ? { forkWorkspaceMaxBytes: config.sessions.forkWorkspaceMaxBytes } : {}),
     };
 }
@@ -335,6 +337,7 @@ export function mergeLegacyIntoNodeConfig(cli, settings) {
             standbyNodeId: typeof settings.syncStandbyNodeId === "string" ? settings.syncStandbyNodeId : undefined,
             resume: settings.sessionResumeMode === "manual" ? "manual" : "auto",
             autoAttachToolImages: settings.autoAttachToolImages === true,
+            appScreenshots: settings.appScreenshots === true,
             forkWorkspaceMaxBytes: Number.isInteger(settings.forkWorkspaceMaxBytes) ? Number(settings.forkWorkspaceMaxBytes) : undefined,
         },
         github: { issuePrompt: typeof settings.githubIssuePrompt === "string" ? settings.githubIssuePrompt : undefined },
@@ -361,7 +364,7 @@ export function setConfigValue(config, dotted, value) {
         "node.workspace", "node.port", "node.maxConcurrentAutomations", "node.capabilities",
         "defaults.agent", "defaults.model", "defaults.sandbox", "defaults.approval",
         "safety.maxSandbox", "safety.approvalFloor",
-        "sessions.sync", "sessions.worktreeSync", "sessions.standbyNodeId", "sessions.resume", "sessions.autoAttachToolImages", "sessions.forkWorkspaceMaxBytes", "sessions.wedgedTurnMinutes",
+        "sessions.sync", "sessions.worktreeSync", "sessions.standbyNodeId", "sessions.resume", "sessions.autoAttachToolImages", "sessions.appScreenshots", "sessions.forkWorkspaceMaxBytes", "sessions.wedgedTurnMinutes",
         "github.issuePrompt", "automation.checks", "automation.checkTimeoutMinutes",
     ]);
     if (!allowed.has(dotted) && !/^agents\.[a-z][a-z0-9-]{1,47}$/.test(dotted) && !/^environment\.[A-Z][A-Z0-9_]+$/.test(dotted))

package/dist/policy/session-limit.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Session limit recovery — the user-driven counterpart to the policy's automatic
+// resume (session-reroute.ts planResume).
+//
+// When a turn ends because the agent hit a provider usage/rate limit and no
+// ruleset recovered it automatically, the session shouldn't just show a dead
+// error. This decides whether the failure IS such a limit, and what the user can
+// do about it: fork the work to another agent right away, or opt in to retrying
+// the same prompt automatically once the window resets. The caller (server.ts)
+// surfaces the offer as a notice with action buttons and, when the user accepts
+// the retry, schedules it through the same durable resume machinery the
+// automatic path uses.
+import { classifyFailure } from "./conditions.js";
+/** The conditions a user can route around (fork) or wait out (retry at reset),
+ *  with how the notice describes each. Adding a limit-like condition is a row. */
+const LIMIT_COPY = {
+    credits_exhausted: "reached its usage limit",
+    rate_limited: "is being rate-limited",
+};
+/** Retry a little after the stated reset: providers round reset times and a
+ *  re-send that lands a few seconds early just hits the same limit again. */
+const RESET_GRACE_MS = 60_000;
+/** Classify a turn error; returns the limit it represents, or undefined when it
+ *  is some other failure. `resetsAtHint` is the provider's structured reset time
+ *  (see ClassifyOptions) and wins over anything scraped from the text. */
+export function detectSessionLimit(error, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const classified = classifyFailure(error, { now, resetsAtHint: opts.resetsAtHint });
+    if (!LIMIT_COPY[classified.condition])
+        return undefined;
+    const resetsAt = classified.resetsAt
+        ?? (classified.retryAfterMs !== undefined ? new Date(now + classified.retryAfterMs).toISOString() : undefined);
+    return { condition: classified.condition, ...(resetsAt ? { resetsAt } : {}) };
+}
+/** The notice offering the user a way past the limit. Actions are client
+ *  action ids: `fork` opens the fork sheet; `retry-at-reset:<iso>` opts in to an
+ *  automatic retry (the timestamp is only for the button's label — the daemon
+ *  schedules from its own remembered limit). */
+export function sessionLimitNotice(agentName, limit) {
+    const what = `${agentName} ${LIMIT_COPY[limit.condition] ?? "hit a limit"}.`;
+    return limit.resetsAt
+        ? {
+            message: `${what} Fork to another agent to keep going, or retry automatically when the limit resets.`,
+            actions: ["fork", `retry-at-reset:${limit.resetsAt}`],
+        }
+        : { message: `${what} Fork to another agent to keep going.`, actions: ["fork"] };
+}
+/** A resume plan for a user who opted in to retrying at reset. Undefined when
+ *  the reset time is unknown. A reset already in the past retries shortly. */
+export function limitResumePlan(limit, now = Date.now()) {
+    const reset = limit.resetsAt ? Date.parse(limit.resetsAt) : NaN;
+    if (!Number.isFinite(reset))
+        return undefined;
+    const dueMs = Math.max(reset, now) + RESET_GRACE_MS;
+    return {
+        condition: limit.condition,
+        summary: `${limit.condition}: retrying when the limit resets at ${limit.resetsAt}.`,
+        delayMs: dueMs - now,
+        resumeAt: new Date(dueMs).toISOString(),
+    };
+}

package/dist/protocol/client-command-routes.js

@@ -3,7 +3,7 @@
 /** Direct-mode adapters for operations whose canonical implementation is the
  * client command registry. Relay and HTTP now differ only in framing. */
 export const CLIENT_COMMAND_ROUTES = [
-    ...["list", "publish", "open", "share", "revoke", "remove"].map((action) => ({ method: "post", path: `/api/apps/${action}`, kind: `apps.${action}` })),
+    ...["list", "publish", "offers", "adopt", "open", "logs", "shot", "clearNotes", "share", "revoke", "remove"].map((action) => ({ method: "post", path: `/api/apps/${action}`, kind: `apps.${action}` })),
     { method: "post", path: "/api/auth/credentials/native-preview", kind: "credentials.native.preview" },
     { method: "post", path: "/api/auth/credentials/native-import", kind: "credentials.native.import" },
     { method: "post", path: "/api/session/pause", kind: "session.pause" },

package/dist/protocol/client-command-schemas.js

@@ -10,7 +10,12 @@ export const CLIENT_COMMAND_SCHEMAS = {
     ping: Type.Object(request),
     "apps.list": Type.Object({ ...request, ...session }),
     "apps.publish": Type.Object({ ...request, ...session, manifest: Type.Unknown() }),
-    "apps.open": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String(), returnTo: Type.Optional(Type.String({ maxLength: 2048 })) }),
+    "apps.offers": Type.Object({ ...request, ...session }),
+    "apps.adopt": Type.Object({ ...request, ...session, port: Type.Integer({ minimum: 1024, maximum: 65535 }) }),
+    "apps.open": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String(), returnTo: Type.Optional(Type.String({ maxLength: 2048 })), direct: Type.Optional(Type.Boolean()), scale: Type.Optional(Type.Integer({ minimum: 1, maximum: 2 })) }),
+    "apps.shot": Type.Object({ ...request, ...session, appId: Type.Optional(Type.String()), widths: Type.Optional(Type.Array(Type.Integer(), { maxItems: 4 })), themes: Type.Optional(Type.Array(Type.Union([Type.Literal("light"), Type.Literal("dark")]), { maxItems: 2 })), path: Type.Optional(Type.String({ maxLength: 2048 })) }),
+    "apps.clearNotes": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
+    "apps.logs": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
     "apps.share": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
     "apps.revoke": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
     "apps.remove": Type.Object({ ...request, ...session, appId: Type.String() }),
@@ -37,6 +42,7 @@ export const CLIENT_COMMAND_SCHEMAS = {
     "session.rename": Type.Object({ ...session, name: Type.String() }),
     abort: Type.Object(optionalSession),
     "session.turn_attention.resolve": Type.Object({ ...session, action: Type.Union([Type.Literal("stop"), Type.Literal("continue")]) }),
+    "session.limit_retry": Type.Object({ ...session, enabled: Type.Boolean() }),
     "session.command.invoke": Type.Object({ ...session, name: Type.String(), args: Type.Optional(Type.String()) }),
     "branches.list": Type.Object({ repo: Type.String() }),
     "history": Type.Object({ ...request, ...optionalSession, have: Type.Optional(Type.Number()), haveToken: Type.Optional(Type.String()) }),

package/dist/server.js

@@ -16,6 +16,7 @@ import { listRuntimes, catalogRuntimes, agentInstallSpec, canonicalAgentId, inva
 import { createRunPolicy } from "./policy/run-policy.js";
 import { DEFAULT_BACKOFF } from "./policy/ruleset.js";
 import { SessionRerouteController } from "./policy/session-reroute.js";
+import { detectSessionLimit, limitResumePlan, sessionLimitNotice } from "./policy/session-limit.js";
 import { activeRulesetFor } from "./runtime/ruleset-store.js";
 import { createRulesetController } from "./controllers/rulesets.js";
 import { createAuditLog, readAuditEvents } from "./audit/index.js";
@@ -31,6 +32,7 @@ import { AppRegistry } from "./apps/registry.js";
 import { AppGateway } from "./apps/gateway.js";
 import { RemotePreview } from "./apps/remote-preview.js";
 import { AppService } from "./apps/service.js";
+import { DisplayHost } from "./apps/display.js";
 import { createAppCommands } from "./controllers/app-commands.js";
 import { bindClientCommandRoutes } from "./http/client-command-routes.js";
 import { collectDiscoveredSessions, planNativeAdoption } from "./runtime/native-session-discovery.js";
@@ -963,6 +965,8 @@ async function harnessEndTurn(record) {
         record.workspaceState = (await harness.isDirty(record.id)) ? "dirty" : "clean";
         if (!result || result.changes.length === 0)
             return;
+        // Open previews of this session reload; static snapshots are re-taken.
+        appService.turnChanged(record.id);
         broadcast({
             type: "session.changes",
             sessionId: record.id,
@@ -1332,6 +1336,7 @@ function writeSettings(settings) {
         ...("syncStandbyNodeId" in settings ? { standbyNodeId: typeof settings.syncStandbyNodeId === "string" ? settings.syncStandbyNodeId || undefined : undefined } : {}),
         ...(settings.sessionResumeMode === "auto" || settings.sessionResumeMode === "manual" ? { resume: settings.sessionResumeMode } : {}),
         ...(typeof settings.autoAttachToolImages === "boolean" ? { autoAttachToolImages: settings.autoAttachToolImages } : {}),
+        ...(typeof settings.appScreenshots === "boolean" ? { appScreenshots: settings.appScreenshots } : {}),
         ...(Number.isInteger(settings.forkWorkspaceMaxBytes) ? { forkWorkspaceMaxBytes: Number(settings.forkWorkspaceMaxBytes) } : {}),
     };
     next.github = {
@@ -1418,6 +1423,15 @@ function nodeConfiguredDefaultAgent() {
 }
 /** How interactive sessions recover after a restart interrupted them mid-turn.
  *  Defaults to "auto" (re-drive the turn); "manual" waits for a user tap. */
+/** Agents may screenshot app previews: the node setting, or BIVY_APP_SCREENSHOTS. */
+function appScreenshotsEnabled() {
+    const env = process.env.BIVY_APP_SCREENSHOTS;
+    if (env === "1" || env === "true")
+        return true;
+    if (env === "0" || env === "false")
+        return false;
+    return readSettings().appScreenshots === true;
+}
 function nodeSessionResumeMode() {
     return readSettings().sessionResumeMode === "manual" ? "manual" : "auto";
 }
@@ -1451,6 +1465,7 @@ function nodeSettingsSnapshot() {
         })(),
         sessionResumeMode: nodeSessionResumeMode(),
         autoAttachToolImages: readSettings().autoAttachToolImages === true,
+        appScreenshots: appScreenshotsEnabled(),
         forkWorkspaceMaxBytes: Number.isInteger(readSettings().forkWorkspaceMaxBytes) ? Number(readSettings().forkWorkspaceMaxBytes) : 50 * 1024 * 1024,
     };
 }
@@ -1508,6 +1523,8 @@ async function applyNodeSettings(patch) {
     if ("sessionResumeMode" in patch) {
         settings.sessionResumeMode = patch.sessionResumeMode === "manual" ? "manual" : "auto";
     }
+    if ("appScreenshots" in patch)
+        settings.appScreenshots = patch.appScreenshots === true;
     if ("autoAttachToolImages" in patch) {
         settings.autoAttachToolImages = patch.autoAttachToolImages === true;
         setConfiguredAutoAttachToolImages(settings.autoAttachToolImages);
@@ -1906,14 +1923,26 @@ const appPreviewPort = Number(process.env.BIVY_APPS_PORT || 4318);
 if (process.env.BIVY_APPS_ORIGIN && (!Number.isInteger(appPreviewPort) || appPreviewPort < 1024 || appPreviewPort > 65535 || appPreviewPort === port)) {
     throw new Error("BIVY_APPS_PORT must be between 1024 and 65535 and different from the node API port.");
 }
-const appRegistry = new AppRegistry([port, ...(process.env.BIVY_APPS_ORIGIN ? [appPreviewPort] : [])]);
+// Apps persist with their IDs, so chat launchers and preview addresses survive
+// restarts; see AppRegistry for which views are restored.
+const appRegistry = new AppRegistry([port, ...(process.env.BIVY_APPS_ORIGIN ? [appPreviewPort] : [])], path.join(appDir, "apps.json"));
 const appReturnOrigins = () => {
     const config = loadRelayConfig(appDir);
     return [config?.clientBaseUrl, config?.controlPlaneUrl, ...(process.env.BIVY_APPS_RETURN_ORIGINS ?? "").split(",")]
         .filter((value) => Boolean(value?.trim())).map((value) => new URL(value.trim()).origin);
 };
-const appGateway = process.env.BIVY_APPS_ORIGIN ? new AppGateway(appRegistry, process.env.BIVY_APPS_ORIGIN, appReturnOrigins) : undefined;
-const remotePreview = new RemotePreview(appRegistry, appReturnOrigins);
+// A signed-out visit to a preview's stable address goes through the Bivy
+// client: open the session on this node, then the client re-opens the view.
+const appSignIn = (view, pagePath) => {
+    const client = loadRelayConfig(appDir)?.clientBaseUrl;
+    if (!client)
+        return undefined;
+    return `${new URL(client).origin}/sessions/${encodeURIComponent(view.app.sessionId)}?node=${encodeURIComponent(identity.nodeId)}#preview=${view.app.id}.${view.view.id}.${encodeURIComponent(pagePath)}`;
+};
+const appGateway = process.env.BIVY_APPS_ORIGIN ? new AppGateway(appRegistry, process.env.BIVY_APPS_ORIGIN, appReturnOrigins, appSignIn) : undefined;
+const remotePreview = new RemotePreview(appRegistry, appReturnOrigins, appSignIn);
+// Desktop app views: one private display per view, started on first open.
+const appDisplays = new DisplayHost();
 const appService = new AppService(appRegistry, appGateway ?? remotePreview, {
     start: async (spec) => {
         let failure = "Could not start the app terminal.";
@@ -1928,7 +1957,7 @@ const appService = new AppService(appRegistry, appGateway ?? remotePreview, {
     },
     has: (id) => terminals.has(id),
     close: (id) => { terminals.close(id); },
-});
+}, { screenshots: { enabled: appScreenshotsEnabled }, displays: appDisplays });
 const RELAY_COMMANDS = {
     ...createAppCommands(appService, (id) => { const record = resolveSession(id); return record ? harnessDirFor(record) : undefined; }, (app) => {
         const record = resolveSession(app.sessionId);
@@ -2187,6 +2216,11 @@ const RELAY_COMMANDS = {
         else
             abortSessionRecord(record, ctx.broadcast);
     },
+    "session.limit_retry"(msg) {
+        const record = resolveSession(msg.sessionId);
+        if (record)
+            setSessionLimitRetry(record, msg.enabled === true);
+    },
     "session.turn_attention.resolve"(msg) {
         const record = resolveSession(msg.sessionId);
         const action = msg.action === "stop" ? "stop" : msg.action === "continue" ? "continue" : undefined;
@@ -2899,6 +2933,7 @@ const RELAY_COMMANDS = {
             // The user is driving this turn manually — supersede any pending auto-resume
             // that was scheduled after a prior limit so it can't re-fire on top of them.
             clearSessionResume(record.id);
+            record.limitHit = undefined;
             await turnWatchdog.promptWithWatchdog(record, agentPrompt, record.lastPromptOptions);
         }).catch((error) => {
             // Mirror the HTTP path (see the /prompt route): a rejected turn after
@@ -6239,6 +6274,21 @@ function rememberSession(record) {
     persistSessionMetadata(record);
     recordSessionLocation(record);
     enforceOpenSessionCap(record.id);
+    // Opened while a `bivy run` pinned to it is live (e.g. `bivy resume` on the
+    // laptop, then the chat on a phone): the terminal owns it until it ends.
+    runTerms.adoptLiveRun(record);
+}
+/** The open session a run's pinned id refers to — by Bivy id or by the
+ *  runtime's own session ref. Unlike resolveSession, never the active one. */
+function findOpenSession(ref) {
+    const direct = openSessions.get(ref);
+    if (direct)
+        return direct;
+    for (const record of openSessions.values()) {
+        if (record.sessionFile === ref)
+            return record;
+    }
+    return undefined;
 }
 // Keep the number of live (in-memory) sessions bounded. Idle-close already
 // trims over time, but a burst of opens within the idle window could pile up
@@ -7246,12 +7296,15 @@ function scheduleSessionResume(record, plan) {
     metadata.setResumeAt(record.id, plan.resumeAt);
     metadata.setResumeAttempts(record.id, attempts + 1);
     const when = Date.parse(plan.resumeAt);
-    const cond = plan.condition.replace(/_/g, " ");
+    const at = Number.isFinite(when)
+        ? new Date(when).toLocaleString("en-US", { timeZone: "UTC", month: "short", day: "numeric", hour: "2-digit", minute: "2-digit", hour12: false })
+        : plan.resumeAt;
     broadcast({
         type: "session.notice",
         sessionId: record.id,
         level: "info",
-        message: `Hit a ${cond} limit — I'll resume this automatically when it resets (${plan.resumeAt}).`,
+        message: `I'll retry this automatically when the limit resets (${at} UTC).`,
+        actions: ["cancel-resume"],
     });
     armSessionResumeTimer(record.id, Number.isFinite(when) ? when : Date.now());
     return true;
@@ -7290,6 +7343,23 @@ async function driveSessionResume(id) {
         console.warn(`[resume] auto-resume after a provider limit failed for ${id}`, error);
     }
 }
+/** The user's answer to a surfaced limit: opt in to retrying the turn when the
+ *  window resets (scheduled through the same durable resume path the policy
+ *  uses), or cancel a pending retry. */
+function setSessionLimitRetry(record, enabled) {
+    if (!enabled) {
+        clearSessionResume(record.id);
+        metadata.setResumeAttempts(record.id, 0);
+        broadcast({ type: "session.notice", sessionId: record.id, level: "info", message: "Automatic retry cancelled." });
+        return;
+    }
+    const plan = record.limitHit && limitResumePlan(record.limitHit);
+    if (!plan) {
+        broadcast({ type: "session.notice", sessionId: record.id, level: "info", message: "There's no pending limit to retry — send a message to continue." });
+        return;
+    }
+    scheduleSessionResume(record, plan);
+}
 /** Re-arm (or immediately fire) durable auto-resume markers. Runs once at boot
  *  and on an interval, so a wait survives a restart and a capped timer's tail
  *  still fires. */
@@ -7618,6 +7688,13 @@ function attachSessionListeners(record) {
                 broadcast({ type: "session.failed", sessionId: record.id, failedAt: record.lastFailureAt });
                 if (messageError)
                     broadcast({ type: "session.error", sessionId: record.id, error: sessionAgentError(record, messageError) });
+                // A usage/rate limit nothing recovered automatically: offer the ways past
+                // it — fork to another agent now, or retry when the window resets.
+                record.limitHit = detectSessionLimit(turnError, { resetsAtHint: limitResetHint(record, Date.now()) });
+                if (record.limitHit) {
+                    const notice = sessionLimitNotice(getRuntime(record.runtimeId).displayName, record.limitHit);
+                    broadcast({ type: "session.notice", sessionId: record.id, level: "warn", ...notice });
+                }
                 // If the terminal error is an auth failure (expired key/token → 4xx),
                 // also raise the sign-in sheet for the failing provider.
                 maybeSignalAuthRequired(record, turnError);
@@ -8590,10 +8667,17 @@ const runTerms = createRunTerminals({
     sendNotificationHint: (hint) => void sendNotificationHint(hint),
     createSession: (workspace, sessionFile, opts) => createSession(workspace, sessionFile, opts),
     resolveSession: (id) => resolveSession(id),
+    findOpenSession: (ref) => findOpenSession(ref),
     sessionBusy: (record) => sessionBusy(record),
     sessionTerminalsRecord: (sessionId, val) => sessionTerminals.record(sessionId, val),
     sessionTerminalsForget: (sessionId) => sessionTerminals.forget(sessionId),
-    upsertSessionMetadata: (patch) => metadata.upsertSession(patch),
+    upsertSessionMetadata: (patch) => {
+        const input = patch;
+        // A run continuing a saved session (`bivy resume`) only moves its status;
+        // the session keeps its own name, source and agent.
+        const prev = metadata.getSession(input.id);
+        metadata.upsertSession(prev ? { id: input.id, status: input.status } : input);
+    },
     sessionListChanged: () => { broadcastSessionsList(); scheduleAdvertise(); },
     saveRunLog: (termId, log) => runLogs.save(termId, log),
     loadRunLog: (termId) => runLogs.load(termId),
@@ -11130,6 +11214,13 @@ app.post("/api/session/abort", (req, res, next) => {
         next(error);
     }
 });
+app.post("/api/session/limit-retry", (req, res) => {
+    const record = resolveSession(req.body?.sessionId);
+    if (!record)
+        return res.status(404).json({ error: "No active session" });
+    setSessionLimitRetry(record, req.body?.enabled === true);
+    res.json({ ok: true });
+});
 app.post("/api/session/turn-attention", (req, res, next) => {
     try {
         const record = resolveSession(req.body?.sessionId);
@@ -11443,6 +11534,7 @@ function shutdown(signal) {
     }
     catch { }
     terminals.disposeAll();
+    appDisplays.stopAll();
     // Drop persistent client/relay sockets so server.close() can actually drain;
     // otherwise a lingering WebSocket keeps the process alive until the supervisor
     // SIGKILLs it, orphaning children.