@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/build/conductor/bring-up-facts.js

@@ -35,7 +35,9 @@ export const WORKER_NOT_PRESENT_REMEDIATION = "start a worker (`python worker.py
 export const SECOND_RECONCILER_REMEDIATION = "find and stop the extra reconciler: check `ps aux | grep worker.py` for a reparented " +
     `survivor of an earlier plane (${BRING_UP_RUNBOOK} §6), and note that a dev server started ` +
     "without DISABLE_SCHEDULER=true runs a reconciler too. A reconciler stopped in the last 120 " +
-    "seconds still counts — heartbeat rows are not deleted on shutdown — so wait and retry.";
+    "seconds still counts — heartbeat rows are not deleted on shutdown — so wait and retry. " +
+    "On a hosted deployment, check that exactly one worker process is scaled (for example one " +
+    "Heroku `worker` dyno): each worker runs its own reconciler.";
 // ---------------------------------------------------------------------------
 // Classification
 // ---------------------------------------------------------------------------

package/build/conductor/doctor.js

@@ -82,8 +82,9 @@ export const MCP_PROFILE_UNSET = "(unset)";
 /**
  * The CLI-only verbs that call the Bridge API from a shell-spawned process and
  * therefore resolve credentials themselves (CLAUDE.md "Shell-Spawned Credential
- * Resolution"): the four BAPI-872 recovery verbs and the six run-addressed repair
- * verbs (BAPI-1154's three and BAPI-1176's three). `.mcp.json` env is invisible to
+ * Resolution"): the four BAPI-872 recovery verbs, the six run-addressed repair
+ * verbs (BAPI-1154's three and BAPI-1176's three), and BAPI-1300's parked-child
+ * continuation pair. `.mcp.json` env is invisible to
  * them — only `BAPI_API_KEY` in the parent env and the user-scoped credential
  * store count.
  */
@@ -98,6 +99,9 @@ export const CREDENTIALED_RECOVERY_COMMANDS = [
     "scope-catch-up",
     "patch-policy",
     "resume-run",
+    // BAPI-1300: parked-child continuation and its read-only receipt lookup.
+    "continue-child",
+    "continuation-receipt",
 ];
 /** Remediation for recovery/repair verbs that cannot resolve Bridge credentials. */
 export const REPAIR_CREDENTIAL_REMEDIATION = "export BAPI_API_KEY in the shell that runs `conductor`, or store a credential for this " +
@@ -803,11 +807,14 @@ export function formatConductorDoctorReport(report) {
     lines.push(`hooks dir:             ${git_hooks.hooks_dir ?? "n/a"}`);
     lines.push(`degraded:              ${git_hooks.degraded}`);
     for (const hook of git_hooks.hooks) {
-        // BAPI-772: the embedded target is shown alongside the structural fields —
-        // a managed block whose binary no longer exists is a DEAD hook, and this line
-        // is where that becomes visible. Advisory only: never changes the exit code.
+        // BAPI-772 made a dead embedded target visible here; BAPI-1290 replaces the
+        // raw path with the shared per-hook verdict, because a file that EXISTS can
+        // still be a prunable cache entry or a runtime whose native binding does not
+        // load. The embedded path stays in `--json` output only. Advisory only:
+        // never changes the exit code. Read defensively — a literal fixture may
+        // predate `state`/`usable`, and unknown is never healthy.
         lines.push(`  ${hook.name}: exists=${hook.exists} executable=${hook.executable} managed=${hook.managed_block_present} ` +
-            `bin=${hook.embedded_bin_path ?? "n/a"} bin_is_file=${hook.embedded_bin_is_file}`);
+            `state=${hook.state ?? "unknown"} usable=${hook.usable === true}`);
     }
     if (git_hooks.warnings.length > 0) {
         lines.push("git hook warnings:");
@@ -962,8 +969,8 @@ export const CONDUCTOR_READINESS_DESCRIPTORS = [
 export const CONDUCTOR_LEDGER_REMEDIATION = "run `epic-implementer doctor` for the ledger detail, then re-create the local ledger directory with " +
     "owner-only permissions; the ledger is local observability and never blocks a run.";
 /** Remediation for degraded or missing managed git hooks. */
-export const CONDUCTOR_GIT_HOOKS_REMEDIATION = "run `epic-implementer install-git-hooks` to install the managed post-commit and reference-transaction " +
-    "hooks; they are local, opportunistic, and bypassable.";
+export const CONDUCTOR_GIT_HOOKS_REMEDIATION = "run `epic-implementer install-git-hooks` from a persistent install to install the managed post-commit and " +
+    "reference-transaction hooks; they are local, opportunistic, and bypassable, and never gate engine admission.";
 /** Remediation for a Claude login this host cannot confirm. */
 export const CONDUCTOR_CLAUDE_LOGIN_REMEDIATION = "run `claude login` on the host that will run conductor workers; Bridge stores no Anthropic " +
     "credential and can only advise here.";
@@ -1014,22 +1021,24 @@ function gitHooksOutcome(report) {
         };
     }
     // Hook NAMES and booleans only — `hooks_dir` is absolute and never projected.
-    const rendered = hooks.hooks
-        .map((hook) => `${hook.name}=${hook.exists && hook.managed_block_present}`)
-        .join(", ");
-    return hooks.degraded
+    // BAPI-1290: the boolean is the shared per-hook `usable` verdict (qualified
+    // persistent runtime, loadable native binding), not mere file presence; a
+    // hook without that verdict is unknown, and unknown is never healthy.
+    const rendered = hooks.hooks.map((hook) => `${hook.name}=${hook.usable === true}`).join(", ");
+    const allUsable = hooks.hooks.length > 0 && hooks.hooks.every((hook) => hook.usable === true);
+    return hooks.degraded || !allUsable
         ? {
             id: "git-hooks",
             label: "Conductor git hooks",
             status: "warn",
-            detail: `managed hooks installed: ${rendered}`,
+            detail: `managed hooks usable: ${rendered}`,
             remediation: CONDUCTOR_GIT_HOOKS_REMEDIATION,
         }
         : {
             id: "git-hooks",
             label: "Conductor git hooks",
             status: "pass",
-            detail: `managed hooks installed: ${rendered}`,
+            detail: `managed hooks usable: ${rendered}`,
         };
 }
 /**

package/build/conductor/epic-child-continuation.js

@@ -0,0 +1,351 @@
+/**
+ * Parked-child continuation — the CLI-side contract (BAPI-1300, D4b).
+ *
+ * Mirrors `api/models/epic_child_continuation.py`. Three things live here:
+ *
+ *  - the canonical request FINGERPRINT, computed byte-for-byte like the server
+ *    (see `docs/epic-child-continuation-wire-contract.md` and its golden vectors);
+ *  - STRICT parsing of the server's typed result bodies — an unknown outcome, a
+ *    missing receipt identity, or an invalid runtime outcome is a parse failure,
+ *    which the caller treats as transport uncertainty, never as success;
+ *  - the local RECOVERY REFERENCE: one small file per in-flight request, written
+ *    BEFORE the request is sent, so a lost response or a restarted process can
+ *    look the receipt up with the ORIGINAL bindings and request id instead of
+ *    minting a new request.
+ *
+ * Nothing here performs HTTP. This module never imports the Bridge API client, so
+ * it stays free of network and credential concerns.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { mkdir as fsMkdir, readFile as fsReadFile, rename as fsRename, unlink as fsUnlink, writeFile as fsWriteFile, } from "node:fs/promises";
+import { getPrimaryCredentialStorePath } from "../credential-store.js";
+// ---------------------------------------------------------------------------
+// Wire constants (must equal the Python module)
+// ---------------------------------------------------------------------------
+export const CONTINUATION_WIRE_VERSION = 1;
+export const CONTINUATION_OPERATION = "continue_parked_child";
+export const CONTINUATION_OUTCOMES = [
+    "committed",
+    "already_continued",
+    "stale_historical_episode",
+    "refused",
+    "unsupported",
+    "unconfirmed",
+];
+export const CONTINUATION_RUNTIME_OUTCOMES = [
+    "queued",
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "dead_letter",
+    "unavailable",
+];
+const REQUEST_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,63}$/;
+const FULL_SHA_RE = /^[0-9a-f]{40}$/;
+const FINGERPRINT_RE = /^[0-9a-f]{64}$/;
+const REASON_CODE_RE = /^[a-z_]{1,64}$/;
+const MAX_TEXT = 500;
+// ---------------------------------------------------------------------------
+// Canonical fingerprint
+// ---------------------------------------------------------------------------
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map((item) => canonicalize(item));
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        const out = {};
+        for (const key of Object.keys(record).sort()) {
+            out[key] = canonicalize(record[key]);
+        }
+        return out;
+    }
+    if (typeof value === "number" && !Number.isSafeInteger(value)) {
+        // The contract carries integers only; a float would serialize differently
+        // across runtimes, so it is refused rather than silently hashed.
+        throw new TypeError("canonical JSON accepts integers only");
+    }
+    return value;
+}
+/** Canonical UTF-8 JSON text: sorted keys at every depth, array order kept. */
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+/** Lowercase SHA-256 hex of {@link canonicalJson}. */
+export function canonicalSha256(value) {
+    return createHash("sha256").update(canonicalJson(value), "utf8").digest("hex");
+}
+/** The fingerprint input document (identical to the Python builder). */
+export function continuationFingerprintInput(b) {
+    return {
+        v: CONTINUATION_WIRE_VERSION,
+        operation: CONTINUATION_OPERATION,
+        target: {
+            repo_name: b.repoName,
+            epic_run_id: b.epicRunId,
+            ticket_key: b.ticketKey,
+            gate: b.parkedGate,
+        },
+        bindings: {
+            expected_row_version: b.expectedRowVersion,
+            expected_head_sha: b.expectedHeadSha,
+            source_park_generation: b.sourceParkGeneration,
+        },
+    };
+}
+export function computeContinuationFingerprint(b) {
+    return canonicalSha256(continuationFingerprintInput(b));
+}
+/** A body that does not satisfy the typed contract. Never read as success. */
+export class ContinuationParseError extends Error {
+    constructor(message) {
+        super(`malformed continuation response: ${message}`);
+        this.name = "ContinuationParseError";
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function req(ok, value, what) {
+    if (!ok)
+        throw new ContinuationParseError(what);
+    return value;
+}
+function nonNegInt(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function posInt(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function boundedText(value) {
+    return typeof value === "string" && value.length <= MAX_TEXT;
+}
+function nullableText(value) {
+    if (value === null || value === undefined)
+        return null;
+    return req(boundedText(value), value, "text field");
+}
+export function parseContinuationReceipt(value) {
+    const r = req(isRecord(value), value, "receipt is not an object");
+    const runtime = r.runtime_outcome ?? null;
+    return {
+        receipt_id: req(typeof r.receipt_id === "string" && r.receipt_id.length > 0 && r.receipt_id.length <= 128, r.receipt_id, "receipt_id"),
+        request_id: req(typeof r.request_id === "string" && REQUEST_ID_RE.test(r.request_id), r.request_id, "request_id"),
+        epic_run_id: req(typeof r.epic_run_id === "string" && r.epic_run_id.length > 0, r.epic_run_id, "epic_run_id"),
+        ticket_key: req(typeof r.ticket_key === "string" && r.ticket_key.length > 0, r.ticket_key, "ticket_key"),
+        gate: req(typeof r.gate === "string" && r.gate.length > 0, r.gate, "gate"),
+        job_type: req(typeof r.job_type === "string" && r.job_type.length > 0, r.job_type, "job_type"),
+        source_park_generation: req(nonNegInt(r.source_park_generation), r.source_park_generation, "source_park_generation"),
+        resulting_park_generation: req(nonNegInt(r.resulting_park_generation), r.resulting_park_generation, "resulting_park_generation"),
+        original_job_id: r.original_job_id === null || r.original_job_id === undefined
+            ? null
+            : req(posInt(r.original_job_id), r.original_job_id, "original_job_id"),
+        continuation_job_id: req(posInt(r.continuation_job_id), r.continuation_job_id, "continuation_job_id"),
+        bound_head_sha: r.bound_head_sha === null || r.bound_head_sha === undefined
+            ? null
+            : req(typeof r.bound_head_sha === "string" && FULL_SHA_RE.test(r.bound_head_sha), r.bound_head_sha, "bound_head_sha"),
+        authorization_kind: req(r.authorization_kind === "operator" || r.authorization_kind === "driver", r.authorization_kind, "authorization_kind"),
+        authorization_ref: req(typeof r.authorization_ref === "string" && r.authorization_ref.length > 0 && r.authorization_ref.length <= 128, r.authorization_ref, "authorization_ref"),
+        committed_at: req(typeof r.committed_at === "string" && r.committed_at.length > 0, r.committed_at, "committed_at"),
+        runtime_outcome: runtime === null
+            ? null
+            : req(CONTINUATION_RUNTIME_OUTCOMES.includes(runtime), runtime, "runtime_outcome"),
+    };
+}
+export function parseChildEpisodeView(value) {
+    const r = req(isRecord(value), value, "current is not an object");
+    const obligations = r.unresolved_obligations ?? [];
+    return {
+        status: req(typeof r.status === "string", r.status, "status"),
+        row_version: req(nonNegInt(r.row_version), r.row_version, "row_version"),
+        parked: req(typeof r.parked === "boolean", r.parked, "parked"),
+        parked_gate: nullableText(r.parked_gate),
+        park_generation: r.park_generation === null || r.park_generation === undefined
+            ? null
+            : req(nonNegInt(r.park_generation), r.park_generation, "park_generation"),
+        expected_head_sha: nullableText(r.expected_head_sha),
+        parked_at: nullableText(r.parked_at),
+        parked_age_seconds: r.parked_age_seconds === null || r.parked_age_seconds === undefined
+            ? null
+            : req(nonNegInt(r.parked_age_seconds), r.parked_age_seconds, "parked_age_seconds"),
+        needs_human_reason: nullableText(r.needs_human_reason),
+        unresolved_obligations: req(Array.isArray(obligations) && obligations.every((item) => typeof item === "string" && item.length <= 128), obligations, "unresolved_obligations"),
+        continuations_used: r.continuations_used === null || r.continuations_used === undefined
+            ? null
+            : req(nonNegInt(r.continuations_used), r.continuations_used, "continuations_used"),
+        continuation_limit: r.continuation_limit === null || r.continuation_limit === undefined
+            ? null
+            : req(nonNegInt(r.continuation_limit), r.continuation_limit, "continuation_limit"),
+        continuation_available: req(typeof r.continuation_available === "boolean", r.continuation_available, "continuation_available"),
+        continuation_unavailable_reason: nullableText(r.continuation_unavailable_reason),
+    };
+}
+function parseOutcome(value) {
+    return req(CONTINUATION_OUTCOMES.includes(value), value, "unknown outcome");
+}
+/**
+ * Parse a continuation result body strictly. A committed or already-continued
+ * outcome MUST carry a receipt; anything less is malformed.
+ */
+export function parseContinueParkedChildResult(value) {
+    const r = req(isRecord(value), value, "body is not an object");
+    const outcome = parseOutcome(r.outcome);
+    const reason = r.reason_code ?? null;
+    const receipt = r.receipt === null || r.receipt === undefined ? null : parseContinuationReceipt(r.receipt);
+    if ((outcome === "committed" || outcome === "already_continued" || outcome === "stale_historical_episode") && receipt === null) {
+        throw new ContinuationParseError(`${outcome} without a receipt`);
+    }
+    return {
+        outcome,
+        reason_code: reason === null ? null : req(typeof reason === "string" && REASON_CODE_RE.test(reason), reason, "reason_code"),
+        explanation: req(boundedText(r.explanation), r.explanation, "explanation"),
+        replayed: r.replayed === true,
+        retryable: r.retryable === true,
+        receipt,
+        current: r.current === null || r.current === undefined ? null : parseChildEpisodeView(r.current),
+    };
+}
+export function parseContinuationStatusResult(value) {
+    const r = req(isRecord(value), value, "body is not an object");
+    const found = req(typeof r.found === "boolean", r.found, "found");
+    const receipt = r.receipt === null || r.receipt === undefined ? null : parseContinuationReceipt(r.receipt);
+    if (found && receipt === null)
+        throw new ContinuationParseError("found without a receipt");
+    return {
+        epic_run_id: req(typeof r.epic_run_id === "string" && r.epic_run_id.length > 0, r.epic_run_id, "epic_run_id"),
+        ticket_key: req(typeof r.ticket_key === "string" && r.ticket_key.length > 0, r.ticket_key, "ticket_key"),
+        current: parseChildEpisodeView(r.current),
+        found,
+        outcome: r.outcome === null || r.outcome === undefined ? null : parseOutcome(r.outcome),
+        receipt,
+    };
+}
+/** The namespace (subdirectory) of the parked-child continuation references. */
+export const CONTINUATION_REFERENCE_NAMESPACE = "epic-child-continuations";
+/**
+ * Directory holding one namespace of recovery references, beside the user
+ * credential store. BAPI-1326's `resume-ci` keeps its pinned operations in its
+ * own namespace through this same store, so the two recoveries share one file
+ * format, one permission model, and one atomic-write path.
+ */
+export function getRecoveryReferenceDirectory(namespace, deps = {}) {
+    const credentials = getPrimaryCredentialStorePath({
+        env: deps.env ?? process.env,
+        homedir: deps.homedir ?? os.homedir,
+    });
+    return path.join(path.dirname(credentials), namespace);
+}
+/** Directory holding continuation recovery references. */
+export function getContinuationReferenceDirectory(deps = {}) {
+    return getRecoveryReferenceDirectory(CONTINUATION_REFERENCE_NAMESPACE, deps);
+}
+function referenceFileName(epicRunId, ticketKey) {
+    // Hashed so an arbitrary run id or ticket key can never form a path segment.
+    const digest = createHash("sha256").update(`${epicRunId}\u0000${ticketKey}`, "utf8").digest("hex");
+    return `${digest.slice(0, 32)}.json`;
+}
+/** The file one (run, ticket) reference occupies within a namespace. */
+export function getRecoveryReferencePath(namespace, epicRunId, ticketKey, deps = {}) {
+    return path.join(getRecoveryReferenceDirectory(namespace, deps), referenceFileName(epicRunId, ticketKey));
+}
+export function getContinuationReferencePath(epicRunId, ticketKey, deps = {}) {
+    return getRecoveryReferencePath(CONTINUATION_REFERENCE_NAMESPACE, epicRunId, ticketKey, deps);
+}
+/** Read one namespaced reference as parsed JSON, or `null` when absent or unreadable. */
+export async function readRecoveryReferenceFile(namespace, key, deps = {}) {
+    const read = deps.readFile ?? fsReadFile;
+    let text;
+    try {
+        text = (await read(getRecoveryReferencePath(namespace, key.epicRunId, key.ticketKey, deps), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** Durably write one namespaced reference (0700 directory, 0600 file, write-then-rename). */
+export async function writeRecoveryReferenceFile(namespace, key, content, deps = {}) {
+    const mkdir = deps.mkdir ?? fsMkdir;
+    const writeFile = deps.writeFile ?? fsWriteFile;
+    const rename = deps.rename ?? fsRename;
+    await mkdir(getRecoveryReferenceDirectory(namespace, deps), { recursive: true, mode: 0o700 });
+    const target = getRecoveryReferencePath(namespace, key.epicRunId, key.ticketKey, deps);
+    const temp = `${target}.${process.pid}.tmp`;
+    await writeFile(temp, `${JSON.stringify(content, null, 2)}\n`, { mode: 0o600 });
+    await rename(temp, target);
+}
+/** Remove one namespaced reference. Never throws. */
+export async function clearRecoveryReferenceFile(namespace, key, deps = {}) {
+    const unlink = deps.unlink ?? fsUnlink;
+    try {
+        await unlink(getRecoveryReferencePath(namespace, key.epicRunId, key.ticketKey, deps));
+    }
+    catch {
+        // Already gone — nothing to clear.
+    }
+}
+function parseReference(raw) {
+    if (!isRecord(raw) || raw.version !== 1 || !isRecord(raw.bindings))
+        return null;
+    const b = raw.bindings;
+    const bindings = {
+        repoName: String(b.repoName ?? ""),
+        epicRunId: String(b.epicRunId ?? ""),
+        ticketKey: String(b.ticketKey ?? ""),
+        parkedGate: String(b.parkedGate ?? ""),
+        expectedRowVersion: b.expectedRowVersion,
+        expectedHeadSha: (b.expectedHeadSha ?? null),
+        sourceParkGeneration: b.sourceParkGeneration,
+    };
+    if (!bindings.repoName || !bindings.epicRunId || !bindings.ticketKey || !bindings.parkedGate ||
+        !nonNegInt(bindings.expectedRowVersion) || !nonNegInt(bindings.sourceParkGeneration) ||
+        (bindings.expectedHeadSha !== null && !FULL_SHA_RE.test(bindings.expectedHeadSha))) {
+        return null;
+    }
+    const requestId = raw.requestId;
+    const fingerprint = raw.requestFingerprint;
+    if (typeof requestId !== "string" || !REQUEST_ID_RE.test(requestId))
+        return null;
+    if (typeof fingerprint !== "string" || !FINGERPRINT_RE.test(fingerprint))
+        return null;
+    // A stored reference whose fingerprint no longer matches its own bindings was
+    // tampered with or truncated; it is never trusted to authorize a replay.
+    if (computeContinuationFingerprint(bindings) !== fingerprint)
+        return null;
+    return {
+        version: 1,
+        bindings,
+        requestId,
+        requestFingerprint: fingerprint,
+        createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "",
+    };
+}
+/** Read the in-flight reference for a child, or `null` when none (or unusable). */
+export async function readContinuationReference(epicRunId, ticketKey, deps = {}) {
+    const raw = await readRecoveryReferenceFile(CONTINUATION_REFERENCE_NAMESPACE, { epicRunId, ticketKey }, deps);
+    return raw === null ? null : parseReference(raw);
+}
+/** Durably write a reference (0700 directory, 0600 file, write-then-rename). */
+export async function writeContinuationReference(reference, deps = {}, key = reference.bindings) {
+    // ``key`` only names the file (the caller may address the run by its epic key);
+    // the stored bindings are always the exact, fingerprinted ones.
+    await writeRecoveryReferenceFile(CONTINUATION_REFERENCE_NAMESPACE, key, reference, deps);
+}
+/** Remove a child's reference once its outcome is authoritative. Never throws. */
+export async function clearContinuationReference(epicRunId, ticketKey, deps = {}) {
+    await clearRecoveryReferenceFile(CONTINUATION_REFERENCE_NAMESPACE, { epicRunId, ticketKey }, deps);
+}
+/** A fresh request id: a UUID, which satisfies the server's request-id bound. */
+export function newContinuationRequestId() {
+    return randomUUID();
+}
+export function isFullSha(value) {
+    return typeof value === "string" && FULL_SHA_RE.test(value);
+}