@clipboard-health/groundcrew 2.1.1 → 2.3.0

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" \
@@ -112,12 +117,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.
@@ -164,16 +171,16 @@ crew cleanup <TICKET>
 
 ## Gotchas
 
-- **Execution is macOS plus Safehouse only.** There is no `models.isolation` strategy and no direct local execution mode. Linux/WSL is not supported.
+- **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/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;AA8IH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAkE/C"}

package/dist/commands/doctor.js

@@ -3,8 +3,9 @@
  * 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";
 // Tokenization stops after this many non-flag tokens. Two is enough to
@@ -140,8 +141,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 +182,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/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;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,16 +1,17 @@
 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 { 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());
@@ -75,12 +76,30 @@ 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 };
-    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
@@ -103,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...");
@@ -120,12 +149,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/config.d.ts

@@ -15,6 +15,39 @@ export declare const AGENT_ANY_MODEL = "any";
  */
 export type WorkspaceKindSetting = "auto" | "cmux" | "tmux";
 export declare const WORKSPACE_KIND_SETTINGS: readonly WorkspaceKindSetting[];
+/**
+ * Concrete local isolation backend selected for a launch. `safehouse` is
+ * macOS-only (clearance HTTP-egress + sandbox profile); `sdx` is Docker
+ * Sandboxes (`sbx` CLI) — works on Linux and macOS and is the only known
+ * option that lets the agent use Docker safely without exposing the host
+ * socket; `none` is an explicit unsandboxed escape hatch.
+ */
+export type LocalRunner = "safehouse" | "sdx" | "none";
+/**
+ * User-facing local runner setting. `auto` resolves at launch time:
+ * macOS picks `safehouse`, Linux picks `sdx`. `none` is never picked
+ * implicitly.
+ */
+export type LocalRunnerSetting = LocalRunner | "auto";
+export declare const LOCAL_RUNNER_SETTINGS: readonly LocalRunnerSetting[];
+/**
+ * Per-model Docker Sandboxes (sdx) binding. Required at launch when
+ * `local.runner` resolves to `sdx` so groundcrew knows which sbx agent
+ * to address and how to seed the sandbox.
+ */
+export interface SandboxDefinition {
+    /** sbx agent name (e.g. "claude", "codex"). */
+    agent: string;
+    /** Optional `sbx run --template` value. */
+    template?: string;
+    /** Optional `sbx run --kit` values (each passed as a separate flag). */
+    kits?: string[];
+    /**
+     * Setup command run **inside** the sandbox before the agent exec.
+     * Defaults to `DEFAULT_SANDBOX_SETUP_COMMAND` when omitted.
+     */
+    setupCommand?: string;
+}
 export interface ModelDefinition {
     /**
      * Shell command launched for the model. Wrapped with Safehouse/clearance
@@ -32,6 +65,12 @@ export interface ModelDefinition {
             source?: string;
         };
     };
+    /**
+     * Docker Sandboxes binding. Required when `local.runner` resolves to
+     * `sdx` — pure additive: omitted models can still run under `safehouse`
+     * or `none` without surprise.
+     */
+    sandbox?: SandboxDefinition;
 }
 /**
  * User-facing model entry shape. Discriminated union so the type system
@@ -51,6 +90,14 @@ type UserModelDefinition = EnabledUserModelDefinition | DisabledUserModelDefinit
  * assumed to already have the right Node and npm versions.
  */
 export declare const DEFAULT_HOST_SETUP_COMMAND = "if [ -x .claude/setup.sh ]; then ./.claude/setup.sh --deps-only; elif [ -f .claude/setup.sh ] && command -v bash >/dev/null 2>&1; then bash .claude/setup.sh --deps-only; else npm clean-install; fi";
+/**
+ * Setup command run inside an sdx (Docker Sandboxes) sandbox before the
+ * agent process exec. Independent of the host setup — sandboxes typically
+ * lack Node tooling on first start, so we keep the recipe scoped to the
+ * common case of an npm-managed repo while still letting per-model
+ * `sandbox.setupCommand` override it for languages outside that path.
+ */
+export declare const DEFAULT_SANDBOX_SETUP_COMMAND = "if [ -x .claude/setup.sh ]; then ./.claude/setup.sh --deps-only; elif [ -f .claude/setup.sh ] && command -v bash >/dev/null 2>&1; then bash .claude/setup.sh --deps-only; else npm clean-install; fi";
 /**
  * Loose user-facing shape — what a `config.ts` file declares.
  * Fields with defaults are optional; only `linear.projectSlug` and the
@@ -107,6 +154,14 @@ export interface Config {
      * to fail loudly when the chosen backend is missing.
      */
     workspaceKind?: WorkspaceKindSetting;
+    /**
+     * Local isolation backend selector. Defaults to `"auto"` (macOS →
+     * safehouse, Linux → sdx). `"none"` is an explicit unsandboxed escape
+     * hatch — never selected implicitly.
+     */
+    local?: {
+        runner?: LocalRunnerSetting;
+    };
     logging?: {
         /**
          * Append-mode log file destination. `log()` and `logEvent()` tee here
@@ -158,6 +213,14 @@ export interface ResolvedConfig {
      * `auto` resolves to cmux when installed, else tmux.
      */
     workspaceKind: WorkspaceKindSetting;
+    /**
+     * Local isolation selection. The user-facing `auto` is preserved here
+     * so `localRunner.resolve()` can pick the platform default later — the
+     * resolver is the only place that knows the host capabilities.
+     */
+    local: {
+        runner: LocalRunnerSetting;
+    };
     logging: {
         file: string;
     };

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5D,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAIzD,CAAC;AAEX,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QACN,QAAQ,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACjD,CAAC;CACH;AAED;;;;;GAKG;AACH,KAAK,0BAA0B,GAAG,OAAO,CAAC,eAAe,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAClF,UAAU,2BAA2B;IACnC,QAAQ,EAAE,IAAI,CAAC;CAChB;AACD,KAAK,mBAAmB,GAAG,0BAA0B,GAAG,2BAA2B,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,yMACiK,CAAC;AAEzM;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE;QACN;;;;;;;;WAQG;QACH,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE;YACT,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;SACrB,CAAC;KACH,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,SAAS,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;KAC7B,CAAC;IACF,YAAY,CAAC,EAAE;QACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,sBAAsB,CAAC,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB;;;;;WAKG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;KACnD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF;;;;OAIG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,OAAO,CAAC,EAAE;QACR;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE;QACN,2EAA2E;QAC3E,WAAW,EAAE,MAAM,CAAC;QACpB,uEAAuE;QACvE,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE;YACR,IAAI,EAAE,MAAM,CAAC;YACb,UAAU,EAAE,MAAM,CAAC;YACnB,IAAI,EAAE,MAAM,CAAC;YACb,QAAQ,EAAE,MAAM,EAAE,CAAC;SACpB,CAAC;KACH,CAAC;IACF,GAAG,EAAE;QACH,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,SAAS,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;KAC7B,CAAC;IACF,YAAY,EAAE;QACZ,iBAAiB,EAAE,MAAM,CAAC;QAC1B,wBAAwB,EAAE,MAAM,CAAC;QACjC,sBAAsB,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;KAC9C,CAAC;IACF,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF;;;OAGG;IACH,aAAa,EAAE,oBAAoB,CAAC;IACpC,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAuPD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,EACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAKT;AA6ND,wBAAsB,UAAU,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CA8BpE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}

package/dist/lib/config.js

@@ -17,11 +17,25 @@ export const WORKSPACE_KIND_SETTINGS = [
     "cmux",
     "tmux",
 ];
+export const LOCAL_RUNNER_SETTINGS = [
+    "auto",
+    "safehouse",
+    "sdx",
+    "none",
+];
 /**
  * Setup command run inside sibling worktrees on the host. The host is
  * assumed to already have the right Node and npm versions.
  */
 export const DEFAULT_HOST_SETUP_COMMAND = "if [ -x .claude/setup.sh ]; then ./.claude/setup.sh --deps-only; elif [ -f .claude/setup.sh ] && command -v bash >/dev/null 2>&1; then bash .claude/setup.sh --deps-only; else npm clean-install; fi";
+/**
+ * Setup command run inside an sdx (Docker Sandboxes) sandbox before the
+ * agent process exec. Independent of the host setup — sandboxes typically
+ * lack Node tooling on first start, so we keep the recipe scoped to the
+ * common case of an npm-managed repo while still letting per-model
+ * `sandbox.setupCommand` override it for languages outside that path.
+ */
+export const DEFAULT_SANDBOX_SETUP_COMMAND = "if [ -x .claude/setup.sh ]; then ./.claude/setup.sh --deps-only; elif [ -f .claude/setup.sh ] && command -v bash >/dev/null 2>&1; then bash .claude/setup.sh --deps-only; else npm clean-install; fi";
 const DEFAULT_STATUSES = {
     todo: "Todo",
     inProgress: "In Progress",
@@ -194,6 +208,43 @@ function normalizeWorkspaceKind(value, path) {
     }
     return value;
 }
+function isLocalRunnerSetting(value) {
+    return typeof value === "string" && LOCAL_RUNNER_SETTINGS.includes(value);
+}
+function normalizeLocalRunner(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isLocalRunnerSetting(value)) {
+        fail(`${path} must be one of ${LOCAL_RUNNER_SETTINGS.join(", ")} (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+function normalizeSandbox(value, path) {
+    if (!isPlainObject(value)) {
+        fail(`${path} must be an object`);
+    }
+    const { agent, template, kits, setupCommand } = value;
+    requireString(agent, `${path}.agent`);
+    const trimmedAgent = agent.trim();
+    if (trimmedAgent.length === 0) {
+        fail(`${path}.agent must be a non-empty string (got ${JSON.stringify(agent)})`);
+    }
+    const sandbox = { agent: trimmedAgent };
+    const normalizedTemplate = normalizeOptionalString(template, `${path}.template`);
+    if (normalizedTemplate !== undefined) {
+        sandbox.template = normalizedTemplate;
+    }
+    const normalizedKits = normalizeOptionalStringArray(kits, `${path}.kits`);
+    if (normalizedKits !== undefined) {
+        sandbox.kits = normalizedKits;
+    }
+    const normalizedSetup = normalizeOptionalString(setupCommand, `${path}.setupCommand`);
+    if (normalizedSetup !== undefined) {
+        sandbox.setupCommand = normalizedSetup;
+    }
+    return sandbox;
+}
 function failIfLegacyModelKeys(name, override) {
     if (!isPlainObject(override)) {
         fail(`models.definitions.${name} must be an object`);
@@ -201,14 +252,11 @@ function failIfLegacyModelKeys(name, override) {
     if (Object.hasOwn(override, "isolation")) {
         fail(`models.definitions.${name}.isolation is no longer supported: per-model isolation is no longer supported`);
     }
-    if (Object.hasOwn(override, "sandbox")) {
-        fail(`models.definitions.${name}.sandbox is no longer supported: Docker Sandboxes are no longer supported`);
-    }
     if (Object.hasOwn(override, "disabled")) {
         if (override["disabled"] !== true) {
             fail(`models.definitions.${name}.disabled must be exactly \`true\` when set (got ${JSON.stringify(override["disabled"])})`);
         }
-        const conflicting = ["cmd", "color", "usage"].filter((key) => Object.hasOwn(override, key));
+        const conflicting = ["cmd", "color", "usage", "sandbox"].filter((key) => Object.hasOwn(override, key));
         if (conflicting.length > 0) {
             fail(`models.definitions.${name}: cannot combine \`disabled: true\` with other fields (${conflicting.join(", ")}). Either disable the model or override its fields, not both.`);
         }
@@ -258,7 +306,10 @@ function mergeDefinitions(user) {
         if (override.usage !== undefined) {
             candidate.usage = override.usage;
         }
-        const { cmd, color, usage } = candidate;
+        if (override.sandbox !== undefined) {
+            candidate.sandbox = normalizeSandbox(override.sandbox, `models.definitions.${name}.sandbox`);
+        }
+        const { cmd, color, usage, sandbox } = candidate;
         if (typeof cmd !== "string" || cmd.length === 0) {
             fail(`models.definitions.${name}.cmd must be a non-empty string`);
         }
@@ -269,6 +320,9 @@ function mergeDefinitions(user) {
         if (usage !== undefined) {
             definition.usage = usage;
         }
+        if (sandbox !== undefined) {
+            definition.sandbox = sandbox;
+        }
         merged[name] = definition;
     }
     return merged;
@@ -294,10 +348,14 @@ function applyDefaults(user) {
     requireString(user.linear.projectSlug, "linear.projectSlug");
     requireObject(user.workspace, "workspace");
     if (isPlainObject(user.models) && Object.hasOwn(user.models, "isolation")) {
-        fail("models.isolation is no longer supported: local isolation is always Safehouse; remove this key");
+        fail("models.isolation is no longer supported: set `local.runner` ('safehouse' | 'sdx' | 'none' | 'auto') instead");
     }
     if (Object.hasOwn(user, "remote")) {
-        fail("remote is no longer supported: groundcrew is macOS + Safehouse only; remove the remote block from your config");
+        fail("remote is no longer supported: groundcrew runs locally via safehouse/sdx/none; remove the remote block from your config");
+    }
+    const userLocal = user.local;
+    if (userLocal !== undefined && !isPlainObject(userLocal)) {
+        fail("local must be an object");
     }
     const slugId = extractSlugId(user.linear.projectSlug);
     if (slugId === undefined) {
@@ -323,6 +381,9 @@ function applyDefaults(user) {
             initial: user.prompts?.initial ?? DEFAULT_PROMPT_INITIAL,
         },
         workspaceKind: normalizeWorkspaceKind(user.workspaceKind, "workspaceKind") ?? "auto",
+        local: {
+            runner: normalizeLocalRunner(userLocal?.runner, "local.runner") ?? "auto",
+        },
         logging: {
             file: expandHome(normalizeOptionalString(user.logging?.file, "logging.file") ?? defaultLogFile()),
         },
@@ -379,6 +440,13 @@ function validate(config) {
             }
             requireString(codexbar.provider, `${usagePath}.codexbar.provider`);
         }
+        if (definition.sandbox !== undefined) {
+            requireString(definition.sandbox.agent, `models.definitions.${name}.sandbox.agent`);
+        }
+    }
+    /* v8 ignore next 5 @preserve -- normalizeLocalRunner rejects invalid strings before validate() runs; this is a belt-and-suspenders guard */
+    if (!LOCAL_RUNNER_SETTINGS.includes(config.local.runner)) {
+        fail(`local.runner must be one of ${LOCAL_RUNNER_SETTINGS.join(", ")} (got ${JSON.stringify(config.local.runner)})`);
     }
     // Disabled-default check must run before the generic "not a key" check so
     // the user gets the specific "is disabled" message instead of a stale-list

package/dist/lib/dockerSandbox.d.ts

@@ -0,0 +1,40 @@
+import type { SandboxDefinition } from "./config.ts";
+/**
+ * Derive a deterministic sbx sandbox name from the repository + model
+ * tuple so `crew sandbox auth <repo>` and the subsequent `crew local`
+ * launch agree on which sandbox to target. Lowercased and reduced to the
+ * sbx-safe charset (`a-z0-9.+-`) so unusual repo names still round-trip
+ * cleanly. Keep the prefix stable — doctor and teardown use it to
+ * identify groundcrew-owned sandboxes.
+ */
+export declare function sandboxNameFor(arguments_: {
+    repository: string;
+    model: string;
+}): string;
+/**
+ * Probe `sbx ls` to see whether a sandbox with `sandboxName` already
+ * exists. Used by `crew sandbox auth` to switch between create vs reuse
+ * branches without surfacing the raw sbx error on first run.
+ */
+export declare function sandboxExists(sandboxName: string, signal?: AbortSignal): Promise<boolean>;
+interface EnsureSandboxArguments {
+    sandboxName: string;
+    sandbox: SandboxDefinition;
+    /**
+     * Host path bound into the sandbox at the same path. Pass the workspace
+     * `projectDir` so all per-ticket worktrees (siblings of the bare repo
+     * clone) are visible to `sbx exec -w <worktreeDir>` after creation.
+     */
+    mountPath: string;
+}
+/**
+ * Idempotent guard: ensure a Docker Sandboxes container exists for the
+ * given repository + model. Probes `sbx ls`; if `sandboxName` is missing,
+ * calls `sbx create --name <name> [--template <t>] [--kit <k>]... <agent>
+ * <mountPath>` to provision it. First-time agent auth still happens inside
+ * the sandbox the first time `sbx exec` runs the agent — `create` only
+ * provisions the container, it does not attach.
+ */
+export declare function ensureSandbox(arguments_: EnsureSandboxArguments, signal?: AbortSignal): Promise<void>;
+export {};
+//# sourceMappingURL=dockerSandbox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dockerSandbox.d.ts","sourceRoot":"","sources":["../../src/lib/dockerSandbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAMxF;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAM/F;AAED,UAAU,sBAAsB;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,sBAAsB,EAClC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAqBf"}