@bridge_gpt/mcp-server 0.2.24 → 0.2.26

package/build/start-tickets.js

@@ -87,6 +87,16 @@ export const DEFAULT_MAX_PARALLEL = 3;
 export const DEFAULT_TMUX_SESSION_PREFIX = "bridge-start-tickets";
 /** Environment variable overriding the tmux session-name prefix. */
 export const TMUX_SESSION_OVERRIDE_ENV = "BAPI_TMUX_SESSION";
+/**
+ * BAPI-642 — internal marker for an explicitly supplied `--tier` value that is
+ * NOT one of the three recognized {@link ModelTier} names (a malformed or empty
+ * flag). It is deliberately distinct from an OMITTED flag (the option property is
+ * absent entirely in that case): an unresolved marker records that the operator
+ * asked for a coarse override we could not honor, so the routing layer fails open
+ * to the premium fallback rather than silently entering difficulty-based routing.
+ * The sentinel string is never a valid `ModelTier`, so `isModelTier` rejects it.
+ */
+export const INJECTED_TIER_UNRESOLVED = "__unresolved__";
 /** Return a copy of `row` with `warning` appended; never mutates the input. */
 export function appendSummaryRowWarning(row, warning) {
     return { ...row, warnings: [...(row.warnings ?? []), warning] };
@@ -103,6 +113,7 @@ export function getStartTicketsUsage() {
         "Flags:",
         "  --agent claude|cursor-agent Agent command to launch in each worktree (default: claude)",
         "  --workflow implement|review-and-implement  Slash command each spawned worktree runs (default: implement). review-and-implement runs /review-ticket then, after a per-ticket halt gate, /implement-ticket in the same session; --auto applies to the selected workflow.",
+        "  --tier cheap|basic|premium  Coarse model-routing override: bypasses the per-ticket difficulty/tier lookup and applies this tier to every ticket. It is still mapped to a model through the agent registry and any configured difficulty_model_tier_overrides, then validated — it is NOT a raw --model alias, and never carries an API key or credential. A malformed value fails open to premium routing.",
         "  --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",
@@ -156,6 +167,10 @@ export function parseStartTicketsArgs(argv) {
     let conductorEnabled = false;
     let workflow = "implement";
     let reviewRoundsRaw;
+    // BAPI-642 `--tier` override. `undefined` = flag absent (property omitted from
+    // the parsed options); a `ModelTier` = usable override; INJECTED_TIER_UNRESOLVED
+    // = supplied-but-malformed (fail open to premium). NEVER an error/throw.
+    let injectedTier;
     const branchEntries = [];
     const keys = [];
     for (let i = 0; i < argv.length; i++) {
@@ -231,6 +246,26 @@ export function parseStartTicketsArgs(argv) {
             reviewRoundsRaw = value;
             continue;
         }
+        if (arg === "--tier" || arg.startsWith("--tier=")) {
+            // BAPI-642: fail-open coarse routing override. A malformed/empty/missing
+            // value is NOT a parse error — it records INJECTED_TIER_UNRESOLVED so the
+            // routing layer can fall back to premium instead of aborting the launch.
+            let value;
+            if (arg.startsWith("--tier=")) {
+                value = arg.slice("--tier=".length);
+            }
+            else {
+                // For the space-separated form, refuse to swallow a following option or
+                // ticket-key token as the value (leaving it to be parsed normally);
+                // an absent value fails open to the unresolved marker.
+                const next = i + 1 < argv.length ? argv[i + 1] : undefined;
+                if (next !== undefined && !next.startsWith("-") && !TICKET_KEY_PATTERN.test(next)) {
+                    value = takeValue();
+                }
+            }
+            injectedTier = isModelTier(value) ? value : INJECTED_TIER_UNRESOLVED;
+            continue;
+        }
         if (arg === "--terminal" || arg.startsWith("--terminal=")) {
             let value;
             if (arg.startsWith("--terminal=")) {
@@ -412,6 +447,10 @@ export function parseStartTicketsArgs(argv) {
             conductorEnabled,
             workflow,
             reviewRounds,
+            // BAPI-642: include the injected-tier property ONLY when `--tier` was
+            // supplied, so an omitted flag leaves the legacy option shape untouched
+            // (no own `injectedTier` key, not even `undefined`).
+            ...(injectedTier !== undefined ? { injectedTier } : {}),
         },
     };
 }
@@ -1469,9 +1508,10 @@ const defaultPruneStaleLaunchScriptsDeps = {
  * recursively. Newer entries and unrelated files/dirs are left untouched.
  *
  * Fully fail-open: any error (missing parent dir, unreadable entry, stat/unlink
- * failure) is swallowed and never blocks or aborts a spawn — the same fail-open
- * discipline as the launch-script writer fallback in
- * {@link materializeWorkerLaunchCommand}.
+ * failure) is swallowed and never blocks or aborts a spawn. (Unconditionally so,
+ * unlike {@link materializeWorkerLaunchCommand}, whose inline fallback is gated on
+ * {@link MAX_TERMINAL_COMMAND_BYTES} — pruning a stale temp dir has no launchable/
+ * unlaunchable axis to gate on.)
  */
 export async function pruneStaleLaunchScripts(deps = defaultPruneStaleLaunchScriptsDeps) {
     try {
@@ -1523,27 +1563,54 @@ export const defaultWriteWorkerLaunchScript = async ({ platform, key, content, }
     await writeFile(file, content, { mode: 0o600 });
     return file;
 };
+/**
+ * Canonical maximum UTF-8 byte length of a single command line handed to a
+ * terminal spawner. macOS `osascript`-driven Terminal/iTerm keystroke delivery
+ * silently truncates (or mangles) a longer line, so a command at or below this
+ * bound is "known-launchable" and anything above it is "known-unlaunchable".
+ *
+ * Exported so the launcher and every install-flow guard read the SAME number:
+ * two independently-written literals would silently drift apart, and the whole
+ * point of the bound is that the launcher's fallback decision and the caller's
+ * final pre-spawn check agree.
+ */
+export const MAX_TERMINAL_COMMAND_BYTES = 1024;
 /**
  * Resolve the command actually handed to the terminal spawner for one worker.
  * When `deps.writeWorkerLaunchScript` is provided, the full command is persisted
- * to a script and a short `source <path>` runner is returned; if writing fails
- * for any reason the original inline command is returned (fail-open — a launch
- * never aborts because a temp file could not be written). When the seam is
+ * to a script and a short `source <path>` runner is returned. When the seam is
  * absent, the inline command is returned unchanged (legacy behaviour).
+ *
+ * The fail-open on a failed write is CONDITIONAL, and the condition is the point.
+ * Falling back to the inline command is only a fallback if the terminal can
+ * actually run it: above {@link MAX_TERMINAL_COMMAND_BYTES} the spawner truncates
+ * the line, so "fail-open" would deliver a corrupted command — a silent, confusing
+ * failure strictly worse than a loud one. So a failed write falls back inline only
+ * at or below the bound, and returns a structured failure above it.
  */
 export async function materializeWorkerLaunchCommand(deps, key, fullCommand) {
     if (!deps.writeWorkerLaunchScript)
-        return fullCommand;
+        return { ok: true, command: fullCommand };
     try {
         const scriptPath = await deps.writeWorkerLaunchScript({
             platform: deps.platform,
             key,
             content: buildLaunchScriptContent(deps.platform, fullCommand),
         });
-        return buildLaunchScriptRunnerCommand(deps.platform, scriptPath);
+        return { ok: true, command: buildLaunchScriptRunnerCommand(deps.platform, scriptPath) };
     }
     catch {
-        return fullCommand;
+        // Bytes, not `.length`: the bound is a byte bound, and a multibyte prompt can
+        // sit under 1024 JS characters while being well over 1024 UTF-8 bytes.
+        if (Buffer.byteLength(fullCommand, "utf8") <= MAX_TERMINAL_COMMAND_BYTES) {
+            return { ok: true, command: fullCommand };
+        }
+        return {
+            ok: false,
+            reason: "launch-script-write-failed-oversized-command",
+            error: "Could not write the temporary launch script, and the full command is too long to send " +
+                "to the terminal directly. Check that the system temporary directory is writable.",
+        };
     }
 }
 // ---------------------------------------------------------------------------
@@ -1569,10 +1636,17 @@ export async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildSh
         // agents, or conductor disabled). Never mutates process/global env.
         const shellCommand = injectConductorEnvIntoShellCommand(deps.platform, baseShellCommand, row.conductorEnv);
         // Deliver the (potentially multi-KB) command via a launch-script file so the
-        // terminal spawn payload stays tiny and escaping-immune. Fail-open / no-op
-        // when no writer seam is configured (see materializeWorkerLaunchCommand).
-        const runnableCommand = await materializeWorkerLaunchCommand(deps, row.key, shellCommand);
-        const result = await deps.spawnTerminalTab(deps, terminal, runnableCommand, {
+        // terminal spawn payload stays tiny and escaping-immune. No-op when no writer
+        // seam is configured; a failed write falls back inline only while the command
+        // is still launchable (see materializeWorkerLaunchCommand).
+        const materialized = await materializeWorkerLaunchCommand(deps, row.key, shellCommand);
+        if (!materialized.ok) {
+            // Known-unlaunchable: spawning the oversized inline command would deliver a
+            // truncated line. Fail this row only — siblings still launch.
+            out.push({ ...row, status: "spawn-failed", error: materialized.error });
+            continue;
+        }
+        const result = await deps.spawnTerminalTab(deps, terminal, materialized.command, {
             key: row.key,
             worktreePath: row.path,
         });
@@ -2251,6 +2325,45 @@ 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";
+/**
+ * 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
+ * to a concrete alias through the agent registry + per-repo overrides and, for
+ * cursor-agent, live-validated before injection. Rows are stamped with
+ * `difficulty: null`, the supplied `modelTier`, and `modelRoutingSource:
+ * "injected"`. Fail-open: an unmappable tier or a failed validation degrades to
+ * the agent default (with a row warning), never a throw. The alias is resolved +
+ * validated ONCE (identical for every row) so a cursor-agent batch fires at most
+ * one advertised-model probe.
+ */
+async function applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, agent, overrides, tier) {
+    const stampInjected = (row) => ({
+        ...row,
+        difficulty: null,
+        modelTier: tier,
+        modelRoutingSource: "injected",
+    });
+    const alias = resolveModelAlias(agent, tier, overrides);
+    if (!alias) {
+        const warning = `model routing: no valid alias for injected tier=${tier}; using agent default`;
+        return rows.map((r) => isEligible(r)
+            ? appendSummaryRowWarning({ ...stampInjected(r), modelAlias: null, modelRoutingReason: warning }, warning)
+            : r);
+    }
+    const validation = await validateResolvedModelAliasForAgent(deps, agent, alias);
+    if (!validation.ok) {
+        return rows.map((r) => isEligible(r)
+            ? appendSummaryRowWarning({ ...stampInjected(r), modelAlias: null, modelRoutingReason: validation.warning }, validation.warning)
+            : r);
+    }
+    return rows.map((r) => isEligible(r)
+        ? {
+            ...stampInjected(r),
+            modelAlias: validation.alias,
+            modelRoutingReason: `injected tier=${tier} model=${validation.alias}`,
+        }
+        : r);
+}
 /**
  * Shared fail-open routing resolution. `isEligible` selects which rows get a
  * resolved tier/alias; every failure mode (unsupported agent, credential/config/
@@ -2283,6 +2396,21 @@ async function resolveModelRoutingForEligible(deps, rows, options, agent, isElig
         const reason = "model routing: disabled for this repo; using agent default";
         return rows.map((r) => (isEligible(r) ? applyDefaultModelRoutingMetadata(r, reason) : r));
     }
+    // BAPI-642: an explicitly injected `--tier` short-circuits the per-ticket
+    // 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.
+    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);
+        return rows.map((r) => (isEligible(r) ? apply(r, warning) : r));
+    }
+    if (injected) {
+        return applyInjectedTierRoutingToEligibleRows(deps, rows, isEligible, agent, overrides, injected);
+    }
     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).
@@ -2379,12 +2507,25 @@ export async function resolveModelRoutingForDryRun(deps, rows, options, agent) {
 /**
  * Format one concise routing decision line per ticket:
  * `KEY difficulty=<n|?> tier=<tier|fallback> agent=<name> model=<alias|default>`.
- */
-export function formatModelRoutingLine(row, agent) {
+ *
+ * BAPI-642: an optional trailing label distinguishes the two non-default launch
+ * shapes so an operator can tell them apart in the diagnostics — `phase=review`
+ * for a `review-and-implement` chain launch and `routing=injected` for a
+ * `--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.
+ */
+export function formatModelRoutingLine(row, agent, context) {
     const difficulty = typeof row.difficulty === "number" ? String(row.difficulty) : "?";
     const tier = row.modelTier ?? "fallback";
     const model = row.modelAlias ?? "default";
-    return `${row.key} difficulty=${difficulty} tier=${tier} agent=${agent.name} model=${model}`;
+    const base = `${row.key} difficulty=${difficulty} tier=${tier} agent=${agent.name} model=${model}`;
+    const labels = [];
+    if (context?.workflow === "review-and-implement")
+        labels.push("phase=review");
+    if (row.modelRoutingSource === "injected")
+        labels.push("routing=injected");
+    return labels.length > 0 ? `${base} ${labels.join(" ")}` : base;
 }
 /** Stable de-dup key for an invocation-level routing diagnostic. */
 function modelRoutingDiagnosticKey(d) {
@@ -2718,7 +2859,7 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     for (const row of routed) {
         if (row.status !== "created" || !row.path)
             continue;
-        overrides.modelRoutingLog?.(formatModelRoutingLine(row, agent));
+        overrides.modelRoutingLog?.(formatModelRoutingLine(row, agent, { workflow: options.workflow }));
     }
     // Single invocation-level routing diagnostic to stderr (de-duplicated across
     // rows). Fail-open: emission is best-effort and never blocks spawning.
@@ -2776,6 +2917,13 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         errorLog(`Error: Unknown agent: '${options.agentName}'. Valid agents: ${formatValidAgentNames()}.`);
         return 1;
     }
+    // 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.
+    if (options.injectedTier === INJECTED_TIER_UNRESOLVED) {
+        errorLog("Warning: --tier value was not one of cheap|basic|premium; ignoring the override and " +
+            "using premium model routing for every ticket.");
+    }
     if (options.dryRun) {
         // Resolve the repo identity for the preview so the dry-run command matches
         // what the real spawn injects (see prependRepoNameEnvAssignment). The real
@@ -2799,7 +2947,7 @@ export async function runStartTicketsCli(argv, overrides = {}) {
             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)) {
                 log(line);
             }
-            log(`DRY-RUN:   model routing: ${formatModelRoutingLine(routedRow ?? { key, branch, status: "dry-run" }, agent)}`);
+            log(`DRY-RUN:   model routing: ${formatModelRoutingLine(routedRow ?? { key, branch, status: "dry-run" }, agent, { workflow: options.workflow })}`);
             if (modelAlias == null && routedRow?.modelRoutingReason) {
                 log(`DRY-RUN:   ${routedRow.modelRoutingReason}`);
             }