@clipboard-health/groundcrew 2.1.0 → 2.2.0

package/dist/commands/setupWorkspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASvF,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAgBD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAmED,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CAoEf;AA6CD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASvF,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAgBD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAmED,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CA6Ef;AA0FD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/commands/setupWorkspace.js

@@ -10,7 +10,7 @@ import { createLinearIssueStatusUpdater } from "../lib/linearIssueStatus.js";
 import { assertLocalRunnerRequirements } from "../lib/localRunner.js";
 import { errorMessage, getLinearClient, log, readEnvironmentVariable } from "../lib/util.js";
 import { workspaces } from "../lib/workspaces.js";
-import { worktrees } from "../lib/worktrees.js";
+import { isWorktreeAlreadyExistsError, worktrees } from "../lib/worktrees.js";
 async function fetchTicket(ticket) {
     const client = getLinearClient();
     const issue = await client.issue(ticket.toUpperCase());
@@ -78,9 +78,19 @@ export async function setupWorkspace(config, options, runOptions = {}) {
     assertLocalRunnerRequirements(await detectHostCapabilities(signal));
     await ensureClearance({ logger: log });
     const spec = { repository, ticket };
-    const created = signal === undefined
-        ? await worktrees.create(config, spec)
-        : await worktrees.create(config, spec, signal);
+    let created;
+    try {
+        created =
+            signal === undefined
+                ? await worktrees.create(config, spec)
+                : await worktrees.create(config, spec, signal);
+    }
+    catch (error) {
+        if (isWorktreeAlreadyExistsError(error)) {
+            await logAccessHintForExistingWorkspace({ config, ticket, signal });
+        }
+        throw error;
+    }
     const { branchName, dir: launchDir } = created;
     const worktreeName = `${repository}-${ticket}`;
     // Anything that fails after the worktree is on disk must roll it back
@@ -120,12 +130,43 @@ export async function setupWorkspace(config, options, runOptions = {}) {
         log(`Workspace "${ticket}" launched (${model})`);
         log(`  Worktree: ${launchDir}`);
         log(`  Branch:   ${branchName}`);
+        await logWorkspaceAccessHint({ config, ticket, signal });
     }
     catch (error) {
         await rollbackWorktree({ config, entry: created, promptDir });
         throw error;
     }
 }
+/**
+ * Probe the workspace backend and, if a workspace for `ticket` is still
+ * live, log the access hint. Used on the pre-launch error path (e.g. the
+ * worktree already exists from a prior run) so the user can find the
+ * still-running session instead of being told only that the worktree is
+ * in the way. Silent when the probe is unavailable or the workspace is
+ * gone — we don't want to point at a window that doesn't exist.
+ */
+async function logAccessHintForExistingWorkspace(arguments_) {
+    const { config, ticket, signal } = arguments_;
+    const accessHint = await workspaces.accessHint(config, ticket, signal);
+    if (accessHint === undefined) {
+        return;
+    }
+    const probe = await workspaces.probe(config, signal);
+    if (probe.kind !== "ok" || !probe.names.has(ticket)) {
+        return;
+    }
+    logAccessHint(accessHint);
+}
+async function logWorkspaceAccessHint(arguments_) {
+    const accessHint = await workspaces.accessHint(arguments_.config, arguments_.ticket, arguments_.signal);
+    if (accessHint === undefined) {
+        return;
+    }
+    logAccessHint(accessHint);
+}
+function logAccessHint(accessHint) {
+    log(`  Attach:   ${accessHint.command}`);
+}
 async function rollbackWorktree(arguments_) {
     log(`Setup failed; rolling back worktree ${arguments_.entry.repository}-${arguments_.entry.ticket}...`);
     let result;

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

@@ -1 +1 @@
-{"version":3,"file":"boardSource.d.ts","sourceRoot":"","sources":["../../src/lib/boardSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAM7F,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,0FAA0F;IAC1F,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,eAAe,CAExE;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,YAAmB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAMjF;CACF;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,8DAA8D;IAC9D,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAC9B;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAUpE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAEhF;AA+LD,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE;IACnD,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,aAAa,CAAC,CAmDzB"}
+{"version":3,"file":"boardSource.d.ts","sourceRoot":"","sources":["../../src/lib/boardSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAM7F,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,0FAA0F;IAC1F,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,eAAe,CAExE;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,YAAmB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAMjF;CACF;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,8DAA8D;IAC9D,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAC9B;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAUpE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAEhF;AAmMD,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE;IACnD,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,aAAa,CAAC,CAmDzB"}

package/dist/lib/boardSource.js

@@ -163,7 +163,11 @@ function escapeRegex(value) {
 // must beat `api` when both are configured. `\b` treats `-` as a word
 // boundary, so without this ordering `api` would win on `api-admin`.
 function buildRepositoryRegex(config) {
-    const alternation = config.workspace.knownRepositories
+    const candidates = config.workspace.knownRepositories.flatMap((repo) => {
+        const slashIndex = repo.indexOf("/");
+        return slashIndex === -1 ? [repo] : [repo, repo.slice(slashIndex + 1)];
+    });
+    const alternation = candidates
         .toSorted((a, b) => b.length - a.length)
         .map(escapeRegex)
         .join("|");
@@ -223,14 +227,29 @@ function parseRepository(arguments_) {
             repositories: config.workspace.knownRepositories,
         });
     }
-    const repository = repositoryRegex.exec(description)?.[1];
-    if (repository === undefined) {
+    const matched = repositoryRegex.exec(description)?.[1];
+    if (matched === undefined) {
         throw new RepositoryResolutionError({
             ticket,
             repositories: config.workspace.knownRepositories,
         });
     }
-    return repository;
+    // Resolve the match to a known repo. The regex may capture a bare repo name
+    // (no org prefix) when only that appears in the description; the filter
+    // handles both full "owner/repo" and bare "repo" matches. Reject if
+    // ambiguous (same bare name under multiple orgs).
+    const candidates = config.workspace.knownRepositories.filter((r) => r === matched || r.endsWith(`/${matched}`));
+    if (candidates.length !== 1) {
+        throw new RepositoryResolutionError({
+            ticket,
+            repositories: config.workspace.knownRepositories,
+        });
+    }
+    /* v8 ignore next 3 @preserve -- candidates.length===1 guarantees [0] is defined */
+    if (candidates[0] === undefined) {
+        throw new Error("unreachable");
+    }
+    return candidates[0];
 }
 function parseAgentLabels(labels, config) {
     const agentLabels = labels.filter((label) => label.name.startsWith(AGENT_LABEL_PREFIX));

package/dist/lib/workspaces.d.ts

@@ -16,6 +16,10 @@ export interface WorkspaceStatus {
     color?: string;
     icon?: string;
 }
+export interface WorkspaceAccessHint {
+    kind: "attachCommand";
+    command: string;
+}
 export interface OpenSpec {
     /** Ticket id; becomes the workspace's name. */
     name: string;
@@ -53,6 +57,7 @@ export declare const workspaces: {
     open(config: ResolvedConfig, spec: OpenSpec, signal?: AbortSignal): Promise<void>;
     probe: typeof probeWorkspaces;
     close(config: ResolvedConfig, name: string, signal?: AbortSignal): Promise<void>;
+    accessHint(config: ResolvedConfig, name: string, signal?: AbortSignal): Promise<WorkspaceAccessHint | undefined>;
 };
 export {};
 //# sourceMappingURL=workspaces.d.ts.map

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,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;AAoL7C,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;AAwND,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;CAIvF,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;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"}

package/dist/lib/workspaces.js

@@ -146,6 +146,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 +192,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 +274,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 +316,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 +328,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 +376,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;AAqND,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() {
@@ -159,7 +170,28 @@ async function removeWorktree(config, entry, options) {
             removeArguments.push("--force");
         }
         removeArguments.push(entry.dir);
-        await runCommandAsync("git", removeArguments, longRunningCommandOptions(options.signal));
+        try {
+            await runCommandAsync("git", removeArguments, longRunningCommandOptions(options.signal));
+        }
+        catch (error) {
+            // git's `fatal: ... use --force to delete it` line goes to inherited
+            // stderr, so the captured error is just "Exit status: 128". Probe the
+            // worktree ourselves so the failure message explains the condition
+            // (modified/untracked files) and points at `crew cleanup --force`.
+            if (options.force || options.signal?.aborted === true) {
+                throw error;
+            }
+            const dirtiness = await probeWorktreeDirtiness(entry.dir, options.signal);
+            if (dirtiness.kind !== "dirty") {
+                throw error;
+            }
+            throw new Error(describeDirtyWorktree({
+                ticket: entry.ticket,
+                dir: entry.dir,
+                modified: dirtiness.modified,
+                untracked: dirtiness.untracked,
+            }), { cause: error });
+        }
     }
     else {
         log(`Worktree directory ${entry.dir} not found, pruning stale refs...`);
@@ -172,6 +204,45 @@ async function removeWorktree(config, entry, options) {
         ...signalProperty(options.signal),
     });
 }
+async function probeWorktreeDirtiness(worktreeDir, signal) {
+    let output;
+    try {
+        output = await runCommandAsync("git", ["-C", worktreeDir, "status", "--porcelain"], signalProperty(signal));
+    }
+    catch {
+        return { kind: "unknown" };
+    }
+    let modified = 0;
+    let untracked = 0;
+    for (const line of output.split("\n")) {
+        if (line.length === 0) {
+            continue;
+        }
+        if (line.startsWith("??")) {
+            untracked += 1;
+        }
+        else {
+            modified += 1;
+        }
+    }
+    if (modified === 0 && untracked === 0) {
+        return { kind: "clean" };
+    }
+    return { kind: "dirty", modified, untracked };
+}
+function describeDirtyWorktree(arguments_) {
+    const { ticket, dir, modified, untracked } = arguments_;
+    const parts = [];
+    if (modified > 0) {
+        parts.push(`${modified} modified file${modified === 1 ? "" : "s"}`);
+    }
+    if (untracked > 0) {
+        parts.push(`${untracked} untracked file${untracked === 1 ? "" : "s"}`);
+    }
+    const summary = parts.join(" and ");
+    const pronoun = modified + untracked === 1 ? "it" : "them";
+    return `worktree has ${summary}. Run \`crew cleanup --force ${ticket}\` to discard ${pronoun}, or commit/stash in ${dir} first.`;
+}
 function list(config) {
     return listWorktrees(config);
 }
@@ -179,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.0",
+  "version": "2.2.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",