maestro-session-manage

<required_reading> @/.maestro/workflows/run-mode.md @/.maestro/workflows/codex-run-mode.md </required_reading>

If any required file above was not expanded into context by the host, or its content is no longer in context, Read it explicitly before executing any step.

Session completion (maestro session complete) is part of the default Run loop — Ralph S_DONE, the orchestrator run loop, and Companion all execute it when the chain turns terminal. This command is the management surface: inspection, knowledge candidate review/promotion, and the explicit transitions the default loop does not perform (--complete for manual pipelines, --archive/--unarchive for optional freezing).

Run completion already stages accepted decisions, locked constraints, and explicit maestro knowledge stage entries. This command reviews those receipts; it does not re-extract the same artifacts or write project knowledge through a second path.

Actions (first match wins; default = inspect):

Flag	Effect
(none)	Inspect: session status + session resume-view projection
--complete	Readiness check → knowledge reconciliation → fenced maestro session complete → DAG progression
--archive	Fenced maestro session archive (only from completed/failed; optional freeze)
--unarchive	Fenced maestro session unarchive (only from archived; returns to open)
--knowledge	Knowledge review/promotion only — no lifecycle mutation

Shared flags:

Flag	Effect	Default
--session <id>	Target session (slug or full ID)	active_session_id
-y / --yes	Auto mode — skip confirmations	false
--skip-knowledge	With --complete: leave candidate backlog pending	false

<v3_lifecycle_reference>

open ──complete──> completed ──archive──> archived ──unarchive──> open
  │                                             
  └──fail──> failed ──archive──> archived

Permissions: open = all mutations; completed/failed/archived = none.

• --complete requires: no running Run, every chain step completed/skipped with evidence, no open decision gate (escalated gates pass as recorded concerns).
• --archive is optional: a completed Session identity stays durable either way; archived Sessions cannot host new Runs until --unarchive.
• Every mutation returns a run-response/1.2 envelope with an immutable transition receipt; never edit runtime-owned protocol JSON. </v3_lifecycle_reference>

Step 0: Resolve Target

1. Resolve target session from --session flag or active_session_id
2. Read maestro session status --session {session_id} --json — capture status, orchestration_revision, activity_revision, active_run_ids
3. Route to the selected action below; default (no action flag) → Step 1 (Inspect)

Step 1: Inspect (default)

1. Run maestro session status --session {session_id} --json and maestro session resume-view --session {session_id} --json
2. Report: status, orchestration/activity revision, active runs, open decisions (openDecisions from the ResumeMap), pending publications, and nextActions
3. Suggest the matching action: open decision gates → maestro run decide; active runs → let the Run loop finish; completed → offer --archive; archived → offer --unarchive; open with terminal chain → offer --complete

Step 2: Complete (--complete) — manual-pipeline terminal step

Note: maestro-next suggests --complete when 'Tests green + active session'. Orchestrated flows (Ralph/orchestrator/Companion) complete the Session themselves; use this action only when driving the pipeline manually.

2a. Readiness check

1. Verify status is open (a completed/archived Session needs no completion; archived requires --unarchive first)
2. Verify no active runs (active_run_ids empty; all runs sealed)
3. Verify critical gates passed (entry/exit gates from last verify/review run). If no verify/review run exists in this session, treat gate check as not applicable (pass) but emit W002
4. Verify no open decision gates (session status → decisions[]; open gates block session complete with DECISION_GATE_BLOCKED). If open gates exist → run maestro run decide <point> --verdict proceed|fix first
5. If not ready → display blockers, suggest next action (e.g., "run the review step first")

2b. Knowledge reconciliation (skip to 2c with --skip-knowledge)

1. Run maestro knowledge review {session_id} --json. Treat its Run ledgers, reconciliation policies, diversified matches, and candidate IDs as authoritative; do not rescan outputs to recreate candidates. Use --refresh only when the review reports missing or stale source receipts
2. Explain signal semantics when relevant: search/injection is exposure only; explicit loads are consumed; cited, validated, and contradicted are explicit Run relations
3. Report exact/semantic duplicates, related/extends candidates, potential conflicts, supersession candidates, missing receipts, and promotion eligibility separately. Exact duplicates are suppressed automatically; unresolved review_required candidates cannot be promoted
4. If --skip-knowledge, report the pending/promoting/review-required/suppressed counts and continue. The backlog and reconciliation receipts remain durable after completion
5. Otherwise resolve review-required candidates before promotion with maestro knowledge review {session_id} --resolve <candidate-id> --as duplicate|related|conflict|supersede|unique [--target <knowledge-id>] --reason "<reason>". A target must come from that candidate's evidence-backed matches
6. Present eligible pending candidates via request_user_input:

   question: "以下知识候选项值得晋升到项目知识库吗？"
   options:
     - "晋升全部合格项" (promote all eligible candidates)
     - "逐个选择" (review each candidate)
     - "暂不晋升" (leave backlog pending)
   

7. Promote only through the receipt-aware CLI:
   • Bulk selection → maestro knowledge promote {session_id} --all
   • Explicit selection → repeat maestro knowledge promote {session_id} --candidate <candidate-id> for each selection (comma-separated compatibility remains supported)
   • -y may run --all, which promotes all eligible candidates (observed-only emits a warning) and skips review-required and suppressed candidates. It MUST NOT auto-resolve a candidate without explicit user selection
8. For a replacement candidate, confirm --as supersede and then promote it; promotion creates the successor and links the evolution chain. For coexisting valid rules, confirm related or conflict as appropriate. Never direct-write a candidate that was already promoted successfully

2c. Complete the Session

1. Use the orchestration_revision captured in Step 0 (re-read if any mutation happened since)
2. When the chain is terminal (every Run sealed, every decision terminal), call the complete maestro session complete command from run-mode.md, supplying the exact session_id, --participant, --actor, --request-id, --reason, --expected-orchestration-revision, and --json
3. Verify the transition receipt; never mutate Session lifecycle state or edit runtime-owned protocol JSON. The completed Session identity remains durable and may be archived/unarchived later

2d. DAG progression

1. Read state.json.sessions[] — find sessions that became dep-ready (all depends_on sealed)
2. If dep-ready sessions exist:

   question: "Session {slug} 已完成。推荐激活下一个 session: {next-slug}，是否确认？"
   options:
     - "激活推荐 session"
     - "选择其他 session"
     - "暂不激活"
   

3. If confirmed → set active_session_id to selected session

Step 3: Archive (--archive) — optional freeze

1. Verify status is completed or failed (an open Session must --complete or fail first; archived is already archived)
2. Call the fenced transition with the current orchestration_revision: maestro session archive --session {session_id} --participant {actor_id} --actor {actor_id} --request-id {archive_request_id} --reason "<reason>" [--evidence <ref> ...] --expected-orchestration-revision {orchestration_revision} --json
3. Verify the run-response/1.2 receipt (status: archived, revision incremented). Archived Sessions reject all mutations (create_run/advance_chain/transition_run/add_evidence/decide) until --unarchive

Step 4: Unarchive (--unarchive) — return to open

1. Verify status is archived
2. Call the fenced transition: maestro session unarchive --session {session_id} --participant {actor_id} --actor {actor_id} --request-id {unarchive_request_id} --reason "<reason>" [--evidence <ref> ...] --expected-orchestration-revision {orchestration_revision} --json
3. Verify the receipt (status: open). The Session accepts Runs and chain mutations again; extend it with maestro session chain insert ... and maestro run next

Step 5: Knowledge only (--knowledge)

Run Step 2b (Knowledge reconciliation) without any lifecycle mutation. Leave the Session status unchanged.

Next-step routing

Condition	Suggestion
Next session activated	route step analyze through /maestro-next or the canonical receipt-chained session open -> session chain insert --command analyze --arg "<goal>" -> run next flow
Session archived, later extension needed	maestro-session-manage --session {session_id} --unarchive
Knowledge candidates pending	maestro knowledge review {session_id}
Knowledge health review needed	/maestro-knowledge audit

<error_codes>

Code	Severity	Condition	Recovery
E001	error	Session not found	Check state.json.sessions[] / maestro session list --json
E002	error	Session already completed / archived	Nothing to do; use inspect or --unarchive
E003	error	Active runs exist	Complete or seal pending runs first
E004	error	Critical gates failed	Run verify/review to resolve
E005	error	ORCHESTRATION_REVISION_CONFLICT on archive/unarchive	Re-read session status, retry with fresh revision and new request-id
E006	error	Open decision gate blocks session complete	maestro run decide <point> --verdict proceed|fix
W001	warning	No knowledge candidates found	Proceed
W002	warning	No verify/review run in session — gate check skipped	Consider running verify before completing
W003	warning	Candidate backlog left pending	Review later with maestro knowledge review {session_id}
W004	warning	Reconciliation review remains unresolved	Completion may continue; promotion stays blocked until maestro knowledge review --resolve
</error_codes>

<success_criteria>

• Target session resolved; status/orchestration_revision read from session status before any mutation
• Action matched the current status (complete only from open; archive only from completed/failed; unarchive only from archived)
• Knowledge candidate receipt/backlog and evidence loaded via maestro knowledge review (or deliberately skipped)
• Reconciliation dispositions reviewed; unresolved items were explicitly retained or resolved
• User reviewed candidates, or pending backlog was reported and deliberately retained
• Selected knowledge promoted only through maestro knowledge promote
• Lifecycle mutations used the fenced v3 command set (--participant/--actor/--request-id/--reason/--expected-orchestration-revision/--json) and the transition receipt was verified
• Dep-ready sessions identified and activation offered (on --complete) </success_criteria>