@bridge_gpt/mcp-server 0.2.14 → 0.2.18

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/permissions.js

@@ -27,7 +27,19 @@ const OCAPI_SETTINGS_READ_ONLY = (ocapiVersion) => JSON.stringify({
                 },
                 {
                     resource_id: "/system_object_definitions/**",
-                    methods: ["get"],
+                    methods: ["get", "post"],
+                    read_attributes: "(**)",
+                    write_attributes: "(**)",
+                },
+                {
+                    resource_id: "/site_preferences/**",
+                    methods: ["get", "post"],
+                    read_attributes: "(**)",
+                    write_attributes: "(**)",
+                },
+                {
+                    resource_id: "/custom_object_definitions/**",
+                    methods: ["get", "post"],
                     read_attributes: "(**)",
                     write_attributes: "(**)",
                 },

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

@@ -2,18 +2,23 @@
  * SFCC custom-object-definition introspection read tools (BAPI-402, T4–T5).
  *
  * Implements:
- *   custom_object_definition_list — GET  /custom_object_definitions
- *   custom_object_definition_get  — GET  /custom_object_definitions/{type}
+ *   custom_object_definition_attributes_get      — GET  /custom_object_definitions/{type}/attribute_definitions
+ *   custom_object_definition_attribute_search    — POST /custom_object_definitions/{type}/attribute_definition_search
  *
  * Both tools are read-only, run behind the T1 call-time gate, and route
  * oversized payloads through the sfcc/output.ts truncate-and-save seam.
  *
+ * OCAPI's CustomObjectDefinitions resource only exposes operations scoped to
+ * a known object_type — there is no top-level list and no bare get-by-type
+ * (unlike SystemObjectDefinitions). A caller-supplied object_type is always
+ * required; OCAPI cannot enumerate custom object types.
+ *
  * Note: custom object TYPE creation/update is NOT available via OCAPI REST.
  * It is a v2 metadata-import capability (metadata XML → WebDAV → import job).
  */
 import path from "path";
 import { z } from "zod";
-import { ocapiGet } from "./client.js";
+import { ocapiGet, ocapiPost } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
 import { normalizeOcapiBody } from "./ocapi-shape.js";
 import { truncateAndSaveIfNeeded } from "./output.js";
@@ -29,14 +34,22 @@ const READ_ANNOTATIONS = {
 // ---------------------------------------------------------------------------
 // Input schemas
 // ---------------------------------------------------------------------------
-const customObjectListInput = z.object({
-    count: z.number().optional().describe("Maximum number of custom object types to return."),
-    start: z.number().optional().describe("Zero-based offset for paging."),
+const customObjectAttributesGetInput = z.object({
+    object_type: z
+        .string()
+        .describe('Known custom object type identifier, e.g. a custom type id starting with "c_". ' +
+        "OCAPI cannot enumerate custom object types — the type must already be known."),
 });
-const customObjectGetInput = z.object({
+const customObjectAttributeSearchInput = z.object({
     object_type: z
         .string()
-        .describe('Custom object type identifier, e.g. "GiftCertificate" or a custom type id starting with "c_".'),
+        .describe('Known custom object type to search within, e.g. a custom type id starting with "c_". ' +
+        "OCAPI cannot enumerate custom object types — the type must already be known."),
+    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. Pass a plain string for a text search across id and display_name, " +
+        "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."),
 });
 // ---------------------------------------------------------------------------
 // Helpers
@@ -57,39 +70,43 @@ async function saveAndReturn(text, dir, filename) {
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
-function buildCustomObjectListHandler(gateDeps, getDocsDir) {
+function buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir) {
     return withSfccGate(gateDeps, async (args, credentials) => {
-        const { count, start } = customObjectListInput.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(`/custom_object_definitions${queryStr}`, credentials);
+        const { object_type } = customObjectAttributesGetInput.parse(args);
+        const encodedType = encodeURIComponent(object_type);
+        const result = await ocapiGet(`/custom_object_definitions/${encodedType}/attribute_definitions`, 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, `custom-object-def-list-${safeTimestamp()}.json`);
+        return saveAndReturn(text, dir, `custom-object-def-attributes-${safeType(object_type)}-${safeTimestamp()}.json`);
     });
 }
-function buildCustomObjectGetHandler(gateDeps, getDocsDir) {
+function buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir) {
     return withSfccGate(gateDeps, async (args, credentials) => {
-        const { object_type } = customObjectGetInput.parse(args);
+        const { object_type, query, start, count, sorts } = customObjectAttributeSearchInput.parse(args);
         const encodedType = encodeURIComponent(object_type);
-        const result = await ocapiGet(`/custom_object_definitions/${encodedType}`, credentials);
+        // Coerce plain string queries into OCAPI text_query shape
+        const resolvedQuery = typeof query === "string"
+            ? { text_query: { fields: ["id", "display_name"], search_phrase: query } }
+            : query;
+        const postBody = { query: resolvedQuery };
+        if (start !== undefined)
+            postBody.start = start;
+        if (count !== undefined)
+            postBody.count = count;
+        if (sorts !== undefined)
+            postBody.sorts = sorts;
+        const result = await ocapiPost(`/custom_object_definitions/${encodedType}/attribute_definition_search`, postBody, 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, `custom-object-def-${safeType(object_type)}-${safeTimestamp()}.json`);
+        return saveAndReturn(text, dir, `custom-object-def-search-${safeType(object_type)}-${safeTimestamp()}.json`);
     });
 }
 /**
@@ -99,21 +116,21 @@ function buildCustomObjectGetHandler(gateDeps, getDocsDir) {
  */
 export function registerSfccCustomObjectDefReadTools(registerTool, deps) {
     const { gateDeps, getDocsDir } = deps;
-    registerTool("custom_object_definition_list", {
-        description: "List all custom object type definitions from the developer sandbox via " +
-            "GET /custom_object_definitions. Read-only introspection; type definitions cannot be created " +
-            "or updated via OCAPI (v2 metadata-import only). " +
-            "Optional `count` and `start` for paging. Oversized outputs auto-saved locally.",
-        inputSchema: customObjectListInput,
+    registerTool("custom_object_definition_attributes_get", {
+        description: "Retrieve attribute definitions for a KNOWN custom object type via " +
+            "GET /custom_object_definitions/{type}/attribute_definitions. " +
+            "OCAPI cannot enumerate types — object_type is required. " +
+            "Type creation is v2 metadata-import only, not OCAPI. Oversized payloads auto-saved locally.",
+        inputSchema: customObjectAttributesGetInput,
         annotations: READ_ANNOTATIONS,
-    }, buildCustomObjectListHandler(gateDeps, getDocsDir));
-    registerTool("custom_object_definition_get", {
-        description: "Retrieve an EXISTING custom object type from the developer sandbox via " +
-            "GET /custom_object_definitions/{type}. " +
-            "Returns the type with key_definition and attribute_definitions/attribute_groups. " +
-            "Read-only introspection; type definitions cannot be created or updated via OCAPI " +
-            "(v2 metadata-import only). Oversized payloads auto-saved locally.",
-        inputSchema: customObjectGetInput,
+    }, buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir));
+    registerTool("custom_object_definition_attribute_search", {
+        description: "Search attribute definitions within a KNOWN custom object type via " +
+            "POST /custom_object_definitions/{type}/attribute_definition_search. " +
+            "OCAPI cannot enumerate types — object_type is required. " +
+            "Pass a string or structured OCAPI query. Type creation is v2 metadata-import only. " +
+            "Oversized results auto-saved locally.",
+        inputSchema: customObjectAttributeSearchInput,
         annotations: READ_ANNOTATIONS,
-    }, buildCustomObjectGetHandler(gateDeps, getDocsDir));
+    }, buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir));
 }

package/build/sfcc/register.js

@@ -59,7 +59,7 @@ export function registerSfccTools(registerTool, deps) {
             gateDeps,
             getDocsDir: deps.getDocsDir,
         });
-        // custom_object_definition_list, custom_object_definition_get (BAPI-402 T4–T5)
+        // custom_object_definition_attributes_get, custom_object_definition_attribute_search (BAPI-402 T4–T5)
         registerSfccCustomObjectDefReadTools(registerTool, {
             gateDeps,
             getDocsDir: deps.getDocsDir,

package/build/sfcc/tool-wrapper.js

@@ -58,7 +58,11 @@ export function withSfccGate(deps, handler) {
                 `Update the version field in your Bridge API project settings.`);
         }
         // (c) Resolve credentials from dw.json
-        const explicitHostname = typeof args.instance === "string" ? args.instance : undefined;
+        // A hostname always contains a dot; the OCAPI instance-context enum
+        // (e.g. "sandbox") never does — only treat args.instance as an explicit
+        // hostname override when it looks like one.
+        const rawInstance = typeof args.instance === "string" ? args.instance : undefined;
+        const explicitHostname = rawInstance && rawInstance.includes(".") ? rawInstance : undefined;
         const credResult = await resolveSfccCredentials(explicitHostname);
         if (!credResult.ok) {
             return notConfigured("missing-dw-json", `SFCC credential resolution failed: ${credResult.error} ` +

package/build/start-tickets-conductor.js

@@ -22,6 +22,7 @@
 import { randomBytes } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+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
@@ -182,11 +190,19 @@ 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. */