@clipboard-health/groundcrew 2.2.0 → 2.3.1

package/README.md

@@ -15,7 +15,12 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
 
 ## Quickstart
 
-1. **Install prereqs.** Node 24, `git`, `cmux` _or_ `tmux`, and the agent CLIs themselves (`claude`, `codex`, `cursor-agent`, ...). Groundcrew is **macOS-only** and requires [Safehouse](https://agent-safehouse.dev/) on `PATH`. Optional: `codexbar` for session-usage gating. The `workspaceKind` config key picks the workspace backend (`auto` resolves to cmux when installed, else tmux).
+1. **Install prereqs.** Node 24, `git`, `cmux` _or_ `tmux`, and the agent CLIs themselves (`claude`, `codex`, `cursor-agent`, ...). Pick a local isolation backend below depending on platform and what the agent needs to do. Optional: `codexbar` for session-usage gating. The `workspaceKind` config key picks the workspace backend (`auto` resolves to cmux when installed, else tmux).
+   - **`safehouse`** (macOS default) — [Safehouse](https://agent-safehouse.dev/) on `PATH`. The fastest local backend; cannot safely give the agent Docker.
+   - **`sdx`** (Linux default, macOS opt-in) — [Docker Sandboxes](https://docs.docker.com/sandboxes/) (`sbx`) on `PATH`. Required when a ticket needs the agent to use Docker (`docker build`, `docker run`, integration tests). Each model that should run under sdx needs a `sandbox: { agent: "<sbx-agent>" }` block in `config.ts` so groundcrew knows which sbx agent to address.
+   - **`none`** — explicit unsandboxed escape hatch. Never picked implicitly; `crew doctor` warns when it is configured.
+
+   Groundcrew resolves `local.runner` per platform: macOS → `safehouse`, Linux/WSL → `sdx`. Set `local.runner` to `"safehouse" | "sdx" | "none"` to override; leave at `"auto"` for the platform default.
 
 2. **Create a Linear project to scope your work.** Any team works — make a project inside it and drop tickets in. The orchestrator polls by project, not by team, so you don't need a dedicated team.
 
@@ -63,11 +68,11 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
 
    `LINEAR_API_KEY` continues to work for existing setups; if both variables are set, `GROUNDCREW_LINEAR_API_KEY` wins.
 
-5. **Prepare the runner and agent auth.** Groundcrew supports one runner: a `cmux` or `tmux` workspace on macOS, with Safehouse on `PATH`, `clearance`, and locally authenticated agent CLIs.
+5. **Prepare the runner and agent auth.** Groundcrew uses a `cmux` or `tmux` workspace hosting the resolved local backend (`safehouse`, `sdx`, or `none`) plus locally authenticated agent CLIs. Setup fails fast when the resolved backend's binary or platform requirement is missing — `safehouse` requires macOS + `safehouse` on PATH; `sdx` requires macOS or Linux + `sbx` on PATH. `models.isolation` and per-model `isolation` are legacy keys and fail config validation. Per-model `sandbox` blocks are accepted again and used by the `sdx` runner.
 
-   Setup fails before creating a worktree when the host is not macOS or `safehouse` is missing. `models.isolation`, per-model `isolation`, and per-model `sandbox` are legacy keys and now fail config validation.
+   For sdx, sandboxes are created automatically on first launch. Groundcrew names them deterministically as `groundcrew-<repository>-<model>`, probes `sbx ls`, and runs `sbx create [--template ...] [--kit ...] <agent> <projectDir>` when missing — `projectDir` is the mount so every per-ticket worktree (created as a sibling of the bare clone) is visible inside the sandbox. First-time agent auth happens inside the sandbox the first time the agent runs via `sbx exec`. To bootstrap manually instead, run `sbx create --name groundcrew-<repo>-<model> <agent> <projectDir>` once.
 
-6. **Set the clearance allowlist for local macOS runs.** Groundcrew starts `clearance` from `@clipboard-health/clearance` on `http://127.0.0.1:19999` (skipping the launch if something is already listening) and runs the agent through the bundled `safehouse-clearance` wrapper. Clearance refuses to start without an allowlist — see [its README](https://github.com/ClipboardHealth/core-utils/tree/main/packages/clearance) for the proxy's env vars, log paths, and DNS rules. The shortest path is to set the env before `crew run`:
+6. **Set the clearance allowlist for local Safehouse runs.** Only applies when `local.runner` resolves to `safehouse`. Groundcrew starts `clearance` from `@clipboard-health/clearance` on `http://127.0.0.1:19999` (skipping the launch if something is already listening) and runs the agent through the bundled `safehouse-clearance` wrapper. Clearance refuses to start without an allowlist — see [its README](https://github.com/ClipboardHealth/core-utils/tree/main/packages/clearance) for the proxy's env vars, log paths, and DNS rules. The shortest path is to set the env before `crew run`:
 
    ```bash
    CLEARANCE_ALLOW_HOSTS="api.openai.com,auth.openai.com,api.anthropic.com,mcp.linear.app,api.linear.app" \
@@ -87,6 +92,7 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
 
    ```bash
    crew doctor
+   crew doctor --ticket TEAM-123
    crew run --dry-run
    crew run            # one-shot
    crew run --watch    # poll forever
@@ -112,12 +118,14 @@ Required fields are marked **required**; everything else has a default and can b
 | `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.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 Safehouse/clearance. `{{worktree}}` is replaced before launch and legacy `{{sandbox}}` expands to an empty string.                                                                                                     |
+| `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).                                                                                                                                                                                                                  |
 | `models.definitions.<name>.usage`       | optional            | If set, codexbar usage is fetched for this model and gated by `sessionLimitPercentage`. Omit to never gate. When `usage.codexbar.source` is omitted, groundcrew uses `auto` on macOS and `cli` elsewhere.                                                                                 |
+| `models.definitions.<name>.sandbox`     | optional            | Docker Sandboxes binding for the model. Required at launch when `local.runner` resolves to `sdx`. Fields: `agent` (required sbx agent name), `template`, `kits`, `setupCommand` (override for the inside-sandbox setup script).                                                           |
 | `models.definitions.<name>.disabled`    | optional            | When set to exactly `true`, drops the named shipped default (`claude` or `codex`). Doctor skips probing it; `agent-<name>` labels fall back to `models.default` with a warning. See "Disabling a shipped default" below.                                                                  |
 | `prompts.initial`                       | (template)          | First message sent to the agent. Placeholders: `{{ticket}}`, `{{worktree}}`, `{{title}}`, `{{description}}`.                                                                                                                                                                              |
 | `workspaceKind`                         | `"auto"`            | Terminal session manager. `"auto"` picks `cmux` when on PATH, else `tmux`. Set to `"cmux"` or `"tmux"` to fail loudly when the chosen backend is missing. tmux windows live in a dedicated `groundcrew` session.                                                                          |
+| `local.runner`                          | `"auto"`            | Local isolation backend. `"auto"` resolves to `safehouse` on macOS and `sdx` on Linux/WSL. Explicit values: `"safehouse"`, `"sdx"`, `"none"`. `"none"` is never picked implicitly — doctor warns when it is configured.                                                                   |
 | `logging.file`                          | XDG state path      | Append-mode log file destination. `log()` / `logEvent()` tee here in addition to stdout, so a vanished workspace doesn't take the evidence with it. Defaults to `${XDG_STATE_HOME:-$HOME/.local/state}/groundcrew/groundcrew.log`.                                                        |
 
 The branch prefix (`<prefix>-<TICKET>`) is derived from your OS username (`os.userInfo().username`), not configured. Agent selection looks for a top-level Linear label named `agent-<model>` (e.g. `agent-claude`, `agent-codex`). **`crew run` without `--ticket` only fetches tickets with an `agent-*` label** — the GraphQL query filters them server-side, so unlabeled tickets are never returned by Linear's API and do not appear in the rendered board. Use `crew run --ticket <TICKET>` to provision an unlabeled ticket on demand (manual setup falls back to `models.default`). The reserved label `agent-any` routes the ticket to the configured model with the most available session capacity (lowest codexbar session-used percent), skipping any model already over `sessionLimitPercentage`. With no usage data, `agent-any` resolves to `models.default`. The name `any` cannot be used in `models.definitions`. Todo tickets blocked by Linear issues that are not in `linear.statuses.terminal` are skipped until their blockers reach a terminal status.
@@ -155,25 +163,81 @@ Rules:
 ## Manual commands
 
 ```bash
+crew doctor --ticket <TICKET>
 crew run --ticket <TICKET>
 crew setup repos [--dry-run] [<repo>...]
 crew cleanup <TICKET>
 ```
 
+`crew doctor --ticket <TICKET>` diagnoses one Linear ticket without provisioning it. It checks the same resolution inputs that decide whether the orchestrator can see the ticket — Todo status, `agent-*` label, model resolution, repository mention, local clone — then checks blockers, model session usage, and available in-progress capacity.
+
 `crew run --ticket <TICKET>` provisions a single ticket the same way the orchestrator would: the repo is parsed from the ticket's Linear description and the model comes from the ticket's `agent-*` label (manual setup falls back to `models.default` for unlabeled tickets). If the description does not mention a repo from `workspace.knownRepositories`, setup fails before provisioning. `--watch` and `--ticket` are mutually exclusive — `--watch` drives the orchestrator loop; `--ticket` provisions one ticket and exits. `crew cleanup <TICKET>` resolves to every tracked worktree carrying that ticket id (across repos) and tears them all down. To inspect codexbar session windows directly, run `codexbar usage`; the orchestrator already gates on this internally via `orchestrator.sessionLimitPercentage`.
 
+### `crew doctor --ticket <ticket>`
+
+Diagnose why a ticket would or wouldn't be dispatched on the next orchestrator tick. Runs the same resolution and eligibility chain as the dispatcher, but for a single ticket, and prints a tree of pass/fail checks.
+
+```bash
+crew doctor --ticket HRD-446
+```
+
+Exits 0 if the ticket would dispatch, 1 otherwise. Useful when you've labelled a ticket with `agent-claude` and it doesn't show up on the board.
+
+Example output for a ticket that would dispatch:
+
+```text
+groundcrew doctor --ticket HRD-446 (Add retry logic to the sync job)
+────────────────────────────────────────────────────────────────────
+
+Resolution
+  [ok] Ticket exists in Linear ("Add retry logic to the sync job")
+  [ok] Status is Todo
+  [ok] Has agent-* label (agent-claude)
+  [ok] Model resolves from agent-* label (model "claude")
+  [ok] Description mentions known repo (owner/repo)
+  [ok] Resolved repo is cloned locally (/dev/workspaces/owner/repo)
+
+Eligibility
+  [ok] No active blockers
+  [ok] Model "claude" usage under sessionLimitPercentage (12% (limit 85%))
+  [ok] In-progress cap not hit (2/4 used)
+
+→ would be dispatched on next tick
+```
+
+Example output for a ticket that's not in the Todo status:
+
+```text
+groundcrew doctor --ticket HRD-447 (Refactor auth middleware)
+─────────────────────────────────────────────────────────────
+
+Resolution
+  [ok] Ticket exists in Linear ("Refactor auth middleware")
+  [--] Status is Todo (current: In Progress)
+  [ok] Has agent-* label (agent-claude)
+  [ok] Model resolves from agent-* label (model "claude")
+  [ok] Description mentions known repo (owner/repo)
+  [ok] Resolved repo is cloned locally (/dev/workspaces/owner/repo)
+
+Eligibility
+  (skipped — resolution checks failed)
+
+→ ineligible: status is In Progress (need Todo)
+```
+
 ## Gotchas
 
-- **Execution is macOS plus Safehouse only.** There is no `models.isolation` strategy and no direct local execution mode. Linux/WSL is not supported.
+- **Ticket labeled but not on the board?** Run `crew doctor --ticket <ticket>` — it lists every check the dispatcher runs and flags the failing one.
+- **Local execution picks one of safehouse/sdx/none.** `local.runner: "auto"` resolves to `safehouse` on macOS and `sdx` (Docker Sandboxes) on Linux/WSL. Override with `local.runner: "safehouse" | "sdx" | "none"`. There is no per-model `isolation` knob anymore — the runner is global. `sdx` requires a per-model `sandbox: { agent }` block so groundcrew can map the model to an sbx agent.
 - **Safehouse-already-wrapped commands are not re-wrapped.** If a `models.definitions.<name>.cmd` already starts with `safehouse`, groundcrew assumes that command owns its Safehouse flags and does not add the `safehouse-clearance` wrapper a second time. Changing the proxy's allowlist after it's running requires killing the PID in `${XDG_CACHE_HOME:-$HOME/.cache}/clearance/clearance.pid` so the next launch picks up the new env.
-- **Legacy Docker Sandboxes state is unmanaged.** Groundcrew no longer discovers or cleans `.sbx` worktrees or persistent Docker Sandboxes containers. If you have old state, inspect and remove it manually with `sbx`.
+- **Sandbox lifecycle is create-only.** Groundcrew auto-creates the sandbox for a `<repository, model>` pair when missing, but never deletes one — sandboxes persist across tickets and across `crew cleanup`. Auth state lives inside the sandbox, so deleting it forces a re-login. Inspect or remove them manually with `sbx ls` / `sbx rm`.
 - **Dead tmux windows vanish by default.** When a wrapped agent command fails (e.g. `safehouse-clearance` not found, `npm install` crash), the tmux window closes immediately and the error scrolls into the void. Set `GROUNDCREW_KEEP_DEAD_WINDOWS=1` (any non-empty value works) in the env you launch `crew` from to flip the per-window `remain-on-exit` to `on`; the window stays open with the error visible. Close it manually with `tmux kill-window -t groundcrew:<ticket>` after diagnosis. tmux backend only.
 - **Status names matter.** If your team uses `Started` instead of `In Progress`, set `linear.statuses.inProgress = "Started"`.
 - **Leaf-only.** Parent issues with children are ignored — sub-issues are the work items.
 - **Tickets stay in the in-progress status until something else moves them.** Groundcrew sets a ticket to `inProgress` when it provisions a workspace and never advances it. The next transition (typically "in review" when a PR opens) is left to your team's Linear automation rules.
 - **Project must be on a single Linear team in practice.** Cross-team projects work — the orchestrator caches the in-progress state ID per team — but every team in the project must use the same status name for `linear.statuses.inProgress`.
 - **Claude launches in bypass-permissions mode by default.** Groundcrew creates isolated per-ticket worktrees for unattended runs, so the shipped `claude` command is `claude --permission-mode bypassPermissions` to avoid workspace-trust and tool-permission prompts blocking automation. Override `models.definitions.claude.cmd` if you want a stricter mode.
-- **Doctor's command introspection is shallow.** Doctor reports whether the host can run local tickets with macOS plus Safehouse, then tokenizes model `cmd` and checks the first two non-flag tokens against PATH (so `safehouse claude --foo` checks both `safehouse` and `claude`). Boolean flags without values, env-var assignments (`FOO=1`), shell pipelines, and subshells are not parsed — verify those manually. In particular, `npx -y claude` and `env FOO=1 claude` only check the wrapper, not the wrapped CLI.
+- **Doctor's command introspection is shallow.** Doctor reports the resolved local runner (safehouse / sdx / none) and whether its prerequisites are met, then tokenizes model `cmd` and checks the first two non-flag tokens against PATH (so `safehouse claude --foo` checks both `safehouse` and `claude`). Boolean flags without values, env-var assignments (`FOO=1`), shell pipelines, and subshells are not parsed — verify those manually. In particular, `npx -y claude` and `env FOO=1 claude` only check the wrapper, not the wrapped CLI. When `local.runner` is `"none"`, doctor surfaces a single WARNING line so the unsandboxed launch is visible at a glance.
 - **Doctor checks every enabled model, including shipped defaults you didn't disable.** `models.definitions` includes both shipped defaults (`claude`, `codex`) by default via additive merge. If you only intend to label tickets `agent-claude` and don't have `codex` installed, set `models.definitions.codex: { disabled: true }` (see "Disabling a shipped default" under "Config reference"). Without that, doctor exits non-zero on a missing `codex` binary even though `crew run` would never route to it.
 - **Switch to tmux if cmux is misbehaving.** Set `workspaceKind: "tmux"` to force the tmux backend when cmux's CLI/socket bridge is flaky (symptoms: `cmux --json list-workspaces` returning `Failed to write to socket (Broken pipe)` or `Socket not found at ...cmux.sock` on every tick). tmux is more reliable — just a unix socket, no GUI app — at the cost of losing cmux's status pills, notifications, and vertical-tab sidebar.
 - **Agent CLI must accept a positional prompt.** The handoff is `<your cmd> "<prompt>"`. `claude`, `codex`, and `cursor-agent` all support this.

package/configExample.ts

@@ -44,9 +44,18 @@ export const config: Config = {
   //       cmd: "cursor-agent",
   //       color: "#929292",
   //     },
+  //     // To run a model under the sdx (Docker Sandboxes) runner, bind it to
+  //     // an sbx agent. Required when `local.runner` resolves to `sdx`.
+  //     // claude: { sandbox: { agent: "claude" } },
   //   },
   // },
   //
+  // // Local isolation backend. Defaults to `"auto"` — macOS → safehouse,
+  // // Linux → sdx (Docker Sandboxes). `"none"` is an explicit unsandboxed
+  // // escape hatch and is never picked implicitly. Switch to `"sdx"` on
+  // // macOS when you need an agent to use Docker safely.
+  // local: { runner: "auto" },
+  //
   // prompts: {
   //   initial: [
   //     "Begin work on {{ticket}} ({{title}}) in the {{worktree}} wt subdirectory.",

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -51,6 +51,24 @@ async function runCli(argv) {
     }
     await setupWorkspaceCli(ticket, { dryRun });
 }
+async function doctorCli(argv) {
+    let ticket;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--ticket") {
+            const value = argv[index + 1];
+            if (value === undefined || value.length === 0 || value.startsWith("-")) {
+                throw new Error("crew doctor --ticket: ticket id is required");
+            }
+            ticket = value;
+            index += 1;
+            continue;
+        }
+        throw new Error(`crew doctor: unknown argument: ${argument}`);
+    }
+    const ok = ticket === undefined ? await doctor() : await doctor({ ticket });
+    process.exitCode = ok ? process.exitCode : 1;
+}
 const SUBCOMMANDS = {
     run: {
         summary: "Run the orchestrator (one-shot by default), or provision one ticket with --ticket",
@@ -58,13 +76,9 @@ const SUBCOMMANDS = {
         invoke: runCli,
     },
     doctor: {
-        summary: "Verify prereqs against the resolved config",
-        invoke: async () => {
-            const ok = await doctor();
-            if (!ok) {
-                process.exitCode = 1;
-            }
-        },
+        summary: "Verify prereqs, or diagnose one ticket with --ticket",
+        usage: "[--ticket <ticket>]",
+        invoke: doctorCli,
     },
     cleanup: {
         summary: "Tear down a worktree",
@@ -87,9 +101,7 @@ function printHelp() {
     writeOutput("Commands:");
     for (const [name, command] of Object.entries(SUBCOMMANDS)) {
         writeOutput(`  ${name.padEnd(width)}  ${command.summary}`);
-        if (command.usage !== undefined) {
-            writeOutput(`  ${" ".repeat(width)}  → crew ${name} ${command.usage}`);
-        }
+        writeOutput(`  ${" ".repeat(width)}  → crew ${name} ${command.usage}`);
     }
     writeOutput("\nSee README.md for full configuration and behavior.");
 }

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

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/commands/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAczD,UAAU,cAAc;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,UAAU,EAAE;QAClB,KAAK,EAAE,UAAU,CAAC;QAClB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;QAC1C,+FAA+F;QAC/F,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;QACvD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAmNjE"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/commands/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAWzD,UAAU,cAAc;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,UAAU,EAAE;QAClB,KAAK,EAAE,UAAU,CAAC;QAClB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;QAC1C,+FAA+F;QAC/F,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;QACvD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAuLjE"}

package/dist/commands/dispatcher.js

@@ -10,42 +10,16 @@ import { isGroundcrewIssue } from "../lib/boardSource.js";
 import { createLinearIssueStatusUpdater } from "../lib/linearIssueStatus.js";
 import { errorMessage, log, logEvent } from "../lib/util.js";
 import { workspaces } from "../lib/workspaces.js";
-import { classifyBlockers, classifyEligibility, } from "./eligibility.js";
+import { classifyBlockers, classifyEligibility, classifyUsageExhaustion, } from "./eligibility.js";
 import { setupWorkspace } from "./setupWorkspace.js";
-const PERCENT_FRACTION_DIVISOR = 100;
-const DAYS_PER_WEEK = 7;
-const MINUTES_PER_DAY = 24 * 60;
-const MINUTES_PER_WEEK = DAYS_PER_WEEK * MINUTES_PER_DAY;
 export function createDispatcher(deps) {
     const { config, client } = deps;
     const issueStatusUpdater = createLinearIssueStatusUpdater({ config, client });
     function buildExhaustedSet(usage) {
         const exhausted = new Set();
-        const sessionLimit = config.orchestrator.sessionLimitPercentage;
-        for (const [model, snapshot] of Object.entries(usage)) {
-            if (snapshot.session !== null && snapshot.session * PERCENT_FRACTION_DIVISOR > sessionLimit) {
-                exhausted.add(model);
-                const pct = (snapshot.session * PERCENT_FRACTION_DIVISOR).toFixed(0);
-                const mins = snapshot.sessionEndDuration ?? "?";
-                log(`${model} session at ${pct}% (> ${sessionLimit}%), resets in ${mins}m — skipping its tickets`);
-            }
-            // Weekly gate paces total weekly usage against day buckets from the
-            // weekly reset. Day 1's budget is available immediately after rollover,
-            // then each later day opens another 1/7 of the weekly budget. Skipped when:
-            //   - weekly is null (no codexbar secondary window this tick)
-            //   - weekly is non-finite (EXHAUSTED_USAGE — session gate above
-            //     already pins it to Infinity)
-            //   - weekEndDuration is null (can't compute where we are in week)
-            if (snapshot.weekly !== null &&
-                Number.isFinite(snapshot.weekly) &&
-                snapshot.weekEndDuration !== null) {
-                const usedPct = snapshot.weekly * PERCENT_FRACTION_DIVISOR;
-                const allowedPct = weeklyPacedBudgetPercentage(snapshot.weekEndDuration);
-                if (usedPct > allowedPct) {
-                    exhausted.add(model);
-                    log(`${model} weekly at ${usedPct.toFixed(1)}% (> ${allowedPct.toFixed(1)}% paced budget), resets in ${snapshot.weekEndDuration}m — skipping its tickets`);
-                }
-            }
+        for (const exhaustion of classifyUsageExhaustion(config, usage)) {
+            exhausted.add(exhaustion.model);
+            log(formatUsageExhaustion(exhaustion));
         }
         return exhausted;
     }
@@ -187,9 +161,10 @@ export function createDispatcher(deps) {
     }
     return { runOnce };
 }
-function weeklyPacedBudgetPercentage(weekEndDuration) {
-    const elapsedMinutes = Math.min(MINUTES_PER_WEEK, Math.max(0, MINUTES_PER_WEEK - weekEndDuration));
-    const elapsedDayCount = Math.ceil(elapsedMinutes / MINUTES_PER_DAY);
-    const budgetDayCount = Math.min(DAYS_PER_WEEK, Math.max(1, elapsedDayCount));
-    return (budgetDayCount / DAYS_PER_WEEK) * PERCENT_FRACTION_DIVISOR;
+function formatUsageExhaustion(exhaustion) {
+    if (exhaustion.kind === "session") {
+        const mins = exhaustion.resetMinutes ?? "?";
+        return `${exhaustion.model} session at ${exhaustion.usedPercentage.toFixed(0)}% (> ${exhaustion.limitPercentage}%), resets in ${mins}m — skipping its tickets`;
+    }
+    return `${exhaustion.model} weekly at ${exhaustion.usedPercentage.toFixed(1)}% (> ${exhaustion.allowedPercentage.toFixed(1)}% paced budget), resets in ${exhaustion.resetMinutes}m — skipping its tickets`;
 }

package/dist/commands/doctor.d.ts

@@ -2,5 +2,8 @@
  * doctor — verify groundcrew prerequisites against the resolved config.
  * Returns true if every required check passes; false otherwise.
  */
-export declare function doctor(): Promise<boolean>;
+export interface DoctorOptions {
+    ticket?: string;
+}
+export declare function doctor(options?: DoctorOptions): Promise<boolean>;
 //# sourceMappingURL=doctor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwIH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CA6D/C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2BH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsHD,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAK1E"}

package/dist/commands/doctor.js

@@ -3,10 +3,12 @@
  * Returns true if every required check passes; false otherwise.
  */
 import { existsSync, statSync } from "node:fs";
-import { loadConfig } from "../lib/config.js";
+import { loadConfig, } from "../lib/config.js";
 import { detectHostCapabilities, which } from "../lib/host.js";
+import { resolveLocalRunner } from "../lib/localRunner.js";
 import { errorMessage, resolveLinearApiKey, writeOutput } from "../lib/util.js";
 import { resolveWorkspaceKind } from "../lib/workspaces.js";
+import { runTicketDoctor } from "./ticketDoctor.js";
 // Tokenization stops after this many non-flag tokens. Two is enough to
 // catch wrapper + wrapped CLI commands like `safehouse claude --foo`.
 const MAX_TOKENS_PER_CMD = 2;
@@ -120,7 +122,26 @@ function format(check) {
     const hint = check.hint !== undefined && check.hint.length > 0 ? `  — ${check.hint}` : "";
     return `${tag}${check.name}${hint}`;
 }
-export async function doctor() {
+export async function doctor(options = {}) {
+    if (options.ticket !== undefined) {
+        return await doctorTicket(options.ticket);
+    }
+    return await doctorHost();
+}
+async function doctorTicket(ticket) {
+    try {
+        return await runTicketDoctor(ticket);
+    }
+    catch (error) {
+        const displayTicket = ticket.toUpperCase();
+        const header = `groundcrew doctor --ticket ${displayTicket}`;
+        writeOutput(header);
+        writeOutput("=".repeat(header.length));
+        writeOutput(`[--] config: ${errorMessage(error)}`);
+        return false;
+    }
+}
+async function doctorHost() {
     writeOutput("groundcrew doctor");
     writeOutput("=================");
     let config;
@@ -140,8 +161,13 @@ export async function doctor() {
         writeOutput(`[--] host: ${errorMessage(error)}`);
         return false;
     }
-    const localCapability = localCapabilityCheck(host);
-    reportLocalCapability(localCapability);
+    const resolvedRunner = resolveLocalRunner(config.local.runner, host);
+    const localCapability = localCapabilityCheck(host, resolvedRunner);
+    reportLocalCapability({
+        check: localCapability,
+        setting: config.local.runner,
+        resolved: resolvedRunner,
+    });
     const workspaceOutcome = resolveWorkspaceOutcome(config, host);
     reportWorkspaceKind(config, workspaceOutcome);
     const checks = [
@@ -176,22 +202,43 @@ export async function doctor() {
     writeOutput("All required checks passed.");
     return true;
 }
-function localCapabilityCheck(host) {
-    const supportsLocalRunner = host.isSafehouseSupported && host.hasSafehouse;
+function localCapabilityCheck(host, resolved) {
+    if (resolved === "safehouse") {
+        const ok = host.isSafehouseSupported && host.hasSafehouse;
+        return {
+            name: "local runner (safehouse)",
+            ok,
+            required: false,
+            hint: ok
+                ? "ready"
+                : "safehouse runner requires macOS with `safehouse` on PATH (install from https://agent-safehouse.dev/)",
+        };
+    }
+    if (resolved === "sdx") {
+        const ok = host.isSdxSupported && host.hasSbx;
+        return {
+            name: "local runner (sdx)",
+            ok,
+            required: false,
+            hint: ok
+                ? "ready"
+                : "sdx runner requires `sbx` (Docker Sandboxes) on PATH (install from https://docs.docker.com/sandboxes/)",
+        };
+    }
+    // resolved === "none"
     return {
-        name: "local runner (macOS + Safehouse)",
-        ok: supportsLocalRunner,
+        name: "local runner (none)",
+        ok: true,
         required: false,
-        hint: supportsLocalRunner
-            ? "ready"
-            : "groundcrew requires macOS with Safehouse on PATH (install from https://agent-safehouse.dev/)",
+        hint: "WARNING: local.runner='none' — agent runs unsandboxed on the host. Only use this when you understand the implications.",
     };
 }
-function reportLocalCapability(check) {
+function reportLocalCapability(arguments_) {
     writeOutput();
     writeOutput("Local runner");
     writeOutput("------------");
-    writeOutput(format(check));
+    writeOutput(`requested: ${arguments_.setting} → resolved: ${arguments_.resolved}`);
+    writeOutput(format(arguments_.check));
 }
 function resolveWorkspaceOutcome(config, host) {
     try {

package/dist/commands/eligibility.d.ts

@@ -37,6 +37,19 @@ export interface SkipVerdict {
     model?: string;
 }
 type Verdict = StartVerdict | SkipVerdict;
+export type ModelUsageExhaustion = {
+    kind: "session";
+    model: string;
+    usedPercentage: number;
+    limitPercentage: number;
+    resetMinutes: number | null;
+} | {
+    kind: "weekly";
+    model: string;
+    usedPercentage: number;
+    allowedPercentage: number;
+    resetMinutes: number;
+};
 export interface ClassifyArguments {
     config: ResolvedConfig;
     /**
@@ -68,6 +81,7 @@ interface BlockerClassification {
  * falls back to the default predictably.
  */
 export declare function pickBestModel(config: ResolvedConfig, usage: UsageByModel, exhausted: Set<string>): string | undefined;
+export declare function classifyUsageExhaustion(config: ResolvedConfig, usage: UsageByModel): ModelUsageExhaustion[];
 /**
  * Cheap pre-pass — partitions Todo into unblocked issues and blocker
  * skip verdicts. Runs before the dispatcher fetches usage or probes the

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

@@ -1 +1 @@
-{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../src/commands/eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAgB,KAAK,eAAe,EAAoB,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,KAAK,UAAU,GACX,SAAS,GACT,oBAAoB,GACpB,oBAAoB,GACpB,iBAAiB,GACjB,4BAA4B,GAC5B,mBAAmB,CAAC;AAExB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,eAAe,CAAC;IACvB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,WAAW,EAAE,UAAU,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,OAAO,GAAG,YAAY,GAAG,WAAW,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;OAKG;IACH,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,cAAc,EAAE,cAAc,CAAC;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,oDAAoD;IACpD,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,qBAAqB;IAC7B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAqCD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,MAAM,GAAG,SAAS,CAepB;AA4CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,qBAAqB,CAYvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,EAAE,CAgE5E"}
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../src/commands/eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAgB,KAAK,eAAe,EAAoB,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOzD,KAAK,UAAU,GACX,SAAS,GACT,oBAAoB,GACpB,oBAAoB,GACpB,iBAAiB,GACjB,4BAA4B,GAC5B,mBAAmB,CAAC;AAExB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,eAAe,CAAC;IACvB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,WAAW,EAAE,UAAU,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,OAAO,GAAG,YAAY,GAAG,WAAW,CAAC;AAE1C,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;OAKG;IACH,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,cAAc,EAAE,cAAc,CAAC;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,oDAAoD;IACpD,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,qBAAqB;IAC7B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAqCD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,MAAM,GAAG,SAAS,CAepB;AAaD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,GAClB,oBAAoB,EAAE,CAmCxB;AA4CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,qBAAqB,CAYvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,EAAE,CAgE5E"}

package/dist/commands/eligibility.js

@@ -8,6 +8,10 @@
  */
 import { isTerminalStatus } from "../lib/boardSource.js";
 import { AGENT_ANY_MODEL } from "../lib/config.js";
+const PERCENT_FRACTION_DIVISOR = 100;
+const DAYS_PER_WEEK = 7;
+const MINUTES_PER_DAY = 24 * 60;
+const MINUTES_PER_WEEK = DAYS_PER_WEEK * MINUTES_PER_DAY;
 function blockerSummary(blocker) {
     return `${blocker.id}:${blocker.status ?? "missing"}`;
 }
@@ -59,6 +63,46 @@ export function pickBestModel(config, usage, exhausted) {
         return best;
     }).name;
 }
+function weeklyPacedBudgetPercentage(weekEndDuration) {
+    const elapsedMinutes = Math.min(MINUTES_PER_WEEK, Math.max(0, MINUTES_PER_WEEK - weekEndDuration));
+    const elapsedDayCount = Math.ceil(elapsedMinutes / MINUTES_PER_DAY);
+    const budgetDayCount = Math.min(DAYS_PER_WEEK, Math.max(1, elapsedDayCount));
+    return (budgetDayCount / DAYS_PER_WEEK) * PERCENT_FRACTION_DIVISOR;
+}
+export function classifyUsageExhaustion(config, usage) {
+    const exhausted = [];
+    const sessionLimit = config.orchestrator.sessionLimitPercentage;
+    for (const [model, snapshot] of Object.entries(usage)) {
+        if (snapshot.session !== null && snapshot.session * PERCENT_FRACTION_DIVISOR > sessionLimit) {
+            exhausted.push({
+                kind: "session",
+                model,
+                usedPercentage: snapshot.session * PERCENT_FRACTION_DIVISOR,
+                limitPercentage: sessionLimit,
+                resetMinutes: snapshot.sessionEndDuration,
+            });
+        }
+        // Weekly gate paces total weekly usage against day buckets from the
+        // weekly reset. Day 1's budget is available immediately after rollover,
+        // then each later day opens another 1/7 of the weekly budget.
+        if (snapshot.weekly !== null &&
+            Number.isFinite(snapshot.weekly) &&
+            snapshot.weekEndDuration !== null) {
+            const usedPercentage = snapshot.weekly * PERCENT_FRACTION_DIVISOR;
+            const allowedPercentage = weeklyPacedBudgetPercentage(snapshot.weekEndDuration);
+            if (usedPercentage > allowedPercentage) {
+                exhausted.push({
+                    kind: "weekly",
+                    model,
+                    usedPercentage,
+                    allowedPercentage,
+                    resetMinutes: snapshot.weekEndDuration,
+                });
+            }
+        }
+    }
+    return exhausted;
+}
 // Stale worktrees with no matching live workspace are filtered out here so
 // they don't permanently block later tickets in the Todo queue.
 function classifyRecovery(arguments_) {

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,CA6Ef;AA0FD,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;AAUvF,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,CAoGf;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

@@ -1,13 +1,14 @@
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { ensureClearance } from "@clipboard-health/clearance";
 import { fetchResolvedIssue } from "../lib/boardSource.js";
 import { BUILD_SECRET_NAMES, loadConfig } from "../lib/config.js";
+import { ensureSandbox, sandboxNameFor } from "../lib/dockerSandbox.js";
 import { detectHostCapabilities } from "../lib/host.js";
 import { buildLaunchCommand, shellSingleQuote } from "../lib/launchCommand.js";
 import { createLinearIssueStatusUpdater } from "../lib/linearIssueStatus.js";
-import { assertLocalRunnerRequirements } from "../lib/localRunner.js";
+import { assertLocalRunnerRequirements, resolveLocalRunner } from "../lib/localRunner.js";
 import { errorMessage, getLinearClient, log, readEnvironmentVariable } from "../lib/util.js";
 import { workspaces } from "../lib/workspaces.js";
 import { isWorktreeAlreadyExistsError, worktrees } from "../lib/worktrees.js";
@@ -75,8 +76,16 @@ export async function setupWorkspace(config, options, runOptions = {}) {
     if (!definition) {
         throw new Error(`Unknown model: ${model}`);
     }
-    assertLocalRunnerRequirements(await detectHostCapabilities(signal));
-    await ensureClearance({ logger: log });
+    const host = await detectHostCapabilities(signal);
+    const runner = resolveLocalRunner(config.local.runner, host);
+    assertLocalRunnerRequirements(host, runner);
+    if (runner === "safehouse") {
+        await ensureClearance({ logger: log });
+    }
+    if (runner === "sdx" && definition.sandbox === undefined) {
+        throw new Error(`Local groundcrew runs with the sdx runner require a sandbox config on model '${model}'. ` +
+            "Add `sandbox: { agent: '<sbx-agent-name>' }` to the model in your config.ts.");
+    }
     const spec = { repository, ticket };
     let created;
     try {
@@ -113,11 +122,21 @@ export async function setupWorkspace(config, options, runOptions = {}) {
         const stagedPrompt = stagePrompt({ config, ticket, ticketDetails, worktreeName });
         promptDir = stagedPrompt.directory;
         const secretsFile = stageBuildSecrets(promptDir);
+        const sandboxName = runner === "sdx" ? sandboxNameFor({ repository, model }) : undefined;
+        if (runner === "sdx" && sandboxName !== undefined && definition.sandbox !== undefined) {
+            await ensureSandbox({
+                sandboxName,
+                sandbox: definition.sandbox,
+                mountPath: resolve(config.workspace.projectDir),
+            }, signal);
+        }
         const launchCommand = buildLaunchCommand({
             definition,
             promptFile: stagedPrompt.file,
             worktreeDir: launchDir,
             secretsFile,
+            runner,
+            sandboxName,
         });
         const launchCmd = stageWorkspaceLaunchCommand(promptDir, launchCommand);
         log("Opening workspace...");