@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/build/sfcc/permissions.js

@@ -8,14 +8,15 @@
  */
 import { ocapiGet } from "./client.js";
 import { normalizeOcapiPage } from "./ocapi-shape.js";
-import { DEFAULT_OCAPI_VERSION } from "./config.js";
+import { DEFAULT_OCAPI_VERSION, OCAPI_SETTINGS_STRUCTURE_VERSION } from "./config.js";
+import { formatSafeHost } from "./hostname.js";
 import { formatOcapiWriteGrantJson } from "./write-grants.js";
 // ---------------------------------------------------------------------------
 // OCAPI Settings JSON template
 // Operators paste this in: Administration > Site Development > Open Commerce API Settings → Data API tab.
 // ---------------------------------------------------------------------------
-const OCAPI_SETTINGS_READ_SEARCH = (ocapiVersion) => JSON.stringify({
-    _v: ocapiVersion,
+const OCAPI_SETTINGS_READ_SEARCH = () => JSON.stringify({
+    _v: OCAPI_SETTINGS_STRUCTURE_VERSION,
     clients: [
         {
             client_id: "<YOUR_CLIENT_ID>",
@@ -52,8 +53,9 @@ const OCAPI_SETTINGS_READ_SEARCH = (ocapiVersion) => JSON.stringify({
 // JSON printed here is byte-identical to what future write handlers echo on a
 // 403. This now covers all required write resource families:
 // /system_object_definitions, /system_object_definitions/**,
-// /custom_object_definitions/**, and /site_preferences/**.
-const OCAPI_SETTINGS_WRITE_IMPORT = (ocapiVersion) => formatOcapiWriteGrantJson(ocapiVersion);
+// /custom_object_definitions/**, and the site-scoped /sites/*/site_preferences/**
+// (the org-level /site_preferences/** above stays read/search only).
+const OCAPI_SETTINGS_WRITE_IMPORT = () => formatOcapiWriteGrantJson();
 // ---------------------------------------------------------------------------
 // Tool implementation
 // ---------------------------------------------------------------------------
@@ -75,7 +77,7 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
                 {
                     type: "text",
                     text: `OCAPI probe failed: ${msg}\n\n` +
-                        ocapiSettingsInstructions(ocapiVersion),
+                        ocapiSettingsInstructions(),
                 },
             ],
         };
@@ -86,8 +88,10 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
             content: [
                 {
                     type: "text",
-                    text: `✓ OCAPI access confirmed.\n` +
-                        `  Instance: ${credentials.hostname.split(".")[0]}\n` +
+                    text: `✓ OCAPI read access confirmed (GET /system_object_definitions). ` +
+                        `Write access is not probed; the sfcc-write tools need the mutation grant — ` +
+                        `run check_permissions after a 403 or see SFCC-SETUP-CHECKLIST.md.\n` +
+                        `  Instance: ${formatSafeHost(credentials.hostname)}\n` +
                         `  OCAPI version: ${ocapiVersion}\n` +
                         `  GET /system_object_definitions: ${formatProbeCount(normalized)}`,
                 },
@@ -99,8 +103,8 @@ export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_O
             content: [
                 {
                     type: "text",
-                    text: `HTTP ${result.status}: OCAPI access denied for instance ${credentials.hostname.split(".")[0]}.\n\n` +
-                        ocapiSettingsInstructions(ocapiVersion),
+                    text: `HTTP ${result.status}: OCAPI access denied for instance ${formatSafeHost(credentials.hostname)}.\n\n` +
+                        ocapiSettingsInstructions(),
                 },
             ],
         };
@@ -157,13 +161,13 @@ function formatProbeCount(normalized) {
  * A label that understates a grant is worse than no label, because the operator
  * stops reading the JSON once the heading has told them it is safe.
  */
-function ocapiSettingsInstructions(ocapiVersion) {
+function ocapiSettingsInstructions() {
     return (`To grant OCAPI access, paste the JSON below in Business Manager:\n` +
         `  Administration > Site Development > Open Commerce API Settings → Data API tab\n\n` +
         `--- READ/SEARCH TOOL GRANTS (required for the sfcc read tools) ---\n` +
-        `${OCAPI_SETTINGS_READ_SEARCH(ocapiVersion)}\n\n` +
+        `${OCAPI_SETTINGS_READ_SEARCH()}\n\n` +
         `--- MUTATION GRANTS (required for the nine sfcc-write tools) ---\n` +
-        `${OCAPI_SETTINGS_WRITE_IMPORT(ocapiVersion)}\n\n` +
+        `${OCAPI_SETTINGS_WRITE_IMPORT()}\n\n` +
         `Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`);
 }
 /**

package/build/sfcc/register.js

@@ -89,7 +89,7 @@ export function registerSfccTools(registerTool, deps) {
         const gatedCheckPermissions = withSfccGate(gateDeps, async (_args, credentials) => checkPermissionsTool(credentials));
         registerSfccTool("check_permissions", {
             description: "Probe SFCC OCAPI access via GET /system_object_definitions. " +
-                "On 200: reports OK and the detected OCAPI version. " +
+                "On 200: reports read access OK and the detected OCAPI version. " +
                 "On 401/403: prints the exact OCAPI Settings JSON to paste in Business Manager " +
                 "(read/search and mutation grants).",
             inputSchema: z.object({

package/build/sfcc/tool-wrapper.js

@@ -65,6 +65,10 @@ import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
 import { publishSfccVersion } from "./tools-configured.js";
 import { resolveSfccCredentials } from "./credentials.js";
 import { formatSfccFailure } from "./sfcc-result.js";
+import { canonicalizeSfccHostname, formatSafeHost } from "./hostname.js";
+// `canonicalizeSfccHostname` moved to hostname.ts; re-exported so existing
+// importers of this module are unaffected.
+export { canonicalizeSfccHostname };
 // ---------------------------------------------------------------------------
 // Hostname policy
 // ---------------------------------------------------------------------------
@@ -108,47 +112,8 @@ export const APPROVED_SANDBOX_HOST_FORMS = [
     "<realm>-<nnn>.sandbox.dx.commercecloud.salesforce.com",
     "<realm>-<nnn>.dx.commercecloud.salesforce.com",
 ];
-/** One DNS label: 1–63 chars, alphanumeric, internal hyphens only. */
-const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 /** Form B's leading label: an SFCC realm id followed by a numeric instance. */
 const REALM_INSTANCE_LABEL = /^[a-z0-9]+-\d{3}$/;
-/**
- * Reduce a raw hostname to a canonical comparable form, or `null` if it is not
- * a bare hostname at all.
- *
- * Only DNS-equivalent normalization is applied — lowercasing and stripping a
- * single trailing root dot. Everything else is a rejection rather than a
- * repair: a value carrying a scheme, port, path, query, credentials, or
- * whitespace is not a hostname, and "cleaning it up" would mean guessing which
- * part the operator meant. Guessing is how a boundary gets bypassed, so this
- * returns `null` and the caller fails closed.
- */
-export function canonicalizeSfccHostname(raw) {
-    if (typeof raw !== "string")
-        return null;
-    let value = raw.trim().toLowerCase();
-    if (value.endsWith("."))
-        value = value.slice(0, -1);
-    if (value === "" || value.length > 253)
-        return null;
-    // Anything that is not strictly `label(.label)*` — scheme, port, path, query,
-    // userinfo, whitespace, IPv6 brackets, wildcards.
-    if (!/^[a-z0-9.-]+$/.test(value))
-        return null;
-    if (value.includes(".."))
-        return null;
-    const labels = value.split(".");
-    if (labels.length < 2)
-        return null;
-    if (!labels.every((label) => DNS_LABEL.test(label)))
-        return null;
-    // A bare IPv4 address is not a sandbox hostname and must not be canonicalized
-    // into one; the suffix check below would reject it anyway, but rejecting here
-    // keeps "is this a hostname?" and "is this host approved?" separate concerns.
-    if (/^\d+(\.\d+)*$/.test(value))
-        return null;
-    return value;
-}
 /**
  * Decide whether a canonical hostname is an approved developer sandbox.
  *
@@ -216,9 +181,9 @@ export function isApprovedSfccSandboxHost(canonical) {
  * raw `dw.json` contents never enter this envelope.
  */
 function targetNotSandbox(rejectedHostname) {
-    // A malformed value is echoed back bounded, so a pathological configuration
-    // value cannot inflate the response.
-    const safeRejected = rejectedHostname.length > 120 ? `${rejectedHostname.slice(0, 120)}…` : rejectedHostname;
+    // A valid host is echoed in full but bounded; anything that is not a bare
+    // hostname is replaced by a fixed label so arbitrary input is never echoed.
+    const safeRejected = formatSafeHost(rejectedHostname);
     return formatSfccFailure({
         code: "TARGET_NOT_SANDBOX",
         status: 403,
@@ -267,9 +232,19 @@ export function withSfccTargetBoundary(handler, deps = {}) {
         // actually returned.
         const rawInstance = typeof safeArgs.instance === "string" ? safeArgs.instance : undefined;
         const explicitHostname = rawInstance && rawInstance.includes(".") ? rawInstance : undefined;
+        // Refuse an unsafe explicit host BEFORE any credential lookup. The check
+        // below on the resolved host stays: this one only adds a refusal earlier, so
+        // an unknown host never reaches the resolver, and a host that resolution
+        // selects is still validated after it.
+        if (explicitHostname !== undefined) {
+            const explicitCanonical = canonicalizeSfccHostname(explicitHostname);
+            if (explicitCanonical === null || !isApprovedSfccSandboxHost(explicitCanonical)) {
+                return targetNotSandbox(explicitHostname);
+            }
+        }
         const credResult = await resolve(explicitHostname);
         if (!credResult.ok) {
-            return handler(safeArgs, { approved: false, error: credResult.error });
+            return handler(safeArgs, { approved: false, error: credResult.error, kind: credResult.kind });
         }
         const rawHostname = credResult.credentials.hostname;
         const canonical = canonicalizeSfccHostname(rawHostname);
@@ -334,6 +309,22 @@ function notConfigured(failureClass, message) {
         details: { failure_class: failureClass },
     });
 }
+/**
+ * Build the failure for a credential problem on a repository that IS set up.
+ *
+ * The repo has a `dw.json` (or the caller named an explicit instance), so the
+ * caller can fix the input. That is why this carries no `NO_RETRY_INSTRUCTION`
+ * and is a 400, not the 503 "not configured" envelope.
+ */
+function credentialResolutionFailed(message) {
+    return formatSfccFailure({
+        code: "CREDENTIAL_RESOLUTION_FAILED",
+        status: 400,
+        message,
+        source: "gate",
+        details: { failure_class: "credential-resolution" },
+    });
+}
 // ---------------------------------------------------------------------------
 // Gate
 // ---------------------------------------------------------------------------
@@ -402,6 +393,11 @@ export function withSfccGate(deps, handler) {
         // reaches here — the boundary already refused it — so the only remaining
         // case is credential resolution having failed outright.
         if (!target.approved) {
+            // Only a genuinely absent dw.json means "this repo is not set up for
+            // SFCC". Every other resolver failure is fixable by the caller.
+            if (target.kind !== undefined && target.kind !== "no-dw-json") {
+                return credentialResolutionFailed(target.error);
+            }
             return notConfigured("missing-dw-json", `SFCC credential resolution failed: ${target.error} ` +
                 "Ensure a dw.json file exists in your project root with " +
                 "hostname, client-id, and client-secret fields.");

package/build/sfcc/write-grants.js

@@ -13,6 +13,7 @@
  * where a caller can read it without parsing text and `result.isError === true`
  * still detects the failure.
  */
+import { OCAPI_SETTINGS_STRUCTURE_VERSION } from "./config.js";
 import { formatSfccWriteFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Write resource families
@@ -25,7 +26,7 @@ export const OCAPI_WRITE_RESOURCE_IDS = [
     "/system_object_definitions",
     "/system_object_definitions/**",
     "/custom_object_definitions/**",
-    "/site_preferences/**",
+    "/sites/*/site_preferences/**",
 ];
 /**
  * The exact HTTP methods each resource family needs, derived from the methods
@@ -50,27 +51,32 @@ export const OCAPI_WRITE_RESOURCE_IDS = [
  *                                    custom preference create.
  *   /custom_object_definitions/**    put, patch (+get for ETag) — attribute
  *                                    definition create/update.
- *   /site_preferences/**             patch (+get) — site_preference_values_set,
- *                                    a direct PATCH with no ETag round trip.
+ *   site-scoped site_preferences     patch (+get) — site_preference_values_set,
+ *                                    a direct PATCH with no ETag round trip on
+ *                                    the site-scoped resource (the org-level
+ *                                    /site_preferences/** is read/search only).
  */
 export const OCAPI_WRITE_RESOURCE_METHODS = {
     "/system_object_definitions": ["get"],
     "/system_object_definitions/**": ["get", "put", "patch"],
     "/custom_object_definitions/**": ["get", "put", "patch"],
-    "/site_preferences/**": ["get", "patch"],
+    "/sites/*/site_preferences/**": ["get", "patch"],
 };
 // ---------------------------------------------------------------------------
 // Grant JSON builders
 // ---------------------------------------------------------------------------
 /**
- * Build the OCAPI Settings write-grant object for the given version.
+ * Build the OCAPI Settings write-grant object.
+ *
+ * `_v` is the settings-structure version, never an OCAPI API version, so no
+ * caller can override it.
  *
  * The `clientIdPlaceholder` stays as `<YOUR_CLIENT_ID>` by default so the output
  * is safe to print and paste — the real resolved client_id is never substituted.
  */
-export function buildOcapiWriteGrantSettings(ocapiVersion, clientIdPlaceholder = "<YOUR_CLIENT_ID>") {
+export function buildOcapiWriteGrantSettings(clientIdPlaceholder = "<YOUR_CLIENT_ID>") {
     return {
-        _v: ocapiVersion,
+        _v: OCAPI_SETTINGS_STRUCTURE_VERSION,
         clients: [
             {
                 client_id: clientIdPlaceholder,
@@ -85,8 +91,8 @@ export function buildOcapiWriteGrantSettings(ocapiVersion, clientIdPlaceholder =
     };
 }
 /** Pretty-printed JSON string of the write-grant settings. */
-export function formatOcapiWriteGrantJson(ocapiVersion, clientIdPlaceholder = "<YOUR_CLIENT_ID>") {
-    return JSON.stringify(buildOcapiWriteGrantSettings(ocapiVersion, clientIdPlaceholder), null, 2);
+export function formatOcapiWriteGrantJson(clientIdPlaceholder = "<YOUR_CLIENT_ID>") {
+    return JSON.stringify(buildOcapiWriteGrantSettings(clientIdPlaceholder), null, 2);
 }
 // ---------------------------------------------------------------------------
 // 403 write-grant UX
@@ -115,7 +121,7 @@ export function ocapiWriteForbiddenMessage(operation, path) {
  * same way an OCAPI read fault body is preserved.
  */
 export function writeGrantForbiddenResult(params) {
-    const { operation, path, ocapiVersion, body } = params;
+    const { operation, path, body } = params;
     return formatSfccWriteFailure({
         code: "OCAPI_WRITE_ERROR",
         status: 403,
@@ -127,7 +133,7 @@ export function writeGrantForbiddenResult(params) {
             remediation: {
                 business_manager_path: OCAPI_WRITE_GRANT_BUSINESS_MANAGER_PATH,
                 instruction: OCAPI_WRITE_GRANT_CLIENT_ID_INSTRUCTION,
-                write_grant: buildOcapiWriteGrantSettings(ocapiVersion),
+                write_grant: buildOcapiWriteGrantSettings(),
             },
             ...(body === undefined ? {} : { body }),
         },

package/build/sfcc/write-result.js

@@ -16,7 +16,6 @@
  * pre-transport ones.
  */
 import { writeGrantForbiddenResult } from "./write-grants.js";
-import { DEFAULT_OCAPI_VERSION } from "./config.js";
 import { formatSfccWriteFailure } from "./sfcc-result.js";
 import { redactSfccBody } from "./read-body.js";
 /** Wrap text in the standard MCP text-result shape (success path only). */
@@ -72,12 +71,14 @@ function ocapiWriteFaultMessage(body, status) {
  * `Response.status` verbatim, so the reported status *is* the upstream status
  * and the shared formatter would rightly omit a duplicate.
  */
-export function formatOcapiWriteToolResult(result, operation, path, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+export function formatOcapiWriteToolResult(result, operation, path, 
+// Kept for call compatibility. It no longer reaches the grant JSON: `_v` there
+// is the settings-structure version, which an API version must not override.
+_ocapiVersion) {
     if (result.status === 403) {
         return writeGrantForbiddenResult({
             operation,
             path,
-            ocapiVersion,
             body: result.body,
         });
     }

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

@@ -2,9 +2,11 @@
  * SFCC site-preference value write tool (BAPI-584).
  *
  * Implements:
- *   site_preference_values_set — PATCH /site_preferences/preference_groups/{group}/sandbox
+ *   site_preference_values_set — PATCH /sites/{site_id}/site_preferences/preference_groups/{group}/sandbox
  *
- * Sets custom site-preference VALUES through the OCAPI Data API. Sandbox-only:
+ * Sets custom site-preference VALUES through the OCAPI Data API for ONE named
+ * site. `site_id` is required and is never derived from `dw.json`: a destructive
+ * write must not pick its target silently. Sandbox-only:
  * the value endpoint would otherwise accept `production`, so the `{instance}`
  * segment is forced to the `sandbox` literal AFTER the shared sandbox guard has
  * validated the requested instance. The body is a FLAT map of `c_`-prefixed
@@ -35,7 +37,17 @@ const INSTANCE_ENUM = z.enum(["staging", "development", "sandbox", "production"]
 // safeguard on the OCAPI route.
 const INSTANCE_DESCRIBE = "OCAPI instance context. v1 supports the 'sandbox' context only; any other " +
     "value is rejected before OCAPI is called.";
+// A site id is one URL path segment. This is a conservative single-segment
+// pattern (no separators, whitespace, or dots), not a claim about the full set
+// OCAPI allows; the exact constraint is confirmed by owner check OR-1.
+const SITE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+const SITE_ID_DESCRIBE = "Site id to write to; required, never defaulted. Not 'instance'.";
 const sitePreferenceValuesSetInput = z.object({
+    site_id: z
+        .string()
+        .min(1)
+        .regex(SITE_ID_PATTERN, "site_id must contain only letters, digits, '_' or '-'.")
+        .describe(SITE_ID_DESCRIBE),
     group: z.string().describe("Custom site preference group id, e.g. 'LLMIntegration'."),
     instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),
     values: sitePreferenceValuesPatchBodySchema.describe("Flat map of c_-prefixed preference ids to values (string, number, boolean, or string[])."),
@@ -44,12 +56,12 @@ const sitePreferenceValuesSetInput = z.object({
 // Path builder
 // ---------------------------------------------------------------------------
 /**
- * Build the site-preference group PATCH path. The `{instance}` segment is the
+ * Build the site-scoped site-preference group PATCH path. The `{instance}` segment is the
  * `sandbox` literal — a non-sandbox instance is rejected by the guard before
  * this is called, so a non-sandbox value can never leak into transport.
  */
-export function sitePreferenceGroupPath(group) {
-    return `/site_preferences/preference_groups/${encodedSegment(group)}/sandbox`;
+export function sitePreferenceGroupPath(siteId, group) {
+    return `/sites/${encodedSegment(siteId)}/site_preferences/preference_groups/${encodedSegment(group)}/sandbox`;
 }
 // ---------------------------------------------------------------------------
 // Handler
@@ -66,7 +78,7 @@ export function buildSitePreferenceValuesSetHandler(gateDeps) {
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard)
             return guard;
-        const path = sitePreferenceGroupPath(parsed.group);
+        const path = sitePreferenceGroupPath(parsed.site_id, parsed.group);
         const body = buildSitePreferenceValuesPatchPayload(parsed.values);
         try {
             // Direct PATCH (no ETag round trip): the value endpoint does not gate on
@@ -92,10 +104,10 @@ export const SITE_PREFERENCE_WRITE_TOOL_NAMES = ["site_preference_values_set"];
 export function registerSitePreferenceWriteTools(registerTool, deps) {
     const { gateDeps } = deps;
     registerTool("site_preference_values_set", {
-        description: "Set site-preference VALUES via PATCH /site_preferences/preference_groups/{group}/sandbox. " +
+        description: "Set site-preference VALUES via PATCH /sites/{site_id}/site_preferences/preference_groups/{group}/sandbox. " +
             "Preference must already be defined via custom_preference_definition_create. Sandbox-only, " +
             "destructive; flat c_-prefixed id→value map (string/number/boolean/string[]). " +
-            "Bad group → 404 CustomPreferenceGroupNotFoundException. 403 → paste-ready grant JSON.",
+            "Bad group → 404. 403 → paste-ready grant JSON.",
         inputSchema: sitePreferenceValuesSetInput,
         annotations: WRITE_ANNOTATIONS,
     }, buildSitePreferenceValuesSetHandler(gateDeps));

package/build/start-tickets-prereqs.js

@@ -17,6 +17,7 @@ import path from "path";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
+import { VERSION } from "./version.generated.js";
 import { probeWorktreeCommandAssets } from "./command-assets-doctor.js";
 import { MCP_SERVER_NAME, MCP_PACKAGE_NAME } from "./mcp-identity.js";
 // BAPI-941: both are LEAF modules (the pure classifier and its git-backed
@@ -159,7 +160,7 @@ const WORKTRUNK_INSTALL_HINTS = {
     linux: "See the Worktrunk documentation for Linux install instructions: https://worktrunk.dev",
 };
 const GIT_INSTALL_HINTS = {
-    darwin: "xcode-select --install (or brew install git)",
+    darwin: "xcode-select --install (or brew install git). Installing another Git does not ensure PATH selects it; verify with which git and git --version.",
     linux: "Install git with your distro package manager, e.g. apt install git",
     win32: "Install Git for Windows: https://git-scm.com/download/win",
 };
@@ -444,24 +445,19 @@ export function worktreeMcpReachabilityDescriptor() {
         },
     };
 }
-/**
- * Secret-free remediation hint shared by the worktree command-assets descriptor
- * (BAPI-664). Directs users to rerun start-tickets — the supported provisioning
- * workflow — rather than manually copying or committing the generated command
- * files, which are fill-only, never refreshed, and Git-excluded per worktree.
- */
-const WORKTREE_COMMAND_ASSETS_HINT = "Re-run start-tickets to provision the packaged Claude command assets " +
-    "(.claude/commands/) into this worktree. Do not manually copy or commit the " +
-    "generated command files — they are bootstrapped per worktree and Git-excluded.";
+/** Version-pinned fill-only repair; permissions and unsafe paths need their own fix. */
+const WORKTREE_COMMAND_ASSETS_HINT = `Run npx -y ${MCP_PACKAGE_NAME}@${VERSION} repair-assets --project-root <established-root> --host claude ` +
+    "to fill missing packaged files. Resolve permission/path/platform problems separately; refresh/reconnect and run doctor.";
+const WORKTREE_COMMAND_ASSETS_PROVISION_HINT = "In-place asset repair is not supported on this platform. Re-run start-tickets to provision the packaged Claude command assets (.claude/commands/) into this worktree. Existing files are preserved; refresh/reconnect and run doctor.";
 const WORKTREE_COMMAND_ASSETS_INSTALL_HINTS = {
-    darwin: WORKTREE_COMMAND_ASSETS_HINT,
+    darwin: WORKTREE_COMMAND_ASSETS_PROVISION_HINT,
     linux: WORKTREE_COMMAND_ASSETS_HINT,
-    win32: WORKTREE_COMMAND_ASSETS_HINT,
+    win32: WORKTREE_COMMAND_ASSETS_PROVISION_HINT,
 };
 /**
  * Doctor-only, strictly read-only probe: does the current worktree contain every
  * packaged Claude slash-command asset under `.claude/commands/`? Delegates to the
- * read-only {@link probeWorktreeCommandAssets} using only `deps.readFile`,
+ * read-only {@link probeWorktreeCommandAssets} using only `deps.commandAssetMetadata`,
  * `deps.platform`, and `deps.cwd`. Reports an unavailable diagnostic (never a
  * false "present") when the optional read-only filesystem boundary is absent. The
  * probe performs NO writes, Git calls, or process spawns.
@@ -472,15 +468,14 @@ export function worktreeCommandAssetsDescriptor() {
         label: "Worktree Claude command assets",
         installHint: WORKTREE_COMMAND_ASSETS_INSTALL_HINTS,
         probe: async (deps) => {
-            const { readFile } = deps;
-            if (!readFile) {
+            if (!deps.commandAssetMetadata) {
                 return {
                     found: false,
                     detail: "command-asset probe unavailable (no read-only filesystem access)",
                 };
             }
             const result = await probeWorktreeCommandAssets(deps.cwd, {
-                readFile,
+                metadata: deps.commandAssetMetadata,
                 platform: deps.platform,
             });
             return { found: result.found, detail: result.detail };
@@ -817,6 +812,7 @@ export function getDoctorOnlyPrereqDescriptors(_platform, _env, agent) {
     return [
         uvDescriptor(),
         agentDescriptor(agent),
+        gitCompatibilityDescriptor(),
         credentialResolutionDescriptor(),
         worktreeMcpReachabilityDescriptor(),
         worktreeCommandAssetsDescriptor(),
@@ -863,6 +859,7 @@ export async function probePrerequisite(deps, descriptor) {
         label: descriptor.label,
         found: outcome.found,
         detail: outcome.detail,
+        gitCompatibility: outcome.gitCompatibility,
         installHint: hintForPlatform(descriptor.installHint, deps.platform),
         authNote: descriptor.authNote,
         // Deliberately NOT carried through when the probe THREW: the catch above
@@ -872,6 +869,63 @@ export async function probePrerequisite(deps, descriptor) {
         renderDetailWhenMissing: descriptor.renderDetailWhenMissing === true && !probeThrew ? true : undefined,
     };
 }
+/** Release-specific advisory baseline; never a launcher admission requirement.
+ * Evidence: https://github.com/max-sixty/worktrunk/blob/v0.80.0/src/git/version.rs
+ */
+export const WORKTRUNK_GIT_BASELINE = "Worktrunk v0.80.0 (Git >= 2.43.0)";
+/** Read-only, advisory compatibility with the documented release, not every release. */
+export async function probeGitWorktrunkCompatibility(deps) {
+    const basis = WORKTRUNK_GIT_BASELINE;
+    let executable;
+    let version;
+    const unknown = (reason) => ({ status: "unknown", executable, version, basis, reason });
+    try {
+        const locator = getCommandProbe("git", deps.platform);
+        const located = await deps.runCommand(locator.file, locator.args, { timeoutMs: 3000 });
+        if (located.unavailable)
+            return unknown("locator-unavailable");
+        if (!commandSucceeded(located))
+            return unknown(located.exitCode === 1 ? "git-missing" : "locator-unavailable");
+        const candidate = located.stdout.trim().split(/\r?\n/)[0];
+        // Only absolute paths from a successful locator are diagnostic metadata.
+        if (!candidate || candidate.length > 512 || /[\x00-\x1f\x7f]/.test(candidate) ||
+            !(deps.platform === "win32" ? path.win32.isAbsolute(candidate) : path.posix.isAbsolute(candidate))) {
+            return unknown("locator-unavailable");
+        }
+        executable = candidate;
+        const result = await deps.runCommand(executable, ["--version"], { timeoutMs: 3000 });
+        if (!commandSucceeded(result))
+            return unknown("version-unavailable");
+        const match = /^git version (\d{1,5})\.(\d{1,5})(?:\.(\d{1,5}))?(?:\.windows\.\d+| \(Apple Git-[\w.-]+\))?$/.exec(result.stdout.trim());
+        if (!match)
+            return unknown("version-unparseable");
+        const parts = [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)];
+        version = parts.join(".");
+        if (deps.env[WORKTRUNK_BINARY_OVERRIDE_ENV]?.trim())
+            return unknown("override-unconfirmed");
+        const minimum = [2, 43, 0];
+        const differing = parts.findIndex((n, i) => n !== minimum[i]);
+        const compatible = differing < 0 || parts[differing] > minimum[differing];
+        return { status: compatible ? "compatible" : "incompatible", executable, version, basis };
+    }
+    catch {
+        return unknown(executable ? "version-unavailable" : "locator-unavailable");
+    }
+}
+/** Pure formatter shared by doctor and first-build output. No raw probe output. */
+export function formatGitCompatibilityDiagnostic(result) {
+    const metadata = [result.executable, result.version && `Git ${result.version}`].filter(Boolean).join("; ");
+    return `Git compatibility advisory: ${result.status}${metadata ? ` — ${metadata}` : ""}; comparison: ${result.basis}` +
+        (result.reason ? `; ${result.reason}` : "") +
+        (result.status === "incompatible" ? ". Verify the Git executable/version selected on PATH and install a supported Git manually." : "") +
+        (result.reason === "override-unconfirmed" ? ". Custom Worktrunk release requirement is unconfirmed." : "");
+}
+export function gitCompatibilityDescriptor() {
+    return {
+        id: "git-compatibility", label: "Git compatibility advisory", installHint: GIT_INSTALL_HINTS,
+        probe: async (deps) => ({ found: true, gitCompatibility: await probeGitWorktrunkCompatibility(deps) }),
+    };
+}
 /**
  * Enforce the preflight descriptors fail-fast (matching the existing
  * `runPreflight` behaviour). Iterates the shared preflight descriptors in order