@pleri/olam-cli 0.1.201 → 0.1.205

package/README.md

@@ -1,8 +1,9 @@
 # @pleri/olam-cli
 
-Standalone CLI for [Olam](https://github.com/pleri/olam) — isolated
-development worlds with thought-graph capture, autonomous Build, and
-an MCP server for Claude Code.
+Standalone CLI for [Olam](https://github.com/pleri/olam) — a **cloud-first**
+agent platform: curated skills, persistent agent memory, symbol-aware code
+search, and dispatch of autonomous coding agents to the cloud, all wired into
+Claude Code.
 
 ```sh
 # Install
@@ -13,170 +14,135 @@ curl -fsSL https://olam.bar.dev/install | sh
 olam --version
 ```
 
-The installer publishes from npmjs.org. Requires **Node.js ≥ 20** and
-`npm`. Track the prerelease tag with `OLAM_CHANNEL=canary`.
+Requires **Node.js ≥ 20** and `npm`. Track the prerelease tag with
+`OLAM_CHANNEL=canary`.
 
-## Run modes
+## Cloud-first by default
 
-Olam ships in two substrate-aware run modes. `olam setup` is the canonical fresh-host wizard; it dispatches to the right backend based on `~/.olam/config.json`'s `host.substrate` value (`bootstrap`, `services`, `upgrade`, and `doctor` are all substrate-aware too).
+A fresh install is **cloud mode**: `olam --help` shows only the cloud surface —
+no Docker, k3s, or compose. The four cloud workflows are the default:
 
-| Mode | What runs | When to use | Bring up |
-|---|---|---|---|
-| **K3s** (default) | Full Kubernetes deployment on a local k3d cluster (`host-cp`, `auth-service`, `mcp-auth-service`, `kg-service`, `memory-service`) plus a `monitoring` namespace with kube-prometheus-stack + Loki + Grafana. | Same cluster topology olam runs in cloud/dogfood, ingress routing, observability dashboards, NetworkPolicy isolation. | `olam setup` — on macOS, auto-installs missing brew formulae by default. Guide: [olam.bar.dev/wiki?p=k3s](https://olam.bar.dev/wiki?p=k3s) |
-| **Compose** | 3 host containers (`olam-auth`, `olam-mcp-auth`, `olam-kg-service`) brought up via docker compose. | Lighter setup for hosts that can't run a Kubernetes cluster locally, or for CI. | `olam setup --substrate=docker`. Guide: [olam.bar.dev/wiki?p=setup](https://olam.bar.dev/wiki?p=setup) |
-
-K3s mode requires `k3d`, `kubectl`, `helm`, `gh`, and `docker`. `olam setup` prompts to install missing tools on macOS (via brew) and Linux (via upstream install scripts); pass `-y` to skip all prompts. Full prereq list at [olam.bar.dev/wiki?p=k3s](https://olam.bar.dev/wiki?p=k3s).
-
-## Wire the MCP server into Claude Code
-
-Olam ships an MCP server with `olam_create`, `olam_dispatch`,
-`olam_destroy`, `olam_list`, `olam_status`, `olam_enter`, `olam_pr`,
-`olam_observe`, `olam_lane_*`, and `olam_capture_view`. Three wiring
-paths:
-
-### One command (recommended)
+| Workflow | What it gives you | Wire it up |
+|---|---|---|
+| **Skills** | sync curated skills + agents into `~/.claude` | `olam skills source add` → `sync` → `install-hook` |
+| **Memory** | persistent agent memory across sessions | `olam memory connect <url>` → `install-hooks` |
+| **Knowledge graph** | symbol-aware code search | `olam kg connect <url>` → `install-hook` |
+| **Remote** | plan + dispatch agents on the cloud | `olam remote connect <url>` → `olam dispatch … --executor cloud` |
 
 ```sh
-olam mcp install                  # default --scope=user
-olam mcp install --scope=project  # writes to project .mcp.json
-olam mcp uninstall                # idempotent; symmetric
-```
-
-Auto-detects whether `olam` is on PATH. If so, writes
-`command: "olam"`. Otherwise falls back to
-`command: "npx", args: ["-y", "@pleri/olam-cli", "mcp", "serve"]`.
-
-### Paste-in JSON
-
-Drop into `~/.claude.json` (user scope) or a project's `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "olam": {
-      "command": "npx",
-      "args": ["-y", "@pleri/olam-cli", "mcp", "serve"]
-    }
-  }
-}
+olam setup        # guided cloud-first wizard (no Docker required)
 ```
 
-If `olam` is already on PATH, `command: "olam", args: ["mcp", "serve"]`
-is faster (no `npx` cold-start).
-
-### Marketplace alias
-
-`olam --mcp` is a thin alias for `olam mcp serve`, matching the MCP
-marketplace convention where snippets invoke `npx -y <pkg> --mcp`. The
-two invocations produce identical stdio output.
-
-### Verify
+The CLI ships **no baked-in endpoints** — you supply your team's service URLs.
+Hidden local commands stay fully callable; reveal them any time:
 
 ```sh
-claude mcp list | grep olam
+olam config local-mode     # show the full docker/k3s command surface
+olam config cloud-mode     # back to cloud-first (default)
 ```
 
-Restart Claude Code; the `olam_*` tools surface automatically.
+## One-shot team setup (URLs as args, secrets via GCP IAM)
 
-## Bootstrap the world stack
+The most secure path for a team: **public URLs are args; secret bearers flow
+through a shared GCS bucket gated by GCP IAM** — nothing sensitive touches the
+command line or shell history.
 
 ```sh
-olam bootstrap                  # pull host-cp + auth + devbox; start services; auth login
-olam bootstrap --with-smoke     # also create a smoke-test world
-olam bootstrap --skip-auth-login
-olam bootstrap --registry ghcr.io/pleri
+olam setup \
+  --skills-source=<git-url> \
+  --remote-memory-url=<memory-url> \
+  --remote-kg-url=<kg-url> \
+  --remote-dispatch-url=<dispatch-url> \
+  --credentials=gcp                       # pull bearers from gs://olam-credentials
 ```
 
-What it does (digest-pinned, idempotent, parallel pulls, retries on
-transient failure): see
-[`docs/architecture/bootstrap.md`](https://github.com/pleri/olam/blob/main/docs/architecture/bootstrap.md).
-For the full stack setup, see
-[`docs/onboarding/k3s-mode-setup.md`](https://github.com/pleri/olam/blob/main/docs/onboarding/k3s-mode-setup.md).
+- **Admin (once):** `olam credentials push` uploads the team's bearers to the
+  bucket (auto-created, uniform bucket-level access). Grant teammates
+  `roles/storage.objectViewer`.
+- **Teammate:** `--credentials=gcp` runs `olam credentials pull` — `gcloud`
+  downloads the bearers with the teammate's own ADC and writes them `0600`.
+  Their GCP permission *is* the access gate.
+- **Verify:** `olam remote status` and `olam doctor` (cloud-aware — it probes
+  the four connections, skipping Docker/k8s checks).
 
-State lands under `~/.olam/`:
+`olam credentials status` lists which bearers exist locally.
 
-- `~/.olam/secrets/auth-secret` — shared secret (`0600`) generated on first
-  `auth up`.
-- `~/.olam/worlds/<world-id>/` — per-world worktree + thought DB.
-- `~/.olam/worlds.db` — world registry.
-- `~/.olam/upgrade.log` — JSONL audit log of `olam upgrade`.
+## Wire the MCP server into Claude Code
 
-## Common commands
+Olam ships an MCP server exposing `olam_create`, `olam_dispatch`,
+`olam_destroy`, `olam_list`, `olam_status`, and more.
 
 ```sh
-olam create --name <slug> --task "<one-line goal>"
-olam list
-olam status <world>
-olam enter <world>            # cd into the world's host clone
-olam dispatch <world> "<msg>"
-olam observe <world>          # tail the world's thought stream
-olam pr <world>               # open / inspect the world's PR
-olam destroy <world>
+olam mcp install                  # default --scope=user
+olam mcp install --scope=project  # writes to project .mcp.json
+olam mcp uninstall                # idempotent; symmetric
 ```
 
-Full surface:
+Auto-detects whether `olam` is on PATH (writes `command: "olam"`); otherwise
+falls back to `npx -y @pleri/olam-cli mcp serve`. Paste-in for `~/.claude.json`
+or a project `.mcp.json`:
 
-```sh
-olam --help
-olam <command> --help
+```json
+{
+  "mcpServers": {
+    "olam": { "command": "npx", "args": ["-y", "@pleri/olam-cli", "mcp", "serve"] }
+  }
+}
 ```
 
-## Agentic coding — yolo dispatch
+`olam --mcp` is a thin alias for `olam mcp serve` (MCP marketplace convention).
+Verify with `claude mcp list | grep olam`, then restart Claude Code.
 
-`olam yolo` dispatches a parallel Claude Code session (`--dangerously-skip-permissions`)
-in a new tmux window backed by an isolated git worktree. Each session gets its
-own branch so it can't clobber the operator's main shell.
+## Cloud dispatch
 
 ```sh
-# Spawn a yolo on a bounded task
-olam yolo my-task --branch feat/my-task --prompt-file /tmp/my-task.txt
+olam dispatch <world> "<task>" --executor cloud   # CF Sandbox / plan-DO runner
+```
 
-# List active yolo windows
-olam yolo --list
+`--executor` accepts `docker | do | sandbox | cloud`. With no flag, dispatch
+routes to the cloud when you're in cloud mode **and** a remote is connected;
+otherwise it uses a local Docker world. The chosen route is always printed.
 
-# Clean up after merge
-olam yolo --cleanup my-task
-```
+State lands under `~/.olam/` (all secrets `0600`):
 
-Full reference: `olam yolo --help` and [`docs/runbooks/olam-yolo-cli.md`](../../docs/runbooks/olam-yolo-cli.md).
+- `~/.olam/memory-connection.json`, `~/.olam/kg-proxy-{url,bearer}`,
+  `~/.olam/plan-chat-bearer.json` — the cloud connections.
+- `~/.olam/secrets/` — bearer secrets (the GCS-distributed set).
 
-## Multi-account Claude Code (`--claude-home`)
+## Cloud auth vault
+
+`withCredential` (in `@olam/auth-client`) routes Claude API calls through a
+cloud auth-worker by default — credential rotation + 429 cooldown stay
+server-side. Resolution order:
 
-Inspired by [t3code](https://github.com/pingdotgg/t3code) — one operator,
-many Claude Code instances, each with its own `HOME` env var pointing at
-a separate `~/.claude.instance-N/` directory.
+1. `OLAM_CREDENTIAL_BACKEND=local` → local `olam-auth` container.
+2. `OLAM_CREDENTIAL_BACKEND=remote` → cloud auth-worker.
+3. Auto-discovery via `OLAM_ANTHROPIC_BASE_URL` / `~/.olam/anthropic-base-url`
+   / `~/.olam/cloud-bearer.json`.
 
 ```sh
-olam create my-world --claude-home work-account
-olam create other-world --claude-home personal-account
+olam auth login                # cloud auth-worker (supply your worker URL)
+olam auth login --local        # legacy local container (deprecated)
+olam auth migrate --dry-run    # plan a local → cloud migration
 ```
 
-Each instance gets its own:
+The auth-worker URL is operator-supplied (`--remote <url>`,
+`OLAM_AUTH_WORKER_URL`, or `~/.olam/auth-worker-url`) — there is no baked-in
+default endpoint.
 
-- login (`claude login` is per-`HOME`)
-- hooks (`settings.json` scoped to the per-world Claude home)
-- MCP topology
-- 429 rate-limit bucket
+## Multi-account Claude Code (`--claude-home`)
 
-One-time setup per home:
+One operator, many Claude Code instances, each with its own `HOME` pointing at a
+separate `~/.claude.instance-N/` (login, hooks, MCP topology, and 429 bucket are
+all per-`HOME`):
 
 ```sh
+olam create my-world --claude-home work-account
 HOME="$HOME/.olam/claude-homes/work-account" claude login
-HOME="$HOME/.olam/claude-homes/personal-account" claude login
 ```
 
-The `--claude-home <id>` value is persisted to the world's metadata, so
-`olam enter <world>` and subsequent operations stay bound to the same
-account. Absolute paths are accepted verbatim
-(`--claude-home /opt/shared-claude`).
-
-Composes with `@olam/auth-client`'s vault — the vault still rotates
-credentials **within** a HOME; `--claude-home` isolates **different**
-HOMEs from each other so two worlds on the same host genuinely use
-different accounts without rotation choreography.
-
-See [ADR 045](../../docs/decisions/045-claude-home-override.md) for the
-full rationale + operator workflow.
+The value persists to the world's metadata. See
+[ADR 045](https://github.com/pleri/olam/blob/main/docs/decisions/045-claude-home-override.md).
 
 ## Self-upgrade
 
@@ -186,61 +152,28 @@ olam upgrade -y                 # pull latest digests; restart services
 
 JSONL audit log at `~/.olam/upgrade.log`.
 
-## Cloud-only auth vault (Phase B)
+## Local mode (advanced)
 
-Olam's credential vault ships two migration phases:
-
-**Phase A** (`@olam/auth-client` — already live): `withCredential` selects the
-cloud auth-worker by default. Resolution order:
-1. `OLAM_CREDENTIAL_BACKEND=local` → local `olam-auth` container at `127.0.0.1:9999`.
-2. `OLAM_CREDENTIAL_BACKEND=remote` → cloud auth-worker.
-3. Auto-discovery via `OLAM_ANTHROPIC_BASE_URL` / `~/.olam/anthropic-base-url` / `~/.olam/cloud-bearer.json`.
-4. Hard-coded fallback → cloud auth-worker (`https://auth-worker.kaluga.co`).
-
-**Phase B** (CLI — this package): `olam auth login | list | list-json` default to
-the cloud auth-worker. Operators with an existing local vault can migrate:
+Run the full stack — host control-plane, auth/KG/memory services, and isolated
+Docker/k3s worlds — locally. Reveal the commands first:
 
 ```sh
-# Plan the migration (read-only, no writes)
-olam auth migrate --dry-run
-
-# Run the migration
-olam auth migrate
-
-# Opt out: stay on the local container vault
-olam auth login --local
-olam auth list --local
-OLAM_CREDENTIAL_BACKEND=local olam auth list   # host-wide env override; no deprecation warning
+olam config local-mode
+olam setup --local-mode          # guided local bootstrap (K3s default, or --substrate=docker)
+olam bootstrap                   # pull + start the host stack
+olam create --name <slug> --task "<goal>"
+olam enter <world>               # shell into the world
+olam yolo my-task --branch feat/x --prompt-file /tmp/task.txt
 ```
 
-`--local` emits a deprecation warning. The flag will be removed in a future
-release. `OLAM_CREDENTIAL_BACKEND=local` is the quiet host-wide opt-out.
-
-**Deferred (OQ7):** `olam auth refresh | disable | enable` are LOCAL ONLY pending
-the admin-mutator UX design tracked in
-[`docs/plans/cloud-only-vault/README.md`](https://github.com/pleri/olam/blob/main/docs/plans/cloud-only-vault/README.md).
-
-### `olam doctor` — auth vault health
-
-`olam doctor` reports both backends' health at probe position 4:
-
-```
-✓ auth vault  remote (auth-worker.kaluga.co) healthy (42ms); local (olam-auth:9999) absent
-```
-
-Three remote states: `healthy` / `unreachable` / `unauthenticated`.
-Three local states: `present-active` / `present-stale` / `absent`.
-
-When both backends are present (`remote=healthy` + `local=present-active|present-stale`),
-doctor suggests `olam auth migrate --dry-run` to plan cloud migration.
-
-Full design:
-[`docs/architecture/cloud-only-vault.md`](https://github.com/pleri/olam/blob/main/docs/architecture/cloud-only-vault.md),
-[`docs/plans/cloud-only-vault/README.md`](https://github.com/pleri/olam/blob/main/docs/plans/cloud-only-vault/README.md).
+K3s mode requires `k3d`, `kubectl`, `helm`, `gh`, and `docker`. Full guide:
+[k3s-mode setup](https://github.com/pleri/olam/blob/main/docs/onboarding/k3s-mode-setup.md).
+Local development keeps the three cloud boosts (Skills / Memory / KG) and can
+shift workloads to the cloud at any time.
 
 ## Docs
 
-- [Full README](https://github.com/pleri/olam#readme)
+- [Cloud-first CLI guide](https://github.com/pleri/olam/blob/main/docs/architecture/cloud-first-cli.md)
 - [MCP wiring deep-dive](https://github.com/pleri/olam/blob/main/docs/architecture/mcp-as-npx-served.md)
 - [Architecture index](https://github.com/pleri/olam/tree/main/docs/architecture)
 

package/dist/agent-stream/agent-sdk-to-chunks.js

@@ -233,7 +233,7 @@ export async function streamMultiTurnSdkToChunks(input) {
  * literal per block was pure parameter-passing garbage. Output is identical;
  * only the intermediate allocation is removed.
  */
-function blockToChunkDraft(block, worldId, sessionId, messageId, seq, createdAt) {
+export function blockToChunkDraft(block, worldId, sessionId, messageId, seq, createdAt) {
     if (block.type === 'text') {
         const text = block.text;
         if (!text)

package/dist/agent-stream/driver-runner.js

@@ -38,6 +38,7 @@ import { randomUUID } from 'node:crypto';
 import { makeHostCpChunkPoster, streamMultiTurnSdkToChunks, } from './agent-sdk-to-chunks.js';
 import { subscribeToChunks } from './chunks-subscriber-transport.js';
 import { filterOperatorPickups, pickupConsumedKey, pickupsToPromptPrefix, } from './operator-subscription.js';
+import { makeAskUserQuestionCanUseTool } from './question-broker-bridge.js';
 /**
  * Default `append` text for the Claude Code preset system prompt.
  * Exported so the regression test can assert non-empty + coordinator-shaped
@@ -84,9 +85,19 @@ export const DEFAULT_SYSTEM_PROMPT_APPEND = `You are the driver agent inside an
 export function buildSdkOptions(input) {
     const driverToolsEnabled = process.env.AGENT_DRIVER_TOOLS_ENABLED === '1';
     const baseAllowedTools = [];
-    const allowedTools = input.extraAllowedTools
-        ? [...baseAllowedTools, ...input.extraAllowedTools]
-        : baseAllowedTools;
+    // Phase B (answer-anywhere): AskUserQuestion MUST be in the allowlist whenever
+    // a broker `canUseTool` is wired — otherwise the SDK filters it out of the
+    // Claude Code preset and NEVER invokes it, leaving the canUseTool bridge
+    // dormant (the question-broker-bridge's interceptor only fires when the SDK
+    // actually calls the tool). Gated strictly on `canUseTool` presence so the
+    // no-broker default stays byte-identical (`allowedTools: []`): the snapshot
+    // regression gate + the D10 coordinator-only guards both pass unchanged.
+    const brokerAllowedTools = input.canUseTool ? ['AskUserQuestion'] : [];
+    const allowedTools = [
+        ...baseAllowedTools,
+        ...(input.extraAllowedTools ?? []),
+        ...brokerAllowedTools,
+    ];
     return {
         systemPrompt: {
             type: 'preset',
@@ -95,6 +106,9 @@ export function buildSdkOptions(input) {
         },
         // Empty allowlist = strict coordinator (no tools); undefined = full preset tools.
         ...(driverToolsEnabled ? {} : { allowedTools }),
+        // Question-broker seam (Phase B). Only attached when the caller supplies a
+        // callback — keeps the snapshot stable for the default path.
+        ...(input.canUseTool ? { canUseTool: input.canUseTool } : {}),
         effort: 'low',
         thinking: { type: 'disabled' },
         model: 'claude-sonnet-4-6',
@@ -127,7 +141,7 @@ export function buildSdkOptions(input) {
  *  - The `prompt` is passed through unchanged.
  */
 export function createSdkQuery(query) {
-    return ({ prompt, abortSignal, systemPromptAppend, extraAllowedTools }) => {
+    return ({ prompt, abortSignal, systemPromptAppend, extraAllowedTools, canUseTool }) => {
         // eslint-disable-next-line no-console
         console.error(`[driver] sdkQuery fired (prompt: ${typeof prompt === 'string' ? `${prompt.length} chars` : 'AsyncIterable<SdkUserMessage>'})`);
         // Forward the runDriver-owned abortSignal to a fresh AbortController
@@ -143,7 +157,7 @@ export function createSdkQuery(query) {
                 });
         }
         const options = {
-            ...buildSdkOptions({ systemPromptAppend, extraAllowedTools }),
+            ...buildSdkOptions({ systemPromptAppend, extraAllowedTools, canUseTool }),
             abortController: sdkAbortController,
         };
         return query({ prompt, options });
@@ -156,7 +170,7 @@ export function createSdkQuery(query) {
  * (SIGTERM via the supervisor → the abortSignal here).
  */
 export function runDriver(opts) {
-    const { hostCpUrl, bearer, worldId, sessionId, systemPromptAppend = DEFAULT_SYSTEM_PROMPT_APPEND, extraAllowedTools, sdkQuery, abortSignal: externalSignal, subscribeImpl = subscribeToChunks, postChunkImpl = (url, b) => makeHostCpChunkPoster({ sidecarUrl: url, bearer: b }), } = opts;
+    const { hostCpUrl, bearer, worldId, sessionId, systemPromptAppend = DEFAULT_SYSTEM_PROMPT_APPEND, extraAllowedTools, sdkQuery, allocateMessageId = () => `driver-${randomUUID()}`, canUseTool, abortSignal: externalSignal, subscribeImpl = subscribeToChunks, postChunkImpl = (url, b) => makeHostCpChunkPoster({ sidecarUrl: url, bearer: b }), } = opts;
     const controller = new AbortController();
     if (externalSignal) {
         if (externalSignal.aborted)
@@ -259,12 +273,17 @@ export function runDriver(opts) {
                 abortSignal: signal,
                 systemPromptAppend,
                 extraAllowedTools,
+                // Phase B: route AskUserQuestion through the operator's mobile inbox
+                // when a broker is configured. Conditionally spread so the default
+                // (no-broker) path is byte-identical (createSdkQuery/buildSdkOptions
+                // only attach canUseTool when this is truthy).
+                ...(canUseTool ? { canUseTool } : {}),
             });
             await streamMultiTurnSdkToChunks({
                 messages,
                 worldId,
                 sessionId,
-                allocateMessageId: () => `driver-${randomUUID()}`,
+                allocateMessageId,
                 postChunk,
             });
         }
@@ -304,6 +323,44 @@ export function runDriver(opts) {
         done,
     };
 }
+/**
+ * Build the AskUserQuestion broker `canUseTool` callback from env, when both
+ * broker env vars are present. Returns `undefined` otherwise → the SDK uses its
+ * own local picker (byte-identical, no-broker default).
+ *
+ * Shared by `main()` (in-world supervisor fork) AND `launchHostDriver` (the
+ * host-side planning driver, the production SPA-agent launcher) so the
+ * question-broker seam wires identically at every launch site — no
+ * two-call-site drift (the host path previously omitted the bridge entirely).
+ *
+ *   OLAM_QUESTION_BROKER_URL    — auth-worker origin hosting the per-operator
+ *                                 broker DO (the same path-transport base the
+ *                                 SPA inbox proxy resolves via
+ *                                 resolveBearerBaseUrl).
+ *   OLAM_QUESTION_BROKER_BEARER — operator Anthropic bearer (Basic
+ *                                 b64(sub:secret)); routes register/poll to
+ *                                 idFromName(sub).
+ *
+ * Explicit `brokerUrl`/`brokerBearer` args win over env (test seam); omit them
+ * to read the env vars. `logEnabled` emits the one-line ENABLED breadcrumb only
+ * when the seam actually activates.
+ */
+export function buildBrokerCanUseTool(input) {
+    const brokerUrl = input.brokerUrl ?? process.env.OLAM_QUESTION_BROKER_URL;
+    const brokerBearer = input.brokerBearer ?? process.env.OLAM_QUESTION_BROKER_BEARER;
+    if (!brokerUrl || !brokerBearer)
+        return undefined;
+    if (input.logEnabled) {
+        // eslint-disable-next-line no-console
+        console.error(`[driver] AskUserQuestion broker ENABLED · broker=${brokerUrl}`);
+    }
+    return makeAskUserQuestionCanUseTool({
+        brokerBaseUrl: brokerUrl,
+        bearer: brokerBearer,
+        worldId: input.worldId,
+        sessionId: input.sessionId,
+    });
+}
 /**
  * CLI entry point when this module is run directly (via supervisor fork).
  * Reads env, validates, calls runDriver, installs SIGTERM handler.
@@ -323,6 +380,14 @@ export async function main() {
     const controller = new AbortController();
     process.on('SIGTERM', () => controller.abort());
     process.on('SIGINT', () => controller.abort());
+    // Phase B (mobile-question-inbox): wire the AskUserQuestion broker seam when
+    // a broker is configured. Both env vars must be present; otherwise the seam
+    // stays off and the SDK uses its own local picker (byte-identical default).
+    //   OLAM_QUESTION_BROKER_URL    — the auth-worker origin hosting the broker.
+    //   OLAM_QUESTION_BROKER_BEARER — the operator's Anthropic bearer
+    //                                 (Basic b64(sub:secret)); routes the
+    //                                 register/poll to idFromName(sub).
+    const canUseTool = buildBrokerCanUseTool({ worldId, sessionId, logEnabled: true });
     // eslint-disable-next-line no-console
     console.error(`[driver] starting · world=${worldId} session=${sessionId} ` +
         `hostCp=${hostCpUrl}`);
@@ -336,6 +401,7 @@ export async function main() {
         // operators with legacy supervisor configs.
         systemPromptAppend: process.env.DRIVER_SYSTEM_PROMPT_APPEND ?? process.env.DRIVER_SYSTEM_PROMPT,
         sdkQuery: createSdkQuery(query),
+        canUseTool,
         abortSignal: controller.signal,
     });
     try {

package/dist/agent-stream/host-driver-launch.js

@@ -17,7 +17,7 @@
  * directly with the planning-agent system-prompt-append default.
  */
 import { PLANNING_SYSTEM_PROMPT } from '../prompts/planning-agent.js';
-import { runDriver, } from './driver-runner.js';
+import { runDriver, buildBrokerCanUseTool, } from './driver-runner.js';
 /**
  * Launch a planning-driver in the host process. Delegates everything
  * substantive to `runDriver`; this function only translates the
@@ -42,6 +42,19 @@ export function launchHostDriver(opts) {
         sdkQuery: opts.sdkQuery,
         systemPromptAppend: opts.systemPromptAppend ?? PLANNING_SYSTEM_PROMPT,
         extraAllowedTools: opts.extraAllowedTools ?? PLANNING_DRIVER_EXTRA_ALLOWED_TOOLS,
+        // Phase B (answer-anywhere): wire the AskUserQuestion broker seam from env,
+        // at parity with driver-runner.main(). The host-side launcher previously
+        // omitted canUseTool entirely, so the production SPA-agent path could never
+        // route AskUserQuestion through the operator's inbox. Undefined when no
+        // broker is configured → byte-identical default (SDK local picker).
+        // Cancellation propagates: opts.abortSignal → runDriver signal → the SDK's
+        // options.signal → the bridge's composite abort, so a blocked await never
+        // leaks when the run is aborted.
+        canUseTool: buildBrokerCanUseTool({
+            worldId: opts.worldId,
+            sessionId: opts.sessionId,
+            logEnabled: true,
+        }),
         abortSignal: opts.abortSignal,
     });
 }

package/dist/agent-stream/prototype-gen-launch.js

@@ -0,0 +1,113 @@
+/**
+ * prototype-gen-launch.ts — thin host-side launcher for the prototype-gen
+ * driver (producer plan §6, P3 mechanism — Option B).
+ *
+ * HOST_DRIVER_CONTRACT (inherited from `host-driver-launch.ts`): this module
+ * ONLY overrides the launch path — every agent-logic decision delegates to
+ * `runDriver()` in driver-runner.ts. It defaults `systemPromptAppend` to the
+ * prototype-gen persona, widens `extraAllowedTools` with the prototype tools,
+ * and installs a lineage-pinned `allocateMessageId` so revisions of one
+ * prototype collapse under a single `message_id` (locked Q2 — render side keys
+ * supersession on `message_id`). Adding agent-logic branches here is a
+ * code-smell; extend `DriverRunnerOptions` instead.
+ *
+ * Mirrors `launchHostDriver`: the caller owns SDK construction (`sdkQuery`),
+ * keeping this launcher sync and the SDK import out of the load graph.
+ *
+ * Scope (Option B, smallest blast radius): this is a launcher FUNCTION, not a
+ * dispatch-config schema change. The first-class `olam dispatch --mode
+ * prototype-gen` ergonomics (Option C) + host token pre-ingest/publish are
+ * gated follow-ups (producer plan §6/§7 P3-P4) — this file wires the prompt,
+ * tools, and lineage allocator that those phases build on.
+ *
+ * Producer plan: docs/plans/prototype-gen-producer/plan.md §1, §4, §6, §7.
+ * Prompt spec:   docs/plans/prototype-gen-prompt-spec/plan.md §3, §9.
+ */
+import { makeLineageMessageIdAllocator } from '@olam/core/src/prototype/lineage-message-id-allocator.js';
+import { buildPrototypeGenSystemPrompt } from '../prompts/prototype-gen-agent.js';
+import { PROTOTYPE_GEN_TOOLS } from '../prompts/prototype-gen-agent.js';
+import { runDriver, } from './driver-runner.js';
+/**
+ * The tool patterns the prototype-gen driver adds to the `allowedTools`
+ * allowlist. The agent emits prototypes + style guides via these two tools;
+ * the SDK surfaces them as `tool_use` blocks that the adapter persists as
+ * `prototype` / `style_guide` chunks (zero adapter changes — producer plan §0).
+ *
+ * Derived from `PROTOTYPE_GEN_TOOLS` so the allowlist can never drift from the
+ * tool definitions.
+ */
+export const PROTOTYPE_GEN_EXTRA_ALLOWED_TOOLS = PROTOTYPE_GEN_TOOLS.map((t) => t.name);
+/**
+ * Normalize a prototype title into a lineage key. Lowercase + collapse internal
+ * whitespace + trim, so cosmetic title variation ("Primary CTA button" vs
+ * "primary  cta  button") does not fork a lineage. Per Q-A (operator-gated):
+ * the title keys the lineage WITHIN a single bounded dispatch — collisions are
+ * the operator's own naming, low-stakes — NOT a global identity.
+ */
+export function normalizeLineageKey(title) {
+    return title.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/**
+ * Build a dispatch-scoped lineage allocator. Pure: the only state is the
+ * in-memory title→root map, which lives for the dispatch's lifetime.
+ */
+export function makePrototypeLineageAllocator(options = {}) {
+    const dispatchPrefix = options.dispatchPrefix ?? `proto-${Math.random().toString(36).slice(2) || '0'}`;
+    const nonceSource = options.nonceSource ?? (() => Math.random().toString(36).slice(2) || '0');
+    const clock = options.clock ?? (() => Date.now());
+    // lineageKey → lineageRoot. Same title reuses the recorded root; a new title
+    // mints a fresh one via the core per-lineage allocator.
+    const lineages = new Map();
+    let untitledCounter = 0;
+    function mintRoot(seed) {
+        // Anchor a core allocator at a dispatch-unique seed and take its lineageRoot
+        // for the per-revision messageId structure. We use the allocator's
+        // `lineageRoot` (stable) as the chunk message_id per the core contract.
+        const anchor = `${dispatchPrefix}-${seed}-${clock()}-${nonceSource()}`;
+        return makeLineageMessageIdAllocator(anchor, { clock, nonceSource }).allocate()
+            .lineageRoot;
+    }
+    return {
+        resolveForTitle(title) {
+            const key = normalizeLineageKey(title);
+            const existing = lineages.get(key);
+            if (existing !== undefined)
+                return existing;
+            const root = mintRoot(key || `untitled-${untitledCounter++}`);
+            lineages.set(key, root);
+            return root;
+        },
+        allocate() {
+            return mintRoot(`turn-${untitledCounter++}`);
+        },
+    };
+}
+/**
+ * Launch a prototype-gen driver in the host process. Delegates everything
+ * substantive to `runDriver`; this function only:
+ *   1. defaults `systemPromptAppend` to the guide-pinned prototype-gen persona,
+ *   2. widens `extraAllowedTools` with the prototype + style_guide tools,
+ *   3. installs a lineage-pinned `allocateMessageId` (Q2 mechanism).
+ *
+ * The host token pre-ingest + `style_guide` chunk publish (producer plan
+ * §3.2-A) is a gated P3 responsibility layered ABOVE this launcher — it runs
+ * before the call so the prompt-pinned guide id resolves on the agent's first
+ * `prototype` emission.
+ */
+export function launchPrototypeGenDriver(opts) {
+    const systemPromptAppend = opts.systemPromptAppend ??
+        buildPrototypeGenSystemPrompt(opts.styleGuideId, opts.styleGuideVersion);
+    const allocateMessageId = opts.allocateMessageId ?? makePrototypeLineageAllocator().allocate;
+    return runDriver({
+        worldId: opts.worldId,
+        sessionId: opts.sessionId,
+        hostCpUrl: opts.hostCpUrl,
+        bearer: opts.bearer,
+        sdkQuery: opts.sdkQuery,
+        systemPromptAppend,
+        extraAllowedTools: opts.extraAllowedTools ?? PROTOTYPE_GEN_EXTRA_ALLOWED_TOOLS,
+        allocateMessageId,
+        abortSignal: opts.abortSignal,
+    });
+}
+//# sourceMappingURL=prototype-gen-launch.js.map