trantor 0.18.40 → 0.18.42

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.40",
+  "version": "0.18.42",
   "description": "Trantor — the hub-world for AI agent crews: live message bus, presence, project Kanban/flow board + crew orchestration for independent AI coding agents (Claude, Codex, Gemini, Kimi, DeepSeek)",
   "mcpServers": {
     "relay": {

package/bin/advise.mjs

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
+import { busDir, readConfig } from "../lib/project.mjs";
 
 const H = homedir();
 const read = (p, fb) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return fb; } };
@@ -64,8 +65,14 @@ export function buildRoster(profile, ocConfig) {
   return { ...BUILTIN_ROSTER, ...discoverSeats(profile, ocConfig) };
 }
 
+export function filterEnabledAgents(agentIds, config = {}) {
+  const disabled = new Set(Array.isArray(config?.agents?.disabled) ? config.agents.disabled : []);
+  return agentIds.filter(agent => !disabled.has(agent));
+}
+
 export function loadWorld() {
-  const profile = read(join(H, ".agent-bus", "profile.json"), { providers: {} });
+  const config = readConfig();
+  const profile = read(join(busDir(), "profile.json"), { providers: {} });
   const registry = read(join(H, ".token-scrooge", "registry.json"), { models: {}, tasks: {} });
   const caps = read(join(H, ".token-scrooge", "capabilities.json"), {});
   const ocConfig = read(join(H, ".config", "opencode", "opencode.json"), {});
@@ -84,8 +91,8 @@ export function loadWorld() {
     const envKey = `${String(s.providerOc).toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
     return opencodeKey(s.providerOc) || envHasKey(envKey) || !!profile?.providers?.[s.provider];
   };
-  const agents = Object.keys(roster).filter(hasSeat);
-  return { profile, registry, caps, roster, agents, scrooge: has("scrooge") };
+  const agents = filterEnabledAgents(Object.keys(roster).filter(hasSeat), config);
+  return { profile, registry, caps, ocConfig, roster, agents, scrooge: has("scrooge") };
 }
 
 const tierOf = (profile, prov) => profile?.providers?.[prov]?.tier || "api";

package/bin/agent-settings.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { buildAgentSettingsStatus, setAgentEnabled, setDefaultAgent } from "../lib/agent-preferences.mjs";
+
+const [command = "status", id, value] = process.argv.slice(2).filter(argument => argument !== "--json");
+
+try {
+  const result = command === "status"
+    ? buildAgentSettingsStatus()
+    : command === "set-enabled"
+      ? setAgentEnabled(id, value === "true")
+      : command === "set-default"
+        ? setDefaultAgent(id === "auto" ? null : id)
+        : null;
+  if (!result) {
+    console.error("usage: agent-settings.mjs status | set-enabled <agent> <true|false> | set-default <agent|auto>");
+    process.exit(1);
+  }
+  console.log(JSON.stringify(result));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/bin/autonomy.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // `trantor autonomy` — read and set the three dials from the CLI.
 //
-// The app will grow a settings pane for this, but the CLI has to work on its own: crew.sh asks
+// The app will grow a settings pane for this, but the CLI has to work on its own: crew.mjs asks
 // this for the harness dial every time it starts your session, and a headless machine has no app.
 import { resolveAutonomy, setAutonomy, loadAutonomy, AUTONOMY_PATH } from "../lib/autonomy.mjs";
 import { resolveProject } from "../lib/project.mjs";
@@ -21,7 +21,7 @@ const BOOLS = ["commit", "push", "deploy", "swapDeadSeat", "retryFailedTurn"];
 const ENUMS = { harness: ["prompt", "bypass"], baton: ["ask", "auto"] };
 
 if (cmd === "get") {
-  // Machine-readable, one value, no decoration — crew.sh reads this.
+  // Machine-readable, one value, no decoration — crew.mjs reads this.
   const key = args[1];
   const a = resolveAutonomy(projectFlag() || "");
   if (!(key in a)) { console.error(`unknown dial '${key}'`); process.exit(1); }

package/bin/cli.mjs

@@ -12,6 +12,10 @@ const run = (file, runner = process.execPath) => {
   const child = spawn(runner, [join(ROOT, file), ...args], { stdio: "inherit", cwd: process.cwd() });
   child.on("exit", (c) => process.exit(c ?? 0));
 };
+const runCrew = () => {
+  spawn(process.execPath, [join(ROOT, "bin/crew.mjs"), cmd, ...args], { stdio: "inherit", cwd: process.cwd() })
+    .on("exit", c => process.exit(c ?? 0));
+};
 
 switch (cmd) {
   case "setup":   run("deploy/setup.sh", "/bin/bash"); break;
@@ -22,15 +26,15 @@ switch (cmd) {
   case "models": run("bin/models.mjs"); break;
   case "advise":  run("bin/advise.mjs"); break;
   case "verify":  run("bin/crew-verify.mjs"); break;
-  case "up":      process.argv.splice(2, 1); spawn("/bin/bash", [join(ROOT, "bin/crew.sh"), "up", ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
-  case "open":    spawn("/bin/bash", [join(ROOT, "bin/crew.sh"), "open", ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
+  case "up":      runCrew(); break;
+  case "open":    runCrew(); break;
   case "herdr":   spawn(process.execPath, [join(ROOT, "bin/herdr-agent.mjs"), ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
   case "autonomy": spawn(process.execPath, [join(ROOT, "bin/autonomy.mjs"), ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
   case "adopt":   spawn(process.execPath, [join(ROOT, "bin/adopt.mjs"), ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
   case "integrate": spawn(process.execPath, [join(ROOT, "bin/integrate.mjs"), ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
-  case "down":    spawn("/bin/bash", [join(ROOT, "bin/crew.sh"), "down", ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
-  case "swap":    spawn("/bin/bash", [join(ROOT, "bin/crew.sh"), "swap", ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
-  case "prune":   spawn("/bin/bash", [join(ROOT, "bin/crew.sh"), "prune", ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
+  case "down":    runCrew(); break;
+  case "swap":    runCrew(); break;
+  case "prune":   runCrew(); break;
   case "hub": {
     const sub = args[0];
     // Per-project hub routing (TDD §12.1): a project lives on exactly ONE hub; codependent
@@ -41,6 +45,9 @@ switch (cmd) {
         const cfg = readConfig();
         const here = resolveProject();
         console.log(`global default: ${cfg.url || DEFAULT_HUB_URL}${cfg.url ? "" : " (built-in)"}`);
+        // SAFETY: cfg.hubs is the config.json hubs map decoded by JSON.parse; the check separates
+        // "a pin map" (any object, even field-less) from primitives/null (no pins to list).
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof
         const hubs = cfg.hubs && typeof cfg.hubs === "object" ? Object.entries(cfg.hubs) : [];
         if (!hubs.length) console.log("no per-project pins — every project uses the global default");
         for (const [p, u] of hubs) console.log(`${p === here ? "*" : " "} ${p} → ${u}`);
@@ -192,7 +199,7 @@ switch (cmd) {
   trantor doctor      where do I stand? hub/plugin/CLIs/auth/keys/profile, with copy-paste fixes
   trantor connect     (re)wire every installed AI CLI to the bus
   trantor profile     declare your plans:  trantor profile set claude=max codex=plus deepseek=api
-  trantor provider    bring ANY model (BYOM): list seats · add <name> --key … · remove <name>
+  trantor provider    bring ANY model (BYOM): list · status [--json] · verify <name> --key … · add <name> --key … · remove <name>
   trantor models      browse live models behind each seat + the router's pick per difficulty
   trantor up …        spawn a crew here:   trantor up codex kimi deepseek:deepseek glm:zai-coding-plan
   trantor open        host THIS session as the project's orchestrator pane (trantor down spares it)

package/bin/crew/cmux.mjs

@@ -0,0 +1,214 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appleScript, appleScriptString, call, commandExists, gridColumns, parseJsonOutput, runnerCommand } from "./core.mjs";
+import { dropState, readRows, recordState } from "./state.mjs";
+
+function binary(ctx) {
+  return commandExists("cmux", ctx.env) ? "cmux" : "/Applications/cmux.app/Contents/Resources/bin/cmux";
+}
+
+function cmuxCall(ctx, args, options = {}) {
+  return call(binary(ctx), args, { ...options, env: { ...ctx.env, CMUX_QUIET: "1" } });
+}
+
+function socketWorks(ctx) {
+  return ctx.have.cmux && cmuxCall(ctx, ["ping"]).ok;
+}
+
+export function liveWorkspaces(ctx) {
+  if (!socketWorks(ctx)) return { proven: false, ids: new Set(), names: new Set(), items: [] };
+  const result = cmuxCall(ctx, ["workspace", "list", "--id-format", "both", "--json"]);
+  const parsed = parseJsonOutput(result.stdout);
+  if (!parsed) return { proven: false, ids: new Set(), names: new Set(), items: [] };
+  const items = Array.isArray(parsed) ? parsed : parsed.workspaces || [];
+  return {
+    proven: true,
+    ids: new Set(items.map(item => item.id).filter(Boolean)),
+    names: new Set(items.map(item => item.custom_title || item.name).filter(Boolean)),
+    items,
+  };
+}
+
+export function closeWorkspace(ctx, id) {
+  if (ctx.dry) { console.log(`[dry] cmux close-workspace ${id}`); return; }
+  if (socketWorks(ctx) && cmuxCall(ctx, ["close-workspace", "--workspace", id]).ok) return;
+  call("osascript", [], { input: `tell application "cmux"\nrepeat with w in windows\nrepeat with tt in tabs of w\nif (id of tt) is "${id}" then close tab tt\nend repeat\nend repeat\nend tell\n` });
+}
+
+export function closePane(ctx, id) {
+  if (ctx.dry) { console.log(`[dry] cmux close-surface ${id}`); return; }
+  if (socketWorks(ctx) && cmuxCall(ctx, ["close-surface", "--surface", id]).ok) return;
+  call("osascript", [], { input: `tell application "cmux"\nrepeat with tr in terminals\nif (id of tr) is "${id}" then close tr\nend repeat\nend tell\n` });
+}
+
+function seatLauncher(ctx, agent, command) {
+  mkdirSync(ctx.seatDir, { recursive: true });
+  const file = join(ctx.seatDir, `${ctx.project}-${agent}.sh`);
+  if (!ctx.dry) writeFileSync(file, `#!/bin/bash\nprintf "\\033]0;%s\\007" ${JSON.stringify(`${agent} · ${ctx.project}`)}\n${command}\n`);
+  return file;
+}
+
+function tracked(ctx) {
+  const ids = readRows(ctx).filter(row => row.project === ctx.project && row.kind === "cmuxws").map(row => row.handle);
+  return { reuse: ids.at(-1) || "", stale: ids.slice(0, -1) };
+}
+
+function prepare(ctx, prune) {
+  const result = tracked(ctx);
+  for (const id of result.stale) {
+    console.log(`  → closing stale stacked crew workspace for ${ctx.project} (${id})`);
+    closeWorkspace(ctx, id);
+    dropState(ctx, ctx.project, "cmuxws", "", id);
+  }
+  if (result.stale.length) prune();
+  if (ctx.dry || result.reuse) return result.reuse;
+  const candidate = liveWorkspaces(ctx).items.find(item => [item.custom_title, item.name].includes(`trantor:${ctx.project}`));
+  const id = candidate?.id || "";
+  if (id) {
+    console.log(`  → adopting existing untracked crew workspace for ${ctx.project} (${id})`);
+    recordState(ctx, ctx.project, "cmuxws", "__ws__", id);
+  }
+  return id;
+}
+
+function surfaceFrom(result) {
+  const parsed = parseJsonOutput(result.stdout);
+  return parsed?.surface_id || parsed?.surface_ref || parsed?.id || "";
+}
+
+function newWorkspace(ctx, launcher) {
+  const created = cmuxCall(ctx, ["new-workspace", "--cwd", ctx.dir, "--command", `bash ${launcher}`]);
+  const ref = created.stdout.split(/\s+/)[1] || "";
+  const list = liveWorkspaces(ctx).items;
+  const workspace = list.find(item => item.ref === ref)?.id || list.at(-1)?.id || "";
+  if (workspace) cmuxCall(ctx, ["rename-workspace", "--workspace", workspace, `trantor:${ctx.project}`]);
+  const panes = cmuxCall(ctx, ["list-pane-surfaces", "--workspace", workspace, "--id-format", "uuids", "--json"]);
+  const parsed = parseJsonOutput(panes.stdout);
+  const first = (parsed?.surfaces || parsed?.panes || (Array.isArray(parsed) ? parsed : []))[0];
+  return { workspace, pane: first?.id || first?.surface_id || "" };
+}
+
+function split(ctx, workspace, direction, target, launcher) {
+  const args = ["new-split", direction, "--workspace", workspace];
+  if (target) args.push("--surface", target);
+  args.push("--id-format", "uuids", "--json");
+  const pane = surfaceFrom(cmuxCall(ctx, args));
+  if (pane) {
+    cmuxCall(ctx, ["send", "--surface", pane, `bash ${launcher}`]);
+    cmuxCall(ctx, ["send-key", "--surface", pane, "enter"]);
+  }
+  return pane;
+}
+
+export function spawnCmux(ctx, specs, resolve, prune) {
+  if (!socketWorks(ctx)) return spawnAppleScript(ctx, specs, resolve);
+  let workspace = prepare(ctx, prune);
+  const reuse = Boolean(workspace);
+  const panes = [];
+  const columns = gridColumns(specs.length);
+  for (let index = 0; index < specs.length; index += 1) {
+    const seat = resolve(specs[index]);
+    if (!seat) continue;
+    const launcher = seatLauncher(ctx, seat.agent, runnerCommand(ctx, seat.agent, seat.model));
+    const old = reuse ? readRows(ctx).filter(row => row.project === ctx.project && row.kind === "cmux" && row.agent === seat.agent).at(-1)?.handle || "" : "";
+    let pane = "";
+    if (reuse) {
+      console.log(ctx.dry ? `[dry] cmux: reuse workspace ${workspace} — new-split for ${seat.agent}${old ? ` (replacing ${old})` : ""}` : `  → reusing workspace ${workspace}`);
+      pane = ctx.dry ? `%DRYT${index}` : split(ctx, workspace, "right", old || panes.at(-1) || "", launcher);
+      if (old) { closePane(ctx, old); dropState(ctx, ctx.project, "cmux", seat.agent); }
+    } else if (index === 0) {
+      if (ctx.dry) {
+        console.log(`[dry] cmux: new-workspace (cwd ${ctx.dir}) --command 'bash ${launcher}' → rename 'trantor:${ctx.project}'`);
+        workspace = "%DRYWS"; pane = "%DRYT0";
+      } else ({ workspace, pane } = newWorkspace(ctx, launcher));
+      recordState(ctx, ctx.project, "cmuxws", "__ws__", workspace);
+    } else {
+      const firstRow = Math.floor(index / columns) === 0;
+      const direction = firstRow ? "right" : "down";
+      const target = panes[firstRow ? index - 1 : index - columns] || "";
+      if (ctx.dry) {
+        console.log(`[dry] cmux: new-split ${direction} --surface ${target || "<focused>"} + send 'bash ${launcher}'`);
+        pane = `%DRYT${index}`;
+      } else pane = split(ctx, workspace, direction, target, launcher);
+    }
+    panes.push(pane);
+    recordState(ctx, ctx.project, "cmux", seat.agent, pane);
+    console.log(`  → ${seat.agent} seat in cmux workspace (${ctx.project})`);
+  }
+  console.log(`— crew grouped in cmux: ONE workspace tab for ${ctx.project}, seats tiled + sidebar status. Teardown (this project only): trantor down —`);
+}
+
+function spawnAppleScript(ctx, specs, resolve) {
+  console.log("— cmux control socket is OFF (mode cmuxOnly) → using AppleScript (works; no native sidebar status).");
+  console.log("  Enable the full integration: add \"automation\": { \"socketControlMode\": \"allowAll\" } to");
+  console.log("  ~/.config/cmux/cmux.json (cmux auto-reloads). —");
+  let tab = prepareAppleScriptWorkspace(ctx);
+  const reuse = Boolean(tab);
+  const panes = [];
+  const columns = gridColumns(specs.length);
+  for (let index = 0; index < specs.length; index += 1) {
+    const seat = resolve(specs[index]);
+    if (!seat) continue;
+    const launcher = seatLauncher(ctx, seat.agent, runnerCommand(ctx, seat.agent, seat.model));
+    const old = reuse ? readRows(ctx).filter(row => row.project === ctx.project && row.kind === "cmux" && row.agent === seat.agent).at(-1)?.handle || "" : "";
+    let pane;
+    if (!tab && index === 0) {
+      if (ctx.dry) {
+        console.log(`[dry] cmux(AppleScript): new tab (trantor:${ctx.project}) + run 'bash ${launcher}'`);
+        tab = "%DRYTAB"; pane = "%DRYT0";
+      } else ({ tab, pane } = createAppleScriptTab(ctx, launcher));
+      recordState(ctx, ctx.project, "cmuxws", "__ws__", tab);
+    } else {
+      const firstRow = Math.floor(index / columns) === 0;
+      const direction = old || firstRow ? "right" : "down";
+      const target = old || panes[firstRow ? index - 1 : index - columns] || "";
+      if (ctx.dry) {
+        console.log(`[dry] cmux(AppleScript): split ${direction} from ${target || "<focused>"} + run 'bash ${launcher}'`);
+        pane = `%DRYT${index}`;
+      } else pane = splitAppleScriptPane(ctx, tab, target, direction, launcher);
+      if (old && pane && pane !== "ERR") { closePane(ctx, old); dropState(ctx, ctx.project, "cmux", seat.agent); }
+    }
+    panes.push(pane);
+    recordState(ctx, ctx.project, "cmux", seat.agent, pane);
+    console.log(`  → ${seat.agent} seat in cmux workspace (${ctx.project})`);
+  }
+  console.log(`— crew grouped in cmux (AppleScript): ONE workspace tab for ${ctx.project}, seats tiled. Teardown: trantor down —`);
+}
+
+function prepareAppleScriptWorkspace(ctx) {
+  const ids = readRows(ctx).filter(row => row.project === ctx.project && row.kind === "cmuxws").map(row => row.handle);
+  const reuse = ids.at(-1) || "";
+  for (const id of ids.slice(0, -1)) {
+    console.log(`  → closing stale stacked crew workspace for ${ctx.project} (${id})`);
+    closeWorkspace(ctx, id);
+    dropState(ctx, ctx.project, "cmuxws", "", id);
+  }
+  if (!reuse || ctx.dry) return reuse;
+  const script = `tell application "cmux"\nrepeat with w in windows\nrepeat with tt in tabs of w\nif (id of tt) is "${appleScriptString(reuse)}" then return "OK"\nend repeat\nend repeat\nreturn "ERR"\nend tell\n`;
+  if (appleScript(script).stdout === "OK") {
+    console.log(`  → reusing existing crew workspace for ${ctx.project} (${reuse})`);
+    return reuse;
+  }
+  dropState(ctx, ctx.project, "cmuxws", "", reuse);
+  dropState(ctx, ctx.project, "cmux");
+  return "";
+}
+
+function createAppleScriptTab(ctx, launcher) {
+  const script = `tell application "cmux"\nactivate\nif (count of windows) is 0 then\nnew window\ndelay 0.5\nend if\nset t to (new tab)\ndelay 0.4\nset term1 to (focused terminal of t)\ninput text ("bash ${appleScriptString(launcher)}" & return) to term1\nreturn (id of t) & "|" & (id of term1)\nend tell\n`;
+  const [tab = "", pane = ""] = appleScript(script).stdout.split("|");
+  return { tab, pane };
+}
+
+function splitAppleScriptPane(ctx, tab, target, direction, launcher) {
+  const script = `tell application "cmux"\nset theTab to missing value\nrepeat with w in windows\nrepeat with tt in tabs of w\nif (id of tt) is "${appleScriptString(tab)}" then set theTab to tt\nend repeat\nend repeat\nif theTab is missing value then return "ERR"\nset srcTerm to missing value\nrepeat with tm in terminals of theTab\nif (id of tm) is "${appleScriptString(target)}" then set srcTerm to tm\nend repeat\nif srcTerm is missing value then set srcTerm to (focused terminal of theTab)\nset newterm to (split srcTerm direction ${direction})\ndelay 0.25\ninput text ("bash ${appleScriptString(launcher)}" & return) to newterm\nreturn (id of newterm)\nend tell\n`;
+  return appleScript(script).stdout;
+}
+
+export function createCmuxAdapter(ctx) {
+  return {
+    closeWorkspace: id => closeWorkspace(ctx, id),
+    closePane: id => closePane(ctx, id),
+    liveWorkspaces: () => liveWorkspaces(ctx),
+  };
+}

package/bin/crew/core.mjs

@@ -0,0 +1,142 @@
+import { accessSync, constants, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+export function commandExists(name, env = process.env) {
+  for (const dir of String(env.PATH || "").split(":")) {
+    try { accessSync(join(dir, name), constants.X_OK); return true; }
+    catch {}
+  }
+  return false;
+}
+
+export function call(command, args = [], options = {}) {
+  const spawnOptions = {
+    cwd: options.cwd || process.cwd(),
+    encoding: "utf8",
+    env: options.env || process.env,
+    input: options.input,
+    stdio: options.stdio || ["ignore", "pipe", "pipe"],
+  };
+  let result = spawnSync(command, args, spawnOptions);
+  if (result.error?.code === "ENOEXEC") result = spawnSync("/bin/sh", [command, ...args], spawnOptions);
+  return {
+    ok: !result.error && result.status === 0,
+    status: result.status ?? 1,
+    stdout: String(result.stdout || "").trim(),
+    stderr: String(result.stderr || "").trim(),
+  };
+}
+
+export function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:@%+-]+$/.test(text)) return text;
+  return `'${text.replaceAll("'", `'\\''`)}'`;
+}
+
+export function formatCommand(command, args = []) {
+  return [command, ...args].map(shellQuote).join(" ");
+}
+
+export function run(ctx, command, args = [], options = {}) {
+  const rendered = options.rendered || formatCommand(command, args);
+  if (ctx.dry) {
+    console.log(`[dry] ${rendered}`);
+    return { ok: true, status: 0, stdout: "", stderr: "" };
+  }
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || ctx.dir,
+    encoding: "utf8",
+    env: options.env || process.env,
+    stdio: options.stdio || "ignore",
+  });
+  return { ok: !result.error && result.status === 0, status: result.status ?? 1 };
+}
+
+function projectFromGit(dir) {
+  const result = call("git", ["-C", dir, "rev-parse", "--show-toplevel"]);
+  return result.ok && result.stdout ? basename(result.stdout) : basename(dir);
+}
+
+function readConfig(home, env) {
+  const base = env.AGENT_BUS_DIR || join(home, ".agent-bus");
+  try { return JSON.parse(readFileSync(join(base, "config.json"), "utf8")); }
+  catch { return {}; }
+}
+
+function resolveHub(home, project, env) {
+  if (env.CREW_HUB) return env.CREW_HUB;
+  const config = readConfig(home, env);
+  return config.hubs?.[project] || env.RELAY_URL || config.url || "http://127.0.0.1:4477";
+}
+
+function selectMux(env, have) {
+  if (env.CREW_MUX === "herdr" && !have.herdr) {
+    throw new Error("CREW_MUX=herdr but herdr is not installed — user-local (no sudo): curl -fsSL https://herdr.dev/install.sh | sh — see https://herdr.dev");
+  }
+  if (env.CREW_MUX) return env.CREW_MUX;
+  if (have.herdr) return "herdr";
+  if (have.cmux) return "cmux";
+  if (have.tmux) return "tmux";
+  return "terminal";
+}
+
+export function createContext(command, env = process.env) {
+  const dir = env.PWD || process.cwd();
+  const home = env.HOME || "";
+  const project = env.RELAY_PROJECT || projectFromGit(dir);
+  const have = {
+    herdr: commandExists("herdr", env),
+    tmux: commandExists("tmux", env),
+    cmux: existsSync("/Applications/cmux.app") || commandExists("cmux", env),
+  };
+  const ctx = {
+    command,
+    dir,
+    home,
+    project,
+    root: ROOT,
+    hub: resolveHub(home, project, env),
+    statePath: join(home, ".agent-bus", "crew-windows.txt"),
+    seatDir: join(home, ".agent-bus", "seats"),
+    dry: env.CREW_DRY_RUN === "1",
+    have,
+    env,
+  };
+  mkdirSync(dirname(ctx.statePath), { recursive: true });
+  ctx.mux = selectMux(env, have);
+  return ctx;
+}
+
+export function parseJsonOutput(text) {
+  const start = String(text).search(/[\[{]/);
+  if (start < 0) return null;
+  try { return JSON.parse(String(text).slice(start)); }
+  catch { return null; }
+}
+
+export function appleScript(script) {
+  return call("osascript", [], { input: script });
+}
+
+export function appleScriptString(value) {
+  return String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+
+export function gridColumns(size) {
+  let columns = 1;
+  while (columns * columns < size) columns += 1;
+  return columns;
+}
+
+export function runnerCommand(ctx, agent, model = "") {
+  return `cd ${shellQuote(ctx.dir)} && CREW_MODEL=${shellQuote(model)} RELAY_PROJECT=${shellQuote(ctx.project)} RELAY_URL=${shellQuote(ctx.hub)} node ${shellQuote(join(ROOT, "bin/crew-runner.mjs"))} ${shellQuote(agent)} ${shellQuote(ctx.dir)}`;
+}
+
+export function listPids(pattern) {
+  const result = call("pgrep", ["-f", pattern]);
+  return result.ok ? result.stdout.split(/\s+/).filter(Boolean) : [];
+}