@clipboard-health/groundcrew 4.0.2 → 4.0.3

package/README.md

@@ -83,15 +83,17 @@ In Linear, assign tickets to yourself and add an `agent-*` label (`agent-claude`
 crew init [--global | --local] [--force] [--dry-run]     # create a crew.config.ts
 crew doctor                                              # check setup
 crew status [<TICKET>]                                   # inspect current state or one ticket
-crew run                                                 # one-shot dispatch
+crew run                                                 # one-shot orchestration
 crew run --watch                                         # poll forever
-crew run --ticket <TICKET>                               # dispatch one ticket
+crew start <TICKET>                                      # provision + launch one ticket now
 crew setup repos [<repo>...] [--dry-run]                 # clone known repos via gh
-crew interrupt <TICKET> [--reason <text>]                # stop workspace, keep worktree
+crew stop <TICKET> [--reason <text>]                     # stop workspace, keep worktree
 crew resume <TICKET>                                     # reopen a paused ticket
 crew cleanup <TICKET>                                    # tear down every worktree for a ticket
 ```
 
+Deprecated aliases still work but print a warning and will be removed in the next major version: `crew interrupt` → `crew stop`, `crew run --ticket <TICKET>` → `crew start <TICKET>`, `crew doctor --ticket <TICKET>` → `crew status <TICKET>`.
+
 ## Configuration
 
 Two keys are required; everything else has a default.
@@ -109,7 +111,7 @@ The branch prefix (`<prefix>-<TICKET>`) is derived from `os.userInfo().username`
 - `agent-claude`, `agent-codex`, `agent-<name>` → that model.
 - `agent-any` → the model with the most available session capacity.
 - Unknown `agent-<name>` → falls back to `models.default` with a warning.
-- No `agent-*` label → ignored by `crew run`. Dispatch on demand with `crew run --ticket <TICKET>` (also falls back to `models.default`).
+- No `agent-*` label → ignored by `crew run`. Dispatch on demand with `crew start <TICKET>` (also falls back to `models.default`).
 - Todo tickets blocked by non-terminal blockers are skipped until their blockers reach a terminal status.
 
 Status classification uses Linear's workflow `state.type` (`unstarted`, `started`, `completed`, `canceled`, `duplicate`), so renamed status columns work without configuration. Parent issues with children are ignored — sub-issues are the work items.
@@ -136,7 +138,7 @@ Resolution order: `GROUNDCREW_CONFIG` → cosmiconfig project-walk from cwd (any
 | `orchestrator.maximumInProgress`        | `4`                 | Cap on in-progress tickets at once for this `crew` instance.                                                                                                                                                                                                                                                                                                            |
 | `orchestrator.pollIntervalMilliseconds` | `120_000`           | Poll interval in `--watch` mode.                                                                                                                                                                                                                                                                                                                                        |
 | `orchestrator.sessionLimitPercentage`   | `85`                | Number in `(0, 100]`. A model whose codexbar session window exceeds this percentage is skipped that tick.                                                                                                                                                                                                                                                               |
-| `models.default`                        | `"claude"`          | Tiebreak for `agent-any` resolution and fallback for explicit but unknown `agent-*` labels. Also used by `crew run --ticket <TICKET>` for unlabeled tickets. `crew run` without `--ticket` ignores unlabeled tickets and does not apply this default. Must exist in `models.definitions`.                                                                               |
+| `models.default`                        | `"claude"`          | Tiebreak for `agent-any` resolution and fallback for explicit but unknown `agent-*` labels. Also used by `crew start <TICKET>` for unlabeled tickets. `crew run` ignores unlabeled tickets and does not apply this default. Must exist in `models.definitions`.                                                                                                         |
 | `models.definitions`                    | `{ claude, codex }` | Agent definitions. Additive merge with shipped defaults.                                                                                                                                                                                                                                                                                                                |
 | `models.definitions.<name>.cmd`         | —                   | Shell command launched for the model. Runs in the worktree through the resolved `local.runner`. `{{worktree}}` is replaced before launch; `{{sandbox}}` expands to the sbx sandbox name under the sdx runner and an empty string otherwise.                                                                                                                             |
 | `models.definitions.<name>.color`       | —                   | Color for the workspace status pill (cmux only; tmux silently drops it).                                                                                                                                                                                                                                                                                                |
@@ -234,21 +236,30 @@ In Progress (state.type=started) — Multi-event extractor: year inference can p
 
 </details>
 
-### `crew interrupt <TICKET>`
+### `crew start <TICKET>`
+
+Provisions and launches one ticket immediately, bypassing orchestrator eligibility. Use it to dispatch a specific ticket on demand — including unlabeled tickets that `crew run` ignores. (Replaces the deprecated `crew run --ticket <TICKET>`.)
+
+```bash
+crew start HRD-442
+crew start HRD-442 --dry-run
+```
+
+### `crew stop <TICKET>`
 
-Stops a live workspace pane while preserving the ticket worktree and branch. The manual pause button for cases where you need terminal capacity back, want to stop an agent that's going in the wrong direction, or need to inspect the diff before letting another agent continue.
+Stops a live workspace pane while preserving the ticket worktree and branch. The manual pause button for cases where you need terminal capacity back, want to stop an agent that's going in the wrong direction, or need to inspect the diff before letting another agent continue. (Replaces the deprecated `crew interrupt <TICKET>`.)
 
 ```bash
-crew interrupt HRD-442 --reason "wrong implementation direction"
+crew stop HRD-442 --reason "wrong implementation direction"
 crew status HRD-442
 crew resume HRD-442
 ```
 
-The command closes the cmux/tmux workspace if present, records local run state, and never tears down the worktree. If the workspace was already gone but the worktree is still present, interrupt records that fact so status can show the preserved branch.
+The command closes the cmux/tmux workspace if present, records local run state, and never tears down the worktree. If the workspace was already gone but the worktree is still present, stop records that fact so status can show the preserved branch.
 
 ### `crew resume <TICKET>`
 
-Reopens an existing ticket worktree with a continuation prompt. Resume never creates a new worktree; if none exists it fails and leaves re-dispatch to `crew run --ticket <ticket>`.
+Reopens an existing ticket worktree with a continuation prompt. Resume never creates a new worktree; if none exists it fails and leaves re-dispatch to `crew start <ticket>`.
 
 The resume prompt tells the agent to inspect git status and diff before editing, includes the previous interrupt reason when recorded, and reuses the recorded model, repository, branch, runner, sandbox, and workspace backend. When no run-state file exists but a worktree does, resume falls back to Linear resolution for the model and ticket context.
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA6MA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCvD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAwQA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCvD"}

package/dist/cli.js

@@ -11,10 +11,17 @@ import { setupWorkspaceCli } from "./commands/setupWorkspace.js";
 import { statusCli } from "./commands/status.js";
 import { createDefaultUpgradeCliOptions, upgradeCli } from "./commands/upgrade.js";
 import { computeUpgradeNudge, defaultUpgradeCheckCachePath, fetchLatestVersion, } from "./lib/upgrade.js";
-import { errorMessage, readEnvironmentVariable, readTicketArgument, writeError, writeOutput, } from "./lib/util.js";
+import { errorMessage, parseDryRunPositionals, readEnvironmentVariable, readTicketArgument, writeError, writeOutput, } from "./lib/util.js";
 const NUDGE_TTL_MS = 6 * 60 * 60 * 1000;
 const NUDGE_FETCH_TIMEOUT_MS = 1000;
 const requireFromCli = createRequire(import.meta.url);
+/**
+ * Prints a deprecation warning to stderr naming the canonical command and that
+ * the old form is removed in the next major, then lets the caller proceed.
+ */
+function warnDeprecated(forms) {
+    writeError(`crew ${forms.oldForm} is deprecated and will be removed in the next major version; use crew ${forms.newForm} instead.`);
+}
 function setupUsage() {
     return "Usage: crew setup repos [--dry-run] [<repo>...]";
 }
@@ -54,6 +61,16 @@ async function runCli(argv) {
         await orchestrate({ watch, dryRun });
         return;
     }
+    warnDeprecated({ oldForm: "run --ticket", newForm: "start" });
+    await setupWorkspaceCli(ticket, { dryRun });
+}
+const START_USAGE = "crew start <ticket> [--dry-run]";
+async function startCli(argv) {
+    const { dryRun, positionals } = parseDryRunPositionals(argv, START_USAGE);
+    const [ticket, ...extras] = positionals;
+    if (ticket === undefined || ticket.length === 0 || extras.length > 0) {
+        throw new Error(`Usage: ${START_USAGE}`);
+    }
     await setupWorkspaceCli(ticket, { dryRun });
 }
 async function upgradeCliInvoke(argv) {
@@ -80,7 +97,23 @@ async function maybeRunUpgradeNudge(metadata) {
         writeError(message);
     }
 }
+function doctorTicketAlias(argv) {
+    if (argv[0] !== "--ticket") {
+        return undefined;
+    }
+    const ticket = readTicketArgument(argv, 0, "doctor");
+    if (argv.length > 2) {
+        throw new Error("Usage: crew status [<ticket>]");
+    }
+    return ticket;
+}
 async function doctorCli(argv) {
+    const aliasTicket = doctorTicketAlias(argv);
+    if (aliasTicket !== undefined) {
+        warnDeprecated({ oldForm: "doctor --ticket", newForm: "status" });
+        await statusCli([aliasTicket]);
+        return;
+    }
     if (argv.length > 0) {
         throw new Error("Usage: crew doctor");
     }
@@ -94,10 +127,15 @@ const SUBCOMMANDS = {
         invoke: initConfigCli,
     },
     run: {
-        summary: "Run the orchestrator (one-shot by default), or provision one ticket with --ticket",
-        usage: "[--watch] [--dry-run] [--ticket <ticket>]",
+        summary: "Run the orchestrator: poll sources and start eligible tickets (one-shot by default)",
+        usage: "[--watch] [--dry-run]",
         invoke: runCli,
     },
+    start: {
+        summary: "Provision and launch one ticket immediately, bypassing eligibility",
+        usage: "<ticket> [--dry-run]",
+        invoke: startCli,
+    },
     doctor: {
         summary: "Verify host prerequisites (PATH tools, config validity, Linear reachability)",
         usage: "",
@@ -113,11 +151,20 @@ const SUBCOMMANDS = {
         usage: "[--force] <ticket>",
         invoke: cleanupWorkspaceCli,
     },
-    interrupt: {
+    stop: {
         summary: "Stop a live ticket workspace while preserving its worktree",
         usage: "<ticket> [--reason <text>]",
         invoke: interruptWorkspaceCli,
     },
+    interrupt: {
+        summary: "Deprecated alias for `crew stop`",
+        usage: "<ticket> [--reason <text>]",
+        deprecated: true,
+        invoke: async (argv) => {
+            warnDeprecated({ oldForm: "interrupt", newForm: "stop" });
+            await interruptWorkspaceCli(argv);
+        },
+    },
     resume: {
         summary: "Reopen an existing ticket worktree with a continuation prompt",
         usage: "<ticket>",
@@ -148,6 +195,9 @@ function printHelp() {
     writeOutput("");
     writeOutput("Commands:");
     for (const [name, command] of Object.entries(SUBCOMMANDS)) {
+        if (command.deprecated === true) {
+            continue;
+        }
         writeOutput(`  ${name.padEnd(width)}  ${command.summary}`);
         writeOutput(`  ${" ".repeat(width)}  → crew ${name} ${command.usage}`);
     }

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

@@ -1 +1 @@
-{"version":3,"file":"interruptWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/interruptWorkspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAMnE,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAuGD,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGzE"}
+{"version":3,"file":"interruptWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/interruptWorkspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAMnE,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAqGD,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGzE"}

package/dist/commands/interruptWorkspace.js

@@ -15,20 +15,20 @@ function parseArguments(argv) {
         if (argument === "--reason") {
             const value = argv[index + 1];
             if (value === undefined || value.length === 0 || value.startsWith("-")) {
-                throw new Error("crew interrupt --reason: reason text is required");
+                throw new Error("crew stop --reason: reason text is required");
             }
             reason = value;
             index += 1;
             continue;
         }
         if (argument.startsWith("-")) {
-            throw new Error(`Unknown option: ${argument}\nUsage: crew interrupt <ticket> [--reason <text>]`);
+            throw new Error(`Unknown option: ${argument}\nUsage: crew stop <ticket> [--reason <text>]`);
         }
         positionals.push(argument);
     }
     const [ticket, ...extras] = positionals;
     if (ticket === undefined || ticket.length === 0 || extras.length > 0) {
-        throw new Error("Usage: crew interrupt <ticket> [--reason <text>]");
+        throw new Error("Usage: crew stop <ticket> [--reason <text>]");
     }
     return { ticket: ticket.toLowerCase(), ...(reason === undefined ? {} : { reason }) };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"setupRepos.d.ts","sourceRoot":"","sources":["../../src/commands/setupRepos.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAInE,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,oBAAoB,GAAG,gBAAgB,CAAC;AAEvF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,wCAAwC;IACxC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;IACzC,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB;AA6JD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CA0D3B;AAwBD,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAajE"}
+{"version":3,"file":"setupRepos.d.ts","sourceRoot":"","sources":["../../src/commands/setupRepos.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAInE,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,oBAAoB,GAAG,gBAAgB,CAAC;AAEvF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,wCAAwC;IACxC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;IACzC,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB;AA6JD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CA0D3B;AAcD,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAajE"}

package/dist/commands/setupRepos.js

@@ -10,7 +10,7 @@ import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { runCommandAsync } from "../lib/commandRunner.js";
 import { loadConfig } from "../lib/config.js";
 import { which } from "../lib/host.js";
-import { errorMessage, log, writeOutput } from "../lib/util.js";
+import { errorMessage, log, parseDryRunPositionals, writeOutput } from "../lib/util.js";
 function emptyResult() {
     return {
         existing: [],
@@ -190,18 +190,7 @@ export async function setupRepos(config, options) {
     return result;
 }
 function parseArguments(argv) {
-    let dryRun = false;
-    const positionals = [];
-    for (const argument of argv) {
-        if (argument === "--dry-run") {
-            dryRun = true;
-            continue;
-        }
-        if (argument.startsWith("-")) {
-            throw new Error(`Unknown option: ${argument}\nUsage: crew setup repos [--dry-run] [<repo>...]`);
-        }
-        positionals.push(argument);
-    }
+    const { dryRun, positionals } = parseDryRunPositionals(argv, "crew setup repos [--dry-run] [<repo>...]");
     const options = { dryRun };
     if (positionals.length > 0) {
         options.only = positionals;

package/dist/lib/util.d.ts

@@ -34,6 +34,17 @@ export declare function lazyLinearClient(factory: () => LinearClient): () => Lin
  * each subcommand's arg parser stays DRY.
  */
 export declare function readTicketArgument(argv: string[], index: number, command: string): string;
+export interface DryRunPositionals {
+    dryRun: boolean;
+    positionals: string[];
+}
+/**
+ * Parses an argv that accepts an optional `--dry-run` flag plus free
+ * positionals, rejecting any other dash-prefixed token. Shared by the
+ * subcommands whose only flag is `--dry-run` so each parser stays DRY; pass the
+ * command's `usage` string for the "Unknown option" error.
+ */
+export declare function parseDryRunPositionals(argv: string[], usage: string): DryRunPositionals;
 export declare function errorMessage(error: unknown): string;
 export {};
 //# sourceMappingURL=util.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/lib/util.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E;AAED,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAGhD;AAQD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAEzD;AAED,wBAAsB,uBAAuB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOxF;AAkBD,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAQzC;AAED,KAAK,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;AAUpF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAcxF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxE;AAED,QAAA,MAAM,sBAAsB,YAAI,2BAA2B,EAAE,gBAAgB,CAAU,CAAC;AAExF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,wBAAgB,mBAAmB,IAAI,oBAAoB,GAAG,SAAS,CAQtE;AAED,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,YAAY,GAAG,MAAM,YAAY,CAMhF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMzF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcnD"}
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/lib/util.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E;AAED,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAGhD;AAQD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAEzD;AAED,wBAAsB,uBAAuB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOxF;AAkBD,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAQzC;AAED,KAAK,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;AAUpF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAcxF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxE;AAED,QAAA,MAAM,sBAAsB,YAAI,2BAA2B,EAAE,gBAAgB,CAAU,CAAC;AAExF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,wBAAgB,mBAAmB,IAAI,oBAAoB,GAAG,SAAS,CAQtE;AAED,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,YAAY,GAAG,MAAM,YAAY,CAMhF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMzF;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAcvF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcnD"}

package/dist/lib/util.js

@@ -146,6 +146,27 @@ export function readTicketArgument(argv, index, command) {
     }
     return value;
 }
+/**
+ * Parses an argv that accepts an optional `--dry-run` flag plus free
+ * positionals, rejecting any other dash-prefixed token. Shared by the
+ * subcommands whose only flag is `--dry-run` so each parser stays DRY; pass the
+ * command's `usage` string for the "Unknown option" error.
+ */
+export function parseDryRunPositionals(argv, usage) {
+    let dryRun = false;
+    const positionals = [];
+    for (const argument of argv) {
+        if (argument === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (argument.startsWith("-")) {
+            throw new Error(`Unknown option: ${argument}\nUsage: ${usage}`);
+        }
+        positionals.push(argument);
+    }
+    return { dryRun, positionals };
+}
 export function errorMessage(error) {
     if (error instanceof Error) {
         return error.message;

package/package.json

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