@clipboard-health/groundcrew 2.2.0 → 2.3.1

package/dist/lib/boardSource.js

@@ -129,9 +129,9 @@ async function fetchBoard(client, config) {
     const issues = nodes
         .filter((node) => node.children.nodes.length === 0)
         .map((node) => {
-        const parsedAgentLabels = parseAgentLabels(node.labels.nodes, config);
-        warnIfDisabledFallback(node.identifier, parsedAgentLabels, config);
-        const repository = parsedAgentLabels === undefined
+        const modelResolution = resolveModelFor({ labels: node.labels.nodes, config });
+        warnIfDisabledFallback(node.identifier, modelResolution, config);
+        const repository = modelResolution.kind === "no-label"
             ? undefined
             : parseRepository({
                 description: node.description ?? undefined,
@@ -139,6 +139,16 @@ async function fetchBoard(client, config) {
                 repositoryRegex,
                 ticket: node.identifier,
             });
+        let model;
+        if (modelResolution.kind === "matched") {
+            ({ model } = modelResolution);
+        }
+        else if (modelResolution.kind === "disabled-fallback") {
+            model = modelResolution.fallbackModel;
+        }
+        else if (modelResolution.kind === "agent-any") {
+            model = AGENT_ANY_MODEL;
+        }
         return {
             id: node.identifier.toLowerCase(),
             uuid: node.id,
@@ -148,7 +158,7 @@ async function fetchBoard(client, config) {
             assignee: node.assignee?.name ?? "Unassigned",
             updatedAt: node.updatedAt,
             repository,
-            model: parsedAgentLabels?.model,
+            model,
             teamId: node.team?.id ?? "",
             blockers: blockersFromRelations(node.inverseRelations?.nodes ?? []),
             hasMoreBlockers: node.inverseRelations?.pageInfo.hasNextPage ?? false,
@@ -174,22 +184,64 @@ function buildRepositoryRegex(config) {
     return new RegExp(String.raw `\b(${alternation})\b`);
 }
 const ISSUE_LABEL_PAGE_SIZE = 50;
-/**
- * `agent-any` collapses to `models.default` here — manual setup doesn't run
- * the usage-gated `any` resolver, so the caller gets a concrete model name
- * instead of a sentinel that downstream code can't interpret.
- */
-export async function fetchResolvedIssue(arguments_) {
-    const { client, config, ticket } = arguments_;
+const ISSUE_RELATION_PAGE_SIZE = 50;
+export async function fetchBlockersForTicket(arguments_) {
+    const { client, uuid } = arguments_;
+    const relations = [];
+    let after = null;
+    for (;;) {
+        // oxlint-disable-next-line no-await-in-loop -- pagination cursor depends on the previous response
+        const response = await client.client.rawRequest(`query IssueBlockers($id: String!, $after: String) {
+        issue(id: $id) {
+          inverseRelations(first: ${ISSUE_RELATION_PAGE_SIZE}, after: $after, includeArchived: false) {
+            nodes {
+              type
+              issue {
+                identifier
+                title
+                state { name }
+              }
+            }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      }`, { id: uuid, after });
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- shape is fixed by our GraphQL query above
+        const { issue } = response.data;
+        if (issue === null) {
+            return [];
+        }
+        relations.push(...issue.inverseRelations.nodes);
+        if (!issue.inverseRelations.pageInfo.hasNextPage) {
+            break;
+        }
+        after = issue.inverseRelations.pageInfo.endCursor;
+    }
+    return blockersFromRelations(relations);
+}
+export async function fetchRawLinearIssue(arguments_) {
+    const { client, ticket } = arguments_;
     const response = await client.client.rawRequest(`query ResolveIssue($id: String!) {
       issue(id: $id) {
         id
         title
         description
         team { id }
+        state { name }
         labels(first: ${ISSUE_LABEL_PAGE_SIZE}) {
           nodes { name }
         }
+        inverseRelations(first: 50, includeArchived: false) {
+          nodes {
+            type
+            issue {
+              identifier
+              title
+              state { name }
+            }
+          }
+          pageInfo { hasNextPage }
+        }
       }
     }`, { id: ticket.toUpperCase() });
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- shape is fixed by our GraphQL query above
@@ -197,26 +249,119 @@ export async function fetchResolvedIssue(arguments_) {
     if (issue === null) {
         throw new Error(`Ticket ${ticket.toUpperCase()} not found in Linear`);
     }
-    const description = issue.description ?? "";
-    const repository = parseRepository({
-        description,
+    return {
+        uuid: issue.id,
+        title: issue.title,
+        description: issue.description ?? "",
+        teamId: issue.team?.id ?? "",
+        labels: issue.labels.nodes,
+        stateName: issue.state?.name ?? "",
+        blockers: blockersFromRelations(issue.inverseRelations?.nodes ?? []),
+        hasMoreBlockers: issue.inverseRelations?.pageInfo.hasNextPage ?? false,
+    };
+}
+export async function fetchInProgressIssueCount(arguments_) {
+    const { client, config } = arguments_;
+    let after = null;
+    let count = 0;
+    for (;;) {
+        // oxlint-disable-next-line no-await-in-loop -- pagination cursor depends on the previous response
+        const response = await client.client.rawRequest(`query InProgressIssues($slugId: String!, $stateName: String!, $agentLabelPrefix: String!, $after: String) {
+        issues(
+          filter: {
+            project: { slugId: { eq: $slugId } }
+            state: { name: { eq: $stateName } }
+            labels: { some: { name: { startsWith: $agentLabelPrefix } } }
+          }
+          first: ${ISSUES_PAGE_SIZE}
+          after: $after
+          includeArchived: false
+        ) {
+          nodes { id }
+          pageInfo { hasNextPage endCursor }
+        }
+      }`, {
+            slugId: config.linear.slugId,
+            stateName: config.linear.statuses.inProgress,
+            agentLabelPrefix: AGENT_LABEL_PREFIX,
+            after,
+        });
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- shape is fixed by our GraphQL query above
+        const { issues: page } = response.data;
+        count += page.nodes.length;
+        if (!page.pageInfo.hasNextPage) {
+            return count;
+        }
+        after = page.pageInfo.endCursor;
+    }
+}
+export function resolveRepositoryFor(arguments_) {
+    const { description, config } = arguments_;
+    if (description === undefined || description.length === 0) {
+        return { kind: "missing" };
+    }
+    const repository = buildRepositoryRegex(config).exec(description)?.[1];
+    if (repository === undefined) {
+        return { kind: "missing" };
+    }
+    return { kind: "ok", repository };
+}
+export function resolveModelFor(arguments_) {
+    const { labels, config } = arguments_;
+    const parsed = parseAgentLabels(labels, config);
+    if (parsed === undefined) {
+        return { kind: "no-label" };
+    }
+    if (parsed.model === AGENT_ANY_MODEL) {
+        return { kind: "agent-any" };
+    }
+    if (parsed.disabledFallback !== undefined) {
+        return {
+            kind: "disabled-fallback",
+            requestedModel: parsed.disabledFallback,
+            fallbackModel: parsed.model,
+        };
+    }
+    return { kind: "matched", model: parsed.model };
+}
+/**
+ * `agent-any` collapses to `models.default` here — manual setup doesn't run
+ * the usage-gated `any` resolver, so the caller gets a concrete model name
+ * instead of a sentinel that downstream code can't interpret.
+ */
+export async function fetchResolvedIssue(arguments_) {
+    const { client, config, ticket } = arguments_;
+    const raw = await fetchRawLinearIssue({ client, ticket });
+    const repositoryResolution = resolveRepositoryFor({
+        description: raw.description,
         config,
-        repositoryRegex: buildRepositoryRegex(config),
         ticket: ticket.toUpperCase(),
     });
+    if (repositoryResolution.kind === "missing") {
+        throw new RepositoryResolutionError({
+            ticket: ticket.toUpperCase(),
+            repositories: config.workspace.knownRepositories,
+        });
+    }
     // Manual setup is an explicit per-ticket opt-in by the user, so an
     // unlabeled ticket still resolves to `models.default` — different from
     // the auto-pickup path, where unlabeled tickets are ignored.
-    const parsed = parseAgentLabels(issue.labels.nodes, config);
-    warnIfDisabledFallback(ticket, parsed, config);
-    const model = parsed === undefined || parsed.model === AGENT_ANY_MODEL ? config.models.default : parsed.model;
+    const modelResolution = resolveModelFor({ labels: raw.labels, config });
+    warnIfDisabledFallback(ticket, modelResolution, config);
+    let model = config.models.default;
+    if (modelResolution.kind === "matched") {
+        ({ model } = modelResolution);
+    }
+    else if (modelResolution.kind === "disabled-fallback") {
+        model = modelResolution.fallbackModel;
+    }
     return {
-        uuid: issue.id,
-        title: issue.title,
-        description,
-        repository,
+        uuid: raw.uuid,
+        title: raw.title,
+        description: raw.description,
+        repository: repositoryResolution.repository,
         model,
-        teamId: issue.team?.id ?? "",
+        teamId: raw.teamId,
     };
 }
 function parseRepository(arguments_) {
@@ -278,11 +423,11 @@ function parseAgentLabels(labels, config) {
     }
     return fallback;
 }
-function warnIfDisabledFallback(ticket, parsed, config) {
-    if (parsed?.disabledFallback === undefined) {
+function warnIfDisabledFallback(ticket, modelResolution, config) {
+    if (modelResolution.kind !== "disabled-fallback") {
         return;
     }
-    log(`${ticket.toLowerCase()}: agent-${parsed.disabledFallback} label refers to a disabled model; falling back to models.default (${config.models.default})`);
+    log(`${ticket.toLowerCase()}: agent-${modelResolution.requestedModel} label refers to a disabled model; falling back to models.default (${config.models.default})`);
 }
 function blockersFromRelations(relations) {
     return relations

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"}

package/dist/lib/dockerSandbox.js

@@ -0,0 +1,58 @@
+import { runCommandAsync } from "./commandRunner.js";
+/**
+ * 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 function sandboxNameFor(arguments_) {
+    const raw = `groundcrew-${arguments_.repository}-${arguments_.model}`.toLowerCase();
+    return raw
+        .replaceAll(/[^a-z0-9.+-]+/g, "-")
+        .replaceAll(/-+/g, "-")
+        .replaceAll(/^-|-$/g, "");
+}
+/**
+ * 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 async function sandboxExists(sandboxName, signal) {
+    const out = signal === undefined
+        ? await runCommandAsync("sbx", ["ls"])
+        : await runCommandAsync("sbx", ["ls"], { signal });
+    return out.split("\n").some((line) => line.trim().split(/\s+/)[0] === sandboxName);
+}
+/**
+ * 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 async function ensureSandbox(arguments_, signal) {
+    if (await sandboxExists(arguments_.sandboxName, signal)) {
+        return;
+    }
+    const createArguments = ["create", "--name", arguments_.sandboxName];
+    if (arguments_.sandbox.template !== undefined) {
+        createArguments.push("--template", arguments_.sandbox.template);
+    }
+    for (const kit of arguments_.sandbox.kits ?? []) {
+        createArguments.push("--kit", kit);
+    }
+    createArguments.push(arguments_.sandbox.agent, arguments_.mountPath);
+    const options = signal === undefined ? {} : { signal };
+    try {
+        await runCommandAsync("sbx", createArguments, options);
+    }
+    catch (error) {
+        if (await sandboxExists(arguments_.sandboxName, signal)) {
+            return;
+        }
+        throw error;
+    }
+}

package/dist/lib/host.d.ts

@@ -6,18 +6,28 @@
 export interface HostCapabilities {
     /** True when the `safehouse` binary is on PATH. */
     hasSafehouse: boolean;
+    /** True when the `sbx` (Docker Sandboxes) binary is on PATH. */
+    hasSbx: boolean;
     /** True when the `cmux` binary is on PATH. */
     hasCmux: boolean;
     /** True when the `tmux` binary is on PATH. */
     hasTmux: boolean;
     /** True when the host platform is macOS. Safehouse is macOS-only. */
     isMacOS: boolean;
+    /** True when the host platform is Linux. */
+    isLinux: boolean;
     /**
      * True when the host platform is one Safehouse supports. Safehouse is
      * macOS-only at time of writing; local setup uses this to reject Linux
      * or WSL before creating a worktree.
      */
     isSafehouseSupported: boolean;
+    /**
+     * True when sdx (Docker Sandboxes) is supportable on this platform —
+     * sbx is published for both macOS and Linux, so this stays in sync with
+     * "macOS || Linux". WSL inherits Linux capabilities transparently.
+     */
+    isSdxSupported: boolean;
 }
 /**
  * Resolves a binary on PATH the same way `which` does. Returns the first

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

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/lib/host.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;IACtB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAc1F;AAED,wBAAsB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAc5F"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/lib/host.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;IACtB,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAc1F;AAED,wBAAsB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmB5F"}