Summary

• Problem: The cleanup service called getDefaultBranch() unconditionally at 3 call sites, causing repeated env_cleanup_error logs on every startup for repos whose default branch is not main and where origin/HEAD is not configured. The error message told users to set worktree.baseBranch in .archon/config.yaml, but that config value was never read by the cleanup service — making the suggestion useless.
• Why it matters: Every tracked environment on a master-branch repo triggered a logged error per startup with no viable workaround. Prior fix attempts (fix(core): respect worktree.baseBranch in cleanup service default branch resolution #1423, fix(core): respect worktree.baseBranch in cleanup service #1424) were closed without landing.
• What changed: Added a private resolveBaseBranch helper in cleanup-service.ts that reads worktree.baseBranch from .archon/config.yaml first, falling back to getDefaultBranch() only when nothing is configured. Replaced all 3 getDefaultBranch call sites with resolveBaseBranch. Added 4 regression tests.
• What did not change: getDefaultBranch itself is unchanged; config-loader.ts is unchanged; no interface or DB schema changes; the codebase.default_branch DB-column fallback (mentioned as "and/or" in the issue) was intentionally omitted to keep scope minimal.

UX Journey

Before

Startup
  ┌─ for each tracked environment
  │    cleanupService.runScheduledCleanup()
  │      getDefaultBranch(mainRepoPath)   ← throws if origin/HEAD unset + no origin/main
  │        ERROR: env_cleanup_error logged  ← repeats every startup, per env
  │        User sees: "Set worktree.baseBranch in .archon/config.yaml"
  │          ↳ User sets config…
  │            ↳ Error still fires (config never read)  ← dead end
  └─ repeat every startup

After

Startup
  ┌─ for each tracked environment
  │    cleanupService.runScheduledCleanup()
  │      resolveBaseBranch(mainRepoPath, cwd)
  │        1. loadRepoConfig(cwd)
  │           worktree.baseBranch set?  →  return configured branch  ← no error
  │           not set?
  │        2. getDefaultBranch(mainRepoPath)
  │           origin/HEAD exists?   →  return detected branch
  │           origin/main exists?   →  return 'main'
  │           neither?              →  throw (legitimate detection failure)
  └─ repeat every startup

Architecture Diagram

Before

cleanup-service.ts
  runScheduledCleanup()       ──calls──▶  @archon/git:getDefaultBranch()
  getWorktreeStatusBreakdown() ──calls──▶  @archon/git:getDefaultBranch()
  cleanupMergedWorktrees()    ──calls──▶  @archon/git:getDefaultBranch()

config-loader.ts (loadRepoConfig)  ◀── NOT imported in cleanup-service.ts

After

cleanup-service.ts
  resolveBaseBranch()  [+]    ──reads──▶  config-loader.ts:loadRepoConfig()  [+new connection]
                              ──calls──▶  @archon/git:getDefaultBranch()  (fallback only)

  runScheduledCleanup()       ──calls──▶  resolveBaseBranch()  [~ was getDefaultBranch]
  getWorktreeStatusBreakdown() ──calls──▶  resolveBaseBranch()  [~ was getDefaultBranch]
  cleanupMergedWorktrees()    ──calls──▶  resolveBaseBranch()  [~ was getDefaultBranch]

Connection inventory:

Label Snapshot

• Risk: risk: low
• Size: size: S
• Scope: core
• Module: core:cleanup-service

Change Metadata

• Change type: bug
• Primary scope: core

Linked Issue

• Closes worktree.baseBranch in .archon/config.yaml is documented but never read — causes repeated env_cleanup_error on startup #1419
• Supersedes fix(core): respect worktree.baseBranch in cleanup service default branch resolution #1423, fix(core): respect worktree.baseBranch in cleanup service #1424

Validation Evidence (required)

bun run validate

All checks passed on the first run:

• Evidence provided: all 7 bun run validate checks passed; 4 new regression tests covering: master-branch-via-config, fallback-to-git-detection, whitespace-trimming, whitespace-only-fallback.
• No checks skipped.

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No — loadRepoConfig reads .archon/config.yaml in the repo CWD, which the cleanup service already has access to.

Compatibility / Migration

• Backward compatible? Yes — when worktree.baseBranch is not configured, behavior is identical to before.
• Config/env changes? No new config keys; existing undocumented-but-documented worktree.baseBranch now actually works.
• Database migration needed? No.

Human Verification (required)

• Verified scenarios: type-check, lint, format, full test suite (including new regression tests) all pass via bun run validate.
• Edge cases checked: whitespace-only baseBranch correctly falls through to git detection; loadRepoConfig returning {} (file absent) correctly falls through to git detection.
• What was not verified: live end-to-end against a real master-branch repo — the regression tests cover this path at the unit level.

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: cleanup service only (runScheduledCleanup, getWorktreeStatusBreakdown, cleanupMergedWorktrees).
• Potential unintended effects: loadRepoConfig is called once per tracked environment per cleanup cycle — this is a cheap local file read on a scheduled (non-hot) path, so performance impact is negligible.
• Guardrails: existing per-environment try/catch in runScheduledCleanup continues to catch any loadRepoConfig parse errors and log them as env_cleanup_error (with a more useful message than before).

Rollback Plan (required)

• Fast rollback: git revert 03fdd3e7 — single commit, no migration to undo.
• Feature flags/config toggles: none required; the change activates only when worktree.baseBranch is set.
• Observable failure symptoms: env_cleanup_error in server logs per tracked environment on startup (same as before the fix).

Risks and Mitigations

• Risk: loadRepoConfig throws on a malformed .archon/config.yaml in a tracked repo.
  • Mitigation: The existing try/catch in runScheduledCleanup at line ~375 already catches per-environment errors and logs them. getWorktreeStatusBreakdown and cleanupMergedWorktrees propagate the error to their callers, which already handle it. No new unhandled throw paths.

Summary by CodeRabbit

• New Features

  • Added configuration option to specify a base branch for repository cleanup operations. Falls back to git default branch detection if not explicitly configured.

• Bug Fixes

  • Enhanced base branch resolution logic for scheduled cleanup tasks (issue #1419), including whitespace trimming and improved fallback handling.