@bridge_gpt/mcp-server 0.2.69 → 0.2.70

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}
+import{realpathSync}from"node:fs";import path from"node:path";import{fileURLToPath}from"node:url";function isBinEntrypoint(callerModuleUrl,argv1=process.argv[1]){if(argv1===void 0)return!1;let callerPath=fileURLToPath(callerModuleUrl);try{return realpathSync(argv1)===realpathSync(callerPath)}catch{return path.resolve(argv1)===callerPath}}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}],["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};
+`}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)}isBinEntrypoint(import.meta.url)&&runEpicImplementerClaudeHookBin();export{runEpicImplementerClaudeHookBin};

package/build/escalation-reachability.js

@@ -0,0 +1,134 @@
+import { normalizeReadinessDetail, normalizeReadinessRemediation, } from "./readiness-check.js";
+/** The server diagnostic that reports whether email can actually leave the server. */
+export const EMAIL_TRANSPORT_LIVE_DIAGNOSTIC_ID = "escalation_email.transport_live";
+/** Both ways to reach a person, spelled once for every reachability warning. */
+export const ESCALATION_REACHABILITY_REMEDY = "declare notify.webhook_url in the run policy, or configure live email on the server.";
+/** Fixed copy for the known failed transport diagnostic. It never infers which failure it was. */
+export const EMAIL_TRANSPORT_NOT_LIVE_DETAIL = "escalations go to email, and this server's email transport is not live (local no-op or unavailable), so no person is told";
+/**
+ * Fixed copy for a failed email transport when email is not the selected channel
+ * (BAPI-1495). It reports an unused capability and never says nobody is told.
+ */
+export const EMAIL_TRANSPORT_UNUSED_DETAIL = "this server's email transport is not live, but escalations do not use email for this run; this is unused email capability";
+/** Fixed copy for a failed email transport when no channel is selected. */
+export const EMAIL_TRANSPORT_NO_CHANNEL_DETAIL = "no escalation channel is selected, and this server's email transport is not live";
+/** Fixed copy for a failed email transport when the channel is not known. */
+export const EMAIL_TRANSPORT_UNCERTAIN_DETAIL = "this server's email transport is not live, and the selected escalation channel is not known, so whether it matters is unconfirmed";
+/** A known email-transport diagnostic that is applicable, declared, and failed. */
+export function isFailedEmailTransportDiagnostic(diagnostic) {
+    return (diagnostic.id === EMAIL_TRANSPORT_LIVE_DIAGNOSTIC_ID &&
+        diagnostic.severity !== null &&
+        diagnostic.applicability === "applicable" &&
+        diagnostic.verdict === "failed");
+}
+/** The fixed id of the escalation-reachability row (BAPI-1490). */
+export const ESCALATION_REACHABILITY_CHECK_ID = "escalation-reachability";
+/**
+ * The one effective-channel resolver (BAPI-1495). Pure.
+ *
+ * The server-reported run channel wins when it is `webhook`, `email` or `none`.
+ * Otherwise the caller's resolved channel is used: `null` is an explicit "no
+ * channel", while an omitted caller channel is not known. With neither, the channel
+ * is `unknown`. Preview, attach and readiness all resolve through this function, so
+ * the same inputs always produce the same wording.
+ *
+ * Warning follow-up belongs to the invoking driver or operator and is independent of
+ * notification delivery. Every row built from this channel stays non-blocking.
+ */
+export function resolveEffectiveEscalationChannel(report, callerChannel) {
+    const reported = report?.escalation_channel;
+    if (reported === "webhook" || reported === "email" || reported === "none")
+        return reported;
+    if (callerChannel === undefined)
+        return "unknown";
+    return callerChannel === null ? "none" : callerChannel;
+}
+/** The fixed detail for a failed email transport row, by effective channel. */
+export function emailTransportDetailForChannel(channel) {
+    switch (channel) {
+        case "email":
+            return EMAIL_TRANSPORT_NOT_LIVE_DETAIL;
+        case "webhook":
+            return EMAIL_TRANSPORT_UNUSED_DETAIL;
+        case "none":
+            return EMAIL_TRANSPORT_NO_CHANNEL_DETAIL;
+        default:
+            return EMAIL_TRANSPORT_UNCERTAIN_DETAIL;
+    }
+}
+/**
+ * Whether a person can be told: one conservative, non-blocking row.
+ *
+ * Pure. It reads only the report it is handed and the resolved channel; it never
+ * fetches, reads a file, or consults a collector. It reports configuration, not
+ * delivery: a `pass` says only that the selected channel has a webhook or a
+ * confirmed-live email transport, and never that an endpoint or a person received
+ * anything. Recipient and template checks stay with the admission diagnostics.
+ *
+ * - `webhook` passes whatever the email transport says, unless the webhook's last
+ *   delivery failed or could not be read; those warn without naming email as the cause.
+ * - `email` passes only on exactly one applicable, confirmed-passed
+ *   `escalation_email.transport_live` observation. A failed, missing, deferred,
+ *   unreadable or conflicting observation warns, and the known failed one uses the
+ *   fixed non-live copy. This function never guesses between local no-op and
+ *   unavailable.
+ * - no channel warns whatever the transport says; an unknown channel warns with an
+ *   uncertainty line.
+ *
+ * Every row is non-blocking and carries fixed prose only: no destination, address,
+ * token or configuration value can reach it.
+ */
+export function buildEscalationReachabilityCheck(report, callerChannel) {
+    const channel = resolveEffectiveEscalationChannel(report, callerChannel);
+    const label = "Escalation reachability";
+    const warn = (detail) => ({
+        id: ESCALATION_REACHABILITY_CHECK_ID,
+        source: "server",
+        label,
+        status: "warn",
+        blocking: false,
+        detail: normalizeReadinessDetail(detail),
+        remediation: normalizeReadinessRemediation(ESCALATION_REACHABILITY_REMEDY),
+    });
+    const pass = () => ({
+        id: ESCALATION_REACHABILITY_CHECK_ID,
+        source: "server",
+        label,
+        status: "pass",
+        blocking: false,
+        detail: normalizeReadinessDetail("the selected channel has a webhook or confirmed-live email transport"),
+    });
+    if (channel === "webhook") {
+        if (report?.webhook_last_delivery === "failed") {
+            return warn("the selected webhook's last delivery failed");
+        }
+        if (report?.webhook_last_delivery === "unknown") {
+            return warn("the selected webhook's last delivery could not be read");
+        }
+        return pass();
+    }
+    if (channel === "none") {
+        return warn("no escalation channel: no webhook is declared and email is not the selected channel, so no person is told");
+    }
+    if (channel === "unknown") {
+        return warn("the selected escalation channel is not known, so whether a person would be told is unconfirmed");
+    }
+    const diagnostics = report === null || report.unavailableSources?.includes("server") === true
+        ? null
+        : report.diagnostics ?? null;
+    const uncertain = "a reachable escalation channel is not confirmed: no webhook is declared, and live email transport is not confirmed";
+    if (diagnostics === null)
+        return warn(uncertain);
+    const observed = diagnostics.filter((entry) => entry.id === EMAIL_TRANSPORT_LIVE_DIAGNOSTIC_ID);
+    if (observed.length !== 1)
+        return warn(uncertain);
+    const [observation] = observed;
+    if (isFailedEmailTransportDiagnostic(observation))
+        return warn(EMAIL_TRANSPORT_NOT_LIVE_DETAIL);
+    if (observation.severity === "advisory" &&
+        observation.applicability === "applicable" &&
+        observation.verdict === "passed") {
+        return pass();
+    }
+    return warn(uncertain);
+}

package/build/executor/cleanup-report.js

@@ -0,0 +1,99 @@
+/** How long a woken executor keeps retrying a retained report (6 minutes). */
+export const CLEANUP_REPORT_WAKE_RETRY_WINDOW_MS = 6 * 60 * 1000;
+/** The record-removal decision for one delivery result. */
+export function cleanupReportPermitsRecordRemoval(result) {
+    return result.kind === "accepted" || result.kind === "not_applicable";
+}
+/**
+ * Deliver one report. Never throws; a client without `reportCleanup`, or one that
+ * throws, is a retained `client_unsupported` / `network_error` outcome.
+ */
+export async function submitCleanupReport(input) {
+    const report = input.httpClient.reportCleanup;
+    if (typeof report !== "function") {
+        return { kind: "retained", reason: "client_unsupported", retryable: false };
+    }
+    try {
+        const result = await report.call(input.httpClient, {
+            jobId: input.jobId,
+            repoName: input.repoName,
+            ownershipToken: input.ownershipToken,
+            path: input.path,
+        });
+        return normalizeCleanupReportResult(result);
+    }
+    catch {
+        return { kind: "retained", reason: "network_error", retryable: true };
+    }
+}
+const RETAINED_REASONS = new Set([
+    "job_running",
+    "retry_later",
+    "network_error",
+    "unsupported",
+    "unauthorized",
+    "rate_limited",
+    "server_error",
+    "malformed_response",
+    "client_unsupported",
+]);
+/** A malformed client result is a retained, non-retryable outcome, never a removal. */
+function normalizeCleanupReportResult(result) {
+    if (typeof result === "object" && result !== null) {
+        const kind = result.kind;
+        if (kind === "accepted")
+            return { kind: "accepted" };
+        if (kind === "not_applicable")
+            return { kind: "not_applicable" };
+        if (kind === "retained") {
+            const reason = result.reason;
+            const retryable = result.retryable;
+            if (typeof reason === "string" && RETAINED_REASONS.has(reason)) {
+                return { kind: "retained", reason: reason, retryable: retryable === true };
+            }
+        }
+    }
+    return { kind: "retained", reason: "malformed_response", retryable: false };
+}
+/**
+ * Retry a retained wake report in the background at the heartbeat cadence, for at
+ * most {@link CLEANUP_REPORT_WAKE_RETRY_WINDOW_MS}. Resolves when it finishes; it
+ * never rejects. Stops early (keeping the record) for an authorization failure or
+ * an unsupported server, on shutdown, and on exhaustion, where it emits the closed
+ * `cleanup_report_retry_exhausted` diagnostic and leaves later delivery to the
+ * startup recovery path.
+ */
+export async function retryWakeCleanupReport(input) {
+    const { deps } = input;
+    const startedAt = deps.now();
+    let result = input.firstResult;
+    try {
+        for (;;) {
+            if (cleanupReportPermitsRecordRemoval(result)) {
+                await input.onTerminal();
+                return;
+            }
+            if (result.kind !== "retained" || !result.retryable)
+                return;
+            if (input.shouldStop())
+                return;
+            if (deps.now() - startedAt + input.intervalMs > CLEANUP_REPORT_WAKE_RETRY_WINDOW_MS) {
+                deps.diagnostic({ event: "cleanup_report_retry_exhausted", jobId: input.jobId });
+                return;
+            }
+            await deps.sleep(input.intervalMs);
+            if (input.shouldStop())
+                return;
+            result = await submitCleanupReport({
+                httpClient: input.httpClient,
+                jobId: input.jobId,
+                repoName: input.repoName,
+                ownershipToken: input.ownershipToken,
+                path: "wake",
+            });
+        }
+    }
+    catch {
+        // Contained: a retry failure keeps the record for the startup path.
+    }
+}

package/build/executor/cli.js

@@ -14,6 +14,7 @@ import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
 import { DEFAULT_EXECUTOR_AGENT_ID } from "./agent-identity.js";
 import { executorEpicRunIdRefusal, isValidExecutorEpicRunId, validateExecutorClaimScope, } from "./claim-scope.js";
 import { createDefaultExecutorDeps } from "./deps.js";
+import { createProductionWorkerResources } from "./worker-resources.js";
 import { scrubExecutorProcessGithubCredentials } from "./env.js";
 import { resolveBaseUrl, resolveExecutorApiAccess, EXECUTOR_BASE_URL_REQUIRED_MESSAGE, } from "./credentials.js";
 import { createExecutorHttpClient } from "./http-client.js";
@@ -320,7 +321,17 @@ export async function runExecutorCli(argv, overrides = {}) {
     if (argv[0] === "watch") {
         return runExecutorWatchCli(argv.slice(1));
     }
-    const deps = overrides.deps ?? createDefaultExecutorDeps();
+    // BAPI-1479: the disposable job database and own-build launcher attach only to
+    // the real executor process — never to `createDefaultExecutorDeps()`, which
+    // tests spread, nor to injected deps. See `worker-resources.ts`.
+    const deps = overrides.deps ?? {
+        ...createDefaultExecutorDeps(),
+        workerResources: createProductionWorkerResources({
+            env: process.env,
+            cwd: process.cwd(),
+            platform: process.platform,
+        }),
+    };
     const context = overrides.context ?? {
         hostname: os.hostname(),
         pid: process.pid,

package/build/executor/completion-contract.js

@@ -27,6 +27,13 @@
 import { createHash } from "node:crypto";
 /** The capability string declared on `POST /claim` and required by covered jobs. */
 export const COMPLETION_EVIDENCE_CAPABILITY = "completion_evidence.v1";
+/**
+ * BAPI-1504 — declared on `POST /claim` by an executor that persists ownership
+ * BEFORE spawning a covered worker and can deliver `POST /{id}/cleanup-report`.
+ * A job stamped with it makes a `null` stored ownership reliable evidence that no
+ * owned worker was spawned. Mirrors the server's `CLEANUP_REPORT_CAPABILITY`.
+ */
+export const CLEANUP_REPORT_CAPABILITY = "cleanup_report.v1";
 export const COMPLETION_CONTRACT_VERSION = 1;
 /**
  * BAPI-1302 (D4c) — the envelope version that carries executor-run check facts
@@ -40,12 +47,13 @@ export const COMPLETION_CONTRACT_VERSION_V2 = 2;
  * without the runner never claims one.
  */
 export const REQUIRED_VERIFICATION_CAPABILITY = "required_verification.v1";
+export const REQUIRED_VERIFICATION_CI_DEFERRAL_CAPABILITY = "required_verification.ci_deferral.v2";
 export const COMPLETION_CONTRACT_MARKER_VALUES = ["completion_evidence.v1", "legacy"];
 export const COVERED_JOB_TYPES = ["implement", "resume", "remediate", "ci_fix"];
 /**
- * The measured runtime identity (BAPI-1292 probe): Claude Code 2.1.282 on macOS
- * arm64. A measured baseline, not a certification — any other CLI version or
- * platform is unsupported until measured.
+ * The measured baseline (BAPI-1292 probe): Claude Code 2.1.282 on macOS arm64.
+ * It is a reference value, not the acceptance rule. `runtimeMatchesSupported`
+ * accepts this identity and any newer CLI version on a supported platform.
  */
 export const SUPPORTED_COMPLETION_RUNTIME = {
     adapter: "claude",
@@ -122,6 +130,7 @@ export const EXECUTION_VALUES = ["complete", "incomplete", "unknown"];
  */
 export const VERIFICATION_VALUES = [
     "not_declared",
+    "awaiting_ci",
     "passed",
     "failed",
     "unavailable",
@@ -162,15 +171,53 @@ export const TASK_STATE_VALUES = [
     "failed",
     "stopped",
     "withdrawn",
+    "failed_to_start",
     "replaced",
     "unknown",
     "conflict",
 ];
-/** The only states that resolve a REQUIRED task. */
+/**
+ * The states that resolve EXECUTION of a REQUIRED task. Resolving execution is
+ * not the same as succeeding or verifying: `withdrawn` (the worker stopped its
+ * own helper) and `failed_to_start` (a background command failed inside the
+ * startup window) only say the work is no longer running. `failed`, a
+ * CLI-teardown `stopped`, a verdict-time `unknown`, and `conflict` stay
+ * unresolved when required. Declared verification depends only on verification
+ * facts, never on this set.
+ */
 export const TASK_RESOLVING_STATES = new Set([
     "succeeded",
     "replaced",
+    "withdrawn",
+    "failed_to_start",
 ]);
+/**
+ * BAPI-1455 — the command kinds whose own terminal result can be DELIVERED to
+ * the worker. Delegates and monitors are not commands and never qualify.
+ */
+export const DELIVERY_RESOLVABLE_KINDS = new Set(["bash_task", "bash_bg", "subagent_bash"]);
+/**
+ * BAPI-1455 — the terminal states a delivered command result resolves. `pending`,
+ * `unknown`, and `conflict` are never resolved by delivery.
+ */
+export const DELIVERY_RESOLVABLE_STATES = new Set(["failed", "stopped"]);
+/**
+ * The one rule for "this required task no longer blocks execution". A task is
+ * resolved when its state is in {@link TASK_RESOLVING_STATES}, or when it is a
+ * command that ended `failed` or `stopped` AND the worker received that
+ * command's own terminal result (`result_delivered === true`, exactly).
+ *
+ * Resolving is not succeeding: a delivered failure keeps its real state, is not
+ * completed work, and proves no verification. Mirror of `task_is_resolved` in
+ * Python; every resolution check in this module goes through it.
+ */
+export function isTaskResolved(task) {
+    if (TASK_RESOLVING_STATES.has(task.state))
+        return true;
+    return (task.result_delivered === true &&
+        DELIVERY_RESOLVABLE_KINDS.has(task.kind) &&
+        DELIVERY_RESOLVABLE_STATES.has(task.state));
+}
 export const DENIAL_OPERATION_VALUES = [
     "push",
     "pr_create",
@@ -186,6 +233,7 @@ export const MISSING_CAPABILITY_VALUES = [
     "focused_ci_repair",
     "repaired_head_convergence",
     "continuation",
+    "cleanup_report",
 ];
 /** BAPI-1302 — where a job's declaration came from. Neither `absent` nor `declared_empty` is a pass. */
 export const DECLARATION_PROVENANCE_VALUES = ["declared", "declared_empty", "absent", "refused"];
@@ -295,7 +343,7 @@ export function runtimeMatchesSupported(runtime) {
         cliVersionAtLeast(version, minimum));
 }
 export function unresolvedRequiredTasks(envelope) {
-    return envelope.tasks.filter((t) => t.required && !TASK_RESOLVING_STATES.has(t.state));
+    return envelope.tasks.filter((t) => t.required && !isTaskResolved(t));
 }
 const FULL_SHA_RE = /^[0-9a-f]{40}$/;
 /**
@@ -312,7 +360,7 @@ export function verificationVerdictFromFacts(facts, declaredCount) {
     if (facts.provenance !== "declared")
         return "incomplete";
     const expected = declaredCount ?? facts.commands.length;
-    if (expected === 0 || facts.commands.length !== expected)
+    if ((expected === 0 && !facts.deferred_obligation_identities?.length) || facts.commands.length !== expected)
         return "incomplete";
     if (facts.artifact !== "stable" || facts.tested_head_sha === null || !FULL_SHA_RE.test(facts.tested_head_sha)) {
         return "incomplete";
@@ -321,12 +369,15 @@ export function verificationVerdictFromFacts(facts, declaredCount) {
         return "incomplete";
     if (facts.commands.some((c) => c.outcome === "exited_nonzero"))
         return "failed";
-    return "passed";
+    return facts.deferred_obligation_identities?.length ? "awaiting_ci" : "passed";
 }
 /**
  * Closed reason the envelope cannot support a covered success, or null.
  * Mirrors the server's `success_refusal_reason` clause for clause, so the
  * executor never sends `/complete` for an envelope the server would refuse.
+ *
+ * A delivered command result (BAPI-1455) only resolves its task's execution.
+ * Verification, finalization, cleanup, and denials still decide on their own.
  */
 export function successRefusalReason(envelope) {
     if (envelope.evidence !== "sufficient")
@@ -335,7 +386,7 @@ export function successRefusalReason(envelope) {
         return "execution_not_complete";
     if (unresolvedRequiredTasks(envelope).length > 0)
         return "required_task_unresolved";
-    if (envelope.verification !== "passed" && envelope.verification !== "not_declared") {
+    if (envelope.verification !== "passed" && envelope.verification !== "not_declared" && envelope.verification !== "awaiting_ci") {
         return "verification_not_acceptable";
     }
     if (envelope.finalization !== "ok" && envelope.finalization !== "not_required") {
@@ -365,7 +416,7 @@ export function deriveCompletionCause(envelope) {
     if (blocking.length > 0 && envelope.evidence === "sufficient" && blocking.some((d) => d.result_after_denial)) {
         return "permission_stop";
     }
-    const unresolved = envelope.tasks.some((t) => t.required && !TASK_RESOLVING_STATES.has(t.state));
+    const unresolved = envelope.tasks.some((t) => t.required && !isTaskResolved(t));
     const requiredWorkIncomplete = blocking.length > 0 ||
         envelope.evidence !== "sufficient" ||
         envelope.execution !== "complete" ||
@@ -417,7 +468,7 @@ export function isNotLaunchedEnvelope(envelope) {
  */
 export function buildNotLaunchedEnvelope(input) {
     return {
-        evidence_version: input.verificationFacts ? COMPLETION_CONTRACT_VERSION_V2 : COMPLETION_CONTRACT_VERSION,
+        evidence_version: input.verificationFacts?.deferred_obligation_identities !== undefined ? 3 : input.verificationFacts ? COMPLETION_CONTRACT_VERSION_V2 : COMPLETION_CONTRACT_VERSION,
         runtime: { ...input.runtime },
         binding: { ...input.binding },
         session_id: null,
@@ -466,7 +517,7 @@ export function boundEnvelope(envelope) {
     };
     let next = markOversize({
         ...envelope,
-        tasks: envelope.tasks.filter((t) => t.required && !TASK_RESOLVING_STATES.has(t.state)),
+        tasks: envelope.tasks.filter((t) => t.required && !isTaskResolved(t)),
     });
     if (size(next) <= MAX_SERIALIZED_BYTES)
         return next;
@@ -479,3 +530,7 @@ export function boundEnvelope(envelope) {
     // Last resort: identities cannot fit. Keep the count-free verdict only.
     return markOversize({ ...next, tasks: next.tasks.slice(0, 8), denials: next.denials.slice(0, 8) });
 }
+/** Whether a stored requirement list names the cleanup-report capability (BAPI-1504). */
+export function claimRequiresCleanupReport(requiredCapabilities) {
+    return Array.isArray(requiredCapabilities) && requiredCapabilities.includes(CLEANUP_REPORT_CAPABILITY);
+}

package/build/executor/completion-supervision.js

@@ -133,6 +133,8 @@ export function readRequiredVerification(payload) {
         return { kind: "refused", reason: "not_an_object", provenance: null, digest: null };
     }
     const d = raw;
+    if (d.schema_version === 2)
+        return readPolicyDeclaration(d);
     const digest = typeof d.digest === "string" && DIGEST_RE.test(d.digest) ? d.digest : null;
     const provenance = d.provenance === "declared" || d.provenance === "declared_empty" || d.provenance === "absent" || d.provenance === "refused"
         ? d.provenance
@@ -200,6 +202,103 @@ export function readDeclaredChecks(payload) {
     const read = readRequiredVerification(payload);
     return read.kind === "ok" ? read.declaration.checks : [];
 }
+export function renderApprovedVerificationGuidance(payload) {
+    const read = readRequiredVerification(payload);
+    if (read.kind !== "ok" || read.declaration.policyVersion !== 2)
+        return "";
+    const raw = payload[REQUIRED_VERIFICATION_PAYLOAD_KEY];
+    return "APPROVED EPIC VERIFICATION POLICY v2. Use targeted checks for this focused job. " +
+        "Run mandatory local checks and focused repair tests. Defer only the explicitly approved CI obligations, even when runnable locally. " +
+        "Do not rerun their full suites during repair or renewal. Missing coverage stays local. " +
+        "Preserve all phase-owned records; focused tests do not prove a suite. Actual local failures remain verification_failures. " +
+        "Use the sealed delivery-plan joins from get_phase_context for remote_ci records, naming all covering checks. " +
+        "Invalidate stale local proof with invalidatedBy stale_verification_head. Do one renewal pass on the final pushed artifact and one confirming readiness read. " +
+        "Deferred obligations remain awaiting_ci, never locally passed.\n" +
+        "Mandatory local commands: " + JSON.stringify(read.declaration.checks) + "\nApproved obligations: " + JSON.stringify(raw.obligations);
+}
+/** The v2 approval is validated whole before selecting local commands. */
+function readPolicyDeclaration(d) {
+    const refuse = () => ({ kind: "refused", reason: "malformed_command", digest: null, provenance: null });
+    const exact = (v, keys) => Object.keys(v).sort().join("|") === keys.sort().join("|");
+    const text = (v) => typeof v === "string" && v.length > 0 && v.length <= 200 && v.trim() === v;
+    if (!exact(d, ["schema_version", "provenance", "plan_version", "plan_hash", "commands", "digest", "policy_revision", "execution_scope", "ticket_key", "obligations"]) ||
+        !isInt(d.plan_version) || d.plan_version < 0 || typeof d.plan_hash !== "string" || !DIGEST_RE.test(d.plan_hash) ||
+        !text(d.policy_revision) || d.execution_scope !== "epic_targeted" || typeof d.ticket_key !== "string" || !/^[A-Z][A-Z0-9_]{0,19}-\d+$/.test(d.ticket_key) ||
+        typeof d.digest !== "string" || !DIGEST_RE.test(d.digest) || computeDeclarationDigest(d) !== d.digest ||
+        !Array.isArray(d.commands) || d.commands.length > 16 || !Array.isArray(d.obligations) || d.obligations.length > 1024 ||
+        !["declared", "declared_empty", "absent"].includes(String(d.provenance)) || (d.provenance === "declared") !== (d.obligations.length > 0))
+        return refuse();
+    const checks = [];
+    const argvKeys = new Set();
+    for (let i = 0; i < d.commands.length; i++) {
+        const command = validCommand(d.commands[i], i);
+        if (typeof command === "string")
+            return refuse();
+        const argvKey = JSON.stringify(command.argv);
+        if (argvKeys.has(argvKey))
+            return refuse();
+        argvKeys.add(argvKey);
+        checks.push(command);
+    }
+    const byIdentity = new Map(checks.map(c => [c.identity, c]));
+    const seen = new Set(), associated = new Set(), local = new Set(), joins = new Set();
+    const deferred = [];
+    for (const raw of d.obligations) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return refuse();
+        const o = raw;
+        if (!exact(o, ["identity", "command_identity", "source", "source_identity", "approval_reference", "classification", "local_reason", "covering_checks", "delivery_plan_digest", "delivery_step_ids"]) ||
+            !["plan", "profile", "inspection"].includes(String(o.source)) || !text(o.source_identity) ||
+            !["mandatory_local", "ci_deferred"].includes(String(o.classification)) ||
+            !Array.isArray(o.covering_checks) || o.covering_checks.length > 64 || !o.covering_checks.every(text) ||
+            new Set(o.covering_checks).size !== o.covering_checks.length || [...o.covering_checks].sort().join("|") !== o.covering_checks.join("|") ||
+            !Array.isArray(o.delivery_step_ids) || o.delivery_step_ids.length > 256 || !o.delivery_step_ids.every(s => isInt(s) && s > 0) ||
+            new Set(o.delivery_step_ids).size !== o.delivery_step_ids.length ||
+            JSON.stringify([...o.delivery_step_ids].sort((a, b) => Number(a) - Number(b))) !== JSON.stringify(o.delivery_step_ids) ||
+            (o.delivery_plan_digest !== null && !text(o.delivery_plan_digest)) ||
+            (o.delivery_step_ids.length > 0) !== text(o.delivery_plan_digest) ||
+            o.approval_reference !== `${d.plan_hash}:${d.policy_revision}`)
+            return refuse();
+        const identity = `ob-${sha256Hex(`${d.ticket_key}:${o.source}:${o.source_identity}`).slice(0, 32)}`;
+        if (o.identity !== identity || seen.has(identity))
+            return refuse();
+        seen.add(identity);
+        for (const step of o.delivery_step_ids) {
+            const join = `${o.delivery_plan_digest}:${step}`;
+            if (joins.has(join))
+                return refuse();
+            joins.add(join);
+        }
+        if (o.source === "inspection") {
+            if (o.command_identity !== null || o.classification !== "mandatory_local" || o.local_reason !== "non_ci_inspection")
+                return refuse();
+        }
+        else {
+            const c = typeof o.command_identity === "string" ? byIdentity.get(o.command_identity) : undefined;
+            const sourcePosition = /^cmd-(\d+)-[a-f0-9]{16}$/.exec(o.source_identity);
+            if (!c || !sourcePosition || declaredCommandIdentity(Number(sourcePosition[1]), { name: c.name, argv: c.argv, timeout_seconds: c.timeoutSeconds }) !== o.source_identity)
+                return refuse();
+            associated.add(c.identity);
+        }
+        if (o.classification === "ci_deferred") {
+            if (o.source !== "plan" || o.local_reason !== null || o.covering_checks.length === 0)
+                return refuse();
+            deferred.push(identity);
+        }
+        else {
+            if (o.covering_checks.length !== 0 || !["coverage_not_established", "explicitly_approved_local", "stamped_local_gate", "non_ci_inspection"].includes(String(o.local_reason)) ||
+                (o.source === "profile" && o.local_reason !== "stamped_local_gate"))
+                return refuse();
+            if (typeof o.command_identity === "string")
+                local.add(o.command_identity);
+        }
+    }
+    if (associated.size !== checks.length)
+        return refuse();
+    return { kind: "ok", declaration: { provenance: d.provenance, digest: d.digest,
+            planVersion: d.plan_version, planHash: d.plan_hash, checks: checks.filter(c => local.has(c.identity)), policyVersion: 2, deferredIdentities: deferred,
+            obligations: structuredClone(d.obligations) } };
+}
 export function finalizationObligations(branch, baseBranch) {
     return {
         push: { remote: "origin", ref: `refs/heads/${branch}` },