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

<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 | Auto mode — skip confirmations | 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 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)

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

1. 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, --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"
• "暂不激活"

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

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

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

</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; 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 (--actor, --expected-orchestration-revision, --json) and the transition receipt was verified
• ] Dep-ready sessions identified and activation offered (on --complete)

</success_criteria>