@clipboard-health/groundcrew 4.7.3 → 4.9.0

package/dist/lib/config.js

@@ -35,7 +35,7 @@ const DEFAULT_ORCHESTRATOR = {
     pollIntervalMilliseconds: 120_000,
     sessionLimitPercentage: 85,
 };
-const DEFAULT_MODEL_DEFINITIONS = {
+const BUILT_IN_MODEL_DEFINITIONS = {
     claude: {
         cmd: "claude --permission-mode auto",
         color: "#C15F3C",
@@ -47,6 +47,30 @@ const DEFAULT_MODEL_DEFINITIONS = {
         usage: { codexbar: { provider: "codex" } },
     },
 };
+const MODEL_DEFINITIONS_MIGRATION_MESSAGE = [
+    "configuration migration required: models are no longer enabled by default.",
+    "",
+    "Add the models you want to use:",
+    "",
+    "models: {",
+    '  default: "claude",',
+    "  definitions: {",
+    "    claude: {},",
+    "  },",
+    "},",
+    "",
+    "To keep the previous claude+codex behavior:",
+    "",
+    "models: {",
+    '  default: "claude",',
+    "  definitions: {",
+    "    claude: {},",
+    "    codex: {},",
+    "  },",
+    "},",
+    "",
+    "`disabled: true` is no longer supported; remove disabled model entries instead.",
+].join("\n");
 const DEFAULT_PROMPT_INITIAL = [
     "You are working on Linear ticket {{ticket}} ({{title}}) in the {{worktree}} worktree subdirectory.",
     "",
@@ -128,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`;
@@ -139,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.
@@ -196,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)) {
@@ -221,23 +268,16 @@ function failIfLegacyModelKeys(name, override) {
         fail(`models.definitions.${name}.isolation is no longer supported: per-model isolation is no longer supported`);
     }
     if (Object.hasOwn(override, "disabled")) {
-        if (override["disabled"] !== true) {
-            fail(`models.definitions.${name}.disabled must be exactly \`true\` when set (got ${JSON.stringify(override["disabled"])})`);
-        }
-        const conflicting = ["cmd", "color", "usage", "sandbox", "preLaunch", "preLaunchEnv"].filter((key) => Object.hasOwn(override, key));
-        if (conflicting.length > 0) {
-            fail(`models.definitions.${name}: cannot combine \`disabled: true\` with other fields (${conflicting.join(", ")}). Either disable the model or override its fields, not both.`);
-        }
+        fail(MODEL_DEFINITIONS_MIGRATION_MESSAGE);
     }
 }
 /**
- * True when `name` is a shipped default the user removed via `disabled: true`.
- * Derived from absence in `definitions` — that's the only path that removes a
- * shipped default, codified in `failIfLegacyModelKeys` + `mergeDefinitions`.
- * Consumers needing to distinguish disabled-by-user from unknown-label use this.
+ * True when `name` is a built-in preset but not present in the enabled
+ * definitions. Consumers use this to distinguish `agent-codex` when codex is
+ * not enabled from an arbitrary unknown label like `agent-typo`.
  */
-export function isShippedDefaultDisabled(config, name) {
-    return (Object.hasOwn(DEFAULT_MODEL_DEFINITIONS, name) &&
+export function isBuiltInModelNotEnabled(config, name) {
+    return (Object.hasOwn(BUILT_IN_MODEL_DEFINITIONS, name) &&
         !Object.hasOwn(config.models.definitions, name));
 }
 function isUsageDisableSentinel(usage) {
@@ -274,27 +314,17 @@ function buildOverrideCandidate(name, override, existing) {
     return candidate;
 }
 function mergeDefinitions(user) {
-    if (user !== undefined && !isPlainObject(user)) {
+    if (user === undefined) {
+        fail(MODEL_DEFINITIONS_MIGRATION_MESSAGE);
+    }
+    if (!isPlainObject(user)) {
         fail("models.definitions must be an object");
     }
-    const merged = Object.fromEntries(Object.entries(DEFAULT_MODEL_DEFINITIONS).map(([name, definition]) => [
-        name,
-        cloneModelDefinition(definition),
-    ]));
-    for (const [name, override] of Object.entries(user ?? {})) {
+    const merged = {};
+    for (const [name, override] of Object.entries(user)) {
         failIfLegacyModelKeys(name, override);
-        if (override.disabled === true) {
-            if (!Object.hasOwn(DEFAULT_MODEL_DEFINITIONS, name)) {
-                fail(`models.definitions.${name}: \`disabled: true\` is only valid for shipped defaults (${Object.keys(DEFAULT_MODEL_DEFINITIONS).join(", ")}). Remove the entry instead.`);
-            }
-            // Drop the key so downstream iterators (doctor, eligibility, usage) ignore
-            // the model automatically; `isShippedDefaultDisabled` lets the few consumers
-            // that need to distinguish disabled from unknown re-derive the set.
-            // oxlint-disable-next-line typescript/no-dynamic-delete -- `merged` is a fresh function-local clone of DEFAULT_MODEL_DEFINITIONS; no V8 dictionary-mode/pollution concerns
-            delete merged[name];
-            continue;
-        }
-        const candidate = buildOverrideCandidate(name, override, merged[name]);
+        const builtIn = BUILT_IN_MODEL_DEFINITIONS[name];
+        const candidate = buildOverrideCandidate(name, override, builtIn);
         const { cmd, color, usage, sandbox, preLaunch, preLaunchEnv } = candidate;
         if (typeof cmd !== "string" || cmd.length === 0) {
             fail(`models.definitions.${name}.cmd must be a non-empty string`);
@@ -416,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",
@@ -456,7 +487,6 @@ function validate(config) {
     requirePositiveInt(config.orchestrator.pollIntervalMilliseconds, "orchestrator.pollIntervalMilliseconds");
     requirePercent(config.orchestrator.sessionLimitPercentage, "orchestrator.sessionLimitPercentage");
     const { definitions } = config.models;
-    /* v8 ignore next 3 @preserve -- mergeDefinitions seeds claude+codex defaults, so an empty map is unreachable */
     if (Object.keys(definitions).length === 0) {
         fail("models.definitions must contain at least one model");
     }
@@ -468,12 +498,12 @@ function validate(config) {
         requireString(definition.color, `models.definitions.${name}.color`);
         if (definition.usage !== undefined) {
             const usagePath = `models.definitions.${name}.usage`;
-            /* v8 ignore next 3 @preserve -- mergeDefinitions only assigns usage from validated overrides or shipped defaults; reaching this guard requires hand-mutating the resolved config */
+            /* v8 ignore next 3 @preserve -- mergeDefinitions only assigns usage from validated overrides or built-in presets; reaching this guard requires hand-mutating the resolved config */
             if (typeof definition.usage !== "object" || definition.usage === null) {
                 fail(`${usagePath} must be an object`);
             }
             const { codexbar } = definition.usage;
-            /* v8 ignore next 3 @preserve -- mergeDefinitions only assigns usage from validated overrides or shipped defaults; reaching this guard requires hand-mutating the resolved config */
+            /* v8 ignore next 3 @preserve -- mergeDefinitions only assigns usage from validated overrides or built-in presets; reaching this guard requires hand-mutating the resolved config */
             if (typeof codexbar !== "object" || codexbar === null) {
                 fail(`${usagePath}.codexbar must be an object`);
             }
@@ -496,11 +526,11 @@ function validate(config) {
     if (!LOCAL_RUNNER_SETTINGS.includes(config.local.runner)) {
         fail(`local.runner must be one of ${LOCAL_RUNNER_SETTINGS.join(", ")} (got ${JSON.stringify(config.local.runner)})`);
     }
-    // Disabled-default check must run before the generic "not a key" check so
-    // the user gets the specific "is disabled" message instead of a stale-list
-    // message they can't act on without realizing they need to re-enable.
-    if (isShippedDefaultDisabled(config, config.models.default)) {
-        fail(`models.default ("${config.models.default}") is disabled. Either re-enable it or set models.default to an enabled model.`);
+    // Built-in-not-enabled check must run before the generic "not a key" check
+    // so the user gets the specific migration-oriented message for `codex`
+    // instead of a stale-list message.
+    if (isBuiltInModelNotEnabled(config, config.models.default)) {
+        fail(`models.default ("${config.models.default}") is not enabled. Add \`models.definitions.${config.models.default}: {}\` or set models.default to an enabled model.`);
     }
     if (!(config.models.default in definitions)) {
         fail(`models.default ("${config.models.default}") is not a key in models.definitions (have: ${Object.keys(definitions).join(", ")})`);

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