@bridge_gpt/mcp-server 0.2.60 → 0.2.65

package/README.md

@@ -369,7 +369,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.65", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -391,7 +391,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.65", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -413,7 +413,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.65", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -436,7 +436,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.65", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -455,7 +455,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.65", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -1049,7 +1049,7 @@ Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switch
 npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
 ```
 
-**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-6 → basic, 7-10 → premium) and may inject `--model` at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand). Claude and Cursor map that tier through their agent registry aliases; Cursor validates against `cursor-agent --list-models`. Routing is gated per repo by `difficulty_model_routing_enabled` (default **ON**). Claude/Cursor may use `difficulty_model_tier_overrides` (tier → alias) and retain their premium fallback behavior on an unknown tier or transient failure. When an alias cannot be validated, the CLI omits `--model` and launches the agent default. `--dry-run` resolves routing read-only to preview the command without creating worktrees or opening tabs.
+**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-6 → basic, 7-10 → premium) and may inject `--model` at the spawn boundary. Under the repo's `quality` optimization posture (also the fail-safe default), premium starts one step earlier, at difficulty 6. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand). Claude and Cursor map that tier through their agent registry aliases; Cursor validates against `cursor-agent --list-models`. Routing is gated per repo by `difficulty_model_routing_enabled` (default **ON**). Claude/Cursor may use `difficulty_model_tier_overrides` (tier → alias) and retain their premium fallback behavior on an unknown tier or transient failure. When an alias cannot be validated, the CLI omits `--model` and launches the agent default. `--dry-run` resolves routing read-only to preview the command without creating worktrees or opening tabs.
 
 For Codex, `GET /jira/codex-model-catalog?repo_name=...` is the sole tier-to-model authority. Bridge derives its three bare CLI IDs and SHA-256 mapping revision at request time from `MODEL_REGISTRY`; the launcher fetches and validates that catalog once per invocation. Repository `difficulty_model_tier_overrides` do not apply to Codex. A failed access, config, tier, catalog, revision, or alias check omits `--model` and launches the configured Codex default. The catalog expresses **Bridge provider policy only**: it cannot confirm that the local Codex login or subscription can use a model. The CLI has no supported non-interactive entitlement probe, so routing emits that limitation as a diagnostic and never uses Bridge's OpenAI API key as proof of local access.
 
@@ -1128,6 +1128,43 @@ including every error path, ever offers you two paths.
 the strategy and the posture (see below). With none of them, a multi-ticket epic
 runs on `epic/<KEY>`, unattended.
 
+**Finding the plan from the epic key (BAPI-1285).** `--plan-file` is optional.
+Without it, `drive-epic` searches `{docs_dir}/epic-plans/*/epic-plan.meta.json` for a
+file whose `epic_key` is exactly this epic (`docs_dir` is `BAPI_DOCS_DIR`, else
+`docs/tmp`, resolved against the Git top level; an absolute `BAPI_DOCS_DIR` is used
+as given). Exactly one match with a sibling `epic-plan.dag.json` is used as if you
+had passed `--plan-file`, and its path is printed before anything is created. Zero
+matches, two or more, or an unusable meta file **stop** with the paths found and
+create nothing, and a folder name, a child ticket key, or
+`sibling-ticket-manifest.json` is never used to guess. A supplied `--plan-file`
+always wins and discovery does not run.
+
+The meta file is `{"epic_key": "<KEY>"}`, written by `emit-epic-implementer-bundle
+finalize` beside the DAG (its own atomic write, reported as `meta_path` in
+`--json`). It is separate from `epic-plan.dag.json` on purpose: the DAG is sent to
+the server, which rejects unknown fields. A plan finalized before this change has no
+meta file, so it is reported as not found — pass its DAG with `--plan-file`.
+
+**A live run with no plan.** If the epic already has a live run and no plan was
+supplied or found, `drive-epic` creates nothing. It makes sure that run has an
+executor: it reuses a verified live one (never starting a second), starts one when
+the old one is gone, starts none for a durable launch profile with a confirmed
+repo-wide executor, and starts none when this checkout's plane is bound to that
+run. An epic with several active runs (`live-run-ambiguous`), or a run that cannot
+be read (`live-run-unknown`), is refused by name.
+
+**Preview with `--dry-run`.** `drive-epic <EPIC> --dry-run` is read-only. It reads
+the target, readiness, the live run, and the plan, runs the bootstrap's own dry-run
+validation when a plan is available, and reports the decision a real invocation
+would make — `create`, `attach`, `refuse`, or `stop` (exit `0` for the first two,
+`1` for the others). It never creates a run, cuts a branch, starts a plane,
+requests a lane, or starts or signals an executor. With `--json` (valid only with
+`--dry-run`) stdout carries exactly one JSON document with `epic_key`, `target`,
+`readiness`, `live_run`, `plan`, `summary`, `decision`, and `refusal`. The
+readiness `reason_id` and `remedy` are the strings the real refusal prints. The
+webhook URL, credentials, and policy contents are never included. The preview does
+not probe ports, so a local plane that is not listening reads as unknown readiness.
+
 **The composed bring-up is two-phase (BAPI-1102).** With `--plan-file` on a
 repository whose readiness is missing only the runtime facts, one invocation runs,
 in order: the **control plane** (Bridge API server + reconciler, each gated on its
@@ -1209,8 +1246,10 @@ default, or, when it declares none, as an explicit recorded `no_ci_gate` mode.
 > combining `--attended` with a file that declares `posture: "unattended"` is a named
 > refusal rather than a silent winner.
 
-An unattended run has two one-time **repository** prerequisites — consent
-(`unattended_epic_implementer_allowed`) and a verified notify webhook default — plus
+An unattended run has two **repository** prerequisites — consent
+(`unattended_epic_implementer_allowed`, ON by default; the repository owner can switch
+"Allow unattended Epic Implementer runs" off and on in the Bridge admin panel's Setup
+page) and a verified notify webhook default — plus
 confirmed default-branch review/CI workflows. Each is refused by name **before any
 run row is created** (`target_not_allowed`, `webhook_unverified`,
 `repository_readiness_unconfirmed`), and `drive-epic` readiness and `doctor` both
@@ -1263,7 +1302,7 @@ one file in your repository that can perform a privileged merge.
 
 | Path | What it is |
 |---|---|
-| `.github/workflows/epic-implementer-merge.yml` | The merge workflow, contract version 1. |
+| `.github/workflows/epic-implementer-merge.yml` | The merge workflow, contract version 2. |
 | `.bridge/merge-workflow/CODEOWNERS.fragment` | A CODEOWNERS rule for that path. Not in force until you merge it into your active CODEOWNERS file. |
 | `.bridge/merge-workflow/REPOSITORY-RULES.md` | The setup steps, including the repository rule that actually enforces review. |
 
@@ -1326,13 +1365,13 @@ against it.
 
 #### Canonical template
 
-Git blob SHA of the rendered workflow: `3d4956c9447223c37075069352cdd9aae2d561dc`
+Git blob SHA of the rendered workflow: `83089be700759e2e4d423ecedb7373829676ef39`
 
 ```yaml
 name: Epic Implementer merge
 
 env:
-  x-bridge-merge-contract-version: 1
+  x-bridge-merge-contract-version: 2
 
 on:
   workflow_dispatch:
@@ -1349,6 +1388,14 @@ on:
           printed, never echoed, never written to an output.
         required: true
         type: string
+      operation:
+        description: >-
+          Which job runs. `child_merge` (the default) merges an approved
+          child pull request; `integration_action` performs one integration
+          action. Selects a job only; the work itself is fetched from Bridge.
+        required: false
+        default: child_merge
+        type: string
 
 permissions:
   contents: write

package/build/agent-launchers/claude-executor-adapter.js

@@ -7,7 +7,8 @@ import { provisionExecutorDenyLayer } from "../executor/permissions.js";
 import { WORKER_GUARD_ROOT_FLAG } from "../executor/worker-guard-hook.js";
 import { SUPPORTED_EXECUTOR_PLATFORMS, evaluateExecutorPlatform } from "../executor/platform.js";
 import { normalizeMcpServerNames } from "../executor/observation.js";
-import { supported } from "./executor-adapter.js";
+import { COMPLETION_EVIDENCE_TRANSPORT, supported } from "./executor-adapter.js";
+import { SUPPORTED_COMPLETION_RUNTIME, boundedIdentifier, } from "../executor/completion-contract.js";
 import { MCP_SERVER_NAME } from "../mcp-identity.js";
 /** Stable identity of this reference implementation. */
 export const CLAUDE_ADAPTER_ID = "claude-reference";
@@ -210,8 +211,17 @@ export function resolveClaudeModelAlias(spec, payload) {
  * Every entry is pushed SEPARATELY and never joined into a command string, so a
  * prompt or path containing a space or a shell metacharacter is just a value.
  */
-export function buildClaudeArgv(prompt, alias, mcpConfigPath, posture) {
-    const argv = ["-p", prompt, "--output-format", "stream-json", "--verbose"];
+export function buildClaudeArgv(prompt, alias, mcpConfigPath, posture, options = {}) {
+    // BAPI-1301 (D4a): the held-stdin form keeps `-p` (headless print mode) but
+    // puts NO prompt on argv — it arrives as the first stream-json user message on
+    // a held-open stdin, which is what lets the executor keep the worker alive
+    // until its required background work resolves. Everything after the input
+    // flags — output format, model, exactly one permission posture, strict MCP
+    // loading — is identical to the argv form. The default is byte-identical to the
+    // pre-BAPI-1301 golden shape.
+    const argv = options.promptTransport === "stdin-stream-json"
+        ? ["-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose"]
+        : ["-p", prompt, "--output-format", "stream-json", "--verbose"];
     if (alias) {
         argv.push("--model", alias);
     }
@@ -219,6 +229,101 @@ export function buildClaudeArgv(prompt, alias, mcpConfigPath, posture) {
     argv.push("--strict-mcp-config", "--mcp-config", mcpConfigPath);
     return argv;
 }
+// ---------------------------------------------------------------------------
+// Held-stdin stream-json messages (BAPI-1301, D4a)
+// ---------------------------------------------------------------------------
+/**
+ * One stream-json user message as the exact NDJSON line written to the held
+ * stdin: `{"type":"user","message":{"role":"user","content":<text>}}\n`.
+ * `JSON.stringify` escapes every newline inside `text`, so one message is always
+ * exactly one line.
+ */
+function claudeStdinUserLine(text) {
+    return `${JSON.stringify({ type: "user", message: { role: "user", content: text } })}\n`;
+}
+/** The prompt as the first held-stdin user message. */
+export function buildClaudeStdinUserMessage(prompt) {
+    return claudeStdinUserLine(prompt);
+}
+/** At most this many task ids are named in a nudge. */
+const NUDGE_MAX_TASK_IDS = 16;
+/**
+ * The ONE optional-watcher nudge (BAPI-1301, D4a), sent when the worker produced
+ * its result while background tasks are still live.
+ *
+ * The wording is the safety property. It asks the worker to WAIT for tasks it
+ * needs and to stop ONLY an optional watcher it no longer needs — it never asks
+ * the worker to cancel, kill, or abandon required work to finish sooner, because
+ * a nudge that could talk a worker out of required work would turn the
+ * supervision meant to guarantee completion into a way to skip it. Task ids are
+ * passed through {@link boundedIdentifier}; anything that is not a safe opaque
+ * identifier is dropped rather than echoed.
+ */
+export function buildClaudeWatcherNudgeMessage(liveTaskIds) {
+    const ids = liveTaskIds
+        .map((id) => boundedIdentifier(id))
+        .filter((id) => id !== null)
+        .slice(0, NUDGE_MAX_TASK_IDS);
+    const named = ids.length > 0 ? ` (task ids: ${ids.join(", ")})` : "";
+    return claudeStdinUserLine(`Your result was received, but background work you started is still running${named}. ` +
+        "If that work is part of this task, wait for it to finish and then report its outcome. " +
+        "If a task is only an optional watcher you no longer need (for example a monitor or a " +
+        "background log tail), you may stop that watcher. Do not cancel, kill, or abandon any " +
+        "required work in order to finish sooner.");
+}
+// ---------------------------------------------------------------------------
+// Runtime identity probe (BAPI-1301, D4a)
+// ---------------------------------------------------------------------------
+/** Bound on the `--version` identity probe. */
+export const CLAUDE_RUNTIME_PROBE_TIMEOUT_MS = 15_000;
+/** Placeholder for a version the probe could not recognize — never matches. */
+export const UNRECOGNIZED_CLI_VERSION = "unrecognized";
+/**
+ * Parse `claude --version` output of the exact measured form
+ * `2.1.282 (Claude Code)` into `2.1.282`. Anything else is null — the raw text
+ * is never carried, because it would travel into logs and evidence.
+ */
+export function parseClaudeCliVersion(stdout) {
+    const firstLine = (typeof stdout === "string" ? stdout : "").trim().split("\n")[0]?.trim() ?? "";
+    const match = /^(\d{1,4}\.\d{1,4}\.\d{1,6}) \(Claude Code\)$/.exec(firstLine);
+    return match ? match[1] : null;
+}
+/**
+ * The completion platform id for a host: `darwin` + `arm64` is `darwin-arm64`.
+ * Every other pair is rendered as `<os>-<arch>` over a closed character set, so
+ * it is bounded and can never equal the approved id by accident.
+ */
+export function completionPlatformId(platform, arch) {
+    const clean = (value) => (typeof value === "string" ? value : "").toLowerCase().replace(/[^a-z0-9_]/g, "").slice(0, 16) ||
+        "unknown";
+    return `${clean(platform)}-${clean(arch)}`;
+}
+/**
+ * Probe the installed Claude runtime's completion identity through the INJECTED
+ * command runner (the adapter never spawns on its own authority). Resolves null
+ * when the probe could not run or exited non-zero; otherwise an identity whose
+ * `cli_version` is the parsed version or {@link UNRECOGNIZED_CLI_VERSION}. The
+ * event schema is the one this adapter's lifecycle parser speaks. Never throws.
+ */
+export async function probeClaudeCompletionRuntime(command, deps) {
+    let output;
+    try {
+        output = await deps.runCommand(command, ["--version"], {
+            timeoutMs: deps.timeoutMs ?? CLAUDE_RUNTIME_PROBE_TIMEOUT_MS,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!output || output.exitCode !== 0)
+        return null;
+    return {
+        adapter: SUPPORTED_COMPLETION_RUNTIME.adapter,
+        cli_version: parseClaudeCliVersion(output.stdout) ?? UNRECOGNIZED_CLI_VERSION,
+        platform: completionPlatformId(deps.platform ?? process.platform, deps.arch ?? process.arch),
+        event_schema: SUPPORTED_COMPLETION_RUNTIME.event_schema,
+    };
+}
 /**
  * The single permission form for one posture — the whole policy→argv mapping,
  * in one exhaustive place.
@@ -348,6 +453,18 @@ export function createClaudeExecutorAdapter(spec, deps = {}) {
             if (input.declaredTouchedFiles !== undefined) {
                 envOptions.declaredTouchedFiles = input.declaredTouchedFiles;
             }
+            // BAPI-1301 (D4a): the held-stdin transport is opted into per spawn. The
+            // argv form returns exactly the pre-BAPI-1301 three-key shape.
+            if (input.promptTransport === "stdin-stream-json") {
+                return {
+                    executable: spec.command,
+                    argv: buildClaudeArgv(input.prompt, input.modelAlias, input.mcpConfigPath, input.posture, {
+                        promptTransport: "stdin-stream-json",
+                    }),
+                    env: buildClaudeWorkerEnv(input.parentEnv, envOptions),
+                    stdinMessages: { initial: buildClaudeStdinUserMessage(input.prompt) },
+                };
+            }
             return {
                 executable: spec.command,
                 argv: buildClaudeArgv(input.prompt, input.modelAlias, input.mcpConfigPath, input.posture),
@@ -470,6 +587,19 @@ export function createClaudeExecutorAdapter(spec, deps = {}) {
             }
         },
     };
+    /**
+     * BAPI-1301 (D4a) — declared for exactly the measured identity (Claude Code
+     * 2.1.282, macOS arm64, the lifecycle event schema this adapter parses).
+     * Declaring it is not qualifying: preflight probes the installed runtime and
+     * advertises `completion_evidence.v1` only on an exact match, so a future CLI
+     * version or another platform stays unsupported until it is measured.
+     */
+    const completionEvidence = {
+        runtime: { ...SUPPORTED_COMPLETION_RUNTIME },
+        transport: COMPLETION_EVIDENCE_TRANSPORT,
+        probeRuntime: (probeDeps) => probeClaudeCompletionRuntime(spec.command, probeDeps),
+        buildWatcherNudge: buildClaudeWatcherNudgeMessage,
+    };
     return {
         identity: {
             agentId: spec.name,
@@ -488,5 +618,6 @@ export function createClaudeExecutorAdapter(spec, deps = {}) {
         redaction: supported(redaction),
         lifecycle: supported(lifecycle),
         advisoryMcpInspection: supported(advisoryMcpInspection),
+        completionEvidence: supported(completionEvidence),
     };
 }

package/build/agent-launchers/executor-adapter.js

@@ -8,6 +8,42 @@ export function unsupported(reason, strategyId) {
         ? { supported: false, reason }
         : { supported: false, reason, strategyId };
 }
+// ---------------------------------------------------------------------------
+// Completion evidence (job-specific, non-required) — BAPI-1301 (D4a)
+// ---------------------------------------------------------------------------
+/** The one held-stdin transport a completion-evidence adapter can declare. */
+export const COMPLETION_EVIDENCE_TRANSPORT = "held-stdin-stream-json";
+/**
+ * Validate an OPTIONAL completion-evidence declaration (BAPI-1301).
+ *
+ * Returns the usable capability or a bounded reason it cannot be used. Never a
+ * refusal of the adapter: an absent, unsupported, or malformed declaration only
+ * means the executor does not advertise `completion_evidence.v1`.
+ */
+export function resolveCompletionEvidenceCapability(adapter) {
+    const declared = adapter.completionEvidence;
+    if (declared === undefined || declared === null) {
+        return { supported: false, reason: "adapter declares no completion-evidence capability" };
+    }
+    if (declared.supported !== true) {
+        const reason = typeof declared.reason === "string" && declared.reason.length > 0
+            ? declared.reason.slice(0, 200)
+            : "completion-evidence capability is declared unsupported";
+        return { supported: false, reason };
+    }
+    const value = declared.value;
+    const runtime = value?.runtime;
+    const wellFormedRuntime = !!runtime &&
+        ["adapter", "cli_version", "platform", "event_schema"].every((key) => typeof runtime[key] === "string" && runtime[key].length > 0);
+    if (!value ||
+        !wellFormedRuntime ||
+        value.transport !== COMPLETION_EVIDENCE_TRANSPORT ||
+        typeof value.probeRuntime !== "function" ||
+        typeof value.buildWatcherNudge !== "function") {
+        return { supported: false, reason: "completion-evidence capability declaration is malformed" };
+    }
+    return { supported: true, value: value };
+}
 /**
  * The capability keys an adapter MUST supply as supported.
  *
@@ -93,10 +129,26 @@ export function validateExecutorAdapterCapabilities(adapter) {
             reason: null,
         });
     }
+    // BAPI-1301 (D4a): the job-specific completion-evidence capability is
+    // validated ONLY when declared, and its outcome never joins `refusals` — an
+    // adapter that cannot supervise required work is still a complete adapter for
+    // every other job. The key is added only when declared, so an adapter without
+    // it validates to exactly the pre-BAPI-1301 shape.
+    const optional = {};
+    if (adapter.completionEvidence !== undefined && adapter.completionEvidence !== null) {
+        const resolved = resolveCompletionEvidenceCapability(adapter);
+        optional.optionalCapabilities = [
+            {
+                capability: "completionEvidence",
+                supported: resolved.supported,
+                reason: resolved.supported ? null : resolved.reason,
+            },
+        ];
+    }
     if (refusals.length > 0) {
-        return { ok: false, identity, refusals, capabilities };
+        return { ok: false, identity, refusals, capabilities, ...optional };
     }
-    return { ok: true, identity, capabilities };
+    return { ok: true, identity, capabilities, ...optional };
 }
 /** Render a bounded, secret-free summary of why an adapter was refused. */
 export function formatAdapterRefusal(identity, refusals) {