@bridge_gpt/mcp-server 0.1.17 → 0.2.1

package/build/schedule-store.js

@@ -11,6 +11,10 @@
  */
 import { promises as fs } from "node:fs";
 import { pathApiForPlatform } from "./scheduler-backends/types.js";
+/** Upper bound on retained run-history events per schedule (oldest dropped). */
+export const MAX_RUN_HISTORY_EVENTS = 50;
+/** Monotonic suffix source for atomic temp files (avoids same-tick collisions). */
+let atomicWriteCounter = 0;
 /**
  * Build the schedule root from the injected home directory and platform path
  * API: `~/.bridge-gpt/schedules` on POSIX, `%USERPROFILE%\.bridge-gpt\schedules`
@@ -47,10 +51,46 @@ export async function ensureScheduleDirectories(homeDir, platform) {
 /**
  * Persist one pretty-printed JSON file per schedule id with a trailing newline.
  * Called only AFTER the scheduler backend successfully creates the unit/job.
+ *
+ * The write is atomic (BAPI-351): the content is written to a temp file in the
+ * same directory and renamed into place, so a concurrent `_execute` run-history
+ * append never observes a partially-written metadata file, and a crash mid-write
+ * leaves the prior valid file intact rather than a truncated one.
  */
 export async function writeScheduleMetadata(metadata, homeDir, platform) {
     const { metadataPath } = getSchedulePaths(metadata.id, homeDir, platform);
-    await fs.writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
+    const content = `${JSON.stringify(metadata, null, 2)}\n`;
+    const tmpPath = `${metadataPath}.tmp-${process.pid}-${atomicWriteCounter++}`;
+    try {
+        await fs.writeFile(tmpPath, content, "utf-8");
+        await fs.rename(tmpPath, metadataPath);
+    }
+    catch (error) {
+        // Best-effort cleanup of the temp file; never leave it orphaned, and never
+        // partially overwrite the real metadata file.
+        await fs.unlink(tmpPath).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Append a bounded run-history event to a schedule's metadata and rewrite it
+ * atomically (BAPI-351). Tolerant of legacy records that have no `run_history`
+ * (initializes it). Returns the updated metadata, or `null` if the schedule
+ * metadata no longer exists.
+ */
+export async function appendScheduleRunEvent(id, event, homeDir, platform) {
+    const metadata = await readScheduleMetadata(id, homeDir, platform);
+    if (!metadata)
+        return null;
+    const history = Array.isArray(metadata.run_history) ? [...metadata.run_history] : [];
+    history.push(event);
+    // Keep the newest events when bounding (drop from the front).
+    metadata.run_history =
+        history.length > MAX_RUN_HISTORY_EVENTS
+            ? history.slice(history.length - MAX_RUN_HISTORY_EVENTS)
+            : history;
+    await writeScheduleMetadata(metadata, homeDir, platform);
+    return metadata;
 }
 /** Read and parse a single schedule metadata JSON file; `null` when missing. */
 export async function readScheduleMetadata(id, homeDir, platform) {

package/build/scheduled-prompt.js

@@ -0,0 +1,109 @@
+import { schemaSupportsAutoFlag } from "./command-catalog.js";
+/** The fixed late-fire threshold, in seconds, shared by every scheduled run. */
+export const LATE_FIRE_THRESHOLD_SECONDS = 60;
+/**
+ * Quote a single argument token for safe inclusion in the rendered prompt while
+ * preserving its boundary. Simple tokens (alphanumerics plus a small set of
+ * path/flag-safe punctuation) are left bare; anything containing whitespace or
+ * prompt/markup-sensitive characters is wrapped in double quotes with embedded
+ * double quotes escaped. This is prompt-token quoting, NOT shell quoting — no
+ * shell ever sees these strings.
+ */
+export function quotePromptToken(token) {
+    if (token === "")
+        return '""';
+    // Safe: letters, digits, and characters that never need quoting in a prompt
+    // (path separators, ISO-timestamp punctuation, flag dashes, etc.).
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(token))
+        return token;
+    return `"${token.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Compute the augmented argv tokens the scheduled run delegates to the command:
+ * the normalized `input.args`, plus (only where the command can parse them)
+ * `--scheduled-at <ISO>` and `--auto`.
+ *
+ * `--scheduled-at` is appended ONLY for the legacy `full-automation` command,
+ * whose Stage 0 parses it and whose drift stage consumes it. Every other command
+ * rejects unrecognized flags and halts (e.g. `start-tickets` stops on any
+ * unsupported flag), and the shared late-fire gate already embeds the scheduled
+ * time — so injecting `--scheduled-at` into their argv would break an otherwise
+ * `schedulable: true` command for no benefit.
+ *
+ * `--auto` is appended when auto-approve is set AND the command supports it (its
+ * schema declares a boolean `--auto` flag, or it is `full-automation`). It is
+ * never duplicated if already present in `input.args`.
+ *
+ * This is the SINGLE source of the delegated argv: both the rendered target
+ * command line and the `$ARGUMENTS` body substitution derive from it, so the body
+ * parse and the command line never disagree (e.g. `review-ticket`, which reads
+ * `--auto` out of `$ARGUMENTS`, sees the same `--auto` the command line shows).
+ */
+export function buildAugmentedArgs(input) {
+    const args = [...input.args];
+    if (input.commandName === "full-automation") {
+        args.push("--scheduled-at", input.scheduledAt);
+    }
+    const supportsAuto = schemaSupportsAutoFlag(input.schema) || input.commandName === "full-automation";
+    const alreadyHasAuto = input.args.includes("--auto");
+    if (input.autoApprove && supportsAuto && !alreadyHasAuto) {
+        args.push("--auto");
+    }
+    return args;
+}
+/**
+ * Render the delegated target command line as
+ * `/<commandName> <augmented args...>` (see {@link buildAugmentedArgs}).
+ */
+export function buildTargetCommandLine(input) {
+    const parts = [`/${input.commandName}`];
+    for (const arg of buildAugmentedArgs(input))
+        parts.push(quotePromptToken(arg));
+    return parts.join(" ");
+}
+/** Render only the fixed late-fire gate text (exposed for focused testing). */
+export function renderLateFireGate(scheduleId, scheduledAt, autoApprove) {
+    const lateAction = autoApprove
+        ? "explain that the run is firing late and then PROCEED with the command below (this schedule was created with auto-approve)."
+        : "explain that the run is firing late and then HALT WITHOUT EXECUTING the command below (this schedule was created without auto-approve, and a headless run must not proceed unconfirmed).";
+    return [
+        "## Scheduled-run drift gate",
+        "",
+        `This is an automated, headless scheduled run (schedule id: ${scheduleId}).`,
+        `It was scheduled to fire at ${scheduledAt}.`,
+        "",
+        `Before doing anything else, check how late this run is firing. If it is more than ${LATE_FIRE_THRESHOLD_SECONDS} seconds later than the scheduled time above, ${lateAction}`,
+        `If it is within ${LATE_FIRE_THRESHOLD_SECONDS} seconds of the scheduled time, proceed silently.`,
+        "",
+        "Then run the following command exactly as written:",
+    ].join("\n");
+}
+/**
+ * Replace `$ARGUMENTS` in a command body with the safely-quoted, normalized
+ * argument string. Every occurrence is replaced (commands often repeat the
+ * placeholder in a title and a body line).
+ */
+function replaceArgumentsPlaceholder(body, argString) {
+    return body.split("$ARGUMENTS").join(argString);
+}
+/**
+ * Render the full scheduled-run prompt: gate + delegated command line + command
+ * body (with `$ARGUMENTS` substituted). Deterministic for identical inputs.
+ */
+export function renderScheduledPrompt(input) {
+    const gate = renderLateFireGate(input.scheduleId, input.scheduledAt, input.autoApprove);
+    const targetInput = {
+        commandName: input.commandName,
+        args: input.args,
+        scheduledAt: input.scheduledAt,
+        autoApprove: input.autoApprove,
+        schema: input.schema,
+    };
+    const targetCommandLine = buildTargetCommandLine(targetInput);
+    // `$ARGUMENTS` must match what the command line shows — including the appended
+    // `--scheduled-at` / `--auto` — so a body that re-parses `$ARGUMENTS` (e.g.
+    // review-ticket reading `--auto`) agrees with the rendered command line.
+    const argString = buildAugmentedArgs(targetInput).map(quotePromptToken).join(" ");
+    const body = replaceArgumentsPlaceholder(input.commandBody, argString);
+    return [gate, "", targetCommandLine, "", body].join("\n");
+}

package/build/scheduler-backends/at-fallback.js

@@ -1,4 +1,4 @@
-import { formatEnvExportsForGeneratedUnit, posixShellQuote } from "./escaping.js";
+import { bakedEnvFromCreateInput, formatEnvExportsForGeneratedUnit, posixShellQuote, } from "./escaping.js";
 /** Virtual artifact path for the script piped to `at` (never written to disk). */
 export const AT_STDIN_ARTIFACT_PATH = "<at-stdin>";
 /** Convert an ISO timestamp to the `YYYYMMDDHHMM` form required by `at -t`. */
@@ -10,15 +10,10 @@ export function formatAtTimestamp(runAtIso) {
 }
 /** Render the script piped into `at`. */
 export function renderAtScript(input) {
-    const exports = formatEnvExportsForGeneratedUnit({
-        envPath: input.envPath,
-        nodePath: input.nodePath,
-        npxPath: input.npxPath,
-        claudePath: input.claudePath,
-        ideaFile: input.ideaFile,
-        repoPath: input.repoPath,
-    });
-    const command = [input.invocation.exe, ...input.invocation.args]
+    const exports = formatEnvExportsForGeneratedUnit(bakedEnvFromCreateInput(input));
+    // The script runs the Node execution shim (trigger invocation); the shim spawns
+    // the stored agent invocation and records run-history events.
+    const command = [input.triggerInvocation.exe, ...input.triggerInvocation.args]
         .map((part) => posixShellQuote(part))
         .join(" ");
     return [

package/build/scheduler-backends/escaping.js

@@ -8,14 +8,23 @@
  * truncate a generated file mid-write and silently drop a security-relevant
  * suffix — via {@link assertNoNul}.
  */
-/** All baked PATH-trap environment variable names, in a stable order. */
+/**
+ * All baked PATH-trap / schedule-context environment variable names, in a stable
+ * order. Generalized in BAPI-351: the full-automation-specific `BRIDGE_GPT_CLAUDE`
+ * became the agent-neutral `BRIDGE_GPT_AGENT_PATH`, and schedule-context vars
+ * (`BRIDGE_GPT_SCHEDULE_ID`, `BRIDGE_GPT_COMMAND`, `BRIDGE_GPT_COMMAND_ARGS_JSON`)
+ * were added. `BRIDGE_GPT_IDEA_FILE` is now legacy-only (baked only when present).
+ */
 export const BAKED_ENV_VAR_NAMES = [
     "PATH",
     "BRIDGE_GPT_NODE",
     "BRIDGE_GPT_NPX",
-    "BRIDGE_GPT_CLAUDE",
-    "BRIDGE_GPT_IDEA_FILE",
+    "BRIDGE_GPT_AGENT",
+    "BRIDGE_GPT_AGENT_PATH",
     "BRIDGE_GPT_REPO_PATH",
+    "BRIDGE_GPT_SCHEDULE_ID",
+    "BRIDGE_GPT_COMMAND",
+    "BRIDGE_GPT_COMMAND_ARGS_JSON",
 ];
 /**
  * Reject any generated value containing a NUL byte. NUL can prematurely
@@ -81,26 +90,47 @@ export function systemdQuote(value) {
     return `"${escaped}"`;
 }
 /**
- * Build the ordered baked PATH-trap env entries from explicit, schedule-time
- * values — never `process.env`. Each value is NUL-checked. This is the single
- * source every backend uses so PATH, BRIDGE_GPT_NODE, BRIDGE_GPT_NPX,
- * BRIDGE_GPT_CLAUDE, BRIDGE_GPT_IDEA_FILE, and BRIDGE_GPT_REPO_PATH are baked
- * consistently across launchd / Task Scheduler / systemd / at.
+ * Build the ordered baked PATH-trap + schedule-context env entries from explicit,
+ * schedule-time values — never `process.env`. Each value is NUL-checked. This is
+ * the single source every backend uses so the baked environment is consistent
+ * across launchd / Task Scheduler / systemd / at. `BRIDGE_GPT_IDEA_FILE` is
+ * appended only for the legacy full-automation path (when `ideaFile` is set).
  */
 export function bakedEnvEntries(env) {
     const entries = [
         ["PATH", env.envPath],
         ["BRIDGE_GPT_NODE", env.nodePath],
         ["BRIDGE_GPT_NPX", env.npxPath],
-        ["BRIDGE_GPT_CLAUDE", env.claudePath],
-        ["BRIDGE_GPT_IDEA_FILE", env.ideaFile],
+        ["BRIDGE_GPT_AGENT", env.agent],
+        ["BRIDGE_GPT_AGENT_PATH", env.agentPath],
         ["BRIDGE_GPT_REPO_PATH", env.repoPath],
+        ["BRIDGE_GPT_SCHEDULE_ID", env.scheduleId],
+        ["BRIDGE_GPT_COMMAND", env.command],
+        ["BRIDGE_GPT_COMMAND_ARGS_JSON", env.commandArgsJson],
     ];
+    if (env.ideaFile !== undefined) {
+        entries.push(["BRIDGE_GPT_IDEA_FILE", env.ideaFile]);
+    }
     for (const [key, value] of entries) {
         assertNoNul(value, key);
     }
     return entries;
 }
+/** Build a {@link BakedEnv} from a generalized scheduler create input. */
+export function bakedEnvFromCreateInput(input) {
+    return {
+        envPath: input.envPath,
+        nodePath: input.nodePath,
+        npxPath: input.npxPath,
+        agent: input.agent,
+        agentPath: input.agentPath,
+        repoPath: input.repoPath,
+        scheduleId: input.id,
+        command: input.command,
+        commandArgsJson: JSON.stringify(input.args),
+        ideaFile: input.legacyIdeaFile,
+    };
+}
 /**
  * Render the baked env as POSIX `export KEY='value'` lines (used by the `at`
  * heredoc script). Values come only from {@link bakedEnvEntries}; no value is

package/build/scheduler-backends/launchd.js

@@ -16,10 +16,24 @@
  */
 import { promises as fs } from "node:fs";
 import { pathApiForPlatform } from "./types.js";
-import { bakedEnvEntries, xmlEscape } from "./escaping.js";
-/** launchd label for a schedule id. */
+import { bakedEnvFromCreateInput, bakedEnvEntries, xmlEscape } from "./escaping.js";
+/** launchd label for a NEW schedule id (neutral, generic schedule-run naming). */
 export function launchdLabelForId(id) {
-    return `com.bridge-gpt.full-automation.${id}`;
+    return `com.bridge-gpt.schedule-run.${id}`;
+}
+/**
+ * Resolve the launchd label for an existing schedule, preferring the label baked
+ * into the recorded plist path so legacy `com.bridge-gpt.full-automation.<id>`
+ * schedules remain list/cancel compatible after the neutral-naming change.
+ */
+export function launchdLabelForMetadata(metadata) {
+    const unitPath = metadata.unit_path;
+    if (unitPath && unitPath.endsWith(".plist")) {
+        const base = unitPath.split(/[\\/]/).pop();
+        if (base)
+            return base.slice(0, -".plist".length);
+    }
+    return launchdLabelForId(metadata.id);
 }
 /** `~/Library/LaunchAgents/<label>.plist` for a schedule id. */
 export function launchdPlistPathForId(id, homeDir) {
@@ -49,15 +63,10 @@ function resolveUid(deps) {
 export function renderLaunchdPlist(input) {
     const label = launchdLabelForId(input.id);
     const cal = startCalendarIntervalFromIso(input.runAtIso);
-    const env = bakedEnvEntries({
-        envPath: input.envPath,
-        nodePath: input.nodePath,
-        npxPath: input.npxPath,
-        claudePath: input.claudePath,
-        ideaFile: input.ideaFile,
-        repoPath: input.repoPath,
-    });
-    const programArgs = [input.invocation.exe, ...input.invocation.args]
+    const env = bakedEnvEntries(bakedEnvFromCreateInput(input));
+    // The OS unit runs the Node execution shim (trigger invocation), which then
+    // spawns the stored agent invocation and records run-history events.
+    const programArgs = [input.triggerInvocation.exe, ...input.triggerInvocation.args]
         .map((arg) => `    <string>${xmlEscape(arg)}</string>`)
         .join("\n");
     const envEntries = env
@@ -168,7 +177,7 @@ export function createLaunchdBackend() {
                     entries.push({ metadata, status: "stale", detail: "plist missing" });
                     continue;
                 }
-                const label = launchdLabelForId(metadata.id);
+                const label = launchdLabelForMetadata(metadata);
                 const printed = await input.deps.runCommand("launchctl", ["print", `gui/${uid}/${label}`]);
                 entries.push({
                     metadata,
@@ -180,7 +189,7 @@ export function createLaunchdBackend() {
         },
         async cancel(input) {
             const uid = resolveUid(input.deps);
-            const label = launchdLabelForId(input.metadata.id);
+            const label = launchdLabelForMetadata(input.metadata);
             const plistPath = input.metadata.unit_path ?? launchdPlistPathForId(input.metadata.id, input.deps.homeDir);
             let plistExisted = true;
             try {

package/build/scheduler-backends/systemd-user.js

@@ -14,12 +14,12 @@
  */
 import { promises as fs } from "node:fs";
 import { pathApiForPlatform } from "./types.js";
-import { bakedEnvEntries, systemdQuote } from "./escaping.js";
-/** Return the unit names for a schedule id. */
+import { bakedEnvFromCreateInput, bakedEnvEntries, systemdQuote } from "./escaping.js";
+/** Return the unit names for a NEW schedule id (neutral schedule-run naming). */
 export function systemdUnitNamesForId(id) {
     return {
-        service: `bridge-gpt-full-automation-${id}.service`,
-        timer: `bridge-gpt-full-automation-${id}.timer`,
+        service: `bridge-gpt-schedule-run-${id}.service`,
+        timer: `bridge-gpt-schedule-run-${id}.timer`,
     };
 }
 /** Return the unit file paths for a schedule id. */
@@ -32,25 +32,40 @@ export function systemdUnitPathsForId(id, homeDir) {
         timer: pathApi.join(dir, names.timer),
     };
 }
+/**
+ * Resolve unit names + paths for an EXISTING schedule, preferring the names baked
+ * into the recorded unit paths so legacy `bridge-gpt-full-automation-<id>` units
+ * remain list/cancel compatible after the neutral-naming change.
+ */
+export function systemdUnitsForMetadata(metadata, homeDir) {
+    const timerPath = metadata.unit_path && metadata.unit_path.endsWith(".timer") ? metadata.unit_path : undefined;
+    const servicePath = (metadata.unit_paths ?? []).find((p) => p.endsWith(".service"));
+    if (timerPath && servicePath) {
+        const basename = (p) => p.split(/[\\/]/).pop();
+        return {
+            names: { service: basename(servicePath), timer: basename(timerPath) },
+            paths: { service: servicePath, timer: timerPath },
+        };
+    }
+    return {
+        names: systemdUnitNamesForId(metadata.id),
+        paths: systemdUnitPathsForId(metadata.id, homeDir),
+    };
+}
 /** Render the systemd service unit. */
 export function renderSystemdService(input) {
-    const env = bakedEnvEntries({
-        envPath: input.envPath,
-        nodePath: input.nodePath,
-        npxPath: input.npxPath,
-        claudePath: input.claudePath,
-        ideaFile: input.ideaFile,
-        repoPath: input.repoPath,
-    });
+    const env = bakedEnvEntries(bakedEnvFromCreateInput(input));
     const envLines = env
         .map(([key, value]) => `Environment=${key}=${systemdQuote(value)}`)
         .join("\n");
-    const execStart = [input.invocation.exe, ...input.invocation.args]
+    // ExecStart runs the Node execution shim (trigger invocation); the shim spawns
+    // the stored agent invocation and records run-history events.
+    const execStart = [input.triggerInvocation.exe, ...input.triggerInvocation.args]
         .map((part) => systemdQuote(part))
         .join(" ");
     return [
         "[Unit]",
-        `Description=Bridge GPT full-automation one-shot run (${input.id})`,
+        `Description=Bridge GPT schedule-run one-shot (${input.id}: ${input.command})`,
         "",
         "[Service]",
         "Type=oneshot",
@@ -82,7 +97,7 @@ export function renderSystemdTimer(input) {
     const names = systemdUnitNamesForId(input.id);
     return [
         "[Unit]",
-        `Description=Bridge GPT full-automation one-shot timer (${input.id})`,
+        `Description=Bridge GPT schedule-run one-shot timer (${input.id}: ${input.command})`,
         "",
         "[Timer]",
         `OnCalendar=${formatSystemdOnCalendar(input.runAtIso)}`,
@@ -181,8 +196,7 @@ export function createSystemdUserBackend() {
         async list(input) {
             const entries = [];
             for (const metadata of input.recorded) {
-                const paths = systemdUnitPathsForId(metadata.id, input.deps.homeDir);
-                const names = systemdUnitNamesForId(metadata.id);
+                const { paths, names } = systemdUnitsForMetadata(metadata, input.deps.homeDir);
                 let timerExists = true;
                 try {
                     await fs.access(paths.timer);
@@ -209,8 +223,7 @@ export function createSystemdUserBackend() {
             return entries;
         },
         async cancel(input) {
-            const paths = systemdUnitPathsForId(input.metadata.id, input.deps.homeDir);
-            const names = systemdUnitNamesForId(input.metadata.id);
+            const { paths, names } = systemdUnitsForMetadata(input.metadata, input.deps.homeDir);
             const disable = await input.deps.runCommand("systemctl", [
                 "--user",
                 "disable",

package/build/scheduler-backends/task-scheduler.js

@@ -18,10 +18,10 @@
  */
 import { promises as fs } from "node:fs";
 import { pathApiForPlatform } from "./types.js";
-import { bakedEnvEntries, escapeWindowsCmdSetValue, windowsCmdQuote, xmlEscape, } from "./escaping.js";
-/** Task Scheduler task name for a schedule id. */
+import { bakedEnvFromCreateInput, bakedEnvEntries, escapeWindowsCmdSetValue, windowsCmdQuote, xmlEscape, } from "./escaping.js";
+/** Task Scheduler task name for a NEW schedule id (neutral schedule-run naming). */
 export function taskNameForId(id) {
-    return `BridgeGPT-FullAutomation-${id}`;
+    return `BridgeGPT-ScheduleRun-${id}`;
 }
 /** `%USERPROFILE%\.bridge-gpt\schedules\<id>.cmd` wrapper path for a schedule id. */
 export function cmdWrapperPathForId(id, homeDir) {
@@ -46,14 +46,7 @@ export function formatTaskSchedulerBoundary(runAtIso) {
 }
 /** Render the `.cmd` wrapper that the Task Scheduler task invokes. */
 export function renderWindowsCmdWrapper(input) {
-    const env = bakedEnvEntries({
-        envPath: input.envPath,
-        nodePath: input.nodePath,
-        npxPath: input.npxPath,
-        claudePath: input.claudePath,
-        ideaFile: input.ideaFile,
-        repoPath: input.repoPath,
-    });
+    const env = bakedEnvEntries(bakedEnvFromCreateInput(input));
     const lines = ["@echo off"];
     for (const [key, value] of env) {
         if (key === "PATH") {
@@ -65,7 +58,9 @@ export function renderWindowsCmdWrapper(input) {
         }
     }
     lines.push(`cd /D ${windowsCmdQuote(input.repoPath)}`);
-    const command = [input.invocation.exe, ...input.invocation.args]
+    // The wrapper runs the Node execution shim (trigger invocation), not the agent
+    // binary directly; the shim spawns the stored agent invocation.
+    const command = [input.triggerInvocation.exe, ...input.triggerInvocation.args]
         .map((part) => windowsCmdQuote(part))
         .join(" ");
     // Append stdout/stderr to the local schedule logs.
@@ -86,7 +81,7 @@ export function renderTaskSchedulerXml(input) {
         '<?xml version="1.0" encoding="UTF-16"?>',
         '<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">',
         "  <RegistrationInfo>",
-        `    <Description>${xmlEscape(`Bridge GPT full-automation one-shot run (${input.id})`)}</Description>`,
+        `    <Description>${xmlEscape(`Bridge GPT schedule-run one-shot (${input.id}: ${input.command})`)}</Description>`,
         "  </RegistrationInfo>",
         "  <Triggers>",
         "    <TimeTrigger>",

package/build/start-tickets-prereqs.js

@@ -13,6 +13,9 @@
  * 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 { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
 // ---------------------------------------------------------------------------
 // Constants (moved here from start-tickets.ts so both consumers share them)
 // ---------------------------------------------------------------------------
@@ -250,6 +253,87 @@ function agentDescriptor(agent) {
 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_INSTALL_HINTS = {
+    darwin: CREDENTIAL_RESOLUTION_HINT,
+    linux: CREDENTIAL_RESOLUTION_HINT,
+    win32: CREDENTIAL_RESOLUTION_HINT,
+};
+/**
+ * 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.
+ */
+export function credentialResolutionDescriptor() {
+    return {
+        id: "bapi-credentials",
+        label: "Bridge API credential resolution",
+        installHint: CREDENTIAL_RESOLUTION_INSTALL_HINTS,
+        probe: async (deps) => {
+            const { readFile, stat, homedir } = deps;
+            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 result = await resolveBapiCredentials(repoName, {
+                env: deps.env,
+                homedir,
+                platform: deps.platform,
+                readFile,
+                stat,
+            });
+            if (result.ok) {
+                const via = result.credentials.source === "env" ? "env" : "store";
+                return { found: true, detail: `credentials resolvable via ${via}` };
+            }
+            return { found: false, detail: CREDENTIAL_RESOLUTION_HINT };
+        },
+    };
+}
+/** Secret-free remediation hint shared by the worktree-MCP descriptor. */
+const WORKTREE_MCP_HINT = "Re-run start-tickets to provision the worktree MCP registration " +
+    "(.mcp.json / .cursor/mcp.json pointing at the mcp-invoke shim).";
+const WORKTREE_MCP_INSTALL_HINTS = {
+    darwin: WORKTREE_MCP_HINT,
+    linux: WORKTREE_MCP_HINT,
+    win32: WORKTREE_MCP_HINT,
+};
+/**
+ * Doctor-only, strictly read-only probe: does the current worktree's generated
+ * MCP registration point at the Bridge API `mcp-invoke` shim? Inspects
+ * `.mcp.json` / `.cursor/mcp.json` under `deps.cwd` without spawning anything.
+ */
+export function worktreeMcpReachabilityDescriptor() {
+    return {
+        id: "worktree-mcp-registration",
+        label: "Worktree MCP registration reachability",
+        installHint: WORKTREE_MCP_INSTALL_HINTS,
+        probe: async (deps) => {
+            const { readFile } = deps;
+            if (!readFile) {
+                return { found: false, detail: "registration probe unavailable (no read-only filesystem access)" };
+            }
+            const result = await probeWorktreeMcpRegistration(deps.cwd, { readFile });
+            return { found: result.found, detail: result.detail };
+        },
+    };
+}
 /**
  * The exact existing live-preflight requirement set per platform, plus the git
  * work-tree custom check appended after the command checks. This is the ONLY
@@ -286,7 +370,12 @@ export function getPreflightPrereqDescriptors(platform, env) {
  * additive (BAPI-302/303 regression-safe).
  */
 export function getDoctorOnlyPrereqDescriptors(_platform, _env, agent) {
-    return [uvDescriptor(), agentDescriptor(agent)];
+    return [
+        uvDescriptor(),
+        agentDescriptor(agent),
+        credentialResolutionDescriptor(),
+        worktreeMcpReachabilityDescriptor(),
+    ];
 }
 /**
  * The doctor's full descriptor set: the preflight descriptors (verbatim) plus