Add finalized orchestration summaries

.agent/docs/architecture/agent-orchestrator.md

@@ -145,14 +145,34 @@ the same compact table style while preserving their hidden durable markers.
 If terminal child metadata is found but rejected by trust checks or cannot be
 safely updated, the dispatcher posts a compact stop comment on the current
 terminal issue or PR with a hidden dedupe marker. Ordinary terminal PR stops
-without sub-orchestrator metadata remain silent.
+without sub-orchestrator metadata post or update one finalized orchestration
+note. The note summarizes the source action and conclusion, target, round,
+reason, source run, and any planner-provided user message. It mentions the
+original requester only when the requester is a human-looking GitHub login,
+never the configured agent handle or a bot identity. When orchestration
+reporting is explicitly enabled, a deterministic write-scoped job publishes a
+non-cancellable progress note in parallel with the read-only planner. The
+resolver updates that note and supersedes any older final marker; otherwise it
+upserts the final note by the hidden `sepo-agent-orchestrate-final` marker.
+Trusted notes carrying the legacy `sepo-agent-orchestrate-stop` marker are
+updated in place and rewritten with the current marker during the next terminal
+run.
 If the resumed parent planner decides there is no next child or action, the
 parent run posts a terminal stop comment on the parent issue with the source
-conclusion, target, round, reason, and hidden `sepo-agent-orchestrate-stop`
-marker. Exact trusted duplicates are skipped on reruns.
+conclusion, target, round, reason, and hidden `sepo-agent-orchestrate-final`
+marker. Reruns update the trusted marker comment instead of posting duplicates.
 When the planner returns `blocked` with `user_message` or
 `clarification_request`, that same terminal comment surfaces the planner's
 question directly and the chain pauses without dispatching an `answer` route.
+After a PR ends with `review`/`SHIP`, `agent-self-approve`/`approved`, or
+`agent-self-merge`/`merged` or `auto_merge_enabled`, the dispatcher also marks
+older trusted review synthesis, rubrics review, fix-pr status, and handoff
+comments as outdated. In agent mode, success wording and cleanup also require a
+validated terminal `stop` decision from the planner; missing or malformed
+planner responses retain the artifacts and report a non-successful stop.
+Finalized orchestration notes are excluded from every cleanup matcher, and
+cleanup is skipped when the planner blocks or requests clarification.
+`AGENT_COLLAPSE_OLD_REVIEWS=false` disables that cleanup.
 
 Initial user-launched `/orchestrate` requests validate that the requester has
 access to the delegated route capability set before dispatching work. When
@@ -180,7 +200,7 @@ In `heuristics` mode, action-originated handoff decisions still use the fixed tr
 
 Review-originated `fix-pr` handoffs carry explicit task context when available. The review dispatcher derives it from the latest review synthesis action items, and heuristic mode falls back to a conservative instruction to address only unresolved review synthesis action items while ignoring optional INFO notes and metadata-only polish. When a review synthesis recommends `HUMAN_DECISION`, self-approval-enabled orchestration routes to `agent-self-approve` instead of `fix-pr` or a human stop; self-approval then decides whether to approve, request changes, or block. Manual PR `/orchestrate` starts with a `CHANGES_REQUESTED` review decision use separate context that tells `fix-pr` to address the latest unresolved requested-change review comments instead of the review-synthesis fallback. Self-approval `REQUEST_CHANGES` handoffs preserve the approval agent's handoff context as the `fix-pr` task. Self-approval `APPROVED` handoffs dispatch `agent-self-merge` only when `AGENT_ALLOW_SELF_MERGE=true`.
 
-In `agent` mode, the orchestrator first runs a scoped planner prompt through the same resolved-provider runtime used by other agent actions. The planner has its own `orchestrator` route and `planner` lane, so session continuation is separate from implement, review, and fix-pr sessions. The planner runs with `approve-all` tool permission so it can gather current GitHub and repository context in non-interactive workflows. It still receives read-only repository memory, selected read-only rubrics, the handoff envelope, any source handoff context, and original request, and returns JSON describing whether to stop, block, delegate a child issue, or hand off. For blocked decisions, the planner may return `user_message` or `clarification_request` to ask for missing context in the visible stop comment. For handoffs, the planner may also return `handoff_context`: explicit, action-oriented instructions for the next workflow. When the next action is `fix-pr`, the dispatcher passes that context into `agent-fix-pr.yml`, and the fix-pr prompt treats it as the selected task and constraints for the automated fix pass. The workflow uses the runtime preflight CLI to skip this planner when the max-round budget is already exhausted or the initial requester lacks delegated-route capability, and the runtime still validates planner JSON against the fixed transition policy, the issue-only direct-implement rule, and max-round budget before dispatching anything.
+In `agent` mode, the orchestrator first runs a scoped planner prompt through the same resolved-provider runtime used by other agent actions. The planner has its own `orchestrator` route and `planner` lane, so session continuation is separate from implement, review, and fix-pr sessions. The planner runs with `approve-all` tool permission so it can gather current GitHub and repository context in non-interactive workflows, but its job and GitHub token remain read-only. The planner-local progress reporter is explicitly disabled. If `AGENT_PROGRESS_POLICY.orchestration_mode` is `report-only`, a parallel deterministic job resolves write-capable authentication and publishes the progress note; publication failures remain visible while the final-marker fallback still runs. The planner uploads its JSON response as a short-lived artifact and uploads any configured session bundle without registering it. A separate deterministic job downloads the response, resolves write-capable GitHub authentication, persists the planner thread state and bundle registration for the next round, validates the transition, and owns final comments, minimization, and workflow dispatch. The planner still receives read-only repository memory, selected read-only rubrics, the handoff envelope, any source handoff context, and original request, and returns JSON describing whether to stop, block, delegate a child issue, or hand off. For blocked decisions, the planner may return `user_message` or `clarification_request` to ask for missing context in the visible stop comment. For handoffs, the planner may also return `handoff_context`: explicit, action-oriented instructions for the next workflow. When the next action is `fix-pr`, the dispatcher passes that context into `agent-fix-pr.yml`, and the fix-pr prompt treats it as the selected task and constraints for the automated fix pass. The workflow uses the runtime preflight CLI to skip this planner when the max-round budget is already exhausted or the initial requester lacks delegated-route capability, and the runtime still validates planner JSON against the fixed transition policy, the issue-only direct-implement rule, and max-round budget before dispatching anything.
 
 When an orchestrator-launched `implement` or `fix-pr` run reports
 `no_changes`, `failed`, `verify_failed`, or `unsupported`, the dispatcher stops
@@ -194,7 +214,16 @@ Before dispatching, the orchestrator checks for a hidden handoff marker on the d
 
 ## Permission note
 
-`agent-orchestrator.yml` requests `actions: write` because `workflow_dispatch` requires it, and `issues: write` to persist dedupe markers on destination issues or pull requests.
+The planner job grants only read access to actions, contents, issues, and pull
+requests. A model-free progress job requests issue and pull-request write access
+only for configured report-only publication. The separate deterministic
+decision job requests `actions: write` for `workflow_dispatch`, `issues: write`
+for issue markers, and `pull-requests: write` for finalized PR notes and trusted
+artifact cleanup. It also requests `contents: write` only for deterministic
+planner thread-state and session-bundle metadata refs; that credential is never
+passed to the planner model. The decision job uses a cancellation-aware
+condition while still running after ordinary planner or artifact-transfer
+failures so it can publish a safe stop.
 
 ## Extension path
 

.agent/docs/architecture/request-lifecycle.md

@@ -26,7 +26,7 @@ By default, an explicit mention without a slash command resolves locally to `ans
 
 PR fix requests never create a tracking issue or a new pull request. The runner updates the existing PR branch after reading PR metadata and review comments. Dirty worktree changes are committed and pushed back to the PR branch; clean history-only updates, such as a successful rebase, run verification against the original PR head and then push the updated `HEAD` back to the PR branch with a lease against that original head. If persistence fails after a successful agent run, the final status comment reports the run as failed. Automatic pushing is limited to open same-repository pull requests, and route access follows the configured trigger access policy.
 
-Direct implementation and PR-fix runs publish a live progress comment on issue and pull request surfaces by default, while answer runs use report-only progress by default. The shared `run-agent-task` action starts a best-effort reporter before the agent run, passes it the agent's ACP stream file, and tears it down after the run. If the reporter created a comment, the final issue/PR response step patches that same comment with the substantive result first and a collapsed activity log below it; otherwise it falls back to posting the normal final comment. An authorized 👎 reaction from the requester, repository owner, member, or collaborator first marks cancellable progress comments as cancelled, then requests GitHub Actions cancellation. `AGENT_PROGRESS_POLICY` can disable the comment or switch a route to `report-only`; review runs remain disabled by default. Runs with explicit orchestration context ignore normal route progress overrides, default to no progress comment, and report state through orchestrator handoff or status comments unless `orchestration_mode` explicitly opts into report-only progress.
+Direct implementation and PR-fix runs publish a live progress comment on issue and pull request surfaces by default, while answer runs use report-only progress by default. The shared `run-agent-task` action starts a best-effort reporter before the agent run, passes it the agent's ACP stream file, and tears it down after the run. If the reporter created a comment, the final issue/PR response step patches that same comment with the substantive result first and a collapsed activity log below it; otherwise it falls back to posting the normal final comment. An authorized 👎 reaction from the requester, repository owner, member, or collaborator first marks cancellable progress comments as cancelled, then requests GitHub Actions cancellation. `AGENT_PROGRESS_POLICY` can disable the comment or switch a route to `report-only`; review runs remain disabled by default. Runs with explicit orchestration context ignore normal route progress overrides, default to no progress comment, and report state through orchestrator handoff or status comments unless `orchestration_mode` explicitly opts into report-only progress. The orchestrator planner itself remains read-only and disables its local reporter; a separate deterministic write-scoped job publishes its configured report-only note and surfaces publication failures before the resolver finalizes or falls back from that note.
 
 ## Branch naming
 

.agent/docs/customization/configuration-list.md

@@ -85,7 +85,7 @@ The bundled workflows still keep native YAML escape hatches: an inline `route_pr
 }
 ```
 
-`enabled` starts the progress comment and allows authorized 👎 cancellation. `report-only` starts the progress comment but ignores cancellation reactions. `disabled` preserves the normal run without a progress comment. Malformed policy disables progress for that run instead of failing the workflow. Orchestrated chains default to `disabled` progress mode and rely on handoff or status comments; set `orchestration_mode` to `report-only` to opt into non-cancellable progress comments for orchestrated runs. `enabled` is not accepted for `orchestration_mode` because cancellable chained-run semantics are not defined.
+`enabled` starts the progress comment and allows authorized 👎 cancellation. `report-only` starts the progress comment but ignores cancellation reactions. `disabled` preserves the normal run without a progress comment. Malformed policy disables progress for that run instead of failing the workflow. Orchestrated chains default to `disabled` progress mode and rely on handoff or status comments; set `orchestration_mode` to `report-only` to opt into non-cancellable progress comments for orchestrated runs. The orchestrator planner keeps its GitHub token read-only, so a parallel model-free write job publishes that configured note and the resolver finalizes it. `enabled` is not accepted for `orchestration_mode` because cancellable chained-run semantics are not defined.
 
 ## Repository secrets
 

.agent/docs/usage/internal-actions.md

@@ -11,7 +11,7 @@ Internal actions are shared composite GitHub Actions under `.github/actions/`. T
 | `.github/actions/resolve-agent-provider` | Resolves the provider, pinned default model, and optional reasoning effort for single-agent runs, reviewer lanes, and review synthesis before runtime setup | `route`, `route_provider`, `default_provider`, `model_policy`, `openai_api_key`, `claude_oauth_token`, `anthropic_api_key`, `required` | outputs `provider`, `reason`, `install_codex`, `install_claude`, `model`, and `reasoning_effort`; selects explicit inline overrides, route provider overrides from `AGENT_MODEL_POLICY`, or `AGENT_DEFAULT_PROVIDER`, otherwise auto-detects from configured provider secrets; uses Sepo's built-in provider model default unless `AGENT_MODEL_POLICY` overrides it |
 | `.github/actions/check-agent-action-expiration` | Shared expiration guard for generated scheduled agent workflows | `expires_at` | outputs `expired`, `expires_at`, and `today`; validates a UTC `YYYY-MM-DD` expiration and skips generated workflows after that date without relying on GNU-only `date -d` parsing |
 | `.github/actions/run-skill-setup` | Checks a repository skill and runs its optional `setup.sh` hook | `skill`, `skill_root`, `trusted_ref`, `run_setup` | outputs `exists`, `skill_path`, `setup_exists`, `setup_ran`, and `setup_path`; refuses setup from untrusted PR checkout refs |
-| `.github/actions/run-agent-task` | Runs a prompt or skill through the runtime and `acpx` | `prompt`, `skill`, `agent`, `model`, `display_model`, `reasoning_effort`, `route`, `agent_cwd`, `lane`, `target_*`, `source_kind`, `request_source_kind`, `request_comment_id`, `request_comment_url`, `request_text`, `session_policy`, `session_bundle_mode`, `memory_policy`, `memory_mode_override`, `memory_ref`, `rubrics_policy`, `rubrics_mode_override`, `rubrics_ref`, `rubrics_limit` | renders the prompt, runs `.agent/dist/run.js` from `agent_cwd` when provided, captures response/session files, exposes `model_display` when enabled, passes configured model-provider credentials through, restores and uploads session bundles when enabled, resolves memory/rubrics modes, optionally mounts `agent/memory` and `agent/rubrics`, and commits permitted memory or validated rubric edits |
+| `.github/actions/run-agent-task` | Runs a prompt or skill through the runtime and `acpx` | `prompt`, `skill`, `agent`, `model`, `display_model`, `reasoning_effort`, `route`, `agent_cwd`, `lane`, `target_*`, `source_kind`, `request_source_kind`, `request_comment_id`, `request_comment_url`, `request_text`, `session_policy`, `session_bundle_mode`, `defer_session_state_persistence`, `memory_policy`, `memory_mode_override`, `memory_ref`, `rubrics_policy`, `rubrics_mode_override`, `rubrics_ref`, `rubrics_limit` | renders the prompt, runs `.agent/dist/run.js` from `agent_cwd` when provided, captures response/session files, exposes `model_display` when enabled, passes configured model-provider credentials through, restores and uploads session bundles when enabled, can defer thread-state and bundle-registration writes to a separately authorized caller, resolves memory/rubrics modes, optionally mounts `agent/memory` and `agent/rubrics`, and commits permitted memory or validated rubric edits |
 | `.github/actions/download-agent-memory` | Best-effort shallow clone of the repo-local `agent/memory` branch into `$RUNNER_TEMP/agent-memory` so the agent can read and write memory without staging it on the feature branch | `github_token`, `ref`, `path`, `continue_on_missing` | outputs `memory_available`, `memory_dir`, `memory_ref` |
 
 `resolve-github-auth` keeps deterministic auth misconfiguration failures explicit. The hosted OIDC broker path retries short-lived transport failures and broker HTTP `429`, `500`, `502`, `503`, or `504` responses with bounded backoff; generic broker `400` responses remain terminal so request/auth bugs are not hidden.

.agent/docs/usage/supported-workflows.md

@@ -71,9 +71,21 @@ Planner-based selection is also used for action-originated handoff runs. The pla
 `handoff_context` string for the next action; `fix-pr` receives it as explicit
 initial steering when the planner dispatches a PR-fix pass. The planner mounts
 memory and rubrics read-only so automated control-flow planning can use steering
-context without mutating those state branches. Orchestration stops when target
-state indicates no safe next action, a route fails, a duplicate handoff marker
+context without mutating those state branches, and it receives a read-only
+GitHub token. A separately permissioned deterministic job validates and applies
+the uploaded planner response, persists planner thread state, and registers any
+uploaded session bundle before dispatching the next round. Orchestration stops
+when target state indicates no safe next action, a route fails, a duplicate handoff marker
 is found, the planner stops or blocks, or the max-round budget is exhausted.
+Terminal PR runs publish one marker-upserted finalized note that summarizes the
+outcome and mentions the original requester only for human GitHub logins. When
+orchestration `report-only` progress is enabled, a separate model-free,
+write-scoped job publishes that note while the planner retains a read-only
+token. The deterministic resolver turns it into the finalized note instead of
+creating a separate comment; publication failures are visible and fall back to
+the final marker note.
+Trusted legacy `sepo-agent-orchestrate-stop` notes are migrated in place to the
+current `sepo-agent-orchestrate-final` marker.
 
 When a child issue reaches a terminal stop, the handoff dispatcher resolves the
 trusted child metadata from the issue body or an agent-authored child issue
@@ -122,6 +134,9 @@ HTML markers for robust matching, with heading/text fallbacks for older
 comments. Rubrics reviews match the `## Rubrics Review` heading, and
 orchestrator handoffs match their hidden handoff marker. This keeps the latest
 generated status prominent while leaving older generated comments expandable.
+Successful terminal PR orchestration also collapses these trusted review and
+handoff artifacts after publishing its finalized note, except when the planner
+blocks or requests clarification. Finalized notes are never cleanup candidates.
 Set `AGENT_COLLAPSE_OLD_REVIEWS=false` to skip this cleanup and leave prior
 generated comments visible.