efaimo 0.1.0 → 0.1.2

package/dist/clients/introspect.js

@@ -23,14 +23,22 @@ export async function introspectServer(target, opts = {}) {
             stderr: "pipe",
         });
         transport = stdio;
+        // Split the budget across the two attempts so a dead server fails in about
+        // one timeout, not two: the legacy handshake got the whole timeout AND the
+        // stateless fallback then re-waited the whole timeout again, so `--timeout 8`
+        // took ~16s wall. The handshake takes the larger share; the fallback gets
+        // what is left, with a floor so a genuinely stateless server still has time
+        // to answer a bare request.
+        const startedAt = Date.now();
         try {
-            await withTimeout(client.connect(stdio), timeoutMs, "connect (stdio)");
+            await withTimeout(client.connect(stdio), Math.max(1, Math.round(timeoutMs * 0.6)), "connect (stdio)");
         }
         catch (e) {
             await safeClose(client, stdio);
             // A 2026-07-28 stateless server has no initialize, so the SDK handshake
             // fails by design; try bare stateless requests before giving up.
-            const rc = await introspectStateless(target, { timeoutMs });
+            const remaining = Math.max(timeoutMs - (Date.now() - startedAt), Math.round(timeoutMs * 0.25));
+            const rc = await introspectStateless(target, { timeoutMs: remaining });
             if (rc)
                 return rc;
             throw connectError(e, target.label, stderrTail);

package/dist/clients/rawprobe.d.ts

@@ -6,7 +6,14 @@ import type { ResolvedTarget } from "../targets/resolve.js";
  * stateless requests, server/discover) need raw transport access.
  * Every probe fails soft into a { skipped } marker.
  */
-export declare const RC_VERSION = "2026-07-28";
+/**
+ * The MCP revision efaimo audits against. It was called RC_VERSION until
+ * 2026-08-01, by which point the revision had been published for four days and
+ * the name had been lying for all of them. scripts/spec-drift.mjs reads this
+ * declaration by name, so renaming it again means updating that regex, which
+ * fails loudly rather than silently watching nothing.
+ */
+export declare const SPEC_VERSION = "2026-07-28";
 interface RpcReply {
     result?: Record<string, unknown>;
     error?: {
@@ -16,7 +23,7 @@ interface RpcReply {
     timeout?: boolean;
     procExit?: number | null;
 }
-export declare function rcMeta(): Record<string, unknown>;
+export declare function specMeta(): Record<string, unknown>;
 /**
  * Only an explicit "not initialized" / "session required" error proves the
  * server requires the removed initialize handshake. A plain timeout is NOT proof
@@ -24,11 +31,20 @@ export declare function rcMeta(): Record<string, unknown>;
  * inconclusive; a crash is its own signal. This keeps E105 from false-flagging a
  * healthy but slow server, the worst verdict a readiness checker can emit.
  *
- * Detection is by message, not by error code: the codes SDKs use here are
+ * Detection is by message, not by error code, and the spec that published on
+ * 2026-07-28 is the argument for why. The codes SDKs use here are
  * implementation-defined (TS StreamableHTTP sends -32000 for both "Server not
  * initialized" and "Mcp-Session-Id header is required", -32001 for "Session not
- * found"), -32002 means Resource-not-found in the 2025 specs, and the RC
- * reserves -32022 for UnsupportedProtocolVersion, so no code is diagnostic.
+ * found"), and the MCP-defined ones MOVED between the locked RC and the
+ * published spec: MissingRequiredClientCapability went -32003 to -32021 and
+ * UnsupportedProtocolVersion went -32004 to -32022, and HeaderMismatch moved
+ * the same way, -32001 to -32020. This comment said HeaderMismatch was "added
+ * alongside them", which was wrong: the RC already defined it at -32001 in the
+ * transport prose, and what the published revision added was its entry in the
+ * schema. The distinction matters to anyone still returning -32001.
+ * -32002 (resource not found) is retired outright,
+ * replaced by -32602 and promised never to be reused. Matching on numbers
+ * would have rotted here on 2026-07-28; matching on messages did not.
  */
 export declare function looksLikeInitGate(o: ProbeOutcome): boolean;
 export declare function runProbes(target: Extract<ResolvedTarget, {

package/dist/clients/rawprobe.js

@@ -8,12 +8,19 @@ import { VERSION } from "../version.js";
  * stateless requests, server/discover) need raw transport access.
  * Every probe fails soft into a { skipped } marker.
  */
-export const RC_VERSION = "2026-07-28";
+/**
+ * The MCP revision efaimo audits against. It was called RC_VERSION until
+ * 2026-08-01, by which point the revision had been published for four days and
+ * the name had been lying for all of them. scripts/spec-drift.mjs reads this
+ * declaration by name, so renaming it again means updating that regex, which
+ * fails loudly rather than silently watching nothing.
+ */
+export const SPEC_VERSION = "2026-07-28";
 const LEGACY_VERSION = "2025-06-18";
-export function rcMeta() {
+export function specMeta() {
     return {
         _meta: {
-            "io.modelcontextprotocol/protocolVersion": RC_VERSION,
+            "io.modelcontextprotocol/protocolVersion": SPEC_VERSION,
             "io.modelcontextprotocol/clientCapabilities": {},
         },
     };
@@ -36,11 +43,20 @@ function toOutcome(reply, timeoutMessage) {
  * inconclusive; a crash is its own signal. This keeps E105 from false-flagging a
  * healthy but slow server, the worst verdict a readiness checker can emit.
  *
- * Detection is by message, not by error code: the codes SDKs use here are
+ * Detection is by message, not by error code, and the spec that published on
+ * 2026-07-28 is the argument for why. The codes SDKs use here are
  * implementation-defined (TS StreamableHTTP sends -32000 for both "Server not
  * initialized" and "Mcp-Session-Id header is required", -32001 for "Session not
- * found"), -32002 means Resource-not-found in the 2025 specs, and the RC
- * reserves -32022 for UnsupportedProtocolVersion, so no code is diagnostic.
+ * found"), and the MCP-defined ones MOVED between the locked RC and the
+ * published spec: MissingRequiredClientCapability went -32003 to -32021 and
+ * UnsupportedProtocolVersion went -32004 to -32022, and HeaderMismatch moved
+ * the same way, -32001 to -32020. This comment said HeaderMismatch was "added
+ * alongside them", which was wrong: the RC already defined it at -32001 in the
+ * transport prose, and what the published revision added was its entry in the
+ * schema. The distinction matters to anyone still returning -32001.
+ * -32002 (resource not found) is retired outright,
+ * replaced by -32602 and promised never to be reused. Matching on numbers
+ * would have rotted here on 2026-07-28; matching on messages did not.
  */
 export function looksLikeInitGate(o) {
     if (o.kind !== "error")
@@ -192,11 +208,60 @@ function hasCacheFields(result) {
     return (Object.prototype.hasOwnProperty.call(result, "ttlMs") &&
         Object.prototype.hasOwnProperty.call(result, "cacheScope"));
 }
+/** JSON-RPC's own "no such method", unchanged by the 2026-07-28 revision. */
+const METHOD_NOT_FOUND = -32601;
+/**
+ * One reading of a server/discover answer, because there are three call sites
+ * (stdio, the bare stateless HTTP path, the legacy HTTP path) and they had
+ * already drifted: the same four branches were spelled three ways, and only
+ * two of them handled a reply that carried neither a result nor an error.
+ *
+ * Returns undefined when there is nothing to read, so each caller keeps its own
+ * fallback: stdio calls that "no answer", while the bare HTTP path deliberately
+ * leaves the verdict unset so the legacy branch can still try after initialize.
+ */
+function classifyDiscover(reply) {
+    if (reply?.result)
+        return { verdict: { supported: true }, cacheFields: hasCacheFields(reply.result) };
+    if (reply?.error) {
+        const detail = `${reply.error.code} ${reply.error.message}`;
+        return reply.error.code === METHOD_NOT_FOUND
+            ? { verdict: { supported: false, errorMessage: detail } }
+            : { verdict: { skipped: `inconclusive (${detail})` } };
+    }
+    return undefined;
+}
 function toolOrder(result) {
     const tools = result?.tools ?? [];
     return tools.map((x) => x?.name).filter((n) => typeof n === "string");
 }
+/**
+ * Kills every spawned server on the way out, including when a probe throws.
+ *
+ * The body below used to run its cleanup only on the happy path, and the
+ * consequence was worse than a leaked process: with no kill(), the child's
+ * stdin is never closed, so it never sees EOF and never exits, and its stdio
+ * handles keep THIS process's event loop alive. runProbes catches the throw and
+ * the report still prints, and then the CLI hangs forever having already said
+ * everything it had to say. Measured: killed at 30s with the cleanup removed,
+ * 664ms clean exit with it.
+ *
+ * statelessStdio next door already had this try/finally; this is the same
+ * pattern in the file that was missing it. kill() is idempotent, so the early
+ * kills inside still free each server as soon as it is done rather than holding
+ * them all open until the end.
+ */
 async function probeStdio(target, budget) {
+    const sessions = [];
+    try {
+        return await probeStdioSessions(target, budget, sessions);
+    }
+    finally {
+        for (const s of sessions)
+            s.kill();
+    }
+}
+async function probeStdioSessions(target, budget, sessions) {
     const results = {};
     // A responsive server answers the bare request in well under a second, so a
     // generous cap only affects genuinely slow/hung servers (introspect already
@@ -204,13 +269,12 @@ async function probeStdio(target, budget) {
     // honored rather than floored.
     const bareT = Math.min(Math.max(budget, 1), 15000);
     const discoverT = Math.min(Math.max(budget, 1), 10000);
-    const sessions = [];
     // A bare stateless tools/list. BOTH legacy (the reference SDK has no init gate)
     // and RC servers answer it, so RC vs legacy is decided by the RESULT shape
     // (resultType, cache fields, server/discover), never by whether it answered.
     const s1 = new StdioSession(target.command, target.args, target.env);
     sessions.push(s1);
-    const bare = await s1.request("tools/list", rcMeta(), bareT);
+    const bare = await s1.request("tools/list", specMeta(), bareT);
     const bareOutcome = toOutcome(bare, `no response within ${Math.round(bareT / 1000)}s (the server may require the removed initialize handshake)`);
     results.bareToolsList = bareOutcome;
     let order1;
@@ -222,18 +286,10 @@ async function probeStdio(target, budget) {
     // Probe server/discover only if the server is responsive (answered or errored,
     // not timed out), to avoid a second long wait on an unresponsive server.
     if (!s1.exited && bareOutcome.kind !== "timeout") {
-        const d = await s1.request("server/discover", rcMeta(), discoverT);
-        if (d.result)
-            results.serverDiscover = { supported: true };
-        else if (d.error && d.error.code === -32601) {
-            results.serverDiscover = { supported: false, errorMessage: `${d.error.code} ${d.error.message}` };
-        }
-        else if (d.error) {
-            results.serverDiscover = { skipped: `inconclusive (${d.error.code} ${d.error.message})` };
-        }
-        else {
-            results.serverDiscover = { skipped: "no answer to server/discover" };
-        }
+        const d = classifyDiscover(await s1.request("server/discover", specMeta(), discoverT));
+        results.serverDiscover = d?.verdict ?? { skipped: "no answer to server/discover" };
+        if (d?.cacheFields !== undefined)
+            results.discoverCacheFieldsPresent = d.cacheFields;
     }
     else {
         results.serverDiscover = { skipped: "server did not answer the bare request" };
@@ -243,7 +299,7 @@ async function probeStdio(target, budget) {
     if (order1 && order1.length > 1) {
         const s2 = new StdioSession(target.command, target.args, target.env);
         sessions.push(s2);
-        const bare2 = await s2.request("tools/list", rcMeta(), bareT);
+        const bare2 = await s2.request("tools/list", specMeta(), bareT);
         s2.kill();
         if (bare2.result) {
             const order2 = toolOrder(bare2.result);
@@ -264,8 +320,13 @@ export async function postMessage(url, extraHeaders, msg, sessionId, protocolVer
             "content-type": "application/json",
             accept: "application/json, text/event-stream",
             "mcp-protocol-version": protocolVersion,
-            // Mcp-Method is well-defined (SEP-2243); Mcp-Name is required too but its
-            // value is not the method name, so it is omitted rather than sent wrong.
+            // Mcp-Method mirrors the body's method and is required on every request
+            // (SEP-2243). Mcp-Name is NOT required here: the published spec requires
+            // it only on tools/call, resources/read and prompts/get, where it carries
+            // params.name or params.uri, and efaimo sends none of those. Omitting it
+            // is correct rather than a known gap. Sending a wrong value would be
+            // worse than sending none: a server MUST reject a header that disagrees
+            // with the body, now with a dedicated code (-32020 HeaderMismatch).
             ...(method ? { "Mcp-Method": method } : {}),
             ...(sessionId ? { "mcp-session-id": sessionId } : {}),
             ...(extraHeaders ?? {}),
@@ -465,7 +526,7 @@ async function probeHttp(target) {
     const results = {};
     const url = target.url;
     const headers = target.headers;
-    const bare = await postMessage(url, headers, { jsonrpc: "2.0", id: 1, method: "tools/list", params: rcMeta() }, undefined, RC_VERSION).catch((e) => ({ status: 0, headers: new Headers(), authHeader: undefined, body: undefined, error: e }));
+    const bare = await postMessage(url, headers, { jsonrpc: "2.0", id: 1, method: "tools/list", params: specMeta() }, undefined, SPEC_VERSION).catch((e) => ({ status: 0, headers: new Headers(), authHeader: undefined, body: undefined, error: e }));
     if (bare.error) {
         const err = bare.error;
         const isTimeout = /timeout|timed out|aborted/i.test(`${err.name} ${err.message}`);
@@ -490,14 +551,15 @@ async function probeHttp(target) {
     // leave E106 (a MUST rule) unmeasured on precisely the servers it targets.
     if (results.bareToolsList && "ok" in results.bareToolsList && results.bareToolsList.ok) {
         try {
-            const d = await postMessage(url, headers, { jsonrpc: "2.0", id: 7, method: "server/discover", params: rcMeta() }, undefined, RC_VERSION);
-            if (d.body?.result)
-                results.serverDiscover = { supported: true };
-            else if (d.body?.error && d.body.error.code === -32601) {
-                results.serverDiscover = { supported: false, errorMessage: `${d.body.error.code} ${d.body.error.message}` };
-            }
-            else if (d.body?.error) {
-                results.serverDiscover = { skipped: `inconclusive (${d.body.error.code} ${d.body.error.message})` };
+            const d = await postMessage(url, headers, { jsonrpc: "2.0", id: 7, method: "server/discover", params: specMeta() }, undefined, SPEC_VERSION);
+            // No fallback verdict on purpose: a reply carrying neither result nor
+            // error leaves serverDiscover unset so the legacy branch below can still
+            // ask, after initialize.
+            const c = classifyDiscover(d.body);
+            if (c) {
+                results.serverDiscover = c.verdict;
+                if (c.cacheFields !== undefined)
+                    results.discoverCacheFieldsPresent = c.cacheFields;
             }
         }
         catch {
@@ -507,7 +569,7 @@ async function probeHttp(target) {
         const bareTools = toolOrder(bare.body && "result" in bare.body ? bare.body.result : undefined);
         if (bareTools.length > 1) {
             try {
-                const again = await postMessage(url, headers, { jsonrpc: "2.0", id: 8, method: "tools/list", params: rcMeta() }, undefined, RC_VERSION);
+                const again = await postMessage(url, headers, { jsonrpc: "2.0", id: 8, method: "tools/list", params: specMeta() }, undefined, SPEC_VERSION);
                 const order2 = toolOrder(again.body?.result);
                 if (order2.length)
                     results.toolsOrderDeterministic = arraysEqual(bareTools, order2);
@@ -545,16 +607,12 @@ async function probeHttp(target) {
                 }
                 if (results.serverDiscover === undefined) {
                     const d = await postMessage(url, headers, { jsonrpc: "2.0", id: 4, method: "server/discover", params: {} }, sessionId);
-                    if (d.body?.result)
-                        results.serverDiscover = { supported: true };
-                    else if (d.body?.error && d.body.error.code === -32601) {
-                        results.serverDiscover = { supported: false, errorMessage: `${d.body.error.code} ${d.body.error.message}` };
-                    }
-                    else if (d.body?.error) {
-                        results.serverDiscover = { skipped: `inconclusive (${d.body.error.code} ${d.body.error.message})` };
-                    }
-                    else
-                        results.serverDiscover = { skipped: "no answer to server/discover" };
+                    const c = classifyDiscover(d.body);
+                    results.serverDiscover = c?.verdict ?? { skipped: "no answer to server/discover" };
+                    // ??= for the same reason as the resultType/cacheFields lines above:
+                    // never clobber a measurement the bare stateless path already took.
+                    if (c?.cacheFields !== undefined)
+                        results.discoverCacheFieldsPresent ??= c.cacheFields;
                 }
                 if (order1 && order1.length > 1 && results.toolsOrderDeterministic === undefined) {
                     const init2 = await postMessage(url, headers, {

package/dist/clients/stateless.js

@@ -1,4 +1,4 @@
-import { RC_VERSION, rcMeta, postMessage, StdioSession } from "./rawprobe.js";
+import { SPEC_VERSION, specMeta, postMessage, StdioSession } from "./rawprobe.js";
 /**
  * 2026-07-28 introspection path: bare stateless requests, no initialize.
  * The SDK client enforces the legacy handshake, so a stateless RC server makes
@@ -8,6 +8,15 @@ import { RC_VERSION, rcMeta, postMessage, StdioSession } from "./rawprobe.js";
  * connect error.
  */
 const MAX_PAGES = 20;
+/**
+ * Newest shape first, then the RC's. Reading only the RC's field made efaimo
+ * report "identity unknown" for precisely the servers that had finished
+ * migrating, which is the worst direction for this error to point.
+ */
+function discoverIdentity(d) {
+    const found = d?._meta?.["io.modelcontextprotocol/serverInfo"] ?? d?.serverInfo;
+    return found ? { name: found.name, version: found.version, title: found.title } : undefined;
+}
 export async function introspectStateless(target, opts = {}) {
     // The legacy path already burned the caller's timeout once; keep this
     // attempt tight so a genuinely dead server fails in bounded time.
@@ -26,7 +35,7 @@ async function statelessStdio(target, budget) {
         let rawFirst;
         let cursor;
         for (let page = 0; page < MAX_PAGES; page++) {
-            const params = cursor ? { ...rcMeta(), cursor } : rcMeta();
+            const params = cursor ? { ...specMeta(), cursor } : specMeta();
             const reply = await session.request("tools/list", params, budget);
             if (!reply.result) {
                 if (page === 0)
@@ -40,7 +49,7 @@ async function statelessStdio(target, budget) {
             if (!cursor)
                 break;
         }
-        const discover = await session.request("server/discover", rcMeta(), Math.min(budget, 10000));
+        const discover = await session.request("server/discover", specMeta(), Math.min(budget, 10000));
         return buildIntrospection(target.label, "stdio", undefined, pages, rawFirst, discover.result);
     }
     finally {
@@ -52,8 +61,8 @@ async function statelessHttp(target) {
     let rawFirst;
     let cursor;
     for (let page = 0; page < MAX_PAGES; page++) {
-        const params = cursor ? { ...rcMeta(), cursor } : rcMeta();
-        const reply = await postMessage(target.url, target.headers, { jsonrpc: "2.0", id: 100 + page, method: "tools/list", params }, undefined, RC_VERSION);
+        const params = cursor ? { ...specMeta(), cursor } : specMeta();
+        const reply = await postMessage(target.url, target.headers, { jsonrpc: "2.0", id: 100 + page, method: "tools/list", params }, undefined, SPEC_VERSION);
         const result = reply.body?.result;
         if (!result) {
             if (page === 0)
@@ -67,7 +76,7 @@ async function statelessHttp(target) {
         if (!cursor)
             break;
     }
-    const discover = await postMessage(target.url, target.headers, { jsonrpc: "2.0", id: 99, method: "server/discover", params: rcMeta() }, undefined, RC_VERSION).catch(() => undefined);
+    const discover = await postMessage(target.url, target.headers, { jsonrpc: "2.0", id: 99, method: "server/discover", params: specMeta() }, undefined, SPEC_VERSION).catch(() => undefined);
     return buildIntrospection(target.label, "http", "streamable", pages, rawFirst, discover?.body?.result);
 }
 function buildIntrospection(label, transport, httpTransport, pages, rawFirst, discoverResult) {
@@ -102,14 +111,8 @@ function buildIntrospection(label, transport, httpTransport, pages, rawFirst, di
         targetLabel: label,
         transport,
         httpTransport,
-        serverInfo: discover?.serverInfo
-            ? {
-                name: discover.serverInfo.name,
-                version: discover.serverInfo.version,
-                title: discover.serverInfo.title,
-            }
-            : undefined,
-        protocolVersion: discover?.supportedVersions?.includes(RC_VERSION) ? RC_VERSION : undefined,
+        serverInfo: discoverIdentity(discover),
+        protocolVersion: discover?.supportedVersions?.includes(SPEC_VERSION) ? SPEC_VERSION : undefined,
         instructions: discover?.instructions,
         capabilities: caps,
         tools,

package/dist/core/engine.js

@@ -6,8 +6,26 @@ export function runRules(rules, ctx) {
         try {
             findings.push(...rule.check(ctx));
         }
-        catch {
-            /* skip a throwing rule */
+        catch (err) {
+            // Say so. This used to be a bare `catch {}`, which meant a rule that
+            // threw was indistinguishable from a rule that passed - and since the
+            // grade is 100 minus the findings, a crashing rule silently RAISED the
+            // score. That is this project's documented dominant failure mode ("green
+            // because it checked nothing") sitting inside the engine every check
+            // runs through.
+            //
+            // Reported ungraded on purpose: a broken rule is our defect, not the
+            // target's, so it must not cost the target points. It must not be
+            // invisible either.
+            const id = rule.id ?? "unknown rule";
+            findings.push({
+                ruleId: "E000",
+                severity: "warn",
+                graded: false,
+                message: `rule ${id} threw and was skipped; this report is incomplete`,
+                detail: err instanceof Error ? `${err.name}: ${err.message}` : String(err),
+                fixHint: "please report this at https://github.com/efaimo-ai/efaimo/issues",
+            });
         }
     }
     return findings;

package/dist/core/grade.js

@@ -1,8 +1,14 @@
 const PENALTY = { error: 15, warn: 5, info: 1 };
 export function gradeFindings(findings) {
     let score = 100;
-    for (const f of findings)
+    // `graded: false` findings are reported but never scored; see Finding.graded
+    // and src/rules/injection.ts. Everything else counts, so a new rule has to
+    // opt out on purpose rather than by forgetting to opt in.
+    for (const f of findings) {
+        if (f.graded === false)
+            continue;
         score -= PENALTY[f.severity] ?? 0;
+    }
     score = Math.max(0, score);
     const letter = score >= 90 ? "A" : score >= 80 ? "B" : score >= 70 ? "C" : score >= 60 ? "D" : "F";
     return { score, letter };

package/dist/core/types.d.ts

@@ -8,6 +8,15 @@ export interface Finding {
     target?: string;
     detail?: string;
     fixHint?: string;
+    /**
+     * Set false by findings that must be reported but must not affect the score.
+     * Today that is the injection heuristics (E130, S105): they are shallow
+     * patterns an attacker evades trivially, and `src/rules/injection.ts` says
+     * so in its own comment. Letting them dock the grade made a linter hint
+     * behave like a security verdict, and ten of them cost a full letter.
+     * Defaults to graded, so a rule opts out deliberately or not at all.
+     */
+    graded?: boolean;
 }
 export type Surface = "mcp" | "skill";
 export interface ToolDef {
@@ -71,8 +80,16 @@ export interface ProbeResults {
     };
     /** Whether tools/list result carried the RC-required resultType field. */
     resultTypePresent?: boolean;
-    /** Whether tools/list result carried both RC-required ttlMs and cacheScope (SEP-2549). */
+    /** Whether tools/list result carried both required ttlMs and cacheScope (SEP-2549). */
     cacheFieldsPresent?: boolean;
+    /**
+     * Same question for the server/discover result, measured separately because
+     * the answer changed between the locked RC and the published spec: the RC's
+     * DiscoverResult extended plain Result, the published 2026-07-28 extends
+     * CacheableResult, so cache fields are required there now and were not then.
+     * Undefined when server/discover did not answer at all (E106's job).
+     */
+    discoverCacheFieldsPresent?: boolean;
     /** Same tool order across two fresh connections. */
     toolsOrderDeterministic?: boolean;
     /** Non-JSON noise observed on stdout before/between JSON-RPC messages (stdio only). */
@@ -170,10 +187,12 @@ export interface SkillInfo {
     frontmatterRaw: string;
     body: string;
     bodyLines: number;
+    /** `escapes` = the reference resolves outside the skill directory. weigh must not read those; S106 reports them. */
     referencedPaths: {
         raw: string;
         resolved: string;
         exists: boolean;
+        escapes: boolean;
         source: "link" | "code";
     }[];
     files: {
@@ -205,8 +224,8 @@ export interface CheckReport {
     grade: GradeInfo;
     /**
      * MCP only: 2026-07-28 readiness findings (E101-E118), reported as an
-     * ungraded migration diff. The target spec is not final until 2026-07-28,
-     * so unreadiness is a to-do list, not a quality defect.
+     * ungraded migration diff: a migration not yet made is a to-do list, not a
+     * quality defect in what shipped.
      */
     readiness?: {
         findings: Finding[];

package/dist/reporters/markdown.js

@@ -1,7 +1,19 @@
 import { VERSION } from "../version.js";
+import { safeText } from "../util/safeText.js";
 const SEV_LABEL = { error: "🔴 error", warn: "🟡 warn", info: "🔵 info" };
+// Everything through here came from the audited target, and
+// docs/INTEGRATIONS.md recommends piping --md into $GITHUB_STEP_SUMMARY, so a
+// hostile tool name or description renders into a page the reader trusts.
+// Two things were missing: control characters (raw ESC bytes were written
+// through literally) and backticks (most call sites wrap the value in a code
+// span, so one backtick closes it and the rest of the name becomes markup).
+// The backtick is neutralised with a zero-width space rather than a backslash,
+// because a backslash is not an escape inside a code span.
 function esc(s) {
-    return s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+    return safeText(s)
+        .replace(/\|/g, "\\|")
+        .replace(/`/g, "​`")
+        .replace(/\n/g, " ");
 }
 function findingsTable(lines, findings) {
     lines.push("| severity | rule | finding |");
@@ -14,7 +26,7 @@ export function renderCheckMarkdown(report) {
     const lines = [];
     lines.push(`## efaimo check (${report.surface}): grade ${report.grade.letter} (${report.grade.score})`);
     lines.push("");
-    lines.push(`target: \`${report.target}\``);
+    lines.push(`target: \`${esc(report.target)}\``);
     lines.push("");
     if (!report.findings.length) {
         lines.push(report.readiness ? "no quality findings. clean." : "no findings. clean.");
@@ -63,7 +75,7 @@ export function renderSkillSetMarkdown(res) {
 export function renderWeighMarkdown(w) {
     const lines = [];
     if (w.kind === "mcp") {
-        lines.push(`## efaimo weigh: \`${w.label}\``);
+        lines.push(`## efaimo weigh: \`${esc(w.label)}\``);
         lines.push("");
         lines.push(`tools ${w.toolCount} | resources ${w.resourceCount} | prompts ${w.promptCount}`);
         lines.push("");
@@ -88,7 +100,7 @@ export function renderWeighMarkdown(w) {
         }
     }
     else {
-        lines.push(`## efaimo weigh (skills): \`${w.label}\``);
+        lines.push(`## efaimo weigh (skills): \`${esc(w.label)}\``);
         lines.push("");
         lines.push("| skill | metadata (always) | body (on trigger) | lines | referenced files |");
         lines.push("|---|---|---|---|---|");