@bridge_gpt/mcp-server 0.2.52 → 0.2.54

package/build/setup-epic.js

@@ -78,7 +78,7 @@
 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
@@ -98,6 +98,35 @@ import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 // 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 +167,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_conductor_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 +207,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 +318,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 +429,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 +500,7 @@ export function parseSetupEpicArgs(argv) {
             planVersion,
             featureBranch,
             intoBase,
+            attended,
             reviewPolicy,
             policyFile,
             replacePolicy,
@@ -523,6 +582,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 +679,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 +716,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 +1114,233 @@ 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_conductor_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;
+}
+/**
+ * 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 +1349,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 +1504,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)
@@ -1292,7 +1655,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 +1746,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 +1764,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 +1842,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)`);
@@ -1922,6 +2341,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 +2363,46 @@ 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; skipped entirely for `--attended` and for any
+        // policy that is not unattended, which is what keeps an attended run from
+        // paying for a readiness read it does not need.
+        //
+        // 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.
+        {
+            if (requestedPolicyIsUnattended(composedForCreate, opts.attended)) {
+                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;
+                }
+                // 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 +2413,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) {
@@ -2203,6 +2669,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_conductor_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 +2854,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;
 }