@clipboard-health/groundcrew 4.17.0 → 4.18.0

package/README.md

@@ -114,6 +114,9 @@ import type { Config } from "@clipboard-health/groundcrew";
 export default {
   workspace: {
     projectDir: "~/dev",
+    // Optional: all worktrees go here regardless of where each repo lives.
+    // worktreeDir: "~/dev/worktrees",
+    // Strings live under projectDir; use { name, projectDirOverride } to override per repo.
     knownRepositories: ["OWNER/REPO"],
   },
   models: {
@@ -131,6 +134,11 @@ export default {
 } satisfies Config;
 ```
 
+Changing `workspace.worktreeDir` only affects worktrees discovered under the new
+root. Clean up existing worktrees before switching it, or temporarily unset
+`worktreeDir` when you need `crew cleanup` to find worktrees created beside the
+repos.
+
 There is no `linear` config block. Groundcrew reads `GROUNDCREW_LINEAR_API_KEY` first, then falls back to `LINEAR_API_KEY`.
 
 ## Reference

package/crew.config.example.ts

@@ -13,12 +13,17 @@ export default {
   // Opt a ticket in: assign it to yourself and add an `agent-<model>`
   // label (e.g. `agent-claude`, `agent-any`).
   workspace: {
-    // Parent directory under which groundcrew clones repositories and
-    // creates per-ticket worktrees.
+    // Parent directory under which groundcrew clones repositories and (by
+    // default) creates per-ticket worktrees.
     projectDir: "~/dev/groundcrew",
+    // Optional: collect ALL worktrees here instead of beside each repo. Useful
+    // when your repos live in more than one place. Defaults to projectDir.
+    // worktreeDir: "~/dev/worktrees",
     // Repositories groundcrew is allowed to set up worktrees in. Add
-    // `<owner>/<repo>` or bare `<repo>` entries; the orchestrator scopes
-    // tickets to these and refuses unknown repos by default.
+    // `<owner>/<repo>` or bare `<repo>` strings; the orchestrator scopes
+    // tickets to these and refuses unknown repos by default. Use the object
+    // form to point a repo at a different parent directory:
+    //   { name: "other-org/other-repo", projectDirOverride: "~/work" }
     knownRepositories: ["your-org/your-repo"],
   },
   models: {
@@ -63,6 +68,9 @@ export default {
   //       inReview: ["Code Review"],
   //     },
   //   },
+  //   // Optional: disable the built-in Linear source entirely for shell-only
+  //   // setups (no Linear API key needed). Replaces the block above.
+  //   // { kind: "linear", enabled: false },
   //   {
   //     kind: "shell",
   //     name: "jira",

package/dist/cli.js

@@ -17,7 +17,7 @@ const REMOVED_SANDBOX_COMMAND_MESSAGE = [
 const requireFromCli = createRequire(import.meta.url);
 const SETUP_REPOS_REMOVED_MESSAGE = [
     "crew setup repos was removed.",
-    "Clone repositories manually with git clone into workspace.projectDir.",
+    "Clone repositories manually with git clone into workspace.projectDir (or each repo's workspace.knownRepositories `projectDirOverride`).",
     "See README.md#manual-repository-bootstrap for the replacement workflow.",
 ].join(" ");
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8KH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAgF/C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+KH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAmF/C"}

package/dist/commands/doctor.js

@@ -5,7 +5,7 @@
 import { existsSync, statSync } from "node:fs";
 import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
-import { loadConfigWithSource, } from "../lib/config.js";
+import { loadConfigWithSource, worktreeBaseDir, } from "../lib/config.js";
 import { detectHostCapabilities, which } from "../lib/host.js";
 import { resolveLocalRunner } from "../lib/localRunner.js";
 import { gatedModels } from "../lib/usage.js";
@@ -184,6 +184,9 @@ export async function doctor() {
         await checkCmd("git", true, "https://git-scm.com/"),
         ...(await workspaceChecks(workspaceOutcome)),
         checkDir(config.workspace.projectDir, "workspace.projectDir"),
+        ...(config.workspace.worktreeDir === undefined
+            ? []
+            : [checkDir(worktreeBaseDir(config), "workspace.worktreeDir")]),
         localCapability,
     ];
     const toolTargets = gatherToolTargets(config);

package/dist/lib/adapters/linear/schema.d.ts

@@ -7,6 +7,7 @@
 import { z } from "zod";
 export declare const linearAdapterConfigSchema: z.ZodObject<{
     kind: z.ZodLiteral<"linear">;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     name: z.ZodOptional<z.ZodString>;
     statuses: z.ZodOptional<z.ZodObject<{
         inProgress: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/lib/adapters/linear/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/linear/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,yBAAyB;;;;;;;iBAYpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/linear/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,yBAAyB;;;;;;;;iBAkBpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/lib/adapters/linear/schema.js

@@ -8,6 +8,12 @@ import { z } from "zod";
 const statusNamesSchema = z.array(z.string().trim().min(1)).min(1);
 export const linearAdapterConfigSchema = z.object({
     kind: z.literal("linear"),
+    /**
+     * Opt-out sentinel. Set `enabled: false` to disable the built-in Linear
+     * source entirely (no adapter is constructed, no API key required) — see
+     * `sourcesFromConfig` in buildSources.ts. Omitted/`true` keeps Linear active.
+     */
+    enabled: z.boolean().optional(),
     name: z
         .string()
         .regex(/^[a-z][a-z0-9-]*$/, "name must be kebab-case (lowercase letters, digits, hyphens)")

package/dist/lib/buildSources.d.ts

@@ -22,9 +22,15 @@ export declare function buildSourcesWith(registry: Record<string, AdapterDefinit
  * implicit Linear source (Linear is always active under the post-#110
  * model — viewer + agent-* label filtering happens at the GraphQL layer)
  * and appends any user-declared `sources`. The implicit source is omitted
- * when the user already declared a Linear source (by `kind` or by runtime
- * name "linear") so they can override its `name` / construction without
- * spawning a duplicate adapter.
+ * when the user already declared a Linear source — by `kind: "linear"`, or by
+ * a surviving (non-disabled) source whose runtime name is "linear" — so they
+ * can override its `name` / construction without spawning a duplicate adapter.
+ *
+ * Users opt out of Linear entirely with the sentinel
+ * `{ kind: "linear", enabled: false }`: it still counts as an explicit Linear
+ * declaration (so the implicit source is suppressed) and is itself filtered
+ * out (so no Linear adapter is constructed and no API key is required). Any
+ * other source with `enabled: false` is likewise dropped from the result.
  */
 export declare function sourcesFromConfig(config: ResolvedConfig): readonly unknown[];
 //# sourceMappingURL=buildSources.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"buildSources.d.ts","sourceRoot":"","sources":["../../src/lib/buildSources.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CAGzB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC3C,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,YAAY,EAAE,CAchB;AA6BD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,OAAO,EAAE,CAM5E"}
+{"version":3,"file":"buildSources.d.ts","sourceRoot":"","sources":["../../src/lib/buildSources.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CAGzB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC3C,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,OAAO,EAAE,cAAc,GACtB,YAAY,EAAE,CAchB;AA6DD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,OAAO,EAAE,CAa5E"}

package/dist/lib/buildSources.js

@@ -35,7 +35,40 @@ export function buildSourcesWith(registry, rawConfigs, context) {
 const sourceShape = z.looseObject({
     name: z.string().optional(),
     kind: z.string().optional(),
+    enabled: z.boolean().optional(),
 });
+/**
+ * Read the structural `name` / `kind` / `enabled` fields off a raw source.
+ * `looseObject()` with all-optional fields only fails to parse non-object
+ * inputs (null, primitives); those are rejected downstream by the per-adapter
+ * Zod schema in buildSourcesWith, so we treat a non-object entry as an empty
+ * field set ("no opinion") rather than branching on it at every call site.
+ */
+function sourceFields(raw) {
+    const parsed = sourceShape.safeParse(raw);
+    /* v8 ignore next 3 @preserve -- non-object inputs never reach here in practice (see above); the guard exists only for type-narrowing. */
+    if (!parsed.success) {
+        return {};
+    }
+    return parsed.data;
+}
+/**
+ * True when `raw` carries the opt-out sentinel `enabled: false`. Used to drop
+ * a source the user explicitly disabled — most importantly a
+ * `{ kind: "linear", enabled: false }` entry — so its adapter is never
+ * constructed.
+ */
+function isSourceDisabled(raw) {
+    return sourceFields(raw).enabled === false;
+}
+/**
+ * True when `raw` declares `kind: "linear"`, regardless of `name` or `enabled`.
+ * This is what lets the `{ kind: "linear", enabled: false }` opt-out suppress
+ * the implicit Linear source even though the entry itself is filtered out.
+ */
+function isLinearKindSource(raw) {
+    return sourceFields(raw).kind === "linear";
+}
 /**
  * True when `raw` is an explicitly-declared Linear source. Matches either a
  * `kind: "linear"` entry — regardless of any `name` override — or any entry
@@ -50,26 +83,34 @@ const sourceShape = z.looseObject({
  * downstream.
  */
 function isExplicitLinearSource(raw) {
-    const parsed = sourceShape.safeParse(raw);
-    /* v8 ignore next 3 @preserve -- looseObject() with all-optional fields only fails to parse non-object inputs (null, primitives); the same input would be rejected by the per-adapter Zod schema in buildSourcesWith, so this guard never fires in practice. */
-    if (!parsed.success) {
-        return false;
-    }
-    return parsed.data.kind === "linear" || (parsed.data.name ?? parsed.data.kind) === "linear";
+    const { kind, name } = sourceFields(raw);
+    return kind === "linear" || (name ?? kind) === "linear";
 }
 /**
  * Build the runtime source list from a ResolvedConfig: synthesizes the
  * implicit Linear source (Linear is always active under the post-#110
  * model — viewer + agent-* label filtering happens at the GraphQL layer)
  * and appends any user-declared `sources`. The implicit source is omitted
- * when the user already declared a Linear source (by `kind` or by runtime
- * name "linear") so they can override its `name` / construction without
- * spawning a duplicate adapter.
+ * when the user already declared a Linear source — by `kind: "linear"`, or by
+ * a surviving (non-disabled) source whose runtime name is "linear" — so they
+ * can override its `name` / construction without spawning a duplicate adapter.
+ *
+ * Users opt out of Linear entirely with the sentinel
+ * `{ kind: "linear", enabled: false }`: it still counts as an explicit Linear
+ * declaration (so the implicit source is suppressed) and is itself filtered
+ * out (so no Linear adapter is constructed and no API key is required). Any
+ * other source with `enabled: false` is likewise dropped from the result.
  */
 export function sourcesFromConfig(config) {
-    const hasExplicitLinear = config.sources.some(isExplicitLinearSource);
+    const kept = config.sources.filter((source) => !isSourceDisabled(source));
+    // A `kind: "linear"` entry suppresses the implicit source even when it is the
+    // disabled opt-out sentinel — it's removed from `kept` above, leaving Linear
+    // off entirely. A source that's Linear only by *name* (e.g. a shell source
+    // named "linear") suppresses the implicit source only while it survives the
+    // filter, so disabling such an entry doesn't silently drop Linear.
+    const hasExplicitLinear = config.sources.some(isLinearKindSource) || kept.some(isExplicitLinearSource);
     if (hasExplicitLinear) {
-        return [...config.sources];
+        return kept;
     }
-    return [{ kind: "linear" }, ...config.sources];
+    return [{ kind: "linear" }, ...kept];
 }

package/dist/lib/config.d.ts

@@ -127,6 +127,15 @@ type UserModelDefinition = EnabledUserModelDefinition;
  * Linear's default "In Progress" / "In Review" status names disambiguate
  * `started` workflow states; unmatched statuses fall back to `state.type`.
  */
+/**
+ * A configured repository. The bare-string form keeps the repo under
+ * `workspace.projectDir`; the object form's optional `projectDirOverride`
+ * overrides that parent directory so repos can live in more than one place.
+ */
+export interface KnownRepository {
+    name: string;
+    projectDirOverride?: string;
+}
 export interface Config {
     /**
      * Additional pluggable ticket sources beyond the built-in Linear adapter
@@ -135,6 +144,11 @@ export interface Config {
      * an external system (Jira, plan-keeper, etc.) by pointing at command
      * templates that emit/consume JSON.
      *
+     * The implicit Linear source can be turned off with the opt-out sentinel
+     * `{ kind: "linear", enabled: false }` — useful for shell-only setups with
+     * no Linear API key, where a failing Linear probe would otherwise take down
+     * the whole queue.
+     *
      * Per-source Zod validation runs at `buildSources` time — config.ts only
      * verifies the structural shape (array of objects with a string `kind`).
      */
@@ -151,7 +165,12 @@ export interface Config {
     };
     workspace: {
         projectDir: string;
-        knownRepositories: string[];
+        /**
+         * Parent directory all per-ticket worktrees are created under. Defaults
+         * to `projectDir` when unset, so single-directory setups are unchanged.
+         */
+        worktreeDir?: string;
+        knownRepositories: (string | KnownRepository)[];
     };
     defaults?: {
         hooks?: HookCommands;
@@ -216,7 +235,12 @@ export interface ResolvedConfig {
     };
     workspace: {
         projectDir: string;
+        /** Resolved worktree root; unset means "use projectDir". */
+        worktreeDir?: string;
+        /** Repository names only — the union's `projectDirOverride`s are lifted out. */
         knownRepositories: string[];
+        /** name -> resolved parent dir, only for entries that override projectDir. */
+        repositoryDirs?: Record<string, string>;
     };
     defaults: {
         hooks: HookCommands;
@@ -250,6 +274,17 @@ export interface ResolvedConfig {
         file: string;
     };
 }
+/**
+ * Parent directory under which a repository's clone lives. The per-repo
+ * `projectDirOverride` wins; otherwise repos sit under `projectDir`.
+ */
+export declare function repositoryBaseDir(config: ResolvedConfig, repository: string): string;
+/**
+ * Parent directory all worktrees are created under, independent of where the
+ * source repositories live. Falls back to `projectDir` when `worktreeDir` is
+ * unset.
+ */
+export declare function worktreeBaseDir(config: ResolvedConfig): string;
 export type ConfigSourceKind = "env" | "project" | "xdg";
 export interface ConfigSource {
     kind: ConfigSourceKind;

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":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAMrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AAEpE,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5D,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAIzD,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,MAAM,CAAC;AAEtD,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAMrD,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QACN,QAAQ,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACjD,CAAC;IACF;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,KAAK,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC;AAC/D,KAAK,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,GAAG;IAC1E,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AACF,KAAK,mBAAmB,GAAG,0BAA0B,CAAC;AAEtD;;;;;;;;;GASG;AACH;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,MAAM;IACrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB;;;;WAIG;QACH,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,SAAS,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB;;;WAGG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,CAAC,MAAM,GAAG,eAAe,CAAC,EAAE,CAAC;KACjD,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,YAAY,CAAC;KACtB,CAAC;IACF,YAAY,CAAC,EAAE;QACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,sBAAsB,CAAC,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB;;;;;WAKG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;KACnD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF;;;;OAIG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC;;;;OAIG;IACH,KAAK,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,kBAAkB,CAAC;KAC7B,CAAC;IACF,OAAO,CAAC,EAAE;QACR;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,GAAG,EAAE;QACH,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,SAAS,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,4DAA4D;QAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gFAAgF;QAChF,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,8EAA8E;QAC9E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACzC,CAAC;IACF,QAAQ,EAAE;QACR,KAAK,EAAE,YAAY,CAAC;KACrB,CAAC;IACF,YAAY,EAAE;QACZ,iBAAiB,EAAE,MAAM,CAAC;QAC1B,wBAAwB,EAAE,MAAM,CAAC;QACjC,sBAAsB,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;KAC9C,CAAC;IACF,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF;;;OAGG;IACH,aAAa,EAAE,oBAAoB,CAAC;IACpC;;;;OAIG;IACH,KAAK,EAAE;QACL,MAAM,EAAE,kBAAkB,CAAC;KAC5B,CAAC;IACF,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAE9D;AAED,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IACjC,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;CAChC;AAsND;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,GAAG,OAAO,CAE1F;AA6FD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,EACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAKT;AA+fD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CA2B5E;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAGpE"}

package/dist/lib/config.js

@@ -27,6 +27,21 @@ export const LOCAL_RUNNER_SETTINGS = [
     "sdx",
     "none",
 ];
+/**
+ * Parent directory under which a repository's clone lives. The per-repo
+ * `projectDirOverride` wins; otherwise repos sit under `projectDir`.
+ */
+export function repositoryBaseDir(config, repository) {
+    return config.workspace.repositoryDirs?.[repository] ?? config.workspace.projectDir;
+}
+/**
+ * Parent directory all worktrees are created under, independent of where the
+ * source repositories live. Falls back to `projectDir` when `worktreeDir` is
+ * unset.
+ */
+export function worktreeBaseDir(config) {
+    return config.workspace.worktreeDir ?? config.workspace.projectDir;
+}
 const DEFAULT_GIT = {
     remote: "origin",
     defaultBranch: "main",
@@ -428,6 +443,65 @@ function normalizeSources(raw) {
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- structural validation above guarantees array of {kind: string} entries; per-source Zod validation lives in buildSources
     return raw;
 }
+/**
+ * Resolve one `knownRepositories` entry to its name and (optional) resolved
+ * base dir. Bare strings live under `projectDir`; the object form's
+ * `projectDirOverride` overrides that parent directory. This is the seam later
+ * per-repo options hang off — add new `KnownRepository` fields here.
+ */
+function normalizeKnownRepository(entry, index) {
+    if (typeof entry === "string") {
+        return { name: entry };
+    }
+    requireObject(entry, `workspace.knownRepositories[${index}]`);
+    requireString(entry.name, `workspace.knownRepositories[${index}].name`);
+    if (entry.projectDirOverride === undefined) {
+        return { name: entry.name };
+    }
+    requireString(entry.projectDirOverride, `workspace.knownRepositories[${index}].projectDirOverride`);
+    return { name: entry.name, projectDirOverride: expandHome(entry.projectDirOverride) };
+}
+/**
+ * Flatten the loose `(string | KnownRepository)[]` union into the strict
+ * resolved shape: a `string[]` of names every downstream consumer reads, plus
+ * a separate `repositoryDirs` map holding only the entries that override
+ * `projectDir`. Types are validated here, at the resolution edge, before any
+ * `expandHome` runs (which would otherwise throw a raw TypeError on a
+ * non-string `worktreeDir`).
+ */
+function normalizeWorkspace(workspace) {
+    requireObject(workspace, "workspace");
+    requireString(workspace.projectDir, "workspace.projectDir");
+    // Track the first index each name was seen at so a duplicate (which would
+    // silently overwrite its `projectDirOverride` in `repositoryDirs`) fails
+    // loudly instead of resolving order-dependently.
+    const seen = new Map();
+    const repositoryDirs = {};
+    const entries = Array.isArray(workspace.knownRepositories) ? workspace.knownRepositories : [];
+    entries.forEach((entry, index) => {
+        const { name, projectDirOverride } = normalizeKnownRepository(entry, index);
+        const previous = seen.get(name);
+        if (previous !== undefined) {
+            fail(`workspace.knownRepositories[${index}] duplicates ${JSON.stringify(name)} from workspace.knownRepositories[${previous}]. Configure distinct repository names.`);
+        }
+        seen.set(name, index);
+        if (projectDirOverride !== undefined) {
+            repositoryDirs[name] = projectDirOverride;
+        }
+    });
+    const names = [...seen.keys()];
+    let worktreeDir;
+    if (workspace.worktreeDir !== undefined) {
+        requireString(workspace.worktreeDir, "workspace.worktreeDir");
+        worktreeDir = expandHome(workspace.worktreeDir);
+    }
+    return {
+        projectDir: expandHome(workspace.projectDir),
+        ...(worktreeDir === undefined ? {} : { worktreeDir }),
+        knownRepositories: names,
+        ...(Object.keys(repositoryDirs).length === 0 ? {} : { repositoryDirs }),
+    };
+}
 function applyDefaults(user) {
     // Guard the top-level shape before reading nested fields, so a
     // malformed runtime config produces a `groundcrew config: ...` error
@@ -458,10 +532,7 @@ function applyDefaults(user) {
             ...user.git,
             ...(branchPrefix === undefined ? {} : { branchPrefix }),
         },
-        workspace: {
-            projectDir: expandHome(user.workspace.projectDir),
-            knownRepositories: user.workspace.knownRepositories,
-        },
+        workspace: normalizeWorkspace(user.workspace),
         defaults: normalizeDefaults(user.defaults),
         orchestrator: { ...DEFAULT_ORCHESTRATOR, ...user.orchestrator },
         models: {

package/dist/lib/srtLaunch.d.ts

@@ -1,4 +1,4 @@
-import type { ModelDefinition, ResolvedConfig } from "./config.ts";
+import { type ModelDefinition, type ResolvedConfig } from "./config.ts";
 export interface StagedSrtLaunch {
     /** Dedicated temp dir holding the settings files (and any relocated config home). */
     directory: string;

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

@@ -1 +1 @@
-{"version":3,"file":"srtLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/srtLaunch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKnE,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,eAAe,CAAC;IAC5B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,eAAe,CA8ClB"}
+{"version":3,"file":"srtLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/srtLaunch.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAqB,MAAM,aAAa,CAAC;AAK3F,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,eAAe,CAAC;IAC5B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,eAAe,CA8ClB"}

package/dist/lib/srtLaunch.js

@@ -2,6 +2,7 @@ import { copyFileSync, existsSync, mkdirSync, mkdtempSync, writeFileSync } from
 import os from "node:os";
 import path from "node:path";
 import { collectAllowedDomains } from "./clearanceHosts.js";
+import { repositoryBaseDir } from "./config.js";
 import { inferAgentCommandName } from "./launchCommand.js";
 import { agentConfigRelocation, buildSrtSettings } from "./srtPolicy.js";
 import { readEnvironmentVariable } from "./util.js";
@@ -27,7 +28,7 @@ import { readEnvironmentVariable } from "./util.js";
 export function buildAndStageSrtLaunch(input) {
     const agent = inferAgentCommandName(input.definition.cmd);
     const homeDir = input.homeDir ?? os.homedir();
-    const repoDir = path.resolve(input.config.workspace.projectDir, input.repository);
+    const repoDir = path.resolve(repositoryBaseDir(input.config, input.repository), input.repository);
     const base = {
         worktreeDir: input.worktreeDir,
         gitCommonDir: path.join(repoDir, ".git"),

package/dist/lib/worktrees.d.ts

@@ -1,13 +1,14 @@
 /**
  * Worktree lifecycle — manages host git worktrees for tickets.
  *
- * A worktree is a `git worktree add`'d sibling at
- * `<projectDir>/<repo>-<TICKET>/`. Callers go through the `worktrees`
- * namespace; the module owns creation, listing, removal, and teardown
- * (workspace-close + worktree-remove paired) so callers don't reach into
- * git directly.
+ * A worktree is a `git worktree add`'d directory at
+ * `<worktreeDir>/<repo>-<TICKET>/` (where `worktreeDir` defaults to
+ * `projectDir`). The source repo it is cut from may live under a different
+ * per-repo `projectDirOverride`. Callers go through the `worktrees` namespace;
+ * the module owns creation, listing, removal, and teardown (workspace-close +
+ * worktree-remove paired) so callers don't reach into git directly.
  */
-import type { ResolvedConfig } from "./config.ts";
+import { type ResolvedConfig } from "./config.ts";
 import { type WorkspaceProbe } from "./workspaces.ts";
 export type WorktreeKind = "host";
 export declare class WorktreeAlreadyExistsError extends Error {

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

@@ -1 +1 @@
-{"version":3,"file":"worktrees.d.ts","sourceRoot":"","sources":["../../src/lib/worktrees.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,KAAK,cAAc,EAAc,MAAM,iBAAiB,CAAC;AAIlE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAgB,GAAG,EAAE,MAAM,CAAC;IAE5B,YAAmB,GAAG,EAAE,MAAM,EAI7B;CACF;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAEhG;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAkBD,iBAAS,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3E;AAmQD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAiHxB,iBAAS,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,EAAE,CAErD;AAED,iBAAS,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAE7E;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,wDAAwD;IACxD,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAyBD,iBAAe,QAAQ,CACrB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAiDzB;AAED,iBAAe,gBAAgB,CAAC,KAAK,EAAE;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE7B;AAED,eAAO,MAAM,SAAS;;;;;;;;CAQrB,CAAC"}
+{"version":3,"file":"worktrees.d.ts","sourceRoot":"","sources":["../../src/lib/worktrees.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,EAAE,KAAK,cAAc,EAAsC,MAAM,aAAa,CAAC;AAGtF,OAAO,EAAE,KAAK,cAAc,EAAc,MAAM,iBAAiB,CAAC;AAIlE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAgB,GAAG,EAAE,MAAM,CAAC;IAE5B,YAAmB,GAAG,EAAE,MAAM,EAI7B;CACF;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAEhG;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAkBD,iBAAS,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3E;AAgQD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAiHxB,iBAAS,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,EAAE,CAErD;AAED,iBAAS,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAE7E;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,YAAY,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED,iBAAe,MAAM,CACnB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,wDAAwD;IACxD,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC;AAyBD,iBAAe,QAAQ,CACrB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAiDzB;AAED,iBAAe,gBAAgB,CAAC,KAAK,EAAE;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE7B;AAED,eAAO,MAAM,SAAS;;;;;;;;CAQrB,CAAC"}

package/dist/lib/worktrees.js

@@ -1,16 +1,18 @@
 /**
  * Worktree lifecycle — manages host git worktrees for tickets.
  *
- * A worktree is a `git worktree add`'d sibling at
- * `<projectDir>/<repo>-<TICKET>/`. Callers go through the `worktrees`
- * namespace; the module owns creation, listing, removal, and teardown
- * (workspace-close + worktree-remove paired) so callers don't reach into
- * git directly.
+ * A worktree is a `git worktree add`'d directory at
+ * `<worktreeDir>/<repo>-<TICKET>/` (where `worktreeDir` defaults to
+ * `projectDir`). The source repo it is cut from may live under a different
+ * per-repo `projectDirOverride`. Callers go through the `worktrees` namespace;
+ * the module owns creation, listing, removal, and teardown (workspace-close +
+ * worktree-remove paired) so callers don't reach into git directly.
  */
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { userInfo } from "node:os";
 import path from "node:path";
 import { runCommandAsync } from "./commandRunner.js";
+import { repositoryBaseDir, worktreeBaseDir } from "./config.js";
 import { resolveDefaultBranch } from "./defaultBranch.js";
 import { debug, errorMessage, isVerbose } from "./util.js";
 import { workspaces } from "./workspaces.js";
@@ -46,7 +48,7 @@ function repoDirFor(config, repository) {
     if (!config.workspace.knownRepositories.includes(repository)) {
         throw new Error(`Repository "${repository}" is not in workspace.knownRepositories: ${config.workspace.knownRepositories.join(", ")}`);
     }
-    const repoDir = path.resolve(config.workspace.projectDir, repository);
+    const repoDir = path.resolve(repositoryBaseDir(config, repository), repository);
     if (!existsSync(repoDir)) {
         throw new Error(`Repository not found: ${repoDir}`);
     }
@@ -59,12 +61,10 @@ function basePaths(config, repository, ticket) {
     if (!TICKET_RE.test(ticket)) {
         throw new Error(`Invalid ticket "${ticket}": must be a plain ticket id`);
     }
-    const projectDir = path.resolve(config.workspace.projectDir);
     const repoDir = repoDirFor(config, repository);
     const hostWorktreeName = `${repository}-${ticket}`;
-    const hostWorktreeDir = path.resolve(projectDir, hostWorktreeName);
+    const hostWorktreeDir = path.resolve(worktreeBaseDir(config), hostWorktreeName);
     return {
-        projectDir,
         repoDir,
         ticket,
         branchName: branchNameForTicket(config, ticket),
@@ -126,17 +126,18 @@ async function createWorktree(config, spec, signal) {
     };
 }
 function listWorktrees(config) {
-    const projectDir = path.resolve(config.workspace.projectDir);
+    const worktreeRoot = path.resolve(worktreeBaseDir(config));
     const entries = [];
-    // Worktrees live at `projectDir/<repository>-<ticket>`. When `repository`
+    // Worktrees live at `worktreeRoot/<repository>-<ticket>`. When `repository`
     // contains a slash (e.g. "owner/repo"), `path.resolve()` nests one level
-    // deeper, so the worktree path is `projectDir/owner/repo-<ticket>`.
-    // Scan each known repository's parent directory rather than the project
-    // root, so nested worktrees are discovered alongside bare ones.
+    // deeper, so the worktree path is `worktreeRoot/owner/repo-<ticket>`.
+    // Scan each known repository's parent directory under the worktree root
+    // rather than the root itself, so nested worktrees are discovered alongside
+    // bare ones.
     const reposByParent = new Map();
     for (const repository of config.workspace.knownRepositories) {
         const lastSlash = repository.lastIndexOf("/");
-        const parentDir = lastSlash === -1 ? projectDir : path.resolve(projectDir, repository.slice(0, lastSlash));
+        const parentDir = lastSlash === -1 ? worktreeRoot : path.resolve(worktreeRoot, repository.slice(0, lastSlash));
         const basename = lastSlash === -1 ? repository : repository.slice(lastSlash + 1);
         let repoByBasename = reposByParent.get(parentDir);
         if (repoByBasename === undefined) {
@@ -182,8 +183,7 @@ function listWorktrees(config) {
     return entries;
 }
 async function removeWorktree(config, entry, options) {
-    const projectDir = path.resolve(config.workspace.projectDir);
-    const repoDir = path.resolve(projectDir, entry.repository);
+    const repoDir = path.resolve(repositoryBaseDir(config, entry.repository), entry.repository);
     if (existsSync(entry.dir)) {
         debug(`Removing worktree ${entry.dir}${options.force ? " (--force)" : ""}...`);
         const removeArguments = ["-C", repoDir, "worktree", "remove"];
@@ -317,7 +317,7 @@ function describeOrphanWorktree(arguments_) {
     return `directory exists but is not a registered git worktree. Run \`crew cleanup --force ${ticket}\` to remove ${dir}, or inspect it first if it may contain valuable files.`;
 }
 function expectedHostWorktreeDir(config, entry) {
-    return path.resolve(config.workspace.projectDir, `${entry.repository}-${entry.ticket}`);
+    return path.resolve(worktreeBaseDir(config), `${entry.repository}-${entry.ticket}`);
 }
 function isInsideDirectory(parentDir, childDir) {
     const childRelativePath = path.relative(parentDir, childDir);
@@ -326,10 +326,10 @@ function isInsideDirectory(parentDir, childDir) {
         !path.isAbsolute(childRelativePath));
 }
 function removeOrphanWorktreeDirectory(config, entry) {
-    const projectDir = path.resolve(config.workspace.projectDir);
+    const worktreeRoot = path.resolve(worktreeBaseDir(config));
     const expectedDir = expectedHostWorktreeDir(config, entry);
     const targetDir = path.resolve(entry.dir);
-    if (targetDir !== expectedDir || !isInsideDirectory(projectDir, targetDir)) {
+    if (targetDir !== expectedDir || !isInsideDirectory(worktreeRoot, targetDir)) {
         throw new Error(`Refusing to force-delete ${entry.dir}: expected groundcrew worktree path ${expectedDir}.`);
     }
     debug(`Removing orphaned worktree directory ${entry.dir} (--force)...`);

package/docs/configuration.md

@@ -4,7 +4,8 @@ Workspace settings and at least one enabled model are required; everything else
 
 | Key                           | What                                                                   |
 | ----------------------------- | ---------------------------------------------------------------------- |
-| `workspace.projectDir`        | Parent dir for cloned repos and sibling ticket worktrees.              |
+| `workspace.projectDir`        | Parent dir for cloned repos and the default ticket worktree root.      |
+| `workspace.worktreeDir`       | Optional parent dir for ticket worktrees.                              |
 | `workspace.knownRepositories` | Repos searched for in ticket descriptions to infer where work belongs. |
 | `models.definitions`          | Enabled model set. Built-in presets can be enabled with `{}`.          |
 
@@ -12,7 +13,10 @@ The branch prefix (`<prefix>-<TICKET>`) defaults to `os.userInfo().username`; ov
 
 ## Repository Layout
 
-Groundcrew never clones repositories for you. `crew init --repo OWNER/REPO` prints the clone command to run. If you are cloning manually, clone each `workspace.knownRepositories` entry into `workspace.projectDir` using the same relative path the config uses.
+Groundcrew never clones repositories for you. `crew init --repo OWNER/REPO`
+prints the clone command to run. If you are cloning manually, clone each string
+`workspace.knownRepositories` entry into `workspace.projectDir` using the same
+relative path the config uses.
 
 ```bash
 PROJECT_DIR="$HOME/dev"
@@ -20,7 +24,18 @@ mkdir -p "$PROJECT_DIR/OWNER"
 git clone git@github.com:OWNER/REPO.git "$PROJECT_DIR/OWNER/REPO"
 ```
 
-Bare-name entries have no owner, so pick the remote URL yourself and clone to `$PROJECT_DIR/<name>`.
+Bare-name entries have no owner, so pick the remote URL yourself and clone to
+`$PROJECT_DIR/<name>`. To keep a repo clone somewhere else, use
+`{ name: "OWNER/REPO", projectDirOverride: "~/other" }` and clone it under that
+parent dir.
+
+By default, ticket worktrees are created beside the repos under
+`workspace.projectDir`. Set `workspace.worktreeDir` to collect worktrees under a
+separate root, regardless of where each source repo clone lives. Changing
+`workspace.worktreeDir` only affects worktrees discovered under the new root.
+Clean up existing worktrees before switching it, or temporarily unset
+`worktreeDir` when you need `crew cleanup` to find worktrees created beside the
+repos.
 
 ## Config Discovery
 
@@ -68,6 +83,23 @@ export default {
 
 Configured names replace the default for that status; omitted fields keep their defaults. Matching is case-insensitive and trims surrounding whitespace.
 
+Linear is implicit-on, but you can turn it off entirely with the opt-out sentinel `{ kind: "linear", enabled: false }`. This suppresses the built-in Linear source so no adapter is constructed and no API key is required — useful for shell-only setups, where a failing Linear probe would otherwise mark the whole queue unavailable:
+
+```ts
+export default {
+  sources: [
+    { kind: "linear", enabled: false },
+    {
+      kind: "shell",
+      name: "plans",
+      commands: {
+        fetch: "~/.config/groundcrew/plans-fetch.sh",
+      },
+    },
+  ],
+};
+```
+
 ## Enabling Model Presets
 
 Groundcrew ships built-in presets for `claude` and `codex`, but models are not enabled by default. List the models you want in `models.definitions`:
@@ -148,12 +180,13 @@ and hook contract.
 
 | Key                                      | Default              | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ---------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `sources`                                | `[]`                 | Additional pluggable ticket sources, dispatched alongside the built-in Linear adapter. Built-in kinds: `shell`, `linear`. Declare `{ kind: "linear", statuses: { ... } }` only to override Linear status names used for `in-progress` / `in-review` disambiguation.                                                                                                                                                                                                                                                         |
+| `sources`                                | `[]`                 | Additional pluggable ticket sources, dispatched alongside the built-in Linear adapter. Built-in kinds: `shell`, `linear`. Declare `{ kind: "linear", statuses: { ... } }` only to override Linear status names used for `in-progress` / `in-review` disambiguation. Disable the implicit Linear source with `{ kind: "linear", enabled: false }` (no API key required) — useful for shell-only setups.                                                                                                                      |
 | `git.remote`                             | `"origin"`           | Remote used for `fetch` and as the worktree base ref.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `git.defaultBranch`                      | `"main"`             | Branch fetched from `git.remote` and used as the worktree base.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `git.branchPrefix`                       | OS username          | Prefix groundcrew puts before the ticket id when naming a worktree branch (`<branchPrefix>-<ticket>`). Must be a slash-free slug of letters, digits, `.`, `_`, or `-`. Defaults to the OS account username. Changing it only affects newly created worktrees; existing local branches keep their original names until cleaned up. Prefer a per-user config for personal prefixes — a committed `git.branchPrefix` gives every contributor the same branch prefix.                                                           |
-| `workspace.projectDir`                   | **required**         | Parent dir for cloned repos and sibling ticket worktrees.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `workspace.knownRepositories`            | **required**         | Repos searched for in ticket descriptions to infer where work belongs. A ticket labeled for groundcrew (`agent-*`) fails fast when no known repo appears; unlabeled tickets are ignored.                                                                                                                                                                                                                                                                                                                                    |
+| `workspace.projectDir`                   | **required**         | Parent dir for cloned repos and the default ticket worktree root.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `workspace.worktreeDir`                  | optional             | Parent dir for ticket worktrees. When unset, worktrees are created under `workspace.projectDir`. Changing this only affects worktrees discovered under the new root; clean up existing worktrees before switching it, or temporarily unset it when you need `crew cleanup` to find old worktrees.                                                                                                                                                                                                                           |
+| `workspace.knownRepositories`            | **required**         | Repos searched for in ticket descriptions to infer where work belongs. Entries can be strings under `workspace.projectDir` or `{ name, projectDirOverride }` objects when a repo clone lives under a different parent dir. A ticket labeled for groundcrew (`agent-*`) fails fast when no known repo appears; unlabeled tickets are ignored.                                                                                                                                                                                |
 | `defaults.hooks.prepareWorktree`         | optional             | Fallback repo-preparation command used only when the worktree does not define `.groundcrew/config.json` `hooks.prepareWorktree`. The hook runs after worktree creation and before the agent starts. Repo-local config wins.                                                                                                                                                                                                                                                                                                 |
 | `orchestrator.maximumInProgress`         | `4`                  | Cap on in-progress tickets at once for this `crew` instance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `orchestrator.pollIntervalMilliseconds`  | `120_000`            | Poll interval in `--watch` mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

package/package.json

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