frontpage-host 0.1.6 → 0.1.8

package/AGENTS.md

@@ -119,10 +119,21 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 
 ```bash
 frontpage prompt "make the hero shorter"
-frontpage runs wait          # wait for the agent run to finish
+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 (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.
+- `--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.
 
 ## Content / JSON-native commands
@@ -165,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/prompt-attach.d.ts

@@ -0,0 +1,59 @@
+/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts (images/docs/text only via proxy media). */
+export declare const CLI_ATTACH_LIMITS: {
+    readonly maxImages: 6;
+    readonly maxDocuments: 4;
+    readonly maxTextFiles: 6;
+};
+export type PromptAttachmentsPayload = {
+    images: Array<{
+        url: string;
+        name?: string;
+    }>;
+    documents: Array<{
+        url: string;
+        name?: string;
+    }>;
+    textFiles: Array<{
+        name: string;
+        content: string;
+    }>;
+};
+export type MediaUploadResult = {
+    kind: string;
+    url?: string;
+    key?: string;
+    filename?: string;
+    sizeBytes?: number;
+    content?: string;
+};
+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 addHttpsRef(out: PromptAttachmentsPayload, url: string, opts?: {
+    name?: string;
+    asImageOnly?: boolean;
+}): void;
+export declare function addUploadResult(out: PromptAttachmentsPayload, data: MediaUploadResult): void;
+export declare function uploadLocalForAttach(slug: string, filePath: string): Promise<MediaUploadResult>;
+export declare function resolveSitePathUrl(slug: string, sitePath: string): Promise<{
+    url: string;
+    name: string;
+    type: string;
+}>;
+/**
+ * Resolve one --attach value (local path, /__media/…, or https URL) into the payload.
+ */
+export declare function resolveAttachRef(slug: string, ref: string, out: PromptAttachmentsPayload): Promise<void>;
+export declare function buildPromptAttachments(args: {
+    slug: string;
+    attachRefs: string[];
+    assetUrls: string[];
+}): Promise<PromptAttachmentsPayload | undefined>;
+/** Parse prompt argv: prompt words + --path / --attach / --asset-url flags. */
+export declare function parsePromptArgs(rest: string[]): {
+    prompt: string;
+    currentPath: string;
+    attachRefs: string[];
+    assetUrls: string[];
+};

package/dist/commands/prompt-attach.js

@@ -0,0 +1,207 @@
+/**
+ * §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`.
+ */
+import { access, readFile } from "node:fs/promises";
+import { basename } from "node:path";
+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). */
+export const CLI_ATTACH_LIMITS = {
+    maxImages: 6,
+    maxDocuments: 4,
+    maxTextFiles: 6,
+};
+export function emptyAttachments() {
+    return { images: [], documents: [], textFiles: [] };
+}
+export function isHttpsUrl(s) {
+    return /^https:\/\/[^\s]+$/i.test(s) && s.length <= 2048;
+}
+export function isMediaSitePath(s) {
+    return s.startsWith("/__media/");
+}
+export function classifyRemoteByName(nameOrUrl) {
+    const base = nameOrUrl.split(/[?#]/)[0] ?? nameOrUrl;
+    const ext = base.includes(".") ? (base.split(".").pop() ?? "").toLowerCase() : "";
+    if (ext === "pdf")
+        return "document";
+    return "image";
+}
+function pushUniqueUrl(list, max, url, name, label) {
+    if (list.some((x) => x.url === url))
+        return;
+    if (list.length >= max) {
+        throw new CliHttpError(`Too many ${label} attachments (max ${max}).`, EXIT_USAGE, 400, "bad_request");
+    }
+    list.push(name ? { url, name } : { url });
+}
+function pushText(list, name, content) {
+    if (list.length >= CLI_ATTACH_LIMITS.maxTextFiles) {
+        throw new CliHttpError(`Too many text attachments (max ${CLI_ATTACH_LIMITS.maxTextFiles}).`, EXIT_USAGE, 400, "bad_request");
+    }
+    list.push({ name, content });
+}
+export function addHttpsRef(out, url, opts) {
+    if (!isHttpsUrl(url)) {
+        throw new CliHttpError(`Not an https URL: ${url}`, EXIT_USAGE, 400, "bad_request");
+    }
+    const kind = opts?.asImageOnly ? "image" : classifyRemoteByName(opts?.name ?? url);
+    if (kind === "document") {
+        pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, url, opts?.name, "document");
+    }
+    else {
+        pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, url, opts?.name, "image");
+    }
+}
+export function addUploadResult(out, data) {
+    const name = data.filename?.trim() || undefined;
+    if (data.kind === "text") {
+        if (typeof data.content !== "string" || !data.content) {
+            throw new CliHttpError("Text upload returned no content.", EXIT_UNEXPECTED, 500, "internal");
+        }
+        pushText(out.textFiles, name ?? "snippet.txt", data.content);
+        return;
+    }
+    if (data.kind === "image" || data.kind === "document") {
+        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");
+        }
+        else {
+            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");
+}
+export async function uploadLocalForAttach(slug, filePath) {
+    try {
+        await access(filePath, fsConstants.R_OK);
+    }
+    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);
+}
+export async function resolveSitePathUrl(slug, sitePath) {
+    const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/media`);
+    const norm = (p) => p.replace(/\/+/g, "/").replace(/\/$/, "") || p;
+    const want = norm(sitePath);
+    const hit = data.assets.find((a) => a.sitePath === sitePath || norm(a.sitePath) === want);
+    if (!hit?.url) {
+        throw new CliHttpError(`No media asset found for ${sitePath}. Upload with frontpage media upload, or pass a Blob https URL.`, EXIT_USAGE, 404, "not_found");
+    }
+    return { url: hit.url, name: hit.name, type: hit.type };
+}
+/**
+ * Resolve one --attach value (local path, /__media/…, or https URL) into the payload.
+ */
+export async function resolveAttachRef(slug, ref, out) {
+    const raw = ref.trim();
+    if (!raw) {
+        throw new CliHttpError("--attach requires a path or URL", EXIT_USAGE, 400, "bad_request");
+    }
+    if (/^https?:\/\//i.test(raw)) {
+        if (!isHttpsUrl(raw)) {
+            throw new CliHttpError(`--attach URLs must be https:// (got ${raw.split(":")[0]}://)`, EXIT_USAGE, 400, "bad_request");
+        }
+        addHttpsRef(out, raw);
+        return;
+    }
+    if (isMediaSitePath(raw)) {
+        const asset = await resolveSitePathUrl(slug, raw);
+        const kind = classifyRemoteByName(asset.name || asset.type || raw);
+        if (kind === "document") {
+            pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, asset.url, asset.name, "document");
+        }
+        else {
+            pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, asset.url, asset.name, "image");
+        }
+        return;
+    }
+    const uploaded = await uploadLocalForAttach(slug, raw);
+    addUploadResult(out, uploaded);
+}
+export async function buildPromptAttachments(args) {
+    if (args.attachRefs.length === 0 && args.assetUrls.length === 0)
+        return undefined;
+    const out = emptyAttachments();
+    for (const url of args.assetUrls) {
+        addHttpsRef(out, url.trim(), { asImageOnly: true });
+    }
+    for (const ref of args.attachRefs) {
+        await resolveAttachRef(args.slug, ref, out);
+    }
+    if (out.images.length === 0 &&
+        out.documents.length === 0 &&
+        out.textFiles.length === 0) {
+        throw new CliHttpError("No attachments could be resolved from --attach / --asset-url.", EXIT_USAGE, 400, "bad_request");
+    }
+    return out;
+}
+/** Parse prompt argv: prompt words + --path / --attach / --asset-url flags. */
+export function parsePromptArgs(rest) {
+    let currentPath = "/";
+    const promptParts = [];
+    const attachRefs = [];
+    const assetUrls = [];
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--path") {
+            currentPath = rest[++i] ?? "/";
+            continue;
+        }
+        if (a.startsWith("--path=")) {
+            currentPath = a.slice("--path=".length) || "/";
+            continue;
+        }
+        if (a === "--attach") {
+            const v = rest[++i];
+            if (!v || v.startsWith("--")) {
+                throw new CliHttpError('Usage: frontpage prompt "…" --attach <file|/__media/…|https://…>', EXIT_USAGE, 400, "bad_request");
+            }
+            attachRefs.push(v);
+            continue;
+        }
+        if (a.startsWith("--attach=")) {
+            const v = a.slice("--attach=".length);
+            if (!v) {
+                throw new CliHttpError("--attach= requires a value", EXIT_USAGE, 400, "bad_request");
+            }
+            attachRefs.push(v);
+            continue;
+        }
+        if (a === "--asset-url") {
+            const v = rest[++i];
+            if (!v || v.startsWith("--")) {
+                throw new CliHttpError("Usage: frontpage prompt \"…\" --asset-url <https://…>", EXIT_USAGE, 400, "bad_request");
+            }
+            assetUrls.push(v);
+            continue;
+        }
+        if (a.startsWith("--asset-url=")) {
+            const v = a.slice("--asset-url=".length);
+            if (!v) {
+                throw new CliHttpError("--asset-url= requires a value", EXIT_USAGE, 400, "bad_request");
+            }
+            assetUrls.push(v);
+            continue;
+        }
+        promptParts.push(a);
+    }
+    return {
+        prompt: promptParts.join(" ").trim(),
+        currentPath,
+        attachRefs,
+        assetUrls,
+    };
+}

package/dist/commands/prompt.js

@@ -1,38 +1,48 @@
 import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, v1Post } from "../http/client.js";
 import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
+import { buildPromptAttachments, parsePromptArgs } from "./prompt-attach.js";
 export async function runPrompt(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
-        let currentPath = "/";
-        const promptParts = [];
-        for (let i = 0; i < rest.length; i++) {
-            const a = rest[i];
-            if (a === "--path") {
-                currentPath = rest[++i] ?? "/";
-                continue;
-            }
-            if (a.startsWith("--path=")) {
-                currentPath = a.slice("--path=".length) || "/";
-                continue;
-            }
-            promptParts.push(a);
-        }
-        const prompt = promptParts.join(" ").trim();
+        const { prompt, currentPath, attachRefs, assetUrls } = parsePromptArgs(rest);
         if (!prompt) {
-            return emitUsage("prompt", 'Usage: frontpage prompt "..." [--site <slug>] [--path /page]', EXIT_USAGE);
+            return emitUsage("prompt", 'Usage: frontpage prompt "..." [--site <slug>] [--path /page] [--attach <file|/__media/…|https://…>]… [--asset-url <https://…>]…', EXIT_USAGE);
         }
         if (!currentPath.startsWith("/")) {
             return emitUsage("prompt", "currentPath must start with /", EXIT_USAGE);
         }
-        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs`, { prompt, currentPath });
+        const attachments = await buildPromptAttachments({ slug, attachRefs, assetUrls });
+        const body = { prompt, currentPath };
+        if (attachments) {
+            body.attachments = attachments;
+            // Legacy image list for run display / back-compat readers.
+            body.assetUrls = attachments.images.map((i) => i.url);
+        }
+        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs`, body);
         if (isJson()) {
-            emitOk("prompt", { slug, ...data });
+            emitOk("prompt", {
+                slug,
+                ...data,
+                attached: attachments
+                    ? {
+                        images: attachments.images.length,
+                        documents: attachments.documents.length,
+                        textFiles: attachments.textFiles.length,
+                    }
+                    : undefined,
+            });
         }
         else {
             console.log(data.runId);
             if (data.coalesced)
                 console.error("(coalesced with an identical queued run)");
+            if (attachments) {
+                const n = attachments.images.length +
+                    attachments.documents.length +
+                    attachments.textFiles.length;
+                console.error(`(attached ${n} file${n === 1 ? "" : "s"})`);
+            }
         }
         return EXIT_OK;
     }

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/completions/generate.js

@@ -26,6 +26,7 @@ _frontpage_completions() {
     analytics) COMPREPLY=( $(compgen -W "dashboard summary query funnel timeseries compare sql" -- "\${cur}") ) ;;
     modules) COMPREPLY=( $(compgen -W "list docs request-setup enable disable archive config" -- "\${cur}") ) ;;
     extensions) COMPREPLY=( $(compgen -W "list docs enable disable config" -- "\${cur}") ) ;;
+    prompt) COMPREPLY=( $(compgen -W "--path --attach --asset-url --site --json --help" -- "\${cur}") ) ;;
     *) COMPREPLY=( $(compgen -W "--site --help --json --quiet --yes" -- "\${cur}") ) ;;
   esac
 }

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)",
@@ -184,11 +191,23 @@ export const COMMANDS = [
     {
         name: "prompt",
         summary: "Enqueue an agent build",
-        usage: 'frontpage prompt "..." [--site <slug>] [--path /] [--json]',
+        usage: 'frontpage prompt "..." [--site <slug>] [--path /] [--attach <file|/__media/…|https://…>]… [--asset-url <https://…>]… [--json]',
         topics: ["agent"],
-        examples: ['frontpage prompt "make the hero shorter"'],
-        flags: ["--path must start with /", "stdout is bare runId (or JSON with --json)"],
-        seeAlso: ["runs", "deploy"],
+        examples: [
+            'frontpage prompt "make the hero shorter"',
+            'frontpage prompt "Use this logo in the header" --attach ./logo.png',
+            'frontpage prompt "Match this PDF brand guide" --attach ./guide.pdf --path /',
+            'frontpage prompt "Reuse uploaded art" --attach /__media/uploads/acme/uuid.png',
+            'frontpage prompt "Use this image" --asset-url "https://….blob.vercel-storage.com/uploads/…"',
+        ],
+        flags: [
+            "--path must start with /",
+            "--attach: local file (uploads via media), /__media/… site path, or https Blob URL; repeatable",
+            "--asset-url: https image URL (legacy); repeatable",
+            "Local attach uses the same caps as frontpage media upload (images/PDF/text; no CLI video yet)",
+            "stdout is bare runId (or JSON with --json)",
+        ],
+        seeAlso: ["runs", "deploy", "media"],
     },
     {
         name: "runs",
@@ -203,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"],
     },
     {
@@ -236,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",
         ],
     },
     {
@@ -410,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]
@@ -419,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.
@@ -467,11 +491,13 @@ export const TOPICS = {
   See also: frontpage help sync | content | AGENTS.md`,
     agent: `Agent + publish
   frontpage prompt "make the hero shorter"
+  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
@@ -482,8 +508,10 @@ export const TOPICS = {
   frontpage modules request-setup <key> --reason "…"
   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>
@@ -532,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

@@ -10,11 +10,13 @@
 - Search flags: --regex --case-sensitive --whole-word --files-only --context-lines --max-results
 - 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.6",
+  "version": "0.1.8",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {