@pleri/olam-cli 0.1.201 → 0.1.204

package/hermes-bundle/version.json

@@ -1,4 +1,4 @@
 {
-  "bundledAt": "2026-05-29T18:19:49.024Z",
+  "bundledAt": "2026-06-02T05:18:01.119Z",
   "kgFirstSha": "29a9ccce1b115d049e375c4a90eb5cf7c123e610e2d0590270a4db2cdbc64a28"
 }

package/hooks/__tests__/_loader.py

@@ -0,0 +1,26 @@
+"""Loads the hyphenated `model-router.py` hook as an importable module.
+
+The hook ships as `packages/cli/hooks/model-router.py` (hyphenated to match
+the operator-local `~/.claude/hooks/` filename convention). A hyphen is not a
+legal module-name char, so a plain `import` cannot reach it. Load it by path.
+
+Stdlib-only so the tests run under either `pytest` (CI / the kg-service
+Docker image) or a bare `python3 -m unittest` on any host — no third-party
+dependency, fully offline.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+_HOOK_PATH = Path(__file__).resolve().parent.parent / "model-router.py"
+
+
+def load_model_router() -> ModuleType:
+    spec = importlib.util.spec_from_file_location("model_router_hook", _HOOK_PATH)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module

package/hooks/__tests__/prompts.py

@@ -0,0 +1,63 @@
+"""Representative prompt corpus for the model-router classifier.
+
+Reflects real `UserPromptSubmit` shapes across the tier spectrum:
+short one-liners, long multi-sentence asks, code-heavy transforms,
+multi-domain (auth/payment/migration/security) prose, and the bulk /
+bounded / negation edge cases the v2 scorer explicitly handles.
+
+Used by BOTH the correctness pin (`test_classify_pins.py`) and the
+benchmark (`test_classify_bench.py`) so the numbers and the
+behaviour-lock cover the same inputs.
+"""
+
+from __future__ import annotations
+
+# Each entry exercises a distinct branch of the classifier. The corpus is
+# deliberately spread across cheap / main / hard so the benchmark's mean is
+# representative of mixed real traffic, not skewed to one fast/slow path.
+PROMPTS: list[str] = [
+    # ── short ──────────────────────────────────────────────────────────
+    "rename foo to bar",
+    "format this file",
+    "add a flag to the dispatch path",
+    "investigate the flaky test",
+    "what's the signature of withCredential",
+    # ── cheap mechanical / bulk ─────────────────────────────────────────
+    "Across the whole codebase, replace every console.log with the logger "
+    "and strip all trailing whitespace — purely mechanical, no logic changes.",
+    "Add jsdoc to every exported function in packages/core/src and add "
+    "explicit return types where missing. One-line change per file.",
+    "prettier --write the entire repo and run eslint --fix afterwards",
+    "convert every require() to an ESM import across all the test files",
+    "bump every internal package.json dependency to the latest minor",
+    # ── main bounded feature work ──────────────────────────────────────
+    "Add an endpoint to host-cp that returns the current world phase, and "
+    "wire a debounce on the SPA hook that consumes it. Just this one file.",
+    "Fix the bug in tier-selection where the fallback reason is undefined; "
+    "add a regression test that pins the fallback branch.",
+    "Add a feature flag check to the dispatch enrichment path in a single "
+    "file and gate the new badge behind it.",
+    # ── hard architecture / cross-service ──────────────────────────────
+    "Design a backwards-compatible migration to shard the credential vault "
+    "across every auth service with zero-downtime cutover; we're paged on "
+    "p99 latency spikes and pool exhaustion under 50K RPS.",
+    "Investigate the cross-service race condition causing the audit-log "
+    "desync; propose a unified idempotency layer and a deprecation rollout "
+    "across all 12 microservices. This is operationally serious.",
+    "Refactor the cross-cutting retry logic across every service into a "
+    "unified middleware; audit all the call sites and plan the migration.",
+    # ── negation / bounded-scope traps ─────────────────────────────────
+    "I know this looks like an architecture change but it's really just a "
+    "rename — don't redesign anything, preserve behaviour exactly.",
+    "Investigate this specific test in `packages/core/src/dispatch/"
+    "verifiability.test.ts` — single file, no design decisions needed.",
+    # ── multi-domain prose ─────────────────────────────────────────────
+    "The payment refund flow leaks a credential into the audit log on a "
+    "stripe webhook retry — this is a security + billing issue, trace it.",
+    # ── long mixed ─────────────────────────────────────────────────────
+    "We need to standardise the error contract across the gateway and "
+    "migrate every public endpoint to it. There's a data-residency "
+    "constraint for EU tenants and a SOC2 audit-log requirement. Propose a "
+    "rollout that's backwards-compatible and won't desync the SDK bindings "
+    "going forward. Bundle is 1.8MB gzipped so watch the cdn/origin split.",
+]

package/hooks/__tests__/test_classify_bench.py

@@ -0,0 +1,94 @@
+"""Hot-path benchmark for the model-router classifier.
+
+`classify()` runs on EVERY operator `UserPromptSubmit` (the
+`[model-router] tier=… scores=(cheap=N,main=N,hard=N)` line). It is the
+hottest per-prompt code path in the harness, so even microseconds compound
+across sessions.
+
+Perf-as-test style (mirrors `packages/kg-service/tests/` — stdlib only, no
+pytest-benchmark dependency). Prints a hard number (classifications/sec,
+µs/call mean, p95) and asserts a loose ceiling so a future regression that
+makes the hot path materially slower fails CI rather than silently shipping.
+
+The ceiling is deliberately generous (1500 µs/call mean over the mixed
+corpus on a cold box) — it guards against ORDER-OF-MAGNITUDE regressions
+(e.g. accidentally recompiling regexes inside the per-rule loop), not
+micro-jitter.
+
+Runs under pytest (CI) OR `python3 -m unittest` (offline). Either way the
+numbers print to stdout.
+"""
+
+from __future__ import annotations
+
+import statistics
+import sys
+import time
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _loader import load_model_router  # noqa: E402
+from prompts import PROMPTS  # noqa: E402
+
+# Mean-per-call ceiling. Generous: catches a 5-10x regression, ignores jitter.
+MAX_MEAN_US_PER_CALL = 1500.0
+
+_WARMUP_ROUNDS = 50
+_MEASURE_ROUNDS = 400
+
+
+def measure(classify) -> dict[str, float]:
+    # Warm the re-cache + interpreter so first-call compile cost doesn't skew
+    # the mean (we measure steady-state per-prompt cost).
+    for _ in range(_WARMUP_ROUNDS):
+        for p in PROMPTS:
+            classify(p)
+
+    per_call_us: list[float] = []
+    t_start = time.perf_counter()
+    for _ in range(_MEASURE_ROUNDS):
+        for p in PROMPTS:
+            t0 = time.perf_counter()
+            classify(p)
+            per_call_us.append((time.perf_counter() - t0) * 1e6)
+    wall = time.perf_counter() - t_start
+
+    n = len(per_call_us)
+    per_call_us.sort()
+    return {
+        "calls": float(n),
+        "classifications_per_sec": n / wall,
+        "us_per_call_mean": statistics.mean(per_call_us),
+        "us_per_call_median": statistics.median(per_call_us),
+        "us_per_call_p95": per_call_us[int(n * 0.95)],
+    }
+
+
+class TestClassifyBench(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.mr = load_model_router()
+
+    def test_classify_throughput(self) -> None:
+        stats = measure(self.mr.classify)
+        print(
+            "\n[model-router classify bench]"
+            f"\n  corpus prompts : {len(PROMPTS)}"
+            f"\n  total calls    : {int(stats['calls'])}"
+            f"\n  throughput     : {stats['classifications_per_sec']:,.0f} classifications/sec"
+            f"\n  µs/call mean   : {stats['us_per_call_mean']:.2f}"
+            f"\n  µs/call median : {stats['us_per_call_median']:.2f}"
+            f"\n  µs/call p95    : {stats['us_per_call_p95']:.2f}"
+        )
+        self.assertLess(
+            stats["us_per_call_mean"],
+            MAX_MEAN_US_PER_CALL,
+            f"classify mean {stats['us_per_call_mean']:.1f}µs/call exceeded "
+            f"ceiling {MAX_MEAN_US_PER_CALL}µs — hot-path regression?",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/hooks/__tests__/test_classify_pins.py

@@ -0,0 +1,78 @@
+"""Behaviour-lock for the model-router classifier.
+
+Pins `classify()`'s (tier, scores) output for every prompt in the
+representative corpus. ANY change to the scoring rules, modifiers, or
+decision logic that moves a tier or a score fails here — so a future
+"optimization" that silently alters behaviour is caught.
+
+This is the contract the perf work in this PR preserves: the hot-path
+regex-precompile change MUST leave every one of these golden values
+byte-identical.
+
+Runs under pytest (CI) OR `python3 -m unittest` (offline, no deps).
+"""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _loader import load_model_router  # noqa: E402
+from prompts import PROMPTS  # noqa: E402
+
+# Golden snapshot captured from the classifier BEFORE the precompile change.
+# (tier, {"cheap": int, "main": int, "hard": int}) — one per PROMPTS entry,
+# same order. Regenerate ONLY with an intentional, reviewed behaviour change.
+GOLDEN: list[tuple[str, dict[str, int]]] = [
+    ("cheap", {"cheap": 5, "main": 0, "hard": 0}),
+    ("cheap", {"cheap": 4, "main": 0, "hard": 0}),
+    ("main", {"cheap": 0, "main": 5, "hard": 0}),
+    ("hard", {"cheap": 0, "main": 0, "hard": 4}),
+    ("main", {"cheap": 0, "main": 0, "hard": 0}),
+    ("cheap", {"cheap": 22, "main": 0, "hard": 5}),
+    ("cheap", {"cheap": 29, "main": 0, "hard": 0}),
+    ("cheap", {"cheap": 18, "main": 0, "hard": 0}),
+    ("cheap", {"cheap": 8, "main": 0, "hard": 0}),
+    ("cheap", {"cheap": 8, "main": 0, "hard": 0}),
+    ("main", {"cheap": 0, "main": 5, "hard": 0}),
+    ("main", {"cheap": 0, "main": 0, "hard": 0}),
+    ("main", {"cheap": 0, "main": 5, "hard": 0}),
+    ("hard", {"cheap": 0, "main": 0, "hard": 43}),
+    ("hard", {"cheap": 0, "main": 0, "hard": 39}),
+    ("hard", {"cheap": 0, "main": 0, "hard": 31}),
+    ("cheap", {"cheap": 13, "main": 0, "hard": 0}),
+    ("main", {"cheap": 0, "main": 4, "hard": 0}),
+    ("hard", {"cheap": 0, "main": 0, "hard": 6}),
+    ("hard", {"cheap": 8, "main": 0, "hard": 37}),
+]
+
+
+class TestClassifyPins(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.mr = load_model_router()
+
+    def test_corpus_and_golden_aligned(self) -> None:
+        self.assertEqual(
+            len(GOLDEN), len(PROMPTS), "one GOLDEN entry per PROMPTS entry"
+        )
+
+    def test_classify_output_is_pinned(self) -> None:
+        for prompt, (want_tier, want_scores) in zip(PROMPTS, GOLDEN):
+            tier, scores, _triggered = self.mr.classify(prompt)
+            self.assertEqual(tier, want_tier, f"tier drift: {prompt[:60]!r}")
+            self.assertEqual(scores, want_scores, f"score drift: {prompt[:60]!r}")
+
+    def test_classify_is_deterministic(self) -> None:
+        for prompt in PROMPTS:
+            first = self.mr.classify(prompt)
+            second = self.mr.classify(prompt)
+            self.assertEqual(first[0], second[0])
+            self.assertEqual(first[1], second[1])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/hooks/model-router.py

@@ -179,6 +179,15 @@ RULES = [
     ("hard", 4, r"\bevery\s+pii\b"),
 ]
 
+# Pre-compiled view of RULES, built ONCE at import time. `classify()` runs on
+# every operator prompt (the hottest per-prompt path in the harness), so the
+# ~150 per-rule regex evaluations must not re-resolve the (pattern, flags)
+# pair through `re`'s internal cache on every call. Compiling up front and
+# iterating the pattern objects directly is behaviour-identical to
+# `re.finditer(pat, text, re.IGNORECASE)` but skips the per-call cache lookup.
+# RULES stays the readable source of truth; this is its compiled mirror.
+COMPILED_RULES = [(tier, weight, re.compile(pat, re.IGNORECASE)) for tier, weight, pat in RULES]
+
 # Bulk indicators — if present alongside a cheap-verb match, boost CHEAP.
 BULK_INDICATORS = re.compile(
     r"\b(?:every|all|each|whole|entire|across\s+(?:our\s+)?(?:the\s+)?"
@@ -231,8 +240,8 @@ NEGATION = re.compile(
 
 def collect_matches(prompt):
     matches = []  # (tier, weight, regex, span_text, start_idx)
-    for tier, weight, regex in RULES:
-        for m in re.finditer(regex, prompt, re.IGNORECASE):
+    for tier, weight, regex in COMPILED_RULES:
+        for m in regex.finditer(prompt):
             matches.append((tier, weight, regex, m.group(0), m.start()))
     return matches
 
@@ -384,6 +393,10 @@ DOMAIN_FLAGS = {
     "security": r"\b(?:security|vulnerability|cve|xss|sqli|injection|exploit|secret\s+leak)\b",
 }
 
+# Pre-compiled once at import time — same per-prompt-path rationale as
+# COMPILED_RULES (these fire on every prompt in `main()`).
+COMPILED_DOMAIN_FLAGS = {name: re.compile(pat, re.IGNORECASE) for name, pat in DOMAIN_FLAGS.items()}
+
 
 def emit_log(record):
     try:
@@ -406,8 +419,8 @@ def main():
 
     tier, scores, triggered = classify(prompt)
     flags = [
-        name for name, pat in DOMAIN_FLAGS.items()
-        if re.search(pat, prompt, re.IGNORECASE)
+        name for name, pat in COMPILED_DOMAIN_FLAGS.items()
+        if pat.search(prompt)
     ]
     word_count = len(prompt.split())
 

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:3c601e4ea81d49e0c494c132dbf34aeffffedf37f9f09d4877b0d3139341bc50
+          image: ghcr.io/pleri/olam-host-cp@sha256:a92c2849bdacd77c1a5dec59c45377af9fd4c76b10da98482e4cd4d59ca7cb33
           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:3f46d206ae15e4cdad15adeaf2e0f0da8367a3292f3c9e80f7e1a12b4d73580b
+          image: ghcr.io/pleri/olam-auth@sha256:b8165709ae12fe6b84a6e61cf935715af75a141835b7e452f5b80c1d98ced062
           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:47f6a594ef402b92032560afd8e6ed4758223d8c8d09f24ede8eff436dc3a31a
+          image: ghcr.io/pleri/olam-kg-service@sha256:e1f3c74e5b8f7e22b1b093ababd16fba59dd973040fa1d7040c81858a3382c66
           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:a97684d8d69922d4ce35af45700e15973a7463f088516a4383b6b6022bc37a16
+          image: ghcr.io/pleri/olam-mcp-auth@sha256:0322f58514626ff0c45ced3a7711d03d5bd2d2ec158de46a396531920a15c49b
           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:6bfa2209ff735728457e155031c526008acd53276f2026ffa95905a301e414bb
+          image: ghcr.io/pleri/olam-memory-service@sha256:a9ede246fc89ad7c47c938400f544f677e92e8f6a3addf49e585f0f314b2c133
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/src/op-side-longpoll.mjs

@@ -0,0 +1,212 @@
+/**
+ * op-side-longpoll.mjs — Operator-side long-poll loop.
+ *
+ * Maintains a persistent outbound HTTPS connection from host-cp to
+ * plan-DO's /v1/op-poll endpoint, waiting for local-Docker dispatch
+ * work to appear. Feature-flag-gated behind OLAM_OPSIDE_LONGPOLL=1
+ * (default OFF — no behavior change when unset).
+ *
+ * ELI5: like installing a phone line to the cloud planner.
+ * Your local machine stays connected, ready to receive coding tasks.
+ * Nothing calls yet — the phone just sits there waiting (v1).
+ *
+ * Phase D ships the plumbing and tests it behind a flag. Future cells
+ * (#3/#6/#7) wire actual producers on the plan-DO side.
+ *
+ * Circuit-breaker: 10 consecutive errors → 60 s pause →
+ * counter resets and polling resumes. Prevents hammering the server
+ * during outages.
+ *
+ * Reconnect delay: 1000ms base + uniform 0-500ms jitter.
+ * All structured log events emitted to console via JSON objects.
+ *
+ * @module op-side-longpoll
+ */
+
+// Reconnect delay constants.
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_JITTER_MS = 500;
+
+// Circuit-breaker constants.
+const CIRCUIT_BREAKER_THRESHOLD = 10;
+const CIRCUIT_BREAKER_PAUSE_MS = 60_000;
+
+// Long-poll timeout — plan-DO blocks up to 25 s; we give a 5 s margin.
+const POLL_TIMEOUT_MS = 30_000;
+
+/**
+ * Compute reconnect delay: 1000 + uniform 0-500 ms jitter.
+ * Exported so tests can mock Math.random and assert the formula.
+ *
+ * @param {() => number} [randFn] - Optional RNG override for testing.
+ * @returns {number} Delay in milliseconds.
+ */
+export function reconnectDelay(randFn = Math.random) {
+  return RECONNECT_BASE_MS + Math.floor(randFn() * RECONNECT_JITTER_MS);
+}
+
+/** @type {ReturnType<typeof setTimeout> | null} */
+let pollTimer = null;
+
+/** @type {boolean} */
+let running = false;
+
+/** @type {number} */
+let consecutiveErrors = 0;
+
+/** @type {string | null} */
+let activeCloudUrl = null;
+
+/** @type {string | null} */
+let activeAuth = null;
+
+/**
+ * Emit a structured log event. Uses console.log to be consistent with
+ * host-cp's existing logging style. All events include `event` + `ts`.
+ *
+ * @param {string} event
+ * @param {Record<string, unknown>} [extra]
+ */
+function emit(event, extra = {}) {
+  console.log(JSON.stringify({ event, ts: new Date().toISOString(), ...extra }));
+}
+
+/**
+ * Sleep for ms milliseconds. Returns a Promise that resolves after the
+ * delay. Cancellable via the token: if token.cancelled becomes true
+ * before the timeout fires, the promise still resolves (callers check
+ * running themselves).
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    pollTimer = setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Single poll iteration: open a GET /v1/op-poll request, wait for
+ * a response, parse the JSON body.
+ *
+ * @param {string} cloudUrl Base URL (e.g. https://plan-do.example.com)
+ * @param {string} auth Authorization header value
+ * @returns {Promise<{ work: null | { worldId: string, dispatchSpec: unknown } }>}
+ */
+async function pollOnce(cloudUrl, auth) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), POLL_TIMEOUT_MS);
+
+  try {
+    const url = `${cloudUrl.replace(/\/$/, '')}/v1/op-poll`;
+    const res = await fetch(url, {
+      method: 'GET',
+      headers: { Authorization: auth },
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      throw new Error(`op-poll returned ${res.status}`);
+    }
+
+    const body = await res.json();
+    return body;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * The main poll loop. Runs until stopPoll() is called.
+ *
+ * State transitions:
+ *   idle
+ *   → connecting (emit op-poll-connect)
+ *   → got { work: null } timeout response (emit op-poll-timeout)
+ *   → wait reconnect delay
+ *   → connecting again
+ *
+ * On error:
+ *   → consecutiveErrors++
+ *   → emit op-poll-error
+ *   → if consecutiveErrors >= threshold: circuit-breaker open
+ *       emit op-poll-circuit-open, wait 60 s, reset counter
+ *   → else: wait reconnect delay
+ *
+ * @returns {Promise<void>}
+ */
+async function pollLoop() {
+  while (running) {
+    emit('op-poll-connect', { cloud_url: activeCloudUrl });
+
+    try {
+      const result = await pollOnce(activeCloudUrl, activeAuth);
+
+      // On a successful { work: null } response, reset the error counter.
+      consecutiveErrors = 0;
+
+      const delay = reconnectDelay();
+      emit('op-poll-timeout', { work: result.work, reconnect_in_ms: delay });
+
+      if (!running) break;
+      await sleep(delay);
+    } catch (err) {
+      consecutiveErrors++;
+      const message = err instanceof Error ? err.message : String(err);
+
+      emit('op-poll-error', {
+        error: message,
+        consecutive_errors: consecutiveErrors,
+      });
+
+      if (consecutiveErrors >= CIRCUIT_BREAKER_THRESHOLD) {
+        emit('op-poll-circuit-open', {
+          consecutive_errors: consecutiveErrors,
+          pause_ms: CIRCUIT_BREAKER_PAUSE_MS,
+        });
+        consecutiveErrors = 0;
+        if (!running) break;
+        await sleep(CIRCUIT_BREAKER_PAUSE_MS);
+      } else {
+        if (!running) break;
+        const delay = reconnectDelay();
+        await sleep(delay);
+      }
+    }
+  }
+}
+
+/**
+ * Start the operator-side long-poll loop.
+ *
+ * No-op if already running. Reads the flag from the environment:
+ * only runs when OLAM_OPSIDE_LONGPOLL === '1'. Call this AFTER
+ * server.listen() to avoid blocking the process startup path.
+ *
+ * @param {string} cloudUrl Base URL of the plan-DO deployment.
+ * @param {string} auth Authorization header value for Basic auth.
+ */
+export function startPoll(cloudUrl, auth) {
+  if (running) return;
+  running = true;
+  consecutiveErrors = 0;
+  activeCloudUrl = cloudUrl;
+  activeAuth = auth;
+  // Fire-and-forget; errors are caught inside pollLoop.
+  void pollLoop();
+}
+
+/**
+ * Stop the operator-side long-poll loop.
+ *
+ * Cancels any in-progress sleep timer; the loop condition will
+ * exit on its next iteration. Idempotent.
+ */
+export function stopPoll() {
+  running = false;
+  if (pollTimer !== null) {
+    clearTimeout(pollTimer);
+    pollTimer = null;
+  }
+}

package/host-cp/src/plan-chat-proxy-headers.mjs

@@ -0,0 +1,53 @@
+// plan-chat-proxy-headers.mjs — header handling for host-cp's /api/plan-chat/*
+// passthrough proxy (server.mjs). Extracted as pure helpers so the F3 (T9)
+// operator-chunk broker-secret contract is unit-testable without booting the
+// whole host-cp server.
+//
+// F3 (T9) boundary: host-cp's /api/plan-chat/* proxy is the TRUSTED operator
+// surface (SPA browser → host-cp → plan-chat-service). A WORLD process never
+// routes through this proxy — it talks to plan-chat-service directly via
+// host.docker.internal. So:
+//   - Client-supplied `x-olam-broker-secret` is ALWAYS stripped (a client must
+//     not be able to smuggle the operator-chunk authority secret through).
+//   - The real secret is injected by the proxy itself (injectBrokerSecret),
+//     only when configured, so the operator's own SPA interject is authorised
+//     while a world process — which can't present the secret — is rejected by
+//     plan-chat-service's gate.
+
+const HOP_BY_HOP = new Set(['host', 'connection', 'content-length']);
+const BROKER_SECRET_HEADER = 'x-olam-broker-secret';
+
+/**
+ * Build the upstream header map for a /api/plan-chat/* proxy request.
+ * Drops hop-by-hop headers AND any client-supplied broker secret (F3).
+ *
+ * @param {Record<string, string | string[] | undefined>} reqHeaders
+ * @returns {Record<string, string>}
+ */
+export function buildPlanChatProxyHeaders(reqHeaders) {
+  const headers = {};
+  for (const [k, v] of Object.entries(reqHeaders ?? {})) {
+    if (HOP_BY_HOP.has(k)) continue;
+    // F3 — never forward a CLIENT-supplied broker secret.
+    if (k === BROKER_SECRET_HEADER) continue;
+    if (Array.isArray(v)) headers[k] = v.join(', ');
+    else if (typeof v === 'string') headers[k] = v;
+  }
+  return headers;
+}
+
+/**
+ * Inject the operator-chunk broker secret into the upstream headers when it is
+ * configured. No-op when the secret is unset/empty (the gate then runs in its
+ * default ungated-but-loud mode). Mutates + returns `headers`.
+ *
+ * @param {Record<string, string>} headers
+ * @param {string | undefined} operatorChunkSecret
+ * @returns {Record<string, string>}
+ */
+export function injectBrokerSecret(headers, operatorChunkSecret) {
+  if (typeof operatorChunkSecret === 'string' && operatorChunkSecret.length > 0) {
+    headers[BROKER_SECRET_HEADER] = operatorChunkSecret;
+  }
+  return headers;
+}