@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/docs/install/mcp-tool-integrations.md

@@ -44,7 +44,6 @@ marked **— none**.
 | **SFCC WebDAV logs** | WebDAV log credentials (separate from OCAPI) plus the `sfcc_log_monitor_enabled` flag. | `sfcc_webdav_hostname/username/access_key`, `sfcc_log_monitor_enabled` |
 | **Deep-research flag** | The `deep_research_enabled` config flag on the project (403 otherwise). Web research runs via Gemini/OpenAI. | `config_projects.deep_research_enabled` |
 | **Image provider** | An image model provider (OpenAI DALL·E / Google Imagen). | platform provider config |
-| **Conductor ledger** | The local conductor event ledger (`~/.config/bridge/events.db`) — a local file, not a remote service. | local file |
 
 ## Profiles (a form of BLOCK)
 
@@ -56,13 +55,13 @@ activated. `core` is always implicitly included.
 | Profile | Registered when |
 |---|---|
 | `core` | always |
-| `pipeline-authoring` | `BRIDGE_MCP_PROFILE` includes `pipeline-authoring` or `full` |
-| `conductor` | includes `conductor` or `full` |
-| `sfcc` | includes `sfcc` or `full` — the OCAPI **read** tools and `sfcc_log_query` (2 diagnostics ship in `core`) |
+| `epic_implementer` | includes `epic_implementer` or `full` — the Epic Implementer run tools. The old token `conductor` is not valid and is dropped |
+| `estimation` | includes `estimation` or `full` — `estimate_epic` |
+| `pipeline-authoring` | includes `pipeline-authoring` or `full` — registers **no** tools since BAPI-909; still accepted so old configs keep working |
+| `sfcc` | includes `sfcc` or `full` — the OCAPI **read** tools, `sfcc_log_query`, and the two SFCC diagnostics |
 | `sfcc-write` | includes `sfcc-write` or `full` — the destructive SFCC **write** tools. Independent of `sfcc`: neither group implies the other (BAPI-817) |
 
-The `pipeline-authoring` tools live in `index.ts` alongside core, gated by
-`ACTIVE_GROUPS.has("pipeline-authoring")`.
+`get_pipeline_recipe` was never gated by `pipeline-authoring`; it is a `core` tool.
 
 > **This document deliberately states no tool counts.** Counts drift on every
 > ticket that adds or moves a tool, and nothing here is generated, so a number
@@ -147,7 +146,14 @@ by tier.
 
 | Tool | Dependencies (class) |
 |---|---|
-| `estimate_epic` | Jira **[BLOCK]** (resolves the repo from `jira_ticket_key`); no code-index dep |
+| `estimate_epic` | Jira **[BLOCK]** (resolves the repo from `jira_ticket_key`); no code-index dep; registered only under the `estimation` profile |
+
+**Epic Implementer eligibility:**
+
+| Tool | Dependencies (class) |
+|---|---|
+| `assess_epic_implementer_eligibility` | — none (read-only; predicts which epic children change workflow files from their text; needs no VCS or code index; fails open to `status: "unavailable"`) |
+| `assess_epic_conductor_eligibility` | — none (retired name; always returns `tool_removed` / 410 naming `assess_epic_implementer_eligibility`) |
 
 ### Repository parse / index — VCS
 
@@ -247,21 +253,24 @@ Constraints worth knowing before calling it:
   authoritative, so a tool-side pass followed by a server refusal is expected for a
   legacy approved comment that carries no head proof.
 
-## `conductor` profile
+## `epic_implementer` profile
 
-Profile-gated **[BLOCK]** to register. The local conductor ledger
-(`~/.config/bridge/events.db`) is now driven by the `conductor` CLI and the git hooks
-rather than by MCP tools, so only the epic snapshot remains registered here.
+Profile-gated **[BLOCK]** to register. Both tools are read-only and need an Epic
+Implementer run to exist; for an unknown epic or run they return
+`status: "unknown"` rather than an error. The local event ledger
+(`~/.config/bridge/events.db`) is driven by the `epic-implementer` CLI and the git
+hooks, not by MCP tools.
 
 | Tool | Dependencies (class) |
 |---|---|
-| `get_epic_snapshot` | Profile-gated **[BLOCK]** · Bridge API epic snapshot (Jira epic keys) |
+| `get_epic_snapshot` | Profile-gated **[BLOCK]** · Bridge API epic run state (by epic key) |
+| `explain_run` | Profile-gated **[BLOCK]** · Bridge API epic run state (by run id or epic key; `ticket_key` narrows it) |
 
 ---
 
 ## `sfcc` group
 
-### Always-on diagnostics (ship in `core`)
+### Diagnostics (gated behind the `sfcc` group since BAPI-912)
 
 | Tool | Dependencies (class) |
 |---|---|
@@ -273,7 +282,7 @@ rather than by MCP tools, so only the epic snapshot remains registered here.
 All are profile-gated **[BLOCK]** to register, and all require SFCC OCAPI creds +
 `version` config + a reachable sandbox → SFCC OCAPI **[BLOCK]**.
 
-Every SFCC tool — including the two always-on diagnostics above — additionally
+Every SFCC tool — including the two diagnostics above — additionally
 crosses the resolved-hostname sandbox boundary at invocation time: if the host
 the credentials resolve to is not a recognized developer sandbox, the call is
 refused with `403 TARGET_NOT_SANDBOX` before any request leaves the machine
@@ -331,7 +340,7 @@ wanting both selects `sfcc,sfcc-write` (or `full`).
 | **SFCC OCAPI** | `check_permissions` + every gated SFCC read and write tool | — |
 | **SFCC WebDAV logs** | `sfcc_log_query` | — |
 | **Deep-research flag** | `request_deep_research`, `get_deep_research` | — |
-| **Profile gating** | all `pipeline-authoring`, `conductor`, `sfcc`, and `sfcc-write` tools | — |
+| **Profile gating** | all `epic_implementer`, `estimation`, `sfcc`, and `sfcc-write` tools | — |
 
 ## Notes & caveats
 

package/docs/install/sfcc-integration.md

@@ -80,13 +80,20 @@ future work. No `delete` is granted, because no shipped write tool performs one;
     { "resource_id": "/system_object_definitions",    "methods": ["get"],                  "read_attributes": "(**)", "write_attributes": "(**)" },
     { "resource_id": "/system_object_definitions/**", "methods": ["get", "put", "patch"],  "read_attributes": "(**)", "write_attributes": "(**)" },
     { "resource_id": "/custom_object_definitions/**", "methods": ["get", "put", "patch"],  "read_attributes": "(**)", "write_attributes": "(**)" },
-    { "resource_id": "/site_preferences/**",          "methods": ["get", "patch"],         "read_attributes": "(**)", "write_attributes": "(**)" }
+    { "resource_id": "/sites/*/site_preferences/**", "methods": ["get", "patch"],         "read_attributes": "(**)", "write_attributes": "(**)" }
   ]
 }
 ```
 
 Notes:
 
+- Value writes (`site_preference_values_set`) are site-scoped: they need the mutation
+  resource `/sites/*/site_preferences/**`. The read/search grant keeps the org-level
+  `/site_preferences/**`. **If you pasted an earlier mutation grant, it lacks the
+  site-scoped resource.** Replace `<YOUR_CLIENT_ID>` with your client id in the newly
+  printed grant (`check_permissions` prints it) and paste it again before running
+  value writes.
+- `check_permissions` probes a GET only. It shows read access, not write access.
 - The `client_id` **must match** the Account Manager API client whose credentials you
   put in `dw.json` / `SFCC_*` below. Replace the value above with your own client id if
   it differs.
@@ -127,9 +134,10 @@ Create a `dw.json` in your project root (auto-added to git exclude — never com
 ```
 
 Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`,
-`client-secret`/`clientSecret`/`client_secret`. Use a single config — a multi-entry
-`configs[]` array is rejected outright, not worked around with an explicit `instance`
-(see the README's SFCC section for why). Alternatively, export
+`client-secret`/`clientSecret`/`client_secret`. A single config is simplest. With a
+multi-entry `configs[]` array, pass one of the listed sandbox hostnames as `instance`
+and that config's credentials are used (an unapproved host is refused before any
+credential lookup); without an `instance` the call fails as `multi-sandbox`. Alternatively, export
 `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.
 
 ## 3. Set the repo `version` config field

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.2.66",
+  "version": "0.2.68",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",
@@ -24,10 +24,10 @@
     "LICENSE"
   ],
   "//test": "The `test` script delegates to the bounded launcher (scripts/run-unit-tests.js → src/run-unit-tests-launcher.ts, BAPI-683), which discovers build/*.test.js at runtime and spawns them in size-bounded batches so the argv never exceeds Windows' ~8191-char command-line limit. Two determinism rules from the pre-launcher script are preserved INSIDE the launcher: (1) multi-file batches run WITHOUT --test-force-exit, because that flag makes node:test exit before aggregating per-subprocess summaries and the tally becomes nondeterministic (failures still surface and still set exit 1, but the count cannot be trusted as a completeness signal); (2) build/secret-safety.test.js leaks a handle that holds the event loop ~60s after its tests finish (they run in ~147ms), so the launcher quarantines it into its own single-file --test-force-exit invocation (FORCE_EXIT_QUARANTINE in src/run-unit-tests-launcher.ts) where the tally stays exact. Do NOT add --test-force-exit to batched invocations, and do NOT remove the quarantine, until the underlying handle leak is fixed.",
-  "//version": "BAPI-930: fired by `npm version <level>` AFTER npm rewrites package.json's version field, so the bumped version and the repinned README land in the SAME commit. A bump performed by hand-editing package.json instead of running `npm version` bypasses this hook entirely and must repin manually via `node scripts/sync-readme-host-examples.js` — the `--check` wired into `build` below is the backstop that catches that case.",
+  "//version": "BAPI-930: fired by `npm version <level>` AFTER npm rewrites package.json's version field, so the bumped version, repinned README and version-rendered command mirrors land in the SAME commit. A bump performed by hand-editing package.json instead of running `npm version` bypasses this hook entirely and must repin manually via `node scripts/sync-readme-host-examples.js` and `node ../commands/build.js` — the `--check` wired into `build` below is the backstop that catches that case.",
   "scripts": {
     "build": "node scripts/bundle-version.js && node scripts/sync-readme-host-examples.js --check && node scripts/validate-packaged-command-references.js && node scripts/bundle-readme.js && node scripts/bundle-pipelines.js && node scripts/bundle-commands.js && node scripts/bundle-agents.js && node scripts/bundle-docs.js && node scripts/bundle-agent-guidance.js && tsc && node scripts/sync-readme-merge-workflow.js --check && node scripts/sync-agent-mirrors.js && node scripts/bundle-esbuild.js",
-    "version": "node scripts/sync-readme-host-examples.js --write && git add -- README.md package.json package-lock.json && git commit -m \"chore(mcp-server): release $npm_package_version\" && git tag \"mcp-server/v$npm_package_version\"",
+    "version": "node scripts/sync-readme-host-examples.js --write && node ../commands/build.js && git add -- ../.claude/commands ../.cursor/commands .claude/commands && git add -- README.md package.json package-lock.json && git commit -m \"chore(mcp-server): release $npm_package_version\" && git tag \"mcp-server/v$npm_package_version\"",
     "check:version-generated": "node scripts/bundle-version.js && node scripts/check-version-generated.js",
     "assert:release-identity": "node scripts/assert-release-identity.js",
     "postbuild": "node scripts/prepend-shebang.cjs",

package/pipelines/greenfield-setup.json

@@ -147,134 +147,10 @@
       "description": "Draft the project standards from the committed framing and take one approval"
     },
     {
-      "type": "mcp_call",
-      "id": "upload_architecture_instructions",
-      "tool": "config_field",
-      "params": {
-        "field_name": "architecture_instructions",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/architecture_instructions.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the architecture standard",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "id": "upload_review_instructions",
-      "tool": "config_field",
-      "params": {
-        "field_name": "review_instructions",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/review_instructions.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the code-review standard",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "id": "upload_documentation_instructions",
-      "tool": "config_field",
-      "params": {
-        "field_name": "documentation_instructions",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/documentation_instructions.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the documentation standard",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "id": "upload_unit_testing_instructions",
-      "tool": "config_field",
-      "params": {
-        "field_name": "unit_testing_instructions",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/unit_testing_instructions.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the unit-testing standard",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "id": "upload_e2e_testing_instructions",
-      "tool": "config_field",
-      "params": {
-        "field_name": "e2e_testing_instructions",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/e2e_testing_instructions.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the end-to-end testing standard",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "id": "upload_frontend_correctness_standards",
-      "tool": "config_field",
-      "params": {
-        "field_name": "frontend_correctness_standards",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/frontend_correctness_standards.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the frontend correctness standard",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "id": "upload_backend_correctness_standards",
-      "tool": "config_field",
-      "params": {
-        "field_name": "backend_correctness_standards",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/backend_correctness_standards.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the backend correctness standard",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "id": "upload_template_correctness_standards",
-      "tool": "config_field",
-      "params": {
-        "field_name": "template_correctness_standards",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/template_correctness_standards.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the template correctness standard",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "id": "upload_style_correctness_standards",
-      "tool": "config_field",
-      "params": {
-        "field_name": "style_correctness_standards",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/style_correctness_standards.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the style correctness standard",
-      "on_error": "warn_and_continue"
-    },
-    {
-      "type": "mcp_call",
-      "id": "upload_design_principles",
-      "tool": "config_field",
-      "params": {
-        "field_name": "design_principles",
-        "file_path": "{docs_dir}/greenfield/{repo_name}/standards/design_principles.md",
-        "operation": "update",
-        "only_if_null": true
-      },
-      "description": "Save the design principles",
-      "on_error": "warn_and_continue"
+      "type": "agent_task",
+      "id": "upload_approved_standards",
+      "instruction_file": "greenfield-upload-approved-standards.md",
+      "description": "Upload only standards explicitly approved in the current synthesis result and report partial failures"
     },
     {
       "type": "agent_task",

package/pipelines/implement-ticket.json

@@ -1,7 +1,7 @@
 {
   "name": "implement-ticket",
   "description": "Initial feature workflow: generate a plan, produce artifacts, checkpoint to origin, verify, commit, open a PR, close post-PR gaps, and monitor CI. Re-entry of this initial workflow may reuse a fresh plan, but remaining-work corrections and continuations use versioned focused intent on the retained branch and never re-enter this recipe.",
-  "variables": ["ticket_key", "docs_dir", "provider"],
+  "variables": ["ticket_key", "docs_dir", "provider", "verification_scope"],
   "steps": [
     {
       "type": "mcp_call",
@@ -23,7 +23,7 @@
     {
       "type": "agent_task",
       "instruction_file": "execute-plan.md",
-      "description": "Produce the plan's implementation artifacts"
+      "description": "Produce the plan's implementation artifacts. Under the Epic Implementer, a minor requirement that cannot be met unattended gets a guarded workaround plus a record at .bridge/epic-workarounds/<TICKET>.md, committed on the ticket branch with git add -f; a core requirement is never worked around and is left unfinished so the run parks the ticket."
     },
     {
       "type": "agent_task",
@@ -69,6 +69,7 @@
       "on_error": "warn_and_continue"
     },
     {
+      "id": "monitor-ci-checks",
       "type": "agent_task",
       "instruction_file": "monitor-ci-checks.md",
       "description": "Monitor CI checks and report results"

package/pipelines/plan-epic.json

@@ -54,11 +54,6 @@
       "type": "agent_task",
       "instruction_file": "write-epic-summary.md",
       "description": "Write epic overview and summary document"
-    },
-    {
-      "type": "agent_task",
-      "instruction_file": "store-and-approve-epic-plan.md",
-      "description": "Create epic run, store the plan DAG, and approve it in the backend"
     }
   ]
 }

package/pipelines/review-ticket.json

@@ -30,7 +30,7 @@
     {
       "type": "agent_task",
       "id": "wait-for-ticket-review",
-      "instruction": "FIRST, check whether a review was actually submitted. The previous step runs with `on_error: warn_and_continue`, so a rejected submission (a 402, 403 or 500 from the generate endpoint, or a dropped connection) lets the pipeline continue into this step. If that step returned an error message rather than its submission confirmation or a `recovery_get` envelope, do NOT wait: nothing is running, and `wait_for_ticket_review` cannot tell \"never submitted\" from \"still running\" \u2014 it would read `pending` in every window until the caller's own timeout. Treat a failed submission as a terminal failure, report the error the previous step gave, and take the verdict contract's `revise` path.\n\nOtherwise, wait for the review submitted by the previous step to finish, using repeated BOUNDED windows.\n\nCall `wait_for_ticket_review` with `ticket_number` set to the ticket key. Each call uses the default 20-second window (set `budget_ms: 20000` explicitly if needed); do not use a longer window, because some MCP clients time out before a pending result arrives. The tool returns a JSON body with a `state` field:\n\n- `state: \"pending\"` \u2014 NORMAL and expected. The review is still running. Call the tool again immediately. Do NOT sleep, do NOT poll in a shell loop, and do NOT re-run `request_ticket_review`: re-submitting starts a second billable multi-model review and abandons the one already in flight.\n- `state: \"ready\"` \u2014 the review is over. BAPI-1121: a ready result has ALREADY persisted exactly the accepted documents and reconciled the canonical source files \u2014 it writes every leg in `saved_legs` to its canonical path and removes the stale canonical file for every leg in `withheld_legs`. Do NOT call `get_clarifying_questions` or `get_ticket_critique` after a ready result; those retrieval calls were removed from this recipe because reading them again could reintroduce exactly the stale content the wait just withheld. Treat `saved_legs` as the authoritative source set for the next steps, not file presence.\n  - `freshness_basis: \"generation\"` is the normal case: `advanced_legs`/`saved_legs` are current-review evidence, proven newer than the submission. Any leg in `withheld_legs` was delivered but NOT proven current \u2014 surface its `reason` (`generation_not_advanced` or `identity_unreadable`) as a visible warning; do not describe the result as an ordinary cost-saved one-leg review when a withholding occurred. A leg in `absent_legs` with `reason: \"not_delivered\"` is an ordinary policy omission (e.g. an Easy-ticket clarify-only review) unless its status also flags it as policy-expected, in which case call that out too.\n  - `freshness_basis: \"terminality_only\"` means no submission baseline was available (e.g. a resumed session) \u2014 `advanced_legs` is empty by construction and `saved_legs` was accepted on terminal delivery alone. Surface this prominently as a DEGRADED-freshness warning: the saved artifact(s) may be indistinguishable from a prior attachment, and the downstream identity-footer agreement check is the remaining backstop. Retain this warning when reporting to the next steps rather than treating a `terminality_only` ready result as equivalent to a `generation`-backed one.\n  - If the result instead carries `state: \"error\"` alongside a persistence failure (an `ARTIFACT_PERSISTENCE_FAILED` `error`/`status`/`message` envelope), HALT rather than proceeding with whatever files happen to exist on disk \u2014 report the failure; the accepted legs already on disk before the failure are named in the envelope and are not lost, but nothing new was persisted for this window.\n- `state: \"error\"` \u2014 terminal. Report the `reason` and stop; the review will not complete on its own. `UPSTREAM_TERMINAL` means the review failed or expired server-side \u2014 take the verdict contract's `revise` path; do NOT open another wait window and do NOT re-run `request_ticket_review`. `INVALID_RESPONSE` means the delivered document could not be read.\n\nKeep looping on `pending` for as long as this session's own budget allows. There is no iteration cap here: the bound is the caller's \u2014 for the conductor's spec-review worker that is the existing 120-minute job timeout, which produces the ordinary liveness outcome if the review never lands. Never fabricate a verdict or a review result from a pending state.",
+      "instruction": "FIRST, check whether a review was actually submitted. The previous step runs with `on_error: warn_and_continue`, so a rejected submission (a 402, 403 or 500 from the generate endpoint, or a dropped connection) lets the pipeline continue into this step. If that step returned an error envelope \u2014 a JSON object with a string `error`, a numeric `status`, and an `operation` field (for example `status: 403` with `error: \"ENTITLEMENT_REQUIRED\"`, or `status: 422` for too little ticket detail) \u2014 rather than its submission confirmation or a `recovery_get` envelope, do NOT wait: nothing is running, and `wait_for_ticket_review` cannot tell \"never submitted\" from \"still running\" \u2014 it would read `pending` in every window until the caller's own timeout. Treat a failed submission as a terminal failure, report the `status`, `error`, and `message` the previous step gave, and take the verdict contract's `revise` path.\n\nOtherwise, wait for the review submitted by the previous step to finish, using repeated BOUNDED windows.\n\nCall `wait_for_ticket_review` with `ticket_number` set to the ticket key. Each call uses the default 20-second window (set `budget_ms: 20000` explicitly if needed); do not use a longer window, because some MCP clients time out before a pending result arrives. The tool returns a JSON body with a `state` field:\n\n- `state: \"pending\"` \u2014 NORMAL and expected. The review is still running. Call the tool again immediately. Do NOT sleep, do NOT poll in a shell loop, and do NOT re-run `request_ticket_review`: re-submitting starts a second billable multi-model review and abandons the one already in flight.\n- `state: \"ready\"` \u2014 the review is over. BAPI-1121: a ready result has ALREADY persisted exactly the accepted documents and reconciled the canonical source files \u2014 it writes every leg in `saved_legs` to its canonical path and removes the stale canonical file for every leg in `withheld_legs`. Do NOT call `get_clarifying_questions` or `get_ticket_critique` after a ready result; those retrieval calls were removed from this recipe because reading them again could reintroduce exactly the stale content the wait just withheld. Treat `saved_legs` as the authoritative source set for the next steps, not file presence.\n  - `freshness_basis: \"generation\"` is the normal case: `advanced_legs`/`saved_legs` are current-review evidence, proven newer than the submission. Any leg in `withheld_legs` was delivered but NOT proven current \u2014 surface its `reason` (`generation_not_advanced` or `identity_unreadable`) as a visible warning; do not describe the result as an ordinary cost-saved one-leg review when a withholding occurred. A leg in `absent_legs` with `reason: \"not_delivered\"` is an ordinary policy omission (e.g. an Easy-ticket clarify-only review) unless its status also flags it as policy-expected, in which case call that out too.\n  - `freshness_basis: \"terminality_only\"` means no submission baseline was available (e.g. a resumed session) \u2014 `advanced_legs` is empty by construction and `saved_legs` was accepted on terminal delivery alone. Surface this prominently as a DEGRADED-freshness warning: the saved artifact(s) may be indistinguishable from a prior attachment, and the downstream identity-footer agreement check is the remaining backstop. Retain this warning when reporting to the next steps rather than treating a `terminality_only` ready result as equivalent to a `generation`-backed one.\n  - If the result instead carries `state: \"error\"` alongside a persistence failure (an `ARTIFACT_PERSISTENCE_FAILED` `error`/`status`/`message` envelope), HALT rather than proceeding with whatever files happen to exist on disk \u2014 report the failure; the accepted legs already on disk before the failure are named in the envelope and are not lost, but nothing new was persisted for this window.\n- `state: \"error\"` \u2014 terminal. Report the `reason` and stop; the review will not complete on its own. `UPSTREAM_TERMINAL` means the review failed or expired server-side \u2014 take the verdict contract's `revise` path; do NOT open another wait window and do NOT re-run `request_ticket_review`. `NO_REVIEW_REQUESTED` means no review was submitted from this session and none is running; `NO_REVIEW_RUNNING` means the submitted review is no longer running on the server \u2014 treat both like `UPSTREAM_TERMINAL`. `INVALID_RESPONSE` means the delivered document could not be read.\n\nKeep looping on `pending` for as long as this session's own budget allows. There is no iteration cap here: the bound is the caller's \u2014 for the conductor's spec-review worker that is the existing 120-minute job timeout, which produces the ordinary liveness outcome if the review never lands. Never fabricate a verdict or a review result from a pending state.",
       "description": "Wait for the submitted review in repeated bounded windows; a ready result has already persisted the accepted documents and reconciled the canonical files (BAPI-1121). Resumable: a pending result is a normal observation, not a failure.",
       "on_error": "halt"
     },