@cabane/companion 0.6.1 → 0.6.3

package/README.md

@@ -2,7 +2,7 @@
 
 Connect a **coding agent on your machine** to your [Cabane](https://cabane.ai) workspaces as a **responder** — it replies to messages inside Cabane while running as a full local AI client, so you can drive work against your own codebase, files, and MCP servers without putting any of it in Cabane. The model and tools run on your box; only the reply crosses back.
 
-The Companion runs **[Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code)** by default, and also supports **[opencode](https://opencode.ai)** — a provider-agnostic coding agent — as an alternate runtime you opt into per machine. See [Runtimes](#runtimes-claude-code-and-opencode).
+The Companion runs your agents through a **harness** on your machine — **[Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code)**, **[Codex](https://developers.openai.com/codex/cli)**, or **[opencode](https://opencode.ai)** — and you expose the ones you have. Install and sign in to a harness yourself; the Companion drives it. See [Harnesses](#harnesses).
 
 This is **v0**. It's a small CLI — install it from npm with one command, pair the machine once, and run. It talks to Cabane only over Cabane's public API.
 
@@ -16,9 +16,25 @@ The Companion runs on a **device you pair**, running **agents you assign to it**
 
 ## Prerequisites
 
-You need **Node 22+** (the Companion runtime — check with `node --version`) and, for the default Claude Code runtime, **Claude Code** on your PATH (`which claude` should resolve). The Agent SDK shells out to `claude`, riding your local Claude Code's auth, so install it with `npm i -g @anthropic-ai/claude-code` and complete the login flow (`claude` → follow the prompts) **before** starting the Companion.
+You need **Node 22+** (the Companion itself runs on Node — check with `node --version`) and **at least one harness installed and signed in**. The Companion installs no harness and drives no login for you — bring your own, and set it up **before** starting the Companion. It refuses to `start` if no harness is exposed, because no turn could be routed to it.
 
-Prefer **opencode**? It's supported as an alternate runtime — install it alongside (or instead of) Claude Code and follow [Runtimes](#runtimes-claude-code-and-opencode) to wire it in.
+Set up whichever you already use — one is enough, and a machine can expose several. [Harnesses](#harnesses) has the full per-harness wiring; the short version:
+
+**Claude Code** — install it globally _and_ log in:
+
+```sh
+npm i -g @anthropic-ai/claude-code
+claude   # complete the login, then quit
+```
+
+Both halves are load-bearing, for different reasons:
+
+- **The install** puts `claude` on your PATH (`which claude` should resolve). That PATH probe is how the Companion exposes Claude Code — it needs no configuration, but without `claude` the device won't offer it.
+- **The login** writes the credential the turn actually uses. The Companion does _not_ run your global `claude` to answer a turn — inference goes through the bundled Claude Agent SDK — but the SDK reads the credential your Claude Code login left on disk. So a machine with `claude` installed and never logged in looks fine (the Connector reads **Online**) and then fails every turn with **"Sign-in needed"**.
+
+**Codex** — install the Codex CLI and log in (`codex login`, or set `CODEX_API_KEY` in Codex's own environment — Cabane never sees the key). Unlike Claude Code, which is auto-detected on the PATH, Codex is an explicit opt-in: a one-line `codex` block in `~/.cabane/config.json`, or one click in the [dashboard](#the-dashboard). → [full setup](https://app.cabane.ai/docs/reference/connectors/chatgpt)
+
+**opencode** — install it, authenticate a provider through its own flow, and start its server (`opencode serve`); the Companion addresses it at the URL you give it. → [full setup](https://app.cabane.ai/docs/reference/connectors/opencode)
 
 You also need **a Cabane account.** A device is registered under your user account; the agents it runs can live in any workspace you have access to.
 
@@ -95,7 +111,7 @@ The prompt returns immediately and you can close the terminal — replies keep l
 
 ## The dashboard
 
-`cabane-companion start` serves a small localhost dashboard (default `http://127.0.0.1:7474`) so the Companion is usable without tailing logs: live per-workspace connection status, the agents currently assigned to this device, a recent-dispatches feed, a log tail, and a few local-only controls (Stop / Restart / Reload-config). It binds to `127.0.0.1` only — same threat model as any localhost dev tool, no auth. It does **not** auto-open a browser by default — the URL is printed on start; pass `--open` (or set `autoOpen: true` in config) to open it automatically, and `--no-open` / `BRIDGE_NO_OPEN=1` force it off. It keeps working when Cabane itself is unreachable, showing a "⚠ Cabane unreachable" banner.
+`cabane-companion start` serves a small localhost dashboard (default `http://127.0.0.1:7474`) so the Companion is usable without tailing logs: live per-workspace connection status, the agents currently assigned to this device, the [harnesses](#harnesses) it can see (with a one-click enable for one that's installed but not yet exposed), a recent-dispatches feed, a log tail, and a few local-only controls (Stop / Restart / Reload-config). It binds to `127.0.0.1` only — same threat model as any localhost dev tool, no auth. It does **not** auto-open a browser by default — the URL is printed on start; pass `--open` (or set `autoOpen: true` in config) to open it automatically, and `--no-open` / `BRIDGE_NO_OPEN=1` force it off. It keeps working when Cabane itself is unreachable, showing a "⚠ Cabane unreachable" banner.
 
 ## Configuring an agent: what's in Cabane vs. on this machine
 
@@ -163,34 +179,44 @@ When an agent's MCP servers in Cabane need a credential, that credential is writ
 
 A `${VAR}` the store doesn't declare fails the turn loudly — it is **never** read from your shell environment, so a config can't smuggle out an ambient credential. The Companion reports the declared **names** (never values) to Cabane on its heartbeat, so the settings UI can warn "this agent needs `${GITHUB_TOKEN}`, this device doesn't expose it" before a turn ever runs.
 
-## Runtimes: Claude Code and opencode
+## Harnesses
+
+A **harness** is the local tool that runs a model — **[Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code)**, **[Codex](https://developers.openai.com/codex/cli)**, or **[opencode](https://opencode.ai)** — together with the credential behind it. A harness connected to Cabane on this device is a **Connector**, and one device runs as many Connectors as it has harnesses. None is privileged: a device advertises exactly the harnesses it actually has.
 
-Each turn runs through a **runtime** — the local AI client that actually executes the agent. **Claude Code is the default**, and every Companion advertises it; it's what the [Prerequisites](#prerequisites) set up. The Companion can _also_ run **[opencode](https://opencode.ai)** — a provider-agnostic coding agent — as a second runtime, opted into per machine.
+Which harness a turn uses follows the agent's **model**, set in Cabane (Workspace settings → Agents): a Claude model runs on Claude Code, an OpenAI model on Codex, an opencode model on opencode. A device only offers a harness's models — and only accepts its turns — once that harness is exposed, so set it up first, then pick a matching model for the agent. A turn is never routed to a harness the machine can't run.
 
-Which runtime a turn uses follows the agent's **model**, set in Cabane (Workspace settings → Agents): a Claude model runs on Claude Code, an opencode model runs on opencode. A device only offers opencode models — and only accepts opencode turns — once it's actually running opencode, so set it up first, then pick an opencode model for the agent. A turn is never routed to a runtime the machine can't run.
+What "exposed" means differs per harness, because each is discoverable in a different way. Bring your own install and your own login in all three cases — the Companion never installs a binary and never drives a login:
 
-To add opencode to this machine:
+| Harness         | How the device exposes it                                                                    | Setup                                                                      |
+| --------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| **Claude Code** | `claude` is on your PATH — auto-detected, no configuration.                                  | [Claude](https://app.cabane.ai/docs/reference/connectors/claude)           |
+| **Codex**       | A `codex` block in `~/.cabane/config.json`. Unlike Claude Code, an explicit opt-in.          | [ChatGPT (Codex)](https://app.cabane.ai/docs/reference/connectors/chatgpt) |
+| **opencode**    | An `opencode.serverUrl` in `~/.cabane/config.json` pointing at a reachable `opencode serve`. | [opencode](https://app.cabane.ai/docs/reference/connectors/opencode)       |
+
+Each harness has a full setup page in the docs — install, login, enable, verify — linked above; this section is just the shape of it and the config the Companion reads.
+
+**You usually don't hand-edit the config.** `cabane-companion start` serves a [localhost dashboard](#the-dashboard) listing every harness it can see, including ones installed but not yet exposed: a `codex` binary on your PATH shows up as detected-but-not-enabled with a **Use Codex** button, and opencode gets an **Add opencode** field for the `serve` URL (health-checked before it's written, so an unreachable server is caught in place). One click writes the block and advertises the Connector straight away — no restart. Editing `~/.cabane/config.json` yourself is the fallback, and what a headless device wants:
+
+```jsonc
+{
+  // …device identity, managed by `pair`; don't hand-edit those fields…
+  "codex": { "enabled": true },
+  "opencode": { "serverUrl": "http://127.0.0.1:4096" },
+}
+```
 
-1. **Install opencode** and authenticate a provider through its own flow (`opencode auth login`). Provider keys live in opencode's own store — **Cabane never sees them**.
-2. **Start its server:** `opencode serve --port 4096` (any free port). Run one `opencode serve` per Companion process.
-3. **Point the Companion at it** — add a top-level `opencode` block to `~/.cabane/config.json`:
-   ```jsonc
-   {
-     // …device identity, managed by `pair`; don't hand-edit those fields…
-     "opencode": { "serverUrl": "http://127.0.0.1:4096" },
-   }
-   ```
-4. **Restart the Companion.** Its next heartbeat advertises the `opencode` runtime, and an agent assigned to this device can now be set to an opencode model in Cabane. Without this block the device stays Claude-Code-only, exactly as before.
+Either block is optional and independent — set only the harnesses you have. Codex is a local CLI the bundled `@openai/codex-sdk` spawns per turn, so it takes a flag and no URL; opencode is a long-lived server addressed by URL, so run one `opencode serve` per Companion process. A hand-edit needs a restart (`cabane-companion stop && cabane-companion start`); the dashboard's button doesn't.
 
-Everything else about a Companion-run agent is unchanged — same assignment, same working directory, same secrets, same dashboard. opencode adds a runtime, not a new way to run the Companion.
+Everything else about a Companion-run agent is the same whichever harness runs it — same assignment, same working directory, same secrets, same dashboard. A harness is a way to execute a turn, not a different way to run the Companion.
 
 ## Files on disk
 
 ```
 ~/.cabane/
 ├── config.json            # device identity: baseUrl + device token (cabdev_…) + device id/label,
-│                          #   plus optional per-agent `agents` overrides (cwd / prepareHook), an
-│                          #   optional `opencode` block (serverUrl), and dashboard prefs. mode 600.
+│                          #   plus optional per-agent `agents` overrides (cwd / prepareHook), the
+│                          #   optional harness blocks (`codex` enabled, `opencode` serverUrl), and
+│                          #   dashboard prefs. mode 600.
 │                          #   No account password, no full-account token.
 ├── credentials.json       # agentId → per-agent workspace-bound token, cached on first assignment
 │                          #   pull (delivered once, then never re-sent). mode 600.
@@ -206,7 +232,7 @@ No SQLite, no embedded DB. Cabane is the source of truth for which agents to run
 
 ## Debugging a turn: transcripts
 
-The dashboard shows the agent's final reply, but not _how_ it got there. When a turn misbehaves — an agent that "couldn't read the file", a tool that errored, MCP tools that didn't load, a missing secret — the full picture is on disk. Every dispatch writes the complete Claude Agent SDK message stream (the system init with its tool list, every tool call **and its result**, the assistant text, the outcome) to a JSONL file under `~/.cabane/transcripts/`. On a failed turn, the Companion log also prints the exact path.
+The dashboard shows the agent's final reply, but not _how_ it got there. When a turn misbehaves — an agent that "couldn't read the file", a tool that errored, MCP tools that didn't load, a missing secret — the full picture is on disk. Every dispatch — on whichever harness ran it — writes the complete turn stream (the system init with its tool list, every tool call **and its result**, the assistant text, the outcome) to a JSONL file under `~/.cabane/transcripts/`. On a failed turn, the Companion log also prints the exact path.
 
 Read one back in a readable form:
 

package/dist/cli.js

@@ -4,7 +4,7 @@
 import { Command } from "commander";
 
 // src/commands/daemon.ts
-import { spawn as spawn3 } from "child_process";
+import { spawn as spawn4 } from "child_process";
 import { closeSync as closeSync2, mkdirSync as mkdirSync4, openSync as openSync2 } from "fs";
 import { fileURLToPath } from "url";
 
@@ -457,11 +457,94 @@ function getLogger() {
 }
 
 // src/prereqs.ts
+import { spawn as spawn3 } from "child_process";
+
+// src/harness-versions.ts
 import { spawn as spawn2 } from "child_process";
+var EMPTY = { claudeCode: null, opencode: null, codex: null };
+function parseVersionToken(raw) {
+  if (!raw) return null;
+  const m = raw.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/);
+  return m ? m[0] : null;
+}
+async function probeCliVersion(command, spawnImpl = spawn2) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => {
+      if (!settled) {
+        settled = true;
+        resolve(v);
+      }
+    };
+    let child;
+    try {
+      child = spawnImpl(command, ["--version"], { stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      done(null);
+      return;
+    }
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      if (out.length < 4096) out += chunk.toString();
+    });
+    child.once("error", () => done(null));
+    child.once("exit", (code) => done(code === 0 ? parseVersionToken(out) : null));
+  });
+}
+async function probeOpencodeVersion(serverUrl, fetchImpl = fetch) {
+  try {
+    const base = serverUrl.endsWith("/") ? serverUrl.slice(0, -1) : serverUrl;
+    const res = await fetchImpl(`${base}/global/health`, {
+      headers: { accept: "application/json" }
+    });
+    if (!res.ok) return null;
+    return extractOpencodeVersion(await res.json());
+  } catch {
+    return null;
+  }
+}
+function extractOpencodeVersion(json) {
+  if (!json || typeof json !== "object") return null;
+  const obj = json;
+  const candidates = [obj.version];
+  for (const v of Object.values(obj)) {
+    if (v && typeof v === "object") candidates.push(v.version);
+  }
+  for (const c of candidates) {
+    if (typeof c === "string") {
+      const parsed = parseVersionToken(c);
+      if (parsed) return parsed;
+    }
+  }
+  return null;
+}
+async function probeHarnessVersions(opts, deps = {}) {
+  const probeClaudeCode = deps.probeClaudeCode ?? (() => probeCliVersion("claude"));
+  const probeCodex = deps.probeCodex ?? (() => probeCliVersion("codex"));
+  const probeOpencode = deps.probeOpencode ?? ((url) => probeOpencodeVersion(url));
+  const [claudeCode, codex, opencode] = await Promise.all([
+    opts.claudeCode ? safe(probeClaudeCode) : Promise.resolve(null),
+    opts.codex ? safe(probeCodex) : Promise.resolve(null),
+    opts.opencodeServerUrl ? safe(() => probeOpencode(opts.opencodeServerUrl)) : Promise.resolve(null)
+  ]);
+  return { claudeCode, opencode, codex };
+}
+function emptyHarnessVersions() {
+  return { ...EMPTY };
+}
+async function safe(fn) {
+  try {
+    return await fn();
+  } catch {
+    return null;
+  }
+}
+
+// src/prereqs.ts
 async function claudeOnPath() {
   return new Promise((resolve) => {
     let settled = false;
-    const child = spawn2("claude", ["--version"], { stdio: "ignore" });
+    const child = spawn3("claude", ["--version"], { stdio: "ignore" });
     child.once("error", () => {
       if (!settled) {
         settled = true;
@@ -476,8 +559,20 @@ async function claudeOnPath() {
     });
   });
 }
+var CODEX_PROBE_TIMEOUT_MS = 4e3;
+async function codexOnPath() {
+  const version = await Promise.race([
+    probeCliVersion("codex"),
+    new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(null), CODEX_PROBE_TIMEOUT_MS);
+      timer.unref?.();
+    })
+  ]);
+  return version !== null;
+}
 async function ensureRuntimeAvailable(cfg, deps = {}) {
   const probeClaude = deps.probeClaude ?? claudeOnPath;
+  const probeCodex = deps.probeCodex ?? codexOnPath;
   const warn = deps.warn ?? ((message) => process.stderr.write(`${message}
 `));
   if (await probeClaude()) return;
@@ -486,15 +581,15 @@ async function ensureRuntimeAvailable(cfg, deps = {}) {
     ...isCodexEnabled(cfg) ? ["codex"] : []
   ];
   if (alternates.length > 0) {
+    const exposed = alternates.join(" + ");
     warn(
-      `warning: Claude Code isn\u2019t on your PATH, so this device will run ${alternates.join(
-        " + "
-      )} only \u2014 it advertises just those runtimes, so assign it matching models (a Claude-model agent won\u2019t be routed here). Install Claude Code (\`npm i -g @anthropic-ai/claude-code\`) if you want it to run Claude models too.`
+      `warning: Claude Code isn\u2019t on your PATH, so this device exposes ${exposed} only \u2014 it advertises nothing else, so a Claude-model agent won\u2019t be routed here. Assign it agents on models ${exposed} can run, or install Claude Code (\`npm i -g @anthropic-ai/claude-code\`) and log in if you want this device to run Claude models too.`
     );
     return;
   }
+  const installedButUnexposed = await probeCodex() ? 'Codex is installed on this machine but not exposed \u2014 enable it with `{ "codex": { "enabled": true } }` in ~/.cabane/config.json. Otherwise, expose a harness:\n' : "Expose at least one:\n";
   throw new CompanionError(
-    "Claude Code, the companion\u2019s default runtime, is not on your PATH. Install it with `npm i -g @anthropic-ai/claude-code`, log in (`claude` then follow the prompts), and run `cabane-companion start` again. The default runtime uses your local Claude Code subscription to run each agent turn; opencode is supported as an alternate runtime you configure per device (see the companion README)."
+    "This device exposes no harness, so no agent turn can run here. " + installedButUnexposed + '  \u2022 Claude Code \u2014 install it (`npm i -g @anthropic-ai/claude-code`) and log in (`claude`, then follow the prompts); it\u2019s exposed automatically once `claude` is on your PATH.\n  \u2022 Codex \u2014 install the Codex CLI and log in (`codex login`), then add `{ "codex": { "enabled": true } }` to ~/.cabane/config.json.\n  \u2022 opencode \u2014 run `opencode serve --port 4096`, then add `{ "opencode": { "serverUrl": "http://127.0.0.1:4096" } }` to ~/.cabane/config.json.\nThen run `cabane-companion start` again (see the companion README).'
   );
 }
 
@@ -648,7 +743,7 @@ function defaultSpawnDetached(args) {
   mkdirSync4(cabaneDir(), { recursive: true });
   const logFd = openSync2(companionLogPath(), "a");
   try {
-    return spawn3(process.execPath, [cliPath, ...args], {
+    return spawn4(process.execPath, [cliPath, ...args], {
       detached: true,
       stdio: ["ignore", logFd, logFd],
       env: { ...process.env, CABANE_COMPANION_DAEMON: "1" }
@@ -922,12 +1017,12 @@ async function pair(opts = {}) {
 import { readFileSync as readFileSync11 } from "fs";
 
 // src/browser.ts
-import { spawn as spawn4 } from "child_process";
+import { spawn as spawn5 } from "child_process";
 import { platform } from "process";
 function openBrowser(url) {
   try {
     const { command, args } = openerFor(url);
-    const child = spawn4(command, args, { stdio: "ignore", detached: true });
+    const child = spawn5(command, args, { stdio: "ignore", detached: true });
     child.on("error", () => {
     });
     child.unref();
@@ -1434,87 +1529,6 @@ function resolveStaticDir() {
   return join6(dirname4(fileURLToPath2(import.meta.url)), "static");
 }
 
-// src/harness-versions.ts
-import { spawn as spawn5 } from "child_process";
-var EMPTY = { claudeCode: null, opencode: null, codex: null };
-function parseVersionToken(raw) {
-  if (!raw) return null;
-  const m = raw.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/);
-  return m ? m[0] : null;
-}
-async function probeCliVersion(command, spawnImpl = spawn5) {
-  return new Promise((resolve) => {
-    let settled = false;
-    const done = (v) => {
-      if (!settled) {
-        settled = true;
-        resolve(v);
-      }
-    };
-    let child;
-    try {
-      child = spawnImpl(command, ["--version"], { stdio: ["ignore", "pipe", "ignore"] });
-    } catch {
-      done(null);
-      return;
-    }
-    let out = "";
-    child.stdout?.on("data", (chunk) => {
-      if (out.length < 4096) out += chunk.toString();
-    });
-    child.once("error", () => done(null));
-    child.once("exit", (code) => done(code === 0 ? parseVersionToken(out) : null));
-  });
-}
-async function probeOpencodeVersion(serverUrl, fetchImpl = fetch) {
-  try {
-    const base = serverUrl.endsWith("/") ? serverUrl.slice(0, -1) : serverUrl;
-    const res = await fetchImpl(`${base}/global/health`, {
-      headers: { accept: "application/json" }
-    });
-    if (!res.ok) return null;
-    return extractOpencodeVersion(await res.json());
-  } catch {
-    return null;
-  }
-}
-function extractOpencodeVersion(json) {
-  if (!json || typeof json !== "object") return null;
-  const obj = json;
-  const candidates = [obj.version];
-  for (const v of Object.values(obj)) {
-    if (v && typeof v === "object") candidates.push(v.version);
-  }
-  for (const c of candidates) {
-    if (typeof c === "string") {
-      const parsed = parseVersionToken(c);
-      if (parsed) return parsed;
-    }
-  }
-  return null;
-}
-async function probeHarnessVersions(opts, deps = {}) {
-  const probeClaudeCode = deps.probeClaudeCode ?? (() => probeCliVersion("claude"));
-  const probeCodex = deps.probeCodex ?? (() => probeCliVersion("codex"));
-  const probeOpencode = deps.probeOpencode ?? ((url) => probeOpencodeVersion(url));
-  const [claudeCode, codex, opencode] = await Promise.all([
-    opts.claudeCode ? safe(probeClaudeCode) : Promise.resolve(null),
-    opts.codex ? safe(probeCodex) : Promise.resolve(null),
-    opts.opencodeServerUrl ? safe(() => probeOpencode(opts.opencodeServerUrl)) : Promise.resolve(null)
-  ]);
-  return { claudeCode, opencode, codex };
-}
-function emptyHarnessVersions() {
-  return { ...EMPTY };
-}
-async function safe(fn) {
-  try {
-    return await fn();
-  } catch {
-    return null;
-  }
-}
-
 // src/api.ts
 var RETRY_BACKOFF_MS = [250, 750];
 var ACTIVE_RUN_OUTBOX_SEQ = 0;
@@ -2972,6 +2986,11 @@ function buildClaudeCodeOptions(req, augment) {
   const freshReason = "fresh" in resumeDecision ? resumeDecision.reason : void 0;
   const devControlsAutoMemory = req.local.claudeCode?.autoMemory === true;
   const model = parseClaudeCodeModel(config.model);
+  if (model === null) {
+    console.warn(
+      `[agent-runtime/claude-code] CT823: dispatching a subscription turn with NO concrete model (config.model=${JSON.stringify(config.model)}) \u2014 the SDK will fall back to its bundled default. This should be unreachable post-CT823; the model resolver should have supplied a concrete house default.`
+    );
+  }
   const base = {
     // model / effort: `model` is pinned only when the config names a real one —
     // omitted for "let it choose" (see `parseClaudeCodeModel`), so the SDK picks
@@ -3593,26 +3612,20 @@ function selectAdapter(registry, runtime) {
 
 // packages/agent-runtime/src/opencode/addendum.ts
 var OPENCODE_ADDENDUM = [
-  "Your Cabane tools have plain names \u2014 `read`, `write`, `search`, `edit`,",
-  "`post_message`, and so on; the host tools are plain verbs too (`bash`, `read`,",
-  "`edit`). If a tool appears in this prompt with an `mcp__\u2026__` prefix, that",
+  "Your one Cabane workspace tool has a plain name \u2014 `sdk` (you act on the",
+  "workspace by writing a TypeScript program and calling `sdk` with it); the",
+  "turn-control verbs (`ask`, `wake_me`, `summon_agent`, `skip_turn`) are",
+  "plain-named too, as are the few ancillary cabane tools (`list_workspaces`,",
+  "`read_binary`, `upload`, `begin_upload`, `finalize_upload`,",
+  "`mint_render_token`), and the host tools are plain verbs (`bash`, `read`,",
+  "`edit`). There is no `write`/`search`/`edit` CABANE tool here \u2014 those are",
+  "`cabane` SDK calls inside your program, not tools (a bare `read`/`edit` is the",
+  "HOST tool). If a tool appears in this prompt with an `mcp__\u2026__` prefix, that",
   "prefix is not part of its name \u2014 call the tool by its plain verb. Write your",
   "closing reply as the last thing you say in the turn: you can interleave",
   "narration with tool calls, but only your final message is recorded as the",
   "turn\u2019s reply."
 ].join(" ");
-var OPENCODE_ADDENDUM_CODE_MODE = [
-  "Your one Cabane workspace tool has a plain name \u2014 `sdk` (you act on the",
-  "workspace by writing a TypeScript program and calling `sdk` with it); the",
-  "turn-control verbs (`ask`, `wake_me`, `summon_agent`, `skip_turn`) are",
-  "plain-named too, and the host tools are plain verbs (`bash`, `read`, `edit`).",
-  "There is no `write`/`search`/`edit` CABANE tool here \u2014 those are `cabane` SDK",
-  "calls inside your program, not tools (a bare `read`/`edit` is the HOST tool). If",
-  "a tool appears in this prompt with an `mcp__\u2026__` prefix, that prefix is not part",
-  "of its name \u2014 call the tool by its plain verb. Write your closing reply as the",
-  "last thing you say in the turn: you can interleave narration with tool calls, but",
-  "only your final message is recorded as the turn\u2019s reply."
-].join(" ");
 
 // packages/agent-runtime/src/opencode/events.ts
 function asRecord(v) {
@@ -4164,7 +4177,7 @@ function createOpencodeAdapter(deps = {}) {
     name: "opencode",
     // CT614: surface-aware — a code-mode turn (only `code` mounted) is taught
     // `code`, not the granular cabane names it no longer has.
-    promptAddendum: (codeMode = false) => codeMode ? OPENCODE_ADDENDUM_CODE_MODE : OPENCODE_ADDENDUM,
+    promptAddendum: () => OPENCODE_ADDENDUM,
     dialectSchema: opencodeDialectSchema,
     async *runTurn(req, signal) {
       if (!transport) {
@@ -4564,14 +4577,6 @@ var OPENCODE_CONFORMANCE_FIXTURES = [
 
 // packages/agent-runtime/src/codex/addendum.ts
 var CODEX_ADDENDUM = [
-  "Your Cabane tools have plain names \u2014 `read`, `write`, `search`, `edit`,",
-  "`post_message`, and so on. If a tool appears in this prompt with an `mcp__\u2026__`",
-  "prefix, that prefix is not part of its name \u2014 call the tool by its plain verb.",
-  "Write your closing reply as the last thing you say in the turn: you can",
-  "interleave narration with tool calls, but only your final message is recorded",
-  "as the turn\u2019s reply."
-].join(" ");
-var CODEX_ADDENDUM_CODE_MODE = [
   "Your Cabane workspace tool is exposed to Codex as the qualified MCP tool",
   "`mcp__cabane__sdk`. On Codex versions that defer MCP tools, locate it in the",
   "`functions.exec` deferred-tool inventory and invoke that exact qualified tool",
@@ -4580,13 +4585,14 @@ var CODEX_ADDENDUM_CODE_MODE = [
   "declare the SDK absent without attempting discovery and invocation. The SDK",
   "call runs a TypeScript program against the ambient `cabane` object. The",
   "turn-control verbs (`ask`, `wake_me`, `summon_agent`, `skip_turn`) are",
-  "qualified `mcp__cabane_companion__\u2026` tools (and may be deferred too). There is",
-  "no Cabane `read`/`write`/`search`/`edit` tool here \u2014 those",
-  "are `cabane` SDK calls inside your program, not tools. If a tool appears in this",
-  "prompt with an `mcp__\u2026__` prefix, preserve that qualified name. Write your",
-  "closing reply as the last thing you say in the",
-  "turn: you can interleave narration with tool calls, but only your final message",
-  "is recorded as the turn\u2019s reply."
+  "qualified `mcp__cabane_companion__\u2026` tools (and may be deferred too), as are",
+  "the few ancillary cabane tools (`mcp__cabane__list_workspaces`,",
+  "`mcp__cabane__read_binary`, the upload tools, `mcp__cabane__mint_render_token`).",
+  "There is no Cabane `read`/`write`/`search`/`edit` tool here \u2014 those are `cabane`",
+  "SDK calls inside your program, not tools. If a tool appears in this prompt with",
+  "an `mcp__\u2026__` prefix, preserve that qualified name. Write your closing reply as",
+  "the last thing you say in the turn: you can interleave narration with tool",
+  "calls, but only your final message is recorded as the turn\u2019s reply."
 ].join(" ");
 
 // packages/agent-runtime/src/codex/events.ts
@@ -4895,10 +4901,16 @@ function buildRunSpec2(req, resumeThreadId) {
   const { policy, config } = req;
   const directory = req.local.cwd ?? "";
   const dialect = readCodexDialect(config.runtimeOptions);
+  const model = config.model ? parseCodexModel(config.model) : null;
+  if (model === null) {
+    console.warn(
+      `[agent-runtime/codex] CT823: dispatching a subscription turn with NO concrete model (config.model=${JSON.stringify(config.model)}) \u2014 Codex will fall back to its own default. This should be unreachable post-CT823; the model resolver should have supplied a concrete house default.`
+    );
+  }
   return {
     resumeThreadId,
     directory,
-    model: config.model ? parseCodexModel(config.model) : null,
+    model,
     policy: codexToolPolicy(policy),
     skipGitRepoCheck: true,
     ...dialect.modelReasoningEffort ? { modelReasoningEffort: dialect.modelReasoningEffort } : {},
@@ -5566,7 +5578,7 @@ function createCodexAdapter(deps = {}) {
     name: "codex",
     // CT614: surface-aware — a code-mode turn (only `code` mounted) is taught
     // `code`, not the granular names it no longer has.
-    promptAddendum: (codeMode = false) => codeMode ? CODEX_ADDENDUM_CODE_MODE : CODEX_ADDENDUM,
+    promptAddendum: () => CODEX_ADDENDUM,
     dialectSchema: codexDialectSchema,
     async *runTurn(req, signal) {
       if (!transport) {
@@ -7319,7 +7331,10 @@ ${reason}`,
       ...this.opts.local.claudeCode ? { claudeCode: this.opts.local.claudeCode } : {}
     });
     const onWarn = (msg, meta) => turnLog.warn(meta ?? {}, msg);
-    const adapters = [createClaudeCodeAdapter({ queryFn: this.opts.queryFn, onWarn })];
+    const adapters = [];
+    if (this.opts.claudeCodeAvailable?.() ?? true) {
+      adapters.push(createClaudeCodeAdapter({ queryFn: this.opts.queryFn, onWarn }));
+    }
     if (this.opts.opencodeServerUrl) {
       adapters.push(createOpencodeAdapter({ serverUrl: this.opts.opencodeServerUrl, onWarn }));
     }
@@ -7868,8 +7883,8 @@ async function probeHarnessSignals(cfg, deps = {}) {
   return {
     claudeOnPath: claudeOnPathResult,
     claudeVersion,
-    // A parseable `codex --version` is our presence signal (codex isn't the
-    // default runtime; its config flag is the manifest gate either way).
+    // A parseable `codex --version` is our presence signal (presence alone never
+    // exposes codex; its config flag is the manifest gate either way).
     codexOnPath: codexVersion !== null,
     codexVersion,
     codexEnabled: isCodexEnabled(cfg),
@@ -8372,7 +8387,7 @@ var CompanionSupervisor = class {
           // until the first re-probe lands. Same exit-0 `claude --version` signal
           // either way, so the manifest's claude-code advertising is unchanged in
           // meaning — just refreshed on the beat instead of frozen at boot.
-          claudeCode: this.harnessSignals?.claudeOnPath ?? this.claudeCode,
+          claudeCode: this.claudeCodePresent(),
           opencode: !!this.config.opencode?.serverUrl,
           // CT481: advertise codex when the operator enabled it (config-gated,
           // like opencode — the CLI's presence is the operator's responsibility;
@@ -8595,6 +8610,13 @@ var CompanionSupervisor = class {
       "companion: stopped agent (unassigned)"
     );
   }
+  // CT833: is Claude Code on this machine right now? The ONE signal both the
+  // heartbeat manifest and the dispatcher's adapter registry read, so what the
+  // device advertises and what it can actually select can't disagree. Live (the
+  // per-beat re-probe), falling back to the boot probe until the first one lands.
+  claudeCodePresent() {
+    return this.harnessSignals?.claudeOnPath ?? this.claudeCode;
+  }
   buildDispatcher(ctx) {
     if (this.dispatcherFactory) return this.dispatcherFactory(ctx);
     return new Dispatcher({
@@ -8612,6 +8634,10 @@ var CompanionSupervisor = class {
       }),
       runConfig: ctx.runConfig,
       log: this.log,
+      // CT833: register the claude-code adapter only when `claude` is actually on
+      // this machine — read per turn (not captured here), so a harness installed
+      // after boot works on the next turn exactly as it appears on the next beat.
+      claudeCodeAvailable: () => this.claudeCodePresent(),
       // CT270: the opencode server URL (operator-configured), when this device
       // offers the opencode runtime. Threaded so an opencode turn selects the
       // opencode adapter; unset leaves the device claude-code-only.

package/dist/runtime.js

@@ -979,8 +979,20 @@ async function claudeOnPath() {
     });
   });
 }
+var CODEX_PROBE_TIMEOUT_MS = 4e3;
+async function codexOnPath() {
+  const version = await Promise.race([
+    probeCliVersion("codex"),
+    new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(null), CODEX_PROBE_TIMEOUT_MS);
+      timer.unref?.();
+    })
+  ]);
+  return version !== null;
+}
 async function ensureRuntimeAvailable(cfg, deps = {}) {
   const probeClaude = deps.probeClaude ?? claudeOnPath;
+  const probeCodex = deps.probeCodex ?? codexOnPath;
   const warn = deps.warn ?? ((message) => process.stderr.write(`${message}
 `));
   if (await probeClaude()) return;
@@ -989,15 +1001,15 @@ async function ensureRuntimeAvailable(cfg, deps = {}) {
     ...isCodexEnabled(cfg) ? ["codex"] : []
   ];
   if (alternates.length > 0) {
+    const exposed = alternates.join(" + ");
     warn(
-      `warning: Claude Code isn\u2019t on your PATH, so this device will run ${alternates.join(
-        " + "
-      )} only \u2014 it advertises just those runtimes, so assign it matching models (a Claude-model agent won\u2019t be routed here). Install Claude Code (\`npm i -g @anthropic-ai/claude-code\`) if you want it to run Claude models too.`
+      `warning: Claude Code isn\u2019t on your PATH, so this device exposes ${exposed} only \u2014 it advertises nothing else, so a Claude-model agent won\u2019t be routed here. Assign it agents on models ${exposed} can run, or install Claude Code (\`npm i -g @anthropic-ai/claude-code\`) and log in if you want this device to run Claude models too.`
     );
     return;
   }
+  const installedButUnexposed = await probeCodex() ? 'Codex is installed on this machine but not exposed \u2014 enable it with `{ "codex": { "enabled": true } }` in ~/.cabane/config.json. Otherwise, expose a harness:\n' : "Expose at least one:\n";
   throw new CompanionError(
-    "Claude Code, the companion\u2019s default runtime, is not on your PATH. Install it with `npm i -g @anthropic-ai/claude-code`, log in (`claude` then follow the prompts), and run `cabane-companion start` again. The default runtime uses your local Claude Code subscription to run each agent turn; opencode is supported as an alternate runtime you configure per device (see the companion README)."
+    "This device exposes no harness, so no agent turn can run here. " + installedButUnexposed + '  \u2022 Claude Code \u2014 install it (`npm i -g @anthropic-ai/claude-code`) and log in (`claude`, then follow the prompts); it\u2019s exposed automatically once `claude` is on your PATH.\n  \u2022 Codex \u2014 install the Codex CLI and log in (`codex login`), then add `{ "codex": { "enabled": true } }` to ~/.cabane/config.json.\n  \u2022 opencode \u2014 run `opencode serve --port 4096`, then add `{ "opencode": { "serverUrl": "http://127.0.0.1:4096" } }` to ~/.cabane/config.json.\nThen run `cabane-companion start` again (see the companion README).'
   );
 }
 
@@ -2627,6 +2639,11 @@ function buildClaudeCodeOptions(req, augment) {
   const freshReason = "fresh" in resumeDecision ? resumeDecision.reason : void 0;
   const devControlsAutoMemory = req.local.claudeCode?.autoMemory === true;
   const model = parseClaudeCodeModel(config.model);
+  if (model === null) {
+    console.warn(
+      `[agent-runtime/claude-code] CT823: dispatching a subscription turn with NO concrete model (config.model=${JSON.stringify(config.model)}) \u2014 the SDK will fall back to its bundled default. This should be unreachable post-CT823; the model resolver should have supplied a concrete house default.`
+    );
+  }
   const base = {
     // model / effort: `model` is pinned only when the config names a real one —
     // omitted for "let it choose" (see `parseClaudeCodeModel`), so the SDK picks
@@ -3248,26 +3265,20 @@ function selectAdapter(registry, runtime) {
 
 // packages/agent-runtime/src/opencode/addendum.ts
 var OPENCODE_ADDENDUM = [
-  "Your Cabane tools have plain names \u2014 `read`, `write`, `search`, `edit`,",
-  "`post_message`, and so on; the host tools are plain verbs too (`bash`, `read`,",
-  "`edit`). If a tool appears in this prompt with an `mcp__\u2026__` prefix, that",
+  "Your one Cabane workspace tool has a plain name \u2014 `sdk` (you act on the",
+  "workspace by writing a TypeScript program and calling `sdk` with it); the",
+  "turn-control verbs (`ask`, `wake_me`, `summon_agent`, `skip_turn`) are",
+  "plain-named too, as are the few ancillary cabane tools (`list_workspaces`,",
+  "`read_binary`, `upload`, `begin_upload`, `finalize_upload`,",
+  "`mint_render_token`), and the host tools are plain verbs (`bash`, `read`,",
+  "`edit`). There is no `write`/`search`/`edit` CABANE tool here \u2014 those are",
+  "`cabane` SDK calls inside your program, not tools (a bare `read`/`edit` is the",
+  "HOST tool). If a tool appears in this prompt with an `mcp__\u2026__` prefix, that",
   "prefix is not part of its name \u2014 call the tool by its plain verb. Write your",
   "closing reply as the last thing you say in the turn: you can interleave",
   "narration with tool calls, but only your final message is recorded as the",
   "turn\u2019s reply."
 ].join(" ");
-var OPENCODE_ADDENDUM_CODE_MODE = [
-  "Your one Cabane workspace tool has a plain name \u2014 `sdk` (you act on the",
-  "workspace by writing a TypeScript program and calling `sdk` with it); the",
-  "turn-control verbs (`ask`, `wake_me`, `summon_agent`, `skip_turn`) are",
-  "plain-named too, and the host tools are plain verbs (`bash`, `read`, `edit`).",
-  "There is no `write`/`search`/`edit` CABANE tool here \u2014 those are `cabane` SDK",
-  "calls inside your program, not tools (a bare `read`/`edit` is the HOST tool). If",
-  "a tool appears in this prompt with an `mcp__\u2026__` prefix, that prefix is not part",
-  "of its name \u2014 call the tool by its plain verb. Write your closing reply as the",
-  "last thing you say in the turn: you can interleave narration with tool calls, but",
-  "only your final message is recorded as the turn\u2019s reply."
-].join(" ");
 
 // packages/agent-runtime/src/opencode/events.ts
 function asRecord(v) {
@@ -3819,7 +3830,7 @@ function createOpencodeAdapter(deps = {}) {
     name: "opencode",
     // CT614: surface-aware — a code-mode turn (only `code` mounted) is taught
     // `code`, not the granular cabane names it no longer has.
-    promptAddendum: (codeMode = false) => codeMode ? OPENCODE_ADDENDUM_CODE_MODE : OPENCODE_ADDENDUM,
+    promptAddendum: () => OPENCODE_ADDENDUM,
     dialectSchema: opencodeDialectSchema,
     async *runTurn(req, signal) {
       if (!transport) {
@@ -4219,14 +4230,6 @@ var OPENCODE_CONFORMANCE_FIXTURES = [
 
 // packages/agent-runtime/src/codex/addendum.ts
 var CODEX_ADDENDUM = [
-  "Your Cabane tools have plain names \u2014 `read`, `write`, `search`, `edit`,",
-  "`post_message`, and so on. If a tool appears in this prompt with an `mcp__\u2026__`",
-  "prefix, that prefix is not part of its name \u2014 call the tool by its plain verb.",
-  "Write your closing reply as the last thing you say in the turn: you can",
-  "interleave narration with tool calls, but only your final message is recorded",
-  "as the turn\u2019s reply."
-].join(" ");
-var CODEX_ADDENDUM_CODE_MODE = [
   "Your Cabane workspace tool is exposed to Codex as the qualified MCP tool",
   "`mcp__cabane__sdk`. On Codex versions that defer MCP tools, locate it in the",
   "`functions.exec` deferred-tool inventory and invoke that exact qualified tool",
@@ -4235,13 +4238,14 @@ var CODEX_ADDENDUM_CODE_MODE = [
   "declare the SDK absent without attempting discovery and invocation. The SDK",
   "call runs a TypeScript program against the ambient `cabane` object. The",
   "turn-control verbs (`ask`, `wake_me`, `summon_agent`, `skip_turn`) are",
-  "qualified `mcp__cabane_companion__\u2026` tools (and may be deferred too). There is",
-  "no Cabane `read`/`write`/`search`/`edit` tool here \u2014 those",
-  "are `cabane` SDK calls inside your program, not tools. If a tool appears in this",
-  "prompt with an `mcp__\u2026__` prefix, preserve that qualified name. Write your",
-  "closing reply as the last thing you say in the",
-  "turn: you can interleave narration with tool calls, but only your final message",
-  "is recorded as the turn\u2019s reply."
+  "qualified `mcp__cabane_companion__\u2026` tools (and may be deferred too), as are",
+  "the few ancillary cabane tools (`mcp__cabane__list_workspaces`,",
+  "`mcp__cabane__read_binary`, the upload tools, `mcp__cabane__mint_render_token`).",
+  "There is no Cabane `read`/`write`/`search`/`edit` tool here \u2014 those are `cabane`",
+  "SDK calls inside your program, not tools. If a tool appears in this prompt with",
+  "an `mcp__\u2026__` prefix, preserve that qualified name. Write your closing reply as",
+  "the last thing you say in the turn: you can interleave narration with tool",
+  "calls, but only your final message is recorded as the turn\u2019s reply."
 ].join(" ");
 
 // packages/agent-runtime/src/codex/events.ts
@@ -4550,10 +4554,16 @@ function buildRunSpec2(req, resumeThreadId) {
   const { policy, config } = req;
   const directory = req.local.cwd ?? "";
   const dialect = readCodexDialect(config.runtimeOptions);
+  const model = config.model ? parseCodexModel(config.model) : null;
+  if (model === null) {
+    console.warn(
+      `[agent-runtime/codex] CT823: dispatching a subscription turn with NO concrete model (config.model=${JSON.stringify(config.model)}) \u2014 Codex will fall back to its own default. This should be unreachable post-CT823; the model resolver should have supplied a concrete house default.`
+    );
+  }
   return {
     resumeThreadId,
     directory,
-    model: config.model ? parseCodexModel(config.model) : null,
+    model,
     policy: codexToolPolicy(policy),
     skipGitRepoCheck: true,
     ...dialect.modelReasoningEffort ? { modelReasoningEffort: dialect.modelReasoningEffort } : {},
@@ -5221,7 +5231,7 @@ function createCodexAdapter(deps = {}) {
     name: "codex",
     // CT614: surface-aware — a code-mode turn (only `code` mounted) is taught
     // `code`, not the granular names it no longer has.
-    promptAddendum: (codeMode = false) => codeMode ? CODEX_ADDENDUM_CODE_MODE : CODEX_ADDENDUM,
+    promptAddendum: () => CODEX_ADDENDUM,
     dialectSchema: codexDialectSchema,
     async *runTurn(req, signal) {
       if (!transport) {
@@ -6974,7 +6984,10 @@ ${reason}`,
       ...this.opts.local.claudeCode ? { claudeCode: this.opts.local.claudeCode } : {}
     });
     const onWarn = (msg, meta) => turnLog.warn(meta ?? {}, msg);
-    const adapters = [createClaudeCodeAdapter({ queryFn: this.opts.queryFn, onWarn })];
+    const adapters = [];
+    if (this.opts.claudeCodeAvailable?.() ?? true) {
+      adapters.push(createClaudeCodeAdapter({ queryFn: this.opts.queryFn, onWarn }));
+    }
     if (this.opts.opencodeServerUrl) {
       adapters.push(createOpencodeAdapter({ serverUrl: this.opts.opencodeServerUrl, onWarn }));
     }
@@ -7523,8 +7536,8 @@ async function probeHarnessSignals(cfg, deps = {}) {
   return {
     claudeOnPath: claudeOnPathResult,
     claudeVersion,
-    // A parseable `codex --version` is our presence signal (codex isn't the
-    // default runtime; its config flag is the manifest gate either way).
+    // A parseable `codex --version` is our presence signal (presence alone never
+    // exposes codex; its config flag is the manifest gate either way).
     codexOnPath: codexVersion !== null,
     codexVersion,
     codexEnabled: isCodexEnabled(cfg),
@@ -8027,7 +8040,7 @@ var CompanionSupervisor = class {
           // until the first re-probe lands. Same exit-0 `claude --version` signal
           // either way, so the manifest's claude-code advertising is unchanged in
           // meaning — just refreshed on the beat instead of frozen at boot.
-          claudeCode: this.harnessSignals?.claudeOnPath ?? this.claudeCode,
+          claudeCode: this.claudeCodePresent(),
           opencode: !!this.config.opencode?.serverUrl,
           // CT481: advertise codex when the operator enabled it (config-gated,
           // like opencode — the CLI's presence is the operator's responsibility;
@@ -8250,6 +8263,13 @@ var CompanionSupervisor = class {
       "companion: stopped agent (unassigned)"
     );
   }
+  // CT833: is Claude Code on this machine right now? The ONE signal both the
+  // heartbeat manifest and the dispatcher's adapter registry read, so what the
+  // device advertises and what it can actually select can't disagree. Live (the
+  // per-beat re-probe), falling back to the boot probe until the first one lands.
+  claudeCodePresent() {
+    return this.harnessSignals?.claudeOnPath ?? this.claudeCode;
+  }
   buildDispatcher(ctx) {
     if (this.dispatcherFactory) return this.dispatcherFactory(ctx);
     return new Dispatcher({
@@ -8267,6 +8287,10 @@ var CompanionSupervisor = class {
       }),
       runConfig: ctx.runConfig,
       log: this.log,
+      // CT833: register the claude-code adapter only when `claude` is actually on
+      // this machine — read per turn (not captured here), so a harness installed
+      // after boot works on the next turn exactly as it appears on the next beat.
+      claudeCodeAvailable: () => this.claudeCodePresent(),
       // CT270: the opencode server URL (operator-configured), when this device
       // offers the opencode runtime. Threaded so an opencode turn selects the
       // opencode adapter; unset leaves the device claude-code-only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "type": "module",
   "description": "The Cabane Companion (headless): connect a coding agent on your machine to your Cabane workspace as a responder — drive work against your own codebase, files, and MCP servers without putting any of it in Cabane.",
   "license": "UNLICENSED",