in2-agent-server 0.20260821.185429

package/dist/core/planFragments.js

@@ -0,0 +1,119 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parsePlanFile } from "./planFile.js";
+// The mechanical half of the fragment merge — verification, never authoring.
+//
+// When one oversized requirement is split across N analyzers, each writes
+// `requirements/<extId>/plan.fragment-<n>.json` and THE SUPERVISOR merges them into the one
+// canonical `plan.json` (playbook step 3). That merge is model-performed, and every reader
+// downstream opens literally `plan.json` — so the two failure shapes are silent by construction:
+// a merge that never happened makes the whole requirement VANISH from the wave order (a missing
+// plan.json is otherwise just "the analyzer has not run yet"), and a merge that dropped a
+// component ships a plan that looks complete. This audit closes both mechanically, from the
+// fragments themselves: fragments with no readable canonical plan are refused as unmerged, and a
+// canonical plan that omits a fragment's component — or carries a fullName two different
+// fragments both claim, the playbook's named planning error — is refused with the component named.
+//
+// The audit VERIFIES the merge rather than performing it, on purpose: concatenation and unioning
+// are mechanical, but the one-paragraph summary and any blocker-dedup judgment are the
+// supervisor's, and an implicit merge inside a derivation would hide an authoring step ("the
+// planner names the split; it never writes it"). plan_waves is the gate because it is the first
+// reader in the loop — Configuration Item ownership and writeback read the same plan.json later,
+// behind the same gate.
+//
+// Archived fragments are audited too: the playbook pins the archive at
+// `<sessionDir>/analysis/fragments/<extId>/`, which keeps the merge verifiable on every later
+// plan_waves call — a plan.json edit that drops a fragment component mid-batch is caught the same
+// way the original merge is.
+const FRAGMENT_NAME = /^plan\.fragment-\d+\.json$/;
+async function listFragments(dir) {
+    const names = await fs.readdir(dir).catch(() => []);
+    return names
+        .filter((name) => FRAGMENT_NAME.test(name))
+        .sort()
+        .map((name) => path.join(dir, name));
+}
+/**
+ * Audit every requirement's plan fragments against its canonical plan.json.
+ *
+ * Requirements with no fragments anywhere are untouched by this — the ordinary "no plan.json yet"
+ * reporting in plan_waves keeps covering them, because absence without fragments still means "the
+ * analyzer has not run", which is a state the supervisor knowingly waits out.
+ */
+export async function auditPlanFragments(root, extIds) {
+    const audit = { unmerged: [], unreadable: [], dropped: [], duplicated: [], clean: true };
+    for (const extId of extIds) {
+        const requirementDir = path.join(root, "requirements", extId);
+        const fragments = [
+            ...(await listFragments(requirementDir)),
+            ...(await listFragments(path.join(root, "analysis", "fragments", extId)))
+        ];
+        if (fragments.length === 0)
+            continue;
+        const canonicalText = await fs.readFile(path.join(requirementDir, "plan.json"), "utf8").catch(() => null);
+        const canonical = canonicalText === null ? null : parsePlanFile(canonicalText, extId);
+        if (canonical === null || !canonical.ok) {
+            // Missing and malformed refuse the same way: either way the canonical plan the fragments
+            // were supposed to become is not there to read, and ordering the batch around it would
+            // silently shrink it by one whole requirement.
+            audit.unmerged.push({ extId, fragments: fragments.map((f) => path.basename(f)) });
+            continue;
+        }
+        const canonicalKeys = new Set(canonical.plan.entries.map((entry) => entry.key));
+        const owners = new Map();
+        const droppedSeen = new Set();
+        for (const file of fragments) {
+            const fragment = path.basename(file);
+            const text = await fs.readFile(file, "utf8").catch(() => null);
+            const parsed = text === null ? null : parsePlanFile(text, extId, file);
+            if (parsed === null || !parsed.ok) {
+                audit.unreadable.push({
+                    extId,
+                    fragment,
+                    detail: parsed === null ? "unreadable" : `${parsed.error.code} — ${parsed.error.message}`
+                });
+                continue;
+            }
+            for (const entry of parsed.plan.entries) {
+                // Two entries for one key WITHIN a fragment is an ordinary revision chain; the same key
+                // across two DIFFERENT fragments is the ownership conflict. A fragment sitting in both the
+                // requirement dir and the archive is one fragment, which the basename set already says.
+                let holders = owners.get(entry.key);
+                if (holders === undefined) {
+                    holders = new Set();
+                    owners.set(entry.key, holders);
+                }
+                holders.add(fragment);
+                const droppedKey = `${fragment} ${entry.key}`;
+                if (!canonicalKeys.has(entry.key) && !droppedSeen.has(droppedKey)) {
+                    droppedSeen.add(droppedKey);
+                    audit.dropped.push({ extId, fragment, key: entry.key });
+                }
+            }
+        }
+        for (const [key, holders] of owners) {
+            if (holders.size > 1)
+                audit.duplicated.push({ extId, key, fragments: [...holders].sort() });
+        }
+    }
+    audit.clean =
+        audit.unmerged.length + audit.unreadable.length + audit.dropped.length + audit.duplicated.length === 0;
+    return audit;
+}
+/** The refusal text — each finding carries its own remediation, per the late-facet lesson. */
+export function renderFragmentAudit(audit) {
+    const lines = ["Plan fragments in this session are not resolved — nothing is ordered until they are."];
+    for (const u of audit.unmerged) {
+        lines.push("", `${u.extId}: ${u.fragments.length} fragment(s) (${u.fragments.join(", ")}) and no readable canonical plan.json — the supervisor merge has not happened.`, `  Merge them yourself (components concatenated, assumptions/blockers unioned with fragment attribution, ONE supervisor-written summary), write requirements/${u.extId}/plan.json, archive the fragments to analysis/fragments/${u.extId}/, then re-run plan_waves.`);
+    }
+    for (const u of audit.unreadable) {
+        lines.push("", `${u.extId}: ${u.fragment} cannot be parsed (${u.detail}) — the merge cannot be verified against it.`, "  Fix the fragment, or remove it if it was superseded by a corrected one.");
+    }
+    for (const d of audit.dropped) {
+        lines.push("", `${d.extId}: ${d.key} is owned by ${d.fragment} but absent from the merged plan.json — a component was dropped in the merge.`, "  Restore it to plan.json, or correct the fragment so the two agree; a merge never silently omits.");
+    }
+    for (const d of audit.duplicated) {
+        lines.push("", `${d.extId}: ${d.key} is claimed by ${d.fragments.length} fragments (${d.fragments.join(", ")}) — a planning error, never merged through.`, "  Resolve ownership with the fragments' owners and re-issue the corrected fragment(s).");
+    }
+    return lines.join("\n");
+}

package/dist/core/readsLog.js

@@ -0,0 +1,398 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { log } from "./result.js";
+import { sessionDir } from "./workspace.js";
+const PATTERN_STRENGTH = { enumeration: 0, targeted: 1, body: 2 };
+/** The stronger of two patterns — R13's per-key fold. */
+export function strongerPattern(a, b) {
+    return PATTERN_STRENGTH[a] >= PATTERN_STRENGTH[b] ? a : b;
+}
+export function readsLogPath(sessionId) {
+    return path.join(sessionDir(sessionId), "reads.jsonl");
+}
+let warned = false;
+/**
+ * Append one record. Never throws.
+ *
+ * A missing session directory, an unwritable disk or an id that fails the workspace guard all cost
+ * a single stderr line and nothing else — the read the caller asked for still returns.
+ */
+export async function appendReadRecord(sessionId, input) {
+    try {
+        const record = { ...input, at: input.at ?? new Date().toISOString() };
+        const file = readsLogPath(sessionId);
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        // One line, one append. O_APPEND keeps concurrent writers from interleaving offsets, and the
+        // reader below tolerates a torn tail rather than failing the whole log for one bad line.
+        await fs.appendFile(file, `${JSON.stringify(record)}\n`, "utf8");
+    }
+    catch (error) {
+        if (!warned) {
+            warned = true;
+            log("read provenance not being recorded:", error instanceof Error ? error.message : String(error));
+        }
+    }
+}
+/** Read the log back. A missing file is an empty log; an unparseable line is skipped, not fatal. */
+export async function readReadsLog(sessionId) {
+    let raw;
+    try {
+        raw = await fs.readFile(readsLogPath(sessionId), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // A torn final line from a killed process. Everything before it is still evidence.
+        }
+    }
+    return out;
+}
+const noOpaque = () => ({ enumeration: 0, targeted: 0, body: 0 });
+/**
+ * The session's per-org read-set: union of keys, strongest pattern per key (R13), in ONE pass.
+ *
+ * Grouped by org id when there is one, by alias otherwise. Two aliases for the same recorded id
+ * collapse into one set; two records with no id and different aliases stay apart, because nothing
+ * on hand proves they are the same org.
+ */
+export function deriveReadSet(records) {
+    const groups = new Map();
+    for (const record of records) {
+        const groupKey = record.orgId ?? `alias:${record.orgAlias}`;
+        let group = groups.get(groupKey);
+        if (!group) {
+            group = {
+                set: {
+                    orgId: record.orgId,
+                    orgAliases: [],
+                    components: [],
+                    manifests: [],
+                    opaqueReads: 0,
+                    opaqueByPattern: noOpaque(),
+                    calls: 0
+                },
+                byKey: new Map()
+            };
+            groups.set(groupKey, group);
+        }
+        const { set, byKey } = group;
+        set.calls += 1;
+        if (record.orgAlias && !set.orgAliases.includes(record.orgAlias))
+            set.orgAliases.push(record.orgAlias);
+        if (record.opaque) {
+            set.opaqueReads += 1;
+            set.opaqueByPattern[record.pattern] += 1;
+        }
+        for (const p of record.manifests ?? []) {
+            set.manifests.push({ path: p, tool: record.tool, pattern: record.pattern });
+        }
+        for (const key of record.keys) {
+            const existing = byKey.get(key);
+            if (!existing) {
+                byKey.set(key, { key, pattern: record.pattern, tools: [record.tool] });
+                continue;
+            }
+            existing.pattern = strongerPattern(existing.pattern, record.pattern);
+            if (!existing.tools.includes(record.tool))
+                existing.tools.push(record.tool);
+        }
+    }
+    return [...groups.values()].map(({ set, byKey }) => ({
+        ...set,
+        components: [...byKey.values()].sort((a, b) => a.key.localeCompare(b.key))
+    }));
+}
+// ---- sf_read identity derivation ---------------------------------------------------------------
+//
+// `sf_read` is an open-world CLI passthrough, so unlike the other probes it cannot know in advance
+// what it is about to look at. Component keys derive ONLY from metadata-shaped reads whose subject
+// maps to a metadata type; every other read appends an opaque record (plan KTD, origin R11).
+//
+// The change-scan table in direct/applyLoop.ts is the precedent, not the source. It answers a
+// different question — "which types carry a usable LastModifiedDate so we can ask what MOVED" — and
+// is therefore restricted to types with that column and enriched with scan-only filters. This table
+// answers "what identity did the rows this read returned name", so it carries the columns that
+// reconstruct a metadata fullName and includes read-only views (FieldDefinition, EntityDefinition)
+// that the change scan has no use for.
+/**
+ * Columns whose value IS the metadata fullName, in preference order — TERMINAL: never joined to a
+ * parent, never suffixed.
+ *
+ * These are the qualified sources, and being qualified is declared here rather than inferred from
+ * the value. They belong to no single shape — `FullName` is a real column on every metadata-bearing
+ * Tooling object and `fullName` is the key inside a `Metadata` payload — so they are declared once
+ * for all shapes, while a shape's `nameFields` are leaves by construction.
+ */
+const QUALIFIED_NAME_COLUMNS = ["FullName", "Metadata.fullName"];
+const ENTITY = "EntityDefinition.QualifiedApiName";
+const METADATA_QUERY_SHAPES = [
+    { object: "CustomField", metadataType: "CustomField", nameFields: ["QualifiedApiName", "DeveloperName"], parentField: ENTITY, suffix: "__c" },
+    // The read-only view describe_object queries. QualifiedApiName is exact, so no suffix guess.
+    { object: "FieldDefinition", metadataType: "CustomField", nameFields: ["QualifiedApiName"], parentField: ENTITY },
+    { object: "ValidationRule", metadataType: "ValidationRule", nameFields: ["ValidationName"], parentField: ENTITY },
+    // A Layout's metadata fullName joins object and label with a DASH, not a dot — the exact shape
+    // that made the change scan report a wave's own layouts as someone else's work.
+    { object: "Layout", metadataType: "Layout", nameFields: ["Name"], parentField: ENTITY, join: "-" },
+    { object: "CustomObject", metadataType: "CustomObject", nameFields: ["QualifiedApiName", "DeveloperName"], suffix: "__c" },
+    { object: "EntityDefinition", metadataType: "CustomObject", nameFields: ["QualifiedApiName"] },
+    { object: "CompactLayout", metadataType: "CompactLayout", nameFields: ["DeveloperName"], parentField: ENTITY },
+    { object: "RecordType", metadataType: "RecordType", nameFields: ["DeveloperName"], parentField: "SobjectType" },
+    { object: "WebLink", metadataType: "WebLink", nameFields: ["Name"], parentField: ENTITY },
+    // Flow rows are VERSIONS with no DeveloperName at all; FlowDefinition carries the API name the
+    // metadata type is addressed by.
+    { object: "FlowDefinition", metadataType: "Flow", nameFields: ["DeveloperName"] },
+    { object: "CustomTab", metadataType: "CustomTab", nameFields: ["DeveloperName"] },
+    { object: "QuickActionDefinition", metadataType: "QuickAction", nameFields: ["DeveloperName"] },
+    { object: "PermissionSet", metadataType: "PermissionSet", nameFields: ["Name"] },
+    { object: "PermissionSetGroup", metadataType: "PermissionSetGroup", nameFields: ["DeveloperName"] },
+    { object: "Profile", metadataType: "Profile", nameFields: ["Name"] },
+    { object: "FlexiPage", metadataType: "FlexiPage", nameFields: ["DeveloperName"] },
+    { object: "CustomApplication", metadataType: "CustomApplication", nameFields: ["DeveloperName"] },
+    { object: "ApexClass", metadataType: "ApexClass", nameFields: ["Name"] },
+    { object: "ApexTrigger", metadataType: "ApexTrigger", nameFields: ["Name"] }
+];
+const SHAPES_BY_OBJECT = new Map(METADATA_QUERY_SHAPES.map((s) => [s.object.toLowerCase(), s]));
+/** Tooling body columns. Selecting either means the call read the component's definition. */
+const BODY_COLUMNS = /^(metadata|fullname)$/i;
+const SUFFIXED = /__(c|mdt|e|b|x|kav|chn|history|share)$/i;
+function withSuffix(value, suffix) {
+    if (!suffix || SUFFIXED.test(value))
+        return value;
+    return `${value}${suffix}`;
+}
+/** Read a possibly-dotted column. Salesforce returns `EntityDefinition.X` NESTED, not flattened. */
+function pluck(row, column) {
+    let node = row;
+    for (const part of column.split(".")) {
+        if (!node || typeof node !== "object")
+            return undefined;
+        node = node[part];
+    }
+    return typeof node === "string" && node !== "" ? node : undefined;
+}
+function flagValue(args, ...flags) {
+    for (const flag of flags) {
+        const i = args.indexOf(flag);
+        if (i >= 0 && args[i + 1] !== undefined)
+            return args[i + 1];
+    }
+    return undefined;
+}
+/** Split a SOQL statement into the three parts identity derivation needs. Nothing else is kept. */
+function parseSoql(soql) {
+    const flat = soql.replace(/\s+/g, " ").trim();
+    const m = /^select\s+(.+?)\s+from\s+([A-Za-z][A-Za-z0-9_]*)\b(.*)$/i.exec(flat);
+    if (!m)
+        return null;
+    // A subquery in the SELECT list would make `from` the INNER object. Bailing to opaque is the
+    // right direction: a wrong key is a false accusation, a missing one is a bounded blind spot.
+    if (/\(\s*select\s/i.test(m[1]))
+        return null;
+    const tail = m[3] ?? "";
+    const w = /\bwhere\b(.*)$/i.exec(tail);
+    return { select: m[1], from: m[2], ...(w ? { where: w[1] } : {}) };
+}
+function queryPattern(select, where, shape) {
+    const columns = select.split(",").map((c) => c.trim());
+    if (columns.some((c) => BODY_COLUMNS.test(c)))
+        return "body";
+    // TARGETED means the call named the COMPONENT. A WHERE on the parent object is object-scoped
+    // enumeration — `describe_object` is exactly that shape, and calling it targeting would grade
+    // every field inventory as if the run had asked for each field by name.
+    //
+    // The lookbehind is load-bearing, not defensive: `EntityDefinition.QualifiedApiName = 'Account'`
+    // ends in a name field, so a bare word match graded every object-scoped field enumeration as a
+    // per-field targeting — the exact over-reading this pattern exists to prevent.
+    if (where && shape.nameFields.some((f) => new RegExp(`(?<![\\w.])${f}\\b`, "i").test(where)))
+        return "targeted";
+    return "enumeration";
+}
+/**
+ * The row's own fully-qualified metadata fullName, when the payload states it outright.
+ *
+ * WHY THIS EXISTS (live-caught, PV corpus Arm A, 2026-08-02). `keysFromRows` used to derive identity
+ * only by RECONSTRUCTING it from SELECTed identity columns — a name field plus a parent plus a
+ * suffix guess. But the strongest read shape selects none of them: `SELECT Metadata FROM Layout
+ * WHERE Id = '...'` is the natural way to read a definition, and it names the component nowhere in
+ * its SELECT list. So every one of Arm A's six body-graded `sf_read` calls landed opaque, and
+ * body-grade overlap was close to non-functional for `sf_read` — the one pattern that can carry a
+ * prior arm's design across arms was the one most likely to go unattributed.
+ *
+ * Tooling answers this from the payload itself. `FullName` is a real column on the metadata-bearing
+ * Tooling objects and its value IS the metadata fullName, already qualified; the `Metadata` payload
+ * carries a `fullName` of its own. Either is exact — no join, no suffix restoration, no guess — so
+ * both are terminal and neither is re-qualified with a parent.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. `Id`. A Tooling Id is not a fullName, and resolving one costs a
+ * second query against the org; recording `Layout:00h5g...` would add a key that can never join the
+ * mirror, dressing an unattributed read as an attributed one. A missing key is a bounded blind spot
+ * that the opaque count reports; a wrong key is a false accusation. The asymmetry decides it.
+ *
+ * A payload that states no name still derives nothing and stays opaque. This widens derivation to
+ * where the org already answered the question — it does not loosen it into guessing.
+ *
+ * Salesforce is deterministic about case here: the column is `FullName`, the key inside the
+ * `Metadata` payload is `fullName`. `pluck` rejects non-strings and empty strings, so a Tooling
+ * `"fullName": null` — the common shape when the column was not also selected — falls through.
+ */
+function qualifiedNameFromPayload(row) {
+    for (const column of QUALIFIED_NAME_COLUMNS) {
+        const stated = pluck(row, column);
+        if (stated)
+            return stated;
+    }
+    return undefined;
+}
+function keysFromRows(rows, shape) {
+    const keys = new Set();
+    for (const row of rows) {
+        // Preferred over reconstruction whenever present, because it is exact where reconstruction
+        // restores a dropped suffix and joins a parent the row may not even carry.
+        const stated = qualifiedNameFromPayload(row);
+        if (stated) {
+            keys.add(`${shape.metadataType}:${stated}`);
+            continue;
+        }
+        let name;
+        let matchedField;
+        for (const field of shape.nameFields) {
+            const value = pluck(row, field);
+            if (value) {
+                name = value;
+                matchedField = field;
+                break;
+            }
+        }
+        if (!name)
+            continue;
+        // QualifiedApiName is already the exact API name; only DeveloperName needs the suffix restored.
+        const leaf = matchedField === "QualifiedApiName" ? name : withSuffix(name, shape.suffix);
+        if (!shape.parentField) {
+            keys.add(`${shape.metadataType}:${leaf}`);
+            continue;
+        }
+        const parent = pluck(row, shape.parentField);
+        // An unqualified row cannot be named. Recording the bare leaf would let a foreign
+        // `Contact.Status__c` stand in for our `Account.Status__c`.
+        if (!parent)
+            continue;
+        // The join is UNCONDITIONAL, because every column in `nameFields` is a leaf. It used to be
+        // skipped when the leaf contained a dot or a dash — a string-sniffed guess at "is this already
+        // qualified?" — which silently dropped the object from any component whose own label carries a
+        // version number or a region dash: `PV Asset Layout v1.2` on `PV_Asset__c` keyed as
+        // `Layout:PV Asset Layout v1.2`, a key that can never join the mirror. Qualified values come
+        // from QUALIFIED_NAME_COLUMNS and have already returned above.
+        keys.add(`${shape.metadataType}:${parent}${shape.join ?? "."}${leaf}`);
+    }
+    return [...keys];
+}
+const EMPTY = (scope, object) => ({
+    ...(object ? { object } : {}),
+    pattern: "enumeration",
+    keys: [],
+    opaque: true,
+    scope,
+    rows: 0
+});
+/**
+ * Classify one `sf_read` call into a provenance record.
+ *
+ * `result` is the parsed `--json` envelope. Three shapes derive identities — a metadata-shaped SOQL
+ * query, `org list metadata`, and `sobject describe`, all of which return component names as data.
+ * Everything else (record data, limits, org display, an unrecognized command) is opaque BY DESIGN:
+ * the read happened and is recorded as unaccounted-for rather than dropped.
+ */
+export function classifySfRead(args, result) {
+    const canonical = args.filter((a) => !a.startsWith("-"));
+    const verb = args.slice(0, 3).join(" ").toLowerCase();
+    if (args[0] === "data" && args[1] === "query") {
+        const soql = flagValue(args, "-q", "--query");
+        const records = recordsOf(result);
+        const parsed = soql ? parseSoql(soql) : null;
+        if (!parsed)
+            return EMPTY("data query");
+        const shape = SHAPES_BY_OBJECT.get(parsed.from.toLowerCase());
+        // The object is recorded either way — an opaque record naming `Account` is what tells a later
+        // report this run read record data, not that it read nothing.
+        if (!shape)
+            return { ...EMPTY(`data query ${parsed.from}`, parsed.from), rows: records.length };
+        const keys = keysFromRows(records, shape);
+        return {
+            object: parsed.from,
+            pattern: queryPattern(parsed.select, parsed.where, shape),
+            keys,
+            // Rows that named nothing derivable (a COUNT(), an aggregate, a bare Id list) leave the read
+            // unaccounted for even though its object mapped.
+            opaque: keys.length === 0,
+            scope: `data query ${parsed.from}`,
+            rows: records.length
+        };
+    }
+    if (args[0] === "org" && args[1] === "list" && args[2] === "metadata") {
+        const type = flagValue(args, "-m", "--metadata-type");
+        // The response literally carries {type, fullName} per row — the one read shape whose identities
+        // need no reconstruction at all.
+        const rows = Array.isArray(result?.result)
+            ? (result.result)
+            : [];
+        const keys = [
+            ...new Set(rows
+                .map((r) => {
+                const full = typeof r.fullName === "string" ? r.fullName : undefined;
+                const t = typeof r.type === "string" ? r.type : type;
+                return full && t ? `${t}:${full}` : undefined;
+            })
+                .filter((k) => Boolean(k)))
+        ];
+        return {
+            ...(type ? { object: type } : {}),
+            pattern: "enumeration",
+            keys,
+            opaque: keys.length === 0,
+            scope: `org list metadata${type ? ` ${type}` : ""}`,
+            rows: rows.length
+        };
+    }
+    if (args[0] === "sobject" && args[1] === "describe") {
+        const subject = flagValue(args, "-s", "--sobject");
+        const described = result?.result;
+        const objectName = typeof described?.name === "string" ? described.name : subject;
+        const fields = Array.isArray(described?.fields) ? described.fields : [];
+        if (!objectName)
+            return EMPTY("sobject describe");
+        // A describe is a full field ENUMERATION of one object — the same access as describe_object,
+        // through a different door. Leaving it opaque would let a run enumerate an entire corpus here
+        // and still report an empty read-set.
+        //
+        // STANDARD fields are keyed too, not just `__c` ones: a field is a `CustomField` component
+        // whether or not its API name carries the suffix, and a delivered picklist-value change on
+        // `Account.Industry` is exactly the kind of prior-arm work this join has to be able to see.
+        const keys = new Set([`CustomObject:${objectName}`]);
+        for (const f of fields) {
+            const name = typeof f.name === "string" ? f.name : undefined;
+            if (name)
+                keys.add(`CustomField:${objectName}.${name}`);
+        }
+        return {
+            object: objectName,
+            pattern: "enumeration",
+            keys: [...keys],
+            opaque: false,
+            scope: `sobject describe ${objectName}`,
+            rows: fields.length
+        };
+    }
+    return EMPTY(canonical.slice(0, 3).join(" ") || verb || "sf_read");
+}
+function recordsOf(result) {
+    const records = result?.result?.records;
+    return Array.isArray(records) ? records : [];
+}

package/dist/core/registration.js

@@ -0,0 +1,24 @@
+// Tool registration instrumentation.
+//
+// The survivor of core/hotSwap.ts (deleted 2026-08-21 with the bespoke updater — the tool surface
+// is fixed for the life of the process now, like any other MCP server's). What stays is the part
+// that was never about swapping: wrapping registerTool ONCE so every tool — present and future —
+// is timed by telemetry without each module having to remember, and keeping the roster of
+// registered names for the startup log.
+const names = new Set();
+let patched = false;
+export function instrumentRegistration(server, telemetry) {
+    if (patched)
+        return;
+    patched = true;
+    const original = server.registerTool.bind(server);
+    server.registerTool = (...args) => {
+        const [name, config, handler] = args;
+        const registered = original(name, config, telemetry.instrument(name, handler));
+        names.add(name);
+        return registered;
+    };
+}
+export function registeredToolNames() {
+    return [...names].sort();
+}

package/dist/core/result.js

@@ -0,0 +1,38 @@
+// stdout is the JSON-RPC channel; all logging goes to stderr.
+export const log = (...args) => console.error("[cc-mcp]", ...args);
+/**
+ * The text is MIRRORED into structuredContent, and that mirror is load-bearing, not belt-and-braces.
+ *
+ * LIVE-CAUGHT (QA round 4, 2026-08-20): Claude Code delivers an MCP result's structuredContent to
+ * the model and silently drops every text block beside it (v2.0.21+; upstream #55677/#15412/#9962,
+ * closed not-planned). A tester activated on a 5-day-stale build and the composed STOP block, the
+ * viewer URL, and the next-steps all vanished — he had to ask for the update by hand. fail() never
+ * suffered this because its message already lives inside structuredContent; org.ts's CF75 comment
+ * records the same mechanism found per-tool. So: on the client we actually ship to, prose a tool
+ * returns beside a structured payload REACHES THE MODEL ONLY THROUGH THIS FIELD.
+ *
+ * `mirrorText: false` is for the handful of results whose text provably duplicates the structured
+ * payload byte-for-byte (sf_read's parsed branch) — mirroring there doubles the largest payloads in
+ * the loop for zero information. Never opt out a result whose text carries an instruction.
+ */
+export function ok(text, structured, opts) {
+    const mirror = opts?.mirrorText !== false && structured !== undefined && structured.text === undefined;
+    return {
+        content: [{ type: "text", text }],
+        ...(structured ? { structuredContent: { ...structured, ...(mirror ? { text } : {}) } } : {})
+    };
+}
+export function fail(code, message, structured) {
+    return {
+        content: [{ type: "text", text: `${code}: ${message}` }],
+        isError: true,
+        structuredContent: { error: { code, message }, ...(structured ?? {}) }
+    };
+}
+export function internalError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return fail("INTERNAL_ERROR", message);
+}
+export function stdoutTail(stdout, lines = 30) {
+    return stdout.split("\n").slice(-lines).join("\n");
+}