@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/build/start-tickets.js

@@ -1,3 +1,4 @@
+import { recordProvisionedAssets } from "./generated-assets-inventory.js";
 /**
  * start-tickets — packaged CLI subcommand of the bridge-api-mcp-server bin.
  *
@@ -136,7 +137,7 @@ export function getStartTicketsUsage() {
         "  --host claude-code|cursor|codex|copilot-vscode|windsurf Current host when --agent is omitted; Claude Code, Cursor, and Codex can launch sessions",
         "  Cursor with --auto launches headlessly after a bounded readiness check; without --auto it stays interactive for the review gate.",
         "  --workflow implement|review-and-implement  Command each spawned worktree runs (default: implement). review-and-implement runs review-ticket then, after a per-ticket halt gate, hands off to a fresh implement-ticket session; --auto applies to both phases.",
-        "  --tier cheap|basic|premium  Strict manual model-routing override: bypasses the per-ticket difficulty/tier lookup and applies this tier to every ticket exactly as supplied, with no per-session posture adjustment. Claude/Cursor use registry aliases and repository overrides; Codex uses the authenticated Bridge catalog. It is NOT a raw --model alias and never carries an API key or credential. A malformed value requests premium routing when available. Mutually exclusive with --auto-tier.",
+        "  --tier cheap|basic|premium  Strict manual model-routing override: bypasses the per-ticket difficulty/tier lookup and applies this tier to every ticket exactly as supplied, with no per-session posture adjustment. Claude/Cursor use registry aliases and repository overrides; Codex uses the authenticated Bridge catalog. It is NOT a raw --model alias and never carries an API key or credential. A malformed value requests premium routing when available. With --workflow review-and-implement a valid value is also forwarded to the spawned command so the review tab and the fresh implementation session both run on it. Mutually exclusive with --auto-tier.",
         "  --auto-tier cheap|basic|premium  Internal/advanced machine-carried raw backend tier for chained automation handoffs (e.g. /review-and-implement): bypasses the per-ticket lookup like --tier, but remains subject to per-session optimization-posture adjustment (may be downshifted under maximize_subscription, unless the server reports configured thresholds). Not the strict-override mechanism — use --tier for a human override. Mutually exclusive with --tier.",
         "  --rounds 1|2                Review round count forwarded to the review phase; review-only, valid only with --workflow review-and-implement",
         "  --terminal terminal|iterm   Override the macOS terminal app (default: auto-detect via $TERM_PROGRAM); honored on macOS only",
@@ -619,7 +620,9 @@ 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, bridgeApiBaseUrlOverride) {
+baseBranch, bridgeApiBaseUrlOverride, 
+// BAPI-1365: a recognized operator `--tier`, forwarded to the review prompt.
+manualTier) {
     if (!isSupportedStartTicketsPlatform(deps.platform)) {
         return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
     }
@@ -640,7 +643,7 @@ baseBranch, bridgeApiBaseUrlOverride) {
             // 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, bridgeApiBaseUrl), 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, manualTier), repoName, platform), prBaseBranch, platform),
             spawnTerminalTab: deps.spawnTerminalTab,
         },
     };
@@ -834,6 +837,7 @@ export function createDefaultStartTicketsDeps() {
             encoding: "utf-8",
             // Optional bounded timeout (e.g. cursor-agent --list-models probes).
             timeout: options?.timeoutMs,
+            signal: options?.signal,
         }, (error, stdout, stderr) => {
             const exitCode = error && typeof error.code === "number"
                 ? (error.code)
@@ -844,6 +848,7 @@ export function createDefaultStartTicketsDeps() {
                 stdout: stdout ?? "",
                 stderr: stderr ?? "",
                 exitCode,
+                ...(error && typeof error.code === "string" ? { unavailable: true } : {}),
             });
         });
     });
@@ -1072,6 +1077,19 @@ export async function refreshBaseBranch(deps, options) {
     // `<baseBranch>` is checked out somewhere: fast-forward it in place. git refuses to
     // force-move a checked-out branch ref, so we must go through merge.
     if (basePath) {
+        // BAPI-1362: a live plane member may be running out of this very checkout.
+        // Fail closed — an unreadable or ambiguous record protects it. When
+        // protected, nothing local is moved: the caller cuts from the fetched
+        // `origin/<base>` SHA through the same fetch-only resolution the
+        // non-mutating path uses.
+        const decision = await evaluateGuardSafely(deps, basePath);
+        if (decision.kind === "protect") {
+            (deps.baseWorktreeGuardWarningLog ?? defaultGuardWarningLog)(formatBaseWorktreeGuardWarning(decision, baseBranch));
+            const resolved = await fetchAndResolveBaseSha(deps, baseBranch);
+            if (!resolved.ok)
+                return { ok: false, error: resolved.error };
+            return { ok: true, protectedBaseSha: resolved.base_sha };
+        }
         const merge = await deps.runCommand("git", ["merge", "--ff-only", originRef], { cwd: basePath });
         if (!commandSucceeded(merge)) {
             return {
@@ -1103,6 +1121,25 @@ export async function refreshBaseBranch(deps, options) {
     }
     return { ok: true };
 }
+function defaultGuardWarningLog(message) {
+    // stderr, never stdout: stdout carries the workflow's normal output.
+    process.stderr.write(`${message}\n`);
+}
+/** Run the guard; any failure of the guard itself is a `protect` (fail closed). */
+async function evaluateGuardSafely(deps, basePath) {
+    try {
+        if (deps.evaluateBaseWorktreeGuard)
+            return await deps.evaluateBaseWorktreeGuard(basePath);
+        return await evaluateBaseWorktreeGuard(basePath, await createBaseWorktreeGuardDeps());
+    }
+    catch {
+        return {
+            kind: "protect",
+            reason: "manifest-unreadable",
+            manifestLocation: ".bridge/plane/plane.json",
+        };
+    }
+}
 /**
  * Compatibility wrapper around {@link refreshBaseBranch} that preserves the
  * historical `refreshMainBranch(deps, { refreshMain })` signature for callers
@@ -1195,6 +1232,7 @@ async function emitClaudeReviewWorkflowDriftAdvisory(deps, baseBranch, overrides
 // import the VALUES here (so internal uses keep working) and re-export the same
 // references so existing importers of `./start-tickets.js` (index.ts,
 // review-tickets.ts) and the pinned start-tickets tests are unaffected.
+import { evaluateBaseWorktreeGuard, createBaseWorktreeGuardDeps, formatBaseWorktreeGuardWarning, } from "./plane/base-worktree-guard.js";
 import { validateBranchName, fetchAndResolveBaseSha, 
 // BAPI-941: both live in the same leaf module so the interactive refresh path
 // and the non-mutating conductor path share one drift implementation.
@@ -1339,8 +1377,9 @@ export async function resumeWorktrees(deps, options) {
  * E1/F3b proved a clean TEXTUAL merge can still hide a SEMANTIC break (branch A
  * adds a helper; branch B adds a contract test over all helpers), which only the
  * FULL suite catches — so this instruction requires the worker to run the full
- * project test suite (the same gate the advisory pre-push hook enforces) and only
- * push/complete on green, escalating otherwise.
+ * project test suite (every unit suite the project defines, the same suites its
+ * pull request CI runs) and only push/complete on green, escalating otherwise.
+ * The wording stays project-neutral because this CLI runs in other repositories.
  *
  * Single line (no newlines, no `;`, no quotes/apostrophes) so it stays safe when
  * single-quoted into a shell command and embedded in terminal-launcher args.
@@ -1351,8 +1390,8 @@ export function buildResumeModeRemediationFinalizeInstruction() {
         "the current base branch and resolve the merge conflicts. A clean textual merge can " +
         "still break behavior, so inspect for semantic conflicts even when there are no textual " +
         "conflict markers. Before you push or mark the ticket complete, run the full test suite " +
-        "for the project (the full unit suite, the same gate enforced by the advisory pre-push " +
-        "hook described in CLAUDE.md under the CI cost model and advisory pre-push hook section) " +
+        "for the project (the full unit suite: every unit test suite the project defines, the " +
+        "same suites its pull request CI runs) " +
         "and do not rely on targeted subsets as your only verification. Push and mark the ticket " +
         "complete only after the full suite is green. If you cannot make the full suite pass, " +
         "report the ticket blocked and escalate rather than pushing a green-looking but broken merge.");
@@ -1385,6 +1424,8 @@ export function buildAgentPrompt(key, opts = {}) {
     // Review-only arguments (`--rounds`, non-default `--base-branch`) must never
     // leak into the legacy `/implement-ticket` prompt.
     if (workflow === "review-and-implement") {
+        if (opts.manualTier !== undefined)
+            command += ` --tier=${opts.manualTier}`;
         if (opts.agentName === "cursor-agent")
             command += " --agent=cursor-agent";
         if (opts.reviewRounds !== undefined) {
@@ -1457,13 +1498,13 @@ 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 = [], 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);
+export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = [], bridgeApiBaseUrl, manualTier) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, agentName: agent.name, manualTier }), (p) => `'${shSquoteInner(p)}'`, modelAlias, agent.name === "cursor-agent" && autoApprove ? worktreePath : launchArgs);
     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 = [], 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);
+export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = [], bridgeApiBaseUrl, manualTier) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, agentName: agent.name, manualTier }), powershellSquote, modelAlias, agent.name === "cursor-agent" && autoApprove ? worktreePath : launchArgs);
     return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${prependBridgeApiBaseUrlEnvAssignment(invocation, bridgeApiBaseUrl, "win32")}`;
 }
 /**
@@ -1474,10 +1515,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 = [], bridgeApiBaseUrl) {
+export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch, launchArgs = [], bridgeApiBaseUrl, manualTier) {
     if (platform === "win32")
-        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);
+        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs, bridgeApiBaseUrl, manualTier);
+    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch, launchArgs, bridgeApiBaseUrl, manualTier);
 }
 /**
  * Build the shell command run inside a spawned tab/session for an ARBITRARY
@@ -1605,7 +1646,7 @@ export async function spawnMacOSTerminalTab(deps, terminal, shellCommand, contex
         : buildTerminalAppleScript(shellCommand, title);
     const result = await deps.runCommand("osascript", ["-e", script]);
     if (commandSucceeded(result))
-        return { ok: true };
+        return { ok: true, destination: terminal === "iterm" ? "iTerm tab" : "macOS Terminal tab" };
     const reason = (result.stderr || result.stdout || "").trim();
     return {
         ok: false,
@@ -1693,7 +1734,7 @@ export async function spawnWindowsTerminalTab(deps, _terminal, shellCommand, con
         const args = buildWindowsTerminalArgs(worktreePath, shellCommand, title);
         const result = await deps.runCommand(WINDOWS_TERMINAL_COMMAND, args);
         if (commandSucceeded(result))
-            return { ok: true };
+            return { ok: true, destination: "Windows Terminal tab" };
         const reason = combineCommandOutput(result);
         return {
             ok: false,
@@ -1716,7 +1757,7 @@ export async function spawnWindowsTerminalTab(deps, _terminal, shellCommand, con
         fallback,
     ]);
     if (commandSucceeded(result))
-        return { ok: true };
+        return { ok: true, destination: "PowerShell fallback window" };
     const reason = combineCommandOutput(result);
     return {
         ok: false,
@@ -1820,7 +1861,7 @@ export async function spawnLinuxTmuxTerminalTab(deps, _terminal, shellCommand, c
         : buildTmuxNewSessionArgs(session, window, worktreePath, paneCommand);
     const result = await deps.runCommand(TMUX_COMMAND, args);
     if (commandSucceeded(result))
-        return { ok: true };
+        return { ok: true, destination: "detached tmux session" };
     const reason = combineCommandOutput(result);
     return {
         ok: false,
@@ -2080,7 +2121,7 @@ export async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildSh
             worktreePath: row.path,
         });
         if (result.ok) {
-            out.push({ ...row, status: "spawned" });
+            out.push({ ...row, status: "spawned", ...(result.destination ? { sessionDestination: result.destination } : {}) });
         }
         else {
             out.push({ ...row, status: "spawn-failed", error: result.error });
@@ -2105,7 +2146,7 @@ export function buildDryRunResults(keys, overrides) {
  * PowerShell on Windows, `wt` + POSIX on macOS/Linux, and a non-throwing `wt` +
  * POSIX fallback for unsupported platforms.
  */
-export function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env, autoApprove = false, conductorEnabled = false, repoName = null, workflow = "implement", reviewRounds, baseBranch) {
+export function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env, autoApprove = false, conductorEnabled = false, repoName = null, workflow = "implement", reviewRounds, baseBranch, manualTier) {
     return {
         worktrunkBinary: resolveWorktrunkBinary(platform, env),
         // The builder accepts an optional resolved modelAlias; the dry-run caller
@@ -2118,7 +2159,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, resolveSpawnBridgeApiBaseUrl(env)), 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), manualTier), repoName, platform), resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch), platform),
     };
 }
 /**
@@ -2157,8 +2198,8 @@ export function buildDryRunMcpProvisioningLines(worktreePath, platform = process
  * the secret-free MCP provisioning preview. Pure platform formatting only — no
  * preflight, no routing failures.
  */
-export function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env, baseBranch = "main", autoApprove = false, modelAlias = null, conductorEnabled = false, repoName = null, mcpServerInvocation, workflow = "implement", reviewRounds) {
-    const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env, autoApprove, conductorEnabled, repoName, workflow, reviewRounds, baseBranch);
+export function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env, baseBranch = "main", autoApprove = false, modelAlias = null, conductorEnabled = false, repoName = null, mcpServerInvocation, workflow = "implement", reviewRounds, manualTier) {
+    const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env, autoApprove, conductorEnabled, repoName, workflow, reviewRounds, baseBranch, manualTier);
     const wtArgs = buildWtSwitchArgs(branch, false, baseBranch);
     const agentInvocation = build(key, "<worktree-path>", modelAlias);
     // BAPI-801/BAPI-847: one concise secondary detail naming the PR base, emitted
@@ -2182,6 +2223,23 @@ export function buildDryRunDetailLines(agent, key, branch, platform = process.pl
  * `  path=PATH` when available) followed by warning lines for any create/spawn
  * failures.
  */
+/** Explain only actual successful sessions; summary serialization stays stable. */
+export function formatSpawnedSessionExplanation(rows, context) {
+    const spawned = rows.filter((row) => row.status === "spawned");
+    if (!spawned.length)
+        return "";
+    const lines = ["Spawned sessions:"];
+    for (const row of spawned) {
+        lines.push(`  ${row.key}: ${context.agent} runs in ${row.path ?? "a worktree whose path was not reported"} on branch ${row.branch}; ${row.sessionDestination ?? "terminal destination not reported"}.`);
+    }
+    lines.push("Work on each branch from its reported folder: it is already checked out there and normally cannot also be checked out in the original folder.");
+    lines.push("Monitor the reported terminal session and its agent output; use the attach commands below on Linux. Session startup is not review or implementation completion.");
+    if (context.workflow === "review-and-implement")
+        lines.push("Each session reviews independently, then opens a fresh implementation session only after its review halt gate permits it.");
+    if (spawned.length > 1)
+        lines.push("Coordinate ownership across these independent sessions; pause affected work if overlapping changes or conflicts appear.");
+    return lines.join("\n");
+}
 export function formatSummaryReport(rows) {
     const lines = ["Summary:"];
     // Surface the single conductor run id near the top (first line stays
@@ -2285,6 +2343,7 @@ export function buildCommandProvisioningDeps(deps) {
         runCommand: deps.runCommand,
         platform: deps.platform,
         cwd: deps.cwd,
+        ...(!deps.readFile && !deps.writeFile && !deps.mkdir ? { recordAssets: recordProvisionedAssets } : {}),
     };
 }
 /**
@@ -2383,6 +2442,12 @@ export function formatModelRoutingDiagnosticLine(d) {
         case "posture-unavailable":
             return ("model routing: optimization posture was unavailable; Quality routing was retained " +
                 "(reason=optimization-posture-unavailable).");
+        case "review-consumer-unrecognized":
+            return (`model routing: the Bridge API server did not recognize the review consumer${ticketSuffix} ` +
+                "(reason=consumer-unrecognized); the review tab uses the premium fallback. Upgrade the server.");
+        case "review-threshold-legacy":
+            return (`model routing: review thresholds are not configured${ticketSuffix} ` +
+                "(reason=legacy); the review tab uses the premium fallback. Configure review model-tier thresholds.");
         default:
             return `model routing degraded: ${d.message} ${failOpen}`;
     }
@@ -3023,7 +3088,43 @@ export function formatModelRoutingDecisionDiagnosticLine(input) {
     return (`[model-routing] source=${input.source} baseline=${input.baseline} ` +
         `posture=${input.posture} adjustment=${input.adjustment} effective=${input.effective} ` +
         `alias=${input.alias ?? "unresolved"}` +
-        (input.threshold ? ` threshold=${input.threshold}` : ""));
+        (input.threshold ? ` threshold=${input.threshold}` : "") +
+        (input.phase === "review" ? " phase=review consumer=review" : ""));
+}
+/**
+ * BAPI-1365: classify a successfully fetched review-consumer `/model-tier`
+ * response. `consumer-unrecognized` = the server did not echo `consumer:
+ * "review"` (its tier and marker are not a review decision and are never
+ * interpreted); `legacy` = it echoed review but no stored review thresholds
+ * decided the tier. `undefined` = a usable review decision, OR a
+ * `source: "fallback"` response (the difficulty itself failed; callers keep the
+ * existing lookup-failure handling for that).
+ */
+function reviewTierFallbackCause(value) {
+    if (value.consumer !== "review")
+        return "consumer-unrecognized";
+    if (value.source === "fallback")
+        return undefined;
+    if (!isThresholdDecidedTierResponse(value))
+        return "legacy";
+    return undefined;
+}
+/** BAPI-1365: the secret-free operator warning and diagnostic for a review fallback cause. */
+function reviewTierFallbackNotice(cause, repoName, ticketKey) {
+    const kind = cause === "consumer-unrecognized" ? "review-consumer-unrecognized" : "review-threshold-legacy";
+    const warning = cause === "consumer-unrecognized"
+        ? `model routing: server did not recognize the review consumer for ${ticketKey} (reason=consumer-unrecognized)`
+        : `model routing: review thresholds are not configured for ${ticketKey} (reason=legacy)`;
+    return {
+        warning,
+        diagnostic: makeModelRoutingDiagnostic({
+            kind,
+            repoName,
+            storeTarget: `bapi:${repoName}`,
+            ticketKey,
+            message: warning,
+        }),
+    };
 }
 /**
  * BAPI-1343 R-6: the threshold marker for a successfully fetched `/model-tier`
@@ -3032,11 +3133,16 @@ export function formatModelRoutingDecisionDiagnosticLine(input) {
  * (`configured` or `anomaly`). Every other case returns `undefined`, so the
  * caller keeps today's exact downshift and text.
  */
-function thresholdSkipMarker(posture, tierResult) {
+function thresholdSkipMarker(posture, tierResult, reviewWorkflow = false) {
     if (posture !== "maximize_subscription")
         return undefined;
     if (!tierResult || !tierResult.ok)
         return undefined;
+    // BAPI-1365: a review-consumer lookup counts only when the server echoed the
+    // review consumer; an older server that ignored the parameter answered for
+    // the implementation consumer, which says nothing about the review threshold.
+    if (reviewWorkflow && tierResult.value.consumer !== "review")
+        return undefined;
     if (!isThresholdDecidedTierResponse(tierResult.value))
         return undefined;
     return tierResult.value.thresholdMode;
@@ -3206,6 +3312,12 @@ errorLog = (message) => console.error(message)) {
     // produced it.
     const postureResolution = await resolveOptimizationPostureForStartTickets(access);
     const posture = postureResolution.posture;
+    // BAPI-1365: the spawned tab of a `review-and-implement` launch is a REVIEW
+    // tab, so its tier lookups ask for the review consumer. An ordinary
+    // `implement` launch supplies no options and keeps the endpoint's default
+    // implementation consumer. Derived once and shared by both fetch paths below.
+    const isReviewWorkflow = options.workflow === "review-and-implement";
+    const tierFetchOptions = isReviewWorkflow ? { consumer: "review" } : {};
     // BAPI-1225: one deterministic, best-effort diagnostic line per repository-level
     // resolution, emitted exactly here — outside the per-ticket row loop below, so a
     // multi-ticket invocation still logs it once for this canonical repository. Uses
@@ -3232,14 +3344,14 @@ errorLog = (message) => console.error(message)) {
         // hoisting pattern above.
         //
         // BAPI-1343 R-6: under `maximize_subscription` ONLY, each eligible row's
-        // `/model-tier` is fetched once (the shared bounded fetch, no `consumer`
-        // parameter) purely to read `threshold_mode`. A threshold-decided
+        // `/model-tier` is fetched once (the shared bounded fetch; BAPI-1365: with
+        // the workflow's consumer) purely to read `threshold_mode`. A threshold-decided
         // (`configured`/`anomaly`) response keeps the carried tier — stored
         // thresholds made it final. A fetch failure, `legacy`, or anything else
         // downshifts exactly as before. `quality`/`speed` never downshift, so they
         // make no extra request.
         const thresholdTierMap = posture === "maximize_subscription"
-            ? await fetchTicketModelTiersForRows(access, eligible, options.maxParallel, isEligible)
+            ? await fetchTicketModelTiersForRows(access, eligible, options.maxParallel, isEligible, tierFetchOptions)
             : null;
         const aliasByEffectiveTier = new Map();
         const resolveAutoTierAlias = async (effectiveTier) => {
@@ -3269,7 +3381,14 @@ errorLog = (message) => console.error(message)) {
                 autoOut.push(row);
                 continue;
             }
-            const threshold = thresholdSkipMarker(posture, thresholdTierMap?.get(row.key));
+            const markerResult = thresholdTierMap?.get(row.key);
+            const threshold = thresholdSkipMarker(posture, markerResult, isReviewWorkflow);
+            // BAPI-1365: for a review launch, say WHY a fetched marker did not decide
+            // the tier (never a review-threshold claim). A failed fetch keeps the
+            // existing silent downshift.
+            const markerCause = isReviewWorkflow && markerResult && markerResult.ok
+                ? reviewTierFallbackCause(markerResult.value)
+                : undefined;
             const effectiveTier = posture === "maximize_subscription" && !threshold
                 ? downshiftModelTier(autoTier)
                 : autoTier;
@@ -3277,7 +3396,7 @@ errorLog = (message) => console.error(message)) {
             const lineageSuffix = threshold
                 ? `; threshold:${threshold}`
                 : posture === "maximize_subscription"
-                    ? `; auto-tier:${autoTier}->maximize:${effectiveTier}`
+                    ? `; auto-tier:${autoTier}->maximize:${effectiveTier}${markerCause ? `; review-marker:${markerCause}` : ""}`
                     : "";
             const { resolvedAlias, aliasWarning } = await resolveAutoTierAlias(effectiveTier);
             const reason = resolvedAlias
@@ -3294,7 +3413,14 @@ errorLog = (message) => console.error(message)) {
                     ? { modelRoutingDiagnostic: codexEntitlementDiagnostic(access.repoName) }
                     : {}),
             };
-            autoOut.push(aliasWarning ? appendSummaryRowWarning(baseRow, aliasWarning) : baseRow);
+            let pushedRow = aliasWarning ? appendSummaryRowWarning(baseRow, aliasWarning) : baseRow;
+            if (markerCause) {
+                const notice = reviewTierFallbackNotice(markerCause, access.repoName, row.key);
+                pushedRow = appendSummaryRowWarning(pushedRow, notice.warning);
+                if (!pushedRow.modelRoutingDiagnostic)
+                    pushedRow = { ...pushedRow, modelRoutingDiagnostic: notice.diagnostic };
+            }
+            autoOut.push(pushedRow);
             // BAPI-1236: one `automatic_snapshot` diagnostic per eligible row — the
             // carried baseline, the newly resolved posture, the exact adjustment token,
             // the calculated effective tier, and the validated alias (or `unresolved`).
@@ -3306,13 +3432,14 @@ errorLog = (message) => console.error(message)) {
                 effective: effectiveTier,
                 alias: resolvedAlias,
                 ...(threshold ? { threshold } : {}),
+                ...(isReviewWorkflow ? { phase: "review" } : {}),
             });
         }
         out = autoOut;
     }
     else {
         // Ordinary per-ticket difficulty-lookup path.
-        const tierMap = await fetchTicketModelTiersForRows(access, eligible, options.maxParallel, isEligible);
+        const tierMap = await fetchTicketModelTiersForRows(access, eligible, options.maxParallel, isEligible, tierFetchOptions);
         // Lazily resolve+validate the premium fallback alias at most once for this run
         // (the alias is identical across rows; cursor-agent validation spawns a probe).
         let premiumApplier = null;
@@ -3351,6 +3478,40 @@ errorLog = (message) => console.error(message)) {
                 continue;
             }
             const { difficulty, tier, source } = tierResult.value;
+            // BAPI-1365: a review-launch response is a review-threshold decision only
+            // when the server echoed `consumer: "review"` AND stored thresholds decided
+            // it. Anything else takes the existing premium fallback with a closed
+            // reason — the returned tier and marker are never interpreted.
+            if (isReviewWorkflow) {
+                const cause = reviewTierFallbackCause(tierResult.value);
+                if (cause) {
+                    const notice = reviewTierFallbackNotice(cause, access.repoName, row.key);
+                    if (agent.name === "codex") {
+                        loopOut.push(codexDefaultRows([row], () => true, notice.warning, notice.diagnostic)[0]);
+                        continue;
+                    }
+                    loopOut.push(await applyPremiumFallback(row, notice.warning, notice.diagnostic));
+                    continue;
+                }
+                if (source === "fallback") {
+                    // The server could not obtain a difficulty: its premium tier is a
+                    // guess, not a review decision — keep the lookup-failure handling.
+                    const warning = `model routing: tier lookup failed for ${row.key}; using agent default model`;
+                    const diagnostic = makeModelRoutingDiagnostic({
+                        kind: "tier-fetch-unavailable",
+                        repoName: access.repoName,
+                        storeTarget: `bapi:${access.repoName}`,
+                        ticketKey: row.key,
+                        message: `tier lookup failed for ${row.key}`,
+                    });
+                    if (agent.name === "codex") {
+                        loopOut.push(codexDefaultRows([row], () => true, warning, diagnostic)[0]);
+                        continue;
+                    }
+                    loopOut.push(await applyPremiumFallback(row, warning, diagnostic));
+                    continue;
+                }
+            }
             if (!tier) {
                 // Backend reported no usable difficulty — default to premium/Opus. (The
                 // backend now returns a premium fallback itself, so this is defensive.)
@@ -3396,7 +3557,7 @@ errorLog = (message) => console.error(message)) {
             // diagnostic carry a distinct `threshold` marker instead. The harness-
             // local premium fallback above is untouched.
             const difficultyTier = tier;
-            const threshold = thresholdSkipMarker(posture, tierResult);
+            const threshold = thresholdSkipMarker(posture, tierResult, isReviewWorkflow);
             const effectiveTier = posture === "maximize_subscription" && !threshold
                 ? downshiftModelTier(difficultyTier)
                 : difficultyTier;
@@ -3406,7 +3567,10 @@ errorLog = (message) => console.error(message)) {
                 : posture === "maximize_subscription"
                     ? `; difficulty:${difficultyTier}->maximize:${effectiveTier}`
                     : "";
-            const thresholdField = threshold ? { threshold } : {};
+            const thresholdField = {
+                ...(threshold ? { threshold } : {}),
+                ...(isReviewWorkflow ? { phase: "review" } : {}),
+            };
             // BAPI-1236: stamp `difficulty_lookup` rather than copying the backend
             // cache/computation source (`cached`/`computed`/`fallback`) into the
             // summary's own routing-provenance field — that backend source is
@@ -3758,7 +3922,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, bridgeApiBaseUrl);
+    options.baseBranch, bridgeApiBaseUrl, isModelTier(options.injectedTier) ? options.injectedTier : undefined);
     if (!platformConfig.ok)
         return { ok: false, error: platformConfig.error };
     // BAPI-527: resolve the base start point new worktrees are cut from BEFORE any
@@ -3787,6 +3951,11 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
         });
         if (!refresh.ok)
             return { ok: false, error: refresh.error };
+        // BAPI-1362: a live plane member runs from the base worktree, so the local
+        // branch was left where it was; cut from the fetched remote SHA instead.
+        if (refresh.protectedBaseSha !== undefined) {
+            effectiveBaseStartPoint = refresh.protectedBaseSha;
+        }
     }
     // BAPI-941: the `claude-review` workflow-drift advisory, emitted ONCE per
     // worker spawn at the one choke point both dispatch paths pass through, after
@@ -4023,7 +4192,7 @@ export async function runStartTicketsCli(argv, overrides = {}) {
             const branch = resolveBranchForTicket(key, options.branchOverrides);
             const routedRow = routedByKey.get(key);
             const modelAlias = routedRow?.modelAlias ?? null;
-            for (const line of buildDryRunDetailLines(agent, key, branch, deps.platform, deps.env, options.baseBranch, options.autoApprove, modelAlias, options.conductorEnabled ?? false, dryRunRepoName, dryRunMcpInvocation, options.workflow, options.reviewRounds)) {
+            for (const line of buildDryRunDetailLines(agent, key, branch, deps.platform, deps.env, options.baseBranch, options.autoApprove, modelAlias, options.conductorEnabled ?? false, dryRunRepoName, dryRunMcpInvocation, options.workflow, options.reviewRounds, isModelTier(options.injectedTier) ? options.injectedTier : undefined)) {
                 log(line);
             }
             log(`DRY-RUN:   model routing: ${formatModelRoutingLine(routedRow ?? { key, branch, status: "dry-run" }, agent, { workflow: options.workflow })}`);
@@ -4065,6 +4234,9 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         return 1;
     }
     log(formatSummaryReport(result.rows));
+    const explanation = formatSpawnedSessionExplanation(result.rows, { agent: options.agentName, workflow: options.workflow ?? "implement" });
+    if (explanation)
+        log(explanation);
     // Linux: each spawned ticket runs in a detached tmux session — tell the user
     // how to attach.
     const spawned = result.rows.filter((r) => r.status === "spawned");

package/build/tool-error-envelope.js

@@ -7,6 +7,10 @@
  * "this operation has no local-backend equivalent" refusal, which the ticket
  * routes return as HTTP 409 with `detail.error = "UNSUPPORTED_IN_LOCAL_MODE"`.
  *
+ * BAPI-1382 adds a second trusted pair: the plan-entitlement denial, which the
+ * server returns as HTTP 403 with `detail.error = "ENTITLEMENT_REQUIRED"`. It
+ * tells a plan limit apart from a bad credential, which is also a 403.
+ *
  * Recognition is by the exact `(error, status)` PAIR — never by message text.
  * Message text is prose that gets reworded; matching on it would make a copy
  * edit silently change orchestration control flow.
@@ -18,6 +22,54 @@
 export const UNSUPPORTED_IN_LOCAL_MODE_ERROR = "UNSUPPORTED_IN_LOCAL_MODE";
 /** The HTTP status that marker is only ever valid with. */
 export const UNSUPPORTED_IN_LOCAL_MODE_STATUS = 409;
+/** The plan-entitlement marker (BAPI-1382): the account's plan lacks a feature. */
+export const ENTITLEMENT_REQUIRED_ERROR = "ENTITLEMENT_REQUIRED";
+/** The HTTP status that marker is only ever valid with. */
+export const ENTITLEMENT_REQUIRED_STATUS = 403;
+/**
+ * The request-time too-little-ticket-detail refusal (BAPI-1382): the generate
+ * routes answer HTTP 422 with `detail.error = "INSUFFICIENT_TICKET_DETAIL"`
+ * plus the measured length, threshold, and description source.
+ */
+export const INSUFFICIENT_TICKET_DETAIL_ERROR = "INSUFFICIENT_TICKET_DETAIL";
+/** The HTTP status that marker is only ever valid with. */
+export const INSUFFICIENT_TICKET_DETAIL_STATUS = 422;
+/**
+ * The server `(error, status)` pairs the MCP relay keeps as received. Every
+ * other server-provided `error` is replaced by the relay's own status-derived
+ * code, so an arbitrary detail object can never forge a code.
+ */
+export const TRUSTED_UPSTREAM_ERROR_PAIRS = [
+    [UNSUPPORTED_IN_LOCAL_MODE_ERROR, UNSUPPORTED_IN_LOCAL_MODE_STATUS],
+    [ENTITLEMENT_REQUIRED_ERROR, ENTITLEMENT_REQUIRED_STATUS],
+    [INSUFFICIENT_TICKET_DETAIL_ERROR, INSUFFICIENT_TICKET_DETAIL_STATUS],
+];
+/** True only for an exact trusted `(error, status)` pair. */
+export function isTrustedUpstreamErrorPair(error, status) {
+    return TRUSTED_UPSTREAM_ERROR_PAIRS.some(([code, code_status]) => error === code && status === code_status);
+}
+/**
+ * Add the typed `operation` to a serialized error envelope (BAPI-1382). A text
+ * that is not an envelope is wrapped into one with the given status, so a
+ * refused request is always parseable and never a prose-prefixed string.
+ */
+export function withRequestOperation(envelopeText, operation, status) {
+    let parsed = null;
+    try {
+        parsed = JSON.parse(envelopeText);
+    }
+    catch {
+        parsed = null;
+    }
+    if (parsed !== null &&
+        typeof parsed === "object" &&
+        !Array.isArray(parsed) &&
+        typeof parsed.error === "string" &&
+        typeof parsed.status === "number") {
+        return JSON.stringify({ ...parsed, operation });
+    }
+    return JSON.stringify({ error: "UNKNOWN_ERROR", status, message: envelopeText, operation });
+}
 /**
  * Parse `text` as a tool-error envelope, or return `null`.
  *
@@ -52,8 +104,17 @@ export function parseToolErrorEnvelope(text) {
     if (Array.isArray(obj.unsupported_fields)) {
         envelope.unsupported_fields = obj.unsupported_fields.filter((v) => typeof v === "string");
     }
+    if (typeof obj.operation === "string") {
+        envelope.operation = obj.operation;
+    }
     return envelope;
 }
+/** True for the exact plan-entitlement contract: the marker AND HTTP 403. */
+export function isEntitlementRequiredEnvelope(envelope) {
+    return (envelope !== null &&
+        envelope.error === ENTITLEMENT_REQUIRED_ERROR &&
+        envelope.status === ENTITLEMENT_REQUIRED_STATUS);
+}
 /** True for the exact unsupported-local contract: the marker AND HTTP 409. */
 export function isUnsupportedInLocalModeEnvelope(envelope) {
     return (envelope !== null &&