@pleri/olam-cli 0.1.142 → 0.1.144

package/dist/mcp-server.js

@@ -5,16 +5,10 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
-var __commonJS = (cb, mod) => function __require2() {
+var __commonJS = (cb, mod) => function __require() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
 var __export = (target, all) => {
@@ -31334,19 +31328,26 @@ function defaultUrl(flavor) {
 function buildHookCommand(opts) {
   const url2 = opts.url ?? defaultUrl(opts.flavor);
   const extractCmd = `python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('tool_input',d).get('command',''))" 2>/dev/null`;
-  const emitContext = `python3 -c 'import json,sys
+  const emitContext = `python3 -c 'import json,sys,os
 try:
   d=json.loads(sys.stdin.read())
   if d.get("route") and d["route"] != "grep":
     label=d.get("top_match") or d.get("reason","")
-    print(json.dumps({"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":f"[kg-classifier L{d.get(\\"layer\\",\\"?\\")}|{d[\\"route\\"]}] {label[:160]}"}}))
+    layer=d.get("layer","?")
+    route=d["route"]
+    nodes=d.get("nodes_matched",0)
+    saved=(d.get("savings") or {}).get("saved_tokens_est",0)
+    saved_k=round(saved/1000)
+    q=os.environ.get("KG_QUERY","")[:60]
+    sys.stderr.write(f"\\x1b[32m\\u2713 KG hit\\x1b[0m  \\"{q}\\"  \\u2192  L{layer}/{route} \\u00b7 {nodes} nodes \\u00b7 ~{saved_k}k tokens saved\\n")
+    print(json.dumps({"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":f"[kg-classifier L{layer}|{route}] {label[:160]}"}}))
 except Exception: pass' 2>/dev/null`;
+  const curlPost = `RESP=$(curl -s --max-time 1 -X POST -H 'Content-Type: application/json' -d "{\\"q\\":\\"$(echo \\"$CMD\\" | head -c 200 | tr '\\"' ' ')\\"}" ${url2} 2>/dev/null)`;
   return [
     `KG_SENTINEL=${KG_HOOK_SENTINEL}`,
     `CMD=$(${extractCmd})`,
-    `case "$CMD" in *grep*|*rg\\ *|*ripgrep*|*find\\ *|*fd\\ *|*ack\\ *|*ag\\ *)`,
-    `RESP=$(curl -s --max-time 1 -X POST -H 'Content-Type: application/json' -d "{\\"q\\":\\"$(echo \\"$CMD\\" | head -c 200 | tr '\\"' ' ')\\"}" ${url2} 2>/dev/null)`,
-    `echo "$RESP" | ${emitContext}`,
+    `case "$CMD" in *grep*|*rg\\ *|*ripgrep*|*find\\ *|*fd\\ *|*ack\\ *|*ag\\ *) ${curlPost}`,
+    `KG_QUERY="$(echo \\"$CMD\\" | head -c 60 | tr '\\"' ' ')" echo "$RESP" | ${emitContext}`,
     `;; esac`
   ].join("; ");
 }
@@ -32300,7 +32301,7 @@ function carryUncommittedEdits(repos, workspacePath, deps = {}) {
   const exec = deps.exec ?? ((cmd, args, opts) => execFileSync4(cmd, args, opts));
   const homedir18 = deps.homedir ?? (() => os12.homedir());
   const existsSync27 = deps.existsSync ?? ((p) => fs19.existsSync(p));
-  const copyFileSync7 = deps.copyFileSync ?? ((src, dest) => fs19.copyFileSync(src, dest));
+  const copyFileSync6 = deps.copyFileSync ?? ((src, dest) => fs19.copyFileSync(src, dest));
   const mkdirSync18 = deps.mkdirSync ?? ((dirPath, opts) => {
     fs19.mkdirSync(dirPath, opts);
   });
@@ -32376,7 +32377,7 @@ function carryUncommittedEdits(repos, workspacePath, deps = {}) {
         continue;
       try {
         mkdirSync18(path21.dirname(dest), { recursive: true });
-        copyFileSync7(src, dest);
+        copyFileSync6(src, dest);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.warn(`[carry] ${plan.name}: copy untracked ${rel} failed: ${msg}`);
@@ -32403,123 +32404,96 @@ function formatBaselineSummary(result) {
 // ../core/dist/world/context-injection.js
 import * as fs20 from "node:fs";
 import * as path22 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-var TEMPLATES_DIR = fileURLToPath2(new URL("./templates", import.meta.url));
+
+// ../core/dist/world/templates/_generated.js
+var GH_PR_CREATE = '# Creating PRs from inside an Olam world\n\n## The problem\n\nCalling `gh pr create` directly inside an Olam container **hangs forever** on a\nTTY confirmation prompt that the agent cannot answer. This is a known, reproduced issue.\n\n## The fix\n\nAlways use this exact pattern:\n\n```bash\necho y | timeout 30 gh pr create \\\n  --base main \\\n  --head <branch> \\\n  --title "<title>" \\\n  --body-file /tmp/pr-body.md\n```\n\n## Why each part matters\n\n- **`echo y |`** \u2014 answers the "Submit?" confirmation prompt up front so `gh` never pauses.\n- **`timeout 30`** \u2014 hard deadline. If `gh` hangs anyway, the command exits non-zero so the\n  agent can react instead of stalling the world indefinitely.\n- **`--body-file /tmp/pr-body.md`** \u2014 write the PR body to a temp file first. Avoids\n  shell-escaping bugs that occur with `--body "..."` for long or multi-line bodies.\n- **`--head` and `--base` explicitly** \u2014 removes all interactive prompts; `gh` has nothing to ask.\n\n## Troubleshooting\n\n**"no commits" or "branch not found" error:**\n\n```bash\ngit push -u origin <branch>\n# then retry:\necho y | timeout 30 gh pr create --base main --head <branch> --title "..." --body-file /tmp/pr-body.md\n```\n\n**Timeout exceeded (command exits 124):**\n\n- Check if the branch was pushed: `git log origin/<branch> --oneline -1`\n- Check GitHub CLI auth: `gh auth status`\n- Retry once; if it hangs again, open the PR via the GitHub web UI.\n';
+var LANE_ORCHESTRATION = '# Lane Orchestration\n\nOlam worlds support parallel work via **lanes** \u2014 independent Claude Code sessions\nrunning in isolated git worktrees inside the same container.\n\nUse lanes when a task has 2+ independent scopes that can work simultaneously\nwithout file conflicts.\n\n## Container API\n\nBase URL: `http://localhost:8080`\n\n### Create a lane\n\n```bash\ncurl -s -X POST \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{"name":"auth-fix","task":"Fix auth bugs","scope":["src/auth/**"],"avoids":["tests/**"]}\' \\\n  http://localhost:8080/lanes/create\n```\n\n### List lanes\n\n```bash\ncurl -s http://localhost:8080/lanes\n```\n\n### Dispatch a prompt to a lane\n\n```bash\ncurl -s -X POST \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{"prompt":"Start by reviewing..."}\' \\\n  http://localhost:8080/lanes/auth-fix/dispatch\n```\n\n### Check lane status\n\n```bash\ncurl -s http://localhost:8080/lanes/auth-fix\n```\n\n### Merge a lane\n\n```bash\ncurl -s -X POST http://localhost:8080/lanes/auth-fix/merge\n```\n\n### Destroy a lane\n\n```bash\ncurl -s -X DELETE http://localhost:8080/lanes/auth-fix\n```\n\n## When to use lanes\n\n- Task has 2+ independent scopes (different directories/modules)\n- Work can be done simultaneously without file conflicts\n- Estimated effort > ~30 tool calls per scope\n\n## When NOT to use lanes\n\n- Simple tasks touching few files\n- Sequential work where each step depends on the previous\n- Everything is in one directory\n\n## Orchestration workflow\n\n1. Analyze the task \u2014 identify independent work streams\n2. Create lanes with non-overlapping scope globs\n3. Dispatch initial prompts to each lane\n4. **Monitor progress** \u2014 poll lane status every 30 seconds:\n   ```bash\n   while true; do\n     STATUS=$(curl -s http://localhost:8080/lanes)\n     RUNNING=$(echo "$STATUS" | jq \'[.lanes[] | select(.status == "running")] | length\')\n     echo "Running lanes: $RUNNING"\n     if [ "$RUNNING" = "0" ]; then echo "All lanes complete!"; break; fi\n     sleep 30\n   done\n   ```\n5. **When a lane completes** (status is "completed" or no longer "running"):\n   - Check its output: `curl -s http://localhost:8080/lanes/<name>`\n   - If satisfactory, merge it: `curl -s -X POST http://localhost:8080/lanes/<name>/merge`\n   - The merge automatically triggers a Codex adversarial review\n6. **After ALL lanes are merged**:\n   - Run tests: `npm test` or equivalent\n   - Review combined changes: `git diff main...HEAD --stat`\n   - Create a PR: see `~/.olam/docs/gh-pr-create.md`\n7. Clean up: `curl -s -X DELETE http://localhost:8080/lanes/<name>`\n\n## Act on completion immediately\n\nWhen all lanes are done, immediately start merging and creating the PR.\nDo not wait for the user to tell you to merge. The workflow is:\n**lanes complete \u2192 merge each \u2192 run tests \u2192 create PR \u2192 report to user.**\n';
+var WORLD_CLAUDE_MD = '# Olam World: {{worldName}}\n\n{{taskBlock}}\n\n## Environment\n- World ID: {{worldId}}\n- Branch: {{branch}}{{servicesLine}}{{pleriPlaneLine}}\n\n## Repos in this World\n{{reposList}}\n\n{{planFileBlock}}## Instructions\n1. Work on the task described above\n2. Write tests first (TDD)\n3. Commit frequently to the world branch\n4. When done, push and the work will be available for review\n5. Your `AskUserQuestion` calls are intercepted and surfaced to the operator\'s host CP automatically. The operator answers in the SPA; claude resumes when keys are injected.\n\n## Sandbox & network \u2014 what is actually true\n\nThe olam-devbox container has FULL outbound internet. Confirm any time:\n\n```bash\ncurl -sI https://registry.npmjs.org/  # \u2192 HTTP 200\ncurl -sI https://github.com/         # \u2192 HTTP 200\n```\n\nRules:\n\n- **Never claim "the sandbox blocks X" without proving it.** Capture the actual `npm install` / `curl` error verbatim. A flaky postinstall is not a network block.\n- **Retry transient failures at least once** before falling back to a manual workaround. `npm install <pkg>` flakes happen; one retry catches >90%.\n- **If you genuinely need a workaround**, say so explicitly with the error message and the retry count, NOT "sandbox network blocked it." Truthful attribution = trustable telemetry.\n- **Playwright `chromium` downloads ~140 MB** from playwright.azureedge.net. Disk-space failures (not network) are the usual cause. Check `df -h` before blaming the network.\n\n## Halt semantics \u2014 when to stop and surface\n\nStop and call `AskUserQuestion` (which surfaces in the host CP) when you hit:\n\n- **Halt-N (new pattern)**: a new dep family, framework, or architectural pattern not in the existing codebase. Don\'t silently adopt it \u2014 surface the choice.\n- **Halt-B (business deal-breaker)**: a breaking constraint that makes the task\'s goal unsatisfiable as stated. Surface the conflict; let the operator re-scope.\n- **Halt-C (complexity blowup)**: the diff is exceeding 1.5x of what the task implied. Surface for re-scoping before continuing.\n\nDon\'t halt on every uncertainty \u2014 only on these three classes. Style/naming/error-handling choices are non-load-bearing; pick the simplest option that works and continue.\n\n## Lane Orchestration (advanced \u2014 read on demand)\n\nThis world supports parallel work lanes via the container API at http://localhost:8080.\nUse only when the task has 2+ independent scopes that can run simultaneously.\n\n**Full lane API + workflow**: see `~/.olam/docs/lane-orchestration.md` (mounted into the world).\n\n## Creating PRs from inside this world\n\n`gh pr create` hangs on a TTY prompt inside the container. Always use:\n\n```bash\necho y | timeout 30 gh pr create --base main --head <branch> --title "..." --body-file /tmp/pr-body.md\n```\n\n**Why + full troubleshooting**: see `~/.olam/docs/gh-pr-create.md`.\n\n## Available Skills & Plugins\n\nYour Claude Code session includes the invoker\'s plugins, rules, and skills.\nThese are copied from the host at world creation time.\nUse `/codex:review` or `/codex:adversarial-review` for code reviews.\nUse `/codex:rescue` to delegate tasks to Codex.\n{{extraContextBlock}}';
+
+// ../core/dist/world/context-injection.js
 function injectWorldContext(opts) {
-  const { world, task, linearTicketId, claudeMdExtra, taskContext, services, pleriPlaneUrl } = opts;
+  const { world } = opts;
   const claudeDir = path22.join(world.workspacePath, ".claude");
   fs20.mkdirSync(claudeDir, { recursive: true });
-  const sections = [];
-  sections.push(`# Olam World: ${world.name}`);
-  sections.push("");
+  const content = WORLD_CLAUDE_MD.replace("{{worldName}}", world.name).replace("{{worldId}}", world.id).replace("{{branch}}", world.branch).replace("{{taskBlock}}", buildTaskBlock(opts)).replace("{{reposList}}", buildReposList(world)).replace("{{servicesLine}}", buildServicesLine(opts.services)).replace("{{pleriPlaneLine}}", buildPleriPlaneLine(opts.pleriPlaneUrl)).replace("{{planFileBlock}}", buildPlanFileBlock(world)).replace("{{extraContextBlock}}", buildExtraContextBlock(opts.claudeMdExtra));
+  fs20.writeFileSync(path22.join(claudeDir, "CLAUDE.md"), content);
+  writeOlamDocs(world.workspacePath);
+}
+function buildTaskBlock(opts) {
+  const { task, linearTicketId, taskContext, world } = opts;
   if (taskContext) {
-    sections.push("## Task");
-    sections.push(`**Source:** ${formatTaskSource(taskContext)}`);
-    if (taskContext.title) {
-      sections.push(`**Title:** ${taskContext.title}`);
-    }
-    sections.push(`**Branch:** ${world.branch}`);
-    sections.push("");
+    const lines = ["## Task"];
+    lines.push(`**Source:** ${formatTaskSource(taskContext)}`);
+    if (taskContext.title)
+      lines.push(`**Title:** ${taskContext.title}`);
+    lines.push(`**Branch:** ${world.branch}`);
+    lines.push("");
     if (taskContext.description) {
-      sections.push("### Description");
-      sections.push(taskContext.description);
-      sections.push("");
+      lines.push("### Description", taskContext.description, "");
     }
     if (taskContext.acceptanceCriteria) {
-      sections.push("### Acceptance Criteria");
-      sections.push(taskContext.acceptanceCriteria);
-      sections.push("");
+      lines.push("### Acceptance Criteria", taskContext.acceptanceCriteria, "");
     }
     if (taskContext.labels && taskContext.labels.length > 0) {
-      sections.push(`### Labels`);
-      sections.push(taskContext.labels.join(", "));
-      sections.push("");
+      lines.push("### Labels", taskContext.labels.join(", "), "");
     }
     if (taskContext.assignee) {
-      sections.push(`### Assignee`);
-      sections.push(taskContext.assignee);
-      sections.push("");
-    }
-  } else if (task) {
-    sections.push("## Task");
-    sections.push(task);
-    sections.push("");
-  }
-  if (linearTicketId && !taskContext) {
-    sections.push("## Linear Ticket");
-    sections.push(`- ID: ${linearTicketId}`);
-    sections.push("- (Fetch full details with Linear MCP tools)");
-    sections.push("");
-  }
-  sections.push("## Environment");
-  sections.push(`- World ID: ${world.id}`);
-  sections.push(`- Branch: ${world.branch}`);
-  if (services && services.length > 0) {
-    const svcList = services.map((s) => `${s.name} (${s.port})`).join(", ");
-    sections.push(`- Services: ${svcList}`);
-  }
-  if (pleriPlaneUrl) {
-    sections.push(`- Pleri Plane: ${pleriPlaneUrl}`);
-  }
-  sections.push("");
-  sections.push("## Repos in this World");
-  for (const repoName of world.repos) {
-    sections.push(`- \`${repoName}\` \u2192 \`/home/olam/workspace/${repoName}\``);
-  }
-  sections.push("");
-  if (hasPlanFile(world)) {
-    sections.push("## Plan");
-    sections.push("A plan file has been provided at `docs/plans/`. Review it before starting work.");
-    sections.push("");
-  }
-  sections.push("## Instructions");
-  sections.push("1. Work on the task described above");
-  sections.push("2. Write tests first (TDD)");
-  sections.push("3. Commit frequently to the world branch");
-  sections.push("4. When done, push and the work will be available for review");
-  sections.push("5. Your `AskUserQuestion` calls are intercepted and surfaced to the operator's host CP automatically. The operator answers in the SPA; claude resumes when keys are injected.");
-  sections.push("");
-  sections.push("## Lane Orchestration (advanced \u2014 read on demand)");
-  sections.push("");
-  sections.push("This world supports parallel work lanes via the container API at http://localhost:8080.");
-  sections.push("Use only when the task has 2+ independent scopes that can run simultaneously.");
-  sections.push("");
-  sections.push("**Full lane API + workflow**: see `~/.olam/docs/lane-orchestration.md` (mounted into the world).");
-  sections.push("");
-  sections.push("## Creating PRs from inside this world");
-  sections.push("");
-  sections.push("`gh pr create` hangs on a TTY prompt inside the container. Always use:");
-  sections.push("");
-  sections.push("```bash");
-  sections.push('echo y | timeout 30 gh pr create --base main --head <branch> --title "..." --body-file /tmp/pr-body.md');
-  sections.push("```");
-  sections.push("");
-  sections.push("**Why + full troubleshooting**: see `~/.olam/docs/gh-pr-create.md`.");
-  sections.push("");
-  sections.push("## Available Skills & Plugins");
-  sections.push("");
-  sections.push("Your Claude Code session includes the invoker's plugins, rules, and skills.");
-  sections.push("These are copied from the host at world creation time.");
-  sections.push("Use `/codex:review` or `/codex:adversarial-review` for code reviews.");
-  sections.push("Use `/codex:rescue` to delegate tasks to Codex.");
-  sections.push("");
-  if (claudeMdExtra) {
-    sections.push("## Additional Context");
-    sections.push(claudeMdExtra);
-    sections.push("");
-  }
-  const content = sections.join("\n");
-  fs20.writeFileSync(path22.join(claudeDir, "CLAUDE.md"), content);
-  writeOlamDocs(world.workspacePath);
+      lines.push("### Assignee", taskContext.assignee, "");
+    }
+    return lines.join("\n").trimEnd();
+  }
+  if (task) {
+    return `## Task
+${task}`;
+  }
+  if (linearTicketId) {
+    return [
+      "## Linear Ticket",
+      `- ID: ${linearTicketId}`,
+      "- (Fetch full details with Linear MCP tools)"
+    ].join("\n");
+  }
+  return "## Task\n_(no task description provided)_";
+}
+function buildReposList(world) {
+  return world.repos.map((repoName) => `- \`${repoName}\` \u2192 \`/home/olam/workspace/${repoName}\``).join("\n");
+}
+function buildServicesLine(services) {
+  if (!services || services.length === 0)
+    return "";
+  const svcList = services.map((s) => `${s.name} (${s.port})`).join(", ");
+  return `
+- Services: ${svcList}`;
+}
+function buildPleriPlaneLine(pleriPlaneUrl) {
+  if (!pleriPlaneUrl)
+    return "";
+  return `
+- Pleri Plane: ${pleriPlaneUrl}`;
+}
+function buildPlanFileBlock(world) {
+  if (!hasPlanFile(world))
+    return "";
+  return [
+    "## Plan",
+    "A plan file has been provided at `docs/plans/`. Review it before starting work.",
+    "",
+    ""
+  ].join("\n");
+}
+function buildExtraContextBlock(extra) {
+  if (!extra)
+    return "";
+  return `
+
+## Additional Context
+${extra}`;
 }
 function writeOlamDocs(workspacePath) {
   const docsDir = path22.join(workspacePath, ".olam", "docs");
   fs20.mkdirSync(docsDir, { recursive: true });
-  for (const filename of ["lane-orchestration.md", "gh-pr-create.md"]) {
-    const src = path22.join(TEMPLATES_DIR, filename);
-    const dest = path22.join(docsDir, filename);
-    fs20.copyFileSync(src, dest);
-  }
+  fs20.writeFileSync(path22.join(docsDir, "gh-pr-create.md"), GH_PR_CREATE);
+  fs20.writeFileSync(path22.join(docsDir, "lane-orchestration.md"), LANE_ORCHESTRATION);
 }
 function formatTaskSource(ctx) {
   if (ctx.source === "linear" && ctx.ticketId) {
@@ -34134,8 +34108,7 @@ ${stderr.split("\n").slice(0, 3).join(" ")}`);
     if (!olamUserPresent) {
       const imageName = (() => {
         try {
-          const { execSync: execSync7 } = __require("node:child_process");
-          return execSync7(`docker inspect ${containerName} --format '{{.Config.Image}}'`, {
+          return execSync5(`docker inspect ${containerName} --format '{{.Config.Image}}'`, {
             encoding: "utf8",
             timeout: 5e3
           }).trim() || "(unknown)";
@@ -35848,7 +35821,7 @@ import * as http2 from "node:http";
 import * as http from "node:http";
 import * as fs26 from "node:fs";
 import * as path29 from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // ../core/dist/dashboard/serialize.js
 function serializeTokenUsage(usage) {
@@ -36353,7 +36326,7 @@ function findSessionInWorld(registry2, sessionId) {
 }
 function createDashboardServer(opts) {
   const { port: port2, registry: registry2 } = opts;
-  const thisDir = path29.dirname(fileURLToPath3(import.meta.url));
+  const thisDir = path29.dirname(fileURLToPath2(import.meta.url));
   const defaultPublicDir = path29.resolve(thisDir, "../../../control-plane/public");
   const publicDir = opts.publicDir ?? defaultPublicDir;
   let hasPublicDir = fs26.existsSync(publicDir);

package/host-cp/compose.yaml

@@ -24,7 +24,7 @@
 # Tear down: `docker compose -f packages/host-cp/compose.yaml down`
 
 services:
-  host-cp:
+  olam-host-cp:
     container_name: olam-host-cp
     # Image-only — operator's `olam bootstrap` pulls the digest-pinned
     # `ghcr.io/pleri/olam-host-cp:latest` (digest from image-digests.json)

package/host-cp/src/agent-runtime-trigger.mjs

@@ -0,0 +1,192 @@
+// agent-runtime-trigger — Phase B B7 (minimum-demo cut) host-side launch hook.
+//
+// When the SPA opens the plan-tab for a (worldId, sessionId), it POSTs
+// here; host-cp idempotently spawns the agent-stream-launch supervisor
+// inside the world's devbox container via `docker exec`. The supervisor
+// (PID 1 within the spawned exec session) then fork-spawns driver +
+// codex runners that long-poll host-cp's /v1/shape.
+//
+// Demo-cut simplifications (per minimum-demo decision; full B7 in follow-up):
+//   - In-memory idempotency map keyed by `(worldId, sessionId)`. Restart of
+//     host-cp loses state; second call after restart re-issues docker exec,
+//     which the supervisor's idempotency check (B6-full's flock + PID-file)
+//     would catch. B6-minimum has no such check → restart of host-cp +
+//     re-trigger may spawn two supervisors. Acceptable for single-operator
+//     local demo; full B7 + B6-full close this.
+//   - Uses shared-secret bearer (from `~/.olam/plan-chat-secret` per the
+//     existing plan-chat-service contract). JWT scope-claim migration is B9.
+//   - No conversation_id ↔ (worldId, sessionId) join-table (A1.4
+//     §migration-schema open question). For demo, the supervisor is
+//     keyed by (worldId, sessionId) directly; codex's APPROVE chunks
+//     write under (worldId, sessionId) — `conversation_id` plumbing
+//     deferred until lookouts (B3) need it.
+//   - No host-cp restart cleanup of dead supervisor entries (the in-memory
+//     map only tracks live spawns; container crash + re-trigger DOES
+//     re-spawn).
+//
+// Source: docs/design/olam-plan-chat-agent-runtime.md `lifecycle` +
+// `bake-in-seam` sections, minimum-demo cut.
+
+import { spawnSync, spawn } from 'node:child_process';
+
+const SPAWN_TIMEOUT_MS = 10_000;
+
+// Default container-side path for the supervisor binary. The devbox image
+// COPYs `packages/intelligence/dist/agent-stream/` to this location during
+// build (devbox Dockerfile update lands alongside this PR or in a follow-up).
+// Compiled supervisor lives at /opt/olam/agent-stream/dist/agent-stream-launch.js
+// per the devbox runtime Dockerfile build-in-image step (tsc writes dist/).
+const DEFAULT_SUPERVISOR_PATH = '/opt/olam/agent-stream/dist/agent-stream-launch.js';
+
+/**
+ * @typedef {object} TriggerArgs
+ * @property {string} worldId
+ * @property {string} sessionId
+ * @property {string} hostCpUrl — URL the container reaches host-cp at
+ *   (e.g. `http://host.docker.internal:3112`)
+ * @property {string} bearer — shared-secret token (read from
+ *   `~/.olam/plan-chat-secret` server-side; never passed in from SPA)
+ * @property {string} [dockerHost='docker-cli'] — `'docker-cli'` for bare-node
+ *   mode; `tcp://...` for container mode (docker-socket-proxy)
+ * @property {string} [supervisorPath] — override for tests
+ * @property {(cmd: string, args: string[], opts?: object) => any} [spawnSyncImpl]
+ *   — injectable for tests; defaults to node:child_process spawnSync
+ * @property {(cmd: string, args: string[], opts?: object) => any} [spawnImpl]
+ *   — injectable for tests; defaults to node:child_process spawn (detached)
+ */
+
+/**
+ * Internal state: which `(worldId, sessionId)` pairs we've already
+ * spawned. Survives only within a single host-cp process instance.
+ *
+ * @type {Map<string, {spawnedAt: number, pid?: number}>}
+ */
+const liveSpawns = new Map();
+
+/** @param {string} worldId @param {string} sessionId */
+function key(worldId, sessionId) {
+  return `${worldId}::${sessionId}`;
+}
+
+/**
+ * Idempotently spawn the agent-stream supervisor inside the world's container.
+ *
+ * Returns `{status: 'spawned' | 'already-running', container, pid?}`.
+ * Throws on docker-CLI failure or container-not-running.
+ *
+ * @param {TriggerArgs} args
+ */
+export async function triggerAgentRuntime(args) {
+  const {
+    worldId,
+    sessionId,
+    hostCpUrl,
+    bearer,
+    dockerHost = 'docker-cli',
+    supervisorPath = DEFAULT_SUPERVISOR_PATH,
+    spawnSyncImpl = spawnSync,
+    spawnImpl = spawn,
+  } = args;
+
+  if (!worldId || !sessionId || !hostCpUrl || !bearer) {
+    throw new Error(
+      'triggerAgentRuntime: worldId, sessionId, hostCpUrl, bearer all required',
+    );
+  }
+
+  const k = key(worldId, sessionId);
+  if (liveSpawns.has(k)) {
+    const entry = liveSpawns.get(k);
+    return {
+      status: 'already-running',
+      container: `olam-${worldId}-devbox`,
+      spawnedAt: entry.spawnedAt,
+      pid: entry.pid,
+    };
+  }
+
+  const containerName = `olam-${worldId}-devbox`;
+
+  // Bare-node mode: shell out to docker exec --detach (or background
+  // via & in a wrapper command). Detached so the SPA's HTTP request
+  // returns promptly; the supervisor lives until SIGTERM.
+  if (dockerHost === 'docker-cli') {
+    // First, verify the container exists and is running. `docker inspect`
+    // returns exit 1 if the container is not found; exit 0 with stdout
+    // containing the state if found.
+    const inspect = spawnSyncImpl(
+      'docker',
+      ['inspect', '--format', '{{.State.Running}}', containerName],
+      { encoding: 'utf-8', timeout: SPAWN_TIMEOUT_MS },
+    );
+    if (inspect.error) {
+      throw new Error(
+        `docker inspect ${containerName} failed: ${inspect.error.message}`,
+      );
+    }
+    if (inspect.status !== 0) {
+      throw new Error(
+        `docker inspect ${containerName} exit ${inspect.status}: ${(inspect.stderr || '').trim()}`,
+      );
+    }
+    if ((inspect.stdout || '').trim() !== 'true') {
+      throw new Error(
+        `container ${containerName} is not running (state: ${(inspect.stdout || '').trim()})`,
+      );
+    }
+
+    // Use docker exec --detach to spawn the supervisor in the background.
+    // -e flags inject the runtime env; the supervisor binary path is the
+    // last positional argument.
+    const env = {
+      HOST_CP_URL: hostCpUrl,
+      HOST_CP_BEARER: bearer,
+      WORLD_ID: worldId,
+      SESSION_ID: sessionId,
+    };
+    const execArgs = ['exec', '--detach'];
+    for (const [k_, v] of Object.entries(env)) {
+      execArgs.push('-e', `${k_}=${v}`);
+    }
+    execArgs.push(containerName, 'node', supervisorPath);
+
+    const detached = spawnImpl('docker', execArgs, {
+      stdio: 'ignore',
+      detached: true,
+    });
+    detached.unref?.();
+
+    liveSpawns.set(k, { spawnedAt: Date.now(), pid: detached.pid });
+
+    return {
+      status: 'spawned',
+      container: containerName,
+      pid: detached.pid,
+    };
+  }
+
+  // Container mode (docker-socket-proxy): POST /containers/<name>/exec then
+  // /exec/<id>/start with Detach:true. Deferred to B7-full — the bare-node
+  // mode covers the local-demo flow.
+  throw new Error(
+    `triggerAgentRuntime: dockerHost mode '${dockerHost}' not supported in minimum-demo cut; use 'docker-cli'`,
+  );
+}
+
+/**
+ * Test-only: clear the in-memory live-spawns map.
+ * Production code should NEVER call this — it would let a duplicate
+ * supervisor spawn.
+ */
+export function _clearLiveSpawnsForTests() {
+  liveSpawns.clear();
+}
+
+/**
+ * Inspect-only: read the current live-spawns map (for observability).
+ *
+ * @returns {ReadonlyMap<string, {spawnedAt: number, pid?: number}>}
+ */
+export function getLiveSpawns() {
+  return new Map(liveSpawns);
+}

package/host-cp/src/server.mjs

@@ -56,6 +56,8 @@ import { createPylonWorldsSource } from './pylon-worlds-source.mjs';
 import { composeWorldsSources } from './compose-worlds-sources.mjs';
 import { createWorldPrStateStore } from './world-pr-state.mjs';
 import { PlanOrchestrator } from './plan-orchestrator.mjs';
+import { triggerAgentRuntime } from './agent-runtime-trigger.mjs';
+import { readSecret as readPlanChatSecret, SECRET_PATH as PLAN_CHAT_SECRET_PATH } from './plan-chat-secret.mjs';
 import { createPrMergePoller } from './pr-merge-poller.mjs';
 import { parse as parseYaml } from 'yaml';
 import { startWorldsDbReconciler } from './worlds-db-source.mjs';
@@ -1847,6 +1849,77 @@ const server = http.createServer(async (req, res) => {
     return jsonReply(res, 200, { ok: true });
   }
 
+  // GET /api/plan/conversations/:id/sidebar — list signals for a conversation.
+  // Phase C C5 addition: lets the new /session/:worldId/plan SPA fetch the
+  // signals state for SidebarBubble rendering. The existing dismiss/use POST
+  // routes (above) already handle mutations; this GET fills the read-side gap
+  // that PR #223's SSE-based UI didn't need (signals streamed via SSE).
+  const planSidebarListMatch = /^\/api\/plan\/conversations\/([^/?#]+)\/sidebar$/.exec(url.pathname);
+  if (planSidebarListMatch && req.method === 'GET') {
+    if (!await requirePlanCredential(res)) return;
+    const conversationId = decodeURIComponent(planSidebarListMatch[1]);
+    const chunkIdParam = url.searchParams.get('chunk_id') ?? undefined;
+    const signals = planOrchestrator.listSignals(conversationId, chunkIdParam);
+    return jsonReply(res, 200, { signals });
+  }
+
+  // POST /api/plan/agent-runtime/trigger — Phase B B7 (minimum-demo cut).
+  // SPA POSTs here when /session/<worldId>/plan opens; host-cp idempotently
+  // docker-execs the agent-stream-launch supervisor inside the world's
+  // devbox container. Body: { worldId, sessionId }. Returns the spawn
+  // status + container name + supervisor pid.
+  //
+  // Source: docs/design/olam-plan-chat-agent-runtime.md `lifecycle` +
+  // `bake-in-seam` sections.
+  if (url.pathname === '/api/plan/agent-runtime/trigger' && req.method === 'POST') {
+    if (!await requirePlanCredential(res)) return;
+    let body;
+    try {
+      body = JSON.parse((await readRequestBody(req)) || '{}');
+    } catch (err) {
+      return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+    }
+    if (!body.worldId || !body.sessionId) {
+      return jsonReply(res, 400, {
+        error: 'missing_fields',
+        message: 'worldId and sessionId required',
+      });
+    }
+    // Bearer for the container-side runners: shared-secret from
+    // ~/.olam/plan-chat-secret (matches plan-chat-service.mjs auth).
+    // JWT scope-claim migration is B9 / post-demo.
+    let bearer;
+    try {
+      bearer = readPlanChatSecret();
+    } catch (err) {
+      return jsonReply(res, 503, {
+        error: 'plan_chat_secret_unavailable',
+        message: `plan-chat-secret unreadable at ${PLAN_CHAT_SECRET_PATH}: ${err.message}`,
+      });
+    }
+    // host-cp's URL as seen from inside the devbox container. Bare-node
+    // mode (docker-cli) uses host.docker.internal; container mode uses
+    // the host-cp service name. Default: host.docker.internal for the
+    // operator-local demo flow.
+    const hostCpUrlForContainer =
+      process.env.OLAM_AGENT_RUNTIME_HOST_CP_URL ?? 'http://host.docker.internal:3112';
+    try {
+      const result = await triggerAgentRuntime({
+        worldId: body.worldId,
+        sessionId: body.sessionId,
+        hostCpUrl: hostCpUrlForContainer,
+        bearer,
+        dockerHost: DOCKER_HOST,
+      });
+      return jsonReply(res, 200, result);
+    } catch (err) {
+      return jsonReply(res, 500, {
+        error: 'agent_runtime_trigger_failed',
+        message: err.message,
+      });
+    }
+  }
+
   // GET /api/worlds/:id/processes
   // GET /api/worlds/:id/processes/stream — SSE fanout (5s cadence, per-world)
   // Handler: routes/process-port.mjs → handleListProcesses