Upstream Readiness Checklist: origin/sessions-redone vs upstream/main

Fetched review baseline:

• upstream/main at 685fd42c3d8b3a3c26b5e96975a8656446a40682
• origin/sessions-redone at cc587a56da074b4e9f3c82c88a97440c02359f52

Range summary after fetch: 50 files changed, +4676 / -278.

This fetched range is focused on the 5-stage lifecycle rollout: canonical lifecycle state, recovery rules, explicit agent reporting, PR/session policy decoupling, and dashboard exposure of split truth.

1. Human Manual Verification

• Manually verify lifecycle behavior on real sessions created before this branch existed. Old metadata without lifecycle v2 fields must load, render, and remain operable.
• Exercise the full session progression on a live repo:
  • spawn
  • working
  • PR opened
  • CI failing
  • review changes requested
  • approved/merge-ready
  • merged
• Exercise failure paths on a live repo:
  • runtime missing/exited
  • stuck/detecting escalation
  • manual kill
  • restore from restorable terminal state
  • closed-unmerged PR
• Verify ao acknowledge and ao report <state> from inside a managed session, including rejection cases for merged, terminated, runtime-dead, and orchestrator sessions.
• Verify the dashboard card lane placement and detail-page truth panels for these states: working, pending review, needs input, detecting, stuck, merged, terminated, closed-unmerged.
• Verify restore affordances are shown only when safe and hidden for merged/non-restorable sessions.
• Verify that a merged PR no longer incorrectly implies the worker runtime must already be dead.
• Verify operator comprehension: on the dashboard, a human should be able to answer separately whether the session is done, whether the PR is open/merged/closed, and whether the runtime is alive.

2. Skeptical Code-Review Agent Focus

Ask a skeptical reviewer to audit these areas in depth:

• packages/core/src/lifecycle-manager.ts
  • transition precedence
  • side-effect ordering
  • detecting-state retry/escalation behavior
  • event emission and observability payload correctness
• packages/core/src/lifecycle-state.ts, packages/core/src/session-manager.ts, packages/core/src/metadata.ts, packages/core/src/agent-report.ts
  • all lifecycle mutations
  • persistence consistency
  • rejection rules for agent self-reporting
  • backward-compat synthesis from old metadata
• packages/core/src/recovery/validator.ts
  • evidence precedence
  • disagreement handling
  • human-vs-auto recovery decision boundaries
• packages/web/src/lib/serialize.ts, packages/web/src/lib/types.ts, packages/web/src/components/SessionCard.tsx, packages/web/src/components/SessionDetail.tsx
  • lifecycle serialization correctness
  • consistency between dashboard card and detail page
  • terminal/restorable/done decisions
• packages/core/src/types.ts
  • required Session.lifecycle field impact on downstream callers/tests/plugins
• packages/core/src/prompt-builder.ts and packages/core/src/prompts/orchestrator.md
  • confirm prompt changes are intentional and do not accidentally alter worker instructions beyond the lifecycle reporting additions

3. Compatibility And Migration Checks

• Confirm old sessions without stateVersion: "2" / statePayload synthesize a correct lifecycle on read with no migration script.
• Confirm Session.lifecycle becoming required does not break any external or semi-external construction sites outside the updated tests/helpers.
• Confirm legacy session.status consumers still behave acceptably via deriveLegacyStatus(), including the newly visible detecting state.
• Confirm existing restore/cleanup behavior remains correct when lifecycle truth disagrees with stale legacy status metadata.
• Confirm web serialization remains compatible with SSR and client rendering when lifecycle is absent on older session payloads.
• Confirm no tracker/SCM webhook behavior regressed because dashboard and API code now lean on lifecycle truth rather than older PR-state inference.

4. Product And Behavior Checks

• Verify split lifecycle truth is actually more helpful than the old single status in the most common operator flows, not just more detailed.
• Verify merged sessions are clearly distinguished from closed-unmerged sessions.
• Verify runtime-dead but PR-open sessions are presented as actionable rather than falsely “done.”
• Verify detecting and related guidance text helps the human understand what AO is waiting on and when intervention is needed.
• Verify active PR sessions remain in working lanes after stage 5 and are not misbucketed as done/pending.
• Verify session-detail truth panels and labels are not noisy or contradictory for ordinary healthy working sessions.

5. Test And Rollout Checks

• Run the required repo checks on the exact fetched branch state to be reviewed upstream:
  • pnpm build
  • pnpm typecheck
  • pnpm lint
  • pnpm test
• Re-run targeted tests for:
  • packages/core/src/__tests__/lifecycle-manager.test.ts
  • packages/core/src/__tests__/agent-report.test.ts
  • packages/core/src/__tests__/recovery-validator.test.ts
  • packages/web/src/lib/__tests__/serialize.test.ts
  • packages/web/src/lib/__tests__/types.test.ts
• Add a manual or automated smoke pass for dashboard rendering against representative old-session and new-session payloads.
• Validate at least one end-to-end scenario where lifecycle metadata is written, reloaded from disk, and shown in the UI after a process restart.
• Have a rollback plan ready. This branch changes canonical state semantics across core and UI, so rollback should be defined before opening upstream.

6. Go / No-Go For Opening The Upstream PR

Go only if all are true

• Manual verification passes on live sessions covering happy path and failure path states.
• A skeptical reviewer signs off on lifecycle mutation correctness and recovery-rule precedence.
• Backward-compatibility checks for old metadata and legacy status consumers are complete.
• The required build, typecheck, lint, and test suite pass on the exact fetched commit.
• The upstream PR description clearly explains the 5-stage rollout and why the split session/PR/runtime model is worth the added complexity.

No-go if any are true

• The UI still presents contradictory answers about done/restorable/terminated/merged.
• Any path allows agent self-reporting to override stronger runtime or PR ground truth incorrectly.
• Detecting/stuck escalation logic still feels too brittle under restart or probe-failure scenarios.
• Old sessions or external constructors break because Session.lifecycle is now mandatory.
• The branch is only green because the manual verification burden was skipped.

Suggested Reviewer Order

1. Review lifecycle mutation and precedence in core.
2. Review backward-compat synthesis and persistence.
3. Review UI serialization and truth rendering.
4. Review manual product behavior on live sessions.
5. Decide go/no-go for the upstream PR.