@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/doctor.js

@@ -36,6 +36,9 @@ import { modelRoutingPreferencesPath, readModelRoutingPreference } from "./model
 import { inspectExecutorAgentAdapter, inspectionForFailedResolution, } from "./agent-launchers/executor-adapter-inspection.js";
 import { resolveExecutorAgentAdapter } from "./agent-launchers/executor-adapter-registry.js";
 import { parseDefaultOnEnvFlag } from "./env-flags.js";
+import { checkForUpdate, isPlainReleaseVersion } from "./update-check.js";
+import { getNoticeDecision, isUnattendedSession, UPDATE_CHECK_ENABLED_ENV, } from "./session-upgrade-notice.js";
+import { formatUpdateAdvice } from "./upgrade-advice.js";
 import { createBridgeApiUrls } from "./bridge-api-urls.js";
 import { probeToolSurface } from "./tool-surface-gating.js";
 import { readStoredBindingState, resolveBapiCredentials } from "./credential-store.js";
@@ -45,7 +48,7 @@ import { validateHttpBaseUrl } from "./base-url.js";
 import { getLiveRepositoryConductors, getParseDispatcherHealth, } from "./epic-shared/bridge-client.js";
 import { resolveRequiredStartTicketsRepoName } from "./start-tickets-repo.js";
 import { collectWorkerContainmentDiagnostic, formatWorkerContainmentDiagnosticReport, } from "./worker-containment-diagnostic.js";
-import { BRIDGE_PACKAGE_NAME, describeLauncherReason, DUPLICATE_REGISTRATION_GUIDANCE, inspectLauncherConfigs, parseLauncherPin as parseSharedLauncherPin, } from "./launcher-config-inspection.js";
+import { BRIDGE_PACKAGE_NAME, describeLauncherReason, DUPLICATE_REGISTRATION_GUIDANCE, inspectLauncherConfigs, isExactVersion, isPrerequisiteFailure, parseLauncherPin as parseSharedLauncherPin, } from "./launcher-config-inspection.js";
 import { MCP_SERVER_NAME, MCP_PACKAGE_NAME, } from "./mcp-identity.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
@@ -53,6 +56,7 @@ import { resolveProfiles } from "./mcp-profile.js";
 import { executorLaunchdDirForHome, executorSystemdDirForHome, executorIdFromLaunchdFilename, executorIdFromSystemdFilename, inspectExecutorServiceArtifact, inspectExecutorServiceDurability, EXECUTOR_SERVICE_BASE_URL_ENV, } from "./executor/index.js";
 import { DEFAULT_BAPI_BASE_URL } from "./executor/credentials.js";
 import { detectClaudeLogin, formatClaudeLoginAdvisory } from "./claude-login.js";
+import { checkGithubSignIn, githubSignInRemedy, } from "./github-sign-in.js";
 import { validateBranchName } from "./base-ref.js";
 import { readPlaneManifest } from "./plane/manifest.js";
 import { validateTicketKey } from "./ticket-key-utils.js";
@@ -74,9 +78,9 @@ export function getDoctorUsage() {
         `  npx -y ${MCP_PACKAGE_NAME} doctor --stale-branch <KEY> [--stale-branch <KEY> ...] \\`,
         "                                   --stale-branch-base <ref> [--branch KEY=BRANCH ...]",
         "",
-        // BAPI-669 (U9b): `doctor` is the general Bridge diagnostic command, not a
-        // start-tickets-only one — and its report leads with install status, so the
-        // usage text describes it in that order too.
+        // `doctor` is the general Bridge diagnostic command, not a start-tickets-only
+        // one — and its report leads with install status, so the usage text
+        // describes it in that order too.
         `${DOCTOR_REPORT_TITLE}. It only checks your environment and prints manual`,
         "install instructions — it does not install anything, modify your system, or",
         "start the MCP server.",
@@ -85,16 +89,23 @@ export function getDoctorUsage() {
         "Flags:",
         "  --agent claude|cursor-agent|codex  Agent to include in the prerequisite check (default: claude)",
         "  --stale-branch KEY            Add a ticket to the read-only stale-ticket-branch check (repeatable); requires --stale-branch-base",
-        "  --stale-branch-base REF       The base ref that check measures ancestry against, e.g. epic/BAPI-902 (required with --stale-branch; never defaulted)",
+        "  --stale-branch-base REF       The base ref that check measures ancestry against, e.g. epic/PROJ-902 (required with --stale-branch; never defaulted)",
         "  --branch KEY=BRANCH           Diagnose BRANCH instead of feature/KEY for that ticket (repeatable); same override rule start-tickets uses",
+        "  --advanced                    Also show Python and self-host diagnostics: the `uv` check and the",
+        "                                local plane credential section. Without it doctor runs no `uv`,",
+        "                                Alembic, or Python check, so it works on a repository in any language.",
         "  -h, --help                    Show this help",
         "",
+        "A 'Getting started' section follows Install status: your Claude sign-in (it reads only",
+        "~/.claude.json) and your GitHub CLI sign-in (one `gh auth status`, ten seconds at most).",
+        "Each one that is not ready names its fix. It never changes the exit code.",
+        "",
         "The report opens with an advisory 'Install status' section (easy-install done",
         "criteria): repo identity, credential resolution, server connectivity,",
         "bootstrap-field completeness, integration credentials, and repository-indexing",
         "state. It performs read-only GETs only and never affects the exit code.",
         "",
-        "Next comes an advisory 'Project identity and root' section (BAPI-1318): whether",
+        "Next comes an advisory 'Project identity and root' section: whether",
         "each BAPI_PROJECT_ROOT (from the environment and the project MCP configs) names",
         "a real project folder the server will use, and whether .bridge/config's",
         "repo_name matches each project MCP config's BAPI_REPO_NAME. It only reads",
@@ -102,7 +113,7 @@ export function getDoctorUsage() {
         "",
         "After that come the start-tickets prerequisite checks (for the current OS):",
         "the start-tickets preflight prerequisites plus",
-        "uv, the selected agent's command, Bridge API credential resolution, and",
+        "the selected agent's command (and uv with --advanced), Bridge API credential resolution, and",
         "worktree MCP registration reachability, and a read-only check of whether the",
         `Claude user config (~/.claude.json) registers a '${MCP_SERVER_NAME}' MCP server that`,
         "could shadow the registration provisioned into a worker worktree. That check",
@@ -113,14 +124,8 @@ export function getDoctorUsage() {
         "migrate a credential, use /install-bridge or the `credentials` subcommand —",
         "doctor stays strictly read-only.",
         "",
-        // BAPI-815/R4: the old text here promised a 'Worker config isolation",
-        // (conductor executor)' section naming a CLAUDE_CONFIG_DIR strategy. BAPI-790
-        // replaced per-job config-directory isolation with --strict-mcp-config argv
-        // scoping, and BAPI-791 deleted that doctor section together with the whole
-        // worker-auth strategy vocabulary. The section it described exists in no
-        // doctor output, so the claim is removed rather than reworded.
-        "It includes an advisory 'Worker containment' section (BAPI-1019) reporting the",
-        "DECLARED posture a conductor worker runs under: that the executor strips this",
+        "It includes an advisory 'Worker containment' section reporting the DECLARED",
+        "posture an Epic Implementer worker runs under: that the executor strips this",
         "checkout's .env* files from a worker's worktree as the last step before spawn",
         "(refusing to spawn with ContractError.WorkerEnvFilePresent when it cannot",
         "confirm they are gone), that a worker's database environment names a target",
@@ -129,14 +134,13 @@ export function getDoctorUsage() {
         "reports constants rather than measurements, so it never claims a live check",
         "ran and never changes the exit code.",
         "",
-        "MCP containment is still not reported here. A conductor worker is scoped",
-        "at spawn time with `--strict-mcp-config --mcp-config <file>`, and the",
-        "executor asserts that scope per spawn from the worker's own system/init",
-        "event — failing the job with ContractError.McpSurfaceMismatch on a confirmed",
-        "leak. That per-spawn assertion, not a doctor health line, is the containment",
-        "proof; see docs/claude/worker-config-isolation-drill.md.",
+        "MCP containment is still not reported here. A worker is scoped at spawn time",
+        "with `--strict-mcp-config --mcp-config <file>`, and the executor asserts that",
+        "scope per spawn from the worker's own system/init event — failing the job with",
+        "ContractError.McpSurfaceMismatch on a confirmed leak. That per-spawn assertion,",
+        "not a doctor health line, is the containment proof.",
         "",
-        "It also includes an advisory 'Local CLI launcher' section (BAPI-815): whether",
+        "It also includes an advisory 'Local CLI launcher' section: whether",
         "the BAPI_MCP_CLI override is set, and whether the launcher it names can be",
         "executed. When the override is unset, NO launcher probe runs at all. When it",
         "is set, doctor runs that launcher exactly once with a single appended",
@@ -146,7 +150,7 @@ export function getDoctorUsage() {
         "is rejected without running anything. The whole section is advisory: a",
         "missing, malformed, or unrunnable override never changes the exit code.",
         "",
-        "It also includes an advisory 'MCP tool surface' section (BAPI-641): what",
+        "It also includes an advisory 'MCP tool surface' section: what",
         "dynamic capability gating would advertise for this repo. It performs at most",
         "one read-only GET to /jira/mcp/tool-surface (none under the kill switch) and",
         "is advisory/fail-open — a timeout or malformed response is reported as",
@@ -154,7 +158,7 @@ export function getDoctorUsage() {
         "ignore notifications/tools/list_changed must reconnect or start a new MCP",
         "session to observe surface changes; no project MCP config change is required.",
         "",
-        "It also includes an advisory 'Executor provisioning' section (BAPI-688): the",
+        "It also includes an advisory 'Executor provisioning' section: the",
         "generated executor service units on this host. It enumerates them read-only by",
         "fixed convention — ~/Library/LaunchAgents/com.bridge-gpt.executor.*.plist on",
         "macOS, ~/.config/systemd/user/bridge-gpt-executor-*.service on Linux (Windows",
@@ -165,19 +169,20 @@ export function getDoctorUsage() {
         "is advisory: missing, malformed, or credential-less units never change the exit code.",
         "",
         "It also includes an advisory '/drive-epic-run permission rules' section",
-        "(BAPI-1398): whether the project permissions.allow rules and the optional user",
-        "autoMode entries that install writes are PRESENT, MISSING, or DRIFTED (for",
+        "whether the project permissions.allow rules and the optional user",
+        "autoMode entries (added through /drive-epic-run or the bridge-permissions",
+        "subcommand, never by install) are PRESENT, MISSING, or DRIFTED (for",
         "example after the BAPI_MCP_CLI launcher changed). It reads .claude/settings.local.json,",
         "~/.claude/settings.json, and .bridge/bridge-permissions.json, writes nothing,",
         "and never changes the exit code.",
         "",
-        "Conductor ledger / native-module diagnostics (the SQLite ledger's native",
+        "Local ledger / native-module diagnostics (the SQLite ledger's native",
         "binding load status and Node-version skew) live under a separate command:",
         "  epic-implementer doctor",
         "That command is likewise strictly read-only — it does not install, rebuild,",
         "migrate, or write ledger files.",
         "",
-        "It also includes an OPT-IN advisory 'Stale ticket branches' section (BAPI-948),",
+        "It also includes an OPT-IN advisory 'Stale ticket branches' section,",
         "and only when you pass --stale-branch: for each named ticket it reports whether",
         "that ticket's branch would be REFUSED by the stale-branch guard that",
         "`start-tickets --guard-stale-branch` (and --conductor, which implies it) runs —",
@@ -191,7 +196,7 @@ export function getDoctorUsage() {
         "",
         "The 'operational advisories' section also reports RETIRED local drive helpers",
         "(~/.local/bin/bapi-runtime-up, ~/.local/bin/bapi-drive) when they are still on",
-        "this machine (BAPI-1102). That is a PATH-PRESENCE check only: doctor does not",
+        "this machine. That is a PATH-PRESENCE check only: doctor does not",
         "run, read, source, chmod, or delete either file, and cannot remove them for you",
         "— they are outside this repository, so their removal is an operator step. The",
         "row is advisory and never changes the exit code.",
@@ -218,6 +223,7 @@ export function parseDoctorArgs(argv) {
     const staleBranchKeys = [];
     let staleBranchBase = null;
     const staleBranchOverrides = {};
+    let advanced = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === "--fix" || arg.startsWith("--fix=")) {
@@ -296,6 +302,10 @@ export function parseDoctorArgs(argv) {
             staleBranchOverrides[overrideKey] = branchName;
             continue;
         }
+        if (arg === "--advanced") {
+            advanced = true;
+            continue;
+        }
         if (arg === "--agent" || arg.startsWith("--agent=")) {
             let value;
             if (arg.startsWith("--agent=")) {
@@ -350,7 +360,13 @@ export function parseDoctorArgs(argv) {
     }
     return {
         status: "ok",
-        options: { agentName, staleBranchKeys, staleBranchBase, staleBranchOverrides },
+        options: {
+            agentName,
+            staleBranchKeys,
+            staleBranchBase,
+            staleBranchOverrides,
+            ...(advanced ? { advanced: true } : {}),
+        },
     };
 }
 /**
@@ -359,13 +375,19 @@ export function parseDoctorArgs(argv) {
  * missing earlier prerequisite never hides a later one. Returns a structured
  * unsupported-platform result (no probes) for unsupported OSes; never throws.
  */
-export async function collectDoctorResults(deps, agentName) {
+export async function collectDoctorResults(deps, agentName, options = { advanced: true }) {
     // agentName is type-guaranteed valid by the parser; resolve is defensive.
     const agent = resolveAgentSpec(agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
     const descriptorsResult = getDoctorPrereqDescriptors(deps.platform, deps.env, agent);
     if (!descriptorsResult.ok) {
         return { ok: false, unsupported: true, error: descriptorsResult.error };
     }
+    // BAPI-1461: the default view drops the Python/self-host descriptors BEFORE any
+    // probe runs, so a non-Python repository never spawns `uv`. The descriptor
+    // table itself is unchanged; `--advanced` keeps them.
+    const descriptors = options.advanced === true
+        ? descriptorsResult.descriptors
+        : descriptorsResult.descriptors.filter((d) => !ADVANCED_ONLY_DESCRIPTOR_IDS.has(d.id));
     // Augment with read-only filesystem deps so the doctor-only credential and
     // worktree-MCP-registration probes can run. These are intentionally NOT part
     // of StartTicketsDeps (live preflight never reads files); doctor injects them
@@ -381,11 +403,93 @@ export async function collectDoctorResults(deps, agentName) {
         homedir: injected.homedir ?? os.homedir,
     };
     const results = [];
-    for (const descriptor of descriptorsResult.descriptors) {
+    for (const descriptor of descriptors) {
         results.push(await probePrerequisite(probeDeps, descriptor));
     }
     return { ok: true, results };
 }
+/**
+ * BAPI-1461 — doctor-only descriptors shown only with `--advanced`, matched by
+ * their stable descriptor id. `uv` serves bridge-api's own Python tooling, not a
+ * customer repository.
+ */
+export const ADVANCED_ONLY_DESCRIPTOR_IDS = new Set(["uv"]);
+/** The production checker, bound so it can neither read nor populate the cache. */
+export function createDoctorVersionChecker(env) {
+    return () => checkForUpdate({ env, readCache: false, writeCache: false });
+}
+/**
+ * Collect the version diagnostic. Never throws. The lookup is skipped when update
+ * checks are disabled or the session is unattended; a null, rejected, or malformed
+ * result is `unavailable`. Only a reliable fresh (or override) result reaches the
+ * shared notice decision, and only then are project pins evaluated.
+ */
+export async function collectVersionDiagnostic(deps) {
+    try {
+        if (!parseDefaultOnEnvFlag(deps.env[UPDATE_CHECK_ENABLED_ENV]) || isUnattendedSession(deps.env)) {
+            return { status: "not-checked" };
+        }
+        let result = null;
+        try {
+            result = await deps.checkLatest();
+        }
+        catch {
+            result = null;
+        }
+        if (!result || typeof result !== "object" || !isPlainReleaseVersion(result.latestVersion)) {
+            return { status: "unavailable" };
+        }
+        const latest = result.latestVersion;
+        const authoritative = { known: true, latest };
+        const upgrade = getNoticeDecision(deps.env, VERSION, authoritative).show;
+        const stalePins = [];
+        try {
+            const shared = await inspectLauncherConfigs({
+                cwd: deps.cwd,
+                targetVersion: VERSION,
+                readFile: deps.readFile,
+            });
+            for (const found of shared) {
+                if (!found.filePresent || !found.bridgeEntryPresent)
+                    continue;
+                if (found.shape !== "standard" || isPrerequisiteFailure(found))
+                    continue;
+                if (!isExactVersion(found.currentVersion))
+                    continue;
+                const pin = found.currentVersion;
+                if (getNoticeDecision(deps.env, pin, authoritative).show) {
+                    stalePins.push({ relPath: found.relPath, pin });
+                }
+            }
+        }
+        catch {
+            // Pin diagnostics are advisory; the installed-runtime line still renders.
+        }
+        return { status: "known", latest, upgrade, stalePins };
+    }
+    catch {
+        return { status: "unavailable" };
+    }
+}
+/** The `Bridge MCP version` lines, or none when no diagnostic was collected. */
+export function formatDoctorVersionLines(diagnostic) {
+    if (!diagnostic)
+        return [];
+    if (diagnostic.status === "not-checked") {
+        return [`Bridge MCP version: installed ${VERSION}, latest: not checked`];
+    }
+    if (diagnostic.status === "unavailable") {
+        return [`Bridge MCP version: installed ${VERSION}, latest: unavailable`];
+    }
+    const lines = [`Bridge MCP version: installed ${VERSION}, latest ${diagnostic.latest}`];
+    if (diagnostic.upgrade)
+        lines.push(`  ${formatUpdateAdvice(VERSION, diagnostic.latest)}`);
+    // Stale project pins are subordinate to the runtime line above.
+    for (const { relPath, pin } of diagnostic.stalePins) {
+        lines.push(`  ${relPath} pin: ${formatUpdateAdvice(pin, diagnostic.latest)}`);
+    }
+    return lines;
+}
 /**
  * The BROAD report header: title plus the run's platform / agent / profile
  * metadata (BAPI-669, U9b). Split out from the prerequisite body so `runDoctorCli`
@@ -393,7 +497,10 @@ export async function collectDoctorResults(deps, agentName) {
  * ordering change is the whole point, and it must not require rewriting the
  * prerequisite formatting below.
  */
-export function buildDoctorReportHeader(platform, agent) {
+export function buildDoctorReportHeader(platform, agent, 
+// A DEFAULT value, not a plain optional marker, so the function's declared arity
+// stays two: the header takes no dependency seam and does no I/O.
+versionDiagnostic = undefined) {
     const activeGroups = Array.from(resolveProfiles(process.env.BRIDGE_MCP_PROFILE)).join(", ");
     return [
         DOCTOR_REPORT_TITLE,
@@ -404,6 +511,7 @@ export function buildDoctorReportHeader(platform, agent) {
         // never blank and never omitted. Neither line feeds launcher-pin drift,
         // which stays a `VERSION`-only comparison.
         `Package version: ${VERSION}`,
+        ...formatDoctorVersionLines(versionDiagnostic),
         `Build commit: ${BUILD_COMMIT}`,
         `Platform: ${platform}`,
         `Selected agent: ${agent.name} (command: ${agent.command})`,
@@ -1696,6 +1804,24 @@ export function formatOperationalAdvisoryReport(diagnostic) {
     lines.push("           runs NO command probe, repairs no scheduler, and never changes the exit code.");
     return lines.join("\n");
 }
+/**
+ * BAPI-1461 — render the "Getting started" section: the Claude sign-in and the
+ * GitHub CLI sign-in, each ready or with its one fix. Both are needed for a
+ * first epic; neither line carries any value read from disk or from `gh`.
+ */
+export function formatGettingStartedReport(claude, github) {
+    const lines = ["", "Getting started (needed for your first epic)"];
+    lines.push(claude.detected
+        ? "  ready        Claude sign-in"
+        : "  needs action Claude sign-in — run `claude login`");
+    const remedy = githubSignInRemedy(github);
+    lines.push(remedy === null
+        ? "  ready        GitHub sign-in"
+        : github === "unavailable"
+            ? `  could not verify GitHub sign-in — ${remedy}`
+            : `  needs action GitHub sign-in — ${remedy}`);
+    return lines.join("\n");
+}
 /** Collect the permission-rules inspection. Reads only; never writes. */
 export async function collectBridgePermissionsDiagnostic(deps) {
     return inspectBridgePermissions({ cwd: deps.cwd, homeDir: deps.homeDir, env: deps.env }, { readFile: deps.readFile });
@@ -1736,10 +1862,10 @@ export function formatBridgePermissionsDiagnosticReport(inspection) {
     else {
         lines.push(...formatPermissionScope("project permissions.allow", inspection.project));
     }
-    lines.push(...formatPermissionScope("user autoMode entries", inspection.user, "Optional: install adds them only after you say yes."));
+    lines.push(...formatPermissionScope("user autoMode entries", inspection.user, `Optional: /drive-epic-run offers to add them, or run \`npx -y ${MCP_PACKAGE_NAME} bridge-permissions\`.`));
     const healthy = inspection.project.state === "present" && inspection.user.state === "present";
     if (!healthy) {
-        lines.push(`  To repair: re-run \`npx -y ${MCP_PACKAGE_NAME} install\` in a terminal (it lists every rule it writes).`);
+        lines.push(`  To repair the project rules: re-run \`npx -y ${MCP_PACKAGE_NAME} install\` in a terminal (it lists every rule it writes).`);
         lines.push(`  To remove Bridge's entries: \`npx -y ${MCP_PACKAGE_NAME} install --remove-bridge-permissions\`.`);
     }
     lines.push(`  Bridge's ownership record: ${BRIDGE_PERMISSIONS_MANIFEST_RELPATH}. Advisory only; never changes the exit code.`);
@@ -1875,7 +2001,8 @@ export async function runDoctorCli(argv, overrides = {}) {
     }
     const deps = overrides.deps ?? createDefaultStartTicketsDeps();
     const agent = resolveAgentSpec(parsed.options.agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
-    const collection = await collectDoctorResults(deps, parsed.options.agentName);
+    const advanced = parsed.options.advanced === true;
+    const collection = await collectDoctorResults(deps, parsed.options.agentName, { advanced });
     // ---- Section order (BAPI-669, U9c) ----
     // Broad header → Install status → Project identity and root (BAPI-1318) →
     // start-tickets prerequisites → launcher cache → MCP tool surface. Install status renders FIRST and UNCONDITIONALLY: it answers
@@ -1885,7 +2012,26 @@ export async function runDoctorCli(argv, overrides = {}) {
     // always-first is both simpler and equivalent. The `installStatus: false` override
     // remains a dependency-injection-only seam for hermetic tests; a normal CLI
     // invocation never takes it.
-    log(buildDoctorReportHeader(deps.platform, agent).join("\n"));
+    // BAPI-1446: the version diagnostic is advisory and read-only (fresh lookup, no
+    // cache read or write, no spawn). A failure leaves the header exactly as it was.
+    let versionDiagnostic;
+    if (overrides.version !== false && (overrides.deps === undefined || overrides.version?.checkLatest)) {
+        try {
+            const versionEnv = overrides.version?.env ?? deps.env;
+            versionDiagnostic = await collectVersionDiagnostic({
+                env: versionEnv,
+                cwd: overrides.version?.cwd ?? overrides.launcherProbe?.cwd ?? deps.cwd,
+                readFile: overrides.version?.readFile ??
+                    overrides.launcherProbe?.readFile ??
+                    ((p) => readFile(p, "utf-8")),
+                checkLatest: overrides.version?.checkLatest ?? createDoctorVersionChecker(versionEnv),
+            });
+        }
+        catch {
+            versionDiagnostic = undefined;
+        }
+    }
+    log(buildDoctorReportHeader(deps.platform, agent, versionDiagnostic).join("\n"));
     // Advisory install-status section (easy-install done criteria). Read-only GETs
     // only; any failure degrades to WARN/SKIP lines inside the section, and any
     // unexpected throw renders the sanitized fallback rather than dropping the
@@ -1914,6 +2060,24 @@ export async function runDoctorCli(argv, overrides = {}) {
             log(formatInstallStatusFallbackReport());
         }
     }
+    // BAPI-1461: "Getting started" — the two sign-ins a first epic needs, right
+    // after Install status. Read-only (one file read, one bounded `gh auth status`)
+    // and advisory: it never changes the exit code. With injected deps it runs only
+    // when its own seam is supplied, so a faked machine never reaches real `gh`.
+    if (overrides.signIn !== false && (overrides.deps === undefined || overrides.signIn !== undefined)) {
+        try {
+            const injectedFs = deps;
+            const claude = await detectClaudeLogin({
+                homedir: overrides.signIn?.homedir ?? injectedFs.homedir ?? os.homedir,
+                readFile: overrides.signIn?.readFile ?? injectedFs.readFile ?? ((p) => readFile(p, "utf-8")),
+            });
+            const github = await checkGithubSignIn(overrides.signIn?.runGh);
+            log(formatGettingStartedReport(claude, github));
+        }
+        catch {
+            log(formatGettingStartedReport({ detected: false }, "unavailable"));
+        }
+    }
     // Advisory "Project identity and root" section (BAPI-1318). Read-only: it
     // validates each explicit BAPI_PROJECT_ROOT the way the server does and
     // compares .bridge/config's repo_name with each project MCP config. Placed
@@ -2176,7 +2340,8 @@ export async function runDoctorCli(argv, overrides = {}) {
     // every section above, never affects the exit code: `plane up` enforces these
     // same invariants at the point where they actually block, and an ordinary MCP
     // user who never runs a conductor plane should not see a failing doctor.
-    if (overrides.planeCredentials !== false) {
+    // BAPI-1461: a self-host diagnostic, so it runs only with --advanced.
+    if (advanced && overrides.planeCredentials !== false) {
         try {
             const injectedFs = deps;
             const planeDeps = {