@tokenoftrust/cli 1.4.0-rc.9 → 1.4.1

package/src/commands/ship.mjs

@@ -0,0 +1,517 @@
+/**
+ * `tot ship` — publish the tenant's CURRENT GREEN AGGREGATE to live. ONE
+ * meaning (unit b10 — SUPERSEDES the retired context-dependent ship, decision
+ * `ship-context-dependent-semantics`, and its developer-accept-then-deploy /
+ * operator-deploy-only / ship-any-built-PR branches):
+ *
+ *   tot dev        run your store locally with save→reload
+ *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)
+ *   tot ship       publish the current green aggregate live                 ← you are here
+ *
+ * `tot ship` NEVER takes a PR/candidate target and NEVER infers context from
+ * your checkout or who's running it. There is nothing to detect: it ships the
+ * tenant's shared `preview` aggregate — the batch of PRs that integrated
+ * cleanly and went green (b07's queue) — full stop. The candidate-level merge
+ * is the separate `tot accept` verb (`accept.mjs`); ship never merges.
+ *
+ * THE FLOW:
+ *
+ *   1. GET the read-only PLAN from `/api/changes/ship` — b09's
+ *      `AggregateShipOrchestrator.plan()` exposed over HTTP: the pinned
+ *      aggregate sha, its content-addressed artifact digest, every included
+ *      PR, the rollback target (what a rollback would restore), and the
+ *      go-live paywall verdict. Zero side effects.
+ *   2. Print the EXACT plan via the shared U10 affordance (`../plan.mjs`) and
+ *      require ONE explicit confirm, defaulting to NO. `--yes` confirms
+ *      non-interactively; a non-TTY WITHOUT `--yes` REFUSES — nothing ships
+ *      without an explicit yes.
+ *   3. On confirm, POST `/api/changes/ship` with `confirmGoLive: true` (the
+ *      human go-live gate) and the reviewed `expectedAggregateSha` +
+ *      `expectedArtifactDigest` — so a STALE plan (the aggregate moved, or the
+ *      artifact changed, between GET and POST) is refused rather than shipping
+ *      something nobody reviewed.
+ *   4. Report the orchestrator's HONEST terminal state verbatim:
+ *      `shipped` (the live channel is VERIFIED serving the pinned artifact —
+ *      the only state ever rendered as "shipped live"), `refused` (a gate
+ *      refused before any side effect — not green, paywalled, etc.),
+ *      `promote_failed` / `record_failed` (a partial failure, recoverable by
+ *      re-running `tot ship`, never a false live claim).
+ *
+ * TRANSPORT: the CLI holds no storefront cookie (its OAuth login is with the
+ * MCP, a different trust boundary), so `/api/changes/ship` is reached with a
+ * Bearer OPERATOR SECRET + `X-Tot-Owner` — the SAME transport the retired
+ * `tot ship <N> --tenant` operator-by-PR path used. No MCP client, no git: ship
+ * is now pure HTTP (dependency-free — global `fetch` only).
+ */
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+import { startProgress } from "../progress.mjs";
+import { openBrowser } from "../open.mjs";
+import { emitActivity } from "../activity.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot ship — publish the tenant's CURRENT GREEN AGGREGATE to live (ONE meaning)
+
+  tot ship                   ship the checkout tenant's current green aggregate
+  tot ship --tenant <t>      ship a named tenant's current green aggregate (no checkout needed)
+  tot ship --yes             confirm non-interactively (skip the [y/N] prompt)
+  tot ship --url <origin>    storefront origin (default: env TOT_STOREFRONT_URL)
+  tot ship --secret <s>      operator secret (prefer the env vars below)
+  tot ship --no-open         don't open the live URL in your browser
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).
+
+  \`tot ship\` has ONE meaning: it publishes the tenant's shared preview
+  aggregate — the batch of PRs that integrated cleanly and went GREEN — to
+  live. It NEVER takes a PR/candidate target and never infers anything from
+  your checkout or who you are. It shows you the EXACT plan first (the pinned
+  sha, the artifact digest, every included PR, the rollback target, and the
+  go-live paywall verdict) and waits for one explicit confirm (\`--yes\` to
+  skip the prompt; a non-TTY without \`--yes\` refuses). Ship then reports
+  VERIFIED live truth — never a false "shipped" — surfacing a refusal or a
+  recoverable partial failure honestly if it isn't.
+
+  The candidate-level merge is the separate \`tot accept\` / \`tot merge\` verb —
+  \`tot ship\` never merges.`;
+
+/** Parse `tot ship` argv. Pure. */
+export function parseShipArgs(argv) {
+  const a = {
+    tenant: null,
+    yes: false,
+    noOpen: false,
+    url: null,
+    secret: null,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+// ─── Operator-secret transport (shared with `tot pr list --tenant` / u16/u17) ────
+//
+// `resolveOperatorSecret` / `normalizeChangesQueue` are the SAME helpers the
+// retired operator-by-PR ship path minted; `tot pr list --tenant` (`pr.mjs`)
+// still imports them for its own (unrelated) `GET /api/changes` candidate-queue
+// listing, so they stay here rather than move — one wire, one place it's typed.
+
+const OPERATOR_SECRET_ENV = ["PREVIEW_RECONCILE_SECRET", "GRANTS_ADMIN_SECRET", "TOT_OPERATOR_SECRET"];
+
+/**
+ * Resolve the operator secret from an explicit `--secret` or the env (first
+ * found). Pure given its env argument.
+ * @param {string|null|undefined} explicit
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+export function resolveOperatorSecret(explicit, env = {}) {
+  if (explicit && `${explicit}`.trim()) return `${explicit}`.trim();
+  for (const k of OPERATOR_SECRET_ENV) {
+    const v = env[k];
+    if (v && `${v}`.trim()) return `${v}`.trim();
+  }
+  return "";
+}
+
+/**
+ * Normalise a `GET /api/changes` body to the OPEN candidate list. Kept for
+ * `tot pr list --tenant` (`pr.mjs`) — NOT used by ship itself anymore (ship
+ * reads the aggregate plan from `/api/changes/ship`, a distinct endpoint).
+ * @param {any} data
+ * @returns {Array<{changeId:string, prNumber?:number|null, headSha?:string|null, previewUrl?:string|null}>}
+ */
+export function normalizeChangesQueue(data) {
+  const list = Array.isArray(data)
+    ? data
+    : data && Array.isArray(data.changes)
+      ? data.changes
+      : [];
+  // Keep an entry if it has a changeId (a BUILT candidate) OR a numeric prNumber (a
+  // not-built forge PR merged in by GET /api/changes, u9b) — so `tot pr list --tenant`
+  // shows orphaned/un-built PRs too, not only built candidates. (Re-applied after a
+  // branch-scale ship rework reverted it to changeId-only.)
+  return list.filter(
+    (c) =>
+      c &&
+      typeof c === "object" &&
+      (typeof c.changeId === "string" || typeof c.prNumber === "number"),
+  );
+}
+
+// ─── Shared with `tot accept` (`accept.mjs`) ─────────────────────────────────────
+//
+// `tot accept` queues a PR's integration into the protected `preview` aggregate
+// (NOT a merge to main — see accept.mjs's header) — a DISTINCT operator verb from
+// ship (no deploy). It imports these two normalisers straight from here rather
+// than re-implementing them.
+
+/**
+ * Normalise a `change_accept` / `change_status` result to { shipped, state,
+ * previewUrl, shippedAt }. `shipped` is true once the record reports the shipped
+ * state (or carries a shipped stamp). Pure — unit-tested.
+ * @param {any} r
+ */
+export function normalizeChangeResult(r) {
+  const o = (r && typeof r === "object" ? r : {});
+  const state = typeof o.state === "string" ? o.state : null;
+  const shippedStamp = o.shipped && typeof o.shipped === "object" ? o.shipped : null;
+  const shipped = state === "shipped" || Boolean(o.shipped === true || shippedStamp);
+  return {
+    shipped,
+    state,
+    previewUrl: o.previewUrl ?? shippedStamp?.previewUrl ?? o.liveUrl ?? null,
+    shippedAt: shippedStamp?.shippedAt ?? o.shippedAt ?? null,
+    raw: r,
+  };
+}
+
+/**
+ * Poll `change_status` until the change reports shipped (or the attempts budget
+ * runs out). Injectable delay/attempts.
+ * @param {{callTool:Function}} client
+ * @param {{ id:string, tenant?:string }} target
+ * @param {{ attempts?:number, delayMs?:number, sleep?:(ms:number)=>Promise<void> }} [opts]
+ */
+export async function pollChangeShipped(client, { id, tenant }, { attempts = 6, delayMs = 1500, sleep } = {}) {
+  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let last = null;
+  for (let i = 0; i < attempts; i++) {
+    last = normalizeChangeResult(await client.callTool("change_status", { id, ...(tenant ? { tenant } : {}) }));
+    if (last.shipped) return last;
+    if (i < attempts - 1) await wait(delayMs);
+  }
+  return last;
+}
+
+// ─── URL derivation (pure) ─────────────────────────────────────────────────────
+
+/** The live site URL for a tenant (the tenant IS its apex domain, e.g. tokenoftrust.com). Pure. */
+export function liveUrlFor(tenant) {
+  const t = (tenant || "").trim();
+  return t ? `https://${t}` : null;
+}
+
+// ─── Response normalisation (defensive — one endpoint, but shapes may vary) ─────
+
+/**
+ * Normalise a `GET /api/changes/ship` body — b09's `AggregateShipPlan` (a
+ * shippable aggregate) or `AggregateShipRefusal` (nothing shippable), read
+ * defensively since it crossed the wire as JSON. Pure — unit-tested.
+ * @param {any} data
+ * @returns {{ok:true, tenantId:string|null, pinnedSha:string|null, artifactDigest:string|null,
+ *   includedPrs:Array<{prNumber?:number|null,changeId?:string|null,headSha?:string|null}>,
+ *   integrationRunId:string|null, receiptId:string|null,
+ *   rollbackTarget:{receiptId:string,aggregateSha:string,artifactDigest?:string}|null,
+ *   paywall:{allowed:boolean,message:string|null}, alreadyShipped:boolean} |
+ *   {ok:false, reason:string, message:string}}
+ */
+export function normalizeShipPlan(data) {
+  const o = data && typeof data === "object" ? data : {};
+  if (o.ok === true) {
+    return {
+      ok: true,
+      tenantId: typeof o.tenantId === "string" ? o.tenantId : null,
+      pinnedSha: typeof o.pinnedSha === "string" ? o.pinnedSha : null,
+      artifactDigest: typeof o.artifactDigest === "string" ? o.artifactDigest : null,
+      includedPrs: Array.isArray(o.includedPrs) ? o.includedPrs : [],
+      integrationRunId: typeof o.integrationRunId === "string" ? o.integrationRunId : null,
+      receiptId: typeof o.receiptId === "string" ? o.receiptId : null,
+      rollbackTarget: o.rollbackTarget && typeof o.rollbackTarget === "object" ? o.rollbackTarget : null,
+      paywall:
+        o.paywall && typeof o.paywall === "object"
+          ? {
+              allowed: o.paywall.allowed === true,
+              message: typeof o.paywall.message === "string" ? o.paywall.message : null,
+            }
+          : { allowed: true, message: null },
+      alreadyShipped: o.alreadyShipped === true,
+    };
+  }
+  return {
+    ok: false,
+    reason: typeof o.reason === "string" ? o.reason : "unknown",
+    message: typeof o.message === "string" ? o.message : "the ship plan was refused for an unknown reason",
+  };
+}
+
+/**
+ * Normalise a `POST /api/changes/ship` body — b09's `AggregateShipResult`.
+ * `state` is the ONLY honest terminal-state authority: render "shipped live"
+ * for `"shipped"` and nothing else. Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeShipResult(data) {
+  const o = data && typeof data === "object" ? data : {};
+  return {
+    ok: o.ok === true,
+    state: typeof o.state === "string" ? o.state : "unknown",
+    reason: typeof o.reason === "string" ? o.reason : null,
+    message: typeof o.message === "string" ? o.message : "",
+    pinnedSha: typeof o.pinnedSha === "string" ? o.pinnedSha : null,
+    artifactDigest: typeof o.artifactDigest === "string" ? o.artifactDigest : null,
+    receiptId: typeof o.receiptId === "string" ? o.receiptId : null,
+    rollbackTarget: o.rollbackTarget && typeof o.rollbackTarget === "object" ? o.rollbackTarget : null,
+  };
+}
+
+/** A clear next step per plan/ship refusal reason. Pure. */
+export function refusalNextStep(reason) {
+  switch (reason) {
+    case "not_green":
+    case "no_passed_run":
+      return "land PRs into the shared preview queue and wait for it to go green, then re-run `tot ship`";
+    case "sha_mismatch":
+    case "digest_mismatch":
+      return "the aggregate moved since you reviewed it — re-run `tot ship` to review the current plan";
+    case "artifact_missing":
+      return "re-integrate to re-materialize the artifact (b09 never rebuilds at ship), then re-run `tot ship`";
+    case "paywall":
+      return "upgrade the storefront subscription to enable go-live";
+    case "golive_unconfirmed":
+      return "re-run `tot ship` and confirm the plan";
+    default:
+      return "re-run `tot ship`";
+  }
+}
+
+/** Read a fetch Response body as JSON, tolerating a non-JSON/empty body. */
+async function readJsonSafe(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+
+// ─── Orchestration ───────────────────────────────────────────────────────────────
+
+/**
+ * The ship flow: GET the plan, print it + confirm, POST to ship, report the
+ * honest terminal state. `fetch`/`confirmPlan`/`openUrl`/`progress` are
+ * injected so it's unit-tested with no live network/TTY.
+ *
+ * @param {{ tenant:string, secret:string, storefrontUrl?:string|null,
+ *   yes?:boolean, noOpen?:boolean }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
+ *   openUrl?:(u:string)=>boolean, progress?:boolean }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runShip({ tenant, secret, storefrontUrl = null, yes = false, noOpen = false }, deps = {}) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+
+  if (!secret) {
+    console.error(
+      fail(
+        "shipping is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+
+  const authHeaders = {
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+
+  // 1. GET the read-only plan: the pinned sha + artifact digest + included PRs +
+  //    rollback target + paywall verdict. Zero side effects.
+  let planRes;
+  try {
+    planRes = await fetchImpl(`${base}/api/changes/ship`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the ship plan at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const planData = await readJsonSafe(planRes);
+  if (!planRes.ok && planData?.ok !== false) {
+    // A transport-level refusal the endpoint didn't explain in its own shape
+    // (auth/tenant-resolution/network) — surface it honestly.
+    const msg = planData?.error || `HTTP ${planRes.status}`;
+    console.error(
+      fail(
+        `the ship plan was refused: ${msg}`,
+        planRes.status === 401 || planRes.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url, then re-run",
+      ),
+    );
+    return 1;
+  }
+  const plan = normalizeShipPlan(planData);
+  if (!plan.ok) {
+    console.error(fail(plan.message, refusalNextStep(plan.reason)));
+    return 1;
+  }
+
+  // 2. Print the EXACT plan via the shared U10 affordance, then require ONE
+  //    explicit confirm (`--yes` non-interactive; a non-TTY without it refuses).
+  const liveUrl = liveUrlFor(tenant);
+  const planLines = planForAction({
+    action: "ship",
+    tenant,
+    pinnedSha: plan.pinnedSha,
+    artifactDigest: plan.artifactDigest,
+    includedPrs: plan.includedPrs,
+    rollbackTarget: plan.rollbackTarget,
+    paywall: plan.paywall,
+    targets: { live: liveUrl },
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Ship ${tenant}'s current green aggregate live?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot ship` needs an interactive terminal to confirm this live change",
+          "run it from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
+    console.log("  Ship cancelled — nothing changed.");
+    return 0;
+  }
+
+  // 3. SHIP — the human go-live gate (confirmGoLive) plus the reviewed pin, so a
+  //    STALE plan (the aggregate moved / the artifact changed since GET) is
+  //    refused rather than shipping something nobody reviewed.
+  const progress = deps.progress === false ? null : startProgress("shipping…");
+  let shipRes;
+  try {
+    shipRes = await fetchImpl(`${base}/api/changes/ship`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders },
+      body: JSON.stringify({
+        confirmGoLive: true,
+        ...(plan.pinnedSha ? { expectedAggregateSha: plan.pinnedSha } : {}),
+        ...(plan.artifactDigest ? { expectedArtifactDigest: plan.artifactDigest } : {}),
+      }),
+    });
+  } catch (e) {
+    progress?.stop();
+    console.error(
+      fail(`couldn't reach the ship endpoint at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const shipData = await readJsonSafe(shipRes);
+  progress?.stop();
+
+  const shipResult = normalizeShipResult(shipData);
+  // D3: emit the ship publish lifecycle event — `tot ship` does no LOCAL git op
+  // (it's HTTP-orchestrated), so this marks the outcome of the publish step
+  // itself, distinct from the outer command's invoked/result pair. Fire-and-
+  // forget best-effort: a silent no-op without a hosted-bridge credential, never
+  // awaited, never throws, never alters the ship. `errorClass` stays low-
+  // cardinality (the orchestrator's own terminal state/reason, never free text).
+  const shipped = shipResult.state === "shipped";
+  void emitActivity({
+    action: "cli.command.result",
+    outcome: {
+      status: shipped ? "succeeded" : "failed",
+      ...(shipped ? {} : { errorClass: `ship_${shipResult.state}` }),
+    },
+    scope: { tenantId: tenant },
+    payload: { args: { command: "ship", subcommand: "ship.publish" } },
+  });
+
+  return reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+}
+
+/**
+ * Report the orchestrator's HONEST terminal state. `shipped` is the ONLY state
+ * rendered as "shipped live" — `refused`/`promote_failed`/`record_failed` are
+ * surfaced with their own message + a clear next step, never dressed up as a
+ * success and never silently swallowed.
+ * @returns {number} process exit code
+ */
+function reportShipResult(result, { tenant, liveUrl, noOpen, openUrl }) {
+  if (result.state === "shipped") {
+    console.log(`\n  ✓ shipped ${tenant} live.`);
+    if (result.pinnedSha) console.log(`  pinned:  ${result.pinnedSha}`);
+    if (result.receiptId) console.log(`  receipt: ${result.receiptId}`);
+    if (liveUrl) {
+      console.log(`  Live: ${liveUrl}`);
+      if (!noOpen && openUrl && openUrl(liveUrl)) console.log("  (opened in your browser)");
+    }
+    if (result.message) console.log(`  ${result.message}`);
+    return 0;
+  }
+  if (result.state === "refused") {
+    console.error(fail(result.message || `ship refused (${result.reason})`, refusalNextStep(result.reason)));
+    return 1;
+  }
+  if (result.state === "promote_failed" || result.state === "record_failed") {
+    console.error(
+      fail(
+        result.message || `ship ${result.state.replace("_", " ")}`,
+        "re-run `tot ship` — the ship is idempotent and safe to retry",
+      ),
+    );
+    return 1;
+  }
+  console.error(
+    fail(
+      `unexpected ship response (state: ${result.state})`,
+      "re-run `tot ship`; check the storefront logs if it persists",
+    ),
+  );
+  return 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseShipArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  // ONE meaning, no context detection: the target tenant is either named
+  // explicitly (`--tenant`, works from anywhere — no checkout needed) or
+  // inferred from the current checkout. Never guessed from a PR/branch/actor.
+  const tenant = (args.tenant || (ctx.mode === "checkout" ? ctx.tenant : null) || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "`tot ship` needs a target tenant",
+        "run it from inside a `tot clone`d store, or pass --tenant <appDomain>",
+      ),
+    );
+    return 2;
+  }
+
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+  return await runShip(
+    {
+      tenant,
+      secret: resolveOperatorSecret(args.secret, env),
+      storefrontUrl,
+      yes: args.yes,
+      noOpen: args.noOpen,
+    },
+    { openUrl: (u) => openBrowser(u) },
+  );
+}

package/src/commands/start.mjs

@@ -67,7 +67,7 @@ import {
   activityBridgeEnv, NativeArtifactUnavailableError,
 } from "./dev.mjs";
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
-import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
+import { startHeartbeatFromEnv, resolveEditor } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
 import { milestoneBanner, cockpitUrlFrom, DEVELOPER_COCKPIT } from "../banner.mjs";
 import { IDEAS } from "./ideas.mjs";
@@ -318,7 +318,7 @@ export async function run(argv, ctx) {
     // (A3) so the "instant" claim is measured. The "Connect Claude" step is
     // intentionally removed for now — a blocking prompt here meant Ctrl-C'ing it
     // tore down the dev server; revisit AI-connect as a non-blocking step later.
-    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl);
+    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl, dir);
 
     // 7. hand the terminal to the running dev server until Ctrl-C.
     console.log("\n  Watching your store — edit content/home.html + save. Ctrl-C to stop.\n");
@@ -693,11 +693,34 @@ function printCheckoutLanding(dir, cockpitUrl = null) {
   console.log(`     content/home.html — you'll see it reflected in ${where}.`);
 }
 
+/**
+ * OS/editor-aware suggestions for opening the checkout, shown once at the
+ * "you're live" moment. $VISUAL/$EDITOR (same signal the cockpit's "open this
+ * file" hint uses — see dev-heartbeat.mjs#resolveEditor) wins when set;
+ * otherwise a short per-platform shortlist of common editor launch commands.
+ * Deliberately NOT probed against PATH — a spawnSync per candidate would add
+ * real latency to the crafted "aha" ending for the common case (nothing set),
+ * so this is a labeled suggestion list, not a detection result.
+ */
+function editorOpenLines(dir, { platform = process.platform, env = process.env } = {}) {
+  const configured = resolveEditor(env);
+  if (configured) return [`${configured} ${dir}`];
+  if (platform === "darwin") {
+    return [`code ${dir}      (VS Code, if installed)`, `cursor ${dir}    (Cursor, if installed)`, `open ${dir}      (Finder)`];
+  }
+  if (platform === "win32") {
+    return [`code ${dir}      (VS Code, if installed)`, `explorer ${dir}  (File Explorer)`];
+  }
+  return [`code ${dir}      (VS Code, if installed)`, `cursor ${dir}    (Cursor, if installed)`, `xdg-open ${dir}  (file manager)`];
+}
+
 /** The crafted "you're live" ending — a PROMINENT milestone banner (u2) that,
  * when we hold a Developer Cockpit URL, explicitly sends the developer BACK to
- * their cockpit as the next place to look; then the AI-wow (G), seeded with
- * IDEAS[0] (G2/G3 — one prompt list shared with `tot ideas`, no drift). */
-function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
+ * their cockpit as the next place to look. Then: an OS-suited "open this in
+ * an editor" suggestion, and the four-pane layout tip (this terminal, cockpit,
+ * local preview, editor) so a build problem, a reload, and the code are never
+ * more than a glance apart. */
+function printLiveEnding(tenant, url, elapsed, cockpitUrl = null, dir = null) {
   const lines = [
     `✨  You're live.${elapsed ? `  (${elapsed})` : ""}`,
     `    ${url}`,
@@ -711,10 +734,19 @@ function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
   console.log(milestoneBanner(lines));
   console.log("  " + versionStamp("native"));
   console.log("");
-  console.log("  Now try, in Claude:");
-  console.log(`     "${IDEAS[0]}"`);
+  if (dir) {
+    console.log("  Open your project in an editor (an AI coding agent like Claude works too —");
+    console.log("  same idea, different hands on the keyboard):");
+    for (const line of editorOpenLines(dir)) console.log(`     ${line}`);
+    console.log("");
+  }
+  console.log("  Keep THIS terminal open — it's your live build/status feed, the fastest way to");
+  console.log("  see a problem the moment it happens. Need the command line for something else?");
+  console.log("  Open a NEW terminal window rather than closing this one.");
   console.log("");
-  console.log("  More ideas: tot ideas");
+  console.log("  Best view: arrange this terminal, your Developer Cockpit, the local preview,");
+  console.log("  and your editor so you can see all four at once — site, cockpit, build status,");
+  console.log("  and code, together.");
   console.log("");
 }