@bridge_gpt/mcp-server 0.2.10 → 0.2.13

package/build/conductor/cli.js

@@ -336,13 +336,13 @@ export function parseEmitEventArgs(argv, deps = {}) {
     return { input, json: bools.has("--json"), help: false };
 }
 /** Run the `emit-event` command. Prints the inserted event summary. */
-export function runEmitEventCommand(argv, deps = {}) {
+export async function runEmitEventCommand(argv, deps = {}) {
     const parsed = parseEmitEventArgs(argv, deps);
     if (parsed.help) {
         console.log(getConductorUsage());
         return 0;
     }
-    const result = emitConductorEvent(parsed.input);
+    const result = await emitConductorEvent(parsed.input);
     if (parsed.json) {
         console.log(JSON.stringify(result));
     }
@@ -442,13 +442,13 @@ export function parseSendMessageArgs(argv, deps = {}) {
  * Run `send-message`. Prints compact JSON when `--json` is set; otherwise a
  * sanitized human summary (message id / status / type only — NEVER the payload).
  */
-export function runSendMessageCommand(argv, deps = {}) {
+export async function runSendMessageCommand(argv, deps = {}) {
     const parsed = parseSendMessageArgs(argv, deps);
     if (parsed.help) {
         console.log(getConductorUsage());
         return 0;
     }
-    const result = sendWorkerMessage(parsed.input);
+    const result = await sendWorkerMessage(parsed.input);
     if (parsed.json) {
         console.log(JSON.stringify(result));
     }
@@ -495,13 +495,13 @@ export function parseCheckMessagesArgs(argv) {
  * Run `check-messages`. Prints compact JSON when `--json` is set; otherwise a
  * sanitized human summary (counts + per-message id/type only — NEVER payloads).
  */
-export function runCheckMessagesCommand(argv) {
+export async function runCheckMessagesCommand(argv) {
     const parsed = parseCheckMessagesArgs(argv);
     if (parsed.help) {
         console.log(getConductorUsage());
         return 0;
     }
-    const result = checkWorkerMessages(parsed.input);
+    const result = await checkWorkerMessages(parsed.input);
     if (parsed.json) {
         console.log(JSON.stringify(result));
         return 0;
@@ -590,7 +590,7 @@ export function parseGitHookArgs(argv) {
  * warning) so a conductor producer failure never blocks the git commit/ref update
  * the hook is attached to.
  */
-export function runGitHookCommand(argv) {
+export async function runGitHookCommand(argv) {
     let parsed;
     try {
         parsed = parseGitHookArgs(argv);
@@ -602,7 +602,7 @@ export function runGitHookCommand(argv) {
     }
     try {
         if (parsed.subcommand === "post-commit") {
-            runPostCommitHookProducer();
+            await runPostCommitHookProducer();
             return 0;
         }
         // reference-transaction: read the captured updates from the stdin file.
@@ -625,7 +625,7 @@ export function runGitHookCommand(argv) {
                 }
             }
         }
-        runReferenceTransactionHookProducer({ phase: parsed.phase ?? "", stdin });
+        await runReferenceTransactionHookProducer({ phase: parsed.phase ?? "", stdin });
         return 0;
     }
     catch {
@@ -996,13 +996,13 @@ export async function runSuperviseCommand(argv) {
     return result.exit_code;
 }
 /** Run the explicit `purge` command. Prints deleted row counts. */
-export function runPurgeCommand(argv) {
+export async function runPurgeCommand(argv) {
     const { bools } = tokenizeFlags(argv, new Set(), DIAGNOSTIC_BOOL_FLAGS);
     if (bools.has("--help")) {
         console.log(getConductorUsage());
         return 0;
     }
-    const result = purgeConductorLedger();
+    const result = await purgeConductorLedger();
     if (bools.has("--json")) {
         console.log(JSON.stringify(result));
         return 0;
@@ -1035,7 +1035,7 @@ export async function runConductorCli(argv) {
     try {
         switch (parsed.command) {
             case "emit-event":
-                return runEmitEventCommand(parsed.argv);
+                return await runEmitEventCommand(parsed.argv);
             case "supervise":
                 return await runSuperviseCommand(parsed.argv);
             case "epic-tick":
@@ -1045,17 +1045,17 @@ export async function runConductorCli(argv) {
             case "epic-status":
                 return await runEpicStatusCommand(parsed.argv);
             case "send-message":
-                return runSendMessageCommand(parsed.argv);
+                return await runSendMessageCommand(parsed.argv);
             case "check-messages":
-                return runCheckMessagesCommand(parsed.argv);
+                return await runCheckMessagesCommand(parsed.argv);
             case "doctor":
                 return await runDoctorCommand(parsed.argv);
             case "purge":
-                return runPurgeCommand(parsed.argv);
+                return await runPurgeCommand(parsed.argv);
             case "install-git-hooks":
                 return runInstallGitHooksCommand(parsed.argv);
             case "git-hook":
-                return runGitHookCommand(parsed.argv);
+                return await runGitHookCommand(parsed.argv);
             default:
                 console.error('Error: Unknown command. Run "conductor --help" for usage.');
                 return 1;

package/build/conductor/doctor.js

@@ -7,6 +7,7 @@
  * failure. This module performs NO writes: no hook installation, no schema
  * migration, no event emission, and no scheduler unit creation.
  */
+import { spawnSync } from "node:child_process";
 import { doctorConductorLedger } from "./store.js";
 import { inspectConductorGitHooks } from "./git-hooks.js";
 /**
@@ -105,6 +106,65 @@ export function inspectMcpProfile(env, epicTick) {
     }
     return { resolved_profile, conductor_context_detected, degraded, warnings };
 }
+/**
+ * Read-only probe of the local-merge (F4) capability. Runs `gh --version` and
+ * `gh auth status` (no writes, no merge) and reports whether the host could merge
+ * a PR locally if `policy_json.local_merge.enabled` were set. Never throws.
+ */
+export function inspectLocalMerge(runCommand) {
+    const run = runCommand ??
+        ((cmd, args) => {
+            try {
+                // Static ESM import (this package is "type": "module"): a lazy
+                // require("child_process") throws ReferenceError under ESM, which the
+                // catch swallowed — making `gh` always look unavailable (false negative).
+                //
+                // `gh auth status` hits api.github.com; with no timeout a network stall
+                // (expired token, DNS hiccup, partition) blocks the doctor process until
+                // the OS TCP timeout fires (30s–2min). Bound it to 10s — a hung health
+                // check then simply reports `gh` unavailable. GH_PROMPT_DISABLED keeps an
+                // interactive prompt from holding the process past the timeout.
+                const r = spawnSync(cmd, args, {
+                    encoding: "utf8",
+                    timeout: 10_000,
+                    env: { ...process.env, GH_PROMPT_DISABLED: "1" },
+                });
+                return { status: r.status };
+            }
+            catch {
+                return { status: null };
+            }
+        });
+    let gh_available = false;
+    let gh_authed = false;
+    try {
+        gh_available = run("gh", ["--version"]).status === 0;
+    }
+    catch {
+        gh_available = false;
+    }
+    if (gh_available) {
+        try {
+            gh_authed = run("gh", ["auth", "status"]).status === 0;
+        }
+        catch {
+            gh_authed = false;
+        }
+    }
+    const warnings = [];
+    if (!gh_available) {
+        warnings.push("`gh` is not installed or not on PATH. Local merge (policy_json.local_merge.enabled) " +
+            "cannot run; install the GitHub CLI to enable conductor-driven merges.");
+    }
+    else if (!gh_authed) {
+        warnings.push("`gh` is installed but not authenticated (`gh auth status` failed). Run `gh auth login` " +
+            "to grant the conductor merge permission; otherwise local merge will emit merge.failed/skip.");
+    }
+    // Capability gap only — local merge is opt-in, so an unauthed host is not a hard
+    // failure unless the operator enabled it. Reported as degraded for visibility.
+    const degraded = !gh_available || !gh_authed;
+    return { gh_available, gh_authed, degraded, warnings };
+}
 /**
  * Build the combined read-only doctor report. Composes the existing ledger
  * doctor, git hook inspection, and the epic-tick schedule enablement check.
@@ -116,10 +176,11 @@ export async function buildConductorDoctorReport(deps = {}) {
     const epicTick = await inspectEpicTickSchedule(deps.scheduleDeps, deps.orchestrateList);
     const mcp_profile = inspectMcpProfile(deps.env ?? process.env, epicTick);
     return {
-        ledger: doctorLedger(),
+        ledger: await doctorLedger(),
         git_hooks: inspectHooks(deps.hooksDeps),
         epic_tick: epicTick,
         mcp_profile,
+        local_merge: inspectLocalMerge(deps.runCommand),
     };
 }
 /**
@@ -128,7 +189,7 @@ export async function buildConductorDoctorReport(deps = {}) {
  * status tags consistent with the git hooks section's visual hierarchy.
  */
 export function formatConductorDoctorReport(report) {
-    const { ledger, git_hooks, epic_tick, mcp_profile } = report;
+    const { ledger, git_hooks, epic_tick, mcp_profile, local_merge } = report;
     const lines = [
         "Conductor ledger doctor",
         "───────────────────────",
@@ -193,5 +254,21 @@ export function formatConductorDoctorReport(report) {
         for (const w of mcp_profile.warnings)
             lines.push(`  - ${w}`);
     }
+    lines.push("");
+    lines.push("Local merge capability (optional, opt-in)");
+    lines.push("─────────────────────────────────────────");
+    const ghTag = local_merge.gh_available
+        ? local_merge.gh_authed
+            ? "[OK]"
+            : "[WARNING] not authenticated"
+        : "[WARNING] not installed";
+    lines.push(`gh available:          ${local_merge.gh_available} ${ghTag}`);
+    lines.push(`gh authenticated:      ${local_merge.gh_authed}`);
+    lines.push(`degraded:              ${local_merge.degraded}`);
+    if (local_merge.warnings.length > 0) {
+        lines.push("local merge warnings:");
+        for (const w of local_merge.warnings)
+            lines.push(`  - ${w}`);
+    }
     return lines.join("\n");
 }

package/build/conductor/epic-reconcile.js

@@ -17,7 +17,7 @@
  * All durable mutations go through injected seams so the logic is testable
  * without real network, ledger, or terminal access.
  */
-import { computeReadySet, decideRemediation } from "./epic-state.js";
+import { computeReadySet, decideRemediation, DEFAULT_MAX_SPEC_REVIEW_ATTEMPTS } from "./epic-state.js";
 import { extractMergeActionIdentityFromGateEvent } from "./merge-ledger.js";
 // ---------------------------------------------------------------------------
 // reconcileEpic
@@ -84,21 +84,26 @@ export async function reconcileEpic(access, observed, plan, deps, supervisorConf
     const readySet = computeReadySet(plan, observed.ticket_statuses);
     // Step 3: Dispatch each ready ticket idempotently.
     //
-    // NOTE (BAPI-442): an earlier draft performed a synchronous two-phase
-    // planned → ready_for_review → ready spec re-review here — it spawned
-    // /review-ticket and then dispatched implementation in the SAME tick. That did
-    // not actually gate implementation on the review (the verdict was never
-    // consulted and the review run_id was discarded), and it overloaded the
-    // BAPI-436 "ready_for_review" (awaiting-merge) state, leaving a liveness gap
-    // if the conductor crashed between the CAS and the dispatch. That path has
-    // been removed. `auto_rereview_enabled` is reserved until real review-gating —
-    // a distinct `reviewing` status, review-run correlation, multi-tick re-entry,
-    // and a spec-review verdict signal — is built (BAPI-445). Until then a ready
-    // ticket dispatches implementation directly regardless of the flag.
+    // BAPI-445 — pre-implementation spec re-review sequencing gate (Phase 1). When
+    // `auto_rereview_enabled` is on and the review seam is wired, a `planned` ready
+    // ticket must first pass a spec re-review: this loop advances it
+    // planned → reviewing, spawns the review run under a `:review` dispatch role,
+    // correlates its run_id, and STOPS — implementation does NOT dispatch in the
+    // same tick (honouring the product directive: "wait for review to complete
+    // before implementation begins"). The reviewing → ready (or → blocked) fold
+    // happens on a later tick once the review completes/votes; only THEN does this
+    // loop dispatch implementation. Gating only on `planned` (not `ready`) is
+    // deliberate: a `ready` ticket already passed review (reviewing → ready) or the
+    // flag is off, so re-gating it would loop forever.
     for (const ticketKey of readySet) {
-        if (supervisorConfig?.auto_rereview_enabled) {
-            deps.log(`[epic-reconcile] auto_rereview_enabled is set but review-gating is not yet ` +
-                `implemented (BAPI-445); dispatching ${ticketKey} directly`);
+        const currentStatus = observed.ticket_statuses.get(ticketKey) ?? "planned";
+        if (supervisorConfig?.auto_rereview_enabled &&
+            deps.dispatchReviewSeam &&
+            currentStatus === "planned") {
+            await enterSpecReview(observed, deps, result, escalate, ticketKey);
+            // Either the review was dispatched, or a benign race/failure was logged;
+            // in every case implementation must NOT dispatch this tick.
+            continue;
         }
         let claimResult;
         try {
@@ -155,6 +160,115 @@ export async function reconcileEpic(access, observed, plan, deps, supervisorConf
             result.warnings.push(`correlate-failed for ${ticketKey}: ${safeMsg}`);
         }
     }
+    // Step 3.2: Reviewing recovery (BAPI-445 Phase 1 re-entry). computeReadySet
+    // never surfaces a `reviewing` ticket (it is mid-flight, not ready), so a
+    // ticket whose spec-review run died before completing would be stranded
+    // forever without this pass. Iterate `reviewing` tickets explicitly (mirroring
+    // how the remediation pass iterates `blocked` tickets): if the review run is
+    // dead and the dedicated review-attempt cap is not yet exhausted, reclaim an
+    // attempt-scoped `:review` dispatch key and re-dispatch the review; once the
+    // cap is exhausted, escalate. This uses its OWN attempt counter — it never
+    // touches the BAPI-441 remediation budget.
+    if (supervisorConfig?.auto_rereview_enabled &&
+        deps.dispatchReviewSeam &&
+        deps.readReviewWorkerLiveness) {
+        const dispatchReviewSeam = deps.dispatchReviewSeam;
+        const readReviewWorkerLiveness = deps.readReviewWorkerLiveness;
+        const maxReviewAttempts = supervisorConfig.max_spec_review_attempts ?? DEFAULT_MAX_SPEC_REVIEW_ATTEMPTS;
+        for (const [ticketKey, status] of observed.ticket_statuses) {
+            if (status !== "reviewing")
+                continue;
+            try {
+                const liveness = await readReviewWorkerLiveness(observed.epic_key, ticketKey);
+                if (liveness.alive)
+                    continue; // review still running — wait across ticks
+                const priorAttempts = deps.countReviewAttempts
+                    ? deps.countReviewAttempts(ticketKey)
+                    : 0;
+                if (priorAttempts >= maxReviewAttempts) {
+                    await escalate(observed.epic_key, `spec-review-liveness-exhausted:${ticketKey}`);
+                    deps.log(`[epic-reconcile] spec-review liveness exhausted for ${ticketKey} ` +
+                        `(attempts=${priorAttempts} max=${maxReviewAttempts}) → escalate`);
+                    continue;
+                }
+                // Reclaim a fresh attempt-scoped review dispatch key. `priorAttempts`
+                // (>= 1 once the initial review dispatched) doubles as the next attempt
+                // index, so the key differs from every prior review run's key.
+                const attempt = priorAttempts;
+                let claim;
+                try {
+                    claim = await deps.claimDispatchKey(observed.epic_key, ticketKey, observed.plan_version, "review", attempt);
+                }
+                catch (err) {
+                    const safeMsg = err instanceof Error ? err.constructor.name : "claim error";
+                    result.warnings.push(`review-reclaim-error for ${ticketKey}: ${safeMsg}`);
+                    continue;
+                }
+                if (!claim.ok) {
+                    result.warnings.push(`review-dispatch-key lease-held for ${ticketKey}`);
+                    continue;
+                }
+                if (claim.kind !== "claimed") {
+                    if (claim.kind === "already-exists" && claim.dispatch.run_id === null) {
+                        result.warnings.push(`review-dispatch-orphan: ${ticketKey} has pending review dispatch key with no run_id`);
+                        await escalate(observed.epic_key, `dispatch-orphan:${ticketKey}`);
+                    }
+                    continue;
+                }
+                const dispatchKey = claim.dispatch.dispatch_key;
+                let runId;
+                try {
+                    runId = await dispatchReviewSeam(observed.epic_key, ticketKey, attempt);
+                }
+                catch (err) {
+                    const safeMsg = err instanceof Error ? err.constructor.name : "dispatch error";
+                    result.warnings.push(`review-redispatch-failed for ${ticketKey}: ${safeMsg}`);
+                    continue;
+                }
+                try {
+                    await deps.correlateRunId(dispatchKey, runId);
+                    deps.log(`[epic-reconcile] re-dispatched spec re-review for ${ticketKey} ` +
+                        `run_id=${runId} attempt=${attempt}`);
+                }
+                catch (err) {
+                    const safeMsg = err instanceof Error ? err.constructor.name : "correlate error";
+                    result.warnings.push(`review-correlate-failed for ${ticketKey}: ${safeMsg}`);
+                }
+            }
+            catch (err) {
+                const safeMsg = err instanceof Error ? err.constructor.name : "reviewing recovery error";
+                result.warnings.push(`reviewing-recovery-error for ${ticketKey}: ${safeMsg}`);
+            }
+        }
+    }
+    // Step 3.4: Spec-review verdict gate (BAPI-445 Phase 2). A ticket blocked by a
+    // changes-requested SPEC review is a spec problem, not a code bug: escalate it
+    //
+    // NOTE: this block is reachable only once the verdict EMISSION primitive
+    // (`emitSpecReviewVerdict` in spec-review-producer.ts) is wired into the
+    // review-ticket completion flow so a `spec_review.changes_requested` event is
+    // folded to `blocked` with this reason. Until that Phase 2 integration lands,
+    // no ticket carries the `spec_review.changes_requested` blocked reason and this
+    // pass is a no-op. That is FAIL-SAFE: a completed review with no verdict does
+    // NOT advance `reviewing → ready` (epic-state filters review-run incidental
+    // terminals), so implementation never proceeds without an explicit pass —
+    // a stranded `reviewing` ticket is escalated by the recovery branch above.
+    // once for operator attention and EXCLUDE it from the BAPI-441 remediation pass
+    // below so it never spends the implementation remediation budget (no nudge, no
+    // redispatch, no budget counter increment). Runs independently of the
+    // remediation seams so a spec rejection is always surfaced.
+    const specRejectedTickets = new Set();
+    for (const [ticketKey, status] of observed.ticket_statuses) {
+        if (status !== "blocked")
+            continue;
+        if (observed.ticket_blocked_reasons?.get(ticketKey) !== "spec_review.changes_requested") {
+            continue;
+        }
+        specRejectedTickets.add(ticketKey);
+        await escalate(observed.epic_key, `spec-review-rejected:${ticketKey}`);
+        deps.log(`[epic-reconcile] spec-review changes-requested for ${ticketKey} → escalate ` +
+            `(remediation budget bypassed)`);
+    }
     // Step 3.5: Remediation pass (BAPI-441) — re-act on blocked tickets under
     // budget. Keyed off the folded "blocked" status + per-ticket counters, NOT a
     // computeReadySet change (the ready-set still returns only planned tickets).
@@ -173,6 +287,10 @@ export async function reconcileEpic(access, observed, plan, deps, supervisorConf
         for (const [ticketKey, status] of observed.ticket_statuses) {
             if (status !== "blocked")
                 continue;
+            // BAPI-445: a spec-review rejection was already escalated in Step 3.4 and
+            // must never enter the implementation remediation budget. Skip it here.
+            if (specRejectedTickets.has(ticketKey))
+                continue;
             // Per-ticket try/catch so a single ticket's failure never aborts the pass.
             try {
                 const counters = observed.ticket_remediation_counters?.get(ticketKey) ?? {
@@ -192,7 +310,10 @@ export async function reconcileEpic(access, observed, plan, deps, supervisorConf
                 const attemptKind = decision;
                 // The folding reason frames the nudge (message type + digest). Default to
                 // the review path when the ledger no longer carries the blocking event.
-                const reason = observed.ticket_blocked_reasons?.get(ticketKey) ?? "review.changes_requested";
+                // spec_review.changes_requested is impossible here (skipped above) but
+                // narrow explicitly so the remediation seams keep their tight reason type.
+                const blockedReason = observed.ticket_blocked_reasons?.get(ticketKey);
+                const reason = blockedReason === "ci.failed" ? "ci.failed" : "review.changes_requested";
                 // A nudge needs a worker to address it to. The liveness scan already
                 // resolved the worker id from the same heartbeat that proved the worker
                 // alive; if it is missing we cannot relay, so skip BEFORE recording an
@@ -254,3 +375,79 @@ export async function reconcileEpic(access, observed, plan, deps, supervisorConf
     // Step 5: Post-action waits are scheduled inline above per-dispatch
     return result;
 }
+// ---------------------------------------------------------------------------
+// enterSpecReview (BAPI-445 Phase 1 — planned → reviewing + spawn review run)
+// ---------------------------------------------------------------------------
+/**
+ * Advance a `planned` ready ticket into the pre-implementation spec re-review:
+ * CAS planned → reviewing, claim the `:review` dispatch key, spawn the review
+ * run, and correlate its run_id. Every failure is absorbed as a per-ticket
+ * warning so the rest of the reconcile pass still runs.
+ *
+ * Deliberately does NOT mutate the local `observed.ticket_statuses` map: the CAS
+ * is durable in Postgres (the NEXT tick's snapshot shows `reviewing`), and
+ * leaving the local status as `planned` keeps the same-tick reviewing-recovery
+ * pass from mistaking this freshly-spawned review for a stranded one and
+ * double-dispatching it.
+ */
+async function enterSpecReview(observed, deps, result, escalate, ticketKey) {
+    const dispatchReviewSeam = deps.dispatchReviewSeam;
+    if (!dispatchReviewSeam)
+        return; // caller-guarded; defensive
+    // CAS planned → reviewing (durable). Idempotency: if another tick already
+    // advanced the ticket, the CAS conflicts and we bail benignly.
+    const rowVersion = observed.ticket_row_versions.get(ticketKey) ?? 0;
+    let cas;
+    try {
+        cas = await deps.casTicketStatus(observed.epic_key, ticketKey, rowVersion, "reviewing", observed.plan_version);
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.constructor.name : "cas error";
+        result.warnings.push(`review-cas-error for ${ticketKey}: ${safeMsg}`);
+        return;
+    }
+    if (!cas.ok) {
+        result.warnings.push(`review-cas-conflict advancing ${ticketKey} → reviewing`);
+        return;
+    }
+    // Claim the :review dispatch key (attempt 0), then spawn + correlate.
+    let claim;
+    try {
+        claim = await deps.claimDispatchKey(observed.epic_key, ticketKey, observed.plan_version, "review", 0);
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.constructor.name : "claim error";
+        result.warnings.push(`review-claim-error for ${ticketKey}: ${safeMsg}`);
+        return;
+    }
+    if (!claim.ok) {
+        result.warnings.push(`review-dispatch-key lease-held for ${ticketKey}`);
+        return;
+    }
+    if (claim.kind !== "claimed") {
+        if (claim.kind === "already-exists" && claim.dispatch.run_id === null) {
+            result.warnings.push(`review-dispatch-orphan: ${ticketKey} has pending review dispatch key with no run_id`);
+            await escalate(observed.epic_key, `dispatch-orphan:${ticketKey}`);
+        }
+        return;
+    }
+    const dispatchKey = claim.dispatch.dispatch_key;
+    let runId;
+    try {
+        runId = await dispatchReviewSeam(observed.epic_key, ticketKey, 0);
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.constructor.name : "dispatch error";
+        result.warnings.push(`review-dispatch-failed for ${ticketKey}: ${safeMsg}`);
+        return;
+    }
+    try {
+        await deps.correlateRunId(dispatchKey, runId);
+        deps.log(`[epic-reconcile] dispatched spec re-review for ${ticketKey} ` +
+            `run_id=${runId} (planned → reviewing; implementation deferred)`);
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.constructor.name : "correlate error";
+        result.warnings.push(`review-correlate-failed for ${ticketKey}: ${safeMsg}`);
+    }
+}