@bridge_gpt/mcp-server 0.2.41 → 0.2.42

package/build/conduct-epic/cut-protocol.js

@@ -0,0 +1,327 @@
+/**
+ * The shared EXACT-CUT protocol and scope-readiness poll (BAPI-843; BAPI-850).
+ *
+ * Extracted from `conduct-epic init` so that the LLM-conductor pilot and the v2
+ * `setup-epic --feature-branch` entry point drive ONE implementation of the
+ * local cut — the same local `git` fetch, the same remote-ref existence check,
+ * the same exact-SHA push, and the same mismatch classification. This module is
+ * the single owner of those operations; neither CLI re-implements any of them.
+ *
+ * What the cut is: the server leases a hold on the canonical parse lock and
+ * names the commit the canonical index actually covers (`cut/begin`); this
+ * module creates `origin/<feature>` at EXACTLY that commit with the operator's
+ * own `git` — never the GitHub App, which is `contents: read` and cannot create
+ * refs — reads the ref back, and asks the server to record it as the scope's
+ * immutable cut (`cut/commit`). The hold is released on every outcome.
+ *
+ * Contract properties, fixed here and relied on by both CLIs:
+ *
+ * - **Never force-updates an existing branch.** The push refspec has no leading
+ *   `+`, so it can only create. A branch that already exists at any commit other
+ *   than the held cut commit is a refusal, never a repoint.
+ * - **Takes an already validated branch and SHA.** Callers validate the branch
+ *   name (`validateBranchName`) and normalize the candidate SHA before calling;
+ *   this module re-proves the SHA shape it pushes, but it is not a parser.
+ * - **No credential ever reaches argv.** The only subprocess is `git`, and its
+ *   arguments are refs, remotes, and SHAs. Bridge and GitHub credentials travel
+ *   only inside the typed client's headers.
+ * - **Every failure is classified, never thrown.** Callers get a discriminated
+ *   outcome with operator-ready sentences and the bounded facts (expected and
+ *   observed SHAs) they need to report; there is nothing to `try/catch`.
+ */
+import { execFile } from "node:child_process";
+import { abandonIndexScopeCut, beginIndexScopeCut, commitIndexScopeCut, getIndexScopeStatus, } from "./bridge-client.js";
+/**
+ * Poll bound for a scope bootstrap, shared by `conduct-epic init` and
+ * `setup-epic`. A seed copies a repository's whole parse cache and the
+ * verifying parse then downloads and change-detects it, so the ceiling is
+ * generous; the interval is what keeps the poll cheap.
+ */
+export const SCOPE_BOOTSTRAP_POLL_INTERVAL_MS = 5_000;
+export const SCOPE_BOOTSTRAP_MAX_POLLS = 240; // ~20 minutes at the interval above.
+/**
+ * Build the default list-argument subprocess runner both CLIs use for `git`.
+ *
+ * One body rather than two copies: `execFile` with `shell: false`, a generous
+ * buffer for porcelain output, and an exit code that never throws — a missing
+ * binary resolves to a non-zero code the caller classifies.
+ */
+export function createExecFileRunCommand() {
+    return (file, args, options) => new Promise((resolve) => {
+        execFile(file, args, {
+            cwd: options?.cwd,
+            // Git porcelain output for a many-worktree checkout can be large.
+            maxBuffer: 16 * 1024 * 1024,
+            encoding: "utf-8",
+            timeout: options?.timeoutMs,
+            // Explicit: arguments are a list, never a concatenated shell string.
+            shell: false,
+        }, (error, stdout, stderr) => {
+            const code = error?.code;
+            resolve({
+                stdout: stdout ?? "",
+                stderr: stderr ?? "",
+                exitCode: typeof code === "number" ? code : error ? 1 : 0,
+            });
+        });
+    });
+}
+/** Run `git` in the operator's checkout. */
+export function runGit(deps, args) {
+    return Promise.resolve(deps.runCommand("git", args, { cwd: deps.cwd }));
+}
+/** The single trimmed line a `git rev-parse`-style command produced, or null. */
+export function firstOutputLine(result) {
+    const value = result.stdout.split("\n")[0]?.trim() ?? "";
+    return value.length === 0 ? null : value;
+}
+/** The SHA from `git ls-remote --heads origin <ref>` output, or null. */
+export function lsRemoteSha(result) {
+    const line = firstOutputLine(result);
+    if (line === null)
+        return null;
+    const sha = line.split(/\s+/)[0]?.trim() ?? "";
+    return sha.length === 0 ? null : sha;
+}
+/**
+ * Normalize a commit SHA to its canonical 40-character lowercase form, or `null`.
+ *
+ * Mirrors the server's own guard so a malformed value is refused HERE — before it
+ * becomes a `git push` refspec — rather than becoming an opaque git error or, far
+ * worse, a ref pushed at something that is not a commit.
+ */
+export function normalizeCommitSha(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return /^[0-9a-f]{40}$/.test(normalized) ? normalized : null;
+}
+/**
+ * Read the head of `origin/<branch>` WITHOUT mutating anything.
+ *
+ * `sha: null` means the branch does not exist on origin. A failed `ls-remote`
+ * (no remote, no network, no git) is its own outcome, never "absent": treating an
+ * unanswered read as absence is how a push lands on top of a branch nobody saw.
+ */
+export async function readRemoteBranchHead(deps, branch) {
+    const result = await runGit(deps, ["ls-remote", "--heads", "origin", `refs/heads/${branch}`]);
+    if (result.exitCode !== 0) {
+        return { ok: false, error: `git ls-remote could not read origin/${branch}.` };
+    }
+    return { ok: true, sha: lsRemoteSha(result) };
+}
+/**
+ * Make sure the exact cut object is resolvable locally, fetching it if needed.
+ *
+ * The cut is pushed BY SHA, so the object must exist in the operator's
+ * repository. A base-branch fetch usually brings it along; when it did not — the
+ * index covers a commit that is no longer an ancestor of the base tip — one
+ * targeted, NON-MUTATING fetch of that SHA is attempted (it updates no ref,
+ * creates no branch, and checks nothing out). Returns `true` when the commit
+ * resolves.
+ */
+export async function ensureCommitResolvableLocally(deps, commitSha) {
+    const present = await runGit(deps, ["rev-parse", "--verify", "--quiet", `${commitSha}^{commit}`]);
+    if (present.exitCode === 0)
+        return true;
+    await runGit(deps, ["fetch", "origin", commitSha]);
+    const retry = await runGit(deps, ["rev-parse", "--verify", "--quiet", `${commitSha}^{commit}`]);
+    return retry.exitCode === 0;
+}
+/**
+ * Drive the exact cut: `cut/begin` → re-check the remote ref under the hold →
+ * create the ref at the held commit (if absent) → read it back → `cut/commit`,
+ * releasing the hold on EVERY outcome.
+ *
+ * Everything between `begin` and the release happens while the SERVER holds the
+ * canonical repository's parse lock, so the commit the index covers cannot move
+ * underneath the ref this module creates.
+ */
+export async function performExactIndexScopeCut(deps, access, request) {
+    const { featureBranch, baseBranch, candidateCommitSha } = request;
+    const lease = await beginIndexScopeCut(access, {
+        featureBranch,
+        baseBranch,
+        candidateCommitSha,
+        epicRunId: request.epicRunId ?? null,
+    }, deps.fetchImpl);
+    if (!lease.ok) {
+        return {
+            ok: false,
+            kind: "begin_refused",
+            failures: [`The index-scope cut could not begin: ${lease.error}`],
+            lease: null,
+            expectedSha: candidateCommitSha,
+            observedSha: null,
+        };
+    }
+    const cut = lease.value;
+    try {
+        if (cut.cut_commit_sha !== candidateCommitSha) {
+            // The server re-read the canonical snapshot under its own hold and named a
+            // different commit. Nothing has been pushed yet, so refusing costs nothing
+            // and continuing would cut the epic at a commit the preflight never checked.
+            return {
+                ok: false,
+                kind: "canonical_moved",
+                failures: [
+                    `The canonical index moved while init was preparing ` +
+                        `(preflight saw ${candidateCommitSha}, the cut hold names ${cut.cut_commit_sha}). Re-run init.`,
+                ],
+                lease: cut,
+                expectedSha: candidateCommitSha,
+                observedSha: cut.cut_commit_sha,
+            };
+        }
+        // Re-check `origin/<feature>` WHILE the hold is active. A preflight
+        // observation is evidence for a refusal, never for a mutation: another
+        // operator may have created the ref in between.
+        const held = await readRemoteBranchHead(deps, featureBranch);
+        if (!held.ok) {
+            return {
+                ok: false,
+                kind: "ls_remote_failed",
+                failures: [held.error],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: null,
+            };
+        }
+        const heldSha = held.sha;
+        if (heldSha !== null && heldSha !== cut.cut_commit_sha) {
+            return {
+                ok: false,
+                kind: "existing_ref_mismatch",
+                failures: [
+                    `origin/${featureBranch} exists at ${heldSha}, which is not the canonical indexed ` +
+                        `commit ${cut.cut_commit_sha}. Delete it or finish the previous run first.`,
+                ],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: heldSha,
+            };
+        }
+        let branchCreated = false;
+        if (heldSha === null) {
+            // Create the ref from the EXACT commit, with the operator's own git. No
+            // local checkout, no branch, no worktree — and deliberately not the GitHub
+            // App, which is `contents: read` and cannot create refs. Not a force push:
+            // the refspec has no leading `+`, so it can only create.
+            const pushed = await runGit(deps, [
+                "push",
+                "origin",
+                `${cut.cut_commit_sha}:refs/heads/${featureBranch}`,
+            ]);
+            if (pushed.exitCode !== 0) {
+                return {
+                    ok: false,
+                    kind: "push_failed",
+                    failures: [
+                        `Could not create origin/${featureBranch} at the canonical indexed commit ${cut.cut_commit_sha}.`,
+                    ],
+                    lease: cut,
+                    expectedSha: cut.cut_commit_sha,
+                    observedSha: null,
+                };
+            }
+            branchCreated = true;
+        }
+        // Read the ref BACK from origin. What matters is what the remote now holds,
+        // not what this process intended to push.
+        const confirmed = await readRemoteBranchHead(deps, featureBranch);
+        const confirmedSha = confirmed.ok ? confirmed.sha : null;
+        if (confirmedSha !== cut.cut_commit_sha) {
+            return {
+                ok: false,
+                kind: "confirm_failed",
+                failures: [`origin/${featureBranch} did not resolve to ${cut.cut_commit_sha} after the push.`],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: confirmedSha,
+            };
+        }
+        const committed = await commitIndexScopeCut(access, { scopeId: cut.scope_id, cutHoldId: cut.cut_hold_id, epicRefCommitSha: confirmedSha }, deps.fetchImpl);
+        if (!committed.ok) {
+            return {
+                ok: false,
+                kind: "commit_refused",
+                failures: [`The index-scope cut could not be recorded: ${committed.error}`],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: confirmedSha,
+            };
+        }
+        return { ok: true, lease: cut, branchCreated, outcome: committed.value.outcome };
+    }
+    finally {
+        // The hold is released on EVERY pre-seed outcome, including the success path
+        // (where the server already released it — abandon is idempotent). The seed
+        // acquires this same canonical lock itself and it is not reentrant, so
+        // handing off while still holding it would deadlock the epic against its own
+        // seed. A failed release never masks the primary failure: it is reported and
+        // the original outcome stands.
+        const abandoned = await abandonIndexScopeCut(access, { scopeId: cut.scope_id, cutHoldId: cut.cut_hold_id }, deps.fetchImpl);
+        if (!abandoned.ok) {
+            deps.errorLog(`announced: the cut hold could not be released cleanly: ${abandoned.error}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Scope-readiness poll (BAPI-843; shared with `setup-epic` by BAPI-850)
+// ---------------------------------------------------------------------------
+/** The operator-facing label for each lifecycle state the poll reports. */
+export const SCOPE_LIFECYCLE_LABELS = Object.freeze({
+    provisioning: "Provisioning",
+    seeding: "Seeding",
+    verifying: "Verifying",
+    ready: "Ready",
+    failed: "Failed",
+});
+/**
+ * Poll a scope's lifecycle until it is `ready`, `failed`, or the bounded wait
+ * elapses, reporting each NEWLY observed lifecycle transition exactly once, in
+ * order, through `onTransition`.
+ *
+ * Readiness is a server-side fact this poll observes rather than concludes from
+ * any request of its own: `ready` is accepted ONLY when the status also proves
+ * `indexed_commit_sha == cut_commit_sha`. A `ready` whose watermark disagrees is
+ * reported as `ready_mismatch` — the control plane contradicting itself, which
+ * is worth refusing rather than proceeding on.
+ *
+ * A transient read failure is not a verdict: the poll keeps going and lets the
+ * bound be the thing that gives up. The interval and cap are the shared
+ * {@link SCOPE_BOOTSTRAP_POLL_INTERVAL_MS} / {@link SCOPE_BOOTSTRAP_MAX_POLLS}.
+ */
+export async function pollIndexScopeLifecycle(deps, access, scopeId, options = {}) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const maxPolls = options.maxPolls ?? SCOPE_BOOTSTRAP_MAX_POLLS;
+    const intervalMs = options.intervalMs ?? SCOPE_BOOTSTRAP_POLL_INTERVAL_MS;
+    let lastState = "unknown";
+    let lastStatus = null;
+    let lastReportedState = null;
+    for (let poll = 0; poll < maxPolls; poll += 1) {
+        await sleep(intervalMs);
+        const status = await getIndexScopeStatus(access, scopeId, deps.fetchImpl);
+        if (!status.ok) {
+            lastState = `unreadable (${status.error})`;
+            continue;
+        }
+        lastStatus = status.value;
+        lastState = status.value.lifecycle_state;
+        if (lastState !== lastReportedState) {
+            lastReportedState = lastState;
+            options.onTransition?.(lastState, status.value);
+        }
+        if (lastState === "ready") {
+            if (status.value.indexed_commit_sha !== null &&
+                status.value.indexed_commit_sha === status.value.cut_commit_sha) {
+                return { kind: "ready", status: status.value };
+            }
+            return { kind: "ready_mismatch", status: status.value };
+        }
+        if (lastState === "failed") {
+            return { kind: "failed", status: status.value, reason: status.value.last_error ?? "unknown" };
+        }
+    }
+    return { kind: "timeout", lastState, lastStatus };
+}

package/build/conduct-epic/spawn.js

@@ -21,6 +21,7 @@
  *   argv would be visible to every process on the machine via `ps`.
  */
 import { powershellSquote, shSquoteInner, } from "../start-tickets.js";
+import { INDEX_SCOPE_ENV_VAR } from "../index-scope-contract.js";
 /** The agents `conduct-epic spawn` may launch. */
 export const CONDUCT_EPIC_AGENTS = ["claude", "cursor-agent"];
 /** The repository's established default agent. */
@@ -52,6 +53,11 @@ export function resolveConductEpicAgent(agent) {
  * Returns the command as a string rather than an argv array because that is what
  * every terminal spawner in this repository consumes — a tab is opened by handing
  * a shell a command line, not by `exec`ing a process.
+ *
+ * BAPI-844: a validated `indexScope` is prefixed as an environment assignment
+ * using the SAME quoting helpers as the rest of the command — the shell's own
+ * environment mechanism, not an argument the agent can see. An absent scope emits
+ * no prefix, so the unscoped command is unchanged byte-for-byte.
  */
 export function buildConductEpicAgentCommand(input) {
     const resolved = resolveConductEpicAgent(input.agent);
@@ -61,15 +67,21 @@ export function buildConductEpicAgentCommand(input) {
         return { ok: false, error: "A worktree path is required to build the agent command." };
     }
     if (input.platform === "win32") {
+        const scopePrefix = input.indexScope
+            ? `$env:${INDEX_SCOPE_ENV_VAR} = ${powershellSquote(input.indexScope)}; `
+            : "";
         return {
             ok: true,
-            command: `Set-Location -LiteralPath ${powershellSquote(input.worktreePath)}; ` +
+            command: `${scopePrefix}Set-Location -LiteralPath ${powershellSquote(input.worktreePath)}; ` +
                 `${resolved.agent} ${powershellSquote(input.prompt)}`,
         };
     }
+    const scopePrefix = input.indexScope
+        ? `export ${INDEX_SCOPE_ENV_VAR}='${shSquoteInner(input.indexScope)}' && `
+        : "";
     return {
         ok: true,
-        command: `cd '${shSquoteInner(input.worktreePath)}' && ` +
+        command: `${scopePrefix}cd '${shSquoteInner(input.worktreePath)}' && ` +
             `${resolved.agent} '${shSquoteInner(input.prompt)}'`,
     };
 }

package/build/conductor/bridge-api-client.js

@@ -1078,6 +1078,13 @@ function parseShadowDispatchFreshnessResult(parsed) {
         indexedCommitSha: typeof obj.indexed_commit_sha === "string" ? obj.indexed_commit_sha : null,
         shadowRepoName: typeof obj.shadow_repo_name === "string" ? obj.shadow_repo_name : null,
         lastError: typeof obj.last_error === "string" ? obj.last_error : null,
+        // Fail closed: only an explicit `true` expires a deadline. An older backend
+        // that does not send the field at all keeps the previous behavior (hold
+        // forever on this side, bounded by the Python reconciler's own park).
+        deadlineExpired: obj.deadline_expired === true,
+        blockedAdvanceReason: typeof obj.blocked_advance_reason === "string" && obj.blocked_advance_reason.length > 0
+            ? obj.blocked_advance_reason
+            : null,
     };
 }
 /**
@@ -1176,7 +1183,26 @@ function parseValidateEpicPlanResult(parsed) {
         insertedEdges < 0) {
         throw new ConductorBridgeApiError("server");
     }
-    return { planHash, serializationEnabled, insertedEdges };
+    // BAPI-848 — the coverage diagnostics are read TOLERANTLY, unlike the fields
+    // above. A server that predates them is not a protocol error, and the CLI must
+    // keep working against one; the defaults below are the honest reading of an
+    // absent field (nothing reported), and the renderer states the scope it was
+    // actually given rather than inventing coverage it cannot see.
+    return {
+        planHash,
+        serializationEnabled,
+        insertedEdges,
+        overlappingPairsFound: safeCount(p["overlapping_pairs_found"]),
+        undeclaredNodes: safeCount(p["undeclared_nodes"]),
+        undeclaredPairsSkipped: safeCount(p["undeclared_pairs_skipped"]),
+        coverageScope: typeof p["coverage_scope"] === "string" && p["coverage_scope"].trim() !== ""
+            ? p["coverage_scope"]
+            : "unreported",
+    };
+}
+/** Non-negative safe integer, or 0 for anything else (absent field included). */
+function safeCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
 }
 /**
  * POST the immutable plan blob to the durable-store endpoint. The blob is

package/build/conductor/cli.js

@@ -18,7 +18,7 @@ import { ConductorValidationError, ConductorEpicTickV1FrozenError, toConductorEr
 import { emitConductorEvent, purgeConductorLedger, sendWorkerMessage, checkWorkerMessages, } from "./store.js";
 import { isDuplicateConstraintError } from "./producer-ledger.js";
 import { SEMANTIC_EVENT_TYPES } from "./taxonomy.js";
-import { installConductorGitHooks } from "./git-hooks.js";
+import { installConductorGitHooks, resolveConductorHookBin } from "./git-hooks.js";
 import { runFileScopeGuardCli } from "./file-scope-guard.js";
 import { runPostCommitHookProducer, runReferenceTransactionHookProducer } from "./git-producer.js";
 import { buildConductorDoctorReport, formatConductorDoctorReport } from "./doctor.js";
@@ -159,6 +159,14 @@ export function getConductorUsage() {
         "  conductor epic-status --epic-key EPIC-405 --json",
     ].join("\n");
 }
+/**
+ * Private diagnostic action (BAPI-772): prints the `conductor-bin.js` path the
+ * EXECUTING artifact resolves for hook installation. It exists so a test can run
+ * `node build/conductor-bin.js __hook-bin` against the real esbuild bundle and
+ * assert the printed path exists — a tsc-emit unit test structurally cannot catch
+ * the bundled-layout bug this ticket fixes. Mirrors `plane __entrypoint`.
+ */
+export const CONDUCTOR_HOOK_BIN_ACTION = "__hook-bin";
 const VALID_COMMANDS = new Set([
     "emit-event",
     "supervise",
@@ -172,6 +180,10 @@ const VALID_COMMANDS = new Set([
     "install-git-hooks",
     "git-hook",
     "file-scope-guard",
+    // Private, and deliberately ABSENT from the usage text: `__hook-bin` exists as
+    // the bundled-artifact regression guard for BAPI-772 (mirroring `plane
+    // __entrypoint`), not as a supported operator workflow.
+    CONDUCTOR_HOOK_BIN_ACTION,
 ]);
 /**
  * Parse the top-level conductor argv into a subcommand (without a CLI
@@ -583,6 +595,11 @@ export async function runDoctorCommand(argv, deps = {}) {
  * Run `install-git-hooks`: install/update the local managed `post-commit` and
  * `reference-transaction` hooks. Returns 0 even when the directory is not a git
  * worktree (degraded optional capability) — never a fatal failure.
+ *
+ * BAPI-772: an unresolvable `conductor-bin.js` IS fatal (exit 1). Writing a hook
+ * that points at a nonexistent binary produced a hook that silently did nothing
+ * on every commit, so the installer now refuses and this command reports the
+ * refusal with the resolver's searched-layout remediation.
  */
 export function runInstallGitHooksCommand(argv) {
     const { bools } = tokenizeFlags(argv, new Set(), DIAGNOSTIC_BOOL_FLAGS);
@@ -591,6 +608,14 @@ export function runInstallGitHooksCommand(argv) {
         return 0;
     }
     const result = installConductorGitHooks();
+    if (!result.ok) {
+        if (bools.has("--json")) {
+            console.error(JSON.stringify({ error: result.error, reason: result.reason }));
+            return 1;
+        }
+        console.error(`Error: conductor git hooks were NOT installed (${result.error}): ${result.reason}`);
+        return 1;
+    }
     if (bools.has("--json")) {
         console.log(JSON.stringify(result));
         return 0;
@@ -600,6 +625,7 @@ export function runInstallGitHooksCommand(argv) {
         "───────────────────────────",
         `is git worktree:  ${result.is_worktree}`,
         `hooks dir:        ${result.hooks_dir ?? "n/a"}`,
+        `conductor bin:    ${result.conductor_bin}`,
     ];
     for (const hook of result.installed) {
         lines.push(`  ${hook.name}: ${hook.action}${hook.warning ? ` (${hook.warning})` : ""}`);
@@ -612,6 +638,21 @@ export function runInstallGitHooksCommand(argv) {
     console.log(lines.join("\n"));
     return 0;
 }
+/**
+ * Run the private `__hook-bin` diagnostic: resolve the hook binary from the
+ * executing artifact and print ONLY that canonical path to stdout, so artifact-
+ * level automation can consume it directly. A failed resolution prints the
+ * sanitized resolver reason to stderr and returns 1 — never a stack trace.
+ */
+export function runHookBinDiagnosticCommand() {
+    const resolution = resolveConductorHookBin();
+    if (!resolution.ok) {
+        console.error(`conductor hook bin UNRESOLVED: ${resolution.reason}`);
+        return 1;
+    }
+    console.log(resolution.path);
+    return 0;
+}
 const GIT_HOOK_VALUE_FLAGS = new Set(["--phase", "--stdin-file"]);
 const GIT_HOOK_BOOL_FLAGS = new Set(["--help"]);
 /**
@@ -1104,6 +1145,10 @@ export async function runConductorCli(argv) {
                 return runInstallGitHooksCommand(parsed.argv);
             case "git-hook":
                 return await runGitHookCommand(parsed.argv);
+            case CONDUCTOR_HOOK_BIN_ACTION:
+                // Dispatched before any MCP server construction or store access: the
+                // guard must be able to run against a bundle whose ledger is absent.
+                return runHookBinDiagnosticCommand();
             case "file-scope-guard":
                 // BAPI-507 (N-2): warn-only worker file-scope guard. Always exits 0.
                 return runFileScopeGuardCli();