@pleri/olam-cli 0.1.175 → 0.1.182

package/hermes-bundle/version.json

@@ -1,4 +1,4 @@
 {
-  "bundledAt": "2026-05-24T13:03:21.307Z",
+  "bundledAt": "2026-05-26T05:28:12.384Z",
   "kgFirstSha": "29a9ccce1b115d049e375c4a90eb5cf7c123e610e2d0590270a4db2cdbc64a28"
 }

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:71e376df97d498e76c51f35698464b26413bcfe4efe926b85e12248422ae1a54
+          image: ghcr.io/pleri/olam-host-cp@sha256:20d84b6d490c633bc5a158b0f7f849152aba3cf1d2d45657360f627d8d41ec3f
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

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:fe6e1ff20ee99aa2ce74e144d33ebf07411855fc2080ec046ee8a82a6144fb54
+          image: ghcr.io/pleri/olam-auth@sha256:57d5f69395f9d4199035bb1e8156ffa1a4b815e50f6ecef28c2fc082f4d40e23
           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:0300a3140a25510703df52ebeae8a1783e620b93aae7115ef0b3577208eb9b1f
+          image: ghcr.io/pleri/olam-kg-service@sha256:7b48bc20dead674fb01f5e01f1fc43fee2b589c05156a7b5384504f42e96a18a
           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:2a442b17f372eb60b2e1444bb16092157df10ad76b4e87cf6cc8975d386e5be4
+          image: ghcr.io/pleri/olam-mcp-auth@sha256:9cbf2fb4c79a6b447282da5f1a190c730eb9c85e5df1c0c16dc238c34352c583
           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:320298284431afbeebc947a55701f486bc1df0d5642817f68a61147056da9056
+          image: ghcr.io/pleri/olam-memory-service@sha256:d94c6699ca3937f67a873b2b6bb28a1d40317f9c0a780f780f45b41c5d103f2d
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

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

@@ -0,0 +1,58 @@
+// 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 the served SPA's own auth resolver +
+// world-fetch shim handle auth.
+//
+// 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.
+//
+// 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 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
+ * generator for "/plan/<rest>".
+ *
+ * @type {readonly string[]}
+ */
+export const BOOTSTRAP_NOOP_PLANNING_PATHS = Object.freeze([
+  '/plan',
+  '/plan/',
+]);
+
+/**
+ * Phase E5 wildcard: TRUE for every string path.
+ *
+ * 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.
+ *
+ * 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) {
+  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;
   }

package/host-cp/src/plan-chat-service.mjs

@@ -37,6 +37,7 @@ import pg from 'pg';
 import { ensureSecret, timingSafeEqual, SECRET_PATH } from './plan-chat-secret.mjs';
 import { listPlanningSessions } from './planning-sessions.mjs';
 import { crystallizePlanningSession } from './crystallize-planning.mjs';
+import { resolveId, RESOLVE_ID_RE, createRateLimiter } from './resolver.mjs';
 
 const DEFAULT_PORT = 3200;
 const DEFAULT_DB_URL = 'postgres://postgres:spike@localhost:54321/chunks';
@@ -243,6 +244,10 @@ export function createHandler({
    *  so the test harness can inject a hardcoded server-resolved actor_id and verify
    *  the mismatch guard. Production callers omit this. */
   resolveActor,
+  /** Phase A A1 — optional override for tests. When supplied, replaces the
+   *  default per-bearer rate limiter (60 req/min). Tests inject a stub with
+   *  lower capacity to exercise the 429 path quickly. Production callers omit. */
+  rateLimiter,
 }) {
   if (!pool) throw new Error('createHandler: { pool } required');
   if (typeof bearer !== 'string' || bearer.length === 0) {
@@ -258,6 +263,13 @@ export function createHandler({
       ? shapeDebugLog
       : (msg, details) => console.error(msg, details);
 
+  // Phase A A1 — per-bearer rate limiter for /v1/resolve. Single token
+  // bucket keyed by the bearer string; capacity 60, refilled at 60/min.
+  // Closes the brute-force enumeration vector (bearer auth alone keeps
+  // unauthenticated probes out, but an authenticated caller could grind
+  // through ids at line-rate without the bucket).
+  const resolveLimiter = rateLimiter ?? createRateLimiter({ capacity: 60, windowMs: 60_000 });
+
   function checkAuth(req) {
     const header = req.headers.authorization;
     if (typeof header !== 'string' || !header.startsWith('Bearer ')) return false;
@@ -707,6 +719,37 @@ export function createHandler({
     }
   }
 
+  // Phase A A1 (plan-chat-spa-supersedes-control-plane) — resolver
+  // endpoint. Disambiguates :id between planning_sessions.session_id
+  // and planning_artifacts.crystallized_world_id via a single UNION ALL
+  // SQL query (see resolver.mjs). Bearer required (closes K1 SEC-1
+  // enumeration oracle); per-bearer 60 req/min token bucket closes the
+  // authenticated brute-force vector.
+  async function handleGetResolve(req, res, id) {
+    if (!checkAuth(req)) return unauthorized(res);
+
+    // Rate-limit BEFORE shape validation so a flood of invalid ids
+    // still consumes the bucket. Key on the bearer; the bucket is
+    // global to a single-secret service. When A4 adds multi-secret
+    // resolution, this key becomes principal.actorId.
+    const { allowed, retryAfterMs } = resolveLimiter.take(bearer);
+    if (!allowed) {
+      res.setHeader('retry-after', Math.ceil(retryAfterMs / 1000));
+      return send(res, 429, { error: 'rate-limited', message: 'too many requests' });
+    }
+
+    if (!RESOLVE_ID_RE.test(id)) {
+      return badRequest(res, 'id must match [A-Za-z0-9._-]{6,80}');
+    }
+
+    try {
+      const result = await resolveId(pool, id);
+      return send(res, 200, result);
+    } catch (err) {
+      return send(res, 500, { error: 'resolve-failed', message: String(err?.message ?? err) });
+    }
+  }
+
   // H4 (Phase G) — GET + PATCH /v1/artifacts/:id endpoint pair backing
   // the SPA's editor-view round-trip. GET returns the artifact row;
   // PATCH updates body (the JSON payload) + bumps updated_at via trigger.
@@ -776,6 +819,13 @@ export function createHandler({
     if (req.method === 'GET' && url.pathname === '/v1/shape') return handleGetShape(req, res, url);
     if (req.method === 'GET' && url.pathname === '/v1/planning-sessions') return handleGetPlanningSessions(req, res, url);
     if (req.method === 'POST' && url.pathname === '/v1/crystallize') return handlePostCrystallize(req, res);
+    // Phase A A1 — /v1/resolve/:id (plan-chat-spa-supersedes-control-plane).
+    const resolveMatch = /^\/v1\/resolve\/([^/]+)$/.exec(url.pathname);
+    if (resolveMatch && req.method === 'GET') {
+      const id = decodeURIComponent(resolveMatch[1]);
+      return handleGetResolve(req, res, id);
+    }
+
     // H4 — /v1/artifacts/:id pair
     const artifactMatch = /^\/v1\/artifacts\/([^/]+)$/.exec(url.pathname);
     if (artifactMatch) {
@@ -815,6 +865,7 @@ export async function startService(opts = {}) {
     shapeDebug: opts.shapeDebug,
     shapeDebugLog: opts.shapeDebugLog,
     resolveActor: opts.resolveActor,
+    rateLimiter: opts.rateLimiter,
   });
   const server = http.createServer((req, res) => {
     handler(req, res).catch((err) => {