frontpage-host 0.1.15 → 0.1.17

package/AGENTS.md

@@ -26,17 +26,22 @@ Frontpage has two surfaces:
 | **Staging** | `https://<subdomain>.frontpage.host` | Working copy for edits, previews, and review |
 | **Production** | Custom domain (when connected), after **publish** | What end customers see on the live domain |
 
-**How changes become visible on staging**
+**Three clocks (do not collapse these)**
 
-- `frontpage push`, `frontpage prompt`, and `frontpage edit` update the site branch and the **staging** surface.
-- After a push or agent run finishes building, changes are on the site branch behind `https://<subdomain>.frontpage.host`.
-- There is **no separate “deploy to staging” step** agents must run. Do not treat `frontpage deploy wait` as “going live.” At most it waits for an in-flight build to finish before you open the subdomain to review.
+1. **Git tip** — `frontpage push` / `prompt` / `edit` land a new SHA. Fast.
+2. **Site compile** — Fly (or Vercel on legacy hosts) builds that SHA. This is what visitors get. Poll `GET /api/v1/sites/<slug>/deploy` until `ready` is true (`liveCommit` equals the tip).
+3. **Editor agent run** — a chat job (`queued` / `running` / `deploying`). `frontpage runs wait` watches this clock only.
+
+- After the compile is ready, staging is `https://<subdomain>.frontpage.host`.
+- There is **no separate “deploy to staging” step**. `frontpage deploy wait` waits for agent-run idle (if a run is in flight) **and** for the tip compile. It is not go-live.
+- A file-only push has **no** agent run. Do not treat a historical run that says “Your changes are live” as this push.
 - `frontpage open` opens the subdomain staging URL.
 - **Custom-domain caveat:** `<subdomain>.frontpage.host` is publicly viewable (anonymous) only when the site has **no** custom domain and subdomain sharing is public. If a custom domain is connected (e.g. `arbiter.wiki`), the subdomain is often **owner-private** — an unauthenticated browser/curl may see the app login page. That login wall is **not** a failed push. Anonymous public review is then on the **published custom domain**; editing the subdomain still needs an owner browser session (CLI API key ≠ browser cookie).
 
 **Production publish is a deliberate promote**
 
-- `frontpage publish` copies the current **staging tip** to **production** (custom domain / published site).
+- `frontpage publish` copies the last **ready staging compile** to **production** (custom domain / published site). It 409s if the tip is not compiled yet. Use `frontpage publish --wait` (or `deploy wait` then `publish`) so you do not promote the previous build.
+- After publish, compare `<meta name="frontpage:commit">` on the custom domain to the push SHA. History’s `P` marker is the stamped tip; it is only trustworthy when it matches the SHA in `productionUrl`.
 - **Never run `publish` or `unpublish` unless the user explicitly asked**, or the user’s own automation/workflow clearly requires autonomous publishing.
 - Default: finish work on staging, tell the user to review the staging subdomain when it is publicly shareable (see custom-domain caveat above), and let **them** publish (or ask you to publish after they approve).
 
@@ -90,14 +95,14 @@ Rules:
 4. Push updates **staging** (subdomain). Production is unchanged until someone runs `publish`.
 5. Pushing module markup may auto-activate modules (same as the editor agent).
 6. Binaries use base64; do not UTF-8 round-trip them.
-7. Prefer reviewing the subdomain after push; only use `deploy wait` if you need to block until a build finishes.
+7. After push, wait for the site compile (`frontpage push --wait` or `frontpage deploy wait`) before reviewing or publishing. Verify `<meta name="frontpage:commit">` when checking production.
 8. The **UI / canvas agent does not use this CLI** — it edits the live tip in-process. Only CLI checkouts need `pull`.
 
 ## Site contract (Astro)
 
 Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or https://frontpage.host/developers/site-building
 
-1. **Every page** wraps content in `<BaseLayout title="…" description="…">` (import from `src/layouts/BaseLayout.astro`).
+1. **Every page** wraps content in `<BaseLayout title="…" description="…">` (import from `src/layouts/BaseLayout.astro`), or in a site layout that itself wraps `BaseLayout`. A custom wrapper MUST identity-forward `description={description}` and `ogImage={ogImage}` from a 1:1 `Astro.props` destructure (no default, no rename, no reassignment), and `title={seoTitle ?? <derived fallback>}` so the H1 can stay on `title` while Search & Social edits `seoTitle`. NEVER pass a derived local as `title={pageTitle}` with no `seoTitle` alias: the editor will lock Title and Share image on every page that uses that layout. Pages set literal `title` / `description` / optional `seoTitle` / `ogImage` on that tag.
 2. **`src/config/site.ts`** — keep `pages` (path registry) and `nav` in sync when adding/renaming/deleting page files. Tab title comes from BaseLayout, not the `pages` map label.
 3. **One file per URL** for similar page sets (services, guides, …). Do not default to `getStaticPaths()` over `src/data/*.ts`. Blog/news → `frontpage articles`, not a hand-rolled catalog.
 4. **No backends / databases / fake forms or checkout.** Real forms use `<form data-fp-form="slug">` + `frontpage modules`. Refuse or use modules for payments.
@@ -108,13 +113,14 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 
 ## Modules & articles
 
-- Forms: `data-fp-form` markup in pages + `frontpage modules` for enable/config. No submit JS / honeypot / `action`.
-- Wizard / connect-once modules (payments/shop/ordering): `frontpage modules <key> connect` opens the browser (Stripe or Square). Finish there, then `status`. `--no-open` for CI. `request-setup` remains valid when you want the **editor amber bar** instead. payments and shop share one Stripe account. Auto-active modules (forms/callbar/…) need markup, not request-setup. Typed settings: `frontpage modules callbar|forms|booking|signups get|set` (forms set needs `--instance`; do not target `default`). `frontpage modules <key>` prints that key's CLI usage (exit 2). Index: https://frontpage.host/developers/modules · payments/shop/ordering pages under /developers/modules/<key>
+- Forms: `data-fp-form` markup in pages + `frontpage modules` for enable/config. No submit JS / honeypot / `action`. Do not put a CRM webhook or token in HTML.
+- Wizard / connect-once modules (payments/shop/ordering): `frontpage modules <key> connect` opens Frontpage (you must be logged in there), then Stripe or Square. Already-connected sites stay live — do not retry connect. payments/shop connect needs an **admin** key; ordering connect needs **editor**. `--no-open` for CI. `request-setup` remains valid when you want the **editor amber bar** instead. payments and shop share one Stripe account — payments disconnect fails if the store still uses it. Auto-active modules (forms/callbar/…) need markup, not request-setup. Typed settings: `frontpage modules callbar|forms|booking|signups get|set` (forms set needs `--instance`; do not target `default`). Form destinations (HubSpot / Pipedrive / Privyr): connect once, then attach each form. `frontpage modules forms destinations|connect-destination|attach-destination|detach-destination|remove-destination --yes|request-destination-setup`. Token write is **admin**; `request-destination-setup` lights the editor amber bar (**editor** key). Do not use `request-setup forms` for a CRM (no-op). Connecting does not attach every form. Privyr: paste the Incoming Webhook URL from Automations → Lead Sources → Webhooks (`https://www.privyr.com/api/v1/incoming-leads/…`), not a token and not Outgoing Webhooks. HubSpot: Development → Keys → Service keys or Development → Legacy apps → Auth → Show token. Pipedrive: profile → Company settings → Personal preferences → API. Full docs: https://frontpage.host/developers/modules#forms-destinations. `frontpage modules <key>` prints that key's CLI usage (exit 2). Index: https://frontpage.host/developers/modules · payments/shop/ordering pages under /developers/modules/<key>
 - Google reviews: platform nodes only (`data-fp-google-reviews` / `data-fp-google-ask` + required `data-fp-requires="google_reviews"`). `data-layout` is `feed` (default), `badge`, or `link`. Never invent stars, quotes, a 1–10, or a Maps URL. Do not pick a Place ID via Autocomplete and do not write `placeId` through `modules config`. Owner-supplied Place ID / Maps URL: `frontpage modules google_reviews connect --place-id …` or `--maps-url …` (server resolves + seeds). Curation: `list-reviews`, `hide --id`, `show --id`, `set-stars`, `set-sort`, `set-weight`, `reset-weights`, `refresh`, `disconnect`. Usage: `frontpage modules google_reviews`. Docs: https://frontpage.host/developers/modules/google-reviews. Ask-widget scores: `frontpage inbox google_reviews`.
 - Articles: `frontpage articles …` for lifecycle; bodies via sync under `content/` or `articles content get|set`. Section landing is an owned `src/pages/<section>/index.astro`.
 - Migrate a folder into Articles: prefer `frontpage prompt "migrate … into articles"` — do not invent a mass delete+write migration.
 - Extensions: `frontpage extensions`; if LOCKED on plan, do not fake charts/etc.
 - Media: `frontpage media upload <file>` — images/PDF ≤25 MB, video (MP4/WebM/MOV) ≤50 MB, SVG/text ≤4 MB (sanitizing proxy). Human output prints `sitePath:` first (use that in markup — never raw blob hosts), then optional `url:`. Optional `?w=` on rasters only. **Text/CSV** uploads are inline only — **not** added to the media library and **cannot** be linked via `/__media` (`media upload --json` omits full `content`; use `inbox … --csv` for submission exports).
+- Generated images: `frontpage images generate --prompt "…"` `[--count N]` — one prompt, 1–4 variations of that same picture. Prints `sitePath:` first. Counts against AI $ and storage. Flag-off environments return 404 (`Image generation is not enabled.`). Do not call xAI / Imagine yourself.
 - Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
 
 ## Agent prompt loop
@@ -134,8 +140,9 @@ frontpage runs wait          # wait for the agent run to finish (failed/canceled
 - Caps: images/PDF ≤25 MB, video ≤50 MB, SVG/text via proxy ≤4 MB (large text/data Blob upload is editor-only).
 - Prompt text is still required (API). Attachments ride on the same enqueue as the editor.
 - `runs wait` with `--json`: failures use `ok: false` and include `data.run` (with `run.error` when present).
-- `deploy wait` is fail-closed: exit 2 if the waited run (or latest, when already idle) is `failed`/`canceled`.
-- `frontpage push --wait` waits for agent-run idle after push (same busy statuses; not a separate Vercel oracle).
+- `runs wait` watches an editor agent run only.
+- `deploy wait` is fail-closed on a failed/canceled agent run it actually watched (or a latest failed/canceled when idle). It then waits until `GET /deploy` `ready` (live compile SHA equals the tip). Exit 2 on compile failure or timeout.
+- `frontpage push --wait` does the same compile wait for the SHA just pushed. A file-only push still waits for the compile.
 
 Mid-task continuation is automatic. There is **no** `runs continue` in v1.
 
@@ -217,7 +224,7 @@ Safe default after finishing work: summarize what changed and give the staging U
 6. **Active-run guard.** Push/revert refuse while an editor agent run is active (exit 3).
 7. **CAS.** Tip moved since pull → exit 3; pull and retry.
 8. **No invented v1 commands:** `domains*`, `billing*`, `members*`, `suggestions*`, `sites delete|restore`, `runs continue`, MCP, git remotes / clone URLs.
-9. **`deploy wait` ≠ publish.** Optional build wait only; staging visibility is the subdomain.
+9. **`deploy wait` ≠ publish.** It waits for the tip compile. Production still requires `publish`. Verify live HTML with `<meta name="frontpage:commit">`.
 10. **Honesty on stubs.** `open --prod` is currently a no-op stub (still opens the subdomain).
 
 ## Isolation (hard fence)

package/README.md

@@ -23,9 +23,9 @@ Requires Node.js ≥ 20.
 3. `frontpage sites` — note the **subdomain** (not a custom domain).
 4. `mkdir my-site && cd my-site && frontpage use <subdomain>`
 5. `frontpage pull` → edit files under `src/`, `public/`, or `content/`
-6. `frontpage push --message "describe the change"`
-7. Review staging at `https://<subdomain>.frontpage.host` (no separate staging-deploy step).
-8. `frontpage publish` only when you intentionally promote to production.
+6. `frontpage push --message "describe the change"` (add `--wait` to block until the site compile is live)
+7. Review staging at `https://<subdomain>.frontpage.host` after the compile is ready.
+8. `frontpage publish --wait` only when you intentionally promote the ready compile to production.
 
 ## Environment
 

package/dist/bin.js

@@ -24,6 +24,7 @@ import { runPages } from "./commands/pages.js";
 import { runModules } from "./commands/modules.js";
 import { runExtensions } from "./commands/extensions.js";
 import { runMedia } from "./commands/media.js";
+import { runImages } from "./commands/images.js";
 import { runInbox } from "./commands/inbox.js";
 import { runSeo } from "./commands/seo.js";
 import { runArticles } from "./commands/articles.js";
@@ -107,6 +108,8 @@ async function main() {
             return runExtensions(args);
         case "media":
             return runMedia(args);
+        case "images":
+            return runImages(args);
         case "inbox":
             return runInbox(args);
         case "seo":

package/dist/commands/deploy.d.ts

@@ -1,2 +1,2 @@
-/** `frontpage deploy wait` — wait until no run is in deploying/queued/running. */
+/** `frontpage deploy wait` — agent-run idle, then the tip's site compile. */
 export declare function runDeploy(args: string[]): Promise<number>;

package/dist/commands/deploy.js

@@ -1,8 +1,8 @@
 import { resolveSlug } from "../site.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. */
+import { waitForAgentThenCompile } from "./wait-site-compile.js";
+/** `frontpage deploy wait` — agent-run idle, then the tip's site compile. */
 export async function runDeploy(args) {
     try {
         const sub = args[0];
@@ -10,12 +10,11 @@ export async function runDeploy(args) {
             return emitUsage("deploy", "Usage: frontpage deploy wait [--site <slug>]", EXIT_USAGE);
         }
         const { slug } = await resolveSlug(args.slice(1));
-        const result = await waitForAgentIdle({
+        return waitForAgentThenCompile({
+            command: "deploy",
             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/images.d.ts

@@ -0,0 +1 @@
+export declare function runImages(args: string[]): Promise<number>;

package/dist/commands/images.js

@@ -0,0 +1,57 @@
+import { resolveSlug } from "../site.js";
+import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Post } from "../http/client.js";
+import { assertNoUnknownFlags, takeFlag } from "../argv.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
+const USAGE = 'Usage: frontpage images generate --prompt "…" [--count N] [--site <slug>] [--json]';
+const GENERATE_TIMEOUT_MS = 180_000;
+export async function runImages(args) {
+    try {
+        const { slug, rest } = await resolveSlug(args);
+        const sub = rest[0];
+        if (sub !== "generate") {
+            console.error(USAGE);
+            return EXIT_USAGE;
+        }
+        const work = rest.slice(1);
+        const prompt = takeFlag(work, "--prompt");
+        const countRaw = takeFlag(work, "--count");
+        assertNoUnknownFlags(work, "images");
+        if (work.length > 0) {
+            console.error(`Unexpected argument: ${work[0]}\n${USAGE}`);
+            return EXIT_USAGE;
+        }
+        if (!prompt) {
+            console.error(USAGE);
+            return EXIT_USAGE;
+        }
+        let count;
+        if (countRaw !== undefined) {
+            const n = Number(countRaw);
+            if (!Number.isInteger(n) || n < 1 || n > 4) {
+                console.error("Ask for 1 to 4 variations.");
+                return EXIT_USAGE;
+            }
+            count = n;
+        }
+        const body = { prompt };
+        if (count !== undefined)
+            body.count = count;
+        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/images`, body, { timeoutMs: GENERATE_TIMEOUT_MS });
+        if (isJson()) {
+            emitOk("images", { slug, images: data.images });
+            return EXIT_OK;
+        }
+        for (const img of data.images ?? []) {
+            console.log(`sitePath: ${img.sitePath}`);
+            if (img.filename)
+                console.log(`filename: ${img.filename}`);
+        }
+        return EXIT_OK;
+    }
+    catch (err) {
+        if (isJson())
+            return emitErr("images", err);
+        console.error(err instanceof Error ? err.message : String(err));
+        return exitCodeForError(err);
+    }
+}

package/dist/commands/modules.js

@@ -5,6 +5,7 @@ import { emitUsage } from "../runtime.js";
 import { formatModuleUsage, formatModulesIndex, isCliModuleAction, isDocumentedModuleKey, isGenericModuleVerb, } from "../modules/commands.js";
 import { runGoogleReviews } from "../modules/google_reviews.js";
 import { isTypedConfigCliKey, runTypedConfig } from "../modules/typed_config.js";
+import { isFormsDestinationCliAction, runFormsDestinations } from "../modules/forms_destinations.js";
 import { isOauthCliKey, runOauthHandoff } from "../modules/oauth.js";
 /** Drop --site so we can print local usage without resolving a checkout. */
 function positionalArgs(args) {
@@ -44,6 +45,9 @@ export async function runModules(args) {
                 if (peekedKey === "google_reviews") {
                     return await runGoogleReviews(slug, peekedAction, extraFlags);
                 }
+                if (peekedKey === "forms" && isFormsDestinationCliAction(peekedAction)) {
+                    return await runFormsDestinations(slug, peekedAction, extraFlags);
+                }
                 if (isTypedConfigCliKey(peekedKey)) {
                     return await runTypedConfig(peekedKey, slug, peekedAction, extraFlags);
                 }

package/dist/commands/publish.js

@@ -1,19 +1,77 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, v1Delete, v1Post } from "../http/client.js";
-import { emitErr, emitOk, emitUsage, isJson, requireYesOrTty } from "../runtime.js";
+import { EXIT_OK, EXIT_USAGE, v1Post, v1Delete } from "../http/client.js";
+import { emitErr, emitFail, emitOk, emitUsage, isJson, progress, requireYesOrTty } from "../runtime.js";
+import { describePublishResult, waitForCompileReady } from "../compile.js";
+function takeWaitFlag(rest) {
+    const i = rest.indexOf("--wait");
+    if (i === -1)
+        return false;
+    rest.splice(i, 1);
+    return true;
+}
+function emitPublished(slug, data) {
+    const described = describePublishResult({
+        productionCommit: data.productionCommit ?? null,
+        productionUrl: data.productionUrl ?? null,
+    });
+    if (isJson()) {
+        emitOk("publish", {
+            slug,
+            productionUrl: data.productionUrl ?? null,
+            productionCommit: data.productionCommit ?? null,
+            servingCommit: described.servingCommit,
+            matchesTip: described.matchesTip,
+        });
+    }
+    else {
+        console.log(`Published ${slug}`);
+        for (const line of described.lines)
+            console.log(line);
+        if (data.productionUrl)
+            console.log(data.productionUrl);
+        if (!described.matchesTip) {
+            console.error("Publish promoted a build that is not the current tip. Wait for the site compile, then publish again.");
+        }
+    }
+    return EXIT_OK;
+}
 export async function runPublish(args) {
     try {
-        const { slug } = await resolveSlug(args);
-        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/publish`);
-        if (isJson()) {
-            emitOk("publish", { slug, productionUrl: data.productionUrl ?? null });
+        const { slug, rest } = await resolveSlug(args);
+        const work = [...rest];
+        const wait = takeWaitFlag(work);
+        if (work.length > 0) {
+            return emitUsage("publish", "Usage: frontpage publish [--site <slug>] [--wait] [--json]", EXIT_USAGE);
         }
-        else {
-            console.log(`Published ${slug}`);
-            if (data.productionUrl)
-                console.log(data.productionUrl);
+        if (wait) {
+            if (!isJson())
+                progress("Waiting for the site compile…\n");
+            const compile = await waitForCompileReady({ slug });
+            if (compile.exitCode !== EXIT_OK) {
+                const message = compile.failed
+                    ? "Site compile failed. Refusing to publish a previous build."
+                    : compile.timedOut
+                        ? "Timed out waiting for the site compile. Refusing to publish a previous build."
+                        : "Site compile is not ready. Refusing to publish a previous build.";
+                return emitFail("publish", {
+                    message,
+                    exitCode: compile.exitCode,
+                    data: {
+                        slug,
+                        compile: compile.status,
+                        tip: compile.status?.stagingCommit ?? null,
+                        live: compile.status?.liveCommit ?? null,
+                        status: compile.failed
+                            ? "compile_failed"
+                            : compile.timedOut
+                                ? "compile_timeout"
+                                : "compile_not_ready",
+                    },
+                });
+            }
         }
-        return EXIT_OK;
+        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/publish`);
+        return emitPublished(slug, data);
     }
     catch (err) {
         return emitErr("publish", err);

package/dist/commands/push.js

@@ -4,7 +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";
+import { waitForAgentThenCompile } from "./wait-site-compile.js";
 const TEXT_EXTS = new Set([
     ".astro",
     ".ts",
@@ -136,8 +136,7 @@ export async function runPush(args) {
                 console.error(`Warning: ${w}`);
             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.
+        // --wait: agent-run idle (if any), then the new commit's site compile.
         if (!isJson()) {
             if (!data.changed) {
                 console.log("Nothing to commit (remote already matches).");
@@ -148,17 +147,12 @@ export async function runPush(args) {
             }
             for (const w of data.warnings ?? [])
                 console.error(`Warning: ${w}`);
-            console.error("Waiting for agent run / deploy idle…");
         }
-        const result = await waitForAgentIdle({
-            slug,
-            // Do not fail on an ancient canceled run when this push never saw busy work.
-            failClosedOnIdleTerminalFailure: false,
-        });
-        return emitWaitOutcome({
+        return waitForAgentThenCompile({
             command: "push",
             slug,
-            result,
+            expectCommit: data.commitSha ?? null,
+            failClosedOnIdleTerminalFailure: false,
             extra: { ...pushPayload, waited: true },
         });
     }

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

@@ -16,6 +16,18 @@ export type WaitIdleResult = {
 };
 export declare function isBusyStatus(status: string): boolean;
 export declare function isFailTerminal(status: string): boolean;
+/**
+ * A historical succeeded run is unrelated when this wait never saw busy work.
+ * Keep failed/canceled latest so deploy wait stays fail-closed (Phase D).
+ */
+export declare function sanitizeUnrelatedIdleRun(args: {
+    observedBusy: boolean;
+    run: WaitRunSnapshot | null;
+    status: string;
+}): {
+    run: WaitRunSnapshot | null;
+    status: string;
+};
 /**
  * Decide exit after idle. Pure — unit-tested.
  * - If we watched a busy run end: succeeded → 0; failed/canceled → 2.

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

@@ -1,6 +1,7 @@
 /**
- * §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.
+ * Shared wait for editor agent-run busy states (queued/running/deploying).
+ * This is the agent-run clock, not the site compile. File-only pushes have
+ * no agent run — success here does not mean the latest commit is built.
  */
 import { EXIT_OK, EXIT_USAGE, v1Get } from "../http/client.js";
 import { emitFail, emitOk, isJson, progress } from "../runtime.js";
@@ -12,6 +13,18 @@ export function isBusyStatus(status) {
 export function isFailTerminal(status) {
     return FAIL_TERMINAL.has(status);
 }
+/**
+ * A historical succeeded run is unrelated when this wait never saw busy work.
+ * Keep failed/canceled latest so deploy wait stays fail-closed (Phase D).
+ */
+export function sanitizeUnrelatedIdleRun(args) {
+    if (args.observedBusy)
+        return { run: args.run, status: args.status };
+    if (args.run && isFailTerminal(args.run.status)) {
+        return { run: args.run, status: args.status };
+    }
+    return { run: null, status: "idle" };
+}
 /**
  * Decide exit after idle. Pure — unit-tested.
  * - If we watched a busy run end: succeeded → 0; failed/canceled → 2.
@@ -111,11 +124,16 @@ export async function waitForAgentIdle(args) {
             observedBusy,
             failClosedOnIdleTerminalFailure: args.failClosedOnIdleTerminalFailure,
         });
+        const sanitized = sanitizeUnrelatedIdleRun({
+            observedBusy,
+            run: decided.run,
+            status: decided.status,
+        });
         return {
             exitCode: decided.exitCode,
-            run: decided.run,
+            run: sanitized.run,
             observedBusy,
-            status: decided.status,
+            status: sanitized.status,
         };
     }
     progress("\n");
@@ -175,7 +193,7 @@ export function emitWaitOutcome(args) {
         console.log(`${result.run.id}  ${result.run.status}${result.run.statusMessage ? `  ${result.run.statusMessage}` : ""}`);
     }
     else {
-        console.log("No active deploy.");
+        console.log("No agent run was in flight. This does not mean the latest commit is compiled.");
     }
     return EXIT_OK;
 }

package/dist/commands/wait-site-compile.d.ts

@@ -0,0 +1,21 @@
+import { type DeployStatus } from "../compile.js";
+import { type WaitIdleResult } from "./wait-agent-idle.js";
+export declare function waitForAgentThenCompile(args: {
+    command: "deploy" | "push";
+    slug: string;
+    expectCommit?: string | null;
+    failClosedOnIdleTerminalFailure: boolean;
+    extra?: Record<string, unknown>;
+}): Promise<number>;
+export declare function emitCompileWaitOutcome(args: {
+    command: "deploy" | "push";
+    slug: string;
+    agent: WaitIdleResult;
+    compile: {
+        exitCode: number;
+        timedOut: boolean;
+        failed?: boolean;
+        status: DeployStatus | null;
+    };
+    extra?: Record<string, unknown>;
+}): number;

package/dist/commands/wait-site-compile.js

@@ -0,0 +1,94 @@
+/**
+ * After the agent-run clock is idle, wait for the site compile of the tip.
+ */
+import { EXIT_OK } from "../http/client.js";
+import { emitFail, emitOk, isJson, progress } from "../runtime.js";
+import { waitForCompileReady } from "../compile.js";
+import { emitWaitOutcome, waitForAgentIdle, } from "./wait-agent-idle.js";
+export async function waitForAgentThenCompile(args) {
+    const agent = await waitForAgentIdle({
+        slug: args.slug,
+        failClosedOnIdleTerminalFailure: args.failClosedOnIdleTerminalFailure,
+    });
+    if (agent.exitCode !== EXIT_OK) {
+        return emitWaitOutcome({
+            command: args.command,
+            slug: args.slug,
+            result: agent,
+            extra: args.extra,
+        });
+    }
+    if (!isJson()) {
+        if (agent.observedBusy && agent.run) {
+            console.log(`${agent.run.id}  ${agent.run.status}${agent.run.statusMessage ? `  ${agent.run.statusMessage}` : ""}`);
+        }
+        else {
+            console.log("No agent run was in flight.");
+        }
+        progress("Waiting for the site compile…\n");
+    }
+    const compile = await waitForCompileReady({
+        slug: args.slug,
+        expectCommit: args.expectCommit,
+    });
+    return emitCompileWaitOutcome({
+        command: args.command,
+        slug: args.slug,
+        agent,
+        compile,
+        extra: args.extra,
+    });
+}
+export function emitCompileWaitOutcome(args) {
+    const compileData = {
+        compile: args.compile.status,
+        compileReady: Boolean(args.compile.status?.ready) && !args.compile.timedOut,
+    };
+    if (args.compile.exitCode !== EXIT_OK) {
+        const message = args.compile.failed
+            ? "Site compile failed. The git tip is not live."
+            : args.compile.timedOut
+                ? "Timed out waiting for the site compile. The git tip is not live yet."
+                : "Site compile is not ready.";
+        if (isJson()) {
+            return emitFail(args.command, {
+                message,
+                exitCode: args.compile.exitCode,
+                data: {
+                    slug: args.slug,
+                    waited: true,
+                    observedBusy: args.agent.observedBusy,
+                    status: args.compile.failed
+                        ? "compile_failed"
+                        : args.compile.timedOut
+                            ? "compile_timeout"
+                            : "compile_not_ready",
+                    run: args.agent.run,
+                    ...compileData,
+                    ...args.extra,
+                },
+            });
+        }
+        console.error(message);
+        if (args.compile.status) {
+            console.error(`tip ${args.compile.status.stagingCommit ?? "(none)"}  live ${args.compile.status.liveCommit ?? "(none)"}`);
+        }
+        return args.compile.exitCode;
+    }
+    if (isJson()) {
+        emitOk(args.command, {
+            slug: args.slug,
+            waited: true,
+            observedBusy: args.agent.observedBusy,
+            status: "ready",
+            run: args.agent.run,
+            ...compileData,
+            ...args.extra,
+        });
+    }
+    else {
+        const live = args.compile.status?.liveCommit ?? args.compile.status?.stagingCommit;
+        console.log(`Site compile ready  ${live ?? ""}`.trim());
+    }
+    return EXIT_OK;
+}

package/dist/compile.d.ts

@@ -0,0 +1,41 @@
+export type DeployStatus = {
+    slug?: string;
+    stagingCommit: string | null;
+    servingCommit: string | null;
+    liveCommit: string | null;
+    ready: boolean;
+    splitBrain: boolean;
+    compileState?: "ready" | "building" | "failed" | "canceled" | "unknown";
+    stagingUrl: string | null;
+    productionCommit: string | null;
+    productionServingCommit: string | null;
+    productionUrl: string | null;
+};
+export declare function normalizeSha(raw: string | null | undefined): string | null;
+export declare function shortSha(raw: string | null | undefined): string;
+/** SHA encoded in a Blob artifact prefix URL. */
+export declare function commitFromArtifactUrl(url: string | null | undefined): string | null;
+export declare function compileIsReady(status: Pick<DeployStatus, "ready" | "liveCommit">, expectCommit?: string | null): boolean;
+export type CompileWaitResult = {
+    exitCode: number;
+    timedOut: boolean;
+    failed: boolean;
+    status: DeployStatus | null;
+};
+export declare function fetchDeployStatus(slug: string): Promise<DeployStatus>;
+export declare function waitForCompileReady(args: {
+    slug: string;
+    expectCommit?: string | null;
+    maxMs?: number;
+    pollMs?: number;
+    fetchStatus?: (slug: string) => Promise<DeployStatus>;
+}): Promise<CompileWaitResult>;
+export declare function describePublishResult(args: {
+    productionCommit: string | null;
+    productionUrl: string | null;
+}): {
+    tipCommit: string | null;
+    servingCommit: string | null;
+    matchesTip: boolean;
+    lines: string[];
+};