@bridge_gpt/mcp-server 0.2.49 → 0.2.50

package/README.md

@@ -343,6 +343,7 @@ package to an exact version and pass `--prefer-offline`, which is what the
 generated entries do and what keeps npx from resolving a different build on some
 later boot.
 
+<!-- BEGIN GENERATED: mcp-host-examples (managed by mcp_server/scripts/sync-readme-host-examples.js — DO NOT EDIT BY HAND) -->
 <details>
 <summary><strong>Claude Code (.mcp.json)</strong></summary>
 
@@ -351,7 +352,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.49", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.50", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -373,7 +374,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.49", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.50", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -395,7 +396,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.49", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.50", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -420,7 +421,7 @@ you select `copilot-cli`; the shape below is what it produces.
     "bridge": {
       "type": "local",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.49", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.50", "serve"],
       "tools": ["*"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
@@ -444,7 +445,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.49", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.50", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -463,7 +464,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.49", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.50", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -474,6 +475,7 @@ BAPI_DOCS_DIR = "docs/tmp"
 
 > Codex users: set `BAPI_PROJECT_ROOT` manually in your config (see [Environment Variables](#environment-variables)).
 </details>
+<!-- END GENERATED: mcp-host-examples -->
 
 After saving, reload your editor and ask your assistant to call the `ping` tool to
 confirm the connection.
@@ -768,7 +770,6 @@ Repository and ticket housekeeping commands, beyond the tiers above. Implementat
 | Command | What it does |
 |---|---|
 | `/parse-repository` | Queue a background job to index the repository for Bridge AI agents |
-| `/check-parse-status` | Check whether a background repository parse job is still running |
 | `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |
 
 > Commands are designed for Claude Code. Other editors may support slash commands differently — check your editor's documentation for how to invoke prompt files.
@@ -1022,6 +1023,22 @@ authenticate. See
 
 It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent's command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
 
+**`claude-review` workflow lineage (advisory, read-only).** `doctor` also reports
+whether the current branch's `.github/workflows/claude-review.yml` matches the
+repository default branch's copy. This matters because
+`anthropics/claude-code-action` refuses to run when the two differ — so a
+long-lived base branch that has fallen behind silently blinds automated review for
+**every pull request based on it**, even though those pull requests change no
+workflow file at all. The probe runs `git symbolic-ref`, `git rev-parse`, and two
+`git show` reads against the local object database: it **fetches nothing, spawns
+nothing, and creates no worktree**, and an unresolvable ref simply reports the
+comparison as unavailable. It is **advisory only** — it is registered as a
+doctor-only diagnostic and **never changes `doctor`'s required-prerequisite exit
+code**, whether it finds drift or cannot complete the comparison. Spawning a
+worker against a stale base prints the same advisory and **still spawns the
+worker**. Remedy and full diagnosis:
+`docs/claude/runbooks/claude-review-base-branch-drift.md`.
+
 ### `drive-epic`
 
 The one conductor entry point every Bridge surface names. Give it an epic key and

package/build/base-ref.js

@@ -23,6 +23,7 @@
  * acyclic (mirrors the existing `worktree-core.ts` / prereqs pattern).
  */
 import path from "path";
+import { resolveRepositoryDefaultBranch } from "./claude-review-workflow-drift-probe.js";
 import { commandSucceeded } from "./start-tickets-prereqs.js";
 /**
  * Returns an error string for an unsafe branch name, or null when valid.
@@ -55,6 +56,16 @@ export function validateBranchName(branch) {
     return null;
 }
 // ---------------------------------------------------------------------------
+// `claude-review` workflow drift evidence (BAPI-941)
+// ---------------------------------------------------------------------------
+// The git-backed acquisition lives in the LEAF `claude-review-workflow-drift-probe`
+// module, not here: `doctor`'s read-only probe in `start-tickets-prereqs.ts` needs
+// the same functions, and this module already imports `commandSucceeded` FROM
+// that module — so defining them here would close a cycle in a runtime graph both
+// modules document as acyclic. They are re-exported so `fetchAndResolveBaseSha`'s
+// callers keep one import site.
+export { resolveRepositoryDefaultBranch, probeClaudeReviewWorkflowDrift, } from "./claude-review-workflow-drift-probe.js";
+// ---------------------------------------------------------------------------
 // Per-repository fetch serialization
 // ---------------------------------------------------------------------------
 /**
@@ -130,9 +141,23 @@ export async function fetchAndResolveBaseSha(deps, baseBranch) {
     }
     const repoKey = normalizeRepoKey(deps.cwd);
     return withRepoFetchLock(repoKey, async () => {
-        const fetch = await deps.runCommand("git", ["fetch", "origin", baseBranch], {
-            cwd: deps.cwd,
-        });
+        // BAPI-941: refresh the DEFAULT branch in the same invocation whenever it
+        // differs from the base, so the caller's drift advisory costs no additional
+        // network round trip. Deduplicated when the base IS the default branch.
+        const defaultBranch = await resolveRepositoryDefaultBranch(deps);
+        const extraRefs = defaultBranch && defaultBranch !== baseBranch && validateBranchName(defaultBranch) === null
+            ? [defaultBranch]
+            : [];
+        let fetch = await deps.runCommand("git", ["fetch", "origin", baseBranch, ...extraRefs], { cwd: deps.cwd });
+        if (!commandSucceeded(fetch) && extraRefs.length > 0) {
+            // The advisory's extra refspec must never turn a resolvable base into a
+            // failure — a renamed or deleted default branch on the remote would do
+            // exactly that. Retry the historical single-ref fetch and keep the
+            // original success semantics; the drift check simply goes unverified.
+            fetch = await deps.runCommand("git", ["fetch", "origin", baseBranch], {
+                cwd: deps.cwd,
+            });
+        }
         if (!commandSucceeded(fetch)) {
             return {
                 ok: false,

package/build/claude-review-workflow-drift-probe.js

@@ -0,0 +1,130 @@
+/**
+ * Git-backed acquisition for the `claude-review` workflow drift advisory (BAPI-941).
+ *
+ * `claude-review-workflow-drift.ts` is a pure classifier — it takes bytes and
+ * returns a verdict, and touches neither git nor the network. This module is the
+ * thin layer that GETS those bytes out of the local object database.
+ *
+ * It is a deliberate LEAF: it imports the pure classifier and a type-only
+ * `RunCommand`, and nothing else. That matters because two very different
+ * callers need it —
+ *
+ *   - `base-ref.ts` (the worker-spawn advisory, on both the fetch-only conductor
+ *     path and the interactive refresh path), and
+ *   - `start-tickets-prereqs.ts` (the read-only `doctor` probe)
+ *
+ * — and `base-ref.ts` already imports `commandSucceeded` FROM
+ * `start-tickets-prereqs.ts`. Putting these functions in either of those modules
+ * would close a cycle in a runtime graph both modules document as acyclic. The
+ * one-line exit-code predicate below is duplicated for exactly that reason; it is
+ * cheaper than the cycle it avoids.
+ *
+ * Every operation here is READ-ONLY. Nothing fetches, checks out, resets,
+ * merges, or moves a ref — `git show <ref>:<path>` reads straight out of the
+ * object database, which is what makes this safe to run against a checkout an
+ * operator's live dev server is editing.
+ */
+import { CLAUDE_REVIEW_WORKFLOW_RELPATH, classifyClaudeReviewWorkflowDrift, } from "./claude-review-workflow-drift.js";
+/** See the module docstring: duplicated to keep this module a leaf. */
+function succeeded(result) {
+    return result.exitCode === 0;
+}
+/**
+ * Resolve the repository's default branch from the local clone, with no network
+ * call and no hardcoded `main`.
+ *
+ * `refs/remotes/origin/HEAD` is git's own record of the remote's default branch,
+ * written at clone time and refreshable with `git remote set-head origin -a`. A
+ * clone that lacks it (a bare `git init` + `git remote add`, or an older shallow
+ * fetch) yields `null`, which callers map to an `unverified` classification —
+ * the advisory fails open rather than guessing a branch name.
+ */
+export async function resolveRepositoryDefaultBranch(deps) {
+    const result = await deps.runCommand("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd: deps.cwd });
+    if (!succeeded(result))
+        return null;
+    const ref = result.stdout.trim();
+    if (ref.length === 0)
+        return null;
+    // `origin/main` -> `main`. Only the leading remote name is stripped, so a
+    // branch whose own name contains `origin/` survives intact.
+    const prefix = "origin/";
+    const branch = ref.startsWith(prefix) ? ref.slice(prefix.length) : ref;
+    return branch.length > 0 ? branch : null;
+}
+/**
+ * Read the reviewed workflow's bytes at a ref without checking anything out.
+ *
+ * A missing file at that ref and an unresolvable ref are indistinguishable from
+ * git's exit code alone, and both are equally inconclusive here, so they share
+ * one reason code chosen by the caller. Git's stderr is never propagated — it
+ * can echo absolute paths.
+ */
+async function readWorkflowBlobAtRef(deps, ref, unreadableReason) {
+    const result = await deps.runCommand("git", ["show", `${ref}:${CLAUDE_REVIEW_WORKFLOW_RELPATH}`], { cwd: deps.cwd });
+    if (!succeeded(result)) {
+        return { ok: false, reason: unreadableReason };
+    }
+    return { ok: true, content: Buffer.from(result.stdout, "utf8") };
+}
+/**
+ * Compare the reviewed workflow at a base ref against the default branch's copy.
+ *
+ * Network-free: every ref it reads must already be present locally, which is why
+ * the spawn-time caller invokes this immediately AFTER its own fetch rather than
+ * fetching again, and why the doctor caller can run it without touching the
+ * network at all. Never throws and never returns an error — the advisory has
+ * exactly three outcomes, and an unusable comparison is one of them.
+ */
+export async function probeClaudeReviewWorkflowDrift(deps, options) {
+    const { baseRef } = options;
+    const defaultRef = options.defaultRef;
+    if (!defaultRef) {
+        return classifyClaudeReviewWorkflowDrift({
+            baseRef,
+            defaultRef: "",
+            base: { ok: false, reason: "default_branch_unknown" },
+            default: { ok: false, reason: "default_branch_unknown" },
+        });
+    }
+    if (baseRef === defaultRef) {
+        // A ref cannot be stale relative to itself. The classifier short-circuits on
+        // this too; returning early keeps the two `git show` invocations unspent.
+        return classifyClaudeReviewWorkflowDrift({
+            baseRef,
+            defaultRef,
+            base: { ok: false, reason: "comparison_unavailable" },
+            default: { ok: false, reason: "comparison_unavailable" },
+        });
+    }
+    // Read against the REMOTE-TRACKING refs, which are what a preceding fetch
+    // actually refreshed. A local `epic/BAPI-902` may lag its origin counterpart,
+    // and the drift that matters is the one a worker's pull request will inherit.
+    const base = await readWorkflowBlobAtRef(deps, `origin/${baseRef}`, "base_workflow_unreadable");
+    const defaultBlob = await readWorkflowBlobAtRef(deps, `origin/${defaultRef}`, "default_workflow_unreadable");
+    return classifyClaudeReviewWorkflowDrift({
+        baseRef,
+        defaultRef,
+        base,
+        default: defaultBlob,
+    });
+}
+/**
+ * Resolve the ref a read-only diagnostic should treat as "the base": the current
+ * checkout's branch. `doctor` has no ticket and no run, so the branch the
+ * operator is standing on is the one whose lineage they are asking about.
+ *
+ * Returns `null` on a detached HEAD or any git failure — both are inconclusive,
+ * and the caller reports that rather than inventing a ref.
+ */
+export async function resolveCurrentBranch(deps) {
+    const result = await deps.runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd: deps.cwd,
+    });
+    if (!succeeded(result))
+        return null;
+    const branch = result.stdout.trim();
+    if (branch.length === 0 || branch === "HEAD")
+        return null;
+    return branch;
+}

package/build/claude-review-workflow-drift.js

@@ -0,0 +1,173 @@
+/**
+ * Shared `claude-review` workflow drift identity and classification (BAPI-941).
+ *
+ * `anthropics/claude-code-action` refuses to run when the workflow file invoking
+ * it is not byte-identical to the copy on the repository's DEFAULT branch — its
+ * own supply-chain guard. The failure everyone recognizes is "this pull request
+ * edited the workflow". The failure nobody recognized is the TRANSITIVE one: a
+ * pull request whose own commits never touch `.github/` still trips the guard
+ * when its BASE branch carries a stale copy. Every open PR based on a long-lived
+ * `epic/**` branch goes silently unreviewed the moment the workflow changes on
+ * `main`, and a conductor-driven epic then parks at `needs_human` with
+ * `review_verdictless_ceiling_reached` an hour later, having produced no verdict
+ * comment at any point.
+ *
+ * This module is the ONE place that knows how to establish workflow identity and
+ * how to name the three outcomes. Worker spawning (`base-ref` / `start-tickets`),
+ * the read-only `doctor` probe, and the conductor install doctor all classify
+ * through here, so they cannot develop independent SHA logic that disagrees
+ * about what "the same workflow" means.
+ *
+ * Deliberate boundaries:
+ *
+ *   - **No CLI dispatch, no spawning, no filesystem or network access.** Callers
+ *     acquire the bytes however their own layer already does (a `git show` against
+ *     an already-fetched ref, a Contents API lookup, a local read) and hand the
+ *     result in. That keeps this importable from `base-ref.ts`, `doctor.ts`, and
+ *     `conductor/install-doctor.ts` without a dependency cycle.
+ *   - **Acquisition failure is never drift.** A missing ref, an unreadable blob,
+ *     an unresolved default branch, or a provider error maps to `unverified`,
+ *     never to `drifted`. The guard is advisory and fail-open everywhere it is
+ *     consumed; reporting drift we could not actually prove would train operators
+ *     to ignore the one diagnostic that matters.
+ *   - **Nothing here logs file content.** Diagnostics carry refs, the workflow
+ *     path, and a fixed reason code — never bytes, never provider exception text.
+ */
+import crypto from "crypto";
+/**
+ * Repo-relative path of the reviewed workflow. Defined here rather than in
+ * `claude-review-workflow.ts` so the drift module stays a leaf: the renderer
+ * imports and re-exports this, and the import direction never reverses.
+ */
+export const CLAUDE_REVIEW_WORKFLOW_RELPATH = ".github/workflows/claude-review.yml";
+/**
+ * Git's blob object header, reproduced so a locally-read file can be compared
+ * against the GitHub Contents API's own `sha` without downloading or decoding the
+ * remote file. Kept as a shared constant because the rendered workflow preflight
+ * builds the identical header inside its `actions/github-script` body — one
+ * construction, two runtimes.
+ */
+export function gitBlobHeader(byteLength) {
+    return Buffer.from(`blob ${byteLength}\0`, "utf8");
+}
+/**
+ * The lowercase Git blob SHA-1 of raw bytes: `sha1("blob <len>\0" + content)`.
+ *
+ * Takes BYTES, not text, deliberately. Decoding to a string and re-encoding would
+ * normalize nothing useful and could silently change the byte length on invalid
+ * UTF-8, producing an identity that disagrees with git's — which is the exact
+ * class of bug a second independent implementation introduces.
+ */
+export function computeGitBlobSha(content) {
+    const raw = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    return crypto
+        .createHash("sha1")
+        .update(Buffer.concat([gitBlobHeader(raw.length), raw]))
+        .digest("hex")
+        .toLowerCase();
+}
+/** Human-readable, secret-free gloss for each reason code. */
+const UNAVAILABLE_REASON_TEXT = {
+    default_branch_unknown: "the repository default branch could not be determined",
+    base_ref_unresolved: "the base ref could not be resolved",
+    default_ref_unresolved: "the default branch ref could not be resolved",
+    base_workflow_unreadable: "the workflow could not be read at the base ref",
+    default_workflow_unreadable: "the workflow could not be read at the default branch",
+    comparison_unavailable: "the comparison could not be completed",
+};
+/**
+ * Classify a base ref's copy of the reviewed workflow against the default
+ * branch's copy.
+ *
+ * A base ref that IS the default branch is `aligned` without comparing anything:
+ * it cannot be stale relative to itself, and short-circuiting keeps callers from
+ * paying for bytes they do not need.
+ */
+export function classifyClaudeReviewWorkflowDrift(input) {
+    const meta = {
+        baseRef: input.baseRef,
+        defaultRef: input.defaultRef,
+        workflowPath: input.workflowPath ?? CLAUDE_REVIEW_WORKFLOW_RELPATH,
+    };
+    if (input.defaultRef.trim().length === 0) {
+        return { ...meta, state: "unverified", reason: "default_branch_unknown" };
+    }
+    if (input.baseRef.trim().length === 0) {
+        return { ...meta, state: "unverified", reason: "base_ref_unresolved" };
+    }
+    if (input.baseRef === input.defaultRef) {
+        return { ...meta, state: "aligned" };
+    }
+    // Acquisition failures are inconclusive, never drift. The base side is checked
+    // first only so the reported reason names the ref the operator would act on.
+    if (!input.base.ok) {
+        return { ...meta, state: "unverified", reason: input.base.reason };
+    }
+    if (!input.default.ok) {
+        return { ...meta, state: "unverified", reason: input.default.reason };
+    }
+    const baseSha = computeGitBlobSha(input.base.content);
+    const defaultSha = computeGitBlobSha(input.default.content);
+    if (baseSha === defaultSha) {
+        return { ...meta, state: "aligned" };
+    }
+    return { ...meta, state: "drifted", baseSha, defaultSha };
+}
+/**
+ * Render the operator-facing diagnostic for a classification.
+ *
+ * Wording rules, all deliberate:
+ *
+ *   - Leads with a color-independent `WARNING:` / `INFO:` / `OK:` label, because
+ *     these lines land on `stderr`, in a plain-text doctor report, and in CI logs
+ *     where color is absent or stripped.
+ *   - Names the STALE BASE first. The original incident's investigation went
+ *     down the wrong path precisely because the diagnostic blamed the pull
+ *     request, so the subject of the sentence is the ref that is actually wrong.
+ *   - States the impact (`Claude review cannot run`) and the remedy (reconcile
+ *     the base with the default branch) in that order.
+ *   - Ends by saying work continues, so an advisory is never mistaken for a stop.
+ */
+export function formatClaudeReviewWorkflowDriftDiagnostic(classification) {
+    const { baseRef, defaultRef, workflowPath } = classification;
+    if (classification.state === "aligned") {
+        return `OK: '${baseRef}' matches '${defaultRef}' for ${workflowPath}.`;
+    }
+    if (classification.state === "unverified") {
+        return (`INFO: could not compare ${workflowPath} between '${baseRef}' and ` +
+            `'${defaultRef}' — ${UNAVAILABLE_REASON_TEXT[classification.reason]}. ` +
+            `This check is advisory and fails open; continuing.`);
+    }
+    return (`WARNING: base branch '${baseRef}' carries a stale ${workflowPath} ` +
+        `(it differs from the default branch '${defaultRef}'). Claude review cannot ` +
+        `run for pull requests based on it — the review action refuses to run and no ` +
+        `verdict is ever posted, so a conductor run parks at needs_human about an hour ` +
+        `later. Remedy: reconcile '${baseRef}' with '${defaultRef}' (merge it in, or ` +
+        `sync ${workflowPath} together with ` +
+        `tests/pytest/commands/test_claude_review_workflow_prompt.py, which carries the ` +
+        `protected-region byte baselines). Retrying the review cannot clear this. ` +
+        `Continuing; this advisory does not block your work.`);
+}
+/**
+ * Compact one-line detail for space-constrained surfaces (the `doctor`
+ * prerequisite line and the install-doctor section detail), where the full
+ * paragraph above would swamp the report. Same facts, same order, no color.
+ */
+export function summarizeClaudeReviewWorkflowDrift(classification) {
+    const { baseRef, defaultRef, workflowPath } = classification;
+    if (classification.state === "aligned") {
+        return `'${baseRef}' matches '${defaultRef}' for ${workflowPath}`;
+    }
+    if (classification.state === "unverified") {
+        return (`comparison unavailable (${classification.reason}) — advisory check failed open, ` +
+            `${workflowPath} lineage unknown`);
+    }
+    return (`WARNING: '${baseRef}' carries a stale ${workflowPath} (differs from ` +
+        `'${defaultRef}') — Claude review cannot run for pull requests based on it; ` +
+        `reconcile '${baseRef}' with '${defaultRef}'`);
+}
+/** Secret-free remediation sentence shared by the doctor and install-doctor surfaces. */
+export const CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION = `Reconcile the base branch with the repository default branch — merge the default ` +
+    `branch in, or sync ${CLAUDE_REVIEW_WORKFLOW_RELPATH} together with ` +
+    `tests/pytest/commands/test_claude_review_workflow_prompt.py. See ` +
+    `docs/claude/runbooks/claude-review-base-branch-drift.md.`;

package/build/claude-review-workflow.js

@@ -20,8 +20,18 @@
  * All filesystem access is injected so the module is unit-testable with
  * in-memory fakes.
  */
-/** Repo-relative path this module owns. It writes NOTHING else. */
-export const CLAUDE_REVIEW_WORKFLOW_RELPATH = ".github/workflows/claude-review.yml";
+import { CLAUDE_REVIEW_WORKFLOW_RELPATH } from "./claude-review-workflow-drift.js";
+/**
+ * Repo-relative path this module owns. It writes NOTHING else.
+ *
+ * BAPI-941: the constant now lives in `claude-review-workflow-drift.ts` — the
+ * leaf module that also owns the Git blob identity the rendered preflight below
+ * reproduces — and is re-exported here so every existing importer is unchanged.
+ * The import direction is renderer → drift and never reverses, so `base-ref.ts`,
+ * `doctor.ts`, and `conductor/install-doctor.ts` can depend on the drift module
+ * without pulling in the renderer or creating a cycle.
+ */
+export { CLAUDE_REVIEW_WORKFLOW_RELPATH };
 /** Thrown when a parameter fails validation. Carries no rendered YAML. */
 export class ClaudeReviewWorkflowValidationError extends Error {
     constructor(message) {
@@ -311,11 +321,28 @@ export function renderClaudeReviewWorkflow(params) {
      * reports that as a warning and exits SUCCESS, so without this preflight the
      * attempts would each publish nothing and the run would blame
      * `retries_exhausted_without_verdict`, naming a cause that did not occur.
+     *
+     * BAPI-941: the mismatch has two sources and they need different remedies. The
+     * obvious one is a pull request that edits this file. The quiet one is
+     * INHERITED drift — a pull request whose own commits never touch `.github/`
+     * still trips the guard when its BASE branch carries a stale copy, because the
+     * action compares against the DEFAULT branch, not the base. Long-lived release
+     * or `epic/**` branches go silently unreviewed that way for days. So resolve
+     * three identities (head, base ref, default branch) and attribute the mismatch
+     * to the ref that is actually stale; blaming the pull request for its base's
+     * staleness prints the wrong remedy to the wrong person.
+     *
+     * The Git blob identity built below is the same construction
+     * `computeGitBlobSha` performs in-process for the spawn-time and doctor
+     * probes — `blob <byte-length>\0` followed by the raw bytes, SHA-1'd. It is
+     * reproduced here rather than imported because this body executes inside
+     * GitHub Actions, not in this process.
      */
     const preflight = () => `      - name: Preflight the review action
         id: preflight
         env:
           DEFAULT_BRANCH: ${gh("github.event.repository.default_branch")}
+          BASE_REF: ${gh("github.event.pull_request.base.ref")}
         uses: actions/github-script@v9
         with:
           script: |
@@ -328,18 +355,26 @@ export function renderClaudeReviewWorkflow(params) {
             const localSha = crypto.createHash('sha1')
               .update(Buffer.concat([header, raw]))
               .digest('hex');
-            let remoteSha = '';
-            try {
-              const res = await github.rest.repos.getContent({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                path: '.github/workflows/claude-review.yml',
-                ref: String(process.env.DEFAULT_BRANCH || ''),
-              });
-              remoteSha = String(res.data.sha || '');
-            } catch (err) {
-              remoteSha = '';
-            }
+            const defaultBranch = String(process.env.DEFAULT_BRANCH || '');
+            const baseRef = String(process.env.BASE_REF || '');
+            // Never surfaces provider exception text: a failed lookup becomes an
+            // empty SHA, and every message below is assembled from refs and the
+            // workflow path only.
+            const shaAtRef = async (ref) => {
+              if (!ref) return '';
+              try {
+                const res = await github.rest.repos.getContent({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  path: '.github/workflows/claude-review.yml',
+                  ref,
+                });
+                return String(res.data.sha || '');
+              } catch (err) {
+                return '';
+              }
+            };
+            const remoteSha = await shaAtRef(defaultBranch);
             if (!remoteSha) {
               // Cannot prove a mismatch. Fail OPEN toward attempting the review: a
               // suppressed review that would have worked is worse than a wasted
@@ -352,11 +387,37 @@ export function renderClaudeReviewWorkflow(params) {
             if (localSha === remoteSha) {
               core.setOutput('action_runnable', 'true');
               core.setOutput('status', 'ok');
-            } else {
+              return;
+            }
+            const blockAsModified = () => {
               core.setOutput('action_runnable', 'false');
               core.setOutput('status', 'workflow_modified');
               core.warning('This pull request modifies the review workflow, so the review action will refuse to run against it. Suppressing all attempts; review this pull request by hand.');
+            };
+            // When the base ref IS the default branch the two comparisons are the
+            // same one, so the mismatch can only be the pull request's own edit.
+            if (baseRef === defaultBranch) {
+              blockAsModified();
+              return;
+            }
+            const baseSha = await shaAtRef(baseRef);
+            if (!baseSha) {
+              // The mismatch is real but cannot be attributed. Fail OPEN for the
+              // same reason as above: naming the wrong culprit prints the wrong
+              // remedy, and suppressing on an unproven attribution is worse.
+              core.setOutput('action_runnable', 'true');
+              core.setOutput('status', 'unverified');
+              core.info('This workflow differs from the default branch, but the base ref copy could not be read, so the mismatch cannot be attributed; proceeding.');
+              return;
+            }
+            if (localSha === baseSha) {
+              // head === base, base !== default: inherited, not authored.
+              core.setOutput('action_runnable', 'false');
+              core.setOutput('status', 'base_workflow_stale');
+              core.warning('Base branch ' + baseRef + ' carries a stale .github/workflows/claude-review.yml (it differs from ' + defaultBranch + '); this pull request did not modify the file and inherited the drift. The review action will refuse to run, so no verdict can be published. Reconcile the base branch ' + baseRef + ' with ' + defaultBranch + ' — retrying this run cannot clear it.');
+              return;
             }
+            blockAsModified();
 
 `;
     /** One paid review attempt: guard the head, review, then check for a verdict. */
@@ -565,7 +626,11 @@ ${attempt(3)}
             let reason;
             if (success) {
               reason = 'verdict_published';
-            } else if (env.PREFLIGHT_STATUS === 'workflow_modified') {
+            } else if (env.PREFLIGHT_STATUS === 'workflow_modified' || env.PREFLIGHT_STATUS === 'base_workflow_stale') {
+              // BAPI-941: both blocked preflight statuses map to the SAME terminal
+              // reason, ahead of every generic cause. \`base_workflow_stale\` is a
+              // new attribution, not a new terminal shape — the aggregate
+              // vocabulary is a documented contract with downstream readers.
               reason = 'review_action_blocked_by_workflow_modification';
             } else if (guards.includes('drift')) {
               reason = 'head_drift';