@bridge_gpt/mcp-server 0.2.10 → 0.2.13

package/build/conductor/git-producer.js

@@ -79,7 +79,7 @@ export function buildWorktreeChangedEventInput(context, updates, phase) {
  * dedupe by `repo + commit_sha`, and emit best-effort. Returns a
  * success-compatible result for every failure mode so the commit is never blocked.
  */
-export function runPostCommitHookProducer(deps = {}) {
+export async function runPostCommitHookProducer(deps = {}) {
     const getContext = deps.getContext ?? getGitWorktreeContext;
     const readMetadata = deps.readMetadata ?? readHeadCommitMetadata;
     const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
@@ -90,7 +90,7 @@ export function runPostCommitHookProducer(deps = {}) {
             return { ok: true, emitted: false, reason: "no-head-commit" };
         }
         const input = buildCommitCreatedEventInput(context, metadata);
-        const decision = emitIfNew(input, {
+        const decision = await emitIfNew(input, {
             event_type: "git.commit_created",
             repo: context.repo,
             commit_sha: metadata.sha,
@@ -109,7 +109,7 @@ export function runPostCommitHookProducer(deps = {}) {
  * success-compatible result for every failure mode so the ref update is never
  * blocked.
  */
-export function runReferenceTransactionHookProducer(args, deps = {}) {
+export async function runReferenceTransactionHookProducer(args, deps = {}) {
     const getContext = deps.getContext ?? getGitWorktreeContext;
     const parseUpdates = deps.parseUpdates ?? parseReferenceTransactionUpdates;
     const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
@@ -124,7 +124,7 @@ export function runReferenceTransactionHookProducer(args, deps = {}) {
         const context = getContext({ cwd: deps.cwd, env: deps.env });
         const input = buildWorktreeChangedEventInput(context, updates, args.phase);
         const refUpdatesHash = stableJsonHash({ phase: args.phase, updates });
-        const decision = emitIfNew(input, {
+        const decision = await emitIfNew(input, {
             event_type: "worktree.changed",
             repo: context.repo,
             ref_updates_hash: refUpdatesHash,

package/build/conductor/local-merge.js

@@ -0,0 +1,212 @@
+/**
+ * Client-side (local) conductor merge executor (F4).
+ *
+ * Performs the GitHub merge in the epic-tick process using the agent's OWN
+ * granted `gh` credentials, instead of the hosted Bridge API merge route (which
+ * would require the backend to hold global GitHub write scope — the reason a
+ * smoke-test merge failed with `provider_unauthorized`). Opt-in only: the runtime
+ * selects this executor when `policy_json.local_merge.enabled === true`.
+ *
+ * It mirrors the backend merge guard's decision order — approval precondition →
+ * re-read PR head (drift / not-open guard) → revalidate required CI for the EXACT
+ * head SHA → provider merge — and returns the SAME `merge.*` ledger events the
+ * backend route returns, so the rest of {@link processGateMetMerge} is unchanged.
+ *
+ * Subprocess safety: argument arrays (never a shell string), a validated numeric
+ * PR number, a merge method from a fixed allowlist, `GH_PROMPT_DISABLED` to avoid
+ * interactive hangs, and no token/secret ever logged. Default OFF everywhere.
+ */
+import { spawnSync } from "child_process";
+import { pollCiChecksForCommit, } from "./bridge-api-client.js";
+const MERGE_METHODS = new Set(["squash", "merge", "rebase"]);
+/**
+ * Hard wall-clock cap on every `gh` subprocess. The epic-tick runs in a single
+ * stateless process with no separate scheduler thread — a `gh` call that hangs
+ * (network stall, an auth prompt that slips past GH_PROMPT_DISABLED) would block
+ * the Node event loop indefinitely, freezing the whole tick. Killing at 60s
+ * yields a `timedOut` result the executor maps to a distinct `*_timeout` reason.
+ */
+const DEFAULT_COMMAND_TIMEOUT_MS = 60_000;
+/** Coerce an untrusted method value to a safe allowlisted method (default squash). */
+export function resolveLocalMergeMethod(value) {
+    return typeof value === "string" && MERGE_METHODS.has(value)
+        ? value
+        : "squash";
+}
+function defaultRunCommand(cmd, args, env) {
+    const result = spawnSync(cmd, args, {
+        encoding: "utf8",
+        env: { ...process.env, ...env },
+        timeout: DEFAULT_COMMAND_TIMEOUT_MS,
+    });
+    // On timeout spawnSync kills the child (status: null, signal: "SIGTERM") and
+    // sets `error.code === "ETIMEDOUT"`. Surface that as a first-class flag.
+    const timedOut = result.error?.code === "ETIMEDOUT" ||
+        result.signal === "SIGTERM";
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        timedOut,
+    };
+}
+function buildResponse(request, status, reason, terminal, ledgerEvents) {
+    return {
+        action_key: request.action_key,
+        repo_name: request.repo_name,
+        pr_number: request.pr_number,
+        expected_head_sha: request.expected_head_sha,
+        status,
+        reason,
+        terminal,
+        ledger_events: ledgerEvents,
+    };
+}
+/**
+ * Decide whether every required CI check is green for the polled head SHA. When
+ * the gate lists no required checks, fall back to the poll's `all_passed` flag.
+ * Defensive against the poll response's exact shape: a check counts as green if
+ * any of `conclusion==="success"`, `status==="success"`, `green===true`, or
+ * `bucket==="pass"`.
+ */
+export function allRequiredChecksGreen(pollResponse, requiredChecks) {
+    if (pollResponse === null || typeof pollResponse !== "object")
+        return false;
+    let obj = pollResponse;
+    // pollCiChecksForCommit returns the `{available, reason, action, detail}`
+    // envelope; checks/all_passed live under `detail`. Unwrap it (envelope-
+    // tolerant, mirroring normalizeCiSnapshot) — reading the top level alone made
+    // every required check look missing → merge always failed ci_not_green.
+    const maybeDetail = obj.detail;
+    if (maybeDetail &&
+        typeof maybeDetail === "object" &&
+        (Array.isArray(maybeDetail.checks) ||
+            "all_passed" in maybeDetail)) {
+        obj = maybeDetail;
+    }
+    const rawChecks = Array.isArray(obj.checks) ? obj.checks : [];
+    if (requiredChecks.length === 0) {
+        return obj.all_passed === true;
+    }
+    const byName = new Map();
+    for (const c of rawChecks) {
+        const name = typeof c.name === "string" ? c.name : null;
+        if (name !== null)
+            byName.set(name, c);
+    }
+    const isGreen = (c) => {
+        if (!c)
+            return false;
+        const conclusion = typeof c.conclusion === "string" ? c.conclusion.toLowerCase() : "";
+        const status = typeof c.status === "string" ? c.status.toLowerCase() : "";
+        const bucket = typeof c.bucket === "string" ? c.bucket.toLowerCase() : "";
+        return c.green === true || conclusion === "success" || status === "success" || bucket === "pass";
+    };
+    return requiredChecks.every((name) => isGreen(byName.get(name)));
+}
+/**
+ * Build a `(access, request) => Promise<ConductorMergeResponse>` that performs the
+ * merge locally via `gh`. Drop-in replacement for `mergePullRequestForGate` used
+ * by {@link processGateMetMerge}'s `merge` seam.
+ */
+export function makeLocalMergeExecutor(options = {}, deps = {}) {
+    const method = resolveLocalMergeMethod(options.method);
+    const run = deps.runCommand ?? defaultRunCommand;
+    const pollCi = deps.pollCi ?? pollCiChecksForCommit;
+    // Non-interactive + no-noise env for gh; the caller's env (incl. any token)
+    // is overlaid first, then the safety pins.
+    const ghEnv = {
+        ...deps.env,
+        GH_PROMPT_DISABLED: "1",
+        GH_NO_UPDATE_NOTIFIER: "1",
+    };
+    return async (access, request) => {
+        const pr = request.pr_number;
+        const expectedSha = request.expected_head_sha;
+        const requiredChecks = request.gate?.required_checks ?? [];
+        const baseDetails = {
+            action_key: request.action_key,
+            repo: request.repo_name,
+            pr_number: pr,
+            expected_head_sha: expectedSha,
+            merge_method: method,
+            executor: "local",
+        };
+        const fail = (reason) => buildResponse(request, "failed", reason, false, [
+            { type: "merge.failed", status: "failed", reason, details: baseDetails },
+        ]);
+        // 1. Approval precondition — never merge when approval is required.
+        if (options.approvalRequired) {
+            return buildResponse(request, "pending_approval", "local_merge_approval_required", false, [
+                {
+                    type: "merge.pending_approval",
+                    status: "pending_approval",
+                    reason: "local_merge_approval_required",
+                    details: baseDetails,
+                },
+            ]);
+        }
+        // 2. Re-read PR head + open-state (head-drift / closed guard).
+        const view = run("gh", ["pr", "view", String(pr), "--json", "headRefOid,state"], ghEnv);
+        if (view.timedOut)
+            return fail("gh_pr_view_timeout");
+        if (view.status !== 0)
+            return fail("gh_pr_view_failed");
+        let headOid;
+        let state;
+        try {
+            const parsed = JSON.parse(view.stdout);
+            headOid = parsed.headRefOid;
+            state = parsed.state;
+        }
+        catch {
+            return fail("gh_pr_view_unparseable");
+        }
+        if (typeof state === "string" && state.toUpperCase() !== "OPEN")
+            return fail("pr_not_open");
+        if (typeof headOid !== "string" || headOid.toLowerCase() !== expectedSha.toLowerCase()) {
+            return fail("head_drift");
+        }
+        // 3. Revalidate required CI green for the exact head SHA.
+        let pollResponse;
+        try {
+            pollResponse = await pollCi(access, expectedSha);
+        }
+        catch {
+            return fail("ci_poll_failed");
+        }
+        if (!allRequiredChecksGreen(pollResponse, requiredChecks))
+            return fail("ci_not_green");
+        // 4. Provider merge.
+        const merge = run("gh", ["pr", "merge", String(pr), `--${method}`, "--match-head-commit", expectedSha], ghEnv);
+        if (merge.status !== 0) {
+            const mergeFailReason = merge.timedOut ? "gh_merge_timeout" : "gh_merge_failed";
+            return buildResponse(request, "failed", mergeFailReason, false, [
+                { type: "merge.attempted", status: "attempted", details: baseDetails },
+                { type: "merge.failed", status: "failed", reason: mergeFailReason, details: baseDetails },
+            ]);
+        }
+        // 5. Best-effort resolve the squash/merge commit SHA for the audit trail.
+        let mergeCommitSha;
+        const post = run("gh", ["pr", "view", String(pr), "--json", "mergeCommit"], ghEnv);
+        if (post.status === 0) {
+            try {
+                const oid = JSON.parse(post.stdout)?.mergeCommit;
+                if (oid && typeof oid === "object" && typeof oid.oid === "string") {
+                    mergeCommitSha = oid.oid;
+                }
+            }
+            catch {
+                /* best-effort only */
+            }
+        }
+        const succeededDetails = {
+            ...baseDetails,
+            ...(mergeCommitSha ? { merge_commit_sha: mergeCommitSha } : {}),
+        };
+        return buildResponse(request, "succeeded", null, true, [
+            { type: "merge.attempted", status: "attempted", details: baseDetails },
+            { type: "merge.succeeded", status: "succeeded", details: succeededDetails },
+        ]);
+    };
+}

package/build/conductor/merge-ledger.js

@@ -103,9 +103,9 @@ export function makeMergeEventId(eventType, actionKey) {
     const h = createHash("sha256").update(`${eventType}:${actionKey}`).digest("hex");
     return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
 }
-function lookupMergeEventByActionKey(eventType, actionKey, deps) {
+async function lookupMergeEventByActionKey(eventType, actionKey, deps) {
     const openDb = deps.openDb ?? (() => openReadonlyConductorDatabaseIfExists());
-    const db = openDb();
+    const db = await openDb();
     if (!db)
         return false;
     try {
@@ -126,7 +126,7 @@ function lookupMergeEventByActionKey(eventType, actionKey, deps) {
  * the action key. Only `merge.succeeded` is terminal — `merge.failed` and
  * `merge.dry_run` are never terminal.
  */
-export function hasTerminalMergeSucceeded(actionKey, deps = {}) {
+export async function hasTerminalMergeSucceeded(actionKey, deps = {}) {
     return lookupMergeEventByActionKey("merge.succeeded", actionKey, deps);
 }
 /**
@@ -134,7 +134,7 @@ export function hasTerminalMergeSucceeded(actionKey, deps = {}) {
  * Dry-run is audit/hygiene only and is NEVER treated as terminal — a later real
  * merge for the same PR/head/gate may still proceed if the repo flag is enabled.
  */
-export function hasMergeDryRun(actionKey, deps = {}) {
+export async function hasMergeDryRun(actionKey, deps = {}) {
     return lookupMergeEventByActionKey("merge.dry_run", actionKey, deps);
 }
 /**
@@ -142,7 +142,7 @@ export function hasMergeDryRun(actionKey, deps = {}) {
  * action key. Pending approval is NEVER terminal — the supervisor must re-dispatch
  * until the backend reports approval (returning `merge.attempted` + `merge.succeeded`).
  */
-export function hasMergePendingApproval(actionKey, deps = {}) {
+export async function hasMergePendingApproval(actionKey, deps = {}) {
     return lookupMergeEventByActionKey("merge.pending_approval", actionKey, deps);
 }
 /** Heuristically detect a SQLite duplicate-id / UNIQUE constraint failure. */
@@ -167,7 +167,7 @@ function isDuplicateConstraintError(error) {
  * outcome fields live under `details`). A duplicate UNIQUE-constraint failure is
  * classified as `{ emitted: false, reason: "duplicate" }` rather than thrown.
  */
-export function emitMergeLedgerEventIfNew(input, deps = {}) {
+export async function emitMergeLedgerEventIfNew(input, deps = {}) {
     const emitEvent = deps.emitEvent ?? emitConductorEvent;
     const eventId = makeMergeEventId(input.type, input.action_key);
     const event = {
@@ -186,7 +186,7 @@ export function emitMergeLedgerEventIfNew(input, deps = {}) {
         },
     };
     try {
-        const result = emitEvent(event);
+        const result = await emitEvent(event);
         return { emitted: true, event_id: eventId, event: result.event };
     }
     catch (error) {

package/build/conductor/pr-ci-producer.js

@@ -9,7 +9,7 @@
  * check. All event types come from the existing conductor taxonomy and use only
  * allowlisted top-level data keys.
  */
-import { GIT_CI_PRODUCER, } from "./git-ci-types.js";
+import { GIT_CI_PRODUCER, REVIEW_STATE, } from "./git-ci-types.js";
 import { evaluateDoneGate, normalizeCiSnapshot, parseDoneGateConfig } from "./done-gate.js";
 import { observeReviewWithResolved } from "./pr-review-producer.js";
 import { fetchEffectiveSupervisorSetup, fetchActiveEpicRuns, fetchEpicRunState, pollCiChecksForCommit, resolveConductorBridgeApiAccess, } from "./bridge-api-client.js";
@@ -149,7 +149,7 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
         reason: "observed",
     };
     // 1. PR opened telemetry (independent of CI / gate).
-    const prDecision = emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
+    const prDecision = await emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
         event_type: "git.pr_opened",
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -174,7 +174,7 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
     }
     else {
         result.ci_status = ciEvent.type === "ci.passed" ? "passed" : "failed";
-        const ciDecision = emitIfNew(ciEvent, {
+        const ciDecision = await emitIfNew(ciEvent, {
             event_type: ciEvent.type,
             repo: binding.repo,
             pr_number: binding.pr_number,
@@ -210,7 +210,7 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
     result.gate_met = true;
     const gateEvent = buildGateMetEventInput(binding, evaluation, run_id, worker_id);
     if (gateEvent !== null) {
-        const gateDecision = emitIfNew(gateEvent, {
+        const gateDecision = await emitIfNew(gateEvent, {
             event_type: "gate.met",
             repo: binding.repo,
             pr_number: binding.pr_number,
@@ -409,7 +409,7 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
         gate_emitted: false,
         reason: "observed",
     };
-    const prDecision = emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
+    const prDecision = await emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
         event_type: "git.pr_opened",
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -423,7 +423,7 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
         return result;
     }
     result.ci_status = ciEvent.type === "ci.passed" ? "passed" : "failed";
-    const ciDecision = emitIfNew(ciEvent, {
+    const ciDecision = await emitIfNew(ciEvent, {
         event_type: ciEvent.type,
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -455,13 +455,23 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
                 rawConfig = undefined;
             }
             const gateConfig = parseDoneGateConfig(rawConfig);
-            if (gateConfig.enabled && gateConfig.valid) {
+            // F6: this poll-driven path observes CI only — it has NO review snapshot
+            // (unlike observeWithResolved, which fetches one via observeReviewWithResolved).
+            // A composite gate with any review_state condition can therefore never be
+            // satisfied here and would only fail closed silently. Rather than pretend to
+            // be a gate path, refuse to evaluate review-gated configs and defer to
+            // `wait_for_done_gate` (the complete observer). CI-only gates still emit here.
+            const requiresReview = gateConfig.conditions.some((c) => c.type === REVIEW_STATE);
+            if (gateConfig.enabled && gateConfig.valid && requiresReview) {
+                result.reason = "review-gated config: gate.met deferred to wait_for_done_gate (poll path is CI-only)";
+            }
+            if (gateConfig.enabled && gateConfig.valid && !requiresReview) {
                 const evaluation = evaluateDoneGate(gateConfig, binding, snapshot, now());
                 if (evaluation.met) {
                     result.gate_met = true;
                     const gateEvent = buildGateMetEventInput(binding, evaluation, run_id, worker_id);
                     if (gateEvent !== null) {
-                        const gateDecision = emitIfNew(gateEvent, {
+                        const gateDecision = await emitIfNew(gateEvent, {
                             event_type: "gate.met",
                             repo: binding.repo,
                             pr_number: binding.pr_number,

package/build/conductor/pr-review-producer.js

@@ -99,13 +99,13 @@ export async function observeReviewWithResolved(binding, access, gateConfig, dep
     };
     if (evalResult.changesRequested) {
         const event = buildReviewObservationEventInput(binding, snapshot, REVIEW_CHANGES_REQUESTED, evalResult.reason, run_id, worker_id);
-        const decision = emitIfNew(event, { event_type: REVIEW_CHANGES_REQUESTED, ...baseDimensions });
+        const decision = await emitIfNew(event, { event_type: REVIEW_CHANGES_REQUESTED, ...baseDimensions });
         result.review_changes_requested_emitted = decision.emitted;
         result.reason = "review changes requested";
     }
     else if (evalResult.passed) {
         const event = buildReviewObservationEventInput(binding, snapshot, REVIEW_PASSED, evalResult.reason, run_id, worker_id);
-        const decision = emitIfNew(event, { event_type: REVIEW_PASSED, ...baseDimensions });
+        const decision = await emitIfNew(event, { event_type: REVIEW_PASSED, ...baseDimensions });
         result.review_passed_emitted = decision.emitted;
         result.reason = "review passed";
     }

package/build/conductor/producer-ledger.js

@@ -59,13 +59,13 @@ const LEDGER_SCAN_MAX_PAGES = 200;
  * full details object is visible. Malformed/non-matching events are skipped; the
  * scan never throws.
  */
-export function eventAlreadyExists(dedupeKey, deps = {}) {
+export async function eventAlreadyExists(dedupeKey, deps = {}) {
     const pollEvents = deps.pollEvents ?? ((options) => pollConductorEvents(options));
     let sinceSeq = 1;
     for (let page = 0; page < LEDGER_SCAN_MAX_PAGES; page += 1) {
         let result;
         try {
-            result = pollEvents({ since_seq: sinceSeq, data_mode: "full", limit: LEDGER_SCAN_PAGE_LIMIT });
+            result = await pollEvents({ since_seq: sinceSeq, data_mode: "full", limit: LEDGER_SCAN_PAGE_LIMIT });
         }
         catch {
             return false;
@@ -95,10 +95,10 @@ export function eventAlreadyExists(dedupeKey, deps = {}) {
  * under `data.details`, then emits. A duplicate-id constraint thrown by a racing
  * producer is classified as a duplicate rather than surfaced as a failure.
  */
-export function emitConductorEventIfNew(input, dimensions, deps = {}) {
+export async function emitConductorEventIfNew(input, dimensions, deps = {}) {
     const emitEvent = deps.emitEvent ?? emitConductorEvent;
     const dedupeKey = makeProducerDedupeKey(dimensions);
-    if (eventAlreadyExists(dedupeKey, deps)) {
+    if (await eventAlreadyExists(dedupeKey, deps)) {
         return { emitted: false, reason: "duplicate" };
     }
     const eventId = makeStableProducerEventId(dedupeKey);
@@ -113,7 +113,7 @@ export function emitConductorEventIfNew(input, dimensions, deps = {}) {
         details: { ...existingDetails, dedupe_key: dedupeKey },
     };
     try {
-        emitEvent({ ...input, id: eventId, data });
+        await emitEvent({ ...input, id: eventId, data });
         return { emitted: true, event_id: eventId };
     }
     catch (error) {

package/build/conductor/spec-review-producer.js

@@ -0,0 +1,88 @@
+/**
+ * Pre-implementation SPEC re-review verdict production (BAPI-445 Phase 2).
+ *
+ * Emits the spec re-review verdict (`spec_review.passed` /
+ * `spec_review.changes_requested`) into the LOCAL conductor ledger, correlated
+ * to the spec-review run via `BAPI_CONDUCTOR_RUN_ID`. The Epic Supervisor's
+ * reconcile pass folds these signals: `passed` → `reviewing → ready` (proceed to
+ * implementation), `changes_requested` → `blocked` (escalate; do NOT implement).
+ *
+ * Why this is a LOCAL producer, not a backend webhook change: the conductor
+ * ledger is a per-worker SQLite file (`~/.config/bridge/events.db`). The
+ * Heroku-hosted Bridge API backend has no access to it. So — exactly like the
+ * PR-review producer ({@link ./pr-review-producer}) — the verdict is emitted by
+ * the LOCAL spec-review run, whose environment carries `BAPI_CONDUCTOR_RUN_ID`
+ * (injected at dispatch time by {@link ../review-tickets}.orchestrateReviewTickets
+ * when an epic identity is present). This corrects the original BAPI-445 plan,
+ * which proposed emitting from the backend review webhook
+ * (`code_writer_jira.py`) — that path cannot reach the worker-local ledger.
+ *
+ * The verdict family is kept DISTINCT from the PR-review `review.passed` /
+ * `review.changes_requested` verdicts (BAPI-440) so a spec-review outcome is
+ * never mis-folded as the implementation PR's review state (Obstacle 2).
+ */
+// TODO(BAPI-445 Phase 2 integration): `emitSpecReviewVerdict` is the verdict
+// EMISSION primitive but currently has no caller. Until the review-ticket
+// completion flow derives a pass/changes-requested decision from the critique
+// and calls this function, no `spec_review.*` event is ever written.
+//
+// This is FAIL-SAFE, not fail-open: epic-state.ts `rebuildObservedState` filters
+// a review run's incidental terminals (run.stopped, …) out of folding, so a
+// completed review with NO verdict leaves the ticket in `reviewing` rather than
+// advancing it to `ready` and dispatching implementation. The reconcile
+// liveness-recovery / escalation path then surfaces the stranded ticket for
+// operator attention. Only an explicit `spec_review.passed` proceeds and only
+// `spec_review.changes_requested` blocks — so wiring this producer in is what
+// makes the gate ACTIVE; without it, opted-in tickets hold safely instead of
+// silently implementing against the review's wishes.
+import { SPEC_REVIEW_CHANGES_REQUESTED, SPEC_REVIEW_PASSED } from "./git-ci-types.js";
+import { emitConductorEventIfNew } from "./producer-ledger.js";
+/** Producer + observed-via identifiers stamped onto emitted spec-review events. */
+export const SPEC_REVIEW_PRODUCER = "spec-review-producer";
+/**
+ * Build a `spec_review.passed` / `spec_review.changes_requested` event input for
+ * a ticket's spec re-review verdict, correlated to the review run via `runId`.
+ */
+export function buildSpecReviewVerdictEventInput(ticketKey, verdict, reason, runId = null, workerId = null) {
+    const eventType = verdict === "passed" ? SPEC_REVIEW_PASSED : SPEC_REVIEW_CHANGES_REQUESTED;
+    return {
+        source: "review",
+        type: eventType,
+        subject: ticketKey,
+        run_id: runId,
+        worker_id: workerId,
+        producer: SPEC_REVIEW_PRODUCER,
+        observed_via: SPEC_REVIEW_PRODUCER,
+        data: {
+            summary: verdict === "passed"
+                ? `Spec re-review passed for ${ticketKey}`
+                : `Spec re-review requested changes for ${ticketKey}`,
+            status: verdict,
+            details: { ticket_key: ticketKey, reason },
+        },
+    };
+}
+/**
+ * Emit a spec re-review verdict for `ticketKey` into the local conductor ledger,
+ * correlated to the spec-review run via `BAPI_CONDUCTOR_RUN_ID` (read from the
+ * injected env). Idempotent: deduped by `event_type` + `run_id`, so re-emitting
+ * the same run's verdict is a no-op. A missing run id still emits (uncorrelated)
+ * but is logged in the result so callers can detect the misconfiguration.
+ */
+export async function emitSpecReviewVerdict(ticketKey, verdict, reason, deps = {}) {
+    const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
+    const run_id = deps.env?.BAPI_CONDUCTOR_RUN_ID?.trim() || null;
+    const worker_id = deps.env?.BAPI_CONDUCTOR_WORKER_ID?.trim() || null;
+    const eventType = verdict === "passed" ? SPEC_REVIEW_PASSED : SPEC_REVIEW_CHANGES_REQUESTED;
+    const event = buildSpecReviewVerdictEventInput(ticketKey, verdict, reason, run_id, worker_id);
+    const decision = await emitIfNew(event, {
+        event_type: eventType,
+        run_id: run_id ?? "",
+    });
+    return {
+        emitted: decision.emitted,
+        event_type: eventType,
+        run_id,
+        reason: run_id ? reason : `${reason} (warning: no BAPI_CONDUCTOR_RUN_ID — verdict uncorrelated)`,
+    };
+}