feat(subagents): allow embedders to isolate runtime state roots

[cacdcaecawae]

Summary

• add an optional EngineConfig::subagent_state_root for embedding hosts that need session-owned delegated-agent state
• keep child execution cwd, file authority, receipts, and the legacy workspace/.codewhale/state default unchanged
• move the worker ledger, complete transcript artifacts, coordination lock, cleanup, and resume_from transcript reads behind the selected state root
• retain source-compatible manager/load helpers while adding explicit-state-root variants
• document that distinct state roots are distinct coordination domains and do not arbitrate writes to a shared execution workspace

This is a partial building block for #4416. It intentionally does not implement durable session ownership, cross-session history union, or write arbitration, and therefore does not close that issue.

Why

Embedding applications can bind multiple conversations to the same project workspace. Today those conversations necessarily share delegated-agent persistence and coordination files under the project. Filtering a shared ledger after the fact cannot provide isolation and still leaves concurrent writers. A host-owned state root separates lifecycle/control-plane storage without changing where agents execute.

The default remains byte-for-byte compatible at the API behavior level: callers that leave the field unset continue to use <workspace>/.codewhale/state.

Testing

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --all-features --locked (warning-free under the CI allow list)
• cargo test --workspace --all-features --locked

Additional checks run:

• cargo check -p codewhale-tui --locked
• explicit_state_roots_isolate_managers_for_the_same_execution_workspace
• resume_from_loads_transcript_artifact_when_available
• adjacent persistence/transcript/process-lock/session-projection regression tests

The two repository TUI suite commands were also run on Windows:

• cargo test -p codewhale-tui --bins --locked
• cargo test -p codewhale-tui --tests --locked

Both execute the same 9,683 binary tests here and ended at 9,661 passed / 14 failed / 8 ignored. The failures are in untouched shell execution, runtime handoff timing, file-mention indexing, TUI responsive-layout, and fleet-detail tests; the new isolation and resume tests pass independently. This draft does not report the full suite as green.

cargo clippy --workspace --all-targets --locked -- -D warnings is also not green on current main with this Windows/Rust 1.97 toolchain: it promotes 43 existing warnings in untouched TUI visibility and command files (including private_interfaces, match_result_ok, and needless_return). No warning points to the changed state-root code.

Checklist

• Updated docs or comments as needed
• Added or updated tests where relevant
• Verified TUI behavior manually if UI changes — N/A, no TUI surface changes
• Harvested/co-authored credit uses a GitHub numeric noreply address — N/A, no harvested code or co-author

[github-actions]

Thanks @cacdcaecawae for taking the time to contribute.

This repository is observing a maintainer-managed PR intake gate in dry-run mode, so this pull request is staying open. This note helps maintainers prepare the allowlist before any enforcement is considered.

Please read CONTRIBUTING.md for the expected contribution shape. A maintainer can grant recurring PR access by commenting /lgtm on a pull request.

[github-actions]

Thanks @cacdcaecawae — your contribution landed in 43f933ca5da6 on main:

Merge embedder-owned sub-agent state roots

Closing this PR now that the code is on main. Credit lives in the commit message and (where applicable) the CHANGELOG.md entry for the next release. Apologies for not closing this at the time of the merge — the auto-close workflow is new in v0.8.31.

If you want to land more work and would prefer your future PRs merge cleanly without a harvest step, the CONTRIBUTING.md doc has a short note on what makes a contribution mergeable as-is.