Architecture: deepen local runtime seams

[ElbertePlinio]

Goal

Concentrate repeated local runtime policy into a few deep modules so future browser, storage, and provisioning work changes one implementation rather than lockstep CLI/MCP or command paths.

Why

Current source duplicates local session lifecycle composition across CLI and MCP, splits local teardown between explicit destroy and reaping, divides run verification among readers, and leaves provisioning privilege metadata outside execution policy. This increases change cost and makes the important interface test surface hard to exercise once.

Top priority

PR 1 — Centralize local session lifecycle composition. It removes source-confirmed duplicate transaction policy with high confidence and medium risk, while preserving browser ownership, viewer behavior, evidence wrapping, and control-state separation.

Architecture constraints

• Browser sessions continue to own their private display and browser lifecycle.
• A combined desktop+Android request remains a recipe for separate local records.
• Human-control authority remains in lease/permit files, never authoritative session JSON (Add supervised pause and human takeover #21).
• MCP never invokes sudo; graphical approval belongs only to Support secure graphical sudo prompts for agent commands #27.
• MCP artifact output remains confined to the project; CLI --out remains unrestricted.
• Android target ambiguity fails closed.
• Store run artifacts outside project repositories by default #34 writes new data at one resolved location, reads legacy data, and never automatically migrates it.
• Cloud Labs (Add cost-aware GCP Cloud Labs #39/Add Pickforge Pro Managed Cloud Labs #41) remain above the local PID/display session model.

Scope / acceptance checklist

• One local lifecycle implementation owns recipe expansion, rollback, typed destroy dispatch, and canonical status aggregation; CLI/MCP output behavior remains unchanged.
• Reaper and explicit destroy use one typed runtime teardown owner; retry and durable finalization semantics remain characterized.
• One verified run catalog owns root precedence, directory/manifest binding, ordering, and verified reads before Store run artifacts outside project repositories by default #34 storage modes land.
• One provisioning implementation owns consent, dry-run, privilege routing, cancellation, and partial results; no credential material is captured or persisted.
• Focused characterization tests cover the retained invariants before each migration.
• Typecheck and build pass for every PR; full validation follows normal repository policy.

Dependency-ordered PR plan

PR 1 — Centralize local session lifecycle composition

• Depends on: none
• Touches: CLI/MCP session adapters, MCP session resources, shared local lifecycle implementation, focused lifecycle tests
• Prove: desktop+Android rollback, abort behavior, browser status, destroy-all partial failures, and adapter-specific viewer/evidence behavior remain unchanged
• Validation: bun run test packages/cli/test/commands.test.ts packages/mcp-server/test/tools.test.ts packages/mcp-server/test/browser.test.ts; bun run typecheck; bun run build
• Link: pending

PR 2 — Route reaper teardown through typed runtime ownership

• Depends on: PR 1 preferred; coordinate with Harden pre-identity browser daemon cleanup #29
• Touches: core reaper, desktop/Android/browser teardown adapters, reaper/destroy characterization tests
• Prove: explicit destroy and reaping share typed stop outcomes; failed cleanup retains retryable state; durable finalization remains correct
• Validation: focused core session/reaper plus desktop, Android, and browser destroy tests; bun run typecheck
• Link: pending

PR 3 — Establish verified run catalog and land #34 storage resolver

• Depends on: none
• Touches: core run/evidence/path/config logic, CLI artifacts, MCP resources, storage compatibility tests
• Prove: verified reads bind manifest identity to its directory; legacy runs remain readable; new writes follow configured storage mode with no automatic migration
• Validation: bun run test packages/core/test/run.test.ts packages/core/test/evidence.test.ts packages/mcp-server/test/resources.test.ts; focused Store run artifacts outside project repositories by default #34 config/path tests; bun run typecheck; bun run build
• Link: pending

PR 4 — Deepen provisioning execution policy

• Depends on: none; Support secure graphical sudo prompts for agent commands #27 follows through this implementation
• Touches: provisioning executor, setup-lab-user, setup-android, doctor, init, planner/executor tests
• Prove: consent, dry-run, privileged routing, cancellation, and partial failures are consistent across commands without changing command wording
• Validation: bun run test packages/cli/test/executor.test.ts packages/cli/test/planner.test.ts packages/cli/test/cli.test.ts; bun run typecheck; bun run build
• Link: pending

Existing issue coordination

• Add first-class browser computer use with live session viewing #17: preserve browser ownership and evidence direction.
• Add supervised pause and human takeover #21: preserve lease/permit authority separation.
• Support secure graphical sudo prompts for agent commands #27: owns graphical privilege execution and uses PR 4’s execution policy.
• Harden pre-identity browser daemon cleanup #29: remains the narrow browser cleanup hardening; coordinate with PR 2.
• Store run artifacts outside project repositories by default #34: PR 3 is its storage implementation architecture.
• Add cost-aware GCP Cloud Labs #39/Add Pickforge Pro Managed Cloud Labs #41: no local session or cloud abstraction work in this plan.
• Standardize isolated Flutter component previews #43: no runtime work in this plan.

Non-goals

• No generic session plugin registry.
• No merge of CLI and MCP adapters.
• No provider-neutral cloud abstraction before a proven provider implementation.
• No broad evidence-journal split.
• No automatic storage migration.
• No new runtime command for Standardize isolated Flutter component previews #43.

No-feature-flag decision

No feature flag. Each PR is an internal refactor or backward-compatible storage rollout with preserved current defaults and independently reviewable behavior.

Audit commit snapshot

de467fbd14d00d4afa4946f610d05d724a6fa777 on main.

Current status

Planned.

Next action

Open PR 1 with characterization tests and migrate only local lifecycle composition; do not combine teardown, storage, or privilege execution changes.

[ElbertePlinio]

CAND-1 landed in #49: createLocalSessions/destroyLocalSessions/status aggregation now live in packages/core/src/session-lifecycle.ts; CLI and MCP adapters route through it with unchanged output. CAND-2 (reaper teardown routing) now has its preferred placement available.

[ElbertePlinio]

CAND-2 started on refactor/reaper-typed-teardown from current origin/main (including #47 and #49). Scope is limited to routing opportunistic reaping through typed runtime teardown ownership while preserving core retry/finalization policy; coordinating with #29 by preserving browser PID-reuse refusal and retryable cleanup semantics.

[ElbertePlinio]

CAND-2 is implemented in #50. Reaping now composes the desktop, Android, and browser typed teardown owners; core retains registry/liveness/retry/evidence policy, and the duplicate stopRecordedPids path is removed.

Validation: core + all runtime suites + CLI/MCP session tests (644 passed, 2 skipped), focused post-review fix tests (47 passed), typecheck, and build. Local serious-backend review found one Android reused-serial ownership issue; it was fixed and targeted verification is clean.

[ElbertePlinio]

CAND-3 is implemented in #52. One verified run catalog now owns current-root discovery/precedence, directory-manifest identity binding, corrupt-entry handling, deterministic ordering, duplicate IDs, and verified root-file reads. Core listRuns, evidence retention, CLI artifacts, MCP artifact tools, and MCP resources now use the catalog.

The seam is ready for #34 to plug in storage-mode roots later; this PR intentionally adds no new storage modes, migration, or write-location changes.

Validation: core run/catalog/evidence (93 passed), MCP resources/tools (58 passed), CLI commands (43 passed), typecheck, and build. Serious-backend local review and targeted fix verification are clean.

[ElbertePlinio]

All four candidates landed: #49 (central session lifecycle), #50 (typed reaper teardown), #52 (verified run catalog — ready for #34 storage modes), #51 (provisioning executor policy). Main CI green.