@bridge_gpt/mcp-server 0.2.16 → 0.2.19

package/build/review-tickets.js

@@ -15,10 +15,12 @@
  * This path is worktree-free and base-branch-free; the human CLI path leaves
  * `epic` unset and retains byte-for-byte identical behavior.
  */
-import { createDefaultStartTicketsDeps, detectTerminal, runWithConcurrency, buildAgentInvocation, shSquoteInner, powershellSquote, isCommandOnPath, resolveFirstCommandOnPath, tmuxSessionNameForTicket, TICKET_KEY_PATTERN, DEFAULT_MAX_PARALLEL, } from "./start-tickets.js";
+import { createDefaultStartTicketsDeps, detectTerminal, runWithConcurrency, buildAgentInvocation, shSquoteInner, powershellSquote, isCommandOnPath, resolveFirstCommandOnPath, tmuxSessionNameForTicket, TICKET_KEY_PATTERN, DEFAULT_MAX_PARALLEL, validateBranchName, fetchAndResolveBaseSha, fetchStartTicketsConfigField, resolveStartTicketsBridgeApiAccess, } from "./start-tickets.js";
 import { WINDOWS_TERMINAL_COMMAND, WINDOWS_POWERSHELL_CANDIDATES, TMUX_COMMAND, isSupportedStartTicketsPlatform, unsupportedPlatformMessage, } from "./start-tickets-prereqs.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, isValidModelAlias, } from "./agent-registry.js";
 import { injectConductorEnvIntoShellCommand, buildEpicIdentityEnv, mintStartTicketsRunId, } from "./start-tickets-conductor.js";
+/** Default base context: no flags threaded through (matches pre-BAPI-474 behavior). */
+const NO_BASE_CONTEXT = { noRefreshBase: false };
 // ---------------------------------------------------------------------------
 // Usage
 // ---------------------------------------------------------------------------
@@ -35,6 +37,8 @@ export function getReviewTicketsUsage() {
         "  --model VALUE                     Model alias to pass as --model to the agent (optional passthrough)",
         "  --max-parallel N                  Max tabs to spawn concurrently (default: 3)",
         "  --dry-run                         Print intended commands; creates no tabs and opens no sessions",
+        "  --base-branch BRANCH              Base branch to fetch+pin for grounding (default: config base_branch, else \"main\")",
+        "  --no-refresh-base                 Skip the parent-fetch-once base pin; restores git-free, in-place-grounded behavior",
         "  -h, --help                        Show this help",
         "",
         "Examples:",
@@ -42,19 +46,107 @@ export function getReviewTicketsUsage() {
         "  npx -y @bridge_gpt/mcp-server review-tickets --auto --rounds=1 BAPI-1 BAPI-2",
         "  npx -y @bridge_gpt/mcp-server review-tickets --review BAPI-1=auto,rounds=1 --review BAPI-2=rounds=2 BAPI-1 BAPI-2",
         "  npx -y @bridge_gpt/mcp-server review-tickets --dry-run BAPI-1 BAPI-2",
+        "  npx -y @bridge_gpt/mcp-server review-tickets --base-branch=develop BAPI-1 BAPI-2",
+        "  npx -y @bridge_gpt/mcp-server review-tickets --no-refresh-base BAPI-1 BAPI-2",
         "",
         "Each KEY must match [A-Z]+-[0-9]+ (e.g., BAPI-248).",
         "",
-        "Prerequisites (terminal launcher only — no wt, git-wt, git, or Worktrunk required):",
-        "  macOS    osascript",
-        "  Windows  wt.exe or PowerShell",
-        "  Linux    tmux",
+        "Prerequisites (terminal launcher, plus git — no wt, git-wt, or Worktrunk required):",
+        "  macOS    osascript, git",
+        "  Windows  wt.exe or PowerShell, git",
+        "  Linux    tmux, git",
         "",
-        "review-tickets runs all tabs in the current repository cwd and creates no Worktrunk worktrees.",
-        "--dry-run works on any platform, including unsupported ones.",
+        "review-tickets runs all tabs in the current repository cwd and creates no Worktrunk worktrees. It now",
+        "requires git on PATH (BAPI-474): before spawning tabs it fetches origin/<base_branch> once and pins a",
+        "single base_sha for the whole batch, so every spawned review grounds against the same base tree even if",
+        "origin advances mid-batch. Pass --no-refresh-base to skip this and restore the prior git-free behavior.",
+        "--dry-run works on any platform, including unsupported ones, and never performs the base-branch fetch.",
     ].join("\n");
 }
 // ---------------------------------------------------------------------------
+// Fail-loud base-fetch diagnostic (BAPI-474 D-4)
+// ---------------------------------------------------------------------------
+const ANSI_BOLD = "\x1b[1m";
+// Warm Coral — a high-contrast 256-color red/coral used exclusively for this
+// fail-loud alert box so a base-branch fetch failure is unmistakable in a scan
+// of scrollback, without hijacking the terminal's general error-red semantics.
+const ANSI_WARM_CORAL = "\x1b[38;5;203m";
+const ANSI_RESET = "\x1b[0m";
+/**
+ * Render a bordered, high-contrast fail-loud alert box for a parent-fetch-once
+ * failure (BAPI-474 D-4 "Design Direction Fail-Loud"): an operation-failed
+ * header, the target base branch, and an actionable remediation line. Pure
+ * formatting (no I/O) so it stays unit-testable; the caller is responsible for
+ * writing it to stderr.
+ */
+export function formatBaseFetchFailureBox(baseBranch, error) {
+    const title = "review-tickets: base-branch fetch failed";
+    // The box always shows a dedicated Remediation line below. fetchAndResolveBaseSha's
+    // own error text embeds the same remediation clause because it also has to stand
+    // alone when surfaced outside a box (e.g. raw JSON from materialize_fresh_base) —
+    // strip it here so the boxed rendering doesn't say it twice.
+    const reason = error
+        .replace(/\s*Check your network and 'git remote get-url origin', or pass --no-refresh-base to skip\.?\s*$/i, "")
+        .trim();
+    const bodyLines = [
+        `Target base branch: origin/${baseBranch}`,
+        `Reason: ${reason}`,
+        "Remediation: check your network and 'git remote get-url origin', or rerun with --no-refresh-base to evaluate in-place.",
+    ];
+    const contentWidth = Math.max(title.length + 2, ...bodyLines.map((l) => l.length)) + 2;
+    const horizontal = "─".repeat(contentWidth);
+    const pad = (s) => `│ ${s}${" ".repeat(contentWidth - s.length - 1)}│`;
+    const lines = [
+        `╭${horizontal}╮`,
+        pad(`✖ ${title}`),
+        `├${horizontal}┤`,
+        ...bodyLines.map((l) => pad(l)),
+        `╰${horizontal}╯`,
+    ];
+    return `${ANSI_BOLD}${ANSI_WARM_CORAL}${lines.join("\n")}${ANSI_RESET}`;
+}
+/**
+ * Resolve ONE base_branch/base_sha pin for the whole review-tickets batch
+ * BEFORE any tab is spawned (D-3), so a mid-batch `origin` advance can never
+ * mix bases within one run. Skipped entirely (never fetches) when
+ * `--no-refresh-base` was passed. base_branch precedence: `--base-branch` flag
+ * > config field `base_branch` (BAPI-313) > `"main"`. The config-field lookup
+ * is best-effort — any failure there falls through to `"main"`; only the git
+ * fetch/resolve itself is a hard failure (the caller applies the D-4 fail-loud
+ * response to that).
+ */
+export async function resolveBatchBaseContext(deps, options) {
+    if (options.noRefreshBase) {
+        return { ok: true, context: { noRefreshBase: true } };
+    }
+    let effectiveBaseBranch = (options.baseBranch ?? "").trim();
+    if (effectiveBaseBranch.length === 0) {
+        try {
+            const accessResult = await resolveStartTicketsBridgeApiAccess(deps);
+            if (accessResult.ok) {
+                const configValue = await fetchStartTicketsConfigField(accessResult.access, "base_branch");
+                if (typeof configValue === "string" && configValue.trim().length > 0) {
+                    effectiveBaseBranch = configValue.trim();
+                }
+            }
+        }
+        catch {
+            /* config-field lookup is best-effort; fall through to the "main" default */
+        }
+    }
+    if (effectiveBaseBranch.length === 0) {
+        effectiveBaseBranch = "main";
+    }
+    const fetchResult = await fetchAndResolveBaseSha(deps, effectiveBaseBranch);
+    if (!fetchResult.ok) {
+        return { ok: false, baseBranch: effectiveBaseBranch, error: fetchResult.error };
+    }
+    return {
+        ok: true,
+        context: { baseBranch: effectiveBaseBranch, baseSha: fetchResult.base_sha, noRefreshBase: false },
+    };
+}
+// ---------------------------------------------------------------------------
 // Argument parsing
 // ---------------------------------------------------------------------------
 export function parseReviewOverrideEntry(entry, requestedKeys) {
@@ -105,6 +197,8 @@ export function parseReviewTicketsArgs(argv) {
     let maxParallelRaw;
     let agentName = DEFAULT_AGENT_NAME;
     let modelAlias;
+    let noRefreshBase = false;
+    let baseBranch;
     const keys = [];
     const rawReviewEntries = [];
     for (let i = 0; i < argv.length; i++) {
@@ -123,6 +217,30 @@ export function parseReviewTicketsArgs(argv) {
             globalAuto = true;
             continue;
         }
+        if (arg === "--no-refresh-base") {
+            noRefreshBase = true;
+            continue;
+        }
+        if (arg === "--base-branch" || arg.startsWith("--base-branch=")) {
+            let value;
+            if (arg.startsWith("--base-branch=")) {
+                value = arg.slice("--base-branch=".length);
+            }
+            else {
+                const next = i + 1 < argv.length ? argv[i + 1] : undefined;
+                if (next === undefined || next.startsWith("-")) {
+                    return { status: "error", message: "--base-branch requires a value (a branch name)." };
+                }
+                value = takeValue();
+            }
+            const trimmed = (value ?? "").trim();
+            const error = validateBranchName(trimmed);
+            if (error) {
+                return { status: "error", message: `Invalid --base-branch value: ${error}` };
+            }
+            baseBranch = trimmed;
+            continue;
+        }
         if (arg === "--rounds" || arg.startsWith("--rounds=")) {
             let value;
             if (arg.startsWith("--rounds=")) {
@@ -267,6 +385,8 @@ export function parseReviewTicketsArgs(argv) {
             auto: globalAuto,
             rounds: globalRounds,
             reviewOverrides,
+            noRefreshBase,
+            baseBranch,
         },
     };
 }
@@ -289,24 +409,27 @@ export function resolveEffectiveReviewMode(key, options) {
 // hard-wired to `/implement-ticket`. Review-aware builders are used instead so
 // the prompt uses `/review-ticket` and no directory change is prepended.
 // ---------------------------------------------------------------------------
-export function buildReviewTicketPrompt(key, mode) {
+export function buildReviewTicketPrompt(key, mode, base = NO_BASE_CONTEXT) {
     const autoFlag = mode.auto ? " --auto" : "";
-    return `/review-ticket ${key}${autoFlag} --rounds=${mode.rounds}`;
+    const baseBranchFlag = base.baseBranch ? ` --base-branch=${base.baseBranch}` : "";
+    const baseShaFlag = base.baseSha ? ` --base-sha=${base.baseSha}` : "";
+    const noRefreshFlag = base.noRefreshBase ? " --no-refresh-base" : "";
+    return `/review-ticket ${key}${autoFlag} --rounds=${mode.rounds}${baseBranchFlag}${baseShaFlag}${noRefreshFlag}`;
 }
-export function buildPosixReviewAgentShellCommand(agent, key, mode, cwd, modelAlias) {
-    const prompt = buildReviewTicketPrompt(key, mode);
+export function buildPosixReviewAgentShellCommand(agent, key, mode, cwd, modelAlias, base = NO_BASE_CONTEXT) {
+    const prompt = buildReviewTicketPrompt(key, mode, base);
     const invocation = buildAgentInvocation(agent, prompt, (p) => `'${shSquoteInner(p)}'`, modelAlias);
     return `cd '${shSquoteInner(cwd)}' && ${invocation}`;
 }
-export function buildPowerShellReviewAgentShellCommand(agent, key, mode, modelAlias) {
-    const prompt = buildReviewTicketPrompt(key, mode);
+export function buildPowerShellReviewAgentShellCommand(agent, key, mode, modelAlias, base = NO_BASE_CONTEXT) {
+    const prompt = buildReviewTicketPrompt(key, mode, base);
     return buildAgentInvocation(agent, prompt, powershellSquote, modelAlias);
 }
-export function buildReviewAgentShellCommand(agent, key, mode, platform, cwd, modelAlias) {
+export function buildReviewAgentShellCommand(agent, key, mode, platform, cwd, modelAlias, base = NO_BASE_CONTEXT) {
     if (platform === "win32") {
-        return buildPowerShellReviewAgentShellCommand(agent, key, mode, modelAlias);
+        return buildPowerShellReviewAgentShellCommand(agent, key, mode, modelAlias, base);
     }
-    return buildPosixReviewAgentShellCommand(agent, key, mode, cwd, modelAlias);
+    return buildPosixReviewAgentShellCommand(agent, key, mode, cwd, modelAlias, base);
 }
 // ---------------------------------------------------------------------------
 // Unsupported platform message for review-tickets
@@ -325,6 +448,16 @@ export async function runReviewTicketsPreflight(deps, options) {
     if (!isSupportedStartTicketsPlatform(deps.platform)) {
         return { ok: false, error: unsupportedReviewTicketsPlatformMessage(deps.platform) };
     }
+    // BAPI-474: the parent-fetch-once base pin adds a git prerequisite unless the
+    // caller opted out via --no-refresh-base. Checked here (before any tab is
+    // spawned) so a missing git fails loud with a clear, actionable message.
+    if (!options.noRefreshBase && !(await isCommandOnPath(deps, "git"))) {
+        return {
+            ok: false,
+            error: "git is required for review-tickets' parent-fetch-once base-branch pin (BAPI-474) but was not " +
+                "found on PATH. Install git, or rerun with --no-refresh-base to skip the fetch and evaluate in-place.",
+        };
+    }
     if (deps.platform === "darwin") {
         if (await isCommandOnPath(deps, "osascript"))
             return { ok: true };
@@ -355,10 +488,10 @@ export async function runReviewTicketsPreflight(deps, options) {
 // ---------------------------------------------------------------------------
 // Plan rows + orchestration
 // ---------------------------------------------------------------------------
-export function buildReviewPlanRows(deps, options, agent, status, overrides = {}) {
+export function buildReviewPlanRows(deps, options, agent, status, overrides = {}, baseContext = NO_BASE_CONTEXT) {
     return options.keys.map((key) => {
         const mode = resolveEffectiveReviewMode(key, options);
-        const baseCommand = buildReviewAgentShellCommand(agent, key, mode, deps.platform, deps.cwd, options.modelAlias);
+        const baseCommand = buildReviewAgentShellCommand(agent, key, mode, deps.platform, deps.cwd, options.modelAlias, baseContext);
         let command = baseCommand;
         let runId;
         if (options.epic) {
@@ -379,6 +512,14 @@ export function buildReviewPlanRows(deps, options, agent, status, overrides = {}
         };
     });
 }
+/** Build a dry-run preview base context from parsed CLI options only — never fetches. */
+function previewBaseContextFromOptions(options) {
+    if (options.noRefreshBase)
+        return { noRefreshBase: true };
+    if (options.baseBranch)
+        return { baseBranch: options.baseBranch, noRefreshBase: false };
+    return NO_BASE_CONTEXT;
+}
 export async function orchestrateReviewTickets(deps, options, overrides = {}) {
     const agent = resolveAgentSpec(options.agentName);
     if (!agent) {
@@ -395,7 +536,9 @@ export async function orchestrateReviewTickets(deps, options, overrides = {}) {
                     "and would be re-claimed for each key in the batch. Call orchestrateReviewTickets once per ticket instead.",
             };
         }
-        const rows = buildReviewPlanRows(deps, options, agent, "dry-run", overrides);
+        // --dry-run never performs the base-branch fetch (side-effect-free preview);
+        // it reflects only what the user explicitly passed on the CLI.
+        const rows = buildReviewPlanRows(deps, options, agent, "dry-run", overrides, previewBaseContextFromOptions(options));
         return { ok: true, rows };
     }
     const preflight = await runReviewTicketsPreflight(deps, options);
@@ -411,10 +554,21 @@ export async function orchestrateReviewTickets(deps, options, overrides = {}) {
                 "and would be re-claimed for each key in the batch. Call orchestrateReviewTickets once per ticket instead.",
         };
     }
+    // BAPI-474 D-3: parent-fetch-once — resolve ONE base_branch/base_sha pin for
+    // the whole batch before any tab is spawned. D-4: on failure (and no
+    // --no-refresh-base), fail loud with a bordered diagnostic and halt the
+    // fan-out entirely rather than silently grounding in place.
+    const resolveContext = overrides.resolveBaseContext ?? resolveBatchBaseContext;
+    const baseContextResult = await resolveContext(deps, options);
+    if (!baseContextResult.ok) {
+        console.error(formatBaseFetchFailureBox(baseContextResult.baseBranch, baseContextResult.error));
+        return { ok: false, error: baseContextResult.error };
+    }
+    const baseContext = baseContextResult.context;
     const terminal = detectTerminal(undefined, deps.env);
     const rows = await runWithConcurrency(options.keys, options.maxParallel, async (key) => {
         const mode = resolveEffectiveReviewMode(key, options);
-        const baseShellCommand = buildReviewAgentShellCommand(agent, key, mode, deps.platform, deps.cwd, options.modelAlias);
+        const baseShellCommand = buildReviewAgentShellCommand(agent, key, mode, deps.platform, deps.cwd, options.modelAlias, baseContext);
         let shellCommand = baseShellCommand;
         let runId;
         if (options.epic) {
@@ -565,7 +719,7 @@ export async function runReviewTicketsCli(argv, overrides = {}) {
             errorLog(`Error: Unknown agent: '${options.agentName}'. Valid agents: ${formatValidAgentNames()}.`);
             return 1;
         }
-        const rows = buildReviewPlanRows(deps, options, agent, "dry-run", overrides.orchestrateOverrides);
+        const rows = buildReviewPlanRows(deps, options, agent, "dry-run", overrides.orchestrateOverrides, previewBaseContextFromOptions(options));
         for (const row of rows) {
             log(`DRY-RUN: ${row.key} -> ${row.command}`);
         }

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

@@ -2,10 +2,11 @@
  * SFCC site-preference introspection read tools (BAPI-403, T6 — optional).
  *
  * Implements:
- *   site_preference_get    — GET  /site_preferences/preference_groups/{group}/{instance}
- *   site_preference_search — POST /site_preferences/preference_groups/{group}/{instance}/preference_search
+ *   site_preference_group_list — GET  /system_object_definitions/SitePreferences/attribute_groups
+ *   site_preference_get        — match-all POST /site_preferences/preference_groups/{group}/{instance}/preference_search
+ *   site_preference_search     — POST /site_preferences/preference_groups/{group}/{instance}/preference_search
  *
- * Both tools are read-only, run behind the T1 call-time gate, and route
+ * All three tools are read-only, run behind the T1 call-time gate, and route
  * oversized payloads through the sfcc/output.ts truncate-and-save seam.
  *
  * NOTE: SCAPI Preferences API (sfcc.preferences) is intentionally NOT used.
@@ -35,20 +36,24 @@ const INSTANCE_ENUM = z.enum(["staging", "development", "sandbox", "production"]
 const INSTANCE_DESCRIBE = "OCAPI instance context. v1 supports the 'sandbox' context only; " +
     "any other value is rejected with a validation error. Defaults to 'sandbox'.";
 const sitePreferenceGetInput = z.object({
-    group: z.string().describe("Preference group ID, e.g. 'Account' or 'General'."),
+    group: z.string().describe("Custom site preference group ID, e.g. 'LLMIntegration'."),
     instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),
     start: z.number().optional().describe("Zero-based offset for paging."),
     count: z.number().optional().describe("Maximum number of preferences to return."),
 });
 const sitePreferenceSearchInput = z.object({
-    group: z.string().describe("Preference group ID to search within."),
+    group: z.string().describe("Custom site preference group ID to search within, e.g. 'LLMIntegration'."),
     instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),
-    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. Pass a plain string for text search across preference ids and values, " +
+    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. Pass a plain string for text search across preference ids, " +
         "or a structured OCAPI query object (term_query, filtered_query, etc.)."),
     start: z.number().optional().describe("Zero-based offset for paging."),
     count: z.number().optional().describe("Maximum number of results to return."),
     sorts: z.array(z.any()).optional().describe("Array of OCAPI sort descriptors."),
 });
+const sitePreferenceGroupListInput = z.object({
+    count: z.number().optional().describe("Maximum number of site preference groups to return."),
+    start: z.number().optional().describe("Zero-based offset for paging."),
+});
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -86,15 +91,14 @@ export function buildSitePreferenceGetHandler(gateDeps, getDocsDir) {
         if (guard)
             return guard;
         const encodedGroup = encodeURIComponent(group);
-        const queryParams = {};
+        const postBody = {
+            query: { match_all_query: {} },
+        };
         if (start !== undefined)
-            queryParams.start = String(start);
+            postBody.start = start;
         if (count !== undefined)
-            queryParams.count = String(count);
-        const queryStr = Object.keys(queryParams).length > 0
-            ? "?" + new URLSearchParams(queryParams).toString()
-            : "";
-        const result = await ocapiGet(`/site_preferences/preference_groups/${encodedGroup}/${instance}${queryStr}`, credentials);
+            postBody.count = count;
+        const result = await ocapiPost(`/site_preferences/preference_groups/${encodedGroup}/${instance}/preference_search`, postBody, credentials);
         if (!result.ok) {
             return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
         }
@@ -113,7 +117,7 @@ export function buildSitePreferenceSearchHandler(gateDeps, getDocsDir) {
         const encodedGroup = encodeURIComponent(group);
         // Coerce plain string queries into OCAPI text_query shape
         const resolvedQuery = typeof query === "string"
-            ? { text_query: { fields: ["id", "value"], search_phrase: query } }
+            ? { text_query: { fields: ["id"], search_phrase: query } }
             : query;
         const postBody = { query: resolvedQuery };
         if (start !== undefined)
@@ -132,25 +136,54 @@ export function buildSitePreferenceSearchHandler(gateDeps, getDocsDir) {
         return saveAndReturn(text, dir, `site-preference-search-${safeGroup(group)}-${safeTimestamp()}.json`);
     });
 }
+export function buildSitePreferenceGroupListHandler(gateDeps, getDocsDir) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        const { count, start } = sitePreferenceGroupListInput.parse(args);
+        const queryParams = {};
+        if (count !== undefined)
+            queryParams.count = String(count);
+        if (start !== undefined)
+            queryParams.start = String(start);
+        const queryStr = Object.keys(queryParams).length > 0
+            ? "?" + new URLSearchParams(queryParams).toString()
+            : "";
+        const result = await ocapiGet(`/system_object_definitions/SitePreferences/attribute_groups${queryStr}`, credentials);
+        if (!result.ok) {
+            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+        }
+        const normalized = normalizeOcapiBody(result.body);
+        const text = JSON.stringify(normalized, null, 2);
+        const dir = path.join(await getDocsDir(), "sfcc");
+        return saveAndReturn(text, dir, `site-preference-group-list-${safeTimestamp()}.json`);
+    });
+}
 /**
- * Register the two SFCC site-preference introspection read tools.
+ * Register the three SFCC site-preference introspection read tools.
  *
  * Called from `registerSfccTools` — no direct `index.ts` edits needed.
  */
 export function registerSitePreferenceTools(registerTool, deps) {
     const { gateDeps, getDocsDir } = deps;
+    registerTool("site_preference_group_list", {
+        description: "List custom site preference group ids from the developer sandbox via " +
+            "GET /system_object_definitions/SitePreferences/attribute_groups. Read-only; " +
+            "use this to discover group ids before site_preference_get or site_preference_search. " +
+            "Accepts optional `count` and `start` for paging. Oversized outputs are auto-saved locally.",
+        inputSchema: sitePreferenceGroupListInput,
+        annotations: READ_ANNOTATIONS,
+    }, buildSitePreferenceGroupListHandler(gateDeps, getDocsDir));
     registerTool("site_preference_get", {
         description: "Read effective preferences for a site preference group from the developer sandbox " +
-            "via GET /site_preferences/preference_groups/{group}/sandbox. Read-only; v1 supports " +
-            "sandboxes only (non-sandbox instances are rejected). Accepts optional `start` and " +
-            "`count` for paging. Oversized payloads are auto-saved locally and previewed inline.",
+            "via a match-all POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
+            "Read-only, sandbox-only. Accepts optional `start`/`count` paging in the POST body. " +
+            "Oversized payloads are auto-saved locally.",
         inputSchema: sitePreferenceGetInput,
         annotations: READ_ANNOTATIONS,
     }, buildSitePreferenceGetHandler(gateDeps, getDocsDir));
     registerTool("site_preference_search", {
         description: "Search/filter preferences within a site preference group from the developer sandbox " +
             "via POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
-            "Read-only; v1 sandbox only. Pass a plain string for text search or a structured " +
+            "Read-only; v1 sandbox only. Pass a plain string for id-only text search or a structured " +
             "OCAPI query object. Oversized results are auto-saved locally.",
         inputSchema: sitePreferenceSearchInput,
         annotations: READ_ANNOTATIONS,

package/build/start-tickets-conductor.js

@@ -20,8 +20,9 @@
  * metadata, or the shell command string.
  */
 import { randomBytes } from "node:crypto";
-import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { mergeClaudeSettingsWithCommandHook, detectExistingPreToolUseMatcher, provisionClaudeSettingsForWorktree, DEFAULT_PRE_TOOL_USE_MATCHER, } from "./claude-settings.js";
+import { normalizeDeclaredTouchedFiles } from "./conductor/file-scope-guard.js";
 import { resolveProfiles } from "./mcp-profile.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 // ---------------------------------------------------------------------------
@@ -54,15 +55,22 @@ export function mintStartTicketsWorkerId(ticketKey, agentName, fragment = random
 }
 /**
  * Build the secret-free epic identity env keys from an {@link EpicDispatchIdentity}.
- * Strict allowlist — constructs a FRESH object with exactly three named keys,
- * never copies arbitrary parent env so credentials cannot leak.
+ * Strict allowlist — constructs a FRESH object with only named conductor keys,
+ * never copies arbitrary parent env so credentials cannot leak. The declared
+ * touched-file set (BAPI-507 N-2) is included as compact JSON ONLY when it
+ * normalizes to a non-empty repo-relative set.
  */
 export function buildEpicIdentityEnv(epic) {
-    return {
+    const env = {
         BAPI_CONDUCTOR_EPIC_KEY: epic.epic_key,
         BAPI_CONDUCTOR_EPIC_RUN_ID: epic.epic_run_id,
         BAPI_CONDUCTOR_PLAN_VERSION: String(epic.plan_version),
     };
+    const declared = normalizeDeclaredTouchedFiles(epic.declared_touched_files);
+    if (declared.length > 0) {
+        env.BAPI_CONDUCTOR_DECLARED_TOUCHED_FILES_JSON = JSON.stringify(declared);
+    }
+    return env;
 }
 // ---------------------------------------------------------------------------
 // Conductor context
@@ -108,6 +116,10 @@ export async function createStartTicketsConductorContext(options, agent, deps) {
         supervisorMode,
         agentName: agent.name,
         cliFile: resolveBinPath("conductor-bin.js"),
+        // Capture the conductor process's Node executable so dispatched workers run
+        // conductor-bin.js under THIS runtime (which owns the ledger), never the
+        // worker's own Node (BAPI-527).
+        conductorNodePath: deps.execPath ?? process.execPath,
         hookBinPath: resolveBinPath("conductor-claude-hook-bin.js"),
     };
     if (options.epic) {
@@ -159,6 +171,10 @@ export function buildConductorWorkerEnv(context, worker, parentEnv) {
         BAPI_CONDUCTOR_GATE_NAME: context.gateName,
         BAPI_CONDUCTOR_SUPERVISOR_MODE: context.supervisorMode,
         BAPI_CONDUCTOR_CLI_FILE: context.cliFile,
+        // BAPI-527: the CLI file + Node runtime are a PAIR. The worker runs
+        // conductor-bin.js under this captured conductor Node for every worker-side
+        // ledger op, so the worker Node never loads better-sqlite3. Non-secret.
+        CONDUCTOR_NODE_PATH: context.conductorNodePath,
     };
     if (context.repoName) {
         env.BAPI_CONDUCTOR_REPO_NAME = context.repoName;
@@ -182,15 +198,25 @@ export function buildConductorWorkerEnv(context, worker, parentEnv) {
 // ---------------------------------------------------------------------------
 // Claude hook settings merge / provisioning
 // ---------------------------------------------------------------------------
-/** Claude lifecycle events always registered for the conductor hook. */
+/**
+ * Claude lifecycle events always registered for the conductor hook.
+ *
+ * BAPI-507 (N-1): `Stop` and `SubagentStop` are deliberately NOT registered.
+ * They are per-turn / per-subagent events (verified against the Claude Code
+ * lifecycle-hook contract), so registering them emitted a `run.stopped` on every
+ * turn and folded the ticket to `ready_for_review` while it was still being
+ * implemented. `SessionEnd` is the one true session-terminal event and is the
+ * only session-end signal registered here.
+ */
 export const CONDUCTOR_HOOK_LIFECYCLE_EVENTS = [
     "SessionStart",
-    "Stop",
-    "SubagentStop",
+    "SessionEnd",
     "Notification",
 ];
-/** Broad matcher used for `PreToolUse` when no existing matcher is present. */
-export const DEFAULT_PRE_TOOL_USE_MATCHER = "*";
+// BAPI-534: the broad PreToolUse matcher and generic hook-merge machinery now
+// live in `claude-settings.ts` (shared with the executor deny-layer path).
+// Re-exported so existing importers of this name keep resolving.
+export { DEFAULT_PRE_TOOL_USE_MATCHER };
 /** Shell-quote a path for embedding in a hook command string. */
 function shellQuotePath(value) {
     // Single-quote for POSIX safety; embedded single quotes are escaped. Hook
@@ -208,55 +234,15 @@ export function resolveConductorHookCommand(env, hookBinPath, execPath = process
     }
     return `${shellQuotePath(execPath)} ${shellQuotePath(hookBinPath)}`;
 }
-function asHookEntries(value) {
-    return Array.isArray(value) ? value : [];
-}
-/** Does this event already register `command` as a command hook? */
-function entriesContainCommand(entries, command) {
-    return entries.some((entry) => Array.isArray(entry?.hooks) &&
-        entry.hooks.some((h) => h && h.type === "command" && h.command === command));
-}
 /**
- * Merge conductor lifecycle hooks into an existing Claude settings object
- * WITHOUT removing any existing settings or hooks. Idempotent: re-applying the
- * same command never duplicates an entry. `PreToolUse` is registered only when
- * `enablePreToolUse` is true, mirroring any existing matcher style.
+ * Merge conductor lifecycle hooks into an existing Claude settings object.
+ * BAPI-534: a thin wrapper over the generic {@link mergeClaudeSettingsWithCommandHook}
+ * bound to the conductor lifecycle events — preserving the exported signature and
+ * behavior (idempotent; `PreToolUse` only when `enablePreToolUse`; mirrors any
+ * existing matcher style; never removes existing settings/hooks).
  */
 export function mergeClaudeSettingsWithConductorHook(settings, command, options = {}) {
-    const existingHooks = settings.hooks !== null && typeof settings.hooks === "object" && !Array.isArray(settings.hooks)
-        ? settings.hooks
-        : {};
-    const hooks = { ...existingHooks };
-    const events = [...CONDUCTOR_HOOK_LIFECYCLE_EVENTS];
-    if (options.enablePreToolUse) {
-        events.push("PreToolUse");
-    }
-    for (const event of events) {
-        const entries = asHookEntries(hooks[event]);
-        if (entriesContainCommand(entries, command)) {
-            // Idempotent: already registered for this event.
-            hooks[event] = entries;
-            continue;
-        }
-        const newEntry = { hooks: [{ type: "command", command }] };
-        if (event === "PreToolUse") {
-            newEntry.matcher = options.preToolUseMatcher ?? DEFAULT_PRE_TOOL_USE_MATCHER;
-        }
-        hooks[event] = [...entries, newEntry];
-    }
-    return { ...settings, hooks };
-}
-/** Detect an existing PreToolUse matcher to mirror, if any. */
-function detectExistingPreToolUseMatcher(settings) {
-    const hooks = settings.hooks;
-    if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks))
-        return undefined;
-    const entries = asHookEntries(hooks.PreToolUse);
-    for (const entry of entries) {
-        if (typeof entry?.matcher === "string")
-            return entry.matcher;
-    }
-    return undefined;
+    return mergeClaudeSettingsWithCommandHook(settings, command, CONDUCTOR_HOOK_LIFECYCLE_EVENTS, options);
 }
 /**
  * Provision the conductor Claude hook into ONE worktree's
@@ -265,52 +251,14 @@ function detectExistingPreToolUseMatcher(settings) {
  * pretty-printed JSON, mirroring any existing PreToolUse matcher.
  */
 export async function provisionConductorHookForWorktree(worktreePath, command, options, deps) {
-    const claudeDir = path.join(worktreePath, ".claude");
-    const settingsPath = path.join(claudeDir, "settings.local.json");
-    let existing = {};
-    let raw = null;
-    try {
-        raw = await deps.readFile(settingsPath);
-    }
-    catch {
-        // Missing file -> treat as empty settings.
-        raw = null;
-    }
-    if (raw !== null) {
-        try {
-            const parsed = JSON.parse(raw);
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                return {
-                    ok: false,
-                    reason: "malformed",
-                    error: "existing .claude/settings.local.json is not a JSON object",
-                };
-            }
-            existing = parsed;
-        }
-        catch {
-            // Malformed JSON: fail the row rather than clobber the user's file. The
-            // error is generic — it never echoes the file contents.
-            return {
-                ok: false,
-                reason: "malformed",
-                error: "existing .claude/settings.local.json contains invalid JSON",
-            };
-        }
-    }
-    const merged = mergeClaudeSettingsWithConductorHook(existing, command, {
+    // BAPI-534: delegate the malformed-safe read/merge/write to the shared
+    // `provisionClaudeSettingsForWorktree`, supplying a conductor-hook merge
+    // closure. The returned `{ ok, reason, error }` shape is identical to
+    // ConductorHookProvisionResult, so the mapping is a pass-through.
+    return provisionClaudeSettingsForWorktree(worktreePath, (existing) => mergeClaudeSettingsWithConductorHook(existing, command, {
         enablePreToolUse: options.enablePreToolUse,
         preToolUseMatcher: options.preToolUseMatcher ?? detectExistingPreToolUseMatcher(existing),
-    });
-    try {
-        await deps.mkdir(claudeDir, { recursive: true });
-        await deps.writeFile(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
-    }
-    catch {
-        // Best-effort: a write/mkdir failure must not block the actual work.
-        return { ok: false, reason: "io", error: "failed to write .claude/settings.local.json" };
-    }
-    return { ok: true };
+    }), deps);
 }
 /**
  * Provision conductor identity across rows. Attaches `runId` to EVERY row (so