refactor(tui): adopt command shapes in session lifecycle slice (FEAT-023)

[aboimpinto]

Summary

FEAT-023 converts the TUI session lifecycle slice to portable command shapes while keeping the production files in codewhale-tui:

• /branch
• /compact
• /fork
• /load
• /new
• /purge
• /save
• /sessions
• /tree

Baseline: current origin/main at a58ef2d52. The branch is eight signed commits ahead with no merge commits.

This PR:

• adds the contract-owned CommandSessionLifecycleContext facet and portable lifecycle DTOs;
• adds SESSION_LIFECYCLE with exact restricted-envelope projection;
• keeps CommandCapabilities storage at u16 while allocating the next free identity (SESSION_LIFECYCLE, bit 13);
• keeps /compact and /purge pure with CommandCapabilities::NONE and no host context bundle;
• declares only SESSION_LIFECYCLE for the seven host-dependent handlers;
• keeps concrete App, session manager, journal, picker, persistence, configuration, Work-state, and reset behavior inside SessionLifecycleAdapter;
• registers all nine handlers through the public contextual dispatch seam;
• retains the root session migration frontier for FEAT-024 through FEAT-026;
• moves TUI-bound acceptance and persistence-regression suites outside the future movable groups/session directory;
• makes portable handlers the single transition-gate authority and pins exact gate order/call counts.

Tracking: EPIC-006 / FEAT-023 in umbrella #5316.

Dependency boundary

Portable lifecycle handlers do not access concrete App, SessionManager, session journals, picker views, configuration, history cells, host callbacks, or service locators. Missing lifecycle authority fails closed with:

Command capability unavailable: session_lifecycle

The remaining staged dependencies are explicit:

• FEAT-037 owns CommandResult, AppAction, synchronization mapping, and mode conversion;
• FEAT-016 owns the shared registry bridge/import boundary needed before physical group moves;
• FEAT-043 owns the final physical session-group move and keeps TUI acceptance/regression fixtures host-side.

No new crate dependency and no physical production-file move occur here. codewhale-command-contract remains independent of codewhale-tui.

Behavior and scope

• Structural migration only: command names, aliases, registry order, parsing, check order, messages, actions, persistence behavior, and output remain unchanged.
• Active-session and explicit-source forks use distinct portable receipts so explicit spawn_depth is mandatory rather than silently defaulted.
• Out-of-scope session control, export, and structcopy commands remain for FEAT-024, FEAT-025, and FEAT-026.
• No localization extraction (FEAT-036), shared outcome move (FEAT-037), or physical group move (FEAT-043).
• No Gherkin expectations changed.

Testing

• cargo fmt --all -- --check
• strict Clippy for codewhale-command-contract and codewhale-tui with --all-targets --all-features --locked -D warnings
• command-contract tests — 47 passed
• portable lifecycle handlers — 8 passed
• retained lifecycle regressions through public dispatch — 29 passed
• adapter/public dispatch lifecycle coverage — 8 passed
• restricted-envelope coverage — 1 passed
• public dispatch seam — 2 passed
• session acceptance scenarios with long-running-tests — 11 passed
• full TUI library — 11,694 passed
• migration fixtures — 56 passed; frontier remains [config, core, debug, session]
• command-boundary fixtures — 8 passed
• CI wiring tests — 11 passed
• git diff --check
• final-head upstream CI workspace matrix — Linux, macOS, Windows, lint, safety, integrations, DCO, OHOS, npm smoke, web checks, and security checks all passed; conditional jobs skipped as expected

The full TUI run used RUST_MIN_STACK=8388608, --test-threads=1, and removed the harness TMUX marker so terminal-policy tests observed their intended fixtures.

Checklist

• This PR adds a new layer/module/abstraction — CommandSessionLifecycleContext replaces direct host access for exactly nine lifecycle handlers
• Updated docs or comments as needed
• Added or updated tests where relevant
• TUI behavior is unchanged; existing acceptance scenarios pass
• All eight commits carry DCO Signed-off-by trailers
• Harvested/co-authored credit uses a GitHub numeric noreply address — N/A; no harvested/co-authored commits

No-Issue: FEAT-023 is tracked in umbrella issue #5316, which remains open for the remaining EPIC-006 work.

Paulo Aboim Pinto

[Hmbown]

Kind: approve-with-nits. Verified against main (a58ef2d52): CommandCapabilities is u16 with bits 0–12 taken (command-contract/src/handler.rs:20-46), so SESSION_LIFECYCLE = bit 13 is the next free bit and the widening preserves every existing identity — exactly as the PR body states. Scope is law-respecting by construction: command-contract/** + tui/src/commands/** only, no turn_loop.rs, no prompts/text.rs, and lifecycle handlers map into the existing SyncSession action rather than inventing a new authority. Full matrix green, 7/7 commits signed. Nit: the u16→u32 widening is premature while only one new bit is consumed — prefer deferring until bits actually run out, or isolate it in its own commit. The 29 regression + 11 acceptance tests through public dispatch are the right coverage shape.

[aboimpinto]

Addressed the capability-storage nit in 52a53ce3a: CommandCapabilities remains backed by u16, and SESSION_LIFECYCLE uses the available bit 13. The speculative u32 widening is now deferred until the existing bits are exhausted.

Verified with cargo fmt --all -- --check, all 47 codewhale-command-contract tests, and strict Clippy for that crate with all targets and features.

Paulo Aboim Pinto