@clipboard-health/groundcrew 2.2.0 → 2.3.1

package/dist/lib/host.js

@@ -3,7 +3,7 @@
  * current machine. Doctor and setup inject a capabilities object directly
  * so tests don't have to mock `which`.
  */
-import { platform } from "node:process";
+import process from "node:process";
 import { runCommandAsync } from "./commandRunner.js";
 /**
  * Resolves a binary on PATH the same way `which` does. Returns the first
@@ -26,17 +26,22 @@ export async function which(cmd, signal) {
     }
 }
 export async function detectHostCapabilities(signal) {
-    const isMacOS = platform === "darwin";
-    const [safehouse, cmux, tmux] = await Promise.all([
+    const isMacOS = process.platform === "darwin";
+    const isLinux = process.platform === "linux";
+    const [safehouse, sbx, cmux, tmux] = await Promise.all([
         which("safehouse", signal),
+        which("sbx", signal),
         which("cmux", signal),
         which("tmux", signal),
     ]);
     return {
         hasSafehouse: safehouse !== undefined,
+        hasSbx: sbx !== undefined,
         hasCmux: cmux !== undefined,
         hasTmux: tmux !== undefined,
         isMacOS,
+        isLinux,
         isSafehouseSupported: isMacOS,
+        isSdxSupported: isMacOS || isLinux,
     };
 }

package/dist/lib/launchCommand.d.ts

@@ -1,4 +1,4 @@
-import { type ModelDefinition } from "./config.ts";
+import { type LocalRunner, type ModelDefinition } from "./config.ts";
 export { shellSingleQuote } from "./shell.ts";
 /**
  * Resolve the shipped Safehouse proxy wrapper inside `@clipboard-health/clearance`
@@ -18,10 +18,24 @@ interface LaunchCommandArguments {
     /**
      * Optional path to a `KEY='value'` env file containing build-time
      * secrets (see `BUILD_SECRET_NAMES`). Sourced on the host shell before
-     * setup and always unset before exec'ing the agent so the agent process
-     * never inherits them.
+     * setup; for the sdx runner the names are propagated into the sandbox
+     * via `sbx exec -e KEY`. Always unset before exec'ing the agent so the
+     * agent process never inherits them.
      */
     secretsFile?: string | undefined;
+    /**
+     * Concrete local isolation backend chosen for this launch. Resolved
+     * from `config.local.runner` via `resolveLocalRunner` before this
+     * function is called — `auto` is never seen here.
+     */
+    runner: LocalRunner;
+    /**
+     * sbx sandbox name when `runner === "sdx"`. Derived by the caller from
+     * `sandboxNameFor({ repository, model })`. Required for sdx; ignored
+     * otherwise. Kept off the model definition so a model can launch under
+     * safehouse on one host and sdx on another without config edits.
+     */
+    sandboxName?: string | undefined;
 }
 /**
  * Build the shell command that runs inside the workspace. The prompt is

package/dist/lib/launchCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkD,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAcvF;AA+BD,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CA2B7E"}
+{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAcvF;AAmCD,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CAK7E"}

package/dist/lib/launchCommand.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
-import { BUILD_SECRET_NAMES, DEFAULT_HOST_SETUP_COMMAND } from "./config.js";
+import { BUILD_SECRET_NAMES, DEFAULT_HOST_SETUP_COMMAND, DEFAULT_SANDBOX_SETUP_COMMAND, } from "./config.js";
 import { shellSingleQuote } from "./shell.js";
 export { shellSingleQuote } from "./shell.js";
 /**
@@ -28,7 +28,7 @@ const SAFEHOUSE_CLEARANCE_WRAPPER_PATH = resolveSafehouseClearancePath();
 function renderAgentCommand(arguments_) {
     return arguments_.agentCmd
         .replaceAll("{{worktree}}", shellSingleQuote(arguments_.worktreeDir))
-        .replaceAll("{{sandbox}}", shellSingleQuote(""));
+        .replaceAll("{{sandbox}}", shellSingleQuote(arguments_.sandboxName));
 }
 function setupWithStatusReporting(setupCommand) {
     return [
@@ -57,17 +57,23 @@ function unsetSecretsLine() {
  * prompt in hand.
  */
 export function buildLaunchCommand(arguments_) {
+    if (arguments_.runner === "sdx") {
+        return buildSdxLaunchCommand(arguments_);
+    }
+    return buildHostLaunchCommand(arguments_);
+}
+function buildHostLaunchCommand(arguments_) {
     const promptDir = dirname(arguments_.promptFile);
     const agentCmd = renderAgentCommand({
         agentCmd: arguments_.definition.cmd,
         worktreeDir: arguments_.worktreeDir,
+        sandboxName: "",
+    });
+    const wrapped = wrapAgentForHostRunner({
+        runner: arguments_.runner,
+        rawCmd: arguments_.definition.cmd,
+        agentCmd,
     });
-    // Skip the wrap if `cmd` already starts with `safehouse` so legacy
-    // configs don't double-wrap.
-    const cmdStartsWithSafehouse = /^safehouse(\s|$)/.test(arguments_.definition.cmd);
-    const wrapped = cmdStartsWithSafehouse
-        ? agentCmd
-        : [shellSingleQuote(SAFEHOUSE_CLEARANCE_WRAPPER_PATH), agentCmd].join(" ");
     const lines = [`cd ${shellSingleQuote(arguments_.worktreeDir)}`];
     if (arguments_.secretsFile !== undefined) {
         lines.push(sourceSecretsLine(arguments_.secretsFile));
@@ -79,3 +85,55 @@ export function buildLaunchCommand(arguments_) {
     lines.push(`_p=$(cat ${shellSingleQuote(arguments_.promptFile)})`, `rm -rf ${shellSingleQuote(promptDir)}`, `exec ${wrapped} "$_p"`);
     return lines.join(" && ");
 }
+function wrapAgentForHostRunner(arguments_) {
+    if (arguments_.runner === "none") {
+        return arguments_.agentCmd;
+    }
+    // buildLaunchCommand routes `sdx` through buildSdxLaunchCommand, so the
+    // only remaining shape here is `safehouse`. Treat the explicit branch as
+    // the safehouse wrap to keep this function readable; the `sdx` arm exists
+    // only to satisfy TS's exhaustiveness checker.
+    /* v8 ignore next 3 @preserve -- buildLaunchCommand short-circuits sdx before calling this helper */
+    if (arguments_.runner === "sdx") {
+        return arguments_.agentCmd;
+    }
+    // safehouse: skip the wrap if `cmd` already starts with `safehouse` so
+    // legacy configs don't double-wrap.
+    const cmdStartsWithSafehouse = /^safehouse(\s|$)/.test(arguments_.rawCmd);
+    if (cmdStartsWithSafehouse) {
+        return arguments_.agentCmd;
+    }
+    return [shellSingleQuote(SAFEHOUSE_CLEARANCE_WRAPPER_PATH), arguments_.agentCmd].join(" ");
+}
+function buildSdxLaunchCommand(arguments_) {
+    /* v8 ignore next 5 @preserve -- setupWorkspace passes sandboxName + sandbox config when picking sdx; missing fields are programmer errors */
+    if (arguments_.sandboxName === undefined || arguments_.definition.sandbox === undefined) {
+        throw new Error("buildLaunchCommand: runner='sdx' requires sandboxName and a model `sandbox` config block (set sandbox.agent on the model in config.ts).");
+    }
+    const promptDir = dirname(arguments_.promptFile);
+    const agentCmd = renderAgentCommand({
+        agentCmd: arguments_.definition.cmd,
+        worktreeDir: arguments_.worktreeDir,
+        sandboxName: arguments_.sandboxName,
+    });
+    const setupCommand = arguments_.definition.sandbox.setupCommand ?? DEFAULT_SANDBOX_SETUP_COMMAND;
+    const innerParts = [setupWithStatusReporting(setupCommand)];
+    if (arguments_.secretsFile !== undefined) {
+        innerParts.push(unsetSecretsLine());
+    }
+    innerParts.push(`exec ${agentCmd} "$@"`);
+    const innerCommand = innerParts.join("; ");
+    // Passthrough form (`-e KEY` without `=VALUE`): sbx reads each value
+    // from its own env at invocation time — populated by sourceSecretsLine
+    // a few lines up. Avoids `-e KEY="$KEY"`, which would embed the value
+    // in argv and break on `"`, `$`, or backticks in the token.
+    const sbxEnvironmentFlags = arguments_.secretsFile === undefined
+        ? ""
+        : `${BUILD_SECRET_NAMES.map((name) => `-e ${name}`).join(" ")} `;
+    const lines = [];
+    if (arguments_.secretsFile !== undefined) {
+        lines.push(sourceSecretsLine(arguments_.secretsFile));
+    }
+    lines.push(`_p=$(cat ${shellSingleQuote(arguments_.promptFile)})`, `rm -rf ${shellSingleQuote(promptDir)}`, `exec sbx exec -it ${sbxEnvironmentFlags}-w ${shellSingleQuote(arguments_.worktreeDir)} ${shellSingleQuote(arguments_.sandboxName)} sh -lc ${shellSingleQuote(innerCommand)} sh "$_p"`);
+    return lines.join(" && ");
+}

package/dist/lib/localRunner.d.ts

@@ -1,3 +1,24 @@
+import type { LocalRunner, LocalRunnerSetting } from "./config.ts";
 import type { HostCapabilities } from "./host.ts";
-export declare function assertLocalRunnerRequirements(host: HostCapabilities): void;
+/**
+ * Resolve `local.runner` from config + host capabilities into a concrete
+ * backend. `auto` defaults to safehouse on macOS and sdx on Linux — both
+ * are the deny-first paths for their platform. `none` and the explicit
+ * names pass through unchanged so users always get exactly what they
+ * asked for. Pure: takes everything it needs as arguments so the
+ * dispatcher can test platform pivots without touching real hosts.
+ */
+export declare function resolveLocalRunner(setting: LocalRunnerSetting, host: HostCapabilities): LocalRunner;
+/**
+ * Verify the host can run the chosen local isolation backend before we
+ * create a worktree. The runner has already been resolved from
+ * `config.local.runner` (via `resolveLocalRunner`), so `auto` never gets
+ * here — the caller passes `safehouse`, `sdx`, or `none`.
+ *
+ * `none` is a deliberately unsafe escape hatch. It is never selected
+ * implicitly (`auto` picks `safehouse`/`sdx`); when the user has set it
+ * explicitly, this helper logs a single warning so the unsandboxed launch
+ * is visible in groundcrew's log, but does not throw.
+ */
+export declare function assertLocalRunnerRequirements(host: HostCapabilities, runner: LocalRunner): void;
 //# sourceMappingURL=localRunner.d.ts.map

package/dist/lib/localRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"localRunner.d.ts","sourceRoot":"","sources":["../../src/lib/localRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAS1E"}
+{"version":3,"file":"localRunner.d.ts","sourceRoot":"","sources":["../../src/lib/localRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGlD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,gBAAgB,GACrB,WAAW,CAQb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CA6B/F"}

package/dist/lib/localRunner.js

@@ -1,8 +1,51 @@
-export function assertLocalRunnerRequirements(host) {
-    if (!host.isSafehouseSupported) {
-        throw new Error("groundcrew runs require macOS with Safehouse. Linux/WSL is not supported.");
+import { log } from "./util.js";
+/**
+ * Resolve `local.runner` from config + host capabilities into a concrete
+ * backend. `auto` defaults to safehouse on macOS and sdx on Linux — both
+ * are the deny-first paths for their platform. `none` and the explicit
+ * names pass through unchanged so users always get exactly what they
+ * asked for. Pure: takes everything it needs as arguments so the
+ * dispatcher can test platform pivots without touching real hosts.
+ */
+export function resolveLocalRunner(setting, host) {
+    if (setting !== "auto") {
+        return setting;
     }
-    if (!host.hasSafehouse) {
-        throw new Error("groundcrew runs require `safehouse` on PATH. Install Safehouse from https://agent-safehouse.dev/ and retry.");
+    // macOS → safehouse; everything else (Linux/WSL, exotic platforms) → sdx.
+    // `assertLocalRunnerRequirements` then enforces sdx's platform/binary
+    // preconditions and surfaces a precise error on truly unsupported hosts.
+    return host.isMacOS ? "safehouse" : "sdx";
+}
+/**
+ * Verify the host can run the chosen local isolation backend before we
+ * create a worktree. The runner has already been resolved from
+ * `config.local.runner` (via `resolveLocalRunner`), so `auto` never gets
+ * here — the caller passes `safehouse`, `sdx`, or `none`.
+ *
+ * `none` is a deliberately unsafe escape hatch. It is never selected
+ * implicitly (`auto` picks `safehouse`/`sdx`); when the user has set it
+ * explicitly, this helper logs a single warning so the unsandboxed launch
+ * is visible in groundcrew's log, but does not throw.
+ */
+export function assertLocalRunnerRequirements(host, runner) {
+    if (runner === "safehouse") {
+        if (!host.isSafehouseSupported) {
+            throw new Error("Local groundcrew runs with the safehouse runner require macOS. On Linux/WSL, set local.runner to 'sdx' (default) or 'auto'.");
+        }
+        if (!host.hasSafehouse) {
+            throw new Error("Local groundcrew runs require `safehouse` on PATH. Install Safehouse from https://agent-safehouse.dev/ and retry.");
+        }
+        return;
+    }
+    if (runner === "sdx") {
+        if (!host.isSdxSupported) {
+            throw new Error("Local groundcrew runs with the sdx runner require macOS or Linux.");
+        }
+        if (!host.hasSbx) {
+            throw new Error("Local groundcrew runs with the sdx runner require `sbx` (Docker Sandboxes) on PATH. Install from https://docs.docker.com/sandboxes/ and retry.");
+        }
+        return;
     }
+    // runner === "none"
+    log("WARNING: local.runner='none' — agent process will run on the host without sandboxing. Only use this when you understand the implications.");
 }

package/dist/lib/workspaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../../src/lib/workspaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAG1E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AA+L7C,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,oBAAoB,CAAC;IAChC,QAAQ,EAAE,aAAa,CAAC;IACxB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,mBAAmB,CAUtF;AA+ND,iBAAe,eAAe,CAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAezB;AAED,eAAO,MAAM,UAAU;IACf,IAAI,SAAS,cAAc,QAAQ,QAAQ,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvF,KAAK;IACC,KAAK,SAAS,cAAc,QAAQ,MAAM,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhF,UAAU,SACN,cAAc,QAChB,MAAM,WACH,WAAW,GACnB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;CAI5C,CAAC"}
+{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../../src/lib/workspaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAI1E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAgU7C,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,oBAAoB,CAAC;IAChC,QAAQ,EAAE,aAAa,CAAC;IACxB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,mBAAmB,CAUtF;AA+ND,iBAAe,eAAe,CAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAezB;AAED,eAAO,MAAM,UAAU;IACf,IAAI,SAAS,cAAc,QAAQ,QAAQ,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvF,KAAK;IACC,KAAK,SAAS,cAAc,QAAQ,MAAM,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhF,UAAU,SACN,cAAc,QAChB,MAAM,WACH,WAAW,GACnB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;CAI5C,CAAC"}

package/dist/lib/workspaces.js

@@ -6,6 +6,7 @@
  */
 import { runCommandAsync } from "./commandRunner.js";
 import { detectHostCapabilities } from "./host.js";
+import { shellSingleQuote } from "./shell.js";
 import { errorMessage, log, readEnvironmentVariable } from "./util.js";
 async function runWorkspaceCommand(command, arguments_, signal) {
     return signal === undefined
@@ -24,23 +25,30 @@ function parseCmuxList(output) {
         if (typeof ws.title !== "string" || ws.title.length === 0) {
             continue;
         }
-        items.push({ title: ws.title, ref: pickCmuxRef({ ...ws, title: ws.title }) });
+        const id = pickCmuxId(ws);
+        if (id === undefined) {
+            log(`cmux list-workspaces returned workspace "${ws.title}" without a usable id or ref; skipping`);
+            continue;
+        }
+        items.push({ title: ws.title, id });
     }
     return items;
 }
 /**
- * Pick the most-specific identifier cmux returned for this workspace.
- * Caller has already verified `title` is non-empty, so the title fallback
- * is always defined.
+ * The stable workspace handle cmux v2 expects in JSON-RPC params. Prefer
+ * the UUID; fall back to the legacy `workspace:N` short ref when older
+ * cmux builds don't surface it. Returns `undefined` when neither is
+ * available — cmux v2 `workspace.close` rejects titles, so we must never
+ * forward `title` as a workspace handle.
  */
-function pickCmuxRef(ws) {
-    if (typeof ws.ref === "string" && ws.ref.length > 0) {
-        return ws.ref;
-    }
+function pickCmuxId(ws) {
     if (typeof ws.id === "string" && ws.id.length > 0) {
         return ws.id;
     }
-    return ws.title;
+    if (typeof ws.ref === "string" && ws.ref.length > 0) {
+        return ws.ref;
+    }
+    return undefined;
 }
 async function listCmuxRaw(signal) {
     try {
@@ -54,13 +62,17 @@ async function listCmuxRaw(signal) {
         return undefined;
     }
 }
-function extractCmuxOpenRef(output) {
+function extractCmuxOpenId(output) {
     try {
-        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- cmux --json prints a workspace ref/id object
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- cmux --json prints a workspace_id/ref object
         const parsed = JSON.parse(output);
-        const candidate = parsed.ref ?? parsed.id ?? "";
-        if (candidate.length > 0) {
-            return candidate;
+        const uuid = parsed.workspace_id ?? parsed.id ?? "";
+        if (uuid.length > 0) {
+            return uuid;
+        }
+        const ref = parsed.workspace_ref ?? parsed.ref ?? "";
+        if (ref.length > 0) {
+            return ref;
         }
     }
     catch {
@@ -69,7 +81,91 @@ function extractCmuxOpenRef(output) {
     const match = /workspace:\d+/.exec(output);
     return match ? match[0] : undefined;
 }
-async function applyCmuxStatus(ref, status, signal) {
+/**
+ * Inspect `cmux current-workspace`. When groundcrew is itself launched
+ * inside a cmux SSH workspace, `workspace.create` lands the new workspace
+ * on the local (macOS) cmux app rather than the remote where the agent's
+ * worktree lives. We can't replicate cmux's full SSH bootstrap
+ * (relay_port, daemon, etc.) from the remote side, so we instead wrap the
+ * agent launch command in a plain `ssh` to the same destination. Returns
+ * `undefined` when there is nothing to inherit, leaving callers free to
+ * launch locally as usual.
+ */
+async function probeCurrentCmuxRemote(signal) {
+    if (readEnvironmentVariable("CMUX_WORKSPACE_ID") === undefined) {
+        return undefined;
+    }
+    let output;
+    try {
+        output = await runWorkspaceCommand("cmux", ["--json", "current-workspace"], signal);
+    }
+    catch (error) {
+        if (isSignalAborted(signal)) {
+            throw error;
+        }
+        // CMUX_WORKSPACE_ID is set, so we are inside a cmux workspace and a
+        // probe failure means we cannot tell whether this is an SSH context.
+        // Silently degrading to the local path would point cmux at a working
+        // directory that lives on a remote host; surface the failure instead
+        // so the caller can roll the worktree back rather than launch into
+        // the void.
+        throw new Error(`cmux current-workspace probe failed while CMUX_WORKSPACE_ID is set: ${errorMessage(error)}`, { cause: error });
+    }
+    try {
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- cmux --json current-workspace shape per v2 API
+        const parsed = JSON.parse(output);
+        const remote = parsed.workspace?.remote;
+        if (remote === undefined ||
+            remote.connected !== true ||
+            remote.transport !== "ssh" ||
+            typeof remote.destination !== "string" ||
+            remote.destination.length === 0) {
+            return undefined;
+        }
+        const inherited = { destination: remote.destination };
+        if (typeof remote.port === "number") {
+            inherited.port = remote.port;
+        }
+        if (typeof remote.identity_file === "string" && remote.identity_file.length > 0) {
+            inherited.identity_file = remote.identity_file;
+        }
+        if (Array.isArray(remote.ssh_options) && remote.ssh_options.length > 0) {
+            inherited.ssh_options = remote.ssh_options;
+        }
+        return inherited;
+    }
+    catch (error) {
+        // Same reasoning as the command-failure branch above: with
+        // CMUX_WORKSPACE_ID set, malformed JSON means we cannot decide
+        // between local and SSH context, so refuse rather than silently
+        // launching at the wrong working directory.
+        throw new Error(`cmux current-workspace returned malformed output while CMUX_WORKSPACE_ID is set: ${errorMessage(error)}`, { cause: error });
+    }
+}
+/**
+ * Compose an `ssh -t <destination> -- <cd && cmd>` invocation that lands
+ * a new cmux workspace's terminal on the same SSH remote where
+ * groundcrew is running. Path-bearing fields (`cwd`, the launch script
+ * inside `command`) stay valid because the remote shell evaluates them.
+ * The outermost return value is a single shell string suitable for
+ * `cmux new-workspace --command`.
+ */
+function buildSshWrappedCommand(spec, remote) {
+    const remoteShell = `cd ${shellSingleQuote(spec.cwd)} && ${spec.command}`;
+    const sshTokens = ["ssh", "-t"];
+    if (remote.port !== undefined) {
+        sshTokens.push("-p", String(remote.port));
+    }
+    if (remote.identity_file !== undefined) {
+        sshTokens.push("-i", shellSingleQuote(remote.identity_file));
+    }
+    for (const option of remote.ssh_options ?? []) {
+        sshTokens.push("-o", shellSingleQuote(option));
+    }
+    sshTokens.push(shellSingleQuote(remote.destination), "--", shellSingleQuote(remoteShell));
+    return sshTokens.join(" ");
+}
+async function applyCmuxStatus(workspaceId, status, signal) {
     const arguments_ = ["set-status", "model", status.text];
     if (status.icon !== undefined) {
         arguments_.push("--icon", status.icon);
@@ -77,41 +173,40 @@ async function applyCmuxStatus(ref, status, signal) {
     if (status.color !== undefined) {
         arguments_.push("--color", status.color);
     }
-    arguments_.push("--workspace", ref);
+    arguments_.push("--workspace", workspaceId);
     await runWorkspaceCommand("cmux", arguments_, signal);
 }
-async function closeCmuxWorkspace(refOrName, signal) {
-    await runWorkspaceCommand("cmux", ["close-workspace", "--workspace", refOrName], signal);
+async function closeCmuxWorkspace(workspaceId, signal) {
+    await runWorkspaceCommand("cmux", ["close-workspace", "--workspace", workspaceId], signal);
 }
 const cmuxAdapter = {
     async open(spec, signal) {
-        const output = await runWorkspaceCommand("cmux", [
-            "--json",
-            "new-workspace",
-            "--name",
-            spec.name,
-            "--cwd",
-            spec.cwd,
-            "--command",
-            spec.command,
-        ], signal);
-        const ref = extractCmuxOpenRef(output);
-        if (ref === undefined) {
+        const inheritedRemote = await probeCurrentCmuxRemote(signal);
+        const newWorkspaceArguments = ["--json", "new-workspace", "--name", spec.name];
+        if (inheritedRemote === undefined) {
+            newWorkspaceArguments.push("--working-directory", spec.cwd, "--command", spec.command);
+        }
+        else {
+            // Skip --working-directory: the path is on the SSH remote and would
+            // fall back to $HOME (macOS) when cmux tries to chdir locally. The
+            // wrapped ssh command does its own `cd` on the remote side.
+            newWorkspaceArguments.push("--command", buildSshWrappedCommand(spec, inheritedRemote));
+        }
+        const output = await runWorkspaceCommand("cmux", newWorkspaceArguments, signal);
+        const workspaceId = extractCmuxOpenId(output);
+        if (workspaceId === undefined) {
             log(`cmux new-workspace returned unrecognized output for ${spec.name}; if a workspace was created, run \`cmux close-workspace\` manually.`);
             throw new Error(`Unexpected cmux output: ${output}`);
         }
         if (spec.status !== undefined) {
             try {
-                await applyCmuxStatus(ref, spec.status, signal);
+                await applyCmuxStatus(workspaceId, spec.status, signal);
             }
             catch (error) {
-                try {
-                    await closeCmuxWorkspace(ref, signal);
-                }
-                catch (closeError) {
-                    log(`cmux close-workspace failed for ${spec.name}: ${errorMessage(closeError)}`);
-                }
-                throw error;
+                // v2 cmux builds may not implement `set-status`; status pills are
+                // a nice-to-have, not load-bearing. Log and keep the workspace
+                // rather than tearing down a successful launch.
+                log(`cmux set-status failed for ${spec.name} (continuing): ${errorMessage(error)}`);
             }
         }
     },
@@ -122,7 +217,10 @@ const cmuxAdapter = {
     async close(name, signal) {
         const raw = await listCmuxRaw(signal);
         if (raw === undefined) {
-            await closeCmuxWorkspace(name, signal);
+            // cmux v2 `workspace.close` rejects titles, so forwarding `name`
+            // would always fail. The list failure has already been logged by
+            // `listCmuxRaw`; bail rather than guarantee a downstream error.
+            log(`cmux close-workspace skipped for ${name}: list-workspaces failed, no usable id`);
             return;
         }
         const match = raw.find((ws) => ws.title === name);
@@ -130,7 +228,7 @@ const cmuxAdapter = {
             return;
         }
         try {
-            await closeCmuxWorkspace(match.ref, signal);
+            await closeCmuxWorkspace(match.id, signal);
         }
         catch (error) {
             if (isSignalAborted(signal)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",