frontpage-host 0.1.7 → 0.1.8

package/AGENTS.md

@@ -122,7 +122,7 @@ 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 runs wait          # wait for the agent run to finish (failed/canceled → exit 2)
 # Review https://<subdomain>.frontpage.host — do not publish unless asked.
 ```
 
@@ -130,6 +130,9 @@ frontpage runs wait          # wait for the agent run to finish
 - `--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).
 - 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 +176,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/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;

package/dist/commands/wait-agent-idle.js

@@ -0,0 +1,181 @@
+/**
+ * §CLI Phase D — shared wait for agent-run busy states (queued/running/deploying).
+ * Used by `deploy wait` and `push --wait`. Not a Vercel deploy oracle.
+ */
+import { EXIT_OK, EXIT_USAGE, v1Get } from "../http/client.js";
+import { emitFail, emitOk, isJson, progress } from "../runtime.js";
+const BUSY = new Set(["queued", "running", "deploying"]);
+const FAIL_TERMINAL = new Set(["failed", "canceled"]);
+export function isBusyStatus(status) {
+    return BUSY.has(status);
+}
+export function isFailTerminal(status) {
+    return FAIL_TERMINAL.has(status);
+}
+/**
+ * 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 function decideIdleExit(args) {
+    if (args.observedBusy && args.watched) {
+        const status = args.watched.status;
+        // Stale snapshot still busy → not success (caller should keep polling).
+        if (isBusyStatus(status)) {
+            return { exitCode: EXIT_USAGE, run: args.watched, status: "still_busy" };
+        }
+        if (isFailTerminal(status)) {
+            return { exitCode: EXIT_USAGE, run: args.watched, status };
+        }
+        return { exitCode: EXIT_OK, run: args.watched, status: status || "succeeded" };
+    }
+    const latest = args.latest;
+    if (args.failClosedOnIdleTerminalFailure &&
+        latest &&
+        isFailTerminal(latest.status)) {
+        return { exitCode: EXIT_USAGE, run: latest, status: latest.status };
+    }
+    return {
+        exitCode: EXIT_OK,
+        run: latest,
+        status: latest?.status ?? "idle",
+    };
+}
+export async function waitForAgentIdle(args) {
+    const maxMs = args.maxMs ?? 30 * 60 * 1000;
+    const pollMs = args.pollMs ?? 2000;
+    const started = Date.now();
+    let observedBusy = false;
+    let watched = null;
+    while (Date.now() - started < maxMs) {
+        const data = await v1Get(`/api/v1/sites/${encodeURIComponent(args.slug)}/agent-runs`);
+        const busy = (data.active ?? []).filter((r) => isBusyStatus(r.status));
+        if (busy.length > 0) {
+            observedBusy = true;
+            // If we were watching a run that left the active set, resolve it before
+            // switching — otherwise a failed run can be skipped when the next starts.
+            if (watched && !busy.some((r) => r.id === watched.id)) {
+                try {
+                    const detail = await v1Get(`/api/v1/sites/${encodeURIComponent(args.slug)}/agent-runs/${encodeURIComponent(watched.id)}`);
+                    if (detail.run && isFailTerminal(detail.run.status)) {
+                        progress("\n");
+                        return {
+                            exitCode: EXIT_USAGE,
+                            run: detail.run,
+                            observedBusy: true,
+                            status: detail.run.status,
+                        };
+                    }
+                }
+                catch {
+                    // Fall through and follow the new busy head.
+                }
+            }
+            const prevId = watched?.id;
+            const still = prevId
+                ? busy.find((r) => r.id === prevId)
+                : undefined;
+            const next = still ?? busy.find((r) => r.status === "deploying") ?? busy[0];
+            watched = next;
+            progress(`\r${next.status}  ${next.statusMessage ?? ""}   `);
+            await new Promise((r) => setTimeout(r, pollMs));
+            continue;
+        }
+        // Idle — if we were watching a busy run, refresh it for terminal fields (error).
+        if (observedBusy && watched) {
+            const watching = watched;
+            let refreshed = watching;
+            try {
+                const detail = await v1Get(`/api/v1/sites/${encodeURIComponent(args.slug)}/agent-runs/${encodeURIComponent(watching.id)}`);
+                if (detail.run)
+                    refreshed = detail.run;
+            }
+            catch {
+                // Fall back to list `run` only when it is the same id.
+                if (data.run?.id === watching.id)
+                    refreshed = data.run;
+            }
+            watched = refreshed;
+            // Active list cleared but our snapshot is still busy → keep polling.
+            if (isBusyStatus(refreshed.status)) {
+                progress(`\r${refreshed.status}  ${refreshed.statusMessage ?? ""}   `);
+                await new Promise((r) => setTimeout(r, pollMs));
+                continue;
+            }
+        }
+        progress("\n");
+        const decided = decideIdleExit({
+            watched,
+            latest: data.run,
+            observedBusy,
+            failClosedOnIdleTerminalFailure: args.failClosedOnIdleTerminalFailure,
+        });
+        return {
+            exitCode: decided.exitCode,
+            run: decided.run,
+            observedBusy,
+            status: decided.status,
+        };
+    }
+    progress("\n");
+    return {
+        exitCode: EXIT_USAGE,
+        run: watched,
+        observedBusy,
+        status: "timed_out",
+    };
+}
+/** Emit deploy/push-wait JSON or text from a WaitIdleResult. */
+export function emitWaitOutcome(args) {
+    const { result } = args;
+    const message = result.status === "timed_out"
+        ? "Timed out waiting for deploy."
+        : result.status === "still_busy"
+            ? "Timed out waiting for deploy (run still busy)."
+            : result.run?.error ||
+                result.run?.statusMessage ||
+                (isFailTerminal(result.status)
+                    ? `Latest run ${result.status}`
+                    : result.status);
+    if (result.exitCode !== EXIT_OK) {
+        if (isJson()) {
+            return emitFail(args.command, {
+                message,
+                exitCode: result.exitCode,
+                data: {
+                    slug: args.slug,
+                    waited: true,
+                    observedBusy: result.observedBusy,
+                    status: result.status,
+                    run: result.run,
+                    ...args.extra,
+                },
+            });
+        }
+        if (result.run) {
+            console.error(`${result.run.id}  ${result.run.status}${result.run.error ? `  ${result.run.error}` : result.run.statusMessage ? `  ${result.run.statusMessage}` : ""}`);
+        }
+        else {
+            console.error(message);
+        }
+        return result.exitCode;
+    }
+    if (isJson()) {
+        emitOk(args.command, {
+            slug: args.slug,
+            waited: true,
+            observedBusy: result.observedBusy,
+            status: result.status,
+            run: result.run,
+            ...args.extra,
+        });
+    }
+    else if (result.run) {
+        console.log(`${result.run.id}  ${result.run.status}${result.run.statusMessage ? `  ${result.run.statusMessage}` : ""}`);
+    }
+    else {
+        console.log("No active deploy.");
+    }
+    return EXIT_OK;
+}

package/dist/http/client.d.ts

@@ -3,13 +3,6 @@ export declare const EXIT_USAGE = 2;
 export declare const EXIT_CONFLICT = 3;
 export declare const EXIT_AUTH = 4;
 export declare const EXIT_UNEXPECTED = 5;
-export declare class CliHttpError extends Error {
-    readonly exitCode: number;
-    readonly status: number;
-    readonly code?: string;
-    constructor(message: string, exitCode: number, status: number, code?: string);
-}
-export declare function apiBase(): string;
 export type V1Envelope = {
     error?: {
         code?: string;
@@ -17,6 +10,17 @@ export type V1Envelope = {
         requestId?: string;
     };
 };
+export declare class CliHttpError extends Error {
+    readonly exitCode: number;
+    readonly status: number;
+    readonly code?: string;
+    /** v1 envelope requestId when the API returned one (§CLI Phase D). */
+    readonly requestId?: string;
+    constructor(message: string, exitCode: number, status: number, code?: string, requestId?: string);
+}
+/** Map a non-OK v1 response into CliHttpError (shared by JSON + multipart clients). */
+export declare function httpErrorFromV1(status: number, parsed: V1Envelope, fallbackMessage?: string): CliHttpError;
+export declare function apiBase(): string;
 export declare function v1Get<T>(path: string): Promise<T>;
 export declare function v1Post<T>(path: string, body?: unknown): Promise<T>;
 export declare function v1Put<T>(path: string, body?: unknown): Promise<T>;

package/dist/http/client.js

@@ -12,14 +12,49 @@ export class CliHttpError extends Error {
     exitCode;
     status;
     code;
-    constructor(message, exitCode, status, code) {
+    /** v1 envelope requestId when the API returned one (§CLI Phase D). */
+    requestId;
+    constructor(message, exitCode, status, code, requestId) {
         super(message);
         this.name = "CliHttpError";
         this.exitCode = exitCode;
         this.status = status;
         this.code = code;
+        this.requestId = requestId;
     }
 }
+/** Map a non-OK v1 response into CliHttpError (shared by JSON + multipart clients). */
+export function httpErrorFromV1(status, parsed, fallbackMessage) {
+    const message = parsed.error?.message ?? fallbackMessage ?? `Request failed (${status})`;
+    const code = parsed.error?.code;
+    const requestId = parsed.error?.requestId;
+    if (status === 401 || status === 403) {
+        return new CliHttpError(message, EXIT_AUTH, status, code, requestId);
+    }
+    if (status === 400 || code === "bad_request") {
+        return new CliHttpError(message, EXIT_USAGE, status, code, requestId);
+    }
+    if (status === 402 || status === 429 || code === "rate_limited" || code === "payment_required") {
+        return new CliHttpError(message, EXIT_USAGE, status, code, requestId);
+    }
+    if (status === 409 || code === "conflict") {
+        return new CliHttpError(message, EXIT_CONFLICT, status, code, requestId);
+    }
+    if (status === 413 || code === "payload_too_large") {
+        return new CliHttpError(message, EXIT_USAGE, status, code, requestId);
+    }
+    if (status === 503 || code === "unavailable") {
+        return new CliHttpError(message, EXIT_USAGE, status, code, requestId);
+    }
+    if (status === 404) {
+        const lower = message.toLowerCase();
+        if (lower === "not found." || lower === "not found") {
+            return new CliHttpError("API not available (is PUBLIC_CLI_ENABLED on for this environment?).", EXIT_UNEXPECTED, status, code, requestId);
+        }
+        return new CliHttpError(message, EXIT_AUTH, status, code, requestId);
+    }
+    return new CliHttpError(message, EXIT_UNEXPECTED, status, code, requestId);
+}
 export function apiBase() {
     const fromEnv = process.env.FRONTPAGE_API_BASE?.replace(/\/$/, "");
     if (fromEnv)
@@ -58,31 +93,7 @@ async function v1Request(method, path, body) {
     }
     if (res.ok)
         return parsed;
-    const message = parsed.error?.message ?? `Request failed (${res.status})`;
-    const code = parsed.error?.code;
-    if (res.status === 401 || res.status === 403) {
-        throw new CliHttpError(message, EXIT_AUTH, res.status, code);
-    }
-    if (res.status === 402 || res.status === 429 || code === "rate_limited" || code === "payment_required") {
-        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
-    }
-    if (res.status === 409 || code === "conflict") {
-        throw new CliHttpError(message, EXIT_CONFLICT, res.status, code);
-    }
-    if (res.status === 413 || code === "payload_too_large") {
-        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
-    }
-    if (res.status === 503 || code === "unavailable") {
-        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
-    }
-    if (res.status === 404) {
-        const lower = message.toLowerCase();
-        if (lower === "not found." || lower === "not found") {
-            throw new CliHttpError("API not available (is PUBLIC_CLI_ENABLED on for this environment?).", EXIT_UNEXPECTED, res.status, code);
-        }
-        throw new CliHttpError(message, EXIT_AUTH, res.status, code);
-    }
-    throw new CliHttpError(message, EXIT_UNEXPECTED, res.status, code);
+    throw httpErrorFromV1(res.status, parsed);
 }
 export async function v1Get(path) {
     return v1Request("GET", path);
@@ -130,31 +141,7 @@ export async function v1PostMultipart(path, form) {
     }
     if (res.ok)
         return parsed;
-    const message = parsed.error?.message ?? `Request failed (${res.status})`;
-    const code = parsed.error?.code;
-    if (res.status === 401 || res.status === 403) {
-        throw new CliHttpError(message, EXIT_AUTH, res.status, code);
-    }
-    if (res.status === 402 || res.status === 429 || code === "rate_limited" || code === "payment_required") {
-        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
-    }
-    if (res.status === 409 || code === "conflict") {
-        throw new CliHttpError(message, EXIT_CONFLICT, res.status, code);
-    }
-    if (res.status === 413 || code === "payload_too_large") {
-        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
-    }
-    if (res.status === 503 || code === "unavailable") {
-        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
-    }
-    if (res.status === 404) {
-        const lower = message.toLowerCase();
-        if (lower === "not found." || lower === "not found") {
-            throw new CliHttpError("API not available (is PUBLIC_CLI_ENABLED on for this environment?).", EXIT_UNEXPECTED, res.status, code);
-        }
-        throw new CliHttpError(message, EXIT_AUTH, res.status, code);
-    }
-    throw new CliHttpError(message, EXIT_UNEXPECTED, res.status, code);
+    throw httpErrorFromV1(res.status, parsed);
 }
 export function exitCodeForError(err) {
     if (err instanceof CliHttpError)

package/dist/registry.js

@@ -88,10 +88,17 @@ export const COMMANDS = [
     {
         name: "push",
         summary: "Upload local allowlisted files (CAS + active-run guard)",
-        usage: "frontpage push [--site <slug>] [--message …] [--json]",
+        usage: "frontpage push [--site <slug>] [--message …] [--wait] [--json]",
         topics: ["sync"],
-        examples: ['frontpage push --message "Update hero copy"'],
-        flags: ["--site <slug>", "--message <text>"],
+        examples: [
+            'frontpage push --message "Update hero copy"',
+            'frontpage push --message "…" --wait',
+        ],
+        flags: [
+            "--site <slug>",
+            "--message <text>",
+            "--wait: after push, wait until no agent run is queued/running/deploying (same as deploy wait; not a Vercel oracle)",
+        ],
         dangers: [
             "Requires prior pull (baseCommitSha)",
             "Refused while an agent run is active (exit 3)",
@@ -215,7 +222,10 @@ export const COMMANDS = [
             "frontpage runs retry <runId>",
             "frontpage runs get <runId>",
         ],
-        flags: ["There is no runs continue — mid-task continuation is automatic"],
+        flags: [
+            "There is no runs continue — mid-task continuation is automatic",
+            "runs wait: failed/canceled → exit 2; --json uses ok:false and includes run.error",
+        ],
         seeAlso: ["prompt", "deploy"],
     },
     {
@@ -248,6 +258,7 @@ export const COMMANDS = [
         flags: [
             "Optional build wait only — staging is https://<subdomain>.frontpage.host",
             "Does NOT promote to production; use publish only when the user asks",
+            "Fail-closed: exit 2 when the waited run (or latest, if already idle) is failed/canceled",
         ],
     },
     {
@@ -422,7 +433,7 @@ export const TOPICS = {
   frontpage status               # tipDrift when remote moved since last pull
   frontpage pull                 # downloads src/, public/, content/ into cwd
   frontpage diff                 # local vs remote via git blobSha (--json → dirty + tipDrift)
-  frontpage push [--message …]   # uploads allowlisted files; CAS + active-run guard
+  frontpage push [--message …] [--wait]   # uploads allowlisted files; CAS + active-run guard
   frontpage ls [prefix]
   frontpage cat <path>
   frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only]
@@ -431,6 +442,7 @@ export const TOPICS = {
   Local state: .frontpage/state.json { slug, baseCommitSha }
   Pull BEFORE EDITING when tip may have moved (UI agent / another checkout) — check tipDrift.
   Pull before push so CAS has baseCommitSha. Do not push while the editor agent is building.
+  --wait after push blocks until no agent run is queued/running/deploying (same as deploy wait).
   The UI/canvas agent does not use this CLI; only CLI checkouts need pull.
   Pushing module markup may auto-activate modules (same as the agent).
   tokens.ts may be auto-repaired at commit if it would break the build.
@@ -482,10 +494,10 @@ export const TOPICS = {
   frontpage prompt "Use this logo" --attach ./logo.png
   frontpage prompt "…" --attach /__media/uploads/<slug>/… --asset-url https://…
   frontpage runs                 # latest + active
-  frontpage runs wait [runId]
+  frontpage runs wait [runId]    # failed/canceled → exit 2; JSON ok:false + run.error
   frontpage runs cancel <runId>
   frontpage runs retry <runId>
-  frontpage deploy wait          # optional: wait for build; NOT publish
+  frontpage deploy wait          # optional build wait; fail-closed on failed/canceled; NOT publish
   frontpage publish              # ONLY if the user asked — production promote
   frontpage unpublish --yes      # admin only; never unless asked; --yes when non-TTY
   frontpage usage
@@ -497,8 +509,9 @@ export const TOPICS = {
   frontpage extensions
 
   --attach uploads local files via media (images/PDF/text) or accepts /__media/… / https URLs.
+  API errors include requestId in --json error envelopes (and stderr when not --json).
   Mid-task continuation is automatic — there is no runs continue.
-  Do not push while an agent run is active.
+  Do not file-sync while an agent run is active (see help sync for push --wait).
   Default after work: review https://<subdomain>.frontpage.host; do not publish.`,
     content: `Content
   frontpage media list|upload <file>
@@ -547,8 +560,9 @@ export const TOPICS = {
 
   Global --json envelope:
     { "ok": true, "command": "…", "data": {…} }
-    { "ok": false, "command": "…", "error": { "message", "code?", "httpStatus?", "exitCode" } }
-  Failures with --json still use the process exit code; envelope is on stdout.`,
+    { "ok": false, "command": "…", "error": { "message", "code?", "httpStatus?", "exitCode", "requestId?" }, "data"? }
+  Failures with --json still use the process exit code; envelope is on stdout.
+  Prefer requestId from error envelopes when filing support issues.`,
 };
 export function findCommand(name) {
     return COMMANDS.find((c) => c.name === name);

package/dist/runtime.d.ts

@@ -13,8 +13,18 @@ export type JsonErrorBody = {
     code?: string;
     httpStatus?: number;
     exitCode: number;
+    requestId?: string;
 };
 export declare function emitOk(command: string, data: unknown): void;
+/** Structured failure with optional data payload (e.g. failed run wait). */
+export declare function emitFail(command: string, args: {
+    message: string;
+    exitCode: number;
+    code?: string;
+    requestId?: string;
+    httpStatus?: number;
+    data?: unknown;
+}): number;
 export declare function emitErr(command: string, err: unknown): number;
 export declare function emitUsage(command: string, message: string, exitCode?: number): number;
 /** Progress / spinner lines — suppressed when --quiet or --json. */

package/dist/runtime.js

@@ -31,23 +31,43 @@ export function requireYesOrTty(action) {
 export function emitOk(command, data) {
     console.log(JSON.stringify({ ok: true, command, data }));
 }
+/** Structured failure with optional data payload (e.g. failed run wait). */
+export function emitFail(command, args) {
+    const body = {
+        message: args.message,
+        exitCode: args.exitCode,
+    };
+    if (args.code)
+        body.code = args.code;
+    if (args.httpStatus)
+        body.httpStatus = args.httpStatus;
+    if (args.requestId)
+        body.requestId = args.requestId;
+    if (jsonMode) {
+        const out = { ok: false, command, error: body };
+        if (args.data !== undefined)
+            out.data = args.data;
+        console.log(JSON.stringify(out));
+    }
+    else {
+        const suffix = args.requestId ? ` (requestId: ${args.requestId})` : "";
+        console.error(`${args.message}${suffix}`);
+    }
+    return args.exitCode;
+}
 export function emitErr(command, err) {
     const exitCode = exitCodeForError(err);
     const message = err instanceof Error ? err.message : String(err);
-    const body = { message, exitCode };
     if (err instanceof CliHttpError) {
-        if (err.code)
-            body.code = err.code;
-        if (err.status)
-            body.httpStatus = err.status;
+        return emitFail(command, {
+            message,
+            exitCode,
+            code: err.code,
+            httpStatus: err.status || undefined,
+            requestId: err.requestId,
+        });
     }
-    if (jsonMode) {
-        console.log(JSON.stringify({ ok: false, command, error: body }));
-    }
-    else {
-        console.error(message);
-    }
-    return exitCode;
+    return emitFail(command, { message, exitCode });
 }
 export function emitUsage(command, message, exitCode = 2) {
     if (jsonMode) {

package/llms.txt

@@ -11,11 +11,12 @@
 - Modules setup: frontpage modules request-setup <key> --reason "…" (owner status bar; CLI cannot show it)
 - Analytics ops: frontpage analytics summary|query|funnel|timeseries|compare|sql (bare analytics = dashboard)
 - Prompt attachments: frontpage prompt "…" --attach <file|/__media/…|https://…> [--asset-url https://…] (media upload for locals; images/PDF/text)
+- Errors: --json error envelopes include requestId; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait fail-closed; push --wait
 - Auth: mint fp_live_ key in Frontpage UI (Developers); frontpage login KEY or FRONTPAGE_API_KEY
 - Site id: subdomain only (frontpage use <subdomain>). Not custom domains.
 - Staging: https://<subdomain>.frontpage.host — push/prompt/edit update staging; no separate staging deploy step for agents
 - Production: custom domain after frontpage publish — NEVER publish/unpublish unless the user explicitly asks
-- Sync: allowlist src/ public/ content/; platform overlay + secret-like paths rejected; pull before edit if tip may have moved (status/diff tipDrift); pull → edit → diff (blobSha) → push (CAS); no push during active agent run; UI agent does not use CLI pull; review on subdomain
+- Sync: allowlist src/ public/ content/; platform overlay + secret-like paths rejected; pull before edit if tip may have moved (status/diff tipDrift); pull → edit → diff (blobSha) → push [--wait] (CAS); no push during active agent run; UI agent does not use CLI pull; review on subdomain
 - Machine: global --json / --quiet; exit 0/2/3/4/5 (see help exit-codes)
-- deploy wait = optional build wait only; it is NOT go-live / publish
+- deploy wait = optional build wait only (fail-closed on failed/canceled); it is NOT go-live / publish
 - No runs continue, domains, billing, members, MCP, or git remotes in v1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {