@clipboard-health/groundcrew 4.8.0 → 4.10.0

package/README.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-  Dispatch your ticket backlog to AI coding agents. One git worktree per ticket, sandboxed by default.
+  Dispatch your ticket backlog to local, interactive AI coding agents. One git worktree per ticket, sandboxed by default.
 </p>
 
 <p align="center">
@@ -17,16 +17,22 @@
 </p>
 
 <p align="center">
-  <img alt="Groundcrew picking up tickets and running coding agents in parallel" src="./static/demo.gif" width="800">
+  <a href="./static/demo.tape"><img alt="Groundcrew dispatching tickets into tmux panes with coding agents running in parallel" src="./static/demo.gif" width="800"></a>
+</p>
+
+<p align="center">
+  VHS source: <a href="./static/demo.tape">static/demo.tape</a>.
 </p>
 
 Groundcrew watches assigned tickets, creates isolated worktrees, launches agent CLIs in dedicated terminals, and leaves each ticket's work on its own PR-ready branch. For the backstory, read _[Tickets to pull requests while you sleep](https://www.clipboardworks.com/resources/blog/tickets-to-pull-requests-while-you-sleep)_.
 
 ## Why
 
+- **Local.** Agents run on your machine with your tools, shell, and credentials. That makes them more steerable than remote agents, and easy to nudge when they drift.
+- **Interactive.** Each ticket launches the real `claude` or `codex` CLI in its own terminal pane, not a wrapper that approximates it. Watch any session live and take over when you need to.
 - **One worktree per ticket.** Agents work in parallel without stepping on each other.
+- **Sandboxed by default.** Safehouse or Docker Sandboxes isolate each agent on the host; `none` is an explicit escape hatch.
 - **Pluggable ticket sources.** Linear by default; Jira and local files via [ticket sources](./docs/ticket-sources.md).
-- **Local-first isolation.** Safehouse, Docker Sandboxes, or an explicit `none` escape hatch.
 - **Multi-agent routing.** Ships `claude` and `codex` presets; bring your own CLI in config.
 
 ## Prerequisites
@@ -83,8 +89,7 @@ crew init [--global | --local] [--force] [--dry-run]     # create a crew.config.
           [--runner <auto|safehouse|sdx|none>] [--model <claude|codex>]
 crew doctor                                              # check setup
 crew status [<TICKET>]                                   # inspect current state or one ticket
-crew run                                                 # one-shot orchestration
-crew run --watch                                         # poll forever
+crew run [--watch]                                       # one-shot or --watch forever
 crew start <TICKET>                                      # provision + launch one ticket now
 crew stop <TICKET> [--reason <text>]                     # stop workspace, keep worktree
 crew resume <TICKET>                                     # reopen a paused ticket
@@ -106,15 +111,18 @@ export default {
     projectDir: "~/dev",
     knownRepositories: ["OWNER/REPO"],
   },
-  local: {
-    runner: "auto",
-  },
   models: {
     default: "claude",
     definitions: {
       claude: {},
     },
   },
+  defaults: {
+    hooks: {
+      // No-op placeholder; replace with your repo's setup, e.g. "npm ci".
+      prepareWorktree: "true",
+    },
+  },
 } satisfies Config;
 ```
 
@@ -125,7 +133,7 @@ There is no `linear` config block. Groundcrew reads `GROUNDCREW_LINEAR_API_KEY`
 - [Configuration](./docs/configuration.md): discovery order, repo layout, 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`.
-- [Setup hooks](./docs/setup-hooks.md): `.groundcrew/setup.sh --deps-only` for per-repo dependency setup.
+- [Prepare worktree hooks](./docs/setup-hooks.md): `.groundcrew/config.json` `hooks.prepareWorktree` for per-repo dependency setup.
 - [Ticket sources](./docs/ticket-sources.md): custom shell/Jira/local-plan adapters.
 - [Troubleshooting](./docs/troubleshooting.md): common operational pitfalls and fixes.
 
@@ -143,6 +151,12 @@ node --run crew:op -- run --watch
 
 Both forms discover config through cosmiconfig. Source edits in `src/**` are picked up on the next invocation. Requires Node >= 24.
 
+Regenerate the README demo with VHS:
+
+```bash
+./static/render-demo.sh
+```
+
 ## License
 
 [MIT](./LICENSE)

package/clearance-allow-hosts

@@ -64,8 +64,9 @@ raw.githubusercontent.com
 release-assets.githubusercontent.com
 results-receiver.actions.githubusercontent.com
 
-# npm registry + package website
+# npm/Conda registries + package websites
 api.npmjs.org
+conda.anaconda.org
 registry.npmjs.org
 www.npmjs.com
 
@@ -83,6 +84,9 @@ formulae.brew.sh
 hub.docker.com
 index.docker.io
 json.schemastore.org
+mise-versions.jdx.dev
 nx.dev
+playwright.azureedge.net
+registry.terraform.io
 sourcegraph.com
 vitest.dev

package/crew.config.example.ts

@@ -35,6 +35,15 @@ export default {
       // },
     },
   },
+  // Repo-preparation hook: runs after each worktree is created and before the
+  // agent launches. The default below is a no-op placeholder. Replace it with
+  // your repo's setup, e.g. "npm ci" or "uv sync --dev --frozen". A repo-local
+  // `.groundcrew/config.json` hooks.prepareWorktree overrides this per repo.
+  defaults: {
+    hooks: {
+      prepareWorktree: "true",
+    },
+  },
   // Everything below is optional — defaults shown for reference. Uncomment
   // and edit to override.
   //

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

package/dist/commands/doctor.js

@@ -5,7 +5,7 @@
 import { existsSync, statSync } from "node:fs";
 import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
-import { loadConfig, } from "../lib/config.js";
+import { loadConfigWithSource, } from "../lib/config.js";
 import { detectHostCapabilities, which } from "../lib/host.js";
 import { resolveLocalRunner } from "../lib/localRunner.js";
 import { gatedModels } from "../lib/usage.js";
@@ -15,6 +15,11 @@ import { resolveWorkspaceKind } from "../lib/workspaces.js";
 // catch wrapper + wrapped CLI commands like `safehouse claude --foo`.
 const MAX_TOKENS_PER_CMD = 2;
 const BUILT_IN_MODEL_NAMES = ["claude", "codex"];
+const CONFIG_SOURCE_LABELS = {
+    env: "GROUNDCREW_CONFIG",
+    project: "project",
+    xdg: "global XDG",
+};
 async function checkCmd(cmd, required, hint) {
     const path = await which(cmd);
     const resolvedHint = path ?? hint;
@@ -148,8 +153,10 @@ export async function doctor() {
     writeOutput("=================");
     let config;
     try {
-        config = await loadConfig();
-        writeOutput("[ok] config loaded");
+        const { config: loadedConfig, source } = await loadConfigWithSource();
+        config = loadedConfig;
+        const sourceLabel = CONFIG_SOURCE_LABELS[source.kind];
+        writeOutput(`[ok] config loaded — ${source.filepath} (${sourceLabel})`);
     }
     catch (error) {
         writeOutput(`[--] config: ${errorMessage(error)}`);

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;AAiBnE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CA+Gf;AAyID,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,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;AAkBnE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,CAAC;CACxB;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,CAqHf;AAyID,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CA4Cf"}

package/dist/commands/setupWorkspace.js

@@ -4,6 +4,7 @@ import { 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 { stageBuildSecrets, stagePromptFromTemplate, stageWorkspaceLaunchCommand, } from "../lib/stagedLaunch.js";
 import { naturalIdFromCanonical } from "../lib/ticketSource.js";
@@ -73,12 +74,17 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             workspaceContinuationInstruction: renderWorkspaceContinuationInstruction(accessHint),
         });
         promptDir = stagedPrompt.directory;
-        const secretsFile = stageBuildSecrets(promptDir);
+        const prepareWorktreeCommand = resolvePrepareWorktreeCommand({
+            worktreeDir: launchDir,
+            defaultHooks: config.defaults.hooks,
+        });
+        const secretsFile = prepareWorktreeCommand === undefined ? undefined : stageBuildSecrets(promptDir);
         const launchCommand = buildLaunchCommand({
             definition,
             promptFile: stagedPrompt.file,
             worktreeDir: launchDir,
             secretsFile,
+            prepareWorktreeCommand,
             runner,
             sandboxName,
         });

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, ModelDefinition, ResolvedConfig, SourceConfig } from "./lib/config.ts";
+export type { Config, HookCommands, ModelDefinition, 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 { fetchBlockersForTicket, 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,EAAE,MAAM,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7F,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,sBAAsB,EACtB,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,oBAAoB,EACpB,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,YAAY,GAClB,MAAM,uBAAuB,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,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,sBAAsB,EACtB,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,oBAAoB,EACpB,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,YAAY,GAClB,MAAM,uBAAuB,CAAC"}

package/dist/lib/buildSecrets.d.ts

@@ -1,6 +1,6 @@
 /**
- * Build-time secrets we shuttle into setup phases only. The launched agent
- * process must not inherit these values.
+ * Build-time secrets we shuttle into prepareWorktree phases only. The launched
+ * agent process must not inherit these values.
  */
 export declare const BUILD_SECRET_NAMES: readonly ["NPM_TOKEN", "BUF_TOKEN"];
 //# sourceMappingURL=buildSecrets.d.ts.map

package/dist/lib/buildSecrets.js

@@ -1,5 +1,5 @@
 /**
- * Build-time secrets we shuttle into setup phases only. The launched agent
- * process must not inherit these values.
+ * Build-time secrets we shuttle into prepareWorktree phases only. The launched
+ * agent process must not inherit these values.
  */
 export const BUILD_SECRET_NAMES = ["NPM_TOKEN", "BUF_TOKEN"];

package/dist/lib/config.d.ts

@@ -8,6 +8,9 @@ export { BUILD_SECRET_NAMES } from "./buildSecrets.ts";
  * adapter's `schema.ts` and runs at `buildSources` time, not here.
  */
 export type SourceConfig = LinearAdapterConfig | ShellAdapterConfig;
+export interface HookCommands {
+    prepareWorktree?: string;
+}
 /**
  * Reserved model name. A ticket labeled `agent-any` resolves at runtime
  * to the configured model with the most available session capacity, so
@@ -47,12 +50,6 @@ export declare const LOCAL_RUNNER_SETTINGS: readonly LocalRunnerSetting[];
 export interface SandboxDefinition {
     /** sbx agent name (e.g. "claude", "codex"). */
     agent: string;
-    /**
-     * Setup command run **inside** the sandbox before the agent exec.
-     * Defaults to the shared `.groundcrew/setup.sh --deps-only` convention
-     * (see `launchCommand.ts`) when omitted.
-     */
-    setupCommand?: string;
 }
 export interface ModelDefinition {
     /**
@@ -69,7 +66,7 @@ export interface ModelDefinition {
      * exec'd and **outside** Safehouse/sdx. Use to mint short-lived credentials
      * (e.g. `export SESSION_TOKEN=...`) that the wrapped `cmd` inherits via
      * the process environment. `{{worktree}}` is replaced before launch.
-     * Failures abort launch (unlike deps setup, which logs and continues).
+     * Failures abort launch (unlike prepareWorktree, which logs and continues).
      * Not supported for `local.runner` `sdx` in v1.
      */
     preLaunch?: string;
@@ -148,6 +145,9 @@ export interface Config {
         projectDir: string;
         knownRepositories: string[];
     };
+    defaults?: {
+        hooks?: HookCommands;
+    };
     orchestrator?: {
         maximumInProgress?: number;
         pollIntervalMilliseconds?: number;
@@ -209,6 +209,9 @@ export interface ResolvedConfig {
         projectDir: string;
         knownRepositories: string[];
     };
+    defaults: {
+        hooks: HookCommands;
+    };
     orchestrator: {
         maximumInProgress: number;
         pollIntervalMilliseconds: number;
@@ -238,6 +241,15 @@ export interface ResolvedConfig {
         file: string;
     };
 }
+export type ConfigSourceKind = "env" | "project" | "xdg";
+export interface ConfigSource {
+    kind: ConfigSourceKind;
+    filepath: string;
+}
+export interface LoadedConfig {
+    config: Readonly<ResolvedConfig>;
+    source: Readonly<ConfigSource>;
+}
 /**
  * Single source of truth for "is preLaunchEnv asking us to forward anything?"
  *
@@ -255,5 +267,6 @@ export declare function hasPreLaunchEnv(definition: Pick<ModelDefinition, "preLa
  * not enabled from an arbitrary unknown label like `agent-typo`.
  */
 export declare function isBuiltInModelNotEnabled(config: Pick<ResolvedConfig, "models">, name: string): boolean;
+export declare function loadConfigWithSource(): Promise<Readonly<LoadedConfig>>;
 export declare function loadConfig(): Promise<Readonly<ResolvedConfig>>;
 //# sourceMappingURL=config.d.ts.map

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

@@ -152,6 +152,31 @@ function normalizeOptionalString(value, configKey) {
     }
     return value.trim();
 }
+function normalizeHookCommands(value, configKey) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!isPlainObject(value)) {
+        fail(`${configKey} must be an object`);
+    }
+    const hooks = {};
+    const prepareWorktree = normalizeOptionalString(value["prepareWorktree"], `${configKey}.prepareWorktree`);
+    if (prepareWorktree !== undefined) {
+        hooks.prepareWorktree = prepareWorktree;
+    }
+    return hooks;
+}
+function normalizeDefaults(value) {
+    if (value === undefined) {
+        return { hooks: {} };
+    }
+    if (!isPlainObject(value)) {
+        fail("defaults must be an object");
+    }
+    return {
+        hooks: normalizeHookCommands(value["hooks"], "defaults.hooks"),
+    };
+}
 const ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function validatePreLaunchEnv(modelName, value) {
     const configPath = `models.definitions.${modelName}.preLaunchEnv`;
@@ -163,7 +188,7 @@ function validatePreLaunchEnv(modelName, value) {
             fail(`${configPath}[${index}] must be a POSIX env var name matching ${ENV_VAR_NAME_PATTERN.source} (got ${JSON.stringify(entry)})`);
         }
         // Build secrets are sourced into the host launch shell, forwarded only to
-        // the Safehouse *setup* wrap, and `unset` on the host before the agent
+        // the Safehouse *prepareWorktree* wrap, and `unset` on the host before the agent
         // wrap is exec'd. Listing one here would silently never reach the agent —
         // fail loudly so the operator picks a different name (or removes the
         // entry) instead of debugging a missing env var at runtime.
@@ -220,22 +245,20 @@ function normalizeSandbox(value, configKey) {
     if (Object.hasOwn(value, "kits")) {
         failRemovedConfigKey(`${configKey}.kits`, "Groundcrew no longer creates sdx sandboxes or applies sandbox kits.");
     }
-    const { agent, setupCommand } = value;
+    if (Object.hasOwn(value, "setupCommand")) {
+        fail(`${configKey}.setupCommand is no longer supported: use repo-local \`.groundcrew/config.json\` \`hooks.prepareWorktree\`, or \`defaults.hooks.prepareWorktree\` in crew.config.ts when you need a fallback for repos without their own hook.`);
+    }
+    const { agent } = value;
     requireString(agent, `${configKey}.agent`);
     const trimmedAgent = agent.trim();
     if (trimmedAgent.length === 0) {
         fail(`${configKey}.agent must be a non-empty string (got ${JSON.stringify(agent)})`);
     }
-    const sandbox = { agent: trimmedAgent };
-    const normalizedSetup = normalizeOptionalString(setupCommand, `${configKey}.setupCommand`);
-    if (normalizedSetup !== undefined) {
-        sandbox.setupCommand = normalizedSetup;
-    }
-    return sandbox;
+    return { agent: trimmedAgent };
 }
 function failRemovedConfigKey(configKey, reason) {
     fail(`${configKey} is no longer supported: ${reason} ` +
-        "Provision and manage the sandbox yourself with `sbx` (for example `sbx create --name groundcrew-<agent> <agent> <projectDir>`), then keep only `models.definitions.<model>.sandbox.agent` plus optional `setupCommand` in crew.config.ts.");
+        "Provision and manage the sandbox yourself with `sbx` (for example `sbx create --name groundcrew-<agent> <agent> <projectDir>`), then keep only `models.definitions.<model>.sandbox.agent` in crew.config.ts.");
 }
 function failIfLegacyModelKeys(name, override) {
     if (!isPlainObject(override)) {
@@ -423,6 +446,7 @@ function applyDefaults(user) {
             projectDir: expandHome(user.workspace.projectDir),
             knownRepositories: user.workspace.knownRepositories,
         },
+        defaults: normalizeDefaults(user.defaults),
         orchestrator: { ...DEFAULT_ORCHESTRATOR, ...user.orchestrator },
         models: {
             default: user.models?.default ?? "claude",
@@ -582,26 +606,28 @@ async function discoverUserConfig() {
         if (!existsSync(overridePath)) {
             fail(`GROUNDCREW_CONFIG=${overridePath} not found`);
         }
-        return await loadAt(overridePath);
+        const result = await loadAt(overridePath);
+        return { result, source: { kind: "env", filepath: result.filepath } };
     }
     const project = await explorer.search(process.cwd());
     if (project !== null && project.isEmpty !== true) {
-        return project;
+        return { result: project, source: { kind: "project", filepath: project.filepath } };
     }
     const xdgPath = findXdgConfigFile();
     if (xdgPath !== undefined) {
-        return await loadAt(xdgPath);
+        const result = await loadAt(xdgPath);
+        return { result, source: { kind: "xdg", filepath: result.filepath } };
     }
     // Throw directly so oxlint's `consistent-return` rule sees a
     // terminating statement; it doesn't track `fail()`'s `never` return.
     throw new Error(`groundcrew config: no crew config found. Create crew.config.ts in your project root, or ${xdgConfigPath("groundcrew", "crew.config.ts")}, or set GROUNDCREW_CONFIG.`);
 }
 let cached;
-export async function loadConfig() {
+export async function loadConfigWithSource() {
     if (cached) {
         return cached;
     }
-    const result = await discoverUserConfig();
+    const { result, source } = await discoverUserConfig();
     const { filepath, isEmpty } = result;
     const userConfig = result.config;
     if (isEmpty === true || !isPlainObject(userConfig)) {
@@ -612,6 +638,13 @@ export async function loadConfig() {
     const resolved = applyDefaults(userConfig);
     validate(resolved);
     setLogFile(resolved.logging.file);
-    cached = Object.freeze(resolved);
+    cached = Object.freeze({
+        config: Object.freeze(resolved),
+        source: Object.freeze(source),
+    });
     return cached;
 }
+export async function loadConfig() {
+    const loadedConfig = await loadConfigWithSource();
+    return loadedConfig.config;
+}

package/dist/lib/launchCommand.d.ts

@@ -11,11 +11,6 @@ export { shellSingleQuote } from "./shell.ts";
  *   exercise the catch branch.
  */
 export declare function resolveSafehouseClearancePath(baseUrl?: string): string;
-/**
- * Per-repo setup hook: if `.groundcrew/setup.sh` exists, run it with
- * `--deps-only`; otherwise no-op.
- */
-export declare const SETUP_COMMAND = "if [ -f .groundcrew/setup.sh ]; then bash .groundcrew/setup.sh --deps-only; fi";
 interface LaunchCommandArguments {
     definition: ModelDefinition;
     promptFile: string;
@@ -23,11 +18,17 @@ interface LaunchCommandArguments {
     /**
      * Optional path to a `KEY='value'` env file containing build-time
      * secrets (see `BUILD_SECRET_NAMES`). Sourced on the host shell before
-     * setup; for the sdx runner the names are propagated into the sandbox
+     * prepareWorktree; for the sdx runner the names are propagated into the sandbox
      * via `sbx exec -e KEY`. Always unset before exec'ing the agent so the
      * agent process never inherits them.
      */
     secretsFile?: string | undefined;
+    /**
+     * Optional repo-preparation hook resolved by the caller from the freshly
+     * created worktree's `.groundcrew/config.json`, falling back to
+     * `defaults.hooks.prepareWorktree` from crew.config.ts.
+     */
+    prepareWorktreeCommand?: string | undefined;
     /**
      * Concrete local isolation backend chosen for this launch. Resolved
      * from `config.local.runner` via `resolveLocalRunner` before this

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

@@ -1 +1 @@
-{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAGA,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;;;GAGG;AACH,eAAO,MAAM,aAAa,mFACwD,CAAC;AAyKnF,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,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CA0B7E"}
+{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAGA,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;AA2KD,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;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CA0B7E"}

package/dist/lib/launchCommand.js

@@ -25,11 +25,6 @@ export function resolveSafehouseClearancePath(baseUrl = import.meta.url) {
     return path.resolve(path.dirname(clearancePackageJson), "safehouse", "safehouse-clearance");
 }
 const SAFEHOUSE_CLEARANCE_WRAPPER_PATH = resolveSafehouseClearancePath();
-/**
- * Per-repo setup hook: if `.groundcrew/setup.sh` exists, run it with
- * `--deps-only`; otherwise no-op.
- */
-export const SETUP_COMMAND = "if [ -f .groundcrew/setup.sh ]; then bash .groundcrew/setup.sh --deps-only; fi";
 function renderAgentCommand(arguments_) {
     return arguments_.agentCmd
         .replaceAll("{{worktree}}", shellSingleQuote(arguments_.worktreeDir))
@@ -38,17 +33,17 @@ function renderAgentCommand(arguments_) {
 function renderPreLaunch(preLaunch, worktreeDir) {
     return preLaunch.replaceAll("{{worktree}}", shellSingleQuote(worktreeDir));
 }
-function setupWithStatusReporting(setupCommand) {
+function prepareWorktreeWithStatusReporting(prepareWorktreeCommand) {
     return [
-        setupCommand,
-        "setup_status=$?",
-        'if [ "$setup_status" -ne 0 ]; then echo "groundcrew setup command exited with status $setup_status; continuing to agent." >&2; fi',
+        `(${prepareWorktreeCommand})`,
+        "prepare_status=$?",
+        'if [ "$prepare_status" -ne 0 ]; then echo "groundcrew prepareWorktree hook exited with status $prepare_status; continuing to agent." >&2; fi',
     ].join("; ");
 }
 /**
  * Source a `KEY='value'` file with auto-export so build-time secrets land
- * in the shell env before setup runs. The `-f` guard keeps it a no-op if
- * the file disappeared between staging and launch.
+ * in the shell env before prepareWorktree runs. The `-f` guard keeps it a
+ * no-op if the file disappeared between staging and launch.
  */
 function sourceSecretsLine(secretsFile) {
     return `if [ -f ${shellSingleQuote(secretsFile)} ]; then set -a && . ${shellSingleQuote(secretsFile)} && set +a; fi`;
@@ -196,8 +191,9 @@ export function buildLaunchCommand(arguments_) {
 /**
  * The Safehouse wrap applies only when `runner === "safehouse"` and `cmd` does
  * not already invoke `safehouse` itself. A `safehouse …` cmd owns its own
- * sandbox flags, and we can't splice setup into a command we don't control, so
- * those (and the `none` runner) fall through to the unwrapped host path.
+ * sandbox flags, and we can't splice prepareWorktree into a command we don't
+ * control, so those (and the `none` runner) fall through to the unwrapped host
+ * path.
  */
 function shouldWrapWithSafehouse(arguments_) {
     if (arguments_.runner !== "safehouse") {
@@ -207,8 +203,9 @@ function shouldWrapWithSafehouse(arguments_) {
 }
 /**
  * Unsandboxed host launch (`runner === "none"`, or a `safehouse …` cmd that
- * brings its own wrap). Setup, secret sourcing, and the agent all run on the
- * host shell because there is no groundcrew-managed sandbox to run them inside.
+ * brings its own wrap). prepareWorktree, secret sourcing, and the agent all run
+ * on the host shell because there is no groundcrew-managed sandbox to run them
+ * inside.
  */
 function buildUnwrappedHostLaunchCommand(arguments_) {
     const promptDir = path.dirname(arguments_.promptFile);
@@ -220,8 +217,10 @@ function buildUnwrappedHostLaunchCommand(arguments_) {
     const lines = [
         ...hostTrapAndCd({ worktreeDir: arguments_.worktreeDir, promptDir }),
         ...hostSourceSecrets(arguments_.secretsFile),
-        setupWithStatusReporting(SETUP_COMMAND),
     ];
+    if (arguments_.prepareWorktreeCommand !== undefined) {
+        lines.push(prepareWorktreeWithStatusReporting(arguments_.prepareWorktreeCommand));
+    }
     if (arguments_.secretsFile !== undefined) {
         lines.push(unsetSecretsLine());
     }
@@ -237,9 +236,11 @@ function buildUnwrappedHostLaunchCommand(arguments_) {
 /**
  * Safehouse launch. Two Safehouse wraps, by design:
  *
- *   1. **Setup wrap**: plain `safehouse-clearance ... sh -c '<setup>'`. Runs
- *      `.groundcrew/setup.sh --deps-only` filesystem-isolated and
- *      egress-restricted, **without** inheriting agent-profile grants.
+ *   1. **prepareWorktree wrap**: plain
+ *      `safehouse-clearance ... sh -c '<prepareWorktree>'`. Runs the repo
+ *      preparation hook filesystem-isolated and egress-restricted,
+ *      **without** inheriting agent-profile grants. Omitted entirely when no
+ *      hook command is configured.
  *   2. **Agent wrap**: `safehouse-clearance "$shim" -c '<exec agent>' sh "$_p"`
  *      where `$shim` is a `mktemp`-d symlink to `/bin/sh` named after the
  *      agent (e.g. `claude`). Safehouse selects the matching agent profile
@@ -253,14 +254,14 @@ function buildUnwrappedHostLaunchCommand(arguments_) {
  * from which `stageBuildSecrets` reads them) nor file-sourced values — and keeps
  * stale same-named ambient credentials from being forwarded. `secrets.env` is
  * then sourced into the host launch shell so Safehouse can forward build secrets
- * into the **setup wrap** via `--env-pass=` (Safehouse's `--env=FILE` mode strips
- * them otherwise). After setup returns, `BUILD_SECRET_NAMES` are `unset` again
+ * into the **prepareWorktree wrap** via `--env-pass=` (Safehouse's `--env=FILE` mode strips
+ * them otherwise). After prepareWorktree returns, `BUILD_SECRET_NAMES` are `unset` again
  * on the host so they cannot reach the agent wrap.
  *
  * `--env-pass` composition is split per wrap (deliberate, post PR #128):
- * - Setup wrap forwards build secrets only.
+ * - prepareWorktree wrap forwards build secrets only.
  * - Agent wrap forwards `preLaunchEnv` names only. preLaunch credentials never
- *   reach the profile-neutral setup phase.
+ *   reach the profile-neutral prepare phase.
  */
 function buildSafehouseLaunchCommand(arguments_) {
     const promptDir = path.dirname(arguments_.promptFile);
@@ -270,15 +271,17 @@ function buildSafehouseLaunchCommand(arguments_) {
         worktreeDir: arguments_.worktreeDir,
         sandboxName: "",
     });
-    const setupCommand = setupWithStatusReporting(SETUP_COMMAND);
+    const prepareWorktreeCommand = arguments_.prepareWorktreeCommand === undefined
+        ? undefined
+        : prepareWorktreeWithStatusReporting(arguments_.prepareWorktreeCommand);
     const agentCommand = `exec ${agentCmd} "$@"`;
-    // Split --env-pass per wrap: the setup wrap only needs build secrets (so
+    // Split --env-pass per wrap: the prepareWorktree wrap only needs build secrets (so
     // `npm install` etc. can authenticate); the agent wrap only needs the
     // user's preLaunchEnv (build secrets are `unset` on the host between the
     // two wraps, so forwarding them here would silently no-op). Keeps preLaunch
-    // credentials out of the profile-neutral setup phase — see PR #128.
+    // credentials out of the profile-neutral prepare phase — see PR #128.
     // Trailing space keeps each flag separated from the next argv token.
-    const setupEnvPassFlag = arguments_.secretsFile === undefined ? "" : `--env-pass=${BUILD_SECRET_NAMES.join(",")} `;
+    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);
@@ -298,7 +301,10 @@ function buildSafehouseLaunchCommand(arguments_) {
         lines.push(unsetEnvironmentLine([...BUILD_SECRET_NAMES, ...preLaunchEnvNames]));
         lines.push(renderPreLaunch(arguments_.definition.preLaunch, arguments_.worktreeDir));
     }
-    lines.push(...hostSourceSecrets(arguments_.secretsFile), `_p=$(cat ${shellSingleQuote(arguments_.promptFile)})`, `rm -rf ${shellSingleQuote(promptDir)}`, `${safehouseWrapper} ${setupEnvPassFlag}sh -c ${shellSingleQuote(setupCommand)}`);
+    lines.push(...hostSourceSecrets(arguments_.secretsFile), `_p=$(cat ${shellSingleQuote(arguments_.promptFile)})`, `rm -rf ${shellSingleQuote(promptDir)}`);
+    if (prepareWorktreeCommand !== undefined) {
+        lines.push(`${safehouseWrapper} ${prepareWorktreeEnvPassFlag}sh -c ${shellSingleQuote(prepareWorktreeCommand)}`);
+    }
     if (arguments_.secretsFile !== undefined) {
         lines.push(unsetSecretsLine());
     }
@@ -321,8 +327,10 @@ function buildSdxLaunchCommand(arguments_) {
         worktreeDir: arguments_.worktreeDir,
         sandboxName: arguments_.sandboxName,
     });
-    const setupCommand = arguments_.definition.sandbox.setupCommand ?? SETUP_COMMAND;
-    const innerParts = [setupWithStatusReporting(setupCommand)];
+    const innerParts = [];
+    if (arguments_.prepareWorktreeCommand !== undefined) {
+        innerParts.push(prepareWorktreeWithStatusReporting(arguments_.prepareWorktreeCommand));
+    }
     if (arguments_.secretsFile !== undefined) {
         innerParts.push(unsetSecretsLine());
     }