@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/doctor.js

@@ -56,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";
@@ -77,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.",
@@ -88,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",
@@ -105,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",
@@ -116,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",
@@ -132,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",
@@ -149,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",
@@ -157,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",
@@ -168,20 +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",
+        "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 —",
@@ -195,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.",
@@ -222,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=")) {
@@ -300,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=")) {
@@ -354,7 +360,13 @@ export function parseDoctorArgs(argv) {
     }
     return {
         status: "ok",
-        options: { agentName, staleBranchKeys, staleBranchBase, staleBranchOverrides },
+        options: {
+            agentName,
+            staleBranchKeys,
+            staleBranchBase,
+            staleBranchOverrides,
+            ...(advanced ? { advanced: true } : {}),
+        },
     };
 }
 /**
@@ -363,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
@@ -385,11 +403,17 @@ 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 });
@@ -1780,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 });
@@ -1959,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
@@ -2017,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
@@ -2279,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 = {

package/build/drive-epic-help.js

@@ -0,0 +1,212 @@
+/**
+ * Help text for `drive-epic`, in two parts.
+ *
+ * Basic help (`-h` / `--help`) is what a customer needs to launch an epic.
+ * Advanced help (`--help-advanced`) holds the material only an owner who runs
+ * their own Bridge server needs: the local plane and its port, the composed
+ * bring-up, durable hosts, repository-wide executors, and launch profiles.
+ *
+ * This module is pure. It reads no files, resolves no credentials, opens no
+ * network connection, starts no process, and imports nothing from
+ * `drive-epic.ts`, so `parseDriveEpicArgs` can return either text before any
+ * side effect. It imports only two neutral constants.
+ */
+import { CONDUCTOR_DEFAULT_BASE_URL } from "./conductor/bridge-api-client.js";
+import { PLANE_SERVER_PORT_ENV_VAR } from "./plane/types.js";
+/** Shown on the last line of basic help. */
+const ADVANCED_HELP_POINTER = "Owners who run their own Bridge server: drive-epic --help-advanced";
+export function getDriveEpicUsage() {
+    return [
+        "Usage: mcp-server drive-epic [options] <EPIC>",
+        "",
+        "Launches one epic. Reads this project's readiness from Bridge API and picks",
+        "exactly one path for you — it never asks you to choose. A refusal names the",
+        "missing item and its fix, and creates nothing.",
+        "",
+        "Arguments:",
+        "  <EPIC>                 Epic key, matches [A-Z]+-[0-9]+ (e.g. PROJ-123)",
+        "",
+        "Finding the plan: without --plan-file, drive-epic searches",
+        "{docs_dir}/epic-plans/*/epic-plan.meta.json for a file naming this epic",
+        "({\"epic_key\": \"<KEY>\"}), where docs_dir is BAPI_DOCS_DIR or docs/tmp",
+        "resolved against the Git top level. Exactly one match with a sibling",
+        "epic-plan.dag.json is used as if you had passed --plan-file, and its path is",
+        "printed before anything is created. It never guesses: no match, two or more",
+        "matches, or an unusable meta file stops with the paths it found and creates",
+        "nothing. /define-tickets writes these files; `emit-epic-implementer-bundle",
+        "finalize` writes them for a plan from /plan-epic. A supplied --plan-file",
+        "always wins.",
+        "",
+        "Branch strategy: a plan with two or more nodes defaults to a dedicated",
+        "epic/<KEY> branch. Child PRs target it, and one draft integration PR targets",
+        "the repository base branch. The flags below only override that default.",
+        "",
+        "Unattended by default: a run on an epic branch merges child PRs into that",
+        "branch on its own. The integration PR into the base branch always stays",
+        "human-gated. Pass --attended to opt out. An unattended run needs consent",
+        "(on by default, switched on the Setup page of the Bridge admin panel), an",
+        "escalation channel (a verified notify webhook or your account email), and",
+        "confirmed review and CI workflows on the default branch. Readiness lists each",
+        "with its state, and a missing one is refused by name before a run is created.",
+        "",
+        "Every run gets an executor: once the run is created, drive-epic starts one in",
+        "the background from this checkout's Git top level. It claims only that run's",
+        "jobs, logs to .bridge/executors/<run>.log, and exits when the run is done.",
+        "Running again for the same live run starts no second one. If it fails to",
+        "start, the run is left intact and the log path and the command to start it",
+        "by hand are printed.",
+        "",
+        "Run it from a Git work tree inside the target repository. Preconditions are",
+        "checked, never repaired: each failure names the fix. Fix it and rerun.",
+        "",
+        "Options:",
+        "  --plan-file <path>     Plan DAG sidecar. Optional: without it, drive-epic finds",
+        "                         the plan by epic key (see above).",
+        "  --repo <name>          Repo name (default: BAPI_REPO_NAME or .bridge/config)",
+        "  --feature-branch <name>  Override the derived epic/<KEY> name. Forwarded",
+        "                         verbatim, never interpreted here.",
+        "  --into-base            Opt out of the epic-branch default: children target the",
+        "                         repository base branch. Cannot be combined with",
+        "                         --feature-branch.",
+        "  --attended             Opt out of the unattended default. Forwarded verbatim to",
+        "                         setup, which owns what it composes.",
+        "",
+        "Policy (forwarded verbatim; drive-epic interprets none of it):",
+        "  --policy-file <path>   JSON file holding the COMPLETE run policy.",
+        "  --review-policy <src>  Per-run review policy source.",
+        "  --replace-policy       Authorize replacing a LIVE run's stored policy.",
+        "  --verification-handoff proceed|block",
+        "                         The owner's verification hand-off choice for a NEW run.",
+        "  --verification-handoff-exception <TICKET>:<e2e_tests|rendered_ui_review>",
+        "                         Repeatable. With `block`, keeps verification a blocker",
+        "                         for that ticket and class.",
+        "",
+        "Target:",
+        "  --base-url <url>       Explicit Bridge API target. Without it, BAPI_BASE_URL is",
+        `                         used; with neither, drive-epic targets production`,
+        `                         (${CONDUCTOR_DEFAULT_BASE_URL}) and uses the stored`,
+        "                         bapi:<repo> key when one is available. A stored key",
+        "                         approved for a different endpoint is never sent.",
+        "",
+        "Preview:",
+        "  --dry-run              Read-only launch preview. Resolves the target, reads",
+        "                         readiness and the epic's live run, discovers the plan,",
+        "                         and runs setup's own dry-run validation. It shows what a",
+        "                         real run WOULD do (create a run, reuse the epic's live run,",
+        "                         refuse, or stop) and creates nothing. Exit 0 when it would",
+        "                         create or reuse a run, 1 when it would refuse or stop.",
+        "  --json                 With --dry-run only: print exactly one JSON document on",
+        "                         stdout and nothing else. Alone, it is a parse error.",
+        "",
+        "Already-merged children: when a NEW run is created, drive-epic leaves out plan",
+        "children that are provably already merged. A child with a merged PR but no",
+        "delivery record is only 'probably done' and runs unless you confirm it.",
+        "Anything uncertain runs. Skipped children are recorded for audit only.",
+        "  --keep-child <KEY>     Repeatable. Run this child even if it is already merged.",
+        "  --skip-child <KEY>     Repeatable. Leave this child out. Refused unless the",
+        "                         child is currently done or probably done.",
+        "  --no-merged-check      Do not look for already-merged children. Cannot be",
+        "                         combined with --skip-child.",
+        "",
+        "  -h, --help             Show this help",
+        "  --help-advanced        Show the owner-only options",
+        "",
+        ADVANCED_HELP_POINTER,
+    ].join("\n");
+}
+export function getDriveEpicAdvancedUsage() {
+    return [
+        "Usage: mcp-server drive-epic [options] <EPIC>   (advanced help)",
+        "",
+        "Owner-only material for people who run their own Bridge server, or who host",
+        "epic launches on a durable machine. Hosted customers do not need any of it:",
+        "see `drive-epic --help` for the normal launch options.",
+        "",
+        "Reconciler liveness is read from the deployment's heartbeat. Against a target",
+        "that is not this machine's local plane (production, say), drive-epic never",
+        "touches a local plane: a target with no live reconciler is refused by name.",
+        "",
+        "Composed bring-up: with --plan-file, drive-epic starts the Epic Implementer",
+        "runtime for you against the local plane endpoint, when readiness is missing",
+        "ONLY the reconciler. It brings up the CONTROL PLANE first (server and",
+        "reconciler), creates and approves the run, then starts executor lanes SCOPED",
+        "to that run, and starts the dead-man observer last — one invocation, no",
+        "manual `plane up` first. A report missing supervisor setup, supervisor",
+        "configuration, GitHub App credentials, or an unattended prerequisite is NOT",
+        "started: those are owner-owned, and drive-epic exits with that one named",
+        "reason instead.",
+        "",
+        "The plane port: with --plan-file and BAPI_BASE_URL naming the local plane",
+        `endpoint (127.0.0.1, port ${PLANE_SERVER_PORT_ENV_VAR} or the default),`,
+        "drive-epic handles the port one of three ways, and never asks you to choose:",
+        "  - cold start: nothing listens there — it brings the plane up, then creates",
+        "    the run;",
+        "  - attach: this repository's own healthy plane is there — it creates the run",
+        "    against that plane and starts NO second server or reconciler;",
+        "  - refusal: anything else holds the port (another listener, a manifest for a",
+        "    different repository, an unreadable manifest, a plane that cannot take a",
+        "    run) — one named reason, and nothing is started.",
+        "One epic per plane — for its LANES: a plane's lanes serve the one run it is",
+        "bound to. A second run attaches to the same plane's reconciler and gets its own",
+        "run-scoped executor instead. A plane whose bound run cannot be read is refused",
+        "as plane-already-bound. Concurrent planes on one database are not supported.",
+        "Executor lanes and run-scoped executors are always scoped to the one run with",
+        "--epic-run-id, on every path.",
+        "",
+        "Run-scoped executors and durable hosts: a durable launch profile starts no",
+        "run-scoped executor. It requires a fresh --repo-wide executor instead, which",
+        "covers the repository. A plane's own lane is that run's executor, so none is",
+        "started beside it. Checks that need no run happen FIRST, so a refusal before",
+        "the run is created creates nothing.",
+        "",
+        "A live run beside a FOUND plan: when the epic already has a live run and the",
+        "plan came from discovery rather than --plan-file, drive-epic attaches to the",
+        "live run first. The found plan is reported as \"Found, unused\", is not treated",
+        "as approved input, and its file is left untouched. A plan you pass with",
+        "--plan-file keeps its create-path behavior unchanged.",
+        "",
+        "A live run with no plan: when the epic already has a live run and no plan was",
+        "supplied or found, drive-epic does not create anything. It makes sure that run",
+        "has an executor (reusing a live one, never starting a second) and shows it. A",
+        "durable launch profile starts none and relies on its host's confirmed",
+        "repo-wide executor; a plane already bound to the run needs none. An epic with",
+        "several active runs, or a run that cannot be read, is refused by name.",
+        "",
+        "Repository-wide executors: `install conductor --executor-id <id> --repo-wide`",
+        "provisions a persistent executor that claims jobs for every run in the",
+        "repository. A durable host needs one before it can launch.",
+        "",
+        "Launch target — decided BEFORE any authenticated request:",
+        "  --launch-profile <name>  Select the host-local launch profile guided setup",
+        "                         approved (`install conductor --launch-profile <name>`):",
+        "                         target, repository, mode, runtime, and policy and",
+        "                         credential references. Useful for a local or other",
+        "                         non-production server and for durable hosts.",
+        "  --base-url <url>       Explicit Bridge API target. With a profile it must",
+        "                         agree with it — an override never rebinds a profile.",
+        "BAPI_EPIC_LAUNCH_PROFILE selects a host-local launch profile for epic",
+        "launches. --launch-profile takes precedence. For an environment-selected",
+        "profile, BAPI_BASE_URL remains the general CLI endpoint and does not",
+        "conflict with the epic launch target; --base-url still must agree.",
+        "Without either, BAPI_BASE_URL is used. With none of the three, drive-epic",
+        `targets production (${CONDUCTOR_DEFAULT_BASE_URL}) and uses the`,
+        "stored bapi:<repo> key when one is available. A stored key approved for a",
+        "different endpoint is never sent; an unapproved key is sent only to",
+        "production.",
+        "",
+        "Local-plane freshness:",
+        "  Before a launch CREATES a run on this machine's plane, drive-epic checks that the",
+        "  plane's pinned snapshot is not behind origin/main and that the database is at the",
+        "  migration head. A CONFIRMED problem refuses before any setup or run creation; evidence",
+        "  it cannot read is a warning. Attaching to a run that already exists only warns.",
+        "  --allow-stale-plane    Override for ONE invocation: bypasses only those two",
+        "                         refusals. It repairs nothing, is not persisted, and does not",
+        "                         bypass readiness, authentication, ownership, or admission.",
+        "                         Valid with or without --dry-run.",
+        "  --dry-run may run `git fetch` (it updates remote-tracking refs) but changes no checkout",
+        "  contents, plane configuration, database state, or run state.",
+        "",
+        "  -h, --help             Show the basic help",
+        "  --help-advanced        Show this help",
+    ].join("\n");
+}