maestro-session-manage

<required_reading> @/.maestro/workflows/run-mode.md @/.maestro/ref/knowledge-closeout.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 every required file explicitly before executing any step; for knowledge closeout, Read @~/.maestro/ref/knowledge-closeout.md explicitly before closeout.

<purpose> Manage the lifecycle of a v3 Session (`session/3.0`) through its read-only projections, knowledge governance, and explicit lifecycle transitions.

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. </purpose>

<context> $ARGUMENTS -- optional session ID and action flags.

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	Bounded auto mode; never grants knowledge publication approval	false
--skip-knowledge	With --complete: leave candidate backlog pending	false

</context>

<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>

<execution>

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 closeout

As completion owner, execute @~/.maestro/ref/knowledge-closeout.md: Review → Refresh → Present → Authorize → Execute → Verify. Review the exact Session with --json; refresh only missing/stale receipts within caller authority. Present candidate IDs/content/evidence/matches/recommendations, obtain explicit human relationship and publication decisions (or verify matching prior authorization), then execute approved adjudication/publication inline with promote --resolve, or use promote --candidate for already eligible fixed approved IDs, one at a time. Relationship-only authorization uses the deprecated review --resolve fallback without publication; material changes require re-presentation and re-confirmation. -y, machine advice, and accepted decisions are not publication approval.

With --skip-knowledge, read the review/backlog counts, report deliberate deferral, and proceed to 2c without refresh/resolution/promotion. Zero candidates, rejection, deferral, or unresolved backlog do not block otherwise valid Session completion. Never fabricate duplicate dispositions to clear rejected/deferred items.

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, --actor, --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} --actor {actor_id} [--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} --actor {actor_id} [--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 and the shared closeout protocol without any lifecycle mutation. Leave the Session status unchanged. If the intent is review-only, do not infer refresh/resolution/publication write authority; present or defer unless separately authorized.

</execution> <completion> ``` === SESSION {ACTION RESULT} === Session: {session_id} Action: {inspect|complete|archive|unarchive|knowledge} Status: {open|completed|archived|failed} (orchestration_revision {n}) Knowledge: {promoted_count} promoted, {pending_count} pending, {review_required_count} review required, {suppressed_count} suppressed Next dep-ready: {next_slug or "none (DAG complete)" or "n/a"} --- STATUS --- Status: DONE ```

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

</completion>

<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; follow the shared closeout protocol for explicit confirmation before promote --resolve (deprecated review --resolve only for relationship-only authorization)
</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 (--actor, --expected-orchestration-revision, --json) and the transition receipt was verified
• Dep-ready sessions identified and activation offered (on --complete) </success_criteria>