Maestro Session Manage

• background: false is the default. Use foreground dispatch whenever the result determines the current answer or next action.
• Use background: true only for independent work. If this turn must consume a background result, call observe exactly once with action: "wait" and a bounded timeout before continuing; never continue independently while the result is pending.
• Otherwise end the turn and wait for the automatic teammate-complete notification. Do not rely on SendMessage, team_msg, or hook callbacks as completion signals.
• Never silently ignore an unfinished dispatch.

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

Shared flags:

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 `[@ask] user prompt`:

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.

</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 (`--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>