@tokenoftrust/storefront-runner 1.4.0 → 1.4.1

package/apps/storefront/src/pages/admin/ops-timeline.astro

@@ -0,0 +1,420 @@
+---
+/**
+ * `/admin/ops-timeline` — the operational-activity timeline VIEW (card D5).
+ *
+ * The READ surface of the actor×action telemetry spine: a chronological,
+ * tenant-scoped list of lifecycle activity answering "who shipped/rejected what,
+ * when, why — and what happened to my change/deploy". It reads the D1
+ * `activity_events` timeline cohort (DECISIONS.md §8) through the pure,
+ * tenant-scoped query module (`lib/activity/query.ts`).
+ *
+ * ROUTING / AUTH — mirrors `admin.astro`: middleware resolves the tenant, injects
+ * CSP/security headers, and already held anonymous/non-member visitors at the
+ * sign-in gate. This surface exposes operational detail, so it renders the data
+ * ONLY for a viewer with owner/admin standing for the routed tenant, or a ToT-staff
+ * session (`resolveAdminEntry` / `resolveAdminTenantMode`, the same machinery the
+ * admin shell uses). A signed-in non-owner sees the chrome + a "no standing" notice,
+ * never another tenant's rows.
+ *
+ * TENANT ISOLATION — the query is ALWAYS scoped to `Astro.locals.tenant.tenant_id`
+ * (the served tenant, never a URL value); `parseTimelineQuery` pins that tenant and
+ * ignores any `tenant`/`tenantId` query param. See `query.isolation.test.ts` for the
+ * hostile read-side proof.
+ *
+ * DEPLOY SKEW (card D2) — the page surfaces `deriveDeploySkew()`: a banner when the
+ * build serving this page (or the timeline) shows more than one live version, plus a
+ * per-row "stale build" chip on superseded `deploy.version_observed` rows.
+ *
+ * ALERTS (card D7) — the page also runs `checkActivityAlerts()` (silent-terminal,
+ * recurring preview.serve miss_no_env, reconcile-hang watchdog, and — promoting the
+ * skew signal above — a persistent deploy-skew alert) and renders an alerts banner
+ * above the deploy-skew visibility banner. Same on-demand posture: computed fresh on
+ * every page load, no cron. `GET /api/admin/activity-alerts` exposes the identical
+ * check for an external poller.
+ */
+export const prerender = false;
+
+import { readViewerSession } from "@/lib/auth/route";
+import { resolveAdminEntry } from "@/lib/auth/adminEntry";
+import { resolveAdminTenantMode } from "@/lib/adminTenantEnvelope";
+import { readD1 } from "@/lib/env";
+import { fromD1 } from "@/lib/d1/catalog";
+import {
+  parseTimelineQuery,
+  loadOpsTimeline,
+  type OpsTimelineData,
+  type ActivityTimelineRow,
+} from "@/lib/activity/query";
+import { checkActivityAlerts, type ActivityAlert } from "@/lib/activity/alerts";
+
+const { tenant, basePath, cspNonce } = Astro.locals;
+const adminPath = `${basePath || ""}/admin`;
+const timelinePath = `${adminPath}/ops-timeline`;
+const tenantLabel = tenant.displayName || tenant.appDomain || tenant.tenant_id;
+const nowSeconds = Math.floor(Date.now() / 1000);
+
+const viewerSession = await readViewerSession(Astro);
+const viewerEmail = (Astro.locals.viewer?.email ?? viewerSession?.email ?? "").toLowerCase();
+
+const adminEntry = resolveAdminEntry({
+  record: viewerSession,
+  hostResource: tenant.appDomain,
+  nowSeconds,
+});
+const { isStaff } = resolveAdminTenantMode({
+  session: viewerSession,
+  adminAppTenant: tenant.appDomain,
+  requestedTarget: null,
+  nowSeconds,
+});
+
+// Gate: a signed-in owner/admin of THIS tenant, or ToT staff. Everyone else gets
+// chrome + a notice, and the query never runs.
+const authorized = Boolean(viewerSession) && (adminEntry.isOwnerViewer || isStaff);
+
+// The query is scoped to the SERVED tenant's id — never a URL value.
+const query = parseTimelineQuery(Astro.url.searchParams, tenant.tenant_id);
+
+let data: OpsTimelineData | null = null;
+let alerts: ActivityAlert[] = [];
+let dbAvailable = true;
+if (authorized) {
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (d1) {
+    const db = fromD1(d1);
+    [data, alerts] = await Promise.all([
+      loadOpsTimeline(db, query),
+      checkActivityAlerts(db, tenant.tenant_id),
+    ]);
+  } else {
+    // Dev/Node or an env without the binding — the timeline lives only in D1.
+    dbAvailable = false;
+  }
+}
+
+const rows = data?.rows ?? [];
+const skew = data?.deploySkew ?? null;
+// Versions superseded by a newer observation → a "stale build" chip on those rows.
+const staleVersions = new Set(
+  (skew?.observedVersions ?? [])
+    .filter((v) => v.version !== skew?.latestObservedVersion)
+    .map((v) => v.version),
+);
+
+/** Short, non-PII actor label (the id is already an opaque pseudonym). */
+function shortActor(row: ActivityTimelineRow): string {
+  const id = row.actorId.length > 14 ? `${row.actorId.slice(0, 14)}…` : row.actorId;
+  return `${row.actorKind}:${id}`;
+}
+
+/** Map a status to a chip color class. */
+function statusClass(status: string): string {
+  switch (status) {
+    case "succeeded":
+      return "green";
+    case "failed":
+      return "red";
+    case "refused":
+      return "amber";
+    default:
+      return "blue"; // invoked
+  }
+}
+
+/** Compact, human detail line from the (already redacted) payload. */
+function detailFor(row: ActivityTimelineRow): string {
+  const parts: string[] = [];
+  const rendered = row.payload.rendered ?? {};
+  for (const [k, v] of Object.entries(rendered)) parts.push(`${k}: ${v}`);
+  const args = row.payload.args ?? {};
+  for (const [k, v] of Object.entries(args)) {
+    if (k === "changeId") continue; // shown in its own column
+    parts.push(`${k}=${String(v)}`);
+  }
+  return parts.join(" · ");
+}
+
+/** The version an event refers to (deploy.version_observed rows carry it). */
+function versionOf(row: ActivityTimelineRow): string | undefined {
+  const v = row.payload.args?.version;
+  return typeof v === "string" ? v : undefined;
+}
+
+const statusOptions = ["", "invoked", "succeeded", "failed", "refused"];
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex, nofollow" />
+    <title>{tenantLabel} · Ops Timeline</title>
+    <style is:global nonce={cspNonce}>
+      :root {
+        color-scheme: light;
+        --bg: #f5f7f6;
+        --surface: #ffffff;
+        --surface-soft: #f9fbfa;
+        --ink: #16211f;
+        --muted: #64716d;
+        --line: #dce5e2;
+        --teal: #007f79;
+        --green-soft: #e3f5eb;
+        --green: #137a55;
+        --red-soft: #fde7e4;
+        --red: #b42318;
+        --amber-soft: #fff0d5;
+        --amber: #a45d00;
+        --blue-soft: #e7efff;
+        --blue: #2458c7;
+        --radius: 8px;
+        --font: Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+        --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      }
+      * { box-sizing: border-box; }
+      body { margin: 0; background: var(--bg); color: var(--ink); font: 14px/1.5 var(--font); }
+      a { color: var(--teal); }
+      .wrap { max-width: 1180px; margin: 0 auto; padding: 24px 20px 64px; }
+      header.page { margin-bottom: 18px; }
+      header.page h1 { margin: 0; font-size: 22px; font-weight: 760; }
+      header.page p { margin: 4px 0 0; color: var(--muted); font-size: 13px; }
+      header.page code { font-family: var(--mono); }
+      .notice {
+        padding: 14px 16px; border: 1px solid var(--amber); border-radius: var(--radius);
+        background: var(--amber-soft); color: #5c3600; margin-bottom: 18px; font-size: 13px;
+      }
+      .skew {
+        display: flex; align-items: flex-start; gap: 12px;
+        padding: 12px 14px; border: 1px solid #f1c883; border-radius: var(--radius);
+        background: #fff6e7; margin-bottom: 18px; font-size: 13px;
+      }
+      .skew strong { display: block; }
+      .skew .versions { color: var(--muted); font-size: 12px; margin-top: 3px; }
+      .skew code { font-family: var(--mono); }
+      .alerts { display: grid; gap: 8px; margin-bottom: 18px; }
+      .alert {
+        display: flex; align-items: flex-start; gap: 12px;
+        padding: 12px 14px; border-radius: var(--radius); font-size: 13px;
+      }
+      .alert strong { display: block; }
+      .alert .meta { color: inherit; opacity: 0.75; font-size: 12px; margin-top: 3px; }
+      .alert.page, .alert.critical {
+        border: 1px solid var(--red); background: var(--red-soft); color: var(--red);
+      }
+      .alert.warning {
+        border: 1px solid #f1c883; background: #fff6e7; color: #7a4a00;
+      }
+      .alert.info {
+        border: 1px solid var(--line); background: var(--surface-soft); color: var(--muted);
+      }
+      form.filters {
+        display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+        gap: 10px; align-items: end;
+        padding: 14px; border: 1px solid var(--line); border-radius: var(--radius);
+        background: var(--surface); margin-bottom: 18px;
+      }
+      form.filters .field { display: grid; gap: 4px; min-width: 0; }
+      form.filters label { color: var(--muted); font-size: 11px; font-weight: 760; text-transform: uppercase; }
+      form.filters input, form.filters select {
+        min-height: 36px; padding: 0 9px; font: inherit;
+        border: 1px solid var(--line); border-radius: 6px; background: #fcfdfc; color: var(--ink);
+      }
+      form.filters .actions { display: flex; gap: 8px; }
+      .btn {
+        min-height: 36px; display: inline-flex; align-items: center; padding: 0 14px;
+        border: 1px solid var(--teal); border-radius: 6px; background: var(--teal); color: #fff;
+        font-weight: 680; text-decoration: none; cursor: pointer;
+      }
+      .btn.ghost { background: var(--surface); color: var(--ink); border-color: var(--line); }
+      .table-wrap { overflow-x: auto; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); }
+      table { width: 100%; min-width: 920px; border-collapse: collapse; font-size: 13px; }
+      th {
+        height: 38px; padding: 0 12px; border-bottom: 1px solid var(--line);
+        background: var(--surface-soft); color: var(--muted); font-size: 11px;
+        font-weight: 760; text-align: left; text-transform: uppercase; white-space: nowrap;
+      }
+      td { padding: 9px 12px; border-bottom: 1px solid var(--line); vertical-align: top; }
+      tr:last-child td { border-bottom: 0; }
+      td.at { white-space: nowrap; font-family: var(--mono); font-size: 12px; color: var(--muted); }
+      td.action code, td.change code, td.actor code { font-family: var(--mono); font-size: 12px; }
+      td.action small { display: block; color: var(--muted); font-size: 11px; margin-top: 2px; }
+      td.detail { color: var(--muted); overflow-wrap: anywhere; }
+      .chip {
+        display: inline-flex; align-items: center; min-height: 20px; padding: 0 8px;
+        border-radius: 999px; background: var(--surface-soft); color: #3f4d49;
+        font-size: 11px; font-weight: 740; white-space: nowrap;
+      }
+      .chip.green { background: var(--green-soft); color: var(--green); }
+      .chip.red { background: var(--red-soft); color: var(--red); }
+      .chip.amber { background: var(--amber-soft); color: var(--amber); }
+      .chip.blue { background: var(--blue-soft); color: var(--blue); }
+      .chip.stale { background: #ffe0d6; color: #a5330a; margin-left: 6px; }
+      .empty { padding: 40px 16px; text-align: center; color: var(--muted); }
+      @media (max-width: 760px) {
+        form.filters { grid-template-columns: 1fr 1fr; }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="wrap">
+      <header class="page">
+        <h1>Operational activity timeline</h1>
+        <p>
+          {tenantLabel} · <code>{tenant.tenant_id}</code> · lifecycle events, newest first ·
+          <a href={adminPath}>← Admin</a>
+        </p>
+      </header>
+
+      {!viewerSession && (
+        <div class="notice">
+          Sign in as an owner/admin of {tenantLabel} to view the operational activity timeline.
+          <a href="/auth/login">Sign in</a>.
+        </div>
+      )}
+
+      {viewerSession && !authorized && (
+        <div class="notice">
+          {viewerEmail} is signed in but has no owner/admin standing for {tenantLabel}. The ops
+          timeline is limited to owners/admins of this store and ToT staff.
+        </div>
+      )}
+
+      {authorized && !dbAvailable && (
+        <div class="notice">
+          The activity timeline is stored in D1 (<code>STOREFRONT_APPS_DB</code>), which isn't
+          bound in this environment — no rows to show here.
+        </div>
+      )}
+
+      {authorized && alerts.length > 0 && (
+        <div class="alerts" role="alert">
+          {alerts.map((a) => (
+            <div class={`alert ${a.severity}`}>
+              <span aria-hidden="true">{a.severity === "page" || a.severity === "critical" ? "🚨" : "⚠️"}</span>
+              <div>
+                <strong>{a.title}</strong>
+                <div>{a.summary}</div>
+                <div class="meta">
+                  {a.changeId && <>Change <code>{a.changeId}</code> · </>}
+                  since {a.since}
+                </div>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {authorized && skew?.skewDetected && (
+        <div class="skew" role="status">
+          <span aria-hidden="true">⚠️</span>
+          <div>
+            <strong>Deploy skew detected</strong>
+            <div class="versions">
+              {skew.runningVersion
+                ? <>Serving build <code>{skew.runningVersion}</code>. </>
+                : <>Serving build unknown. </>}
+              Observed builds:{" "}
+              {skew.observedVersions.map((v, i) => (
+                <>
+                  {i > 0 ? ", " : ""}
+                  <code>{v.version}</code>{v.env ? ` (${v.env})` : ""}
+                  {v.version === skew.latestObservedVersion ? " — latest" : " — stale"}
+                </>
+              ))}.
+              This is a visibility signal only (alerting is a separate concern).
+            </div>
+          </div>
+        </div>
+      )}
+
+      {authorized && (
+        <form class="filters" method="get" action={timelinePath}>
+          <div class="field">
+            <label for="f-changeId">Change ID</label>
+            <input id="f-changeId" type="text" name="changeId" value={query.changeId ?? ""} placeholder="chg-…" />
+          </div>
+          <div class="field">
+            <label for="f-action">Action</label>
+            <input id="f-action" type="text" name="action" value={query.action ?? ""} placeholder="change.ship" />
+          </div>
+          <div class="field">
+            <label for="f-actionPrefix">Action family</label>
+            <input id="f-actionPrefix" type="text" name="actionPrefix" value={query.actionPrefix ?? ""} placeholder="change." />
+          </div>
+          <div class="field">
+            <label for="f-actorId">Actor ID</label>
+            <input id="f-actorId" type="text" name="actorId" value={query.actorId ?? ""} placeholder="h_…" />
+          </div>
+          <div class="field">
+            <label for="f-status">Status</label>
+            <select id="f-status" name="status">
+              {statusOptions.map((s) => (
+                <option value={s} selected={query.status === s || (s === "" && !query.status)}>
+                  {s === "" ? "any" : s}
+                </option>
+              ))}
+            </select>
+          </div>
+          <div class="field">
+            <label for="f-since">Since (ISO)</label>
+            <input id="f-since" type="text" name="since" value={query.since ?? ""} placeholder="2026-08-01" />
+          </div>
+          <div class="field">
+            <label for="f-until">Until (ISO)</label>
+            <input id="f-until" type="text" name="until" value={query.until ?? ""} placeholder="2026-08-31" />
+          </div>
+          <div class="field actions">
+            <button class="btn" type="submit">Filter</button>
+            <a class="btn ghost" href={timelinePath}>Reset</a>
+          </div>
+        </form>
+      )}
+
+      {authorized && dbAvailable && (
+        <div class="table-wrap">
+          <table>
+            <thead>
+              <tr>
+                <th>When</th>
+                <th>Actor</th>
+                <th>Action</th>
+                <th>Status</th>
+                <th>Change</th>
+                <th>Detail</th>
+              </tr>
+            </thead>
+            <tbody>
+              {rows.length === 0 && (
+                <tr>
+                  <td class="empty" colspan="6">No activity matches these filters yet.</td>
+                </tr>
+              )}
+              {rows.map((row) => {
+                const version = versionOf(row);
+                const isStale = version != null && staleVersions.has(version);
+                return (
+                  <tr>
+                    <td class="at">{row.at}</td>
+                    <td class="actor"><code>{shortActor(row)}</code></td>
+                    <td class="action">
+                      <code>{row.action}</code>
+                      {row.actionDesc && <small>{row.actionDesc}</small>}
+                    </td>
+                    <td>
+                      <span class={`chip ${statusClass(row.status)}`}>{row.status}</span>
+                      {row.errorClass && <span class="chip amber">{row.errorClass}</span>}
+                      {isStale && <span class="chip stale">stale build</span>}
+                    </td>
+                    <td class="change">{row.changeId ? <code>{row.changeId}</code> : "—"}</td>
+                    <td class="detail">{detailFor(row) || "—"}</td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  </body>
+</html>

package/apps/storefront/src/pages/admin.astro

@@ -103,7 +103,9 @@ const { envelope: tenantEnvelope, isStaff, pickerTenants, deniedTarget } = admin
         const adminTabs = ["orders", "products", "subscriptions", "customers", "fulfillment", "reporting", "ai-workflows", "publish", "settings"];
         const canViewInternalGuide = document.documentElement.dataset.internalAdminGuide === "true";
         const defaultTab = canViewInternalGuide ? "orders" : "settings";
-        const hash = window.location.hash.slice(1);
+        // A deep link may carry a query suffix in the hash (e.g. #publish?pr=42);
+        // the tab id is only the part before "?".
+        const hash = window.location.hash.slice(1).split("?")[0];
         const activeTab = adminTabs.includes(hash) ? hash : defaultTab;
         const mode = canViewInternalGuide && hash && !adminTabs.includes(hash) ? "guide" : "work-area";
 
@@ -252,6 +254,100 @@ const { envelope: tenantEnvelope, isStaff, pickerTenants, deniedTarget } = admin
         background: rgba(255, 255, 255, 0.06);
       }
 
+      /* Cross-surface hop to the developer cockpit — same card language as the
+         sidebar's other blocks, kept visually quieter than the nav tabs. */
+      .cockpit-link {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        padding: 10px 12px;
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        border-radius: var(--admin-radius);
+        background: rgba(255, 255, 255, 0.04);
+        color: rgba(238, 247, 245, 0.85);
+        font-size: 13px;
+        text-decoration: none;
+      }
+      .cockpit-link:hover {
+        background: rgba(255, 255, 255, 0.1);
+        color: #fff;
+      }
+      .cockpit-link svg {
+        width: 15px;
+        height: 15px;
+        stroke: currentColor;
+        fill: none;
+      }
+
+      /* Signed-in-as chip (identity visibility — Trello 13075 postscript: an
+         owner staring at a read-only Publish tab could not tell WHO the shell
+         thought they were). Mirrors .store's card language; the standing line
+         states the resolved principal FOR THIS STORE, not a global role. */
+      .account {
+        display: grid;
+        grid-template-columns: auto 1fr;
+        gap: 10px;
+        align-items: center;
+        padding: 12px;
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        border-radius: var(--admin-radius);
+        background: rgba(255, 255, 255, 0.06);
+        /* Pinned to the sidebar's lower-left (the conventional account slot) —
+           the sidebar is a flex column, so this soaks the remaining space. */
+        margin-top: auto;
+      }
+      .account .account-avatar {
+        display: grid;
+        place-items: center;
+        width: 32px;
+        height: 32px;
+        border-radius: 50%;
+        border: 1px solid rgba(255, 255, 255, 0.2);
+        background: rgba(255, 255, 255, 0.08);
+      }
+      .account .account-avatar svg {
+        width: 16px;
+        height: 16px;
+        stroke: currentColor;
+        fill: none;
+        stroke-width: 1.8;
+      }
+      .account .account-meta {
+        display: grid;
+        gap: 2px;
+        min-width: 0;
+      }
+      .account .account-email {
+        font-weight: 640;
+        font-size: 13px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+      .account .account-standing {
+        color: rgba(238, 247, 245, 0.7);
+        font-size: 11px;
+      }
+      .account .account-standing[data-standing="none"] {
+        color: rgba(255, 196, 120, 0.9);
+      }
+      .account a {
+        color: inherit;
+      }
+      .account .account-signout button {
+        margin-top: 2px;
+        padding: 0;
+        border: 0;
+        background: none;
+        color: rgba(238, 247, 245, 0.6);
+        font-size: 11px;
+        text-decoration: underline;
+        cursor: pointer;
+      }
+      .account .account-signout button:hover {
+        color: rgba(238, 247, 245, 0.9);
+      }
+
       .tenant-picker {
         display: grid;
         gap: 4px;
@@ -805,6 +901,13 @@ const { envelope: tenantEnvelope, isStaff, pickerTenants, deniedTarget } = admin
         background: #fff6e7;
       }
 
+      /* A JS-toggled `.risk-alert` (e.g. the degraded-forge strip) must stay hidden
+         when `hidden` is set — the base display:flex above would otherwise win over
+         the UA [hidden] rule and keep it visible. */
+      .risk-alert[hidden] {
+        display: none;
+      }
+
       .risk-alert svg {
         color: var(--admin-amber);
       }
@@ -1089,6 +1192,7 @@ const { envelope: tenantEnvelope, isStaff, pickerTenants, deniedTarget } = admin
       <symbol id="i-orders" viewBox="0 0 24 24"><path d="M7 4h10a2 2 0 0 1 2 2v14l-3-2-2 2-2-2-2 2-3 2V6a2 2 0 0 1 2-2Z"></path><path d="M9 9h6M9 13h6"></path></symbol>
       <symbol id="i-box" viewBox="0 0 24 24"><path d="m3 7 9-4 9 4-9 4-9-4Z"></path><path d="M3 7v10l9 4 9-4V7"></path><path d="M12 11v10"></path></symbol>
       <symbol id="i-users" viewBox="0 0 24 24"><path d="M16 21v-2a4 4 0 0 0-4-4H7a4 4 0 0 0-4 4v2"></path><circle cx="9.5" cy="7" r="4"></circle><path d="M22 21v-2a4 4 0 0 0-3-3.9"></path><path d="M16 3.1a4 4 0 0 1 0 7.8"></path></symbol>
+      <symbol id="i-user" viewBox="0 0 24 24"><path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"></path><circle cx="12" cy="7" r="4"></circle></symbol>
       <symbol id="i-shield" viewBox="0 0 24 24"><path d="M12 3 20 6v6c0 5-3.4 8.4-8 9-4.6-.6-8-4-8-9V6l8-3Z"></path><path d="m8.8 12 2.2 2.2L15.8 9"></path></symbol>
       <symbol id="i-chart" viewBox="0 0 24 24"><path d="M4 19V5"></path><path d="M4 19h16"></path><path d="M8 16v-5"></path><path d="M12 16V8"></path><path d="M16 16v-3"></path></symbol>
       <symbol id="i-workflows" viewBox="0 0 24 24"><path d="M6 5h6a4 4 0 0 1 4 4v1"></path><path d="m19 7-3 3-3-3"></path><path d="M18 19h-6a4 4 0 0 1-4-4v-1"></path><path d="m5 17 3-3 3 3"></path><circle cx="6" cy="5" r="2"></circle><circle cx="18" cy="19" r="2"></circle></symbol>
@@ -1163,6 +1267,44 @@ const { envelope: tenantEnvelope, isStaff, pickerTenants, deniedTarget } = admin
           <div class="health-row"><span>Payments</span><strong>OK</strong></div>
           <div class="health-row"><span>Risk checks</span><strong>OK</strong></div>
         </div>
+
+        <!-- Cross-surface hop: the developer cockpit is a SIBLING surface (dev
+             setup + connection status), not an admin tab — link, don't embed.
+             basePath-aware so it stays inside the tenant prefix. -->
+        <a class="cockpit-link" href={`${basePath || ""}/cockpit`}>
+          <svg><use href="#i-gear"></use></svg><span>Developer cockpit</span>
+        </a>
+
+        <div class="account" data-admin-account>
+          <span class="account-avatar" aria-hidden="true"><svg><use href="#i-user"></use></svg></span>
+          <span class="account-meta">
+            {viewerEmail ? (
+              <>
+                <span class="account-email" title={viewerEmail}>{viewerEmail}</span>
+                <span
+                  class="account-standing"
+                  data-standing={adminEntry.isOwnerViewer ? "owner" : isStaff ? "staff" : "none"}
+                >
+                  {adminEntry.isOwnerViewer
+                    ? `owner/admin of ${tenantEnvelope.targetTenant}`
+                    : isStaff
+                      ? `ToT staff · not an owner of ${tenantEnvelope.targetTenant}`
+                      : `signed in · no owner/admin standing for ${tenantEnvelope.targetTenant}`}
+                </span>
+                <form class="account-signout" method="post" action="/api/auth/logout">
+                  <button type="submit">Sign out</button>
+                </form>
+              </>
+            ) : (
+              <>
+                <span class="account-email">Not signed in</span>
+                <span class="account-standing" data-standing="none">
+                  <a href="/auth/login">sign in</a> as an owner/admin of {tenantEnvelope.targetTenant} to publish
+                </span>
+              </>
+            )}
+          </span>
+        </div>
       </aside>
 
       <main class="main">
@@ -1490,12 +1632,15 @@ const { envelope: tenantEnvelope, isStaff, pickerTenants, deniedTarget } = admin
         };
 
         const panelIdFromHash = () => {
-          const hash = window.location.hash.slice(1);
-          if (!hash) return defaultTab;
+          const rawHash = window.location.hash.slice(1);
+          // The tab id is the part before any "?" query suffix (#publish?pr=42);
+          // the raw hash is still used for internal-guide anchor resolution.
+          const hash = rawHash.split("?")[0];
+          if (!rawHash) return defaultTab;
           if (tabSet.has(hash)) return hash;
           if (!canViewInternalGuide) return defaultTab;
 
-          const target = hash ? document.getElementById(hash) : null;
+          const target = rawHash ? document.getElementById(rawHash) : null;
           const panel = target?.closest?.("[data-admin-panel]");
           if (panel?.id && tabSet.has(panel.id)) return panel.id;
 
@@ -1625,8 +1770,11 @@ const { envelope: tenantEnvelope, isStaff, pickerTenants, deniedTarget } = admin
 
           if (panelId) {
             setActiveTab(panelId);
-            const hash = window.location.hash.slice(1);
-            if (!canViewInternalGuide && (!hash || !tabSet.has(hash))) {
+            // Strip any query suffix before deciding whether the hash names a
+            // real tab — a valid deep link like #publish?pr=42 must not be
+            // normalized away to #settings for merchant viewers.
+            const hashTab = window.location.hash.slice(1).split("?")[0];
+            if (!canViewInternalGuide && !tabSet.has(hashTab)) {
               history.replaceState(null, "", "#settings");
             }
             if (scroll) requestAnimationFrame(() => scrollToHashTarget(panelId));