@cabane/companion 0.6.32 → 0.6.34

package/dist/runtime.js

@@ -287,10 +287,11 @@ var companionConfigSchema = z2.object({
   // device with no device-level entry behaves exactly as it did before. A hook
   // that fails still fails the dispatch loudly, as now.
   prepareHook: prepareHookSchema.optional(),
-  // Dashboard settings (all optional). dashboardPort: preferred bind port (next
-  // free one if taken); autoOpen: whether `start` opens the browser (the
-  // `--no-open` flag / `COMPANION_NO_OPEN=1` override per-run); logLevel: pino
-  // level, live-editable from the dashboard settings panel.
+  // CT1085 §9: `dashboardPort` and `autoOpen` are READ AND IGNORED by the CLI —
+  // it binds no port and opens no browser. They stay in the schema (rather than
+  // becoming a strict-mode parse error on an existing config file) and still mean
+  // what they say to the Electron shell, the one front-end that renders a
+  // dashboard. `logLevel` is unaffected: pino level, live-editable.
   dashboardPort: z2.number().int().min(1).max(65535).optional(),
   autoOpen: z2.boolean().optional(),
   logLevel: z2.enum(["warn", "info", "debug"]).optional(),
@@ -950,6 +951,163 @@ function resolveStaticDir() {
   return join4(dirname3(fileURLToPath(import.meta.url)), "static");
 }
 
+// src/control-socket.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync3, rmSync as rmSync2, mkdirSync as mkdirSync3 } from "fs";
+import { createServer, connect } from "net";
+import { join as join5 } from "path";
+var CONTROL_TIMEOUT_MS = 1e3;
+function controlSocketPath() {
+  const dir2 = cabaneDir();
+  if (process.platform === "win32") {
+    const key = createHash("sha256").update(dir2).digest("hex").slice(0, 16);
+    return `\\\\.\\pipe\\cabane-companion-${key}`;
+  }
+  return join5(dir2, "companion.sock");
+}
+async function startControlServer(handlers) {
+  const path = controlSocketPath();
+  mkdirSync3(cabaneDir(), { recursive: true });
+  if (process.platform !== "win32" && existsSync3(path)) {
+    const alive = await ping(path);
+    if (alive) throw new Error(`another companion is already listening on ${path}`);
+    rmSync2(path, { force: true });
+  }
+  const server = createServer((socket) => {
+    void serveConnection(socket, handlers);
+  });
+  server.unref();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(path, () => {
+      server.removeListener("error", reject);
+      resolve();
+    });
+  });
+  server.on("error", () => {
+  });
+  return {
+    path,
+    close: () => new Promise((resolve) => {
+      server.close(() => {
+        if (process.platform !== "win32") rmSync2(path, { force: true });
+        resolve();
+      });
+    })
+  };
+}
+async function serveConnection(socket, handlers) {
+  socket.on("error", () => socket.destroy());
+  const line = await readLine(socket, CONTROL_TIMEOUT_MS * 5);
+  if (line === null) {
+    socket.destroy();
+    return;
+  }
+  let req;
+  try {
+    req = JSON.parse(line);
+  } catch {
+    reply(socket, { error: "malformed request" });
+    return;
+  }
+  try {
+    if (req.cmd === "status") {
+      reply(socket, handlers.status());
+      return;
+    }
+    if (req.cmd === "connect") {
+      const result = await handlers.connect(req.runtime, req.serverUrl);
+      reply(socket, result);
+      return;
+    }
+    if (req.cmd === "stop") {
+      reply(socket, { ok: true });
+      setTimeout(() => handlers.stop(), 50).unref?.();
+      return;
+    }
+    reply(socket, { error: `unknown command "${String(req.cmd)}"` });
+  } catch (err) {
+    reply(socket, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+function reply(socket, body) {
+  try {
+    socket.end(`${JSON.stringify(body)}
+`);
+  } catch {
+    socket.destroy();
+  }
+}
+async function controlRequest(path, req, timeoutMs = CONTROL_TIMEOUT_MS) {
+  const socket = connect(path);
+  try {
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new ControlTimeout()), timeoutMs);
+      timer.unref?.();
+      socket.once("connect", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      socket.once("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+    socket.write(`${JSON.stringify(req)}
+`);
+    const line = await readLine(socket, timeoutMs);
+    if (line === null) throw new ControlTimeout();
+    return JSON.parse(line);
+  } finally {
+    socket.destroy();
+  }
+}
+var ControlTimeout = class extends Error {
+  constructor() {
+    super("the companion did not answer its control socket in time");
+    this.name = "ControlTimeout";
+  }
+};
+function isNotListening(err) {
+  const code = err?.code;
+  return code === "ENOENT" || code === "ECONNREFUSED";
+}
+function readLine(socket, timeoutMs) {
+  return new Promise((resolve) => {
+    let buf = "";
+    let settled = false;
+    const done = (v) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeListener("data", onData);
+      resolve(v);
+    };
+    const timer = setTimeout(() => done(null), timeoutMs);
+    timer.unref?.();
+    const onData = (chunk) => {
+      buf += chunk.toString("utf8");
+      const nl = buf.indexOf("\n");
+      if (nl >= 0) done(buf.slice(0, nl));
+      else if (buf.length > 1e6) done(null);
+    };
+    socket.on("data", onData);
+    socket.once("close", () => done(null));
+    socket.once("error", () => done(null));
+  });
+}
+async function ping(path) {
+  try {
+    await controlRequest(path, { cmd: "status" });
+    return true;
+  } catch (err) {
+    return !isNotListening(err);
+  }
+}
+
+// src/harness-check.ts
+import { spawn as spawn4 } from "child_process";
+
 // src/harness-versions.ts
 import { spawn as spawn2 } from "child_process";
 var EMPTY = { claudeCode: null, opencode: null, codex: null };
@@ -1031,6 +1189,20 @@ async function safe(fn) {
   }
 }
 
+// src/manifest.ts
+var DEVICE_MANIFEST = {
+  runtimes: [{ name: "claude-code", version: null }],
+  capabilities: { hostFs: true, browser: true, userMcp: true }
+};
+function buildCompanionManifest(opts) {
+  const v = opts.versions ?? {};
+  const runtimes = [];
+  if (opts.claudeCode) runtimes.push({ name: "claude-code", version: v.claudeCode ?? null });
+  if (opts.opencode) runtimes.push({ name: "opencode", version: v.opencode ?? null });
+  if (opts.codex) runtimes.push({ name: "codex", version: v.codex ?? null });
+  return { runtimes, capabilities: { ...DEVICE_MANIFEST.capabilities } };
+}
+
 // src/prereqs.ts
 import { spawn as spawn3 } from "child_process";
 async function claudeOnPath() {
@@ -1102,33 +1274,292 @@ async function warnAboutHarnessReadiness(cfg, deps = {}) {
   );
 }
 
+// src/harness-status.ts
+var HARNESS_LABELS = {
+  "claude-code": "Claude Code",
+  codex: "Codex",
+  opencode: "opencode"
+};
+var LABELS = HARNESS_LABELS;
+function deriveHarnessSnapshot(signals) {
+  const advertised = new Set(
+    buildCompanionManifest({
+      // CT1082: connected AND installed — the manifest's own rule, restated here
+      // through the same function rather than re-decided.
+      claudeCode: signals.claudeCodeConnected && signals.claudeOnPath,
+      opencode: signals.opencodeConfigured,
+      codex: signals.codexEnabled
+    }).runtimes.map((r) => r.name)
+  );
+  const harnesses = [
+    deriveClaudeCode(signals, advertised.has("claude-code")),
+    deriveCodex(signals, advertised.has("codex")),
+    deriveOpencode(signals, advertised.has("opencode"))
+  ];
+  return { harnesses, anyExposed: harnesses.some((h) => h.state === "exposed") };
+}
+function deriveClaudeCode(signals, manifestHas) {
+  const base = { runtime: "claude-code", label: LABELS["claude-code"] };
+  if (manifestHas) {
+    return {
+      ...base,
+      state: "exposed",
+      version: signals.claudeVersion,
+      detail: "Claude Code is connected and exposed to Cabane.",
+      enable: null
+    };
+  }
+  if (signals.claudeCodeConnected) {
+    return {
+      ...base,
+      state: "needs_attention",
+      version: null,
+      detail: "Connected, but the `claude` CLI isn\u2019t on your PATH. Install it (`npm i -g @anthropic-ai/claude-code`) and sign in, or disconnect it.",
+      enable: null
+    };
+  }
+  if (signals.claudeOnPath) {
+    return {
+      ...base,
+      state: "detected_not_exposed",
+      version: signals.claudeVersion,
+      detail: "Claude Code is installed here but not connected yet. Connect it to let Cabane run Claude Code on this device.",
+      enable: "claude-code"
+    };
+  }
+  return {
+    ...base,
+    state: "not_detected",
+    version: null,
+    detail: "Not detected. Install Claude Code (`npm i -g @anthropic-ai/claude-code`) and sign in with `claude`, then connect it here.",
+    enable: null
+  };
+}
+function deriveCodex(signals, manifestHas) {
+  const base = { runtime: "codex", label: LABELS.codex };
+  if (manifestHas) {
+    if (signals.codexOnPath) {
+      return {
+        ...base,
+        state: "exposed",
+        version: signals.codexVersion,
+        detail: "Codex is enabled and exposed to Cabane.",
+        enable: null
+      };
+    }
+    return {
+      ...base,
+      state: "needs_attention",
+      version: null,
+      detail: "Enabled, but the `codex` CLI isn\u2019t on your PATH. Install it and sign in (`codex login`), or turn Codex off.",
+      enable: null
+    };
+  }
+  if (signals.codexOnPath) {
+    return {
+      ...base,
+      state: "detected_not_exposed",
+      version: signals.codexVersion,
+      detail: "Codex is installed but not exposed yet. Turn it on to let Cabane run Codex here.",
+      enable: "codex"
+    };
+  }
+  return {
+    ...base,
+    state: "not_detected",
+    version: null,
+    detail: "Not detected. Install the Codex CLI and sign in (`codex login`), then enable it here.",
+    enable: null
+  };
+}
+function deriveOpencode(signals, manifestHas) {
+  const base = { runtime: "opencode", label: LABELS.opencode };
+  if (manifestHas) {
+    if (signals.opencodeReachable) {
+      return {
+        ...base,
+        state: "exposed",
+        version: signals.opencodeVersion,
+        detail: "An opencode server is reachable and exposed to Cabane.",
+        enable: null
+      };
+    }
+    return {
+      ...base,
+      state: "needs_attention",
+      version: null,
+      detail: "Configured, but the opencode server isn\u2019t answering. Start `opencode serve` and check the URL.",
+      enable: null
+    };
+  }
+  return {
+    ...base,
+    state: "not_detected",
+    version: null,
+    detail: "Not detected. Run `opencode serve` and add its URL here to expose opencode.",
+    enable: "opencode"
+  };
+}
+function detectedRuntimesFor(snapshot) {
+  return snapshot.harnesses.filter((h) => h.state === "detected_not_exposed").map((h) => ({ runtime: h.runtime, version: h.version }));
+}
+var PROBE_TIMEOUT_MS = 4e3;
+async function probeHarnessSignals(cfg, deps = {}) {
+  const probeClaudePresence = deps.probeClaudePresence ?? claudeOnPath;
+  const probeClaudeVersion = deps.probeClaudeVersion ?? (() => probeCliVersion("claude"));
+  const probeCodexVersion = deps.probeCodexVersion ?? (() => probeCliVersion("codex"));
+  const probeOpencode = deps.probeOpencode ?? ((url) => probeOpencodeVersion(url));
+  const serverUrl = cfg.opencode?.serverUrl;
+  const [claudeOnPathResult, claudeVersion, codexVersion, opencodeVersion] = await Promise.all([
+    withTimeout(probeClaudePresence(), false),
+    withTimeout(probeClaudeVersion(), null),
+    withTimeout(probeCodexVersion(), null),
+    serverUrl ? withTimeout(probeOpencode(serverUrl), null) : Promise.resolve(null)
+  ]);
+  return {
+    claudeOnPath: claudeOnPathResult,
+    claudeVersion,
+    // CT1082: the user's opt-in. Presence alone exposes nothing now, so this is
+    // the manifest gate and the probe above is only a suggestion.
+    claudeCodeConnected: isClaudeCodeConnected(cfg),
+    // 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),
+    opencodeConfigured: !!serverUrl,
+    // A version came back ⟺ the serve answered its health endpoint (CT584).
+    opencodeReachable: opencodeVersion !== null,
+    opencodeVersion
+  };
+}
+function withTimeout(promise, fallback) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => {
+      if (!settled) {
+        settled = true;
+        resolve(v);
+      }
+    };
+    const timer = setTimeout(() => done(fallback), PROBE_TIMEOUT_MS);
+    timer.unref?.();
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        done(v);
+      },
+      () => {
+        clearTimeout(timer);
+        done(fallback);
+      }
+    );
+  });
+}
+
+// src/harness-check.ts
+var CHECK_TIMEOUT_MS = 4e3;
+async function shakeOutHarness(runtime, cfg, deps = {}) {
+  const run = deps.run ?? runBounded;
+  const probeOpencode = deps.probeOpencode ?? ((url) => probeOpencodeVersion(url));
+  try {
+    if (runtime === "opencode") {
+      const url = cfg.opencode?.serverUrl;
+      if (!url) return "failed";
+      return await probeOpencode(url) !== null ? "ok" : "failed";
+    }
+    const { auth, presence } = runtime === "codex" ? {
+      auth: ["codex", ["login", "status"]],
+      presence: ["codex", ["--version"]]
+    } : {
+      auth: ["claude", ["auth", "status"]],
+      presence: ["claude", ["--version"]]
+    };
+    const authRun = await run(auth[0], [...auth[1]]);
+    if (authRun.code === 0) return "ok";
+    if (looksUnsupported(authRun.output)) {
+      const presenceRun = await run(presence[0], [...presence[1]]);
+      return presenceRun.code === 0 ? "unverified" : "failed";
+    }
+    return "failed";
+  } catch {
+    return "unverified";
+  }
+}
+function connectedLine(runtime, verdict) {
+  const label = HARNESS_LABELS[runtime];
+  if (verdict !== "failed") return `${label} connected.`;
+  return `${label} connected \u2014 ${FAILED_SUFFIX[runtime]}`;
+}
+var FAILED_SUFFIX = {
+  "claude-code": "it doesn\u2019t look signed in yet. Run `claude` once and sign in, then it\u2019s ready.",
+  codex: "it doesn\u2019t look signed in yet. Run `codex login` once, then it\u2019s ready.",
+  opencode: "its server isn\u2019t answering. Start `opencode serve`, then it\u2019s ready."
+};
+function looksUnsupported(output) {
+  return /unrecognized|unknown (sub)?command|unexpected argument|invalid (sub)?command|no such (sub)?command|usage:|did you mean/i.test(
+    output
+  );
+}
+function runBounded(command, args) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (code, output) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code, output });
+    };
+    let child;
+    try {
+      child = spawn4(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    } catch {
+      resolve({ code: null, output: "" });
+      return;
+    }
+    let out = "";
+    const capture = (chunk) => {
+      if (out.length < 4096) out += chunk.toString();
+    };
+    child.stdout?.on("data", capture);
+    child.stderr?.on("data", capture);
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      done(null, out);
+    }, CHECK_TIMEOUT_MS);
+    timer.unref?.();
+    child.once("error", () => done(null, out));
+    child.once("exit", (code) => done(code, out));
+  });
+}
+
 // src/runtime-file.ts
 import {
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   readFileSync as readFileSync2,
-  rmSync as rmSync2,
+  rmSync as rmSync3,
   writeFileSync as writeFileSync2,
-  mkdirSync as mkdirSync3,
+  mkdirSync as mkdirSync4,
   openSync as openSync2,
   closeSync as closeSync2
 } from "fs";
-import { join as join5 } from "path";
-var PROBE_TIMEOUT_MS = 1e3;
+import { join as join6 } from "path";
+var PROBE_TIMEOUT_MS2 = 1e3;
 function runtimePath() {
-  return join5(cabaneDir(), "runtime.json");
+  return join6(cabaneDir(), "runtime.json");
 }
 function serialize(state) {
   return JSON.stringify(state, null, 2) + "\n";
 }
 function writeRuntimeState(state) {
   const path = runtimePath();
-  mkdirSync3(cabaneDir(), { recursive: true });
+  mkdirSync4(cabaneDir(), { recursive: true });
   writeFileSync2(path, serialize(state), "utf8");
 }
 function acquireRuntimeState(state) {
   const live = readLiveRuntimeState();
   if (live) return { acquired: false, existing: live };
-  mkdirSync3(cabaneDir(), { recursive: true });
+  mkdirSync4(cabaneDir(), { recursive: true });
   let fd;
   try {
     fd = openSync2(runtimePath(), "wx");
@@ -1144,11 +1575,21 @@ function acquireRuntimeState(state) {
 }
 function clearRuntimeState() {
   const path = runtimePath();
-  if (existsSync3(path)) rmSync2(path, { force: true });
+  if (existsSync4(path)) rmSync3(path, { force: true });
+}
+function clearRuntimeStateIfOurs(instanceId) {
+  const path = runtimePath();
+  if (!existsSync4(path)) return;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    if (parsed.instanceId && parsed.instanceId !== instanceId) return;
+  } catch {
+  }
+  rmSync3(path, { force: true });
 }
 function readLiveRuntimeState() {
   const path = runtimePath();
-  if (!existsSync3(path)) return null;
+  if (!existsSync4(path)) return null;
   let parsed;
   try {
     parsed = JSON.parse(readFileSync2(path, "utf8"));
@@ -1164,33 +1605,21 @@ function readLiveRuntimeState() {
   }
   return parsed;
 }
-async function verifyRuntime(state, fetchImpl = fetch) {
-  if (!state.instanceId) return "unknown";
-  const url = `${trimSlash(state.url)}/api/status`;
-  let res;
-  try {
-    res = await fetchImpl(url, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
-  } catch (err) {
-    return isConnRefused(err) ? "stale" : "unknown";
-  }
-  if (!res.ok) return "unknown";
+async function verifyRuntime(state, requestImpl = controlRequest) {
+  if (!state.instanceId || !state.socket) return "unknown";
   let body;
   try {
-    body = await res.json();
-  } catch {
-    return "unknown";
+    body = await requestImpl(
+      state.socket,
+      { cmd: "status" },
+      PROBE_TIMEOUT_MS2
+    );
+  } catch (err) {
+    return isNotListening(err) ? "stale" : "unknown";
   }
-  if (typeof body.instance_id !== "string") return "unknown";
+  if (typeof body?.instance_id !== "string") return "unknown";
   return body.instance_id === state.instanceId ? "ours" : "stale";
 }
-function isConnRefused(err) {
-  if (!err || typeof err !== "object") return false;
-  const cause = err.cause;
-  return !!cause && typeof cause === "object" && cause.code === "ECONNREFUSED";
-}
-function trimSlash(s) {
-  return s.endsWith("/") ? s.slice(0, -1) : s;
-}
 
 // src/api.ts
 var RETRY_BACKOFF_MS = [250, 750];
@@ -1667,22 +2096,22 @@ function errorMessage2(status, body) {
 // src/credentials.ts
 import {
   chmodSync as chmodSync2,
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync4,
+  existsSync as existsSync5,
+  mkdirSync as mkdirSync5,
   readFileSync as readFileSync3,
   renameSync as renameSync2,
-  rmSync as rmSync3,
+  rmSync as rmSync4,
   writeFileSync as writeFileSync3
 } from "fs";
-import { dirname as dirname4, join as join6 } from "path";
+import { dirname as dirname4, join as join7 } from "path";
 import { z as z3 } from "zod";
 function credentialsPath() {
-  return join6(cabaneDir(), "credentials.json");
+  return join7(cabaneDir(), "credentials.json");
 }
 var credentialStoreSchema = z3.record(z3.string(), z3.string());
 function load() {
   const path = credentialsPath();
-  if (!existsSync4(path)) return {};
+  if (!existsSync5(path)) return {};
   let raw;
   try {
     raw = readFileSync3(path, "utf8");
@@ -1699,7 +2128,7 @@ function load() {
 }
 function save(map) {
   const path = credentialsPath();
-  mkdirSync4(dirname4(path), { recursive: true });
+  mkdirSync5(dirname4(path), { recursive: true });
   try {
     chmodSync2(cabaneDir(), 448);
   } catch {
@@ -1714,7 +2143,7 @@ function save(map) {
     renameSync2(tmp, path);
   } catch (err) {
     try {
-      rmSync3(tmp, { force: true });
+      rmSync4(tmp, { force: true });
     } catch {
     }
     throw err;
@@ -1744,20 +2173,20 @@ function pruneCredentials(keepAgentIds) {
 }
 
 // src/cursor.ts
-import { mkdirSync as mkdirSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync5 } from "fs";
-import { join as join7 } from "path";
+import { mkdirSync as mkdirSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync6 } from "fs";
+import { join as join8 } from "path";
 function pathFor(workspaceId) {
-  return join7(cabaneDir(), "cursors", encodeURIComponent(workspaceId));
+  return join8(cabaneDir(), "cursors", encodeURIComponent(workspaceId));
 }
 function readCursor(workspaceId) {
   const path = pathFor(workspaceId);
-  if (!existsSync5(path)) return null;
+  if (!existsSync6(path)) return null;
   const raw = readFileSync4(path, "utf8").trim();
   return raw.length > 0 ? raw : null;
 }
 function writeCursor(workspaceId, eventId) {
   const path = pathFor(workspaceId);
-  mkdirSync5(join7(cabaneDir(), "cursors"), { recursive: true });
+  mkdirSync6(join8(cabaneDir(), "cursors"), { recursive: true });
   writeFileSync4(path, eventId + "\n", "utf8");
 }
 
@@ -1801,18 +2230,18 @@ var CursorTracker = class {
 };
 
 // src/dispatch-dedupe.ts
-import { mkdirSync as mkdirSync6, readFileSync as readFileSync5, writeFileSync as writeFileSync5, existsSync as existsSync6 } from "fs";
-import { join as join8 } from "path";
+import { mkdirSync as mkdirSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync5, existsSync as existsSync7 } from "fs";
+import { join as join9 } from "path";
 var MAX_IDS = 256;
 function dir(log) {
-  return join8(cabaneDir(), log);
+  return join9(cabaneDir(), log);
 }
 function pathFor2(log, workspaceId) {
-  return join8(dir(log), encodeURIComponent(workspaceId));
+  return join9(dir(log), encodeURIComponent(workspaceId));
 }
 function readIds(log, workspaceId) {
   const path = pathFor2(log, workspaceId);
-  if (!existsSync6(path)) return [];
+  if (!existsSync7(path)) return [];
   try {
     return readFileSync5(path, "utf8").split("\n").map((s) => s.trim()).filter((s) => s.length > 0);
   } catch {
@@ -1827,7 +2256,7 @@ function mark(log, workspaceId, eventId) {
   if (ids.includes(eventId)) return;
   ids.push(eventId);
   const trimmed = ids.length > MAX_IDS ? ids.slice(-MAX_IDS) : ids;
-  mkdirSync6(dir(log), { recursive: true });
+  mkdirSync7(dir(log), { recursive: true });
   writeFileSync5(pathFor2(log, workspaceId), trimmed.join("\n") + "\n", "utf8");
 }
 function hasDispatched(workspaceId, eventId) {
@@ -1844,15 +2273,15 @@ function markCompleted(workspaceId, eventId) {
 }
 var MAX_RESUME_ATTEMPTS = 3;
 function resumeDir() {
-  return join8(cabaneDir(), "resume-attempts");
+  return join9(cabaneDir(), "resume-attempts");
 }
 function resumePathFor(workspaceId) {
-  return join8(resumeDir(), encodeURIComponent(workspaceId));
+  return join9(resumeDir(), encodeURIComponent(workspaceId));
 }
 function readResumeCounts(workspaceId) {
   const out = /* @__PURE__ */ new Map();
   const path = resumePathFor(workspaceId);
-  if (!existsSync6(path)) return out;
+  if (!existsSync7(path)) return out;
   try {
     for (const line of readFileSync5(path, "utf8").split("\n")) {
       const trimmed = line.trim();
@@ -1874,7 +2303,7 @@ function bumpResumeAttempt(workspaceId, eventId) {
   counts.set(eventId, next);
   const entries = [...counts.entries()];
   const trimmed = entries.length > MAX_IDS ? entries.slice(-MAX_IDS) : entries;
-  mkdirSync6(resumeDir(), { recursive: true });
+  mkdirSync7(resumeDir(), { recursive: true });
   writeFileSync5(
     resumePathFor(workspaceId),
     trimmed.map(([id, c]) => `${id}	${c}`).join("\n") + "\n",
@@ -3766,7 +4195,7 @@ async function acquireServerTurnLock(url) {
   };
 }
 function createHttpOpencodeTransport(opts) {
-  const base = trimSlash2(opts.baseUrl);
+  const base = trimSlash(opts.baseUrl);
   const doFetch = opts.fetchImpl ?? fetch;
   return {
     async run(spec, signal) {
@@ -3912,7 +4341,7 @@ function belongsToSession(ev, sessionId) {
 function newOpencodeMessageId() {
   return `msg_${crypto.randomUUID().replace(/-/g, "")}`;
 }
-function trimSlash2(s) {
+function trimSlash(s) {
   return s.endsWith("/") ? s.slice(0, -1) : s;
 }
 
@@ -4662,7 +5091,13 @@ function parseCodexModel(model) {
 var CABANE_MCP_SERVER3 = "cabane";
 var TURN_CONTROL_MCP_SERVER2 = "cabane_companion";
 var ACTIVE_CONVERSATION_HEADER4 = "x-cabane-active-conversation";
-var ENV_ENVELOPE_KEYS = ["CABANE_ENV_TIER", "CABANE_ENV_KEY", "CABANE_ENV_BINDING"];
+var ENV_ENVELOPE_KEYS = [
+  "CABANE_PLAYGROUND",
+  "CABANE_PLAYGROUND_BIN",
+  "CABANE_CONVERSATION_ID",
+  "CABANE_AGENT_ID",
+  "CABANE_CONVERSATION_TITLE"
+];
 function buildRunSpec2(req, resumeThreadId, instructionsFile = null, threadPromptFingerprint = null) {
   const { policy, config } = req;
   const directory = req.local.cwd ?? "";
@@ -5567,8 +6002,8 @@ var ConnectorHealthStore = class {
 
 // src/dispatcher.ts
 import { randomUUID } from "crypto";
-import { appendFileSync as appendFileSync2, existsSync as existsSync9, mkdirSync as mkdirSync9, readdirSync as readdirSync2, statSync } from "fs";
-import { join as join13 } from "path";
+import { appendFileSync as appendFileSync2, existsSync as existsSync10, mkdirSync as mkdirSync10, readdirSync as readdirSync2, statSync } from "fs";
+import { join as join14 } from "path";
 
 // src/summon.ts
 import { z as z12 } from "zod";
@@ -5842,10 +6277,10 @@ function createSummonMcpServer(summonState, skipState, askState, subAgentCreate,
 
 // src/build-options.ts
 function cabaneMcpUrl(baseUrl) {
-  return `${trimSlash3(baseUrl)}/api/mcp`;
+  return `${trimSlash2(baseUrl)}/api/mcp`;
 }
 function turnControlMcpUrl(baseUrl) {
-  return `${trimSlash3(baseUrl)}/api/turn-control`;
+  return `${trimSlash2(baseUrl)}/api/turn-control`;
 }
 function buildCompanionTurnRequest(params) {
   const { turnContext: t } = params;
@@ -5894,18 +6329,18 @@ function buildCompanionTurnRequest(params) {
     }
   };
 }
-function trimSlash3(s) {
+function trimSlash2(s) {
   return s.endsWith("/") ? s.slice(0, -1) : s;
 }
 
 // src/codex-instructions.ts
 import { mkdtemp, rm, writeFile } from "fs/promises";
 import { tmpdir } from "os";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 var PREFIX = "cabane-codex-instructions-";
 async function writeCodexInstructionsFile(contents) {
-  const dir2 = await mkdtemp(join9(tmpdir(), PREFIX));
-  const path = join9(dir2, "instructions.md");
+  const dir2 = await mkdtemp(join10(tmpdir(), PREFIX));
+  const path = join10(dir2, "instructions.md");
   await writeFile(path, contents, { encoding: "utf8", mode: 384 });
   return {
     path,
@@ -5916,20 +6351,20 @@ async function writeCodexInstructionsFile(contents) {
 }
 
 // src/prepared.ts
-import { mkdirSync as mkdirSync7, readFileSync as readFileSync6, rmSync as rmSync4, writeFileSync as writeFileSync6, existsSync as existsSync7 } from "fs";
-import { join as join10 } from "path";
+import { mkdirSync as mkdirSync8, readFileSync as readFileSync6, rmSync as rmSync5, writeFileSync as writeFileSync6, existsSync as existsSync8 } from "fs";
+import { join as join11 } from "path";
 function dirFor(workspaceId) {
-  return join10(cabaneDir(), "prepared", encodeURIComponent(workspaceId));
+  return join11(cabaneDir(), "prepared", encodeURIComponent(workspaceId));
 }
 function conversationDir(workspaceId, conversationId) {
-  return join10(dirFor(workspaceId), encodeURIComponent(conversationId));
+  return join11(dirFor(workspaceId), encodeURIComponent(conversationId));
 }
 function pathFor3(workspaceId, conversationId, agentId) {
-  return join10(conversationDir(workspaceId, conversationId), `${encodeURIComponent(agentId)}.json`);
+  return join11(conversationDir(workspaceId, conversationId), `${encodeURIComponent(agentId)}.json`);
 }
 function readPrepared(workspaceId, conversationId, agentId) {
   const path = pathFor3(workspaceId, conversationId, agentId);
-  if (!existsSync7(path)) return null;
+  if (!existsSync8(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync6(path, "utf8"));
     if (parsed && typeof parsed.cwd === "string" && parsed.cwd.length > 0) {
@@ -5944,7 +6379,7 @@ function readPrepared(workspaceId, conversationId, agentId) {
   }
 }
 function writePrepared(workspaceId, conversationId, agentId, result) {
-  mkdirSync7(conversationDir(workspaceId, conversationId), { recursive: true });
+  mkdirSync8(conversationDir(workspaceId, conversationId), { recursive: true });
   writeFileSync6(
     pathFor3(workspaceId, conversationId, agentId),
     JSON.stringify(result) + "\n",
@@ -5952,21 +6387,21 @@ function writePrepared(workspaceId, conversationId, agentId, result) {
   );
 }
 function clearPrepared(workspaceId, conversationId, agentId) {
-  rmSync4(pathFor3(workspaceId, conversationId, agentId), { force: true });
+  rmSync5(pathFor3(workspaceId, conversationId, agentId), { force: true });
 }
 
 // src/secrets.ts
-import { existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync7 } from "fs";
+import { join as join12 } from "path";
 import { z as z13 } from "zod";
 var PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
 function secretsPath() {
-  return join11(cabaneDir(), "secrets.json");
+  return join12(cabaneDir(), "secrets.json");
 }
 var secretStoreSchema = z13.record(z13.string(), z13.string());
 function loadSecretStore() {
   const path = secretsPath();
-  if (!existsSync8(path)) return makeStore({});
+  if (!existsSync9(path)) return makeStore({});
   let raw;
   try {
     raw = readFileSync7(path, "utf8");
@@ -6047,10 +6482,10 @@ function resolveMcpSecrets(mcpServers, store) {
 }
 
 // src/transcript-writer.ts
-import { appendFileSync, chmodSync as chmodSync3, mkdirSync as mkdirSync8, readdirSync, rmSync as rmSync5 } from "fs";
-import { join as join12 } from "path";
+import { appendFileSync, chmodSync as chmodSync3, mkdirSync as mkdirSync9, readdirSync, rmSync as rmSync6 } from "fs";
+import { join as join13 } from "path";
 function transcriptsDir() {
-  return join12(cabaneDir(), "transcripts");
+  return join13(cabaneDir(), "transcripts");
 }
 var RETAIN = 200;
 var TranscriptWriter = class {
@@ -6059,9 +6494,9 @@ var TranscriptWriter = class {
   onWarn;
   constructor(dir2, meta, onWarn) {
     this.onWarn = onWarn;
-    this.path = join12(dir2, fileName(meta));
+    this.path = join13(dir2, fileName(meta));
     try {
-      mkdirSync8(dir2, { recursive: true });
+      mkdirSync9(dir2, { recursive: true });
       try {
         chmodSync3(dir2, 448);
       } catch {
@@ -6118,7 +6553,7 @@ function pruneOld(dir2, retain) {
   const drop = files.sort().slice(0, files.length - retain);
   for (const f of drop) {
     try {
-      rmSync5(join12(dir2, f), { force: true });
+      rmSync6(join13(dir2, f), { force: true });
     } catch {
     }
   }
@@ -6464,7 +6899,7 @@ var DEFAULT_AGENT_IDLE_TIMEOUT_MS = 10 * 6e4;
 var DEFAULT_AGENT_TOTAL_TIMEOUT_MS = 6 * 60 * 6e4;
 function checkoutState(cwd) {
   if (!cwd) return { ok: false, reason: "no working directory was resolved for this turn" };
-  if (!existsSync9(cwd)) return { ok: false, reason: `the working directory is gone (${cwd})` };
+  if (!existsSync10(cwd)) return { ok: false, reason: `the working directory is gone (${cwd})` };
   let entries;
   try {
     entries = readdirSync2(cwd);
@@ -6474,15 +6909,15 @@ function checkoutState(cwd) {
   if (entries.length === 0) {
     return { ok: false, reason: `${cwd} is empty \u2014 a recreated shell, not a prepared directory` };
   }
-  const gitPath = join13(cwd, ".git");
-  if (!existsSync9(gitPath)) return { ok: true, reason: "usable" };
+  const gitPath = join14(cwd, ".git");
+  if (!existsSync10(gitPath)) return { ok: true, reason: "usable" };
   let stat;
   try {
     stat = statSync(gitPath);
   } catch (error) {
     return { ok: false, reason: `${gitPath} is unreadable (${error.message})` };
   }
-  if (stat.isDirectory() && !existsSync9(join13(gitPath, "HEAD")))
+  if (stat.isDirectory() && !existsSync10(join14(gitPath, "HEAD")))
     return { ok: false, reason: `${gitPath} has no HEAD \u2014 an empty shell, not a checkout` };
   return { ok: true, reason: "usable" };
 }
@@ -6673,7 +7108,7 @@ var Dispatcher = class {
     let seqCounter = 0;
     const nextSeq = () => ++seqCounter;
     let effectiveCwd = localCwd ?? cabaneCwd;
-    if (effectiveCwd && !existsSync9(effectiveCwd)) {
+    if (effectiveCwd && !existsSync10(effectiveCwd)) {
       turnLog.warn(
         { cwd: effectiveCwd },
         "dispatcher: configured working directory does not exist on this device \u2014 falling back to the process cwd"
@@ -6981,7 +7416,7 @@ ${reason}`,
         }
         return this.concludeBeforeRun(payload, turnLog, startedAt, reason);
       }
-      const receiptPath = join13(effectiveCwd, ".git", "cabane", "readiness.jsonl");
+      const receiptPath = join14(effectiveCwd, ".git", "cabane", "readiness.jsonl");
       const receiptLine = (fields) => `${JSON.stringify({
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         taskId: hookEnv.CABANE_TASK_ID,
@@ -7005,7 +7440,7 @@ ${reason}`,
       })}
 `;
       try {
-        mkdirSync9(join13(effectiveCwd, ".git", "cabane"), { recursive: true });
+        mkdirSync10(join14(effectiveCwd, ".git", "cabane"), { recursive: true });
         appendFileSync2(
           receiptPath,
           // `starting` is the honest classification before the proof has run. The
@@ -7433,202 +7868,6 @@ ${reason}`,
   }
 };
 
-// src/manifest.ts
-var DEVICE_MANIFEST = {
-  runtimes: [{ name: "claude-code", version: null }],
-  capabilities: { hostFs: true, browser: true, userMcp: true }
-};
-function buildCompanionManifest(opts) {
-  const v = opts.versions ?? {};
-  const runtimes = [];
-  if (opts.claudeCode) runtimes.push({ name: "claude-code", version: v.claudeCode ?? null });
-  if (opts.opencode) runtimes.push({ name: "opencode", version: v.opencode ?? null });
-  if (opts.codex) runtimes.push({ name: "codex", version: v.codex ?? null });
-  return { runtimes, capabilities: { ...DEVICE_MANIFEST.capabilities } };
-}
-
-// src/harness-status.ts
-var LABELS = {
-  "claude-code": "Claude Code",
-  codex: "Codex",
-  opencode: "opencode"
-};
-function deriveHarnessSnapshot(signals) {
-  const advertised = new Set(
-    buildCompanionManifest({
-      // CT1082: connected AND installed — the manifest's own rule, restated here
-      // through the same function rather than re-decided.
-      claudeCode: signals.claudeCodeConnected && signals.claudeOnPath,
-      opencode: signals.opencodeConfigured,
-      codex: signals.codexEnabled
-    }).runtimes.map((r) => r.name)
-  );
-  const harnesses = [
-    deriveClaudeCode(signals, advertised.has("claude-code")),
-    deriveCodex(signals, advertised.has("codex")),
-    deriveOpencode(signals, advertised.has("opencode"))
-  ];
-  return { harnesses, anyExposed: harnesses.some((h) => h.state === "exposed") };
-}
-function deriveClaudeCode(signals, manifestHas) {
-  const base = { runtime: "claude-code", label: LABELS["claude-code"] };
-  if (manifestHas) {
-    return {
-      ...base,
-      state: "exposed",
-      version: signals.claudeVersion,
-      detail: "Claude Code is connected and exposed to Cabane.",
-      enable: null
-    };
-  }
-  if (signals.claudeCodeConnected) {
-    return {
-      ...base,
-      state: "needs_attention",
-      version: null,
-      detail: "Connected, but the `claude` CLI isn\u2019t on your PATH. Install it (`npm i -g @anthropic-ai/claude-code`) and sign in, or disconnect it.",
-      enable: null
-    };
-  }
-  if (signals.claudeOnPath) {
-    return {
-      ...base,
-      state: "detected_not_exposed",
-      version: signals.claudeVersion,
-      detail: "Claude Code is installed here but not connected yet. Connect it to let Cabane run Claude Code on this device.",
-      enable: "claude-code"
-    };
-  }
-  return {
-    ...base,
-    state: "not_detected",
-    version: null,
-    detail: "Not detected. Install Claude Code (`npm i -g @anthropic-ai/claude-code`) and sign in with `claude`, then connect it here.",
-    enable: null
-  };
-}
-function deriveCodex(signals, manifestHas) {
-  const base = { runtime: "codex", label: LABELS.codex };
-  if (manifestHas) {
-    if (signals.codexOnPath) {
-      return {
-        ...base,
-        state: "exposed",
-        version: signals.codexVersion,
-        detail: "Codex is enabled and exposed to Cabane.",
-        enable: null
-      };
-    }
-    return {
-      ...base,
-      state: "needs_attention",
-      version: null,
-      detail: "Enabled, but the `codex` CLI isn\u2019t on your PATH. Install it and sign in (`codex login`), or turn Codex off.",
-      enable: null
-    };
-  }
-  if (signals.codexOnPath) {
-    return {
-      ...base,
-      state: "detected_not_exposed",
-      version: signals.codexVersion,
-      detail: "Codex is installed but not exposed yet. Turn it on to let Cabane run Codex here.",
-      enable: "codex"
-    };
-  }
-  return {
-    ...base,
-    state: "not_detected",
-    version: null,
-    detail: "Not detected. Install the Codex CLI and sign in (`codex login`), then enable it here.",
-    enable: null
-  };
-}
-function deriveOpencode(signals, manifestHas) {
-  const base = { runtime: "opencode", label: LABELS.opencode };
-  if (manifestHas) {
-    if (signals.opencodeReachable) {
-      return {
-        ...base,
-        state: "exposed",
-        version: signals.opencodeVersion,
-        detail: "An opencode server is reachable and exposed to Cabane.",
-        enable: null
-      };
-    }
-    return {
-      ...base,
-      state: "needs_attention",
-      version: null,
-      detail: "Configured, but the opencode server isn\u2019t answering. Start `opencode serve` and check the URL.",
-      enable: null
-    };
-  }
-  return {
-    ...base,
-    state: "not_detected",
-    version: null,
-    detail: "Not detected. Run `opencode serve` and add its URL here to expose opencode.",
-    enable: "opencode"
-  };
-}
-function detectedRuntimesFor(snapshot) {
-  return snapshot.harnesses.filter((h) => h.state === "detected_not_exposed").map((h) => ({ runtime: h.runtime, version: h.version }));
-}
-var PROBE_TIMEOUT_MS2 = 4e3;
-async function probeHarnessSignals(cfg, deps = {}) {
-  const probeClaudePresence = deps.probeClaudePresence ?? claudeOnPath;
-  const probeClaudeVersion = deps.probeClaudeVersion ?? (() => probeCliVersion("claude"));
-  const probeCodexVersion = deps.probeCodexVersion ?? (() => probeCliVersion("codex"));
-  const probeOpencode = deps.probeOpencode ?? ((url) => probeOpencodeVersion(url));
-  const serverUrl = cfg.opencode?.serverUrl;
-  const [claudeOnPathResult, claudeVersion, codexVersion, opencodeVersion] = await Promise.all([
-    withTimeout(probeClaudePresence(), false),
-    withTimeout(probeClaudeVersion(), null),
-    withTimeout(probeCodexVersion(), null),
-    serverUrl ? withTimeout(probeOpencode(serverUrl), null) : Promise.resolve(null)
-  ]);
-  return {
-    claudeOnPath: claudeOnPathResult,
-    claudeVersion,
-    // CT1082: the user's opt-in. Presence alone exposes nothing now, so this is
-    // the manifest gate and the probe above is only a suggestion.
-    claudeCodeConnected: isClaudeCodeConnected(cfg),
-    // 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),
-    opencodeConfigured: !!serverUrl,
-    // A version came back ⟺ the serve answered its health endpoint (CT584).
-    opencodeReachable: opencodeVersion !== null,
-    opencodeVersion
-  };
-}
-function withTimeout(promise, fallback) {
-  return new Promise((resolve) => {
-    let settled = false;
-    const done = (v) => {
-      if (!settled) {
-        settled = true;
-        resolve(v);
-      }
-    };
-    const timer = setTimeout(() => done(fallback), PROBE_TIMEOUT_MS2);
-    timer.unref?.();
-    promise.then(
-      (v) => {
-        clearTimeout(timer);
-        done(v);
-      },
-      () => {
-        clearTimeout(timer);
-        done(fallback);
-      }
-    );
-  });
-}
-
 // src/opencode-models.ts
 var OPENCODE_RUNTIME = "opencode";
 function mapOpencodeProviders(json) {
@@ -7672,15 +7911,15 @@ async function enumerateOpencodeModels(serverUrl, fetchImpl = fetch) {
 
 // src/outbox.ts
 import {
-  existsSync as existsSync10,
-  mkdirSync as mkdirSync10,
+  existsSync as existsSync11,
+  mkdirSync as mkdirSync11,
   readdirSync as readdirSync3,
   readFileSync as readFileSync8,
   renameSync as renameSync3,
-  rmSync as rmSync6,
+  rmSync as rmSync7,
   writeFileSync as writeFileSync7
 } from "fs";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 var MAX_ENTRIES = 2e3;
 var MAX_AGE_MS = 24 * 60 * 60 * 1e3;
 var Outbox = class {
@@ -7693,17 +7932,17 @@ var Outbox = class {
   // Resolved lazily (per call, like cursor.ts) so tests that swap HOME between
   // cases route writes at the right tmpdir.
   dir() {
-    return join14(cabaneDir(), "outbox", encodeURIComponent(this.workspaceId));
+    return join15(cabaneDir(), "outbox", encodeURIComponent(this.workspaceId));
   }
   fileFor(turnId, seq) {
-    return join14(this.dir(), `${encodeURIComponent(turnId)}__${seq}.json`);
+    return join15(this.dir(), `${encodeURIComponent(turnId)}__${seq}.json`);
   }
   // Persist a commit for later draining. Atomic (temp file + rename) so a
   // concurrent `list()` never reads a half-written entry, then enforces the
   // per-workspace bounds.
   persist(entry) {
     const dir2 = this.dir();
-    mkdirSync10(dir2, { recursive: true });
+    mkdirSync11(dir2, { recursive: true });
     const target = this.fileFor(entry.turnId, entry.seq);
     const tmp = `${target}.${process.pid}.tmp`;
     try {
@@ -7711,7 +7950,7 @@ var Outbox = class {
       renameSync3(tmp, target);
     } catch (err) {
       try {
-        rmSync6(tmp, { force: true });
+        rmSync7(tmp, { force: true });
       } catch {
       }
       this.log?.warn(
@@ -7728,7 +7967,7 @@ var Outbox = class {
   // wedging the drain.
   list() {
     const dir2 = this.dir();
-    if (!existsSync10(dir2)) return [];
+    if (!existsSync11(dir2)) return [];
     let names;
     try {
       names = readdirSync3(dir2);
@@ -7738,7 +7977,7 @@ var Outbox = class {
     const entries = [];
     for (const name of names) {
       if (!name.endsWith(".json")) continue;
-      const full = join14(dir2, name);
+      const full = join15(dir2, name);
       try {
         const parsed = JSON.parse(readFileSync8(full, "utf8"));
         if (parsed && typeof parsed.turnId === "string" && typeof parsed.seq === "number" && typeof parsed.path === "string") {
@@ -7758,13 +7997,13 @@ var Outbox = class {
   // Remove a delivered (or terminally-discarded) entry. No-op if already gone.
   remove(turnId, seq) {
     try {
-      rmSync6(this.fileFor(turnId, seq), { force: true });
+      rmSync7(this.fileFor(turnId, seq), { force: true });
     } catch {
     }
   }
   size() {
     const dir2 = this.dir();
-    if (!existsSync10(dir2)) return 0;
+    if (!existsSync11(dir2)) return 0;
     try {
       return readdirSync3(dir2).filter((n) => n.endsWith(".json")).length;
     } catch {
@@ -7777,7 +8016,7 @@ var Outbox = class {
       "companion outbox: dropping unreadable entry"
     );
     try {
-      rmSync6(full, { force: true });
+      rmSync7(full, { force: true });
     } catch {
     }
   }
@@ -8706,6 +8945,26 @@ var CompanionSupervisor = class {
   async recheckHarnesses() {
     await this.refreshHarnessStatuses();
   }
+  // CT1085 §1 step 3: beat NOW and wait for it to land. `start` calls this
+  // between bringing the runtime up and asking the person anything, so the
+  // browser's connect step is already showing what this machine has ("your
+  // terminal is asking") rather than sitting blank while the terminal blocks on
+  // an answer. Coalesces with an in-flight beat rather than stacking a second.
+  async heartbeatNow() {
+    if (this.inFlightHeartbeat) {
+      await this.inFlightHeartbeat;
+      return;
+    }
+    this.kickHeartbeat();
+    if (this.inFlightHeartbeat) await this.inFlightHeartbeat;
+  }
+  // CT1085: the config as it stands right now — after any `enableHarness` write.
+  // The control socket's connect handler needs it to run the shake-out check
+  // against the URL/flag that was just persisted, not the one this process booted
+  // with.
+  currentConfig() {
+    return this.config;
+  }
   // Friendly enable for the config-driven harnesses — flip the flag the app owns in
   // `~/.cabane/config.json`, no hand-edited JSON. This is enable/expose ONLY: it
   // never installs a binary and never drives a login (BYO — Decided).
@@ -8847,9 +9106,9 @@ var CompanionSupervisor = class {
 };
 function defaultReexec() {
   clearRuntimeState();
-  void import("child_process").then(({ spawn: spawn4 }) => {
+  void import("child_process").then(({ spawn: spawn5 }) => {
     try {
-      const child = spawn4(process.execPath, process.argv.slice(1), {
+      const child = spawn5(process.execPath, process.argv.slice(1), {
         stdio: "inherit",
         detached: false
       });
@@ -8919,14 +9178,14 @@ function handleUncaught(log, err, origin) {
 }
 
 // src/crash-marker.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync11, readFileSync as readFileSync9, rmSync as rmSync7, writeFileSync as writeFileSync8 } from "fs";
-import { join as join15 } from "path";
+import { existsSync as existsSync12, mkdirSync as mkdirSync12, readFileSync as readFileSync9, rmSync as rmSync8, writeFileSync as writeFileSync8 } from "fs";
+import { join as join16 } from "path";
 function crashMarkerPath() {
-  return join15(cabaneDir(), "last-error.json");
+  return join16(cabaneDir(), "last-error.json");
 }
 function recordCrash(rec) {
   try {
-    mkdirSync11(cabaneDir(), { recursive: true });
+    mkdirSync12(cabaneDir(), { recursive: true });
     writeFileSync8(crashMarkerPath(), JSON.stringify(rec, null, 2) + "\n");
   } catch {
   }
@@ -8934,7 +9193,7 @@ function recordCrash(rec) {
 function clearCrash() {
   try {
     const path = crashMarkerPath();
-    if (existsSync11(path)) rmSync7(path, { force: true });
+    if (existsSync12(path)) rmSync8(path, { force: true });
   } catch {
   }
 }
@@ -8953,7 +9212,13 @@ async function createCompanionRuntime(opts = {}) {
         onPath ? "companion: carried Claude Code over as a connected harness on this device (connectors are now chosen, not detected)" : "companion: no Claude Code on PATH, so this device starts with it disconnected (connectors are now chosen, not detected)"
       )
     }));
-    await warnAboutHarnessReadiness(cfg, { probeClaude: async () => claudeCode });
+    await warnAboutHarnessReadiness(cfg, {
+      probeClaude: async () => claudeCode,
+      // CT1085: the CLI's onboarding script owns the terminal and says this in
+      // its own words (the `!` block, or the per-harness offer), so it hands us a
+      // sink that logs instead. Every other caller keeps the stderr line.
+      ...opts.onReadinessWarning ? { warn: opts.onReadinessWarning } : {}
+    });
   } catch (err) {
     recordCrash({
       reason: err instanceof Error ? err.message : String(err),
@@ -8977,8 +9242,6 @@ async function createCompanionRuntime(opts = {}) {
   if (pre && await verifyRuntime(pre) === "stale") clearRuntimeState();
   const claim = acquireRuntimeState({
     pid: process.pid,
-    url: "",
-    port: 0,
     startedAt,
     daemon: process.env.CABANE_COMPANION_DAEMON === "1",
     instanceId
@@ -8986,7 +9249,7 @@ async function createCompanionRuntime(opts = {}) {
   if (!claim.acquired) {
     return { ok: false, reason: "already-running", existing: claim.existing ?? null };
   }
-  process.on("exit", () => clearRuntimeState());
+  process.on("exit", () => clearRuntimeStateIfOurs(instanceId));
   const hub = new CompanionStateHub({
     // CT29: one device, one base URL — the cabane instance this device is paired
     // with. The dashboard's connection line shows it.
@@ -9004,17 +9267,36 @@ async function createCompanionRuntime(opts = {}) {
     harnessVersions
   });
   await supervisor.start();
-  const preferredPort = opts.port ?? cfg.dashboardPort;
-  const dashboard = await startDashboard({
-    supervisor,
-    hub,
-    ...preferredPort !== void 0 ? { port: preferredPort } : {}
+  const connectHarness = async (runtime, serverUrl) => {
+    const result = await supervisor.enableHarness(
+      runtime === "opencode" ? { runtime: "opencode", serverUrl: serverUrl ?? "" } : { runtime }
+    );
+    if (!result.ok) return { ok: false, error: result.error };
+    const verdict = await shakeOutHarness(runtime, supervisor.currentConfig());
+    return { ok: true, message: connectedLine(runtime, verdict) };
+  };
+  const control = await startControlServer({
+    status: () => hub.statusJson(),
+    connect: async (runtime, serverUrl) => {
+      const result = await connectHarness(runtime, serverUrl);
+      return result.ok ? { ok: true, message: result.message } : { ok: false, message: result.error };
+    },
+    stop: () => void supervisor.requestStop()
   });
-  hub.setDashboardUrl(dashboard.url);
+  let dashboard = null;
+  if (opts.dashboard) {
+    const preferredPort = opts.port ?? cfg.dashboardPort;
+    dashboard = await startDashboard({
+      supervisor,
+      hub,
+      ...preferredPort !== void 0 ? { port: preferredPort } : {}
+    });
+    hub.setDashboardUrl(dashboard.url);
+  }
   writeRuntimeState({
     pid: process.pid,
-    url: dashboard.url,
-    port: dashboard.port,
+    socket: control.path,
+    ...dashboard ? { url: dashboard.url, port: dashboard.port } : {},
     startedAt,
     // SJ495: the daemon launcher sets this env on the detached child, so the
     // marker records whether this companion is backgrounded (foreground start
@@ -9027,30 +9309,37 @@ async function createCompanionRuntime(opts = {}) {
   const stop = async () => {
     if (stopped) return;
     stopped = true;
-    clearRuntimeState();
+    clearRuntimeStateIfOurs(instanceId);
     try {
       await supervisor.shutdown();
-      await dashboard.close();
+      await closeSurfaces(control, dashboard);
     } catch {
     }
   };
   return {
     ok: true,
     runtime: {
-      url: dashboard.url,
-      port: dashboard.port,
+      ...dashboard ? { url: dashboard.url, port: dashboard.port } : {},
+      socketPath: control.path,
       config: cfg,
       stop,
+      heartbeatNow: () => supervisor.heartbeatNow(),
+      harnesses: () => hub.statusJson().harnesses ?? [],
+      connectHarness,
       drainForRestart: async (graceMs) => {
-        clearRuntimeState();
+        clearRuntimeStateIfOurs(instanceId);
         const result = await supervisor.drainForRestart(graceMs);
-        await dashboard.close();
+        await closeSurfaces(control, dashboard);
         stopped = true;
         return result;
       }
     }
   };
 }
+async function closeSurfaces(control, dashboard) {
+  await control.close();
+  if (dashboard) await dashboard.close();
+}
 export {
   createCompanionRuntime
 };