frontpage-host 0.1.7 → 0.1.9

package/AGENTS.md

@@ -112,7 +112,7 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 - Articles: `frontpage articles …` for lifecycle; bodies via sync under `content/` or `articles content get|set`. Section landing is an owned `src/pages/<section>/index.astro`.
 - Migrate a folder into Articles: prefer `frontpage prompt "migrate … into articles"` — do not invent a mass delete+write migration.
 - Extensions: `frontpage extensions`; if LOCKED on plan, do not fake charts/etc.
-- Media in markup: `/__media/uploads/<slug>/…` from `frontpage media` (not raw blob URLs).
+- Media: `frontpage media upload <file>` — images/PDF ≤25 MB, video (MP4/WebM/MOV) ≤50 MB, SVG/text ≤4 MB (sanitizing proxy). Use returned `sitePath` (`/__media/uploads/<slug>/…`) in markup — never raw blob hosts. Optional `?w=` on rasters only.
 - Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
 
 ## Agent prompt loop
@@ -122,14 +122,18 @@ frontpage prompt "make the hero shorter"
 frontpage prompt "Use this logo in the header" --attach ./logo.png
 frontpage prompt "Match this brand PDF" --attach ./guide.pdf --path /
 frontpage prompt "Reuse uploaded art" --attach /__media/uploads/<slug>/<file>
-frontpage runs wait          # wait for the agent run to finish
+frontpage media upload ./clip.mp4
+frontpage runs wait          # wait for the agent run to finish (failed/canceled → exit 2)
 # Review https://<subdomain>.frontpage.host — do not publish unless asked.
 ```
 
-- `--attach` accepts a local file (uploads via the same path as `frontpage media upload`), an existing `/__media/…` site path, or an `https://` Blob URL. Repeatable.
+- `--attach` accepts a local file (same transport as `frontpage media upload`), an existing `/__media/…` site path, or an `https://` Blob URL. Repeatable.
 - `--asset-url <https://…>` adds a legacy image URL. Repeatable.
-- Caps match the media proxy: images / PDF / text-code. CLI video and >4 MB binaries are not supported yet (editor attach / Phase E).
+- Caps: images/PDF ≤25 MB, video ≤50 MB, SVG/text via proxy ≤4 MB (large text/data Blob upload is editor-only).
 - Prompt text is still required (API). Attachments ride on the same enqueue as the editor.
+- `runs wait` with `--json`: failures use `ok: false` and include `data.run` (with `run.error` when present).
+- `deploy wait` is fail-closed: exit 2 if the waited run (or latest, when already idle) is `failed`/`canceled`.
+- `frontpage push --wait` waits for agent-run idle after push (same busy statuses; not a separate Vercel oracle).
 
 Mid-task continuation is automatic. There is **no** `runs continue` in v1.
 
@@ -173,10 +177,10 @@ Global machine envelope (`--json`):
 
 ```json
 { "ok": true, "command": "status", "data": { } }
-{ "ok": false, "command": "push", "error": { "message": "…", "code": "conflict", "httpStatus": 409, "exitCode": 3 } }
+{ "ok": false, "command": "push", "error": { "message": "…", "code": "conflict", "httpStatus": 409, "exitCode": 3, "requestId": "…" } }
 ```
 
-Failures with `--json` print the envelope on **stdout** (still use the process exit code).
+Failures with `--json` print the envelope on **stdout** (still use the process exit code). Include `requestId` when filing support issues.
 
 ## Global flags
 

package/dist/commands/deploy.js

@@ -1,7 +1,7 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, v1Get } from "../http/client.js";
-import { emitErr, emitOk, emitUsage, progress } from "../runtime.js";
-import { isJson } from "../runtime.js";
+import { EXIT_USAGE } from "../http/client.js";
+import { emitErr, emitUsage } from "../runtime.js";
+import { emitWaitOutcome, waitForAgentIdle } from "./wait-agent-idle.js";
 /** `frontpage deploy wait` — wait until no run is in deploying/queued/running. */
 export async function runDeploy(args) {
     try {
@@ -10,30 +10,12 @@ export async function runDeploy(args) {
             return emitUsage("deploy", "Usage: frontpage deploy wait [--site <slug>]", EXIT_USAGE);
         }
         const { slug } = await resolveSlug(args.slice(1));
-        const started = Date.now();
-        const maxMs = 30 * 60 * 1000;
-        while (Date.now() - started < maxMs) {
-            const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs`);
-            const busy = (data.active ?? []).filter((r) => ["queued", "running", "deploying"].includes(r.status));
-            if (busy.length === 0) {
-                if (isJson()) {
-                    emitOk("deploy", {
-                        slug,
-                        waited: true,
-                        run: data.run,
-                        status: data.run?.status ?? "idle",
-                    });
-                }
-                else {
-                    console.log(data.run ? `${data.run.id}  ${data.run.status}` : "No active deploy.");
-                }
-                return EXIT_OK;
-            }
-            const head = busy.find((r) => r.status === "deploying") ?? busy[0];
-            progress(`\r${head.status}  ${head.statusMessage ?? ""}   `);
-            await new Promise((r) => setTimeout(r, 2000));
-        }
-        return emitUsage("deploy", "Timed out waiting for deploy.", EXIT_USAGE);
+        const result = await waitForAgentIdle({
+            slug,
+            // Fail-closed: idle with latest failed/canceled is not success.
+            failClosedOnIdleTerminalFailure: true,
+        });
+        return emitWaitOutcome({ command: "deploy", slug, result });
     }
     catch (err) {
         return emitErr("deploy", err);

package/dist/commands/media.js

@@ -1,13 +1,18 @@
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1PostMultipart } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, exitCodeForError } from "../http/client.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
+import { uploadLocalMedia } from "../media/upload.js";
+import { v1Get } from "../http/client.js";
 export async function runMedia(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
         const sub = rest[0] ?? "list";
         if (sub === "list" || sub === "ls") {
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/media`);
+            if (isJson()) {
+                emitOk("media", { slug, ...data });
+                return EXIT_OK;
+            }
             for (const a of data.assets) {
                 console.log(`${a.sitePath.padEnd(48)}  ${String(a.sizeBytes).padStart(8)}  ${a.name}`);
             }
@@ -17,27 +22,32 @@ export async function runMedia(args) {
         if (sub === "upload") {
             const filePath = rest[1];
             if (!filePath) {
-                console.error("Usage: frontpage media upload <file> [--site <slug>]");
+                console.error("Usage: frontpage media upload <file> [--site <slug>] [--json]");
                 return EXIT_USAGE;
             }
-            const bytes = await readFile(filePath);
-            const form = new FormData();
-            form.append("file", new Blob([Uint8Array.from(bytes)]), basename(filePath));
-            const data = await v1PostMultipart(`/api/v1/sites/${encodeURIComponent(slug)}/media`, form);
+            const data = await uploadLocalMedia({ slug, filePath });
+            if (isJson()) {
+                emitOk("media", { slug, ...data });
+                return EXIT_OK;
+            }
             if (data.kind === "text") {
                 console.log(`Inline text (${data.filename}): ${data.sizeBytes ?? 0} bytes — not stored.`);
+                return EXIT_OK;
             }
-            else {
-                console.log(data.url ?? data.key ?? JSON.stringify(data));
-                if (data.key)
-                    console.log(`sitePath: /__media/${data.key}`);
-            }
+            if (data.url)
+                console.log(data.url);
+            if (data.sitePath)
+                console.log(`sitePath: ${data.sitePath}`);
+            else if (data.key)
+                console.log(`sitePath: /__media/${data.key}`);
             return EXIT_OK;
         }
-        console.error("Usage: frontpage media list|upload <file> [--site <slug>]");
+        console.error("Usage: frontpage media list|upload <file> [--site <slug>] [--json]");
         return EXIT_USAGE;
     }
     catch (err) {
+        if (isJson())
+            return emitErr("media", err);
         console.error(err instanceof Error ? err.message : String(err));
         return exitCodeForError(err);
     }

package/dist/commands/prompt-attach.d.ts

@@ -1,8 +1,10 @@
-/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts (images/docs/text only via proxy media). */
+import { type UploadedMedia } from "../media/upload.js";
+/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts. */
 export declare const CLI_ATTACH_LIMITS: {
     readonly maxImages: 6;
     readonly maxDocuments: 4;
     readonly maxTextFiles: 6;
+    readonly maxVideos: 3;
 };
 export type PromptAttachmentsPayload = {
     images: Array<{
@@ -17,19 +19,19 @@ export type PromptAttachmentsPayload = {
         name: string;
         content: string;
     }>;
+    videos: Array<{
+        url: string;
+        name?: string;
+        sizeBytes?: number;
+    }>;
 };
-export type MediaUploadResult = {
-    kind: string;
-    url?: string;
-    key?: string;
-    filename?: string;
-    sizeBytes?: number;
-    content?: string;
-};
+export type MediaUploadResult = UploadedMedia;
 export declare function emptyAttachments(): PromptAttachmentsPayload;
 export declare function isHttpsUrl(s: string): boolean;
 export declare function isMediaSitePath(s: string): boolean;
-export declare function classifyRemoteByName(nameOrUrl: string): "image" | "document";
+export declare function classifyRemoteByName(nameOrUrl: string): "image" | "document" | "video";
+/** Agent normalizeAttachments only keeps videos on our Blob host under uploads/. */
+export declare function isFrontpageBlobUploadUrl(url: string): boolean;
 export declare function addHttpsRef(out: PromptAttachmentsPayload, url: string, opts?: {
     name?: string;
     asImageOnly?: boolean;

package/dist/commands/prompt-attach.js

@@ -1,19 +1,21 @@
 /**
- * §CLI Phase C — resolve --attach / --asset-url into the agent attachments payload.
- * Local files upload via the same multipart media endpoint as `frontpage media upload`.
+ * §CLI Phase C (+ E) — resolve --attach / --asset-url into the agent attachments payload.
+ * Local files use the same transport matrix as `frontpage media upload`.
  */
-import { access, readFile } from "node:fs/promises";
-import { basename } from "node:path";
+import { access } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
-import { v1Get, v1PostMultipart, CliHttpError, EXIT_USAGE, EXIT_UNEXPECTED } from "../http/client.js";
-/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts (images/docs/text only via proxy media). */
+import { v1Get, CliHttpError, EXIT_USAGE, EXIT_UNEXPECTED } from "../http/client.js";
+import { uploadLocalMedia } from "../media/upload.js";
+import { VIDEO_UPLOAD_EXT, extOf } from "../media/limits.js";
+/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts. */
 export const CLI_ATTACH_LIMITS = {
     maxImages: 6,
     maxDocuments: 4,
     maxTextFiles: 6,
+    maxVideos: 3,
 };
 export function emptyAttachments() {
-    return { images: [], documents: [], textFiles: [] };
+    return { images: [], documents: [], textFiles: [], videos: [] };
 }
 export function isHttpsUrl(s) {
     return /^https:\/\/[^\s]+$/i.test(s) && s.length <= 2048;
@@ -23,7 +25,9 @@ export function isMediaSitePath(s) {
 }
 export function classifyRemoteByName(nameOrUrl) {
     const base = nameOrUrl.split(/[?#]/)[0] ?? nameOrUrl;
-    const ext = base.includes(".") ? (base.split(".").pop() ?? "").toLowerCase() : "";
+    const ext = extOf(base);
+    if (VIDEO_UPLOAD_EXT.has(ext))
+        return "video";
     if (ext === "pdf")
         return "document";
     return "image";
@@ -42,6 +46,19 @@ function pushText(list, name, content) {
     }
     list.push({ name, content });
 }
+/** Agent normalizeAttachments only keeps videos on our Blob host under uploads/. */
+export function isFrontpageBlobUploadUrl(url) {
+    try {
+        const u = new URL(url);
+        if (!u.hostname.endsWith(".blob.vercel-storage.com"))
+            return false;
+        const pathname = u.pathname.replace(/^\/+/, "");
+        return pathname.startsWith("uploads/");
+    }
+    catch {
+        return false;
+    }
+}
 export function addHttpsRef(out, url, opts) {
     if (!isHttpsUrl(url)) {
         throw new CliHttpError(`Not an https URL: ${url}`, EXIT_USAGE, 400, "bad_request");
@@ -49,10 +66,16 @@ export function addHttpsRef(out, url, opts) {
     const kind = opts?.asImageOnly ? "image" : classifyRemoteByName(opts?.name ?? url);
     if (kind === "document") {
         pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, url, opts?.name, "document");
+        return;
     }
-    else {
-        pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, url, opts?.name, "image");
+    if (kind === "video") {
+        if (!isFrontpageBlobUploadUrl(url)) {
+            throw new CliHttpError("Video --attach URLs must be Frontpage Blob uploads (…blob.vercel-storage.com/uploads/…). Upload with frontpage media upload first, or pass a local .mp4/.webm/.mov file.", EXIT_USAGE, 400, "bad_request");
+        }
+        pushUniqueUrl(out.videos, CLI_ATTACH_LIMITS.maxVideos, url, opts?.name, "video");
+        return;
     }
+    pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, url, opts?.name, "image");
 }
 export function addUploadResult(out, data) {
     const name = data.filename?.trim() || undefined;
@@ -63,19 +86,31 @@ export function addUploadResult(out, data) {
         pushText(out.textFiles, name ?? "snippet.txt", data.content);
         return;
     }
-    if (data.kind === "image" || data.kind === "document") {
+    if (data.kind === "image" || data.kind === "document" || data.kind === "video") {
         if (!data.url || !isHttpsUrl(data.url)) {
             throw new CliHttpError(`Upload of ${name ?? "file"} did not return a Blob URL.`, EXIT_UNEXPECTED, 500, "internal");
         }
         if (data.kind === "document") {
             pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, data.url, name, "document");
+            return;
         }
-        else {
-            pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, data.url, name, "image");
+        if (data.kind === "video") {
+            if (out.videos.length >= CLI_ATTACH_LIMITS.maxVideos) {
+                throw new CliHttpError(`Too many video attachments (max ${CLI_ATTACH_LIMITS.maxVideos}).`, EXIT_USAGE, 400, "bad_request");
+            }
+            if (!out.videos.some((x) => x.url === data.url)) {
+                out.videos.push({
+                    url: data.url,
+                    name,
+                    sizeBytes: data.sizeBytes,
+                });
+            }
+            return;
         }
+        pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, data.url, name, "image");
         return;
     }
-    throw new CliHttpError(`Unsupported upload kind "${data.kind}" for prompt attach. Use images, PDFs, or text/code files (video/large files need the editor path until Phase E).`, EXIT_USAGE, 400, "bad_request");
+    throw new CliHttpError(`Unsupported upload kind "${data.kind}" for prompt attach. Use images, PDFs, videos, or text/code files.`, EXIT_USAGE, 400, "bad_request");
 }
 export async function uploadLocalForAttach(slug, filePath) {
     try {
@@ -84,13 +119,7 @@ export async function uploadLocalForAttach(slug, filePath) {
     catch {
         throw new CliHttpError(`Cannot read file for --attach: ${filePath}`, EXIT_USAGE, 400, "bad_request");
     }
-    const bytes = await readFile(filePath);
-    if (bytes.length === 0) {
-        throw new CliHttpError(`File is empty: ${filePath}`, EXIT_USAGE, 400, "bad_request");
-    }
-    const form = new FormData();
-    form.append("file", new Blob([Uint8Array.from(bytes)]), basename(filePath));
-    return v1PostMultipart(`/api/v1/sites/${encodeURIComponent(slug)}/media`, form);
+    return uploadLocalMedia({ slug, filePath });
 }
 export async function resolveSitePathUrl(slug, sitePath) {
     const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/media`);
@@ -123,6 +152,9 @@ export async function resolveAttachRef(slug, ref, out) {
         if (kind === "document") {
             pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, asset.url, asset.name, "document");
         }
+        else if (kind === "video") {
+            pushUniqueUrl(out.videos, CLI_ATTACH_LIMITS.maxVideos, asset.url, asset.name, "video");
+        }
         else {
             pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, asset.url, asset.name, "image");
         }
@@ -143,7 +175,8 @@ export async function buildPromptAttachments(args) {
     }
     if (out.images.length === 0 &&
         out.documents.length === 0 &&
-        out.textFiles.length === 0) {
+        out.textFiles.length === 0 &&
+        out.videos.length === 0) {
         throw new CliHttpError("No attachments could be resolved from --attach / --asset-url.", EXIT_USAGE, 400, "bad_request");
     }
     return out;

package/dist/commands/prompt.js

@@ -29,6 +29,7 @@ export async function runPrompt(args) {
                         images: attachments.images.length,
                         documents: attachments.documents.length,
                         textFiles: attachments.textFiles.length,
+                        videos: attachments.videos.length,
                     }
                     : undefined,
             });
@@ -40,7 +41,8 @@ export async function runPrompt(args) {
             if (attachments) {
                 const n = attachments.images.length +
                     attachments.documents.length +
-                    attachments.textFiles.length;
+                    attachments.textFiles.length +
+                    attachments.videos.length;
                 console.error(`(attached ${n} file${n === 1 ? "" : "s"})`);
             }
         }

package/dist/commands/push.js

@@ -4,6 +4,7 @@ import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, v1Put } from "../http/client.js";
 import { readState, writeState } from "../state/frontpage-state.js";
 import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
+import { emitWaitOutcome, waitForAgentIdle } from "./wait-agent-idle.js";
 const TEXT_EXTS = new Set([
     ".astro",
     ".ts",
@@ -59,13 +60,22 @@ function isTextPath(repoPath) {
         return true;
     return TEXT_EXTS.has(repoPath.slice(i).toLowerCase());
 }
+function takeWaitFlag(rest) {
+    const i = rest.indexOf("--wait");
+    if (i === -1)
+        return false;
+    rest.splice(i, 1);
+    return true;
+}
 export async function runPush(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
-        const messageIdx = rest.indexOf("--message");
+        const work = [...rest];
+        const wait = takeWaitFlag(work);
+        const messageIdx = work.indexOf("--message");
         const message = messageIdx >= 0
-            ? rest[messageIdx + 1]
-            : rest.find((a) => a.startsWith("--message="))?.slice("--message=".length);
+            ? work[messageIdx + 1]
+            : work.find((a) => a.startsWith("--message="))?.slice("--message=".length);
         const cwd = process.cwd();
         const state = await readState(cwd);
         if (!state.baseCommitSha) {
@@ -99,25 +109,51 @@ export async function runPush(args) {
         if (data.commitSha) {
             await writeState({ ...state, slug, baseCommitSha: data.commitSha }, cwd);
         }
-        if (isJson()) {
-            emitOk("push", {
-                slug,
-                changed: data.changed,
-                commitSha: data.commitSha,
-                baseCommitSha: data.baseCommitSha,
-                filesChanged: data.filesChanged,
-            });
+        const pushPayload = {
+            slug,
+            changed: data.changed,
+            commitSha: data.commitSha,
+            baseCommitSha: data.baseCommitSha,
+            filesChanged: data.filesChanged,
+        };
+        if (!wait) {
+            if (isJson()) {
+                emitOk("push", pushPayload);
+                return EXIT_OK;
+            }
+            if (!data.changed) {
+                console.log("Nothing to commit (remote already matches).");
+                return EXIT_OK;
+            }
+            console.log(`Pushed ${data.filesChanged.length} file(s) → ${data.commitSha}`);
+            console.log("Updated .frontpage/state.json baseCommitSha");
+            console.log("Note: module markup may auto-activate modules (same as the editor agent).");
+            console.log("tokens.ts may be auto-repaired at commit if it would break the build.");
             return EXIT_OK;
         }
-        if (!data.changed) {
-            console.log("Nothing to commit (remote already matches).");
-            return EXIT_OK;
+        // --wait: after push, wait for agent-run busy to clear (same statuses as deploy wait).
+        // Does not invent a Vercel deploy oracle; file-only pushes with no active run return promptly.
+        if (!isJson()) {
+            if (!data.changed) {
+                console.log("Nothing to commit (remote already matches).");
+            }
+            else {
+                console.log(`Pushed ${data.filesChanged.length} file(s) → ${data.commitSha}`);
+                console.log("Updated .frontpage/state.json baseCommitSha");
+            }
+            console.error("Waiting for agent run / deploy idle…");
         }
-        console.log(`Pushed ${data.filesChanged.length} file(s) → ${data.commitSha}`);
-        console.log("Updated .frontpage/state.json baseCommitSha");
-        console.log("Note: module markup may auto-activate modules (same as the editor agent).");
-        console.log("tokens.ts may be auto-repaired at commit if it would break the build.");
-        return EXIT_OK;
+        const result = await waitForAgentIdle({
+            slug,
+            // Do not fail on an ancient canceled run when this push never saw busy work.
+            failClosedOnIdleTerminalFailure: false,
+        });
+        return emitWaitOutcome({
+            command: "push",
+            slug,
+            result,
+            extra: { ...pushPayload, waited: true },
+        });
     }
     catch (err) {
         return emitErr("push", err);

package/dist/commands/runs.js

@@ -1,13 +1,33 @@
 import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, v1Get, v1Post } from "../http/client.js";
-import { emitErr, emitOk, emitUsage, isJson, progress } from "../runtime.js";
+import { emitErr, emitFail, emitOk, emitUsage, isJson, progress } from "../runtime.js";
 const TERMINAL = new Set(["succeeded", "failed", "canceled"]);
+const FAIL_TERMINAL = new Set(["failed", "canceled"]);
 function printRun(run) {
-    const msg = run.statusMessage || run.summary || run.error || "";
+    const msg = run.statusMessage || run.summary || "";
     console.log(`${run.id}  ${run.status}${msg ? `  ${msg}` : ""}`);
+    if (run.error)
+        console.log(`  error: ${run.error}`);
     if (run.commitSha)
         console.log(`  commit: ${run.commitSha}`);
 }
+/** Finish runs wait — honest JSON (ok:false on failure) + always surface run.error. */
+function finishWait(slug, run) {
+    const failed = FAIL_TERMINAL.has(run.status);
+    if (isJson()) {
+        if (failed) {
+            return emitFail("runs", {
+                message: run.error || run.statusMessage || `Run ${run.status}`,
+                exitCode: EXIT_USAGE,
+                data: { slug, action: "wait", run },
+            });
+        }
+        emitOk("runs", { slug, action: "wait", run });
+        return EXIT_OK;
+    }
+    printRun(run);
+    return failed ? EXIT_USAGE : EXIT_OK;
+}
 export async function runRuns(args) {
     try {
         const sub = args[0];
@@ -84,17 +104,7 @@ async function waitRun(args) {
             progress(`\r${data.run.status}  ${data.run.statusMessage ?? ""}   `);
             if (TERMINAL.has(data.run.status)) {
                 progress("\n");
-                if (isJson()) {
-                    emitOk("runs", { slug, action: "wait", run: data.run });
-                }
-                else {
-                    printRun(data.run);
-                }
-                if (data.run.status === "failed")
-                    return EXIT_USAGE;
-                if (data.run.status === "canceled")
-                    return EXIT_USAGE;
-                return EXIT_OK;
+                return finishWait(slug, data.run);
             }
         }
         else {
@@ -107,13 +117,17 @@ async function waitRun(args) {
                 progress(`\r${current.status}  ${current.statusMessage ?? ""}   `);
                 if (TERMINAL.has(current.status) && !data.poll?.active) {
                     progress("\n");
-                    if (isJson()) {
-                        emitOk("runs", { slug, action: "wait", run: current });
-                    }
-                    else {
-                        printRun(current);
+                    // Refresh full run for error field when list view is thin.
+                    if (!current.error) {
+                        try {
+                            const full = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs/${encodeURIComponent(current.id)}`);
+                            return finishWait(slug, full.run);
+                        }
+                        catch {
+                            return finishWait(slug, current);
+                        }
                     }
-                    return current.status === "succeeded" ? EXIT_OK : EXIT_USAGE;
+                    return finishWait(slug, current);
                 }
             }
             else {

package/dist/commands/wait-agent-idle.d.ts

@@ -0,0 +1,49 @@
+export type WaitRunSnapshot = {
+    id: string;
+    status: string;
+    statusMessage?: string | null;
+    summary?: string | null;
+    error?: string | null;
+    commitSha?: string | null;
+};
+export type WaitIdleResult = {
+    exitCode: number;
+    /** Run that determined the outcome (watched busy run, or latest when idle). */
+    run: WaitRunSnapshot | null;
+    /** True when we observed queued/running/deploying during this wait. */
+    observedBusy: boolean;
+    status: string;
+};
+export declare function isBusyStatus(status: string): boolean;
+export declare function isFailTerminal(status: string): boolean;
+/**
+ * Decide exit after idle. Pure — unit-tested.
+ * - If we watched a busy run end: succeeded → 0; failed/canceled → 2.
+ * - If never busy: optional fail-closed on latest terminal failure (deploy wait);
+ *   otherwise idle/succeeded → 0 (push --wait after a file-only push).
+ */
+export declare function decideIdleExit(args: {
+    watched: WaitRunSnapshot | null;
+    latest: WaitRunSnapshot | null;
+    observedBusy: boolean;
+    failClosedOnIdleTerminalFailure: boolean;
+}): {
+    exitCode: number;
+    run: WaitRunSnapshot | null;
+    status: string;
+};
+export declare function waitForAgentIdle(args: {
+    slug: string;
+    /** When true, idle + latest failed/canceled → non-zero (deploy wait). */
+    failClosedOnIdleTerminalFailure: boolean;
+    maxMs?: number;
+    pollMs?: number;
+}): Promise<WaitIdleResult>;
+/** Emit deploy/push-wait JSON or text from a WaitIdleResult. */
+export declare function emitWaitOutcome(args: {
+    command: "deploy" | "push";
+    slug: string;
+    result: WaitIdleResult;
+    /** Extra fields merged into JSON data (e.g. push commitSha). */
+    extra?: Record<string, unknown>;
+}): number;