feat: per-project worktree.path config option by joelsb · Pull Request #1117 · coleam00/Archon

joelsb · 2026-04-12T11:55:22Z

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.

Allows repositories to configure a custom worktree directory relative to the repo root (e.g. `.worktrees`) via `.archon/config.yaml`: ```yaml worktree: path: .worktrees ``` When set, worktrees are created at `<repoRoot>/<path>/<branchName>` instead of the global `~/.archon/worktrees/` directory. This keeps worktrees co-located with the project and visible in the IDE. The per-project path takes highest priority, overriding both the project-scoped workspaces path and the legacy global path. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

coderabbitai · 2026-04-12T11:55:39Z

📝 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 }

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

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

Exposes the per-project worktree.path through MergedConfig so tools, the web UI, and API endpoints can read and display both the global paths.worktrees and the per-project worktreePath override. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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 · 2026-04-12T12:02:31Z

+  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');
+    }


⚠️ 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 · 2026-04-15T09:27:59Z

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!

Adds an opt-in `worktree.path` to .archon/config.yaml so a repo can co-locate worktrees with its own checkout (`<repoRoot>/<path>/<branch>`) instead of the default `~/.archon/workspaces/<owner>/<repo>/worktrees/<branch>`. Requested in joelsb's #1117. Primitive changes (clean up the graveyard rather than add parallel code paths): - Collapse worktree layouts from three to two. The old "legacy global" layout (`~/.archon/worktrees/<owner>/<repo>/<branch>`) is gone — every repo resolves to the workspace-scoped layout (`~/.archon/workspaces/<owner>/<repo>/worktrees/<branch>`), whether it was archon-cloned or locally registered. `extractOwnerRepo()` on the repo path is the stable identity fallback. Ends the divergence where workspace-cloned and local repos had visibly different worktree trees. - `getWorktreeBase()` in @archon/git now returns `{ base, layout }` and accepts an optional `{ repoLocal }` override. The layout value replaces the old `isProjectScopedWorktreeBase()` classification at the call sites (`isProjectScopedWorktreeBase` stays exported as deprecated back-compat). - `WorktreeCreateConfig.path` carries the validated override from repo config. `resolveRepoLocalOverride()` fails loudly on absolute paths, `..` escapes, and resolve-escape edge cases (Fail Fast — no silent default fallback when the config is syntactically wrong). - `WorktreeProvider.create()` now loads repo config exactly once and threads it through `getWorktreePath()` + `createWorktree()`. Replaces the prior swallow-then-retry pattern flagged on #1117. `generateEnvId()` is gone — envId is assigned directly from the resolved path (the invariant was already documented on `destroy(envId)`). Tests (packages/git + packages/isolation): - Update the pre-existing `getWorktreeBase` / `isProjectScopedWorktreeBase` suite for the new two-layout return shape and precedence. - Add 8 tests for `worktree.path`: default fallthrough, empty/whitespace ignored, override wins for workspace-scoped repos, rejects absolute, rejects `../` escapes (three variants), accepts nested relative paths. Docs: add `worktree.path` to the repo config reference with explicit precedence and the `.gitignore` responsibility note. Co-authored-by: Joel Bastos <joelsb2001@gmail.com>

… policy (#1310) * feat(isolation): per-project worktree.path + collapse to two layouts Adds an opt-in `worktree.path` to .archon/config.yaml so a repo can co-locate worktrees with its own checkout (`<repoRoot>/<path>/<branch>`) instead of the default `~/.archon/workspaces/<owner>/<repo>/worktrees/<branch>`. Requested in joelsb's #1117. Primitive changes (clean up the graveyard rather than add parallel code paths): - Collapse worktree layouts from three to two. The old "legacy global" layout (`~/.archon/worktrees/<owner>/<repo>/<branch>`) is gone — every repo resolves to the workspace-scoped layout (`~/.archon/workspaces/<owner>/<repo>/worktrees/<branch>`), whether it was archon-cloned or locally registered. `extractOwnerRepo()` on the repo path is the stable identity fallback. Ends the divergence where workspace-cloned and local repos had visibly different worktree trees. - `getWorktreeBase()` in @archon/git now returns `{ base, layout }` and accepts an optional `{ repoLocal }` override. The layout value replaces the old `isProjectScopedWorktreeBase()` classification at the call sites (`isProjectScopedWorktreeBase` stays exported as deprecated back-compat). - `WorktreeCreateConfig.path` carries the validated override from repo config. `resolveRepoLocalOverride()` fails loudly on absolute paths, `..` escapes, and resolve-escape edge cases (Fail Fast — no silent default fallback when the config is syntactically wrong). - `WorktreeProvider.create()` now loads repo config exactly once and threads it through `getWorktreePath()` + `createWorktree()`. Replaces the prior swallow-then-retry pattern flagged on #1117. `generateEnvId()` is gone — envId is assigned directly from the resolved path (the invariant was already documented on `destroy(envId)`). Tests (packages/git + packages/isolation): - Update the pre-existing `getWorktreeBase` / `isProjectScopedWorktreeBase` suite for the new two-layout return shape and precedence. - Add 8 tests for `worktree.path`: default fallthrough, empty/whitespace ignored, override wins for workspace-scoped repos, rejects absolute, rejects `../` escapes (three variants), accepts nested relative paths. Docs: add `worktree.path` to the repo config reference with explicit precedence and the `.gitignore` responsibility note. Co-authored-by: Joel Bastos <joelsb2001@gmail.com> * feat(workflows): per-workflow worktree.enabled policy Introduces a declarative top-level `worktree:` block on a workflow so authors can pin isolation behavior regardless of invocation surface. Solves the case where read-only workflows (e.g. `repo-triage`) should always run in the live checkout, without every CLI/web/scheduled-trigger caller having to remember to set the right flag. Schema (packages/workflows/src/schemas/workflow.ts + loader.ts): - New optional `worktree.enabled: boolean` on `workflowBaseSchema`. Loader parses with the same warn-and-ignore discipline used for `interactive` and `modelReasoningEffort` — invalid shapes log and drop rather than killing workflow discovery. Policy reconciliation (packages/cli/src/commands/workflow.ts): - Three hard-error cases when YAML policy contradicts invocation flags: • `enabled: false` + `--branch` (worktree required by flag, forbidden by policy) • `enabled: false` + `--from` (start-point only meaningful with worktree) • `enabled: true` + `--no-worktree` (policy requires worktree, flag forbids it) - `enabled: false` + `--no-worktree` is redundant, accepted silently. - `--resume` ignores the pinned policy (it reuses the existing run's worktree even when policy would disable — avoids disturbing a paused run). Orchestrator wiring (packages/core/src/orchestrator/orchestrator-agent.ts): - `dispatchOrchestratorWorkflow` short-circuits `validateAndResolveIsolation` when `workflow.worktree?.enabled === false` and runs directly in `codebase.default_cwd`. Web chat/slack/telegram callers have no flag equivalent to `--no-worktree`, so the YAML field is their only control. - Logged as `workflow.worktree_disabled_by_policy` for operator visibility. First consumer (.archon/workflows/repo-triage.yaml): - `worktree: { enabled: false }` — triage reads issues/PRs and writes gh labels; no code mutations, no reason to spin up a worktree per run. Tests: - Loader: parses `worktree.enabled: true|false`, omits block when absent. - CLI: four new integration tests for the reconciliation matrix (skip when policy false, three hard-error cases, redundant `--no-worktree` accepted, `--no-worktree` + `enabled: true` rejected). Docs: authoring-workflows.md gets the new top-level field in the schema example with a comment explaining the precedence and the `enabled: true|false` semantics. * fix(isolation): use path.sep for repo-containment check on Windows resolveRepoLocalOverride was hardcoding '/' as the separator in the startsWith check, so on Windows (where `resolve()` returns backslash paths like `D:\Users\dev\Projects\myapp`) every otherwise-valid relative `worktree.path` was rejected with "resolves outside the repo root". Fixed by importing `path.sep` and using it in the sentinel. Fixes the 3 Windows CI failures in `worktree.path repo-local override`. --------- Co-authored-by: Joel Bastos <joelsb2001@gmail.com>

@jonasvanderhaegen

* feat(paths/cli/setup): unify env load + write on three-path model (coleam00#1302, coleam00#1303) (coleam00#1304) * feat(paths/cli/setup): unify env load + write on three-path model (coleam00#1302, coleam00#1303) Key env handling on directory ownership rather than filename. `.archon/` (at `~/` or `<cwd>/`) is archon-owned; anything else is the user's. - `<repo>/.env` — stripped at boot (guard kept), never loaded, never written - `<repo>/.archon/.env` — loaded at repo scope (wins over home), writable via `archon setup --scope project` - `~/.archon/.env` — loaded at home scope, writable via `--scope home` (default) Read side (coleam00#1302): - New `@archon/paths/env-loader` with `loadArchonEnv(cwd)` shared by CLI and server entry points. Loads both archon-owned files with `override: true`; repo scope wins. - Replaced `[dotenv@17.3.1] injecting env (0) from .env` (always lied about stripped keys) with `[archon] stripped N keys from <cwd> (...)` and `[archon] loaded N keys from <path>` lines, emitted only when N > 0. `quiet: true` passed to dotenv to silence its own output. - `stripCwdEnv` unchanged in semantics — still the only source that deletes keys from `process.env`; now logs what it did. Write side (coleam00#1303): - `archon setup` never writes to `<repo>/.env`. Writing there was incoherent because `stripCwdEnv` deletes those keys on every run. - New `--scope home|project` (default home) targets exactly one archon-owned file. New `--force` overrides the merge; backup still written. - Merge-only by default: existing non-empty values win, user-added custom keys survive, `<path>.archon-backup-<ISO-ts>` written before every rewrite. Fixes silent PostgreSQL→SQLite downgrade and silent token loss in Add mode. - One-time migration note emitted when `<cwd>/.env` exists at setup start. Tests: new `env-loader.test.ts` (6), extended `strip-cwd-env.test.ts` (+4 for the log line), extended `setup.test.ts` (+10 for scope/merge/backup/force/ repo-untouched), extended `cli.test.ts` (+5 for flag parsing). Docs: configuration.md, cli.md, security.md, cli-internals.md, setup skill — all updated to the three-path model. * fix(cli/setup): address PR review — scope/path/secret-handling edge cases - cli: resolve --scope project to git repo root so running setup from a subdir writes to <repo-root>/.archon/.env (what loadArchonEnv reads at boot), not <subdir>/.archon/.env. Fail fast with a useful message when --scope project is used outside a git repo. - setup: resolveScopedEnvPath() now delegates to @archon/paths helpers (getArchonEnvPath / getRepoArchonEnvPath) so Docker's /.archon home, ARCHON_HOME overrides, and the "undefined" literal guard all behave identically between the loader and the writer. - setup: wrap the writeScopedEnv call in try/catch so an fs exception (permission denied, read-only FS, backup copy failure) stops the clack spinner cleanly and emits an actionable error instead of a raw stack trace after the user has completed the entire wizard. - setup: checkExistingConfig(envPath?) — scope-aware existing-config read. Add/Update/Fresh now reflects the actual write target, not an unconditional ~/.archon/.env. - setup: serializeEnv escapes \r (was only \n) so values with bare CR or CRLF round-trip through dotenv.parse without corruption. Regression test added. - setup: merge path treats whitespace-only existing values (' ') as empty, so a copy-paste stray space doesn't silently defeat the wizard update for that key forever. Regression test added. - setup: 0o600 mode on the written env file AND on backup copies — writeFileSync+copyFileSync default to 0o666 & ~umask, which can leave secrets group/world-readable on a permissive umask. - docs/cli.md + setup skill: appendix sections that still described the pre-coleam00#1303 two-file symlink model now reflect the three-path model. * fix(paths/env-loader): Windows-safe assertion for home-scope load line The test asserted the log line contained `from ~/`, which is opportunistic tilde-shortening that only happens when the tmpdir lives under `homedir()`. On Windows CI the tmpdir is on `D:\\` while homedir is `C:\\Users\\...`, so the path renders absolute and the `~/` never appears. Match on the count and the archon-home tmpdir segment instead — robust on both Unix tilde-short paths and Windows absolute paths. * feat(paths,workflows): unify ~/.archon/{workflows,commands,scripts} + drop globalSearchPath (closes coleam00#1136) (coleam00#1315) * feat(paths,workflows): unify ~/.archon/{workflows,commands,scripts} + drop globalSearchPath Collapses the awkward `~/.archon/.archon/workflows/` convention to a direct `~/.archon/workflows/` child (matching `workspaces/`, `archon.db`, etc.), adds home-scoped commands and scripts with the same loading story, and kills the opt-in `globalSearchPath` parameter so every call site gets home-scope for free. Closes coleam00#1136 (supersedes @jonasvanderhaegen's tactical fix — the bug was the primitive itself: an easy-to-forget parameter that five of six call sites on dev dropped). Primitive changes: - Home paths are direct children of `~/.archon/`. New helpers in `@archon/paths`: `getHomeWorkflowsPath()`, `getHomeCommandsPath()`, `getHomeScriptsPath()`, and `getLegacyHomeWorkflowsPath()` (detection-only for migration). - `discoverWorkflowsWithConfig(cwd, loadConfig)` reads home-scope internally. The old `{ globalSearchPath }` option is removed. Chat command handler, Web UI workflow picker, orchestrator resolve path — all inherit home-scope for free without maintainer patches at every new site. - `discoverScriptsForCwd(cwd)` merges home + repo scripts (repo wins on name collision). dag-executor and validator use it; the hardcoded `resolve(cwd, '.archon', 'scripts')` single-scope path is gone. - Command resolution is now walked-by-basename in each scope. `loadCommand` and `resolveCommand` walk 1 subfolder deep and match by `.md` basename, so `.archon/commands/triage/review.md` resolves as `review` — closes the latent bug where subfolder commands were listed but unresolvable. - All three (`workflows/`, `commands/`, `scripts/`) enforce a 1-level subfolder cap (matches the existing `defaults/` convention). Deeper nesting is silently skipped. - `WorkflowSource` gains `'global'` alongside `'bundled'` and `'project'`. Web UI node palette shows a dedicated "Global (~/.archon/commands/)" section; badges updated. Migration (clean cut — no fallback read): - First use after upgrade: if `~/.archon/.archon/workflows/` exists, Archon logs a one-time WARN per process with the exact `mv` command: `mv ~/.archon/.archon/workflows ~/.archon/workflows && rmdir ~/.archon/.archon` The legacy path is NOT read — users migrate manually. Rollback caveat noted in CHANGELOG. Tests: - `@archon/paths/archon-paths.test.ts`: new helper tests (default HOME, ARCHON_HOME override, Docker), plus regression guards for the double-`.archon/` path. - `@archon/workflows/loader.test.ts`: home-scoped workflows, precedence, subfolder 1-depth cap, legacy-path deprecation warning fires exactly once per process. - `@archon/workflows/validator.test.ts`: home-scoped commands + subfolder resolution. - `@archon/workflows/script-discovery.test.ts`: depth cap + merge semantics (repo wins, home-missing tolerance). - Existing CLI + orchestrator tests updated to drop `globalSearchPath` assertions. E2E smoke (verified locally, before cleanup): - `.archon/workflows/e2e-home-scope.yaml` + scratch repo at /tmp - Home-scoped workflow discovered from an unrelated git repo - Home-scoped script (`~/.archon/scripts/*.ts`) executes inside a script node - 1-level subfolder workflow (`~/.archon/workflows/triage/*.yaml`) listed - Legacy path warning fires with actionable `mv` command; workflows there are NOT loaded Docs: `CLAUDE.md`, `docs-web/guides/global-workflows.md` (full rewrite for three-type scope + subfolder convention + migration), `docs-web/reference/ configuration.md` (directory tree), `docs-web/reference/cli.md`, `docs-web/guides/authoring-workflows.md`. Co-authored-by: Jonas Vanderhaegen <7755555+jonasvanderhaegen@users.noreply.github.com> * test(script-discovery): normalize path separators in mocks for Windows The 4 new tests in `scanScriptDir depth cap` and `discoverScriptsForCwd — merge repo + home with repo winning` compared incoming mock paths with hardcoded forward-slash strings (`if (path === '/scripts/triage')`). On Windows, `path.join('/scripts', 'triage')` produces `\scripts\triage`, so those branches never matched, readdir returned `[]`, and the tests failed. Added a `norm()` helper at module scope and wrapped the incoming `path` argument in every `mockImplementation` before comparing. Stored paths go through `normalizeSep()` in production code, so the existing equality assertions on `script.path` remain OS-independent. Fixes Windows CI job `test (windows-latest)` on PR coleam00#1315. * address review feedback: home-scope error handling, depth cap, and tests Critical fixes: - api.ts: add `maxDepth: 1` to all 3 findMarkdownFilesRecursive calls in GET /api/commands (bundled/home/project). Without this the UI palette surfaced commands from deep subfolders that the executor (capped at 1) could not resolve — silent "command not found" at runtime. - validator.ts: wrap home-scope findMarkdownFilesRecursive and resolveCommandInDir calls in try/catch so EACCES/EPERM on ~/.archon/commands/ doesn't crash the validator with a raw filesystem error. ENOENT still returns [] via the underlying helper. Error handling fixes: - workflow-discovery.ts: maybeWarnLegacyHomePath now sets the "warned-once" flag eagerly before `await access()`, so concurrent discovery calls (server startup with parallel codebase resolution) can't double-warn. Non-ENOENT probe errors (EACCES/EPERM) now log at WARN instead of DEBUG so permission issues on the legacy dir are visible in default operation. - dag-executor.ts: wrap discoverScriptsForCwd in its own try/catch so an EACCES on ~/.archon/scripts/ routes through safeSendMessage / logNodeError with a dedicated "failed to discover scripts" message instead of being mis-attributed by the outer catch's "permission denied (check cwd permissions)" branch. Tests: - load-command-prompt.test.ts (new): 6 tests covering the executor's command resolution hot path — home-scope resolves when repo misses, repo shadows home, 1-level subfolder resolvable by basename, 2-level rejected, not-found, empty-file. Runs in its own bun test batch. - archon-paths.test.ts: add getHomeScriptsPath describe block to match the existing getHomeCommandsPath / getHomeWorkflowsPath coverage. Comment clarity: - workflow-discovery.ts: MAX_DISCOVERY_DEPTH comment now leads with the actual value (1) before describing what 0 would mean. - script-discovery.ts: copy the "routing ambiguity" rationale from MAX_DISCOVERY_DEPTH to MAX_SCRIPT_DISCOVERY_DEPTH. Cleanup: - Remove .archon/workflows/e2e-home-scope.yaml — one-off smoke test that would ship permanently in every project's workflow list. Equivalent coverage exists in loader.test.ts. Addresses all blocking and important feedback from the multi-agent review on PR coleam00#1315. --------- Co-authored-by: Jonas Vanderhaegen <7755555+jonasvanderhaegen@users.noreply.github.com> * feat(isolation,workflows): worktree location + per-workflow isolation policy (coleam00#1310) * feat(isolation): per-project worktree.path + collapse to two layouts Adds an opt-in `worktree.path` to .archon/config.yaml so a repo can co-locate worktrees with its own checkout (`<repoRoot>/<path>/<branch>`) instead of the default `~/.archon/workspaces/<owner>/<repo>/worktrees/<branch>`. Requested in joelsb's coleam00#1117. Primitive changes (clean up the graveyard rather than add parallel code paths): - Collapse worktree layouts from three to two. The old "legacy global" layout (`~/.archon/worktrees/<owner>/<repo>/<branch>`) is gone — every repo resolves to the workspace-scoped layout (`~/.archon/workspaces/<owner>/<repo>/worktrees/<branch>`), whether it was archon-cloned or locally registered. `extractOwnerRepo()` on the repo path is the stable identity fallback. Ends the divergence where workspace-cloned and local repos had visibly different worktree trees. - `getWorktreeBase()` in @archon/git now returns `{ base, layout }` and accepts an optional `{ repoLocal }` override. The layout value replaces the old `isProjectScopedWorktreeBase()` classification at the call sites (`isProjectScopedWorktreeBase` stays exported as deprecated back-compat). - `WorktreeCreateConfig.path` carries the validated override from repo config. `resolveRepoLocalOverride()` fails loudly on absolute paths, `..` escapes, and resolve-escape edge cases (Fail Fast — no silent default fallback when the config is syntactically wrong). - `WorktreeProvider.create()` now loads repo config exactly once and threads it through `getWorktreePath()` + `createWorktree()`. Replaces the prior swallow-then-retry pattern flagged on coleam00#1117. `generateEnvId()` is gone — envId is assigned directly from the resolved path (the invariant was already documented on `destroy(envId)`). Tests (packages/git + packages/isolation): - Update the pre-existing `getWorktreeBase` / `isProjectScopedWorktreeBase` suite for the new two-layout return shape and precedence. - Add 8 tests for `worktree.path`: default fallthrough, empty/whitespace ignored, override wins for workspace-scoped repos, rejects absolute, rejects `../` escapes (three variants), accepts nested relative paths. Docs: add `worktree.path` to the repo config reference with explicit precedence and the `.gitignore` responsibility note. Co-authored-by: Joel Bastos <joelsb2001@gmail.com> * feat(workflows): per-workflow worktree.enabled policy Introduces a declarative top-level `worktree:` block on a workflow so authors can pin isolation behavior regardless of invocation surface. Solves the case where read-only workflows (e.g. `repo-triage`) should always run in the live checkout, without every CLI/web/scheduled-trigger caller having to remember to set the right flag. Schema (packages/workflows/src/schemas/workflow.ts + loader.ts): - New optional `worktree.enabled: boolean` on `workflowBaseSchema`. Loader parses with the same warn-and-ignore discipline used for `interactive` and `modelReasoningEffort` — invalid shapes log and drop rather than killing workflow discovery. Policy reconciliation (packages/cli/src/commands/workflow.ts): - Three hard-error cases when YAML policy contradicts invocation flags: • `enabled: false` + `--branch` (worktree required by flag, forbidden by policy) • `enabled: false` + `--from` (start-point only meaningful with worktree) • `enabled: true` + `--no-worktree` (policy requires worktree, flag forbids it) - `enabled: false` + `--no-worktree` is redundant, accepted silently. - `--resume` ignores the pinned policy (it reuses the existing run's worktree even when policy would disable — avoids disturbing a paused run). Orchestrator wiring (packages/core/src/orchestrator/orchestrator-agent.ts): - `dispatchOrchestratorWorkflow` short-circuits `validateAndResolveIsolation` when `workflow.worktree?.enabled === false` and runs directly in `codebase.default_cwd`. Web chat/slack/telegram callers have no flag equivalent to `--no-worktree`, so the YAML field is their only control. - Logged as `workflow.worktree_disabled_by_policy` for operator visibility. First consumer (.archon/workflows/repo-triage.yaml): - `worktree: { enabled: false }` — triage reads issues/PRs and writes gh labels; no code mutations, no reason to spin up a worktree per run. Tests: - Loader: parses `worktree.enabled: true|false`, omits block when absent. - CLI: four new integration tests for the reconciliation matrix (skip when policy false, three hard-error cases, redundant `--no-worktree` accepted, `--no-worktree` + `enabled: true` rejected). Docs: authoring-workflows.md gets the new top-level field in the schema example with a comment explaining the precedence and the `enabled: true|false` semantics. * fix(isolation): use path.sep for repo-containment check on Windows resolveRepoLocalOverride was hardcoding '/' as the separator in the startsWith check, so on Windows (where `resolve()` returns backslash paths like `D:\Users\dev\Projects\myapp`) every otherwise-valid relative `worktree.path` was rejected with "resolves outside the repo root". Fixed by importing `path.sep` and using it in the sentinel. Fixes the 3 Windows CI failures in `worktree.path repo-local override`. --------- Co-authored-by: Joel Bastos <joelsb2001@gmail.com> * docs(worktree): fix stale rename example + document copyFiles properly (coleam00#1328) Three related fixes around the `worktree.copyFiles` primitive: 1. Remove the `.env.example -> .env` rename example from reference/configuration.md and getting-started/overview.md. The `->` parser was removed in coleam00#739 (2026-03-19) because it caused the stale-credentials production bug in coleam00#228 — but the docs kept advertising it. A user writing `.env.example -> .env` today gets `parseCopyFileEntry` returning `{source: '.env.example -> .env', destination: '.env.example -> .env'}`, stat() fails with ENOENT, and the copy silently no-ops at debug level. 2. Replace the single-line "Default behavior: .archon/ is always copied" note with a proper "Worktree file copying" subsection that explains: - Why this exists (git worktree add = tracked files only; gitignored workflow inputs need this hook) - The `.archon/` default (no config needed for the common case) - Common entries: .env, .vscode/, .claude/, plans/, reports/, data fixtures - Semantics: source=destination, ENOENT silently skipped, per-entry error isolation, path-traversal rejected - Interaction with `worktree.path` (both layouts get the same treatment) 3. Update the overview example to drop the `.env.example + .env` pair (which implied rename semantics) in favor of `.env + plans/`, and call out that `.archon/` is auto-copied so users don't list it. No code changes. `bun run format:check` and `bun run lint` green. * fix(workflows): archon-assist runs in live checkout (worktree.enabled: false) — closes coleam00#1546 (coleam00#1555) Co-authored-by: Zolto <zolto@zhome.local> * chore(changelog): document Tier 4 paths/env unification cherry-pick batch (5 commits) Adds a CHANGELOG entry under [Unreleased] / Fixed summarizing the five upstream commits picked in this batch: - 28908f0 — env load/write three-path model + loadArchonEnv helper (coleam00#1302/coleam00#1303/coleam00#1304) - 7be4d0a — unify ~/.archon/{workflows,commands,scripts} (coleam00#1315) - 5ed38dc — worktree.path config + per-workflow worktree.enabled policy (coleam00#1310) - ba4b9b4 — docs follow-up to 5ed38dc (coleam00#1328) - e33e0de — archon-assist worktree.enabled: false (deferred from PR #8, now unblocked) Notes that cc78071 (worktree timeout 5m) was already absorbed in earlier batches. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Rasmus Widing <152263317+Wirasm@users.noreply.github.com> Co-authored-by: Jonas Vanderhaegen <7755555+jonasvanderhaegen@users.noreply.github.com> Co-authored-by: Joel Bastos <joelsb2001@gmail.com> Co-authored-by: ztech-gthb <ztech-001@gmx.net> Co-authored-by: Zolto <zolto@zhome.local> Co-authored-by: cjnprospa <sirhcle.j23@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

joelsb and others added 2 commits April 12, 2026 13:46

chore: add .worktrees to gitignore

659d5b6

coderabbitai Bot reviewed Apr 12, 2026

View reviewed changes

dhcdata mentioned this pull request Apr 12, 2026

feat(workflows): symmetric fallback chain — workspace + global tiers for scripts/commands #1144

Closed

Wirasm mentioned this pull request Apr 20, 2026

feat(isolation,workflows): worktree location + per-workflow isolation policy #1310

Merged

Wirasm closed this in #1310 Apr 20, 2026

Wirasm mentioned this pull request Apr 22, 2026

Release 0.3.7 #1352

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: per-project worktree.path config option#1117

feat: per-project worktree.path config option#1117
joelsb wants to merge 3 commits into
coleam00:devfrom
joelsb:feat/per-project-worktree-path

joelsb commented Apr 12, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 12, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Apr 12, 2026

Uh oh!

Wirasm commented Apr 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

joelsb commented Apr 12, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

Changes

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Wirasm commented Apr 15, 2026

The primitive

The side effects

Suggested cleanup checklist

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

joelsb commented Apr 12, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 12, 2026 •

edited

Loading