@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/apps/storefront/src/lib/d1/schema-apps.ts

@@ -27,6 +27,14 @@ export const appInstalls = sqliteTable(
     webhookEndpoint: text("webhook_endpoint"),
     widgetPlacements: text("widget_placements").notNull().default("[]"),
     installActor: text("install_actor").notNull(),
+    // Nullable discriminator keeps the managed-analytics v1 lifecycle on the
+    // canonical install row instead of creating a second install authority.
+    managedKind: text("managed_kind"),
+    managedRevision: integer("managed_revision").notNull().default(0),
+    managedActiveRevisionId: text("managed_active_revision_id"),
+    // Validated non-live candidate only. Live effects remain in manifest and
+    // app_version_snapshots, the registry's established serving authorities.
+    managedCandidate: text("managed_candidate"),
     createdAt: text("created_at").notNull(),
     updatedAt: text("updated_at").notNull(),
   },
@@ -70,6 +78,23 @@ export const appAuditLog = sqliteTable(
   }),
 );
 
+// Inert reviewed migration suggestions. This is deliberately NOT an install,
+// live effect, revision, or publish authority; conversion requires a separate
+// canonical `app_installs` mutation and drafts can never be enabled.
+export const integrationMigrationDrafts = sqliteTable(
+  "integration_migration_drafts",
+  {
+    draftId: text("draft_id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    revision: integer("revision").notNull(),
+    state: text("state").notNull().default("open"),
+    record: text("record").notNull(),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+  },
+  (t) => ({ idxIntegrationMigrationDraftsTenant: index("idx_integration_migration_drafts_tenant").on(t.tenantId, t.createdAt) }),
+);
+
 // --- Operational activity timeline ------------------------------------------
 // The low-volume / high-value LIFECYCLE cohort of the actor×action telemetry
 // spine (DECISIONS.md §8). Only actions whose catalog `spec.sinks` include
@@ -344,3 +369,254 @@ export const newsletterSends = sqliteTable(
   },
   (t) => ({ pk: primaryKey({ columns: [t.tenantId, t.collection, t.digestId] }) }),
 );
+
+// --- Canonical publish-candidate identity -----------------------------------
+// ONE canonical candidate per `(tenant_id, repository, pr_number)` — the real
+// forge PR. Retries/rebuilds are NOT new candidates; they are child `attempts`
+// (below). This is the durable identity spine other units resolve against; the
+// KV `ReviewEnvironment` (`cust:*`) and aggregate/release models (`rel:*`) are
+// read projections that reference this row's `change_id`/`pr_number`.
+//
+// `id` is a SYNTHETIC surrogate (`cand_<uuid>`), deliberately DISTINCT from the
+// canonical key so foreign keys (attempts) never depend on the mutable natural
+// key. `change_id` is the REAL forge change id — the stable branch/build
+// identity (`candidate/<change_id>`) — preserved, never derived from `id`.
+// `tenant_id` is the isolation boundary, written from the resolved session,
+// NEVER a client body. The UNIQUE `(tenant_id, repository, pr_number)` is what
+// makes "one candidate per PR" a schema invariant (upsert-by-key, not
+// insert-then-dedupe); the UNIQUE `(tenant_id, change_id)` keeps the branch/
+// build identity unambiguous for resolve-by-changeId callers.
+export const candidates = sqliteTable(
+  "candidates",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    // The `<tenant>-<tag>` forge repository the PR lives in.
+    repository: text("repository").notNull(),
+    // The forge PR number — the third leg of the canonical key.
+    prNumber: integer("pr_number").notNull(),
+    // The real forge change id — stable branch/build identity (`candidate/<change_id>`).
+    changeId: text("change_id").notNull(),
+    // Source branch, conventionally `candidate/<change_id>` (nullable convenience mirror).
+    branch: text("branch"),
+    title: text("title"),
+    author: text("author"),
+    // Canonical candidate lifecycle: open | preparing | ready | needs-attention | accepted | rejected | closed.
+    status: text("status").notNull().default("open"),
+    // The PR head/base shas as last reconciled (nullable until first read).
+    headSha: text("head_sha"),
+    baseSha: text("base_sha"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+  },
+  (t) => ({
+    uqCandidatesCanonical: uniqueIndex("uq_candidates_tenant_repo_pr").on(
+      t.tenantId,
+      t.repository,
+      t.prNumber,
+    ),
+    uqCandidatesChange: uniqueIndex("uq_candidates_tenant_change").on(t.tenantId, t.changeId),
+    idxCandidatesTenantStatus: index("idx_candidates_tenant_status").on(t.tenantId, t.status),
+  }),
+);
+
+// One `attempt` = one build/check/rebase EXECUTION of a candidate. Attempts are
+// the child rows retries produce — they must NEVER queue as separate top-level
+// candidate rows. `candidate_id` references `candidates.id` in code only (no SQL
+// FK — repo convention, matches `webhook_deliveries.event_id` / `orders`).
+// `tenant_id` is denormalized for tenant-scoped reads/isolation without a join.
+// `attempt_number` is monotonic per candidate (1,2,3…) giving stable ordering;
+// UNIQUE `(candidate_id, attempt_number)` makes a double-assigned number a loud
+// failure rather than a silent duplicate. `kind`: build | check | rebase;
+// `status`: pending | running | passed | failed | cancelled (mirrors
+// `IntegrationRun`'s state vocabulary). `evidence` is a JSON EvidenceReport
+// snapshot; `detail` a human-legible terminal-state message.
+export const candidateAttempts = sqliteTable(
+  "candidate_attempts",
+  {
+    id: text("id").primaryKey(),
+    candidateId: text("candidate_id").notNull(),
+    tenantId: text("tenant_id").notNull(),
+    attemptNumber: integer("attempt_number").notNull(),
+    kind: text("kind").notNull(),
+    status: text("status").notNull().default("pending"),
+    // The candidate head sha this attempt executed against, or null if unknown.
+    headSha: text("head_sha"),
+    detail: text("detail"),
+    evidence: text("evidence"),
+    startedAt: text("started_at").notNull(),
+    // Null while pending/running; set on a terminal transition.
+    finishedAt: text("finished_at"),
+  },
+  (t) => ({
+    uqAttemptNumber: uniqueIndex("uq_candidate_attempts_candidate_number").on(
+      t.candidateId,
+      t.attemptNumber,
+    ),
+    idxAttemptsCandidate: index("idx_candidate_attempts_candidate").on(t.candidateId),
+    idxAttemptsTenant: index("idx_candidate_attempts_tenant").on(t.tenantId),
+  }),
+);
+
+// One active submit per tenant/change. This serializes identity authorization,
+// the Gitea mutation, and audit finalization so a verified callback cannot
+// become stale between its forge read and its KV writes. `expires_at` is
+// diagnostic only; recovery is explicit so a slow live submit cannot be
+// time-fenced incorrectly.
+export const candidateSubmitLeases = sqliteTable(
+  "candidate_submit_leases",
+  {
+    tenantId: text("tenant_id").notNull(),
+    changeId: text("change_id").notNull(),
+    authorizationId: text("authorization_id").notNull(),
+    status: text("status").notNull().default("active"),
+    acquiredAt: text("acquired_at").notNull(),
+    expiresAt: text("expires_at").notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.tenantId, t.changeId] }),
+    idxExpires: index("idx_candidate_submit_leases_expires").on(t.expiresAt),
+  }),
+);
+
+// --- Merchant consent configuration -----------------------------------------
+// APPEND-ONLY revision history of a tenant's consent configuration (the
+// ext-admin-03 surface that feeds the ext-policy-03 broker). Each save is a NEW
+// immutable row — the current config is `MAX(revision)` per tenant — so the table
+// IS the audit trail (actor + timestamp per revision, never mutated in place) and
+// a revert is a forward-only new revision that copies a prior `config` and records
+// `reverted_from`. `config` is the JSON `TenantConsentConfig` (never secret-bearing
+// — consent config carries no secrets). `tenant_id` is the isolation boundary,
+// written from the resolved session, never a client body. UNIQUE
+// `(tenant_id, revision)` makes the monotonic revision a schema invariant.
+export const consentConfigRevisions = sqliteTable(
+  "consent_config_revisions",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    // Monotonic per tenant (1, 2, 3…) — the latest revision is the current config.
+    revision: integer("revision").notNull(),
+    // The JSON-serialized validated `TenantConsentConfig`.
+    config: text("config").notNull(),
+    // Opaque actor id — never email/PII (matches `app_audit_log`).
+    actor: text("actor").notNull(),
+    // Human-legible note (e.g. the reason, or "revert to revision N").
+    note: text("note"),
+    // When this revision copies an earlier one, the source revision — else null.
+    revertedFrom: integer("reverted_from"),
+    createdAt: text("created_at").notNull(),
+  },
+  (t) => ({
+    uqConsentConfigTenantRevision: uniqueIndex("uq_consent_config_tenant_revision").on(
+      t.tenantId,
+      t.revision,
+    ),
+    idxConsentConfigTenant: index("idx_consent_config_tenant").on(t.tenantId),
+  }),
+);
+
+// Demonstrated CMP demand — one row per `(tenant, adapter)` demand signal. The set
+// of SELECTABLE CMP adapters is DERIVED from these rows (distinct-tenant count over
+// a threshold), never a hardcoded catalog: the first CMP Storefront adapts is
+// whichever real demand first proves (ADR 0014 P2 / 0025). UNIQUE
+// `(tenant_id, adapter_id)` makes demand a per-tenant fact (a tenant re-asking does
+// not inflate the count); the `adapter_id` index serves the per-adapter rollup.
+export const consentCmpDemand = sqliteTable(
+  "consent_cmp_demand",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    adapterId: text("adapter_id").notNull(),
+    // Where the demand came from (a merchant request, a support ticket), for the record.
+    source: text("source"),
+    at: text("at").notNull(),
+  },
+  (t) => ({
+    uqConsentCmpDemandTenantAdapter: uniqueIndex("uq_consent_cmp_demand_tenant_adapter").on(
+      t.tenantId,
+      t.adapterId,
+    ),
+    idxConsentCmpDemandAdapter: index("idx_consent_cmp_demand_adapter").on(t.adapterId),
+  }),
+);
+
+// --- Commerce conversion attribution (ext-commerce-04) -----------------------
+// The single-use ledger for the signed checkout-correlation token's `jti`
+// (`packages/public-runtime/src/integration/correlation-token.ts`). The order join
+// consumes a token EXACTLY once: a replay of a consumed `jti` is refused. `jti` is
+// the natural key (the token's own 96-bit nonce); `expires_at` is the token's Unix-
+// seconds `exp` so a consumed row can be pruned once the token is already `expired`
+// (a past-`exp` token is rejected before the guard is even reached). Carries no PII
+// and no secret — the `jti` is an opaque nonce, never the token or the signing key.
+export const correlationReplay = sqliteTable("correlation_replay", {
+  jti: text("jti").primaryKey(),
+  expiresAt: integer("expires_at").notNull(),
+  consumedAt: text("consumed_at").notNull(),
+});
+
+// --- Retained managed-app version facets (ext-apps-02) -----------------------
+// APPEND-ONLY retention of every activated managed-app VERSION's COMPLETE
+// restorable facet set, and the atomic-rollback spine over it. One row per
+// activation of an install; the CURRENT active version is `MAX(seq)` per install
+// (same "the latest row is current" model as `consent_config_revisions`). The
+// whole restorable facet set (code ref/digest, entry module, public config,
+// contributions, granted scopes, consent declaration, CSP origins) is one JSON
+// blob in `facets` — so retaining a version and rolling one back are each a
+// SINGLE-ROW insert: the restore is atomic by construction (you get the whole
+// prior facet set or nothing — never a partial/mixed activation). A rollback is
+// forward-only: it appends a NEW activation copying a retained version's facets
+// and records `restored_from_seq`, so history is never rewritten and the rollback
+// is itself an audited row. `tenant_id` is the isolation boundary, denormalized
+// for tenant-scoped reads (no SQL FK — repo convention). `facets` carries no
+// secret material (proved by the ext-kernel-01 secret scan before insert). UNIQUE
+// `(install_id, seq)` makes the monotonic sequence a schema invariant.
+export const appVersionSnapshots = sqliteTable(
+  "app_version_snapshots",
+  {
+    id: text("id").primaryKey(),
+    installId: text("install_id").notNull(),
+    tenantId: text("tenant_id").notNull(),
+    // Monotonic per install (1, 2, 3…); the largest is the active version.
+    seq: integer("seq").notNull(),
+    // The app package version this activation serves (mirror of facets.appVersion).
+    appVersion: text("app_version").notNull(),
+    // The complete restorable facet set as one JSON blob (AppVersionFacets).
+    facets: text("facets").notNull(),
+    // Opaque actor id — never email/PII (matches `app_audit_log`).
+    actor: text("actor").notNull(),
+    // Human-legible note (e.g. the reason, or "rollback to version N").
+    note: text("note"),
+    // When this activation restores an earlier one, its source `seq` — else null.
+    restoredFromSeq: integer("restored_from_seq"),
+    createdAt: text("created_at").notNull(),
+  },
+  (t) => ({
+    uqAppVersionSnapshotsInstallSeq: uniqueIndex("uq_app_version_snapshots_install_seq").on(
+      t.installId,
+      t.seq,
+    ),
+    idxAppVersionSnapshotsInstall: index("idx_app_version_snapshots_install").on(t.installId),
+  }),
+);
+
+// The per-`(tenant, external_order_id)` attribution ledger. An order's attribution is
+// decided ONCE (on its first `order.created`/`order.fulfilled` conversion) and reused
+// for every later lifecycle conversion, so the correlation `jti` is consumed once per
+// order — not once per lifecycle event — and a duplicate/replayed/out-of-order webhook
+// reproduces the same outcome. `attributed` is 0/1; when attributed, `correlation_id`
+// + `correlation_expires_at` hold the shared thread; when not, `reason` records why
+// (missing/expired/context_mismatch/replay/…). Never customer identity — only the
+// opaque correlation handle. `(tenant_id, external_order_id)` is the natural key.
+export const orderAttribution = sqliteTable(
+  "order_attribution",
+  {
+    tenantId: text("tenant_id").notNull(),
+    externalOrderId: text("external_order_id").notNull(),
+    attributed: integer("attributed").notNull().default(0),
+    correlationId: text("correlation_id"),
+    correlationExpiresAt: text("correlation_expires_at"),
+    reason: text("reason"),
+    recordedAt: text("recorded_at").notNull(),
+  },
+  (t) => ({ pk: primaryKey({ columns: [t.tenantId, t.externalOrderId] }) }),
+);

package/apps/storefront/src/lib/dev/cockpit/ask.ts

@@ -0,0 +1,49 @@
+/**
+ * "Stuck? Ask" recovery affordance. A quiet FAB that opens a scoped Q&A
+ * for "why isn't the loop working" — NOT general AI editing. Static answers
+ * ship as markup; the two stateful answers (is it running? / save-vs-reload)
+ * update from the shared tot:loop-state signal + window.__totLoop (monitor.ts
+ * — no second poll). "Reconnect preview" reloads the page, re-establishing
+ * the HMR connection and re-reading loop state (recovers a stale client); a
+ * fully-down server is handled by the answer text (run tot start). Imported
+ * from a processed `<script>` in cockpit.astro (ADR 0013), rendered only when
+ * isLocalDevLoop.
+ */
+export function initAsk(): void {
+  const fab = document.getElementById("askFab");
+  const panel = document.getElementById("askPanel");
+  if (!fab || !panel) return;
+  const ansRunning = document.getElementById("ans-running");
+  const ansChange = document.getElementById("ans-change");
+  const restart = document.getElementById("restartBtn");
+
+  fab.addEventListener("click", (e) => { e.stopPropagation(); panel.classList.toggle("open"); });
+  document.addEventListener("click", (e) => {
+    if (!panel.contains(e.target as Node) && e.target !== fab && !fab.contains(e.target as Node)) panel.classList.remove("open");
+  });
+  if (restart) restart.addEventListener("click", () => { location.reload(); });
+
+  function rel(ts: number | string): string {
+    const d = Math.max(0, Math.round((Date.now() - Number(ts)) / 1000));
+    return d < 2 ? "just now" : d < 60 ? d + "s ago" : Math.floor(d / 60) + "m ago";
+  }
+  function update(s: any) {
+    if (!s) return;
+    if (ansRunning) {
+      ansRunning.textContent = (s.offline || !s.server)
+        ? "Your dev server isn't reachable right now — run tot start in your terminal, then reload this page."
+        : "Yes — your server is running" + (s.port ? " on port " + s.port : "") + ". This page is connected to it.";
+    }
+    if (ansChange) {
+      if (!s.lastSaveAt) {
+        ansChange.textContent = "No saves seen yet. Edit a watched file (like content/home.html) and save — it'll show up here.";
+      } else if ((s.lastReloadAt || 0) >= s.lastSaveAt) {
+        ansChange.textContent = "Working: your last save (" + rel(s.lastSaveAt) + ") triggered a reload (" + rel(s.lastReloadAt) + "). If the page didn't visibly change, make sure you edited the file the page renders from.";
+      } else {
+        ansChange.textContent = "Your save (" + rel(s.lastSaveAt) + ") hasn't been reflected by a reload yet — the preview may be stale. Try Reconnect preview below.";
+      }
+    }
+  }
+  window.addEventListener("tot:loop-state", (e: any) => { update(e.detail); });
+  if (window.__totLoop) update(window.__totLoop);
+}

package/apps/storefront/src/lib/dev/cockpit/clickToSource.ts

@@ -0,0 +1,71 @@
+/**
+ * C8 · Click-to-source capstone — the cockpit side. Runs the live-preview
+ * iframe (mini + full-screen dialog) and LISTENS for the framed picker's
+ * tot:locate postMessage. The picker (ai-widget-client.js, auto-injected into
+ * the same-origin preview) resolves a click to {path,line,col} via
+ * /__tot/locate, then — because it is framed — postMessages the result here
+ * instead of showing its own toast. We verify event.origin === our origin,
+ * then hand off to files.ts's window.__totOpenFileAt to open the source +
+ * drop the caret. Only content-region hits ever arrive (chrome/refused
+ * clicks stay silent in the frame), per decision
+ * click-to-source-anchors-at-content-region. Imported from a processed
+ * `<script>` in cockpit.astro (ADR 0013), rendered only when isLocalDevLoop.
+ * isDev and the hosted app domain are read from `document.body.dataset`.
+ */
+export function initClickToSource(): void {
+  const isDev = document.body.dataset.cockpitIsDev === "true";
+  const hostedAppDomain = document.body.dataset.cockpitAppDomain || "";
+  const dlg: any = document.getElementById("previewDialog");
+  const expandBtn = document.getElementById("previewExpand");
+  const closeBtn = document.getElementById("previewClose");
+  const dlgFrame: any = document.getElementById("previewDialogFrame");
+  const miniFrame: any = document.getElementById("previewFrame");
+  const urlEl = document.getElementById("previewUrl");
+
+  if (miniFrame) {
+    if (isDev) {
+      // Point the preview at the DEV tenant (TOT_DEV_TENANT), read from the server
+      // via /__tot/dev-loop-status — NOT the SSR appDomain (workerd can't see
+      // TOT_DEV_*). Same-origin, so the auto-injected picker can postMessage back.
+      fetch("/__tot/dev-loop-status")
+        .then((r) => r.json())
+        .then((s) => {
+          const tenant = s && s.tenant;
+          if (!tenant) return;
+          const src = "/" + tenant + "/";
+          miniFrame.src = src;
+          if (urlEl) urlEl.textContent = "localhost preview · " + tenant;
+        })
+        .catch(() => { /* dev server unreachable — preview stays blank */ });
+    } else if (hostedAppDomain) {
+      // Hosted: the SSR-resolved tenant IS the signed-in developer's own store
+      // (cp-env's capability gate already scoped it) — same-origin, so a cp-write
+      // save + this reload shows the developer's own draft overlay via the
+      // middleware's tot_dev_draft cookie check.
+      miniFrame.src = "/" + hostedAppDomain + "/";
+      if (urlEl) urlEl.textContent = "your store · " + hostedAppDomain;
+    }
+  }
+
+  if (expandBtn && dlg) {
+    expandBtn.addEventListener("click", () => {
+      if (dlgFrame && !dlgFrame.getAttribute("src") && miniFrame) dlgFrame.src = miniFrame.getAttribute("src") || miniFrame.src;
+      if (typeof dlg.showModal === "function") dlg.showModal(); else dlg.setAttribute("open", "");
+    });
+  }
+  if (closeBtn && dlg) closeBtn.addEventListener("click", () => { dlg.close ? dlg.close() : dlg.removeAttribute("open"); });
+  if (dlg) dlg.addEventListener("click", (e: MouseEvent) => { if (e.target === dlg) { dlg.close ? dlg.close() : dlg.removeAttribute("open"); } });
+
+  // The one privileged inbound message: a source location from OUR OWN origin's
+  // framed preview. Reject any other origin, shape, or type outright.
+  window.addEventListener("message", (e) => {
+    if (e.origin !== window.location.origin) return;
+    const d: any = e.data;
+    if (!d || d.type !== "tot:locate" || typeof d.path !== "string") return;
+    if (typeof (window as any).__totOpenFileAt === "function") {
+      const opened = (window as any).__totOpenFileAt(d.path, d.line, d.col);
+      // If the preview was expanded full-screen, close it so the editor + caret are visible.
+      if (opened && dlg && dlg.open) { dlg.close ? dlg.close() : dlg.removeAttribute("open"); }
+    }
+  });
+}

package/apps/storefront/src/lib/dev/cockpit/copyCommand.ts

@@ -0,0 +1,227 @@
+/**
+ * Copy the one command. Two behaviours:
+ *  · fastpath (signed-in dev): mint a single-use `tot login --code … && tot start` from
+ *    /api/dev/cli-signin-code, reveal it (textContent, never innerHTML — it carries a
+ *    live code), and copy the whole thing.
+ *  · otherwise: copy the generic install-and-run command directly.
+ *
+ * Also drives rendezvous approval: after a command is generated, the
+ * terminal ATTACHES its own PKCE key and prints a fingerprint; the developer
+ * confirms it here — the load-bearing anti-interception step, since
+ * approving the wrong fingerprint is how a hijack is caught.
+ *
+ * Imported from a processed `<script>` in cockpit.astro. The values below are
+ * carried as data-attrs on #copyCmd because this module runs standalone (not
+ * inside the same closure as hostedActivity.ts's basePath).
+ */
+export function initCopyCommand(): void {
+  const btn: any = document.getElementById("copyCmd");
+  const textEl = document.getElementById("cli-cmd-text");
+  const note = document.getElementById("cli-cmd-note");
+  const toast = document.getElementById("toast");
+  const toastMsg = document.getElementById("toastMsg");
+  const copyIcon: any = document.getElementById("copyIcon");
+  if (!btn || !textEl) return;
+  const generic = btn.getAttribute("data-generic") || "";
+  const fastpath = btn.getAttribute("data-fastpath") === "1";
+  // The request's tenant prefix ("" host-routed, "/<tenant>" path-routed). Carried
+  // as a data-attr because `basePath` is otherwise defined only inside the SEPARATE
+  // hostedActivity module (hostedActivity.ts) — referencing it here (the
+  // cli-signin-code / -status / -approve fetches below) was a ReferenceError that
+  // the mint's catch surfaced as the opaque "Couldn't reach the sign-in service"
+  // with no request ever sent.
+  const basePath = btn.getAttribute("data-base-path") || "";
+  let tT: ReturnType<typeof setTimeout>;
+  function ping(m: string) {
+    if (!toast) return;
+    if (toastMsg) toastMsg.textContent = m;
+    toast.classList.add("show");
+    clearTimeout(tT); tT = setTimeout(() => { toast.classList.remove("show"); }, 1900);
+  }
+  function copy(text: string): Promise<boolean> {
+    if (navigator.clipboard) return navigator.clipboard.writeText(text).then(() => true).catch(() => false);
+    return Promise.resolve(false);
+  }
+  function label(s: string) { btn.childNodes[btn.childNodes.length - 1].textContent = s; }
+
+  // Standard copy-icon affordance on the terminal box. Once the command is
+  // revealed, this is the obvious, always-there way to (re)copy it — the
+  // icon→check swap is its own inline confirmation, so copying no longer
+  // depends on the transient toast being noticed.
+  let iconT: ReturnType<typeof setTimeout>;
+  function flashCopied() {
+    if (!copyIcon) return;
+    copyIcon.setAttribute("data-copied", "1");
+    copyIcon.setAttribute("aria-label", "Copied");
+    copyIcon.setAttribute("title", "Copied");
+    clearTimeout(iconT);
+    iconT = setTimeout(() => {
+      copyIcon.removeAttribute("data-copied");
+      copyIcon.setAttribute("aria-label", "Copy the command");
+      copyIcon.setAttribute("title", "Copy the command");
+    }, 1600);
+  }
+  function revealIcon() {
+    if (copyIcon) copyIcon.hidden = false;
+  }
+  if (copyIcon) {
+    copyIcon.addEventListener("click", () => {
+      copy(textEl.textContent || "").then((ok) => {
+        if (ok) { flashCopied(); ping("Copied — paste & press Enter"); }
+        else ping("Select the command above to copy");
+      });
+    });
+  }
+
+  // ── Rendezvous approval: after a command is generated, the terminal ATTACHES
+  // its own PKCE key and prints a fingerprint; the developer confirms it HERE. This
+  // is the load-bearing anti-interception step — approving the wrong fingerprint is
+  // how a hijack is caught, so the confirm is an explicit, human decision.
+  const rzvRoot: any = document.getElementById("rzvApprove");
+  const rzvWait: any = document.getElementById("rzvWait");
+  const rzvConfirm: any = document.getElementById("rzvConfirm");
+  const rzvFp: any = document.getElementById("rzvFp");
+  const rzvApproveBtn: any = document.getElementById("rzvApproveBtn");
+  const rzvDenyBtn: any = document.getElementById("rzvDenyBtn");
+  const rzvDone: any = document.getElementById("rzvDone");
+  let rzvTimer: ReturnType<typeof setTimeout> | null = null;
+  let rzvCode: string | null = null;
+  let rzvDecided = false;
+  function rzvShow(el: any) { if (el) el.hidden = false; }
+  function rzvHide(el: any) { if (el) el.hidden = true; }
+  // Once the terminal has ATTACHED, the command has plainly been pasted and
+  // run — hide the copy affordances so the approve prompt is the page's
+  // single focus (DZ 2026-08-18). An EXPIRED sign-in restores the generate
+  // button (a fresh mint is needed); the stale command's copy icon stays gone.
+  function rzvHideCopyCtas() {
+    if (btn) btn.hidden = true;
+    if (copyIcon) copyIcon.hidden = true;
+  }
+  function rzvRestoreGenerate() {
+    if (btn) btn.hidden = false;
+  }
+  function rzvStopPoll() { if (rzvTimer) { clearTimeout(rzvTimer); rzvTimer = null; } }
+  function rzvFinish(msg: string) {
+    rzvStopPoll(); rzvDecided = true;
+    rzvHide(rzvWait); rzvHide(rzvConfirm);
+    if (rzvDone) { rzvDone.textContent = msg; rzvDone.hidden = false; }
+  }
+  async function rzvPoll(): Promise<void> {
+    if (rzvDecided) return;
+    let r: Response, b: any;
+    try {
+      r = await fetch(basePath + "/api/dev/cli-signin-status", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ rendezvousCode: rzvCode }),
+      });
+      b = await r.json().catch(() => ({}));
+    } catch (e) { rzvTimer = setTimeout(rzvPoll, 2800); return; }
+    if (!r || !r.ok) { rzvTimer = setTimeout(rzvPoll, 3200); return; }
+    if (b.state === "attached" && b.fingerprint) {
+      rzvHideCopyCtas();
+      rzvHide(rzvWait); rzvShow(rzvConfirm);
+      if (rzvFp) { rzvFp.textContent = b.fingerprint; rzvFp.setAttribute("data-fp", b.fingerprint); }
+      return; // stop polling — wait for the human decision
+    }
+    if (b.state === "approved") { rzvHideCopyCtas(); rzvFinish("Signed in ✓ — your terminal is good to go."); return; }
+    if (b.state === "denied") { rzvHideCopyCtas(); rzvFinish("Rejected — that terminal wasn't approved. You're safe; generate a fresh command to try again."); return; }
+    if (b.state === "expired") { rzvRestoreGenerate(); rzvFinish("This sign-in expired. Generate a fresh setup command above."); return; }
+    rzvTimer = setTimeout(rzvPoll, 2500); // pending → keep watching
+  }
+  function rzvStart(code: string) {
+    rzvCode = code; rzvDecided = false;
+    if (rzvApproveBtn) rzvApproveBtn.disabled = false;
+    if (rzvDenyBtn) rzvDenyBtn.disabled = false;
+    rzvShow(rzvRoot); rzvShow(rzvWait); rzvHide(rzvConfirm); rzvHide(rzvDone);
+    rzvStopPoll(); rzvPoll();
+  }
+  async function rzvDecide(decision: string): Promise<void> {
+    if (rzvDecided) return;
+    const fp = rzvFp ? (rzvFp.getAttribute("data-fp") || "") : "";
+    if (rzvApproveBtn) rzvApproveBtn.disabled = true;
+    if (rzvDenyBtn) rzvDenyBtn.disabled = true;
+    let r: Response;
+    try {
+      r = await fetch(basePath + "/api/dev/cli-signin-approve", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ rendezvousCode: rzvCode, fingerprint: fp, decision: decision }),
+      });
+    } catch (e) {
+      if (rzvApproveBtn) rzvApproveBtn.disabled = false;
+      if (rzvDenyBtn) rzvDenyBtn.disabled = false;
+      return;
+    }
+    if (decision === "deny") { rzvFinish("Rejected — that terminal wasn't approved."); return; }
+    if (r.ok) { rzvFinish("Signed in ✓ — your terminal is good to go."); return; }
+    if (rzvApproveBtn) rzvApproveBtn.disabled = false;
+    if (rzvDenyBtn) rzvDenyBtn.disabled = false;
+    const m = r.status === 403 ? "That didn't match your identity — generate a fresh command and try again."
+      : r.status === 409 ? "That code didn't match a waiting terminal — re-check it, or generate a fresh command."
+      : "Couldn't complete approval — try again.";
+    if (rzvDone) { rzvDone.textContent = m; rzvDone.hidden = false; }
+  }
+  if (rzvApproveBtn) rzvApproveBtn.addEventListener("click", () => { rzvDecide("approve"); });
+  if (rzvDenyBtn) rzvDenyBtn.addEventListener("click", () => { rzvDecide("deny"); });
+
+  if (!fastpath) {
+    btn.addEventListener("click", () => {
+      copy(generic).then((ok) => {
+        label(ok ? " Copied — paste & press Enter" : " Copy the command");
+        ping(ok ? "Copied the command" : "Select the command to copy");
+        setTimeout(() => { label(" Copy the command"); }, 2600);
+      });
+    });
+    return;
+  }
+
+  let busy = false;
+  btn.addEventListener("click", async () => {
+    if (busy) return;
+    busy = true;
+    label(" …"); btn.disabled = true;
+    let res: Response, body: any;
+    try {
+      res = await fetch(basePath + "/api/dev/cli-signin-code", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      });
+      body = await res.json().catch(() => ({}));
+    } catch (err) {
+      if (note) note.textContent = "Couldn't reach the sign-in service — try again in a moment.";
+      label(" Copy the command"); btn.disabled = false; busy = false;
+      return;
+    }
+    if (!res.ok || !body.command) {
+      const byStatus: Record<number, string> = {
+        401: "Your session expired — reload the page and sign in again.",
+        403: "This account doesn't have developer access to a store yet.",
+        409: "Your store isn't set up yet — reload this page for its status.",
+        502: "The sign-in service is having a moment — try again.",
+        503: "Terminal sign-in isn't configured on this environment.",
+      };
+      if (note) note.textContent = byStatus[res.status] || "Couldn't mint a sign-in command — try again.";
+      label(" Copy the command"); btn.disabled = false; busy = false;
+      return;
+    }
+    // Reveal the real command (carries the non-secret rendezvous handle) as a pure
+    // text node, then copy it.
+    textEl.textContent = body.command;
+    textEl.classList.remove("is-placeholder");
+    revealIcon();
+    // Start watching for the terminal to attach so we can prompt for approval.
+    if (body.rendezvousCode) rzvStart(body.rendezvousCode);
+    const ok = await copy(body.command);
+    if (ok) flashCopied();
+    label(ok ? " Copied ✓" : " Select & copy");
+    ping(ok ? "Copied — paste & press Enter" : "Select the command above to copy");
+    if (note) {
+      note.textContent = ok
+        ? "Copied. Paste into your terminal and press Enter — it signs you in, runs your store, and opens your browser. Single-use, short-lived code."
+        : "Select the command above and copy it, then paste into your terminal and press Enter. Single-use, short-lived code.";
+    }
+    btn.disabled = false;
+    setTimeout(() => { label(" Copy the command"); }, 4000);
+    busy = false;
+  });
+}