@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/setup-epic.js

@@ -47,7 +47,7 @@
  *      association is immutable server-side and can never be attached later.
  *   c. Cut or validate `origin/<feature>` at EXACTLY the canonical indexed SHA
  *      with the operator's LOCAL `git`, through the shared cut protocol
- *      `conduct-epic init` also drives, with the run id so the scope is minted
+ *      `implement-epic init` also drives, with the run id so the scope is minted
  *      owned by the run. An existing branch at a different commit fails closed.
  *      The GitHub App never pushes — it is `contents: read`.
  *   d. Store and approve (unchanged requests). The server now READ-validates the
@@ -78,10 +78,10 @@
 import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
 import os from "node:os";
 import { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, formatEpicIntegrationPullRequestOutcome, } from "./epic-integration-pr.js";
-import { approveEpicPlan, createEpicRunWithDisposition, fetchEpicRunState, replaceEpicRunPolicy, resolveConductorBridgeApiAccess, storeEpicPlan, validateEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
+import { approveEpicPlan, createEpicRunWithDisposition, fetchConductorReadiness, fetchEpicRunState, replaceEpicRunPolicy, resolveConductorBridgeApiAccess, storeEpicPlan, validateEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
 import { resolveTrackedPaths } from "./git-reachability.js";
 import { validateBranchName } from "./base-ref.js";
-// Reused from the conduct-epic client on purpose: adding a second wrapper under
+// Reused from the implement-epic client on purpose: adding a second wrapper under
 // `conductor/` would give the v2 path its own copy to drift from.
 //
 // BAPI-850 extends that reuse to the canonical parse read, the repository base
@@ -89,15 +89,45 @@ import { validateBranchName } from "./base-ref.js";
 // typed clients the pilot already has are the v2 path's clients too, so neither
 // conductor can drift on a field name or an endpoint shape. No MCP tool, no
 // input-schema field, and no description changes.
-import { getConfigFieldBaseBranch, getIndexScopeLifecycle, getParseStatus, } from "./conduct-epic/bridge-client.js";
-import { boundScopeLifecycleLabel, createExecFileRunCommand, ensureCommitResolvableLocally, normalizeCommitSha, performExactIndexScopeCut, pollIndexScopeLifecycle, readRemoteBranchHead, runGit, SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, SCOPE_LIFECYCLE_LABELS, } from "./conduct-epic/cut-protocol.js";
+import { getConfigFieldBaseBranch, getIndexScopeLifecycle, getParseStatus, } from "./implement-epic/bridge-client.js";
+import { boundScopeLifecycleLabel, createExecFileRunCommand, ensureCommitResolvableLocally, normalizeCommitSha, performExactIndexScopeCut, pollIndexScopeLifecycle, readRemoteBranchHead, runGit, SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, SCOPE_LIFECYCLE_LABELS, } from "./implement-epic/cut-protocol.js";
 import { hashPlan } from "./conductor/plan.js";
+import { BRING_UP_REFUSAL_MESSAGES, firstBringUpRefusal, } from "./conductor/bring-up-facts.js";
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 // BAPI-872: local plane-manifest binding, so `plane down` can later stop the
 // run this setup resolved WITHOUT guessing from repository-wide active-run
 // state. See `planeBinding` on `SetupEpicDeps` below.
 import { createPlaneFsDeps, createPlaneProcessDeps } from "./plane/defaults.js";
 import { bindPlaneManifestEpicRun, manifestHasLiveProcess, readPlaneManifest, } from "./plane/manifest.js";
+/**
+ * The one `policy_json.posture` value that means "unattended" (BAPI-1102).
+ *
+ * Mirrors the server's `api.models.epic_run.RUN_POSTURE_UNATTENDED`, which is a
+ * closed one-member vocabulary: the model refuses any other value and treats an
+ * omitted key as attended. Written out here rather than derived, because the
+ * client cannot import a Python constant; a unit test pins the two together.
+ */
+export const SETUP_EPIC_UNATTENDED_POSTURE = "unattended";
+/**
+ * The server's stable error code for an unattended-posture refusal (BAPI-734).
+ *
+ * Mirrors `api.library.epic_conductor.unattended_posture.UNATTENDED_POSTURE_REFUSED_CODE`.
+ * Matched by EQUALITY on the structured `error_code`, never by searching the
+ * message text: the message is prose that may be rewritten, the code is the
+ * contract.
+ */
+export const SETUP_EPIC_UNATTENDED_POSTURE_REFUSED_CODE = "UNATTENDED_POSTURE_REFUSED";
+/**
+ * The `policy_json` key authorizing automatic merge dispatch (BAPI-722).
+ *
+ * Composed into the unattended default alongside the posture. The two are not
+ * redundant: `posture` selects the unattended predicate set and the escalation
+ * discipline, `v2_auto_merge_enabled` is what actually authorizes the reconciler
+ * to dispatch a merge. A run with the posture and without the flag is a valid,
+ * fully supported configuration — it simply parks at every merge for a human,
+ * which is what the observed BAPI-1085 run did.
+ */
+export const SETUP_EPIC_AUTO_MERGE_POLICY_KEY = "v2_auto_merge_enabled";
 /** Accepted `policy_json.review_policy.source` values (the `ReviewPolicy` surface). */
 export const SETUP_EPIC_REVIEW_POLICY_SOURCES = [
     "verdict_protocol",
@@ -138,6 +168,19 @@ export function getSetupEpicUsage() {
         "integration PR targets the repository base branch. A single-node plan keeps the",
         "repository base branch, matching plain start-tickets semantics.",
         "",
+        "Posture (default): a run that selects an epic branch is created UNATTENDED —",
+        "posture: unattended and v2_auto_merge_enabled: true — and the server stamps its",
+        "CI gate at first approval from the repository default, or records an explicit",
+        "no-CI-gate mode when the repository declares none. Child PRs merge into the epic",
+        "branch; the INTEGRATION PR into the repository base branch stays human-gated.",
+        "Pass --attended to opt out. A run that selects no epic branch (--into-base, or a",
+        "single-node plan) is unchanged and composes no posture at all.",
+        "",
+        "Unattended runs have TWO one-time repository prerequisites, refused by name",
+        "before any run is created: repository consent (unattended_epic_implementer_allowed) and",
+        "a verified notify webhook default. `drive-epic` readiness lists both with their",
+        "current state.",
+        "",
         "Required:",
         "  --epic-key <KEY>       Jira epic key (e.g. BAPI-405)",
         "  --plan-file <path>     Path to epic-plan.dag.json (from decompose-epic)",
@@ -165,6 +208,13 @@ export function getSetupEpicUsage() {
         "                         (the pre-BAPI-1009 behavior). Use this if automation",
         "                         depended on \"no flag = direct to base\". Contradictory",
         "                         with --feature-branch; passing both is a parse error.",
+        "  --attended             OPT OUT of the unattended default: compose only",
+        "                         base_branch (plus --review-policy when supplied), with",
+        "                         no posture and no auto-merge authorization, and skip the",
+        "                         unattended repository prerequisites entirely. The create",
+        "                         request is byte-for-byte the pre-BAPI-1102 one.",
+        "                         Contradictory with a --policy-file that declares",
+        "                         posture: unattended; that pair is refused by name.",
         "  --review-policy <src>  PER-RUN review policy source, one of:",
         `                         ${SETUP_EPIC_REVIEW_POLICY_SOURCES.join(", ")}.`,
         "                         Composed into policy_json.review_policy on create.",
@@ -269,6 +319,7 @@ export function parseSetupEpicArgs(argv) {
     // fire on the INTENT, not on whether a name survived normalization.
     let featureBranchSupplied = false;
     let intoBase = false;
+    let attended = false;
     let reviewPolicy;
     let policyFile;
     let replacePolicy = false;
@@ -379,6 +430,14 @@ export function parseSetupEpicArgs(argv) {
             case "--into-base":
                 intoBase = true;
                 break;
+            // BAPI-1102. Valueless, like `--into-base` and `--replace-policy`. It is
+            // deliberately NOT contradictory with `--into-base`: a direct-to-main run
+            // composes no policy at all, so `--attended` is redundant there rather than
+            // conflicting, and refusing a redundant flag would be a worse experience
+            // than accepting it.
+            case "--attended":
+                attended = true;
+                break;
             case "--replace-policy":
                 replacePolicy = true;
                 break;
@@ -442,6 +501,7 @@ export function parseSetupEpicArgs(argv) {
             planVersion,
             featureBranch,
             intoBase,
+            attended,
             reviewPolicy,
             policyFile,
             replacePolicy,
@@ -523,6 +583,15 @@ export function composeSetupEpicPolicy(filePolicy, selections) {
     // contradiction purposes so a conflicting value is reported rather than
     // silently ignored, but never invent it and never rewrite it into snake_case:
     // the server's strict boundary should be the one to reject it.
+    //
+    // BAPI-1127: this paired read is CONTRADICTION DETECTION over a policy file
+    // the operator just handed in, at SETUP time, before any run exists — it is
+    // not run-branch resolution and must never become one. It asks "did the file
+    // name a branch under either spelling that disagrees with --feature-branch?",
+    // so it reads both keys for PRESENCE and deliberately picks no winner between
+    // them. `conductor/run-branch.ts#resolveDeclaredRunBaseBranch` is the single
+    // authority for resolving a PERSISTED run's declared branch; this is a
+    // documented exception to that, not a second implementation of it.
     const declaredBranches = [];
     for (const key of ["base_branch", "baseBranch"]) {
         if (key in composed && composed[key] !== undefined && composed[key] !== null) {
@@ -611,7 +680,30 @@ export function preflightSetupEpicPolicy(args) {
                 `branch declaration from the policy file, or drop --into-base.`,
         };
     }
-    // 2. Policy-source contradictions between the file and the CLI selections.
+    // 2. Posture contradiction (BAPI-1102). Placed SECOND — after the branch
+    //    strategy, before the composer's field-level conflicts — so one invocation
+    //    still yields exactly one named reason, deterministically. It belongs above
+    //    the composer because it is a whole-INTENT contradiction: an operator who
+    //    said "attended" and supplied a file that says "unattended" has not made a
+    //    field mistake, and reporting a downstream field conflict first would send
+    //    them to the wrong line of the file.
+    //
+    //    READ-ONLY, and the read is deliberately the narrowest possible: only
+    //    whether the file explicitly declares `posture: "unattended"`. Nothing is
+    //    normalized, no other key is inspected, and — like every message here — the
+    //    refusal interpolates the file PATH and fixed prose only, never a value
+    //    read out of the file.
+    if (args.attended === true && policyFileDeclaresUnattendedPosture(args.filePolicy)) {
+        return {
+            ok: false,
+            reason: "attended_with_policy_file_posture",
+            message: `--attended opts out of the unattended default, but --policy-file ` +
+                `'${args.policyFile}' declares posture: "unattended". setup-epic will not ` +
+                `pick a winner between them: drop --attended, or remove the posture ` +
+                `declaration from the policy file.`,
+        };
+    }
+    // 3. Policy-source contradictions between the file and the CLI selections.
     //    Delegated to the composer, which owns the "no silent winner" rule; the
     //    gate only gives the outcome a stable name.
     if (args.filePolicy === undefined)
@@ -625,6 +717,24 @@ export function preflightSetupEpicPolicy(args) {
     }
     return { ok: true, policy: composed.policy };
 }
+/**
+ * Does this policy file explicitly declare the UNATTENDED posture (BAPI-1102)?
+ *
+ * Strict by construction, and narrow on purpose. `true` only for a plain object
+ * whose `posture` is exactly the string `"unattended"` — the one spelling the
+ * server's `RUN_POSTURE_UNATTENDED` accepts. It never reads another key, never
+ * normalizes, and never returns the value it read, so the caller cannot leak a
+ * policy value into a refusal message even by accident.
+ *
+ * A file that declares no posture is not a contradiction: `--attended` is the
+ * opt-out from a DEFAULT, and a file that stays silent about posture leaves that
+ * default in play for `--attended` to decline.
+ */
+export function policyFileDeclaresUnattendedPosture(filePolicy) {
+    if (filePolicy === undefined || filePolicy === null)
+        return false;
+    return filePolicy.posture === SETUP_EPIC_UNATTENDED_POSTURE;
+}
 /**
  * Does this policy object explicitly supply the `notify.webhook_url` leaf?
  *
@@ -1005,6 +1115,258 @@ export function resolveFeatureBranchSelection(opts, planNodeCount, policyDeclare
         return undefined;
     return proposeFeatureBranchName(opts.epicKey);
 }
+/**
+ * Evaluate the unattended prerequisites against a readiness report.
+ *
+ * Pure and total: it takes an already-read report (or `null` for a failed read)
+ * and the COMPOSED policy the create request will carry, and returns at most ONE
+ * refusal, in a fixed order that matches the server's own cheapest-first
+ * sequence, so readiness, this gate, and the approval refusal all name the same
+ * first blocker.
+ *
+ * The policy is a parameter rather than something re-derived here because one
+ * prerequisite — the escalation channel — is satisfiable per RUN as well as per
+ * repository. A version of this gate that read only the repository report
+ * refused every unattended run, its own named remedy included.
+ *
+ * The reason CODES are the server's bounded vocabulary, spelled exactly as
+ * `api/library/epic_conductor/unattended_posture.py` spells them. The client adds
+ * remediation TEXT around them and invents no aliases — an alias would drift from
+ * the server's refusal the first time either side was edited, and an operator
+ * comparing a CLI message with an API response would have no way to tell they
+ * were the same refusal.
+ *
+ * `readiness_unreadable` is the one code with no server twin, and it is
+ * deliberately generic and secret-free: an unreadable or older-server report has
+ * PROVEN nothing, and fail-closed is the only safe direction for a check that
+ * authorizes unattended merging.
+ */
+/**
+ * Does this policy declare a notify webhook the server would probe?
+ *
+ * BAPI-1102. The shape check mirrors `_extract_webhook_url` in
+ * `api/library/epic_conductor/webhook_verification.py` exactly as far as
+ * PRESENCE goes — a `notify` object carrying a non-blank string `webhook_url` —
+ * and stops there on purpose. Scheme, host, and reachability are the server's to
+ * judge at activation, where the probe actually happens; re-deciding them here
+ * would mean a client that refused a URL the server accepts, or accepted one it
+ * refuses, the first time either side's rules were edited.
+ *
+ * `notify.local_sink` deliberately does NOT satisfy this, matching the server: a
+ * local sink has no destination to prove reachable, so it is not an escalation
+ * channel for a run nobody is watching.
+ */
+export function policyDeclaresNotifyWebhook(policy) {
+    if (policy === undefined || policy === null)
+        return false;
+    const notify = policy.notify;
+    if (typeof notify !== "object" || notify === null || Array.isArray(notify)) {
+        return false;
+    }
+    const url = notify.webhook_url;
+    return typeof url === "string" && url.trim() !== "";
+}
+export function evaluateSetupEpicUnattendedPrerequisites(readiness, requestedPolicy) {
+    const unattended = readiness?.unattended ?? null;
+    if (unattended === null) {
+        return {
+            reason: "readiness_unreadable",
+            message: "the Bridge API did not report this repository's unattended prerequisites, so " +
+                "they could not be confirmed. Retry once the server is reachable and running a " +
+                "build that reports them, or pass --attended to create an attended run. No run " +
+                "was created.",
+        };
+    }
+    if (!unattended.conductor_allowed) {
+        return {
+            reason: "target_not_allowed",
+            message: "this repository has not consented to unattended conductor runs. Set " +
+                "`unattended_epic_implementer_allowed` for it (see " +
+                "docs/claude/account-settings-operator-runbook.md), or pass --attended to " +
+                "create an attended run. No run was created.",
+        };
+    }
+    // Two independent sources satisfy the escalation channel, and the check has to
+    // consult BOTH or it refuses its own documented remedy. No column supplies a
+    // repository-level notify default today, so `notify_webhook_default_declared`
+    // is `false` for every repository; reading only that field made this branch
+    // refuse EVERY unattended run — including the `--policy-file` supplying
+    // `notify.webhook_url` that its own message names as the fix — and left
+    // `--attended` as the only reachable path. The run-level declaration is the
+    // supported form, so it is the one that has to be honoured here.
+    //
+    // Presence, not verification: the server probes the URL at activation and is
+    // the authority on whether it is reachable. This gate exists to spare the
+    // operator a created-and-refused run, not to duplicate the probe.
+    if (!unattended.notify_webhook_default_declared &&
+        !policyDeclaresNotifyWebhook(requestedPolicy)) {
+        return {
+            reason: "webhook_unverified",
+            message: "an unattended run must have a verified escalation channel, and neither this " +
+                "repository nor this run declares one. Supply a --policy-file declaring " +
+                "notify.webhook_url (notify.local_sink does not satisfy this), or pass " +
+                "--attended to create an attended run. No run was created.",
+        };
+    }
+    if (!unattended.repository_readiness_confirmed) {
+        return {
+            reason: "repository_readiness_unconfirmed",
+            message: "the unattended default authorizes automatic merge, which requires the review and " +
+                "conductor-CI workflows to be CONFIRMED on the default branch, and they are not. " +
+                "Run `install-bridge conductor` to install them, or pass --attended to create an " +
+                "attended run. No run was created.",
+        };
+    }
+    return null;
+}
+/** The closing sentence every pre-create refusal ends with. */
+const NO_RUN_WAS_CREATED = "No run was created.";
+/**
+ * Evaluate the bring-up facts against a readiness report.
+ *
+ * Pure and total: `null` is a readiness read that failed, which has proven
+ * nothing and refuses as `readiness_unreadable`. Otherwise at most ONE refusal,
+ * in the fixed {@link BRING_UP_REFUSAL_REASONS} order — each fact's
+ * "unreadable" before its "bad", so an operator is never told to repair a
+ * condition that could not be read.
+ */
+export function evaluateSetupEpicBringUpPrerequisites(readiness) {
+    if (readiness === null) {
+        return {
+            reason: "readiness_unreadable",
+            message: "the Bridge API conductor readiness report could not be read, so the database " +
+                "migration, worker presence, and single-reconciler facts could not be confirmed. " +
+                `Retry once the server is reachable. ${NO_RUN_WAS_CREATED}`,
+        };
+    }
+    const reason = firstBringUpRefusal(readiness.bring_up ?? null);
+    if (reason === null)
+        return null;
+    return { reason, message: `${BRING_UP_REFUSAL_MESSAGES[reason]} ${NO_RUN_WAS_CREATED}` };
+}
+/**
+ * Does the policy this invocation will actually send request unattended operation?
+ *
+ * Read off the COMPOSED policy — the same object the create request carries —
+ * rather than off the flags, so a `--policy-file` that declares
+ * `posture: "unattended"` is gated exactly as the default profile is. Reading the
+ * flags instead would let the file route around the prerequisites, which is the
+ * one thing this gate exists to prevent.
+ *
+ * `--attended` short-circuits before the read: it is the explicit opt-out, and
+ * the preflight gate above has already refused the one case where it contradicts
+ * a policy file.
+ */
+export function requestedPolicyIsUnattended(policy, attended) {
+    if (attended)
+        return false;
+    if (policy === undefined)
+        return false;
+    return policy.posture === SETUP_EPIC_UNATTENDED_POSTURE;
+}
+/**
+ * Compose the create-time `policy_json` for a run with NO `--policy-file`.
+ *
+ * BAPI-1102. Extracted from the create branch so the default profile has one
+ * definition and one place to read it, rather than an inline object literal that
+ * a later edit could silently widen.
+ *
+ * Three shapes, and the boundaries between them are the contract:
+ *
+ * * **No feature branch selected** → `{}`. `--into-base`, a single-node plan,
+ *   and the branch-silent path each keep the EXACT legacy create request shape:
+ *   the caller sends no `policy_json` key at all, byte-for-byte what it sent
+ *   before BAPI-1009 (AC-9). Adding a posture, an auto-merge authorization, an
+ *   empty policy object, or anything else here would break all three at once —
+ *   and, worse, would ask the server to admit an ungated auto-merge on a run
+ *   whose children merge straight into the repository base branch.
+ * * **Feature branch, `--attended`** → `base_branch` plus an explicitly
+ *   requested `review_policy`, and nothing else. Byte-identical to the
+ *   pre-BAPI-1102 composition, which is precisely what the opt-out promises.
+ * * **Feature branch, default** → adds `posture: "unattended"` and
+ *   `v2_auto_merge_enabled: true`.
+ *
+ * Deliberately absent from every shape:
+ *
+ * * **`caps`.** Absent and JSON `null` both mean "the system default applies"
+ *   (`unattended_posture.py`), so composing a caps object here would replace a
+ *   server-owned ceiling table with a client-authored one.
+ * * **`required_checks` / `no_ci_gate`.** The client has no business encoding a
+ *   repository's check names, and a repository default may change between run
+ *   creation and approval. First approval resolves the CI gate server-side from
+ *   the repository default, or records the explicit no-gate mode — and the stamp
+ *   is fill-if-ABSENT, so anything composed here would suppress it.
+ * * **`notify`.** The escalation channel is a repository prerequisite, refused by
+ *   name before creation; inventing one here would fake a verified channel.
+ */
+export function composeDefaultSetupEpicPolicy(args) {
+    const policy = {};
+    if (args.featureBranch !== undefined) {
+        policy.base_branch = args.featureBranch;
+        if (!args.attended) {
+            policy.posture = SETUP_EPIC_UNATTENDED_POSTURE;
+            policy[SETUP_EPIC_AUTO_MERGE_POLICY_KEY] = true;
+        }
+    }
+    if (args.reviewPolicy !== undefined) {
+        policy.review_policy = { source: args.reviewPolicy };
+    }
+    return policy;
+}
+/**
+ * Apply the unattended default to a policy a `--policy-file` supplied (BAPI-1102).
+ *
+ * `composeDefaultSetupEpicPolicy` covers the NO-FILE path. This covers the other
+ * one, and without it the default was unreachable by any documented invocation:
+ * a file bypasses that composer entirely, so a file declaring only
+ * `notify.webhook_url` — the exact remedy the `webhook_unverified` refusal, the
+ * readiness remediation, and the record all name — produced a policy with no
+ * `posture`, was never gated, and created an ATTENDED run with no auto-merge
+ * that then parked `v2_merge_approval_required` at every merge. Silently. The
+ * only working unattended invocation was a hand-written file carrying `posture`,
+ * `v2_auto_merge_enabled` and the webhook together, which nothing documents.
+ *
+ * `policyFileDeclaresUnattendedPosture` already states the intended contract in
+ * its own docstring — "a file that stays silent about posture leaves that
+ * default in play for `--attended` to decline" — and this is the code that makes
+ * that true.
+ *
+ * FILL-IF-ABSENT, on the strictest reading of absent, and the boundaries are the
+ * contract:
+ *
+ * * **The file declared a `posture`** → untouched, whatever it says. A file that
+ *   answered the question owns the answer; that is what `--policy-file` means,
+ *   and the one case where it contradicts `--attended` is already a named
+ *   refusal upstream (`attended_with_policy_file_posture`).
+ * * **`--attended`** → untouched. It is the explicit opt-out from a default, and
+ *   this is the default it opts out of.
+ * * **No feature branch** → untouched. Identical to the no-file composer's own
+ *   boundary: a run whose children merge straight into the repository base
+ *   branch must never be handed a posture and an auto-merge authorization.
+ * * **`v2_auto_merge_enabled` already present** → left exactly as the file set
+ *   it, including `false`. Filling the posture does not overwrite an explicit
+ *   merge decision.
+ *
+ * Pure: it returns a new object and never mutates the input. It is applied on the
+ * CREATE path only. A reused live run reconciles the file against its STORED
+ * policy, and adding a posture there would let `--replace-policy` newly authorize
+ * auto-merge on a run that never had it — the AC-3 guarantee this ticket's gate
+ * placement already rests on.
+ */
+export function applySetupEpicUnattendedDefault(policy, args) {
+    if (args.attended)
+        return policy;
+    if (args.featureBranch === undefined)
+        return policy;
+    if ("posture" in policy)
+        return policy;
+    const composed = { ...policy };
+    composed.posture = SETUP_EPIC_UNATTENDED_POSTURE;
+    if (!(SETUP_EPIC_AUTO_MERGE_POLICY_KEY in composed)) {
+        composed[SETUP_EPIC_AUTO_MERGE_POLICY_KEY] = true;
+    }
+    return composed;
+}
 /**
  * One line naming the selected branch strategy AND why it was selected.
  *
@@ -1013,14 +1375,30 @@ export function resolveFeatureBranchSelection(opts, planNodeCount, policyDeclare
  * their policy file asked for it, or the multi-node default derived it — those
  * three have different recovery steps when the name is not the one they wanted.
  */
-function describeBranchStrategy(opts, featureBranch, policyDeclaresBranch) {
+function describeBranchStrategy(opts, featureBranch, policyDeclaresBranch, 
+/**
+ * BAPI-1102 — `false` when a `--policy-file` owns the whole policy. The posture
+ * suffix describes what THIS COMMAND composes, so claiming a posture over a
+ * policy the file supplied would be a statement setup-epic cannot make: the
+ * file may declare any posture, or none, and this function never reads it.
+ */
+composesDefaultPolicy = true) {
     const cutNote = "cut on origin with local git at the canonical indexed commit; " +
         "validated server-side at approval";
+    // BAPI-1102: the posture is stated ALONGSIDE the branch, on the same line, and
+    // only for the paths where this command actually chooses it. An operator
+    // reading `epic/BAPI-1102` needs to know whether the run will drive itself.
+    const posture = !composesDefaultPolicy
+        ? ""
+        : opts.attended
+            ? "; ATTENDED posture (--attended): no auto-merge authorization"
+            : "; UNATTENDED posture with auto-merge into the epic branch " +
+                "(the integration PR stays human-gated) — pass --attended to opt out";
     if (featureBranch !== undefined) {
         if (opts.featureBranch !== undefined) {
-            return `${featureBranch} (explicit --feature-branch override; ${cutNote})`;
+            return `${featureBranch} (explicit --feature-branch override; ${cutNote}${posture})`;
         }
-        return `${featureBranch} (derived epic branch for this multi-ticket plan; ${cutNote})`;
+        return `${featureBranch} (derived epic branch for this multi-ticket plan; ${cutNote}${posture})`;
     }
     if (opts.intoBase) {
         return "repository base branch — epic branch disabled by --into-base; every child PR targets base";
@@ -1152,6 +1530,17 @@ export const SETUP_EPIC_PARSE_FIRST_MESSAGE = "parse the repository first";
  * `baseBranch` slip) is deliberately NOT interpreted here: the server's strict
  * `RunPolicy` validation owns rejecting it, so this returns `undefined` and the
  * request proceeds to that 422 unchanged.
+ *
+ * BAPI-1127: SNAKE-CASE ONLY, on purpose, and a documented exception to the
+ * "one persisted-run resolver" rule rather than a violation of it. The input
+ * here is a REQUESTED policy document the operator is about to submit — not a
+ * persisted run — so the right answer to the camelCase slip is to leave it
+ * alone and let the server's strict boundary refuse it with a 422 the operator
+ * can act on. Honoring the alias here would quietly repair a file the server is
+ * about to reject, and the operator would never learn their file was wrong.
+ * The canonical precedence for a PERSISTED run's declared branch lives in
+ * `conductor/run-branch.ts#resolveDeclaredRunBaseBranch`; this function is not
+ * it and must not grow into it.
  */
 export function resolveEffectiveFeatureBranch(featureBranch, requestedPolicy) {
     if (featureBranch !== undefined)
@@ -1256,13 +1645,13 @@ function scopeFailureGuidance(reason, featureBranch, epicRunId) {
     if (reason === "canonical_index_advanced") {
         return (`${SETUP_EPIC_SCOPE_REDRIVE_RECOVERY} The canonical index advanced before the ` +
             `scope could be seeded: delete origin/${featureBranch}, abandon this run ` +
-            `(conductor abandon-run --epic-run-id ${epicRunId}), and re-run setup-epic.`);
+            `(epic-implementer abandon-run --epic-run-id ${epicRunId}), and re-run setup-epic.`);
     }
     if (reason === "head_mismatch") {
         return (`${SETUP_EPIC_SCOPE_REDRIVE_RECOVERY} origin/${featureBranch} does not sit at the ` +
             `commit this scope was cut at, and setup-epic never force-updates an existing ` +
             `ref: delete origin/${featureBranch}, abandon this run ` +
-            `(conductor abandon-run --epic-run-id ${epicRunId}), and re-run setup-epic.`);
+            `(epic-implementer abandon-run --epic-run-id ${epicRunId}), and re-run setup-epic.`);
     }
     return `Recovery: ${SETUP_EPIC_SCOPE_RECOVERY_COMMAND}.`;
 }
@@ -1292,7 +1681,29 @@ function describeScopeTransition(state, status) {
     }
     return `Scope:      ${label}…`;
 }
+/**
+ * Run the whole `setup-epic` workflow and return its authoritative result.
+ *
+ * The internal entry point composed callers use. Behaviorally identical to
+ * {@link runSetupEpicCli} in every observable way — same output, same refusals,
+ * same exit codes — and differs only in what it hands back.
+ */
+export async function runSetupEpicWorkflow(argv, overrides = {}) {
+    const sink = {};
+    const exitCode = await executeSetupEpic(argv, overrides, sink);
+    return {
+        exitCode,
+        ...(sink.epicRunId !== undefined ? { epicRunId: sink.epicRunId } : {}),
+    };
+}
+/**
+ * The PUBLIC `setup-epic` entry point. Returns the process exit code and nothing
+ * else, exactly as it always has.
+ */
 export async function runSetupEpicCli(argv, overrides = {}) {
+    return (await runSetupEpicWorkflow(argv, overrides)).exitCode;
+}
+async function executeSetupEpic(argv, overrides, runIdSink) {
     const deps = { ...createDefaultSetupEpicDeps(), ...overrides };
     const parsed = parseSetupEpicArgs(argv);
     if (parsed.status === "help") {
@@ -1361,7 +1772,12 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     // network and asks no question, so running it here is what makes `--local-only`
     // and an ordinary invocation report the same strategy for the same plan.
     const featureBranch = resolveFeatureBranchSelection(opts, plan.nodes.length, policyDeclaresBranch);
-    const branchStrategyLine = describeBranchStrategy(opts, featureBranch, policyDeclaresBranch);
+    const branchStrategyLine = describeBranchStrategy(opts, featureBranch, policyDeclaresBranch, 
+    // `filePolicy` is set exactly when `--policy-file` was supplied, and a
+    // supplied file supersedes composition entirely — so this is the same
+    // predicate as "this command composes the policy", available here, several
+    // statements before the gate resolves `requestedPolicy`.
+    filePolicy === undefined);
     // --- Consolidated policy preflight (BAPI-1054) ---------------------------
     // ONE gate, run BEFORE credential resolution and before any request, over the
     // whole flag-backed choice-set. It sits above the `--local-only` return
@@ -1374,6 +1790,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     // still the better error for everything inside the policy file.
     const policyGate = preflightSetupEpicPolicy({
         intoBase: opts.intoBase,
+        attended: opts.attended,
         policyFile: opts.policyFile,
         filePolicy,
         policyDeclaresBranch,
@@ -1451,14 +1868,42 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     // that passed the gate — not a second composition — so the payload the create
     // request carries is exactly what was validated.
     const requestedPolicy = policyGate.policy;
-    if (requestedPolicy !== undefined) {
-        say(`Policy:     ${opts.policyFile} (complete run policy, applied at creation)`);
-    }
     // --- Effective feature branch (BAPI-850) ----------------------------------
     // Derived AFTER policy composition so a branch the policy file declares under
     // `base_branch` is honored exactly as `--feature-branch` would be. A malformed
     // or unknown policy field is left for the server's strict validation.
     const effectiveFeatureBranch = resolveEffectiveFeatureBranch(featureBranch, requestedPolicy);
+    // --- The policy the CREATE path will send (BAPI-1102) ---------------------
+    // Composed HERE, as soon as both of its inputs exist, so the one object that
+    // gets reported, gated, and sent is the same object throughout. It is consumed
+    // only on the create branch below; the reuse branch reconciles the RAW file
+    // against the run's stored policy, because adding a posture there would let
+    // `--replace-policy` newly authorize auto-merge on a run that never had it.
+    const composedForCreate = requestedPolicy !== undefined
+        ? applySetupEpicUnattendedDefault(requestedPolicy, {
+            featureBranch: effectiveFeatureBranch,
+            attended: opts.attended,
+        })
+        : composeDefaultSetupEpicPolicy({
+            featureBranch,
+            attended: opts.attended,
+            reviewPolicy: opts.reviewPolicy,
+        });
+    if (requestedPolicy !== undefined) {
+        // The posture is stated for the FILE path too, and read off the composed
+        // object rather than re-derived. The `--policy-file` invocation is the one
+        // the `webhook_unverified` remedy steers operators toward, so it was the one
+        // path that could create an auto-merging run without ever printing that it
+        // had — the exact thing this line exists to prevent. "Complete run policy"
+        // is likewise no longer said when this command added the posture to it.
+        const inherited = composedForCreate !== requestedPolicy
+            ? "; UNATTENDED posture with auto-merge into the epic branch composed by " +
+                "default over a posture-silent file (the integration PR stays " +
+                "human-gated) — pass --attended to opt out"
+            : "";
+        const shape = inherited === "" ? "complete run policy" : "run policy";
+        say(`Policy:     ${opts.policyFile} (${shape}, applied at creation${inherited})`);
+    }
     if (effectiveFeatureBranch !== undefined && featureBranch === undefined) {
         say(`Feature:    ${effectiveFeatureBranch} (from the policy file; cut on origin with local ` +
             `git at the canonical indexed commit; validated server-side at approval)`);
@@ -1505,7 +1950,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         else if (err instanceof ConductorBridgeApiError && err.status === 409) {
             deps.errorLog(`Epic ${opts.epicKey} has MULTIPLE active runs — it is wedged, and every ` +
                 `plan call will keep failing. Abandon the duplicate before retrying:\n` +
-                `  conductor abandon-run --epic-run-id <duplicate_epic_run_id>\n` +
+                `  epic-implementer abandon-run --epic-run-id <duplicate_epic_run_id>\n` +
                 `Detail: ${errorDetail(err)}`);
             return 1;
         }
@@ -1563,7 +2008,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 `'${existingBaseBranch}', not the repository base '${repositoryBase}', and ` +
                 `--into-base asks for the repository base branch. setup-epic will not retarget ` +
                 `an existing run. Re-run without --into-base to reuse it unchanged, or abandon ` +
-                `the run (conductor abandon-run --epic-run-id ${existingRunId}) and recreate ` +
+                `the run (epic-implementer abandon-run --epic-run-id ${existingRunId}) and recreate ` +
                 `it on base.`);
             return 1;
         }
@@ -1693,7 +2138,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 `keep failing. This is TERMINAL: it will not clear on retry, and it is ` +
                 `NOT a problem with your plan. Adopt the run you want to keep, or ` +
                 `abandon the duplicate:\n` +
-                `  conductor abandon-run --epic-run-id <duplicate_epic_run_id>\n` +
+                `  epic-implementer abandon-run --epic-run-id <duplicate_epic_run_id>\n` +
                 `No run was created and no automation-start charge occurred.\n` +
                 `Detail: ${errorDetail(err)}`);
             return 1;
@@ -1767,7 +2212,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     // used for status instead). A no-feature run performs none of this.
     //
     // The scope's BASE is the repository's configured base branch (the same
-    // resolution `conduct-epic init` uses), NOT `policy_json.base_branch` — that
+    // resolution `implement-epic init` uses), NOT `policy_json.base_branch` — that
     // key names the FEATURE branch. A feature branch equal to the configured base
     // needs no scope (dispatch already cuts from it) and matches the server's
     // long-standing no-op for that case.
@@ -1922,6 +2367,9 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         result.feature_branch = effectiveFeatureBranch;
     // --- Step 1: create (only when there is no live run) ---------------------
     if (existingRunId) {
+        // BAPI-1102 — the reuse path's authoritative id, taken from the pre-check's
+        // server response rather than from anything local.
+        runIdSink.epicRunId = existingRunId;
         say(`Run:        reusing ${existingRunId} (status: ${existingStatus})`);
         // A pre-check that already found a live run means create would answer 200
         // anyway; reconcile the file against that run's stored policy directly.
@@ -1941,6 +2389,58 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         }
     }
     else {
+        // --- BAPI-1102: the pre-create unattended prerequisite gate -------------
+        //
+        // Applied ONLY on the create path, and that placement is the AC-3 guarantee
+        // in code: a reused live run keeps its stored policy and its dispatch
+        // behavior untouched, so no deploy of this ticket can refuse or re-gate a
+        // run that is already going.
+        //
+        // Evaluated against the COMPOSED policy, so it covers the default profile and
+        // a `--policy-file` alike; the UNATTENDED evaluation is skipped for
+        // `--attended` and for any policy that is not unattended. (The readiness
+        // read itself is no longer skipped — see BAPI-1153 below.)
+        //
+        // The file branch runs through `applySetupEpicUnattendedDefault` rather than
+        // taking the file verbatim: a file bypasses the no-file composer entirely, so
+        // a posture-SILENT file used to skip this gate and create an attended run —
+        // which made the default profile unreachable by any documented invocation.
+        // The composed object is what gets gated AND what gets sent, so the create
+        // request carries exactly what was validated.
+        //
+        // BAPI-1153: ONE readiness read now serves both gates, and it happens for
+        // EVERY create — attended included — because the bring-up gate below applies
+        // to every run. Before any create request, manifest binding, or lane.
+        {
+            let readiness = null;
+            try {
+                readiness = await fetchConductorReadiness(access, deps.fetch);
+            }
+            catch {
+                // Fail CLOSED, and silently as to WHY: the thrown value can carry a URL
+                // or a response excerpt, and this refusal is rendered to a terminal. The
+                // generic `readiness_unreadable` message says what to do about it.
+                readiness = null;
+            }
+            // Bring-up first: a behind database or a missing worker makes the
+            // unattended questions moot, and refusing on the cheaper, universal fact
+            // keeps the first-named blocker the same for attended and unattended runs.
+            const bringUpRefusal = evaluateSetupEpicBringUpPrerequisites(readiness);
+            if (bringUpRefusal !== null) {
+                deps.errorLog(`setup-epic REFUSED (${bringUpRefusal.reason}): ${bringUpRefusal.message}`);
+                return 1;
+            }
+            if (requestedPolicyIsUnattended(composedForCreate, opts.attended)) {
+                // The COMPOSED policy, not the flags: a --policy-file declaring
+                // notify.webhook_url satisfies the escalation-channel prerequisite, and
+                // it is the same object the create request carries.
+                const refusal = evaluateSetupEpicUnattendedPrerequisites(readiness, composedForCreate);
+                if (refusal !== null) {
+                    deps.errorLog(`setup-epic REFUSED (${refusal.reason}): ${refusal.message}`);
+                    return 1;
+                }
+            }
+        }
         try {
             // Persist the confirmed feature branch as policy_json.base_branch ONLY when
             // one was selected; otherwise keep the exact legacy create request shape.
@@ -1951,23 +2451,27 @@ export async function runSetupEpicCli(argv, overrides = {}) {
             // BAPI-754: a --policy-file supersedes that ad-hoc composition entirely —
             // `requestedPolicy` IS the composed result, flags included — so the whole
             // policy reaches the server in the create that mints the run.
-            let policyJson;
-            if (requestedPolicy !== undefined) {
-                policyJson = requestedPolicy;
-            }
-            else {
-                policyJson = {};
-                if (featureBranch !== undefined)
-                    policyJson.base_branch = featureBranch;
-                if (opts.reviewPolicy !== undefined) {
-                    policyJson.review_policy = { source: opts.reviewPolicy };
-                }
-            }
+            //
+            // BAPI-1102: a run that SELECTS A FEATURE BRANCH is composed unattended by
+            // default, whether or not a policy file supplied the rest of the policy.
+            // The gating on a feature branch being selected is the whole safety of it,
+            // not an optimization — see `composeDefaultSetupEpicPolicy` and
+            // `applySetupEpicUnattendedDefault`.
+            //
+            // This is the OBJECT THE GATE ABOVE JUST VALIDATED, not a second
+            // composition of the same inputs. Recomposing here is how the two could
+            // drift: the gate would pass on one policy and the server would receive
+            // another.
+            const policyJson = composedForCreate;
             const createRequest = Object.keys(policyJson).length > 0 || requestedPolicy !== undefined
                 ? { epicKey: opts.epicKey, policyJson }
                 : { epicKey: opts.epicKey };
             const { run, created } = await createEpicRunWithDisposition(access, createRequest, deps.fetch);
             result.epic_run_id = run.epic_run_id;
+            // BAPI-1102 — the create path's authoritative id. `createEpicRunWithDisposition`
+            // returns the server's run for a fresh creation AND for a create-race
+            // adoption (`created: false`), so both are captured by this one assignment.
+            runIdSink.epicRunId = run.epic_run_id;
             result.status = run.status;
             result.run_created = created;
             if (created) {
@@ -1990,7 +2494,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 say(`Run:        adopting existing active run ${run.epic_run_id} (status: ${run.status})`);
                 say(`            No second run was created — one epic has at most one active ` +
                     `run. Continue on this one, or abandon it first with ` +
-                    `\`conductor abandon-run --epic-run-id ${run.epic_run_id}\` to start over.`);
+                    `\`epic-implementer abandon-run --epic-run-id ${run.epic_run_id}\` to start over.`);
                 if (requestedPolicy !== undefined) {
                     const outcome = await applyReusedRunPolicy({
                         access,
@@ -2056,7 +2560,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                     else {
                         const msg = `Could not bind the local plane to run ${result.epic_run_id} (${bound.message}). ` +
                             "A later `plane down` cannot be guaranteed to stop it automatically — if you need " +
-                            `to stop this run, run \`conductor stop-run --epic-run-id ${result.epic_run_id}\`.`;
+                            `to stop this run, run \`epic-implementer stop-run --epic-run-id ${result.epic_run_id}\`.`;
                         warnings.push(msg);
                         say(`Plane:      [warn] ${msg}`);
                     }
@@ -2076,7 +2580,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 const msg = `A local plane manifest exists but could not be validated (${manifestRead.error}), so ` +
                     `run ${result.epic_run_id} was NOT bound to it. If a plane is running, \`plane down\` ` +
                     "will not stop this run automatically — use " +
-                    `\`conductor stop-run --epic-run-id ${result.epic_run_id}\`. A manifest written by a ` +
+                    `\`epic-implementer stop-run --epic-run-id ${result.epic_run_id}\`. A manifest written by a ` +
                     "NEWER build must be wound down with that build's `plane down`.";
                 warnings.push(msg);
                 say(`Plane:      [warn] ${msg}`);
@@ -2087,7 +2591,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
             // an unexpected error here is reported as a warning, never thrown.
             const msg = `Could not check for a local plane to bind run ${result.epic_run_id} to (${errorDetail(err)}). ` +
                 "A later `plane down` cannot be guaranteed to stop it automatically — if you need to stop " +
-                `this run, run \`conductor stop-run --epic-run-id ${result.epic_run_id}\`.`;
+                `this run, run \`epic-implementer stop-run --epic-run-id ${result.epic_run_id}\`.`;
             warnings.push(msg);
             say(`Plane:      [warn] ${msg}`);
         }
@@ -2096,7 +2600,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     // AFTER the run exists and BEFORE the plan is stored/approved: the scope's run
     // association is immutable server-side, so the cut is driven with this run's
     // id and the scope is minted owned by it. Everything from `cut/begin` to the
-    // hold's release is the SHARED protocol `conduct-epic init` drives — local git
+    // hold's release is the SHARED protocol `implement-epic init` drives — local git
     // only, an exact-SHA create-only push, never the GitHub App, never a force
     // update. A failure leaves the run non-active (never discoverable by the
     // reconciler) and re-running setup-epic reuses it and re-drives the cut.
@@ -2203,6 +2707,25 @@ export async function runSetupEpicCli(argv, overrides = {}) {
                 `dispatch has NOT started. Correct repository access or the branch ` +
                 `configuration, then re-run setup-epic.\nDetail: ${errorDetail(err)}`);
         }
+        else if (err instanceof ConductorBridgeApiError &&
+            err.errorCode === SETUP_EPIC_UNATTENDED_POSTURE_REFUSED_CODE) {
+            // BAPI-1102 — the one approval refusal with a canonical, non-obvious
+            // remedy. Consent is read at BOTH boundaries, so a repository whose consent
+            // was revoked between creation and approval refuses HERE, with the run left
+            // exactly as it was: created, planning, unapproved, no activation, no
+            // executor dispatch, and reusable once consent is restored.
+            //
+            // Named separately from the generic approval failure because the generic
+            // message ("Failed to approve the plan: …") tells an operator to look at the
+            // plan, which is the wrong place entirely.
+            deps.errorLog(`The plan was NOT approved: this repository is no longer authorized for ` +
+                `unattended runs. The run WAS created and is left in 'planning' with no ` +
+                `activation and no executor dispatch — nothing was half-applied.\n` +
+                `Restore \`unattended_epic_implementer_allowed\` for this repository (see ` +
+                `docs/claude/account-settings-operator-runbook.md) and re-run setup-epic, ` +
+                `or deliberately convert this run to an attended posture through the ` +
+                `supported operator flow.\nDetail: ${errorDetail(err)}`);
+        }
         else {
             deps.errorLog(`Failed to approve the plan: ${errorDetail(err)}`);
         }
@@ -2369,8 +2892,14 @@ export async function runSetupEpicCli(argv, overrides = {}) {
         else {
             say("The server-side reconciler will pick it up within ~30s.");
         }
-        say("To execute claimed jobs on this machine, run:");
-        say(`  npx -y ${MCP_PACKAGE_NAME} executor --repo ${access.repoName}`);
+        // BAPI-1102 — the executor command is printed WITH a claim scope. Since
+        // BAPI-1026 an executor started with no scope REFUSES TO START, so the
+        // unscoped form printed here was guidance that could not work: an operator
+        // who copied it got a startup error, and the natural reading of that error is
+        // that the run is broken rather than that the instruction was.
+        say("To execute this run's claimed jobs on this machine, run:");
+        say(`  npx -y ${MCP_PACKAGE_NAME} executor --repo ${access.repoName} ` +
+            `--epic-run-id ${result.epic_run_id}`);
     }
     return exitCode;
 }