@clipboard-health/groundcrew 4.31.0 → 4.32.0

package/README.md

@@ -50,8 +50,8 @@ crew init --global --project-dir ~/dev --repo OWNER/REPO --agent claude
 
 # 3. Run the clone commands printed by `crew init`.
 
-# 4. Set the clearance egress proxy allowlist.
-export CLEARANCE_ALLOW_HOSTS_FILES="$(npm root -g)/@clipboard-health/groundcrew/clearance-allow-hosts"
+# 4. Safehouse runs use groundcrew's bundled clearance allowlist automatically.
+#    Add extra hosts later via CLEARANCE_ALLOW_HOSTS or CLEARANCE_ALLOW_HOSTS_FILES.
 
 # 5. Using Linear? Export your API key. (Jira and other trackers: see Task Pickup.)
 export GROUNDCREW_LINEAR_API_KEY="lin_api_..."

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;AA+KH,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;AAyLH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAmF/C"}

package/dist/commands/doctor.js

@@ -7,6 +7,7 @@ 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 { gatedAgents } from "../lib/usage.js";
 import { errorMessage, writeOutput } from "../lib/util.js";
@@ -78,12 +79,14 @@ function checkDir(path, label) {
  * the executable name (first non-flag token), and any subsequent
  * non-flag, non-flag-value token until a flag is hit. Flag tokens are
  * dropped along with the token immediately following them (treated as
- * the flag's value).
+ * the flag's value). `env VAR=val` assignments are skipped (they are not
+ * binaries), so the wrapped command is still found.
  *
  * Examples:
  *   "safehouse claude --permission-mode auto" → ["safehouse", "claude"]
  *   "claude"                                  → ["claude"]
  *   "node --inspect script.ts"                → ["node"]  (script.ts skipped — flag value)
+ *   "env GIT_CONFIG_COUNT=1 claude --foo"     → ["env", "claude"]  (assignment skipped)
  */
 function commandTokensToCheck(cmd) {
     const parts = cmd.trim().split(/\s+/);
@@ -101,6 +104,13 @@ function commandTokensToCheck(cmd) {
             index += 2;
             continue;
         }
+        if (isEnvironmentAssignment(token)) {
+            // An `env VAR=val …` prefix: the assignment is not a binary, so don't
+            // probe it on PATH. Mirrors the launch path's inferAgentCommandName,
+            // which skips assignments to find the real agent command.
+            index += 1;
+            continue;
+        }
         result.push(token);
         if (result.length >= MAX_TOKENS_PER_CMD) {
             break;

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

@@ -1 +1 @@
-{"version":3,"file":"agentLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/agentLaunch.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AASrB;;;;;;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;CAClC,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAwBhE;AAED,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,CA+C/B;AAqBD,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":"AAGA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AASrB;;;;;;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;CAClC,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CA0BhE;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,CA+C/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,10 +1,11 @@
 import { ensureClearance } 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 { assertLocalRunnerRequirements, resolveLocalRunner } from "./localRunner.js";
 import { sandboxNameFor } from "./sandboxName.js";
-import { buildAndStageSrtLaunch } from "./srtLaunch.js";
+import { buildAndStageSrtLaunch, resolveGitCommonDir } from "./srtLaunch.js";
 import { debug, sleep } from "./util.js";
 import { workspaces } from "./workspaces.js";
 /**
@@ -35,9 +36,29 @@ export function composeAgentLaunch(input) {
         srtAgentSettingsFile: staged?.agentFile,
         srtSettingsDir: staged?.directory,
         srtAgentConfigDirEnv: staged?.agentConfigDirEnv,
+        safehouseAddDirs: input.runner === "safehouse" ? resolveSafehouseAddDirs(input.worktreeDir) : undefined,
     });
     return { launchCommand, srtSettingsDir: staged?.directory };
 }
+/**
+ * Filesystem paths the safehouse sandbox must be granted (read/write) beyond
+ * its automatic cwd grant, so git works for every worktree shape:
+ *
+ * - `worktreeDir` — the checkout root. A `workdir` subproject cwd's into a
+ *   subdir, so without this the worktree-root `.git` gitfile is unreachable.
+ * - the **git common dir** — resolved from the worktree itself (not assumed to
+ *   be `<projectDir>/<repo>/.git`), so a scripted/sparse-checkout worktree
+ *   whose store lives outside the worktree tree (e.g. graft's `~/carrot/.git`)
+ *   gets git access. This is the path the bare cwd grant fundamentally cannot
+ *   cover, and the reason this resolution exists.
+ * Gated to the safehouse runner at the call site (srt fences its own equivalent
+ * surface — worktree root + git common dir — through its settings file; sdx/none
+ * don't use it). Deduped defensively in case git resolves either path to the
+ * same directory in an unusual checkout shape.
+ */
+function resolveSafehouseAddDirs(worktreeDir) {
+    return [...new Set([worktreeDir, resolveGitCommonDir(worktreeDir)])];
+}
 export async function prepareAgentLaunch(input) {
     const host = await detectHostCapabilities(input.signal);
     const runner = resolveLocalRunner(input.config.local.runner, host);
@@ -77,6 +98,9 @@ async function alreadyReady() {
 }
 async function ensureSafehouseClearance(signal) {
     await ensureClearance({
+        envOverrides: {
+            CLEARANCE_ALLOW_HOSTS_FILES: clearanceAllowHostsFilesFromEnvironment(),
+        },
         logger: debug,
         ...(signal === undefined
             ? {}

package/dist/lib/clearanceAllowlist.d.ts

@@ -0,0 +1,8 @@
+interface ClearanceAllowHostsFilesInput {
+    defaultFile?: string | undefined;
+    existingFiles?: string | undefined;
+}
+export declare function clearanceAllowHostsFilesValue(input?: ClearanceAllowHostsFilesInput): string;
+export declare function clearanceAllowHostsFilesFromEnvironment(): string;
+export {};
+//# sourceMappingURL=clearanceAllowlist.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clearanceAllowlist.d.ts","sourceRoot":"","sources":["../../src/lib/clearanceAllowlist.ts"],"names":[],"mappings":"AAOA,UAAU,6BAA6B;IACrC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAMD,wBAAgB,6BAA6B,CAAC,KAAK,GAAE,6BAAkC,GAAG,MAAM,CAa/F;AAED,wBAAgB,uCAAuC,IAAI,MAAM,CAIhE"}

package/dist/lib/clearanceAllowlist.js

@@ -0,0 +1,26 @@
+import path from "node:path";
+import { splitPathList } from "./pathList.js";
+import { readEnvironmentVariable } from "./util.js";
+const CLEARANCE_ALLOW_HOSTS_FILES = "CLEARANCE_ALLOW_HOSTS_FILES";
+function groundcrewClearanceAllowHostsFile() {
+    return path.resolve(import.meta.dirname, "..", "..", "clearance-allow-hosts");
+}
+export function clearanceAllowHostsFilesValue(input = {}) {
+    const defaultFile = input.defaultFile ?? groundcrewClearanceAllowHostsFile();
+    const files = [defaultFile, ...splitPathList(input.existingFiles)];
+    const seen = new Set();
+    const uniqueFiles = [];
+    for (const file of files) {
+        if (seen.has(file)) {
+            continue;
+        }
+        seen.add(file);
+        uniqueFiles.push(file);
+    }
+    return uniqueFiles.join(path.delimiter);
+}
+export function clearanceAllowHostsFilesFromEnvironment() {
+    return clearanceAllowHostsFilesValue({
+        existingFiles: readEnvironmentVariable(CLEARANCE_ALLOW_HOSTS_FILES),
+    });
+}

package/dist/lib/clearanceHosts.js

@@ -14,7 +14,7 @@
  * validates.
  */
 import { readFileSync } from "node:fs";
-import path from "node:path";
+import { splitPathList } from "./pathList.js";
 import { debug } from "./util.js";
 /**
  * Parse and validate clearance allow-host sources into a de-duplicated list of
@@ -51,15 +51,6 @@ export function collectAllowedDomains(input) {
     }
     return domains;
 }
-function splitPathList(value) {
-    if (value === undefined || value.length === 0) {
-        return [];
-    }
-    return value
-        .split(path.delimiter)
-        .map((entry) => entry.trim())
-        .filter((entry) => entry.length > 0);
-}
 /**
  * Split a host source into candidate tokens. Handles env-style
  * comma/whitespace separators and file-style newline lists with `#` comments

package/dist/lib/launchCommand.d.ts

@@ -30,6 +30,7 @@ export declare function resolveSrtBinPath(baseUrl?: string): string;
 export declare function srtBinEntry(manifest: {
     bin?: string | Record<string, string>;
 }): string;
+export declare function isEnvironmentAssignment(token: string): boolean;
 /**
  * Infer the agent's command basename from a agent `cmd` (skipping a leading
  * `env`/`KEY=val` prefix). Safehouse uses it to pick the matching `.sb`
@@ -102,6 +103,14 @@ interface LaunchCommandArguments {
         name: string;
         value: string;
     } | undefined;
+    /**
+     * Extra filesystem paths granted read/write to the safehouse sandbox via
+     * `--add-dirs`, beyond safehouse's automatic cwd grant. Resolved (and deduped)
+     * by `composeAgentLaunch`'s `resolveSafehouseAddDirs` — see there for which
+     * paths and why git needs them. Empty/undefined → no `--add-dirs` flag (the
+     * pre-existing behavior). Only consumed by the safehouse wrap.
+     */
+    safehouseAddDirs?: readonly string[] | undefined;
 }
 /**
  * Build the shell command that runs inside the workspace. The prompt is

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;AAGrB,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;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8B9D;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;CACpE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CA6B7E"}
+{"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,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;CAClD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CA6B7E"}

package/dist/lib/launchCommand.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { BUILD_SECRET_NAMES, hasPreLaunchEnv, } from "./config.js";
+import { clearanceAllowHostsFilesFromEnvironment } from "./clearanceAllowlist.js";
 import { shellSingleQuote } from "./shell.js";
 export { shellSingleQuote } from "./shell.js";
 /**
@@ -100,6 +101,9 @@ function unsetEnvironmentLine(names) {
 function unsetSecretsLine() {
     return unsetEnvironmentLine(BUILD_SECRET_NAMES);
 }
+function safehouseClearanceWrapperCommand() {
+    return `CLEARANCE_ALLOW_HOSTS_FILES=${shellSingleQuote(clearanceAllowHostsFilesFromEnvironment())} ${shellSingleQuote(SAFEHOUSE_CLEARANCE_WRAPPER_PATH)}`;
+}
 function trapCleanupLine(promptDir) {
     const cleanupCmd = `rm -rf ${shellSingleQuote(promptDir)}`;
     return `trap ${shellSingleQuote(cleanupCmd)} EXIT`;
@@ -209,7 +213,7 @@ function tokenizeShellPrefix(command) {
     }
     return tokens;
 }
-function isEnvironmentAssignment(token) {
+export function isEnvironmentAssignment(token) {
     return /^[A-Za-z_][A-Za-z0-9_]*=/.test(token);
 }
 /**
@@ -363,7 +367,14 @@ function buildSafehouseLaunchCommand(arguments_) {
     const prepareWorktreeEnvPassFlag = arguments_.secretsFile === undefined ? "" : `--env-pass=${BUILD_SECRET_NAMES.join(",")} `;
     const preLaunchEnvNames = arguments_.definition.preLaunchEnv ?? [];
     const agentEnvPassFlag = preLaunchEnvNames.length === 0 ? "" : `--env-pass=${preLaunchEnvNames.join(",")} `;
-    const safehouseWrapper = shellSingleQuote(SAFEHOUSE_CLEARANCE_WRAPPER_PATH);
+    // 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 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
     // path. Keeps the failure-window between shim creation and the explicit
@@ -382,7 +393,7 @@ function buildSafehouseLaunchCommand(arguments_) {
         secretsFile: arguments_.secretsFile,
     }));
     if (prepareWorktreeCommand !== undefined) {
-        lines.push(`${safehouseWrapper} ${prepareWorktreeEnvPassFlag}sh -c ${shellSingleQuote(prepareWorktreeCommand)}`);
+        lines.push(`${safehouseWrapper} ${safehouseAddDirsFlag}${prepareWorktreeEnvPassFlag}sh -c ${shellSingleQuote(prepareWorktreeCommand)}`);
     }
     if (arguments_.secretsFile !== undefined) {
         lines.push(unsetSecretsLine());
@@ -392,7 +403,7 @@ 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} ${agentEnvPassFlag}"$_safehouse_shim" -c ${shellSingleQuote(agentCommand)} sh "$_p"; _safehouse_status=$?; rm -rf "$_safehouse_shim_dir"; trap - EXIT; exit "$_safehouse_status"; }`);
+    `{ ${safehouseWrapper} ${safehouseAddDirsFlag}${agentEnvPassFlag}"$_safehouse_shim" -c ${shellSingleQuote(agentCommand)} sh "$_p"; _safehouse_status=$?; rm -rf "$_safehouse_shim_dir"; trap - EXIT; exit "$_safehouse_status"; }`);
     return lines.join(" && ");
 }
 /**

package/dist/lib/pathList.d.ts

@@ -0,0 +1,2 @@
+export declare function splitPathList(value: string | undefined): string[];
+//# sourceMappingURL=pathList.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pathList.d.ts","sourceRoot":"","sources":["../../src/lib/pathList.ts"],"names":[],"mappings":"AAEA,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CASjE"}

package/dist/lib/pathList.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+export function splitPathList(value) {
+    const paths = [];
+    for (const entry of value?.split(path.delimiter) ?? []) {
+        const pathEntry = entry.trim();
+        if (pathEntry.length > 0) {
+            paths.push(pathEntry);
+        }
+    }
+    return paths;
+}

package/dist/lib/srtLaunch.d.ts

@@ -16,6 +16,18 @@ export interface StagedSrtLaunch {
         value: string;
     };
 }
+/**
+ * Resolve the worktree's real git common dir — the shared `.git` the srt policy
+ * fences off (read-grant + narrow write-allow + write-denies). Derived from the
+ * worktree itself rather than assuming a `<projectDir>/<repo>/.git` clone, so
+ * scripted/sparse-checkout worktrees — whose checkout is owned by an external
+ * provisioner and whose `repo` is just an alias with no clone on disk — get the
+ * correct dir instead of a phantom path that breaks git access and leaves the
+ * real common dir unfenced. For native worktrees this returns the same
+ * `<projectDir>/<repo>/.git` as before. `--path-format=absolute` keeps the path
+ * absolute regardless of git version or cwd.
+ */
+export declare function resolveGitCommonDir(worktreeDir: string): string;
 /**
  * Generate the srt policies for a launch and stage them, plus — for agents that
  * cannot run with a read-only config home (codex) — a relocated, writable

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

@@ -1 +1 @@
-{"version":3,"file":"srtLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/srtLaunch.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKnD,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAuBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,eAAe,CAAC;IAC5B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,eAAe,CA6ClB"}
+{"version":3,"file":"srtLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/srtLaunch.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKnD,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,eAAe,CAAC;IAC5B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,eAAe,CA6ClB"}

package/dist/lib/srtLaunch.js

@@ -1,6 +1,7 @@
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { clearanceAllowHostsFilesFromEnvironment } from "./clearanceAllowlist.js";
 import { collectAllowedDomains } from "./clearanceHosts.js";
 import { runCommand } from "./commandRunner.js";
 import { inferAgentCommandName } from "./launchCommand.js";
@@ -17,7 +18,7 @@ import { readEnvironmentVariable } from "./util.js";
  * `<projectDir>/<repo>/.git` as before. `--path-format=absolute` keeps the path
  * absolute regardless of git version or cwd.
  */
-function resolveGitCommonDir(worktreeDir) {
+export function resolveGitCommonDir(worktreeDir) {
     return runCommand("git", [
         "-C",
         worktreeDir,
@@ -53,7 +54,7 @@ export function buildAndStageSrtLaunch(input) {
         gitCommonDir: resolveGitCommonDir(input.worktreeDir),
         allowedDomains: collectAllowedDomains({
             hosts: readEnvironmentVariable("CLEARANCE_ALLOW_HOSTS"),
-            files: readEnvironmentVariable("CLEARANCE_ALLOW_HOSTS_FILES"),
+            files: clearanceAllowHostsFilesFromEnvironment(),
         }),
     };
     const directory = mkdtempSync(path.join(os.tmpdir(), `groundcrew-srt-${input.task}-`));

package/docs/runners.md

@@ -13,19 +13,21 @@
 
 ## Safehouse Clearance Allowlist
 
-Only applies when `local.runner` resolves to `safehouse`. Groundcrew starts `clearance` on `http://127.0.0.1:19999` and runs the agent through the bundled `safehouse-clearance` wrapper. Clearance refuses to start without an allowlist.
+Only applies when `local.runner` resolves to `safehouse`. Groundcrew starts `clearance` on `http://127.0.0.1:19999` and runs the agent through the bundled `safehouse-clearance` wrapper. Groundcrew automatically points clearance at its shipped starter allowlist, so a fresh install does not need a `CLEARANCE_ALLOW_HOSTS_FILES` export.
 
-Shortest path:
+Groundcrew ships that starter file at `$(npm root -g)/@clipboard-health/groundcrew/clearance-allow-hosts`, covering model APIs, Linear, Notion, Slack, Datadog, GitHub, npm, and common dev tooling.
+
+To add ad hoc hosts for one run, use `CLEARANCE_ALLOW_HOSTS`:
 
 ```bash
 CLEARANCE_ALLOW_HOSTS="api.openai.com,auth.openai.com,api.anthropic.com,mcp.linear.app,api.linear.app" \
 crew run --watch
 ```
 
-Groundcrew ships a starter file covering model APIs, Linear, Notion, Slack, Datadog, GitHub, npm, and common dev tooling at `$(npm root -g)/@clipboard-health/groundcrew/clearance-allow-hosts`. Point clearance at it, optionally with a personal file:
+To keep personal hosts in a file, set `CLEARANCE_ALLOW_HOSTS_FILES` to only the additional files. Groundcrew prepends its shipped file automatically:
 
 ```bash
-CLEARANCE_ALLOW_HOSTS_FILES="$(npm root -g)/@clipboard-health/groundcrew/clearance-allow-hosts:$HOME/.config/clearance/personal-allow-hosts" \
+CLEARANCE_ALLOW_HOSTS_FILES="$HOME/.config/clearance/personal-allow-hosts" \
 crew run --watch
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.31.0",
+  "version": "4.32.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.1.14",
+    "@clipboard-health/clearance": "1.2.0",
     "@linear/sdk": "86.0.0",
     "cosmiconfig": "9.0.1",
     "tslib": "2.8.1",