@clipboard-health/groundcrew 2.1.1 → 2.3.0

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)) {
@@ -146,6 +244,12 @@ const cmuxAdapter = {
             throw error;
         }
     },
+    accessHint(_name) {
+        // cmux is a TUI; users surface workspaces by launching the cmux app,
+        // not a shell command. No useful hint to emit.
+        // oxlint-disable-next-line unicorn/no-useless-undefined -- explicit signal that the backend has no hint
+        return undefined;
+    },
 };
 export function resolveWorkspaceKind(arguments_) {
     const { config, host } = arguments_;
@@ -186,6 +290,9 @@ const TMUX_SESSION = "groundcrew";
 // sentinel and filter it out — it stays around as a placeholder so the
 // session doesn't collapse when the last ticket window closes.
 const TMUX_IDLE_WINDOW = "_groundcrew_idle";
+function tmuxTarget(name) {
+    return `${TMUX_SESSION}:${name}`;
+}
 function isTmuxNotFoundError(error) {
     // runCommand surfaces the child's stderr in error.message, so the "no
     // server" / "missing session" / "can't find window" signatures are visible
@@ -265,7 +372,7 @@ function parseTmuxWindows(output) {
 const tmuxAdapter = {
     async open(spec, signal) {
         await ensureTmuxSession(signal);
-        const target = `${TMUX_SESSION}:${spec.name}`;
+        const target = tmuxTarget(spec.name);
         const keepDeadWindowsEnv = readEnvironmentVariable("GROUNDCREW_KEEP_DEAD_WINDOWS");
         const keepDeadWindows = keepDeadWindowsEnv !== undefined && keepDeadWindowsEnv.length > 0;
         await runWorkspaceCommand("tmux", [
@@ -307,7 +414,7 @@ const tmuxAdapter = {
     },
     async close(name, signal) {
         try {
-            await runWorkspaceCommand("tmux", ["kill-window", "-t", `${TMUX_SESSION}:${name}`], signal);
+            await runWorkspaceCommand("tmux", ["kill-window", "-t", tmuxTarget(name)], signal);
         }
         catch (error) {
             if (isSignalAborted(signal)) {
@@ -319,6 +426,9 @@ const tmuxAdapter = {
             throw error;
         }
     },
+    accessHint(name) {
+        return { kind: "attachCommand", command: `tmux attach -t ${tmuxTarget(name)}` };
+    },
 };
 // Per-config cache: production resolves the adapter once at first use
 // (loadConfig returns a frozen, cached instance); each test uses a fresh
@@ -364,4 +474,8 @@ export const workspaces = {
         const adapter = await adapterFor(config, signal);
         await adapter.close(name, signal);
     },
+    async accessHint(config, name, signal) {
+        const adapter = await adapterFor(config, signal);
+        return adapter.accessHint(name);
+    },
 };

package/dist/lib/worktrees.d.ts

@@ -10,6 +10,11 @@
 import type { ResolvedConfig } from "./config.ts";
 import { type WorkspaceProbe } from "./workspaces.ts";
 export type WorktreeKind = "host";
+export declare class WorktreeAlreadyExistsError extends Error {
+    readonly dir: string;
+    constructor(dir: string);
+}
+export declare function isWorktreeAlreadyExistsError(error: unknown): error is WorktreeAlreadyExistsError;
 export interface WorktreeEntry {
     repository: string;
     /** Linear ticket id, lowercased — e.g. "team-220". */

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

@@ -1 +1 @@
-{"version":3,"file":"worktrees.d.ts","sourceRoot":"","sources":["../../src/lib/worktrees.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,KAAK,cAAc,EAAc,MAAM,iBAAiB,CAAC;AAIlE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAoSD,iBAAS,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,EAAE,CAErD;AAED,iBAAS,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAE7E;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAUxB;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,wDAAwD;IACxD,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAKD,iBAAe,QAAQ,CACrB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAkDzB;AAED,eAAO,MAAM,SAAS;;;;;;CAMrB,CAAC"}
+{"version":3,"file":"worktrees.d.ts","sourceRoot":"","sources":["../../src/lib/worktrees.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,KAAK,cAAc,EAAc,MAAM,iBAAiB,CAAC;AAIlE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAgB,GAAG,EAAE,MAAM,CAAC;IAE5B,YAAmB,GAAG,EAAE,MAAM,EAI7B;CACF;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAEhG;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAoSD,iBAAS,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,EAAE,CAErD;AAED,iBAAS,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAE7E;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,wDAAwD;IACxD,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAKD,iBAAe,QAAQ,CACrB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAkDzB;AAED,eAAO,MAAM,SAAS;;;;;;CAMrB,CAAC"}

package/dist/lib/worktrees.js

@@ -14,6 +14,17 @@ import { runCommandAsync } from "./commandRunner.js";
 import { errorMessage, log } from "./util.js";
 import { workspaces } from "./workspaces.js";
 const LONG_RUNNING_COMMAND_OPTIONS = { stdio: "inherit", timeoutMs: 0 };
+export class WorktreeAlreadyExistsError extends Error {
+    dir;
+    constructor(dir) {
+        super(`Worktree already exists: ${dir}`);
+        this.dir = dir;
+        this.name = "WorktreeAlreadyExistsError";
+    }
+}
+export function isWorktreeAlreadyExistsError(error) {
+    return error instanceof WorktreeAlreadyExistsError;
+}
 const TICKET_RE = /^[a-z][\da-z]*-\d+$/;
 const TICKET_DIR_RE = /^(.+)-([a-z][\da-z]*-\d+)$/;
 function branchPrefix() {
@@ -239,11 +250,9 @@ function findByTicket(config, ticket) {
     return list(config).filter((entry) => entry.ticket === ticket);
 }
 async function create(config, spec, signal) {
-    const existing = findByTicket(config, spec.ticket).filter((entry) => entry.repository === spec.repository);
-    if (existing.length > 0) {
-        const [first] = existing;
-        /* v8 ignore next @preserve -- length>0 guarantees [0] is defined */
-        throw new Error(`Worktree already exists: ${first?.dir}`);
+    const existing = findByTicket(config, spec.ticket).find((entry) => entry.repository === spec.repository);
+    if (existing !== undefined) {
+        throw new WorktreeAlreadyExistsError(existing.dir);
     }
     return await createWorktree(config, spec, signal);
 }

package/package.json

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