@bridge_gpt/mcp-server 0.2.68 → 0.2.70

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

@@ -1,5 +1,5 @@
-/** The pinned operator runbook every remedy below points into. */
-export const BRING_UP_RUNBOOK = "docs/epic-implementer/operator-runbook.md";
+/** Where the owner-only bring-up steps these remedies refer to are printed. */
+export const BRING_UP_RUNBOOK = "`drive-epic --help-advanced`";
 /**
  * The client-derived refusal vocabulary, IN REFUSAL ORDER.
  *
@@ -20,20 +20,20 @@ export const BRING_UP_REFUSAL_REASONS = [
 // ---------------------------------------------------------------------------
 // Fixed remediations
 // ---------------------------------------------------------------------------
-export const BRING_UP_UNREPORTED_REMEDIATION = "upgrade the Bridge API deploy to a build that reports the bring-up safety facts; " +
-    "their state is unknown here, not healthy.";
+export const BRING_UP_UNREPORTED_REMEDIATION = "retry later; the server did not report the bring-up safety facts, so their state is unknown here, " +
+    "not healthy. If it persists, email info@bridgegpt.ai.";
 export const DATABASE_MIGRATION_UNREADABLE_REMEDIATION = "retry; the migration state could not be read, which is not the same as confirmed-behind. " +
-    `If it persists, check the applied revision with \`alembic current\` (${BRING_UP_RUNBOOK} §3d).`;
+    `If it persists, check the applied revision with \`alembic current\` (see ${BRING_UP_RUNBOOK}).`;
 export const DATABASE_MIGRATION_BEHIND_REMEDIATION = "confirm the applied revision with `alembic current` (not `alembic heads`, which reads the " +
-    "migration scripts), apply this checkout's migrations with `alembic -c alembic.ini upgrade head`, " +
-    `then retry (${BRING_UP_RUNBOOK} §3d).`;
+    "migration scripts), apply this checkout's migrations with `alembic upgrade head`, " +
+    `then retry (see ${BRING_UP_RUNBOOK}).`;
 export const WORKER_HEARTBEAT_UNREADABLE_REMEDIATION = "retry once the Bridge API database is reachable; the reconciler heartbeat could not be read, " +
     "so worker presence is unknown, not confirmed absent.";
 export const WORKER_NOT_PRESENT_REMEDIATION = "start a worker (`python worker.py`, or bring up a local plane) — a server started with " +
     "DISABLE_SCHEDULER=true runs none. Create and approve only against a server that has a " +
-    `worker (${BRING_UP_RUNBOOK} §3d).`;
+    `worker (see ${BRING_UP_RUNBOOK}).`;
 export const SECOND_RECONCILER_REMEDIATION = "find and stop the extra reconciler: check `ps aux | grep worker.py` for a reparented " +
-    `survivor of an earlier plane (${BRING_UP_RUNBOOK} §6), and note that a dev server started ` +
+    `survivor of an earlier plane (see ${BRING_UP_RUNBOOK}), and note that a dev server started ` +
     "without DISABLE_SCHEDULER=true runs a reconciler too. A reconciler stopped in the last 120 " +
     "seconds still counts — heartbeat rows are not deleted on shutdown — so wait and retry. " +
     "On a hosted deployment, check that exactly one worker process is scaled (for example one " +

package/build/conductor/doctor.js

@@ -14,10 +14,13 @@ import { doctorConductorLedger } from "./store.js";
 import { detectClaudeLogin, formatClaudeLoginAdvisory } from "../claude-login.js";
 import { inspectConductorGitHooks } from "./git-hooks.js";
 import { MERGE_WORKFLOW_IDENTIFIER } from "./merge-execution-contract.js";
+import { LOCAL_MERGE_CREDENTIAL_ALIAS_ENV_KEY, LOCAL_MERGE_CREDENTIAL_ENV_KEYS, resolveLocalMergeCredentialDetailed, } from "./merge-credential.js";
+import { resolveMergeCredentialAtAction } from "./stored-merge-credential.js";
 import { resolveMcpShimInvocationForRuntime, resolvePackageRootFromModuleUrl, } from "../mcp-server-invocation.js";
 import { projectCommandDriftRow } from "./command-drift.js";
 import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
 import { resolveProfiles } from "../mcp-profile.js";
+import { isValidWorkerDatabaseName } from "../executor/worker-database-target.js";
 import { createReadinessCheck, createReadinessCheckSafely, } from "../readiness-check.js";
 /**
  * Remediation for a conductor context whose resolved MCP groups omit `epic_implementer`.
@@ -53,7 +56,7 @@ export const GH_CLI_REMEDIATION = "install the GitHub CLI (`gh`) and put it on P
  * and changes nothing. `merge-pull-request.ts` says exactly that about the same
  * text; this is the last place it was still live.
  */
-export const GH_AUTH_REMEDIATION = "set BAPI_LOCAL_MERGE_TOKEN (or BAPI_MACHINE_MERGE_TOKEN for machine-user mode) in the " +
+export const GH_AUTH_REMEDIATION = "set GITHUB_MERGE_TOKEN (or BAPI_MACHINE_MERGE_TOKEN for machine-user mode) in the " +
     "environment this host launches the conductor with; local merge has no ambient-login " +
     "fallback and fails closed with a named reason when neither is configured.";
 /** Detail used when the credential check was not reached because `gh` is absent. */
@@ -80,6 +83,342 @@ export const DENY_ENFORCEMENT_SKIP_REMEDIATION = "run `epic-implementer doctor`
     "preflight; `epic-implementer readiness` never spawns that probe itself.";
 /** Explicit display value for an unset `BRIDGE_MCP_PROFILE`. */
 export const MCP_PROFILE_UNSET = "(unset)";
+/** BAPI-1461: the printed setup command, used in stored-token remedies. */
+const PRINTED_SETUP_COMMAND = `npx -y ${MCP_PACKAGE_NAME} install conductor`;
+/** BAPI-1461: the fix for a stored token GitHub rejected. */
+export const STORED_MERGE_TOKEN_REJECTED_REMEDIATION = `replace the stored merge token: run \`${PRINTED_SETUP_COMMAND}\` and accept the offer to ` +
+    `replace it, or remove it with \`${PRINTED_SETUP_COMMAND} --remove-merge-token\`.`;
+/** BAPI-1461: the advice when the stored token could not be checked. */
+export const STORED_MERGE_TOKEN_UNVERIFIED_REMEDIATION = "the stored merge token could not be checked right now (GitHub or the credential store did " +
+    "not answer). This is not a rejection; run doctor again later.";
+/**
+ * BAPI-1461: collect the stored-entry finding. It runs only when no LOCAL
+ * credential is set in the environment (an env value always wins, and an
+ * invalid one is never rescued), resolves through the shared resolver, and —
+ * for a stored token — runs the bounded capability probe. Never throws and
+ * never returns the token.
+ */
+export async function collectStoredMergeCredentialEvidence(env, context) {
+    if (resolveLocalMergeCredentialDetailed(env, "local").status !== "missing")
+        return { status: "absent" };
+    let resolution;
+    try {
+        resolution = await resolveMergeCredentialAtAction(env, "local", context);
+    }
+    catch {
+        return { status: "unverified" };
+    }
+    if (resolution.status === "store-unavailable")
+        return { status: "unverified" };
+    if (resolution.status === "invalid")
+        return { status: "rejected", reason: "invalid" };
+    if (resolution.status !== "resolved" || resolution.source !== "store")
+        return { status: "absent" };
+    if (context.probe === undefined)
+        return { status: "configured" };
+    const repository = context.providerRepository ?? context.localRemote ?? null;
+    if (repository === null)
+        return { status: "configured" };
+    let verdict;
+    try {
+        verdict = await context.probe({ repository, credential: resolution.credential });
+    }
+    catch {
+        return { status: "unverified" };
+    }
+    switch (verdict) {
+        case "passed":
+            return { status: "configured" };
+        case "credential_invalid":
+            return { status: "rejected", reason: "invalid" };
+        case "no_access":
+            return { status: "rejected", reason: "unpermitted" };
+        default:
+            // An unavailable or inconclusive probe is uncertainty — never a revocation.
+            return { status: "unverified" };
+    }
+}
+/**
+ * BAPI-1452: the note printed when the deprecated local alias supplies the
+ * credential. Names the canonical key; never mentions the machine credential,
+ * which has no alias and is not deprecated.
+ */
+export const LOCAL_MERGE_ALIAS_DEPRECATION_NOTE = `the local merge credential is being read from the deprecated ${LOCAL_MERGE_CREDENTIAL_ALIAS_ENV_KEY}; ` +
+    `it still works, but rename it to ${LOCAL_MERGE_CREDENTIAL_ENV_KEYS.local}.`;
+// ---------------------------------------------------------------------------
+// Worker-database advisory section (BAPI-1479)
+// ---------------------------------------------------------------------------
+/**
+ * Runbook section every worker-database row points to. Mirrors
+ * `WORKER_DATABASE_RUNBOOK_SECTION` in `executor/worker-database.ts`, which is
+ * not imported at runtime (see the import note above); a test pins the two
+ * values together.
+ */
+export const WORKER_DATABASE_DOCTOR_RUNBOOK_SECTION = "docs/claude/runbooks/local-db-safety.md#worker-databases";
+/** Who acts on every worker-database row. */
+export const WORKER_DATABASE_DOCTOR_OWNER = "host operator";
+/** Hard ceiling on one worker-database inspection, so it can never hang doctor. */
+export const WORKER_DATABASE_DOCTOR_TIMEOUT_MS = 20_000;
+/** Maximum validated names listed per inventory group; the rest are counted. */
+export const WORKER_DATABASE_DOCTOR_NAME_LIMIT = 20;
+const ROW_STATES = new Set(["healthy", "unsafe", "unknown"]);
+const RETAIN_REASONS = new Set([
+    "owner_alive",
+    "owner_unknown",
+    "foreign_host",
+    "no_comment",
+    "malformed_comment",
+    "ownership_changed",
+    "drop_failed",
+]);
+const UNAVAILABLE_CATEGORIES = new Set([
+    "client_missing",
+    "postgres_unavailable",
+    "role_missing",
+    "role_misconfigured",
+    "bridgeapi_reachable",
+    "boundary_unknown",
+    "alembic_missing",
+    "create_failed",
+    "migration_failed",
+    "timeout",
+    "cancelled",
+]);
+function safeState(value) {
+    return typeof value === "string" && ROW_STATES.has(value) ? value : "unknown";
+}
+function safeCategory(value) {
+    return typeof value === "string" && UNAVAILABLE_CATEGORIES.has(value)
+        ? value
+        : undefined;
+}
+/** Fixed prose for a category that made a check unavailable or unsafe. */
+function describeUnavailableCategory(category) {
+    switch (category) {
+        case "client_missing":
+            return "the psql client was not found";
+        case "postgres_unavailable":
+            return "local PostgreSQL could not be reached";
+        case "timeout":
+            return "the check timed out";
+        case "cancelled":
+            return "the check was cancelled";
+        default:
+            return "the check could not be completed";
+    }
+}
+function makeRow(id, label, state, detail) {
+    return {
+        id,
+        label,
+        state,
+        owner: WORKER_DATABASE_DOCTOR_OWNER,
+        detail,
+        ...(state === "healthy" ? {} : { runbook: WORKER_DATABASE_DOCTOR_RUNBOOK_SECTION }),
+    };
+}
+function roleRow(role) {
+    const r = (role ?? {});
+    let state = safeState(r.state);
+    const category = safeCategory(r.category);
+    let detail;
+    if (state === "healthy") {
+        detail = "bridge_epic_worker exists with the expected attributes and no elevating memberships";
+    }
+    else if (state === "unsafe") {
+        detail =
+            category === "role_missing"
+                ? "bridge_epic_worker does not exist"
+                : "bridge_epic_worker attributes or memberships differ from the expected least-privilege set";
+    }
+    else if (category === "role_missing") {
+        // A definitive "missing" answer is actionable, not unknown.
+        state = "unsafe";
+        detail = "bridge_epic_worker does not exist";
+    }
+    else {
+        detail = `unknown — ${describeUnavailableCategory(category)}`;
+    }
+    return makeRow("worker-db-role", "worker role", state, detail);
+}
+function boundaryRow(boundary) {
+    const b = (boundary ?? {});
+    const state = safeState(b.state);
+    const category = safeCategory(b.category);
+    const detail = state === "healthy"
+        ? "bridge_epic_worker is refused on bridgeapi"
+        : state === "unsafe"
+            ? "UNSAFE — bridge_epic_worker can connect to bridgeapi"
+            : `unknown — ${category === "boundary_unknown" ? "the bridgeapi refusal could not be confirmed" : describeUnavailableCategory(category)}`;
+    return makeRow("worker-db-boundary", "bridgeapi boundary", state, detail);
+}
+function alembicRow(alembic) {
+    const state = safeState(alembic?.state);
+    const detail = state === "healthy"
+        ? "the operator checkout's .venv Alembic is present"
+        : state === "unsafe"
+            ? "the operator checkout's .venv Alembic is missing"
+            : "unknown — the operator checkout's .venv Alembic could not be checked";
+    return makeRow("worker-db-alembic", "operator-checkout Alembic", state, detail);
+}
+function safeNameList(value, redacted) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (isValidWorkerDatabaseName(entry))
+            out.push(entry);
+        else
+            redacted.count += 1;
+    }
+    return out;
+}
+function sanitizeInventory(inventory) {
+    const inv = inventory;
+    if (!inv || inv.state !== "known" || typeof inv.value !== "object" || inv.value === null) {
+        return { state: "unknown" };
+    }
+    const value = inv.value;
+    if (!Array.isArray(value.active) ||
+        !Array.isArray(value.leftovers) ||
+        !Array.isArray(value.unverifiable) ||
+        typeof value.harnessCount !== "number" ||
+        !Number.isInteger(value.harnessCount) ||
+        value.harnessCount < 0) {
+        return { state: "unknown" };
+    }
+    const redacted = { count: 0 };
+    const active = safeNameList(value.active, redacted);
+    const leftovers = safeNameList(value.leftovers, redacted);
+    const unverifiable = [];
+    for (const entry of value.unverifiable) {
+        const e = (entry ?? {});
+        if (!isValidWorkerDatabaseName(e.name)) {
+            redacted.count += 1;
+            continue;
+        }
+        const reason = typeof e.reason === "string" && RETAIN_REASONS.has(e.reason)
+            ? e.reason
+            : "unrecognized";
+        unverifiable.push({ name: e.name, reason });
+    }
+    return {
+        state: "known",
+        active,
+        leftovers,
+        unverifiable,
+        harness_count: value.harnessCount,
+        redacted_count: redacted.count,
+    };
+}
+function inventoryRows(inventory) {
+    if (inventory.state === "unknown") {
+        const detail = "unknown — the database inventory could not be read";
+        return [
+            makeRow("worker-db-leftovers", "worker databases", "unknown", detail),
+            makeRow("worker-db-unverifiable", "unverifiable worker databases", "unknown", detail),
+            makeRow("worker-db-harness", "conductor_harness databases", "unknown", detail),
+        ];
+    }
+    const leftoverCount = inventory.leftovers.length;
+    // A redacted name is unverifiable by definition — it could not be validated.
+    const unverifiableCount = inventory.unverifiable.length + inventory.redacted_count;
+    return [
+        makeRow("worker-db-leftovers", "worker databases", leftoverCount === 0 ? "healthy" : "unsafe", `${inventory.active.length} active (owned by a live executor), ${leftoverCount} left over ` +
+            "(dead executor on this host; the next executor start sweeps them)"),
+        makeRow("worker-db-unverifiable", "unverifiable worker databases", unverifiableCount === 0 ? "healthy" : "unsafe", `${unverifiableCount} with unreadable, malformed, foreign-host, or unknown ownership ` +
+            "(left in place; review manually)"),
+        makeRow("worker-db-harness", "conductor_harness databases", inventory.harness_count === 0 ? "healthy" : "unsafe", `${inventory.harness_count} present (owned by the Python harness reaper; the executor never cleans them)`),
+    ];
+}
+/** Project a (possibly hostile or malformed) inspection into the sanitized advisory section. */
+export function buildWorkerDatabaseDoctorSection(inspection) {
+    const insp = (inspection ?? {});
+    const inventory = inspection ? sanitizeInventory(insp.inventory) : { state: "unknown" };
+    return {
+        advisory: true,
+        owner: WORKER_DATABASE_DOCTOR_OWNER,
+        runbook: WORKER_DATABASE_DOCTOR_RUNBOOK_SECTION,
+        rows: [
+            roleRow(insp.role),
+            boundaryRow(insp.boundary),
+            alembicRow(insp.alembic),
+            ...inventoryRows(inventory),
+        ],
+        inventory,
+    };
+}
+/**
+ * Run the worker-database inspector with a hard ceiling. A throw, a rejection,
+ * or a timeout yields an all-unknown section — never healthy, never a crash.
+ *
+ * BAPI-1496: exported so a local `drive-epic` launch can collect the same
+ * advisory section the doctor shows. `onFailure` receives only the closed
+ * `timeout`/`error` classification — never the thrown value — so a caller can
+ * say that the inspection failed without echoing exception text.
+ */
+export async function collectWorkerDatabaseDoctorSection(inspect, timeoutMs = WORKER_DATABASE_DOCTOR_TIMEOUT_MS, onFailure) {
+    let timer;
+    try {
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), timeoutMs);
+            timer.unref?.();
+        });
+        const inspection = await Promise.race([Promise.resolve().then(inspect), timeout]);
+        if (inspection === null)
+            onFailure?.("timeout");
+        return buildWorkerDatabaseDoctorSection(inspection);
+    }
+    catch {
+        onFailure?.("error");
+        return buildWorkerDatabaseDoctorSection(null);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+const WORKER_DB_STATE_TAG = {
+    healthy: "[OK]",
+    unsafe: "[WARNING]",
+    unknown: "[UNKNOWN]",
+};
+function formatNameGroup(lines, heading, names) {
+    if (names.length === 0)
+        return;
+    lines.push(`  ${heading}:`);
+    for (const name of names.slice(0, WORKER_DATABASE_DOCTOR_NAME_LIMIT))
+        lines.push(`    - ${name}`);
+    if (names.length > WORKER_DATABASE_DOCTOR_NAME_LIMIT) {
+        lines.push(`    … and ${names.length - WORKER_DATABASE_DOCTOR_NAME_LIMIT} more`);
+    }
+}
+/** Render the advisory worker-database section. Names are re-validated at render time. */
+export function formatWorkerDatabaseDoctorSection(section) {
+    const lines = [];
+    lines.push("Worker databases (advisory, read-only)");
+    lines.push("──────────────────────────────────────");
+    for (const row of section.rows) {
+        const state = safeState(row.state);
+        lines.push(`${row.label.padEnd(30)} ${WORKER_DB_STATE_TAG[state]} ${state} — ${row.detail}`);
+        if (state !== "healthy") {
+            lines.push(`  → ${WORKER_DATABASE_DOCTOR_OWNER}: see ${WORKER_DATABASE_DOCTOR_RUNBOOK_SECTION}`);
+        }
+    }
+    const inv = section.inventory;
+    if (inv.state === "known") {
+        formatNameGroup(lines, "active", inv.active.filter(isValidWorkerDatabaseName));
+        formatNameGroup(lines, "left over", inv.leftovers.filter(isValidWorkerDatabaseName));
+        formatNameGroup(lines, "unverifiable", inv.unverifiable
+            .filter((e) => isValidWorkerDatabaseName(e.name))
+            .map((e) => `${e.name} (${RETAIN_REASONS.has(e.reason) ? e.reason : "unrecognized"})`));
+        if (inv.redacted_count > 0) {
+            lines.push(`  ${inv.redacted_count} name(s) failed validation and are not shown`);
+        }
+    }
+    lines.push("These rows are advisory: they never change this command's exit status.");
+    return lines;
+}
 /**
  * The CLI-only verbs that call the Bridge API from a shell-spawned process and
  * therefore resolve credentials themselves (CLAUDE.md "Shell-Spawned Credential
@@ -103,6 +442,8 @@ export const CREDENTIALED_RECOVERY_COMMANDS = [
     // BAPI-1300: parked-child continuation and its read-only receipt lookup.
     "continue-child",
     "continuation-receipt",
+    // BAPI-1469: the read-only bounded wait on a run's state.
+    "wait-run",
 ];
 /** Remediation for recovery/repair verbs that cannot resolve Bridge credentials. */
 export const REPAIR_CREDENTIAL_REMEDIATION = "export BAPI_API_KEY in the shell that runs `conductor`, or store a credential for this " +
@@ -439,7 +780,13 @@ export function inspectMcpProfile(env) {
  * `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, env = process.env) {
+export function inspectLocalMerge(runCommand, env = process.env, 
+/**
+ * BAPI-1461: the stored-entry finding, collected beforehand by
+ * {@link collectStoredMergeCredentialEvidence}. Absent ⇒ env-only, exactly as
+ * before. Never consulted for machine-user mode.
+ */
+stored) {
     const run = runCommand ??
         ((cmd, args) => {
             try {
@@ -481,16 +828,62 @@ export function inspectLocalMerge(runCommand, env = process.env) {
     // read-only from the environment — no subprocess, no network, and no credential
     // VALUE anywhere in the result. Either mode's key satisfies it: which one a run
     // uses is the server-resolved typed mode, which a local doctor cannot know.
-    const merge_credential_configured = ["BAPI_LOCAL_MERGE_TOKEN", "BAPI_MACHINE_MERGE_TOKEN"].some((key) => typeof env[key] === "string" && env[key].trim().length > 0);
+    //
+    // BAPI-1452: presence is now decided by the SAME resolver the merge uses, so
+    // the canonical-then-alias precedence and the "an invalid canonical value is
+    // not rescued by the alias" rule cannot drift between doctor and the merge.
+    const localResolution = resolveLocalMergeCredentialDetailed(env, "local");
+    const machineResolution = resolveLocalMergeCredentialDetailed(env, "machine_token");
+    // BAPI-1461: a stored token counts only when the environment set no local
+    // value at all, and only when GitHub did not reject it.
+    const storedConfigured = localResolution.status === "missing" && stored?.status === "configured";
+    const storedRejected = localResolution.status === "missing" && stored?.status === "rejected";
+    const storedUnverified = localResolution.status === "missing" && stored?.status === "unverified";
+    const merge_credential_configured = localResolution.status === "resolved" || storedConfigured || machineResolution.status === "resolved";
+    const localInvalid = localResolution.status === "invalid";
+    const local_credential_source = localResolution.status === "resolved"
+        ? localResolution.via_alias
+            ? "alias"
+            : "env"
+        : storedConfigured
+            ? "store"
+            : undefined;
+    const notes = [];
+    if (localResolution.status === "resolved" && localResolution.via_alias) {
+        notes.push(LOCAL_MERGE_ALIAS_DEPRECATION_NOTE);
+    }
     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 (!merge_credential_configured && storedRejected) {
+        warnings.push("the merge token stored for this repository was rejected by GitHub (expired, revoked, or " +
+            `without write access), so it is not configured. Fix: ${STORED_MERGE_TOKEN_REJECTED_REMEDIATION}`);
+    }
+    else if (!merge_credential_configured && storedUnverified) {
+        warnings.push(`no merge credential could be confirmed: ${STORED_MERGE_TOKEN_UNVERIFIED_REMEDIATION}`);
+    }
     else if (!merge_credential_configured) {
-        warnings.push("`gh` is installed but no merge credential is configured. Set BAPI_LOCAL_MERGE_TOKEN " +
-            "(or BAPI_MACHINE_MERGE_TOKEN for machine-user mode); local merge has no ambient-login " +
-            "fallback and fails closed with a named reason.");
+        warnings.push(localInvalid
+            ? "`gh` is installed but the configured GITHUB_MERGE_TOKEN is not a usable token value " +
+                "(it contains whitespace or control characters), and BAPI_LOCAL_MERGE_TOKEN is not " +
+                "used in its place. Fix GITHUB_MERGE_TOKEN (or set BAPI_MACHINE_MERGE_TOKEN for " +
+                "machine-user mode)."
+            : "`gh` is installed but no merge credential is configured. Set GITHUB_MERGE_TOKEN " +
+                "(or BAPI_MACHINE_MERGE_TOKEN for machine-user mode); local merge has no ambient-login " +
+                "fallback and fails closed with a named reason.");
+    }
+    else if (storedRejected) {
+        // BAPI-1461: a machine credential must not conceal a rejected local one.
+        warnings.push("the merge token stored for this repository was rejected by GitHub, so a local-mode merge " +
+            `would refuse. Fix: ${STORED_MERGE_TOKEN_REJECTED_REMEDIATION}`);
+    }
+    else if (localInvalid) {
+        // A machine credential satisfies the check, but the local one is still
+        // broken — worth saying, because local mode would refuse.
+        warnings.push("the configured GITHUB_MERGE_TOKEN is not a usable token value, so a local-mode merge " +
+            "would refuse; BAPI_LOCAL_MERGE_TOKEN is not used in its place.");
     }
     // Capability gap only — local merge is opt-in, so an unconfigured host is not a
     // hard failure unless the operator enabled it. Reported as degraded for visibility.
@@ -537,18 +930,52 @@ export function inspectLocalMerge(runCommand, env = process.env) {
                     id: "merge-credential",
                     label: "Configured merge credential",
                     status: "pass",
-                    detail: "BAPI_LOCAL_MERGE_TOKEN or BAPI_MACHINE_MERGE_TOKEN is set",
+                    detail: localResolution.status === "resolved"
+                        ? localResolution.via_alias
+                            ? "the local credential is set through the deprecated BAPI_LOCAL_MERGE_TOKEN"
+                            : "GITHUB_MERGE_TOKEN is set"
+                        : storedConfigured
+                            ? "a merge token is stored for this repository"
+                            : "BAPI_MACHINE_MERGE_TOKEN is set",
                 }
-                : {
-                    id: "merge-credential",
-                    label: "Configured merge credential",
-                    status: "warn",
-                    detail: "`gh` is installed but neither BAPI_LOCAL_MERGE_TOKEN nor " +
-                        "BAPI_MACHINE_MERGE_TOKEN is set, so a local merge would fail closed",
-                    remediation: GH_AUTH_REMEDIATION,
-                },
+                : storedRejected
+                    ? {
+                        id: "merge-credential",
+                        label: "Configured merge credential",
+                        status: "warn",
+                        detail: "the merge token stored for this repository was rejected by GitHub",
+                        remediation: STORED_MERGE_TOKEN_REJECTED_REMEDIATION,
+                    }
+                    : storedUnverified
+                        ? {
+                            id: "merge-credential",
+                            label: "Configured merge credential",
+                            status: "warn",
+                            detail: "the stored merge token could not be checked right now",
+                            remediation: STORED_MERGE_TOKEN_UNVERIFIED_REMEDIATION,
+                        }
+                        : {
+                            id: "merge-credential",
+                            label: "Configured merge credential",
+                            status: "warn",
+                            detail: localInvalid
+                                ? "`gh` is installed but GITHUB_MERGE_TOKEN is not a usable token value and " +
+                                    "BAPI_MACHINE_MERGE_TOKEN is not set, so a local merge would fail closed"
+                                : "`gh` is installed but neither GITHUB_MERGE_TOKEN nor " +
+                                    "BAPI_MACHINE_MERGE_TOKEN is set, so a local merge would fail closed",
+                            remediation: GH_AUTH_REMEDIATION,
+                        },
     ];
-    return { gh_available, merge_credential_configured, degraded, warnings, outcomes };
+    return {
+        gh_available,
+        merge_credential_configured,
+        degraded,
+        warnings,
+        outcomes,
+        notes,
+        ...(local_credential_source !== undefined ? { local_credential_source } : {}),
+        ...(stored !== undefined ? { stored_credential: stored } : {}),
+    };
 }
 /** Remediation when this host has no `gh` identity to observe with. */
 export const GH_ACTIONS_MERGE_AUTH_REMEDIATION = "run `gh auth login` so this host has a GitHub identity; without one it cannot " +
@@ -698,17 +1125,25 @@ export async function buildConductorDoctorReport(deps = {}) {
     const command_drift = deps.inspectCommandDrift
         ? await inspectCommandDriftSafe(deps.inspectCommandDrift)
         : undefined;
+    const worker_database = deps.inspectWorkerDatabase
+        ? await collectWorkerDatabaseDoctorSection(deps.inspectWorkerDatabase, deps.workerDatabaseTimeoutMs ?? WORKER_DATABASE_DOCTOR_TIMEOUT_MS)
+        : undefined;
     return {
         ledger,
         git_hooks: inspectHooks(deps.hooksDeps),
         mcp_profile,
-        local_merge: inspectLocalMerge(deps.runCommand),
+        // BAPI-1461: the SAME env the rest of the report reads, plus the stored-entry
+        // finding when a store context was supplied.
+        local_merge: inspectLocalMerge(deps.runCommand, deps.env ?? process.env, deps.storedMergeCredential
+            ? await collectStoredMergeCredentialEvidence(deps.env ?? process.env, deps.storedMergeCredential)
+            : undefined),
         github_actions_merge: inspectGitHubActionsMergeSafe(deps),
         native_ledger,
         deny_enforcement,
         claude_login,
         repair_credentials: await inspectRepairVerbCredentials(deps.env ?? process.env, deps.resolveRepairAccess),
         ...(command_drift ? { command_drift } : {}),
+        ...(worker_database ? { worker_database } : {}),
     };
 }
 /** Run the drift inspector, containing any throw as an unassessable `warn`. */
@@ -865,7 +1300,9 @@ export function formatConductorDoctorReport(report) {
             : "[WARNING] no merge credential configured"
         : "[WARNING] not installed";
     lines.push(`gh available:          ${local_merge.gh_available} ${ghTag}`);
-    lines.push(`merge credential set:  ${local_merge.merge_credential_configured}`);
+    lines.push(`merge credential set:  ${local_merge.merge_credential_configured}` +
+        // BAPI-1461: say where a stored token came from (never its value).
+        (local_merge.local_credential_source === "store" ? " (stored for this repository)" : ""));
     lines.push(`degraded:              ${local_merge.degraded}`);
     // BAPI-1135 — the two observations render INDEPENDENTLY, each leading with its
     // own decisive word, because they have two different fixes. Collapsing them
@@ -897,6 +1334,11 @@ export function formatConductorDoctorReport(report) {
         for (const w of local_merge.warnings)
             lines.push(`  - ${w}`);
     }
+    if (local_merge.notes && local_merge.notes.length > 0) {
+        lines.push("local merge notes:");
+        for (const n of local_merge.notes)
+            lines.push(`  - ${n}`);
+    }
     if (report.repair_credentials) {
         const repair = report.repair_credentials;
         lines.push("");
@@ -965,6 +1407,12 @@ export function formatConductorDoctorReport(report) {
         if (row.remediation)
             lines.push(`  → ${row.remediation}`);
     }
+    // BAPI-1479 — advisory worker-database rows, after every existing section so
+    // the output of a report without them is byte-identical.
+    if (report.worker_database) {
+        lines.push("");
+        lines.push(...formatWorkerDatabaseDoctorSection(report.worker_database));
+    }
     return lines.join("\n");
 }
 // ---------------------------------------------------------------------------