@clipboard-health/groundcrew 4.8.0 → 4.9.0

package/README.md

@@ -125,7 +125,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.
 

package/crew.config.example.ts

@@ -59,6 +59,14 @@ export default {
   //
   // git: { remote: "origin", defaultBranch: "main" },
   //
+  // // Fallback repo-preparation hook for repos that do not define
+  // // `.groundcrew/config.json` hooks.prepareWorktree. Repo-local config wins.
+  // defaults: {
+  //   hooks: {
+  //     prepareWorktree: "test ! -f package-lock.json || npm ci",
+  //   },
+  // },
+  //
   // orchestrator: {
   //   maximumInProgress: 4,
   //   pollIntervalMilliseconds: 120_000,

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;

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

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());
     }

package/dist/lib/repositoryHooks.d.ts

@@ -0,0 +1,8 @@
+import type { HookCommands } from "./config.ts";
+interface ResolvePrepareWorktreeCommandArguments {
+    worktreeDir: string;
+    defaultHooks: HookCommands;
+}
+export declare function resolvePrepareWorktreeCommand(arguments_: ResolvePrepareWorktreeCommandArguments): string | undefined;
+export {};
+//# sourceMappingURL=repositoryHooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repositoryHooks.d.ts","sourceRoot":"","sources":["../../src/lib/repositoryHooks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,UAAU,sCAAsC;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,sCAAsC,GACjD,MAAM,GAAG,SAAS,CAGpB"}

package/dist/lib/repositoryHooks.js

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+const REPOSITORY_CONFIG_RELATIVE_PATH = ".groundcrew/config.json";
+export function resolvePrepareWorktreeCommand(arguments_) {
+    const repositoryConfig = readRepositoryConfig(arguments_.worktreeDir);
+    return repositoryConfig?.hooks.prepareWorktree ?? arguments_.defaultHooks.prepareWorktree;
+}
+function readRepositoryConfig(worktreeDir) {
+    const configPath = path.join(worktreeDir, REPOSITORY_CONFIG_RELATIVE_PATH);
+    let contents;
+    try {
+        contents = readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return undefined;
+        }
+        throw new Error(`Could not read ${REPOSITORY_CONFIG_RELATIVE_PATH}.`, { cause: error });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch (error) {
+        throw new Error(`${REPOSITORY_CONFIG_RELATIVE_PATH}: expected valid JSON.`, { cause: error });
+    }
+    return normalizeRepositoryConfig(parsed);
+}
+function normalizeRepositoryConfig(value) {
+    if (!isPlainObject(value)) {
+        fail("must be a JSON object");
+    }
+    if (value["version"] !== 1) {
+        fail("version must be 1");
+    }
+    return {
+        hooks: normalizeHookCommands(value["hooks"]),
+    };
+}
+function normalizeHookCommands(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!isPlainObject(value)) {
+        fail("hooks must be an object");
+    }
+    const hooks = {};
+    const prepareWorktree = normalizeOptionalHookCommand(value["prepareWorktree"], "hooks.prepareWorktree");
+    if (prepareWorktree !== undefined) {
+        hooks.prepareWorktree = prepareWorktree;
+    }
+    return hooks;
+}
+function normalizeOptionalHookCommand(value, configKey) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        fail(`${configKey} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function fail(message) {
+    throw new Error(`${REPOSITORY_CONFIG_RELATIVE_PATH}: ${message}`);
+}
+function isFileNotFoundError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/docs/adr/0001-groundcrew-uses-but-does-not-provision-sandboxes.md

@@ -7,7 +7,7 @@ Groundcrew launches agent processes _inside_ an isolation backend (safehouse on
 ## Considered Options
 
 - **Keep the sdx lifecycle commands** — rejected: they reimplement `sbx run`/`sbx exec` setup flows, and every concept they expose (`authRecipes`, `template`, `kits`, `gitDefaults`) is a sandbox concern, not an orchestration concern.
-- **Generalize the launch wrap to a user-supplied template string** — rejected for now: the build-time-secrets and `.groundcrew/setup.sh` plumbing inside the sdx wrap is awkward to express in a user template. Kept a small `safehouse | sdx | none` WRAP enum in core instead.
+- **Generalize the launch wrap to a user-supplied template string** — rejected for now: the build-time-secrets and `prepareWorktree` plumbing inside the sdx wrap is awkward to express in a user template. Kept a small `safehouse | sdx | none` WRAP enum in core instead.
 
 ## Consequences
 

package/docs/configuration.md

@@ -105,6 +105,25 @@ export default {
 
 This keeps package defaults portable while letting your private config reference team-specific statuses, tools, plugins, or review loops.
 
+## Default Hooks
+
+Repo-local `.groundcrew/config.json` is the preferred place for
+`hooks.prepareWorktree`. To provide a fallback for repos that do not define one,
+set `defaults.hooks.prepareWorktree`:
+
+```ts
+export default {
+  defaults: {
+    hooks: {
+      prepareWorktree: "test ! -f package-lock.json || npm ci",
+    },
+  },
+};
+```
+
+See [Prepare Worktree Hooks](./setup-hooks.md) for the repo-local config shape
+and hook contract.
+
 ## Full Reference
 
 | Key                                      | Default              | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -114,6 +133,7 @@ This keeps package defaults portable while letting your private config reference
 | `git.defaultBranch`                      | `"main"`             | Branch fetched from `git.remote` and used as the worktree base.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `workspace.projectDir`                   | **required**         | Parent dir for cloned repos and sibling ticket worktrees.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `workspace.knownRepositories`            | **required**         | Repos searched for in ticket descriptions to infer where work belongs. A ticket labeled for groundcrew (`agent-*`) fails fast when no known repo appears; unlabeled tickets are ignored.                                                                                                                                                                                                                                                                                                                                    |
+| `defaults.hooks.prepareWorktree`         | optional             | Fallback repo-preparation command used only when the worktree does not define `.groundcrew/config.json` `hooks.prepareWorktree`. The hook runs after worktree creation and before the agent starts. Repo-local config wins.                                                                                                                                                                                                                                                                                                 |
 | `orchestrator.maximumInProgress`         | `4`                  | Cap on in-progress tickets at once for this `crew` instance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `orchestrator.pollIntervalMilliseconds`  | `120_000`            | Poll interval in `--watch` mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `orchestrator.sessionLimitPercentage`    | `85`                 | Number in `(0, 100]`. A model whose codexbar session window exceeds this percentage is skipped that tick.                                                                                                                                                                                                                                                                                                                                                                                                                   |
@@ -122,7 +142,7 @@ This keeps package defaults portable while letting your private config reference
 | `models.definitions.<name>.cmd`          | preset for built-ins | Shell command launched for the model. Required for custom models. Runs in the worktree through the resolved `local.runner`. `{{worktree}}` is replaced before launch; `{{sandbox}}` expands to the sbx sandbox name under the sdx runner and an empty string otherwise.                                                                                                                                                                                                                                                     |
 | `models.definitions.<name>.color`        | preset for built-ins | Color for the workspace status pill (cmux only; tmux silently drops it). Required for custom models.                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `models.definitions.<name>.usage`        | preset for built-ins | If set, codexbar usage is fetched for this model and gated by `sessionLimitPercentage`. When `usage.codexbar.source` is omitted, groundcrew uses `oauth` for Codex/Claude on macOS, `auto` for other macOS providers, and `cli` elsewhere. Set to `{ disabled: true }` to disable usage gating while keeping the model enabled.                                                                                                                                                                                             |
-| `models.definitions.<name>.sandbox`      | optional             | Docker Sandboxes binding for the model. Required at launch when `local.runner` resolves to `sdx`. Fields: `agent` (required sbx agent name) and `setupCommand` (override for the inside-sandbox setup script). Groundcrew assumes the `groundcrew-<agent>` sandbox already exists.                                                                                                                                                                                                                                          |
+| `models.definitions.<name>.sandbox`      | optional             | Docker Sandboxes binding for the model. Required at launch when `local.runner` resolves to `sdx`. Field: `agent` (required sbx agent name). Groundcrew assumes the `groundcrew-<agent>` sandbox already exists.                                                                                                                                                                                                                                                                                                             |
 | `models.definitions.<name>.preLaunch`    | optional             | Host-only shell snippet run before the agent exec and outside Safehouse/sdx. Exports survive into the launch shell; under the default `safehouse` runner they are only forwarded to the agent when listed via `preLaunchEnv` or when `cmd` includes its own `safehouse --env-pass=NAMES`. `{{worktree}}` is substituted. A non-zero exit aborts launch. Not supported when `local.runner` resolves to `sdx` in v1.                                                                                                          |
 | `models.definitions.<name>.preLaunchEnv` | optional             | Companion to `preLaunch`: list of env var names to append to groundcrew's `safehouse-clearance` `--env-pass=` flag, so `preLaunch` exports reach the agent without overriding `cmd` and losing the project's egress allowlist. Each entry must match `[A-Za-z_][A-Za-z0-9_]*`. Under `runner: "none"` exports already inherit and `preLaunchEnv` is a no-op. An empty array is a uniform no-op in every runner; a non-empty list is rejected when `cmd` already starts with `safehouse` or when `runner` resolves to `sdx`. |
 | `prompts.initial`                        | unattended template  | First message sent to the agent. Placeholders: `{{ticket}}`, `{{worktree}}`, `{{title}}`, `{{description}}`. Override this from `crew.config.ts` for team-specific statuses, tools, plugins, or review loops.                                                                                                                                                                                                                                                                                                               |

package/docs/credentials.md

@@ -18,7 +18,7 @@ op run --env-file .env.1password -- crew doctor
 
 ## Build-Time Secrets
 
-Groundcrew forwards a small allowlist of build-time secrets from your shell into the setup phase so package installs can authenticate against private registries. The agent process never inherits these values.
+Groundcrew forwards a small allowlist of build-time secrets from your shell into the `prepareWorktree` phase so package installs can authenticate against private registries. The agent process never inherits these values.
 
 Recognized names, defined in [`BUILD_SECRET_NAMES`](../src/lib/buildSecrets.ts):
 
@@ -32,9 +32,9 @@ Set them in the shell you run `crew` from. Anything not in this list is ignored.
 
 For each ticket:
 
-1. If any recognized var is set and non-empty, groundcrew writes `secrets.env` with mode `0600` into the ticket's temp prompt dir as `KEY='value'` lines.
-2. The launch script sources `secrets.env` with `set -a` so the values are exported into the setup phase only. Under `sdx`, they are forwarded into the sandbox via `-e KEY` flags.
-3. After setup completes, the script removes every name in `BUILD_SECRET_NAMES` from the environment and removes the entire prompt dir before executing the agent.
+1. If a `prepareWorktree` hook is configured and any recognized var is set and non-empty, groundcrew writes `secrets.env` with mode `0600` into the ticket's temp prompt dir as `KEY='value'` lines.
+2. The launch script sources `secrets.env` with `set -a` so the values are exported into the `prepareWorktree` phase only. Under `sdx`, they are forwarded into the sandbox via `-e KEY` flags.
+3. After `prepareWorktree` completes, the script removes every name in `BUILD_SECRET_NAMES` from the environment and removes the entire prompt dir before executing the agent.
 
 Net effect: by the time the agent process exists, the values are gone from the environment and the file is gone from disk.
 
@@ -46,8 +46,8 @@ Net effect: by the time the agent process exists, the values are gone from the e
 
 The "preLaunch never sees build secrets" contract is enforced differently per runner:
 
-- `runner: "safehouse"`: `preLaunch` runs immediately after `cd`, before `secrets.env` is sourced into the launch shell. `.groundcrew/setup.sh` then runs inside its own profile-neutral `safehouse-clearance` wrap with `--env-pass=NPM_TOKEN,BUF_TOKEN`; build secrets are unset on the host before the agent's Safehouse wrap is executed.
-- `runner: "none"`: `secrets.env` is sourced first, `.groundcrew/setup.sh` runs on the host, build-secret names are unset, then `preLaunch` runs against a clean env, then the agent is executed.
+- `runner: "safehouse"`: `preLaunch` runs immediately after `cd`, before `secrets.env` is sourced into the launch shell. `prepareWorktree` then runs inside its own profile-neutral `safehouse-clearance` wrap with `--env-pass=NPM_TOKEN,BUF_TOKEN`; build secrets are unset on the host before the agent's Safehouse wrap is executed.
+- `runner: "none"`: `secrets.env` is sourced first, `prepareWorktree` runs on the host, build-secret names are unset, then `preLaunch` runs against a clean env, then the agent is executed.
 
 Under the default `safehouse` runner, the agent runs under a sanitized env allowlist. Exports from `preLaunch` land in the launch shell but are stripped before reaching the agent unless they are forwarded. `preLaunchEnv` is the supported way to forward them:
 

package/docs/setup-hook-agent-prompt.md

@@ -1,62 +1,59 @@
-# Agent prompt: generate `.groundcrew/setup.sh`
+# Agent prompt: generate `.groundcrew/config.json`
 
-When onboarding a new repository to groundcrew, an operator needs to author `.groundcrew/setup.sh` — the per-worktree setup hook. The hook has a non-obvious contract: the `--deps-only` branch must skip anything interactive or one-time-only, and several things that look like setup (codegen, db seeds, husky, pre-commit, local-package linking) belong only in the no-flag branch.
+When onboarding a repository to Groundcrew, an operator can ask a coding agent
+to author the repo-local `prepareWorktree` hook. The hook has a narrow contract:
+it is recurring, non-interactive worktree preparation for unattended agents.
 
-To hand the job to a coding agent (Claude Code, Cursor, etc.) without re-explaining the rules, open the agent at the target repo's root and paste the prompt below. For the full contract this prompt encodes, see [Per-repo setup hook](../README.md#per-repo-setup-hook) in the README.
+Paste this prompt at the target repo root:
 
 ```text
-You're adding a per-worktree setup hook for this repository. Produce a single
-file at `.groundcrew/setup.sh` and smoke-test it.
-
-Context: groundcrew launches each agent in a fresh git worktree per ticket and
-invokes `bash .groundcrew/setup.sh --deps-only` before the agent starts. The
-flag tells the script "you're being called by automation; skip anything
-interactive or one-time-only." The same hook also runs inside the sdx sandbox.
-
-Script requirements:
-
-- Start with `set -euo pipefail`.
-- Branch on `$1`:
-  - `--deps-only` → recurring per-worktree work only (lockfile install,
-    codegen the agent needs to navigate). NO prompts, NO global installs, NO
-    runtime-version-manager bootstrap (`nvm`, `pyenv`, `rustup`, `mise`,
-    `asdf` — assume the host has the runtime).
-  - No flag → full interactive bootstrap for first-time onboarding or
-    SessionStart-hook reuse (husky install, pre-commit install, db seed,
-    local-package linking).
-- Fast. The operator pays this cost on every ticket spinup, and each
-  worktree starts fresh (`node_modules` / `.venv` / `target` are
-  gitignored). Use the package manager's frozen-lockfile install (`npm
-  clean-install`, `uv sync --frozen`, `cargo fetch`, etc.) and trust its
-  global cache — a "fresh" install in a new worktree should resolve from
-  `~/.cache/uv`, `~/.npm`, etc. rather than re-downloading. Setup failures
-  are logged but don't block the agent, so exit non-zero on real problems
-  so the operator sees them.
-
-Detect this repo's stack and install accordingly. Examples:
-
-- `package.json` + `pnpm-lock.yaml` / `package-lock.json` / `yarn.lock` →
-  matching Node package manager's frozen-lockfile install
-- `pyproject.toml` + `uv.lock` → `uv sync --dev`; `poetry.lock` → poetry;
-  `Pipfile.lock` → pipenv; bare `requirements.txt` → pip + venv
+You're adding Groundcrew's repo-local prepareWorktree hook for this repository.
+Produce `.groundcrew/config.json` and smoke-test the command.
+
+Context: Groundcrew launches each agent in a fresh git worktree per ticket. If
+`.groundcrew/config.json` contains `hooks.prepareWorktree`, Groundcrew runs that
+command from the repo root after creating the worktree and before launching the
+agent. The same command runs under Safehouse, sdx, or the host runner.
+
+Hook requirements:
+
+- JSON shape:
+  {
+    "version": 1,
+    "hooks": {
+      "prepareWorktree": "<command>"
+    }
+  }
+- The command must be non-interactive and idempotent.
+- Include only recurring worktree preparation the agent needs, such as lockfile
+  installs, dependency downloads, or type/code generation required for
+  navigation and tests.
+- Do NOT include prompts, global installs, auth setup, runtime-version-manager
+  bootstrap (`nvm`, `pyenv`, `rustup`, `mise`, `asdf`), db seeds, husky,
+  pre-commit, or local package linking.
+- Keep it fast. Each ticket starts from a fresh worktree, so use frozen-lockfile
+  installs (`npm ci`, `pnpm install --frozen-lockfile`, `uv sync --frozen`,
+  `cargo fetch`, `go mod download`, etc.) and trust global package-manager
+  caches.
+
+Detect this repo's stack and write the shortest command that prepares the root
+worktree:
+
+- `package.json` + `package-lock.json` → `npm ci`
+- `package.json` + `pnpm-lock.yaml` → `pnpm install --frozen-lockfile`
+- `package.json` + `yarn.lock` → `yarn install --frozen-lockfile`
+- `pyproject.toml` + `uv.lock` → `uv sync --dev --frozen`
+- `poetry.lock` → `poetry install`
 - `Cargo.lock` → `cargo fetch`
 - `go.mod` → `go mod download`
 - `Gemfile.lock` → `bundle install --jobs=4`
-- Multiple lockfiles → polyglot; install each under its own guard.
-- No install step (docs repo, polyglot monorepo with per-package setup) →
-  do not create the script. Groundcrew skips the hook silently when the
-  file is absent.
-
-Put codegen-the-agent-doesn't-need, db seeds, husky install, pre-commit
-install, and local-package linking ONLY in the no-flag branch — never in
-`--deps-only`.
+- Multiple lockfiles → combine each required root-level prep command with `&&`.
+- No recurring root worktree prep → do not create the file.
 
 Verify before reporting done:
 
-1. `bash .groundcrew/setup.sh --deps-only` exits 0 with no interactive prompts.
-2. The output has no runtime-bootstrap warnings (`nvm not found`, `Python not
-   on PATH`, etc.) — if you see them, the script is doing too much; strip
-   those branches.
+1. Run the exact `hooks.prepareWorktree` command from the repo root.
+2. Confirm it exits 0 with no prompts and no runtime-bootstrap warnings.
 
 Do NOT commit. Report exactly what you wrote so the operator can review.
 ```

package/docs/setup-hooks.md

@@ -1,46 +1,81 @@
-# Setup Hooks
+# Prepare Worktree Hooks
 
-If `.groundcrew/setup.sh` exists in the repo root, groundcrew runs `bash .groundcrew/setup.sh --deps-only` before each agent launch. Otherwise nothing runs. Same convention applies inside the sdx sandbox, overridable per model via `models.definitions.<name>.sandbox.setupCommand`.
+Groundcrew can run one repo-preparation hook after it creates a ticket worktree
+and before it launches the agent. Add a repo-local `.groundcrew/config.json`:
 
-There is no implicit `npm install`, `uv sync`, or anything else. Groundcrew is language-agnostic, so opt in by adding the script.
+```json
+{
+  "version": 1,
+  "hooks": {
+    "prepareWorktree": "npm ci && npm run codegen:types"
+  }
+}
+```
+
+If the file or hook is absent, Groundcrew skips this phase. There is no
+implicit `npm install`, `uv sync`, or legacy setup script convention.
+
+`prepareWorktree` must be non-interactive, idempotent, and limited to recurring
+worktree preparation the agent needs: lockfile installs, dependency downloads,
+or type/code generation required for navigation and tests. Do not put human
+onboarding in this hook: no prompts, global installs, auth setup, runtime
+manager bootstrap (`nvm`, `pyenv`, `rustup`, `mise`, `asdf`), db seeds, husky,
+pre-commit, or local package linking.
+
+The hook runs from the repo root under every runner:
+
+- `safehouse`: inside a profile-neutral Safehouse wrap before the agent wrap.
+- `sdx`: inside the Docker Sandbox before the agent command.
+- `none`: on the host shell before the agent command.
 
-The `--deps-only` flag tells the script it is being called by an automated system before an agent launches. Skip anything interactive or one-time-only. The same script handles both modes; branch on `$1`:
+Hook failures are advisory. Groundcrew logs the non-zero exit and still launches
+the agent so a flaky package registry or stale lockfile does not block the
+session.
 
-- With `--deps-only`: do the cheap recurring work this worktree needs, such as lockfile installs or type generation. No prompts, no global installs, no `nvm` / `pyenv` bootstrap.
-- Without the flag: full interactive bootstrap for first-time onboarding or another tool's SessionStart hook.
+## Defaults
 
-Setup failures are advisory. Groundcrew logs the non-zero exit and still launches the agent so a flaky network or stale lockfile does not block the session.
+For repos without local config, set a fallback in `crew.config.ts`:
+
+```ts
+export default {
+  defaults: {
+    hooks: {
+      prepareWorktree: "test ! -f package-lock.json || npm ci",
+    },
+  },
+  // ...
+};
+```
+
+Repo-local `.groundcrew/config.json` wins for that hook. A repo-local file
+without `hooks.prepareWorktree` still falls back to the `crew.config.ts`
+default.
 
 ## Examples
 
 Python with uv:
 
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-if [ "${1:-}" = "--deps-only" ]; then
-  uv sync --dev
-else
-  uv sync --dev
-  # Extra one-time bootstrap, such as pre-commit install or db seed.
-fi
+```json
+{
+  "version": 1,
+  "hooks": {
+    "prepareWorktree": "uv sync --dev --frozen"
+  }
+}
 ```
 
 Node with npm:
 
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-if [ "${1:-}" = "--deps-only" ]; then
-  npm clean-install
-else
-  npm clean-install
-  # Extra one-time bootstrap, such as husky install or codegen.
-fi
+```json
+{
+  "version": 1,
+  "hooks": {
+    "prepareWorktree": "npm ci"
+  }
+}
 ```
 
-Docs-only or polyglot repos can omit the script. With nothing at `.groundcrew/setup.sh`, groundcrew skips the hook silently.
-
-For a comprehensive real-world example with nvm bootstrap, hash-based skip-on-no-changes caching, and portable SHA-256 detection, see [this repo's own `.groundcrew/setup.sh`](../.groundcrew/setup.sh). It is also symlinked at `.claude/setup.sh` so the same script doubles as a Claude Code SessionStart hook for this repo; that symlink is local convenience, not part of groundcrew's contract.
+Docs-only or manually prepared repos can omit the file.
 
-To scaffold `.groundcrew/setup.sh` with a coding agent, see [setup-hook-agent-prompt.md](./setup-hook-agent-prompt.md).
+To scaffold `.groundcrew/config.json` with a coding agent, see
+[setup-hook-agent-prompt.md](./setup-hook-agent-prompt.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",