@clipboard-health/groundcrew 4.30.0 → 4.31.1

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_..."
@@ -145,7 +145,7 @@ There is no `linear` config block. Groundcrew reads `GROUNDCREW_LINEAR_API_KEY`
 
 ## Reference
 
-- [Configuration](./docs/configuration.md): discovery order, repo layout, full config table, prompt customization.
+- [Configuration](./docs/configuration.md): discovery order, repo layout, scripted/sparse-checkout (graft) worktrees, full config table, prompt customization.
 - [Runners](./docs/runners.md): Safehouse, Docker Sandboxes, and the `none` escape hatch.
 - [Credentials](./docs/credentials.md): Linear API keys, 1Password, build secrets, and `preLaunch`.
 - [Prepare worktree hooks](./docs/setup-hooks.md): `.groundcrew/config.json` `hooks.prepareWorktree` for per-repo dependency setup.

package/crew.config.example.ts

@@ -26,6 +26,29 @@ export default {
     // form to point a repo at a different parent directory:
     //   { name: "other-org/other-repo", projectDirOverride: "~/work" }
     knownRepositories: ["your-org/your-repo"],
+    // A knownRepositories entry can also be an object that provisions the
+    // worktree with a custom command instead of `git worktree add` — e.g. a
+    // sparse checkout via `graft`. `repo` is a logical name (task token +
+    // worktree dir basename); the physical clone is the command's concern.
+    // Templates interpolate ${branch} ${dir} ${baseRef} ${repo} ${task}.
+    //
+    //   {
+    //     name: "billing",
+    //     provision: {
+    //       create: "graft new ${branch} billing --from ${baseRef} --dir ${dir}",
+    //       remove: "graft rm ${branch} -f",
+    //     },
+    //     // Optional: run the agent, prepareWorktree hook, and
+    //     // .groundcrew/config.json lookup in this subdirectory of the
+    //     // checkout (relative, no ".."). Use it when the checkout is a
+    //     // monorepo whose project lives in a subdir.
+    //     workdir: "services/billing",
+    //   },
+    //
+    // Set up graft once outside groundcrew:
+    //   graft repo add ~/dev/owner/monorepo
+    //   graft alias add billing services/billing libs/common
+    // `crew doctor` does not parse or validate these shell templates.
   },
   agents: {
     default: "claude",

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;AAuID,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA0Ff;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;AAanE,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAuID,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA2Ef;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}

package/dist/commands/resumeWorkspace.js

@@ -2,14 +2,12 @@ import { fetchResolvedIssue } from "../lib/adapters/linear/fetch.js";
 import { getLinearClient } from "../lib/adapters/linear/client.js";
 import { isLinearEnabled } from "../lib/buildSources.js";
 import { loadConfig } from "../lib/config.js";
-import { openAgentWorkspace, prepareAgentLaunch } from "../lib/agentLaunch.js";
-import { buildLaunchCommand } from "../lib/launchCommand.js";
+import { composeAgentLaunch, openAgentWorkspace, prepareAgentLaunch } from "../lib/agentLaunch.js";
 import { readRunState, recordRunState } from "../lib/runState.js";
-import { buildAndStageSrtLaunch } from "../lib/srtLaunch.js";
 import { removeStagedPrompt, stageBuildSecrets, stagePromptText, stageWorkspaceLaunchCommand, } from "../lib/stagedLaunch.js";
 import { errorMessage, log } from "../lib/util.js";
 import { workspaces } from "../lib/workspaces.js";
-import { worktrees } from "../lib/worktrees.js";
+import { resolveLaunchDir, worktrees } from "../lib/worktrees.js";
 function parseArguments(argv) {
     const [task, ...extras] = argv;
     if (task === undefined || task.length === 0 || extras.length > 0 || task.startsWith("-")) {
@@ -124,50 +122,36 @@ export async function resumeWorkspace(config, options) {
         purpose: "resumes",
     });
     await ensureReady();
+    const worktreeDir = context.worktree.dir;
+    const launchDir = resolveLaunchDir(config, context.repository, worktreeDir);
     const stagedPrompt = stagePromptText({
         prefix: "groundcrew-resume",
         task,
         text: renderResumePrompt(context),
     });
     const secretsFile = stageBuildSecrets(stagedPrompt.directory);
-    // Resume must stage srt settings exactly like setup, or `buildLaunchCommand`
-    // throws under the srt runner — and a relocating agent (codex) needs its
-    // config home re-seeded so it authenticates on the resumed launch.
-    let srtPrepareSettingsFile;
-    let srtAgentSettingsFile;
+    // Resume stages srt settings exactly like setup (a relocating agent such as
+    // codex needs its config home re-seeded to authenticate on the resumed launch).
+    // Composition runs inside the try so a pre-launch failure still cleans up the
+    // staged prompt (and any srt settings) dir.
     let srtSettingsDir;
-    let srtAgentConfigDirEnv;
-    if (runner === "srt") {
-        const staged = buildAndStageSrtLaunch({
-            config,
-            repository: context.repository,
+    try {
+        let launchCommand;
+        ({ launchCommand, srtSettingsDir } = composeAgentLaunch({
+            runner,
             task,
-            worktreeDir: context.worktree.dir,
             definition,
-        });
-        srtPrepareSettingsFile = staged.prepareFile;
-        srtAgentSettingsFile = staged.agentFile;
-        srtSettingsDir = staged.directory;
-        srtAgentConfigDirEnv = staged.agentConfigDirEnv;
-    }
-    const launchCommand = buildLaunchCommand({
-        definition,
-        promptFile: stagedPrompt.file,
-        worktreeDir: context.worktree.dir,
-        secretsFile,
-        runner,
-        sandboxName,
-        srtPrepareSettingsFile,
-        srtAgentSettingsFile,
-        srtSettingsDir,
-        srtAgentConfigDirEnv,
-    });
-    const launchCmd = stageWorkspaceLaunchCommand(stagedPrompt.directory, launchCommand);
-    try {
+            promptFile: stagedPrompt.file,
+            worktreeDir,
+            workingDir: launchDir,
+            secretsFile,
+            sandboxName,
+        }));
+        const launchCmd = stageWorkspaceLaunchCommand(stagedPrompt.directory, launchCommand);
         await openAgentWorkspace({
             config,
             name: task,
-            cwd: context.worktree.dir,
+            cwd: launchDir,
             command: launchCmd,
             agent: context.agent,
             color: definition.color,

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;AAmBnE,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,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,CA0If;AA8ID,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CA4Cf"}
+{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAsBnE,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,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,CA0Hf;AA8ID,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CA4Cf"}

package/dist/commands/setupWorkspace.js

@@ -1,17 +1,15 @@
 import { rmSync } from "node:fs";
 import { loadConfig } from "../lib/config.js";
-import { openAgentWorkspace, prepareAgentLaunch } from "../lib/agentLaunch.js";
+import { composeAgentLaunch, openAgentWorkspace, prepareAgentLaunch } from "../lib/agentLaunch.js";
 import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
-import { buildLaunchCommand } from "../lib/launchCommand.js";
 import { resolvePrepareWorktreeCommand } from "../lib/repositoryHooks.js";
 import { recordRunState } from "../lib/runState.js";
-import { buildAndStageSrtLaunch } from "../lib/srtLaunch.js";
 import { stageBuildSecrets, stagePromptFromTemplate, stageWorkspaceLaunchCommand, } from "../lib/stagedLaunch.js";
 import { naturalIdFromCanonical } from "../lib/taskSource.js";
 import { debug, errorMessage, log, okMark } from "../lib/util.js";
 import { workspaces } from "../lib/workspaces.js";
-import { isWorktreeAlreadyExistsError, worktrees } from "../lib/worktrees.js";
+import { isWorktreeAlreadyExistsError, resolveLaunchDir, worktrees, } from "../lib/worktrees.js";
 function stagePrompt(input) {
     return stagePromptFromTemplate({
         config: input.config,
@@ -53,7 +51,8 @@ export async function setupWorkspace(config, options, runOptions = {}) {
         }
         throw error;
     }
-    const { branchName, dir: launchDir } = created;
+    const { branchName, dir: worktreeDir } = created;
+    const launchDir = resolveLaunchDir(config, repository, worktreeDir);
     const worktreeName = `${repository}-${task}`;
     // Anything that fails after the worktree is on disk must roll it back
     // (the worktree and the just-created branch). `workspaces.open` cleans
@@ -81,35 +80,18 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             defaultHooks: config.defaults.hooks,
         });
         const secretsFile = prepareWorktreeCommand === undefined ? undefined : stageBuildSecrets(promptDir);
-        let srtPrepareSettingsFile;
-        let srtAgentSettingsFile;
-        let srtAgentConfigDirEnv;
-        if (runner === "srt") {
-            const staged = buildAndStageSrtLaunch({
-                config,
-                repository,
-                task,
-                worktreeDir: launchDir,
-                definition,
-            });
-            srtPrepareSettingsFile = staged.prepareFile;
-            srtAgentSettingsFile = staged.agentFile;
-            srtSettingsDir = staged.directory;
-            srtAgentConfigDirEnv = staged.agentConfigDirEnv;
-        }
-        const launchCommand = buildLaunchCommand({
+        const { launchCommand, srtSettingsDir: stagedSrtSettingsDir } = composeAgentLaunch({
+            runner,
+            task,
             definition,
             promptFile: stagedPrompt.file,
-            worktreeDir: launchDir,
+            worktreeDir,
+            workingDir: launchDir,
             secretsFile,
             prepareWorktreeCommand,
-            runner,
             sandboxName,
-            srtPrepareSettingsFile,
-            srtAgentSettingsFile,
-            srtSettingsDir,
-            srtAgentConfigDirEnv,
         });
+        srtSettingsDir = stagedSrtSettingsDir;
         const launchCmd = stageWorkspaceLaunchCommand(promptDir, launchCommand);
         debug("Opening workspace...");
         await openAgentWorkspace({
@@ -126,7 +108,7 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             task,
             repository,
             agent,
-            worktreeDir: launchDir,
+            worktreeDir,
             branchName,
             workspaceName: task,
             state: "running",
@@ -147,7 +129,7 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             task,
             repository,
             agent,
-            worktreeDir: launchDir,
+            worktreeDir,
             branchName,
             workspaceName: task,
             state: "failed-to-launch",

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { orchestrate, type OrchestratorOptions } from "./commands/orchestrator.t
 export { resumeWorkspace, type ResumeWorkspaceOptions } from "./commands/resumeWorkspace.ts";
 export { setupWorkspace, type SetupWorkspaceOptions } from "./commands/setupWorkspace.ts";
 export { status, type StatusOptions } from "./commands/status.ts";
-export type { Config, HookCommands, AgentDefinition, ResolvedConfig, SourceConfig, } from "./lib/config.ts";
+export type { Config, HookCommands, AgentDefinition, KnownRepository, ResolvedConfig, SourceConfig, } from "./lib/config.ts";
 export { loadConfig } from "./lib/config.ts";
 export { readRunState, recordRunState, removeRunState, runStateDirectory, runStatePath, updateRunState, type RunLifecycleState, type RunState, } from "./lib/runState.ts";
 export { fetchBlockersForTask, fetchInProgressIssueCount, fetchRawLinearIssue, fetchResolvedIssue, isIssueInProgress, isIssueTodo, isTerminalStateType, isTerminalStatusForBlocker, isTerminalStatusForIssue, type RawLinearIssue, } from "./lib/adapters/linear/fetch.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAChG,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EACV,MAAM,EACN,YAAY,EACZ,eAAe,EACf,cAAc,EACd,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,QAAQ,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,KAAK,cAAc,GACpB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,KAAK,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,aAAa,EACb,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,kBAAkB,EAClB,KAAK,OAAO,IAAI,gBAAgB,EAChC,KAAK,UAAU,IAAI,mBAAmB,EACtC,KAAK,eAAe,EACpB,KAAK,eAAe,IAAI,wBAAwB,EAChD,KAAK,KAAK,IAAI,cAAc,EAC5B,iBAAiB,IAAI,0BAA0B,EAC/C,KAAK,UAAU,IAAI,mBAAmB,EACtC,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAChG,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EACV,MAAM,EACN,YAAY,EACZ,eAAe,EACf,eAAe,EACf,cAAc,EACd,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,QAAQ,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,KAAK,cAAc,GACpB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,KAAK,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,aAAa,EACb,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,kBAAkB,EAClB,KAAK,OAAO,IAAI,gBAAgB,EAChC,KAAK,UAAU,IAAI,mBAAmB,EACtC,KAAK,eAAe,EACpB,KAAK,eAAe,IAAI,wBAAwB,EAChD,KAAK,KAAK,IAAI,cAAc,EAC5B,iBAAiB,IAAI,0BAA0B,EAC/C,KAAK,UAAU,IAAI,mBAAmB,EACtC,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC"}

package/dist/lib/agentLaunch.d.ts

@@ -1,4 +1,25 @@
 import { type LocalRunner, type AgentDefinition, type ResolvedConfig } from "./config.ts";
+/**
+ * Stage any srt settings and build the workspace launch command — the assembly
+ * shared verbatim by `setupWorkspace` (fresh runs) and `resumeWorkspace`
+ * (resumes). `worktreeDir` is the checkout root (srt grants + `{{worktree}}`);
+ * `workingDir` is the agent cwd (the worktree root, or its `workdir` subproject).
+ * Returns `srtSettingsDir` so callers can tear it down on a pre-launch failure.
+ */
+export declare function composeAgentLaunch(input: {
+    runner: LocalRunner;
+    task: string;
+    definition: AgentDefinition;
+    promptFile: string;
+    worktreeDir: string;
+    workingDir: string;
+    secretsFile?: string | undefined;
+    prepareWorktreeCommand?: string | undefined;
+    sandboxName?: string | undefined;
+}): {
+    launchCommand: string;
+    srtSettingsDir: string | undefined;
+};
 interface PreparedAgentLaunch {
     runner: LocalRunner;
     sandboxName: string | undefined;

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;AAOrB,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,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;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,44 @@
 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 { debug, sleep } from "./util.js";
 import { workspaces } from "./workspaces.js";
+/**
+ * Stage any srt settings and build the workspace launch command — the assembly
+ * shared verbatim by `setupWorkspace` (fresh runs) and `resumeWorkspace`
+ * (resumes). `worktreeDir` is the checkout root (srt grants + `{{worktree}}`);
+ * `workingDir` is the agent cwd (the worktree root, or its `workdir` subproject).
+ * Returns `srtSettingsDir` so callers can tear it down on a pre-launch failure.
+ */
+export function composeAgentLaunch(input) {
+    const staged = input.runner === "srt"
+        ? buildAndStageSrtLaunch({
+            task: input.task,
+            worktreeDir: input.worktreeDir,
+            definition: input.definition,
+        })
+        : undefined;
+    const launchCommand = buildLaunchCommand({
+        definition: input.definition,
+        promptFile: input.promptFile,
+        worktreeDir: input.worktreeDir,
+        workingDir: input.workingDir,
+        secretsFile: input.secretsFile,
+        prepareWorktreeCommand: input.prepareWorktreeCommand,
+        runner: input.runner,
+        sandboxName: input.sandboxName,
+        srtPrepareSettingsFile: staged?.prepareFile,
+        srtAgentSettingsFile: staged?.agentFile,
+        srtSettingsDir: staged?.directory,
+        srtAgentConfigDirEnv: staged?.agentConfigDirEnv,
+    });
+    return { launchCommand, srtSettingsDir: staged?.directory };
+}
 export async function prepareAgentLaunch(input) {
     const host = await detectHostCapabilities(input.signal);
     const runner = resolveLocalRunner(input.config.local.runner, host);
@@ -44,6 +78,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/config.d.ts

@@ -129,14 +129,42 @@ type UserAgentDefinition = EnabledUserAgentDefinition;
  * Linear's default "In Progress" / "In Review" status names disambiguate
  * `started` workflow states; unmatched statuses fall back to `state.type`.
  */
+/**
+ * Scripted provisioning templates for a repository. Both run via `sh -c` in
+ * place of the native git porcelain: `create` replaces `git worktree add`,
+ * `remove` replaces `git worktree remove`. Grouping them in one object makes the
+ * native/scripted split structural — an entry either has `provision` (scripted)
+ * or it doesn't (native) — and removes the need for a both-or-neither check.
+ */
+export interface ProvisionScripts {
+    /** Shell template run in place of `git worktree add`. */
+    create: string;
+    /** Shell template run in place of `git worktree remove`. */
+    remove: string;
+}
 /**
  * A configured repository. The bare-string form keeps the repo under
  * `workspace.projectDir`; the object form's optional `projectDirOverride`
- * overrides that parent directory so repos can live in more than one place.
+ * overrides that parent directory so repos can live in more than one place. When
+ * a `provision` block is present (a *scripted* entry), groundcrew runs its
+ * templates via `sh -c` in place of `git worktree add`/`remove`; the `name` is
+ * then a logical handle and the physical clone is the template's concern (e.g.
+ * graft's own registry).
  */
 export interface KnownRepository {
+    /** Logical repo name: the token tickets reference and the worktree dir basename. */
     name: string;
+    /** Overrides the parent directory the source repo lives under (defaults to `projectDir`). */
     projectDirOverride?: string;
+    /** Scripted provisioning templates; presence marks this a scripted entry. Mutually exclusive with `projectDirOverride`. */
+    provision?: ProvisionScripts;
+    /**
+     * Project subdirectory within the worktree. When set, the agent cwd, the
+     * `prepareWorktree` hook, and the `.groundcrew/config.json` lookup re-root to
+     * `<worktree>/<workdir>`. The worktree root itself (identity, sandbox access)
+     * is unchanged. Relative, no `..`.
+     */
+    workdir?: string;
 }
 export interface Config {
     /**
@@ -246,8 +274,10 @@ export interface ResolvedConfig {
         projectDir: string;
         /** Resolved worktree root; unset means "use projectDir". */
         worktreeDir?: string;
-        /** Repository names only — the union's `projectDirOverride`s are lifted out. */
+        /** Repository names only — derived; what name-matching consumers read. */
         knownRepositories: string[];
+        /** Normalized full entries carrying any `projectDirOverride`/`provision`. */
+        repositories: KnownRepository[];
         /** name -> resolved parent dir, only for entries that override projectDir. */
         repositoryDirs?: Record<string, string>;
     };

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

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

package/dist/lib/config.js

@@ -466,46 +466,65 @@ function normalizeSources(raw) {
  * per-repo options hang off — add new `KnownRepository` fields here.
  */
 function normalizeKnownRepository(entry, index) {
+    const label = `workspace.knownRepositories[${index}]`;
     if (typeof entry === "string") {
+        requireString(entry, label);
         return { name: entry };
     }
-    requireObject(entry, `workspace.knownRepositories[${index}]`);
-    requireString(entry.name, `workspace.knownRepositories[${index}].name`);
-    if (entry.projectDirOverride === undefined) {
-        return { name: entry.name };
+    requireObject(entry, label);
+    requireString(entry.name, `${label}.name`);
+    const recipe = { name: entry.name };
+    if (entry.projectDirOverride !== undefined) {
+        requireString(entry.projectDirOverride, `${label}.projectDirOverride`);
+        recipe.projectDirOverride = expandHome(entry.projectDirOverride);
+    }
+    if (entry.provision !== undefined) {
+        requireObject(entry.provision, `${label}.provision`);
+        const create = normalizeOptionalString(entry.provision.create, `${label}.provision.create`);
+        const remove = normalizeOptionalString(entry.provision.remove, `${label}.provision.remove`);
+        if (create === undefined || remove === undefined) {
+            fail(`${label}.provision must define both \`create\` and \`remove\` templates`);
+        }
+        recipe.provision = { create, remove };
+    }
+    const workdir = normalizeOptionalString(entry.workdir, `${label}.workdir`);
+    if (workdir !== undefined) {
+        recipe.workdir = workdir;
     }
-    requireString(entry.projectDirOverride, `workspace.knownRepositories[${index}].projectDirOverride`);
-    return { name: entry.name, projectDirOverride: expandHome(entry.projectDirOverride) };
+    return recipe;
 }
 /**
  * Flatten the loose `(string | KnownRepository)[]` union into the strict
  * resolved shape: a `string[]` of names every downstream consumer reads, plus
  * a separate `repositoryDirs` map holding only the entries that override
- * `projectDir`. Types are validated here, at the resolution edge, before any
- * `expandHome` runs (which would otherwise throw a raw TypeError on a
- * non-string `worktreeDir`).
+ * `projectDir`. Types are validated at the resolution edge: every path is
+ * `requireString`-checked before its `expandHome` runs (here for `projectDir`/
+ * `worktreeDir`, and in `normalizeKnownRepository` for `projectDirOverride`),
+ * which would otherwise throw a raw TypeError on a non-string value.
  */
 function normalizeWorkspace(workspace) {
     requireObject(workspace, "workspace");
     requireString(workspace.projectDir, "workspace.projectDir");
+    const entries = workspace.knownRepositories;
+    if (!Array.isArray(entries) || entries.length === 0) {
+        fail("workspace.knownRepositories must be a non-empty array");
+    }
+    const repositories = entries.map((entry, index) => normalizeKnownRepository(entry, index));
     // Track the first index each name was seen at so a duplicate (which would
     // silently overwrite its `projectDirOverride` in `repositoryDirs`) fails
     // loudly instead of resolving order-dependently.
     const seen = new Map();
     const repositoryDirs = {};
-    const entries = Array.isArray(workspace.knownRepositories) ? workspace.knownRepositories : [];
-    entries.forEach((entry, index) => {
-        const { name, projectDirOverride } = normalizeKnownRepository(entry, index);
-        const previous = seen.get(name);
+    repositories.forEach((recipe, index) => {
+        const previous = seen.get(recipe.name);
         if (previous !== undefined) {
-            fail(`workspace.knownRepositories[${index}] duplicates ${JSON.stringify(name)} from workspace.knownRepositories[${previous}]. Configure distinct repository names.`);
+            fail(`workspace.knownRepositories[${index}] duplicates ${JSON.stringify(recipe.name)} from workspace.knownRepositories[${previous}]. Configure distinct repository names.`);
         }
-        seen.set(name, index);
-        if (projectDirOverride !== undefined) {
-            repositoryDirs[name] = projectDirOverride;
+        seen.set(recipe.name, index);
+        if (recipe.projectDirOverride !== undefined) {
+            repositoryDirs[recipe.name] = recipe.projectDirOverride;
         }
     });
-    const names = [...seen.keys()];
     let worktreeDir;
     if (workspace.worktreeDir !== undefined) {
         requireString(workspace.worktreeDir, "workspace.worktreeDir");
@@ -514,7 +533,8 @@ function normalizeWorkspace(workspace) {
     return {
         projectDir: expandHome(workspace.projectDir),
         ...(worktreeDir === undefined ? {} : { worktreeDir }),
-        knownRepositories: names,
+        knownRepositories: repositories.map((recipe) => recipe.name),
+        repositories,
         ...(Object.keys(repositoryDirs).length === 0 ? {} : { repositoryDirs }),
     };
 }
@@ -606,12 +626,19 @@ function validate(config) {
     requireString(config.git.remote, "git.remote");
     requireString(config.git.defaultBranch, "git.defaultBranch");
     requireString(config.workspace.projectDir, "workspace.projectDir");
-    if (!Array.isArray(config.workspace.knownRepositories) ||
-        config.workspace.knownRepositories.length === 0) {
-        fail("workspace.knownRepositories must be a non-empty array");
-    }
-    config.workspace.knownRepositories.forEach((repository, index) => {
-        requireString(repository, `workspace.knownRepositories[${index}]`);
+    config.workspace.repositories.forEach((recipe, index) => {
+        const label = `workspace.knownRepositories[${index}]`;
+        if (recipe.projectDirOverride !== undefined && recipe.provision !== undefined) {
+            fail(`${label}.projectDirOverride cannot be combined with \`provision\`: a scripted entry has no groundcrew-managed clone, so \`projectDirOverride\` would be ignored`);
+        }
+        if (recipe.workdir !== undefined) {
+            if (path.isAbsolute(recipe.workdir)) {
+                fail(`${label}.workdir must be a relative path`);
+            }
+            if (recipe.workdir.split("/").includes("..")) {
+                fail(`${label}.workdir must not contain '..' segments`);
+            }
+        }
     });
     requirePositiveInt(config.orchestrator.maximumInProgress, "orchestrator.maximumInProgress");
     requirePositiveInt(config.orchestrator.pollIntervalMilliseconds, "orchestrator.pollIntervalMilliseconds");

package/dist/lib/launchCommand.d.ts

@@ -40,6 +40,13 @@ interface LaunchCommandArguments {
     definition: AgentDefinition;
     promptFile: string;
     worktreeDir: string;
+    /**
+     * Directory the agent and prepareWorktree hook cwd into (the `cd`/`-w`
+     * target). Equals `worktreeDir` unless the repo recipe sets a `workdir`, in
+     * which case it is the subproject dir. The `{{worktree}}` template and the srt
+     * filesystem grants keep using `worktreeDir` (the whole checkout).
+     */
+    workingDir: string;
     /**
      * Optional path to a `KEY='value'` env file containing build-time
      * secrets (see `BUILD_SECRET_NAMES`). Sourced on the host shell before

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;AAqMD;;;;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;;;;;;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;AA0MD;;;;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"}

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`;
@@ -107,12 +111,13 @@ function trapCleanupLine(promptDir) {
 /**
  * Shared head of every host-shell `&&` chain: arm the `EXIT` trap that wipes
  * `promptDir` (must come before any link that can fail, including the `cd`),
- * then `cd` into the worktree. Kept separate from secret sourcing so the
- * safehouse path can splice `preLaunch` between the `cd` and the secrets
- * source — preLaunch must never see build-time secrets in env.
+ * then `cd` into the working directory (the worktree root, or its `workdir`
+ * subproject). Kept separate from secret sourcing so the safehouse path can
+ * splice `preLaunch` between the `cd` and the secrets source — preLaunch must
+ * never see build-time secrets in env.
  */
 function hostTrapAndCd(arguments_) {
-    return [trapCleanupLine(arguments_.promptDir), `cd ${shellSingleQuote(arguments_.worktreeDir)}`];
+    return [trapCleanupLine(arguments_.promptDir), `cd ${shellSingleQuote(arguments_.workingDir)}`];
 }
 /**
  * Optional source-of-secrets line. Returns `[]` when no `secretsFile` is
@@ -301,7 +306,7 @@ function buildUnwrappedHostLaunchCommand(arguments_) {
         sandboxName: "",
     });
     const lines = [
-        ...hostTrapAndCd({ worktreeDir: arguments_.worktreeDir, promptDir }),
+        ...hostTrapAndCd({ workingDir: arguments_.workingDir, promptDir }),
         ...hostSourceSecrets(arguments_.secretsFile),
     ];
     if (arguments_.prepareWorktreeCommand !== undefined) {
@@ -362,14 +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);
+    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
     // post-wrap cleanup covered for both targets without an unarmed window.
     const shimAndPromptCleanup = `rm -rf "$_safehouse_shim_dir"; rm -rf ${shellSingleQuote(promptDir)}`;
     const shimAndPromptTrap = `trap ${shellSingleQuote(shimAndPromptCleanup)} EXIT`;
-    const lines = hostTrapAndCd({ worktreeDir: arguments_.worktreeDir, promptDir });
+    const lines = hostTrapAndCd({ workingDir: arguments_.workingDir, promptDir });
     // Scrub inherited env before preLaunch (build secrets are copied out of
     // `process.env`, which the launch shell inherits), then source secrets and
     // read the staged prompt. See `hostPreLaunchSourceAndReadPrompt`.
@@ -486,7 +491,7 @@ function buildSrtLaunchCommand(arguments_) {
     const cleanup = `rm -rf ${shellSingleQuote(arguments_.srtSettingsDir)}; rm -rf ${shellSingleQuote(promptDir)}`;
     const lines = [
         `trap ${shellSingleQuote(cleanup)} EXIT`,
-        `cd ${shellSingleQuote(arguments_.worktreeDir)}`,
+        `cd ${shellSingleQuote(arguments_.workingDir)}`,
         ...hostPreLaunchSourceAndReadPrompt({
             definition: arguments_.definition,
             worktreeDir: arguments_.worktreeDir,
@@ -528,6 +533,6 @@ function buildSdxLaunchCommand(arguments_) {
     if (arguments_.secretsFile !== undefined) {
         lines.push(sourceSecretsLine(arguments_.secretsFile));
     }
-    lines.push(`_p=$(cat ${shellSingleQuote(arguments_.promptFile)})`, `rm -rf ${shellSingleQuote(promptDir)}`, `exec sbx exec -it ${sbxEnvironmentFlags}-w ${shellSingleQuote(arguments_.worktreeDir)} ${shellSingleQuote(arguments_.sandboxName)} sh -c ${shellSingleQuote(innerCommand)} sh "$_p"`);
+    lines.push(`_p=$(cat ${shellSingleQuote(arguments_.promptFile)})`, `rm -rf ${shellSingleQuote(promptDir)}`, `exec sbx exec -it ${sbxEnvironmentFlags}-w ${shellSingleQuote(arguments_.workingDir)} ${shellSingleQuote(arguments_.sandboxName)} sh -c ${shellSingleQuote(innerCommand)} sh "$_p"`);
     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

@@ -1,4 +1,4 @@
-import { type AgentDefinition, type ResolvedConfig } from "./config.ts";
+import type { AgentDefinition } from "./config.ts";
 export interface StagedSrtLaunch {
     /** Dedicated temp dir holding the settings files (and any relocated config home). */
     directory: string;
@@ -36,8 +36,6 @@ export interface StagedSrtLaunch {
  * command tears the whole dir down after srt exits.
  */
 export declare function buildAndStageSrtLaunch(input: {
-    config: ResolvedConfig;
-    repository: string;
     task: string;
     worktreeDir: string;
     definition: AgentDefinition;

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

@@ -1 +1 @@
-{"version":3,"file":"srtLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/srtLaunch.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAqB,MAAM,aAAa,CAAC;AAK3F,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;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,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,CA8ClB"}
+{"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;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"}

package/dist/lib/srtLaunch.js

@@ -1,11 +1,32 @@
 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 { repositoryBaseDir } from "./config.js";
+import { runCommand } from "./commandRunner.js";
 import { inferAgentCommandName } from "./launchCommand.js";
 import { agentConfigRelocation, buildSrtSettings } from "./srtPolicy.js";
 import { readEnvironmentVariable } from "./util.js";
+/**
+ * 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.
+ */
+function resolveGitCommonDir(worktreeDir) {
+    return runCommand("git", [
+        "-C",
+        worktreeDir,
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-common-dir",
+    ]);
+}
 /**
  * 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
@@ -28,13 +49,12 @@ import { readEnvironmentVariable } from "./util.js";
 export function buildAndStageSrtLaunch(input) {
     const agent = inferAgentCommandName(input.definition.cmd);
     const homeDir = input.homeDir ?? os.homedir();
-    const repoDir = path.resolve(repositoryBaseDir(input.config, input.repository), input.repository);
     const base = {
         worktreeDir: input.worktreeDir,
-        gitCommonDir: path.join(repoDir, ".git"),
+        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/dist/lib/worktrees.d.ts

@@ -30,6 +30,14 @@ export interface WorktreeSpec {
     task: string;
 }
 declare function branchNameForTask(config: ResolvedConfig, task: string): string;
+/**
+ * The directory the agent and its setup hooks actually run in. Equals the
+ * worktree root unless the repo recipe sets a `workdir`, in which case it is
+ * `<worktreeDir>/<workdir>` — a monorepo subproject inside a sparse checkout.
+ * Pure path resolution; existence is enforced at create time by
+ * assertWorkdirPresent.
+ */
+export declare function resolveLaunchDir(config: ResolvedConfig, repository: string, worktreeDir: string): string;
 export type WorktreeDirtiness = {
     kind: "dirty";
     modified: number;

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

@@ -1 +1 @@
-{"version":3,"file":"worktrees.d.ts","sourceRoot":"","sources":["../../src/lib/worktrees.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,EAAE,KAAK,cAAc,EAAsC,MAAM,aAAa,CAAC;AAItF,OAAO,EAAE,KAAK,cAAc,EAAc,MAAM,iBAAiB,CAAC;AAIlE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAgB,GAAG,EAAE,MAAM,CAAC;IAE5B,YAAmB,GAAG,EAAE,MAAM,EAI7B;CACF;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAEhG;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAeD,iBAAS,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvE;AA4QD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAiHxB,iBAAS,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,EAAE,CAErD;AAED,iBAAS,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAEzE;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,wDAAwD;IACxD,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAuBD,iBAAe,QAAQ,CACrB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAiDzB;AAED,iBAAe,gBAAgB,CAAC,KAAK,EAAE;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE7B;AAED,eAAO,MAAM,SAAS;;;;;;;;CAQrB,CAAC"}
+{"version":3,"file":"worktrees.d.ts","sourceRoot":"","sources":["../../src/lib/worktrees.ts"],"names":[],"mappings":"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"}

package/dist/lib/worktrees.js

@@ -8,11 +8,12 @@
  * the module owns creation, listing, removal, and teardown (workspace-close +
  * worktree-remove paired) so callers don't reach into git directly.
  */
-import { existsSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
 import { userInfo } from "node:os";
 import path from "node:path";
+import { applySubstitutions } from "./adapters/shell/invoke.js";
 import { runCommandAsync } from "./commandRunner.js";
-import { repositoryBaseDir, worktreeBaseDir } from "./config.js";
+import { repositoryBaseDir, worktreeBaseDir, } from "./config.js";
 import { resolveDefaultBranch } from "./defaultBranch.js";
 import { assertPlainTaskId, isPlainTaskId } from "./taskId.js";
 import { debug, errorMessage, isVerbose } from "./util.js";
@@ -43,22 +44,88 @@ function branchPrefix(config) {
 function branchNameForTask(config, task) {
     return `${branchPrefix(config)}-${task}`;
 }
+// Membership in knownRepositories is enforced by recipeFor (called first in
+// basePaths), so this resolves the clone dir for a repo already known to exist
+// in config and only guards against the clone being absent on disk.
 function repoDirFor(config, repository) {
-    if (!config.workspace.knownRepositories.includes(repository)) {
-        throw new Error(`Repository "${repository}" is not in workspace.knownRepositories: ${config.workspace.knownRepositories.join(", ")}`);
-    }
     const repoDir = path.resolve(repositoryBaseDir(config, repository), repository);
     if (!existsSync(repoDir)) {
         throw new Error(`Repository not found: ${repoDir}`);
     }
     return repoDir;
 }
+function recipeFor(config, repository) {
+    const recipe = config.workspace.repositories.find((entry) => entry.name === repository);
+    if (recipe === undefined) {
+        throw new Error(`Repository "${repository}" is not in workspace.knownRepositories: ${config.workspace.knownRepositories.join(", ")}`);
+    }
+    return recipe;
+}
+/**
+ * The directory the agent and its setup hooks actually run in. Equals the
+ * worktree root unless the repo recipe sets a `workdir`, in which case it is
+ * `<worktreeDir>/<workdir>` — a monorepo subproject inside a sparse checkout.
+ * Pure path resolution; existence is enforced at create time by
+ * assertWorkdirPresent.
+ */
+export function resolveLaunchDir(config, repository, worktreeDir) {
+    const recipe = recipeFor(config, repository);
+    return recipe.workdir === undefined ? worktreeDir : path.resolve(worktreeDir, recipe.workdir);
+}
+function assertWorkdirPresent(config, entry) {
+    const recipe = recipeFor(config, entry.repository);
+    if (recipe.workdir === undefined) {
+        return;
+    }
+    const launchDir = path.resolve(entry.dir, recipe.workdir);
+    if (!existsSync(launchDir) || !statSync(launchDir).isDirectory()) {
+        throw new Error(`Configured workdir "${recipe.workdir}" not found in worktree ${entry.dir}; the create template must produce it (looked for ${launchDir}).`);
+    }
+}
+function provisionerSubstitutions(config, arguments_) {
+    return {
+        branch: arguments_.branchName,
+        dir: arguments_.dir,
+        baseRef: `${config.git.remote}/${config.git.defaultBranch}`,
+        repo: arguments_.repository,
+        task: arguments_.task,
+    };
+}
+/**
+ * Runs a provisioner template (`create`/`remove`) with no timeout. Mirrors
+ * runLongGitCommand: under --verbose the child streams live; otherwise it is
+ * captured and discarded on success (failures still carry stderr via the
+ * thrown error).
+ */
+async function runLongShellCommand(command, cwd, signal) {
+    const signalOption = signal === undefined ? {} : { signal };
+    if (isVerbose()) {
+        await runCommandAsync("sh", ["-c", command], {
+            cwd,
+            stdio: "inherit",
+            timeoutMs: 0,
+            ...signalOption,
+        });
+        return;
+    }
+    await runCommandAsync("sh", ["-c", command], {
+        cwd,
+        stdio: "captured",
+        timeoutMs: 0,
+        ...signalOption,
+    });
+}
 function basePaths(config, repository, task) {
     // Tasks must match the same shape the worktree discovery regexes use,
     // so create()/list()/findByTask() agree on what's a valid worktree.
     // This also rejects traversal tokens before they reach path.resolve().
     assertPlainTaskId(task);
-    const repoDir = repoDirFor(config, repository);
+    const recipe = recipeFor(config, repository);
+    // Scripted entries have no source clone — graft owns the checkout — so run
+    // templates with cwd = the worktree root and never resolve a clone dir.
+    const repoDir = recipe.provision === undefined
+        ? repoDirFor(config, repository)
+        : path.resolve(worktreeBaseDir(config));
     const hostWorktreeName = `${repository}-${task}`;
     const hostWorktreeDir = path.resolve(worktreeBaseDir(config), hostWorktreeName);
     return {
@@ -119,6 +186,24 @@ async function deleteBranchBestEffort(arguments_) {
 }
 async function createWorktree(config, spec, signal) {
     const base = basePaths(config, spec.repository, spec.task);
+    const recipe = recipeFor(config, spec.repository);
+    if (recipe.provision !== undefined) {
+        const command = applySubstitutions(recipe.provision.create, provisionerSubstitutions(config, {
+            branchName: base.branchName,
+            dir: base.hostWorktreeDir,
+            task: spec.task,
+            repository: spec.repository,
+        }));
+        debug(`Provisioning worktree ${spec.repository}-${spec.task} via create template...`);
+        await runLongShellCommand(command, base.repoDir, signal);
+        return {
+            repository: spec.repository,
+            task: spec.task,
+            branchName: base.branchName,
+            dir: base.hostWorktreeDir,
+            kind: "host",
+        };
+    }
     const defaultBranch = await resolveDefaultBranch({
         repoDir: base.repoDir,
         remote: config.git.remote,
@@ -188,6 +273,11 @@ function listWorktrees(config) {
     return entries;
 }
 async function removeWorktree(config, entry, options) {
+    const recipe = recipeFor(config, entry.repository);
+    if (recipe.provision !== undefined) {
+        await removeScriptedWorktree(config, entry, recipe.provision.remove, options);
+        return;
+    }
     const repoDir = path.resolve(repositoryBaseDir(config, entry.repository), entry.repository);
     if (existsSync(entry.dir)) {
         debug(`Removing worktree ${entry.dir}${options.force ? " (--force)" : ""}...`);
@@ -223,15 +313,7 @@ async function removeWorktree(config, entry, options) {
                 removeOrphanWorktreeDirectory(config, entry);
             }
             else {
-                const dirtiness = await probeWorktreeDirtiness(entry.dir, options.signal);
-                if (dirtiness.kind === "dirty") {
-                    throw new Error(describeDirtyWorktree({
-                        task: entry.task,
-                        dir: entry.dir,
-                        modified: dirtiness.modified,
-                        untracked: dirtiness.untracked,
-                    }), { cause: error });
-                }
+                const dirtiness = await throwIfWorktreeDirty(entry, options.signal, error);
                 if (dirtiness.kind === "unknown") {
                     const registration = await probeWorktreeRegistration({
                         repoDir,
@@ -259,6 +341,31 @@ async function removeWorktree(config, entry, options) {
         ...signalProperty(options.signal),
     });
 }
+async function removeScriptedWorktree(config, entry, removeTemplate, options) {
+    const worktreeRoot = path.resolve(worktreeBaseDir(config));
+    // A scripted worktree's teardown lives in the remove template (e.g. `graft rm`),
+    // which owns provisioner-side branch/metadata beyond the checkout dir. Run it
+    // even when the dir is already gone so that state is still cleaned up; only the
+    // dirtiness guard — which needs the dir to inspect — is skipped in that case.
+    const worktreeExists = existsSync(entry.dir);
+    if (worktreeExists && !options.force) {
+        // Keep the data-loss guard: a dirty worktree is not removed without --force.
+        // Fail closed when the dirtiness probe can't confirm the worktree is clean,
+        // so the remove template never runs over uncommitted work.
+        const dirtiness = await throwIfWorktreeDirty(entry, options.signal);
+        if (dirtiness.kind !== "clean") {
+            throw new Error(`Could not verify ${entry.dir} is clean; rerun with --force after manual inspection.`);
+        }
+    }
+    const command = applySubstitutions(removeTemplate, provisionerSubstitutions(config, {
+        branchName: entry.branchName,
+        dir: entry.dir,
+        task: entry.task,
+        repository: entry.repository,
+    }));
+    debug(`Removing worktree ${entry.dir} via remove template...`);
+    await runLongShellCommand(command, worktreeRoot, options.signal);
+}
 async function probeWorktreeDirtiness(worktreeDir, signal) {
     let output;
     try {
@@ -285,6 +392,24 @@ async function probeWorktreeDirtiness(worktreeDir, signal) {
     }
     return { kind: "dirty", modified, untracked };
 }
+/**
+ * Probe a worktree and, when it has uncommitted work, throw the data-loss guard
+ * error. Returns the dirtiness so the git-native path can still branch on
+ * `unknown`. `cause` chains the underlying git failure when called from a catch.
+ */
+async function throwIfWorktreeDirty(entry, signal, cause) {
+    const dirtiness = await probeWorktreeDirtiness(entry.dir, signal);
+    if (dirtiness.kind === "dirty") {
+        const message = describeDirtyWorktree({
+            task: entry.task,
+            dir: entry.dir,
+            modified: dirtiness.modified,
+            untracked: dirtiness.untracked,
+        });
+        throw cause === undefined ? new Error(message) : new Error(message, { cause });
+    }
+    return dirtiness;
+}
 function describeDirtyWorktree(arguments_) {
     const { task, dir, modified, untracked } = arguments_;
     const parts = [];
@@ -351,7 +476,15 @@ async function create(config, spec, signal) {
     if (existing !== undefined) {
         throw new WorktreeAlreadyExistsError(existing.dir);
     }
-    return await createWorktree(config, spec, signal);
+    const entry = await createWorktree(config, spec, signal);
+    try {
+        assertWorkdirPresent(config, entry);
+    }
+    catch (error) {
+        await removeWorktree(config, entry, { force: true, ...signalProperty(signal) });
+        throw error;
+    }
+    return entry;
 }
 async function remove(config, entry, options) {
     await removeWorktree(config, entry, {

package/docs/configuration.md

@@ -37,6 +37,42 @@ Clean up existing worktrees before switching it, or temporarily unset
 `worktreeDir` when you need `crew cleanup` to find worktrees created beside the
 repos.
 
+## Scripted Worktrees (Sparse Checkouts)
+
+A `workspace.knownRepositories` entry can be an **object** instead of a string when you want groundcrew to provision the worktree with a custom command — for example a sparse checkout via `graft` — instead of `git worktree add`:
+
+```ts
+workspace: {
+  projectDir: "~/dev/groundcrew",
+  knownRepositories: [
+    "your-org/your-repo",
+    {
+      name: "billing",
+      provision: {
+        create: "graft new ${branch} billing --from ${baseRef} --dir ${dir}",
+        remove: "graft rm ${branch} -f",
+      },
+      workdir: "services/billing",
+    },
+  ],
+},
+```
+
+- **`name`** is a logical name — it is the token matched in task descriptions and the basename of the per-task worktree directory. The physical clone is the command's concern, so several scripted entries can share one underlying clone.
+- **`provision`** marks the entry as scripted. **`provision.create`** runs in place of `git worktree add`; **`provision.remove`** runs in place of `git worktree remove`. Both are required — a `provision` block missing either is rejected at config load. `projectDirOverride` (the per-repo source-directory override for native entries) cannot be combined with `provision`; a scripted entry has no groundcrew-managed clone, so it is rejected at config load.
+- Both templates run on the host via `sh -c` with the working directory set to the worktree root (`worktreeDir`, defaulting to `projectDir`). They interpolate `${branch}`, `${dir}`, `${baseRef}` (`<remote>/<defaultBranch>`), `${repo}`, and `${task}`; each value is shell-quoted.
+- **`workdir`** (optional) is a relative subdirectory of the worktree. When set, the agent's working directory, the `prepareWorktree` hook, and the `.groundcrew/config.json` lookup all re-root to `<worktree>/<workdir>` — use it when a sparse checkout materializes a monorepo whose project lives in a subdirectory (e.g. `uv sync` must run there). The worktree root is unchanged: it is still what create/remove/list operate on, and a sandboxed agent keeps full read/write access to the whole checkout. `workdir` must be relative with no `..` segments; if it is missing after checkout, `crew` fails fast.
+- A dirty scripted worktree is still protected from data loss: `crew cleanup` refuses to run `remove` unless you pass `--force`. Orphan and branch cleanup are delegated to your `remove` template, since groundcrew does not track the scripted clone.
+
+Set `graft` (or whatever tool your templates call) up once, outside groundcrew:
+
+```bash
+graft repo add ~/dev/owner/monorepo
+graft alias add billing services/billing libs/common
+```
+
+`crew doctor` does not parse or validate provisioner templates; if your setup is more than a simple command, put it in a wrapper script and call that from `provision.create` / `provision.remove`.
+
 ## Config Discovery
 
 Resolution order:

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.30.0",
+  "version": "4.31.1",
   "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",