@bridge_gpt/mcp-server 0.2.21 → 0.2.24

package/build/sfcc/log-query.js

@@ -0,0 +1,170 @@
+/**
+ * `sfcc_log_query` — gated, on-demand SFCC log-query MCP tool (T7 / BAPI-556).
+ *
+ * A thin, profile-gated handler that forwards an explicitly bounded query to the
+ * Bridge backend, which runs T1 pull → T2 redaction → T3 filtering server-side
+ * and returns scoped, redacted findings. `environment` and `time_range` are
+ * REQUIRED with no broad defaults; entries, time range, and log-file prefixes are
+ * all capped to prevent runaway retrieval. Basic-auth WebDAV credentials never
+ * leave the backend — this tool holds none.
+ *
+ * The backend response has already passed through the `RedactionPort`, so its JSON
+ * is returned to the LLM unchanged; there is deliberately NO local retrieval
+ * bypass in TypeScript.
+ */
+import { z } from "zod";
+import { withSfccLogGate } from "./log-gate.js";
+// ---------------------------------------------------------------------------
+// Bounds — mirror src/python/sfcc_monitor/log_query.py (kept in lock-step).
+// ---------------------------------------------------------------------------
+const MAX_QUERY_RANGE_HOURS = 24;
+const HIGH_VOLUME_MAX_RANGE_HOURS = 6;
+const HIGH_VOLUME_PREFIXES = new Set(["info", "jobs", "debug", "customdebug"]);
+const MAX_SELECTED_PREFIXES = 5;
+const MAX_MAX_ENTRIES = 2000;
+const SUPPORTED_ENVIRONMENTS = ["production", "staging", "development"];
+const PREFIX_RE = /^[a-z][a-z0-9]*$/;
+function jsonResult(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+}
+function validationError(message) {
+    return jsonResult({ error: "VALIDATION_ERROR", status: 400, message });
+}
+// ---------------------------------------------------------------------------
+// Zod input schema
+// ---------------------------------------------------------------------------
+const inputSchema = z.object({
+    environment: z
+        .enum(SUPPORTED_ENVIRONMENTS)
+        .describe("REQUIRED environment to scope the query to. Deliberately required so a " +
+        "query can never fan across every environment at once."),
+    time_range: z
+        .object({
+        start: z.string().datetime({ offset: true }).describe("Inclusive ISO-8601 UTC start."),
+        end: z.string().datetime({ offset: true }).describe("Exclusive ISO-8601 UTC end (after start)."),
+    })
+        .strict()
+        .describe("REQUIRED bounded window. No open-ended or inferred period is ever assumed."),
+    prefixes: z
+        .array(z.string().regex(PREFIX_RE, "prefix must be a letter followed by letters/digits"))
+        .max(MAX_SELECTED_PREFIXES)
+        .optional()
+        .describe(`Optional log-file prefix selection (max ${MAX_SELECTED_PREFIXES}). Empty = the ` +
+        "shipped error-class defaults. High-volume prefixes (info/jobs/debug/customdebug) " +
+        `impose a stricter ${HIGH_VOLUME_MAX_RANGE_HOURS}h max time range.`),
+    max_entries: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_MAX_ENTRIES)
+        .optional()
+        .describe(`Optional per-query entry-scan cap (1..${MAX_MAX_ENTRIES}).`),
+});
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+/**
+ * Perform handler-level semantic checks so agents get a structured
+ * VALIDATION_ERROR before any network retrieval where possible.
+ */
+function semanticCheck(args) {
+    const start = Date.parse(args.time_range.start);
+    const end = Date.parse(args.time_range.end);
+    if (Number.isNaN(start) || Number.isNaN(end)) {
+        return "time_range.start and time_range.end must be valid ISO-8601 timestamps.";
+    }
+    if (!(start < end)) {
+        return "time_range.start must be strictly before time_range.end.";
+    }
+    const prefixes = args.prefixes ?? [];
+    const hasHighVolume = prefixes.some((p) => HIGH_VOLUME_PREFIXES.has(p));
+    const maxHours = hasHighVolume ? HIGH_VOLUME_MAX_RANGE_HOURS : MAX_QUERY_RANGE_HOURS;
+    const spanHours = (end - start) / 3_600_000;
+    if (spanHours > maxHours) {
+        return (`time_range spans ${spanHours.toFixed(1)}h but the maximum for this prefix ` +
+            `selection is ${maxHours}h. environment and time_range are required, and the ` +
+            "range is capped, to prevent broad cross-environment or open-ended log scans.");
+    }
+    // Uniqueness (Zod validates grammar + count; this catches duplicates).
+    if (new Set(prefixes).size !== prefixes.length) {
+        return "prefixes must be unique.";
+    }
+    return null;
+}
+function buildHandler(deps) {
+    return async (rawArgs) => {
+        const parsed = inputSchema.safeParse(rawArgs);
+        if (!parsed.success) {
+            return validationError(parsed.error.issues.map((i) => i.message).join("; "));
+        }
+        const args = parsed.data;
+        const semanticFailure = semanticCheck(args);
+        if (semanticFailure)
+            return validationError(semanticFailure);
+        const body = {
+            repo_name: deps.repoName,
+            environment: args.environment,
+            time_range: { start: args.time_range.start, end: args.time_range.end },
+            prefixes: args.prefixes ?? [],
+            ...(args.max_entries !== undefined ? { max_entries: args.max_entries } : {}),
+        };
+        let resp;
+        try {
+            const url = deps.buildGetUrl("/sfcc/logs/query", { repo_name: deps.repoName });
+            resp = await fetch(url, {
+                method: "POST",
+                headers: await deps.getPostHeaders(),
+                body: JSON.stringify(body),
+            });
+        }
+        catch {
+            return jsonResult({
+                error: "BAD_GATEWAY",
+                status: 502,
+                message: "Could not reach Bridge API to run the SFCC log query. Check that " +
+                    "BAPI_BASE_URL points to a running Bridge API instance.",
+            });
+        }
+        const text = await resp.text();
+        if (!resp.ok) {
+            let detail = text;
+            try {
+                detail = JSON.parse(text);
+            }
+            catch {
+                /* keep raw text detail */
+            }
+            return jsonResult({
+                error: resp.status >= 500 ? "SERVICE_UNAVAILABLE" : "REQUEST_FAILED",
+                status: resp.status,
+                detail,
+            });
+        }
+        // The backend response has already passed through RedactionPort — return it
+        // unchanged as the MCP text payload (bounded server-side; no local persistence).
+        return { content: [{ type: "text", text }] };
+    };
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+/**
+ * Register the `sfcc_log_query` tool through the host's registerTool wrapper.
+ * Called only inside the `deps.includeReadTools` SFCC-profile branch.
+ */
+export function registerSfccLogQueryTool(registerTool, deps) {
+    const gated = withSfccLogGate({ buildGetUrl: deps.buildGetUrl, getGetHeaders: deps.getGetHeaders, repoName: deps.repoName }, buildHandler(deps));
+    registerTool("sfcc_log_query", {
+        description: "Query redacted, filtered SFCC logs on demand, scoped to a REQUIRED environment " +
+            "and time_range. Runs pull→redact→filter on the Bridge backend; entries, time range, " +
+            "and log-file prefixes are capped (high-volume prefixes get a stricter range). Returns " +
+            "a NOT_CONFIGURED 503 when the log capability isn't set up — run sfcc_setup_status.",
+        inputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, gated);
+}

package/build/sfcc/register.js

@@ -14,6 +14,7 @@ import { registerSystemObjectReadTools } from "./reads-system-object.js";
 import { registerSfccCustomObjectDefReadTools } from "./reads-custom-object-def.js";
 import { registerSitePreferenceTools } from "./reads-site-preference.js";
 import { registerSfccWriteTools } from "./writes.js";
+import { registerSfccLogQueryTool } from "./log-query.js";
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
@@ -78,5 +79,14 @@ export function registerSfccTools(registerTool, deps) {
             gateDeps,
             getDocsDir: deps.getDocsDir,
         });
+        // sfcc_log_query (BAPI-556 T7) — gated, on-demand redacted/filtered log query.
+        // Uses its OWN call-time gate (log capability = WebDAV Basic auth), NOT the
+        // OCAPI version/dw.json/AM-token gate above.
+        registerSfccLogQueryTool(registerTool, {
+            buildGetUrl: deps.buildGetUrl,
+            getGetHeaders: deps.getGetHeaders,
+            getPostHeaders: deps.getPostHeaders,
+            repoName: deps.repoName,
+        });
     }
 }

package/build/sfcc/setup-status.js

@@ -19,7 +19,8 @@ import { getAmToken } from "./client.js";
  *   2. Repo name set (REPO_NAME)
  *   3. version config field is an SFCC version
  *   4. dw.json found / instance unambiguous
- *   5. AM token acquisition
+ *   5. AM token acquisition (OCAPI Account Manager — NOT log/WebDAV access)
+ *   6. SFCC Log Query capability (WebDAV Basic auth — independent of steps 3–5)
  *
  * Never throws; each check is caught independently so partial states are
  * always reported. Output is completely secret-free.
@@ -97,8 +98,37 @@ export async function sfccSetupStatusTool(deps) {
             tokenStatus = `✗ ${msg}`;
         }
     }
-    lines.push(`5. AM Token: ${tokenStatus}`);
-    lines.push("\nRun `check_permissions` to probe OCAPI access once steps 1–5 are all green.");
+    lines.push(`5. AM Token (OCAPI): ${tokenStatus}`);
+    // 6. SFCC Log Query capability — WebDAV Basic auth, independent of OCAPI/AM.
+    // A single Bridge backend probe (secret-free) reports readiness. This is a
+    // separate credential surface: an SFCC repo can have OCAPI working (steps 3–5)
+    // while log/WebDAV access is not configured, and vice versa.
+    let logQueryStatus = "— Skipped (Bridge API not configured)";
+    if (apiKeyOk && repoOk) {
+        try {
+            const url = deps.buildGetUrl("/sfcc/logs/capability", { repo_name: deps.repoName });
+            const resp = await fetch(url, { headers: await deps.getGetHeaders() });
+            if (!resp.ok) {
+                logQueryStatus = `✗ Could not read (Bridge API ${resp.status})`;
+            }
+            else {
+                const body = (await resp.json());
+                if (body?.configured === true) {
+                    logQueryStatus = "✓ Configured (WebDAV log access ready)";
+                }
+                else {
+                    const msg = typeof body?.message === "string" ? body.message : "Not configured";
+                    logQueryStatus = `✗ ${msg}`;
+                }
+            }
+        }
+        catch (err) {
+            logQueryStatus = `✗ Resolution error: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    lines.push(`6. SFCC Log Query (WebDAV): ${logQueryStatus}`);
+    lines.push("\nRun `check_permissions` to probe OCAPI access once steps 1–5 are all green. " +
+        "Step 6 (log/WebDAV access) is independent and gates `sfcc_log_query`.");
     return {
         content: [{ type: "text", text: lines.join("\n") }],
     };

package/build/start-tickets.js

@@ -71,6 +71,7 @@ import { WORKTRUNK_BINARY_OVERRIDE_ENV, WINDOWS_TERMINAL_COMMAND, WINDOWS_POWERS
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, resolveModelAlias, isValidModelAlias, isModelTier, } from "./agent-registry.js";
 import { createStartTicketsConductorContext, provisionConductorHooksForRows, emitStartTicketsRunStarted, injectConductorEnvIntoShellCommand, buildSupervisorTabCommand, isSupervisorLaunchEnabled, supervisorSpawnKey, } from "./start-tickets-conductor.js";
 import { transitionEpicDispatch, resolveConductorBridgeApiAccess, } from "./conductor/bridge-api-client.js";
+import { PR_BASE_BRANCH_ENV_VAR, buildPrBaseContractLaunchInstruction, } from "./pr-base-contract.js";
 // Re-export the shared prereq surface (constants, platform helpers, command
 // probes) so existing import sites that read them from "./start-tickets.js"
 // keep working unchanged.
@@ -101,6 +102,8 @@ export function getStartTicketsUsage() {
         "",
         "Flags:",
         "  --agent claude|cursor-agent Agent command to launch in each worktree (default: claude)",
+        "  --workflow implement|review-and-implement  Slash command each spawned worktree runs (default: implement). review-and-implement runs /review-ticket then, after a per-ticket halt gate, /implement-ticket in the same session; --auto applies to the selected workflow.",
+        "  --rounds 1|2                Review round count forwarded to the review phase; review-only, valid only with --workflow review-and-implement",
         "  --terminal terminal|iterm   Override the macOS terminal app (default: auto-detect via $TERM_PROGRAM); honored on macOS only",
         "  --dry-run                   Print intended actions; creates no worktrees and opens no tabs, but DOES resolve model routing read-only (may compute+cache a ticket's difficulty) to preview the --model each tab would use",
         "  --branch KEY=BRANCH         Use BRANCH instead of feature/KEY for that ticket (repeatable)",
@@ -151,6 +154,8 @@ export function parseStartTicketsArgs(argv) {
     let agentName = DEFAULT_AGENT_NAME;
     let baseBranch = "main";
     let conductorEnabled = false;
+    let workflow = "implement";
+    let reviewRoundsRaw;
     const branchEntries = [];
     const keys = [];
     for (let i = 0; i < argv.length; i++) {
@@ -183,6 +188,49 @@ export function parseStartTicketsArgs(argv) {
             agentName = value;
             continue;
         }
+        if (arg === "--workflow" || arg.startsWith("--workflow=")) {
+            let value;
+            if (arg.startsWith("--workflow=")) {
+                value = arg.slice("--workflow=".length);
+            }
+            else {
+                value = takeValue();
+                if (value === undefined) {
+                    return {
+                        status: "error",
+                        message: "--workflow requires a value (allowed values: implement, review-and-implement).",
+                    };
+                }
+            }
+            if (value !== "implement" && value !== "review-and-implement") {
+                return {
+                    status: "error",
+                    message: `Invalid --workflow value: '${value}' (allowed values: implement, review-and-implement).`,
+                };
+            }
+            workflow = value;
+            continue;
+        }
+        if (arg === "--rounds" || arg.startsWith("--rounds=")) {
+            let value;
+            if (arg.startsWith("--rounds=")) {
+                value = arg.slice("--rounds=".length);
+            }
+            else {
+                value = takeValue();
+                if (value === undefined) {
+                    return { status: "error", message: "--rounds requires a value (allowed values: 1, 2)." };
+                }
+            }
+            if (value !== "1" && value !== "2") {
+                return {
+                    status: "error",
+                    message: `Invalid --rounds value: '${value}' (allowed values: 1, 2).`,
+                };
+            }
+            reviewRoundsRaw = value;
+            continue;
+        }
         if (arg === "--terminal" || arg.startsWith("--terminal=")) {
             let value;
             if (arg.startsWith("--terminal=")) {
@@ -337,29 +385,38 @@ export function parseStartTicketsArgs(argv) {
         }
         branchOverrides[overrideKey] = branchName;
     }
+    // --- rounds validation: review-only, checked after the full argument scan
+    // so flag order (e.g. --rounds before --workflow) never affects validation.
+    let reviewRounds;
+    if (reviewRoundsRaw !== undefined) {
+        if (workflow !== "review-and-implement") {
+            return {
+                status: "error",
+                message: "--rounds is only valid with --workflow review-and-implement.",
+            };
+        }
+        reviewRounds = reviewRoundsRaw === "1" ? 1 : 2;
+    }
     return {
         status: "ok",
-        options: { keys, terminal, dryRun, autoApprove, refreshMain, maxParallel, branchOverrides, agentName, baseBranch, conductorEnabled },
+        options: {
+            keys,
+            terminal,
+            dryRun,
+            autoApprove,
+            refreshMain,
+            maxParallel,
+            branchOverrides,
+            agentName,
+            baseBranch,
+            conductorEnabled,
+            workflow,
+            reviewRounds,
+        },
     };
 }
-/** Returns an error string for an unsafe branch name, or null when valid. */
-export function validateBranchName(branch) {
-    if (branch.trim().length === 0)
-        return "branch name must not be empty.";
-    if (branch.length > 255)
-        return "branch name must be 255 characters or fewer.";
-    if (branch.startsWith("-"))
-        return "branch name must not start with '-'.";
-    // Reject ASCII control characters (0x00-0x1F and 0x7F) without embedding
-    // raw control bytes in source.
-    for (let i = 0; i < branch.length; i++) {
-        const code = branch.charCodeAt(i);
-        if (code <= 0x1f || code === 0x7f) {
-            return "branch name must not contain control characters.";
-        }
-    }
-    return null;
-}
+// `validateBranchName` moved to `base-ref.ts` (BAPI-586); imported + re-exported
+// above. See the import block near the worktree-core re-exports.
 /**
  * Determine which macOS terminal to drive. An explicit choice wins; otherwise
  * auto-detect iTerm from `$TERM_PROGRAM` (case-insensitive), defaulting to
@@ -403,19 +460,27 @@ export function getDefaultSpawnTerminalTabForPlatform(platform) {
 export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = false, conductorEnabled = false, repoName = null, 
 // BAPI-494: a conductor remediation re-dispatch. Appends the full-suite finalize
 // instruction to the resume-mode worker's prompt.
-resumeMode = false) {
+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.
+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;
     return {
         ok: true,
         config: {
             platform,
             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).
-            buildAgentShellCommand: (key, worktreePath, modelAlias) => prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode), repoName, platform),
+            // 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.
+            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,
         },
     };
@@ -445,6 +510,24 @@ 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).
+ */
+export function prependBaseBranchEnvAssignment(command, baseBranch, platform = "darwin") {
+    if (!baseBranch)
+        return command;
+    if (platform === "win32") {
+        return `$env:${PR_BASE_BRANCH_ENV_VAR} = ${powershellSquote(baseBranch)}; ${command}`;
+    }
+    return `export ${PR_BASE_BRANCH_ENV_VAR}='${shSquoteInner(baseBranch)}' && ${command}`;
+}
 /**
  * Escape a string for inclusion inside a single-quoted shell context: each
  * embedded single-quote becomes the sequence `'\''`. Returns only the inner
@@ -725,42 +808,10 @@ export async function refreshBaseBranch(deps, options) {
 export async function refreshMainBranch(deps, options) {
     return refreshBaseBranch(deps, { refreshMain: options.refreshMain, baseBranch: "main" });
 }
-/**
- * Non-mutating counterpart to {@link refreshBaseBranch}: fetches
- * `origin/<baseBranch>` and resolves the fetched tip to an immutable commit
- * SHA, WITHOUT ever fast-forwarding or force-moving any local branch ref (no
- * `git merge --ff-only`, no `git branch --force`). Used by review-grounding
- * (BAPI-474), which must read a pinned base tree without touching the user's
- * working tree, index, stash, or local branch refs.
- *
- * Validates `baseBranch` with {@link validateBranchName} first so an
- * injection-shaped ref name is rejected before any git invocation. Every git
- * call uses an argv array (never a shell string), consistent with
- * {@link refreshBaseBranch}.
- */
-export async function fetchAndResolveBaseSha(deps, baseBranch) {
-    const validationError = validateBranchName(baseBranch);
-    if (validationError) {
-        return { ok: false, error: `Invalid base branch '${baseBranch}': ${validationError}` };
-    }
-    const fetch = await deps.runCommand("git", ["fetch", "origin", baseBranch], {
-        cwd: deps.cwd,
-    });
-    if (!commandSucceeded(fetch)) {
-        return {
-            ok: false,
-            error: `git fetch origin ${baseBranch} failed. Check your network and 'git remote get-url origin', or pass --no-refresh-base to skip.`,
-        };
-    }
-    const resolve = await deps.runCommand("git", ["rev-parse", "--verify", `origin/${baseBranch}^{commit}`], { cwd: deps.cwd });
-    if (!commandSucceeded(resolve)) {
-        return {
-            ok: false,
-            error: `Failed to resolve origin/${baseBranch} to a commit SHA after fetch (git rev-parse --verify failed).`,
-        };
-    }
-    return { ok: true, base_sha: resolve.stdout.trim() };
-}
+// `fetchAndResolveBaseSha` + `FetchAndResolveBaseShaResult` moved to
+// `base-ref.ts` (BAPI-586) and re-exported above. The shared helper now also
+// serializes the fetch per repository via an async mutex so concurrent executor
+// fresh jobs against one clone cannot collide on git lock files.
 // ---------------------------------------------------------------------------
 // Concurrency + worktree creation
 // ---------------------------------------------------------------------------
@@ -798,6 +849,13 @@ export async function runWithConcurrency(items, limit, worker) {
 // same function references.
 import { resolveBranchForTicket, branchExists, buildWtSwitchArgs, pathApiForPlatform, extractWorktreePath, isExistingBranchSafeToReuse, createWorktreeForTicket, } from "./worktree-core.js";
 export { resolveBranchForTicket, branchExists, buildWtSwitchArgs, pathApiForPlatform, extractWorktreePath, isExistingBranchSafeToReuse, createWorktreeForTicket, };
+// BAPI-586: base-ref resolution now lives in the focused `base-ref.ts` module so
+// the executor can depend on it without pulling in this large CLI module. We
+// import the VALUES here (so internal uses keep working) and re-export the same
+// references so existing importers of `./start-tickets.js` (index.ts,
+// review-tickets.ts) and the pinned start-tickets tests are unaffected.
+import { validateBranchName, fetchAndResolveBaseSha } from "./base-ref.js";
+export { validateBranchName, fetchAndResolveBaseSha };
 /**
  * Create / switch worktrees for every ticket, throttled to `maxParallel`, using
  * the resolved Worktrunk binary. Returns one row per ticket in original key
@@ -811,7 +869,17 @@ export { resolveBranchForTicket, branchExists, buildWtSwitchArgs, pathApiForPlat
  * historical branch-name behavior unchanged.
  */
 export async function createWorktrees(deps, options, worktrunkBinary, baseStartPoint = options.baseBranch) {
-    return runWithConcurrency(options.keys, options.maxParallel, (key) => createWorktreeForTicket(deps, key, options.branchOverrides, worktrunkBinary, baseStartPoint, options.guardStaleWorktree === true));
+    // BAPI-586: for guard-enabled Conductor fresh dispatch the caller has already
+    // resolved `baseStartPoint` to an immutable base SHA (`nonMutatingBase`). Align
+    // any safe pre-existing branch exactly to that SHA and verify the resulting
+    // head against it, so a dependent ticket starts at fresh `origin/<base>` rather
+    // than at a stale ancestor or a sibling seed. Interactive dispatch (a moving
+    // branch name, guard off) keeps the historical reuse-as-is behavior.
+    const exactBase = options.guardStaleWorktree === true && options.nonMutatingBase === true;
+    const behavior = exactBase
+        ? { alignExistingBranchTo: baseStartPoint, verifyHeadMatches: baseStartPoint }
+        : {};
+    return runWithConcurrency(options.keys, options.maxParallel, (key) => createWorktreeForTicket(deps, key, options.branchOverrides, worktrunkBinary, baseStartPoint, options.guardStaleWorktree === true, behavior));
 }
 /**
  * Resume-mode worktree resolution (BAPI-441). Instead of creating worktrees,
@@ -931,10 +999,26 @@ export function buildAgentPrompt(key, opts = {}) {
     // `modelAlias` is accepted for signature consistency only — the model is
     // injected as a `--model` flag (see buildAgentInvocationArgv), never embedded
     // in the prompt text.
-    const command = `/implement-ticket ${key}${opts.autoApprove ? " --auto" : ""}`;
+    const workflow = opts.workflow ?? "implement";
+    const head = workflow === "review-and-implement" ? "/review-and-implement" : "/implement-ticket";
+    let command = `${head} ${key}${opts.autoApprove ? " --auto" : ""}`;
+    // Review-only arguments (`--rounds`, non-default `--base-branch`) must never
+    // leak into the legacy `/implement-ticket` prompt.
+    if (workflow === "review-and-implement") {
+        if (opts.reviewRounds !== undefined) {
+            command += ` --rounds=${opts.reviewRounds}`;
+        }
+        if (opts.baseBranch !== undefined && opts.baseBranch !== "main") {
+            command += ` --base-branch='${shSquoteInner(opts.baseBranch)}'`;
+        }
+    }
     const parts = [command];
-    if (opts.conductorEnabled)
+    if (opts.conductorEnabled) {
         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.
+        parts.push(buildPrBaseContractLaunchInstruction());
+    }
     if (opts.resumeMode)
         parts.push(buildResumeModeRemediationFinalizeInstruction());
     return parts.join(" ");
@@ -976,13 +1060,13 @@ export function buildAgentInvocation(agent, prompt, quote, modelAlias) {
     }
 }
 /** POSIX agent shell command: `cd '<path>' && <agent> [--model '<alias>'] '<prompt>'`. */
-export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode }), (p) => `'${shSquoteInner(p)}'`, modelAlias);
+export function buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch }), (p) => `'${shSquoteInner(p)}'`, modelAlias);
     return `cd '${shSquoteInner(worktreePath)}' && ${invocation}`;
 }
 /** PowerShell agent shell command: `Set-Location -LiteralPath '<path>'; <agent> [--model '<alias>'] '<prompt>'`. */
-export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false) {
-    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode }), powershellSquote, modelAlias);
+export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key, { autoApprove, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch }), powershellSquote, modelAlias);
     return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${invocation}`;
 }
 /**
@@ -993,10 +1077,10 @@ export function buildPowerShellAgentShellCommand(agent, key, worktreePath, autoA
  * injected as `--model` at the spawn boundary. `conductorEnabled` appends the
  * BAPI-397 message-relay instruction to the prompt (opt-in via `--conductor`).
  */
-export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false) {
+export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin", autoApprove = false, modelAlias, conductorEnabled = false, resumeMode = false, workflow = "implement", reviewRounds, baseBranch) {
     if (platform === "win32")
-        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode);
-    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode);
+        return buildPowerShellAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch);
+    return buildPosixAgentShellCommand(agent, key, worktreePath, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch);
 }
 /**
  * Build the shell command run inside a spawned tab/session for an ARBITRARY
@@ -1518,14 +1602,16 @@ export function buildDryRunResults(keys, overrides) {
  * PowerShell on Windows, `wt` + POSIX on macOS/Linux, and a non-throwing `wt` +
  * POSIX fallback for unsupported platforms.
  */
-export function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env, autoApprove = false, conductorEnabled = false, repoName = null) {
+export function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env, autoApprove = false, conductorEnabled = false, repoName = null, workflow = "implement", reviewRounds, baseBranch) {
     return {
         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.
-        buildAgentShellCommand: (key, worktreePath, modelAlias) => prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled), repoName, platform),
+        // 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),
     };
 }
 /**
@@ -1563,8 +1649,8 @@ export function buildDryRunMcpProvisioningLines(worktreePath, platform = process
  * the secret-free MCP provisioning preview. Pure platform formatting only — no
  * preflight, no routing failures.
  */
-export function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env, baseBranch = "main", autoApprove = false, modelAlias = null, conductorEnabled = false, repoName = null, mcpServerInvocation) {
-    const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env, autoApprove, conductorEnabled, repoName);
+export function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env, baseBranch = "main", autoApprove = false, modelAlias = null, conductorEnabled = false, repoName = null, mcpServerInvocation, workflow = "implement", reviewRounds) {
+    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);
     return [
@@ -2504,7 +2590,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.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.
+    options.baseBranch);
     if (!platformConfig.ok)
         return { ok: false, error: platformConfig.error };
     // BAPI-527: resolve the base start point new worktrees are cut from BEFORE any
@@ -2707,7 +2796,7 @@ export async function runStartTicketsCli(argv, overrides = {}) {
             const branch = resolveBranchForTicket(key, options.branchOverrides);
             const routedRow = routedByKey.get(key);
             const modelAlias = routedRow?.modelAlias ?? null;
-            for (const line of buildDryRunDetailLines(agent, key, branch, deps.platform, deps.env, options.baseBranch, options.autoApprove, modelAlias, options.conductorEnabled ?? false, dryRunRepoName, dryRunMcpInvocation)) {
+            for (const line of buildDryRunDetailLines(agent, key, branch, deps.platform, deps.env, options.baseBranch, options.autoApprove, modelAlias, options.conductorEnabled ?? false, dryRunRepoName, dryRunMcpInvocation, options.workflow, options.reviewRounds)) {
                 log(line);
             }
             log(`DRY-RUN:   model routing: ${formatModelRoutingLine(routedRow ?? { key, branch, status: "dry-run" }, agent)}`);

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.21";
+export const VERSION = "0.2.24";