@bridge_gpt/mcp-server 0.2.37 → 0.2.39

package/build/sfcc/write-grants.js

@@ -27,6 +27,38 @@ export const OCAPI_WRITE_RESOURCE_IDS = [
     "/custom_object_definitions/**",
     "/site_preferences/**",
 ];
+/**
+ * The exact HTTP methods each resource family needs, derived from the methods
+ * the nine shipped write handlers actually call (BAPI-817).
+ *
+ * Previously every family was granted `["get","put","patch","delete"]`. **No
+ * shipped handler performs a DELETE** — the write surface is create/update only
+ * (`ocapiPut`, `ocapiPatch`, `ocapiPatchDirect` in `client.ts`; verified across
+ * `writes-system-object.ts`, `writes-custom-object-def.ts`, and
+ * `writes-site-preference.ts`). Granting `delete` handed an operator's OCAPI
+ * client a destructive capability that Bridge cannot even invoke, on a grant
+ * they were told to paste once and forget. The narrower set below is what the
+ * code demonstrably needs and nothing more.
+ *
+ * `get` is retained where a write path genuinely reads: `ocapiPatch` performs a
+ * GET-then-If-Match ETag round trip before the PATCH, so removing `get` would
+ * break every update tool.
+ *
+ *   /system_object_definitions       get   — the check_permissions probe.
+ *   /system_object_definitions/**    put, patch (+get for ETag) — attribute and
+ *                                    attribute-group create/update, assignment,
+ *                                    custom preference create.
+ *   /custom_object_definitions/**    put, patch (+get for ETag) — attribute
+ *                                    definition create/update.
+ *   /site_preferences/**             patch (+get) — site_preference_values_set,
+ *                                    a direct PATCH with no ETag round trip.
+ */
+export const OCAPI_WRITE_RESOURCE_METHODS = {
+    "/system_object_definitions": ["get"],
+    "/system_object_definitions/**": ["get", "put", "patch"],
+    "/custom_object_definitions/**": ["get", "put", "patch"],
+    "/site_preferences/**": ["get", "patch"],
+};
 // ---------------------------------------------------------------------------
 // Grant JSON builders
 // ---------------------------------------------------------------------------
@@ -44,7 +76,7 @@ export function buildOcapiWriteGrantSettings(ocapiVersion, clientIdPlaceholder =
                 client_id: clientIdPlaceholder,
                 resources: OCAPI_WRITE_RESOURCE_IDS.map((resource_id) => ({
                     resource_id,
-                    methods: ["get", "put", "patch", "delete"],
+                    methods: [...(OCAPI_WRITE_RESOURCE_METHODS[resource_id] ?? [])],
                     read_attributes: "(**)",
                     write_attributes: "(**)",
                 })),

package/build/sfcc/write-guard.js

@@ -1,11 +1,36 @@
 /**
- * Reusable sandbox-only write guard (BAPI-582 foundation).
+ * Secondary OCAPI instance-CONTEXT check for writes (BAPI-582 foundation).
  *
- * Future SFCC write handlers MUST call `rejectIfNotSandboxForWrite`
- * immediately after input parsing and BEFORE any payload construction or OCAPI
- * mutation. A non-null return value is
- * the pre-formatted MCP rejection to return directly; a null return means the
- * effective instance is a sandbox and the handler may proceed.
+ * ⚠️ **This is NOT the sandbox security boundary.** It validates a
+ * caller-supplied *input string*, not the instance the request will reach. The
+ * hostname boundary lives in `tool-wrapper.ts`
+ * (`withSfccTargetBoundary` / `isApprovedSfccSandboxHost`), runs at
+ * registration level for all twenty SFCC tools, and validates the hostname
+ * credential resolution actually selected.
+ *
+ * The distinction is the entire subject of BAPI-817. This guard was previously
+ * described — in the README and in its own comments — as the thing that made
+ * SFCC writes sandbox-only. It never could be: `instance` is an argument the
+ * caller chooses, the target came from `dw.json`/`SFCC_HOSTNAME`, and the two
+ * were never compared. Worse, the guard **defaulted an omitted `instance` to
+ * `"sandbox"` and passed**, so it approved its single most common call shape
+ * while the request went to whatever host was configured. Nine destructive
+ * tools sat behind that.
+ *
+ * The behavior below is deliberately UNCHANGED, and is kept only as
+ * defence-in-depth on the OCAPI instance-context input: it rejects a caller who
+ * explicitly asks for `"staging"` or `"production"` context, which is still
+ * worth refusing. What changed is what it is allowed to *mean*. Its acceptance
+ * no longer authorizes anything — a write reaching this guard has already had
+ * its target hostname independently approved, and omitting `instance` cannot
+ * bypass that approval because the hostname check does not consult `instance`
+ * at all.
+ *
+ * SFCC write handlers still call `rejectIfNotSandboxForWrite` immediately after
+ * input parsing and BEFORE any payload construction or OCAPI mutation. A
+ * non-null return value is the pre-formatted MCP rejection to return directly;
+ * a null return means the effective instance context is `sandbox` and the
+ * handler may proceed.
  *
  * BAPI-766 moved the rejection's *representation* to the shared SFCC formatter
  * so the guardrail fails at the protocol level like every other SFCC failure.
@@ -17,13 +42,17 @@ import { formatSfccWriteFailure } from "./sfcc-result.js";
 // Guard
 // ---------------------------------------------------------------------------
 /**
- * Reject any write targeting a non-sandbox instance.
+ * Reject a write whose OCAPI instance CONTEXT is not `sandbox`.
+ *
+ * The effective context defaults to `"sandbox"` when `undefined` (some schemas
+ * default the value elsewhere), so an omitted instance is allowed here. That
+ * permissive default is safe only because it is no longer load-bearing: the
+ * resolved-hostname boundary has already approved the target before any handler
+ * runs, and it never consults this argument. Returning `null` therefore means
+ * "this input is not objectionable", never "this target is a sandbox".
  *
- * SFCC write tools are sandbox-only in this foundation. The effective instance
- * defaults to `"sandbox"` when `undefined` (some schemas default the value
- * elsewhere), so an omitted instance is allowed. Any other value returns the
- * unified validation failure naming the rejected instance; a sandbox returns
- * `null` so the caller proceeds.
+ * Any other value returns the unified validation failure naming the rejected
+ * context.
  *
  * `details` carries non-sensitive guard metadata only — the rejected value is
  * caller-supplied.

package/build/sfcc/write-result.js

@@ -6,15 +6,19 @@
  * their own 403/fault/success response logic, guaranteeing a consistent surface
  * across every write tool.
  *
- * Successful results are unchanged and never gain `isError`. Every *failure*
- * branch — including the 403 write-grant remediation, which used to be prose —
- * now returns the universal nested envelope from `sfcc-result.ts`, so
- * `result.isError === true` is total across a write tool's post-transport
- * failures as well as its pre-transport ones.
+ * Successful results never gain `isError`, but their echoed `body` is redacted
+ * (BAPI-769): an attribute-definition write's success body can carry the same
+ * `default_value` a read can, so it is withheld via `read-body.ts`'s
+ * `redactSfccBody` before serialization. Every other *failure* branch —
+ * including the 403 write-grant remediation, which used to be prose — returns
+ * the universal nested envelope from `sfcc-result.ts`, so `result.isError ===
+ * true` is total across a write tool's post-transport failures as well as its
+ * pre-transport ones.
  */
 import { writeGrantForbiddenResult } from "./write-grants.js";
 import { DEFAULT_OCAPI_VERSION } from "./config.js";
 import { formatSfccWriteFailure } from "./sfcc-result.js";
+import { redactSfccBody } from "./read-body.js";
 /** Wrap text in the standard MCP text-result shape (success path only). */
 function textResult(text) {
     return { content: [{ type: "text", text }] };
@@ -54,7 +58,12 @@ function ocapiWriteFaultMessage(body, status) {
  *
  *  - `403` → the unified failure carrying the paste-ready write-grant
  *    remediation as structured data (via write-grants.ts).
- *  - success → JSON with `status`, `outcome`, and `body`; no `isError`.
+ *  - success → JSON with `status`, `outcome`, and `body`; no `isError`. `body`
+ *    is redacted (BAPI-769) before serialization: a successful
+ *    attribute-definition PUT/PATCH echoes the updated resource in the same
+ *    shape a GET returns, so it can carry a real `default_value` exactly like a
+ *    read can — `redactSfccBody` withholds it here the same way `readSfccBody`
+ *    withholds it on the read path. Every other key survives untouched.
  *  - other failure → the unified `OCAPI_WRITE_ERROR` failure, source `ocapi`,
  *    with the structured fault mapping and the upstream body under
  *    `error.details`.
@@ -76,7 +85,7 @@ export function formatOcapiWriteToolResult(result, operation, path, ocapiVersion
         return textResult(JSON.stringify({
             status: result.status,
             outcome: result.outcome,
-            body: result.body,
+            body: redactSfccBody(result.body),
         }));
     }
     return formatSfccWriteFailure({

package/build/sfcc/writes-custom-object-def.js

@@ -8,7 +8,10 @@
  * Both tools write ATTRIBUTE DEFINITIONS on an already-known custom object type.
  * Custom object TYPE creation is intentionally NOT attempted: OCAPI cannot
  * create custom object types (that is a v2 metadata-import capability), so the
- * type must pre-exist. Mirrors reads-custom-object-def.ts.
+ * type must pre-exist. OCAPI also cannot enumerate custom object type IDs
+ * directly — see reads-custom-object-def.ts for the `system_object_list` +
+ * `projection: "full"` discovery path a caller can use to find one before
+ * writing to it. Mirrors reads-custom-object-def.ts.
  *
  * Every handler is call-time gated by `withSfccGate`, sandbox-guarded via
  * `rejectIfNotSandboxForWrite`, and routes its OCAPI result through
@@ -25,13 +28,18 @@ import { WRITE_ANNOTATIONS, encodedSegment, preTransportErrorEnvelope, unexpecte
 // ---------------------------------------------------------------------------
 // Input schemas
 // ---------------------------------------------------------------------------
-const INSTANCE_DESCRIBE = "OCAPI instance context. SFCC writes are sandbox-only; omit for sandbox. Any " +
-    "other value is rejected before OCAPI is called.";
+// OCAPI instance CONTEXT, not a target selector: the instance actually
+// contacted is decided by the resolved-hostname boundary (BAPI-817), which this
+// value cannot influence. "omit for sandbox" is gone because omitting it never
+// selected anything.
+const INSTANCE_DESCRIBE = "OCAPI instance context. Omit or pass \"sandbox\"; any other value is " +
+    "rejected before OCAPI is called.";
 const createCustomObjectAttributeDefinitionInput = z.object({
     object_type: z
         .string()
         .describe('Known custom object type identifier (must already exist). OCAPI cannot ' +
-        "enumerate or create custom object types — only attribute definitions on a known type."),
+        "create types, and cannot enumerate type IDs directly — only attribute " +
+        "definitions on a known type."),
     attribute_id: z
         .string()
         .describe("URL attribute-definition id. If the body also carries `id`, it must match."),

package/build/sfcc/writes-site-preference.js

@@ -28,8 +28,13 @@ import { WRITE_ANNOTATIONS, encodedSegment, preTransportErrorEnvelope, unexpecte
 // Mirror reads-site-preference.ts so callers see the same instance enum, while
 // the write remains sandbox-only (enforced by the guard + the literal path).
 const INSTANCE_ENUM = z.enum(["staging", "development", "sandbox", "production"]);
+// OCAPI instance CONTEXT only. The trailing "Defaults to 'sandbox'" is gone:
+// it read as though the default selected a safe target, when the target is
+// decided by the resolved-hostname boundary (BAPI-817) and this value cannot
+// influence it. The forced `/sandbox` path segment below remains as an extra
+// safeguard on the OCAPI route.
 const INSTANCE_DESCRIBE = "OCAPI instance context. v1 supports the 'sandbox' context only; any other " +
-    "value is rejected before OCAPI is called. Defaults to 'sandbox'.";
+    "value is rejected before OCAPI is called.";
 const sitePreferenceValuesSetInput = z.object({
     group: z.string().describe("Custom site preference group id, e.g. 'LLMIntegration'."),
     instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),

package/build/sfcc/writes-system-object.js

@@ -50,11 +50,20 @@ function preferenceObjectTypeForScope(scope) {
 // ---------------------------------------------------------------------------
 // Input schemas
 // ---------------------------------------------------------------------------
-/** Optional sandbox instance context. Writes are sandbox-only (see write-guard). */
+/**
+ * Optional OCAPI instance CONTEXT — not a target selector.
+ *
+ * The old description ("Sandbox-only: omit (defaults to sandbox) or pass
+ * \"sandbox\"") told the model that omitting this field selected a sandbox. It
+ * never did: the host came from `dw.json`/`SFCC_HOSTNAME`, and omitting the
+ * field only made `write-guard.ts` default to `"sandbox"` and pass. Which
+ * instance is actually contacted is decided by the resolved-hostname boundary in
+ * `tool-wrapper.ts` (BAPI-817), which this value cannot influence.
+ */
 const instanceSchema = z
     .string()
     .optional()
-    .describe("Sandbox-only: omit (defaults to sandbox) or pass \"sandbox\".");
+    .describe("OCAPI instance context. Omit or pass \"sandbox\".");
 const createAttributeDefinitionInput = z.object({
     object_type: z.string().describe("System object type, e.g. \"Product\"."),
     attribute_id: z.string().describe("Attribute id (URL id); the body id must match it."),

package/build/sfcc/writes.js

@@ -3,9 +3,10 @@
  * populated by BAPI-584).
  *
  * This is the registration seam that write-surface tickets register through.
- * `register.ts` wires this behind the existing `includeReadTools` SFCC gate, so
- * the write tools become default-on with the reads without touching
- * `register.ts` or `index.ts`.
+ * `register.ts` wires it behind its OWN `includeWriteTools` gate, driven by the
+ * `sfcc-write` profile group (BAPI-817). The nine tools here are destructive, so
+ * they are no longer default-on with the reads: enabling `sfcc` registers the
+ * read profile and nothing from this module.
  *
  * Each write handler follows the foundation recipe:
  *   1. Parse inputs.
@@ -25,7 +26,8 @@ import { registerSitePreferenceWriteTools, SITE_PREFERENCE_WRITE_TOOL_NAMES, } f
  * Write tool names registered by this seam (centralized inventory). Extended by
  * each write-surface ticket — BAPI-583 adds the six system-object write tools,
  * BAPI-584 adds the custom-object attribute-definition and site-preference value
- * write tools.
+ * write tools. These nine have SHIPPED; `registration-inventory.ts` reuses this
+ * array as the `sfcc-write` profile inventory rather than duplicating it.
  */
 export const SFCC_WRITE_TOOL_NAMES = [
     ...SYSTEM_OBJECT_WRITE_TOOL_NAMES,
@@ -47,14 +49,17 @@ export const SFCC_WRITE_TOOL_NAMES = [
  *   4. Call `ocapiPut` or `ocapiPatch` (client.ts) for transport.
  *   5. Route the result through `formatOcapiWriteToolResult` (write-result.ts).
  *
- * Each handler is additionally call-time gated by `withSfccGate` and
- * sandbox-guarded, so registering them here (default-on with the reads) does
- * not weaken the per-call safety model.
+ * Every handler registered here crosses three checks before it can mutate
+ * anything: the resolved-hostname sandbox boundary (registration-level,
+ * `tool-wrapper.ts`), the call-time `withSfccGate` version check, and the
+ * secondary instance-context guard in `write-guard.ts`. Only the first of those
+ * decides which instance is contacted.
  *
  * BAPI-583 registers the system-object write surface here; BAPI-584 adds the
  * custom-object attribute-definition and site-preference value write surfaces
  * alongside it. Later write-surface tickets add their modules the same way,
- * without touching `register.ts`/`index.ts`.
+ * without touching `register.ts`/`index.ts` — a new tool added here is
+ * automatically inside the `sfcc-write` group and inside the target boundary.
  */
 export function registerSfccWriteTools(registerTool, deps) {
     // System-object attribute/group definition writes (BAPI-583).

package/build/start-tickets-prereqs.js

@@ -18,7 +18,7 @@ import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./creden
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
 import { probeWorktreeCommandAssets } from "./command-assets-doctor.js";
-import { CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV, formatClaudeMcpShadowFinding, formatClaudeUserConfigDiagnostic, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "./claude-user-config-doctor.js";
+import { CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND, formatClaudeMcpShadowFinding, formatClaudeUserConfigDiagnostic, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "./claude-user-config-doctor.js";
 // ---------------------------------------------------------------------------
 // Constants (moved here from start-tickets.ts so both consumers share them)
 // ---------------------------------------------------------------------------
@@ -531,12 +531,11 @@ export async function resolveMainWorktreePathForDoctor(deps) {
  * which is why the advice below is phrased as "delete, or move aside". Keep every
  * such identifier out of this file, even inside a comment like this one.
  */
-const CLAUDE_MCP_SHADOWING_HINT = "Delete, or move aside, the 'bridge-api' MCP registration in ~/.claude.json (at user scope, " +
-    "or under the projects entry for this repository/worktree) so the registration the " +
-    "conductor provisions into each worker worktree is the one that takes effect. If the " +
-    "collision is deliberate, set " +
-    `${CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV}=1 to override the executor's refusal ` +
-    "(doctor still reports it).";
+const CLAUDE_MCP_SHADOWING_HINT = `Run \`${CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND}\` to clear the 'bridge-api' MCP ` +
+    "registration in ~/.claude.json (use the matching scope if it is registered at user scope, " +
+    "or under the projects entry for this repository/worktree). This is ADVISORY: workers load " +
+    "MCP servers with --strict-mcp-config from their own worktree registration, so this entry " +
+    "does not reach a worker and does not block a conductor run.";
 const CLAUDE_MCP_SHADOWING_INSTALL_HINTS = {
     darwin: CLAUDE_MCP_SHADOWING_HINT,
     linux: CLAUDE_MCP_SHADOWING_HINT,
@@ -547,17 +546,25 @@ const CLAUDE_MCP_SHADOWING_INSTALL_HINTS = {
  * configuration register a `bridge-api` MCP server that could shadow a worker's
  * provisioned registration?
  *
+ * ADVISORY SINCE BAPI-790. Every outcome reports `found: true`, so this never
+ * fails the prerequisite section or the exit code; a confirmed collision is
+ * surfaced through the DETAIL, which names the scope and carries the exact
+ * remediation command. The downgrade is not a softening of the diagnostic — it
+ * reflects that strict flag-scoped worker MCP loading means the collision can no
+ * longer reach a worker (inventory Finding 6), so reporting it as a broken
+ * prerequisite would tell an operator to fix something that is not breaking
+ * anything.
+ *
  * Status mapping:
  *   - no registration, or only acceptable provisioned shims → `found: true`
- *   - a CONFIRMED foreign registration                      → `found: false`
+ *   - a CONFIRMED foreign registration                      → `found: true` + advisory detail
  *   - unreadable / malformed config, or an unresolved main
  *     worktree path                                          → `found: true` + detail
  *
- * The failing case is deliberately independent of
- * `BAPI_CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING`: the override changes what the
- * EXECUTOR does at runtime, not whether the collision exists. A diagnostic that
- * went quiet because an override happened to be exported would hide the exact
- * condition an operator ran doctor to find.
+ * Reporting stays deliberately independent of the retired
+ * `BAPI_CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING` override: whether that variable is
+ * exported has never had any bearing on whether the collision exists, and now it
+ * has no bearing on anything at all.
  */
 export function claudeMcpShadowingDescriptor() {
     return {
@@ -589,8 +596,11 @@ export function claudeMcpShadowingDescriptor() {
                 degraded.push("the main worktree path could not be resolved; only user and current-worktree scopes were checked");
             }
             if (inspection.findings.length > 0) {
-                const findings = inspection.findings.map(formatClaudeMcpShadowFinding);
-                return { found: false, detail: [...findings, ...degraded].join("; ") };
+                // Advisory (BAPI-790): reported in full, with the remediation command,
+                // but `found: true` so it never fails the prerequisite or the exit code.
+                const findings = inspection.findings.map((finding) => `advisory: ${formatClaudeMcpShadowFinding(finding)} — not loaded by a worker under ` +
+                    `strict MCP loading; clear it with \`${CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND}\``);
+                return { found: true, detail: [...findings, ...degraded].join("; ") };
             }
             return {
                 found: true,

package/build/start-tickets.js

@@ -59,6 +59,10 @@ import os from "node:os";
 import path from "path";
 import { VERSION } from "./version.generated.js";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
+// BAPI-814/E1b: the read-only index-branch override probe. `getIndexBranch` is
+// reused from the conduct-epic client rather than re-wrapped, so both conductor
+// paths read the one repository-wide override through the same client.
+import { getIndexBranch } from "./conduct-epic/bridge-client.js";
 import { resolveStartTicketsRepoName as resolveSharedStartTicketsRepoName, resolveRequiredStartTicketsRepoName, } from "./start-tickets-repo.js";
 import { provisionMcpRegistrationsForCreatedWorktrees, } from "./mcp-provisioning.js";
 import { provisionCommandsForCreatedWorktrees, } from "./command-provisioning.js";
@@ -173,6 +177,7 @@ export function parseStartTicketsArgs(argv) {
     let maxParallelRaw;
     let agentName = DEFAULT_AGENT_NAME;
     let baseBranch = "main";
+    let baseBranchExplicit = false;
     let conductorEnabled = false;
     let workflow = "implement";
     let reviewRoundsRaw;
@@ -342,6 +347,7 @@ export function parseStartTicketsArgs(argv) {
                 return { status: "error", message: `Invalid --base-branch value: ${error}` };
             }
             baseBranch = trimmed;
+            baseBranchExplicit = true;
             continue;
         }
         if (arg === "--dry-run") {
@@ -449,6 +455,7 @@ export function parseStartTicketsArgs(argv) {
             branchOverrides,
             agentName,
             baseBranch,
+            ...(baseBranchExplicit ? { baseBranchExplicit: true } : {}),
             conductorEnabled,
             workflow,
             reviewRounds,
@@ -506,16 +513,19 @@ export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = fal
 // instruction to the resume-mode worker's prompt.
 resumeMode = false, workflow = "implement", reviewRounds, 
 // BAPI-586: the effective run base branch (incl. epic.base_branch override).
-// Injected as BAPI_BASE_BRANCH for conductor workers so their PR targets it,
-// and threaded (BAPI-593) into the spawned workflow command.
+// Injected as BAPI_BASE_BRANCH so the spawned worker's PR targets it — for
+// conductor runs always, and (BAPI-801) for plain runs whose base is a
+// non-default branch — and threaded (BAPI-593) into the spawned workflow command.
 baseBranch) {
     if (!isSupportedStartTicketsPlatform(deps.platform)) {
         return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
     }
     const platform = deps.platform;
-    // Only conductor dispatch uses the PR-base contract; interactive dispatch omits
-    // the BAPI_BASE_BRANCH assignment so its worker launch is unchanged.
-    const prBaseBranch = conductorEnabled ? baseBranch : null;
+    // BAPI-801: both conductor and plain dispatch carry the PR-base ENVIRONMENT
+    // contract (see resolvePrBaseBranchEnvValue). Only the conductor launch
+    // INSTRUCTION remains conductor-only — a plain worker's prompt stays bare and
+    // learns the base from the env plus the create-PR instruction files.
+    const prBaseBranch = resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch);
     return {
         ok: true,
         config: {
@@ -523,7 +533,8 @@ baseBranch) {
             worktrunkBinary: resolveWorktrunkBinary(platform, deps.env),
             // Inject the resolved repo identity so the spawned worktree session never
             // falls back to the basename-derived repo name (the 403 root cause), and
-            // (BAPI-586) the run base so the conductor worker opens its PR against it.
+            // (BAPI-586/BAPI-801) the run base so the spawned worker opens its PR
+            // against it. The base assignment stays outermost.
             buildAgentShellCommand: (key, worktreePath, modelAlias) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch), repoName, platform), prBaseBranch, platform),
             spawnTerminalTab: deps.spawnTerminalTab,
         },
@@ -555,14 +566,40 @@ export function prependRepoNameEnvAssignment(command, repoName, platform = "darw
     return `export BAPI_REPO_NAME='${shSquoteInner(repoName)}' && ${command}`;
 }
 /**
- * BAPI-586: prepend a `BAPI_BASE_BRANCH` environment assignment to a spawned
- * conductor worker's shell command so the worker can open its PR against the run
- * base via `gh pr create --base "$BAPI_BASE_BRANCH"` (paired with the PR-base
- * launch instruction), instead of inferring the repo default branch. Platform
- * correct — `$env:VAR = '…'; …` on PowerShell, `export VAR='…' && …` on POSIX —
- * with the value quoted by the same escaper used for the rest of the command.
- * Fail-open: a null/empty `baseBranch` returns the command unchanged (interactive
- * dispatch does not use the PR-base contract).
+ * BAPI-801: decide the `BAPI_BASE_BRANCH` value a spawned worker's shell should
+ * carry — the single rule shared by the real spawn builder
+ * ({@link resolveStartTicketsPlatformConfig}) and the dry-run preview builder
+ * ({@link getDryRunPlatformDetails}), so the preview can never drift from what
+ * is actually spawned.
+ *
+ * - Conductor runs export whatever base was resolved, `main` included — BAPI-586
+ *   behavior, unchanged.
+ * - Plain runs export only a non-empty base other than the CLI default `main`.
+ *   This mirrors the `--base-branch` threading rule in {@link buildAgentPrompt},
+ *   keeps today's plain spawn strings byte-stable on the default base, and costs
+ *   nothing: the create-PR fallback tier is `main` anyway.
+ *
+ * Returns `null` when nothing should be exported;
+ * {@link prependBaseBranchEnvAssignment} is fail-open on that value.
+ */
+function resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch) {
+    if (conductorEnabled)
+        return baseBranch ?? null;
+    if (!baseBranch || baseBranch === "main")
+        return null;
+    return baseBranch;
+}
+/**
+ * BAPI-586/BAPI-801: prepend a `BAPI_BASE_BRANCH` environment assignment to a
+ * spawned worker's shell command so the worker opens its PR against the run base
+ * instead of inferring the repo default branch. Conductor workers additionally
+ * receive the paired launch instruction; plain workers (BAPI-801) carry the same
+ * env and learn the contract from the create-PR instruction files, which resolve
+ * `$BAPI_BASE_BRANCH` first. Platform correct — `$env:VAR = '…'; …` on
+ * PowerShell, `export VAR='…' && …` on POSIX — with the value quoted by the same
+ * escaper used for the rest of the command. Fail-open: a null/empty `baseBranch`
+ * returns the command unchanged (the caller's rule already decided not to
+ * export — see {@link resolvePrBaseBranchEnvValue}).
  */
 export function prependBaseBranchEnvAssignment(command, baseBranch, platform = "darwin") {
     if (!baseBranch)
@@ -1061,6 +1098,9 @@ export function buildAgentPrompt(key, opts = {}) {
         parts.push(buildConductorMessageRelayLaunchInstruction());
         // BAPI-586: conductor implementation workers must open their PR against the
         // run base (injected as BAPI_BASE_BRANCH), never the repo default branch.
+        // The launch INSTRUCTION stays conductor-only. BAPI-801 gave plain runs the
+        // same env, but their prompt stays bare — the create-PR instruction files
+        // read $BAPI_BASE_BRANCH for them.
         parts.push(buildPrBaseContractLaunchInstruction());
     }
     if (opts.resumeMode)
@@ -1723,11 +1763,13 @@ export function getDryRunPlatformDetails(agent, platform = process.platform, env
         worktrunkBinary: resolveWorktrunkBinary(platform, env),
         // The builder accepts an optional resolved modelAlias; the dry-run caller
         // now passes the previewed tier's alias so `--model` shows in the preview.
-        // The resolved repo name (when known) is injected as a BAPI_REPO_NAME prefix
-        // so the dry-run preview matches the real spawn command exactly. Reuses the
-        // same buildAgentShellCommand/buildAgentPrompt path as a real spawn — dry-run
-        // is never special-cased — so the previewed workflow prompt is exact.
-        buildAgentShellCommand: (key, worktreePath, modelAlias) => prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch), repoName, platform),
+        // The resolved repo name (when known) is injected as a BAPI_REPO_NAME prefix,
+        // and (BAPI-801) the PR base as a BAPI_BASE_BRANCH prefix through the SAME
+        // resolvePrBaseBranchEnvValue rule and the same outermost ordering the real
+        // spawn builder uses — dry-run shares both environment renderings with real
+        // spawning. Reuses the same buildAgentShellCommand/buildAgentPrompt path as a
+        // real spawn — dry-run is never special-cased — so the preview is exact.
+        buildAgentShellCommand: (key, worktreePath, modelAlias) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch), repoName, platform), resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch), platform),
     };
 }
 /**
@@ -1769,10 +1811,17 @@ export function buildDryRunDetailLines(agent, key, branch, platform = process.pl
     const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env, autoApprove, conductorEnabled, repoName, workflow, reviewRounds, baseBranch);
     const wtArgs = buildWtSwitchArgs(branch, false, baseBranch);
     const agentInvocation = build(key, "<worktree-path>", modelAlias);
+    // BAPI-801: one concise secondary detail naming the PR base, emitted only when
+    // the shared rule actually exports BAPI_BASE_BRANCH. It sits AFTER the rendered
+    // spawn command so the copyable command stays the primary scan target, and it
+    // is ordinary routing detail — never warning-like. An ordinary plain run on
+    // `main` exports nothing and so keeps its existing output density verbatim.
+    const prBaseBranch = resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch);
     return [
         `DRY-RUN: ${key} -> branch=${branch}`,
         `DRY-RUN:   ${worktrunkBinary} ${wtArgs.join(" ")}`,
         `DRY-RUN:   ${agentInvocation}`,
+        ...(prBaseBranch ? [`DRY-RUN:   PR base: ${prBaseBranch}`] : []),
         ...buildDryRunMcpProvisioningLines("<worktree-path>", platform, mcpServerInvocation),
     ];
 }
@@ -2792,8 +2841,10 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     const platformConfig = resolveStartTicketsPlatformConfig(deps, agent, options.autoApprove, options.conductorEnabled ?? false, resolvedRepoName, 
     // BAPI-494: resume-mode dispatches get the full-suite remediation finalize prompt.
     options.resumeMode ?? false, options.workflow, options.reviewRounds, 
-    // BAPI-586: the effective run base (already carries any epic.base_branch
-    // override applied above) so conductor workers get BAPI_BASE_BRANCH.
+    // BAPI-586/BAPI-801: the effective run base (already carries any
+    // epic.base_branch override applied above) so the spawned worker gets
+    // BAPI_BASE_BRANCH — every conductor worker, and a plain worker whose base
+    // is non-default.
     options.baseBranch);
     if (!platformConfig.ok)
         return { ok: false, error: platformConfig.error };
@@ -2940,6 +2991,54 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     const rows = await spawnTabsFn(deps, routed, terminal, platformConfig.config.buildAgentShellCommand);
     return { ok: true, rows };
 }
+/**
+ * Warn when an implicit base branch could be resolved through an active
+ * repository-wide index-branch override (BAPI-814/E1b).
+ *
+ * Informational only, and deliberately narrow:
+ *
+ * - **Only for an IMPLICIT base.** An explicit `--base-branch` is the caller's
+ *   own decision and is unaffected by the override, so the probe is skipped
+ *   entirely — no request is made and no warning is printed.
+ * - **Only with resolvable credentials.** `start-tickets` creates worktrees and
+ *   opens tabs; it does not require Bridge access to do its job. "No credential"
+ *   is therefore an ordinary state for this command, not a diagnostic, and
+ *   staying silent keeps an unrelated command from growing a credential
+ *   complaint. A lookup that FAILS after credentials resolved is different, and
+ *   does produce one bounded, sanitized line.
+ * - **Never a refusal.** Nothing here changes the exit code, the base branch, or
+ *   any spawn behavior.
+ *
+ * Warnings go to `errorLog` (stderr), so machine-readable stdout stays clean.
+ */
+async function warnOnIndexOverrideForImplicitBase(deps, options, errorLog, fetchImpl) {
+    if (options.baseBranchExplicit)
+        return;
+    const access = await resolveConductorBridgeApiAccess({
+        env: deps.env,
+        cwd: deps.cwd,
+        homedir: os.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile ?? ((filePath) => readFile(filePath, "utf-8")),
+        stat: (filePath) => stat(filePath).then((info) => ({ mode: info.mode })),
+    });
+    if (!access.ok)
+        return;
+    const result = await getIndexBranch(access.access, fetchImpl);
+    if (!result.ok) {
+        errorLog(`Warning: the repository's indexed-branch override could not be read: ${result.error}. ` +
+            "Continuing — ticket startup is unaffected.");
+        return;
+    }
+    const override = result.value.override;
+    if (override === null)
+        return;
+    errorLog(`Warning: ${access.access.repoName} has an ACTIVE index-branch override: ` +
+        `'${override.override_branch}'. No --base-branch was given, so the implicit base — ` +
+        "the base-branch config field and feature-branch provisioning — may resolve through " +
+        "that override rather than the repository's usual base. Ticket startup is ALLOWED and " +
+        "continues; pass --base-branch to choose explicitly.");
+}
 /** Platform-specific guidance printed when one or more tabs fail to spawn. */
 function spawnFailureHintForPlatform(platform) {
     if (platform === "darwin") {
@@ -2995,6 +3094,9 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         errorLog("Warning: --tier value was not one of cheap|basic|premium; ignoring the override and " +
             "using premium model routing for every ticket.");
     }
+    // BAPI-814/E1b: informational only, ahead of the dry-run branch so both a
+    // preview and a real run report the same repository-wide condition.
+    await warnOnIndexOverrideForImplicitBase(deps, options, errorLog, overrides.fetchImpl ?? globalThis.fetch);
     if (options.dryRun) {
         // Resolve the repo identity for the preview so the dry-run command matches
         // what the real spawn injects (see prependRepoNameEnvAssignment). The real

package/build/version.generated.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.37";
+export const VERSION = "0.2.39";