@chamba/core 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -70,6 +70,35 @@ interface FilesystemPort {
     remove(path: string): Promise<void>;
 }
 
+type WorktreeLayout = 'sibling' | 'nested';
+interface WorktreeConfig {
+    /**
+     * `sibling`: one folder per ticket under `<workspaceRoot>/<root>/<ticket>/<repo>`.
+     * `nested`: a worktree under each repo at `<workspaceRoot>/<repo>/<root>/<ticket>`.
+     */
+    layout: WorktreeLayout;
+    /** Worktree root: relative to workspace root (sibling) or to each repo (nested). */
+    root: string;
+    /** Branch prefix; the branch is `<branchPrefix><ticket>`, shared across repos. */
+    branchPrefix: string;
+    /** Branch to fork from when the ticket branch doesn't exist yet. */
+    baseBranch: string;
+    /** Copy git-ignored `.env*` files into the new worktree (off by default). */
+    copyEnvFiles: boolean;
+    /** Directories pruned while scanning for `.env*` files. */
+    envPruneDirs: string[];
+    /** Generate an editor workspace file (`.code-workspace`) for the ticket. */
+    editorWorkspace: 'code-workspace' | null;
+    /** Repos to act on; `null` means autodetect the workspace's git repos. */
+    repos: string[] | null;
+    /** Escape hatch: if set, chamba shells out to this command instead of the built-in. */
+    command: string | null;
+}
+type PartialWorktreeConfig = Partial<WorktreeConfig>;
+declare const DEFAULT_WORKTREE_CONFIG: WorktreeConfig;
+/** Merge a partial (on-disk) worktree config over the compiled defaults. */
+declare function resolveWorktreeConfig(file?: PartialWorktreeConfig): WorktreeConfig;
+
 /** Raised when a config is invalid and the caller asked to fail hard. */
 declare class ConfigError extends Error {
     constructor(message: string);
@@ -84,6 +113,8 @@ interface ConfigSource {
 }
 interface LoadConfigResult {
     config: ResolvedConfig;
+    /** Resolved multi-repo worktree policy (defaults ← global ← project). */
+    worktrees: WorktreeConfig;
     sources: ConfigSource[];
 }
 interface LoadConfigOptions {
@@ -109,10 +140,42 @@ declare function resolveRole(config: ResolvedConfig, role: AgentRole): AgentConf
  */
 declare function buildHint(role: AgentRole, cfg: AgentConfig): string;
 
+/** The `worktrees` block of a config file (all fields optional). */
+declare const worktreeConfigSchema: z.ZodObject<{
+    layout: z.ZodOptional<z.ZodEnum<["sibling", "nested"]>>;
+    root: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    branchPrefix: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    baseBranch: z.ZodOptional<z.ZodString>;
+    copyEnvFiles: z.ZodOptional<z.ZodBoolean>;
+    envPruneDirs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    editorWorkspace: z.ZodOptional<z.ZodNullable<z.ZodEnum<["code-workspace"]>>>;
+    repos: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    command: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    layout?: "sibling" | "nested" | undefined;
+    root?: string | undefined;
+    branchPrefix?: string | undefined;
+    baseBranch?: string | undefined;
+    copyEnvFiles?: boolean | undefined;
+    envPruneDirs?: string[] | undefined;
+    editorWorkspace?: "code-workspace" | null | undefined;
+    repos?: string[] | null | undefined;
+    command?: string | null | undefined;
+}, {
+    layout?: "sibling" | "nested" | undefined;
+    root?: string | undefined;
+    branchPrefix?: string | undefined;
+    baseBranch?: string | undefined;
+    copyEnvFiles?: boolean | undefined;
+    envPruneDirs?: string[] | undefined;
+    editorWorkspace?: "code-workspace" | null | undefined;
+    repos?: string[] | null | undefined;
+    command?: string | null | undefined;
+}>;
 /**
- * What a config file on disk may contain. Both `defaults` and `overrides` are
- * optional and partial per role — a project file can carry just one role's one
- * field. Unknown roles and unknown models are rejected with clear messages.
+ * What a config file on disk may contain. `defaults`/`overrides` are optional
+ * and partial per role; `worktrees` is the optional multi-repo worktree policy.
+ * Unknown roles, unknown models and unknown keys are rejected with clear messages.
  */
 declare const configFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -142,6 +205,37 @@ declare const configFileSchema: z.ZodObject<{
         effort?: Effort | undefined;
         reasoning_priority?: ReasoningPriority | undefined;
     }>>>;
+    worktrees: z.ZodOptional<z.ZodObject<{
+        layout: z.ZodOptional<z.ZodEnum<["sibling", "nested"]>>;
+        root: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        branchPrefix: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        baseBranch: z.ZodOptional<z.ZodString>;
+        copyEnvFiles: z.ZodOptional<z.ZodBoolean>;
+        envPruneDirs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        editorWorkspace: z.ZodOptional<z.ZodNullable<z.ZodEnum<["code-workspace"]>>>;
+        repos: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+        command: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strict", z.ZodTypeAny, {
+        layout?: "sibling" | "nested" | undefined;
+        root?: string | undefined;
+        branchPrefix?: string | undefined;
+        baseBranch?: string | undefined;
+        copyEnvFiles?: boolean | undefined;
+        envPruneDirs?: string[] | undefined;
+        editorWorkspace?: "code-workspace" | null | undefined;
+        repos?: string[] | null | undefined;
+        command?: string | null | undefined;
+    }, {
+        layout?: "sibling" | "nested" | undefined;
+        root?: string | undefined;
+        branchPrefix?: string | undefined;
+        baseBranch?: string | undefined;
+        copyEnvFiles?: boolean | undefined;
+        envPruneDirs?: string[] | undefined;
+        editorWorkspace?: "code-workspace" | null | undefined;
+        repos?: string[] | null | undefined;
+        command?: string | null | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: 1;
     defaults?: Partial<Record<AgentRole, {
@@ -154,6 +248,17 @@ declare const configFileSchema: z.ZodObject<{
         effort?: Effort | undefined;
         reasoning_priority?: ReasoningPriority | undefined;
     }>> | undefined;
+    worktrees?: {
+        layout?: "sibling" | "nested" | undefined;
+        root?: string | undefined;
+        branchPrefix?: string | undefined;
+        baseBranch?: string | undefined;
+        copyEnvFiles?: boolean | undefined;
+        envPruneDirs?: string[] | undefined;
+        editorWorkspace?: "code-workspace" | null | undefined;
+        repos?: string[] | null | undefined;
+        command?: string | null | undefined;
+    } | undefined;
 }, {
     version: 1;
     defaults?: Partial<Record<AgentRole, {
@@ -166,6 +271,17 @@ declare const configFileSchema: z.ZodObject<{
         effort?: Effort | undefined;
         reasoning_priority?: ReasoningPriority | undefined;
     }>> | undefined;
+    worktrees?: {
+        layout?: "sibling" | "nested" | undefined;
+        root?: string | undefined;
+        branchPrefix?: string | undefined;
+        baseBranch?: string | undefined;
+        copyEnvFiles?: boolean | undefined;
+        envPruneDirs?: string[] | undefined;
+        editorWorkspace?: "code-workspace" | null | undefined;
+        repos?: string[] | null | undefined;
+        command?: string | null | undefined;
+    } | undefined;
 }>;
 type ConfigFile = z.infer<typeof configFileSchema>;
 type ParseResult = {
@@ -561,6 +677,59 @@ declare function buildBranchName(input: BranchNameInput): string;
 /** Worktree directory relative to the repo root. */
 declare function worktreeRelativePath(taskSlug: string, workerId: string): string;
 
+interface WorktreePlanItem {
+    /** Repo name (a directory under the workspace root). */
+    repo: string;
+    /** Absolute path to the main repo checkout. */
+    repoPath: string;
+    /** Absolute path where the worktree will be created. */
+    worktreePath: string;
+    /** The ticket branch (shared across repos). */
+    branch: string;
+}
+interface PlanWorktreesInput {
+    workspaceRoot: string;
+    ticket: string;
+    /** Already-resolved repo names. */
+    repos: string[];
+    config: WorktreeConfig;
+}
+/**
+ * Make a ticket id safe as a single git ref / path component, **preserving
+ * case** (git refs are case-sensitive, so `TICKET-123` must not become
+ * `ticket-123` or it wouldn't match an existing branch).
+ */
+declare function safeTicket(ticket: string): string;
+/** Branch shared across repos: `<branchPrefix><ticket>`. */
+declare function buildTicketBranch(branchPrefix: string, ticket: string): string;
+/** Where a repo's worktree lives, per layout. */
+declare function worktreePathFor(config: WorktreeConfig, workspaceRoot: string, ticket: string, repo: string): string;
+/** Directory where the editor workspace file is written. */
+declare function editorWorkspaceDir(config: WorktreeConfig, workspaceRoot: string, ticket: string): string;
+/** Pure plan: one item per repo. No IO. */
+declare function planWorktrees(input: PlanWorktreesInput): WorktreePlanItem[];
+/**
+ * Content of the `.code-workspace` file: each repo's worktree as a folder.
+ * Paths are made relative to `baseDir` when nested under it (the sibling case,
+ * where they become just the repo name), otherwise absolute.
+ */
+declare function editorWorkspaceContent(items: WorktreePlanItem[], baseDir: string): string;
+
+/**
+ * Write a `<ticket>.code-workspace` into `dir` listing each repo's worktree as a
+ * folder. Returns the file path. Editor-agnostic (Cursor/VS Code share the format).
+ */
+declare function writeEditorWorkspace(fs: FilesystemPort, dir: string, ticket: string, items: WorktreePlanItem[]): Promise<string>;
+
+/**
+ * Copy git-ignored `.env*` files from `src` into `dst`, preserving relative
+ * paths (so nested ones land in the right subdir). Worktrees share the repo's
+ * tracked files but NOT untracked/ignored ones, so without this a local `.env`
+ * would be missing. Heavy/generated dirs in `pruneDirs` are skipped. Returns the
+ * number of files copied.
+ */
+declare function copyEnvFiles(fs: FilesystemPort, src: string, dst: string, pruneDirs: string[]): Promise<number>;
+
 /**
  * Detect whether a directory is inside a git work tree, via
  * `git rev-parse --is-inside-work-tree`. Caches per root for the session.
@@ -572,6 +741,13 @@ declare class GitDetector {
     isGitRepo(root: string): Promise<boolean>;
 }
 
+/**
+ * The immediate child directories of `workspaceRoot` that are git repos
+ * (have a `.git` directory). A `.git` *file* marks a linked worktree, which is
+ * deliberately excluded — consistent with the workspace scanner.
+ */
+declare function detectGitRepos(fs: FilesystemPort, workspaceRoot: string): Promise<string[]>;
+
 declare class WorktreeError extends Error {
     readonly name = "WorktreeError";
 }
@@ -616,4 +792,47 @@ declare class WorktreeManager {
     cleanup(root: string, branch: string): Promise<CleanupResult>;
 }
 
-export { AGENT_ROLES, type AgentConfig, type AgentRole, type BranchNameInput, type BuiltContext, type ChambaConfig, type CleanupResult, type ClockPort, ConfigError, type ConfigFile, type ConfigSource, type ConfigSourceKind, type ContextBuildInput, ContextBuilder, type CreateWorktreeInput, DEFAULT_CONFIG, type DetectOptions, type DirEntry, EFFORT_LEVELS, type Effort, FakeProcess, FilesystemMemoryStore, type FilesystemPort, type GeneratePlanInput, GitDetector, type Issue, type IssueSeverity, type ListedWorktree, type LoadConfigOptions, type LoadConfigResult, MEMORY_DIR, MODEL_CATALOG, type Memory, MemoryFilesystem, type MemoryStore, type ModelInfo, type ModelProvider, type NoteFields, ObsidianDetector, type ParseResult, type PlanReview, type ProcessExecOptions, type ProcessHandler, type ProcessPort, type ProcessResult, type ProjectRef, REASONING_PRIORITIES, ROLE_DESCRIPTIONS, type ReasoningPriority, type RecordedCall, type RelevantNote, type RememberInput, type ResolvedConfig, type ReviewInput, Reviewer, type SubtaskSpec, VAULT_NOTES_DIR, type ValidatePlanInput, type ValidationResult, type VaultDetection, VaultWriter, WORKSPACE_DIR, WORKSPACE_FILE, WORKSPACE_RELATIVE_PATH, type WorkerKind, type Workspace, WorkspaceScanner, WorktreeError, type WorktreeHandle, WorktreeManager, type WriteNoteInput, type WriteNoteResult, basename, buildBranchName, buildHint, configFileSchema, diffLines, dirname, extname, generatePlanTemplate, getModel, joinPath, loadConfig, modelsByProvider, parseChambaConfig, renderNote, renderWorkspaceMarkdown, resolveEffort, resolveRole, slugify, slugifyForGit, suggestFilesLikelyTouched, suggestSubtasks, textsEqual, validatePlan, worktreeRelativePath };
+type WorktreeStatus = 'created' | 'reused-local' | 'reused-remote' | 'skipped-exists' | 'skipped-not-git';
+interface MultiRepoWorktreeResult {
+    repo: string;
+    branch: string;
+    worktreePath: string;
+    status: WorktreeStatus;
+    envCopied: number;
+}
+interface CreateMultiInput {
+    items: WorktreePlanItem[];
+    baseBranch: string;
+    copyEnvFiles: boolean;
+    envPruneDirs: string[];
+}
+interface CleanupMultiResult {
+    repo: string;
+    branch: string;
+    removed: boolean;
+    mergeSuggestion: string;
+}
+/**
+ * Create and clean up git worktrees across several repos for one ticket.
+ *
+ * Mirrors the battle-tested manual flow: reuse an existing local/remote branch
+ * or fork a new one from the base branch; optionally copy git-ignored `.env*`
+ * files (worktrees don't carry untracked files). Same safety guarantees as the
+ * single-repo manager: cleanup NEVER deletes branches and NEVER uses `--force`.
+ */
+declare class MultiRepoWorktreeManager {
+    private readonly process;
+    private readonly fs;
+    constructor(process: ProcessPort, fs: FilesystemPort);
+    create(input: CreateMultiInput): Promise<MultiRepoWorktreeResult[]>;
+    private createOne;
+    private addWorktree;
+    cleanup(items: WorktreePlanItem[]): Promise<CleanupMultiResult[]>;
+    private mergeSuggestion;
+    private isGitRepo;
+    private branchExistsLocal;
+    private branchExistsRemote;
+    private git;
+}
+
+export { AGENT_ROLES, type AgentConfig, type AgentRole, type BranchNameInput, type BuiltContext, type ChambaConfig, type CleanupMultiResult, type CleanupResult, type ClockPort, ConfigError, type ConfigFile, type ConfigSource, type ConfigSourceKind, type ContextBuildInput, ContextBuilder, type CreateMultiInput, type CreateWorktreeInput, DEFAULT_CONFIG, DEFAULT_WORKTREE_CONFIG, type DetectOptions, type DirEntry, EFFORT_LEVELS, type Effort, FakeProcess, FilesystemMemoryStore, type FilesystemPort, type GeneratePlanInput, GitDetector, type Issue, type IssueSeverity, type ListedWorktree, type LoadConfigOptions, type LoadConfigResult, MEMORY_DIR, MODEL_CATALOG, type Memory, MemoryFilesystem, type MemoryStore, type ModelInfo, type ModelProvider, MultiRepoWorktreeManager, type MultiRepoWorktreeResult, type NoteFields, ObsidianDetector, type ParseResult, type PartialWorktreeConfig, type PlanReview, type PlanWorktreesInput, type ProcessExecOptions, type ProcessHandler, type ProcessPort, type ProcessResult, type ProjectRef, REASONING_PRIORITIES, ROLE_DESCRIPTIONS, type ReasoningPriority, type RecordedCall, type RelevantNote, type RememberInput, type ResolvedConfig, type ReviewInput, Reviewer, type SubtaskSpec, VAULT_NOTES_DIR, type ValidatePlanInput, type ValidationResult, type VaultDetection, VaultWriter, WORKSPACE_DIR, WORKSPACE_FILE, WORKSPACE_RELATIVE_PATH, type WorkerKind, type Workspace, WorkspaceScanner, type WorktreeConfig, WorktreeError, type WorktreeHandle, type WorktreeLayout, WorktreeManager, type WorktreePlanItem, type WorktreeStatus, type WriteNoteInput, type WriteNoteResult, basename, buildBranchName, buildHint, buildTicketBranch, configFileSchema, copyEnvFiles, detectGitRepos, diffLines, dirname, editorWorkspaceContent, editorWorkspaceDir, extname, generatePlanTemplate, getModel, joinPath, loadConfig, modelsByProvider, parseChambaConfig, planWorktrees, renderNote, renderWorkspaceMarkdown, resolveEffort, resolveRole, resolveWorktreeConfig, safeTicket, slugify, slugifyForGit, suggestFilesLikelyTouched, suggestSubtasks, textsEqual, validatePlan, worktreeConfigSchema, worktreePathFor, worktreeRelativePath, writeEditorWorkspace };

package/dist/index.js

@@ -196,10 +196,27 @@ var agentConfigSchema = z.object({
   reasoning_priority: reasoningPrioritySchema
 });
 var partialAgentConfigSchema = agentConfigSchema.partial();
+var safePathSchema = z.string().refine((s) => !s.includes("..") && !s.startsWith("/"), {
+  message: 'must be a relative path without ".."'
+});
+var worktreeConfigSchema = z.object({
+  layout: z.enum(["sibling", "nested"]).optional(),
+  root: safePathSchema.optional(),
+  branchPrefix: z.string().refine((s) => !s.includes("..") && !/\s/.test(s), {
+    message: 'branchPrefix must have no spaces and no ".."'
+  }).optional(),
+  baseBranch: z.string().min(1).optional(),
+  copyEnvFiles: z.boolean().optional(),
+  envPruneDirs: z.array(z.string()).optional(),
+  editorWorkspace: z.enum(["code-workspace"]).nullable().optional(),
+  repos: z.array(z.string()).nullable().optional(),
+  command: z.string().nullable().optional()
+}).strict();
 var configFileSchema = z.object({
   version: z.literal(1),
   defaults: z.record(roleSchema, partialAgentConfigSchema).optional(),
-  overrides: z.record(roleSchema, partialAgentConfigSchema).optional()
+  overrides: z.record(roleSchema, partialAgentConfigSchema).optional(),
+  worktrees: worktreeConfigSchema.optional()
 }).strict();
 function parseChambaConfig(raw) {
   const result = configFileSchema.safeParse(raw);
@@ -208,6 +225,46 @@ function parseChambaConfig(raw) {
   return { ok: false, error };
 }
 
+// src/config/worktrees.ts
+var DEFAULT_WORKTREE_CONFIG = {
+  layout: "sibling",
+  root: "WORKTREES",
+  branchPrefix: "chamba/",
+  baseBranch: "main",
+  copyEnvFiles: false,
+  envPruneDirs: [
+    "node_modules",
+    ".git",
+    ".next",
+    "dist",
+    "build",
+    ".venv",
+    "cdk.out",
+    ".aws-sam",
+    ".turbo",
+    "coverage"
+  ],
+  editorWorkspace: null,
+  repos: null,
+  command: null
+};
+function resolveWorktreeConfig(file) {
+  const d = DEFAULT_WORKTREE_CONFIG;
+  if (!file) return { ...d };
+  return {
+    layout: file.layout ?? d.layout,
+    root: file.root ?? d.root,
+    branchPrefix: file.branchPrefix ?? d.branchPrefix,
+    baseBranch: file.baseBranch ?? d.baseBranch,
+    copyEnvFiles: file.copyEnvFiles ?? d.copyEnvFiles,
+    envPruneDirs: file.envPruneDirs ?? d.envPruneDirs,
+    // nullable fields: `null` is meaningful, so only override when defined
+    editorWorkspace: file.editorWorkspace !== void 0 ? file.editorWorkspace : d.editorWorkspace,
+    repos: file.repos !== void 0 ? file.repos : d.repos,
+    command: file.command !== void 0 ? file.command : d.command
+  };
+}
+
 // src/config/loader.ts
 var ConfigError = class extends Error {
   constructor(message) {
@@ -218,6 +275,7 @@ var ConfigError = class extends Error {
 async function loadConfig(fs, opts = {}) {
   const sources = [{ kind: "default", status: "applied" }];
   const config = cloneDefaults();
+  let worktreesPartial = {};
   const layers = [
     { kind: "global", path: opts.globalPath },
     { kind: "project", path: opts.projectPath }
@@ -234,9 +292,12 @@ async function loadConfig(fs, opts = {}) {
       continue;
     }
     applyLayer(config, loaded.file);
+    if (loaded.file.worktrees) {
+      worktreesPartial = { ...worktreesPartial, ...loaded.file.worktrees };
+    }
     sources.push({ kind: layer.kind, path: layer.path, status: "applied" });
   }
-  return { config, sources };
+  return { config, worktrees: resolveWorktreeConfig(worktreesPartial), sources };
 }
 function cloneDefaults() {
   const out = {};
@@ -1396,6 +1457,89 @@ function worktreeRelativePath(taskSlug, workerId) {
   return joinPath(WORKSPACE_DIR, "worktrees", slugifyForGit(taskSlug), slugifyForGit(workerId));
 }
 
+// src/worktree/multi-repo-plan.ts
+function safeTicket(ticket) {
+  const s = ticket.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/\.\.+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+  return s.length > 0 ? s : "ticket";
+}
+function buildTicketBranch(branchPrefix, ticket) {
+  return `${branchPrefix}${safeTicket(ticket)}`;
+}
+function worktreePathFor(config, workspaceRoot, ticket, repo) {
+  const t = safeTicket(ticket);
+  if (config.layout === "nested") {
+    return joinPath(workspaceRoot, repo, config.root, t);
+  }
+  return joinPath(workspaceRoot, config.root, t, repo);
+}
+function editorWorkspaceDir(config, workspaceRoot, ticket) {
+  if (config.layout === "nested") return workspaceRoot;
+  return joinPath(workspaceRoot, config.root, safeTicket(ticket));
+}
+function planWorktrees(input) {
+  const { workspaceRoot, ticket, repos, config } = input;
+  const branch = buildTicketBranch(config.branchPrefix, ticket);
+  return repos.map((repo) => ({
+    repo,
+    repoPath: joinPath(workspaceRoot, repo),
+    worktreePath: worktreePathFor(config, workspaceRoot, ticket, repo),
+    branch
+  }));
+}
+function editorWorkspaceContent(items, baseDir) {
+  const prefix = `${baseDir}/`;
+  const folders = items.map((item) => {
+    const path = item.worktreePath.startsWith(prefix) ? item.worktreePath.slice(prefix.length) : item.worktreePath;
+    return { path };
+  });
+  return `${JSON.stringify({ folders }, null, 2)}
+`;
+}
+
+// src/worktree/editor-workspace.ts
+async function writeEditorWorkspace(fs, dir, ticket, items) {
+  const path = joinPath(dir, `${safeTicket(ticket)}.code-workspace`);
+  await fs.mkdir(dir);
+  await fs.writeFile(path, editorWorkspaceContent(items, dir));
+  return path;
+}
+
+// src/worktree/env-copy.ts
+function isEnvFile(name) {
+  if (name !== ".env" && !name.startsWith(".env.")) return false;
+  if (/\.(example|sample)$/i.test(name)) return false;
+  if (/\.bak(\.|$)/i.test(name)) return false;
+  return true;
+}
+async function copyEnvFiles(fs, src, dst, pruneDirs) {
+  const prune = new Set(pruneDirs);
+  let count = 0;
+  const walk = async (rel) => {
+    const abs = rel.length > 0 ? joinPath(src, rel) : src;
+    let entries;
+    try {
+      entries = await fs.readDir(abs);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const childRel = rel.length > 0 ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory) {
+        if (prune.has(entry.name)) continue;
+        await walk(childRel);
+      } else if (isEnvFile(entry.name)) {
+        const content = await fs.readFile(joinPath(src, childRel));
+        const target = joinPath(dst, childRel);
+        await fs.mkdir(dirname(target));
+        await fs.writeFile(target, content);
+        count++;
+      }
+    }
+  };
+  await walk("");
+  return count;
+}
+
 // src/worktree/git-detector.ts
 var GitDetector = class {
   constructor(process) {
@@ -1415,6 +1559,30 @@ var GitDetector = class {
   }
 };
 
+// src/worktree/git-repo-detector.ts
+async function hasGitDir(fs, dir) {
+  try {
+    const entries = await fs.readDir(dir);
+    return entries.some((e) => e.name === ".git" && e.isDirectory);
+  } catch {
+    return false;
+  }
+}
+async function detectGitRepos(fs, workspaceRoot) {
+  let entries;
+  try {
+    entries = await fs.readDir(workspaceRoot);
+  } catch {
+    return [];
+  }
+  const repos = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory) continue;
+    if (await hasGitDir(fs, joinPath(workspaceRoot, entry.name))) repos.push(entry.name);
+  }
+  return repos.sort();
+}
+
 // src/worktree/manager.ts
 var WorktreeError = class extends Error {
   name = "WorktreeError";
@@ -1482,11 +1650,130 @@ function parsePorcelain(output) {
   }
   return result;
 }
+
+// src/worktree/multi-repo-manager.ts
+var MultiRepoWorktreeManager = class {
+  constructor(process, fs) {
+    this.process = process;
+    this.fs = fs;
+  }
+  process;
+  fs;
+  async create(input) {
+    const results = [];
+    for (const item of input.items) {
+      results.push(await this.createOne(item, input));
+    }
+    return results;
+  }
+  async createOne(item, input) {
+    const base = { repo: item.repo, branch: item.branch, worktreePath: item.worktreePath };
+    if (!await this.isGitRepo(item.repoPath)) {
+      return { ...base, status: "skipped-not-git", envCopied: 0 };
+    }
+    if (await this.fs.exists(item.worktreePath)) {
+      return { ...base, status: "skipped-exists", envCopied: 0 };
+    }
+    const status = await this.addWorktree(item, input.baseBranch);
+    let envCopied = 0;
+    if (input.copyEnvFiles) {
+      envCopied = await copyEnvFiles(this.fs, item.repoPath, item.worktreePath, input.envPruneDirs);
+    }
+    return { ...base, status, envCopied };
+  }
+  async addWorktree(item, baseBranch) {
+    const { repoPath, branch, worktreePath } = item;
+    if (await this.branchExistsLocal(repoPath, branch)) {
+      await this.git(repoPath, ["worktree", "add", worktreePath, branch]);
+      return "reused-local";
+    }
+    if (await this.branchExistsRemote(repoPath, branch)) {
+      await this.git(repoPath, ["fetch", "origin", `${branch}:${branch}`]);
+      await this.git(repoPath, ["worktree", "add", worktreePath, branch]);
+      return "reused-remote";
+    }
+    await this.process.exec("git", ["fetch", "origin", baseBranch], { cwd: repoPath });
+    await this.git(repoPath, [
+      "worktree",
+      "add",
+      "-b",
+      branch,
+      worktreePath,
+      `origin/${baseBranch}`
+    ]);
+    return "created";
+  }
+  async cleanup(items) {
+    const results = [];
+    for (const item of items) {
+      if (!await this.fs.exists(item.worktreePath)) {
+        results.push({
+          repo: item.repo,
+          branch: item.branch,
+          removed: false,
+          mergeSuggestion: this.mergeSuggestion(item)
+        });
+        continue;
+      }
+      const result = await this.process.exec("git", ["worktree", "remove", item.worktreePath], {
+        cwd: item.repoPath
+      });
+      if (result.exitCode !== 0) {
+        throw new WorktreeError(
+          `git worktree remove failed for ${item.repo} (uncommitted changes?): ${result.stderr.trim() || "unknown error"}`
+        );
+      }
+      results.push({
+        repo: item.repo,
+        branch: item.branch,
+        removed: true,
+        mergeSuggestion: this.mergeSuggestion(item)
+      });
+    }
+    return results;
+  }
+  mergeSuggestion(item) {
+    return `git -C ${item.repoPath} merge --no-ff ${item.branch}`;
+  }
+  async isGitRepo(repoPath) {
+    try {
+      const entries = await this.fs.readDir(repoPath);
+      return entries.some((e) => e.name === ".git" && e.isDirectory);
+    } catch {
+      return false;
+    }
+  }
+  async branchExistsLocal(repoPath, branch) {
+    const result = await this.process.exec(
+      "git",
+      ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
+      { cwd: repoPath }
+    );
+    return result.exitCode === 0;
+  }
+  async branchExistsRemote(repoPath, branch) {
+    const result = await this.process.exec(
+      "git",
+      ["ls-remote", "--exit-code", "--heads", "origin", branch],
+      { cwd: repoPath }
+    );
+    return result.exitCode === 0;
+  }
+  async git(repoPath, args) {
+    const result = await this.process.exec("git", args, { cwd: repoPath });
+    if (result.exitCode !== 0) {
+      throw new WorktreeError(
+        `git ${args.join(" ")} failed: ${result.stderr.trim() || "unknown error"}`
+      );
+    }
+  }
+};
 export {
   AGENT_ROLES,
   ConfigError,
   ContextBuilder,
   DEFAULT_CONFIG,
+  DEFAULT_WORKTREE_CONFIG,
   EFFORT_LEVELS,
   FakeProcess,
   FilesystemMemoryStore,
@@ -1494,6 +1781,7 @@ export {
   MEMORY_DIR,
   MODEL_CATALOG,
   MemoryFilesystem,
+  MultiRepoWorktreeManager,
   ObsidianDetector,
   REASONING_PRIORITIES,
   ROLE_DESCRIPTIONS,
@@ -1509,9 +1797,14 @@ export {
   basename,
   buildBranchName,
   buildHint,
+  buildTicketBranch,
   configFileSchema,
+  copyEnvFiles,
+  detectGitRepos,
   diffLines,
   dirname,
+  editorWorkspaceContent,
+  editorWorkspaceDir,
   extname,
   generatePlanTemplate,
   getModel,
@@ -1519,15 +1812,21 @@ export {
   loadConfig,
   modelsByProvider,
   parseChambaConfig,
+  planWorktrees,
   renderNote,
   renderWorkspaceMarkdown,
   resolveEffort,
   resolveRole,
+  resolveWorktreeConfig,
+  safeTicket,
   slugify,
   slugifyForGit,
   suggestFilesLikelyTouched,
   suggestSubtasks,
   textsEqual,
   validatePlan,
-  worktreeRelativePath
+  worktreeConfigSchema,
+  worktreePathFor,
+  worktreeRelativePath,
+  writeEditorWorkspace
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chamba/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Core logic for chamba: workspace scanner, plan + heuristic reviewer, git worktrees, Obsidian, memory — no Node APIs, no LLM",
   "license": "MIT",
   "type": "module",