in2-agent-server 0.20260821.185429

package/dist/tools/org.js

@@ -0,0 +1,739 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { fail, internalError, ok, stdoutTail } from "../core/result.js";
+import { WorkspaceError, sessionDir } from "../core/workspace.js";
+import { loadSession } from "./session.js";
+import { SessionOrgError, resolveSessionOrg } from "../core/sessionOrg.js";
+import { GateError, assertTargetOrg } from "../core/gate.js";
+import { runProcess, sfCliEnv } from "../core/spawn.js";
+import { sfQueryTruncation } from "../core/sfQuery.js";
+import { appendReadRecord, classifySfRead } from "../core/readsLog.js";
+// Turn an sf CLI failure into something a supervisor can act on.
+//
+// `sf --json` prints a full error object on failure — name, message, exitCode, a stack, and a cause
+// carrying a SECOND stack. Echoing that raw put ~40 lines of jsforce internals into the transcript
+// for what was usually a one-line fact, and buried the fact.
+//
+// The case that matters most is NOT_FOUND on an sobject describe, which in this workflow is
+// ORDINARY rather than broken: the batch's whole purpose is to create objects that do not exist
+// yet, so describing one before it is applied is the expected answer, not a malfunction. Rendered
+// as a raw stack it reads like the toolchain is failing, and invites the supervisor to go
+// debugging instead of getting on with creating the thing.
+//
+// Still fail-closed: this is reported as a failure, never as a clean empty read. It says what
+// happened, not that nothing is wrong.
+export function sfReadFailure(matched, args, exitCode, body, stderr) {
+    const command = matched.join(" ");
+    let code;
+    let message;
+    try {
+        const parsed = JSON.parse(body);
+        code = parsed.errorCode ?? parsed.data?.errorCode ?? parsed.name;
+        message = parsed.message;
+    }
+    catch {
+        // Not JSON — fall through to the tail, which is still better than the whole buffer.
+    }
+    if (!code) {
+        return fail("SF_READ_FAILED", `sf ${command} exited ${exitCode}.\n${stdoutTail(body || stderr, 15)}`);
+    }
+    // Read the subject from ARGS, not from `matched` — `matched` is only the allowlist entry
+    // ("sobject describe"), so the flag is never in it. And guard the index: indexOf returning -1
+    // would make `[-1 + 1]` read element 0 and confidently report that "sobject" does not exist.
+    const flag = [args.indexOf("-s"), args.indexOf("--sobject")].find((i) => i >= 0);
+    const subject = flag === undefined ? undefined : args[flag + 1];
+    if (code === "NOT_FOUND" && matched.includes("describe")) {
+        return fail("SF_NOT_FOUND", [
+            `${subject ?? "That component"} does not exist in this org.`,
+            "If the batch is supposed to create it, this is the expected answer before it is applied —",
+            "carry on and create it. If it was supposed to already exist, the API name in the requirement",
+            "is wrong; project the org to see what is actually there."
+        ].join("\n"));
+    }
+    // INVALID_TYPE is "that API cannot see this type", NOT "this type does not exist" — and the two
+    // have different remedies. Live-caught (EV-31…40): `data query` on CustomPermission failed here,
+    // the run read the refusal as absence, and `org list metadata -m CustomPermission` returned the
+    // very components it had just concluded were missing. The crib belongs in the message because
+    // this is the one moment the caller is certain to be reading it.
+    if (code === "INVALID_TYPE") {
+        const named = /sObject type '([^']+)' is not supported/.exec(message ?? "")?.[1];
+        const subject = named ?? "That type";
+        return fail("SF_READ_FAILED", [
+            `${subject} is not queryable through that API. INVALID_TYPE means the API cannot SEE it — not that it does not exist.`,
+            `Retry with --use-tooling-api; if that also refuses, enumerate it as metadata instead — ["org","list","metadata","-m","${named ?? "<Type>"}"] — which is the path that works for CustomPermission and other types no query API exposes.`
+        ].join("\n"));
+    }
+    return fail("SF_READ_FAILED", `sf ${command} failed: ${code}${message ? ` — ${message}` : ""}`);
+}
+// Read-only advisory probes. Fail-closed posture throughout: an org-read error is
+// reported as an error, never as "does not exist".
+const OBJECT_NAME_RE = /^[A-Za-z][A-Za-z0-9_]{0,79}(__c|__mdt|__e)?$/;
+// Read-only sf CLI passthrough. list_components covers a FIXED set of types,
+// so anything outside it dead-ends (live-caught: a run needed a type the tool did not cover and
+// had nowhere to go). SOQL + describe are open-world, so this closes the gap dynamically instead
+// of growing another hand-maintained table.
+//
+// NOT the gate — this list only supplies a friendly label for messages. The gate is sfReadRefusal,
+// which works on canonical segments and refuses by verb. There is no shell (execFile with an argv
+// array), so redirection and command chaining remain impossible either way.
+export const SF_READ_ONLY_COMMANDS = [
+    ["data", "query"],
+    ["data", "get", "record"],
+    ["sobject", "describe"],
+    ["sobject", "list"],
+    ["org", "display"],
+    ["org", "list"],
+    ["limits", "display"]
+];
+/**
+ * DENY-list of everything that can change an org, a file tree, or an auth store. Anything not
+ * matched here is allowed through unchanged.
+ *
+ * This was an ALLOW-list of seven command prefixes, and it was the wrong shape. The Salesforce CLI
+ * has a large read surface — `data export`, `data search`, `org list metadata`, `apex list log`,
+ * `apex get log`, `package version list`, `force:schema` and more — and every one of them refused
+ * with "not on the allowlist" even though none can write. The tool therefore fought its user on
+ * legitimate questions while providing no real safety, because a model with Bash can call the same
+ * CLI directly; the allowlist only ever constrained the honest path. Measured cost across one week:
+ * 217 calls, 56 failures.
+ *
+ * Inverting it keeps the one property worth keeping — no mutation reaches an org except through
+ * direct_apply and its evidence loop — and stops pretending a curated list of seven commands is the
+ * whole of "reading Salesforce".
+ *
+ * Named families only. This list is the FIRST of three layers and the weakest — it says nothing
+ * about a command it has never heard of, which is how `sf deploy metadata` (a live alias for
+ * `project deploy start`), the colon spelling of every entry below, and 146 unenumerated commands
+ * all ran unchallenged until 2026-07-31. The verb rules in sfReadRefusal are what actually hold.
+ *
+ * Kept anyway: an explicit family gives a precise refusal message, and it names the specific
+ * commands this loop must never take even if someone later widens SF_READ_VERBS.
+ */
+export const SF_WRITE_COMMANDS = [
+    ["project", "deploy"],
+    ["project", "retrieve"],
+    ["project", "delete"],
+    ["project", "convert"],
+    ["project", "generate"],
+    ["data", "create"],
+    ["data", "update"],
+    ["data", "delete"],
+    ["data", "upsert"],
+    ["data", "import"],
+    ["data", "resume"],
+    ["apex", "run"],
+    ["apex", "test"],
+    ["org", "create"],
+    ["org", "delete"],
+    ["org", "login"],
+    ["org", "logout"],
+    ["org", "resume"],
+    ["org", "enable"],
+    ["org", "disable"],
+    ["org", "assign"],
+    ["package", "create"],
+    ["package", "install"],
+    ["package", "uninstall"],
+    // NOT ["package","version"] wholesale — `package version list` and `package version report` are
+    // reads. Only the mutating verbs.
+    ["package", "version", "create"],
+    ["package", "version", "delete"],
+    ["package", "version", "promote"],
+    ["package", "version", "update"],
+    ["alias", "set"],
+    ["alias", "unset"],
+    ["config", "set"],
+    ["config", "unset"],
+    ["schema", "generate"],
+    ["sobject", "create"],
+    ["force", "source"],
+    ["force", "data"],
+    ["force", "apex"],
+    ["force", "org"],
+    ["force", "mdapi"],
+    ["force", "package"],
+    ["agent", "create"],
+    ["lightning", "generate"],
+    ["static-resource", "generate"],
+    ["visualforce", "generate"],
+    ["community", "create"],
+    ["analytics", "generate"]
+];
+/**
+ * The command as the CLI will actually resolve it: lowercased segments, before any flag.
+ *
+ * oclif accepts `sf project deploy start`, `sf project:deploy:start` and `sf project deploy:start`
+ * interchangeably. A gate that compares raw argv segments sees three different commands and blocks
+ * one of them, which is exactly what happened here — `matchedWriteCommand` matched literal argv
+ * from index 0, so `["project:deploy:start", "-x", "package.xml"]` walked straight through and
+ * deployed metadata. Normalising first is what makes any of the checks below meaningful.
+ */
+export function canonicalSegments(args) {
+    const leading = [];
+    for (const arg of args) {
+        if (arg.startsWith("-"))
+            break;
+        leading.push(arg);
+    }
+    return leading
+        .join(":")
+        .split(":")
+        .map((segment) => segment.trim().toLowerCase())
+        .filter((segment) => segment.length > 0);
+}
+// Verbs that CHANGE something — an org, an auth store, a local tree, a package, a subscriber.
+// Checked against every segment, so a write verb anywhere in the path is refused whatever the topic
+// and whatever position it sits in (`org create user`, `force source deploy`, `package1 version
+// create`). Topic-prefix matching cannot do this: it has to know the topic in advance.
+const SF_WRITE_VERBS = new Set([
+    "create", "update", "delete", "upsert", "import", "install", "uninstall", "deploy", "retrieve",
+    "convert", "generate", "set", "unset", "run", "execute", "publish", "activate", "deactivate",
+    "enable", "disable", "assign", "promote", "reset", "refresh", "login", "logout",
+    "store", "grant", "revoke", "cancel", "schedule", "push-upgrade", "start", "restart", "stop",
+    "add", "remove", "rename", "move", "copy", "write", "apply", "migrate", "seed", "init"
+    // NOT "resume": `data query resume` collects a bulk query's results and only reads. The write
+    // resumes (`data import resume`, `data upsert resume`) already carry a write verb of their own,
+    // and `org resume sandbox` has no read verb, so it is refused by default anyway.
+]);
+// Verbs that only READ. A command must contain one of these to run at all, so anything Salesforce
+// ships in the future is refused until someone looks at it — the property the old comment claimed
+// ("an unknown FUTURE subcommand of a dangerous family is blocked") and the old code did not have.
+//
+// The verb is not always last (`data get record`, `org list metadata`) and not always second
+// (`package version list`), which is why this matches ANY segment rather than a fixed position.
+const SF_READ_VERBS = new Set([
+    "query", "get", "list", "describe", "display", "report", "search", "export", "preview", "diff",
+    "check", "validate", "status", "history", "view", "read", "print", "show", "info", "log", "logs"
+]);
+/**
+ * Commands that hand back a CREDENTIAL rather than data.
+ *
+ * `org auth show-sfdx-auth-url` returns a `force://` URL containing the REFRESH TOKEN — durable,
+ * full-privilege access to the org from any machine, long after this session ends. It reads rather
+ * than writes, so no verb rule can catch it; it has to be named. `org open` is the same shape (a
+ * frontdoor URL carrying a live session), and `org display --verbose` prints the same auth URL as
+ * `show-sfdx-auth-url`.
+ *
+ * `org display` WITHOUT --verbose still returns an access token and is still allowed, because it is
+ * how the loop resolves instance hosts and it was reachable under the old allowlist too. That is a
+ * deliberate line, not an oversight: a short-lived session token the harness already holds, versus
+ * a refresh token it does not.
+ */
+function credentialExposure(segments, args) {
+    if (segments.includes("auth"))
+        return segments.join(" ");
+    if (segments[0] === "org" && segments[1] === "open")
+        return "org open";
+    if (segments[0] === "org" && segments[1] === "display" && args.includes("--verbose")) {
+        return "org display --verbose";
+    }
+    return null;
+}
+/** The write family this command belongs to, or null when no explicit family matches. */
+export function matchedWriteCommand(args) {
+    const segments = canonicalSegments(args);
+    return SF_WRITE_COMMANDS.find((cmd) => cmd.every((seg, i) => segments[i] === seg)) ?? null;
+}
+/**
+ * Why this command may not run, or null to allow it.
+ *
+ * Three layers, cheapest first. The explicit family list is kept because it names the specific
+ * commands this loop must never take, but it is no longer load-bearing on its own: the verb rules
+ * below are what make an UNLISTED command safe by default. Before this, `sf deploy metadata` (a
+ * live alias for `project deploy start`) and `sf api request graphql --body mutation.txt` were both
+ * permitted, and so was every one of the 146 commands nobody had thought to enumerate.
+ */
+export function sfReadRefusal(args) {
+    const segments = canonicalSegments(args);
+    if (segments.length === 0)
+        return "sf_read needs a command.";
+    const credential = credentialExposure(segments, args);
+    if (credential) {
+        return `sf_read will not run "${credential}" — it returns a credential rather than data. If an org needs re-authenticating, the operator does that through org_login.`;
+    }
+    const family = SF_WRITE_COMMANDS.find((cmd) => cmd.every((seg, i) => segments[i] === seg));
+    const writeVerb = segments.find((segment) => SF_WRITE_VERBS.has(segment));
+    if (family || writeVerb) {
+        const named = family ? family.join(" ") : `${segments.join(" ")}`;
+        return `sf_read is read-only and "${named}" mutates. Org changes flow through direct_apply, which projects before and after, diffs three ways and leaves an evidence bundle — none of which happens if a write goes around it.`;
+    }
+    if (!segments.some((segment) => SF_READ_VERBS.has(segment))) {
+        return `sf_read does not recognise "${segments.join(" ")}" as a read. Commands are allowed by their verb (query, list, describe, display, get, report, search…), so anything new is refused until it is reviewed rather than assumed safe. If this genuinely only reads, add its verb to SF_READ_VERBS.`;
+    }
+    return null;
+}
+export const SF_TARGET_FLAGS = new Set(["-o", "--target-org", "-u", "--targetusername"]);
+const SF_OUTPUT_CAP = 24_000;
+export function matchedReadCommand(args) {
+    return SF_READ_ONLY_COMMANDS.find((cmd) => cmd.every((seg, i) => args[i] === seg)) ?? null;
+}
+/**
+ * Resolve the org a READ should hit, allowing the symbolic role "campfire".
+ *
+ * A session is bound to TWO orgs — the target org it deploys to, and the Campfire consultant org
+ * it reads requirements from and writes Configuration Items back to. Every read tool defaulted to
+ * the target and could otherwise only take a literal alias, so verifying a writeback meant the
+ * supervisor GUESSING the consultant org's alias from nothing.
+ *
+ * Live (CF77): the first verification query ran against the deploy target and failed
+ * `INVALID_TYPE: Campfire_Configuration_Item__c is not supported` — correct, that object lives in
+ * the other org. The next attempt hard-coded an alias remembered from an unrelated context. The
+ * session knew the answer the whole time; the campfire write tools resolve it by role on every
+ * call. This just exposes the same lookup to reads.
+ *
+ * Returns the ORG ID as well as the alias. Read provenance joins on the id (R9): an alias is
+ * operator-controlled and can be repointed, so keying a contamination report on one would let a
+ * repoint silently merge two orgs' read-sets. A literal `targetOrg` override names an org this
+ * session was never bound to, so there is no recorded id to report — null, honestly, rather than an
+ * `sf org display` round-trip on every read.
+ */
+async function resolveReadOrg(sessionId, override) {
+    const requested = override?.trim();
+    if (requested && requested !== "campfire" && requested !== "target")
+        return { alias: requested, orgId: null };
+    const role = requested === "campfire" ? "campfire" : "target";
+    // verify:false — reading the wrong org is visible and harmless, and the round-trip is not free.
+    const binding = await resolveSessionOrg(await loadSession(sessionId), role, { verify: false });
+    return { alias: binding.alias, orgId: binding.orgId ?? null };
+}
+/** Drop the `attributes` envelope Salesforce puts on every SOQL record. */
+function stripAttributes(value) {
+    if (Array.isArray(value))
+        return value.map(stripAttributes);
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (k === "attributes")
+            continue;
+        out[k] = stripAttributes(v);
+    }
+    return out;
+}
+export function registerOrgTools(server) {
+    server.registerTool("sf_read", {
+        description: "READ-ONLY sf CLI passthrough — works like the CLI. Pass any `sf` arguments WITHOUT the leading `sf` and without a target flag (the org is injected); --json is added unless you pass it. " +
+            "Commands are allowed BY VERB, so any non-mutating command runs (`data query` — add --use-tooling-api for Tooling objects — `sobject describe`, `org list metadata`, `apex get log`, and anything else that only reads); a mutating or unrecognised one is refused with the reason and the alternative. " +
+            "OVERSIZE OUTPUT IS NEVER DISCARDED: past the inline cap the full result is written to <session>/sf-read/ and the response carries the path, the row count and the first 2,000 chars, so a big describe becomes a file to grep rather than a refusal.",
+        inputSchema: {
+            sessionId: z.string().describe("The session whose org to read. Supplies the org so the alias never has to be restated."),
+            targetOrg: z
+                .string()
+                .optional()
+                .describe("Omit for the session's deploy target, which is the normal case. Pass \"campfire\" to read the session's Campfire CONSULTANT org — where requirements, Configuration Items and Deployment Tasks live — without knowing its alias; that is how you verify a writeback landed. Any other value is a literal alias, the open-world escape hatch for an org this session is not bound to."),
+            args: z
+                .array(z.string())
+                .min(1)
+                .describe('sf arguments without the leading "sf", e.g. ["data","query","-q","SELECT Id FROM Account LIMIT 1"] or ["sobject","describe","-s","CF71_Intake_Request__c"].'),
+            timeoutMs: z.number().optional().describe("Default 120000.")
+        }
+    }, async ({ sessionId, targetOrg: targetOrgOverride, args, timeoutMs }) => {
+        try {
+            // Session-derived by default; an explicit targetOrg is an intentional override for reading
+            // an org this session is not bound to. Reads skip the alias re-check (verify:false) —
+            // reading the wrong org is visible and harmless, and the round-trip is not free.
+            const org = await resolveReadOrg(sessionId, targetOrgOverride);
+            const targetOrg = org.alias;
+            assertTargetOrg(targetOrg);
+            // Gated on the CLI's own canonical form (colon and space spellings collapse to one), by
+            // VERB rather than by topic prefix, so an unlisted command is refused rather than assumed
+            // safe. See sfReadRefusal.
+            const refusal = sfReadRefusal(args);
+            if (refusal)
+                return fail("SF_COMMAND_NOT_ALLOWED", refusal);
+            // Label for messages only. An unrecognised-but-safe command is fine and simply names itself.
+            const matched = matchedReadCommand(args) ?? args.slice(0, 2);
+            const conflicting = args.find((a) => SF_TARGET_FLAGS.has(a));
+            if (conflicting) {
+                return fail("SF_TARGET_FLAG_CONFLICT", `Remove ${conflicting} from args — the target org is injected from the targetOrg parameter.`);
+            }
+            const full = [...args, "--target-org", targetOrg, ...(args.includes("--json") ? [] : ["--json"])];
+            const run = await runProcess("sf", full, { env: sfCliEnv(), timeoutMs: timeoutMs ?? 120_000 });
+            const raw = run.stdout.trim();
+            // READ PROVENANCE (R9, R11-R12). Recorded HERE — after the org answered, before any branch
+            // returns — so every path that reached the org leaves exactly one record and no path that
+            // did not (a gate refusal, a target-flag conflict) leaves any.
+            //
+            // sf_read is the open-world door, so it is the one probe that cannot know in advance what it
+            // is looking at. classifySfRead derives keys only from metadata-shaped reads and marks
+            // everything else OPAQUE rather than silently clean; the RAW QUERY never enters the record,
+            // only the object it named, because the reads segment ships in a provenance parcel while
+            // <session>/sf-read/ stays on this machine.
+            //
+            // Parsed ONCE, here, and reused by both branches below. A 5 MB describe is exactly the case
+            // this tool exists to handle well, and parsing it three times to answer three questions
+            // about the same bytes is the kind of cost that only shows up on the reads that hurt.
+            let parsedRaw;
+            try {
+                parsedRaw = JSON.parse(raw);
+            }
+            catch {
+                // Not JSON — classification falls through to an opaque record, which is the truth.
+            }
+            {
+                const seen = classifySfRead(args, parsedRaw);
+                const succeeded = run.exitCode === 0 && !run.timedOut;
+                await appendReadRecord(sessionId, {
+                    tool: "sf_read",
+                    orgId: org.orgId,
+                    orgAlias: targetOrg,
+                    scope: seen.scope,
+                    pattern: seen.pattern,
+                    keys: succeeded ? seen.keys : [],
+                    rows: succeeded ? seen.rows : 0,
+                    durationMs: run.durationMs,
+                    outcome: succeeded ? "ok" : "failed",
+                    ...(seen.object ? { object: seen.object } : {}),
+                    // A FAILED read saw nothing, so it is not an unaccounted-for read — counting it opaque
+                    // would inflate the very number that bounds the clean claim.
+                    ...(succeeded && seen.opaque ? { opaque: true } : {})
+                });
+            }
+            if (run.timedOut)
+                return fail("SF_TIMEOUT", `sf ${matched.join(" ")} timed out.`);
+            const truncated = raw.length > SF_OUTPUT_CAP;
+            const body = truncated ? `${raw.slice(0, SF_OUTPUT_CAP)}\n…[truncated ${raw.length - SF_OUTPUT_CAP} chars — narrow the query]` : raw;
+            if (run.exitCode !== 0) {
+                return sfReadFailure(matched, args, run.exitCode, body, run.stderr);
+            }
+            if (truncated) {
+                // SPILL, don't refuse.
+                //
+                // This used to answer a legitimate question with nothing: the org had replied, the answer
+                // was correct, and the tool discarded it because it was large. That is the single worst
+                // thing a read tool can do — worse than truncating, because the caller is left with no
+                // data AND no file to go look at. It is what a developer would never accept from `sf`,
+                // where the obvious move is `sf ... > out.json` and then grep it.
+                //
+                // The full output now goes to disk and the response carries a readable head plus the
+                // path, so the answer is always recoverable: Read it with an offset, grep it, or narrow
+                // the query — the caller's choice, made with the data in hand rather than instead of it.
+                //
+                // (The cap itself stays: a 5 MB describe pasted into the context window is its own kind
+                // of failure, and the reason the cap existed in the first place.)
+                const dir = path.join(sessionDir(sessionId), "sf-read");
+                await fs.mkdir(dir, { recursive: true });
+                const file = path.join(dir, `${Date.now()}-${matched.join("-").replace(/[^a-z0-9-]/gi, "")}.json`);
+                await fs.writeFile(file, raw, "utf8");
+                // Not every read is a query envelope; the file is the answer either way.
+                const envelope = parsedRaw?.result;
+                const rows = envelope?.totalSize ?? envelope?.records?.length;
+                const describe = matched[0] === "sobject" && matched[1] === "describe";
+                const subject = args[args.indexOf("-s") + 1] ?? args[args.indexOf("--sobject") + 1];
+                return ok([
+                    `sf ${matched.join(" ")} returned ${raw.length.toLocaleString()} chars${rows !== undefined ? ` (${rows.toLocaleString()} rows)` : ""} — over the ${SF_OUTPUT_CAP.toLocaleString()}-char inline cap, so the FULL output was written to:`,
+                    `  ${file}`,
+                    "",
+                    "Nothing was lost. Read that file (with an offset for a slice), grep it, or re-run a narrower query.",
+                    describe
+                        ? `For a field inventory specifically, describe_object {sessionId, objectApiName: "${subject ?? "<object>"}", match: "<term>"} answers the same question compactly.`
+                        : "",
+                    "",
+                    "First 2,000 chars:",
+                    raw.slice(0, 2_000)
+                ]
+                    .filter(Boolean)
+                    .join("\n"), {
+                    command: matched.join(" "),
+                    truncated: true,
+                    spilledTo: file,
+                    bytes: raw.length,
+                    ...(rows !== undefined ? { rows } : {})
+                });
+            }
+            // THE ROWS MUST BE IN structuredContent, not only in the text.
+            //
+            // Live-caught CF75: this returned {command, truncated} as its structured payload and put the
+            // records in the text alone. A client that renders structuredContent when present therefore
+            // showed the caller an envelope with no rows, on every single query. The run concluded the
+            // tool was broken, stopped using it, and — worse — briefly asserted a namespace was empty on
+            // the strength of a read that had returned nothing. A read tool that silently returns
+            // nothing is a correctness hazard, not an inconvenience.
+            //
+            // The two tools that appeared to "work" prove the mechanism: fail() nests the message inside
+            // structuredContent, and describe_object nests its `fields` there — so errors and field
+            // inventories both rendered, while sf_read's rows never did.
+            //
+            // `parsedRaw` is `body` here — truncation returned above, so raw and body are the same
+            // bytes. Undefined when the output was not JSON, in which case the text is the only
+            // representation, which is correct: there is nothing structured to hand back.
+            let parsed;
+            // Salesforce echoes an `attributes` block ({type, url}) on EVERY record. It is never the
+            // answer to anything — the type is in the query, the id is already a field — and it costs
+            // ~109 chars per row. One 80-row enumeration in the CF78 run carried 8.5 KB of it, and
+            // every query pays proportionally. Stripped here rather than asked of every caller.
+            if (parsedRaw && typeof parsedRaw === "object" && "result" in parsedRaw) {
+                parsed = { result: stripAttributes(parsedRaw.result) };
+            }
+            // The mirror is off exactly when `result` rides structuredContent, and on otherwise.
+            // `parsed === undefined` is NOT "parsing failed" — it also covers a valid JSON envelope
+            // with no `result` key (org list, some tooling reads). Both cases mirror, and must: with
+            // the client dropping the content channel (ok()'s header), whatever is not in
+            // structuredContent does not exist for the model, and CF75 was precisely a read whose rows
+            // rode the text alone. The wire carries the body twice on the mirrored branches; the model
+            // sees it once either way, which is the budget that matters.
+            return ok(body || "(empty result)", {
+                command: matched.join(" "),
+                truncated,
+                ...(parsed ?? {})
+            }, { mirrorText: parsed === undefined });
+        }
+        catch (error) {
+            if (error instanceof GateError)
+                return fail(error.code, error.message);
+            if (error instanceof SessionOrgError)
+                return fail(error.code, error.message);
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+    server.registerTool("list_components", {
+        description: "Enumerate the org's actual candidates for one component family — DISCOVERY, which project_org cannot do (it can only project components you can already name). Use when a binding is ambiguous or missing: 19 Account layouts, no 'Sales User' profile. Read-only, fail-closed, session-scoped. Layout and RecordType require objectApiName. Pass `match` to narrow. Prefer this over hand-writing the SOQL through sf_read: the queries encode traps (Layout needs the Tooling API; PermissionSet must exclude IsOwnedByProfile, or profile-owned sets come back looking like real ones).",
+        inputSchema: {
+            sessionId: z.string().describe("The session whose org to read. Supplies the org so the alias never has to be restated."),
+            targetOrg: z
+                .string()
+                .optional()
+                .describe("Omit for the session's deploy target, which is the normal case. Pass \"campfire\" to describe/list against the session's Campfire CONSULTANT org without knowing its alias — use it before querying Campfire objects rather than guessing a field or relationship name. Any other value is a literal alias."),
+            typeName: z.enum(["Layout", "Profile", "PermissionSet", "PermissionSetGroup", "RecordType"]),
+            objectApiName: z
+                .string()
+                .optional()
+                .describe("Required for Layout and RecordType: the object whose candidates to list."),
+            match: z.string().optional().describe("Case-insensitive substring filter on the returned names. An org can have hundreds of profiles and permission sets.")
+        }
+    }, async ({ sessionId, targetOrg: targetOrgOverride, typeName, objectApiName, match }) => {
+        try {
+            // Session-derived by default; an explicit targetOrg is an intentional override for reading
+            // an org this session is not bound to. Reads skip the alias re-check (verify:false) —
+            // reading the wrong org is visible and harmless, and the round-trip is not free.
+            const org = await resolveReadOrg(sessionId, targetOrgOverride);
+            const targetOrg = org.alias;
+            assertTargetOrg(targetOrg);
+            const needsObject = typeName === "Layout" || typeName === "RecordType";
+            if (needsObject) {
+                if (!objectApiName) {
+                    return fail("OBJECT_REQUIRED", `${typeName} enumeration requires objectApiName.`);
+                }
+                if (!OBJECT_NAME_RE.test(objectApiName)) {
+                    return fail("INVALID_OBJECT_NAME", `Object API name ${JSON.stringify(objectApiName)} fails the allowlist charset guard.`);
+                }
+            }
+            let soql;
+            let tooling = false;
+            let mapRow;
+            switch (typeName) {
+                case "Layout":
+                    soql = `SELECT Name FROM Layout WHERE EntityDefinition.QualifiedApiName = '${objectApiName}' ORDER BY Name`;
+                    tooling = true;
+                    mapRow = (row) => ({
+                        name: row.Name,
+                        fullName: `${objectApiName}-${String(row.Name)}`
+                    });
+                    break;
+                case "Profile":
+                    soql = "SELECT Name FROM Profile ORDER BY Name";
+                    mapRow = (row) => ({ name: row.Name });
+                    break;
+                case "PermissionSet":
+                    soql = "SELECT Name, Label FROM PermissionSet WHERE IsOwnedByProfile = false ORDER BY Name";
+                    mapRow = (row) => ({ name: row.Name, label: row.Label });
+                    break;
+                case "PermissionSetGroup":
+                    soql = "SELECT DeveloperName, MasterLabel FROM PermissionSetGroup ORDER BY DeveloperName";
+                    mapRow = (row) => ({ name: row.DeveloperName, label: row.MasterLabel });
+                    break;
+                case "RecordType":
+                    soql = `SELECT DeveloperName, Name FROM RecordType WHERE SobjectType = '${objectApiName}' ORDER BY DeveloperName`;
+                    mapRow = (row) => ({ name: row.DeveloperName, label: row.Name });
+                    break;
+            }
+            const args = ["data", "query", "-q", soql, "--target-org", targetOrg, "--json"];
+            if (tooling)
+                args.splice(2, 0, "--use-tooling-api");
+            const run = await runProcess("sf", args, { env: sfCliEnv(), timeoutMs: 60_000 });
+            const scope = `${typeName}${objectApiName ? ` ${objectApiName}` : ""}${match ? ` match=${match}` : ""}`;
+            if (run.exitCode !== 0) {
+                // Still a record: the call reached the org (R9). A failed read saw nothing, so it carries
+                // no keys — and is not counted opaque, which is reserved for reads that DID return.
+                await appendReadRecord(sessionId, {
+                    tool: "list_components", orgId: org.orgId, orgAlias: targetOrg, scope,
+                    pattern: "enumeration", keys: [], rows: 0, durationMs: run.durationMs, outcome: "failed",
+                    ...(objectApiName ? { object: objectApiName } : {})
+                });
+                return fail("ORG_READ_FAILED", `sf data query exited ${run.exitCode}${run.timedOut ? " (timeout)" : ""}. Fail-closed: candidates are UNKNOWN.\n${stdoutTail(run.stderr || run.stdout, 15)}`);
+            }
+            const parsed = JSON.parse(run.stdout);
+            const truncation = sfQueryTruncation(parsed);
+            if (truncation) {
+                // Same posture as the exit-code branch above: a capped read saw SOMETHING, but
+                // delivering it as complete would let absence of data read as absence of records.
+                // Refused, so nothing reaches the supervisor — recorded like a failed read.
+                await appendReadRecord(sessionId, {
+                    tool: "list_components", orgId: org.orgId, orgAlias: targetOrg, scope,
+                    pattern: "enumeration", keys: [], rows: 0, durationMs: run.durationMs, outcome: "failed",
+                    ...(objectApiName ? { object: objectApiName } : {})
+                });
+                return fail("ORG_READ_TRUNCATED", `${truncation} Fail-closed: candidates are INCOMPLETE.`);
+            }
+            const every = (parsed.result?.records ?? []).map(mapRow);
+            // Filtered server-side for the same reason as describe_object: candidates the supervisor is
+            // not hunting for cost context whether or not it reads them.
+            const needle = match?.trim().toLowerCase();
+            const rows = needle
+                ? every.filter((row) => Object.values(row).some((v) => String(v).toLowerCase().includes(needle)))
+                : every;
+            // READ PROVENANCE (R9, R12). This tool's whole purpose is DISCOVERY, so its pattern is
+            // always ENUMERATION — it lists a family, it never reads a definition.
+            //
+            // Keyed off the DELIVERED rows, not the org's full answer. `match` filters after the query,
+            // so a filtered call caused a wide enumeration but the supervisor only ever saw the
+            // matches — and a name nobody saw cannot have influenced anything. Over-reporting here
+            // would make a narrow lookup read like a corpus sweep in the contamination report.
+            await appendReadRecord(sessionId, {
+                tool: "list_components",
+                orgId: org.orgId,
+                orgAlias: targetOrg,
+                scope,
+                pattern: "enumeration",
+                keys: rows
+                    .map((row) => typeName === "Layout"
+                    ? String(row.fullName)
+                    : typeName === "RecordType"
+                        ? `${objectApiName}.${String(row.name)}`
+                        : String(row.name))
+                    .map((fullName) => `${typeName}:${fullName}`),
+                rows: rows.length,
+                durationMs: run.durationMs,
+                outcome: "ok",
+                ...(objectApiName ? { object: objectApiName } : {})
+            });
+            if (needle && rows.length === 0) {
+                return ok(`${typeName}${objectApiName ? ` (${objectApiName})` : ""}: no candidate matching "${match}" among ${every.length}. Fail-closed — that is "none matched", not "none exist"; re-run without match to see them all.`, { typeName, objectApiName: objectApiName ?? null, match, matched: 0, total: every.length, candidates: [] });
+            }
+            const head = rows
+                .slice(0, 50)
+                .map((row) => Object.values(row).join("\t"))
+                .join("\n");
+            return ok(`${typeName}${objectApiName ? ` (${objectApiName})` : ""} in ${targetOrg}: ${needle ? `${rows.length} of ${every.length} matching "${match}"` : `${rows.length} candidate(s)`}\n${head}` +
+                (rows.length > 50 ? `\n… (${rows.length - 50} more)` : ""), { typeName, objectApiName: objectApiName ?? null, total: every.length, ...(needle ? { match } : {}), candidates: rows });
+        }
+        catch (error) {
+            if (error instanceof GateError)
+                return fail(error.code, error.message);
+            if (error instanceof SessionOrgError)
+                return fail(error.code, error.message);
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+    server.registerTool("describe_object", {
+        description: "Field inventory for one object via the Tooling API (FieldDefinition): apiName, dataType, label per field. Read-only, session-scoped. THE tool for binding work (mapping prose field references to real API names) — `sf_read sobject describe` returns ~800 KB for a standard object (it now spills the full answer to a file and hands back the path, so it is usable but costs a file read), and project_org costs a read per component. Pass `match` to get just the candidates you are hunting for instead of every field.",
+        inputSchema: {
+            sessionId: z.string().describe("The session whose org to read. Supplies the org so the alias never has to be restated."),
+            targetOrg: z
+                .string()
+                .optional()
+                .describe("Omit for the session's deploy target, which is the normal case. Pass \"campfire\" to describe/list against the session's Campfire CONSULTANT org without knowing its alias — use it before querying Campfire objects rather than guessing a field or relationship name. Any other value is a literal alias."),
+            objectApiName: z.string().describe("Object API name, e.g. Account or Invoice__c."),
+            match: z
+                .string()
+                .optional()
+                .describe("Case-insensitive substring filter on apiName or label. Binding work is a lookup, not an inventory: Account has 365 fields, and `match: \"priority\"` answers the question in two lines instead of twenty kilobytes. Omit only when you genuinely need the whole object.")
+        }
+    }, async ({ sessionId, targetOrg: targetOrgOverride, objectApiName, match }) => {
+        try {
+            // Session-derived by default; an explicit targetOrg is an intentional override for reading
+            // an org this session is not bound to. Reads skip the alias re-check (verify:false) —
+            // reading the wrong org is visible and harmless, and the round-trip is not free.
+            const org = await resolveReadOrg(sessionId, targetOrgOverride);
+            const targetOrg = org.alias;
+            assertTargetOrg(targetOrg);
+            if (!OBJECT_NAME_RE.test(objectApiName)) {
+                return fail("INVALID_OBJECT_NAME", `Object API name ${JSON.stringify(objectApiName)} fails the allowlist charset guard.`);
+            }
+            const soql = "SELECT QualifiedApiName, DataType, Label FROM FieldDefinition " +
+                `WHERE EntityDefinition.QualifiedApiName = '${objectApiName}' ORDER BY QualifiedApiName`;
+            const run = await runProcess("sf", ["data", "query", "--use-tooling-api", "-q", soql, "--target-org", targetOrg, "--json"], { env: sfCliEnv(), timeoutMs: 60_000 });
+            const scope = `${objectApiName}${match ? ` match=${match}` : ""}`;
+            if (run.exitCode !== 0) {
+                await appendReadRecord(sessionId, {
+                    tool: "describe_object", orgId: org.orgId, orgAlias: targetOrg, scope, object: objectApiName,
+                    pattern: "enumeration", keys: [], rows: 0, durationMs: run.durationMs, outcome: "failed"
+                });
+                return fail("ORG_READ_FAILED", `sf data query exited ${run.exitCode}${run.timedOut ? " (timeout)" : ""}. Fail-closed.\n${stdoutTail(run.stderr || run.stdout, 15)}`);
+            }
+            const parsed = JSON.parse(run.stdout);
+            const truncation = sfQueryTruncation(parsed);
+            if (truncation) {
+                await appendReadRecord(sessionId, {
+                    tool: "describe_object", orgId: org.orgId, orgAlias: targetOrg, scope, object: objectApiName,
+                    pattern: "enumeration", keys: [], rows: 0, durationMs: run.durationMs, outcome: "failed"
+                });
+                return fail("ORG_READ_TRUNCATED", `${truncation} Fail-closed: the field inventory is INCOMPLETE.`);
+            }
+            const records = parsed.result?.records ?? [];
+            const all = records.map((record) => ({
+                apiName: record.QualifiedApiName,
+                dataType: record.DataType,
+                label: record.Label
+            }));
+            // Filtered HERE rather than by the caller reading everything: the point is to keep the
+            // other 363 fields out of the transcript, which only works if they never arrive.
+            const needle = match?.trim().toLowerCase();
+            const fields = needle
+                ? all.filter((f) => f.apiName.toLowerCase().includes(needle) || f.label.toLowerCase().includes(needle))
+                : all;
+            // READ PROVENANCE (R9, R12) — ENUMERATION-PER-FIELD of the described object. The object is
+            // named because the call named it; each field is enumerated because the call listed them.
+            // Neither is a body read: this returns apiName/dataType/label, never a definition.
+            //
+            // Standard fields are keyed alongside custom ones — a field is a `CustomField` component
+            // regardless of suffix, and prior-arm work on a standard field has to stay joinable. Keys
+            // follow the DELIVERED rows for the same reason list_components does: `match` filters
+            // before the supervisor sees anything, and a name nobody saw influenced nothing.
+            await appendReadRecord(sessionId, {
+                tool: "describe_object",
+                orgId: org.orgId,
+                orgAlias: targetOrg,
+                scope,
+                object: objectApiName,
+                pattern: "enumeration",
+                // Zero rows means the object may not exist at all, so the object key is withheld:
+                // positive evidence only, and "we read CustomObject:X" would be a claim about something
+                // this call just failed to find.
+                keys: records.length
+                    ? [`CustomObject:${objectApiName}`, ...fields.map((f) => `CustomField:${objectApiName}.${f.apiName}`)]
+                    : [],
+                rows: fields.length,
+                durationMs: run.durationMs,
+                outcome: "ok"
+            });
+            if (records.length === 0) {
+                return ok(`object ${objectApiName}: 0 fields returned — the object may not exist in ${targetOrg} (verify with project_org, scope.components {typeName: CustomObject}).`, { object: objectApiName, exists: "unknown", fields: [] });
+            }
+            if (needle && fields.length === 0) {
+                return ok(`object ${objectApiName}: no field matching "${match}" among ${all.length} field(s). The prose name is not the API name — widen the match or read the projection.`, { object: objectApiName, match, matched: 0, totalFields: all.length, fields: [] });
+            }
+            const head = fields
+                .slice(0, 40)
+                .map((field) => `${field.apiName}\t${field.dataType}\t${field.label}`)
+                .join("\n");
+            return ok(`object ${objectApiName}: ${needle ? `${fields.length} of ${all.length} field(s) matching "${match}"` : `${fields.length} field(s)`}\napiName\tdataType\tlabel\n${head}` +
+                (fields.length > 40 ? `\n… (${fields.length - 40} more)` : "") +
+                (!needle && all.length > 60 ? `\nThis is the whole object. For a lookup, pass match to get only the candidates.` : ""), { object: objectApiName, totalFields: all.length, ...(needle ? { match } : {}), fields });
+        }
+        catch (error) {
+            if (error instanceof GateError)
+                return fail(error.code, error.message);
+            if (error instanceof SessionOrgError)
+                return fail(error.code, error.message);
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+}