@clipboard-health/groundcrew 4.35.0 → 4.36.0

package/README.md

@@ -69,10 +69,15 @@ crew run --watch
 
 Linear works out of the box: assign tasks to yourself and add an `agent-*` label.
 
-- `agent-claude`, `agent-codex`, or `agent-<name>` routes to that agent.
+- `agent-claude`, `agent-codex`, or `agent-<name>` routes to that enabled launch profile.
 - `agent-any` routes to the enabled agent with the most session headroom, after skipping agents over their session limit or weekly paced budget.
 - Tasks without an `agent-*` label are ignored by `crew run`; dispatch one manually with `crew start <TASK>`.
 
+Agent names are launch profiles, so you can use them to pick model tiers. For example,
+define `claude-fable` with `claude --model claude-fable-5 --permission-mode auto`
+and `claude-opus` with `claude --model claude-opus-4-8 --permission-mode auto`,
+then label tasks with `agent-claude-fable` or `agent-claude-opus`.
+
 Groundcrew scans `workspace.knownRepositories` to infer which repo a task belongs to.
 
 A task blocked by non-terminal blockers is skipped until those blockers are done.

package/crew.config.example.ts

@@ -52,13 +52,24 @@ export default {
   },
   agents: {
     default: "claude",
-    // `definitions` is the enabled agent set. Built-in keys can use `{}` to
-    // opt into the shipped command/color/usage preset. Add `codex: {}` if you
-    // want both shipped agents, or add a custom entry and tag tasks with
-    // `agent-<name>`.
+    // `definitions` is the enabled launch profile set. Built-in keys can use
+    // `{}` to opt into the shipped command/color/usage preset. Add
+    // `codex: {}` if you want both shipped agents. Agent names are launch
+    // profiles: add custom entries such as `claude-fable` or `claude-opus` to
+    // pin a model per task, then tag tasks with `agent-<name>`.
     definitions: {
       claude: {},
       // codex: {},
+      // "claude-fable": {
+      //   cmd: "claude --model claude-fable-5 --permission-mode auto",
+      //   color: "#C15F3C",
+      //   usage: { codexbar: { provider: "claude" } },
+      // },
+      // "claude-opus": {
+      //   cmd: "claude --model claude-opus-4-8 --permission-mode auto",
+      //   color: "#8A4FFF",
+      //   usage: { codexbar: { provider: "claude" } },
+      // },
       // cursor: {
       //   cmd: "cursor-agent",
       //   color: "#929292",

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;AAyLH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAmF/C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuQH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAmF/C"}

package/dist/commands/doctor.js

@@ -3,12 +3,12 @@
  * Returns true if every required check passes; false otherwise.
  */
 import { existsSync, statSync } from "node:fs";
-import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
 import { loadConfigWithSource, worktreeBaseDir, } from "../lib/config.js";
 import { detectHostCapabilities, which } from "../lib/host.js";
 import { isEnvironmentAssignment } from "../lib/launchCommand.js";
 import { resolveLocalRunner } from "../lib/localRunner.js";
+import { naturalIdFromCanonical } from "../lib/taskSource.js";
 import { gatedAgents } from "../lib/usage.js";
 import { errorMessage, writeOutput } from "../lib/util.js";
 import { resolveWorkspaceKind } from "../lib/workspaces.js";
@@ -34,27 +34,97 @@ async function checkCmd(cmd, required, hint) {
     }
     return result;
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
 /**
- * Source-agnostic reachability check: build every configured task source
- * and run the Board's `verify()` fan-out. Replaces the old Linear-only
- * "api key + reachability" probe so a misconfigured shell (or future Jira)
- * source surfaces here too. A missing Linear API key still fails verify with
- * its own user-facing message, so the prior behavior is preserved.
+ * True when a raw source config entry declares `kind: "shell"`. Gates the
+ * shell-only read probe.
  */
-async function checkSourceProbe(config) {
+function isShellSource(raw) {
+    if (!isRecord(raw)) {
+        return false;
+    }
+    const { kind } = raw;
+    return kind === "shell";
+}
+function hasExplicitGetTaskCommand(raw) {
+    const { commands } = raw;
+    if (!isRecord(commands)) {
+        return false;
+    }
+    const { getTask, resolveOne } = commands;
+    return typeof getTask === "string" || typeof resolveOne === "string";
+}
+function shellReadProbeFor(raw) {
+    if (!isShellSource(raw)) {
+        return "none";
+    }
+    return hasExplicitGetTaskCommand(raw) ? "listTasksAndGetTask" : "listTasks";
+}
+/**
+ * Probe each configured task source independently and emit one `Check` per
+ * source (named `source: <name>`), so a single broken source is attributable
+ * instead of hidden behind an aggregate "N source(s) verified" line.
+ *
+ * Every source runs its `verify()`. Shell sources are additionally deep-probed
+ * via `listTasks()`: their `verify` command can discard stdout (e.g.
+ * `... fetch >/dev/null`), so a malformed task payload sails through verify and
+ * only blows up later in `crew run`. Running listTasks here surfaces a
+ * wrong-shape payload (a `TaskSourceOutputError` with a readable message) at
+ * doctor time. Non-shell sources (Linear) are left to `verify()` alone — their
+ * fetch is an expensive network call that verify already exercises.
+ */
+async function checkSourceProbes(config) {
+    const rawSources = sourcesFromConfig(config);
+    let sources;
     try {
-        const sources = await buildSources(sourcesFromConfig(config), { globalConfig: config });
-        const board = createBoard(sources);
-        await board.verify();
-        return {
-            name: "source probe",
-            ok: true,
-            required: true,
-            hint: `${sources.length} source(s) verified`,
-        };
+        sources = await buildSources(rawSources, { globalConfig: config });
+    }
+    catch (error) {
+        // Building sources failed before any individual probe (bad config / unknown
+        // kind). Surface it as a single failed check rather than per-source.
+        return [{ name: "sources", ok: false, required: true, hint: errorMessage(error) }];
+    }
+    if (sources.length === 0) {
+        return [{ name: "sources", ok: false, required: true, hint: "no task sources configured" }];
+    }
+    const checks = [];
+    for (const [index, source] of sources.entries()) {
+        const shellReadProbe = shellReadProbeFor(rawSources[index]);
+        // oxlint-disable-next-line no-await-in-loop -- sequential keeps each verdict attributable to one source
+        checks.push(await probeSource(source, shellReadProbe));
+    }
+    return checks;
+}
+async function probeSource(source, shellReadProbe) {
+    const name = `source: ${source.name}`;
+    try {
+        await source.verify();
+        if (shellReadProbe === "none") {
+            return { name, ok: true, required: true, hint: "verified" };
+        }
+        const tasks = await source.listTasks();
+        const parts = [`fetched ${tasks.length} task(s)`];
+        // Read-path symmetry: an id listTasks emitted must resolve via getTask.
+        // Skipped when getTask is only the adapter's listTasks fallback, since that
+        // would just re-run listTasks and can race changing source output.
+        const [first] = tasks;
+        if (first !== undefined && shellReadProbe === "listTasksAndGetTask") {
+            const naturalId = naturalIdFromCanonical(first.id);
+            const resolved = await source.getTask(naturalId);
+            if (resolved === null) {
+                throw new Error(`getTask("${naturalId}") returned nothing, but listTasks emitted it`);
+            }
+            if (resolved.id !== first.id) {
+                throw new Error(`getTask("${naturalId}") resolved "${resolved.id}", but listTasks emitted "${first.id}"`);
+            }
+            parts.push("getTask round-trips");
+        }
+        return { name, ok: true, required: true, hint: `verified; ${parts.join("; ")}` };
     }
     catch (error) {
-        return { name: "source probe", ok: false, required: true, hint: errorMessage(error) };
+        return { name, ok: false, required: true, hint: errorMessage(error) };
     }
 }
 function checkDir(path, label) {
@@ -190,7 +260,7 @@ export async function doctor() {
     const workspaceOutcome = resolveWorkspaceOutcome(config, host);
     reportWorkspaceKind(config, workspaceOutcome);
     const checks = [
-        await checkSourceProbe(config),
+        ...(await checkSourceProbes(config)),
         await checkCmd("git", true, "https://git-scm.com/"),
         ...(await workspaceChecks(workspaceOutcome)),
         checkDir(config.workspace.projectDir, "workspace.projectDir"),

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

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2DH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAiBD,wBAAsB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgE7E"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoEH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAiBD,wBAAsB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgE7E"}

package/dist/commands/orchestrator.js

@@ -8,7 +8,7 @@ import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
 import { loadConfigWithSource } from "../lib/config.js";
 import { findPullRequestsForBranch } from "../lib/pullRequests.js";
-import { RepositoryResolutionError } from "../lib/taskSource.js";
+import { RepositoryResolutionError, TaskSourceOutputError, } from "../lib/taskSource.js";
 import { getUsageByAgent } from "../lib/usage.js";
 import { errorMessage, log, sleep, writeOutput } from "../lib/util.js";
 import { worktrees } from "../lib/worktrees.js";
@@ -30,6 +30,11 @@ async function withRetry(function_, signal, maxRetries = RETRY_MAX_ATTEMPTS, bas
             if (error instanceof RepositoryResolutionError) {
                 throw error;
             }
+            // A source returned unparseable output — deterministic, so retrying just
+            // delays a guaranteed failure behind confusing "Retrying in Ns" lines.
+            if (error instanceof TaskSourceOutputError) {
+                throw error;
+            }
             if (attempt === maxRetries) {
                 throw error;
             }

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

@@ -1 +1 @@
-{"version":3,"file":"resumeWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/resumeWorkspace.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAenE,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AA0ID,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA6Ef;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}
+{"version":3,"file":"resumeWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/resumeWorkspace.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAenE,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AA0ID,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}

package/dist/commands/resumeWorkspace.js

@@ -119,7 +119,7 @@ export async function resumeWorkspace(config, options) {
     if (definition === undefined) {
         throw new Error(`Unknown agent: ${context.agent}`);
     }
-    const { runner, sandboxName, ensureReady } = await prepareAgentLaunch({
+    const { runner, sandboxName, workspaceKind, ensureReady } = await prepareAgentLaunch({
         config,
         agent: context.agent,
         definition,
@@ -150,6 +150,7 @@ export async function resumeWorkspace(config, options) {
             workingDir: launchDir,
             secretsFile,
             sandboxName,
+            workspaceKind,
             workerEnvironment: workerEnvironmentForTask(context.completionTaskId),
         }));
         const launchCmd = stageWorkspaceLaunchCommand(stagedPrompt.directory, launchCommand);

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

@@ -1 +1 @@
-{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAuBnE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CA8Hf;AAgJD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CA6Cf"}
+{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAuBnE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CA+Hf;AAgJD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CA6Cf"}

package/dist/commands/setupWorkspace.js

@@ -32,7 +32,7 @@ export async function setupWorkspace(config, options, runOptions = {}) {
     if (!definition) {
         throw new Error(`Unknown agent: ${agent}`);
     }
-    const { runner, sandboxName, ensureReady } = await prepareAgentLaunch({
+    const { runner, sandboxName, workspaceKind, ensureReady } = await prepareAgentLaunch({
         config,
         agent,
         definition,
@@ -92,6 +92,7 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             secretsFile,
             prepareWorktreeCommand,
             sandboxName,
+            workspaceKind,
             workerEnvironment: workerEnvironmentForTask(completionTaskId),
         });
         srtSettingsDir = stagedSrtSettingsDir;

package/dist/lib/adapters/shell/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAIL,KAAK,KAAK,IAAI,cAAc,EAG5B,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAyErB,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAuB3F;AA8BD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,cAAc,GACvB,UAAU,CA6LZ"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAIL,KAAK,KAAK,IAAI,cAAc,EAG5B,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAyErB,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAuB3F;AA8BD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,cAAc,GACvB,UAAU,CAsMZ"}

package/dist/lib/adapters/shell/factory.js

@@ -22,6 +22,7 @@
 import { toCanonicalId, } from "../../taskSource.js";
 import { errorMessage, writeError } from "../../util.js";
 import { invokeShellCommand } from "./invoke.js";
+import { parseShellJson } from "./parseOutput.js";
 import { shellFetchOutputSchema, shellIssueSchema, shellValidateOutputSchema, } from "./schema.js";
 const DEFAULT_TIMEOUTS = {
     verify: 10_000,
@@ -134,7 +135,10 @@ export function createShellTaskSource(config, _context) {
             env: config.env,
             sourceName,
         });
-        const parsed = shellFetchOutputSchema.parse(JSON.parse(stdout));
+        const parsed = parseShellJson(shellFetchOutputSchema, stdout, {
+            sourceName,
+            command: "listTasks",
+        });
         return parsed.map((si) => toCanonicalIssue(si, sourceName));
     }
     async function getTask(naturalId) {
@@ -158,7 +162,10 @@ export function createShellTaskSource(config, _context) {
         if (result.exitCode === 3 || result.stdout.trim().length === 0) {
             return null;
         }
-        const parsed = shellIssueSchema.parse(JSON.parse(result.stdout));
+        const parsed = parseShellJson(shellIssueSchema, result.stdout, {
+            sourceName,
+            command: "getTask",
+        });
         return toCanonicalIssue(parsed, sourceName);
     }
     // Shared by markInProgress / markInReview: both pipe the canonical issue's
@@ -259,7 +266,10 @@ export function createShellTaskSource(config, _context) {
             if (trimmed.length === 0) {
                 throw new Error(`shell source "${sourceName}" createTask command produced no output (expected one ShellIssue JSON)`);
             }
-            const parsed = shellIssueSchema.parse(JSON.parse(trimmed));
+            const parsed = parseShellJson(shellIssueSchema, trimmed, {
+                sourceName,
+                command: "createTask",
+            });
             return toCanonicalIssue(parsed, sourceName);
         };
     }

package/dist/lib/adapters/shell/parseOutput.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Friendly stdout parsing for the shell adapter. A shell source emits JSON on
+ * stdout; both `JSON.parse` and the Zod schema can reject it. A raw `ZodError`
+ * stringifies to a JSON array of issues — cryptic, unattributed, and (for a
+ * fetch array) repeated once per task. This module collapses that into a
+ * single user-facing `TaskSourceOutputError` that names the source, the
+ * command, and the offending field(s), with a targeted hint for the common
+ * "missing `agent`" mistake.
+ */
+import type { z } from "zod";
+export interface ShellParseContext {
+    /** The source's configured `name`, surfaced so the user knows which source broke. */
+    sourceName: string;
+    /** The contract method that produced the output, e.g. `"listTasks"` or `"getTask"`. */
+    command: string;
+}
+/**
+ * Parse `stdout` as JSON and validate it against `schema`. On any failure,
+ * throws a `TaskSourceOutputError` with a readable, source-attributed message
+ * instead of a raw `SyntaxError` / `ZodError`.
+ */
+export declare function parseShellJson<T>(schema: z.ZodType<T>, stdout: string, context: ShellParseContext): T;
+//# sourceMappingURL=parseOutput.d.ts.map

package/dist/lib/adapters/shell/parseOutput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseOutput.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/parseOutput.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAK7B,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,CAAC,CAcH"}

package/dist/lib/adapters/shell/parseOutput.js

@@ -0,0 +1,67 @@
+/**
+ * Friendly stdout parsing for the shell adapter. A shell source emits JSON on
+ * stdout; both `JSON.parse` and the Zod schema can reject it. A raw `ZodError`
+ * stringifies to a JSON array of issues — cryptic, unattributed, and (for a
+ * fetch array) repeated once per task. This module collapses that into a
+ * single user-facing `TaskSourceOutputError` that names the source, the
+ * command, and the offending field(s), with a targeted hint for the common
+ * "missing `agent`" mistake.
+ */
+import { TaskSourceOutputError } from "../../taskSource.js";
+import { errorMessage } from "../../util.js";
+/**
+ * Parse `stdout` as JSON and validate it against `schema`. On any failure,
+ * throws a `TaskSourceOutputError` with a readable, source-attributed message
+ * instead of a raw `SyntaxError` / `ZodError`.
+ */
+export function parseShellJson(schema, stdout, context) {
+    let json;
+    try {
+        json = JSON.parse(stdout);
+    }
+    catch (error) {
+        throw new TaskSourceOutputError(`source "${context.sourceName}": the ${context.command} command did not return valid JSON (${errorMessage(error)}).`);
+    }
+    const result = schema.safeParse(json);
+    if (result.success) {
+        return result.data;
+    }
+    throw new TaskSourceOutputError(formatSchemaError(result.error, context));
+}
+/** The last string segment of an issue path — the field name, ignoring array indices. */
+function fieldName(path) {
+    for (let index = path.length - 1; index >= 0; index -= 1) {
+        const segment = path[index];
+        if (typeof segment === "string") {
+            return segment;
+        }
+    }
+    return undefined;
+}
+/** One human-readable phrase describing what's wrong with a single issue. */
+function describeIssue(issue) {
+    const field = fieldName(issue.path);
+    const label = field === undefined ? "field" : `"${field}"`;
+    // Zod v4 reports a missing required key as an `invalid_type` whose message
+    // ends in "received undefined"; there is no separate `received` property to
+    // branch on, so we match the message.
+    if (issue.code === "invalid_type" && issue.message.includes("received undefined")) {
+        return `are missing the required ${label} field`;
+    }
+    return `have an invalid ${label} field: ${issue.message}`;
+}
+function formatSchemaError(error, context) {
+    // A fetch array yields one issue per task (48 tasks missing `agent` → 48
+    // identical issues). Collapse identical phrasings into a single counted line,
+    // preserving first-seen order via the Map's insertion order.
+    const counts = new Map();
+    for (const issue of error.issues) {
+        const description = describeIssue(issue);
+        counts.set(description, (counts.get(description) ?? 0) + 1);
+    }
+    const lines = [...counts].map(([description, count]) => `  • ${count} issue(s) ${description}`);
+    return [
+        `source "${context.sourceName}": the ${context.command} command returned task JSON that doesn't match the expected shape:`,
+        ...lines,
+    ].join("\n");
+}

package/dist/lib/agentLaunch.d.ts

@@ -1,5 +1,6 @@
 import { type LocalRunner, type AgentDefinition, type ResolvedConfig } from "./config.ts";
 import { type WorkerEnvironment } from "./launchCommand.ts";
+import type { WorkspaceKind } from "./workspaceAdapter.ts";
 /**
  * Stage any srt settings and build the workspace launch command — the assembly
  * shared verbatim by `setupWorkspace` (fresh runs) and `resumeWorkspace`
@@ -17,6 +18,7 @@ export declare function composeAgentLaunch(input: {
     secretsFile?: string | undefined;
     prepareWorktreeCommand?: string | undefined;
     sandboxName?: string | undefined;
+    workspaceKind: WorkspaceKind;
     workerEnvironment?: WorkerEnvironment | undefined;
 }): {
     launchCommand: string;
@@ -25,6 +27,7 @@ export declare function composeAgentLaunch(input: {
 interface PreparedAgentLaunch {
     runner: LocalRunner;
     sandboxName: string | undefined;
+    workspaceKind: WorkspaceKind;
     ensureReady: () => Promise<void>;
 }
 export declare function prepareAgentLaunch(input: {

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

@@ -1 +1 @@
-{"version":3,"file":"agentLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/agentLaunch.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAOhF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACnD,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CA2BhE;AAsBD,UAAU,mBAAmB;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqD/B;AAwBD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB"}
+{"version":3,"file":"agentLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/agentLaunch.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAM5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACnD,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAgChE;AAmDD,UAAU,mBAAmB;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsD/B;AAwBD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB"}

package/dist/lib/agentLaunch.js

@@ -1,13 +1,13 @@
-import { ensureClearance } from "@clipboard-health/clearance";
+import { ensureClearance, resolveSafehouseCmuxIntegration, safehouseCmuxIntegrationWarningLines, } from "@clipboard-health/clearance";
 import { clearanceAllowHostsFilesFromEnvironment } from "./clearanceAllowlist.js";
 import { hasPreLaunchEnv, } from "./config.js";
 import { detectHostCapabilities } from "./host.js";
-import { buildLaunchCommand } from "./launchCommand.js";
+import { buildLaunchCommand, inferAgentCommandName, } from "./launchCommand.js";
 import { assertLocalRunnerRequirements, resolveLocalRunner } from "./localRunner.js";
 import { sandboxNameFor } from "./sandboxName.js";
 import { buildAndStageSrtLaunch, resolveGitCommonDir } from "./srtLaunch.js";
-import { debug, sleep } from "./util.js";
-import { workspaces } from "./workspaces.js";
+import { debug, sleep, writeError } from "./util.js";
+import { resolveWorkspaceKind, workspaces } from "./workspaces.js";
 /**
  * Stage any srt settings and build the workspace launch command — the assembly
  * shared verbatim by `setupWorkspace` (fresh runs) and `resumeWorkspace`
@@ -23,6 +23,9 @@ export function composeAgentLaunch(input) {
             definition: input.definition,
         })
         : undefined;
+    const safehouseAgentIntegration = input.runner === "safehouse"
+        ? safehouseAgentIntegrationFor(input.workspaceKind, input.definition)
+        : undefined;
     const launchCommand = buildLaunchCommand({
         definition: input.definition,
         promptFile: input.promptFile,
@@ -38,6 +41,7 @@ export function composeAgentLaunch(input) {
         srtAgentConfigDirEnv: staged?.agentConfigDirEnv,
         workerEnvironment: input.workerEnvironment,
         safehouseAddDirs: input.runner === "safehouse" ? resolveSafehouseAddDirs(input.worktreeDir) : undefined,
+        safehouseAgentIntegration,
     });
     return { launchCommand, srtSettingsDir: staged?.directory };
 }
@@ -60,9 +64,33 @@ export function composeAgentLaunch(input) {
 function resolveSafehouseAddDirs(worktreeDir) {
     return [...new Set([worktreeDir, resolveGitCommonDir(worktreeDir)])];
 }
+function safehouseAgentIntegrationFor(workspaceKind, definition) {
+    if (workspaceKind !== "cmux") {
+        return undefined;
+    }
+    const isClaudeAgent = inferAgentCommandName(definition.cmd) === "claude";
+    const cmuxIntegration = resolveSafehouseCmuxIntegration();
+    if (isClaudeAgent) {
+        warnOnCmuxIntegrationDrift({ unreviewedEnvNames: cmuxIntegration.unreviewedEnvNames });
+    }
+    return {
+        addDirsReadOnly: cmuxIntegration.addDirsReadOnly,
+        envPass: cmuxIntegration.envPass,
+        commandPreludes: isClaudeAgent ? [cmuxIntegration.claudeCommandPrelude] : [],
+    };
+}
+function warnOnCmuxIntegrationDrift(input) {
+    for (const warningLine of safehouseCmuxIntegrationWarningLines({
+        commandName: "groundcrew",
+        unreviewedEnvNames: input.unreviewedEnvNames,
+    })) {
+        writeError(warningLine);
+    }
+}
 export async function prepareAgentLaunch(input) {
     const host = await detectHostCapabilities(input.signal);
     const runner = resolveLocalRunner(input.config.local.runner, host);
+    const workspaceKind = resolveWorkspaceKind({ config: input.config, host }).resolved;
     assertLocalRunnerRequirements(host, runner);
     const ensureReady = runner === "safehouse"
         ? async () => {
@@ -96,7 +124,7 @@ export async function prepareAgentLaunch(input) {
     const sandboxName = runner === "sdx" && input.definition.sandbox !== undefined
         ? sandboxNameFor({ agent: input.definition.sandbox.agent })
         : undefined;
-    return { runner, sandboxName, ensureReady };
+    return { runner, sandboxName, workspaceKind, ensureReady };
 }
 async function alreadyReady() {
     await Promise.resolve();

package/dist/lib/launchCommand.d.ts

@@ -41,6 +41,11 @@ declare const WORKER_ENVIRONMENT_NAMES: readonly ["GROUNDCREW_TASK_ID", "GROUNDC
 type WorkerEnvironmentName = (typeof WORKER_ENVIRONMENT_NAMES)[number];
 export type WorkerEnvironment = Readonly<Record<WorkerEnvironmentName, string>>;
 export declare function workerEnvironmentForTask(taskId: string): WorkerEnvironment;
+export interface SafehouseAgentIntegration {
+    addDirsReadOnly: readonly string[];
+    envPass: readonly string[];
+    commandPreludes: readonly string[];
+}
 interface LaunchCommandArguments {
     definition: AgentDefinition;
     promptFile: string;
@@ -115,6 +120,13 @@ interface LaunchCommandArguments {
      * pre-existing behavior). Only consumed by the safehouse wrap.
      */
     safehouseAddDirs?: readonly string[] | undefined;
+    /**
+     * Extra host-terminal integration surface granted only to the Safehouse agent
+     * wrap. The agent may need to execute host shims and reach their sockets
+     * while repo-controlled prepareWorktree hooks should not inherit those paths
+     * or env vars.
+     */
+    safehouseAgentIntegration?: SafehouseAgentIntegration | undefined;
     /**
      * Groundcrew-managed task metadata exposed to the launched worker. Forwarded
      * to the agent process, not the prepareWorktree hook.

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

@@ -1 +1 @@
-{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAcvF;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAgB3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,MAAM,CAMvF;AAsMD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8B9D;AAED,QAAA,MAAM,wBAAwB,YAAI,oBAAoB,EAAE,qBAAqB,CAAU,CAAC;AAExF,KAAK,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAK1E;AAsBD,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACnE;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CAkC7E"}
+{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAcvF;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAgB3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,MAAM,CAMvF;AAsMD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8B9D;AAED,QAAA,MAAM,wBAAwB,YAAI,oBAAoB,EAAE,qBAAqB,CAAU,CAAC;AAExF,KAAK,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAK1E;AAsBD,MAAM,WAAW,yBAAyB;IACxC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACnE;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,yBAAyB,GAAG,SAAS,CAAC;IAClE;;;OAGG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CAkC7E"}

package/dist/lib/launchCommand.js

@@ -381,7 +381,12 @@ function buildUnwrappedHostLaunchCommand(arguments_) {
 function buildSafehouseLaunchCommand(arguments_) {
     const promptDir = path.dirname(arguments_.promptFile);
     const safehouseCommandName = inferAgentCommandName(arguments_.definition.cmd);
-    const { agentCommand, prepareWorktreeCommand } = renderPrepareAndAgentCommand(arguments_);
+    const { agentCommand: rawAgentCommand, prepareWorktreeCommand } = renderPrepareAndAgentCommand(arguments_);
+    const { safehouseAgentIntegration } = arguments_;
+    const agentCommand = [
+        ...(safehouseAgentIntegration?.commandPreludes ?? []),
+        rawAgentCommand,
+    ].join("; ");
     // Split --env-pass per wrap: the prepareWorktree wrap only needs build secrets (so
     // `npm install` etc. can authenticate); the agent wrap only needs the
     // user's preLaunchEnv (build secrets are `unset` on the host between the
@@ -392,14 +397,15 @@ function buildSafehouseLaunchCommand(arguments_) {
     const agentEnvPassFlag = envPassFlag([
         ...(arguments_.definition.preLaunchEnv ?? []),
         ...workerEnvironmentNames(arguments_.workerEnvironment),
+        ...(safehouseAgentIntegration?.envPass ?? []),
     ]);
     // safehouse reads colon-separated paths from `--add-dirs`; both wraps get the
     // same grant so the prepareWorktree hook and the agent can each reach git.
     // Quote the whole value so shell-special chars survive; the trailing space
     // separates it from the next argv token. See `resolveSafehouseAddDirs` for
     // which paths these are and why.
-    const addDirs = arguments_.safehouseAddDirs ?? [];
-    const safehouseAddDirsFlag = addDirs.length === 0 ? "" : `--add-dirs=${shellSingleQuote(addDirs.join(":"))} `;
+    const safehouseAddDirsFlag = safehousePathListFlag("--add-dirs", arguments_.safehouseAddDirs ?? []);
+    const safehouseAgentAddDirsReadOnlyFlag = safehousePathListFlag("--add-dirs-ro", safehouseAgentIntegration?.addDirsReadOnly ?? []);
     const safehouseWrapper = safehouseClearanceWrapperCommand();
     // Defensive shim+promptDir trap: by the time we arm it, `rm -rf <promptDir>`
     // has already run (line below) so the promptDir wipe is a no-op on the happy
@@ -429,9 +435,12 @@ function buildSafehouseLaunchCommand(arguments_) {
     // Running the real launch chain as `sh -c` would make it see `sh`, so use
     // an agent-named symlink to /bin/sh. This preserves per-agent profile
     // selection without enabling every agent profile.
-    `{ ${safehouseWrapper} ${safehouseAddDirsFlag}${agentEnvPassFlag}"$_safehouse_shim" -c ${shellSingleQuote(agentCommand)} sh "$_p"; _safehouse_status=$?; rm -rf "$_safehouse_shim_dir"; trap - EXIT; exit "$_safehouse_status"; }`);
+    `{ ${safehouseWrapper} ${safehouseAddDirsFlag}${safehouseAgentAddDirsReadOnlyFlag}${agentEnvPassFlag}"$_safehouse_shim" -c ${shellSingleQuote(agentCommand)} sh "$_p"; _safehouse_status=$?; rm -rf "$_safehouse_shim_dir"; trap - EXIT; exit "$_safehouse_status"; }`);
     return lines.join(" && ");
 }
+function safehousePathListFlag(flagName, paths) {
+    return paths.length === 0 ? "" : `${flagName}=${shellSingleQuote(paths.join(":"))} `;
+}
 /**
  * Benign baseline env the srt wraps run under (via `env -i`). This is an
  * allowlist on purpose: srt's CLI spawns its child with the *inherited* host

package/dist/lib/taskSource.d.ts

@@ -210,6 +210,19 @@ export declare class RepositoryResolutionError extends Error {
         repositories: readonly string[];
     });
 }
+/**
+ * A task source returned output that groundcrew could not parse — non-JSON
+ * stdout, or JSON that doesn't match the source's contract (e.g. a shell
+ * script's `listTasks` payload missing the required `agent` field). Carries a
+ * user-facing message that names the source and what was wrong.
+ *
+ * Marked deterministic: re-running the same command yields the same bad
+ * output, so the orchestrator's `withRetry` must NOT retry it (retrying only
+ * delays a guaranteed failure behind confusing "Retrying in Ns" lines).
+ */
+export declare class TaskSourceOutputError extends Error {
+    constructor(message: string);
+}
 export declare class AmbiguousTaskError extends Error {
     constructor(arguments_: {
         naturalId: string;

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

@@ -1 +1 @@
-{"version":3,"file":"taskSource.d.ts","sourceRoot":"","sources":["../../src/lib/taskSource.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"taskSource.d.ts","sourceRoot":"","sources":["../../src/lib/taskSource.ts"],"names":[],"mappings":"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"}

package/dist/lib/taskSource.js

@@ -17,6 +17,22 @@ export class RepositoryResolutionError extends Error {
         this.name = "RepositoryResolutionError";
     }
 }
+/**
+ * A task source returned output that groundcrew could not parse — non-JSON
+ * stdout, or JSON that doesn't match the source's contract (e.g. a shell
+ * script's `listTasks` payload missing the required `agent` field). Carries a
+ * user-facing message that names the source and what was wrong.
+ *
+ * Marked deterministic: re-running the same command yields the same bad
+ * output, so the orchestrator's `withRetry` must NOT retry it (retrying only
+ * delays a guaranteed failure behind confusing "Retrying in Ns" lines).
+ */
+export class TaskSourceOutputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TaskSourceOutputError";
+    }
+}
 export class AmbiguousTaskError extends Error {
     constructor(arguments_) {
         const { naturalId, matches } = arguments_;

package/docs/adr/0002-one-task-source-path-linear-is-an-adapter.md

@@ -10,8 +10,8 @@ There is a single path from board state to dispatch: `Source[] → Board → Dis
 
 ## Consequences
 
-- The canonical seam is the `Issue` contract: a source emits `model` and `repository`, or the task is ignored (`isGroundcrewIssue` keys off exactly that). Consumers branch on the canonical `CanonicalStatus` enum, never on a source's native status names.
+- The canonical seam is the `Issue` contract: a source emits `agent` and `repository`, or the task is ignored (`isGroundcrewIssue` keys off exactly that). Consumers branch on the canonical `CanonicalStatus` enum, never on a source's native status names.
 - **Linear-specific** concepts live in the adapter: `agent-*` label parsing, `agent-any` routing, sub-issue/parent detection, assigned-to-viewer + label selection policy.
-- **Canonical** concepts stay in eligibility so every source benefits: blocker classification (sources populate `blockers[]`) and exhausted-model gating (sources pick a `model`).
+- **Canonical** concepts stay in eligibility so every source benefits: blocker classification (sources populate `blockers[]`) and exhausted-agent gating (sources pick an `agent`).
 - This was a pure internal refactor with no user-visible change — Linear keeps working identically — so it carried no migration cost and landed before the breaking v5 cuts.
 - Changing the Linear selection mechanism (assigned + labeled) is now an adapter-local change that does not touch the engine.

package/docs/commands.md

@@ -7,7 +7,7 @@
 ```bash
 crew task list
 crew task list --source todo --status todo --unblocked
-crew task list --agent codex --repo ClipboardHealth/api --json
+crew task list --agent claude-fable --repo ClipboardHealth/api --json
 ```
 
 `crew task get <task-id>` prints one normalized task. Canonical IDs such as `todo:GC-20260608-001` route directly to the named source. Natural IDs can be resolved with `--source <name>` or, when unique, by searching all configured sources. If more than one source matches, the command fails and asks for a canonical ID or `--source`.
@@ -23,7 +23,7 @@ crew task get todo:GC-20260608-001 --prompt
 ```bash
 crew task create "Fix cancellation retry race" \
   --source todo \
-  --agent codex \
+  --agent claude-fable \
   --repo ClipboardHealth/api \
   --project marketplace \
   --context backend \
@@ -35,7 +35,7 @@ Linear creation creates a Todo issue assigned to the current Linear API viewer,
 ```bash
 crew task create "Fix cancellation retry race" \
   --source linear \
-  --agent codex \
+  --agent claude-fable \
   --team ENG \
   --repo ClipboardHealth/api \
   --description "Investigate retry handling."
@@ -70,7 +70,7 @@ done and schedules the next `status:todo` recurrence itself.
 ```bash
 crew task create "Run flaky triage sweep" \
   --source todo \
-  --agent codex \
+  --agent claude-fable \
   --repo ClipboardHealth/groundcrew \
   --id flaky-triage-1 \
   --rec 2h \

package/docs/configuration.md

@@ -92,13 +92,40 @@ The "Loaded config from ..." line at startup tells you which config won.
 
 ## Agent Label Routing
 
-- `agent-claude`, `agent-codex`, `agent-<name>` routes to that enabled agent.
+- `agent-claude`, `agent-codex`, `agent-<name>` routes to that enabled launch profile.
 - `agent-any` routes to the agent with the most session headroom, after skipping agents over their session limit or weekly paced budget.
 - Unknown `agent-<name>` falls back to `agents.default`.
 - A built-in `agent-<name>` label whose agent is not enabled falls back to `agents.default` with a warning.
 - No `agent-*` label is ignored by `crew run`. Dispatch on demand with `crew start <TASK>`, which falls back to `agents.default`.
 - Todo tasks blocked by non-terminal blockers are skipped until their blockers reach a terminal status.
 
+Agent names are launch profiles, not just vendor names. To choose a model per
+task, define model-specific profiles and route tasks to them:
+
+```ts
+export default {
+  agents: {
+    default: "claude-fable",
+    definitions: {
+      "claude-fable": {
+        cmd: "claude --model claude-fable-5 --permission-mode auto",
+        color: "#C15F3C",
+        usage: { codexbar: { provider: "claude" } },
+      },
+      "claude-opus": {
+        cmd: "claude --model claude-opus-4-8 --permission-mode auto",
+        color: "#8A4FFF",
+        usage: { codexbar: { provider: "claude" } },
+      },
+    },
+  },
+};
+```
+
+Use the same profile name in every source: Linear label `agent-claude-fable`,
+todo.txt token `agent:claude-fable`, shell JSON `"agent": "claude-fable"`,
+or `crew task create ... --agent claude-fable`.
+
 Status classification uses Linear's default status names `In Progress` and `In Review` to disambiguate multiple `started` workflow states. Statuses that do not match those names fall back to Linear's workflow `state.type` (`unstarted`, `started`, `completed`, `canceled`, `duplicate`), so broad lifecycle classification still works without configuration. Parent issues with children are ignored; sub-issues are the work items.
 
 If your Linear workflow uses different names, explicitly declare the built-in Linear source and override only the names you need:
@@ -167,9 +194,9 @@ export default {
 
 Rules:
 
-- `agents.definitions` is the enabled agent set; `crew doctor` only probes listed agents.
+- `agents.definitions` is the enabled launch profile set; `crew doctor` only probes listed profiles.
 - Built-in entries can be `{}` or partial overrides such as `{ cmd: "..." }`.
-- Custom agent names must provide `cmd` and `color`.
+- Custom launch profile names must provide `cmd` and `color`.
 - `agents.default` must point at an enabled agent.
 - Legacy agent entries like `codex: { disabled: true }` are rejected with migration guidance; remove unwanted entries instead.
 
@@ -244,9 +271,9 @@ and hook contract.
 | `orchestrator.pollIntervalMilliseconds`  | `120_000`            | Poll interval in `--watch` mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `orchestrator.sessionLimitPercentage`    | `85`                 | Number in `(0, 100]`. An agent whose codexbar session window exceeds this percentage is skipped that tick. Agents are also skipped when codexbar reports weekly usage over the current weekly paced budget.                                                                                                                                                                                                                                                                                                                 |
 | `agents.default`                         | `"claude"`           | Tiebreak for `agent-any` resolution and fallback for explicit but unknown `agent-*` labels. Also used by `crew start <TASK>` for unlabeled tasks. `crew run` ignores unlabeled tasks and does not apply this default. Must exist in `agents.definitions`. If you enable only `codex`, set `default: "codex"`.                                                                                                                                                                                                               |
-| `agents.definitions`                     | **required**         | Enabled agent set. Built-in keys (`claude`, `codex`) can use `{}` to opt into the shipped preset. Custom agent names must provide `cmd` and `color`.                                                                                                                                                                                                                                                                                                                                                                        |
-| `agents.definitions.<name>.cmd`          | preset for built-ins | Shell command launched for the agent. Required for custom agents. 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.                                                                                                                                                                                                                                                     |
-| `agents.definitions.<name>.color`        | preset for built-ins | Color for the workspace status pill (cmux only; tmux and zellij silently drop it). Required for custom agents.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `agents.definitions`                     | **required**         | Enabled launch profile set. Built-in keys (`claude`, `codex`) can use `{}` to opt into the shipped preset. Custom profile names must provide `cmd` and `color`; use custom profiles such as `claude-fable` and `claude-opus` to select model-specific commands per task.                                                                                                                                                                                                                                                    |
+| `agents.definitions.<name>.cmd`          | preset for built-ins | Shell command launched for the agent. Required for custom profiles. 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.                                                                                                                                                                                                                                                   |
+| `agents.definitions.<name>.color`        | preset for built-ins | Color for the workspace status pill (cmux only; tmux and zellij silently drop it). Required for custom profiles.                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `agents.definitions.<name>.usage`        | preset for built-ins | If set, codexbar usage is fetched for this agent and gated by `sessionLimitPercentage` plus the weekly paced budget when codexbar exposes a weekly window. When `usage.codexbar.source` is omitted, groundcrew uses `oauth` for Codex/Claude on macOS, `auto` for other macOS providers, and `cli` elsewhere. Set to `{ disabled: true }` to disable usage gating while keeping the agent enabled.                                                                                                                          |
 | `agents.definitions.<name>.sandbox`      | optional             | Docker Sandboxes binding for the agent. Required at launch when `local.runner` resolves to `sdx`. Field: `agent` (required sbx agent name). Groundcrew assumes the `groundcrew-<agent>` sandbox already exists.                                                                                                                                                                                                                                                                                                             |
 | `agents.definitions.<name>.preLaunch`    | optional             | Host-only shell snippet run before the agent exec and outside Safehouse/sdx. Exports survive into the launch shell; under the default `safehouse` runner they are only forwarded to the agent when listed via `preLaunchEnv` or when `cmd` includes its own `safehouse --env-pass=NAMES`. `{{worktree}}` is substituted. A non-zero exit aborts launch. Not supported when `local.runner` resolves to `sdx` in v1.                                                                                                          |

package/docs/task-sources.md

@@ -53,7 +53,7 @@ state is expected or explicitly allowed.
     "description": "Task body",
     "status": "todo",
     "repository": "your-org/your-repo",
-    "model": "claude",
+    "agent": "claude-fable",
     "assignee": "Alice",
     "updatedAt": "2026-05-22T15:00:00Z",
     "blockers": [{ "id": "JIRA-122", "title": "Schema migration", "status": "done" }],
@@ -63,7 +63,7 @@ state is expected or explicitly allowed.
 ]
 ```
 
-Allowed `status` values are `todo`, `in-progress`, `in-review`, `done`, and `other`. Use `null` for `repository` or `model` when a task should not be groundcrew-eligible. `hasMoreBlockers` is optional and defaults to `false`; `sourceRef` is opaque data that groundcrew passes back to your writeback command.
+Allowed `status` values are `todo`, `in-progress`, `in-review`, `done`, and `other`. Omit `repository` or `agent` when a task should not be groundcrew-eligible. `hasMoreBlockers` is optional and defaults to `false`; `sourceRef` is opaque data that groundcrew passes back to your writeback command.
 
 ## Todo.txt
 
@@ -89,7 +89,7 @@ Creating a todo task appends a line with `status:todo` as the final meaningful t
 ```bash
 crew task create "Fix cancellation retry race" \
   --source todo \
-  --agent codex \
+  --agent claude-fable \
   --repo ClipboardHealth/api \
   --project marketplace \
   --context backend \
@@ -97,7 +97,7 @@ crew task create "Fix cancellation retry race" \
 ```
 
 ```txt
-Fix cancellation retry race +marketplace @backend id:GC-20260608-001 repo:ClipboardHealth/api agent:codex status:todo
+Fix cancellation retry race +marketplace @backend id:GC-20260608-001 repo:ClipboardHealth/api agent:claude-fable status:todo
 ```
 
 For hand-written todo lines, a non-empty title is enough prompt text when `.tasks/<id>.md` is absent. Omit `agent:` to default to `agent:any`:
@@ -126,7 +126,7 @@ export default {
 ```bash
 crew task create "Fix cancellation retry race" \
   --source linear \
-  --agent codex \
+  --agent claude-fable \
   --repo ClipboardHealth/api \
   --description "Investigate retry handling."
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.35.0",
+  "version": "4.36.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",
@@ -69,7 +69,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.52",
-    "@clipboard-health/clearance": "1.2.0",
+    "@clipboard-health/clearance": "1.3.2",
     "@linear/sdk": "86.0.0",
     "cosmiconfig": "9.0.1",
     "tslib": "2.8.1",
@@ -82,12 +82,12 @@
     "@tsconfig/node24": "24.0.4",
     "@tsconfig/strictest": "2.0.8",
     "@types/node": "25.9.2",
-    "@typescript/native-preview": "7.0.0-dev.20260606.1",
+    "@typescript/native-preview": "7.0.0-dev.20260608.1",
     "@vitest/coverage-v8": "4.1.8",
     "cspell": "10.0.1",
     "dependency-cruiser": "17.4.3",
     "husky": "9.1.7",
-    "jscpd": "4.2.4",
+    "jscpd": "5.0.5",
     "knip": "6.15.0",
     "lint-staged": "17.0.7",
     "markdownlint-cli2": "0.22.1",