@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/build/epic-implementer-claude-hook-bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 import path from"node:path";import{fileURLToPath}from"node:url";import{spawnSync}from"node:child_process";import{readFileSync}from"node:fs";var CONDUCTOR_HOOK_EMIT_FAILED_WARNING="Warning: conductor hook emit failed.";function resolveClaudeHookEventName(payload){if(payload===null||typeof payload!="object"||Array.isArray(payload))return null;let record=payload,candidates=["hook_event_name","hookEventName","event_name","event"];for(let key of candidates){let value=record[key];if(typeof value=="string"&&value.trim().length>0)return value.trim()}return null}function mapClaudeHookEventToSemanticType(eventName){switch(eventName){case"SessionStart":return"run.started";case"SessionEnd":return"run.stopped";case"Stop":return null;case"SubagentStop":return null;case"Notification":return"agent.notification";case"PreToolUse":return"tool.intent";default:return null}}var REQUIRED_IDENTITY_ENV=["BAPI_EPIC_IMPLEMENTER_RUN_ID","BAPI_EPIC_IMPLEMENTER_WORKER_ID","BAPI_EPIC_IMPLEMENTER_TICKET_KEY","BAPI_EPIC_IMPLEMENTER_WORKTREE_PATH"];function nonEmpty(value){return typeof value=="string"&&value.trim().length>0}function buildClaudeHookConductorEvent(payload,env){let eventName=resolveClaudeHookEventName(payload),type=mapClaudeHookEventToSemanticType(eventName);if(type===null||env.BAPI_EPIC_IMPLEMENTER_ENABLED!=="1")return null;for(let key of REQUIRED_IDENTITY_ENV)if(!nonEmpty(env[key]))return null;let ticketKey=env.BAPI_EPIC_IMPLEMENTER_TICKET_KEY.trim(),worktreePath=env.BAPI_EPIC_IMPLEMENTER_WORKTREE_PATH.trim(),details={ticket_key:ticketKey,worktree_path:worktreePath};nonEmpty(env.BAPI_EPIC_IMPLEMENTER_REPO_NAME)&&(details.repo=env.BAPI_EPIC_IMPLEMENTER_REPO_NAME.trim());let raw=payload!==null&&typeof payload=="object"&&!Array.isArray(payload)?payload:{payload};return{source:"claude-code",type,subject:ticketKey,run_id:env.BAPI_EPIC_IMPLEMENTER_RUN_ID.trim(),worker_id:env.BAPI_EPIC_IMPLEMENTER_WORKER_ID.trim(),producer:"claude-code-hook",observed_via:"claude-code-hook",data:{details,raw}}}function buildConductorEmitEventArgs(event){let args=["--type",event.type,"--source",event.source];return nonEmpty(event.subject??void 0)&&args.push("--subject",event.subject),nonEmpty(event.run_id??void 0)&&args.push("--run-id",event.run_id),nonEmpty(event.worker_id??void 0)&&args.push("--worker-id",event.worker_id),nonEmpty(event.producer??void 0)&&args.push("--producer",event.producer),nonEmpty(event.observed_via??void 0)&&args.push("--observed-via",event.observed_via),args.push("--data-json-stdin","--json"),args}function resolveConductorEmitCommand(env,emitArgs){let cliFile=env.BAPI_EPIC_IMPLEMENTER_CLI_FILE;return nonEmpty(cliFile)?{command:process.execPath,args:[cliFile.trim(),"emit-event",...emitArgs]}:{command:nonEmpty(env.BAPI_EPIC_IMPLEMENTER_BIN)?env.BAPI_EPIC_IMPLEMENTER_BIN.trim():"epic-implementer",args:["emit-event",...emitArgs]}}var defaultConductorSpawn=(command,args,input)=>{let result=spawnSync(command,args,{input,encoding:"utf-8",shell:!1});return{status:result.status,error:result.error}};function emitClaudeHookEventWithConductorCli(event,deps={}){let env=deps.env??process.env,spawn=deps.spawn??defaultConductorSpawn,emitArgs=buildConductorEmitEventArgs(event),{command,args}=resolveConductorEmitCommand(env,emitArgs),stdinPayload=JSON.stringify(event.data??{});try{let result=spawn(command,args,stdinPayload);return result.error?!1:result.status===0}catch{return!1}}function runClaudeConductorHookCli(deps={}){let env=deps.env??process.env,readStdin=deps.readStdin??(()=>readStdinSync()),warn=deps.warn??(m=>process.stderr.write(`${m}
-`)),payload;try{let raw=readStdin();payload=JSON.parse(raw)}catch{return warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}let event;try{event=buildClaudeHookConductorEvent(payload,env)}catch{return warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}return event===null||emitClaudeHookEventWithConductorCli(event,{env,spawn:deps.spawn})||warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}function readStdinSync(){return readFileSync(0,"utf-8")}var LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX="BAPI_CONDUCTOR_",EPIC_IMPLEMENTER_ENV_PREFIX="BAPI_EPIC_IMPLEMENTER_",LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV="CONDUCTOR_NODE_PATH",EPIC_IMPLEMENTER_NODE_PATH_ENV="EPIC_IMPLEMENTER_NODE_PATH",renamed=suffix=>[`${LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX}${suffix}`,{kind:"renamed",successor:`${EPIC_IMPLEMENTER_ENV_PREFIX}${suffix}`}],RENAMED_SUFFIXES=["ALLOW_LIVE_SOURCE_DISPATCH","BIN","BUSY_TIMEOUT_MS","CLI_FILE","DEAD_AFTER_MS","DECLARED_TOUCHED_FILES_JSON","DENY_PROBE_TIMEOUT_MS","DISPATCH_DRY_RUN","ENABLE_PRE_TOOL_USE","ENABLED","EPIC_KEY","EPIC_RUN_ID","ESCALATION_COOLDOWN_MS","GATE_NAME","GLOBAL_TIMEOUT_MS","HOOK_COMMAND","LIVE_SOURCE_PATH","LIVENESS_STALLED_AFTER_MS","MESSAGE_COOLDOWN_MS","PLAN_VERSION","QUIET_AFTER_MS","REPO_NAME","RETENTION_DAYS","RETENTION_MAX_ROWS","RUN_ID","STALL_ACTIVE_MS","STALL_BLOCKED_MS","STALL_CANDIDATE_DONE_MS","STALL_NOT_STARTED_MS","STALL_STALLED_MS","STALL_UNKNOWN_MS","STALL_VERIFYING_MS","SUPERVISOR_MODE","SUPERVISOR_POLL_LIMIT","TICKET_KEY","WAKE_INTERVAL_MS","WORKER_ID","WORKTREE_PATH"],LEGACY_EPIC_IMPLEMENTER_ENV_MAPPINGS=new Map([...RENAMED_SUFFIXES.map(renamed),[`${LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX}ALLOW_CLAUDE_MCP_SHADOWING`,{kind:"retired"}],[LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV,{kind:"renamed",successor:EPIC_IMPLEMENTER_NODE_PATH_ENV}]]);function isLegacyEpicImplementerEnvKey(key){return key.startsWith(LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX)||key===LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV}function findLegacyEpicImplementerEnv(env){return Object.keys(env).filter(isLegacyEpicImplementerEnvKey).sort((a,b)=>a<b?-1:a>b?1:0).map(key=>({key,mapping:LEGACY_EPIC_IMPLEMENTER_ENV_MAPPINGS.get(key)??null}))}var LEGACY_EPIC_IMPLEMENTER_ENV_ERROR_HEADER="Error: legacy Conductor environment variables are set. They were renamed to the Epic Implementer names and are no longer read. Update or remove each one, then retry:";function describeFinding(finding){let{key,mapping}=finding;return mapping===null?`  ${key}: unknown legacy setting. If it is still a current setting, rename the ${LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX} prefix to ${EPIC_IMPLEMENTER_ENV_PREFIX}; otherwise remove it.`:mapping.kind==="retired"?`  ${key}: retired with no replacement. Remove it.`:`  ${key} -> ${mapping.successor}`}function formatLegacyEpicImplementerEnvError(findings){return[LEGACY_EPIC_IMPLEMENTER_ENV_ERROR_HEADER,...findings.map(describeFinding)].join(`
+`)),payload;try{let raw=readStdin();payload=JSON.parse(raw)}catch{return warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}let event;try{event=buildClaudeHookConductorEvent(payload,env)}catch{return warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}return event===null||emitClaudeHookEventWithConductorCli(event,{env,spawn:deps.spawn})||warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}function readStdinSync(){return readFileSync(0,"utf-8")}var LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX="BAPI_CONDUCTOR_",EPIC_IMPLEMENTER_ENV_PREFIX="BAPI_EPIC_IMPLEMENTER_",LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV="CONDUCTOR_NODE_PATH",EPIC_IMPLEMENTER_NODE_PATH_ENV="EPIC_IMPLEMENTER_NODE_PATH",renamed=suffix=>[`${LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX}${suffix}`,{kind:"renamed",successor:`${EPIC_IMPLEMENTER_ENV_PREFIX}${suffix}`}],RENAMED_SUFFIXES=["ALLOW_LIVE_SOURCE_DISPATCH","BIN","BUSY_TIMEOUT_MS","CLI_FILE","DEAD_AFTER_MS","DECLARED_TOUCHED_FILES_JSON","DENY_PROBE_TIMEOUT_MS","DISPATCH_DRY_RUN","ENABLE_PRE_TOOL_USE","ENABLED","EPIC_KEY","EPIC_RUN_ID","ESCALATION_COOLDOWN_MS","GATE_NAME","GLOBAL_TIMEOUT_MS","HOOK_COMMAND","LIVE_SOURCE_PATH","LIVENESS_STALLED_AFTER_MS","MESSAGE_COOLDOWN_MS","PLAN_VERSION","QUIET_AFTER_MS","REPO_NAME","RETENTION_DAYS","RETENTION_MAX_ROWS","RUN_ID","STALL_ACTIVE_MS","STALL_BLOCKED_MS","STALL_CANDIDATE_DONE_MS","STALL_NOT_STARTED_MS","STALL_STALLED_MS","STALL_UNKNOWN_MS","STALL_VERIFYING_MS","SUPERVISOR_MODE","SUPERVISOR_POLL_LIMIT","TICKET_KEY","WAKE_INTERVAL_MS","WORKER_ID","WORKTREE_PATH"],LEGACY_EPIC_IMPLEMENTER_ENV_MAPPINGS=new Map([...RENAMED_SUFFIXES.map(renamed),[`${LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX}ALLOW_CLAUDE_MCP_SHADOWING`,{kind:"retired"}],[LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV,{kind:"renamed",successor:EPIC_IMPLEMENTER_NODE_PATH_ENV}],["CONDUCTOR_DEAD_MAN_ONLY",{kind:"renamed",successor:"EPIC_IMPLEMENTER_DEAD_MAN_ONLY"}],["CONDUCTOR_DEADMAN_CHANNEL_TYPE",{kind:"renamed",successor:"EPIC_IMPLEMENTER_DEADMAN_CHANNEL_TYPE"}],["CONDUCTOR_DEADMAN_DESTINATION_REF",{kind:"renamed",successor:"EPIC_IMPLEMENTER_DEADMAN_DESTINATION_REF"}]]);function isLegacyEpicImplementerEnvKey(key){return key.startsWith(LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX)||key===LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV||key==="CONDUCTOR_DEAD_MAN_ONLY"||key==="CONDUCTOR_DEADMAN_CHANNEL_TYPE"||key==="CONDUCTOR_DEADMAN_DESTINATION_REF"}function findLegacyEpicImplementerEnv(env){return Object.keys(env).filter(isLegacyEpicImplementerEnvKey).sort((a,b)=>a<b?-1:a>b?1:0).map(key=>({key,mapping:LEGACY_EPIC_IMPLEMENTER_ENV_MAPPINGS.get(key)??null}))}var LEGACY_EPIC_IMPLEMENTER_ENV_ERROR_HEADER="Error: legacy Conductor environment variables are set. They were renamed to the Epic Implementer names and are no longer read. Update or remove each one, then retry:";function describeFinding(finding){let{key,mapping}=finding;return mapping===null?`  ${key}: unknown legacy setting. If it is still a current setting, rename the ${LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX} prefix to ${EPIC_IMPLEMENTER_ENV_PREFIX}; otherwise remove it.`:mapping.kind==="retired"?`  ${key}: retired with no replacement. Remove it.`:`  ${key} -> ${mapping.successor}`}function formatLegacyEpicImplementerEnvError(findings){return[LEGACY_EPIC_IMPLEMENTER_ENV_ERROR_HEADER,...findings.map(describeFinding)].join(`
 `)+`
 `}function runLegacyEpicImplementerEnvPreflight(env,writeStderr){let findings=findLegacyEpicImplementerEnv(env);return findings.length===0?0:(writeStderr(formatLegacyEpicImplementerEnvError(findings)),1)}function runEpicImplementerClaudeHookBin(deps={}){let handler=deps.handler??runClaudeConductorHookCli,exit=deps.exit??process.exit.bind(process),writeStderr=deps.writeStderr??(chunk=>process.stderr.write(chunk));if(runLegacyEpicImplementerEnvPreflight(deps.env??process.env,writeStderr)!==0){exit(0);return}let exitCode=0;try{exitCode=handler()}catch{exitCode=0}exit(exitCode)}var invokedDirectly=process.argv[1]!==void 0&&path.resolve(process.argv[1])===fileURLToPath(import.meta.url);invokedDirectly&&runEpicImplementerClaudeHookBin();export{runEpicImplementerClaudeHookBin};

package/build/epic-implementer-env.js

@@ -14,22 +14,25 @@
  * any side effect, and refuses to start when an old name is present.
  *
  * Contract:
- *   - Detection is prefix-based: ANY key starting with `BAPI_CONDUCTOR_` is
- *     rejected, whether or not the table below knows it. `CONDUCTOR_NODE_PATH`
- *     is rejected by exact name (it has no `BAPI_` prefix).
+ *   - Detection is prefix-based for the `BAPI_CONDUCTOR_*` family: ANY key with
+ *     that prefix is rejected, whether or not the table below knows it.
+ *     `CONDUCTOR_NODE_PATH` and the three dead-man names below are rejected by
+ *     EXACT NAME only — none of them has a `BAPI_` prefix, and no `^CONDUCTOR_`
+ *     prefix rule exists or is ever added, so unrelated `CONDUCTOR`-containing
+ *     tokens (`CONDUCTOR_FETCH_TIMEOUT_MS`, `BRIDGE_CONDUCTOR_HOOK_START`,
+ *     `CURRENT_CONDUCTOR_SCHEMA_VERSION`) are never checked.
  *   - A key is rejected on presence alone, whatever its value (including empty).
  *   - All offending keys are reported in one message, sorted by code point.
  *   - Diagnostics carry key names only. An env value is never read into the
  *     findings, so it can never be printed — these variables can hold secrets.
  *   - The env is injectable, so tests never mutate the real process environment.
  *
- * This module is the ONLY non-test source file allowed to spell an old name.
- * Other modules import the prefix and node-path constants from here.
- *
- * Out of scope: the Python dead-man variables (`CONDUCTOR_DEAD_MAN_ONLY`,
- * `CONDUCTOR_DEADMAN_*`) keep their own exact-name contract (BAPI-1231), and
- * non-env tokens such as `BRIDGE_CONDUCTOR_HOOK_START` or
- * `CURRENT_CONDUCTOR_SCHEMA_VERSION` are never checked.
+ * This module is the ONLY non-test source file allowed to spell an old name —
+ * including the three dead-man names below, which are otherwise Python's own
+ * exact-name contract (BAPI-1231, `api/library/epic_implementer/legacy_env_guard.py`).
+ * Sharing the mapping here (BAPI-1237) lets one plane preflight check cover the
+ * TypeScript-side entry points too, instead of leaving them enforced only at
+ * Python worker boot.
  */
 /** Legacy env-var prefix. Any key with this prefix is refused. */
 export const LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX = "BAPI_CONDUCTOR_";
@@ -51,6 +54,11 @@ const renamed = (suffix) => [
  * retired `LLM_*` names (their literals are forbidden in production source by
  * `supervisor-retired-judgment.static.test.ts`), and test-only sentinels. All of
  * those still fall through to the generic prefix pointer.
+ *
+ * These 38 prefix-derived suffixes are distinct from the three BAPI-1237
+ * exact-name dead-man entries added directly to
+ * {@link LEGACY_EPIC_IMPLEMENTER_ENV_MAPPINGS} below: the dead-man names carry no
+ * `BAPI_CONDUCTOR_` prefix at all, so they cannot be expressed as a suffix here.
  */
 const RENAMED_SUFFIXES = [
     "ALLOW_LIVE_SOURCE_DISPATCH",
@@ -93,9 +101,12 @@ const RENAMED_SUFFIXES = [
     "WORKTREE_PATH",
 ];
 /**
- * Old name -> resolution. Exactly 40 keys: the 38 renamed names above, the
- * retired shadowing override (inert since BAPI-790; this supersedes that
- * ticket's "no error" promise), and the exact-name node-path variable.
+ * Old name -> resolution. Exactly 43 keys: the 38 `BAPI_CONDUCTOR_*`
+ * prefix-derived renamed names above, the retired shadowing override (inert
+ * since BAPI-790; this supersedes that ticket's "no error" promise), the
+ * exact-name node-path variable, and the three BAPI-1237 exact-name dead-man
+ * entries shared with the Python guard's `LEGACY_DEADMAN_ENV_RENAMES`
+ * (`api/library/epic_implementer/legacy_env_guard.py`).
  */
 export const LEGACY_EPIC_IMPLEMENTER_ENV_MAPPINGS = new Map([
     ...RENAMED_SUFFIXES.map(renamed),
@@ -104,10 +115,28 @@ export const LEGACY_EPIC_IMPLEMENTER_ENV_MAPPINGS = new Map([
         LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV,
         { kind: "renamed", successor: EPIC_IMPLEMENTER_NODE_PATH_ENV },
     ],
+    // BAPI-1237 — the three Python dead-man names (BAPI-1231), added here so
+    // this shared table is the single cross-runtime source of truth. Exact-name
+    // only, like CONDUCTOR_NODE_PATH above: none of these has a BAPI_ prefix.
+    ["CONDUCTOR_DEAD_MAN_ONLY", { kind: "renamed", successor: "EPIC_IMPLEMENTER_DEAD_MAN_ONLY" }],
+    [
+        "CONDUCTOR_DEADMAN_CHANNEL_TYPE",
+        { kind: "renamed", successor: "EPIC_IMPLEMENTER_DEADMAN_CHANNEL_TYPE" },
+    ],
+    [
+        "CONDUCTOR_DEADMAN_DESTINATION_REF",
+        { kind: "renamed", successor: "EPIC_IMPLEMENTER_DEADMAN_DESTINATION_REF" },
+    ],
 ]);
 /** True when `key` is a legacy env name this guard refuses. */
 export function isLegacyEpicImplementerEnvKey(key) {
-    return key.startsWith(LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX) || key === LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV;
+    return (key.startsWith(LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX) ||
+        key === LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV ||
+        // BAPI-1237 — exact-name only, like CONDUCTOR_NODE_PATH above. No
+        // `^CONDUCTOR_` prefix rule is introduced by these three comparisons.
+        key === "CONDUCTOR_DEAD_MAN_ONLY" ||
+        key === "CONDUCTOR_DEADMAN_CHANNEL_TYPE" ||
+        key === "CONDUCTOR_DEADMAN_DESTINATION_REF");
 }
 /**
  * Pure finder: env in, sorted findings out. Reads keys only, so a key is found

package/build/epic-integration-pr.js

@@ -20,7 +20,7 @@ export const EPIC_INTEGRATION_PR_READ_TIMEOUT_MS = 5_000;
 export const EPIC_INTEGRATION_PR_WRITE_TIMEOUT_MS = 20_000;
 /** Bounded result count for the existence probe. */
 const LIST_LIMIT = 20;
-const PR_LIST_JSON_FIELDS = "number,headRefName,baseRefName,isDraft";
+const PR_LIST_JSON_FIELDS = "number,headRefName,baseRefName,isDraft,headRefOid";
 /**
  * `epic/<KEY>` prefix a child PR's base branch carries under BAPI-949/BAPI-950.
  * Exported (BAPI-1010) so every call site that derives an epic key from a base
@@ -40,6 +40,9 @@ export const EPIC_INTEGRATION_PR_COMMANDS = [
     // "executor merge" so the generated PR body and diagnostics never mislabel
     // a done-state readiness request as a ticket merge enrichment.
     "executor wind-down",
+    // BAPI-1259: a durable `mark_ready` integration action performed by a local or
+    // repo-wide executor under explicitly configured customer authority.
+    "executor integration",
 ];
 /** Only the sanctioned safe fields. Never raw command output. */
 export function formatEpicIntegrationPullRequestOutcome(outcome) {
@@ -69,6 +72,10 @@ export function buildEpicIntegrationPullRequestBody(epicKey, command) {
         "Only a human merges an epic integration branch — the conductor never merges it.",
     ].join("\n");
 }
+/** `--repo owner/name` when an explicit repository is bound, else nothing. */
+function repoArgs(repo) {
+    return repo !== undefined ? ["--repo", repo] : [];
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -100,9 +107,16 @@ async function classifyGhUnavailable(gh, cwd) {
  * (non-zero exit, unparseable output, a non-array shape, an item with an
  * invalid number, or a record whose head/base do not match) is `unavailable`,
  * never treated as absence.
+ *
+ * BAPI-1259: the probe is also CONCLUSIVE only about exactly one PR. More than
+ * one matching record is `probe_ambiguous`, and a page that fills the whole
+ * limit is `probe_inconclusive` (there may be more records than it shows) —
+ * the old "first matching record wins" rule could bind readiness to an
+ * arbitrary pull request.
  */
-async function probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd) {
+async function probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd, repo) {
     const args = [
+        ...repoArgs(repo),
         "pr",
         "list",
         "--state",
@@ -139,6 +153,11 @@ async function probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd) {
     if (parsed.length === 0) {
         return { kind: "absent" };
     }
+    if (parsed.length >= LIST_LIMIT) {
+        // A saturated page may be hiding more records; nothing here is conclusive.
+        return { kind: "unavailable", reason: "probe_inconclusive" };
+    }
+    const matches = [];
     for (const item of parsed) {
         if (!isRecord(item))
             continue;
@@ -152,9 +171,17 @@ async function probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd) {
             head === epicBranch &&
             base === baseBranch &&
             typeof isDraft === "boolean") {
-            return { kind: "found", number, isDraft };
+            const oid = item.headRefOid;
+            const headSha = typeof oid === "string" && /^[0-9a-f]{40}$/i.test(oid) ? oid.toLowerCase() : null;
+            matches.push({ number, isDraft, headSha });
         }
     }
+    if (matches.length > 1) {
+        return { kind: "unavailable", reason: "probe_ambiguous" };
+    }
+    if (matches.length === 1) {
+        return { kind: "found", ...matches[0] };
+    }
     // Records exist but none matches both head and base exactly, or the shape is
     // unexpected — never treated as absence.
     return { kind: "unavailable", reason: "probe_malformed" };
@@ -168,10 +195,11 @@ function extractPrNumberFromCreateOutput(stdout) {
     const n = Number(match[1]);
     return Number.isInteger(n) && n > 0 ? n : null;
 }
-async function createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd) {
+async function createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd, repo) {
     const title = buildEpicIntegrationPullRequestTitle(epicKey);
     const body = buildEpicIntegrationPullRequestBody(epicKey, command);
     const args = [
+        ...repoArgs(repo),
         "pr",
         "create",
         "--draft",
@@ -200,15 +228,23 @@ async function createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd)
     }
     return { kind: "create_failed" };
 }
-async function maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd) {
+async function maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd, headBinding = {
+    observedHeadSha: null,
+}, repo) {
     if (!requestReady)
         return "not_requested";
     if (prNumber === null)
         return "ready_failed";
+    if (headBinding.expectedHeadSha !== undefined) {
+        // Bound readiness: an unknown observed head is not the expected head.
+        if (headBinding.observedHeadSha !== headBinding.expectedHeadSha.toLowerCase()) {
+            return "ready_refused_head_drift";
+        }
+    }
     if (!isDraft)
         return "already_ready";
     try {
-        const result = await gh(["pr", "ready", String(prNumber)], {
+        const result = await gh([...repoArgs(repo), "pr", "ready", String(prNumber)], {
             cwd,
             timeoutMs: EPIC_INTEGRATION_PR_WRITE_TIMEOUT_MS,
         });
@@ -219,33 +255,34 @@ async function maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd) {
     }
 }
 async function ensureEpicIntegrationPullRequestInner(options) {
-    const { epicKey, epicBranch, baseBranch, command, gh, cwd, requestReady } = options;
-    const probe = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd);
+    const { epicKey, epicBranch, baseBranch, command, gh, cwd, requestReady, expectedHeadSha, repo } = options;
+    const bind = (observedHeadSha) => expectedHeadSha === undefined ? undefined : { expectedHeadSha, observedHeadSha };
+    const probe = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd, repo);
     if (probe.kind === "unavailable") {
         return { kind: "unavailable", reason: probe.reason };
     }
     if (probe.kind === "found") {
-        const readiness = await maybeMakeReady(gh, probe.number, probe.isDraft, requestReady, cwd);
+        const readiness = await maybeMakeReady(gh, probe.number, probe.isDraft, requestReady, cwd, bind(probe.headSha), repo);
         return { kind: "already_open", reason: "already_open", prNumber: probe.number, readiness };
     }
     // Confirmed absent: create.
-    const created = await createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd);
+    const created = await createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd, repo);
     if (created.kind === "no_commits") {
         return { kind: "deferred", reason: "no_commits_between_branches" };
     }
     if (created.kind === "created") {
         // Resolve the number through a fresh matching probe first; fall back to the
         // strict URL-derived hint only when the probe cannot confirm it.
-        const reprobe = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd);
+        const reprobe = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd, repo);
         const prNumber = reprobe.kind === "found" ? reprobe.number : created.numberHint;
         const isDraft = reprobe.kind === "found" ? reprobe.isDraft : true;
-        const readiness = await maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd);
+        const readiness = await maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd, bind(reprobe.kind === "found" ? reprobe.headSha : null), repo);
         return { kind: "created", reason: "created", prNumber, readiness };
     }
     // Generic create failure: resolve a possible concurrent creator once, never more.
-    const race = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd);
+    const race = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd, repo);
     if (race.kind === "found") {
-        const readiness = await maybeMakeReady(gh, race.number, race.isDraft, requestReady, cwd);
+        const readiness = await maybeMakeReady(gh, race.number, race.isDraft, requestReady, cwd, bind(race.headSha), repo);
         return { kind: "already_open", reason: "already_open", prNumber: race.number, readiness };
     }
     return { kind: "unavailable", reason: "create_unavailable" };
@@ -270,9 +307,18 @@ export async function ensureEpicIntegrationPullRequest(options) {
  * binary, timeout, spawn error) resolves a non-zero/timed-out result rather
  * than rejecting.
  */
-export function createProductionEpicIntegrationGhRunner(execFileImpl = nodeExecFile) {
+export function createProductionEpicIntegrationGhRunner(execFileImpl = nodeExecFile, 
+/**
+ * BAPI-1259: an EXPLICIT child environment. A durable integration action
+ * passes the restricted environment `buildLocalMergeChildEnv` builds from the
+ * configured customer credential, so an ambient `gh` login, `GH_TOKEN`, or
+ * `GITHUB_TOKEN` can never authorize the write. Omitted, the child inherits
+ * the parent environment exactly as before (the wind-down observer).
+ */
+env) {
     return (args, options) => new Promise((resolve) => {
         execFileImpl("gh", args, {
+            ...(env ? { env } : {}),
             cwd: options.cwd,
             timeout: options.timeoutMs,
             maxBuffer: 4 * 1024 * 1024,