@bridge_gpt/mcp-server 0.2.66 → 0.2.67

package/build/install-bridge-conductor.js

@@ -106,6 +106,7 @@
  * The command does NOT persist a repository-level review policy: that is
  * BAPI-694's. The policy selected here is per-run and is reported as such.
  */
+import { PRINTED_INSTALL_COMMAND } from "./printed-remedy-commands.js";
 import { bootstrapConductorSupervisorDefaults, classifySupervisorBootstrapFailure, fetchConductorReadiness, previewConductorSupervisorBootstrap, } from "./conductor/bridge-api-client.js";
 import { CONDUCTOR_OPERATOR_RUNBOOK_POINTER, EXECUTOR_PROVISIONING_GUIDANCE, conductorInstallDoctorExitCode, conductorInstallDoctorHasFatal, formatConductorInstallDoctorReport, } from "./conductor/install-doctor.js";
 import { describeNativeLedgerAvailability, } from "./conductor/doctor.js";
@@ -138,7 +139,7 @@ export function getInstallBridgeConductorUsage() {
     return [
         "Usage: install conductor [options]",
         "",
-        "Bootstrap Epic Conductor v2 for this repository: run the unified read-only",
+        "Bootstrap the Epic Implementer for this repository: run the unified read-only",
         "doctor, write the safe project-default supervisor posture, optionally scaffold",
         "the claude-review workflow, report the capability matrix, and re-run the doctor.",
         "",
@@ -183,9 +184,10 @@ export function getInstallBridgeConductorUsage() {
         "                             approves one named server and has no default.",
         "  --execution-mode <mode>    local | durable (default: durable with",
         "                             --executor-id, otherwise local).",
-        "  --policy-file <path>       Run policy the profile references; an unattended",
-        "                             run needs notify.webhook_url reachable from the",
-        "                             API server (notify.local_sink is not enough).",
+        "  --policy-file <path>       Run policy the profile references. An unattended",
+        "                             run escalates to a notify.webhook_url reachable",
+        "                             from the API server or, with none declared, to the",
+        "                             account's email (notify.local_sink is not enough).",
         "  --dry-run                  Diagnose and preview only. Performs NO writes:",
         "                             no POST, no file write, no host MCP config write,",
         "                             no Git hook write, no install-state or capability",
@@ -208,7 +210,7 @@ export function getInstallBridgeConductorUsage() {
         "nor changed. No file is ever created: when no supported config carries a",
         "a Bridge entry, the run says so and points at the base `install` command.",
         "The MCP server captures its active groups at startup, so a merge activates on",
-        "the next launch — restart your MCP client to see the conductor tools.",
+        "the next launch — restart your MCP client to see the Epic Implementer tools.",
         "",
         "Local observability (a SEPARATE consent): installs or updates this",
         "repository's managed conductor Git hooks (post-commit,",
@@ -939,7 +941,7 @@ export function formatConductorRestartAdvisory(mergedProfile) {
         "client to gain access to the Epic Implementer tools.");
 }
 /** Remediation printed when no supported host config carries a Bridge entry. */
-export const CONDUCTOR_PROFILE_EMPTY_MERGE_REMEDIATION = `run \`npx ${MCP_PACKAGE_NAME} install\` to create and register the host MCP entry, ` +
+export const CONDUCTOR_PROFILE_EMPTY_MERGE_REMEDIATION = `run \`${PRINTED_INSTALL_COMMAND}\` to create and register the host MCP entry, ` +
     "then re-run `install conductor`.";
 /** Remediation printed whenever the managed conductor hooks were not installed. */
 export const CONDUCTOR_HOOKS_MANUAL_REMEDIATION = "re-run `install conductor` and accept the local-observability consent, or run " +

package/build/install-bridge.js

@@ -171,7 +171,7 @@ import { runInstallBridgeConductorCli, } from "./install-bridge-conductor.js";
 // BAPI-1136: the merge-workflow generate-and-PR installer. Domain logic lives in
 // its own module; this file supplies the parser and the process seams.
 import { runMergeWorkflowInstall, } from "./merge-workflow-install.js";
-import { MERGE_WORKFLOW_REMEDY_COMMAND, } from "./conductor/merge-execution-contract.js";
+import { MERGE_WORKFLOW_CODEOWNER_INSTRUCTION, MERGE_WORKFLOW_REMEDY_COMMAND, } from "./conductor/merge-execution-contract.js";
 import { MERGE_WORKFLOW_API_KEY_SECRET_NAME, } from "./merge-workflow-config.js";
 import { runConductorInstallDoctor, EPIC_IMPLEMENTER_PROFILE_TOKEN, } from "./conductor/install-doctor.js";
 import { resolveConductorBridgeApiAccess, } from "./conductor/bridge-api-client.js";
@@ -564,7 +564,7 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "  -h, --help                    Show this help.",
         "",
         "Subcommands:",
-        "  install conductor             Bootstrap Epic Conductor v2 for this repository",
+        "  install conductor             Bootstrap the Epic Implementer for this repository",
         "                                (BAPI-679). Runs a unified READ-ONLY doctor that",
         "                                composes the conductor, executor-preflight,",
         "                                install-status, and executor service-unit",
@@ -1548,7 +1548,7 @@ export function parseMergeWorkflowInstallArgs(argv) {
 /** Usage text for the merge-workflow installer. */
 export function getMergeWorkflowInstallUsage() {
     return [
-        `Usage: ${MERGE_WORKFLOW_REMEDY_COMMAND} --codeowner <@org/team|@user> [--dry-run]`,
+        `Usage: ${MERGE_WORKFLOW_REMEDY_COMMAND} [--dry-run]\n${MERGE_WORKFLOW_CODEOWNER_INSTRUCTION}`,
         "",
         "Generate the Epic Implementer merge workflow plus its CODEOWNERS fragment and",
         "repository-rule guidance, commit them on a managed branch, push with your own",

package/build/phase-context-git-probe.js

@@ -0,0 +1,68 @@
+/**
+ * BAPI-1363 — the bounded git probe behind `get_phase_context`.
+ *
+ * `phase-result-artifacts.ts` is filesystem-only by contract, so the question "is
+ * the recorded checkpoint actually in this worktree's history?" is answered here
+ * and passed to it as plain values. Every call is shell-free, rooted at the
+ * server-resolved project root, and bounded by a short timeout.
+ *
+ * Nothing in this module throws on a git problem. A failed probe degrades to
+ * `"unknown"` with a closed-vocabulary reason, which the artifact layer treats as
+ * "not evidence", so work is redone rather than trusted. Raw stderr, command text,
+ * and paths never leave this module.
+ */
+import { execFile } from "child_process";
+/** Bound on each local git call. */
+export const PHASE_CONTEXT_GIT_TIMEOUT_MS = 5000;
+const FULL_HEX_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+/** Build a runner over `execFileImpl` (the real `execFile` unless a test injects one). */
+export function createPhaseContextGitRunner(execFileImpl = execFile) {
+    return (cwd, args) => new Promise((resolve, reject) => {
+        execFileImpl("git", args, { cwd, shell: false, timeout: PHASE_CONTEXT_GIT_TIMEOUT_MS, windowsHide: true }, (err, stdout) => {
+            if (err)
+                reject(err);
+            else
+                resolve(String(stdout));
+        });
+    });
+}
+/** Closed-vocabulary classification of a failed git call. Raw error text never escapes. */
+function classifyGitFailure(err) {
+    const code = err?.code;
+    return code === "ENOENT" ? "git_unavailable" : "probe_failed";
+}
+/**
+ * Capture HEAD once, then — only when a checkpoint SHA was recorded — probe its
+ * ancestry against that same captured HEAD.
+ *
+ * Only git's ordinary not-ancestor exit (status 1) is `false`. Anything else that
+ * goes wrong is `"unknown"`, never a guess.
+ */
+export async function evaluateCheckpointReachability(options) {
+    const run = options.run ?? createPhaseContextGitRunner();
+    let head;
+    try {
+        head = (await run(options.root, ["rev-parse", "HEAD"])).trim();
+    }
+    catch (err) {
+        const reason = classifyGitFailure(err);
+        return { reachable: "unknown", reason: reason === "git_unavailable" ? reason : "head_unavailable" };
+    }
+    if (!FULL_HEX_SHA.test(head))
+        return { reachable: "unknown", reason: "head_unavailable" };
+    if (options.checkpointSha === undefined) {
+        return { head, reachable: "unknown", reason: "not_evaluated" };
+    }
+    if (!FULL_HEX_SHA.test(options.checkpointSha)) {
+        return { head, reachable: "unknown", reason: "invalid_sha" };
+    }
+    try {
+        await run(options.root, ["merge-base", "--is-ancestor", options.checkpointSha, head]);
+        return { head, reachable: true };
+    }
+    catch (err) {
+        if (err?.code === 1)
+            return { head, reachable: false };
+        return { head, reachable: "unknown", reason: classifyGitFailure(err) };
+    }
+}

package/build/phase-result-artifacts.js

@@ -59,7 +59,7 @@ export const PHASE_RESULT_ARTIFACT_VERSION = 1;
  * it reaches the filesystem, rather than being sanitized into something that
  * silently addresses a different ticket's artifact.
  */
-const TICKET_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+const TICKET_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_]*-\d+$/;
 /** Terminal dispositions that mean "this step is done; do not redo it". */
 const REENTRY_TERMINAL_DISPOSITIONS = new Set([
     "executed",
@@ -74,6 +74,24 @@ const REENTRY_TERMINAL_DISPOSITIONS = new Set([
  */
 export const INLINE_ROUTING_SOURCE = "inline:get_plan_metadata+phase_result_artifacts";
 // ---------------------------------------------------------------------------
+// Shapes
+// ---------------------------------------------------------------------------
+/**
+ * Why a checkpoint is not trusted as commit evidence. Closed vocabulary: these
+ * tokens are the only diagnostics a response may carry about a failed probe, so
+ * no raw git output, path, or credential can ride along.
+ */
+export const CHECKPOINT_STALE_REASONS = [
+    "not_ancestor",
+    "git_unavailable",
+    "invalid_sha",
+    "probe_failed",
+    "head_unavailable",
+    "checkpoint_changed",
+    "coverage_mismatch",
+    "not_evaluated",
+];
+// ---------------------------------------------------------------------------
 // Path safety
 // ---------------------------------------------------------------------------
 function assertValidTicketKey(ticketKey) {
@@ -265,6 +283,9 @@ export async function loadInlinePhaseContext(options) {
     const fingerprint = planFingerprint(metadata);
     let ledger = [];
     const artifactPaths = [];
+    // Latest record index per produce step, within the produce artifact's own list.
+    const produceLatestIndex = new Map();
+    let produceRecordCount = 0;
     // Canonical phase order, not directory order: the ledger is chronological and
     // production always precedes the phases that verify it.
     for (const priorPhase of PLAN_PHASES) {
@@ -277,21 +298,72 @@ export async function loadInlinePhaseContext(options) {
         // Re-check against the CURRENT metadata: an artifact that was valid when
         // written must still describe steps this phase owns under the plan in play now.
         const routable = assertStoredRecordsRoutable(artifact.records, metadata, priorPhase, relativePath);
+        if (priorPhase === "produce") {
+            produceRecordCount = routable.length;
+            routable.forEach((record, index) => produceLatestIndex.set(record.stepId, index));
+        }
         ledger = [...ledger, ...sanitizePlanStepRecords(routable)];
         artifactPaths.push(relativePath);
     }
     const checkpoint = await readInlineCheckpoint(docsDir, ticketKey);
     if (checkpoint)
         artifactPaths.push(checkpointRelativePath(ticketKey));
+    // Reachability is decided by the caller's git probe. Anything other than a
+    // confirmed `true` fails toward redo, and a checkpoint that changed between the
+    // probe and this load is not the one that was probed.
+    let reachable = options.checkpointReachable ?? "unknown";
+    let staleReason;
+    if (reachable === "unknown") {
+        staleReason = options.checkpointUnknownReason ?? "not_evaluated";
+    }
+    else if (reachable === false) {
+        staleReason = "not_ancestor";
+    }
+    if (checkpoint &&
+        reachable !== "unknown" &&
+        options.probedCheckpoint !== undefined &&
+        !sameCheckpoint(options.probedCheckpoint, checkpoint)) {
+        reachable = "unknown";
+        staleReason = "checkpoint_changed";
+    }
+    // A checkpoint covers the produce prefix only when its binding is intact.
+    const coverageIntact = checkpoint !== undefined &&
+        checkpoint.producedRecordCount > 0 &&
+        checkpoint.producedRecordCount <= produceRecordCount &&
+        checkpoint.producePlanFingerprint === fingerprint;
+    const coveredCount = checkpoint && reachable === true && coverageIntact
+        ? checkpoint.producedRecordCount
+        : 0;
+    if (checkpoint &&
+        reachable === true &&
+        checkpoint.producedRecordCount > 0 &&
+        !coverageIntact) {
+        staleReason = "coverage_mismatch";
+    }
     const current = currentLedgerState(ledger);
     const currentRecordsByStep = {};
     const terminalStepIds = [];
+    const uncommittedStepIds = [];
     for (const [stepId, record] of current) {
         currentRecordsByStep[stepId] = record;
-        if (REENTRY_TERMINAL_DISPOSITIONS.has(record.disposition))
+        if (!REENTRY_TERMINAL_DISPOSITIONS.has(record.disposition))
+            continue;
+        const producedAt = produceLatestIndex.get(stepId);
+        if (producedAt !== undefined && producedAt >= coveredCount) {
+            // Latest produce record is not inside the committed prefix: the work it
+            // describes is not evidenced at the evaluated HEAD.
+            uncommittedStepIds.push(stepId);
+        }
+        else {
             terminalStepIds.push(stepId);
+        }
     }
     terminalStepIds.sort((a, b) => a - b);
+    uncommittedStepIds.sort((a, b) => a - b);
+    const checkpointIsEvidence = checkpoint !== undefined && reachable === true && staleReason === undefined;
+    const ledgerNote = uncommittedStepIds.length > 0
+        ? "Produce steps listed in uncommittedStepIds are recorded as done but no reachable checkpoint covers them, so redo them (checking for equivalent existing work first) and do not report them as already done."
+        : "";
     return {
         phase,
         routingSource: INLINE_ROUTING_SOURCE,
@@ -306,12 +378,40 @@ export async function loadInlinePhaseContext(options) {
         ledger,
         currentRecordsByStep,
         terminalStepIds,
+        uncommittedStepIds,
+        ledgerNote,
         unresolved: unresolvedLedgerRecords(ledger),
-        ...(checkpoint ? { checkpoint } : {}),
+        ...(options.evaluatedHead ? { evaluatedHead: options.evaluatedHead } : {}),
+        ...(checkpoint && checkpointIsEvidence
+            ? { checkpoint: { branch: checkpoint.branch, sha: checkpoint.sha } }
+            : {}),
+        ...(checkpoint && !checkpointIsEvidence
+            ? {
+                staleCheckpoint: {
+                    branch: checkpoint.branch,
+                    sha: checkpoint.sha,
+                    reason: staleReason ?? "not_evaluated",
+                },
+            }
+            : {}),
         artifactPaths,
     };
 }
-async function readInlineCheckpoint(docsDir, ticketKey) {
+function sameCheckpoint(a, b) {
+    return (a.branch === b.branch &&
+        a.sha === b.sha &&
+        a.producedRecordCount === b.producedRecordCount &&
+        a.producePlanFingerprint === b.producePlanFingerprint);
+}
+/**
+ * Read and structurally validate the checkpoint artifact.
+ *
+ * Filesystem only. A legacy checkpoint with no coverage fields reads as covering
+ * zero produce records; it is never upgraded by inferring coverage from the
+ * current ledger. Malformed coverage, or a mis-versioned artifact, fails closed.
+ */
+export async function readInlineCheckpoint(docsDir, ticketKey) {
+    ticketKey = assertValidTicketKey(ticketKey);
     const relativePath = checkpointRelativePath(ticketKey);
     const absolutePath = resolveWithinRoot(docsDir, relativePath);
     const parsed = await readJsonArtifact(absolutePath, relativePath);
@@ -333,7 +433,69 @@ async function readInlineCheckpoint(docsDir, ticketKey) {
         artifact.sha.trim() === "") {
         throw new PlanLedgerError(`${relativePath} is missing its branch or sha`);
     }
-    return { branch: artifact.branch, sha: artifact.sha };
+    const hasCount = artifact.produce_record_count !== undefined;
+    const fingerprintValue = artifact.produce_plan_fingerprint;
+    if (!hasCount) {
+        if (fingerprintValue !== undefined && fingerprintValue !== null) {
+            throw new PlanLedgerError(`${relativePath} has a produce fingerprint but no record count`);
+        }
+        return {
+            branch: artifact.branch,
+            sha: artifact.sha,
+            producedRecordCount: 0,
+            producePlanFingerprint: null,
+        };
+    }
+    const count = artifact.produce_record_count;
+    if (typeof count !== "number" || !Number.isInteger(count) || count < 0) {
+        throw new PlanLedgerError(`${relativePath} has an invalid produce_record_count`);
+    }
+    if (count > 0 && (typeof fingerprintValue !== "string" || fingerprintValue === "")) {
+        throw new PlanLedgerError(`${relativePath} covers produce records but has no valid produce_plan_fingerprint`);
+    }
+    if (count === 0 &&
+        fingerprintValue !== undefined &&
+        fingerprintValue !== null &&
+        typeof fingerprintValue !== "string") {
+        throw new PlanLedgerError(`${relativePath} has an invalid produce_plan_fingerprint`);
+    }
+    return {
+        branch: artifact.branch,
+        sha: artifact.sha,
+        producedRecordCount: count,
+        producePlanFingerprint: typeof fingerprintValue === "string" && fingerprintValue !== "" ? fingerprintValue : null,
+    };
+}
+/**
+ * How much of the produce artifact a checkpoint written now would cover.
+ *
+ * Structural validation only, with no plan metadata fetch: the count and the
+ * artifact's stored fingerprint are read as written. An absent artifact covers
+ * zero records, and nothing is created to calculate that.
+ */
+async function readProduceCoverage(docsDir, ticketKey) {
+    const relativePath = phaseResultRelativePath(ticketKey, "produce");
+    const absolutePath = resolveWithinRoot(docsDir, relativePath);
+    const parsed = await readJsonArtifact(absolutePath, relativePath);
+    if (parsed === undefined)
+        return { count: 0, fingerprint: null };
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PlanLedgerError(`${relativePath} is not a phase-result artifact object`);
+    }
+    const artifact = parsed;
+    if (artifact.artifact_version !== PHASE_RESULT_ARTIFACT_VERSION) {
+        throw new PlanLedgerError(`${relativePath} has unsupported artifact_version ${String(artifact.artifact_version)}; expected ${PHASE_RESULT_ARTIFACT_VERSION}`);
+    }
+    if (artifact.ticket_key !== ticketKey || artifact.phase !== "produce") {
+        throw new PlanLedgerError(`${relativePath} does not describe the produce phase of '${ticketKey}'`);
+    }
+    if (typeof artifact.plan_fingerprint !== "string" || artifact.plan_fingerprint === "") {
+        throw new PlanLedgerError(`${relativePath} has no plan_fingerprint`);
+    }
+    if (!Array.isArray(artifact.records)) {
+        throw new PlanLedgerError(`${relativePath} has no records array`);
+    }
+    return { count: artifact.records.length, fingerprint: artifact.plan_fingerprint };
 }
 // ---------------------------------------------------------------------------
 // Writing
@@ -435,6 +597,10 @@ export async function writeInlineCheckpoint(options) {
     if (checkpoint.pushed !== true || checkpoint.remoteMatchesHead !== true) {
         throw new PlanLedgerError("checkpoint must report pushed and remoteMatchesHead true; a checkpoint that is not on origin is not a checkpoint");
     }
+    // Coverage is derived here from the produce artifact as it stands, never taken
+    // from the caller: the push facts above are the caller's claim, but what the
+    // push covers is a fact about the ledger this module owns.
+    const coverage = await readProduceCoverage(docsDir, ticketKey);
     const relativePath = checkpointRelativePath(ticketKey);
     const absolutePath = resolveWithinRoot(docsDir, relativePath);
     const artifact = {
@@ -444,6 +610,8 @@ export async function writeInlineCheckpoint(options) {
         sha,
         pushed: true,
         remote_matches_head: true,
+        produce_record_count: coverage.count,
+        produce_plan_fingerprint: coverage.fingerprint,
     };
     await writeAtomically(absolutePath, relativePath, artifact);
     return { branch, sha, artifactPath: relativePath };