@bridge_gpt/mcp-server 0.2.56 → 0.2.58

package/build/start-tickets.js

@@ -58,9 +58,11 @@ import { readFile, writeFile, mkdir, mkdtemp, stat, lstat, symlink, unlink, copy
 import os from "node:os";
 import { createHash } from "node:crypto";
 import path from "path";
+import { fileURLToPath } from "node:url";
+import { validateHttpBaseUrl } from "./base-url.js";
 import { VERSION } from "./version.generated.js";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
-import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+import { LEGACY_SERVER_NAMES, MCP_PACKAGE_NAME, MCP_SERVER_NAME } from "./mcp-identity.js";
 // BAPI-941: the shared drift diagnostic formatter. The leaf drift module imports
 // nothing from here, so this direction stays acyclic.
 import { formatClaudeReviewWorkflowDriftDiagnostic } from "./claude-review-workflow-drift.js";
@@ -560,7 +562,7 @@ resumeMode = false, workflow = "implement", reviewRounds,
 // conductor runs always, and (BAPI-801/BAPI-847) for every plain run whose base
 // resolved, `main` included — and threaded (BAPI-593) into the spawned workflow
 // command.
-baseBranch) {
+baseBranch, bridgeApiBaseUrlOverride) {
     if (!isSupportedStartTicketsPlatform(deps.platform)) {
         return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
     }
@@ -571,6 +573,7 @@ baseBranch) {
     // conductor-only — a plain worker's prompt stays bare and learns the base from
     // the env plus the create-PR instruction files.
     const prBaseBranch = resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch);
+    const bridgeApiBaseUrl = bridgeApiBaseUrlOverride ?? resolveSpawnBridgeApiBaseUrl(deps.env);
     return {
         ok: true,
         config: {
@@ -580,7 +583,7 @@ baseBranch) {
             // falls back to the basename-derived repo name (the 403 root cause), and
             // (BAPI-586/BAPI-801) the run base so the spawned worker opens its PR
             // against it. The base assignment stays outermost.
-            buildAgentShellCommand: (key, worktreePath, modelAlias, launchArgs) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs), repoName, platform), prBaseBranch, platform),
+            buildAgentShellCommand: (key, worktreePath, modelAlias, launchArgs) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs, bridgeApiBaseUrl), repoName, platform), prBaseBranch, platform),
             spawnTerminalTab: deps.spawnTerminalTab,
         },
     };
@@ -610,6 +613,51 @@ export function prependRepoNameEnvAssignment(command, repoName, platform = "darw
     }
     return `export BAPI_REPO_NAME='${shSquoteInner(repoName)}' && ${command}`;
 }
+/** Carry the parent's non-secret Bridge endpoint into a newly opened terminal. */
+export function prependBridgeApiBaseUrlEnvAssignment(command, baseUrl, platform = "darwin") {
+    if (!baseUrl)
+        return command;
+    if (platform === "win32") {
+        return `$env:BAPI_BASE_URL = ${powershellSquote(baseUrl)}; ${command}`;
+    }
+    return `export BAPI_BASE_URL='${shSquoteInner(baseUrl)}' && ${command}`;
+}
+/** Validate before placing an endpoint in a launch script or MCP registration. */
+export function resolveSpawnBridgeApiBaseUrl(env) {
+    const raw = env.BAPI_BASE_URL;
+    if (!raw || !raw.trim())
+        return undefined;
+    const result = validateHttpBaseUrl(raw);
+    return result.ok ? result.baseUrl : undefined;
+}
+/**
+ * A shell-spawned CLI cannot see the parent MCP process's environment. Read only
+ * the non-secret endpoint from the selected host's project registration when the
+ * shell did not inherit BAPI_BASE_URL (common for Cursor launched from the GUI).
+ */
+export async function resolveStartTicketsBridgeApiBaseUrl(deps, agent) {
+    const inherited = resolveSpawnBridgeApiBaseUrl(deps.env);
+    if (inherited)
+        return inherited;
+    const configPath = agent.name === "cursor-agent"
+        ? path.join(deps.cwd, ".cursor", "mcp.json")
+        : path.join(deps.cwd, ".mcp.json");
+    try {
+        const raw = await (deps.readFile ?? ((filePath) => readFile(filePath, "utf-8")))(configPath);
+        const parsed = JSON.parse(raw);
+        const bridge = parsed.mcpServers?.[MCP_SERVER_NAME] ?? parsed.mcpServers?.[LEGACY_SERVER_NAMES[0]];
+        if (!bridge)
+            return undefined;
+        const args = Array.isArray(bridge.args) ? bridge.args : [];
+        const flagIndex = args.indexOf("--base-url");
+        const candidate = bridge.env?.BAPI_BASE_URL ?? (flagIndex >= 0 ? args[flagIndex + 1] : undefined);
+        const validated = validateHttpBaseUrl(candidate);
+        return validated.ok ? validated.baseUrl : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * BAPI-801/BAPI-847: decide the `BAPI_BASE_BRANCH` value a spawned worker's shell
  * should carry — the single rule shared by the real spawn builder
@@ -1316,7 +1364,12 @@ export function buildAgentInvocationArgv(agent, prompt, modelAlias, launchArgsOr
     if (agent.name === "codex" && Array.isArray(launchArgsOrCursorWorkspace))
         argv.push(...launchArgsOrCursorWorkspace);
     if (agent.name === "cursor-agent" && typeof launchArgsOrCursorWorkspace === "string" && launchArgsOrCursorWorkspace) {
-        argv.push("-p", "--output-format", "text", "--trust", "--approve-mcps", "--force", "--workspace", launchArgsOrCursorWorkspace);
+        // Cursor's text mode can buffer the entire headless turn. Route NDJSON
+        // through our progress renderer, which prints assistant prose and tool
+        // names without dumping tool arguments or results into the terminal.
+        const progressScript = fileURLToPath(new URL("./cursor-agent-progress.js", import.meta.url));
+        argv.splice(0, 1, "node", progressScript, "--", agent.command);
+        argv.push("-p", "--output-format", "stream-json", "--trust", "--approve-mcps", "--force", "--workspace", launchArgsOrCursorWorkspace);
     }
     if (agent.supportsModelOverride &&
         typeof modelAlias === "string" &&
@@ -1347,14 +1400,14 @@ export function buildAgentInvocation(agent, prompt, quote, modelAlias, launchArg
     }
 }
 /** POSIX agent shell command: `cd '<path>' && <agent> [--model '<alias>'] '<prompt>'`. */
-export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = []) {
+export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = [], bridgeApiBaseUrl) {
     const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, agentName: agent.name }), (p) => `'${shSquoteInner(p)}'`, modelAlias, agent.name === "cursor-agent" && autoApprove ? worktreePath : launchArgs);
-    return `cd '${shSquoteInner(worktreePath)}' && ${invocation}`;
+    return `cd '${shSquoteInner(worktreePath)}' && ${prependBridgeApiBaseUrlEnvAssignment(invocation, bridgeApiBaseUrl, "darwin")}`;
 }
 /** PowerShell agent shell command: `Set-Location -LiteralPath '<path>'; <agent> [--model '<alias>'] '<prompt>'`. */
-export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = []) {
+export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = [], bridgeApiBaseUrl) {
     const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, agentName: agent.name }), powershellSquote, modelAlias, agent.name === "cursor-agent" && autoApprove ? worktreePath : launchArgs);
-    return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${invocation}`;
+    return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${prependBridgeApiBaseUrlEnvAssignment(invocation, bridgeApiBaseUrl, "win32")}`;
 }
 /**
  * Build the shell command run inside each spawned tab/session, dispatched by
@@ -1364,10 +1417,10 @@ export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoA
  * injected as `--model` at the spawn boundary. `conductorEnabled` appends the
  * BAPI-586 PR-base contract instruction to the prompt (opt-in via `--conductor`).
  */
-export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = []) {
+export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = [], bridgeApiBaseUrl) {
     if (platform === "win32")
-        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs);
-    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs);
+        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs, bridgeApiBaseUrl);
+    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs, bridgeApiBaseUrl);
 }
 /**
  * Build the shell command run inside a spawned tab/session for an ARBITRARY
@@ -2008,7 +2061,7 @@ export function getDryRunPlatformDetails(agent, platform = process.platform, env
         // buildAgentShellCommand/buildAgentPrompt path as a real spawn. A Codex
         // dry-run has no created worktree to bind, so its preview omits the
         // process-local -C/-c MCP scope that the real spawn resolves later.
-        buildAgentShellCommand: (key, worktreePath, modelAlias, launchArgs) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch, launchArgs), repoName, platform), resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch), platform),
+        buildAgentShellCommand: (key, worktreePath, modelAlias, launchArgs) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch, launchArgs, resolveSpawnBridgeApiBaseUrl(env)), repoName, platform), resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch), platform),
     };
 }
 /**
@@ -2017,7 +2070,7 @@ export function getDryRunPlatformDetails(agent, platform = process.platform, env
  * the `bapi` target. Lists both registration files and the version-pinned shim
  * command. Pure formatting — implies no credentials and writes no files.
  */
-export function buildDryRunMcpProvisioningLines(worktreePath, platform = process.platform, mcpServerInvocation) {
+export function buildDryRunMcpProvisioningLines(worktreePath, platform = process.platform, mcpServerInvocation, bridgeApiBaseUrl) {
     const api = platform === "win32" ? path.win32 : path.posix;
     const mcpJson = api.join(worktreePath, ".mcp.json");
     const cursorJson = api.join(worktreePath, ".cursor", "mcp.json");
@@ -2038,6 +2091,7 @@ export function buildDryRunMcpProvisioningLines(worktreePath, platform = process
         `DRY-RUN:     ${mcpJson}`,
         `DRY-RUN:     ${cursorJson}`,
         `DRY-RUN:     ${shim}`,
+        ...(bridgeApiBaseUrl ? [`DRY-RUN:     bapi shim adds --base-url ${bridgeApiBaseUrl}`] : []),
     ];
 }
 /**
@@ -2062,7 +2116,7 @@ export function buildDryRunDetailLines(agent, key, branch, platform = process.pl
         `DRY-RUN:   ${worktrunkBinary} ${wtArgs.join(" ")}`,
         `DRY-RUN:   ${agentInvocation}`,
         ...(prBaseBranch ? [`DRY-RUN:   PR base: ${prBaseBranch}`] : []),
-        ...buildDryRunMcpProvisioningLines("<worktree-path>", platform, mcpServerInvocation),
+        ...buildDryRunMcpProvisioningLines("<worktree-path>", platform, mcpServerInvocation, resolveSpawnBridgeApiBaseUrl(env)),
     ];
 }
 /**
@@ -2136,13 +2190,15 @@ export function formatSummaryReport(rows) {
  * Provisioning needs real `fs/promises` ops (not part of the command-runner DI
  * boundary), but inherits the platform and cwd from the orchestration deps.
  */
-export function buildMcpProvisioningDeps(deps) {
+export function buildMcpProvisioningDeps(deps, bridgeApiBaseUrlOverride) {
     return {
+        env: deps.env,
         readFile: deps.readFile ?? ((filePath) => readFile(filePath, "utf-8")),
         writeFile: deps.writeFile ?? ((filePath, data) => writeFile(filePath, data, "utf-8")),
         mkdir: deps.mkdir ?? ((dirPath, options) => mkdir(dirPath, options)),
         platform: deps.platform,
         cwd: deps.cwd,
+        bridgeApiBaseUrl: bridgeApiBaseUrlOverride ?? resolveSpawnBridgeApiBaseUrl(deps.env),
         // Resolve how the worker MCP shim launches at dispatch time from the running
         // conductor's own on-disk build (absolute-build-path primary, npm-channel
         // fallback) — never from process.cwd(). `nodeExecutable` is kept as "node"
@@ -3199,6 +3255,7 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     // Fail-open: an unresolved name is warned about loudly but never aborts the run.
     const resolveRepoNameFn = overrides.resolveRepoName ?? resolveStartTicketsRepoName;
     const resolvedRepoName = await resolveRepoNameFn(deps);
+    const bridgeApiBaseUrl = await resolveStartTicketsBridgeApiBaseUrl(deps, agent);
     if (!resolvedRepoName) {
         overrides.repoNameWarningLog?.("Warning: could not resolve the repo name (set BAPI_REPO_NAME or add a valid " +
             ".bridge/config). Spawned worktrees may fall back to the directory name and " +
@@ -3211,7 +3268,7 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     // epic.base_branch override applied above) so the spawned worker gets
     // BAPI_BASE_BRANCH — every conductor worker, and a plain worker whose base
     // is non-default.
-    options.baseBranch);
+    options.baseBranch, bridgeApiBaseUrl);
     if (!platformConfig.ok)
         return { ok: false, error: platformConfig.error };
     // BAPI-527: resolve the base start point new worktrees are cut from BEFORE any
@@ -3261,7 +3318,7 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     const provisionCommandsFn = overrides.provisionCommands ??
         ((rows, d) => provisionCommandsForCreatedWorktrees(rows, buildCommandProvisioningDeps(d), agent.name === "codex"));
     const provisionFn = overrides.provisionMcpRegistrations ??
-        ((rows, d) => provisionMcpRegistrationsForCreatedWorktrees(rows, buildMcpProvisioningDeps(d)));
+        ((rows, d) => provisionMcpRegistrationsForCreatedWorktrees(rows, buildMcpProvisioningDeps(d, bridgeApiBaseUrl)));
     const materializeFn = overrides.materializeFileCredentials ?? materializeFileCredentialsForCreatedWorktrees;
     const detectTerminalFn = overrides.detectTerminal ?? detectTerminal;
     const spawnTabsFn = overrides.spawnTabsForCreatedWorktrees ?? spawnTabsForCreatedWorktrees;
@@ -3376,14 +3433,20 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     let scoped = stampIndexScopeOnRows(routed, indexScope);
     if (agent.name === "codex") {
         const mcpDeps = buildMcpProvisioningDeps(deps);
-        scoped = await Promise.all(scoped.map(async (row) => {
-            if (row.status !== "created" || !row.path)
-                return row;
+        // Scope resolution can refresh one shared Codex profile. Serialize these
+        // reads and writes so sibling worktrees cannot observe a half-written update.
+        const resolved = [];
+        for (const row of scoped) {
+            if (row.status !== "created" || !row.path) {
+                resolved.push(row);
+                continue;
+            }
             const scope = await (overrides.resolveCodexScope ?? resolveCodexLaunchScope)(row.path, mcpDeps);
-            return scope.ok
+            resolved.push(scope.ok
                 ? { ...row, codexLaunchArgs: scope.argv }
-                : { ...row, status: "spawn-failed", error: scope.error };
-        }));
+                : { ...row, status: "spawn-failed", error: scope.error });
+        }
+        scoped = resolved;
     }
     const rows = await spawnTabsFn(deps, scoped, terminal, platformConfig.config.buildAgentShellCommand);
     return { ok: true, rows };
@@ -3427,7 +3490,7 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         return 1;
     }
     const options = parsed.options;
-    const deps = overrides.deps ?? createDefaultStartTicketsDeps();
+    const rawDeps = overrides.deps ?? createDefaultStartTicketsDeps();
     const orchestrate = overrides.orchestrate ?? orchestrateStartTickets;
     // The parser validates `--agent`, so this resolves to a real spec; the guard
     // is defensive only.
@@ -3436,6 +3499,14 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         errorLog(`Error: Unknown agent: '${options.agentName}'. Launchable agents: ${formatStartTicketsAgentNames()}.`);
         return 1;
     }
+    // The editor's MCP registration can have a local endpoint that its Bash tool
+    // does not inherit. Use that endpoint for the CLI's own routing as well as for
+    // its generated worktree registration and terminal command. Never mutate the
+    // caller's environment or read/copy its API key from the registration.
+    const bridgeApiBaseUrl = await resolveStartTicketsBridgeApiBaseUrl(rawDeps, agent);
+    const deps = bridgeApiBaseUrl
+        ? { ...rawDeps, env: { ...rawDeps.env, BAPI_BASE_URL: bridgeApiBaseUrl } }
+        : rawDeps;
     // BAPI-642: a malformed `--tier` value is fail-open — emit ONE concise,
     // secret-free warning and continue (routing applies the premium fallback). It
     // never aborts the launch or changes the numeric exit code.

package/build/version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.56";
-export const BUILD_COMMIT = "ba95aad09dd4";
-export const LAUNCHER_ARGS = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"];
+export const VERSION = "0.2.58";
+export const BUILD_COMMIT = "e29c3f46e4eb";
+export const LAUNCHER_ARGS = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.58", "serve"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.2.56",
+  "version": "0.2.58",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",

package/pipelines/implement-ticket.json

@@ -14,11 +14,11 @@
       "tool": "request_plan_generation",
       "params": {
         "ticket_number": "{ticket_key}",
-        "wait_for_result": true,
+        "wait_for_result": false,
         "save_locally": true,
         "provider": "{provider}"
       },
-      "description": "Generate implementation plan. Re-entry-safe: a non-forced request against a fresh existing plan returns reused: true and runs nothing new — the expected fast path on recovery re-entry. force is reserved for deliberate regeneration; this step never sets it. On a GATEWAY_TIMEOUT/504 response, poll get_plan (or the response's recovery_get URL) until a terminal result — never reissue this step."
+      "description": "Submit implementation-plan generation without waiting through an MCP client deadline. Re-entry-safe: the backend reuses a fresh existing plan (reused: true, no new run). force is reserved for deliberate regeneration; this step never sets it. On a dropped connection or other ambiguous submission outcome, use get_plan to inspect the existing run — never reissue this step automatically."
     },
     {
       "type": "agent_task",

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 occupies at most 240 seconds and 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 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.",
       "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"
     },