@clipboard-health/groundcrew 4.47.5 → 4.48.0

package/README.md

@@ -159,6 +159,7 @@ There is no `linear` config block. Groundcrew reads `GROUNDCREW_LINEAR_API_KEY`
 - [Runners](./docs/runners.md): Safehouse, Docker Sandboxes, and the `none` escape hatch.
 - [Credentials](./docs/credentials.md): Linear API keys, 1Password, build secrets, and `preLaunch`.
 - [Prepare worktree hooks](./docs/setup-hooks.md): `.groundcrew/config.json` `hooks.prepareWorktree` for per-repo dependency setup.
+- [Operator host setup](./docs/setup-hooks.md#unsandboxedhooks-operator-only-host-setup): `crew.config.ts` `knownRepositories[].unsandboxedHooks.prepareWorktree` runs trusted, per-repo setup on the host outside the sandbox.
 - [Task sources](./docs/task-sources.md): custom shell/Jira/local-plan adapters.
 - [Development](./docs/development.md): local source workflow and README/demo asset regeneration.
 - [Troubleshooting](./docs/troubleshooting.md): common operational pitfalls and fixes.

package/dist/commands/openWorkspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/openWorkspace.ts"],"names":[],"mappings":"AAKA,OAAO,EAAiC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAetF,UAAU,gBAAgB;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA6JD,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA8Gf;AA4ID,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAE3E;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE"}
+{"version":3,"file":"openWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/openWorkspace.ts"],"names":[],"mappings":"AAKA,OAAO,EAAiC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAetF,UAAU,gBAAgB;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA6JD,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA0Hf;AA4ID,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAE3E;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE"}

package/dist/commands/openWorkspace.js

@@ -156,11 +156,20 @@ export async function openWorkspace(config, options) {
     });
     let srtSettingsDir;
     try {
+        const repositoryEntry = config.workspace.repositories.find((entry) => entry.name === repository);
         const prepareWorktreeCommand = resolvePrepareWorktreeCommand({
             worktreeDir: launchDir,
+            // Spread-conditional: exactOptionalPropertyTypes forbids an explicit
+            // `undefined` for an optional field, and the lookup yields undefined for
+            // repos with no hooks. Mirrors setupWorkspace so `crew open` honors the
+            // same per-repo operator hooks as `crew setup`.
+            ...(repositoryEntry?.hooks === undefined ? {} : { perRepoHooks: repositoryEntry.hooks }),
             defaultHooks: config.defaults.hooks,
         });
-        const secretsFile = prepareWorktreeCommand === undefined ? undefined : stageBuildSecrets(stagedPrompt.directory);
+        const prepareWorktreeUnsandboxedCommand = repositoryEntry?.unsandboxedHooks?.prepareWorktree;
+        const secretsFile = prepareWorktreeCommand === undefined && prepareWorktreeUnsandboxedCommand === undefined
+            ? undefined
+            : stageBuildSecrets(stagedPrompt.directory);
         seedLaunchWorkspaceTrust({
             agentCommandName: inferAgentCommandName(definition.cmd),
             launchDir,
@@ -176,6 +185,7 @@ export async function openWorkspace(config, options) {
             workingDir: launchDir,
             secretsFile,
             prepareWorktreeCommand,
+            prepareWorktreeUnsandboxedCommand,
             sandboxName,
             workspaceKind,
             readOnlyDirs: config.local.readOnlyDirs,

package/dist/commands/setupWorkspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA0BnE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6FAA6F;IAC7F,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CAsJf;AA8MD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CAkDf"}
+{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA0BnE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6FAA6F;IAC7F,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CA2Jf;AA8MD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CAkDf"}

package/dist/commands/setupWorkspace.js

@@ -85,7 +85,9 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             workspaceContinuationInstruction: renderWorkspaceContinuationInstruction(accessHint),
         });
         promptDir = stagedPrompt.directory;
-        const perRepoHooks = config.workspace.repositories.find((entry) => entry.name === repository)?.hooks;
+        const repositoryEntry = config.workspace.repositories.find((entry) => entry.name === repository);
+        const perRepoHooks = repositoryEntry?.hooks;
+        const prepareWorktreeUnsandboxedCommand = repositoryEntry?.unsandboxedHooks?.prepareWorktree;
         const prepareWorktreeCommand = resolvePrepareWorktreeCommand({
             worktreeDir: launchDir,
             // Spread-conditional rather than a direct assignment: under
@@ -94,7 +96,9 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             ...(perRepoHooks === undefined ? {} : { perRepoHooks }),
             defaultHooks: config.defaults.hooks,
         });
-        const secretsFile = prepareWorktreeCommand === undefined ? undefined : stageBuildSecrets(promptDir);
+        const secretsFile = prepareWorktreeCommand === undefined && prepareWorktreeUnsandboxedCommand === undefined
+            ? undefined
+            : stageBuildSecrets(promptDir);
         const completionTaskId = options.completionTaskId ?? task;
         const completionMarkDoneSupported = options.completionMarkDoneSupported ?? true;
         const taskSourceWritePaths = runner === "safehouse" || runner === "srt"
@@ -118,6 +122,7 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             workingDir: launchDir,
             secretsFile,
             prepareWorktreeCommand,
+            prepareWorktreeUnsandboxedCommand,
             sandboxName,
             workspaceKind,
             readOnlyDirs: config.local.readOnlyDirs,

package/dist/commands/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAenE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA4rBD,wBAAsB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/F;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7D"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAenE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAosBD,wBAAsB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/F;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7D"}

package/dist/commands/status.js

@@ -489,15 +489,20 @@ function statusByWorktreeTask(boardResult) {
     }
     return statuses;
 }
-function writeQueueSections(boardResult) {
+function writeQueueSections(boardResult, worktreeTasks) {
     if (boardResult.kind === "error") {
         writeSection("Queue");
         writeOutput(`unavailable: ${errorMessage(boardResult.error)}`);
         return;
     }
     // Only groundcrew-eligible Todos are dispatchable; non-eligible ones lack
-    // a repo or agent, so `crew run` would skip them.
-    const todos = boardResult.issues.filter(isTodoSourceIssue).filter(isGroundcrewIssue);
+    // a repo or agent, so `crew run` would skip them. Todos whose task already
+    // has a local worktree are omitted so a dispatched-but-not-yet-transitioned
+    // ticket doesn't show as both provisioning and queued.
+    const todos = boardResult.issues
+        .filter(isTodoSourceIssue)
+        .filter(isGroundcrewIssue)
+        .filter((i) => !worktreeTasks.has(naturalIdFromCanonical(i.id).toLowerCase()));
     const ready = todos.filter((i) => !hasOpenBlocker(i));
     const blocked = todos.filter(hasOpenBlocker);
     // Hide the section entirely when nothing's queued and nothing's blocked.
@@ -587,7 +592,7 @@ async function writeInventoryStatus(config) {
         writeOutput();
         writeOutput(`slots: ${used}/${config.orchestrator.maximumInProgress} used`);
     }
-    writeQueueSections(boardResult);
+    writeQueueSections(boardResult, worktreeTasks);
 }
 export async function status(config, options = {}) {
     const task = options.task?.trim();

package/dist/lib/agentLaunch.d.ts

@@ -18,6 +18,7 @@ export declare function composeAgentLaunch(input: {
     workingDir: string;
     secretsFile?: string | undefined;
     prepareWorktreeCommand?: string | undefined;
+    prepareWorktreeUnsandboxedCommand?: string | undefined;
     sandboxName?: string | undefined;
     workspaceKind: WorkspaceKind;
     workerEnvironment?: WorkerEnvironment | undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"agentLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/agentLaunch.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAM5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,aAAa,EAAE,oBAAoB,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAClD,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrD,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACxD,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC9C,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CA2ChE;AA4DD,UAAU,mBAAmB;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,iFAAiF;IACjF,aAAa,EAAE,oBAAoB,CAAC;IACpC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsD/B;AAwBD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB"}
+{"version":3,"file":"agentLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/agentLaunch.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAM5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,aAAa,EAAE,oBAAoB,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,iCAAiC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvD,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAClD,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrD,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACxD,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC9C,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CA4ChE;AA4DD,UAAU,mBAAmB;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,iFAAiF;IACjF,aAAa,EAAE,oBAAoB,CAAC;IACpC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsD/B;AAwBD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB"}

package/dist/lib/agentLaunch.js

@@ -38,6 +38,7 @@ export function composeAgentLaunch(input) {
         workingDir: input.workingDir,
         secretsFile: input.secretsFile,
         prepareWorktreeCommand: input.prepareWorktreeCommand,
+        prepareWorktreeUnsandboxedCommand: input.prepareWorktreeUnsandboxedCommand,
         runner: input.runner,
         networkEgress: input.networkEgress,
         sandboxName: input.sandboxName,

package/dist/lib/config.d.ts

@@ -25,6 +25,17 @@ export type SourceConfig = LinearAdapterConfig | ShellAdapterConfig | TodoTxtAda
 export interface HookCommands {
     prepareWorktree?: string;
 }
+/**
+ * Operator-only hooks that run OUTSIDE the sandbox, on the host shell. Mirrors
+ * the `prepareWorktree` phase name of {@link HookCommands} but is a distinct
+ * type: the two families follow opposite rules (host hooks are operator-only
+ * with no `defaults` cascade), and keeping them separate lets a consumer that
+ * takes an `UnsandboxedHookCommands` be self-documenting about isolation and
+ * lets the two shapes diverge without leaking into each other.
+ */
+export interface UnsandboxedHookCommands {
+    prepareWorktree?: string;
+}
 /**
  * Reserved agent name. A task labeled `agent-any` resolves at runtime
  * to the configured agent with the most available session capacity, so
@@ -202,6 +213,18 @@ export interface KnownRepository {
      * they don't want to (or can't) commit a `.groundcrew/config.json` into.
      */
     hooks?: HookCommands;
+    /**
+     * Operator-only, per-repository hooks run on the HOST shell outside any
+     * sandbox. `unsandboxedHooks.prepareWorktree` runs before the sandboxed
+     * `hooks.prepareWorktree` and the agent. Honored ONLY from `crew.config.ts`;
+     * a `.groundcrew/config.json` that sets `unsandboxedHooks` is a hard config
+     * error (see `repositoryHooks.ts`). There is deliberately no `defaults`
+     * equivalent — host execution is an explicit per-repo grant, never a global
+     * default. Runs with the operator's full host authority against
+     * repo-controlled code (lifecycle scripts, the repo's own `bin/setup`), so
+     * granting it is an explicit trust decision.
+     */
+    unsandboxedHooks?: UnsandboxedHookCommands;
 }
 export interface Config {
     /**

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

@@ -258,6 +258,20 @@ function normalizeHookCommands(value, configKey) {
     }
     return hooks;
 }
+// Caller guards `entry.unsandboxedHooks !== undefined`, so unlike
+// `normalizeHookCommands` (also reached via `defaults.hooks`) this never sees
+// `undefined` — there is deliberately no `defaults.unsandboxedHooks`.
+function normalizeUnsandboxedHookCommands(value, configKey) {
+    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: {} };
@@ -625,6 +639,9 @@ function normalizeKnownRepository(entry, index) {
     if (entry.hooks !== undefined) {
         recipe.hooks = normalizeHookCommands(entry.hooks, `${label}.hooks`);
     }
+    if (entry.unsandboxedHooks !== undefined) {
+        recipe.unsandboxedHooks = normalizeUnsandboxedHookCommands(entry.unsandboxedHooks, `${label}.unsandboxedHooks`);
+    }
     return recipe;
 }
 /**

package/dist/lib/launchCommand.d.ts

@@ -90,6 +90,14 @@ interface LaunchCommandArguments {
      * `defaults.hooks.prepareWorktree` from crew.config.ts.
      */
     prepareWorktreeCommand?: string | undefined;
+    /**
+     * Operator-only, per-repository setup command run on the HOST shell (never a
+     * sandbox), before `prepareWorktreeCommand` and the agent. Resolved by the
+     * caller from `knownRepositories[].unsandboxedHooks.prepareWorktree` in
+     * crew.config.ts. Emitted for the safehouse, srt, and none runners; the sdx
+     * runner rejects it (no host to run it on).
+     */
+    prepareWorktreeUnsandboxedCommand?: 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":"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"}
+{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"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"}

package/dist/lib/launchCommand.js

@@ -98,6 +98,19 @@ function prepareWorktreeWithStatusReporting(prepareWorktreeCommand) {
         'if [ "$prepare_status" -ne 0 ]; then echo "groundcrew prepareWorktree hook exited with status $prepare_status; continuing to agent." >&2; fi',
     ].join("; ");
 }
+/**
+ * Host-shell line for the operator-only `unsandboxedHooks.prepareWorktree` command.
+ * Reuses the same status-reporting wrapper as the sandboxed hook so a failure is
+ * surfaced but non-fatal. `scrubNames` (the agent's `preLaunchEnv`) are `unset`
+ * inside the subshell so this trusted host command cannot read agent
+ * credentials minted by `preLaunch`. Build secrets are intentionally left in
+ * scope so `npm`/`bundle` can authenticate; the caller `unset`s them before the
+ * agent wrap.
+ */
+function hostPrepareWorktreeLine(command, scrubNames) {
+    const scrub = scrubNames.length === 0 ? "" : `${unsetEnvironmentLine(scrubNames)}; `;
+    return `{ ${prepareWorktreeWithStatusReporting(`${scrub}${command}`)}; }`;
+}
 /**
  * Source a `KEY='value'` file with auto-export so build-time secrets land
  * in the shell env before prepareWorktree runs. The `-f` guard keeps it a
@@ -328,6 +341,9 @@ export function buildLaunchCommand(arguments_) {
         if (hasPreLaunchEnv(arguments_.definition)) {
             throw new Error("preLaunchEnv is not yet supported for runner='sdx'. Set local.runner to 'safehouse' or 'none', or open an issue for sdx support.");
         }
+        if (arguments_.prepareWorktreeUnsandboxedCommand !== undefined) {
+            throw new Error("unsandboxedHooks.prepareWorktree is not supported for runner='sdx': the sdx container has no host to run it on. Remove unsandboxedHooks for this repo, or use runner 'safehouse', 'srt', or 'none'.");
+        }
         return buildSdxLaunchCommand(arguments_);
     }
     if (shouldWrapWithSafehouse(arguments_)) {
@@ -374,6 +390,9 @@ function buildUnwrappedHostLaunchCommand(arguments_) {
         ...hostTrapAndCd({ workingDir: arguments_.workingDir, promptDir }),
         ...hostSourceSecrets(arguments_.secretsFile),
     ];
+    if (arguments_.prepareWorktreeUnsandboxedCommand !== undefined) {
+        lines.push(hostPrepareWorktreeLine(arguments_.prepareWorktreeUnsandboxedCommand, arguments_.definition.preLaunchEnv ?? []));
+    }
     if (arguments_.prepareWorktreeCommand !== undefined) {
         lines.push(prepareWorktreeWithStatusReporting(arguments_.prepareWorktreeCommand));
     }
@@ -477,6 +496,9 @@ function buildSafehouseLaunchCommand(arguments_) {
         promptDir,
         secretsFile: arguments_.secretsFile,
     }));
+    if (arguments_.prepareWorktreeUnsandboxedCommand !== undefined) {
+        lines.push(hostPrepareWorktreeLine(arguments_.prepareWorktreeUnsandboxedCommand, arguments_.definition.preLaunchEnv ?? []));
+    }
     if (prepareWorktreeCommand !== undefined) {
         lines.push(`${safehouseWrapper} ${safehouseAddDirsFlag}${prepareWorktreeEnvPassFlag}sh -c ${shellSingleQuote(prepareWorktreeCommand)}`);
     }
@@ -604,6 +626,9 @@ function buildSrtLaunchCommand(arguments_) {
             secretsFile: arguments_.secretsFile,
         }),
     ];
+    if (arguments_.prepareWorktreeUnsandboxedCommand !== undefined) {
+        lines.push(hostPrepareWorktreeLine(arguments_.prepareWorktreeUnsandboxedCommand, arguments_.definition.preLaunchEnv ?? []));
+    }
     if (prepareWorktreeCommand !== undefined) {
         lines.push(`${prepareWrap} sh -c ${shellSingleQuote(prepareWorktreeCommand)}`);
     }

package/dist/lib/repositoryHooks.js

@@ -39,10 +39,23 @@ function normalizeRepositoryConfig(value) {
     if (value["version"] !== 1) {
         fail("version must be 1");
     }
+    rejectUnsandboxedField(value);
     return {
         hooks: normalizeHookCommands(value["hooks"]),
     };
 }
+// `unsandboxedHooks` grants host execution, which is operator-only. A
+// repo-committed config must never be able to set it — top-level or nested under
+// `hooks` — so fail closed with guidance to move it to crew.config.ts. Checked
+// before `normalizeHookCommands`, which would otherwise silently drop the nested
+// form.
+function rejectUnsandboxedField(value) {
+    const hooks = value["hooks"];
+    const nestedHasField = isPlainObject(hooks) && "unsandboxedHooks" in hooks;
+    if ("unsandboxedHooks" in value || nestedHasField) {
+        fail("unsandboxedHooks is operator-only and cannot be set in a repository config. Move it to crew.config.ts.");
+    }
+}
 function normalizeHookCommands(value) {
     if (value === undefined) {
         return {};

package/docs/credentials.md

@@ -32,7 +32,7 @@ Set them in the shell you run `crew` from. Anything not in this list is ignored.
 
 For each task:
 
-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 task's temp prompt dir as `KEY='value'` lines.
+1. If a `prepareWorktree` or `unsandboxedHooks.prepareWorktree` hook is configured and any recognized var is set and non-empty, groundcrew writes `secrets.env` with mode `0600` into the task'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.
 
@@ -44,6 +44,13 @@ Net effect: by the time the agent process exists, the values are gone from the e
 
 `preLaunch` runs a host-shell snippet outside Safehouse/sdx before the agent starts. Use it when the agent needs a short-lived credential that must be minted from something the sandbox cannot reach, such as an engineer CLI session in Keychain.
 
+Build secrets are staged whenever either `prepareWorktree` or
+`unsandboxedHooks.prepareWorktree` is configured. When
+`unsandboxedHooks.prepareWorktree` is set, it runs on the host before
+`prepareWorktree` with build secrets sourced; `preLaunchEnv` names are scrubbed
+before it runs so the command cannot read agent credentials. After it completes,
+execution continues with the normal sandboxed `prepareWorktree` phase.
+
 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. `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.

package/docs/runners.md

@@ -97,6 +97,10 @@ sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
 
 ## Docker Sandboxes Setup
 
+`sdx` does not support `unsandboxedHooks`. The sdx container has no
+host to run it on; configuring it for an `sdx`-runner repo is a launch-time
+config error. Use `safehouse`, `srt`, or `none` if you need host-side setup.
+
 Each agent that runs under `sdx` needs a `sandbox: { agent: "<sbx-agent>" }` block in `crew.config.ts`. Groundcrew addresses the sandbox as `groundcrew-<agent>` and reuses one existing sandbox per agent across repos and tasks.
 
 First-time setup is manual:

package/docs/setup-hooks.md

@@ -94,6 +94,45 @@ This reuses the same `hooks` container and `prepareWorktree` contract as the
 other two layers. It beats `defaults.hooks` but still yields to a committed
 `.groundcrew/config.json` in that repo.
 
+## `unsandboxedHooks` (operator-only host setup)
+
+Some setup cannot run in the sandbox — it needs host toolchains, host network
+posture, or writes outside the worktree. For those cases an operator may grant a
+**per-repository** host hook. It mirrors the `hooks` container's
+`prepareWorktree` phase, on the opposite side of the sandbox boundary:
+
+```ts
+// crew.config.ts (operator only)
+knownRepositories: [
+  {
+    name: "catalog-admin",
+    hooks: { prepareWorktree: "npm ci" }, // sandboxed
+    unsandboxedHooks: { prepareWorktree: "bin/setup" }, // HOST, explicit opt-in
+  },
+];
+```
+
+When both are set, `unsandboxedHooks.prepareWorktree` runs first on the host,
+then `hooks.prepareWorktree` runs sandboxed, then the agent starts.
+
+**The trust granted.** `unsandboxedHooks.prepareWorktree` runs on the host shell
+outside any sandbox, with the operator's full host authority, against
+repo-controlled code (lifecycle scripts, `Gemfile`, the repo's own `bin/setup`).
+Grant it only to repositories you trust to run arbitrary code on the host.
+
+**Constraints.**
+
+- **Operator-only.** It is honored only from `crew.config.ts`. Setting
+  `unsandboxedHooks` in a repo-committed `.groundcrew/config.json`
+  (top-level or under `hooks`) is a hard config error.
+- **Per-repository only.** There is no `defaults.unsandboxedHooks`;
+  host execution is never a fleet-wide default.
+- **Runner support.** Runs on the host for `safehouse`, `srt`, and `none`. The
+  `sdx` runner rejects it at launch — a container has no host to run it on.
+- **Credentials.** Build secrets are available so `npm`/`bundle` can
+  authenticate; the agent's `preLaunchEnv` names are scrubbed so the command
+  cannot read agent credentials.
+
 ## Examples
 
 Python with uv:

package/docs/spec/e2e-scenario-catalog.md

@@ -0,0 +1,164 @@
+# E2E scenario catalog (DEVOP-5974)
+
+The executable half of the groundcrew v2 spec: the black-box scenarios the acceptance suite must cover, plus the harness shape that makes them hermetic. The suite is written **before v2 code exists** and brings v2 up red→green; it is v2's system-level TDD loop and the language-agnostic escape hatch (any implementation that passes is conformant).
+
+**Iteration 1 changes:** the green-on-v1 gate is dropped — v2 breaks too much of v1's surface for v1 scenarios to pay for themselves; that budget moves to migration easing (map fog item). Suite trustworthiness comes from harness self-tests instead (§1.5). The v1 reviewer loop (poll `gh`, advance in-review/done) does not survive into v2: the completion model (§2) is agent-reported, forge-blind, and lingers for human review.
+
+## 1. Suite architecture
+
+### 1.1 Black-box rules
+
+- The suite spawns the `crew` binary and observes the world. It never imports groundcrew code, reads groundcrew internals, or mocks in-process.
+- Assertions target the **observation surface** (§1.2), not stdout prose. Stdout/exit codes are asserted only where the output _is_ the behavior (`status`, `doctor`, loud errors), and then loosely (key substrings, not full-text golden files).
+
+### 1.2 Observation surface
+
+Everything a scenario may assert on:
+
+| Channel                | How observed                                                                                                     |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Exit codes             | direct                                                                                                           |
+| Worktrees & branches   | `git worktree list`, `git branch`, `git log`/`status` in the scenario tmpdir                                     |
+| Run/task state on disk | v2's state files (path + schema fixed by the spec; suite parses them read-only)                                  |
+| Terminal sessions      | real tmux on an isolated socket (`tmux -L <scenario-id>`) — session exists / alive / exited                      |
+| Source interactions    | the fixture source's **call journal** (§1.4): every command invocation with args + stdin, appended as JSON lines |
+| Structured logs        | JSON-line log file under the scenario's state dir                                                                |
+| Human-facing output    | `status` / `doctor` stdout, loose match                                                                          |
+
+### 1.3 Command binding
+
+Scenarios call abstract operations bound in exactly one harness module. The CLI surface ([DEVOP-5975](https://linear.app/clipboardhealth/issue/DEVOP-5975)) has since landed the concrete names — `start` (merged run+start, `--watch`/`--force`), `pause`/`resume`, `cleanup`, `status`, `doctor`, and in-session `repo add` / `artifact add` / `done` — so the binding is now mechanical:
+
+```text
+configure(fixture)            // write config into the scenario tmpdir
+seedSource(tasks[])           // load the fixture source's task store
+tick()                        // one poll/dispatch cycle
+start(taskId, {force?})       // dispatch that task; force bypasses eligibility, never the repo-on-disk gate
+pause(taskId) / resume(taskId) / cleanup(taskId, {force}) / status(taskId?) / doctor()
+killOrchestrator() / restart()  // crash scenarios
+paths: { worktreeFor(repo, task), workspaceFor(task), stateFor(task), logFile }
+expect: { branchFor(task), sessionFor(task) }
+```
+
+### 1.4 Fakes
+
+| Real thing                  | Stand-in                                                                                                                                                                                                                                                                                 | Notes                                                                                                                                   |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Linear / Jira / any tracker | **Fixture source**: a protocol-1 manifest bundle backed by a JSON task store in the scenario tmpdir. Every invocation appends `{command, args, stdin, timestamp}` to `calls.jsonl` — the writeback assertion point.                                                                      | First-party sources are conformance tests of the boundary (DEVOP-5973); the fixture source tests the same boundary from the other side. |
+| Agent CLI (claude/codex/…)  | **Scripted agent**: an executable that reads a per-scenario script (env-pointed file) and deterministically acts — sleep, write files, `git commit`, invoke in-session `crew` commands, report artifacts, exit 0/1. Agent profiles are declarative config with `cmd`, so this is honest. | Emits a heartbeat file so scenarios synchronize on "agent is running" without sleeps.                                                   |
+| GitHub / forge              | **Fake `gh` on PATH that exists only to record calls.** v2 core is forge-blind; any core-process invocation is a failure (FLOW-06). Agent-initiated calls are scripted and allowed.                                                                                                      | The absence of a real forge fake is itself a spec assertion.                                                                            |
+| Git remotes                 | Local bare repos (`file://` remotes) under the scenario tmpdir; `origin/main` seeded with a few commits.                                                                                                                                                                                 | Real git throughout.                                                                                                                    |
+| tmux                        | Real tmux, isolated per scenario via `-L <socket>`.                                                                                                                                                                                                                                      | Real seam, cheap, deterministic enough.                                                                                                 |
+| Host env                    | Per-scenario tmpdir owning `HOME`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`; PATH prepended with the fakes dir; no network in the core lane.                                                                                                                                                  |                                                                                                                                         |
+
+### 1.5 Harness self-tests
+
+With no working implementation to validate against (green-on-v1 dropped), the harness proves itself directly: the fixture source, scripted agent, journal, and tmux/git observation helpers each get their own tests that run without any `crew` binary. A suite failure during v2 bring-up then points at v2, not at the suite.
+
+### 1.6 Lanes
+
+- **Core lane**: hermetic, no sandbox runner, runs anywhere including CI.
+- **Sandbox lane**: real srt (macOS `sandbox-exec` / Linux bubblewrap), platform-gated; asserts denial behavior that can't be faked honestly. v2-only by definition — v1's posture keeps its existing unit-level coverage.
+
+### 1.7 Suite packaging
+
+An `e2e/` package in the groundcrew repo, plain TypeScript + vitest, spawning the built binary; fixture source and scripted agent are committed executables.
+
+## 2. Completion model (codified from iteration 1)
+
+- **Core never polls a destination for done-ness.** No forge calls, no tracker reads to infer task completion. `status` reports what groundcrew knows: **observed** workspace git facts (branches, commits, dirty state) and **agent-reported** events and artifacts. Whether the tracker moves to done is the source's business (its `update` handler) or tracker automation's — humans see the agent's report and judge for themselves.
+- **`completed{outcome}` frees the dispatch slot immediately** — a finished task never blocks the queue.
+- **The workspace lingers after completion, with two exits.** Worktrees, branches, and the final state record stay on disk until **either** a human runs `cleanup` **or** polling observes the _source_ reporting the task terminal (e.g. the tracker moved to Done after the PR merged) — v1's cleaner, kept as-is because it watches the source, not the forge. The review window holds in practice: the tracker rarely reaches done the instant the agent reports delivered. Auto-reap never removes a dirty worktree; it skips loudly and leaves it for a human.
+
+## 3. The catalog
+
+Each entry: **ID · lane · Given** (source store, config, disk, scripts) · **When** (harness ops) · **Then** (observation-surface assertions). IDs are stable; the suite implements one test per ID.
+
+### A. Dispatch & happy paths
+
+- **DISPATCH-01** (core) — _Single-repo happy path._ Given one todo task designating repo `alpha` and an agent profile, repo `alpha` cloned under the base dir. When `tick()`. Then: worktree exists at `paths.worktreeFor(alpha, task)` on branch `expect.branchFor(task)` cut from `origin/main`; tmux session alive; state records running; journal shows `update:claimed` acknowledged.
+- **DISPATCH-02** (core) — _Slot limit respected._ Given max-in-progress 1 and two eligible tasks. When `tick()`. Then exactly one provisions; the other stays queued (no worktree, no session, no writeback).
+- **DISPATCH-03** (core) — _Priority ordering._ Given two eligible tasks with different priorities and one slot. Then the higher-priority task is the one provisioned.
+- **DISPATCH-04** (core) — _Blocked task skipped, dispatched when unblocked._ Given a task with an open blocker. When `tick()`: nothing provisions. When the fixture marks the blocker done and `tick()` again: it provisions.
+- **DISPATCH-05** (core) — _Ineligible task ignored._ Given a task with no agent routing. When `tick()`. Then no provisioning, no writeback, task still listed as queued.
+- **DISPATCH-06** (core) — _Designated repo not on disk → bail._ Given a task designating a repo not cloned under the base dir. When `tick()`. Then no worktree/branch/session/state; the task stays queued at the source; the skip reason is visible (log line + status). (DEVOP-5967 §2.)
+- **DISPATCH-07** (core) — _Manual start bypasses eligibility, never the repo gate._ Given an unlabeled/no-agent task. When `start(task)` (`crew start <task> --force`). Then it provisions exactly as DISPATCH-01. Variant: the same forced start on a task designating a repo not on disk still bails per DISPATCH-06 — `--force` cannot override the repo-on-disk gate.
+- **DISPATCH-08** (core) — _Branch reuse._ Given a prior local branch `expect.branchFor(task)` with a commit. When dispatched. Then the worktree re-attaches to that branch (prior commit present), not a fresh one.
+- **DISPATCH-09** (core) — _Recurrence is a source concern._ Given a fixture source that re-lists a completed task per its recurrence rule. When the task completes and `tick()` runs after re-listing. Then a fresh dispatch occurs; core has no recurrence machinery to observe. (DEVOP-5968 §6.)
+
+### B. Completion & writeback
+
+- **COMPLETE-01** (core) — _Publishing work is reporting it._ Scripted agent commits and runs `crew artifact add <pr-url> --kind pr`. Then: the reported artifact appears in the run record and rides the `completed` writeback; status shows both layers (commits _observed_, PR _reported_); core made no forge call.
+- **COMPLETE-02** (core) — _Delivered: slot freed, workspace lingers._ Scripted agent ends `completed {outcome: delivered, artifacts}`. Then: journal carries the completed event exactly once with artifacts intact; state is `complete{delivered}`; session ended; **worktree, branch, and state record still on disk**; next `tick()` dispatches the next queued task (slot freed) while the delivered workspace lingers.
+- **COMPLETE-03** (core) — _Launch failure is truthful and rolled back._ Given an agent profile whose `cmd` doesn't exist. When `start(task)`. Then state records `complete{failed, reason: launch}`; worktree and branch rolled back; the failure appears in the journal if the task was already claimed.
+- **COMPLETE-04** (core) — _Agent failure is truth-told._ Scripted agent ends `completed {outcome: failed, message}`. Then journal carries the failure event with the message; state is `complete{failed}`; no artifact records invented; workspace lingers for inspection.
+- **COMPLETE-05** (core) — _Read-only source end-to-end._ Given a fixture manifest with no `update` command. Then dispatch, run, and completion all succeed; journal shows zero update calls; status labels the source read-only. (Also asserted at discovery level in PLUGIN-05.)
+- **COMPLETE-08** (core) — _`crew done` honors the dirty-worktree guard._ Scripted agent leaves uncommitted changes and runs `crew done --outcome delivered`: refused with a nonzero exit naming the dirt; task stays running; no completed event. Rerun with `--allow-dirty`: completes normally.
+- **COMPLETE-06** (core) — _Manual cleanup ends the linger._ Given a delivered task's lingering workspace. When `cleanup(task)`. Then worktree removed, branch deleted, state record gone; the source hears nothing new.
+- **COMPLETE-07** (core) — _Source-terminal auto-reap (v1 cleaner parity)._ Given a delivered task's lingering clean workspace. When the fixture source's store marks the task done and `tick()` runs. Then worktree, branch, and state record reaped automatically; the reap is logged. Variant: if the lingering worktree is dirty, auto-reap skips it with a visible warning and everything stays on disk.
+
+### C. Session lifecycle
+
+- **SESSION-01** (core) — _Pause keeps work._ Given a running task. When `pause(task)`. Then session closed, worktree and branch intact, state paused, resumable.
+- **SESSION-02** (core) — _Resume reopens, never recreates._ When `resume(task)` on a paused task: session live again, same worktree, resume count incremented, state running. When `resume` on a task with no worktree: hard error, nothing created.
+- **SESSION-03** (core) — _Status tells the truth about strays._ Given state says running but the tmux session was killed externally. Then `status` flags the disagreement (stray/dead). Given no state but a live session matching a task: `status` flags the stray session.
+
+### D. Crash & recovery
+
+- **CRASH-01** (core) — _SIGKILL mid-run, restart reconciles._ Given a running task. When the orchestrator is SIGKILLed and restarted with `tick()`. Then no duplicate worktree/session/dispatch; state agrees with disk; the running task is still running. (Reconcile-on-startup, DEVOP-5972.)
+- **CRASH-02** (core) — _Orphan worktree directory._ Given a directory at the expected worktree path but absent from `git worktree list`. Then `cleanup --force` removes it only when the path exactly matches the expected shape; a non-matching path is refused.
+- **CRASH-03** (core) — _Dirty worktree is a data-loss guard._ Given a worktree with uncommitted changes. When `cleanup(task)`: refused, names the dirt. When `cleanup(task, {force})`: removed.
+- **CRASH-04** (core) — _Stale state, no disk._ Given a state file for a task with no worktree and no session. Then cleanup clears it; if the session probe is unavailable, everything is left intact.
+- **CRASH-05** (core) — _Reconcile GCs the full triple._ After SIGKILL during provisioning (worktree half-created, session never launched), restart reconciles worktrees **and** tmux **and** sandbox state against expected task state; orphans of each kind GC'd; a log line records each GC action.
+
+### E. Multi-repo & workspace (DEVOP-5967)
+
+- **MULTI-01** (core) — _Designated multi-repo._ Given `Repos: alpha, beta`, both cloned. Then one workspace directory with two worktrees side by side, the **same** task branch in each, **one** tmux session at the workspace root.
+- **MULTI-02** (core) — _Designated-and-missing → bail._ Given `Repos: alpha, gamma`, `gamma` not cloned. Then nothing provisions (not even `alpha`), visible "repo not found" skip, task stays queued.
+- **MULTI-03** (core) — _Empty-workspace dispatch._ Given a task with no repo designation. Then the session launches in an empty workspace; zero worktrees; state running.
+- **MULTI-04** (core) — _Runtime acquisition, allowed._ Scripted agent runs `crew repo add alpha` in-session (task identity via `$GROUNDCREW_WORKSPACE`). Then a worktree for `alpha` appears under the workspace on the uniform task branch; the addition is recorded in task state; prepare-worktree hook ran. Variants exercise the other two identity paths: explicit `--task`, and env unset with cwd inside the workspace (walk-up to `.groundcrew/task.json`).
+- **MULTI-05** (core) — _Runtime acquisition, gate-rejected._ Agent runs `crew repo add not-cloned`. Then a loud error, **exit 2** (repo not cloned under the base directory), nothing created; task keeps running.
+- **MULTI-08** (core) — _In-session command without task context._ `crew repo add alpha` run outside any workspace, with no `--task` and no `$GROUNDCREW_WORKSPACE`. Then **exit 3** (no task context), nothing created, no journal entry.
+- **MULTI-06** (core) — _Partial completion truth-telling._ Agent commits in `alpha` and `beta`, reports a pr artifact for `alpha` only, completes `{outcome: failed}`. Then per-repo records show exactly that (alpha: artifact reported + commits observed; beta: commits observed, nothing reported); no invented atomicity, no rollback.
+- **MULTI-07** (core) — _Repo-less delivery._ Agent in an empty workspace reports `{kind: document, locator: <url>}` and completes delivered. Then the completed event carries the artifact; no git facts exist or are claimed.
+
+### F. Artifacts & source contract (DEVOP-5968)
+
+- **FLOW-01** (core) — _Reported vs observed are separate layers._ Agent commits but reports nothing. Then status shows commits _observed_ and no artifact _reported_ — a missing link, never a lie.
+- **FLOW-02** (core) — _Mixed artifact kinds round-trip._ Agent reports `pr`, `ticket`, and `file` artifacts. Then `completed.artifacts` in the journal carries all three, kinds and locators intact.
+- **FLOW-03** (core) — _Claim rejected._ Given the fixture source answers `claimed` with _rejected_. Then no provisioning, no session; task remains listed; the rejection is visible in log/status. (The remote-runner door.)
+- **FLOW-04** (core, **deferred post-v2.0**) — _Progress events flow._ Requires an agent-facing progress emitter, and v2.0 ships none: `crew progress` is a documented seam, not built (DEVOP-5982 §6). The `progress` event stays in protocol 1; this ID is reserved and the scenario activates when the emitter ships.
+- **FLOW-05** (core) — _Done-ness is not core's business._ After COMPLETE-02, the source's task store still says whatever its own `update` handler chose; core issues no reads to confirm or reconcile it, and status renders the agent's report unchanged.
+- **FLOW-06** (core) — _Core is forge-blind._ Across MULTI/FLOW scenarios, the fake `gh` (and any recorded network attempt in the core lane) shows **zero** invocations by the core process. Agent-initiated calls don't count.
+
+### G. Source packaging & protocol (DEVOP-5973)
+
+- **PLUGIN-01** (core) — _User-dir source discovery._ Given a bundle at `~/.config/groundcrew/task-sources/fixture/` (`source.json` + scripts). Then it lists in `source list`, verifies, and serves dispatch.
+- **PLUGIN-02** (core) — _Name collision: user dir wins._ Given a package-shipped bundle and a user-dir bundle with the same name. Then the user's is used; the override is visible in `source list`/doctor.
+- **PLUGIN-03** (core) — _Protocol mismatch is loud._ Given `protocolVersion: 99`. Then discovery/doctor/status emit an explicit, actionable error naming the version and the supported set; the source is not silently skipped; other sources unaffected.
+- **PLUGIN-04** (core) — _Unparseable manifest: skip + warn._ Given malformed `source.json`. Then a warning names the file; everything else proceeds.
+- **PLUGIN-05** (core) — _Capability by omission._ Given a manifest omitting `update`. Then no version sniffing, no error: the source is treated read-only (COMPLETE-05's mechanism, asserted at discovery level).
+
+### H. Sandbox posture (sandbox lane, platform-gated)
+
+- **SANDBOX-01** (sandbox) — _Agent contained by default._ Scripted agent writes inside the worktree (succeeds) and outside `HOME`-scoped allowed paths (fails). Both outcomes observed via marker files.
+- **SANDBOX-02** (sandbox) — _Agent network egress allowlisted._ Agent curls an allowlisted host (loopback fixture; succeeds) and a non-allowlisted one (fails).
+- **SANDBOX-03** (sandbox) — _Sources sandboxed by default._ Fixture source's `list` script attempts undeclared egress and an out-of-scope write → both denied; declared scratch dir + install dir (read) work. (Manifest `network` allowlist, DEVOP-5973 §4.)
+- **SANDBOX-04** (sandbox) — _`sandbox: false` opt-out is loud._ Given the fixture source configured with `sandbox: false`. Then it runs unsandboxed (undeclared write succeeds) **and** status/doctor visibly flag the opt-out.
+
+### I. Surface & diagnostics
+
+- **SURFACE-01** (core) — _Init → doctor green._ On a healthy fixture host, the init flow produces a config that `doctor` passes and DISPATCH-01 runs against unmodified.
+- **SURFACE-02** (core) — _Doctor catches broken hosts._ Missing agent binary; unreachable/failing source verify; missing base dir — each produces a failing doctor with the cause named, exit 1.
+- **SURFACE-03** (core) — _Status degrades gracefully._ Given the fixture source errors on list. Then `status` still prints local truth (worktrees, sessions, state) and marks the queue unavailable with the reason; exit 0.
+- **SURFACE-04** (core) — _Structured logs are parseable._ After DISPATCH-01 + COMPLETE-02, every line of the log file parses as JSON and carries the task id on task-scoped events. (Deeper schema assertions belong to the observability design — fog.)
+- **SURFACE-05** (core) — _`init --yes` is non-interactive and sufficient._ On a fixture host with an agent CLI on PATH. When `crew init --yes`. Then a `crew.config.jsonc` exists that `doctor` passes and DISPATCH-01 runs against unmodified — no prompts, exit 0.
+- **SURFACE-06** (core) — _v1 config conversion._ Given a v1 `crew.config.ts` (with `knownRepositories`, a `shell` source block, and a safehouse runner setting). When `crew init`. Then a converted `crew.config.jsonc` is written and every dropped or renamed key is named in the output; `doctor` passes afterward.
+- **SURFACE-07** (core) — _`source doctor` live round-trip._ Given the fixture source installed. When `crew source doctor`. Then it exercises the source's verify/read probe end-to-end (journal shows the probe call) and reports healthy; with the fixture's script made to fail, it reports the failure with the source named, exit 1.
+
+## 4. Iteration log
+
+- **Iteration 1** (2026-07-16): green-on-v1 gate dropped in favor of harness self-tests plus a migration-easing budget; completion model codified (forge-blind, agent-reported, linger-until-cleanup); suite stack confirmed (`e2e/` package, TS + vitest); sandbox lane confirmed v2-only. Tier A/B structure and the v1 driver removed accordingly.
+- **Iteration 2** (2026-07-16): linger gets two exits — manual `cleanup` or source-terminal auto-reap (v1's cleaner kept: it watches the source, never the forge; v1's merged-PR reviewer path dies). COMPLETE-07 added; dirty worktrees are never auto-reaped.
+- **Iteration 3** (2026-07-16): absorbed the CLI surface resolution's handoff (DEVOP-5975, resolved concurrently): `workspace add` → `repo add`; completion via `crew done`; task-identity resolution order with exit codes 2/3 (MULTI-04/05/08); `--force` never overrides the repo gate (DISPATCH-07); `done` dirty-guard (COMPLETE-08); `init --yes`, v1-config conversion, and `source doctor` round-trip (SURFACE-05/06/07).
+- **Iteration 4** (2026-07-17): review pass on the design-doc assembly PR: "draft prototype" label dropped (the catalog is ratified); harness binding renamed `stop` → `pause` and `start` gains `{force?}` (SESSION-01, DISPATCH-07); progress assertions removed from COMPLETE-01 and FLOW-04 deferred post-v2.0 — v2.0 ships no agent-facing progress emitter (DEVOP-5982 §6).

package/docs/spec/v2-design.md

@@ -0,0 +1,353 @@
+# Groundcrew v2 design
+
+The implementation handoff for groundcrew v2, assembled from the [Groundcrew v2 spec wayfinder map](https://linear.app/clipboardhealth/issue/DEVOP-5966) (DEVOP-5966). Every decision below was resolved on that map; the [decision record](#13-decision-record) links each section to its ticket, where the full resolution and its rationale live. Where resolutions conflicted, later amendments win and are marked.
+
+This document and the [E2E scenario catalog](./e2e-scenario-catalog.md) together are the spec. **The first implementation task is building the acceptance suite red-first from the catalog — before any v2 code exists.** The suite brings v2 up red-to-green; harness self-tests carry the suite's trustworthiness (the green-on-v1 gate was dropped: v2 breaks too much of v1's surface for v1 scenarios to pay for themselves).
+
+## 1. Destination and locked constraints
+
+Groundcrew dispatches task backlogs to local, interactive AI coding agents — one workspace per task, sandboxed by default. v2 is a rewrite of that product with a smaller, sharper surface.
+
+Locked constraints, not to be re-litigated during implementation:
+
+- **TypeScript.** The language-agnostic escape hatch is the black-box acceptance suite (any implementation that passes is conformant), not a new language.
+- **Free to break v1** — config, CLI, conventions — easing migration opportunistically (section 11).
+- **Sandboxed and secure by default**; interactive sessions are the baseline.
+- **Pluggable agent harnesses** with model and effort-level selection.
+- **Structured logs; minimal CLI surface; sane defaults with minimal required config; install/setup script.**
+- **E2E-first confidence**: the black-box acceptance suite exists red-first before v2 code starts.
+
+## 2. Verdict: rewrite
+
+**Rewrite, not evolve.** ([Rewrite vs evolve](https://linear.app/clipboardhealth/issue/DEVOP-5978))
+
+- The locked decisions kill or fundamentally reshape most of v1 (~21K source lines, ~38K test lines): `config.ts` dies with the TS-config format, the reviewer PR-polling loop dies, clearance/safehouse/sbx die, several commands die, and the core nouns are redefined. Every external surface breaks: config, CLI, source contract, sandbox posture, completion model.
+- Evolve's safety-net premise was stale: the acceptance suite never runs against v1 (green-on-v1 dropped), so in-place evolution gets zero protection from it. "Evolve" would be the same rewrite executed as a thousand PRs fighting 38K test lines that assert dying behavior.
+- Roughly 15–25% of v1 survives recognizably (srtPolicy/srtLaunch, the cleaner, tmux/git plumbing, doctor pieces, usage, completions). Surviving code is **ported file-by-file with its unit tests**; `git mv` preserves history.
+
+**Repo strategy: same repo, isolated `v2/` workspace.** v2 grows on `main` under a top-level `v2/` with its own `package.json`, flat `src/<module>` layout, and its own `CLAUDE.md`/`AGENTS.md`/`CONTEXT.md` carrying the v2 ubiquitous language. v1 and v2 use the same nouns with contradictory meanings ("Workspace" means a terminal pane in v1 and a per-task directory of worktrees in v2), so sharing one `src/` was rejected — it would contaminate agent-driven work. dependency-cruiser forbids cross-tree imports in both directions. **Flip condition:** if v2-building agents keep tripping over v1 despite the boundary, escalate mid-build to a new repo initialized from a full clone, then rename old → `groundcrew-v1`, new → `groundcrew`.
+
+**Package strategy.** Keep `@clipboard-health/groundcrew` and the `crew` bin; the release is **5.0.0** (v1 is at 4.47.x). No npm publish until the E2E suite is green — the team dogfoods from the repo. v1 goes **fixes-only** once v2 construction starts. Cutover: cut a `4.x` maintenance branch, flatten `v2/` to the repo root, delete the v1 tree; later v1 patches publish from `4.x` under a `v4` dist-tag.
+
+**Release-automation wrinkle (must be handled before v2 commits land):** `main`'s Nx Release automation would treat v2 conventional commits as 4.x releases — it needs a path filter or commit-scope exclusion so v2 commits don't trigger 4.x publishes.
+
+## 3. Flow model
+
+([Flow model](https://linear.app/clipboardhealth/issue/DEVOP-5968), informed by the [prior-art research](https://linear.app/clipboardhealth/issue/DEVOP-5969): symmetric source/sink type systems are where Concourse and Tekton died, so the generalization is asymmetric.)
+
+What exists: **sources, agent profiles, tasks, artifact records.** Two things deliberately do not exist:
+
+- **Sinks dissolve.** Every task output happens through the agent's own tools (it opens PRs with `gh`, writes docs, files tickets — it has the credentials and the judgment) or the source's writeback. No typed sink stage; "produce a PR" is the default writeback pattern for repo work, not a privileged path.
+- **Flows dissolve.** Config declares sources and agent profiles; each task carries its routing (an agent designation); a source-level default agent covers the common case. No pipeline/flow config object.
+
+**Artifact record: plural, kind-tagged, agent-reported — no exceptions.** Per task: `{status, logs, artifacts: []}`, each artifact `{kind, locator, title?, repo?}` with an open kind set (`pr | branch | document | file | ticket | …`). All artifacts are reported by the agent via in-session `crew artifact add`. Groundcrew observes only what it owns — workspace-local git facts (branches, commits, dirty state), readable without credentials. **The core knows nothing about GitHub or any forge.** Status renders both layers ("3 commits _observed_; PR _reported_"); a forgotten report is a missing link, never a lie.
+
+**Source contract** — `list`, `get`, `update`, capability by omission:
+
+- `list` (poll for ready tasks) and `get` are required; a source without `update` is legal and read-only (writeback no-ops).
+- `update(task, event)` is the single callback verb. Events: `claimed` (ack; may return _rejected_ where the source arbitrates contention — the remote-runner door, open but unbuilt), `progress` (note), `completed{outcome, artifacts, message}`. Errors are `outcome: failed`, not a separate channel.
+- `create` is dropped; tasks are created in the tracker or file directly.
+
+**Run states** (core-owned, recorded only for started work; the queue stays derived from source polls):
+
+```text
+provisioning → running ⇄ paused → complete{outcome: delivered | failed | stopped}
+```
+
+v1's `resumed` collapses into `running` (resumeCount is a field), `interrupted` → `paused`, `failed-to-launch` → `complete{failed, reason: launch}`. Bail (designated repo not on disk) never enters the machine — the task stays queued at the source with a visible skip reason. `input-required` is **not** a state: in interactive mode the terminal is the input surface; the extensible event set is the seam if headless needs it later.
+
+**Recurring tasks are a source concern.** A source that re-lists a task on a schedule is indistinguishable from a human re-creating it; core ships no recurrence machinery.
+
+## 4. Task model: workspaces of worktrees
+
+([Multi-repo task model](https://linear.app/clipboardhealth/issue/DEVOP-5967))
+
+**One agent session per task, over a workspace of worktrees.** Groundcrew provisions worktrees side by side under a single task workspace directory; one agent session launches at the workspace root and coordinates all repos itself. One terminal surface per task, N PRs out. The session can start before any worktree exists — an empty workspace is legal. The capable agent is the coordinator; there are no federated sessions or relay pipelines.
+
+**Repo resolution — two modes, one mechanism:**
+
+- **Designated:** the task carries a `Repos:` designation. Groundcrew resolves each name against what is actually cloned under the configured base directory and provisions those worktrees up front. Any designated repo not found on disk → **bail**: skip the task with a visible "repo not found" status, provision nothing (not even the repos that do exist).
+- **Not designated:** dispatch anyway, into an empty workspace. The ticket's prose decides what happens: the agent discovers repos and acquires worktrees at runtime, or never touches a repo at all. Repo-less tasks are legal.
+- There is no `Repos: discover` marker, and v1's prose-inference (scanning descriptions for repo mentions) is dropped: explicit designation or nothing.
+
+**`knownRepositories` dies.** The repo universe is the disk under the base directory. Groundcrew never clones — provisioning is always worktree-from-local-clone. (The agent may clone repos itself if the sandbox policy allows; that is the sandbox's jurisdiction.) Accepted tradeoff, recorded honestly: the gate widens from "repos listed in config" to "anything cloned under the base directory" — mitigated by sandboxing; an optional allowlist can be layered on later without redesign.
+
+**Runtime acquisition:** the agent runs `crew repo add <repo>` in-session. The CLI applies the disk-presence gate, creates the worktree from the local clone on the uniform task branch, runs the repo's prepare-worktree hook, and records the addition in task state. Provisioning stays groundcrew's job with all guarantees intact — only the trigger moves from dispatch-time to agent-runtime.
+
+**Branch/PR topology:** a uniform task-derived branch name across every acquired worktree — the correlation key that keeps status/resume/cleanup trivial; one PR per repo as the default writeback, cross-linked to each other and the task; one artifact record per repo. A repo that needs no change simply produces no PR.
+
+**Partial failure: groundcrew does nothing but tell the truth.** Cross-repo atomicity is an explicit non-goal. Per-repo artifact records show exactly how far each repo got; merge outcomes are human/CI territory; recovery is a human action. The uniform branch plus cross-linked PRs guarantee the full blast radius is reconstructible from any one artifact.
+
+Single-repo tasks stay dead simple as the degenerate case: one designated repo, one worktree, one branch, one PR — exactly v1's shape.
+
+## 5. Completion model
+
+(Codified in the [E2E scenario catalog](https://linear.app/clipboardhealth/issue/DEVOP-5974); full statement in [the catalog, section 2](./e2e-scenario-catalog.md#2-completion-model-codified-from-iteration-1).)
+
+- **Core never polls a destination for done-ness.** No forge calls, no tracker reads to infer completion. v1's reviewer (merged-PR polling via `gh`) dies.
+- Status = **observed** workspace git facts plus **agent-reported** events and artifacts; humans judge from the agent's report.
+- `completed{outcome}` **frees the dispatch slot immediately** — a finished task never blocks the queue.
+- **The workspace lingers after completion, with two exits:** a human runs `cleanup`, or polling observes the _source_ reporting the task terminal — v1's cleaner survives unchanged because it watches the source, never the forge (this is how Linear cleanup actually worked in v1: Linear's GitHub integration moves the issue; the poll observes it). Dirty worktrees are never auto-reaped — loud skip, left for a human.
+
+## 6. Plugin boundary: task sources
+
+([Plugin packaging and review isolation](https://linear.app/clipboardhealth/issue/DEVOP-5973), informed by the [plugin-distribution research](https://linear.app/clipboardhealth/issue/DEVOP-5971): in-process npm plugins deliver no sandboxing and no real review isolation; the models that work — Terraform providers, MCP — use a versioned process boundary.)
+
+**"Plugin" means exactly one thing in v2: a task source.** Everything else that looked pluggable is config or core:
+
+- **Agent harnesses are declarative config**, not plugins: `cmd`, resume args, sandbox preferences, plus first-class `model`/`effort` fields. `cmd`-points-at-your-script is the escape hatch for odd agents.
+- **Sandbox runners are core-only**, explicitly not pluggable — a pluggable sandbox is a contradiction under sandboxed-by-default. **v2 ships exactly one runner: srt** (`sandbox-exec` on macOS, bubblewrap on Linux). Safehouse, clearance, and sbx die, including the `crew-clearance-ensure` bin.
+- **No in-process plugin class exists.** The internal `TaskSource` interface survives only as core's private representation of a discovered manifest.
+
+**Packaging:** a plugin is a **directory bundle** — `source.json` plus scripts — discovered under `~/.config/groundcrew/task-sources/<name>/` (user) or bundled in the package (first-party). The directory is the plugin: language-agnostic, no runtime loading. Distribution is deliberately not groundcrew's problem (git clone, `curl | tar`, npm postinstall). No registry or catalog in v2.0; provenance tiers collapse to `package | user`. Review isolation is met structurally: third-party code never enters the core repo and never runs in the core process.
+
+**Versioning:** `source.json` carries a required integer `protocolVersion: 1` naming the contract generation, bumped only on breaking change — capability-by-omission carries all additive change (no version sniffing: `update` absent means read-only). Parseable-but-unsupported version → explicit actionable error in discovery/doctor/status, never a silent skip; unparseable manifests keep skip-plus-warn. Core declares a supported set; v2.0 ships `{1}`. No v1 command aliases.
+
+**Sources are sandboxed by default**, under the same srt machinery as agents: deny-by-default; a source gets its install dir (read), declared secret files, declared env, stdout/stderr, and a per-source scratch dir. The manifest gains a **network egress allowlist** (e.g. `network: ["api.linear.app"]`) alongside `secrets`/`env`/`prerequisites`. Uniform across origins — bundled first-party sources run under the same policy. Per-source opt-out (`sandbox: false`) is loud in status/doctor.
+
+**Batteries included, kernel-pure code paths:** `linear`, `jira`, and `todo-txt` ship as manifest bundles crossing the same process boundary as third-party sources — first-party sources are the protocol's permanent conformance tests. The generic `shell` config-block adapter dies: bring-your-own-scripts is just a user-dir manifest.
+
+## 7. CLI surface and config
+
+([CLI surface](https://linear.app/clipboardhealth/issue/DEVOP-5975); prototype with rendered `--help` for every command on branch [`prototype/devop-5975-cli-surface`](https://github.com/ClipboardHealth/groundcrew/tree/prototype/devop-5975-cli-surface), `node --run proto:cli2 -- --tour`. Amended by [Headless extension point](https://linear.app/clipboardhealth/issue/DEVOP-5976): config field `multiplexer` → `presenter`.)
+
+### 7.1 Commands — 14 leaves (v1 had ~20)
+
+| Group      | Command                                                       | Notes                                                                                                                                                                                                                |
+| ---------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Operate    | `start [task]`                                                | Merged v1 `run`+`start`. No task = poll and dispatch eligible (`--watch` continuous); with task = dispatch that one (`--force` bypasses eligibility but never the repo-on-disk gate; `--agent` override).            |
+| Operate    | `status [task]`                                               | Absorbs `task list`/`get`. Renders **observed** git facts vs **reported** agent claims as separate layers; is the "why" affordance (section 10.4).                                                                   |
+| Operate    | `pause` / `resume`                                            | v1 `stop` renamed. `resume` reopens the _same conversation_ via captured `{{sessionId}}` where the harness exposes one (Claude Code and Codex do); falls back to `resumeArguments`; `--fresh` = new session.         |
+| Operate    | `cleanup [task\|--all]`                                       | An uncompleted task completes as `stopped`.                                                                                                                                                                          |
+| In-session | `repo add <repo>`                                             | Runtime acquisition (section 4). Renamed from `workspace add` to dodge the cmux "workspace" collision.                                                                                                               |
+| In-session | `artifact add <locator> [--kind\|--title\|--repo]`            | Agent-reported artifacts (section 3).                                                                                                                                                                                |
+| In-session | `done [--outcome delivered\|failed\|stopped] [--allow-dirty]` | Replaces `$GROUNDCREW_COMPLETE` — the prompt just says "run `crew done`". Dirty-worktree guard refuses with the dirt named unless `--allow-dirty`.                                                                   |
+| Sources    | `source list`                                                 | Discovered source bundles with origin (`package`/`user`), protocol version, and user-dir override visibility (catalog PLUGIN-01/02).                                                                                 |
+| Sources    | `source doctor`                                               | Live round-trip probe of each configured source, naming the failing source on exit 1 (catalog SURFACE-07). Absorbs v1 `source verify` and `task validate`.                                                           |
+| Setup      | `init`                                                        | Interactive 5-step: baseDirectory, agent detection, source pick, write config, run doctor. Detects a v1 `crew.config.ts` and converts it, printing every dropped/renamed key. Global by default; `--local`, `--yes`. |
+| Setup      | `doctor` / `upgrade` / `completions`                          | `doctor` is the health-check verb everywhere: `crew doctor`, `crew source doctor`.                                                                                                                                   |
+
+In-session commands are ordinary subcommands (no separate namespace). **Task identity resolution:** `--task` flag → `$GROUNDCREW_WORKSPACE` env (injected at launch) → walk up from cwd to `.groundcrew/task.json`. Exit codes: **2** = repo not cloned under `baseDirectory`, **3** = no task context.
+
+**Killed:** `open`, `task create`, `task list/get/validate`, `source install`, `interrupt`, `sandbox`, `setup`, the `crew-clearance-ensure` bin (`source verify` is renamed into `source doctor`, not killed). No `progress` command in v2.0 (the protocol event exists; add a CLI if the need shows up). No `crew migrate` — `init`'s conversion is the migration aid.
+
+**Verb families locked:** lifecycle `start → pause → resume → done`; health checks are `doctor`.
+
+### 7.2 Config — `crew.config.jsonc`
+
+- **JSONC plus a published JSON Schema** (generated from zod, referenced via `$schema`). TS config dies: a global config can't resolve the package import for its types, so it was ceremony without safety. One filename, one location rule: `~/.config/groundcrew/`, or project-local.
+- **Principle 1 — omitted = detected, specified = exactly yours, never merged.** `sources` omitted → `[{ "kind": "todo-txt" }]`; `agents` omitted → presets for CLIs on PATH (claude > codex > cursor); `presenter` omitted → first of cmux/tmux/zellij found. Listing anything replaces the detected set — disabling = not listing.
+- **Principle 2 — no secrets, structurally.** No schema field accepts a token value; manifests declare secret _names_, resolved from the parent environment, a `secrets.env` (doctor warns unless 0600), or `op run`. `GROUNDCREW_LINEAR_API_KEY` dies; the linear bundle declares `LINEAR_API_KEY` like any source. Doctor flags credential-looking strings in config.
+- Minimal legal config: `{ "workspace": { "baseDirectory": "~/dev" } }`. Worktrees default to `<baseDirectory>/.groundcrew/worktrees`. No abbreviations anywhere (`maximumInProgress`, `pollIntervalMilliseconds`, `sessionLimitPercentage`, `readOnlyDirectories`, `workingDirectory`).
+- Agent profiles get first-class `model` / `effort` / `resume` fields; presets map them to CLI flags; `{{model}}` / `{{sessionId}}` placeholders for custom commands. Per-harness session-id capture mechanics are an implementation detail under this shape.
+
+### 7.3 Setup
+
+`curl -fsSL …/install.sh | sh` → node ≥ 24 check, global npm install, exec `crew init` (`--yes` for CI/dotfiles). The script is a thin, inspectable wrapper over `npm install -g @clipboard-health/groundcrew`; that command is the direct path for anyone unwilling to pipe a remote script into a shell, and npm's registry integrity checks are the trust anchor either way. Deliberately manual forever: cloning repos, minting API keys, installing agent CLIs.
+
+## 8. Session presenter
+
+([Headless extension point](https://linear.app/clipboardhealth/issue/DEVOP-5976))
+
+**The seam is a standalone core interface: the session presenter** — presentation-only, deciding where a local, already-sandbox-wrapped agent process runs and how a human reaches it. Remote execution is permanently outside this seam: a remote runner enters via the source-contract door (`claimed` → _rejected_ arbitration), never as a presenter.
+
+**Contract — born serializable.** JSON in/out, nothing in-process, which outlaws v1's real leak (cmux `set-progress` hooks injected through the launch layer) by construction:
+
+- `open(spec)` — spec = `{name, displayName?, cwd, command, status?}`; `command` arrives fully composed, sandbox wrap included. Nesting is **presenter → sandbox → agent**; the presenter never knows about sandboxing.
+- `probe()` — live workspace list; "unavailable" is never treated as "empty".
+- `close(name)`.
+- `accessHint(name)` — how a human attaches, or nothing.
+- `setStatus(name, {text, color?, icon?})` — **optional, capability by omission** (cmux implements; tmux/zellij omit). Driven by core's run-state machine, not agent-internal hooks. v1's cmux/Claude in-sandbox hook plumbing dies with no replacement.
+
+**Packaging:** cmux/tmux/zellij ship in-core for v2.0; sources remain the only v2.0 plugin kind. Presenter _bundles_ are pre-committed as an additive v2.x kind — same manifest/process-boundary mechanics as sources but an explicitly different trust posture: presenters are inherently unsandboxable (their job is spawning the agent's pane on the host, launch command in hand), so a presenter bundle is **host-trusted like an agent CLI**, never sandbox-defaulted.
+
+**Headless = a future "detached" presenter** implementing the same contract (`open` spawns directly, `probe` is process liveness, `accessHint` returns nothing, `setStatus` omitted). v2.0 ships no detached presenter — one of cmux/tmux/zellij on PATH stays required (doctor checks). **Subagent panes: same seam, deferred** — a future presenter verb plus an in-session command routed through core; nothing outside the presenter may ever talk to a multiplexer.
+
+The fate of v1's tmux-shaped env toggles (`GROUNDCREW_TMUX_SESSION_PER_TASK`, `GROUNDCREW_KEEP_DEAD_WINDOWS`) is presenter-internal implementation detail.
+
+## 9. Architecture: one context, seven modules
+
+([Bounded-context layout](https://linear.app/clipboardhealth/issue/DEVOP-5977))
+
+### 9.1 Single bounded context
+
+One root `CONTEXT.md`, no `CONTEXT-MAP.md`. v2's real boundaries are **process seams** — the source protocol, the presenter contract, the sandbox wrap — and each carries the _same_ language across it; a source bundle translating tracker-speak into protocol-speak is an anticorruption layer living outside the repo. One team, one deployable, one language ⇒ one context.
+
+### 9.2 The core noun triple
+
+- **Workspace** — the per-task directory set: the worktrees (possibly zero) a task's agent works over. Filesystem/git facts only. v1's "Workspace = terminal pane" dies.
+- **Run** — the core-owned execution lifecycle of a claimed task: the state machine of section 3, resumeCount. One claim = one run.
+- **Session** — one live occupancy of a run: the harness process in a presenter surface, with its captured harness session-id. A run spans sessions (`pause`/`resume`; `--fresh` = new session, same run).
+
+Consequences: the session presenter presents sessions, not runs; `status` renders runs; `resume` reopens a session within a run.
+
+### 9.3 Modules
+
+| Module          | Responsibility                                                                                                                                                                             | Owns                                                           |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| **Acquisition** | Source bundle discovery, the versioned `list`/`get`/`update` process protocol, source sandboxing                                                                                           | the **source-protocol contract seam**                          |
+| **Dispatch**    | Per-tick picker: poll, eligibility, claim, provision, terminal-status sweep; persists per-task skip verdicts (section 10.4)                                                                | wiring the Writeback adapter into Run                          |
+| **Run**         | The run record: state machine, **reported layer** (`artifact add`/`done` intake), outcomes, writeback point                                                                                | the **Writeback port** (consumer-owned, defined in `src/run/`) |
+| **Workspace**   | Worktrees, branches, **observed layer** (credential-free git facts), `.groundcrew/task.json` and the task-identity resolver; typed errors that Shell maps to exit codes 2/3                | the workspace marker-file format                               |
+| **Session**     | Harness profiles (declarative), launch composition (presenter → sandbox → agent), pause/resume and session-id capture; cmux/tmux/zellij adapters in-core                                   | the **presenter contract seam**                                |
+| **Sandbox**     | Pure library: `wrap(command, policy) → command`; srt mechanics hidden; no lifecycle ownership                                                                                              | nothing pluggable — core-only by decision                      |
+| **Shell**       | commander wiring, routing (`repo add` → Workspace; `artifact add`/`done` → Run), rendering, error→exit-code mapping; `status` = read model joining Run (reported) and Workspace (observed) | —                                                              |
+
+The flow model's central invariant gets one owner per layer — **observed = Workspace, reported = Run** — so a lie or missing link is always attributable to exactly one module. Sandbox has two real callers (Session wraps agents, Acquisition wraps sources): a real seam, and the one place that keeps "sandbox runners are not pluggable" enforceable.
+
+### 9.4 Dependency graph
+
+```text
+Shell ──▶ everything (thin)
+Dispatch ──▶ Acquisition · Workspace · Session · Run
+Run ──▶ Writeback port only (Dispatch injects the adapter closed over the source)
+Session ──▶ Sandbox        Acquisition ──▶ Sandbox
+Workspace ──▶ git only     Sandbox ──▶ nothing
+```
+
+Load-bearing properties: **(a)** Run never sees Acquisition — a read-only source is a no-op handle, and Run's tests never touch discovery; **(b)** each edge module owns exactly one published contract seam; **(c)** acyclic, nothing calls upward — sources are spawned processes that answer; agents talk back only via in-session Shell commands routed downward.
+
+### 9.5 Layout
+
+```text
+CONTEXT.md            ← the one glossary
+docs/adr/             ← wayfinder resolutions seed the first ADRs
+src/
+  acquisition/ dispatch/ run/ workspace/ session/ sandbox/ shell/
+task-sources/
+  linear/ jira/ todo-txt/   ← shipped bundles, OUTSIDE src/ — no import path
+e2e/                  ← black-box suite (spawns the built binary only)
+```
+
+Conventions: **a module's interface is its `index.ts`** — the only importable path from outside; flat `src/<module>/` so path = glossary noun; colocated `*.test.ts` are intra-module and free.
+
+### 9.6 Enforcement — the graph as CI rules
+
+Extend v1's `config/dependencyCruiser.cjs` (already wired as `architecture:check`), keeping `no-circular`/`no-orphans` and adding:
+
+1. **Entry-point boundary** — imports into `src/<module>/` from outside must target `index.ts`.
+2. **The section 9.4 graph as an allowlist** — one `forbidden` rule per module encoding exactly the ratified edges; an undeclared edge fails CI naming the violated seam. The spec diagram and lint config cannot drift silently.
+3. **Process-boundary rules** — `src ↛ task-sources`, `task-sources ↛ src`, `e2e ↛ src` (the suite stays black-box).
+
+Validation step: prove the rules bite with one deliberate deep import and one undeclared edge, watch both fail, revert.
+
+### 9.7 Glossary seed for v2 `CONTEXT.md`
+
+Task · Source · Bundle · Workspace · Worktree · Run · Session · Presenter · Agent profile · Sandbox · Artifact · Writeback · Observed/Reported · Reconcile · Skip verdict — with the triple from 9.2 as the anchor definitions.
+
+## 10. Observability
+
+([Observability design](https://linear.app/clipboardhealth/issue/DEVOP-5982))
+
+**Root fork: logs are diagnostics; the run record is the truth.** "Why did/didn't X happen" is answered from the run record plus observed git facts, never by parsing logs. The run record gains a compact, versioned, append-only event history `{ts, event, detail}` covering state transitions and writeback events. Logs stay freely deletable; no log line is a compatibility surface beyond the line format itself.
+
+### 10.1 Topology
+
+One global JSON-lines file (config `logging.file`), size-based rotation (~10 MB × 3). Runs interleave; run-less events (poll ticks, reconcile, claim-rejected, doctor) share the stream. Correlation ids are the filter mechanism — no per-run files, no sink routing.
+
+### 10.2 Line schema
+
+```json
+{
+  "ts": "…Z",
+  "level": "info",
+  "module": "dispatch",
+  "event": "task_claimed",
+  "msg": "claimed DEVOP-123 from linear",
+  "taskId": "DEVOP-123",
+  "runId": "r_8f3a",
+  "source": "linear"
+}
+```
+
+- `ts` ISO-8601 UTC; `level` ∈ `debug|info|warn|error` (four, no trace/fatal); `module` ∈ the seven ratified modules — all three on every line.
+- `event`: required snake_case name, unique per call site; no dotted module prefix.
+- Correlation ids **flat at top level**, present when known: `taskId`, `runId`, `sessionId`, plus `source`/`repo` where relevant. Extra fields flat too; reserved keys enforced by the logging lib's types. `msg` optional (human lines only).
+- The cross-cutting logging lib (no eighth module) **exports a zod schema for the line format**; the E2E suite validates every emitted line against it.
+
+### 10.3 Console rendering
+
+The file sink gets everything, always. Console: `info`+ by default, human-rendered; `--verbose` = debug threshold. Raw JSON never hits the console — the file is the only JSON surface.
+
+### 10.4 The "why" affordance — no 15th command
+
+`crew status <task>` is the why affordance. It must answer three situations:
+
+1. **Ran / running** — run-record event history merged chronologically with observed git facts, observed-vs-reported layering explicit, ending with a log pointer (file path plus a ready-made jq filter on the run id).
+2. **Queued, never starts** — **spec commitment:** Dispatch persists its last-poll verdict per task id (`{skipReason, ts}` — repo missing / slots full / claim rejected) in a small dispatch-owned state map, making the flow model's "visible skip reason" promise renderable. No run record exists for unclaimed tasks, so this is the only home.
+3. **Finished / lingering** — terminal outcome, delivered vs merely observed, what `cleanup` would do.
+
+### 10.5 Reconcile and reaping
+
+**Active sweep yes, TTL no.** srt sandboxes are process-scoped — nothing standing to reap except a live agent process, and the interactive baseline forbids killing those on a timer.
+
+- **Reconcile is an idempotent library routine with two callers**: startup (the crash-safety guarantee — on-disk git/tmux/sandbox state is the source of truth, compared against expected task state; `using`/signal handlers are the graceful path only) and the dispatcher tick (every Nth poll cycle).
+- Auto-GC only the provably dead: presenter surfaces whose process exited, stale run records, clean worktrees of source-terminal tasks (the cleaner, section 5).
+- **Never auto-kill a live agent process.** Orphaned-but-running sessions are reported loudly — `warn` line plus a prominent `status` flag — and left to the human.
+
+### 10.6 Live activity finer than run-state
+
+Nothing finer ships in v2.0. Run-state drives presenter `setStatus`; the observed layer is the truthful on-demand activity signal for free. The seam is documented, not built: a future in-session `crew progress <note>` routed to Run, fanning out to presenter `setStatus` and the source `progress` event — fully additive.
+
+## 11. Migration
+
+([Migration easing](https://linear.app/clipboardhealth/issue/DEVOP-5981))
+
+**Migration easing is deferred to post-v2 handoff work** — designing conversion details against a spec that will shift during implementation is waste. The spec carries exactly two commitments:
+
+1. **5.0.0 release blocker — the `crew upgrade` ambush.** v1's `upgrade` self-updates to `@latest`; the moment 5.0.0 hits the `latest` dist-tag, every v1 user who runs `crew upgrade` gets silently major-bumped. Before publishing 5.0.0, decide a dist-tag strategy or a first-run v1 guard. (No publish happens until the E2E suite is green, so this fires late — it must not be forgotten.)
+2. **v2 fails loudly on v1-only config.** When v2 finds a v1 config (`crew.config.ts` et al.) and no v2 config, it errors with a migration pointer — never silently falls back to defaults.
+
+Everything else — `crew init` conversion detail, killed-command stubs, the migration doc, 5.0.0 release notes — moves to the handoff backlog, gated on a working v2.
+
+## 12. Implementation stack and handoff
+
+### 12.1 Stack
+
+**Plain TypeScript** ([Effect vs plain TypeScript](https://linear.app/clipboardhealth/issue/DEVOP-5972), informed by the [Effect research](https://linear.app/clipboardhealth/issue/DEVOP-5970)). Effect was rejected for now: v4-beta churn with the platform/CLI layers least stable, span-based-not-stack-based debugging against "dead simple to know what happened", and function coloring as a contributor/AI filter against pluggability.
+
+- **Public plugin/source boundary: result-shaped protocol data on one channel.** Authors emit a structured response; expected failure is a failure variant in it; a process crash or nonzero exit is mapped by the core into the _same_ failure shape.
+- **Internals: plain exceptions plus typed error classes** (native stack traces). The adapter layer is the single seam converting caught exception / nonzero exit → protocol failure. No code anywhere handles both models. neverthrow dies.
+- **Crash safety = reconcile-on-startup** (section 10.5), strictly stronger than in-process finalizers since it survives SIGKILL/OOM/power loss.
+
+| Capability             | Choice                                                    |
+| ---------------------- | --------------------------------------------------------- |
+| Retry / backoff        | p-retry                                                   |
+| Concurrency and cancel | p-limit plus AbortSignal (cooperative)                    |
+| Process spawning       | execa (deletes most of v1's 325-line `commandRunner.ts`)  |
+| Schema / config        | zod 4                                                     |
+| CLI parsing            | commander plus `@commander-js/extra-typings`              |
+| Logs                   | JSON-lines via the cross-cutting logging lib (section 10) |
+
+If Effect is ever reconsidered: gate on v4-stable, follow the opencode pattern (Effect core plus platform, skip `@effect/cli`), mandate `Effect.fn` spans from day one.
+
+### 12.2 Handoff sequence
+
+1. **Build the acceptance suite red-first from the [E2E scenario catalog](./e2e-scenario-catalog.md)** — the `e2e/` package, fixture source, scripted agent, fake `gh`, harness self-tests. This is the entry point; no v2 code before it.
+2. Fix `main`'s release automation (path/scope filter) so v2 commits don't trigger 4.x publishes (section 2).
+3. Scaffold the `v2/` workspace: seven-module skeleton, dependency-cruiser rules (section 9.6) proven to bite, `CONTEXT.md` from the glossary seed, ADRs seeded from the wayfinder resolutions.
+4. Bring the suite green module by module, porting the surviving v1 code (srtPolicy/srtLaunch, cleaner, tmux/git plumbing, doctor pieces) file-by-file with its tests.
+5. Before publishing 5.0.0: resolve the `crew upgrade` ambush (section 11) and execute the cutover (section 2).
+
+Post-v2 handoff backlog (deferred by decision): migration easing detail (section 11); presenter bundles and their trust posture (section 8); `crew progress` (section 10.6); an optional repo allowlist (section 4).
+
+## 13. Decision record
+
+Every map decision, in resolution order. Full rationale lives in the linked tickets.
+
+| Decision                                                                                     | Outcome                                                                                                                | Section |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- |
+| [Prior-art research](https://linear.app/clipboardhealth/issue/DEVOP-5969)                    | Symmetric source/sink abstractions die in practice; generalize asymmetrically (branch `research/agent-flow-prior-art`) | 3       |
+| [Plugin-distribution research](https://linear.app/clipboardhealth/issue/DEVOP-5971)          | Versioned process boundary, not in-process npm plugins (branch `research/plugin-distribution-models`)                  | 6       |
+| [Effect research](https://linear.app/clipboardhealth/issue/DEVOP-5970)                       | Effect's costs cut against the locked constraints (branch `research/effect-for-cli-orchestrator`)                      | 12.1    |
+| [Multi-repo task model](https://linear.app/clipboardhealth/issue/DEVOP-5967)                 | One session per task over a workspace of worktrees                                                                     | 4       |
+| [Flow model](https://linear.app/clipboardhealth/issue/DEVOP-5968)                            | Sinks and flows dissolve; `list`/`get`/`update` source contract; run-state machine                                     | 3       |
+| [Effect vs plain TypeScript](https://linear.app/clipboardhealth/issue/DEVOP-5972)            | Plain TypeScript; exceptions inside, result-shaped protocol at the boundary; reconcile-on-startup                      | 12.1    |
+| [Plugin packaging and review isolation](https://linear.app/clipboardhealth/issue/DEVOP-5973) | Task sources are the only plugin kind; directory bundles; `protocolVersion`; sandboxed by default; srt only            | 6       |
+| [CLI surface](https://linear.app/clipboardhealth/issue/DEVOP-5975)                           | 14 commands; `crew.config.jsonc`; install.sh → `crew init`                                                             | 7       |
+| [E2E scenario catalog](https://linear.app/clipboardhealth/issue/DEVOP-5974)                  | v2-only red-first suite; harness self-tests; completion model codified (amends the destination)                        | 5       |
+| [Headless extension point](https://linear.app/clipboardhealth/issue/DEVOP-5976)              | Session-presenter seam; headless = future detached presenter (amends CLI config: `multiplexer` → `presenter`)          | 8       |
+| [Bounded-context layout](https://linear.app/clipboardhealth/issue/DEVOP-5977)                | One context, seven modules, graph enforced by dependency-cruiser                                                       | 9       |
+| [Rewrite vs evolve](https://linear.app/clipboardhealth/issue/DEVOP-5978)                     | Rewrite in `v2/` on `main`; ships as 5.0.0                                                                             | 2       |
+| [Migration easing](https://linear.app/clipboardhealth/issue/DEVOP-5981)                      | Deferred post-v2; two spec commitments carried                                                                         | 11      |
+| [Observability design](https://linear.app/clipboardhealth/issue/DEVOP-5982)                  | Run record is the truth; one JSON-lines file; `status` is the why affordance; active sweep, no TTL                     | 10      |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.47.5",
+  "version": "4.48.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",
@@ -71,31 +71,31 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.65",
-    "@clipboard-health/clearance": "1.4.4",
-    "@linear/sdk": "88.0.0",
+    "@clipboard-health/clearance": "1.4.7",
+    "@linear/sdk": "88.1.0",
     "agent-trust": "1.0.0",
     "cosmiconfig": "9.0.2",
     "tslib": "2.8.1",
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@clipboard-health/ai-rules": "2.34.0",
-    "@clipboard-health/oxlint-config": "1.12.6",
-    "@nx/js": "22.7.6",
+    "@clipboard-health/ai-rules": "2.37.1",
+    "@clipboard-health/oxlint-config": "1.12.9",
+    "@nx/js": "22.7.7",
     "@tsconfig/node24": "24.0.4",
     "@tsconfig/strictest": "2.0.8",
     "@types/node": "25.9.5",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "4.1.10",
     "cspell": "10.0.1",
-    "dependency-cruiser": "18.0.0",
+    "dependency-cruiser": "18.1.0",
     "husky": "9.1.7",
     "jscpd": "5.0.12",
-    "knip": "6.24.0",
+    "knip": "6.27.0",
     "lint-staged": "17.0.8",
     "markdownlint-cli2": "0.23.0",
-    "nx": "22.7.6",
-    "oxfmt": "0.58.0",
+    "nx": "22.7.7",
+    "oxfmt": "0.59.0",
     "oxlint": "1.73.0",
     "oxlint-tsgolint": "0.24.0",
     "syncpack": "15.3.2",