relayburn-sdk: default ledger home moves to ~/.agentworkforce/burn

[willwashburn]

Summary

Moves the Rust 2.0 port's default ledger home from ~/.relayburn to ~/.agentworkforce/burn so it can coexist on disk with the TS 1.x package (still at ~/.relayburn) during the #249 cutover.

• ledger_home() in crates/relayburn-sdk/src/ledger/paths.rs now pushes .agentworkforce/burn (two levels) under $HOME. The two-level path is handled by the existing create_dir_all in Connections::open, so no additional plumbing is needed.
• analyze::ghost_surface::default_archive_dir now reuses crate::ledger::ledger_home() instead of duplicating the home resolution; ghost-archive/ follows the configured home (and any env override) for free.
• Doc-only updates to relayburn-cli (CLI help text, harness comments), relayburn-sdk-node, and a few in-source comments swap ~/.relayburn for the new default.
• New unit tests in paths.rs lock both the default and the RELAYBURN_HOME override.

What is unchanged

• Env var names: RELAYBURN_HOME, RELAYBURN_SQLITE_PATH, RELAYBURN_CONTENT_PATH, RELAYBURN_CONTENT_STORE, RELAYBURN_CONTENT_TTL_DAYS, RELAYBURN_ARCHIVE are all preserved — they're an established interface and existing test infrastructure depends on them. Renaming them is a separate decision the project lead can make later.
• TS 1.x: packages under packages/** continue to read/write ~/.relayburn. The whole point of this PR is letting the two trees coexist.
• Harness session stores: ~/.claude/projects/, ~/.codex/sessions/, ~/.local/share/opencode/storage/session/ are untouched — those belong to the harnesses, not the ledger.

Migration

Anyone testing the Rust port who already has data under ~/.relayburn can mv ~/.relayburn ~/.agentworkforce/burn to carry it over. Note that the formats are not compatible across the 1.x → 2.0 boundary — the Rust port will treat any non-2.0 layout as empty and require a fresh burn ingest to re-populate.

Context

Part of the Rust port epic (#240); unblocks the #249 cutover by letting Rust 2.0 and TS 1.x sit on the same machine simultaneously without trampling each other's databases.

Test plan

• cargo build --workspace clean
• cargo test --workspace green (612 unit tests, plus integration + sdk-node)
• BURN_GOLDEN=1 cargo test --test golden -p relayburn-cli — all enabled snapshots still pass byte-for-byte (no drift)
• New unit tests in paths.rs cover the default and the RELAYBURN_HOME override
• Manual smoke (deferred; would dirty the project lead's real ~/.agentworkforce/): cargo run --release -p relayburn-cli -- state status with RELAYBURN_HOME unset should report a ~/.agentworkforce/burn/burn.sqlite path. Covered indirectly by the new unit tests.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: de440407-9701-4c72-a894-b4d4db709e44

📥 Commits

Reviewing files that changed from the base of the PR and between ad48f65 and bbdd279.

📒 Files selected for processing (12)

• CHANGELOG.md
• crates/relayburn-cli/src/cli.rs
• crates/relayburn-cli/src/harnesses/codex.rs
• crates/relayburn-cli/src/harnesses/opencode.rs
• crates/relayburn-sdk-node/src/lib.rs
• crates/relayburn-sdk/src/analyze/ghost_surface.rs
• crates/relayburn-sdk/src/ingest/orchestration_tests.rs
• crates/relayburn-sdk/src/ingest_verb.rs
• crates/relayburn-sdk/src/ledger/config.rs
• crates/relayburn-sdk/src/ledger/paths.rs
• crates/relayburn-sdk/src/lib.rs
• crates/relayburn-sdk/tests/integration.rs

---

📝 Walkthrough

Walkthrough

This PR updates the default ledger home directory from ~/.relayburn to ~/.agentworkforce/burn across the Rust codebase to enable concurrent Rust 2.0 and TypeScript 1.x coexistence during cutover. The change affects default path construction, test isolation, archive directory resolution, and documentation throughout the SDK and CLI.

Changes

Ledger Home Path Migration

Layer / File(s)	Summary
Core Path Definition crates/relayburn-sdk/src/ledger/paths.rs	Default ledger_home() now constructs paths under ~/.agentworkforce/burn instead of ~/.relayburn; RELAYBURN_HOME env var continues to override. Test module adds a static ENV_LOCK mutex for serializing parallel tests that mutate HOME and RELAYBURN_HOME, plus new unit tests verifying default path and override precedence.
Archive Directory Resolution crates/relayburn-sdk/src/analyze/ghost_surface.rs	default_archive_dir() now uses crate::ledger::ledger_home().join("ghost-archive") instead of home_dir().join(".relayburn"), delegating to the centralized path function.
Config & Public API Docs crates/relayburn-sdk/src/ledger/config.rs, crates/relayburn-sdk/src/lib.rs, crates/relayburn-sdk-node/src/lib.rs	Doc comments for ledger config path and LedgerOpenOptions default home now reference ~/.agentworkforce/burn.
Test & Ingest Docs crates/relayburn-sdk/src/ingest/orchestration_tests.rs, crates/relayburn-sdk/src/ingest_verb.rs, crates/relayburn-sdk/tests/integration.rs	Test module and integration comments updated to reflect the new default directory; no executable logic changes.
CLI & Harness Documentation crates/relayburn-cli/src/cli.rs, crates/relayburn-cli/src/harnesses/codex.rs, crates/relayburn-cli/src/harnesses/opencode.rs	Help text and inline comments for GlobalArgs::ledger_path, burn state command, and harness adapters updated to reference ~/.agentworkforce/burn as the default fallback.
Release Notes CHANGELOG.md	New [Unreleased] entry for relayburn-sdk documents the default path move, override behavior via RELAYBURN_HOME and per-DB environment variables, and migration guidance (with incompatibility warning that non-2.0 layouts require burn ingest repopulation).

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly Related PRs

• AgentWorkforce/burn#320: Updates opencode harness module and defaults documentation alongside related path changes.
• AgentWorkforce/burn#302: Added the ingest verb and IngestOptions in ingest_verb.rs; this PR updates docs and tests in the same file.
• AgentWorkforce/burn#304: Adds integration tests that isolate RELAYBURN_HOME; this PR refines the default ledger home logic and test serialization.

Poem

🐰 The burrow moves east, from reef to new ground,
To share the same forest where two paths are found.
No collision, no chaos—just .agentworkforce cheer,
As Rust 2.0 and TypeScript coexist here! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and accurately summarizes the main change: moving the default ledger home path from ~/.relayburn to ~/.agentworkforce/burn, which is the primary objective of this PR.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing the motivation, implementation, scope, migration path, and testing approach for the ledger home directory relocation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rust-port/home-dir-rename

---

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