@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/executor/observation.js

@@ -53,6 +53,118 @@ export async function collectGitTelemetry(deps, worktreePath, baseBranch) {
     }
     return telemetry;
 }
+/** A full 40-character hex object name. */
+const FULL_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+/** Normalize a candidate SHA, or `null` when it is absent/malformed. */
+function normalizeSha(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return FULL_SHA_PATTERN.test(trimmed) ? trimmed.toLowerCase() : null;
+}
+/**
+ * Fail-CLOSED pre-spawn contract over already-collected telemetry (BAPI-731,
+ * WS-E). Pure: it shells out to nothing and reuses `collectGitTelemetry()`'s
+ * existing reads rather than adding new git invocations.
+ *
+ * THE DEGRADED-READ RULE IS THE POINT. `collectGitTelemetry()` degrades silently
+ * — a failed `status --porcelain` simply omits `dirty`, and a failed
+ * `rev-parse HEAD` omits `last_commit_sha`. For ordinary telemetry that is
+ * correct (an observability gap must never fail a worker). For a fail-closed
+ * assertion it is the opposite: an omitted field means "could not verify", and
+ * "could not verify" must never be reported as "verified clean". Both omissions
+ * therefore REFUSE.
+ *
+ * `expectedHeadSha` is optional because `resume` legitimately has no
+ * remote-derived expectation: its protocol auto-commits dirty state as a WIP
+ * checkpoint, so it is verified for cleanliness AFTER that checkpoint but is
+ * exempt from SHA equality. Every other path supplies one.
+ *
+ * Messages are fixed strings plus validated hex SHAs — never porcelain output, a
+ * filename, a worktree path, stderr, or raw exception text.
+ */
+export function evaluatePreSpawnGitVerification(telemetry, expectedHeadSha) {
+    if (typeof telemetry.dirty !== "boolean") {
+        return {
+            ok: false,
+            reason: "status-unverifiable",
+            message: "pre-spawn verification failed: the worktree's clean/dirty status could not be read, " +
+                "so cleanliness cannot be confirmed",
+        };
+    }
+    if (telemetry.dirty) {
+        return {
+            ok: false,
+            reason: "dirty",
+            message: "pre-spawn verification failed: the prepared worktree has uncommitted or untracked " +
+                "changes; refusing to spawn a worker that could commit unrelated leftover work",
+        };
+    }
+    const observedSha = normalizeSha(telemetry.last_commit_sha);
+    if (observedSha === null) {
+        return {
+            ok: false,
+            reason: "head-unverifiable",
+            message: "pre-spawn verification failed: the worktree's HEAD commit could not be read, " +
+                "so it cannot be confirmed to match the prepared commit",
+        };
+    }
+    // No expectation supplied (`resume`): cleanliness plus a readable HEAD is the
+    // whole contract.
+    if (expectedHeadSha === undefined) {
+        return { ok: true, observedSha };
+    }
+    const expected = normalizeSha(expectedHeadSha);
+    if (expected === null) {
+        // Never echo an unvalidated value into a message.
+        return {
+            ok: false,
+            reason: "head-unverifiable",
+            message: "pre-spawn verification failed: the expected commit supplied by worktree preparation " +
+                "is not a valid commit id",
+            observedSha,
+        };
+    }
+    if (expected !== observedSha) {
+        return {
+            ok: false,
+            reason: "head-mismatch",
+            message: `pre-spawn verification failed: the prepared worktree is at ${observedSha} but ` +
+                `preparation expected ${expected}`,
+            observedSha,
+        };
+    }
+    return { ok: true, observedSha };
+}
+/**
+ * Read the LOCAL remote-tracking marker for a branch (BAPI-731, WS-H).
+ *
+ * Reads `refs/remotes/origin/<branch>` from the local object store only. It
+ * deliberately issues NO network operation — no `fetch`, no `ls-remote`, no
+ * provider API — because this runs on the high-frequency telemetry path where a
+ * network stall would block the heartbeat loop and defeat the dead-man switch.
+ * A worker's own `git push` updates this ref locally, which is precisely the
+ * signal being sampled.
+ *
+ * Degrade-don't-throw, exactly like `collectGitTelemetry()`: any failure or
+ * malformed output yields `undefined` and never fails the job.
+ */
+export async function collectRemoteTrackingSha(deps, worktreePath, branch) {
+    try {
+        const result = await deps.runCommand("git", [
+            "-C",
+            worktreePath,
+            "rev-parse",
+            `refs/remotes/origin/${branch}^{commit}`,
+        ]);
+        if (result.exitCode !== 0)
+            return undefined;
+        return normalizeSha(result.stdout) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Tolerantly parse one Claude stream-json line for an advisory `phase_hint`.
  * Catches ALL parse/schema errors and never throws; returns `{}` when nothing
@@ -89,6 +201,8 @@ export function createObservationState(deps, options) {
     let git = {};
     const advisory = {};
     let exitCode;
+    let attemptStartSha;
+    let attemptEndSha;
     return {
         recordStdout(chunk) {
             advisory.last_stdout_at = new Date(deps.now()).toISOString();
@@ -106,6 +220,16 @@ export function createObservationState(deps, options) {
         setExitCode(code) {
             exitCode = code;
         },
+        setAttemptStartSha(sha) {
+            const normalized = normalizeSha(sha);
+            if (normalized)
+                attemptStartSha = normalized;
+        },
+        setAttemptEndSha(sha) {
+            const normalized = normalizeSha(sha);
+            if (normalized)
+                attemptEndSha = normalized;
+        },
         git() {
             return git;
         },
@@ -117,6 +241,12 @@ export function createObservationState(deps, options) {
                 residue.last_stdout_at = advisory.last_stdout_at;
             if (exitCode !== undefined)
                 residue.exit_code = exitCode;
+            // The attempt boundary pair is independent of `last_commit_sha`: it
+            // survives a degraded final sample rather than being overwritten by one.
+            if (attemptStartSha !== undefined)
+                residue.attempt_start_sha = attemptStartSha;
+            if (attemptEndSha !== undefined)
+                residue.attempt_end_sha = attemptEndSha;
             return residue;
         },
     };

package/build/executor/permissions.js

@@ -8,16 +8,37 @@
  * liveness never does. (Refusing to claim on `enforced:false` is a SEPARATE,
  * fatal preflight concern — see `preflight.ts`.)
  *
+ * BAPI-724: the worker model is now provisioned with default Bridge MCP access
+ * (see `../mcp-provisioning.js` wiring in `job-runner.ts`), so this module also
+ * denies direct reads of the user-scoped Bridge credential store
+ * (`~/.config/bridge/**`). MCP authentication stays available to the worker
+ * through the separately launched `mcp-invoke` shim process, which resolves the
+ * credential itself — the model process never reads it directly.
+ *
+ * BAPI-740/F2: worker-config isolation seeds a repo-scoped copy of that store
+ * INSIDE the per-job isolation directory (`bapi-conductor-claude-cfg-*` under the
+ * executor tmp root — see `worker-config-isolation.ts`), where the `~/.config`
+ * rule cannot reach it. A prefix glob denies model reads under any isolation
+ * directory so the seeded `credentials.json` gets the same shielding as the
+ * operator store. The shim still reads it: the shim is a separate process, not
+ * the model.
+ *
  * The Wave-1 probe on the target machine reports enforcement layer `settings-deny`
  * (claude 2.1.201), so plain `permissions.deny` is provisioned; the PreToolUse
  * fallback is available for CLIs where settings-deny is not enforced.
  */
+import path from "node:path";
 import { mergeClaudeSettingsWithCommandHook, provisionClaudeSettingsForWorktree, DEFAULT_PRE_TOOL_USE_MATCHER, } from "../claude-settings.js";
+import { ISOLATION_DIR_PREFIX } from "./worker-config-isolation.js";
 /**
  * The stable executor deny rules. Grammar mirrors the deny-enforcement probe's
  * `Bash(<cmd>:<args-glob>)` / `Read(<path-glob>)` form. Covers: reads under
- * ~/.ssh, ~/.aws, and keychain paths; force-push to the base branch; and
- * destructive `rm -rf` outside the worktree.
+ * ~/.ssh, ~/.aws, and keychain paths; the user-scoped Bridge credential store
+ * (BAPI-724 — the model is denied direct reads, while the separately launched
+ * `mcp-invoke` shim process still resolves it); the per-job isolation directory
+ * (BAPI-740/F2 — the seeded repo-scoped `credentials.json` lives there, outside
+ * the `~/.config` rule's reach); force-push to the base branch; and destructive
+ * `rm -rf` outside the worktree.
  */
 export function executorDenyRules(inputs) {
     return [
@@ -25,6 +46,11 @@ export function executorDenyRules(inputs) {
         "Read(~/.aws/**)",
         "Read(~/Library/Keychains/**)",
         "Read(/etc/shadow)",
+        "Read(~/.config/bridge/**)",
+        // Any path under any per-job isolation directory, wherever the executor's
+        // tmp root lives (`//` anchors at the filesystem root; the prefix constant
+        // is shared with `worker-config-isolation.ts` so they cannot drift).
+        `Read(//**/${ISOLATION_DIR_PREFIX}*/**)`,
         `Bash(git push:*--force*${inputs.baseBranch}*)`,
         "Bash(git push:*--force*)",
         "Bash(rm:*-rf /*)",
@@ -53,7 +79,80 @@ export function mergeExecutorDenySettings(existing, inputs) {
     return { ...existing, permissions };
 }
 /**
- * Provision the executor deny layer into `<worktree>/.claude/settings.local.json`.
+ * The exact line appended to the worktree's `.git/info/exclude` so a worker's
+ * `git add -A` cannot commit the executor-owned settings file.
+ */
+export const EXECUTOR_SETTINGS_EXCLUDE_LINE = ".claude/settings.local.json";
+/**
+ * Keep the executor-owned `.claude/settings.local.json` out of worker commits
+ * (BAPI-740/F2). Worker-config isolation redirects `XDG_CONFIG_HOME`, so the
+ * operator's global git excludes (`~/.config/git/ignore`) no longer apply inside
+ * a worker — empirically, a worker `git add -A` commits the deny-layer file this
+ * module just wrote. A per-worktree `.git/info/exclude` entry is invisible to
+ * the diff and travels with the gitdir, so it closes that without touching the
+ * worktree's tracked `.gitignore`.
+ *
+ * A linked worktree's `.git` is a FILE containing `gitdir: <path>` pointing at
+ * the main repository's per-worktree gitdir; that indirection is resolved rather
+ * than assuming a directory (`EISDIR` on the read identifies a real main-checkout
+ * `.git` directory). Idempotent: the line is appended once, never duplicated.
+ * Fail-open, matching the rest of this module: unresolvable git metadata is a
+ * silent skip, and an exclude-write failure returns a warning — never a block.
+ */
+async function provisionWorktreeSettingsExclude(worktreePath, deps) {
+    const gitPath = path.join(worktreePath, ".git");
+    let gitDir;
+    try {
+        const raw = await deps.readFile(gitPath);
+        const match = /^gitdir:\s*(.+?)\s*$/m.exec(raw);
+        if (!match) {
+            // A readable `.git` file with no gitdir pointer is not git metadata this
+            // function understands; do not guess at a location to write into.
+            return { ok: true };
+        }
+        const target = match[1];
+        gitDir = path.isAbsolute(target) ? target : path.resolve(worktreePath, target);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code === "EISDIR") {
+            // Main-checkout shape: `.git` is a real directory.
+            gitDir = gitPath;
+        }
+        else {
+            // No readable git metadata at all (e.g. ENOENT) — nothing to protect.
+            return { ok: true };
+        }
+    }
+    try {
+        const infoDir = path.join(gitDir, "info");
+        await deps.mkdir(infoDir, { recursive: true });
+        const excludePath = path.join(infoDir, "exclude");
+        let existing = "";
+        try {
+            existing = await deps.readFile(excludePath);
+        }
+        catch {
+            existing = "";
+        }
+        if (existing.split(/\r?\n/).includes(EXECUTOR_SETTINGS_EXCLUDE_LINE)) {
+            return { ok: true };
+        }
+        const prefix = existing.length === 0 || existing.endsWith("\n") ? existing : `${existing}\n`;
+        await deps.writeFile(excludePath, `${prefix}${EXECUTOR_SETTINGS_EXCLUDE_LINE}\n`);
+        return { ok: true };
+    }
+    catch {
+        return {
+            ok: false,
+            warning: "worktree git-exclude provisioning did not complete " +
+                `(${EXECUTOR_SETTINGS_EXCLUDE_LINE} may appear in worker commits); continuing fail-open`,
+        };
+    }
+}
+/**
+ * Provision the executor deny layer into `<worktree>/.claude/settings.local.json`,
+ * and shield that file from worker commits via `.git/info/exclude` (BAPI-740/F2).
  * Fails open: a malformed existing file is preserved (not clobbered) and I/O
  * errors return a warning — the caller still spawns the worker.
  */
@@ -70,10 +169,17 @@ export async function provisionExecutorDenyLayer(worktreePath, options, deps) {
         }
         return merged;
     }, deps);
-    if (result.ok)
+    // Independent of the settings write above: the exclude protects a file that
+    // may already exist from an earlier provisioning, so it runs even when the
+    // merge-write was refused or failed.
+    const exclude = await provisionWorktreeSettingsExclude(worktreePath, deps);
+    const warnings = [];
+    if (!result.ok) {
+        warnings.push(`deny-layer provisioning did not complete (${result.reason}); continuing fail-open`);
+    }
+    if (!exclude.ok)
+        warnings.push(exclude.warning);
+    if (warnings.length === 0)
         return { ok: true };
-    return {
-        ok: false,
-        warning: `deny-layer provisioning did not complete (${result.reason}); continuing fail-open`,
-    };
+    return { ok: false, warning: warnings.join("; ") };
 }

package/build/executor/preflight.js

@@ -14,8 +14,71 @@
  * allowed reuse surface — it does not pull the v1 event/ledger graph).
  */
 import { runDenyEnforcementPreflight } from "../conductor/deny-enforcement-preflight.js";
-import { resolveAllExecutorApiAccess } from "./credentials.js";
+import { DEFAULT_PROBE_TIMEOUT_MS } from "../agent-capabilities/types.js";
+import { evaluateClaudeMcpShadowingPolicy, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "../claude-user-config-doctor.js";
+import { resolveAllExecutorApiAccess, resolveBaseUrl, EXECUTOR_BASE_URL_REQUIRED_MESSAGE, } from "./credentials.js";
 const VERSION_DETAIL_MAX = 200;
+/**
+ * Environment override for the deny probe's headless timeout (BAPI-722).
+ *
+ * EXECUTOR-PROCESS CONFIGURATION ONLY. It is deliberately excluded from spawned
+ * worker environments by `isExecutorEnvKeyAllowed` — a worker has no deny probe to
+ * time out, and letting a job influence the executor's own safety-probe budget
+ * would be a privilege inversion.
+ */
+export const DENY_PROBE_TIMEOUT_ENV_KEY = "BAPI_CONDUCTOR_DENY_PROBE_TIMEOUT_MS";
+/**
+ * Accepted bounds for the resolved probe timeout. The lower bound keeps a
+ * fat-fingered `1` from turning every probe into an instant HANG (which is FATAL —
+ * the executor would refuse to claim forever); the upper bound keeps a typo from
+ * wedging the claim loop for hours. Anything outside them falls back to the
+ * established capability-probe default rather than being clamped, so a
+ * misconfiguration produces the known-good value instead of a silently different
+ * one the operator never chose.
+ */
+const DENY_PROBE_TIMEOUT_MIN_MS = 1_000;
+const DENY_PROBE_TIMEOUT_MAX_MS = 600_000;
+/**
+ * Resolve the deny probe's timeout from the environment, falling back to the
+ * established capability-probe default (`DEFAULT_PROBE_TIMEOUT_MS`).
+ *
+ * Strict: blank, non-numeric, non-integer, zero, negative, and out-of-range values
+ * all resolve to the default. The result is ALWAYS a finite positive number — never
+ * `undefined`, never `0`, never unbounded — because an unbounded deny probe is
+ * exactly the hang this timeout exists to prevent.
+ *
+ * The value itself is never logged alongside its surrounding environment.
+ */
+export function resolveDenyProbeTimeoutMs(env = {}) {
+    const raw = env[DENY_PROBE_TIMEOUT_ENV_KEY];
+    if (typeof raw !== "string" || raw.trim().length === 0)
+        return DEFAULT_PROBE_TIMEOUT_MS;
+    const parsed = Number(raw.trim());
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed))
+        return DEFAULT_PROBE_TIMEOUT_MS;
+    if (parsed < DENY_PROBE_TIMEOUT_MIN_MS || parsed > DENY_PROBE_TIMEOUT_MAX_MS) {
+        return DEFAULT_PROBE_TIMEOUT_MS;
+    }
+    return parsed;
+}
+/** True only for a result safe to reuse: genuinely enforced by a real layer. */
+function isCacheableDenyResult(result) {
+    return result.enforced === true && result.layer !== "none";
+}
+/** Create a fresh, empty executor-scoped deny-probe cache. */
+export function createDenyProbeCache() {
+    let cached;
+    return {
+        get: () => cached,
+        set: (result) => {
+            if (isCacheableDenyResult(result))
+                cached = result;
+        },
+        reset: () => {
+            cached = undefined;
+        },
+    };
+}
 function normalizeVersion(stdout, stderr) {
     return (stdout || stderr || "").trim().slice(0, VERSION_DETAIL_MAX);
 }
@@ -61,11 +124,20 @@ export async function collectExecutorPreflight(options, deps, seams = {}) {
     catch {
         fatalFindings.push("claude could not be probed");
     }
-    // --- Credentials for every configured repo ----------------------------
-    const access = await resolveAllExecutorApiAccess(options.repos, deps);
-    for (const a of access) {
-        if (!a.ok)
-            fatalFindings.push(`credential resolution failed for repo '${a.repoName}'`);
+    // --- Explicit base URL (fatal; never defaults to production, BAPI-676) ---
+    // Resolved before per-repo credentials so a missing URL reports ONCE rather
+    // than once per repo. The remaining probes still run and accumulate findings.
+    const baseUrlResult = resolveBaseUrl(deps.env, options.baseUrl);
+    if (!baseUrlResult.ok) {
+        fatalFindings.push(EXECUTOR_BASE_URL_REQUIRED_MESSAGE);
+    }
+    else {
+        // --- Credentials for every configured repo --------------------------
+        const access = await resolveAllExecutorApiAccess(options.repos, deps, baseUrlResult.baseUrl);
+        for (const a of access) {
+            if (!a.ok)
+                fatalFindings.push(`credential resolution failed for repo '${a.repoName}'`);
+        }
     }
     // --- Disk space (fatal when it cannot be verified) --------------------
     let diskFreeGb = null;
@@ -97,10 +169,26 @@ export async function collectExecutorPreflight(options, deps, seams = {}) {
         warnings.push("local `gh` is unavailable/unauthenticated; local merges would be degraded");
     }
     // --- Deny-layer enforcement (binding fatal contract) ------------------
+    // BAPI-722: only THIS probe is cached across claim cycles. Every probe above —
+    // tooling, credentials, disk, gh — still runs on each collection, because each of
+    // them can genuinely change between polls (a binary removed, a credential
+    // rotated, a disk filled). Deny-layer enforcement is a property of the machine's
+    // static settings; once verified it does not spontaneously unverify.
     let denyEnforced = false;
     try {
-        const denyProbe = seams.runDenyPreflight ?? runDenyEnforcementPreflight;
-        const deny = await denyProbe();
+        const cache = seams.bypassDenyProbeCache === true ? undefined : seams.denyProbeCache;
+        const cachedDeny = cache?.get();
+        let deny;
+        if (cachedDeny !== undefined) {
+            deny = cachedDeny;
+        }
+        else {
+            const denyProbe = seams.runDenyPreflight ?? runDenyEnforcementPreflight;
+            deny = await denyProbe({ timeoutMs: resolveDenyProbeTimeoutMs(deps.env) });
+            // `set` itself refuses anything that is not a genuine success, so a failure
+            // cannot become sticky even if this call site were later moved.
+            seams.denyProbeCache?.set(deny);
+        }
         denyEnforced = deny.enforced === true;
         if (!deny.enforced) {
             fatalFindings.push(`deny-layer enforcement not verified (enforced=false, layer=${deny.layer}); refusing to claim`);
@@ -114,6 +202,37 @@ export async function collectExecutorPreflight(options, deps, seams = {}) {
     catch {
         fatalFindings.push("deny-layer enforcement probe failed; refusing to claim");
     }
+    // --- Claude user-config MCP shadowing (fatal by default, BAPI-727) ----
+    // REFUSAL BY DEFAULT is the whole point. A `bridge-api` entry in the machine's
+    // ~/.claude.json was observed to win over a linked worktree's provisioned
+    // `.mcp.json`, so the worker silently talks to whatever endpoint that entry
+    // names instead of the one the executor provisioned — a production-integrity
+    // failure that produces no error, only wrong work. A warning-only check would
+    // preserve exactly that silence; the explicit
+    // BAPI_CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING override is the deliberate operator
+    // escape hatch for the cases where the collision is known and intended.
+    //
+    // Inconclusive states (unreadable/malformed config) are warnings, never fatal:
+    // "could not look" must not become "found a collision".
+    try {
+        const inspect = seams.inspectClaudeUserConfig ?? inspectClaudeUserConfigForMcpShadowing;
+        const inspection = await inspect({
+            claudeConfigPath: resolveClaudeUserConfigPath(deps.homedir(), deps.platform),
+            platform: deps.platform,
+            cwd: deps.cwd,
+            // The executor's own checkout is the main repository. Preflight runs
+            // before any job, so there is no prepared worktree to name here — the
+            // per-job check in `job-runner.ts` covers that scope.
+            mainRepositoryPath: deps.cwd,
+        }, { readFile: deps.readFile });
+        const policy = evaluateClaudeMcpShadowingPolicy(inspection, deps.env);
+        warnings.push(...policy.warnings);
+        if (!policy.ok)
+            fatalFindings.push(...policy.refusals);
+    }
+    catch {
+        warnings.push("Claude user-config MCP shadowing check did not complete; could not verify worker MCP integrity");
+    }
     return {
         ok: fatalFindings.length === 0,
         fatalFindings,

package/build/executor/prompt-spec.js

@@ -26,6 +26,20 @@ const SUPPORTED_PROMPT_SPEC_VERSION = 1;
 const GIT_LOG_MAX_CHARS = 8_000;
 /** Explicit "no prior revise reasons" value — never an empty string. */
 const REVISE_REASONS_NONE = "(none — this is the first review of the ticket spec)";
+/**
+ * Explicit "no related-ticket context" value (BAPI-699) — never an empty string.
+ *
+ * The server normally renders this section itself (availability header + one
+ * record block per related ticket), so this fallback only fires when a payload
+ * reaches a placeholder-aware executor without a `related_context` field at all
+ * — e.g. a job enqueued by an older server revision. Substituting an empty
+ * string there would hand the reviewer a blank section that reads exactly like
+ * "this ticket has no neighbors", so the fallback states the blindness instead.
+ */
+const RELATED_CONTEXT_NONE = "(no related-ticket context was supplied with this job. This review is " +
+    "PARTIALLY BLIND to the surrounding tickets: do NOT conclude that the ticket " +
+    "has no related tickets, no dependencies, and no already-merged neighbors — " +
+    "that information was simply not provided.)";
 /** The `git log` argv used to resolve `{{GIT_LOG}}` (list-based, never shelled). */
 const GIT_LOG_ARGS = ["log", "--oneline", "--decorate", "--max-count=50"];
 /**
@@ -39,7 +53,21 @@ const SUPPORTED_PLACEHOLDERS = new Set([
     "WORK_BRANCH",
     "GIT_LOG",
     "REVISE_REASONS",
+    "RELATED_CONTEXT",
+    "SPEC_CITATION_FRESHNESS_WARNING",
 ]);
+/**
+ * Explicit "no stale-citation advisory" value (BAPI-722) — never an empty string.
+ *
+ * Unlike `RELATED_CONTEXT`, absence here is the COMMON and entirely healthy case:
+ * most tickets have no predecessor that merged after their spec was written, so the
+ * server omits the field. The substituted text therefore states that plainly rather
+ * than warning about blindness — a reviewer must not read "no advisory" as "the
+ * server could not tell", which would push them toward re-verifying every citation
+ * on every review.
+ */
+const SPEC_CITATION_FRESHNESS_NONE = "(none — no dependency of this ticket merged after this ticket's " +
+    "specification snapshot was taken.)";
 function promptContractError(message) {
     return new ExecutorNamedError(PROMPT_CONTRACT_ERROR, message);
 }
@@ -190,6 +218,29 @@ export async function buildPromptSpecPlaceholderValues(job, spec, context) {
                 values.REVISE_REASONS = formatReviseReasons(payload.reasons);
                 break;
             }
+            case "RELATED_CONTEXT": {
+                // The server renders this section (availability header, per-entry
+                // record blocks, its own bounded trim marker) and records the SHA-256
+                // of EXACTLY the text it rendered. So the value is substituted VERBATIM
+                // — no `.trim()`, no re-wrapping, no re-bounding — otherwise the
+                // recorded display hash would stop describing what the reviewer read.
+                values.RELATED_CONTEXT = isNonBlankString(payload.related_context)
+                    ? payload.related_context
+                    : RELATED_CONTEXT_NONE;
+                break;
+            }
+            case "SPEC_CITATION_FRESHNESS_WARNING": {
+                // OPTIONAL by contract (BAPI-722): an absent field is the normal case and
+                // resolves to the explicit "none" text, NEVER a thrown contract error and
+                // never an empty substitution. This deliberately does not weaken
+                // {{TICKET_SPEC}}, which stays required — a review with no spec is not a
+                // review, whereas a review with no advisory is simply the usual review.
+                // Substituted verbatim: the server composed this text and bounded it.
+                values.SPEC_CITATION_FRESHNESS_WARNING = isNonBlankString(payload.spec_citation_freshness_warning)
+                    ? payload.spec_citation_freshness_warning
+                    : SPEC_CITATION_FRESHNESS_NONE;
+                break;
+            }
         }
     }
     return values;

package/build/executor/runner.js

@@ -6,7 +6,7 @@
  * preflight finding. `once` mode performs one preflight/claim cycle and returns
  * after all active jobs finish. Depends on NO v1 conductor event/ledger module.
  */
-import { collectExecutorPreflight, buildClaimManifest } from "./preflight.js";
+import { collectExecutorPreflight, buildClaimManifest, createDenyProbeCache, } from "./preflight.js";
 import { runClaimedJob } from "./job-runner.js";
 import { sweepExecutorWorktrees } from "./worktree-gc.js";
 /**
@@ -28,6 +28,19 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             platform: deps.platform,
         }));
     const active = new Map();
+    // BAPI-722: ONE deny-probe cache per `runExecutor` invocation, created OUTSIDE
+    // the claim loop below — that scope is the whole feature. A cache created inside
+    // the loop would be discarded every cycle and re-probe exactly as before; a
+    // module-level cache would leak across invocations and survive a deliberate
+    // restart, which is precisely the escape hatch an operator fixing a broken deny
+    // layer needs. Process lifetime is the correct boundary.
+    //
+    // An injected `preflightSeams.denyProbeCache` (or `bypassDenyProbeCache`) wins,
+    // so a test can force deterministic fresh probes.
+    const preflightSeams = {
+        denyProbeCache: createDenyProbeCache(),
+        ...(seams.preflightSeams ?? {}),
+    };
     /**
      * Run the conservative worktree GC sweep ONLY while the runner owns no active
      * job worktree. Failures are logged to stderr and never abort claiming
@@ -60,7 +73,15 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
         active.set(job.id, promise);
     }
     for (;;) {
-        const report = await collectPreflight(options, deps, seams.preflightSeams ?? {});
+        const report = await collectPreflight(options, deps, preflightSeams);
+        // BAPI-727: preflight warnings were previously collected but never emitted, so
+        // a non-fatal finding — an overridden MCP-shadowing collision, an unreadable
+        // ~/.claude.json — was invisible to the operator. Emit them before the claim
+        // decision; this only logs and never changes the existing `!report.ok`
+        // claim-skipping behavior below.
+        for (const warning of report.warnings) {
+            deps.errorLog(`executor preflight warning: ${warning}`);
+        }
         if (!report.ok) {
             deps.errorLog(`executor preflight refused claiming: ${report.fatalFindings.join("; ")}`);
         }