@bridge_gpt/mcp-server 0.2.2 → 0.2.3

package/build/start-tickets-conductor.js

@@ -0,0 +1,496 @@
+/**
+ * Conductor identity, hook provisioning, and run-level emission for
+ * `start-tickets` (BAPI-394, conductor C2 — Claude Code producer run).
+ *
+ * This module is the seam between the start-tickets orchestration pipeline and
+ * the local conductor event ledger. It:
+ *
+ *   - mints a single per-invocation `run_id` and a unique `worker_id` per Claude
+ *     worker (Langfuse-style `{ticket}-{automation}-{frag}` identifiers),
+ *   - builds the secret-free per-worker environment injected at the spawn
+ *     boundary so each spawned Claude session inherits ONLY its own conductor
+ *     identity,
+ *   - merges a Claude lifecycle hook registration into each created worktree's
+ *     `.claude/settings.local.json` (idempotent, preserving existing hooks),
+ *   - emits one canonical `run.started` event for a real invocation,
+ *   - renders per-row conductor env into the spawned shell command string.
+ *
+ * Everything here is secret-free by construction: no API keys, tokens, auth
+ * headers, or raw payload material are ever placed in env, hook commands, run
+ * metadata, or the shell command string.
+ */
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
+// ---------------------------------------------------------------------------
+// Identity minting
+// ---------------------------------------------------------------------------
+/** Short lowercase-hex correlation fragment (4 bytes -> 8 hex chars). */
+export function randomCorrelationFragment() {
+    return randomBytes(4).toString("hex");
+}
+/** Sanitize an automation/agent segment to `[A-Za-z0-9_-]`. */
+function sanitizeIdSegment(value) {
+    return value.replace(/[^A-Za-z0-9_-]/g, "-");
+}
+/**
+ * Mint the single per-invocation run id, `{firstTicket}-start-tickets-{frag}`
+ * (e.g. `BAPI-392-start-tickets-a1b2c3d4`). The fragment is injectable for
+ * deterministic tests.
+ */
+export function mintStartTicketsRunId(keys, fragment = randomCorrelationFragment()) {
+    const ticket = keys.length > 0 ? keys[0] : "start-tickets";
+    return `${ticket}-start-tickets-${fragment}`;
+}
+/**
+ * Mint a per-worker id, `{ticket}-{agent}-{frag}` (e.g.
+ * `BAPI-392-claude-a1b2c3d4`). The agent segment is sanitized to
+ * `[A-Za-z0-9_-]`. The fragment is injectable for deterministic tests.
+ */
+export function mintStartTicketsWorkerId(ticketKey, agentName, fragment = randomCorrelationFragment()) {
+    return `${ticketKey}-${sanitizeIdSegment(agentName)}-${fragment}`;
+}
+/**
+ * Build the secret-free epic identity env keys from an {@link EpicDispatchIdentity}.
+ * Strict allowlist — constructs a FRESH object with exactly three named keys,
+ * never copies arbitrary parent env so credentials cannot leak.
+ */
+export function buildEpicIdentityEnv(epic) {
+    return {
+        BAPI_CONDUCTOR_EPIC_KEY: epic.epic_key,
+        BAPI_CONDUCTOR_EPIC_RUN_ID: epic.epic_run_id,
+        BAPI_CONDUCTOR_PLAN_VERSION: String(epic.plan_version),
+    };
+}
+// ---------------------------------------------------------------------------
+// Conductor context
+// ---------------------------------------------------------------------------
+/** Default gate name when no `BAPI_CONDUCTOR_GATE_NAME` override is present. */
+export const DEFAULT_CONDUCTOR_GATE_NAME = "implement-ticket";
+/** Resolve a packaged build artifact path relative to this compiled module. */
+function defaultResolveBinPath(filename) {
+    return fileURLToPath(new URL(`./${filename}`, import.meta.url));
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Resolve the conductor context once per invocation, after agent/platform
+ * resolution and before any rows are spawned. Repo resolution is fail-soft
+ * (`null` on any error). Gate/supervisor honour env overrides; supervisor
+ * defaults to `auto` for auto-approved runs and `interactive` otherwise.
+ */
+export async function createStartTicketsConductorContext(options, agent, deps) {
+    const resolveRepoName = deps.resolveRepoName ?? resolveStartTicketsRepoName;
+    let repoName = null;
+    try {
+        repoName = await resolveRepoName({ env: deps.env, cwd: deps.cwd, readFile: deps.readFile });
+    }
+    catch {
+        // Repo resolution must never abort conductor setup; fall back to null.
+        repoName = null;
+    }
+    const gateName = nonEmpty(deps.env.BAPI_CONDUCTOR_GATE_NAME)
+        ? deps.env.BAPI_CONDUCTOR_GATE_NAME.trim()
+        : DEFAULT_CONDUCTOR_GATE_NAME;
+    const supervisorMode = nonEmpty(deps.env.BAPI_CONDUCTOR_SUPERVISOR_MODE)
+        ? deps.env.BAPI_CONDUCTOR_SUPERVISOR_MODE.trim()
+        : options.autoApprove
+            ? "auto"
+            : "interactive";
+    const resolveBinPath = deps.resolveBinPath ?? defaultResolveBinPath;
+    const context = {
+        runId: mintStartTicketsRunId(options.keys, deps.fragment),
+        repoName,
+        gateName,
+        supervisorMode,
+        agentName: agent.name,
+        cliFile: resolveBinPath("conductor-bin.js"),
+        hookBinPath: resolveBinPath("conductor-claude-hook-bin.js"),
+    };
+    if (options.epic) {
+        context.epic = options.epic;
+    }
+    return context;
+}
+// ---------------------------------------------------------------------------
+// Per-worker environment
+// ---------------------------------------------------------------------------
+/** Conductor store-tuning env keys forwarded only when already set upstream. */
+const CONDUCTOR_TUNING_ENV_KEYS = [
+    "BAPI_CONDUCTOR_BUSY_TIMEOUT_MS",
+    "BAPI_CONDUCTOR_RETENTION_DAYS",
+    "BAPI_CONDUCTOR_RETENTION_MAX_ROWS",
+    // BAPI-397: per-type relay cooldown — forwarded only when explicitly set so a
+    // worker's check_messages cooldown probe matches the supervisor's send config.
+    "BAPI_CONDUCTOR_MESSAGE_COOLDOWN_MS",
+];
+/** Truthy predicate for opt-in conductor boolean flags (`1` / `true`). */
+export function isConductorFlagEnabled(value) {
+    if (typeof value !== "string")
+        return false;
+    const v = value.trim().toLowerCase();
+    return v === "1" || v === "true";
+}
+/**
+ * Build the secret-free per-worker conductor environment. Constructs a FRESH
+ * object containing only the allowlisted conductor keys — it never copies
+ * arbitrary parent env, so secrets/tokens/headers cannot leak. `PreToolUse`
+ * propagation and store-tuning keys are forwarded only when explicitly present
+ * upstream.
+ */
+export function buildConductorWorkerEnv(context, worker, parentEnv) {
+    const env = {
+        BAPI_CONDUCTOR_ENABLED: "1",
+        BAPI_CONDUCTOR_RUN_ID: context.runId,
+        BAPI_CONDUCTOR_WORKER_ID: worker.workerId,
+        BAPI_CONDUCTOR_TICKET_KEY: worker.ticketKey,
+        BAPI_CONDUCTOR_WORKTREE_PATH: worker.worktreePath,
+        BAPI_CONDUCTOR_GATE_NAME: context.gateName,
+        BAPI_CONDUCTOR_SUPERVISOR_MODE: context.supervisorMode,
+        BAPI_CONDUCTOR_CLI_FILE: context.cliFile,
+    };
+    if (context.repoName) {
+        env.BAPI_CONDUCTOR_REPO_NAME = context.repoName;
+    }
+    if (context.epic) {
+        const epicEnv = buildEpicIdentityEnv(context.epic);
+        for (const [k, v] of Object.entries(epicEnv)) {
+            env[k] = v;
+        }
+    }
+    if (isConductorFlagEnabled(parentEnv.BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE)) {
+        env.BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE = "1";
+    }
+    for (const key of CONDUCTOR_TUNING_ENV_KEYS) {
+        if (nonEmpty(parentEnv[key])) {
+            env[key] = parentEnv[key].trim();
+        }
+    }
+    return env;
+}
+// ---------------------------------------------------------------------------
+// Claude hook settings merge / provisioning
+// ---------------------------------------------------------------------------
+/** Claude lifecycle events always registered for the conductor hook. */
+export const CONDUCTOR_HOOK_LIFECYCLE_EVENTS = [
+    "SessionStart",
+    "Stop",
+    "SubagentStop",
+    "Notification",
+];
+/** Broad matcher used for `PreToolUse` when no existing matcher is present. */
+export const DEFAULT_PRE_TOOL_USE_MATCHER = "*";
+/** Shell-quote a path for embedding in a hook command string. */
+function shellQuotePath(value) {
+    // Single-quote for POSIX safety; embedded single quotes are escaped. Hook
+    // command strings are interpreted by Claude Code's shell.
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Resolve the hook command string. Prefers `BAPI_CONDUCTOR_HOOK_COMMAND`
+ * verbatim; otherwise runs the packaged hook bin via the current Node
+ * executable.
+ */
+export function resolveConductorHookCommand(env, hookBinPath, execPath = process.execPath) {
+    if (nonEmpty(env.BAPI_CONDUCTOR_HOOK_COMMAND)) {
+        return env.BAPI_CONDUCTOR_HOOK_COMMAND;
+    }
+    return `${shellQuotePath(execPath)} ${shellQuotePath(hookBinPath)}`;
+}
+function asHookEntries(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** Does this event already register `command` as a command hook? */
+function entriesContainCommand(entries, command) {
+    return entries.some((entry) => Array.isArray(entry?.hooks) &&
+        entry.hooks.some((h) => h && h.type === "command" && h.command === command));
+}
+/**
+ * Merge conductor lifecycle hooks into an existing Claude settings object
+ * WITHOUT removing any existing settings or hooks. Idempotent: re-applying the
+ * same command never duplicates an entry. `PreToolUse` is registered only when
+ * `enablePreToolUse` is true, mirroring any existing matcher style.
+ */
+export function mergeClaudeSettingsWithConductorHook(settings, command, options = {}) {
+    const existingHooks = settings.hooks !== null && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
+        ? settings.hooks
+        : {};
+    const hooks = { ...existingHooks };
+    const events = [...CONDUCTOR_HOOK_LIFECYCLE_EVENTS];
+    if (options.enablePreToolUse) {
+        events.push("PreToolUse");
+    }
+    for (const event of events) {
+        const entries = asHookEntries(hooks[event]);
+        if (entriesContainCommand(entries, command)) {
+            // Idempotent: already registered for this event.
+            hooks[event] = entries;
+            continue;
+        }
+        const newEntry = { hooks: [{ type: "command", command }] };
+        if (event === "PreToolUse") {
+            newEntry.matcher = options.preToolUseMatcher ?? DEFAULT_PRE_TOOL_USE_MATCHER;
+        }
+        hooks[event] = [...entries, newEntry];
+    }
+    return { ...settings, hooks };
+}
+/** Detect an existing PreToolUse matcher to mirror, if any. */
+function detectExistingPreToolUseMatcher(settings) {
+    const hooks = settings.hooks;
+    if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks))
+        return undefined;
+    const entries = asHookEntries(hooks.PreToolUse);
+    for (const entry of entries) {
+        if (typeof entry?.matcher === "string")
+            return entry.matcher;
+    }
+    return undefined;
+}
+/**
+ * Provision the conductor Claude hook into ONE worktree's
+ * `.claude/settings.local.json`. Missing settings are treated as `{}`; malformed
+ * JSON is a per-row safety failure (the user's file is never overwritten). Writes
+ * pretty-printed JSON, mirroring any existing PreToolUse matcher.
+ */
+export async function provisionConductorHookForWorktree(worktreePath, command, options, deps) {
+    const claudeDir = path.join(worktreePath, ".claude");
+    const settingsPath = path.join(claudeDir, "settings.local.json");
+    let existing = {};
+    let raw = null;
+    try {
+        raw = await deps.readFile(settingsPath);
+    }
+    catch {
+        // Missing file -> treat as empty settings.
+        raw = null;
+    }
+    if (raw !== null) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                return {
+                    ok: false,
+                    reason: "malformed",
+                    error: "existing .claude/settings.local.json is not a JSON object",
+                };
+            }
+            existing = parsed;
+        }
+        catch {
+            // Malformed JSON: fail the row rather than clobber the user's file. The
+            // error is generic — it never echoes the file contents.
+            return {
+                ok: false,
+                reason: "malformed",
+                error: "existing .claude/settings.local.json contains invalid JSON",
+            };
+        }
+    }
+    const merged = mergeClaudeSettingsWithConductorHook(existing, command, {
+        enablePreToolUse: options.enablePreToolUse,
+        preToolUseMatcher: options.preToolUseMatcher ?? detectExistingPreToolUseMatcher(existing),
+    });
+    try {
+        await deps.mkdir(claudeDir, { recursive: true });
+        await deps.writeFile(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
+    }
+    catch {
+        // Best-effort: a write/mkdir failure must not block the actual work.
+        return { ok: false, reason: "io", error: "failed to write .claude/settings.local.json" };
+    }
+    return { ok: true };
+}
+/**
+ * Provision conductor identity across rows. Attaches `runId` to EVERY row (so
+ * the run-level event can attribute all of them), and — for created Claude rows
+ * with a path — mints a `workerId`, builds the per-worker env, and writes the
+ * hook file. Non-Claude rows get the `runId` only (no Claude hook file).
+ * Malformed-settings / write failures mark only the affected row `spawn-failed`.
+ */
+export async function provisionConductorHooksForRows(rows, context, deps) {
+    const isClaude = context.agentName === "claude";
+    const enablePreToolUse = isConductorFlagEnabled(deps.env.BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE);
+    const command = resolveConductorHookCommand(deps.env, context.hookBinPath, deps.execPath);
+    const fragment = deps.workerFragment;
+    const out = [];
+    for (const row of rows) {
+        // Every row carries the run id.
+        const base = { ...row, runId: context.runId };
+        if (row.status !== "created" || !row.path) {
+            out.push(base);
+            continue;
+        }
+        if (!isClaude) {
+            // Non-Claude agents: run-level event still applies, but no Claude hook
+            // file or Claude-only worker env is injected.
+            out.push(base);
+            continue;
+        }
+        const workerId = mintStartTicketsWorkerId(row.key, context.agentName, fragment ? fragment() : randomCorrelationFragment());
+        const conductorEnv = buildConductorWorkerEnv(context, { workerId, ticketKey: row.key, worktreePath: row.path }, deps.env);
+        const result = await provisionConductorHookForWorktree(row.path, command, { enablePreToolUse }, deps);
+        if (!result.ok) {
+            // Either failure mode — a malformed existing settings file we refuse to
+            // clobber, or a best-effort I/O failure — skips hook injection but must
+            // NOT cancel the spawn: conductor observability never blocks the actual
+            // work (see the fail-open principle documented throughout). We still never
+            // overwrite the user's file; we simply attach a non-fatal warning and let
+            // the worker spawn.
+            out.push({
+                ...base,
+                workerId,
+                warnings: [...(base.warnings ?? []), `conductor hook not injected: ${result.error}`],
+            });
+            continue;
+        }
+        out.push({
+            ...base,
+            workerId,
+            conductorEnv,
+            conductorHookInjected: true,
+        });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// run.started emission
+// ---------------------------------------------------------------------------
+/**
+ * Build the canonical `run.started` event. Run-level metadata lives under
+ * `data.details` (never as non-allowlisted top-level data keys). Subject is the
+ * repo name when known, else the first requested ticket key.
+ */
+export function buildStartTicketsRunStartedEventInput(context, rows, options) {
+    const worktreeRows = rows.filter((r) => typeof r.path === "string" && r.path.length > 0);
+    const workers = worktreeRows.map((r) => ({
+        ticket_key: r.key,
+        worker_id: r.workerId ?? null,
+        worktree_path: r.path ?? null,
+        status: r.status,
+    }));
+    const subject = context.repoName ?? (options.keys.length > 0 ? options.keys[0] : "start-tickets");
+    return {
+        source: "start-tickets",
+        type: "run.started",
+        run_id: context.runId,
+        producer: "bridge-api-mcp-server",
+        observed_via: "start-tickets",
+        subject,
+        data: {
+            summary: "start-tickets run started",
+            status: "started",
+            details: {
+                repo: context.repoName,
+                requested_ticket_keys: options.keys,
+                ticket_keys: worktreeRows.map((r) => r.key),
+                worktree_paths: worktreeRows.map((r) => r.path),
+                workers,
+                gate_name: context.gateName,
+                supervisor_mode: context.supervisorMode,
+                dry_run: options.dryRun,
+                agent: context.agentName,
+                ...(context.epic
+                    ? {
+                        epic_key: context.epic.epic_key,
+                        epic_run_id: context.epic.epic_run_id,
+                        plan_version: context.epic.plan_version,
+                    }
+                    : {}),
+            },
+        },
+    };
+}
+/** Generic, secret-free warning appended when run-start emission fails. */
+export const CONDUCTOR_RUN_START_EMIT_FAILED_WARNING = "conductor run-start emit failed (continuing without run-level event)";
+/**
+ * Emit the run-level `run.started` event. Best-effort: any emission error
+ * appends a generic, secret-free warning to the first row rather than aborting
+ * the start-tickets run.
+ */
+export async function emitStartTicketsRunStarted(context, rows, options, deps = {}) {
+    const event = buildStartTicketsRunStartedEventInput(context, rows, options);
+    try {
+        if (deps.emit) {
+            deps.emit(event);
+        }
+        else {
+            const { emitConductorEvent } = await import("./conductor/store.js");
+            emitConductorEvent(event);
+        }
+        return rows;
+    }
+    catch {
+        if (rows.length === 0)
+            return rows;
+        const [first, ...rest] = rows;
+        const warned = {
+            ...first,
+            warnings: [...(first.warnings ?? []), CONDUCTOR_RUN_START_EMIT_FAILED_WARNING],
+        };
+        return [warned, ...rest];
+    }
+}
+// ---------------------------------------------------------------------------
+// Shell-command env injection (spawn boundary)
+// ---------------------------------------------------------------------------
+/** Valid env key shape rendered into a shell command. */
+const ENV_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+/** POSIX single-quote escape (close, escaped quote, reopen). */
+function posixSingleQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/** PowerShell single-quote escape (double any single quote). */
+function powershellSingleQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * Prepend per-row conductor env assignments to a spawned shell command so the
+ * env is scoped to that one terminal/tab/session only. POSIX uses
+ * `export KEY='value';`; Windows uses `$env:KEY='value';`. Invalid keys are
+ * skipped. Never mutates process/global env.
+ */
+export function injectConductorEnvIntoShellCommand(platform, shellCommand, env) {
+    if (!env)
+        return shellCommand;
+    const entries = Object.entries(env).filter(([key]) => ENV_KEY_PATTERN.test(key));
+    if (entries.length === 0)
+        return shellCommand;
+    const isWindows = platform === "win32";
+    const assignments = entries
+        .map(([key, value]) => isWindows
+        ? `$env:${key}=${powershellSingleQuote(value)};`
+        : `export ${key}=${posixSingleQuote(value)};`)
+        .join(" ");
+    return `${assignments} ${shellCommand}`;
+}
+// ---------------------------------------------------------------------------
+// Supervisor peer-tab launch (BAPI-396, conductor C4)
+// ---------------------------------------------------------------------------
+/** Spawn-context key suffix that identifies the supervisor tab. */
+export const SUPERVISOR_SPAWN_KEY_SUFFIX = "supervisor";
+/**
+ * Build the supervisor peer-tab shell command, `node <cliFile> supervise
+ * --run-id <runId>`. The node executable, the packaged `cliFile`, and the run id
+ * are shell-quoted with the SAME platform helpers used for worker commands
+ * (POSIX single-quote / PowerShell single-quote) so paths with spaces are safe.
+ */
+export function buildSupervisorTabCommand(context, platform, nodeExecPath = process.execPath) {
+    const quote = platform === "win32" ? powershellSingleQuote : posixSingleQuote;
+    return `${quote(nodeExecPath)} ${quote(context.cliFile)} supervise --run-id ${quote(context.runId)}`;
+}
+/**
+ * Decide whether the supervisor peer tab should launch. Enabled by default for a
+ * normal packaged conductor context; disabled only when the resolved supervisor
+ * mode is `off` (i.e. `BAPI_CONDUCTOR_SUPERVISOR_MODE=off`).
+ */
+export function isSupervisorLaunchEnabled(context) {
+    return context.supervisorMode.trim().toLowerCase() !== "off";
+}
+/** Build the spawn-context key that identifies the supervisor tab for a run. */
+export function supervisorSpawnKey(keys) {
+    const firstTicket = keys.length > 0 ? keys[0] : "start-tickets";
+    return `${firstTicket}-${SUPERVISOR_SPAWN_KEY_SUFFIX}`;
+}

package/build/start-tickets-prereqs.js

@@ -13,8 +13,8 @@
  * the runtime graph stays acyclic — `start-tickets.ts` imports values FROM here,
  * never the reverse.
  */
-import { resolveBapiCredentials } from "./credential-store.js";
-import { readBridgeConfig } from "./bridge-config.js";
+import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
+import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
 // ---------------------------------------------------------------------------
 // Constants (moved here from start-tickets.ts so both consumers share them)
@@ -254,8 +254,10 @@ function uvDescriptor() {
     return commandDescriptor("uv", "uv", UV_INSTALL_HINTS);
 }
 /** Secret-free remediation hint shared by the credential-resolution descriptor. */
-const CREDENTIAL_RESOLUTION_HINT = 'Set BAPI_API_KEY in the environment, or add it under "bapi:<repo_name>" in ' +
-    "~/.config/bridge/credentials.json.";
+const CREDENTIAL_RESOLUTION_HINT = "Rerun /install-bridge to persist the routing credential, set BAPI_API_KEY in the " +
+    'environment, or add it under "bapi:<repo_name>" in ~/.config/bridge/credentials.json. ' +
+    "To migrate a key that only lives in .mcp.json / .cursor/mcp.json, run: " +
+    "npx -y @bridge_gpt/mcp-server credentials migrate-agent-config --write-credentials.";
 const CREDENTIAL_RESOLUTION_INSTALL_HINTS = {
     darwin: CREDENTIAL_RESOLUTION_HINT,
     linux: CREDENTIAL_RESOLUTION_HINT,
@@ -263,9 +265,11 @@ const CREDENTIAL_RESOLUTION_INSTALL_HINTS = {
 };
 /**
  * Doctor-only, strictly read-only probe: can the Bridge API credentials be
- * resolved for the current repo? Resolves repo identity from `BAPI_REPO_NAME`
- * first, then `.bridge/config`, then asks the credential resolver. Reports only
- * the SOURCE CLASS (env vs. store) — NEVER the resolved key value.
+ * resolved for the current repo? Resolves repo identity via the SHARED
+ * {@link resolveStartTicketsRepoName} helper (so it can never drift from what
+ * `start-tickets` itself uses), then asks the credential resolver. Reports the
+ * exact resolver path/source — env vs. `store target bapi:<repo>` at the primary
+ * store path — but NEVER the resolved key value. This probe performs NO writes.
  */
 export function credentialResolutionDescriptor() {
     return {
@@ -277,20 +281,19 @@ export function credentialResolutionDescriptor() {
             if (!readFile || !stat || !homedir) {
                 return { found: false, detail: "credential probe unavailable (no read-only filesystem access)" };
             }
-            let repoName = (deps.env.BAPI_REPO_NAME ?? "").trim();
-            if (repoName.length === 0) {
-                const read = await readBridgeConfig(deps.cwd, { readFile });
-                if (read.ok) {
-                    repoName = read.manifest.repoName;
-                }
-                else {
-                    return {
-                        found: false,
-                        detail: "cannot determine repo identity (set BAPI_REPO_NAME or add a valid .bridge/config). " +
-                            CREDENTIAL_RESOLUTION_HINT,
-                    };
-                }
+            const repoName = await resolveStartTicketsRepoName({
+                env: deps.env,
+                cwd: deps.cwd,
+                readFile,
+            });
+            if (!repoName) {
+                return {
+                    found: false,
+                    detail: "cannot determine repo identity (set BAPI_REPO_NAME or add a valid .bridge/config). " +
+                        CREDENTIAL_RESOLUTION_HINT,
+                };
             }
+            const storePath = getPrimaryCredentialStorePath({ env: deps.env, homedir });
             const result = await resolveBapiCredentials(repoName, {
                 env: deps.env,
                 homedir,
@@ -299,10 +302,16 @@ export function credentialResolutionDescriptor() {
                 stat,
             });
             if (result.ok) {
-                const via = result.credentials.source === "env" ? "env" : "store";
-                return { found: true, detail: `credentials resolvable via ${via}` };
+                const detail = result.credentials.source === "env"
+                    ? `credentials resolvable via env for repo ${repoName}`
+                    : `credentials resolvable via store target bapi:${repoName} at ${storePath}`;
+                return { found: true, detail };
             }
-            return { found: false, detail: CREDENTIAL_RESOLUTION_HINT };
+            return {
+                found: false,
+                detail: `no usable BAPI_API_KEY for bapi:${repoName} (store path ${storePath}). ` +
+                    CREDENTIAL_RESOLUTION_HINT,
+            };
         },
     };
 }

package/build/start-tickets-repo.js

@@ -0,0 +1,49 @@
+/**
+ * Shared repo-name discovery for `start-tickets`, `doctor`, credential migration,
+ * and install-time persistence.
+ *
+ * Keeping repo identity resolution in ONE module guarantees the `bapi:<repo>`
+ * store-target identity cannot drift between the credential writer, the resolver,
+ * the doctor probe, and the routing layer. The resolution order is always:
+ *   1. a trimmed, non-empty `BAPI_REPO_NAME` env value, then
+ *   2. `repoName` from `.bridge/config` under the working directory.
+ */
+import { readBridgeConfig } from "./bridge-config.js";
+/**
+ * Resolve the repo name: prefer a trimmed, non-empty `BAPI_REPO_NAME`, then
+ * `.bridge/config` under `deps.cwd`. Returns `null` when neither is available.
+ * Never throws — a malformed/unreadable config simply falls through to `null`.
+ */
+export async function resolveStartTicketsRepoName(deps) {
+    const fromEnv = deps.env.BAPI_REPO_NAME;
+    if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+        return fromEnv.trim();
+    }
+    try {
+        const result = await readBridgeConfig(deps.cwd, { readFile: deps.readFile });
+        if (result.ok && result.manifest.repoName) {
+            return result.manifest.repoName;
+        }
+    }
+    catch {
+        // A read/parse failure is non-fatal here — fall through to null. The error
+        // is never surfaced (it could echo file contents), keeping this secret-free.
+    }
+    return null;
+}
+/**
+ * Required variant: returns a structured, secret-free `repo-missing` failure when
+ * neither env nor `.bridge/config` resolves the repo. Use this where the caller
+ * must distinguish "no repo identity" from other routing/credential failures.
+ */
+export async function resolveRequiredStartTicketsRepoName(deps) {
+    const repoName = await resolveStartTicketsRepoName(deps);
+    if (!repoName) {
+        return {
+            ok: false,
+            kind: "repo-missing",
+            error: "could not resolve repo name (set BAPI_REPO_NAME or add a valid .bridge/config)",
+        };
+    }
+    return { ok: true, repoName };
+}