@bridge_gpt/mcp-server 0.2.37 → 0.2.39

package/build/install-bridge-conductor.js

@@ -26,11 +26,31 @@
  * 3. **Two independent consents.** Confirming the resolved base URL is NOT
  *    consent to write, and neither is consent to overwrite a workflow file. Each
  *    write surface asks for itself.
- * 4. **The executor leg is never claimed as provisioned by a bootstrap.** The
- *    doctor *detects* generated service units (`executor install-service`,
- *    BAPI-688), but starting one stays operator-managed, so the capability
- *    matrix reports `executor_ready` only from a live server-observed claim and
- *    the run prints `complete-with-manual-steps` until then.
+ * 4. **The executor leg is never claimed as provisioned by local success.**
+ *    AMENDED BY BAPI-779 (R-1): this command can now write the service unit
+ *    *and* start it. What did not change — and must not — is where readiness
+ *    comes from. The capability matrix reports `executor_ready` only from a
+ *    live server-observed claim, so a written unit, a successful
+ *    `launchctl bootstrap`, and a successful `systemctl --user enable --now`
+ *    all still print `complete-with-manual-steps` until the SERVER says
+ *    otherwise. Local lifecycle success and server observation are reported as
+ *    two separate facts, and the second is never derived from the first.
+ *
+ * The executor phase (BAPI-779) is opt-in via `--executor-id` and runs behind
+ * TWO independent consents, per property 3: writing the unit is not consent to
+ * start a persistent daemon. Its shape is:
+ *
+ *   preflight (platform / `wt`,`git`,`claude` / explicit base URL — plus an
+ *   ADVISORY `claude login` line that never blocks, because BAPI-791 moved the
+ *   definitive auth check to the first worker spawn)
+ *     → consent 1: write the unit through the existing generator
+ *     → consent 2: start the service, ONE attempt, never a retry loop
+ *     → bounded server observation (~90s) — observed ⇒ `executor_ready`,
+ *       timeout ⇒ an honest degradation naming what was and was not achieved.
+ *
+ * Declining either consent, a start failure, and an observation timeout are all
+ * non-fatal: the run prints the exact platform-specific start command and
+ * finishes at `complete-with-manual-steps`.
  *
  * The command does NOT persist a repository-level review policy: that is
  * BAPI-694's. The policy selected here is per-run and is reported as such.
@@ -38,6 +58,9 @@
 import { bootstrapConductorSupervisorDefaults, ConductorBridgeApiError, fetchConductorReadiness, } from "./conductor/bridge-api-client.js";
 import { CONDUCTOR_OPERATOR_RUNBOOK_POINTER, EXECUTOR_PROVISIONING_GUIDANCE, conductorInstallDoctorExitCode, conductorInstallDoctorHasFatal, formatConductorInstallDoctorReport, } from "./conductor/install-doctor.js";
 import { CLAUDE_REVIEW_WORKFLOW_RELPATH, renderClaudeReviewWorkflow, } from "./claude-review-workflow.js";
+import { formatExecutorInstallPreflight, } from "./executor/install-preflight.js";
+import { buildExecutorServiceStartPlan, formatExecutorServiceStartFailure, } from "./executor/service-lifecycle.js";
+import { planExecutorServiceInstall, } from "./executor/service-unit.js";
 // ---------------------------------------------------------------------------
 // Options + parsing
 // ---------------------------------------------------------------------------
@@ -63,19 +86,26 @@ export function getInstallBridgeConductorUsage() {
         "  --required-check <name>    Required CI check for the done gate (repeatable, REQUIRED)",
         "  --required-checks a,b      Comma-separated form of --required-check",
         `  --review-policy <source>   One of: ${CONDUCTOR_REVIEW_POLICY_SOURCES.join(", ")}`,
-        `                             (default: ${DEFAULT_CONDUCTOR_REVIEW_POLICY}; PER-RUN only —`,
-        "                             repository defaults are not stored until BAPI-694)",
+        `                             (default: ${DEFAULT_CONDUCTOR_REVIEW_POLICY}). Supplying it`,
+        "                             EXPLICITLY also persists it as the supervisor",
+        "                             project default, stamped into a new run that",
+        "                             carries no review policy of its own. Omitting it",
+        "                             stores no default at all.",
         "  --epic-key <KEY>           Epic key for the setup-epic verification phase",
         "  --plan-file <path>         Plan sidecar for the setup-epic verification phase",
+        "  --executor-id <id>         Stable executor id. Supplying it OPTS IN to the",
+        "                             consented executor-provisioning phase below; the",
+        "                             phase is skipped entirely without it.",
         "  --allowed-bot <slug>       claude-review workflow: allowed bot login",
         "  --secret-name <NAME>       claude-review workflow: OAuth token secret NAME",
         "  --branches a,b             claude-review workflow: PR branch triggers",
         "  --skip-workflow            Never offer the claude-review workflow",
         "  --dry-run                  Diagnose and preview only. Performs NO writes:",
         "                             no POST, no file write, no install-state write,",
-        "                             and no write-consent prompt. Still asks the",
-        "                             base-URL confirmation below first — its doctor",
-        "                             readiness GET carries the repo API key.",
+        "                             no service-unit write, no launchctl/systemctl",
+        "                             command, and no write- or start-consent prompt.",
+        "                             Still asks the base-URL confirmation below first —",
+        "                             its doctor readiness GET carries the repo API key.",
         "  -h, --help                 Show this help",
         "",
         "The resolved BAPI_BASE_URL is displayed and confirmed BEFORE any network call",
@@ -83,9 +113,27 @@ export function getInstallBridgeConductorUsage() {
         "production when unset). The bootstrap POST then asks its own, separate write",
         "consent. Without a TTY there is no consent, so the command aborts.",
         "",
-        "Executor provisioning: generate a persistent service unit with",
-        "`executor install-service` (BAPI-688). Starting/stopping it stays",
-        `operator-managed; see ${CONDUCTOR_OPERATOR_RUNBOOK_POINTER}.`,
+        "Executor provisioning: `executor install-service` still generates a unit and",
+        "nothing else, and remains available for operators who want the file only.",
+        "",
+        "With --executor-id, this command does the whole leg. A preflight checks the platform,",
+        "`wt` / `git` / `claude` on PATH, and an explicit base URL, then reports whether",
+        "this host has a `claude login` marker — that line is ADVISORY and never blocks,",
+        "and no API key, token, or other credential is requested, stored, or checked.",
+        "",
+        "Two independent consents follow. The first writes the service unit; the second,",
+        `asked separately, starts it (${"`launchctl bootstrap`"} on darwin,`,
+        "`systemctl --user daemon-reload && systemctl --user enable --now` on linux) with",
+        "exactly one attempt and no retry loop. Declining either one, or a start that",
+        "fails, prints the exact start command and finishes at complete-with-manual-steps.",
+        "",
+        "After a successful start the command polls the server for roughly 90 seconds for",
+        "the executor to be observed. Only that live server observation can report",
+        "executor_ready: a written unit and a successful local start never can, so an",
+        "observation timeout finishes at complete-with-manual-steps and says exactly what",
+        "was and was not achieved.",
+        "",
+        `See ${CONDUCTOR_OPERATOR_RUNBOOK_POINTER}.`,
     ].join("\n");
 }
 function splitList(raw) {
@@ -109,8 +157,10 @@ export function parseInstallBridgeConductorArgs(argv) {
     let dryRun = false;
     let skipWorkflow = false;
     let reviewPolicy = DEFAULT_CONDUCTOR_REVIEW_POLICY;
+    let reviewPolicyExplicit = false;
     let epicKey;
     let planFile;
+    let executorId;
     let allowedBot;
     let secretName;
     let branches;
@@ -148,6 +198,7 @@ export function parseInstallBridgeConductorArgs(argv) {
             case "--review-policy":
             case "--epic-key":
             case "--plan-file":
+            case "--executor-id":
             case "--allowed-bot":
             case "--secret-name":
             case "--branches": {
@@ -167,6 +218,8 @@ export function parseInstallBridgeConductorArgs(argv) {
                     epicKey = value;
                 else if (flag === "--plan-file")
                     planFile = value;
+                else if (flag === "--executor-id")
+                    executorId = value;
                 else if (flag === "--allowed-bot")
                     allowedBot = value;
                 else if (flag === "--secret-name")
@@ -185,6 +238,7 @@ export function parseInstallBridgeConductorArgs(argv) {
                         };
                     }
                     reviewPolicy = value;
+                    reviewPolicyExplicit = true;
                 }
                 break;
             }
@@ -218,16 +272,85 @@ export function parseInstallBridgeConductorArgs(argv) {
             dryRun,
             requiredChecks: normalizedChecks,
             reviewPolicy,
+            reviewPolicyExplicit,
             epicKey,
             planFile,
             allowedBot,
             secretName,
             branches,
             skipWorkflow,
+            executorId,
         },
     };
 }
 // ---------------------------------------------------------------------------
+// Bounded readiness observation (BAPI-779)
+// ---------------------------------------------------------------------------
+/** Total wall-clock budget for observing the executor server-side. */
+export const EXECUTOR_OBSERVATION_BUDGET_MS = 90_000;
+/** Fixed gap between readiness reads, clamped by the remaining budget. */
+export const EXECUTOR_OBSERVATION_INTERVAL_MS = 5_000;
+/**
+ * Poll `GET /jira/epic-runs/conductor-readiness` until the SERVER reports the
+ * executor ready, or the monotonic budget expires.
+ *
+ * Three properties matter here and are pinned by tests:
+ *
+ *  - **Only `executor.ready === true` is readiness.** `false`, `null`, a
+ *    truthy non-boolean, a payload that fails shape validation, and a transport
+ *    error are all non-ready. This is the single place the `executor_ready`
+ *    claim can originate, so a loose truthiness check here would silently
+ *    reintroduce the dishonest-claim failure mode property 4 exists to prevent.
+ *  - **The deadline bounds fetches AND sleeps.** No request is issued after the
+ *    deadline, and a sleep is clamped to the remaining time, so the phase can
+ *    never overrun its budget by up to one interval.
+ *  - **Validation is centralized.** Every read goes through
+ *    `fetchConductorReadiness`, so the authenticated URL construction and the
+ *    response shape check are the same ones the doctor uses.
+ */
+export async function observeExecutorReadiness(access, fetchJson, deps, options = {}) {
+    const budgetMs = options.budgetMs ?? EXECUTOR_OBSERVATION_BUDGET_MS;
+    const intervalMs = options.intervalMs ?? EXECUTOR_OBSERVATION_INTERVAL_MS;
+    const deadline = deps.now() + budgetMs;
+    let lastReady = null;
+    let lastSeenAt = null;
+    let lastSeenAgeSeconds = null;
+    let readFailures = 0;
+    let attempts = 0;
+    while (deps.now() < deadline) {
+        attempts++;
+        try {
+            const readiness = await fetchConductorReadiness(access, fetchJson);
+            if (readiness.executor.ready === true) {
+                return { status: "observed", readiness };
+            }
+            // A validated non-ready read: remember it so the timeout can report what
+            // the server actually said, not merely that nothing happened.
+            lastReady = readiness.executor.ready;
+            lastSeenAt = readiness.executor.last_seen_at;
+            lastSeenAgeSeconds = readiness.executor.last_seen_age_seconds;
+        }
+        catch {
+            // Shape-validation failures and transport errors are indistinguishable to
+            // an operator waiting for an executor, and both are retryable within the
+            // budget. The thrown value is discarded — it can carry a URL.
+            readFailures++;
+        }
+        const remaining = deadline - deps.now();
+        if (remaining <= 0)
+            break;
+        await deps.sleep(Math.min(intervalMs, remaining));
+    }
+    return {
+        status: "timeout",
+        lastReady,
+        lastSeenAt,
+        lastSeenAgeSeconds,
+        readFailures,
+        attempts,
+    };
+}
+// ---------------------------------------------------------------------------
 // Runner
 // ---------------------------------------------------------------------------
 const CONSENT_YES = new Set(["y", "yes"]);
@@ -260,6 +383,126 @@ function renderCapabilityMatrix(deps, readiness) {
     deps.log(`  runbook:              ${CONDUCTOR_OPERATOR_RUNBOOK_POINTER}`);
     return { apiReady, configurationReady, executorReady };
 }
+/**
+ * Build both plans, or explain why the host cannot be provisioned.
+ *
+ * PURE apart from `resolveInvocation`, which reads this process's own launcher
+ * path. Computing the plans BEFORE any consent is what lets a dry run print the
+ * real target path and the real start command instead of a guess.
+ */
+function buildExecutorProvisioningPlans(executor, executorId, baseUrl, 
+/**
+ * The repositories the generated unit serves. Taken from the RESOLVED Bridge
+ * access rather than from a flag, so the unit can only ever serve the
+ * repository this install actually authenticated for.
+ */
+repos) {
+    if (executor.platform !== "darwin" && executor.platform !== "linux") {
+        return {
+            ok: false,
+            error: `platform '${executor.platform}' has no supported executor service format.`,
+        };
+    }
+    const platform = executor.platform;
+    const invocation = executor.resolveInvocation();
+    if (!invocation.ok)
+        return { ok: false, error: invocation.error };
+    let install;
+    try {
+        install = planExecutorServiceInstall({
+            invocation: invocation.invocation,
+            executorId,
+            repos,
+            baseUrl,
+            homeDir: executor.homeDir,
+            envPath: executor.envPath,
+        }, platform);
+    }
+    catch (err) {
+        // The generator's validation errors are already secret-free sentences.
+        return { ok: false, error: err instanceof Error ? err.message : "invalid unit input" };
+    }
+    const start = buildExecutorServiceStartPlan({
+        platform,
+        unitPath: install.unitPath,
+        serviceIdentifier: install.serviceIdentifier,
+        uid: executor.uid,
+    });
+    if (!start.ok)
+        return { ok: false, error: start.error };
+    return { ok: true, plans: { install, start: start.plan } };
+}
+/**
+ * Write the unit, start the service, and watch for a server observation — each
+ * step behind its own gate, and every failure a reported degradation.
+ *
+ * Returns the readiness payload ONLY when the server actually observed the
+ * executor. Returning `null` for every other path is what keeps the capability
+ * matrix honest: there is no code path here that can hand the matrix a
+ * fabricated ready response derived from a written file or a zero exit code.
+ */
+async function runExecutorProvisioningPhase(deps, executor, plans, access) {
+    // ---- Consent A: write the unit ----------------------------------------
+    const writeOk = await confirm(deps, `Write the executor service unit ${plans.install.unitPath}? [y/N]: `);
+    if (!writeOk) {
+        deps.log("  declined — no unit was written and nothing was started.");
+        deps.log(`  to provision by hand later: ${plans.start.manualCommand}`);
+        return null;
+    }
+    let writeResult;
+    try {
+        writeResult = await executor.writeUnit(plans.install);
+    }
+    catch {
+        deps.errorLog("  the service unit could not be written; nothing was started.");
+        return null;
+    }
+    deps.log(`  ${writeResult.outcome} ${writeResult.unitPath}`);
+    // Install-state is a diagnostic aid, not a correctness dependency: a failure
+    // here does not invalidate the unit that was just written, so it warns.
+    const recorded = await executor.recordUnit(writeResult.unitPath);
+    if (!recorded.ok) {
+        deps.errorLog(`  note: install-state not updated (${recorded.error ?? "unknown"})`);
+    }
+    // ---- Consent B: start the service -------------------------------------
+    // Deliberately separate from consent A. Writing a file and starting a
+    // persistent daemon that will claim work are different decisions, and the
+    // exact command is printed BEFORE the question so the operator is consenting
+    // to something specific.
+    deps.log("");
+    deps.log(`  start command: ${plans.start.manualCommand}`);
+    const startOk = await confirm(deps, "Start the executor service now? [y/N]: ");
+    if (!startOk) {
+        deps.log("  declined — the unit is written but the service was not started.");
+        deps.log(`  start it by hand with: ${plans.start.manualCommand}`);
+        return null;
+    }
+    const startResult = await executor.startService(plans.start);
+    if (!startResult.ok) {
+        deps.errorLog(`  ${formatExecutorServiceStartFailure(startResult)}`);
+        deps.errorLog(`  start it by hand with: ${startResult.manualCommand}`);
+        return null;
+    }
+    deps.log("  the service manager accepted the unit.");
+    // ---- Bounded observation ----------------------------------------------
+    // Only reached after a SUCCESSFUL start: polling for an executor that was
+    // never started would burn the whole budget to learn what we already know.
+    deps.log(`  watching the server for an executor claim (up to ${Math.round(EXECUTOR_OBSERVATION_BUDGET_MS / 1000)}s)…`);
+    const observation = await observeExecutorReadiness(access, deps.fetchJson, executor);
+    if (observation.status === "observed") {
+        deps.log("  the server observed this executor.");
+        return observation.readiness;
+    }
+    // The honest degradation: name what WAS achieved and what was not, separately.
+    deps.log("  the unit was written and the service manager started it,");
+    deps.log("  but the server did not observe an executor claim within the budget " +
+        `(${observation.attempts} read(s), ${observation.readFailures} unreadable).`);
+    deps.log(observation.lastReady === false
+        ? "  the server last reported this repository's executor as stale/not ready."
+        : "  the server has not yet seen any executor claim for this repository.");
+    deps.log("  executor_ready is NOT claimed — only a live server observation can produce it.");
+    return null;
+}
 /**
  * Run the nested conductor installer. Returns the process exit code.
  */
@@ -299,7 +542,7 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     const access = accessResult.ok ? accessResult.access : null;
     const accessError = accessResult.ok ? undefined : accessResult.error;
     // ---- Phase 1: unified doctor, BEFORE every write -----------------------
-    deps.log("Phase 1/5 — running the unified conductor doctor (read-only)…");
+    deps.log("Phase 1/6 — running the unified conductor doctor (read-only)…");
     const firstReport = await deps.runDoctor({
         access,
         accessError,
@@ -312,11 +555,63 @@ export async function runInstallBridgeConductorCli(argv, deps) {
             "install-state, or verification step was attempted.");
         return 1;
     }
-    // ---- Review policy: per-run, explicitly NOT a repository default -------
+    // ---- Review policy: per-run, and a repository default when explicit ----
     deps.log("");
-    deps.log(`Review policy (per-run): ${options.reviewPolicy}`);
-    deps.log("  This selection applies to runs created with it. Repository-level review-policy " +
-        "defaults are not stored yet — that is BAPI-694.");
+    deps.log(`Review policy: ${options.reviewPolicy}`);
+    deps.log(options.reviewPolicyExplicit
+        ? "  Explicitly selected, so it is ALSO persisted as the supervisor project " +
+            "default and stamped into a new run that sets no review policy of its own. " +
+            "An explicit per-run policy always wins, and changing this later never " +
+            "alters an already-approved run."
+        : "  Applied to runs created with this selection. No repository default is " +
+            "persisted — pass --review-policy explicitly to store one.");
+    // ---- Executor preflight: AFTER the URL consent, BEFORE any mutation ----
+    // Placed here so an unsupported host or a missing `wt`/`git`/`claude` refuses
+    // before the bootstrap POST, the workflow write, or a single filesystem
+    // effect — provisioning a service that cannot run is worse than refusing —
+    // and before the dry-run return, so `--dry-run` reports the same refusal.
+    const executor = deps.executorProvisioning;
+    const executorRequested = Boolean(executor && options.executorId);
+    let executorPlans = null;
+    if (executor && executorRequested) {
+        deps.log("");
+        deps.log("Executor provisioning — preflight (read-only)…");
+        const preflight = await executor.runPreflight({
+            platform: executor.platform,
+            baseUrl,
+        });
+        deps.log(formatExecutorInstallPreflight(preflight));
+        if (!preflight.ok) {
+            // A plain refusal with remediation — never a silent skip, and never a
+            // credential complaint: the only auth-related output above is the
+            // advisory login line.
+            deps.errorLog("");
+            deps.errorLog("Executor provisioning refused — this host cannot run a conductor executor.");
+            for (const remediation of preflight.remediations)
+                deps.errorLog(`  → ${remediation}`);
+            deps.log("");
+            deps.log("complete-with-manual-steps");
+            return 1;
+        }
+        // The unit serves the repository this run resolved access for. When access
+        // could not be resolved the doctor above has already produced a fatal
+        // section, so this fallback only matters for the narrow window where a
+        // caller injected a non-fatal doctor.
+        const planned = buildExecutorProvisioningPlans(executor, options.executorId, baseUrl, access ? [access.repoName] : []);
+        if (!planned.ok) {
+            deps.errorLog("");
+            deps.errorLog(`Executor provisioning refused — ${planned.error}`);
+            deps.log("");
+            deps.log("complete-with-manual-steps");
+            return 1;
+        }
+        executorPlans = planned.plans;
+    }
+    else if (executor) {
+        deps.log("");
+        deps.log("  executor provisioning skipped — pass --executor-id <id> to write and start a " +
+            "service unit for this host.");
+    }
     // ---- Dry run: preview and RETURN before every write/prompt -------------
     if (options.dryRun) {
         deps.log("");
@@ -327,6 +622,8 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         deps.log("    - done_gate_config.required_checks " +
             `(${options.requiredChecks.length} check(s))`);
         deps.log("    - review_source");
+        if (options.reviewPolicyExplicit)
+            deps.log("    - review_policy");
         deps.log("    - auto_merge_enabled");
         deps.log("    - merge_approval_required");
         deps.log(`  Would target base URL: ${baseUrl}`);
@@ -336,6 +633,19 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         deps.log(options.epicKey && options.planFile
             ? `  Would verify with: setup-epic --dry-run --epic-key ${options.epicKey}`
             : "  setup-epic verification: skipped (no --epic-key/--plan-file supplied)");
+        // The REAL planned path and the REAL start command — computed by the same
+        // pure planners the live run uses, so the preview cannot drift from what
+        // would actually happen. Still zero writes: no unit writer, no
+        // install-state recorder, no lifecycle runner, and no consent prompt has
+        // been reached on this branch.
+        if (executorPlans) {
+            deps.log(`  Would write executor unit: ${executorPlans.install.unitPath}`);
+            deps.log(`  Would start it with:       ${executorPlans.start.manualCommand}`);
+            deps.log("  Executor provisioning: two separate consents (write, then start) — neither was asked.");
+        }
+        else if (executor) {
+            deps.log("  Executor provisioning: skipped (no --executor-id supplied)");
+        }
         renderCapabilityMatrix(deps, firstReport.readiness);
         deps.log("");
         deps.log("complete-with-manual-steps (dry run)");
@@ -358,12 +668,19 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     }
     // ---- Phase 2: bootstrap ------------------------------------------------
     deps.log("");
-    deps.log("Phase 2/5 — bootstrapping supervisor project defaults…");
+    deps.log("Phase 2/6 — bootstrapping supervisor project defaults…");
     let bootstrapResponse;
     try {
         bootstrapResponse = await bootstrapConductorSupervisorDefaults(access, {
             required_checks: options.requiredChecks,
             review_source: "verdict_protocol",
+            // BAPI-694 — the narrow ReviewPolicy object, sent ONLY on an explicit
+            // selection. `review_source` above is deliberately left alone: it is the
+            // WIDER done-gate vocabulary and the two are not interchangeable, so
+            // neither value is coerced into the other.
+            ...(options.reviewPolicyExplicit
+                ? { review_policy: { source: options.reviewPolicy } }
+                : {}),
             merge_approval_required: "true",
         }, deps.postJson);
     }
@@ -375,7 +692,7 @@ export async function runInstallBridgeConductorCli(argv, deps) {
     deps.log(`  wrote supervisor setup + config (fields: ${bootstrapResponse.audited_field_names.join(", ")})`);
     // ---- Phase 3: optional workflow scaffold -------------------------------
     deps.log("");
-    deps.log("Phase 3/5 — claude-review workflow…");
+    deps.log("Phase 3/6 — claude-review workflow…");
     if (options.skipWorkflow || options.reviewPolicy !== "verdict_protocol") {
         deps.log(`  skipped — the '${options.reviewPolicy}' review policy does not consume the ` +
             "sticky verdict this workflow emits.");
@@ -432,25 +749,13 @@ export async function runInstallBridgeConductorCli(argv, deps) {
             }
         }
     }
-    // ---- Phase 4: capability matrix from POST-bootstrap readiness ----------
-    deps.log("");
-    deps.log("Phase 4/5 — capability report…");
-    let postReadiness = null;
-    try {
-        postReadiness = await fetchConductorReadiness(access, deps.fetchJson);
-    }
-    catch {
-        // Degraded, not fatal: the write already succeeded, and the matrix simply
-        // reports what it can observe.
-        deps.errorLog("  readiness could not be re-read; capability matrix is best-effort.");
-    }
-    const matrix = renderCapabilityMatrix(deps, postReadiness);
-    // ---- setup-epic verification (conditional) -----------------------------
+    // ---- Phase 4: setup-epic verification (conditional) --------------------
     // `parseSetupEpicArgs` hard-requires --epic-key AND --plan-file before any
     // dry-run branch, so this phase can only run when both are supplied. Fresh
     // repositories skip it with an explicit message rather than hard-failing.
+    deps.log("");
+    deps.log("Phase 4/6 — setup-epic verification…");
     if (options.epicKey && options.planFile) {
-        deps.log("");
         deps.log("  verifying with `setup-epic --dry-run`…");
         const verification = await deps.runSetupEpicDryRun([
             "--dry-run",
@@ -471,12 +776,45 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         deps.log("  setup-epic verification passed.");
     }
     else {
-        deps.log("");
         deps.log("  setup-epic verification skipped — pass --epic-key and --plan-file once a plan exists.");
     }
-    // ---- Phase 5: final doctor ---------------------------------------------
+    // ---- Phase 5: consented executor provisioning (BAPI-779) ---------------
+    // Runs AFTER the pre-existing phases so a bootstrap failure never leaves a
+    // started daemon behind, and BEFORE the capability report so the matrix can
+    // use the readiness this phase actually observed.
+    deps.log("");
+    deps.log("Phase 5/6 — executor provisioning…");
+    let observedReadiness = null;
+    if (executor && executorPlans) {
+        observedReadiness = await runExecutorProvisioningPhase(deps, executor, executorPlans, access);
+    }
+    else {
+        deps.log("  skipped — " +
+            (executor
+                ? "no --executor-id was supplied."
+                : "this caller supplied no executor-provisioning seams."));
+    }
+    // ---- Phase 6: capability matrix + final doctor -------------------------
+    deps.log("");
+    deps.log("Phase 6/6 — capability report…");
+    // The observed payload WINS when the executor phase actually saw the server
+    // report readiness. Otherwise the matrix re-reads readiness itself — it is
+    // never handed a synthesized response, so `executor_ready` still originates
+    // from exactly one place: a live server observation.
+    let postReadiness = observedReadiness;
+    if (postReadiness === null) {
+        try {
+            postReadiness = await fetchConductorReadiness(access, deps.fetchJson);
+        }
+        catch {
+            // Degraded, not fatal: the write already succeeded, and the matrix simply
+            // reports what it can observe.
+            deps.errorLog("  readiness could not be re-read; capability matrix is best-effort.");
+        }
+    }
+    const matrix = renderCapabilityMatrix(deps, postReadiness);
     deps.log("");
-    deps.log("Phase 5/5 — re-running the unified conductor doctor (read-only)…");
+    deps.log("  re-running the unified conductor doctor (read-only)…");
     const finalReport = await deps.runDoctor({
         access,
         reviewPolicySource: options.reviewPolicy,