@pleri/olam-cli 0.1.180 → 0.1.185

package/hermes-bundle/version.json

@@ -1,4 +1,4 @@
 {
-  "bundledAt": "2026-05-24T18:50:58.922Z",
+  "bundledAt": "2026-05-27T14:19:47.128Z",
   "kgFirstSha": "29a9ccce1b115d049e375c4a90eb5cf7c123e610e2d0590270a4db2cdbc64a28"
 }

package/host-cp/k8s/manifests/30-configmap.yaml

@@ -24,12 +24,17 @@ data:
   OLAM_WORLDS_DB: "/data/worlds.db"
   OLAM_PLAN_DB_PATH: "/data/plan.db"
   OLAM_PLAN_DIR: "/data/plan"
-  # Same /data routing for the plan-chat bearer gateway. K8s pod runs as
-  # UID 1000 with readOnlyRootFilesystem: true, so the bearer file CAN
-  # NEVER be created under /home/node/.olam even with mkdir-recursive —
-  # the env override is mandatory here, not optional. Bind-mounted /data
-  # is the writable PVC.
-  OLAM_PLAN_CHAT_SECRET_PATH: "/data/plan-chat-secret"
+  # Phase B Model B: bearer file is now sourced from the shared
+  # olam-plan-chat-secret Kubernetes Secret (mounted at /etc/olam-plan-chat/).
+  # Two readers, one source-of-truth — replaces the per-pod /data/plan-chat-secret
+  # file that couldn't be shared across pods on RWO PVCs. The plan-chat-service
+  # pod also mounts the SAME Secret at the SAME path so bearer comparisons
+  # work both ways.
+  OLAM_PLAN_CHAT_SECRET_PATH: "/etc/olam-plan-chat/secret"
+  # In-cluster plan-chat-service URL. Rewritten by upgrade-kubernetes.ts step 2.5
+  # (buildK8sDnsUrl) — the default below is a sane fallback for raw
+  # `kubectl apply -f` operators who skip the CLI wrapper.
+  PLAN_CHAT_SERVICE_URL: "http://olam-plan-chat-service.olam.svc.cluster.local:3200"
   # NDJSON span sink + recovery ledger — route to the writable PVC mount at
   # /data rather than the default ~/.olam/logs (which resolves to
   # /home/node/.olam/logs and is not writable with readOnlyRootFilesystem: true).

package/host-cp/k8s/manifests/45-pvc.yaml

@@ -1,4 +1,4 @@
-# PersistentVolumeClaim for olam-host-cp /data volume.
+# PersistentVolumeClaim for olam-host-cp /data volume — k3d substrate default.
 #
 # Why PVC instead of hostPath:
 #   hostPath volumes on k3d nodes resolve to paths INSIDE the k3d node
@@ -9,7 +9,11 @@
 #   root-owned hostPath mounts even when fsGroup: 1000 is set.
 #
 # local-path StorageClass ships with k3d by default (rancher/local-path-provisioner).
-# On non-k3d clusters, substitute with the appropriate StorageClass name.
+# On non-k3d clusters, substitute with the appropriate StorageClass name (D24,
+# operator-editable). For managed clusters (GKE, EKS, AKS) use the GKE-variant
+# manifest instead: packages/host-cp/k8s/manifests/gke/45-pvc.yaml (storageClassName:
+# standard-rwo). See docs/architecture/peripheral-services-on-k3s.md Decision #3
+# for the full per-cluster storageclass table.
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:

package/host-cp/k8s/manifests/50-deployment.yaml

@@ -118,7 +118,7 @@ spec:
         # k3d), started by `olam upgrade` Step 0.7 — not inside this Pod.
       containers:
         - name: olam-host-cp
-          image: ghcr.io/pleri/olam-host-cp@sha256:50598fca503775b8984c8717505f4f6266d61d86f5e55343733215a4cb7794e7
+          image: ghcr.io/pleri/olam-host-cp@sha256:843bea5159a7b5ec792a7d0a9766c49eb0443180023526c0c21d56e32982fd4e
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true
@@ -147,6 +147,13 @@ spec:
               readOnly: true
             - name: tmp
               mountPath: /tmp
+            # Phase B Model B: shared olam-plan-chat-secret mounted read-only
+            # so renderSpaShell can inject window.__OLAM_PLAN_CHAT_BEARER__.
+            # Plan-chat-service mounts the SAME Secret at the SAME path so
+            # bearer compares match across pods.
+            - name: plan-chat-secret
+              mountPath: /etc/olam-plan-chat
+              readOnly: true
             # docker-socket volumeMount REMOVED in olam-k3d-on-mac-substrate-
             # decision Phase B B2. Docker access now goes via TCP to the
             # docker-socket-proxy ExternalName Service in the olam namespace.
@@ -191,6 +198,13 @@ spec:
             type: DirectoryOrCreate
         - name: tmp
           emptyDir: {}
+        - name: plan-chat-secret
+          secret:
+            secretName: olam-plan-chat-secret
+            defaultMode: 0400
+            items:
+              - key: PLAN_CHAT_SECRET
+                path: secret
         # host-colima + docker-socket volumes REMOVED in olam-k3d-on-mac-
         # substrate-decision Phase B B2 (2026-05-21). R3-A's two-volume
         # hostPath approach is fully retracted: round-4 R4-W2-F demonstrated

package/host-cp/k8s/manifests/auth-service/50-deployment.yaml

@@ -70,7 +70,7 @@ spec:
               mountPath: /data
       containers:
         - name: olam-auth-service
-          image: ghcr.io/pleri/olam-auth@sha256:5dec481a1bf4ab87a5dc354a3d6f71323f3f5403476cea50a934afde18a58bc5
+          image: ghcr.io/pleri/olam-auth@sha256:59de0618b656c45ed75465aefab637bd3b50ef803ae8d802c828c26d97183328
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/k8s/manifests/kg-service/50-deployment.yaml

@@ -61,7 +61,7 @@ spec:
               mountPath: /data
       containers:
         - name: olam-kg-service
-          image: ghcr.io/pleri/olam-kg-service@sha256:aa4138021389e303064babf7c81169e5b159aaf1570ba97429e29899f56f5000
+          image: ghcr.io/pleri/olam-kg-service@sha256:b53af63d452bb04420a1f89b5834888a324ee3995f45c908fa9321ec76b84047
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/k8s/manifests/mcp-auth-service/50-deployment.yaml

@@ -68,7 +68,7 @@ spec:
               mountPath: /data
       containers:
         - name: olam-mcp-auth-service
-          image: ghcr.io/pleri/olam-mcp-auth@sha256:e9d7c5c4222e2af20a2eb204dc3fa8090504bf99ddb5489115c21849706f1ad7
+          image: ghcr.io/pleri/olam-mcp-auth@sha256:635c1518e45cc0a1b5859cfb412d5a6eb9ab389630553eb9cdb6c903d97d8d15
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/k8s/manifests/memory-service/50-deployment.yaml

@@ -70,7 +70,7 @@ spec:
           # bootstrap-placeholder comment + run `npm run refresh:manifest-digests`
           # once ghcr.io/pleri/olam-memory-service has a real published digest.
           # bootstrap-placeholder: pre-publish; refresh after first release
-          image: ghcr.io/pleri/olam-memory-service@sha256:052c0d82d7888a0bd8970847dd5d3e001036e16feefda615b0e88eecf82d111f
+          image: ghcr.io/pleri/olam-memory-service@sha256:efad791c760420e6bccc68120621aba97a2532da517eb3f7d0e0349f6a2f8a06
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/k8s/templates/chunks-postgres-secret-template.yaml

@@ -0,0 +1,24 @@
+# Secret TEMPLATE for olam-chunks-postgres.
+#
+# Generates a random 64-char hex POSTGRES_PASSWORD on first apply (via
+# k8s-secret-render.ts generate-if-missing). The Secret is consumed by:
+#   - chunks-postgres StatefulSet (envFrom → POSTGRES_PASSWORD)
+#   - chunks-electric Deployment   (env: valueFrom.secretKeyRef)
+#   - plan-chat-service Deployment (env: valueFrom.secretKeyRef)
+#
+# All three resolve the SAME random value because the secret-renderer
+# persists generated values in ~/.olam/k8s-secrets-state.json so reapply
+# is idempotent (no rotation unless --rotate-secrets).
+apiVersion: v1
+kind: Secret
+metadata:
+  name: olam-chunks-postgres-secret
+  namespace: olam
+  labels:
+    app: olam-chunks-postgres
+    olam.io/component: substrate
+type: Opaque
+stringData:
+  # Postgres superuser password. Generated by the CLI's secret-renderer on
+  # first apply (no host-side file to read; this is in-cluster-only state).
+  POSTGRES_PASSWORD: "REPLACE_ME_GENERATE_RANDOM_HEX"

package/host-cp/k8s/templates/plan-chat-service-secret-template.yaml

@@ -0,0 +1,35 @@
+# Secret TEMPLATE for olam-plan-chat-secret.
+#
+# This file is a TEMPLATE — it MUST NOT be applied directly without substituting
+# the placeholder values. The placeholders are intentionally invalid; a raw
+# `kubectl apply` will result in auth failures rather than silently shipping
+# fake credentials.
+#
+# Preferred substitution (keeps secrets out of git):
+#   kubectl create secret generic olam-plan-chat-secret -n olam \
+#     --from-literal=PLAN_CHAT_SECRET=$(cat ~/.olam/plan-chat-secret) \
+#     --dry-run=client -o yaml | kubectl apply -f -
+#
+# This template lives in packages/host-cp/k8s/templates/ (NOT manifests/)
+# so that `kubectl apply -f manifests/plan-chat-service/` does NOT apply it —
+# operators must explicitly handle Secret provisioning before applying manifests.
+#
+# Architecture: this Secret is mounted by BOTH the host-cp pod (so its
+# renderSpaShell can inject window.__OLAM_PLAN_CHAT_BEARER__) AND the
+# plan-chat-service pod (so its bearer-auth gate timing-safe-compares incoming
+# Authorization: Bearer headers against the same value). One source-of-truth,
+# two readers — replaces the previous "/data/plan-chat-secret in host-cp PVC"
+# pattern that couldn't be shared across pods (RWO PVC).
+apiVersion: v1
+kind: Secret
+metadata:
+  name: olam-plan-chat-secret
+  namespace: olam
+  labels:
+    olam.io/component: substrate
+type: Opaque
+stringData:
+  # Shared bearer secret for plan-chat-service's POST /v1/chunks and
+  # GET /v1/shape endpoints. host-cp injects this into window.__OLAM_PLAN_CHAT_BEARER__.
+  # Source: cat ~/.olam/plan-chat-secret
+  PLAN_CHAT_SECRET: "REPLACE_ME_FROM_HOME_DOTOLAM_PLAN_CHAT_SECRET"

package/host-cp/observability/trace-summary.mjs

@@ -0,0 +1,267 @@
+// Trace summary — operator triage digest over the NDJSON span trace.
+//
+// The NDJSON span sink (see `ndjson-span-sink.mjs`) writes one JSON line
+// per span to ~/.olam/logs/host.trace.ndjson. Operators triage it today
+// with hand-typed `jq` one-liners (README § Observability): "longest 5
+// spans", "all failed spans", "failure-kind tally". This module codifies
+// those recipes into ONE digest so the common questions get one answer
+// without remembering jq incantations.
+//
+// Design:
+//   - `summarizeSpans(spans, opts)` is PURE — no I/O. Given an array of
+//     parsed span records (the exact shape the sink writes) it returns a
+//     digest object. This is the unit-testable core.
+//   - `parseTrace(ndjsonText)` turns raw file bytes into { spans, skipped }.
+//     Malformed lines (truncated tail line, partial write mid-rotation)
+//     are COUNTED, never thrown — triage tooling must survive a corrupt
+//     line, not die on it.
+//   - `summarizeTraceFile(path, opts)` is the thin file-reading wrapper.
+//   - `formatDigest(digest)` renders a human-readable report for the CLI.
+//
+// Read-only + additive: this module never writes the trace, never changes
+// the line schema. It only READS fields the sink already emits
+// (durationMs, exit._tag, exit.reason, name, attributes.failureKind).
+
+import { readFile } from 'node:fs/promises';
+
+const DEFAULT_TOP_N = 5;
+
+/**
+ * Parse NDJSON trace text into spans, tolerating malformed lines.
+ *
+ * @param {string} text raw file contents
+ * @returns {{ spans: object[], skipped: number }}
+ */
+export function parseTrace(text) {
+  const spans = [];
+  let skipped = 0;
+  for (const line of String(text).split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    try {
+      spans.push(JSON.parse(trimmed));
+    } catch {
+      // Truncated tail line or a partial write straddling rotation — the
+      // append-only log can leave one half-line. Triage must not crash on
+      // it; count and move on.
+      skipped += 1;
+    }
+  }
+  return { spans, skipped };
+}
+
+function isFailure(span) {
+  return span?.exit?._tag === 'Failure';
+}
+
+/**
+ * Compute a triage digest over parsed spans. Pure.
+ *
+ * @param {object[]} spans
+ * @param {{ topN?: number }} [opts]
+ * @returns {{
+ *   totalSpans: number,
+ *   failures: number,
+ *   successes: number,
+ *   failureRate: number,
+ *   slowest: object[],
+ *   recentFailures: object[],
+ *   failureReasons: { reason: string, count: number }[],
+ *   failureKinds: { kind: string, count: number }[],
+ *   byName: { name: string, count: number, failures: number, meanMs: number|null, maxMs: number|null }[],
+ * }}
+ */
+export function summarizeSpans(spans, { topN = DEFAULT_TOP_N } = {}) {
+  const list = Array.isArray(spans) ? spans : [];
+  const totalSpans = list.length;
+  const failingSpans = list.filter(isFailure);
+  const failures = failingSpans.length;
+  const successes = totalSpans - failures;
+  const failureRate = totalSpans === 0 ? 0 : failures / totalSpans;
+
+  // Slowest spans by durationMs. Spans with a null duration (in-flight or
+  // missing endedAt) are excluded — they carry no comparable cost signal.
+  const timed = list.filter((s) => typeof s?.durationMs === 'number');
+  const slowest = [...timed]
+    .sort((a, b) => b.durationMs - a.durationMs)
+    .slice(0, topN)
+    .map(projectSpan);
+
+  // Recent failures — the trace is append-only, so the last failures in
+  // file order are the most recent. Take the tail.
+  const recentFailures = failingSpans.slice(-topN).reverse().map(projectSpan);
+
+  const failureReasons = tally(
+    failingSpans,
+    (s) => (s?.exit?.reason != null ? String(s.exit.reason) : '(no reason)'),
+    'reason',
+  );
+
+  // failureKind is the world.lifecycle attribute the README already greps
+  // for; surface it as a first-class tally regardless of span name so
+  // recovery-relevant failures aggregate even when span names differ.
+  const failureKinds = tally(
+    list.filter((s) => s?.attributes?.failureKind != null),
+    (s) => String(s.attributes.failureKind),
+    'kind',
+  );
+
+  const byName = aggregateByName(list);
+
+  return {
+    totalSpans,
+    failures,
+    successes,
+    failureRate,
+    slowest,
+    recentFailures,
+    failureReasons,
+    failureKinds,
+    byName,
+  };
+}
+
+function projectSpan(s) {
+  return {
+    name: s?.name ?? null,
+    traceId: s?.traceId ?? null,
+    spanId: s?.spanId ?? null,
+    durationMs: typeof s?.durationMs === 'number' ? s.durationMs : null,
+    startedAt: typeof s?.startedAt === 'number' ? s.startedAt : null,
+    reason: s?.exit?.reason != null ? String(s.exit.reason) : null,
+  };
+}
+
+// Group spans by a string key and count occurrences, labelling the key
+// field per the caller (`reason` for failure reasons, `kind` for failure
+// kinds). Sorted by count descending so the dominant cause leads.
+function tally(spans, keyFn, label) {
+  const counts = new Map();
+  for (const s of spans) {
+    const key = keyFn(s);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const out = [];
+  for (const [k, count] of counts) out.push({ count, [label]: k });
+  return out.sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Per-span-name aggregate: count, failure count, mean + max duration.
+ * Sorted by count descending so the busiest spans surface first.
+ */
+function aggregateByName(spans) {
+  const groups = new Map();
+  for (const s of spans) {
+    const name = s?.name != null ? String(s.name) : '(unnamed)';
+    let g = groups.get(name);
+    if (!g) {
+      g = { name, count: 0, failures: 0, durSum: 0, durCount: 0, maxMs: null };
+      groups.set(name, g);
+    }
+    g.count += 1;
+    if (isFailure(s)) g.failures += 1;
+    if (typeof s?.durationMs === 'number') {
+      g.durSum += s.durationMs;
+      g.durCount += 1;
+      g.maxMs = g.maxMs === null ? s.durationMs : Math.max(g.maxMs, s.durationMs);
+    }
+  }
+  return [...groups.values()]
+    .map((g) => ({
+      name: g.name,
+      count: g.count,
+      failures: g.failures,
+      meanMs: g.durCount === 0 ? null : g.durSum / g.durCount,
+      maxMs: g.maxMs,
+    }))
+    .sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Read + summarize a trace file. Missing file → empty digest (an operator
+ * who hasn't generated any spans yet sees a clean zero-state, not a crash).
+ *
+ * @param {string} path
+ * @param {{ topN?: number }} [opts]
+ */
+export async function summarizeTraceFile(path, opts = {}) {
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { ...summarizeSpans([], opts), skipped: 0, missing: true };
+    }
+    throw err;
+  }
+  const { spans, skipped } = parseTrace(text);
+  return { ...summarizeSpans(spans, opts), skipped, missing: false };
+}
+
+function fmtMs(ms) {
+  if (ms == null) return '—';
+  if (ms >= 1000) return `${(ms / 1000).toFixed(2)}s`;
+  return `${Math.round(ms)}ms`;
+}
+
+/**
+ * Render a digest as a human-readable, plain-text report for the CLI.
+ *
+ * @param {ReturnType<typeof summarizeSpans> & { skipped?: number, missing?: boolean, path?: string }} digest
+ * @returns {string}
+ */
+export function formatDigest(digest) {
+  const lines = [];
+  const path = digest.path ? ` (${digest.path})` : '';
+  lines.push(`Trace summary${path}`);
+  if (digest.missing) {
+    lines.push('  no trace file yet — nothing recorded.');
+    return lines.join('\n');
+  }
+  const pct = (digest.failureRate * 100).toFixed(1);
+  lines.push(
+    `  ${digest.totalSpans} spans · ${digest.failures} failed (${pct}%) · ${digest.successes} ok` +
+      (digest.skipped ? ` · ${digest.skipped} malformed line(s) skipped` : ''),
+  );
+
+  if (digest.slowest.length) {
+    lines.push('');
+    lines.push(`Top ${digest.slowest.length} slowest:`);
+    for (const s of digest.slowest) {
+      lines.push(`  ${fmtMs(s.durationMs).padStart(7)}  ${s.name ?? '(unnamed)'}${s.traceId ? `  [${s.traceId}]` : ''}`);
+    }
+  }
+
+  if (digest.recentFailures.length) {
+    lines.push('');
+    lines.push(`Recent failures (${digest.recentFailures.length}):`);
+    for (const f of digest.recentFailures) {
+      lines.push(`  ${f.name ?? '(unnamed)'}: ${f.reason ?? '(no reason)'}${f.traceId ? `  [${f.traceId}]` : ''}`);
+    }
+  }
+
+  if (digest.failureKinds.length) {
+    lines.push('');
+    lines.push('Failure kinds:');
+    for (const k of digest.failureKinds) lines.push(`  ${String(k.count).padStart(4)}  ${k.kind}`);
+  }
+
+  if (digest.failureReasons.length) {
+    lines.push('');
+    lines.push('Failure reasons:');
+    for (const r of digest.failureReasons) lines.push(`  ${String(r.count).padStart(4)}  ${r.reason}`);
+  }
+
+  if (digest.byName.length) {
+    lines.push('');
+    lines.push('By span name (count · failures · mean · max):');
+    for (const n of digest.byName) {
+      lines.push(
+        `  ${String(n.count).padStart(5)} · ${String(n.failures).padStart(4)}f · ${fmtMs(n.meanMs).padStart(7)} · ${fmtMs(n.maxMs).padStart(7)}  ${n.name}`,
+      );
+    }
+  }
+
+  return lines.join('\n');
+}

package/host-cp/src/bootstrap-selective.mjs

@@ -1,19 +1,32 @@
-// bootstrap-selective.mjs — Phase D1 helper.
+// bootstrap-selective.mjs — Phase D1 helper, collapsed to a wildcard in
+// Phase E5 (ATOMIC SERVING CUTOVER).
 //
 // Determines whether a SPA shell render path should SKIP the host-cp
 // BOOTSTRAP_SCRIPT injection (cookie-bootstrap + fetch/EventSource
-// rewrite shim) and instead let plan-chat-spa's own readBearer()
-// resolver handle auth.
+// rewrite shim) and instead let the served SPA's own auth resolver +
+// world-fetch shim handle auth.
 //
-// Reversal: set BOOTSTRAP_NOOP_PLANNING_PATHS to [] to restore universal
-// injection. Single-line revert.
+// Phase E5: plan-chat-spa is now host-cp's SOLE served SPA. Its bundle
+// re-homes the cookie-bootstrap + world-fetch-rewrite + 401-recover shim
+// (packages/plan-chat-spa/src/lib/worldFetch.ts, installed at the top of
+// src/main.tsx — Phase C). Therefore host-cp NEVER needs to inject
+// BOOTSTRAP_SCRIPT anymore: every path is a "planning" (== SPA-owned)
+// path. isPlanningPath() is collapsed to a wildcard accordingly.
 //
-// Per K1 SCP-3 + phase-d-tasks.md D1.
+// Reversal: set isPlanningPath to consult BOOTSTRAP_NOOP_PLANNING_PATHS
+// again (restore the prefix-match body below) to re-narrow the no-op to
+// the explicit planning prefixes; or, for full pre-D behaviour, also set
+// BOOTSTRAP_NOOP_PLANNING_PATHS to []. The const is retained as the
+// documented revert seam.
+//
+// Per K1 SCP-3 + phase-d-tasks.md D1 + phase-e-tasks.md E2.
 
 /**
- * Path prefixes that are owned by plan-chat-spa. Bootstrap injection
- * is suppressed for these so the SPA's readBearer() resolver is the
- * sole auth path on planning surfaces.
+ * Path prefixes that WERE owned by plan-chat-spa under the Phase D
+ * selective no-op. Retained as the documented single-line revert seam:
+ * to re-narrow the bootstrap no-op back to only the planning surfaces,
+ * restore the prefix-match body in isPlanningPath() (see git history of
+ * this file at the Phase E5 commit) so it consults this array again.
  *
  * Format: include both the bare segment ("/plan") and the trailing-slash
  * variant ("/plan/"). The trailing-slash form is the prefix-match
@@ -27,30 +40,19 @@ export const BOOTSTRAP_NOOP_PLANNING_PATHS = Object.freeze([
 ]);
 
 /**
- * True when `pathname` is a planning surface owned by plan-chat-spa.
+ * Phase E5 wildcard: TRUE for every string path.
  *
- * Matches:
- *   /plan
- *   /plan/
- *   /plan/<sid>
- *   /plan/<sid>/<anything>
+ * host-cp now serves plan-chat-spa exclusively, whose bundle re-homes the
+ * cookie-bootstrap + world-fetch-rewrite shim (worldFetch.ts). No served
+ * path needs host-cp's BOOTSTRAP_SCRIPT injection anymore, so every path
+ * is treated as an SPA-owned ("planning") path and skips bootstrap.
  *
- * Does NOT match:
- *   /plan-something          (different top-level segment)
- *   /workspaces/plan         (planning isn't the top segment)
- *   /plans                   (different segment)
- *   undefined / null         (defensive)
+ * Returns false only for non-string input (defensive — a non-string
+ * pathname is never a real served path).
  *
  * @param {unknown} pathname
  * @returns {boolean}
  */
 export function isPlanningPath(pathname) {
-  if (typeof pathname !== 'string') return false;
-  for (const prefix of BOOTSTRAP_NOOP_PLANNING_PATHS) {
-    if (pathname === prefix) return true;
-    const bare = prefix.replace(/\/$/, '');
-    if (pathname === bare) return true;
-    if (prefix.endsWith('/') && pathname.startsWith(prefix)) return true;
-  }
-  return false;
+  return typeof pathname === 'string';
 }

package/host-cp/src/host-stream.mjs

@@ -23,6 +23,13 @@
 //         in-memory buffer; overflow drops oldest events with an
 //         `:overflow` comment so consumers know they missed updates.
 //   - E4: per-event-type broadcast counter + sink count metric line.
+//   - E5: the metrics tick ALSO broadcasts a `stream.health` typed event
+//         carrying the same counters it logs, so any SPA tab can observe
+//         live stream health (sink count, per-event broadcast rates,
+//         overflow drops) without polling. Snapshot-cached like every
+//         other state event — reconnecting clients replay the last
+//         health payload immediately (first-paint parity). Opt out via
+//         `deps.healthEvents = false`.
 //
 // Pure module: no docker, no DB, no global clock except `setInterval`
 // for the heartbeat/metrics timers (injectable in tests). Wiring those
@@ -43,7 +50,9 @@ import crypto from 'node:crypto';
  * @property {number}                    [debounceMs.default]  default trailing-edge ms (Phase E1)
  * @property {number}                    [heartbeatMs]         per-sink heartbeat interval (Phase E2)
  * @property {number}                    [metricsMs]           per-broadcaster metrics tick (Phase E4)
+ * @property {boolean}                   [healthEvents]        broadcast `stream.health` on each metrics tick (Phase E5; default true)
  * @property {number}                    [maxQueuedPerSink]    bounded queue size (Phase E3)
+ * @property {() => number}              [now]                 injectable clock for `stream.health.at` (tests)
  * @property {(cb: () => void, ms: number) => any} [setTimer]  injectable setInterval (tests)
  * @property {(handle: any) => void}     [clearTimer]          injectable clearInterval (tests)
  */
@@ -66,6 +75,26 @@ import crypto from 'node:crypto';
  * @property {number}                 overflows total `:overflow` drops since last reset
  */
 
+/**
+ * Payload wire-shape for the `stream.health` event (Phase E5). A
+ * point-in-time projection of the broadcaster's own observability
+ * counters, emitted on each metrics tick. `events` carries the
+ * per-event-type broadcast counts accrued during the just-elapsed
+ * interval (reset afterward), so consumers see a per-interval RATE
+ * rather than a monotonic total. `at` is the wall-clock emit time so a
+ * reconnecting client can tell how stale the replayed snapshot is.
+ *
+ * @typedef {object} StreamHealthPayload
+ * @property {Record<string, number>} events     per-event broadcasts during the interval
+ * @property {number}                 sinks      active-sink count at emit time
+ * @property {number}                 overflows  `:overflow` drops during the interval
+ * @property {number}                 intervalMs the metrics-tick cadence that produced this payload
+ * @property {number}                 at         Date.now() at emit time
+ */
+
+/** Event type emitted by the metrics tick (Phase E5). */
+export const STREAM_HEALTH_EVENT = 'stream.health';
+
 const DEFAULT_DEBOUNCE_MS = 100;
 const DEFAULT_HEARTBEAT_MS = 25_000;
 const DEFAULT_METRICS_MS = 60_000;
@@ -104,6 +133,8 @@ export function createHostStream(deps = {}) {
   const defaultDebounceMs = deps.debounceMs?.default ?? DEFAULT_DEBOUNCE_MS;
   const heartbeatMs = deps.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
   const metricsMs = deps.metricsMs ?? DEFAULT_METRICS_MS;
+  const healthEvents = deps.healthEvents ?? true;
+  const now = deps.now ?? (() => Date.now());
   const maxQueuedPerSink = deps.maxQueuedPerSink ?? DEFAULT_MAX_QUEUED;
   const setTimer = deps.setTimer ?? ((cb, ms) => setInterval(cb, ms));
   const clearTimer = deps.clearTimer ?? ((h) => clearInterval(h));
@@ -273,6 +304,27 @@ export function createHostStream(deps = {}) {
     const events = {};
     for (const [type, count] of eventCounters) events[type] = count;
     log(`events=${JSON.stringify(events)} sinks=${sinks.size}${overflowCounter > 0 ? ` overflows=${overflowCounter}` : ''}`);
+
+    // Phase E5: broadcast the same counters as a typed `stream.health`
+    // event so SPA tabs can observe live stream health without polling.
+    // Built from the interval's counters BEFORE the reset below, so the
+    // payload is a per-interval rate. The broadcast itself bumps the
+    // `stream.health` counter, but the immediately-following reset wipes
+    // it — the next interval never double-counts this tick's own emit.
+    // Bypasses debounce (immediate path) since each tick is already
+    // rate-limited to the metrics cadence.
+    if (healthEvents) {
+      /** @type {StreamHealthPayload} */
+      const payload = {
+        events,
+        sinks: sinks.size,
+        overflows: overflowCounter,
+        intervalMs: metricsMs,
+        at: now(),
+      };
+      doBroadcast(STREAM_HEALTH_EVENT, payload);
+    }
+
     eventCounters.clear();
     overflowCounter = 0;
   }