@bridge_gpt/mcp-server 0.2.58 → 0.2.60

package/build/start-tickets.js

@@ -77,7 +77,7 @@ import { TICKET_KEY_PATTERN as SHARED_TICKET_KEY_PATTERN, TICKET_KEY_USAGE_SUMMA
 // can never drift. `start-tickets.ts` imports VALUES from there; the prereqs
 // module imports only TYPES back, so the runtime graph stays acyclic.
 import { WORKTRUNK_BINARY_OVERRIDE_ENV, WINDOWS_TERMINAL_COMMAND, WINDOWS_POWERSHELL_CANDIDATES, DEFAULT_WINDOWS_WORKTRUNK_BINARY, DEFAULT_POSIX_WORKTRUNK_BINARY, TMUX_COMMAND, GIT_FOR_WINDOWS_BASH_HINT, isSupportedStartTicketsPlatform, unsupportedPlatformMessage, resolveWorktrunkBinary, commandSucceeded, getCommandProbe, isCommandOnPath, resolveFirstCommandOnPath, enforcePreflightPrerequisites, appendDoctorHint, } from "./start-tickets-prereqs.js";
-import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, resolveModelAlias, isValidModelAlias, isModelTier, } from "./agent-registry.js";
+import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, resolveModelAlias, isValidModelAlias, isModelTier, downshiftModelTier, } from "./agent-registry.js";
 import { agentForPlatform, getHostTarget, getWorktreeHostTargets, isRunnableHostTarget, isHostPlatformId } from "./mcp-host-targets.js";
 import { resolveCodexLaunchScope } from "./codex-launch-scope.js";
 import { tmpdir } from "node:os";
@@ -135,7 +135,8 @@ 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  Coarse model-routing override: bypasses the per-ticket difficulty/tier lookup and applies this tier to every ticket. 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.",
+        "  --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.",
+        "  --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). 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",
         "  --dry-run                   Print intended actions; creates no worktrees and opens no tabs, but DOES resolve model routing read-only (may compute+cache a ticket's difficulty) to preview the --model each tab would use",
@@ -143,16 +144,16 @@ export function getStartTicketsUsage() {
         "  --base-branch BRANCH        Cut new worktrees from BRANCH and refresh origin/BRANCH (default: main)",
         "  --no-refresh-main           Skip refresh of the configured base branch (default main); historical name retained for backward compatibility",
         "  --max-parallel N            Max worktrees to create concurrently (default: 3)",
-        "  --conductor                 Enable the Conductor system: per-worker hook injection + BAPI_CONDUCTOR_* env, lifecycle ledger events, and a supervisor peer tab (default: off — a plain run just spawns cd <worktree> && <agent> '/implement-ticket <KEY>'). Implies --guard-stale-branch: a pre-existing ticket branch carrying commits beyond the resolved base is refused, not silently reused.",
+        "  --conductor                 Enable the Conductor system: per-worker hook injection + BAPI_EPIC_IMPLEMENTER_* env, lifecycle ledger events, and a supervisor peer tab (default: off — a plain run just spawns cd <worktree> && <agent> '/implement-ticket <KEY>'). Implies --guard-stale-branch: a pre-existing ticket branch carrying commits beyond the resolved base is refused, not silently reused.",
         "  --guard-stale-branch        Refuse to reuse a pre-existing feature/KEY branch whose tip is NOT an ancestor of the resolved base (it carries commits the base does not). The ticket is reported create-failed with the stale-worktree remedy instead of spawning a worker on leftover code. Implied by --conductor; pass it explicitly on the LLM-conductor pilot cut path. Off by default, so a plain interactive run keeps reusing a same-named branch.",
         "  -h, --help                  Show this help",
         "",
         "Environment:",
         `  ${WORKTRUNK_BINARY_OVERRIDE_ENV}     Override the Worktrunk executable name/path for nonstandard installs`,
         `  ${TMUX_SESSION_OVERRIDE_ENV}        Override the tmux session-name prefix on Linux (default: ${DEFAULT_TMUX_SESSION_PREFIX})`,
-        "  BAPI_CONDUCTOR_GATE_NAME          Conductor gate name for this run (default: implement-ticket)",
-        "  BAPI_CONDUCTOR_SUPERVISOR_MODE    Conductor supervisor mode (default: auto when --auto, else interactive)",
-        "  BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE  Set 1/true to also register a PreToolUse conductor hook",
+        "  BAPI_EPIC_IMPLEMENTER_GATE_NAME            Conductor gate name for this run (default: implement-ticket)",
+        "  BAPI_EPIC_IMPLEMENTER_SUPERVISOR_MODE      Conductor supervisor mode (default: auto when --auto, else interactive)",
+        "  BAPI_EPIC_IMPLEMENTER_ENABLE_PRE_TOOL_USE  Set 1/true to also register a PreToolUse conductor hook",
         "",
         "Conductor observability (opt-in via --conductor):",
         "  With --conductor, real Claude Code workers launched by start-tickets receive",
@@ -160,7 +161,7 @@ export function getStartTicketsUsage() {
         "  local lifecycle events into the conductor ledger. Each such run mints one run_id",
         "  and attributes worker events by worker_id, ticket key, and worktree path, and a",
         "  supervisor peer tab is opened. Without --conductor none of this happens. Inspect",
-        "  the ledger with the `conductor` CLI. The BAPI_CONDUCTOR_* env vars above apply",
+        "  the ledger with the `conductor` CLI. The BAPI_EPIC_IMPLEMENTER_* env vars above apply",
         "  only when --conductor is set.",
         "",
         "Prerequisites:",
@@ -207,6 +208,13 @@ export function parseStartTicketsArgs(argv) {
     // the parsed options); a `ModelTier` = usable override; INJECTED_TIER_UNRESOLVED
     // = supplied-but-malformed (fail open to premium). NEVER an error/throw.
     let injectedTier;
+    // BAPI-1236 `--auto-tier` machine-carried raw tier. `undefined` = flag absent.
+    // Unlike `--tier`, an invalid/repeated occurrence is a hard parser error —
+    // there is no fail-open sentinel — because this flag is meant for chained
+    // automation, not interactive typing, so a malformed value should surface
+    // immediately rather than silently degrade routing.
+    let autoTier;
+    let autoTierSeen = false;
     const branchEntries = [];
     const keys = [];
     for (let i = 0; i < argv.length; i++) {
@@ -310,6 +318,39 @@ export function parseStartTicketsArgs(argv) {
             injectedTier = isModelTier(value) ? value : INJECTED_TIER_UNRESOLVED;
             continue;
         }
+        if (arg === "--auto-tier" || arg.startsWith("--auto-tier=")) {
+            // BAPI-1236: strict machine-carried tier boundary. Unlike `--tier`, a
+            // malformed/empty/missing/repeated value is a hard parser error — there
+            // is no INJECTED_TIER_UNRESOLVED-style fail-open sentinel for this flag.
+            let value;
+            if (arg.startsWith("--auto-tier=")) {
+                value = arg.slice("--auto-tier=".length);
+            }
+            else {
+                // Same lookahead rule as `--tier`: never swallow a following option or
+                // ticket-key token as the value.
+                const next = i + 1 < argv.length ? argv[i + 1] : undefined;
+                if (next !== undefined && !next.startsWith("-") && !TICKET_KEY_PATTERN.test(next)) {
+                    value = takeValue();
+                }
+            }
+            // Validate the value directly with `isModelTier()` — no trimming, case
+            // normalization, or reuse of `INJECTED_TIER_UNRESOLVED` — before ever
+            // checking repetition, so a malformed occurrence always fails as an
+            // invalid-value error rather than a repeated-flag or mutual-exclusion one.
+            if (!isModelTier(value)) {
+                return {
+                    status: "error",
+                    message: `Invalid --auto-tier value: '${value ?? ""}' (accepted values: cheap, basic, premium).`,
+                };
+            }
+            if (autoTierSeen) {
+                return { status: "error", message: "--auto-tier may only be supplied once." };
+            }
+            autoTierSeen = true;
+            autoTier = value;
+            continue;
+        }
         if (arg === "--terminal" || arg.startsWith("--terminal=")) {
             let value;
             if (arg.startsWith("--terminal=")) {
@@ -404,6 +445,18 @@ export function parseStartTicketsArgs(argv) {
         }
         keys.push(arg);
     }
+    // --- tier-flag mutual exclusion (BAPI-1236) ---
+    // Checked immediately after the full argument scan, before any ticket/option
+    // semantic validation, so the conflict exits before orchestration or any
+    // network-capable dependency can run. Fires whenever BOTH flag names were
+    // supplied at all — including a malformed `--tier` (INJECTED_TIER_UNRESOLVED),
+    // since the flag was still supplied — regardless of argument order.
+    if (injectedTier !== undefined && autoTier !== undefined) {
+        return {
+            status: "error",
+            message: "--tier and --auto-tier cannot be used together.",
+        };
+    }
     // --- key validation ---
     if (keys.length === 0) {
         return {
@@ -508,6 +561,9 @@ export function parseStartTicketsArgs(argv) {
             // supplied, so an omitted flag leaves the legacy option shape untouched
             // (no own `injectedTier` key, not even `undefined`).
             ...(injectedTier !== undefined ? { injectedTier } : {}),
+            // BAPI-1236: include the auto-tier property ONLY when `--auto-tier` was
+            // supplied, mirroring `injectedTier`'s omitted-flag contract.
+            ...(autoTier !== undefined ? { autoTier } : {}),
         },
     };
 }
@@ -2203,7 +2259,7 @@ export function buildMcpProvisioningDeps(deps, bridgeApiBaseUrlOverride) {
         // conductor's own on-disk build (absolute-build-path primary, npm-channel
         // fallback) — never from process.cwd(). `nodeExecutable` is kept as "node"
         // here: Ticket 3 (P2) can later replace this single field with
-        // CONDUCTOR_NODE_PATH without re-plumbing argv construction.
+        // EPIC_IMPLEMENTER_NODE_PATH without re-plumbing argv construction.
         mcpServerInvocation: resolveMcpShimInvocationForRuntime({
             moduleUrl: import.meta.url,
             nodeExecutable: "node",
@@ -2323,6 +2379,9 @@ export function formatModelRoutingDiagnosticLine(d) {
             return `model routing degraded: Codex model catalog failed validation. ${failOpen}`;
         case "codex-entitlement-unverified":
             return "model routing: Bridge permits the selected model; local Codex account entitlement cannot be verified non-interactively.";
+        case "posture-unavailable":
+            return ("model routing: optimization posture was unavailable; Quality routing was retained " +
+                "(reason=optimization-posture-unavailable).");
         default:
             return `model routing degraded: ${d.message} ${failOpen}`;
     }
@@ -2568,6 +2627,77 @@ export async function fetchDifficultyModelRoutingConfig(access, includeOverrides
         };
     }
 }
+/** Type guard: true only for a recognized posture value. */
+export function isOptimizationPosture(value) {
+    return value === "quality" || value === "speed" || value === "maximize_subscription";
+}
+const POSTURE_UNAVAILABLE_WARNING = "model routing: optimization posture was unavailable; Quality routing was retained " +
+    "(reason=optimization-posture-unavailable)";
+/**
+ * BAPI-1225: the single stable message every posture-resolution emitter uses,
+ * verbatim. Textually identical to (but independently defined from) the Python
+ * contract in `src/python/library/optimization_posture_observability.py` — the
+ * two runtimes share no import, only the agreed-on literal string.
+ */
+const OPTIMIZATION_POSTURE_RESOLVED_MESSAGE = "optimization posture resolved";
+/** BAPI-1225: this harness diagnostic's fixed resolution-path value. */
+const RESOLUTION_PATH_HARNESS_ROUTING = "harness_routing";
+/**
+ * Format the BAPI-1225 repository-level harness routing-diagnostic line.
+ * Deterministic and secret-free: only the normalized closed posture value, the
+ * canonical repo name already supplied to routing-config resolution, and the
+ * constant resolution path — no raw config, resolved alias/model/tier, file
+ * path, ticket content, error, credential, or fallback provenance.
+ */
+function formatOptimizationPostureResolvedLine(posture, repoName) {
+    return (`${OPTIMIZATION_POSTURE_RESOLVED_MESSAGE} optimization_posture=${posture} ` +
+        `repo_name=${repoName} resolution_path=${RESOLUTION_PATH_HARNESS_ROUTING}`);
+}
+/** Build the shared, secret-free, invocation-scoped posture-unavailable diagnostic. */
+function makePostureUnavailableDiagnostic() {
+    // Deliberately carries no repoName/ticketKey/status so every degraded row's
+    // diagnostic shares the same de-dup key (BAPI-377) and collapses to one line.
+    return makeModelRoutingDiagnostic({
+        kind: "posture-unavailable",
+        message: "optimization posture unavailable; Quality routing retained",
+    });
+}
+/**
+ * Read and normalize the repo's `optimization_posture` config field in its own
+ * total `try/catch`, entirely separate from {@link fetchDifficultyModelRoutingConfig}.
+ * A posture read can never turn into that function's `{ ok: false }` result or
+ * trigger the premium fallback — it only ever yields `"quality"` on any
+ * unset/malformed/unreadable outcome, with a sanitized warning+diagnostic
+ * attached when the outcome was NOT the ordinary unset case.
+ */
+export async function resolveOptimizationPostureForStartTickets(access) {
+    try {
+        const raw = await fetchStartTicketsConfigField(access, "optimization_posture");
+        if (raw === null || raw === undefined) {
+            // Ordinary S1 defaulting — NULL/unset resolves to quality, no diagnostic.
+            return { posture: "quality", degraded: false };
+        }
+        if (isOptimizationPosture(raw)) {
+            return { posture: raw, degraded: false };
+        }
+        // Unknown/malformed non-null value.
+        return {
+            posture: "quality",
+            degraded: true,
+            warning: POSTURE_UNAVAILABLE_WARNING,
+            diagnostic: makePostureUnavailableDiagnostic(),
+        };
+    }
+    catch {
+        // Structured fetch failure or thrown error — never leak exception text.
+        return {
+            posture: "quality",
+            degraded: true,
+            warning: POSTURE_UNAVAILABLE_WARNING,
+            diagnostic: makePostureUnavailableDiagnostic(),
+        };
+    }
+}
 /** One bounded authenticated fetch; reject partial, unsafe, or stale wire data. */
 export async function fetchCodexModelCatalog(access) {
     let body;
@@ -2816,6 +2946,67 @@ async function applyPremiumFallbackToEligibleRows(deps, rows, isEligible, agent,
 const isCreatedRoutingEligible = (r) => r.status === "created" && !!r.path;
 /** Dry-run path: rows have no worktree path yet but are eligible for a preview. */
 const isDryRunRoutingEligible = (r) => r.status === "dry-run";
+/**
+ * Pure resolver for the diagnostic's `adjustment` token. `none` for manual
+ * routing (posture `not_evaluated_manual_override`) and for `quality`/`speed`;
+ * the exact transition token — including the `cheap` floor — under
+ * `maximize_subscription`. Total and exhaustive over {@link ModelTier}.
+ */
+function resolveModelRoutingDecisionAdjustment(posture, baseline) {
+    if (posture !== "maximize_subscription")
+        return "none";
+    switch (baseline) {
+        case "premium":
+            return "premium->basic";
+        case "basic":
+            return "basic->cheap";
+        case "cheap":
+            return "cheap->cheap_floor";
+    }
+}
+/**
+ * Format the exact deterministic diagnostic line. Inputs are restricted to
+ * closed tier/posture/adjustment/source values plus an already-validated
+ * alias, so raw command arguments, backend responses, URLs, headers, and
+ * credentials cannot enter the line.
+ */
+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"}`);
+}
+/**
+ * Best-effort emitter: calls the supplied stderr sink once and swallows any
+ * logger exception so diagnostic emission can never affect routing.
+ */
+function emitModelRoutingDecisionDiagnostic(errorLog, input) {
+    try {
+        errorLog(formatModelRoutingDecisionDiagnosticLine(input));
+    }
+    catch {
+        // Diagnostic emission is best-effort and must never affect routing.
+    }
+}
+/**
+ * Emit one `manual_override` diagnostic per eligible row for the two manual
+ * `--tier` routing paths (a recognized tier, or the malformed-value premium
+ * fallback). `tier` is both the baseline and the effective tier — a manual
+ * override is applied exactly as supplied, with posture never evaluated.
+ */
+function emitManualOverrideDiagnostics(errorLog, routedRows, isEligible, tier) {
+    for (const row of routedRows) {
+        if (!isEligible(row))
+            continue;
+        emitModelRoutingDecisionDiagnostic(errorLog, {
+            source: "manual_override",
+            baseline: tier,
+            posture: "not_evaluated_manual_override",
+            adjustment: "none",
+            effective: tier,
+            alias: row.modelAlias ?? null,
+        });
+    }
+}
 /**
  * BAPI-642 — apply a single explicitly injected tier to every eligible row,
  * bypassing the per-ticket difficulty/tier HTTP lookup. The tier is still mapped
@@ -2864,7 +3055,15 @@ async function applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, ag
  * `--model`; Claude/Cursor retain their premium fallback. Non-eligible rows
  * pass through untouched, and routing failures never abort worktree creation.
  */
-async function resolveModelRoutingForEligible(deps, rows, options, agent, isEligible) {
+async function resolveModelRoutingForEligible(deps, rows, options, agent, isEligible, 
+/**
+ * BAPI-1225: injected sink for the harness routing-diagnostic line, matching
+ * the shape of the existing `modelRoutingWarningLog`/`errorLog` seams. Every
+ * caller's production path already has a `console.error`-backed logger in
+ * scope; a missing injection (e.g. an older test double) falls back to
+ * `console.error` directly, never `console.log`/stdout.
+ */
+errorLog = (message) => console.error(message)) {
     const eligible = rows.filter(isEligible);
     if (eligible.length === 0)
         return rows;
@@ -2907,98 +3106,276 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
     // difficulty/tier lookup — `fetchTicketModelTiersForRows` is NEVER called for
     // any injected value. A recognized tier is applied to every eligible row; a
     // malformed value (INJECTED_TIER_UNRESOLVED) fails open to the premium
-    // fallback. When the flag is absent (`injected === undefined`) the legacy
-    // difficulty-lookup path below runs unchanged.
+    // fallback. When the flag is absent (`injected === undefined`) the
+    // automatic-snapshot / difficulty-lookup path below runs.
+    //
+    // BAPI-1224: an explicit `--tier` is an operator-forced MANUAL override and is
+    // applied exactly as supplied, below, with no posture downshifting — the
+    // optimization posture is never even read on this path (it is resolved only
+    // further down, immediately before the automatic-snapshot and per-ticket
+    // difficulty-lookup paths).
     const injected = options.injectedTier;
     if (injected === INJECTED_TIER_UNRESOLVED) {
         const warning = "model routing: --tier was not one of cheap|basic|premium; defaulting to premium routing";
         const apply = await makePremiumFallbackApplier(deps, agent, overrides, catalog, access.repoName);
-        return rows.map((r) => (isEligible(r) ? apply(r, warning) : r));
+        const routed = rows.map((r) => (isEligible(r) ? apply(r, warning) : r));
+        // BAPI-1236: the malformed-value premium fallback is still a manual
+        // override — never posture-evaluated — so it emits `manual_override` too.
+        emitManualOverrideDiagnostics(errorLog, routed, isEligible, "premium");
+        return routed;
     }
     if (injected) {
-        return applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, agent, overrides, injected, catalog, access.repoName);
-    }
-    const tierMap = await fetchTicketModelTiersForRows(access, eligible, options.maxParallel, isEligible);
-    // 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;
-    const applyPremiumFallback = async (row, warning, diagnostic) => {
-        if (!premiumApplier)
-            premiumApplier = await makePremiumFallbackApplier(deps, agent, overrides, catalog, access.repoName);
-        return premiumApplier(row, warning, diagnostic);
-    };
-    const out = [];
-    for (const row of rows) {
-        if (!isEligible(row)) {
-            out.push(row);
-            continue;
+        const routed = await applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, agent, overrides, injected, catalog, access.repoName);
+        emitManualOverrideDiagnostics(errorLog, routed, isEligible, injected);
+        return routed;
+    }
+    // BAPI-1224/BAPI-1236: resolve the repo's optimization posture ONCE, shared by
+    // both the automatic-snapshot path (BAPI-1236's `--auto-tier`, immediately
+    // below) and the ordinary per-ticket difficulty-lookup path — it cannot
+    // affect any earlier short-circuit (no-eligible-row, unsupported agent,
+    // access/config failure, routing-disabled, or the manual injected-tier
+    // override above). The resolver is total and never throws; a degraded read
+    // fails safe to "quality" (no downshift) plus a sanitized, invocation-scoped
+    // warning/diagnostic attached to `out` below, regardless of which branch
+    // produced it.
+    const postureResolution = await resolveOptimizationPostureForStartTickets(access);
+    const posture = postureResolution.posture;
+    // 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
+    // the SAME normalized `posture` value that decides the S5 downshift immediately
+    // below; this never re-resolves configuration. The existing `postureResolution`
+    // degraded-warning/diagnostic plumbing is untouched — this is an addition, not a
+    // replacement.
+    try {
+        errorLog(formatOptimizationPostureResolvedLine(posture, access.repoName));
+    }
+    catch {
+        // Diagnostic emission is best-effort and must never affect routing.
+    }
+    let out;
+    const autoTier = options.autoTier;
+    if (autoTier) {
+        // BAPI-1236 — automatic-snapshot routing: a machine-carried raw tier from a
+        // chained automation handoff (e.g. `/review-and-implement`'s `--auto-tier`).
+        // Routed through the CURRENT session's posture EXACTLY ONCE — unlike the
+        // manual override above, this path IS subject to `downshiftModelTier()`
+        // under `maximize_subscription` — while skipping ONLY the redundant
+        // per-ticket `fetchTicketModelTiersForRows()` lookup. The alias is
+        // resolved+validated ONCE (identical for every row), matching the premium
+        // fallback / injected-tier hoisting pattern above.
+        const effectiveTier = posture === "maximize_subscription" ? downshiftModelTier(autoTier) : autoTier;
+        const adjustment = resolveModelRoutingDecisionAdjustment(posture, autoTier);
+        const lineageSuffix = posture === "maximize_subscription"
+            ? `; auto-tier:${autoTier}->maximize:${effectiveTier}`
+            : "";
+        const alias = resolveRoutingAlias(agent, effectiveTier, overrides, catalog);
+        let resolvedAlias = null;
+        let aliasWarning = null;
+        if (!alias) {
+            aliasWarning = `model routing: no valid alias for tier=${effectiveTier}; using agent default`;
         }
-        const tierResult = tierMap.get(row.key);
-        if (!tierResult || !tierResult.ok) {
-            // Error reaching the per-ticket tier endpoint — default to premium/Opus,
-            // stamping the per-ticket tier-fetch diagnostic.
-            const warning = tierResult && !tierResult.ok
-                ? tierResult.warning
-                : `model routing: no tier resolved for ${row.key}; assuming hard ticket`;
-            const diagnostic = tierResult && !tierResult.ok
-                ? tierResult.diagnostic
-                : makeModelRoutingDiagnostic({
-                    kind: "tier-fetch-unavailable",
+        else {
+            const validation = await validateResolvedModelAliasForAgent(deps, agent, alias);
+            if (validation.ok) {
+                resolvedAlias = validation.alias;
+            }
+            else {
+                aliasWarning = validation.warning;
+            }
+        }
+        const reason = resolvedAlias
+            ? `auto-tier=${autoTier} model=${resolvedAlias} (posture=${posture})${lineageSuffix}`
+            : `${aliasWarning}${lineageSuffix}`;
+        out = rows.map((row) => {
+            if (!isEligible(row))
+                return row;
+            const baseRow = {
+                ...row,
+                difficulty: null,
+                modelTier: effectiveTier,
+                modelAlias: resolvedAlias,
+                modelRoutingSource: "automatic_snapshot",
+                modelRoutingReason: reason,
+                ...(agent.name === "codex" && resolvedAlias
+                    ? { modelRoutingDiagnostic: codexEntitlementDiagnostic(access.repoName) }
+                    : {}),
+            };
+            return aliasWarning ? appendSummaryRowWarning(baseRow, aliasWarning) : baseRow;
+        });
+        // 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`).
+        for (const row of rows) {
+            if (!isEligible(row))
+                continue;
+            emitModelRoutingDecisionDiagnostic(errorLog, {
+                source: "automatic_snapshot",
+                baseline: autoTier,
+                posture,
+                adjustment,
+                effective: effectiveTier,
+                alias: resolvedAlias,
+            });
+        }
+    }
+    else {
+        // Ordinary per-ticket difficulty-lookup path.
+        const tierMap = await fetchTicketModelTiersForRows(access, eligible, options.maxParallel, isEligible);
+        // 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;
+        const applyPremiumFallback = async (row, warning, diagnostic) => {
+            if (!premiumApplier)
+                premiumApplier = await makePremiumFallbackApplier(deps, agent, overrides, catalog, access.repoName);
+            return premiumApplier(row, warning, diagnostic);
+        };
+        const loopOut = [];
+        for (const row of rows) {
+            if (!isEligible(row)) {
+                loopOut.push(row);
+                continue;
+            }
+            const tierResult = tierMap.get(row.key);
+            if (!tierResult || !tierResult.ok) {
+                // Error reaching the per-ticket tier endpoint — default to premium/Opus,
+                // stamping the per-ticket tier-fetch diagnostic.
+                const warning = tierResult && !tierResult.ok
+                    ? tierResult.warning
+                    : `model routing: no tier resolved for ${row.key}; assuming hard ticket`;
+                const diagnostic = tierResult && !tierResult.ok
+                    ? tierResult.diagnostic
+                    : makeModelRoutingDiagnostic({
+                        kind: "tier-fetch-unavailable",
+                        repoName: access.repoName,
+                        storeTarget: `bapi:${access.repoName}`,
+                        ticketKey: row.key,
+                        message: `no tier resolved for ${row.key}`,
+                    });
+                if (agent.name === "codex") {
+                    loopOut.push(codexDefaultRows([row], () => true, warning, diagnostic)[0]);
+                    continue;
+                }
+                loopOut.push(await applyPremiumFallback(row, warning, diagnostic));
+                continue;
+            }
+            const { difficulty, tier, source } = tierResult.value;
+            if (!tier) {
+                // Backend reported no usable difficulty — default to premium/Opus. (The
+                // backend now returns a premium fallback itself, so this is defensive.)
+                // BAPI-1224: this is the harness-LOCAL premium fallback, deliberately
+                // exempt from maximize downshifting — this fail-safe-to-strong path must
+                // stay strong regardless of posture, so `makePremiumFallbackApplier`
+                // receives the literal "premium" tier unchanged.
+                const baseRow = { ...row, difficulty: difficulty ?? null, modelTier: tier ?? null, modelRoutingSource: source };
+                const warning = `model routing: ${row.key} resolved no tier (source=${source}); assuming hard ticket`;
+                const diagnostic = makeModelRoutingDiagnostic({
+                    kind: "no-tier",
                     repoName: access.repoName,
                     storeTarget: `bapi:${access.repoName}`,
                     ticketKey: row.key,
-                    message: `no tier resolved for ${row.key}`,
+                    message: `${row.key} resolved no tier (source=${source})`,
                 });
-            if (agent.name === "codex") {
-                out.push(codexDefaultRows([row], () => true, warning, diagnostic)[0]);
+                if (agent.name === "codex") {
+                    loopOut.push(codexDefaultRows([baseRow], () => true, warning, diagnostic)[0]);
+                    continue;
+                }
+                loopOut.push(await applyPremiumFallback(baseRow, warning, diagnostic));
                 continue;
             }
-            out.push(await applyPremiumFallback(row, warning, diagnostic));
-            continue;
-        }
-        const { difficulty, tier, source } = tierResult.value;
-        const baseRow = {
-            ...row,
-            difficulty: difficulty ?? null,
-            modelTier: tier ?? null,
-            modelRoutingSource: source,
-        };
-        if (!tier) {
-            // Backend reported no usable difficulty — default to premium/Opus. (The
-            // backend now returns a premium fallback itself, so this is defensive.)
-            const warning = `model routing: ${row.key} resolved no tier (source=${source}); assuming hard ticket`;
-            const diagnostic = makeModelRoutingDiagnostic({
-                kind: "no-tier",
-                repoName: access.repoName,
-                storeTarget: `bapi:${access.repoName}`,
-                ticketKey: row.key,
-                message: `${row.key} resolved no tier (source=${source})`,
-            });
-            if (agent.name === "codex") {
-                out.push(codexDefaultRows([baseRow], () => true, warning, diagnostic)[0]);
+            // BAPI-1224 — automatic downshift call site: the backend-returned tier
+            // (`difficultyTier`, retained regardless of whether its source is
+            // `cached`/`computed`/`fallback` — a valid backend "fallback" tier is NOT
+            // the harness-local fallback above and IS downshifted) is transformed to
+            // `effectiveTier` only under `maximize_subscription`; every other posture
+            // passes it through unchanged. The downshift happens here, before
+            // `resolveRoutingAlias()`, so `applyInjectedTierRoutingToEligibleRows()`
+            // and `makePremiumFallbackApplier()` — which call `resolveRoutingAlias()`
+            // with an injected or literal "premium" tier — can never be downshifted
+            // by accident. Claude and Cursor resolve `effectiveTier` through their
+            // unmodified registry `tierModels`; Codex indexes the fetched
+            // `catalog.models[effectiveTier]` — neither gains a maximize-specific
+            // alias table. Copilot never reaches this loop at all: it has no
+            // `AGENT_REGISTRY` entry and `isRunnableHostTarget()` rejects hosts
+            // without a launch agent before an `AgentSpec` is ever resolved.
+            const difficultyTier = tier;
+            const effectiveTier = posture === "maximize_subscription" ? downshiftModelTier(difficultyTier) : difficultyTier;
+            const adjustment = resolveModelRoutingDecisionAdjustment(posture, difficultyTier);
+            const lineageSuffix = posture === "maximize_subscription"
+                ? `; difficulty:${difficultyTier}->maximize:${effectiveTier}`
+                : "";
+            // 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
+            // preserved separately in `modelRoutingReason` below via `(source=...)`.
+            const baseRow = {
+                ...row,
+                difficulty: difficulty ?? null,
+                modelTier: effectiveTier,
+                modelRoutingSource: "difficulty_lookup",
+            };
+            const alias = resolveRoutingAlias(agent, effectiveTier, overrides, catalog);
+            if (!alias) {
+                const warning = `model routing: no valid alias for tier=${effectiveTier}; using agent default`;
+                loopOut.push(appendSummaryRowWarning({ ...baseRow, modelAlias: null, modelRoutingReason: warning + lineageSuffix }, warning));
+                emitModelRoutingDecisionDiagnostic(errorLog, {
+                    source: "difficulty_lookup",
+                    baseline: difficultyTier,
+                    posture,
+                    adjustment,
+                    effective: effectiveTier,
+                    alias: null,
+                });
                 continue;
             }
-            out.push(await applyPremiumFallback(baseRow, warning, diagnostic));
-            continue;
-        }
-        const alias = resolveRoutingAlias(agent, tier, overrides, catalog);
-        if (!alias) {
-            const warning = `model routing: no valid alias for tier=${tier}; using agent default`;
-            out.push(appendSummaryRowWarning({ ...baseRow, modelAlias: null, modelRoutingReason: warning }, warning));
-            continue;
-        }
-        const validation = await validateResolvedModelAliasForAgent(deps, agent, alias);
-        if (!validation.ok) {
-            out.push(appendSummaryRowWarning({ ...baseRow, modelAlias: null, modelRoutingReason: validation.warning }, validation.warning));
-            continue;
+            const validation = await validateResolvedModelAliasForAgent(deps, agent, alias);
+            if (!validation.ok) {
+                loopOut.push(appendSummaryRowWarning({ ...baseRow, modelAlias: null, modelRoutingReason: validation.warning + lineageSuffix }, validation.warning));
+                emitModelRoutingDecisionDiagnostic(errorLog, {
+                    source: "difficulty_lookup",
+                    baseline: difficultyTier,
+                    posture,
+                    adjustment,
+                    effective: effectiveTier,
+                    alias: null,
+                });
+                continue;
+            }
+            loopOut.push({
+                ...baseRow,
+                modelAlias: validation.alias,
+                modelRoutingReason: `tier=${effectiveTier} model=${validation.alias} (source=${source})${lineageSuffix}`,
+                ...(agent.name === "codex"
+                    ? { modelRoutingDiagnostic: codexEntitlementDiagnostic(access.repoName) }
+                    : {}),
+            });
+            emitModelRoutingDecisionDiagnostic(errorLog, {
+                source: "difficulty_lookup",
+                baseline: difficultyTier,
+                posture,
+                adjustment,
+                effective: effectiveTier,
+                alias: validation.alias,
+            });
         }
-        out.push({
-            ...baseRow,
-            modelAlias: validation.alias,
-            modelRoutingReason: `tier=${tier} model=${validation.alias} (source=${source})`,
-            ...(agent.name === "codex"
-                ? { modelRoutingDiagnostic: codexEntitlementDiagnostic(access.repoName) }
-                : {}),
+        out = loopOut;
+    }
+    // BAPI-1224: a degraded posture read attaches ONE sanitized warning +
+    // invocation-scoped diagnostic to every eligible row, without altering any
+    // row's already-resolved tier/alias. A row that already carries a stronger
+    // routing diagnostic (tier-fetch/no-tier/etc.) keeps it — the posture
+    // diagnostic never overwrites a stronger one, so `selectPrimaryInvocation-
+    // ModelRoutingDiagnostic` still surfaces the more actionable finding. Applies
+    // uniformly to `out` regardless of whether the automatic-snapshot or the
+    // ordinary difficulty-lookup branch produced it.
+    if (postureResolution.degraded) {
+        return out.map((r) => {
+            if (!isEligible(r))
+                return r;
+            const withWarning = appendSummaryRowWarning(r, postureResolution.warning);
+            return r.modelRoutingDiagnostic
+                ? withWarning
+                : { ...withWarning, modelRoutingDiagnostic: postureResolution.diagnostic };
         });
     }
     return out;
@@ -3008,8 +3385,8 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
  * entrypoint for the real spawn path. ALWAYS fail-open (see
  * {@link resolveModelRoutingForEligible}).
  */
-export async function resolveModelRoutingForRows(deps, rows, options, agent) {
-    return resolveModelRoutingForEligible(deps, rows, options, agent, isCreatedRoutingEligible);
+export async function resolveModelRoutingForRows(deps, rows, options, agent, errorLog) {
+    return resolveModelRoutingForEligible(deps, rows, options, agent, isCreatedRoutingEligible, errorLog);
 }
 /**
  * Dry-run variant: resolve routing for `dry-run` rows so `--dry-run` can preview
@@ -3019,8 +3396,8 @@ export async function resolveModelRoutingForRows(deps, rows, options, agent) {
  * difficulty the backend may compute and cache it (one LLM call) — exactly what
  * the subsequent real run would have done.
  */
-export async function resolveModelRoutingForDryRun(deps, rows, options, agent) {
-    return resolveModelRoutingForEligible(deps, rows, options, agent, isDryRunRoutingEligible);
+export async function resolveModelRoutingForDryRun(deps, rows, options, agent, errorLog) {
+    return resolveModelRoutingForEligible(deps, rows, options, agent, isDryRunRoutingEligible, errorLog);
 }
 /**
  * Format one concise routing decision line per ticket:
@@ -3032,6 +3409,11 @@ export async function resolveModelRoutingForDryRun(deps, rows, options, agent) {
  * `--tier`-driven implementation handoff. The ORDINARY implementation launch (a
  * plain `--workflow implement` with no `--tier`) appends NO label, so its line
  * stays byte-for-byte identical to the pre-feature format.
+ *
+ * BAPI-1236: `routing=auto-snapshot` is exclusive to a stored
+ * `modelRoutingSource: "automatic_snapshot"` row (a `--auto-tier` machine
+ * handoff) and is never applied to an `injected` row, so an automatic snapshot
+ * can never be misread as a manual `--tier` override in the diagnostics.
  */
 export function formatModelRoutingLine(row, agent, context) {
     const difficulty = typeof row.difficulty === "number" ? String(row.difficulty) : "?";
@@ -3043,6 +3425,8 @@ export function formatModelRoutingLine(row, agent, context) {
         labels.push("phase=review");
     if (row.modelRoutingSource === "injected")
         labels.push("routing=injected");
+    if (row.modelRoutingSource === "automatic_snapshot")
+        labels.push("routing=auto-snapshot");
     return labels.length > 0 ? `${base} ${labels.join(" ")}` : base;
 }
 /** Stable de-dup key for an invocation-level routing diagnostic. */
@@ -3412,7 +3796,7 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     // BEFORE building the spawn command. Always fail-open: routing never aborts a
     // spawn — at worst a ticket runs on the agent's default model.
     const resolveRoutingFn = overrides.resolveModelRoutingForRows ?? resolveModelRoutingForRows;
-    const routed = await resolveRoutingFn(deps, conductorReady, options, agent);
+    const routed = await resolveRoutingFn(deps, conductorReady, options, agent, overrides.modelRoutingWarningLog);
     // Per-ticket routing DECISION lines stay (one per spawnable ticket). The
     // noisy per-row routing WARNING emission is intentionally gone (BAPI-377): the
     // CLI now emits a single de-duplicated, actionable routing diagnostic per
@@ -3525,7 +3909,7 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         // per-ticket routing decision line.
         const resolveDryRunRoutingFn = overrides.resolveModelRoutingForDryRun ?? resolveModelRoutingForDryRun;
         const dryRunRows = buildDryRunResults(options.keys, options.branchOverrides);
-        const routedDryRunRows = await resolveDryRunRoutingFn(deps, dryRunRows, options, agent);
+        const routedDryRunRows = await resolveDryRunRoutingFn(deps, dryRunRows, options, agent, errorLog);
         const routedByKey = new Map(routedDryRunRows.map((r) => [r.key, r]));
         // Resolve the SAME worker MCP shim invocation the real provisioning would use
         // so the dry-run preview matches the `.mcp.json` that would actually be written.