feat: per-project worktree.path config option

[joelsb]

Summary

• Adds worktree.path to repo-level .archon/config.yaml — a relative path from repo root where worktrees should be created
• When set, worktrees are created at <repoRoot>/<path>/<branchName> instead of ~/.archon/worktrees/
• Per-project path takes highest priority, overriding both project-scoped workspaces and legacy global paths

Motivation

When working with Archon on a project, worktrees are created in ~/.archon/worktrees/ by default — invisible to the IDE and far from the project. This PR allows repos to opt in to keeping worktrees co-located:

# .archon/config.yaml
worktree:
  path: .worktrees

Worktrees then appear at myproject/.worktrees/archon/task-fix-bug — visible in the IDE file tree and easy to navigate.

Changes

File	Change
packages/isolation/src/types.ts	Added path?: string to WorktreeCreateConfig
packages/core/src/config/config-types.ts	Added path?: string to RepoConfig.worktree
packages/isolation/src/providers/worktree.ts	getWorktreePath() checks config.path first; create() loads config early; createWorktree() handles custom path mkdir
packages/isolation/src/providers/worktree.test.ts	4 new tests covering custom path, empty/whitespace path, null config fallback, priority over project-scoped

Test plan

• All existing tests pass (0 failures across all packages)
• New tests verify: custom path resolution, empty/whitespace ignored, null config falls back to defaults, custom path overrides project-scoped path
• Manual: set worktree.path: .worktrees in a repo's .archon/config.yaml and run archon workflow run — worktree should appear under .worktrees/

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Per-project worktree path configuration: specify a repo-relative directory for worktrees instead of the global default.

• Chores

  • Updated ignore rules to exclude .worktrees directories.

• Tests

  • Added tests covering per-project worktree path behavior, validation of empty/whitespace handling, and precedence over other path strategies.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds per-repository worktree directory support via a new optional worktree.path config; updates path resolution and creation to honor per-project paths with early config loading; adds tests and .gitignore entry for .worktrees.

Changes

Cohort / File(s)	Summary
Config Types packages/core/src/config/config-types.ts, packages/isolation/src/types.ts	Add optional path?: string to repo/worktree config and add worktreePath?: string to merged config to carry effective per-project worktree path.
Worktree Provider Logic packages/isolation/src/providers/worktree.ts	Early config load in create(), extend getWorktreePath(...) to accept optional config and prefer <repoRoot>/<worktree.path>/<branch> when set; createWorktree() accepts optional preloaded config and ensures parent dir under repo root when using worktree.path.
Config Loader packages/core/src/config/config-loader.ts	mergeRepoConfig propagates repo.worktree.path into result.worktreePath when non-empty; warns (config.worktree_path_whitespace_ignored) if trimmed value is empty.
Tests packages/isolation/src/providers/worktree.test.ts	Add tests for per-project worktree.path behavior: correct path formation, whitespace-as-empty handling, fallback when config missing, and precedence over other path strategies.
Ignore Rules .gitignore	Add .worktrees to .gitignore.

Sequence Diagram(s)

sequenceDiagram
    participant Caller as Isolation Request
    participant Provider as WorktreeProvider
    participant Config as Config Loader
    participant FS as FileSystem
    participant Git as Worktree Tool

    Caller->>Provider: create(request)
    Provider->>Config: loadConfig(canonicalRepoPath)
    Config-->>Provider: WorktreeCreateConfig | null

    Provider->>Provider: getWorktreePath(request, branchName, config)
    alt config.path exists
        Note right of Provider: use <repoRoot>/<config.path>/<branch>
    else
        Note right of Provider: fallback to project-scoped or legacy path
    end
    Provider->>Provider: worktreePath

    Provider->>Provider: createWorktree(request, worktreePath, branchName, preloadedConfig)
    alt config.path is set
        Provider->>FS: mkdirAsync(join(repoRoot, config.path))
    else
        Provider->>FS: ensure base-layout directories
    end
    FS-->>Provider: dirs ready

    Provider->>Git: create worktree at worktreePath
    Git-->>Provider: warnings[]
    Provider-->>Caller: { warnings }

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I hopped through configs, sniffed each repo tree,
A path for each branch now lives where it should be,
No more one-size worktrees wandering afar,
Per-project burrows now cozy and smart,
Hooray — tidy roots for every branch we see! 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers key sections (Summary, Motivation, Changes table) and explains the feature well, but several required template sections are missing or incomplete.	Add missing sections: UX Journey (Before/After flows), Architecture Diagram (Before/After with module connections), Label Snapshot, Validation Evidence with command results, Security Impact assessment, Compatibility details, Human Verification details, Side Effects/Blast Radius analysis, and Rollback Plan. Complete the manual test verification checkbox and provide evidence.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding per-project worktree.path config option support.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/core/src/config/config-loader.ts`:
- Around line 389-395: The code calls repo.worktree.path.trim() after checking
!== undefined which will throw if path is non-string (e.g., null); update the
branch in config-loader.ts to first assert the type is string (e.g., typeof
repo.worktree.path === 'string') before calling .trim(), set result.worktreePath
when trimmed is non-empty, and otherwise either log the whitespace-warning using
getLog().warn or throw a clear error for unsupported non-string values (per
guidelines) so the unsafe state is rejected explicitly; reference symbols:
repo.worktree.path, result.worktreePath, and getLog().warn.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ec9164cc-04c1-40ff-be9f-4d9ec639025e

📥 Commits

Reviewing files that changed from the base of the PR and between b7bd6e9 and 6a630d8.

📒 Files selected for processing (2)

• packages/core/src/config/config-loader.ts
• packages/core/src/config/config-types.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/core/src/config/config-types.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Guard repo.worktree.path type before calling .trim().

This branch can throw if YAML contains a non-string value (e.g., path: null), because !== undefined still passes and .trim() is invoked on a non-string.

Suggested fix

   // Propagate per-project worktree path for isolation providers
   if (repo.worktree?.path !== undefined) {
-    const trimmed = repo.worktree.path.trim();
+    if (typeof repo.worktree.path !== 'string') {
+      throw new Error('Invalid .archon/config.yaml: worktree.path must be a string');
+    }
+    const trimmed = repo.worktree.path.trim();
     if (trimmed) {
       result.worktreePath = trimmed;
     } else {
       getLog().warn({ rawValue: repo.worktree.path }, 'config.worktree_path_whitespace_ignored');
     }
   }

As per coding guidelines, “Throw early with a clear error for unsupported or unsafe states” and “keep unsupported paths explicit (error out) rather than adding partial fake support.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if (repo.worktree?.path !== undefined) {
	const trimmed = repo.worktree.path.trim();
	if (trimmed) {
	result.worktreePath = trimmed;
	} else {
	getLog().warn({ rawValue: repo.worktree.path }, 'config.worktree_path_whitespace_ignored');
	}
	if (repo.worktree?.path !== undefined) {
	if (typeof repo.worktree.path !== 'string') {
	throw new Error('Invalid .archon/config.yaml: worktree.path must be a string');
	}
	const trimmed = repo.worktree.path.trim();
	if (trimmed) {
	result.worktreePath = trimmed;
	} else {
	getLog().warn({ rawValue: repo.worktree.path }, 'config.worktree_path_whitespace_ignored');
	}
	}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/config/config-loader.ts` around lines 389 - 395, The code
calls repo.worktree.path.trim() after checking !== undefined which will throw if
path is non-string (e.g., null); update the branch in config-loader.ts to first
assert the type is string (e.g., typeof repo.worktree.path === 'string') before
calling .trim(), set result.worktreePath when trimmed is non-empty, and
otherwise either log the whitespace-warning using getLog().warn or throw a clear
error for unsupported non-string values (per guidelines) so the unsafe state is
rejected explicitly; reference symbols: repo.worktree.path, result.worktreePath,
and getLog().warn.

[Wirasm]

Hey @joelsb — thanks for this! The motivation is real (worktrees in ~/.archon/worktrees/ being invisible in IDEs is a genuine UX papercut) and the wiring through RepoConfig.worktree.path → WorktreeCreateConfig.path → provider is clean and follows the existing pattern for baseBranch/copyFiles. I'd like to land this — but the primitive and a few of the side effects need tightening before it's safe to ship.

The primitive

The config field is a free-form relative path string, but the actual semantics is "a directory inside this repo". That mismatch leaves a few foot-guns the PR doesn't address:

• No path-traversal guard — path: ../sibling would create worktrees outside the repo. Untested.
• No absolute-path guard — path: /tmp/foo silently bypasses repoRoot. Untested.
• No symlink-escape consideration.

The actual user need is "put them somewhere under the repo so I can see them in my IDE". Two cheaper-to-validate primitives that express that intent more precisely:

• worktree.coLocate: true — fixed conventional dirname (e.g. .archon-worktrees/)
• worktree.dirname: string — single segment, validated to not contain / or ..

If you want to keep the full path flexibility, please add validation that rejects (or warns + ignores) absolute paths and any path that resolves outside repoRoot (use path.resolve and check the result startsWith(repoRoot)), with tests for each rejection.

The side effects

A few things that aren't quite right yet:

1. Asymmetric config-load error handling.

try { earlyConfig = await this.loadConfig(...); earlyConfigLoaded = true; }
catch { /* swallowed */ }

The early load silently swallows errors and falls back to defaults; the later load in createWorktree throws. So one config error produces two different behaviors depending on whether the second load also fails the same way. That violates our "Fail Fast + Explicit Errors" rule (CLAUDE.md). Pick one model — either both warn-and-default, or both throw — and apply it once.

2. generateEnvId() is now stale.

The PR replaces envId = this.generateEnvId(request) with envId = worktreePath (correct, because generateEnvId doesn't take config). But the method is left on the class unmodified — any future caller will get the default path even when config overrides it. Either delete generateEnvId (it's only used here) or make it config-aware.

3. MergedConfig.worktreePath is added but never read.

The PR plumbs worktree.path into MergedConfig.worktreePath in config-loader.ts, but no code consumes it — the worktree provider gets path via WorktreeCreateConfig (the RepoConfigLoader path), not via MergedConfig. That field is dead on arrival. Please remove it (or wire an actual consumer if you have one in mind).

4. Implicit .gitignore requirement.

A user opting into worktree.path: .worktrees needs to add .worktrees to their .gitignore, or git status immediately shows the worktree dir as untracked. The PR adds it to Archon's own .gitignore but doesn't surface this for end users. Cheap, high-value addition: at worktree-create time, check whether the configured path is gitignored in the parent repo, and log a warn-level message if not. (Don't error — let the user decide, but make the foot-gun visible.)

5. Worktree-inside-repo recursion hazard (worth thinking about, not necessarily blocking).

When the worktree lives at <repo>/.worktrees/foo/, the worktree contains a working copy of the repo, which contains .worktrees/. Git itself handles this OK, but downstream tooling can get confused:

• copyFiles (which already copies .archon/ into worktrees) could shovel worktree state around
• IDE indexers, TypeScript project references, ESLint globs, test runners scanning **/*.test.ts — all need to be told to skip the new dir
• Workflows running inside a worktree may discover and re-execute their own siblings if any tooling walks .worktrees/

Probably not a blocker, but worth a note in the doc/changelog so users opt in with eyes open.

Suggested cleanup checklist

• Validate path (reject absolute, reject .. traversal, reject anything resolving outside repoRoot) — with tests
• Pick a single error-handling model for config load and apply consistently
• Drop MergedConfig.worktreePath (dead) OR wire a real consumer
• Either delete generateEnvId or make it config-aware
• Add a startup warn when worktree.path is set but not present in the repo's .gitignore
• (Optional) consider coLocate: true or dirname: string instead of free-form path
• Document the recursion/IDE-scan caveat in the feature docs

Happy to review the next iteration. Thanks again for digging into this one!