@bridge_gpt/mcp-server 0.2.1 → 0.2.3

package/build/conductor/tools.js

@@ -0,0 +1,367 @@
+/**
+ * Conductor MCP tool registration.
+ *
+ * Exposes the local SQLite ledger operations as strict, Zod-backed MCP tools
+ * that follow the existing Bridge MCP return convention
+ * (`{ content: [{ type: "text", text }] }`). All ledger access is LOCAL — these
+ * tools never round-trip through the Bridge API HTTP helpers. Every handler is
+ * wrapped by {@link withConductorToolErrorHandling} so failures surface as
+ * sanitized, structured JSON without raw payloads, stack traces, or secrets.
+ */
+import { z } from "zod";
+import { SEMANTIC_EVENT_TYPES } from "./taxonomy.js";
+import { ConductorValidationError, toConductorErrorEnvelope } from "./errors.js";
+import { emitConductorEvent, pollConductorEvents, waitForConductorEvent, getSupervisorSnapshot, sendWorkerMessage, checkWorkerMessages, } from "./store.js";
+import { normalizePrNumber, normalizeSha } from "./git-ci-types.js";
+import { waitForDoneGate } from "./pr-ci-producer.js";
+import { resolveConductorBridgeApiAccess, fetchEpicRunState, ConductorBridgeApiError } from "./bridge-api-client.js";
+/** Build a Zod enum from the semantic taxonomy so arbitrary types are rejected up front. */
+export function buildEventTypeZodEnum() {
+    return z.enum(SEMANTIC_EVENT_TYPES);
+}
+/** Allowlisted, parameterized read filter schema (shared by poll + wait). */
+const EventFilterSchema = z
+    .object({
+    type: buildEventTypeZodEnum().optional(),
+    types: z.array(buildEventTypeZodEnum()).optional(),
+    source: z.string().optional(),
+    run_id: z.string().optional(),
+    worker_id: z.string().optional(),
+    subject: z.string().optional(),
+    producer: z.string().optional(),
+})
+    .strict();
+function jsonResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+/**
+ * Wrap a tool handler so any thrown value becomes a sanitized structured JSON
+ * error envelope (validation -> 400, store-busy -> 503, otherwise 500). Raw
+ * input data, stack traces, and secret material are never echoed back.
+ */
+export function withConductorToolErrorHandling(handler) {
+    return async (args) => {
+        try {
+            return await handler(args);
+        }
+        catch (error) {
+            return jsonResult(toConductorErrorEnvelope(error));
+        }
+    };
+}
+function registerEmitEventTool(registerTool) {
+    registerTool("emit_event", {
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: "Append a semantic coordination event to the LOCAL conductor ledger (~/.config/bridge/events.db). " +
+            "This is a local, append-only event store for multi-agent coordination — it does NOT call the Bridge API. " +
+            "Only the fixed semantic event taxonomy is accepted (e.g. run.started, agent.notification, ci.passed). " +
+            "Place tool-native fields (branch, commitSha, etc.) under data.raw — non-allowlisted top-level data keys are rejected. " +
+            "Secrets are redacted before storage and large payloads must be passed by reference (data.payload_ref / data.references).",
+        inputSchema: {
+            source: z.string().describe("Logical producer of the event (e.g. 'claude-code', 'git-hook')."),
+            type: buildEventTypeZodEnum().describe("Semantic event type from the fixed conductor taxonomy."),
+            subject: z.string().optional().describe("Optional subject the event is about (e.g. a ticket key)."),
+            run_id: z.string().optional().describe("Optional run/session identifier this event belongs to."),
+            worker_id: z.string().optional().describe("Optional worker/agent identifier."),
+            producer: z.string().optional().describe("Optional finer-grained producer identity."),
+            schema_version: z.number().int().positive().optional().describe("Event schema version (default 1)."),
+            time: z.string().optional().describe("Optional ISO-8601 event time (defaults to now)."),
+            data: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Normalized event data. Allowed top-level keys: summary, status, message, details, reason, metrics, labels, references, payload_ref, raw. Tool-native fields go under 'raw'."),
+            confidence: z.number().min(0).max(1).optional().describe("Optional confidence in [0,1]."),
+            observed_via: z.string().optional().describe("Optional channel the event was observed through."),
+        },
+    }, withConductorToolErrorHandling(async (args) => {
+        const result = emitConductorEvent({
+            source: args.source,
+            type: args.type,
+            subject: args.subject,
+            run_id: args.run_id,
+            worker_id: args.worker_id,
+            producer: args.producer,
+            schema_version: args.schema_version,
+            time: args.time,
+            data: args.data ?? {},
+            confidence: args.confidence,
+            observed_via: args.observed_via,
+        });
+        return jsonResult(result);
+    }));
+}
+function registerPollEventsTool(registerTool) {
+    registerTool("poll_events", {
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: "Read ordered events from the LOCAL conductor ledger starting at an inclusive 'since_seq' cursor. " +
+            "Returns compact metadata-first summaries by default (data.raw omitted; raw_keys surfaced) and a 'next_seq' cursor to pass on the next call. " +
+            "Set data_mode='full' to retrieve complete (redacted) event data. Local read-only; does not call the Bridge API.",
+        inputSchema: {
+            since_seq: z.number().int().nonnegative().optional().describe("Inclusive sequence cursor (default 1)."),
+            filter: EventFilterSchema.optional().describe("Optional allowlisted filter."),
+            data_mode: z.enum(["summary", "full"]).optional().describe("Projection mode (default 'summary')."),
+            limit: z.number().int().positive().optional().describe("Max events to return (default 100, max 1000)."),
+        },
+    }, withConductorToolErrorHandling(async (args) => {
+        const result = pollConductorEvents({
+            since_seq: args.since_seq ?? 1,
+            filter: args.filter,
+            data_mode: args.data_mode ?? "summary",
+            limit: args.limit,
+        });
+        return jsonResult(result);
+    }));
+}
+function registerWaitForEventTool(registerTool) {
+    registerTool("wait_for_event", {
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: "Long-poll the LOCAL conductor ledger: block up to 'timeout_ms' (bounded, max 120000) until events matching the filter appear at/after 'since_seq'. " +
+            "Returns the same shape as poll_events plus 'timed_out'. SQLite locks are never held between polls. Local read-only; does not call the Bridge API.",
+        inputSchema: {
+            since_seq: z.number().int().nonnegative().optional().describe("Inclusive sequence cursor (default 1)."),
+            filter: EventFilterSchema.optional().describe("Optional allowlisted filter."),
+            data_mode: z.enum(["summary", "full"]).optional().describe("Projection mode (default 'summary')."),
+            timeout_ms: z.number().int().nonnegative().optional().describe("Max wait in ms (bounded, max 120000)."),
+            limit: z.number().int().positive().optional().describe("Max events to return (default 100, max 1000)."),
+        },
+    }, withConductorToolErrorHandling(async (args) => {
+        const result = await waitForConductorEvent({
+            since_seq: args.since_seq ?? 1,
+            filter: args.filter,
+            data_mode: args.data_mode ?? "summary",
+            timeout_ms: args.timeout_ms,
+            limit: args.limit,
+        });
+        return jsonResult(result);
+    }));
+}
+function registerGetSupervisorSnapshotTool(registerTool) {
+    registerTool("get_supervisor_snapshot", {
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: "Read the supervisor projection for a run_id from the LOCAL conductor ledger. " +
+            "The projection is maintained by the conductor supervisor runtime (`conductor supervise --run-id <id>`), " +
+            "which owns the deterministic worker watchdog state; this tool ONLY reads that projection and never derives state from raw events. " +
+            "Returns { run_id, status, projection } where projection is null and status is 'unknown' when no projection exists yet. " +
+            "Local read-only; does not call the Bridge API.",
+        inputSchema: {
+            run_id: z.string().describe("The run/session identifier to read the supervisor projection for."),
+        },
+    }, withConductorToolErrorHandling(async (args) => {
+        const result = getSupervisorSnapshot(args.run_id);
+        return jsonResult(result);
+    }));
+}
+function registerGetEpicSnapshotTool(registerTool) {
+    registerTool("get_epic_snapshot", {
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        description: "Read the Epic Run snapshot for an epic key from the Bridge API. " +
+            "Returns the full EpicRunState: the epic run record (status, plan version, lease state, budget/consumed), " +
+            "per-ticket status rows, and dispatch rows. " +
+            "Returns { epic_key, status: 'unknown', state: null } if the Epic Run does not exist. " +
+            "Read-only; never triggers a tick, transitions Jira, or mutates Epic state.",
+        inputSchema: {
+            epic_key: z.string().min(1).describe("The epic identifier to fetch the snapshot for (e.g. EPIC-123)."),
+        },
+    }, withConductorToolErrorHandling(async (args) => {
+        const epicKey = args.epic_key;
+        const accessResult = await resolveConductorBridgeApiAccess();
+        if (!accessResult.ok) {
+            throw new ConductorValidationError(accessResult.error);
+        }
+        try {
+            const result = await fetchEpicRunState(accessResult.access, epicKey);
+            return jsonResult(result);
+        }
+        catch (error) {
+            if (error instanceof ConductorBridgeApiError && error.status === 404) {
+                return jsonResult({ epic_key: epicKey, status: "unknown", state: null });
+            }
+            throw error;
+        }
+    }));
+}
+const SHA_PATTERN = /^[0-9a-fA-F]{40}$|^[0-9a-fA-F]{64}$/;
+function registerWaitForDoneGateTool(registerTool) {
+    registerTool("wait_for_done_gate", {
+        annotations: {
+            // Read/write + non-idempotent: this tool can EMIT conductor events
+            // (git.pr_opened, ci.passed/failed, gate.met) as a side effect of observing.
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        description: "Bounded wait for the conductor done-gate on a pull request. Resolves the PR number + immutable head SHA " +
+            "once, polls CI for that SHA on a clamped interval, and emits conductor events (git.pr_opened, ci.passed/ci.failed, " +
+            "and gate.met when the configured required CI checks are green). " +
+            "This EMITS conductor coordination events only — it does NOT merge the PR, transition Jira, or mutate any repository state. " +
+            "Fails closed: an unset/disabled/malformed conductor_done_gate config never produces gate.met.",
+        inputSchema: {
+            repo_name: z.string().optional().describe("Optional repo name override (defaults to BAPI_REPO_NAME/.bridge/config)."),
+            pr_number: z.number().int().positive().optional().describe("Optional explicit PR number (positive integer)."),
+            head_sha: z
+                .string()
+                .regex(SHA_PATTERN)
+                .optional()
+                .describe("Optional explicit head SHA (40- or 64-character hex)."),
+            timeout_ms: z.number().int().nonnegative().optional().describe("Max wait in ms (clamped, max 120000)."),
+            poll_interval_ms: z.number().int().nonnegative().optional().describe("CI poll interval in ms (clamped)."),
+            worktree_path: z.string().optional().describe("Optional worktree path to resolve git/PR context from."),
+        },
+    }, withConductorToolErrorHandling(async (args) => {
+        // Defensive boundary validation (mirrors the schema) so an invalid identifier
+        // is a sanitized 400 and never reaches waitForDoneGate.
+        if (args.pr_number !== undefined && normalizePrNumber(args.pr_number) === null) {
+            throw new ConductorValidationError("'pr_number' must be a positive integer.");
+        }
+        if (args.head_sha !== undefined && normalizeSha(args.head_sha) === null) {
+            throw new ConductorValidationError("'head_sha' must be a 40- or 64-character hex SHA.");
+        }
+        const result = await waitForDoneGate({
+            repoName: args.repo_name,
+            prNumber: args.pr_number,
+            headSha: args.head_sha,
+            timeoutMs: args.timeout_ms,
+            pollIntervalMs: args.poll_interval_ms,
+            worktreePath: args.worktree_path,
+        });
+        return jsonResult({
+            gate_met: result.gate_met,
+            timed_out: result.timed_out,
+            reason: result.reason,
+            repo: result.repo,
+            pr_number: result.pr_number,
+            head_sha: result.head_sha,
+            gate_event_summary: result.gate_event_summary,
+        });
+    }));
+}
+function registerSendMessageTool(registerTool) {
+    registerTool("send_message", {
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            // Enqueueing the same idempotency key (run_id+worker_id+type+cause_seq)
+            // never inserts a second message, so the tool is idempotent.
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: "Enqueue a typed, auditable message for ONE worker through the LOCAL cooperative conductor relay " +
+            "(~/.config/bridge/events.db). The supervisor sends; the worker reads/acknowledges later via check_messages. " +
+            "This is COOPERATIVE — it does NOT inject into, mutate, or prompt-inject a live worker session. " +
+            "Idempotent: a duplicate idempotency key (run_id+worker_id+type+cause_seq) does not enqueue a second message, " +
+            "and a same-type message inside the cooldown window is suppressed. Local only; does not call the Bridge API.",
+        inputSchema: {
+            run_id: z.string().min(1).describe("Run/session identifier the message is scoped to."),
+            worker_id: z.string().min(1).describe("Target worker/agent identifier."),
+            type: z.string().min(1).describe("Typed message kind (e.g. 'supervisor.worker_stalled')."),
+            cause_seq: z
+                .number()
+                .int()
+                .nonnegative()
+                .describe("Idempotency cause sequence (the supervisor's last_seq at decision time)."),
+            payload: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .default({})
+                .describe("Optional compact payload. Allowed top-level keys: summary, status, message, details, reason, metrics, labels, references, payload_ref, raw."),
+            available_at: z.string().optional().describe("Optional ISO-8601 time the message becomes available (default now)."),
+            cooldown_ms: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Optional per-call cooldown override in ms (falls back to the configured cooldown)."),
+        },
+    }, withConductorToolErrorHandling(async (args) => {
+        const result = sendWorkerMessage({
+            run_id: args.run_id,
+            worker_id: args.worker_id,
+            type: args.type,
+            cause_seq: args.cause_seq,
+            payload: args.payload ?? {},
+            available_at: args.available_at,
+            cooldown_ms: args.cooldown_ms,
+        });
+        return jsonResult(result);
+    }));
+}
+function registerCheckMessagesTool(registerTool) {
+    registerTool("check_messages", {
+        annotations: {
+            // Reads AND acknowledges (mutates pending -> acked), so not read-only and
+            // not idempotent: the first call returns+acks pending messages, later
+            // calls return none.
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: "Worker checkpoint poll for the LOCAL cooperative conductor relay. Call this at natural checkpoints to read " +
+            "any supervisor messages addressed to this worker. Returned messages are ACKNOWLEDGED by this call and are " +
+            "NOT redelivered on later polls. This is cooperative polling — it is NOT live prompt injection. " +
+            "run_id/worker_id default to BAPI_CONDUCTOR_RUN_ID / BAPI_CONDUCTOR_WORKER_ID from the environment when omitted. " +
+            "Local only; does not call the Bridge API.",
+        inputSchema: {
+            run_id: z.string().optional().describe("Run identifier (defaults to BAPI_CONDUCTOR_RUN_ID)."),
+            worker_id: z.string().optional().describe("Worker identifier (defaults to BAPI_CONDUCTOR_WORKER_ID)."),
+            limit: z.number().int().positive().max(100).optional().describe("Max messages to deliver/ack (default 10, max 100)."),
+        },
+    }, withConductorToolErrorHandling(async (args) => {
+        const runId = args.run_id ?? process.env.BAPI_CONDUCTOR_RUN_ID ?? "";
+        const workerId = args.worker_id ?? process.env.BAPI_CONDUCTOR_WORKER_ID ?? "";
+        if (runId.trim().length === 0 || workerId.trim().length === 0) {
+            throw new ConductorValidationError("Conductor worker identity is unavailable: provide run_id + worker_id, or set BAPI_CONDUCTOR_RUN_ID and BAPI_CONDUCTOR_WORKER_ID.");
+        }
+        const result = checkWorkerMessages({
+            run_id: runId,
+            worker_id: workerId,
+            limit: args.limit,
+        });
+        return jsonResult(result);
+    }));
+}
+/**
+ * Register all conductor MCP tools through the host's `registerTool` wrapper.
+ * Keeping registration in this single module keeps `index.ts` thin. The host's
+ * `registerTool` is the SDK's heavily-generic signature, so it is accepted as
+ * `unknown` here and narrowed once to {@link RegisterToolFn} — our handlers
+ * return the same `{ content: [{ type: "text", text }] }` shape every Bridge
+ * tool uses, just expressed with a simpler local type.
+ */
+export function registerConductorTools(registerTool) {
+    const reg = registerTool;
+    registerEmitEventTool(reg);
+    registerPollEventsTool(reg);
+    registerWaitForEventTool(reg);
+    registerGetSupervisorSnapshotTool(reg);
+    registerGetEpicSnapshotTool(reg);
+    registerWaitForDoneGateTool(reg);
+    registerSendMessageTool(reg);
+    registerCheckMessagesTool(reg);
+}

package/build/conductor/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared DTO/type contracts for the conductor event ledger.
+ *
+ * These types describe the envelope a caller emits, the row stored in SQLite,
+ * the compact vs. full read projections, the query filter, and the result
+ * shapes for each ledger operation. They are pure type declarations with no
+ * runtime behavior so every conductor module can depend on them freely.
+ */
+export {};

package/build/conductor-bin.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Standalone `conductor` bin entry.
+ *
+ * Allows the conductor CLI to be invoked directly (`conductor ...`) in addition
+ * to the package subcommand form (`@bridge_gpt/mcp-server conductor ...`) routed
+ * through index.ts. Both paths share the same {@link runConductorCli} dispatcher,
+ * which is async (the foreground `supervise` command is awaited) and resolves to
+ * an exit code; this wrapper is the only place that calls `process.exit`.
+ */
+import { runConductorCli } from "./conductor/cli.js";
+Promise.resolve(runConductorCli(process.argv.slice(2)))
+    .then((exitCode) => {
+    process.exit(exitCode);
+})
+    .catch(() => {
+    // Sanitized top-level catch: never print a stack trace, raw error, or
+    // secret material. A failure here is a non-zero exit.
+    process.stderr.write("Error: conductor command failed.\n");
+    process.exit(2);
+});

package/build/conductor-claude-hook-bin.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Standalone Claude Code → conductor lifecycle hook bin.
+ *
+ * Registered into a spawned Claude worker's `.claude/settings.local.json` by
+ * `start-tickets`. Claude Code pipes the native hook payload to this process on
+ * stdin; the runner maps it to a conductor event and shells to the `conductor`
+ * CLI. It is intentionally non-blocking: {@link runClaudeConductorHookCli}
+ * always returns `0`, and any unexpected top-level failure here also exits `0`
+ * so the Claude tool loop is never blocked by hook problems.
+ */
+import { runClaudeConductorHookCli } from "./conductor/claude-hook.js";
+let exitCode = 0;
+try {
+    exitCode = runClaudeConductorHookCli();
+}
+catch {
+    // Defensive: never let a hook failure propagate into the Claude tool loop.
+    exitCode = 0;
+}
+process.exit(exitCode);

package/build/credential-store.js

@@ -1,14 +1,26 @@
 /**
- * Resolver for Tier-1 bridge-api credentials.
+ * Resolver and writer for Tier-1 bridge-api credentials.
  *
  * Resolution order is env-first, then a user-scoped credentials file:
  *   1. `BAPI_API_KEY` in the process environment (overrides everything).
  *   2. `$XDG_CONFIG_HOME/bridge/credentials.json` (or `~/.config/bridge/credentials.json`).
  *   3. `~/.bridge/credentials.json` (only when the primary path is absent).
  *
- * The file is keyed by a logical target `bapi:<repoName>`. This module NEVER
- * creates or initializes credential files, and NEVER places secret values in
- * thrown errors, returned error strings, or stderr warnings.
+ * The file is keyed by a logical target `bapi:<repoName>`. The resolver NEVER
+ * creates or initializes credential files. The writer ({@link upsertBapiCredential})
+ * is the ONLY mutation primitive: it upserts a single key into the user-scoped
+ * primary store via explicit install/migration code paths, preserves every
+ * other entry, and never touches project/worktree config files (those remain
+ * secret-free). No code path here places secret values in thrown errors,
+ * returned error strings, or stderr warnings.
+ *
+ * Two-runtime credential rule: the MCP server process env and a Bash-spawned
+ * CLI (e.g. `start-tickets`) env are DIFFERENT runtime surfaces. A secret in
+ * `.mcp.json`/`.cursor/mcp.json` is visible to the MCP server but NOT to a
+ * shell-spawned CLI. Any shell-spawned, credential-bearing HTTP feature must
+ * therefore resolve credentials through {@link resolveBapiCredentials} /
+ * {@link resolveCredentialBundle}, and the durable source of truth is the
+ * user-scoped `~/.config/bridge/credentials.json` store written here.
  */
 import path from "path";
 // ---------------------------------------------------------------------------
@@ -230,3 +242,162 @@ export async function resolveBapiCredentials(repoName, deps) {
         credentials: { apiKey: result.values.BAPI_API_KEY, source: result.source },
     };
 }
+// ---------------------------------------------------------------------------
+// Writer (explicit install / migration paths only)
+// ---------------------------------------------------------------------------
+/** Serialize credential JSON deterministically: 2-space indent + trailing newline. */
+export function formatCredentialStoreJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/**
+ * Read an existing store file if present. Returns `{ state: "missing" }` on
+ * `ENOENT`, a parsed value on success, and a secret-free error otherwise. Never
+ * echoes file contents or secret values.
+ */
+async function readCredentialStoreJsonIfPresent(filePath, deps) {
+    let raw;
+    try {
+        raw = await deps.readFile(filePath);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code === "ENOENT") {
+            return { state: "missing" };
+        }
+        return {
+            state: "error",
+            kind: "read-error",
+            error: `Unable to read credentials file at ${filePath}.`,
+        };
+    }
+    const parsed = parseCredentialStoreJson(raw);
+    if (!parsed.ok) {
+        return {
+            state: "error",
+            kind: "parse-error",
+            error: `Invalid credentials file at ${filePath}: ${parsed.error}.`,
+        };
+    }
+    return { state: "present", value: parsed.value };
+}
+/**
+ * When the primary store does not yet exist, seed the new primary from the
+ * legacy fallback (`~/.bridge/credentials.json`) so its entries are not shadowed
+ * by the new primary going forward. A missing or malformed fallback yields an
+ * empty base and `migratedFallback: false` — never block or migrate broken JSON.
+ */
+async function mergeFallbackCredentialStoreOnFirstPrimaryWrite(deps) {
+    const fallbackPath = getFallbackCredentialStorePath(deps);
+    const fallback = await readCredentialStoreJsonIfPresent(fallbackPath, deps);
+    if (fallback.state === "present") {
+        return { base: { ...fallback.value }, migratedFallback: true };
+    }
+    return { base: {}, migratedFallback: false };
+}
+let tempSuffixCounter = 0;
+function defaultTempSuffix() {
+    tempSuffixCounter += 1;
+    return `${process.pid}.${tempSuffixCounter}`;
+}
+/**
+ * Upsert `BAPI_API_KEY` for `bapi:<repoName>` into the user-scoped PRIMARY
+ * credential store, atomically (temp file + rename) and secret-safely.
+ *
+ *   - Always targets {@link getPrimaryCredentialStorePath}; never writes the
+ *     fallback path and never touches project/worktree config.
+ *   - Preserves every existing top-level entry and every sibling secret under
+ *     `bapi:<repoName>`; replaces only `BAPI_API_KEY`.
+ *   - On a first primary write, seeds from the legacy fallback store so its
+ *     entries are not shadowed (`migratedFallback: true`).
+ *   - POSIX: writes mode `0600` and `chmod`s the temp file before rename.
+ *     `win32`: skips chmod and relies on user-profile ACLs.
+ *   - Returns a structured, secret-free result. The `apiKey` value never appears
+ *     in any returned error, even if an underlying I/O error message contains it.
+ */
+export async function upsertBapiCredential(repoName, apiKey, deps) {
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    const trimmedRepo = (repoName ?? "").trim();
+    const trimmedKey = (apiKey ?? "").trim();
+    // Derive the logical target WITHOUT lowercasing or otherwise canonicalizing.
+    const target = `bapi:${trimmedRepo}`;
+    if (trimmedRepo.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target: "bapi:",
+            kind: "invalid-repo",
+            error: "Cannot store BAPI_API_KEY: a non-empty repo name is required.",
+        };
+    }
+    if (trimmedKey.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "invalid-key",
+            error: `Cannot store BAPI_API_KEY for ${target}: the provided key was empty.`,
+        };
+    }
+    // Load the existing primary; if absent, seed from the legacy fallback store.
+    // NOTE: this load → merge → temp-write → rename sequence is NOT locked. It is
+    // safe because the writer only ever runs single-shot from the explicit
+    // install/migration paths; two genuinely concurrent upserts could last-writer-win
+    // and drop a sibling key. If a concurrent caller is ever added, introduce a lock.
+    const primary = await readCredentialStoreJsonIfPresent(primaryPath, deps);
+    let base;
+    let migratedFallback = false;
+    if (primary.state === "error") {
+        return { ok: false, path: primaryPath, target, kind: primary.kind, error: primary.error };
+    }
+    if (primary.state === "present") {
+        base = { ...primary.value };
+    }
+    else {
+        const seeded = await mergeFallbackCredentialStoreOnFirstPrimaryWrite(deps);
+        base = seeded.base;
+        migratedFallback = seeded.migratedFallback;
+    }
+    const existingEntry = base[target];
+    const hadKey = !!existingEntry &&
+        typeof existingEntry.BAPI_API_KEY === "string" &&
+        existingEntry.BAPI_API_KEY.length > 0;
+    const action = hadKey ? "updated" : "created";
+    // Preserve sibling secret names; replace ONLY BAPI_API_KEY.
+    const nextEntry = { ...(existingEntry ?? {}), BAPI_API_KEY: trimmedKey };
+    const next = { ...base, [target]: nextEntry };
+    const dir = path.dirname(primaryPath);
+    const suffix = (deps.tempSuffix ?? defaultTempSuffix)();
+    const tempPath = path.join(dir, `${path.basename(primaryPath)}.${suffix}.tmp`);
+    const json = formatCredentialStoreJson(next);
+    const isPosix = deps.platform !== "win32";
+    try {
+        await deps.mkdir(dir, { recursive: true });
+        const writeOptions = isPosix
+            ? { encoding: "utf-8", mode: 0o600 }
+            : { encoding: "utf-8" };
+        await deps.writeFile(tempPath, json, writeOptions);
+        if (isPosix) {
+            await deps.chmod(tempPath, 0o600);
+        }
+        await deps.rename(tempPath, primaryPath);
+    }
+    catch {
+        // Best-effort temp cleanup; never surface the secret or the raw I/O message.
+        if (deps.unlink) {
+            try {
+                await deps.unlink(tempPath);
+            }
+            catch {
+                /* cleanup failure must not mask the primary write error */
+            }
+        }
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "write-error",
+            error: `Failed to write credentials file at ${primaryPath}.`,
+        };
+    }
+    return { ok: true, path: primaryPath, target, action, migratedFallback };
+}