@bridge_gpt/mcp-server 0.2.67 → 0.2.69

package/build/codex-launcher-pin.js

@@ -0,0 +1,598 @@
+/**
+ * Pure, conservative reader and surgical splicer for the Bridge launcher in
+ * Codex's global `config.toml` (BAPI-1445).
+ *
+ * Codex keeps its MCP registrations in one per-user TOML file that also holds
+ * unrelated settings, comments, and a Bridge `.env` table full of credentials.
+ * `upgrade` must move the package pin inside that file without ever
+ * re-serializing it. So this module does not parse TOML into a document model.
+ * It runs a small lexical scanner that finds exactly one supported
+ * `[mcp_servers.<name>]` base table, where `<name>` is any recognized key,
+ * reads its `args` array, and reports the character offsets of the one package
+ * specifier worth changing. {@link applyCodexRepin} then splices only those
+ * characters; every other byte of the file is carried through unchanged.
+ *
+ * The contract is "refuse when unsure". Any structure the scanner cannot read
+ * with confidence — inline tables, dotted keys, repeated tables, escapes inside
+ * the package token, multiline strings in the Bridge table, malformed arrays —
+ * comes back as `unlocatable`, never as a guess.
+ *
+ * Purity and secret safety:
+ *  - No file I/O, network, process spawning, or logging. Imports are limited to
+ *    identity-level constants and types from `mcp-identity.ts`; this module must
+ *    never import `launcher-config-inspection.ts` or `mcp-host-config.ts`.
+ *  - A result carries only the registration name, the parsed launcher
+ *    arguments, and splice coordinates. It never carries the file text, the
+ *    command, any environment value, a parse excerpt, or a raw error. The
+ *    `.env` table is scanned only to keep lexical state and table boundaries.
+ *  - Offsets are half-open JavaScript string offsets in UTF-16 code units, not
+ *    UTF-8 byte positions. Callers must read and write the file as UTF-8 text so
+ *    string offsets and file content stay in step.
+ */
+import { MCP_PACKAGE_NAME, RECOGNIZED_SERVER_NAMES, WORKTREE_SHIM_TOKEN, } from "./mcp-identity.js";
+/** The only error {@link applyCodexRepin} throws. Carries no source text. */
+export const CODEX_SPLICE_ERROR_MESSAGE = "the Codex launcher splice no longer matches the inspected configuration";
+// ---------------------------------------------------------------------------
+// Lexical scanner
+// ---------------------------------------------------------------------------
+/** Internal: the scanner met a construct it will not interpret. Never escapes. */
+class ScanFailure extends Error {
+}
+const BARE_KEY_CHAR = /[A-Za-z0-9_-]/;
+/** Scan the whole document into headers, key/values, and multiline-string starts. */
+function scanDocument(content) {
+    const items = [];
+    const multilineStarts = [];
+    const n = content.length;
+    const skipHorizontal = (from) => {
+        let i = from;
+        while (i < n && (content[i] === " " || content[i] === "\t"))
+            i++;
+        return i;
+    };
+    /** Skip whitespace, newlines, and comments. */
+    const skipBlank = (from) => {
+        let i = from;
+        while (i < n) {
+            const c = content[i];
+            if (c === " " || c === "\t" || c === "\r" || c === "\n") {
+                i++;
+            }
+            else if (c === "#") {
+                while (i < n && content[i] !== "\n")
+                    i++;
+            }
+            else {
+                break;
+            }
+        }
+        return i;
+    };
+    const readString = (from) => {
+        const quote = content[from];
+        const triple = content.startsWith(quote.repeat(3), from);
+        const kind = quote === '"' ? "basic" : "literal";
+        if (triple) {
+            multilineStarts.push(from);
+            let j = from + 3;
+            while (j < n) {
+                if (kind === "basic" && content[j] === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (content.startsWith(quote.repeat(3), j)) {
+                    let end = j + 3;
+                    let extra = 0;
+                    while (extra < 2 && content[end] === quote) {
+                        end++;
+                        extra++;
+                    }
+                    return {
+                        start: from,
+                        end,
+                        innerStart: from + 3,
+                        innerEnd: end - 3,
+                        kind,
+                        multiline: true,
+                    };
+                }
+                j++;
+            }
+            throw new ScanFailure();
+        }
+        let j = from + 1;
+        while (j < n) {
+            const c = content[j];
+            if (c === "\n" || c === "\r")
+                throw new ScanFailure();
+            if (kind === "basic" && c === "\\") {
+                j += 2;
+                continue;
+            }
+            if (c === quote) {
+                return {
+                    start: from,
+                    end: j + 1,
+                    innerStart: from + 1,
+                    innerEnd: j,
+                    kind,
+                    multiline: false,
+                };
+            }
+            j++;
+        }
+        throw new ScanFailure();
+    };
+    const parseKeyPath = (from) => {
+        const segments = [];
+        let i = from;
+        for (;;) {
+            i = skipHorizontal(i);
+            const c = content[i];
+            if (c === '"' || c === "'") {
+                const token = readString(i);
+                if (token.multiline)
+                    throw new ScanFailure();
+                const raw = content.slice(token.innerStart, token.innerEnd);
+                segments.push(token.kind === "basic" ? decodeBasicString(raw) : raw);
+                i = token.end;
+            }
+            else {
+                let j = i;
+                while (j < n && BARE_KEY_CHAR.test(content[j]))
+                    j++;
+                if (j === i)
+                    throw new ScanFailure();
+                segments.push(content.slice(i, j));
+                i = j;
+            }
+            i = skipHorizontal(i);
+            if (content[i] === ".") {
+                i++;
+                continue;
+            }
+            return { segments, next: i };
+        }
+    };
+    /** Skip one value of any TOML type, returning the offset just past it. */
+    const skipValue = (from) => {
+        const c = content[from];
+        if (c === '"' || c === "'")
+            return readString(from).end;
+        if (c === "[") {
+            let i = from + 1;
+            for (;;) {
+                i = skipBlank(i);
+                if (i >= n)
+                    throw new ScanFailure();
+                if (content[i] === "]")
+                    return i + 1;
+                i = skipBlank(skipValue(i));
+                if (content[i] === ",") {
+                    i++;
+                    continue;
+                }
+                if (content[i] === "]")
+                    return i + 1;
+                throw new ScanFailure();
+            }
+        }
+        if (c === "{") {
+            let i = from + 1;
+            for (;;) {
+                i = skipBlank(i);
+                if (i >= n)
+                    throw new ScanFailure();
+                if (content[i] === "}")
+                    return i + 1;
+                const { next } = parseKeyPath(i);
+                i = skipHorizontal(next);
+                if (content[i] !== "=")
+                    throw new ScanFailure();
+                i = skipBlank(i + 1);
+                i = skipBlank(skipValue(i));
+                if (content[i] === ",") {
+                    i++;
+                    continue;
+                }
+                if (content[i] === "}")
+                    return i + 1;
+                throw new ScanFailure();
+            }
+        }
+        // A bare scalar: number, boolean, or date-time, ending at a delimiter.
+        let j = from;
+        while (j < n && !/[\s,\]}#]/.test(content[j]))
+            j++;
+        if (j === from)
+            throw new ScanFailure();
+        return j;
+    };
+    /** After a statement, only horizontal space and a comment may precede the newline. */
+    const expectLineEnd = (from) => {
+        let i = skipHorizontal(from);
+        if (content[i] === "#") {
+            while (i < n && content[i] !== "\n")
+                i++;
+        }
+        if (i < n && content[i] === "\r")
+            i++;
+        if (i < n && content[i] !== "\n")
+            throw new ScanFailure();
+        return i;
+    };
+    let i = 0;
+    while (i < n) {
+        i = skipBlank(i);
+        if (i >= n)
+            break;
+        const start = i;
+        if (content[i] === "[") {
+            const isArrayTable = content[i + 1] === "[";
+            const { segments, next } = parseKeyPath(i + (isArrayTable ? 2 : 1));
+            let j = skipHorizontal(next);
+            const closer = isArrayTable ? "]]" : "]";
+            if (!content.startsWith(closer, j))
+                throw new ScanFailure();
+            j += closer.length;
+            items.push({ type: "header", start, end: j, segments, isArrayTable });
+            i = expectLineEnd(j);
+            continue;
+        }
+        const { segments, next } = parseKeyPath(i);
+        let j = skipHorizontal(next);
+        if (content[j] !== "=")
+            throw new ScanFailure();
+        j = skipHorizontal(j + 1);
+        const valueStart = j;
+        const valueEnd = skipValue(valueStart);
+        items.push({ type: "kv", start, keySegments: segments, valueStart, valueEnd });
+        i = expectLineEnd(valueEnd);
+    }
+    return { items, multilineStarts };
+}
+/** Decode a TOML basic-string body. Throws {@link ScanFailure} on a bad escape. */
+function decodeBasicString(raw) {
+    let out = "";
+    for (let i = 0; i < raw.length; i++) {
+        const c = raw[i];
+        if (c !== "\\") {
+            out += c;
+            continue;
+        }
+        const e = raw[++i];
+        switch (e) {
+            case "b":
+                out += "\b";
+                break;
+            case "t":
+                out += "\t";
+                break;
+            case "n":
+                out += "\n";
+                break;
+            case "f":
+                out += "\f";
+                break;
+            case "r":
+                out += "\r";
+                break;
+            case '"':
+                out += '"';
+                break;
+            case "\\":
+                out += "\\";
+                break;
+            case "u":
+            case "U": {
+                const width = e === "u" ? 4 : 8;
+                const hex = raw.slice(i + 1, i + 1 + width);
+                if (hex.length !== width || !/^[0-9A-Fa-f]+$/.test(hex))
+                    throw new ScanFailure();
+                try {
+                    out += String.fromCodePoint(parseInt(hex, 16));
+                }
+                catch {
+                    throw new ScanFailure();
+                }
+                i += width;
+                break;
+            }
+            default:
+                throw new ScanFailure();
+        }
+    }
+    return out;
+}
+/** Read a single- or multi-line array of single-line strings, strictly. */
+function readArgsArray(content, valueStart, valueEnd) {
+    const n = content.length;
+    if (content[valueStart] !== "[")
+        throw new ScanFailure();
+    const elements = [];
+    let i = valueStart + 1;
+    const skipBlank = (from) => {
+        let j = from;
+        while (j < n) {
+            const c = content[j];
+            if (c === " " || c === "\t" || c === "\r" || c === "\n") {
+                j++;
+            }
+            else if (c === "#") {
+                while (j < n && content[j] !== "\n")
+                    j++;
+            }
+            else {
+                break;
+            }
+        }
+        return j;
+    };
+    for (;;) {
+        i = skipBlank(i);
+        if (i >= valueEnd)
+            throw new ScanFailure();
+        if (content[i] === "]") {
+            if (i + 1 !== valueEnd)
+                throw new ScanFailure();
+            return elements;
+        }
+        const quote = content[i];
+        if (quote !== '"' && quote !== "'")
+            throw new ScanFailure();
+        if (content.startsWith(quote.repeat(3), i))
+            throw new ScanFailure();
+        let j = i + 1;
+        let closed = false;
+        while (j < valueEnd) {
+            const c = content[j];
+            if (c === "\n" || c === "\r")
+                throw new ScanFailure();
+            if (quote === '"' && c === "\\") {
+                j += 2;
+                continue;
+            }
+            if (c === quote) {
+                closed = true;
+                break;
+            }
+            j++;
+        }
+        if (!closed)
+            throw new ScanFailure();
+        const raw = content.slice(i + 1, j);
+        elements.push({
+            value: quote === '"' ? decodeBasicString(raw) : raw,
+            innerStart: i + 1,
+            innerEnd: j,
+            hasBackslash: quote === '"' && raw.includes("\\"),
+        });
+        i = skipBlank(j + 1);
+        if (content[i] === ",") {
+            i++;
+            continue;
+        }
+        if (content[i] === "]") {
+            if (i + 1 !== valueEnd)
+                throw new ScanFailure();
+            return elements;
+        }
+        throw new ScanFailure();
+    }
+}
+// ---------------------------------------------------------------------------
+// Inspection
+// ---------------------------------------------------------------------------
+const SERVERS_ROOT = "mcp_servers";
+const NONE = { kind: "none" };
+const UNLOCATABLE = { kind: "unlocatable" };
+function recognizedName(name) {
+    return RECOGNIZED_SERVER_NAMES.includes(name ?? "")
+        ? name
+        : null;
+}
+/** True when a package token names the Bridge package, bare or with an `@` suffix. */
+function isBridgePackageToken(arg) {
+    return arg === MCP_PACKAGE_NAME || arg.startsWith(`${MCP_PACKAGE_NAME}@`);
+}
+/**
+ * Locate the one supported Bridge launcher in a Codex `config.toml`.
+ *
+ * Returns `none` only when the file holds no Bridge declaration of any kind.
+ * A file the scanner cannot read at all is `none` when it never mentions Bridge
+ * and `unlocatable` when it does — a broken file that might hide a registration
+ * is never reported as "nothing to do".
+ */
+export function inspectCodexLauncher(content) {
+    let doc;
+    try {
+        doc = scanDocument(content);
+    }
+    catch (err) {
+        if (!(err instanceof ScanFailure))
+            throw err;
+        return /bridge/i.test(content) ? UNLOCATABLE : NONE;
+    }
+    try {
+        return classifyDocument(content, doc);
+    }
+    catch (err) {
+        if (!(err instanceof ScanFailure))
+            throw err;
+        return UNLOCATABLE;
+    }
+}
+function classifyDocument(content, doc) {
+    const { items, multilineStarts } = doc;
+    const baseTables = [];
+    const subtableNames = new Set();
+    let sawUnsupportedDeclaration = false;
+    let current = [];
+    for (let index = 0; index < items.length; index++) {
+        const item = items[index];
+        if (item.type === "header") {
+            current = item.segments;
+            if (item.segments[0] !== SERVERS_ROOT || item.segments.length < 2)
+                continue;
+            const name = recognizedName(item.segments[1]);
+            if (!name)
+                continue;
+            if (item.isArrayTable) {
+                sawUnsupportedDeclaration = true;
+            }
+            else if (item.segments.length === 2) {
+                baseTables.push({ name, headerIndex: index });
+            }
+            else {
+                subtableNames.add(name);
+            }
+            continue;
+        }
+        // A key/value. Its full path is the enclosing table path plus its own key.
+        const full = [...current, ...item.keySegments];
+        if (full[0] !== SERVERS_ROOT)
+            continue;
+        if (full.length === 1) {
+            // `mcp_servers = { ... }`: an inline servers table. Refuse it if it could
+            // be declaring Bridge.
+            if (/bridge/i.test(content.slice(item.valueStart, item.valueEnd))) {
+                sawUnsupportedDeclaration = true;
+            }
+            continue;
+        }
+        const name = recognizedName(full[1]);
+        if (!name)
+            continue;
+        const insideOwnTable = current[0] === SERVERS_ROOT && current[1] === full[1];
+        if (!insideOwnTable)
+            sawUnsupportedDeclaration = true;
+    }
+    const names = new Set(baseTables.map((t) => t.name));
+    for (const name of subtableNames) {
+        if (!names.has(name))
+            return UNLOCATABLE; // an orphan `.env` or other subtable
+    }
+    if (sawUnsupportedDeclaration)
+        return UNLOCATABLE;
+    if (names.size > 1)
+        return { kind: "duplicate" };
+    if (baseTables.length === 0)
+        return NONE;
+    if (baseTables.length > 1)
+        return UNLOCATABLE; // the same base table repeated
+    const [base] = baseTables;
+    const bodyStart = items[base.headerIndex].end;
+    const nextHeader = items.slice(base.headerIndex + 1).find((i) => i.type === "header");
+    const bodyEnd = nextHeader ? nextHeader.start : content.length;
+    if (multilineStarts.some((s) => s >= bodyStart && s < bodyEnd))
+        return UNLOCATABLE;
+    const argsItems = [];
+    for (let k = base.headerIndex + 1; k < items.length; k++) {
+        const item = items[k];
+        if (item.type === "header")
+            break;
+        if (item.keySegments[0] !== "args")
+            continue;
+        if (item.keySegments.length > 1)
+            return UNLOCATABLE;
+        argsItems.push(item);
+    }
+    if (argsItems.length !== 1)
+        return UNLOCATABLE;
+    const elements = readArgsArray(content, argsItems[0].valueStart, argsItems[0].valueEnd);
+    const args = elements.map((e) => e.value);
+    const tokenElements = elements.filter((e) => isBridgePackageToken(e.value));
+    if (tokenElements.some((e) => e.hasBackslash))
+        return UNLOCATABLE;
+    if (tokenElements.length > 1)
+        return UNLOCATABLE;
+    if (args.includes(WORKTREE_SHIM_TOKEN)) {
+        return { kind: "worktree-shim", registrationName: base.name, args };
+    }
+    if (tokenElements.length === 0)
+        return UNLOCATABLE;
+    const [token] = tokenElements;
+    return {
+        kind: "located",
+        registrationName: base.name,
+        args,
+        splice: spliceFor(token),
+    };
+}
+function spliceFor(token) {
+    const tokenText = token.value;
+    const common = {
+        tokenStart: token.innerStart,
+        tokenEnd: token.innerEnd,
+        tokenText,
+    };
+    if (tokenText === MCP_PACKAGE_NAME) {
+        return {
+            ...common,
+            replaceStart: token.innerEnd,
+            replaceEnd: token.innerEnd,
+            replacedText: "",
+            needsAtSign: true,
+        };
+    }
+    const specStart = token.innerStart + MCP_PACKAGE_NAME.length + 1;
+    const rest = tokenText.slice(MCP_PACKAGE_NAME.length + 1);
+    const trimmed = rest.trim();
+    if (trimmed.length === 0) {
+        return {
+            ...common,
+            replaceStart: specStart,
+            replaceEnd: specStart,
+            replacedText: "",
+            needsAtSign: false,
+        };
+    }
+    const lead = rest.length - rest.trimStart().length;
+    return {
+        ...common,
+        replaceStart: specStart + lead,
+        replaceEnd: specStart + lead + trimmed.length,
+        replacedText: trimmed,
+        needsAtSign: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// Surgical splice
+// ---------------------------------------------------------------------------
+/** A target version safe to write inside a TOML string without escaping. */
+const SAFE_VERSION = /^[0-9A-Za-z][0-9A-Za-z.+-]*$/;
+/**
+ * Splice `version` into `content` at the coordinates `inspection` located.
+ *
+ * Everything outside the replaced range — comments, CRLF, table names, the whole
+ * `.env` table, non-ASCII text — is copied through unchanged. Throws the one
+ * fixed {@link CODEX_SPLICE_ERROR_MESSAGE} when the inspection is not a located
+ * launcher, the coordinates fall outside `content`, or the text at them no longer
+ * matches what was inspected. The error never contains source text.
+ */
+export function applyCodexRepin(content, inspection, version) {
+    if (inspection.kind !== "located" || !SAFE_VERSION.test(version)) {
+        throw new Error(CODEX_SPLICE_ERROR_MESSAGE);
+    }
+    const s = inspection.splice;
+    const offsets = [s.tokenStart, s.tokenEnd, s.replaceStart, s.replaceEnd];
+    const inRange = offsets.every((o) => Number.isInteger(o) && o >= 0 && o <= content.length) &&
+        s.tokenStart <= s.replaceStart &&
+        s.replaceStart <= s.replaceEnd &&
+        s.replaceEnd <= s.tokenEnd;
+    if (!inRange)
+        throw new Error(CODEX_SPLICE_ERROR_MESSAGE);
+    if (content.slice(s.tokenStart, s.tokenEnd) !== s.tokenText ||
+        content.slice(s.replaceStart, s.replaceEnd) !== s.replacedText) {
+        throw new Error(CODEX_SPLICE_ERROR_MESSAGE);
+    }
+    const shapeOk = s.needsAtSign
+        ? s.tokenText === MCP_PACKAGE_NAME && s.replaceStart === s.tokenEnd && s.replaceEnd === s.tokenEnd
+        : s.tokenText.startsWith(`${MCP_PACKAGE_NAME}@`);
+    if (!shapeOk)
+        throw new Error(CODEX_SPLICE_ERROR_MESSAGE);
+    return (content.slice(0, s.replaceStart) +
+        (s.needsAtSign ? "@" : "") +
+        version +
+        content.slice(s.replaceEnd));
+}

package/build/command-assets-doctor.js

@@ -1,72 +1,26 @@
-/**
- * Read-only worktree Claude command-asset diagnostic (doctor-only, BAPI-664).
- *
- * Reports whether the current worktree contains every packaged Claude slash
- * command under `.claude/commands/`. This probe ONLY reads command paths — it
- * never writes, creates directories, invokes Git, spawns a process, compares or
- * reports command file CONTENTS, or leaks raw exceptions. A committed customer
- * version of a command counts as present regardless of its contents (the command
- * bundle is fill-only and never refreshed), so the probe checks presence /
- * readability, not freshness. The sole injected dependencies are `readFile` and
- * `platform`.
- */
-import path from "path";
-import { COMMANDS } from "./commands.generated.js";
-/** Stable user-facing relative location shown in every detail string. */
-const COMMAND_DIR_LABEL = ".claude/commands/";
-/** How many missing filenames to list before summarizing the remainder. */
-const MAX_LISTED_MISSING = 5;
-/** The `path` API for the target platform (win32 vs posix). */
-function pathApiForPlatform(platform) {
-    return platform === "win32" ? path.win32 : path.posix;
-}
-/** Render a bounded, deterministic list of missing filenames (generated order). */
-function formatMissing(missing) {
-    if (missing.length <= MAX_LISTED_MISSING) {
-        return missing.join(", ");
-    }
-    const shown = missing.slice(0, MAX_LISTED_MISSING).join(", ");
-    return `${shown} (+${missing.length - MAX_LISTED_MISSING} more)`;
-}
-/**
- * Probe whether `<worktreeRoot>/.claude/commands/` contains every packaged
- * command asset. A `readFile` that resolves counts the asset as present (any
- * contents); a rejection (missing OR unreadable) counts it as absent. Returns
- * `found: true` only when every packaged command filename is present, otherwise a
- * `found: false` result with a concise, actionable, secret-free detail that
- * points the operator back to `start-tickets` (never to manually copying or
- * committing generated files).
- */
-export async function probeWorktreeCommandAssets(worktreeRoot, deps) {
-    const filenames = Object.keys(COMMANDS);
-    if (filenames.length === 0) {
-        return {
-            found: false,
-            detail: "Packaged command bundle is empty — reinstall or rebuild the MCP server package.",
-        };
-    }
-    const api = pathApiForPlatform(deps.platform);
-    const commandsDir = api.join(worktreeRoot, ".claude", "commands");
-    const missing = [];
-    for (const filename of filenames) {
-        try {
-            await deps.readFile(api.join(commandsDir, filename));
-        }
-        catch {
-            // Missing OR unreadable — either way the asset is not usable. We never
-            // surface the underlying error (it can carry paths / exception text).
-            missing.push(filename);
-        }
-    }
-    if (missing.length === 0) {
-        return {
-            found: true,
-            detail: `${filenames.length} packaged command assets present under ${COMMAND_DIR_LABEL}`,
-        };
+/** Metadata-only compatibility probe for worktree command assets. */
+import { buildPackagedAssetCatalog } from "./generated-assets-catalog.js";
+import { inspectPackagedDependency } from "./generated-assets-health.js";
+import { packagedAssetRemedy } from "./generated-assets-remedy.js";
+export async function probeWorktreeCommandAssets(root, deps) {
+    if (!deps.metadata)
+        return { found: false, detail: "Command-asset inspection indeterminate (metadata access unavailable)." };
+    const catalog = buildPackagedAssetCatalog();
+    const assets = catalog.assets.filter(a => a.kind === "command" && a.hosts.includes("claude"));
+    if (!assets.length || catalog.packageProblems.length)
+        return { found: false, detail: "Packaged command bundle is empty or unavailable — rebuild or reinstall the package." };
+    const findings = [];
+    const deadline = Date.now() + 1000;
+    for (const asset of assets) {
+        if (Date.now() >= deadline)
+            return { found: false, detail: "Command-asset inspection indeterminate (time budget)." };
+        findings.push(await inspectPackagedDependency(root, asset, { ...deps.metadata, platform: deps.platform }, deadline - Date.now()));
     }
-    return {
-        found: false,
-        detail: `${missing.length} of ${filenames.length} packaged command assets missing or unreadable under ` +
-            `${COMMAND_DIR_LABEL} (${formatMissing(missing)}). Re-run start-tickets to provision them.`,
-    };
+    const unusable = findings.filter(f => f.status !== "present");
+    if (!unusable.length)
+        return { found: true, detail: `${assets.length} packaged command assets present under .claude/commands/` };
+    const shown = unusable.slice(0, 5).map(f => `${f.destination.split("/").at(-1)}: ${f.status} (${f.reason})`).join(", ");
+    const missing = unusable.filter(f => f.status === "missing").length;
+    const guidance = missing ? packagedAssetRemedy(root, "claude", undefined, deps.platform).command : "Resolve path/permission problems; use explicit --project-root and --host for provisioning.";
+    return { found: false, detail: `${unusable.length} of ${assets.length} packaged command assets unusable under .claude/commands/ (${shown}${unusable.length > 5 ? `, +${unusable.length - 5} more` : ""}). ${guidance}` };
 }