in2-agent-server 0.20260821.185429

package/dist/tools/direct.js

@@ -0,0 +1,1613 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { fail, internalError, ok } from "../core/result.js";
+import { WorkspaceError, sessionDir } from "../core/workspace.js";
+import { OPERATOR_IDENTITY } from "../core/paths.js";
+import { GateError, assertDirectWriteAllowed } from "../core/gate.js";
+import { SessionOrgError, resolveSessionOrg } from "../core/sessionOrg.js";
+import { loadRequirementsIndex, loadSession } from "./session.js";
+import { projectionExistence } from "./waves.js";
+import { readPlanFile } from "../core/planFile.js";
+import { deriveRevisionChains } from "../core/revisionChain.js";
+import { OrgReaderUnavailableError, createLiveOrgReader } from "../projection/bridge.js";
+import { runLint } from "../direct/lint.js";
+import { loadPredecessorPreImages, previewPredecessorDrops, runDirectApply, validateComponents } from "../direct/applyLoop.js";
+import { RollbackError } from "../direct/rollback.js";
+import { resolveRollbackBaseline, runRollback } from "../direct/rollbackRun.js";
+import { OrgRepoError, historyDiff, historyIncompleteFacets, historyLog, historyShow } from "../direct/orgRepo.js";
+import { computeContamination, renderContamination, writeContaminationArtifacts } from "../direct/contamination.js";
+import { matchedComponentCount } from "../direct/waveCounts.js";
+import { walkSourceTree } from "../direct/sourceTree.js";
+import { assembleWave, resolveAuthored } from "../direct/waveAssembly.js";
+import { compareToDerivation, readWaveDerivation, renderDivergence } from "../direct/waveDerivation.js";
+import { ProjectionNotReadableError, readProjectionManifest } from "../direct/knownTokens.js";
+import { collectSessionProjection, describeSources, projectionView, viewKnownTokens, viewProvenValues } from "../direct/sessionProjection.js";
+import { emitDomainTelemetryEvent } from "../core/telemetryContext.js";
+import { orgCallMeterSnapshot } from "../core/orgCallMeter.js";
+import { appendReadRecord } from "../core/readsLog.js";
+/**
+ * Which attempt at this wave label this is, 1-based.
+ *
+ * The ledger dedupes waves on (batchId, waveLabel, attempt) and this was hardcoded to 1, so a
+ * RETRY of the same label collided with its own first attempt and was dropped on arrival: attempt 1
+ * `REJECTED_BY_ORG`, the fixed retry `DIFF_VERIFIED`, and the dashboard kept showing red for a wave
+ * that had succeeded — permanently, since the row is never revisited.
+ *
+ * Persisted in the bundle because the bundle directory IS the identity here: a same-label re-run
+ * reuses it (that is what makes `direct_lint {projection: "<label>"}` resolve), so the previous
+ * attempt's marker is exactly where the next run will look. Written BEFORE the apply, not after —
+ * a crashed attempt that never wrote a verdict still consumed its number, and over-counting
+ * attempts is harmless while re-using one silently discards a result.
+ *
+ * A retry under a DIFFERENT label is a different wave to everything downstream, and no numbering
+ * here can change that; it is the operator naming two things the same work.
+ */
+async function nextWaveAttempt(bundleDir) {
+    const marker = path.join(bundleDir, "attempt.json");
+    let previous = 0;
+    try {
+        const parsed = JSON.parse(await fs.readFile(marker, "utf8"));
+        if (typeof parsed.attempt === "number" && Number.isFinite(parsed.attempt))
+            previous = parsed.attempt;
+    }
+    catch {
+        // No marker, or unreadable — first attempt. Never fail an apply over bookkeeping.
+    }
+    const attempt = previous + 1;
+    try {
+        await fs.mkdir(bundleDir, { recursive: true });
+        await fs.writeFile(marker, `${JSON.stringify({ attempt }, null, 1)}\n`, "utf8");
+    }
+    catch {
+        // Same reasoning: a wave that cannot record its attempt number still deploys.
+    }
+    return attempt;
+}
+/**
+ * Preserve the PRIOR attempt's evidence before a retry overwrites it.
+ *
+ * The bundle dir is keyed by wave label alone and runDirectApply rewrites pre/ (and later post/
+ * and verdict.json) in place — so before this existed, a same-label retry replaced attempt 1's
+ * pre-image with org state attempt 1 had already changed, and a later rollback would "restore" a
+ * mid-wave state while reporting success. attempts/<n>/ is written once and never rewritten: the
+ * earliest archived attempt that captured a pre-image holds the baseline from before this wave
+ * first touched the org, which is the only state a rollback of the wave can honestly restore.
+ *
+ * First-write-wins, because attempt.json increments even for a run that never rewrote pre/ — an
+ * unsupported-metadata-type throw dies before request.json, let alone the pre-write — so a later
+ * archive call for the same number must not re-copy bytes a newer attempt has since replaced.
+ * "Written" is defined by COMPLETION, not by the directory existing: the copy lands in
+ * attempts/.tmp-<n> and is renamed into place only after every entry, plus the archive.json
+ * manifest recording which entries the prior attempt actually left, is on disk. A crash mid-copy
+ * therefore leaves only a temp dir the next call clears — never a half-archive that looks
+ * finished. The manifest is what lets resolveRollbackBaseline tell "attempt n left nothing
+ * behind, so it never reached the org" (a proven no-op — the bundle's own pre/ is still honest)
+ * apart from "attempt n's evidence is gone" (refuse). An attempt that left NOTHING still gets its
+ * directory and an all-false manifest, for the same reason: recorded absence is evidence, silent
+ * absence is indistinguishable from a legacy unarchived retry and refuses a rollback forever.
+ *
+ * Never throws: same contract as nextWaveAttempt — a wave that cannot record its bookkeeping
+ * still deploys.
+ */
+export async function archivePriorAttempt(bundleDir, priorAttempt) {
+    const attemptsRoot = path.join(bundleDir, "attempts");
+    const dest = path.join(attemptsRoot, String(priorAttempt));
+    try {
+        await fs.access(dest);
+        return;
+    }
+    catch {
+        // Not yet archived — this call owns the write.
+    }
+    try {
+        const tmp = path.join(attemptsRoot, `.tmp-${priorAttempt}`);
+        await fs.rm(tmp, { recursive: true, force: true });
+        await fs.mkdir(tmp, { recursive: true });
+        const archived = {};
+        for (const entry of ["pre", "post", "verdict.json", "request.json"]) {
+            try {
+                await fs.cp(path.join(bundleDir, entry), path.join(tmp, entry), { recursive: true });
+                archived[entry] = true;
+            }
+            catch {
+                // The prior attempt never wrote this entry; the manifest records the absence as a fact.
+                archived[entry] = false;
+            }
+        }
+        await fs.writeFile(path.join(tmp, "archive.json"), `${JSON.stringify({ archived }, null, 1)}\n`, "utf8");
+        await fs.rename(tmp, dest);
+    }
+    catch {
+        // Never throws — see the contract above. A failed archive leaves at most a temp dir, and the
+        // resolver refuses an attempt with no completed archive rather than guessing.
+    }
+}
+const DEFAULT_API_VERSION = "61.0";
+const LABEL_RE = /^[A-Za-z0-9_-]{1,40}$/;
+// How many inline components still count as a "correction" rather than a batch.
+//
+// Set from the evidence rather than taste: in the CF73 run, 21 of 22 applies passed XML inline and
+// ZERO used the wave path, even though the contract has always said to author files. Nothing was
+// disobeyed — inline is one tool call and files are N writes plus an apply, so the cheap path won
+// every time. A warning would have changed nothing; the contract already was the warning.
+//
+// Three is where a correction stops looking like a correction. Below it, inline stays frictionless
+// for the genuine one-off (fix a label, re-emit a field). At or above it, the batch has to go
+// through files, which is what makes analyzer authoring, wave assembly, per-wave lint, diffs and
+// (later) git history mean anything at all. `sourceDir` remains for trees outside the session, so
+// this closes a shortcut, not an escape route.
+//
+// SCOPED TO INLINE. `waveComponents` is a list of component KEYS, not XML — a wave of forty of them
+// is the shape this guard exists to push callers toward, so it never counts against this limit.
+const INLINE_MAX = 3;
+// Where a wave's authored metadata lives. Making this DERIVED rather than passed is the point:
+// the session already knows the workspace, so a caller that names the wave does not also have to
+// carry an absolute path between the lint call and the apply call — and cannot have the two
+// disagree. Returns undefined unless BOTH are given, so an explicit sourceDir still wins and
+// nothing changes for callers that pass one.
+function authoredWaveDir(sessionId, wave) {
+    if (!sessionId || !wave)
+        return undefined;
+    if (!LABEL_RE.test(wave))
+        return undefined;
+    return path.join(sessionDir(sessionId), "authored", wave);
+}
+/**
+ * A derived source tree that does not exist must refuse by NAME, not as a raw ENOENT. Live-caught:
+ * `direct_apply {wave: "no-such-wave"}` surfaced
+ * `INTERNAL_ERROR: ENOENT ... scandir '<path>/authored/no-such-wave'`, which reads as a server
+ * fault rather than "you named a wave you have not authored yet" — and gives the model nothing to
+ * correct toward. Listing the waves that DO exist turns a dead end into a choice, the same way the
+ * projection and wave-label refusals do.
+ */
+async function assertAuthoredWaveExists(sessionId, wave, dir) {
+    try {
+        if ((await fs.stat(dir)).isDirectory())
+            return { ok: true, dir };
+    }
+    catch {
+        /* fall through to the listing refusal */
+    }
+    let available = [];
+    try {
+        available = (await fs.readdir(path.join(sessionDir(sessionId), "authored"), { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        /* none authored yet */
+    }
+    return {
+        ok: false,
+        code: "WAVE_NOT_FOUND",
+        message: `no authored tree for wave "${wave}" (expected ${dir}).` +
+            (available.length ? ` Authored waves: ${available.join(", ")}.` : " Nothing authored in this session yet.") +
+            " Write the wave's source-format files there first."
+    };
+}
+async function isProjection(dir) {
+    try {
+        await fs.access(path.join(dir, "projection.json"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The session's target-org alias, or undefined when it cannot be determined.
+ *
+ * Best-effort BY DESIGN: this only scopes which projections the referential tier may union, and an
+ * unbound or unreadable session should downgrade that union rather than fail a lint that has
+ * nothing to do with the org. `verify: false` for the same reason — the caller is naming a
+ * directory on disk, not touching the org.
+ */
+async function sessionTargetOrg(sessionId) {
+    try {
+        const session = await loadSession(sessionId);
+        return (await resolveSessionOrg(session, "target", { verify: false })).alias;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every projection label available in this session, for a useful refusal rather than a dead end. */
+async function availableProjections(sessionId, targetOrg) {
+    const out = [];
+    const orgRoot = path.join(sessionDir(sessionId), "org-projection", targetOrg);
+    try {
+        for (const e of await fs.readdir(orgRoot, { withFileTypes: true })) {
+            if (e.isDirectory() && (await isProjection(path.join(orgRoot, e.name))))
+                out.push(e.name);
+        }
+    }
+    catch {
+        /* none yet */
+    }
+    const directRoot = path.join(sessionDir(sessionId), "direct");
+    try {
+        for (const e of await fs.readdir(directRoot, { withFileTypes: true })) {
+            if (e.isDirectory() && (await isProjection(path.join(directRoot, e.name, "post"))))
+                out.push(e.name);
+        }
+    }
+    catch {
+        /* none yet */
+    }
+    return [...new Set(out)].sort();
+}
+/**
+ * The facets a history entry's record does NOT contain, rendered for an operator.
+ *
+ * Printed rather than left to the trailer text, because the failure this guards against is a reader
+ * drawing a conclusion from an ABSENCE. `readLayoutSnapshot` deletes the facet it could not verify,
+ * so `relatedLists` missing from a stored layout looks exactly like a layout with none — and a
+ * supervisor who reads it that way authors a replace that deletes them. "NOT READ at capture" is
+ * the sentence that stops it.
+ */
+function renderIncompleteFacets(records) {
+    if (records.length === 0)
+        return "";
+    const lines = records.map((r) => `  ${r.component} — ${r.facets.map((f) => `${f}: NOT READ at capture`).join("; ")}`);
+    return (`\n\nINCOMPLETE RECORD — this entry's post-image is missing ${records.length === 1 ? "a facet" : "facets"} the read ` +
+        `could not reach. NOT a claim that the facet is empty; it was never read, and nothing below shows it:\n${lines.join("\n")}`);
+}
+/**
+ * Resolve a projection LABEL to a directory, session-relative.
+ *
+ * A label, not a path, for the same reason `waves` is: the session already knows where projections
+ * live, so making the caller carry an absolute path between project_org and direct_lint is state
+ * living in the model's context that can go stale or disagree with itself.
+ *
+ * TWO sources, because both are real projections and the second is the common one: `project_org`
+ * writes org-projection/<org>/<label>/, and every `direct_apply` writes <bundle>/post/ — which is
+ * the org as of the moment that wave landed, and exactly what the NEXT wave should lint against.
+ * Resolving only the first would leave the model hand-building the post/ path, i.e. would not
+ * actually remove the path from the calling convention.
+ *
+ * Omitting the label does NOT pick one automatically — picking one is the failure mode. A session
+ * accumulates narrow probes and pre-deploy baselines alongside broad grounding projections, so
+ * "newest wins" lands on the wrong one routinely (MEASURED on CF72: wave2 against the pre-deploy
+ * baseline produced 2 REF_UNKNOWN findings naming 5 fields that exist and are spelled correctly;
+ * against wave1's post-image the same wave is clean). With no label the tools ground against ALL of
+ * them at once, freshest observation per component — see `collectSessionProjection`. A label is
+ * therefore an override: it narrows grounding to one org state on purpose.
+ */
+export async function resolveProjection(sessionId, projection) {
+    if (!sessionId) {
+        return { ok: false, code: "SESSION_REQUIRED", message: "`projection` is a label resolved inside a session — pass sessionId too, or use projectionDir for a path outside it." };
+    }
+    if (!LABEL_RE.test(projection)) {
+        return { ok: false, code: "INVALID_LABEL", message: `projection label must match ${LABEL_RE}.` };
+    }
+    const session = await loadSession(sessionId);
+    const { alias: targetOrg } = await resolveSessionOrg(session, "target", { verify: false });
+    const fromProjectOrg = path.join(sessionDir(sessionId), "org-projection", targetOrg, projection);
+    const fromApply = path.join(sessionDir(sessionId), "direct", projection, "post");
+    const hits = [
+        ...((await isProjection(fromProjectOrg)) ? [fromProjectOrg] : []),
+        ...((await isProjection(fromApply)) ? [fromApply] : [])
+    ];
+    if (hits.length === 1)
+        return { ok: true, dir: hits[0] };
+    if (hits.length > 1) {
+        // project_org labels and direct_apply labels are separate namespaces, so a collision is
+        // possible. Refuse rather than pick: the two mean different org states.
+        return {
+            ok: false,
+            code: "AMBIGUOUS_PROJECTION",
+            message: `"${projection}" matches both a project_org projection and a deploy bundle's post-image:\n  ${hits.join("\n  ")}\nPass projectionDir with the one you mean.`
+        };
+    }
+    const available = await availableProjections(sessionId, targetOrg);
+    return {
+        ok: false,
+        code: "PROJECTION_NOT_FOUND",
+        message: `no projection labelled "${projection}" in this session.` +
+            (available.length ? ` Available: ${available.join(", ")}.` : " None captured yet — run project_org first.") +
+            " Labels come from project_org's `label`, or a direct_apply bundle label (its post-image)."
+    };
+}
+const EDIT_SCHEMA = z.object({
+    typeName: z.string().describe("Metadata type, e.g. CustomField, Flow, ListView. Any single-file XML or content-file type Salesforce's registry knows; directory bundles (LWC/Aura) refuse."),
+    fullName: z.string().describe("Component fullName, e.g. CF63_Intake_Request__c.My_Field__c (folder types: 'Folder/Name')."),
+    xml: z.string().describe("The component's (meta) XML (root element = typeName; xmlns/header auto-added)."),
+    content: z.string().optional().describe("REQUIRED for content-file types (EmailTemplate → the .email body, StaticResource → the .resource content, Document): the accompanying content-file body."),
+    contentEncoding: z.enum(["utf8", "base64"]).optional().describe("Encoding of `content`; base64 for binary static resources (default utf8).")
+});
+const WAVE_COMPONENT_SCHEMA = z.object({
+    typeName: z.string().describe("Metadata type, e.g. CustomField, Flow, Layout."),
+    fullName: z.string().describe("Component fullName, exactly as plan.json records it."),
+    path: z
+        .string()
+        .optional()
+        .describe("WHICH authored file, for a component this batch changes more than once. Matched against the plan entries' `authoredFile`. plan_waves emits it on multi-revision keys and leaves it off single-revision ones, so an ordinary wave list is bare {typeName, fullName}.")
+});
+/**
+ * The wave path: rebuild `<session>/authored/<wave>` from the files the analyzers authored, and hand
+ * back the tree to walk.
+ *
+ * This is the step the supervisor used to take as a separate `assemble_wave` call, and moving it
+ * inside is what closes the window between the two: whatever this writes is what the very next line
+ * lints and deploys, in the same call, so there is no longer a moment where the assembled tree and
+ * the deployed tree can be different things.
+ *
+ * The tree is a BUILD ARTIFACT — every call rebuilds it — so a fix that must survive belongs in the
+ * revision's own authored file under `requirements/<extId>/authored/`, which is the thing plan.json
+ * binds and the thing this copies from. `WAVE_EXISTS` is gone with the same reasoning: there is
+ * nothing authored in there to protect.
+ *
+ * Assembly refusals come back as data and are re-emitted by the caller through `fail()` with their
+ * own codes, so `OWNERSHIP_CONFLICT`, `COMPONENT_STILL_PROVISIONAL`, `COMPONENT_NOT_OWNED` and
+ * `NOTHING_TO_ASSEMBLE` read exactly as they did from the tool that used to own them.
+ */
+async function assembleRequestedWave(sessionId, wave, waveComponents, sourceDir, ackIncomplete) {
+    if (sourceDir) {
+        return {
+            ok: false,
+            code: "AMBIGUOUS_INPUT",
+            message: "`waveComponents` assembles the analyzers' authored files into <session>/authored/<wave>; `sourceDir` names a tree that already exists outside the session. Pass one or the other."
+        };
+    }
+    if (!sessionId || !wave) {
+        return {
+            ok: false,
+            code: "WAVE_REQUIRED",
+            message: "`waveComponents` is the component list for a named wave — pass `sessionId` and `wave` with it."
+        };
+    }
+    const result = await assembleWave({ sessionId, wave, components: waveComponents, ...(ackIncomplete ? { ackIncomplete: true } : {}) });
+    if (!result.ok)
+        return { ok: false, code: result.code, message: result.message };
+    return { ok: true, dir: result.dir, report: result.report };
+}
+const normRel = (value) => value.split(/[\\/]/).filter(Boolean).join("/");
+/**
+ * WHAT THIS WAVE IS DOING TO EACH OF ITS COMPONENTS, and which file holds the state it supersedes.
+ *
+ * Assembly answers "which file goes where"; this answers "and what does that file MEAN" — the two
+ * facts that live in plan.json and cannot survive `walkSourceTree`, which is lossy by design
+ * (`RevisionBinding` says why it stays that way). It reads the same plan entries the assembler
+ * resolved ownership from, and derives the same chains `plan_waves` ordered the waves by, so all
+ * three agree about a component with more than one state in this batch.
+ *
+ * FAIL-OPEN, ENTIRELY. Everything downstream of this is additive — intent recorded in the evidence
+ * bundle, a message branch on a check that already fires, and a warning-only preview. A batch whose
+ * plans cannot be read is a batch `plan_waves` and the assembler have already refused for better
+ * reasons and in more useful words; nothing here should be the thing that stops a delivery, so an
+ * unreadable plan, an unresolvable chain or a key this wave asks for that no chain covers each cost
+ * their own binding and nothing else.
+ *
+ * A key whose wave entry carries no `path` while the batch holds two states of it resolves to
+ * NOTHING rather than to a guess — assembly refuses that same request as `COMPONENT_AUTHORED_TWICE`,
+ * and inventing an answer here would only decide which of two files the guard below compares.
+ */
+async function resolveWaveRevisions(sessionId, waveComponents) {
+    try {
+        const root = sessionDir(sessionId);
+        const entries = [];
+        const unreadable = [];
+        for (const requirement of await loadRequirementsIndex(sessionId)) {
+            const parsed = await readPlanFile(path.join(root, "requirements", requirement.extId, "plan.json"), requirement.extId);
+            if (!parsed.ok) {
+                // A plan that has not been written is an ordinary state mid-run; one that cannot be READ is
+                // not, and the difference is the only thing worth a note here.
+                if (parsed.error.code !== "PLAN_NOT_FOUND")
+                    unreadable.push(`${requirement.extId} (${parsed.error.code})`);
+                continue;
+            }
+            entries.push(...parsed.plan.entries);
+        }
+        const note = unreadable.length > 0
+            ? `intent could not be read from ${unreadable.length} plan.json (${unreadable.join(", ")}) — the deploy is unaffected, but this wave's evidence bundle records no intent for those components`
+            : undefined;
+        if (entries.length === 0)
+            return { revisions: [], ...(note ? { note } : {}) };
+        // The SAME three-valued predicate plan_waves grounds its cross-check on, from local disk only —
+        // this session's own project_org runs plus every completed wave's post-image. Two derivations of
+        // "does this component exist?" is two answers to a question the batch has to be consistent about.
+        //
+        // Collected HERE rather than handed in by the caller, even though direct_lint has just built one
+        // of its own: a caller may pass `projection` to narrow grounding to a single org state on
+        // purpose, and intent inference must not inherit that narrowing — an entry whose intent depends
+        // on which projection the reader happened to name is an entry with two answers.
+        const view = await collectSessionProjection(root, await sessionTargetOrg(sessionId));
+        const chains = new Map(deriveRevisionChains(entries, projectionExistence(view)).chains.map((chain) => [chain.key, chain]));
+        const revisions = [];
+        for (const want of waveComponents) {
+            const chain = chains.get(`${want.typeName}:${want.fullName}`);
+            if (!chain)
+                continue;
+            // A DELETION IS NOT A STATE TO DEPLOY, so it is never one of these bindings. It carries no
+            // authored file, which already excludes it from the `path` branch; the single-revision branch
+            // has to exclude it explicitly, or a delete-only chain — one revision, no file — would hand
+            // this loop an `intent: "delete"` for a component the wave is about to WRITE. Deletions leave
+            // through `deletes`, which is a separate argument and a separate decision.
+            const states = chain.revisions.filter((r) => r.intent !== "delete");
+            const link = want.path
+                ? states.find((r) => r.entry.authoredFile && normRel(r.entry.authoredFile) === normRel(want.path))
+                : states.length === 1
+                    ? states[0]
+                    : undefined;
+            if (!link || link.intent === "delete")
+                continue;
+            const previous = link.predecessor;
+            // `resolveAuthored` is the one place an analyzer-written relative path crosses into a real one,
+            // and it stays the one place: an `authoredFile` of "../../../../.ssh/authorized_keys" resolves
+            // to null here rather than to a file this then opens and reads into a lint finding.
+            const previousFile = previous?.authoredFile
+                ? resolveAuthored(path.join(root, "requirements", previous.extId), previous.authoredFile)
+                : null;
+            revisions.push({
+                typeName: want.typeName,
+                fullName: want.fullName,
+                intent: link.intent,
+                intentSource: link.intentSource,
+                ...(previous?.authoredFile && previousFile
+                    ? { predecessorFile: previousFile, predecessor: `${previous.extId}/${normRel(previous.authoredFile)}` }
+                    : {})
+            });
+        }
+        return { revisions, ...(note ? { note } : {}) };
+    }
+    catch (error) {
+        return {
+            revisions: [],
+            note: `intent could not be derived for this wave (${error instanceof Error ? error.message : String(error)}) — the deploy is unaffected; the evidence bundle records no intent`
+        };
+    }
+}
+/** Every wave bundle recorded in this session, so a mistyped wave gets a choice, not a dead end. */
+async function availableWaveBundles(sessionId) {
+    try {
+        const entries = await fs.readdir(path.join(sessionDir(sessionId), "direct"), { withFileTypes: true });
+        const out = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            try {
+                await fs.access(path.join(sessionDir(sessionId), "direct", entry.name, "verdict.json"));
+                out.push(entry.name);
+            }
+            catch {
+                /* a directory that never reached a verdict is not a wave anyone can roll back */
+            }
+        }
+        return out.sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The label the ROLLBACK's own bundle takes — never the target wave's.
+ *
+ * A rollback is a wave and earns a bundle (R21), and `direct_apply`'s bundle directory IS its
+ * identity: reusing the target's label would make the rollback attempt 2 of the wave it is undoing
+ * and overwrite that bundle's `pre/`, `post/` and `request.json` — including the `pre/source/` tree
+ * the rollback is reading its bytes out of. Prefixed rather than suffixed so the bundles sort
+ * together.
+ *
+ * NEVER TRUNCATED, WHICH IS WHY THIS CAN REFUSE. `revert-` is 7 characters and a wave label may
+ * itself be the full 40, so the old `.slice(0, 40)` mapped every pair of waves sharing their first
+ * 33 characters onto ONE rollback bundle directory. That is not cosmetic: the bundle directory is
+ * the identity `nextWaveAttempt` counts against, so the second wave's rollback files itself as
+ * ATTEMPT 2 of the first wave's rollback — and the mirror then carries one rollback's evidence,
+ * verdict and diff under another rollback's address, permanently, since those rows are never
+ * revisited. No truncation is safe and no derived suffix is one an operator could predict, so a
+ * derived label that will not fit is refused by name and the operator passes their own `label`.
+ * Returns null for "cannot derive one"; an explicit label is already length-checked by LABEL_RE.
+ */
+function rollbackLabel(wave, label) {
+    if (label)
+        return label;
+    const derived = `revert-${wave}`;
+    return derived.length <= 40 ? derived : null;
+}
+/**
+ * The component keys ONE requirement's plan.json owns, as a set of `typeName:fullName`.
+ *
+ * THE SCOPE OF `validate_components`, and the reason that tool is safe to hand fifteen analyzers at
+ * once. An analyzer is dispatched with one requirement and authors under one requirement's tree, so
+ * "my components" is a fact already written down — it does not need to be asserted in the call, and
+ * a call that could name any component would let one analyzer spend the org's validation queue on
+ * another analyzer's work, or discover a refusal it cannot fix and has no context for.
+ *
+ * DELETES ARE EXCLUDED. A deletion owns no authored file, so it can never be a member of a source
+ * checkOnly; validating one means submitting a destructive package, which is `direct_apply
+ * {dryRunOnly, deletes}` and is the supervisor's call to make deliberately.
+ *
+ * ROUTES ARE EXCLUDED for the same reason assembly excludes them: `deployable: false` means the work
+ * leaves by another path and there is no file to submit.
+ */
+async function ownedComponentKeys(sessionId, extId) {
+    const parsed = await readPlanFile(path.join(sessionDir(sessionId), "requirements", extId, "plan.json"), extId);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            code: parsed.error.code,
+            message: parsed.error.code === "PLAN_NOT_FOUND"
+                ? `No plan.json for ${extId} yet. validate_components checks the components THAT PLAN owns, so write the plan (or at least its components[]) first — the components you have authored can carry draftNotes and be validated on the next call.`
+                : `${extId}'s plan.json could not be read (${parsed.error.code}): ${parsed.error.message}`
+        };
+    }
+    const keys = new Set(parsed.plan.entries.filter((e) => e.deployable && e.intent !== "delete").map((e) => e.key));
+    if (keys.size === 0) {
+        return {
+            ok: false,
+            code: "NOTHING_TO_VALIDATE",
+            message: `${extId}'s plan.json owns no deployable component. Routes (\`deployable: false\`) and deletions have no ` +
+                `authored file to submit, so there is nothing a checkOnly could be run over. A deletion is validated by the ` +
+                `supervisor with direct_apply {dryRunOnly, deletes} — a destructive package, not a source deploy.`
+        };
+    }
+    return { ok: true, keys };
+}
+/**
+ * Every token the batch's plans OWN — fullNames plus bare field names, the shapes the referential
+ * tier matches. What splits `REF_PENDING_DEPENDENCY` (the plan explains this unknown) from
+ * `REF_UNKNOWN` (nothing does). Delete entries are excluded: a reference to a component this batch
+ * REMOVES is exactly as broken as a reference to one that never existed.
+ *
+ * FAIL-OPEN to null: with no readable plans the lint simply classifies as it always has. An
+ * unreadable plan is refused by plan_waves and assembly in better words; the referential SPLIT must
+ * never be what stops a lint.
+ */
+async function batchPlannedTokens(sessionId) {
+    try {
+        const root = sessionDir(sessionId);
+        const tokens = new Set();
+        for (const requirement of await loadRequirementsIndex(sessionId)) {
+            const parsed = await readPlanFile(path.join(root, "requirements", requirement.extId, "plan.json"), requirement.extId);
+            if (!parsed.ok)
+                continue;
+            for (const entry of parsed.plan.entries) {
+                if (entry.intent === "delete")
+                    continue;
+                tokens.add(entry.fullName);
+                if (entry.typeName === "CustomField") {
+                    const field = entry.fullName.split(".")[1];
+                    if (field)
+                        tokens.add(field);
+                }
+            }
+        }
+        return tokens.size > 0 ? tokens : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Inline XML and a wave component list are two different answers to "what is in this wave". */
+const inlineVsWave = () => fail("AMBIGUOUS_INPUT", "Provide either `waveComponents` (the wave's component list — the files the analyzers authored are assembled for you) or inline `components` XML, not both.");
+export function registerDirectTools(server) {
+    server.registerTool("direct_lint", {
+        description: "Millisecond LOCAL lint of metadata XML edits. Four tiers: SCHEMA (official Metadata API definitions — invalid enums, missing required elements, caught locally instead of a ~45s checkOnly round-trip) + LEMMA rules compiled from the live-caught quirk corpus + REFERENTIAL (every custom API token an edit references must exist in the org, be introduced by this batch's edits, or be PLANNED by the batch — a planned-but-unlanded reference is `REF_PENDING_DEPENDENCY`, an ordering fact; only the residual is `REF_UNKNOWN`, and direct_apply then verifies those against the org DIRECTLY: proven-present is suppressed, proven-absent BLOCKS the real deploy, ackable) + ORG-PRECEDENT (`UNPROVEN_ORG_TOKEN` — elements the API types as a free string but the ORG validates against its own contents; the finding names the values an existing component of that type proves acceptable. Warning, never error). " +
+            "GROUNDING IS AUTOMATIC: pass `sessionId` and both org-aware tiers run against everything this session knows about the target org, freshest observation per component; the result prints which tiers ran and against what. No org contact, no gate. Errors are ackable by rule name via `ackLints` on direct_apply (except malformed XML); the authoritative server-side tier (checkOnly) still runs inside direct_apply. " +
+            "NORMAL USE IS {sessionId, wave, waveComponents}: the analyzers' authored files are ASSEMBLED into <session>/authored/<wave> first, so there is no separate collection step. " +
+            "THIS CALL IS OPTIONAL — direct_apply assembles and lints identically, in the same call as the deploy. Use it to read a wave's findings before spending a checkOnly. " +
+            "When the batch changes one component MORE THAN ONCE, `PREVIEW_REPLACE_DROPS_EARLIER` names what the later file omits that the earlier one establishes. Warning only, never blocking, not ackable — it compares two authored files rather than the org, so the org-grounded check (`PREFLIGHT_REPLACE_DROPS_*`) still runs inside direct_apply. " +
+            "`sourceDir` takes a tree outside the session and inline `components` is for one-offs.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .optional()
+                .describe("The session this wave belongs to. With `wave`, the authored tree is derived — no path to carry."),
+            wave: z
+                .string()
+                .optional()
+                .describe("Wave label. With `sessionId` this resolves to <session>/authored/<wave>, which is where direct_apply also looks — author each wave there and neither call needs a path."),
+            waveComponents: z
+                .array(WAVE_COMPONENT_SCHEMA)
+                .nonempty()
+                .optional()
+                .describe("The components this wave contains, straight from plan_waves' output for that wave. Given these, the wave tree is ASSEMBLED from the files the analyzers authored before linting — so a wave nobody has assembled yet still lints. Omit to lint whatever is already at <session>/authored/<wave>."),
+            ackIncompleteWave: z.boolean().optional().describe("Acknowledge linting an INCOMPLETE wave: some requested components have no authored file, and only the assembled subset will lint — direct_lint deploys nothing regardless; the same flag on direct_apply is what consents to deploying it. Only pass this after the operator has agreed to partial delivery — an approved wave is a scope, and delivering part of it is a change to that scope."),
+            components: z.array(EDIT_SCHEMA).optional().describe("Inline metadata edits. Omit when using sessionId+wave or sourceDir."),
+            sourceDir: z.string().optional().describe("ESCAPE HATCH: an explicit absolute path to a source-format metadata tree (objects/…, flows/…, quickActions/…; a force-app/main/default wrapper is tolerated). Prefer sessionId+wave."),
+            projection: z
+                .string()
+                .optional()
+                .describe("OVERRIDE — ground the org-aware tiers against ONE projection instead of everything this session knows. A LABEL resolved inside the session (a `project_org` label, or a direct_apply bundle label meaning that wave's post-image); unknown labels refuse and list what is available. It NARROWS ground truth — leave it off for ordinary linting."),
+            projectionDir: z
+                .string()
+                .optional()
+                .describe("ESCAPE HATCH: absolute path to a projection outside this session. Narrows grounding exactly as `projection` does.")
+        }
+    }, async ({ sessionId, wave, waveComponents, ackIncompleteWave, components, sourceDir, projection, projectionDir }) => {
+        try {
+            let edits = (components ?? []);
+            let skippedNote = "";
+            let assemblyNote = "";
+            if (waveComponents?.length && components?.length)
+                return inlineVsWave();
+            // The wave tree is BUILT here when the caller names the wave's components, so lint reads a
+            // tree it just produced rather than one it hopes is current.
+            let walkDir = sourceDir ?? authoredWaveDir(sessionId, wave);
+            if (walkDir && components?.length) {
+                return fail("AMBIGUOUS_INPUT", "Provide either a source tree (sessionId+wave or sourceDir) or inline components, not both.");
+            }
+            if (waveComponents?.length) {
+                const assembled = await assembleRequestedWave(sessionId, wave, waveComponents, sourceDir, ackIncompleteWave);
+                if (!assembled.ok)
+                    return fail(assembled.code, assembled.message);
+                walkDir = assembled.dir;
+                assemblyNote = `\n${assembled.report}`;
+            }
+            else if (walkDir && !sourceDir && sessionId && wave) {
+                const w = await assertAuthoredWaveExists(sessionId, wave, walkDir);
+                if (!w.ok)
+                    return fail(w.code, w.message);
+            }
+            if (walkDir) {
+                const walked = await walkSourceTree(walkDir);
+                edits = walked.components;
+                if (walked.skipped.length)
+                    skippedNote = `\nskipped ${walked.skipped.length} file(s): ${walked.skipped.map((s) => `${s.file} (${s.reason})`).join("; ")}`;
+            }
+            if (edits.length === 0) {
+                return fail("NO_WORK", walkDir
+                    ? `No recognized metadata files under ${walkDir}.`
+                    : "Provide sessionId+wave (the authored tree is derived), an explicit sourceDir, or inline components.");
+            }
+            // GROUNDING. The DEFAULT is everything this session knows about the target org, freshest
+            // observation per component — not a decision the caller makes and can get wrong. A
+            // `projection`/`projectionDir` is an OVERRIDE that narrows to ONE org state on purpose
+            // (a compareTo-style check); it is reported as narrowed so a downgraded result is never
+            // mistaken for the whole truth.
+            let resolvedProjectionDir = projectionDir;
+            if (projection && !projectionDir) {
+                const r = await resolveProjection(sessionId, projection);
+                if (!r.ok)
+                    return fail(r.code, r.message);
+                resolvedProjectionDir = r.dir;
+            }
+            let known = null;
+            let proven = null;
+            let tiers = "tiers: schema+lemma (referential + org-precedent SKIPPED — no session and no projection to ground against)";
+            if (resolvedProjectionDir) {
+                let view;
+                try {
+                    view = projectionView([{ dir: resolvedProjectionDir, manifest: await readProjectionManifest(resolvedProjectionDir) }]);
+                }
+                catch (error) {
+                    if (error instanceof ProjectionNotReadableError)
+                        return fail("PROJECTION_NOT_READABLE", error.message);
+                    throw error;
+                }
+                known = viewKnownTokens(view);
+                proven = await viewProvenValues(view);
+                tiers =
+                    `tiers: schema+lemma + referential + org-precedent (${known.size} known tokens from ${resolvedProjectionDir} ONLY — ` +
+                        "an explicit projection narrows grounding on purpose; omit it to ground against every projection this session holds)";
+            }
+            else if (sessionId) {
+                const view = await collectSessionProjection(sessionDir(sessionId), await sessionTargetOrg(sessionId));
+                if (view.sources.length === 0) {
+                    tiers =
+                        "tiers: schema+lemma (referential + org-precedent SKIPPED — this session holds no projection of its target org yet; run project_org)";
+                }
+                else {
+                    known = viewKnownTokens(view);
+                    proven = await viewProvenValues(view);
+                    tiers = `tiers: schema+lemma + referential + org-precedent (${known.size} known tokens from ${view.sources.length} session projection(s): ${describeSources(view)})`;
+                }
+            }
+            const result = runLint(edits, known, [], proven, sessionId ? await batchPlannedTokens(sessionId) : null);
+            // THE STATIC DROP PREVIEW (origin R5). When this batch changes a component more than once,
+            // the earlier state is sitting on disk as an authored file — so the omission a later file
+            // makes can be named HERE, before the ~45s checkOnly that would otherwise be the first thing
+            // to notice it. Warning-only and it never touches `blocked`: see `previewPredecessorDrops`.
+            if (waveComponents?.length && sessionId) {
+                const { revisions, note } = await resolveWaveRevisions(sessionId, waveComponents);
+                result.findings.push(...previewPredecessorDrops(edits, await loadPredecessorPreImages(revisions)));
+                if (note)
+                    assemblyNote = `${assemblyNote}\n${note}`;
+            }
+            const summary = result.findings.length
+                ? result.findings.map((f) => `${f.severity.toUpperCase()} ${f.rule} [${f.component}]: ${f.message}`).join("\n")
+                : "clean — no findings";
+            return ok(`${result.blocked ? "BLOCKED" : "ok"} — ${result.findings.length} finding(s) over ${edits.length} component(s)\n${tiers}\n${summary}${skippedNote}${assemblyNote}`, {
+                findings: result.findings,
+                blocked: result.blocked,
+                componentsLinted: edits.length,
+                referentialTier: Boolean(known),
+                grounding: resolvedProjectionDir ? "projection" : known ? "session" : "none"
+            });
+        }
+        catch (error) {
+            return internalError(error);
+        }
+    });
+    server.registerTool("validate_components", {
+        title: "Ask the org whether it would accept the components you authored",
+        description: "SUBMIT YOUR OWN AUTHORED COMPONENTS TO SALESFORCE AS A checkOnly DEPLOY AND REPORT WHAT IT SAID. Mutates NOTHING — a checkOnly writes nothing and needs no write gate. " +
+            "FOR ANALYZERS, after you author and after direct_lint: `validate_components {sessionId, extId}`. It reads the components YOUR plan.json owns, assembles the files you bound to them, and asks the org. " +
+            "WHY THIS IS NOT direct_lint: the lint ladder is local and catches what a schema or a live-caught lemma can express. This is the ORG's own answer — the tier that returns `length must be specified`, `Cannot delete last filter`, `Invalid field name`. Historically that answer arrived at deploy time, serially, one wave at a time, where a refusal takes every other component in its wave down with it. Here it arrives while you still hold the context that produced the file. " +
+            "RECORD EVERY REFUSAL AS A BLOCKER WITH THE ORG'S MESSAGE VERBATIM. Salesforce's sentence is the evidence; your paraphrase of it is not. A refusal you can fix yourself (a missing required attribute, a typo'd reference) is a fix, not a blocker — the same rule direct_lint findings follow. " +
+            "SCOPED TO YOUR PLAN: only the components your requirement's plan.json owns and that are deployable. Routes and deletions are excluded — a deletion has no authored file, and validating one means a destructive package, which is the supervisor's deliberate call. " +
+            "CONCURRENCY, MEASURED (26 concurrent validation deploys on a live org, 2026-08-05): the org QUEUES these — it does not run them in parallel. Expect roughly one completion every 4-5 seconds across all callers, so with 8 analyzers validating at once a single call can take 30s while serially it would take 5s. That is the queue, not a hang; do not retry it. Wall-clock across the batch still improves ~1.4-1.6x, and that is not the main win — moving refusal discovery out of the serial deploy phase is. NO LOCK CONTENTION: six simultaneous validations of the SAME component on the SAME object all returned clean, so overlapping component sets are not a hazard here (a real deploy is a different question). Each caller gets its own deploy id and its own failures — attribution is never mixed. " +
+            "NOT A DEPLOY AND NOT A VERDICT: no evidence bundle, no pre/post projection, no diff, no org history entry. A clean result means the org would ACCEPT this metadata, never that it behaves correctly. " +
+            "A TIMEOUT IS NOT A PASS AND NOT A REFUSAL — the org never answered; it is reported as its own state.",
+        inputSchema: {
+            sessionId: z.string().describe("Your session, from your Task prompt. The target org is derived from it, exactly as for every other org-touching tool."),
+            extId: z
+                .string()
+                .describe("YOUR requirement id, e.g. \"REQ-15462\". The components validated are the ones this requirement's plan.json owns — you validate your own work, not the batch's."),
+            components: z
+                .array(WAVE_COMPONENT_SCHEMA)
+                .nonempty()
+                .optional()
+                .describe("Narrow to some of your own components (each must be one your plan.json owns; anything else is refused by name). Omit to validate everything deployable in your plan."),
+            apiVersion: z.string().optional()
+        }
+    }, async ({ sessionId, extId, components, apiVersion }) => {
+        const startedAt = new Date().toISOString();
+        try {
+            const owned = await ownedComponentKeys(sessionId, extId);
+            if (!owned.ok)
+                return fail(owned.code, owned.message);
+            // AN ANALYZER MAY ONLY NAME ITS OWN. Refused by name rather than filtered silently: a
+            // narrowing that quietly dropped the component the caller cared most about would report a
+            // clean validation of something else entirely.
+            const foreign = (components ?? []).filter((c) => !owned.keys.has(`${c.typeName}:${c.fullName}`));
+            if (foreign.length > 0) {
+                return fail("COMPONENT_NOT_OWNED", [
+                    `${foreign.length} component(s) are not owned by ${extId}'s plan.json, so they are not yours to validate:`,
+                    ...foreign.map((c) => `  ${c.typeName}:${c.fullName}`),
+                    "",
+                    `${extId} owns: ${[...owned.keys].sort().join(", ")}`,
+                    "",
+                    "If one of these IS yours, add it to your plan.json components[] with its authoredFile. If it belongs",
+                    "to another requirement, that analyzer validates it — a dependsOn is something that must already exist,",
+                    "not something you check."
+                ].join("\n"));
+            }
+            // Assembled through the SAME assembler direct_apply uses, into a scratch wave label of this
+            // requirement's own. That is what makes a clean answer here mean something later: the bytes
+            // submitted are the bytes the wave will submit, resolved by the same ownership rules, with
+            // the same provisional/orphan refusals firing at the same moment.
+            const wanted = (components ?? [...owned.keys].map((key) => {
+                const at = key.indexOf(":");
+                return { typeName: key.slice(0, at), fullName: key.slice(at + 1) };
+            }));
+            const waveLabel = `validate-${extId}`.slice(0, 40).replace(/[^A-Za-z0-9_-]/g, "-");
+            // ackIncomplete: this is not a delivery and there is no approved scope to under-deliver
+            // against. An analyzer mid-authoring legitimately has some components written and some not,
+            // and refusing to check the written ones until all of them exist would make the tool useless
+            // exactly when it is most useful. What was NOT assembled is named in the report below.
+            const assembled = await assembleRequestedWave(sessionId, waveLabel, wanted, undefined, true);
+            if (!assembled.ok)
+                return fail(assembled.code, assembled.message);
+            const walked = await walkSourceTree(assembled.dir);
+            if (walked.components.length === 0) {
+                return fail("NO_WORK", `None of ${extId}'s ${wanted.length} owned component(s) have an authored file yet, so there is nothing to submit. Author them under requirements/${extId}/authored/ and record each as its entry's authoredFile.`);
+            }
+            const session = await loadSession(sessionId);
+            const binding = await resolveSessionOrg(session, "target");
+            // NO assertDirectWriteAllowed. Deliberate, and the one line of this handler most worth
+            // reading twice: a checkOnly mutates nothing, so there is no write to authorize. The gate
+            // exists to guard the org's STATE, and this call cannot change it (measured — see
+            // .audit/parallel-validation.md). Gating it anyway would deny the analyzers the check on
+            // every install whose write authority arrives later, which is every install before approval.
+            const version = apiVersion?.trim() || DEFAULT_API_VERSION;
+            const result = await validateComponents({
+                edits: walked.components,
+                targetOrg: binding.alias,
+                apiVersion: version
+            });
+            // SHAPE ONLY, no component names and no org messages. A telemetry event travels off this
+            // machine; a refusal's text quotes the org about a client's metadata, and a component key
+            // names their schema. What the ledger needs to answer — is this check being used, does it
+            // catch anything, and is the queue as slow as the description claims — is answerable from
+            // counts and durations alone.
+            emitDomainTelemetryEvent("analysis.components_validated", {
+                extId,
+                componentCount: result.componentCount,
+                accepted: result.accepted,
+                failureCount: result.failures.length,
+                timedOut: result.timedOut,
+                durationMs: result.durationMs,
+                startedAt,
+                completedAt: new Date().toISOString()
+            }, {
+                stage: "analysis",
+                outcome: result.timedOut ? "unanswered" : result.accepted ? "confirmed" : "refused"
+            });
+            // READ PROVENANCE (R9). A checkOnly is a real round-trip to the org about real components,
+            // and a read-set that omitted it would understate what this session put to the org.
+            await appendReadRecord(sessionId, {
+                tool: "validate_components",
+                orgId: binding.orgId ?? null,
+                orgAlias: binding.alias,
+                scope: `validate ${extId}`,
+                pattern: "body",
+                keys: walked.components.map((c) => `${c.typeName}:${c.fullName}`),
+                manifests: [],
+                rows: walked.components.length,
+                durationMs: result.durationMs,
+                // A REFUSAL IS A SUCCESSFUL READ. The org answered — that answer is the whole product of
+                // this call. Only a timeout is a failed read, because only then did nothing come back.
+                outcome: result.timedOut ? "failed" : "ok"
+            });
+            const headline = result.timedOut
+                ? `NO ANSWER — the org did not respond within the timeout. This is neither a pass nor a refusal: nothing was validated, and nothing was deployed either. Re-run it; if it times out again, say so in your plan rather than treating silence as approval.`
+                : result.accepted
+                    ? `ACCEPTED — the org would deploy all ${result.componentCount} component(s) as authored. This proves the metadata is DEPLOYABLE, never that it behaves correctly; runtime behavior is still unproven.`
+                    : `REFUSED — the org will not accept ${result.failures.length} of ${result.componentCount} component(s) as authored.`;
+            const lines = [
+                headline,
+                `org status: ${result.status}   (${(result.durationMs / 1000).toFixed(1)}s — the org queues concurrent validations, so a slow call is usually the queue)`,
+                ...(result.failures.length > 0
+                    ? [
+                        "",
+                        "SALESFORCE'S OWN WORDS, verbatim — quote these, do not paraphrase them:",
+                        ...result.failures.map((f) => `  ${f.component}: ${f.problem}${f.problemType ? `   [${f.problemType}]` : ""}${f.line ? `   (line ${f.line}${f.column ? `, col ${f.column}` : ""})` : ""}`),
+                        "",
+                        "Fix what is yours to fix and re-run — a missing required attribute or a mistyped reference is a typo,",
+                        "not a decision. A refusal that means the requested DESIGN is not expressible is a BLOCKER: record it",
+                        "in your plan.json with the org's message above quoted verbatim, and a recommendedAnswer for the",
+                        "alternative. The supervisor consolidates it into the operator's one clarification card."
+                    ]
+                    : []),
+                ...(assembled.report.includes("NO authored file") ? ["", assembled.report] : [])
+            ];
+            return ok(lines.join("\n"), {
+                extId,
+                accepted: result.accepted,
+                timedOut: result.timedOut,
+                status: result.status,
+                componentCount: result.componentCount,
+                failures: result.failures,
+                durationMs: result.durationMs
+            });
+        }
+        catch (error) {
+            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("direct_apply", {
+        description: "GATED (CC_MCP_DIRECT_WRITE=1 + allowlist, default T-Pinto; the consultant org is HARD-refused). " +
+            "NORMAL USE IS {sessionId, wave, waveComponents}: pass plan_waves' component list for the wave and this ASSEMBLES, lints and deploys it in ONE call, so the tree cannot be edited between the two. " +
+            "THE WAVE TREE IS A BUILD ARTIFACT rebuilt on every call: an edit made inside <session>/authored/<wave>/ is silently OVERWRITTEN rather than deployed — a wave-specific fix belongs in the revision's own file under requirements/<extId>/authored/. Nothing checks this; it is the one footgun with no refusal behind it. " +
+            "Assembly refuses rather than guessing, and each refusal names the decision and its fix: `OWNERSHIP_CONFLICT`, `COMPONENT_AUTHORED_TWICE`, `COMPONENT_STILL_PROVISIONAL`, `COMPONENT_NOT_OWNED`. Two softer cases never refuse: components nobody authored come back in `missing`, and a file plan.json forgot is used and reported under `recoveredFromDisk`. " +
+            "Author a wave BY HAND and pass {sessionId, wave} alone to deploy it as-is. Inline `components` is for ONE-OFF corrections and refuses past a handful (`INLINE_BATCH_REFUSED`). " +
+            "THE LOOP, in one call: pre-projection → lint (blockable, ackable via `ackLints`; includes the pre-flight full-file-replace diff, and grounds exactly as direct_lint does) → checkOnly → real deploy → optional destructive deletes → post-projection → three-way diff (intended vs actual vs everything-else-that-moved) → per-component intent verification → verdict. Every stage's raw output persists in an evidence bundle. " +
+            "VERDICTS: LINT_BLOCKED | REJECTED_BY_ORG | VALIDATED (`dryRunOnly`) | DIFF_VERIFIED | DELIVERED_WITH_DRIFT | AMBIGUOUS_DELIVERY (an UNRECOVERABLE deploy timeout OR a post-deploy read-back failure — the mutation may have LANDED; re-project to confirm, never blind-re-apply). A timed-out deploy is now recovered where possible: the Salesforce job outlives our watcher, so it is reported on by job id and cancelled if still running, and a recovered outcome is the org's real answer rather than an ambiguity. " +
+            "LOSS CHECKS, all self-describing when they fire: `removals` (what an edited component LOST, pre vs post) and its pre-deploy form `PREFLIGHT_REPLACE_DROPS_UNSTATED`/`_STATED`; `PREFLIGHT_PREIMAGE_FACET_INCOMPLETE` when the pre-image cannot support the question; `PREVIEW_REPLACE_DROPS_EARLIER` at lint time when the batch changes one component twice. Any removal blocks DIFF_VERIFIED. " +
+            "`unstatedChanges` (`unstated-changes.json`) reports facets your file never states that CHANGED VALUE — org normalization and reorders subtracted, so every entry is a real change nobody asked for, and any entry blocks DIFF_VERIFIED. " +
+            "Accepts ANY single-file-XML metadata type (resolved from Salesforce's SDR registry — no hand-maintained allowlist) AND content-file types (EmailTemplate/StaticResource/Document — body via `content`, base64 for binary). " +
+            "DIFF_VERIFIED is NOT gate certification; it is mechanical read-back proof of the edited slice (metadata shape; runtime behavior is never proven). " +
+            "LONG-RUNNING: checkOnly + deploy + two projections take typically 30-60s; up to 3 minutes on a large or brownfield wave — call with a generous timeout (measured over 121 applies: 25% exceed 47s, 10% exceed 88s, and a 60s client default kills real runs).",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .describe("The session this work belongs to. The target org comes FROM the session — bound and verified by activate_session (or create_session) — so there is no targetOrg to pass and no alias to get wrong. Refuses if the session's alias has since been repointed at a different org."),
+            wave: z
+                .string()
+                .optional()
+                .describe("Wave label — resolves to <session>/authored/<wave>, the SAME tree direct_lint reads. Author the wave there and lint/apply cannot disagree about what is being deployed. Also used as the evidence-bundle label when `label` is omitted."),
+            waveComponents: z
+                .array(WAVE_COMPONENT_SCHEMA)
+                .nonempty()
+                .optional()
+                .describe("The components this wave contains, straight from plan_waves' output for that wave. Given these, the wave tree is REBUILT from the files the analyzers authored before anything is linted or deployed — so the thing this call validates is the thing it just assembled. Omit only when you authored the wave tree by hand."),
+            ackIncompleteWave: z.boolean().optional().describe("Acknowledge deploying an INCOMPLETE wave: some requested components have no authored file, and only the assembled subset will lint and deploy. Only pass this after the operator has agreed to partial delivery — an approved wave is a scope, and delivering part of it is a change to that scope."),
+            components: z
+                .array(EDIT_SCHEMA)
+                .optional()
+                .describe(`ESCAPE HATCH for one-off corrections: creates/updates as inline metadata XML. Refuses past ${INLINE_MAX} components unless ackInline is set — more than that is a batch, and a batch belongs in a wave. Omit when using wave or sourceDir.`),
+            ackInline: z
+                .boolean()
+                .optional()
+                .describe("Acknowledge deploying a batch inline anyway. Recorded in the evidence bundle. Prefer authoring files and passing `wave`."),
+            sourceDir: z
+                .string()
+                .optional()
+                .describe("ESCAPE HATCH: absolute path to a source-format metadata tree outside the session (a force-app/main/default wrapper is tolerated). Prefer `wave`. Mutually exclusive with `components`; can accompany deletes/objectFacetUpdates."),
+            deletes: z
+                .array(z.object({ typeName: z.string(), fullName: z.string() }))
+                .optional()
+                .describe("Destructive deletes (mdapi destructiveChanges deploy)."),
+            objectFacetUpdates: z
+                .array(z.object({ objectApiName: z.string(), facets: z.record(z.string(), z.unknown()) }))
+                .optional()
+                .describe("FALLBACK for parent-object TOP-LEVEL facet changes (enableActivities, compactLayoutAssignment, ...) via CRUD read-modify-write, which REPLACES the object's top-level properties — anything the read did not return resets. PREFER a full CustomObject source deploy (CustomObject merges; it rides the normal lint/checkOnly/diff path). ORDERING: in a combined call the metadata deploy runs BEFORE these. Child collections refuse."),
+            ackLints: z.array(z.string()).optional().describe("Lint rule names to override (explicit ack — recorded in evidence)."),
+            requirementIds: z
+                .array(z.string())
+                .optional()
+                .describe("The requirement(s) this wave delivers, e.g. [\"REQ-15462\"]. Recorded in the evidence bundle and carried into the org's history, which is the only place the question 'why does this field exist?' can be answered months later — the bundle proves WHAT changed and never what it was for. Identifiers only; they end up in a commit trailer."),
+            dryRunOnly: z
+                .boolean()
+                .optional()
+                .describe("Stop after checkOnly; write nothing. Covers file components AND deletes (the destructive package goes as a destructive checkOnly, so each delete reports its own verdict). objectFacetUpdates have no validation step — they report NOT VALIDATED, and a wave of only those refuses (`DRY_RUN_NOTHING_TO_VALIDATE`)."),
+            wideObjectScope: z
+                .boolean()
+                .optional()
+                .describe("Project the WHOLE parent object before and after, instead of only the components this wave touches. Off by default — it is slower and can trip the projection's component cap. Turn it on for a deliberate 'show me everything on this object, before and after'."),
+            label: z.string().optional().describe("Evidence-bundle label [A-Za-z0-9_-]{1,40}; default timestamp."),
+            apiVersion: z.string().optional()
+        }
+    }, async ({ sessionId, wave, waveComponents, ackIncompleteWave, components, sourceDir, deletes, objectFacetUpdates, ackLints, ackInline, requirementIds, dryRunOnly, wideObjectScope, label, apiVersion }) => {
+        try {
+            if (waveComponents?.length && components?.length)
+                return inlineVsWave();
+            if (components && components.length > INLINE_MAX && !ackInline) {
+                return fail("INLINE_BATCH_REFUSED", [
+                    `${components.length} components inline. That is a batch, and a batch belongs in a wave.`,
+                    "",
+                    "Inline XML lives only in this tool call: there is no file to lint on its own, diff, hand back",
+                    "for review, edit without re-emitting the whole component, or commit. It also means one agent",
+                    "writes serially what the analyzers already wrote in parallel.",
+                    "",
+                    `  direct_apply {sessionId, wave, waveComponents} — pass this wave's component list from`,
+                    `  plan_waves and the analyzers' authored files are assembled, linted and deployed in this`,
+                    `  one call. Components no analyzer authored come back NAMED: write those as source-format`,
+                    `  files under requirements/<extId>/authored/, record each as its entry's authoredFile, and`,
+                    `  call again.`,
+                    "",
+                    `Genuinely a one-off? Send ${INLINE_MAX} or fewer. Genuinely need this batch inline? Pass ackInline: true —`,
+                    "it is recorded in the evidence bundle."
+                ].join("\n"));
+            }
+            let edits = (components ?? []);
+            const dels = (deletes ?? []);
+            const facets = (objectFacetUpdates ?? []);
+            const notes = [];
+            if (wave && !LABEL_RE.test(wave))
+                return fail("INVALID_LABEL", `wave must match ${LABEL_RE}.`);
+            let walkDir = sourceDir ?? authoredWaveDir(sessionId, wave);
+            let revisions = [];
+            if (walkDir && components?.length) {
+                return fail("AMBIGUOUS_INPUT", "Provide either a source tree (wave or sourceDir) or inline components, not both.");
+            }
+            if (waveComponents?.length) {
+                // Assembly runs INSIDE the apply, so the tree this walks is the tree it just wrote — the
+                // lint, the checkOnly and the deploy all see the same files, with no window between them
+                // in which the tree could be edited or go stale.
+                const assembled = await assembleRequestedWave(sessionId, wave, waveComponents, sourceDir, ackIncompleteWave);
+                if (!assembled.ok)
+                    return fail(assembled.code, assembled.message);
+                walkDir = assembled.dir;
+                notes.push(assembled.report);
+                // Intent rides ALONGSIDE the tree, because the tree cannot carry it. Derived from the same
+                // plan entries assembly just read, so the bundle's record of what this wave meant to do
+                // agrees with the files it deployed.
+                const resolved = await resolveWaveRevisions(sessionId, waveComponents);
+                revisions = resolved.revisions;
+                if (resolved.note)
+                    notes.push(resolved.note);
+                // PROVENANCE, AS A WARNING AND NOTHING MORE. plan_waves is advisory and hand-ordering is
+                // legitimate — but nothing used to NOTICE when a submitted wave corresponded to no derived
+                // one, so a mistake and a judgement call looked identical. Now the divergence is named
+                // where it costs money: every extra wave is two org round-trips plus two projections.
+                //
+                // Silent when the session holds no derivation (plan_waves never ran, or ran before this
+                // shipped) — an absent plan is not evidence of a bad wave, and a warning about nothing is
+                // the fastest way to train a reader past the block that matters.
+                const derivation = await readWaveDerivation(sessionId);
+                if (derivation) {
+                    const divergence = renderDivergence(compareToDerivation(waveComponents, derivation), derivation);
+                    if (divergence)
+                        notes.push(divergence);
+                }
+            }
+            else if (walkDir && !sourceDir && sessionId && wave) {
+                const w = await assertAuthoredWaveExists(sessionId, wave, walkDir);
+                if (!w.ok)
+                    return fail(w.code, w.message);
+            }
+            if (walkDir) {
+                const walked = await walkSourceTree(walkDir);
+                edits = walked.components;
+                if (walked.skipped.length) {
+                    notes.push(`skipped ${walked.skipped.length} unrecognized file(s): ${walked.skipped.map((s) => `${s.file} (${s.reason})`).join("; ")}`);
+                }
+                notes.push(`authored from ${edits.length} component(s) walked from ${walkDir}`);
+            }
+            if (edits.length === 0 && dels.length === 0 && facets.length === 0) {
+                return fail("NO_WORK", walkDir
+                    ? `No recognized metadata files under ${walkDir}, and no deletes/facets.`
+                    : "Provide wave (the authored tree is derived), sourceDir, components, deletes, and/or objectFacetUpdates.");
+            }
+            // A practice run that can run no practice — now exactly ONE path rather than two.
+            //
+            // Deletes are checkable: a destructive mdapi package takes `--dry-run` like any other deploy
+            // (checkOnly is a deploy-API option, not a property of the source format), and the org answers
+            // per member — validated, blocked by a live reference, or not found. A delete-only dry run is
+            // therefore a real practice run and no longer refuses.
+            //
+            // objectFacetUpdates have no such mode: a CRUD read-modify-write is applied or it is not.
+            // A facet-only wave would return VALIDATED having checked nothing — and VALIDATED is the
+            // verdict this tool maps to a `confirmed` telemetry outcome and the word an operator quotes,
+            // so it would both report and RECORD a success nobody established.
+            //
+            // (The apply loop is independently safe: under dryRunOnly it performs no write at all and
+            // labels the facet path NOT VALIDATED. This refusal is about not handing back a green light.)
+            if (dryRunOnly && edits.length === 0 && dels.length === 0 && facets.length > 0) {
+                return fail("DRY_RUN_NOTHING_TO_VALIDATE", [
+                    `dryRunOnly cannot check this wave: it carries only objectFacetUpdates, and that is the one path`,
+                    `Salesforce exposes no validation step for — a CRUD read-modify-write is applied or it is not.`,
+                    "",
+                    `  file components    are submitted as a checkOnly deploy`,
+                    `  deletes            are submitted as a destructive checkOnly (--metadata-dir --dry-run)`,
+                    `  objectFacetUpdates have no validation step at all`,
+                    "",
+                    `Reporting VALIDATED here would mean "checked and accepted" over work that was submitted nowhere.`,
+                    "",
+                    `Either drop dryRunOnly and apply for real — the post-deploy read-back is what verifies this path,`,
+                    `and it is stronger than a checkOnly — or add the file components or deletes you wanted validated,`,
+                    `in which case those are checked and the facets are reported NOT VALIDATED beside them.`
+                ].join("\n"));
+            }
+            if (label && !LABEL_RE.test(label))
+                return fail("INVALID_LABEL", `label must match ${LABEL_RE}.`);
+            // The org is derived, never supplied. resolveSessionOrg re-checks that the session's alias
+            // still points at the org the session was bound to, so a repointed alias is refused BY NAME
+            // rather than surfacing later as a confusing allowlist miss.
+            const session = await loadSession(sessionId);
+            const binding = await resolveSessionOrg(session, "target");
+            const targetOrg = binding.alias;
+            await assertDirectWriteAllowed(targetOrg);
+            const version = apiVersion?.trim() || DEFAULT_API_VERSION;
+            // Evidence lives UNDER THE SESSION, not in a per-org pile. A bundle is the proof of what
+            // THIS session's wave did, so the session is its only correct home. Filing by org alias
+            // instead meant two sessions against the same org shared a directory and could collide on
+            // label, deleting a session left its evidence orphaned, and — the tell — the CI planner had
+            // to be handed absolute bundle paths because nothing could find them from the session.
+            const bundleDir = path.join(sessionDir(sessionId), "direct", 
+            // `wave` defaults the bundle label so the NEXT wave can lint against this one by name:
+            // direct_lint's `projection` resolves a bundle label to its post-image, and that only
+            // works if the bundle is named after the wave rather than an opaque timestamp.
+            label ?? wave ?? new Date().toISOString().replace(/[:.]/g, "-"));
+            const reader = await createLiveOrgReader(targetOrg, version);
+            const attempt = await nextWaveAttempt(bundleDir);
+            if (attempt > 1)
+                await archivePriorAttempt(bundleDir, attempt - 1);
+            const startedAt = new Date().toISOString();
+            const result = await runDirectApply({
+                reader,
+                targetOrg,
+                apiVersion: version,
+                edits,
+                deletes: dels,
+                facetUpdates: facets,
+                ...(revisions.length ? { revisions } : {}),
+                ...(await batchPlannedTokens(sessionId).then((t) => (t ? { plannedTokens: t } : {}))),
+                acks: ackLints ?? [],
+                ...(ackInline ? { ackInline: true } : {}),
+                // The who/why the evidence bundles have never carried (origin R3). All three come from
+                // state that already exists — the session's batch, the caller's requirement ids, and the
+                // authenticated username the session was bound with — so nothing new is asked of the
+                // supervisor and nothing is invented when they are absent.
+                ...(session.batchId ? { batchId: session.batchId } : {}),
+                ...(requirementIds?.length ? { requirementIds } : {}),
+                ...(OPERATOR_IDENTITY ?? session.actors?.targetUsername
+                    ? { operator: OPERATOR_IDENTITY ?? session.actors?.targetUsername }
+                    : {}),
+                dryRunOnly: dryRunOnly ?? false,
+                ...(wideObjectScope ? { wideObjectScope: true } : {}),
+                bundleDir
+            });
+            // Reported from the result the apply loop already computed — no extra read, no extra
+            // round-trip, and nothing here can alter the verdict the evidence bundle records.
+            //
+            // COMPONENTS, not facets. `item.matched` is the number of matched FACETS on one component
+            // — a field with nine compared facets contributes nine — while `intendedCount` below counts
+            // components. Summing the former and dividing by the latter is a facets-per-component
+            // ratio wearing an automation-rate label: the ops dashboard read "1800.0% — 432 of 24
+            // components verified" off six clean waves (live-caught 2026-07-31).
+            //
+            // A component counts as matched when it reached its intended end state and nothing
+            // mismatched — the same rule DIFF_VERIFIED uses, so the panel and the verdict agree.
+            //
+            // `item.found` was the first attempt at "reached its intended end state" and is wrong for
+            // DELETES, where success IS absence: applyLoop records a removed component as
+            // `matched: 1, mismatches: [], found: false`. Filtering on `found` therefore scored a wave
+            // of three cleanly deleted components as "0.0% — 0 of 3 verified" beside a green
+            // DIFF_VERIFIED, having just replaced a bug that scored six clean waves at 1800%.
+            //
+            // `matched > 0` covers both directions: compareIntent returns `matched: 0` with an
+            // "(absent)" mismatch when an EDIT is missing, so a component that failed to land still
+            // cannot count. The rule lives in direct/waveCounts.ts so its test pins THIS code rather
+            // than a copy of it — the previous test asserted a local reimplementation and stayed green
+            // while this line was wrong.
+            // READ PROVENANCE (R9-R10, R12). A wave is a WRITE, but it reads too — a pre-projection
+            // before it deploys and a post-projection after — and both are full component snapshots, so
+            // the pattern is a body read. Omitting them would leave the read-set claiming a session
+            // never looked at the very components it delivered.
+            //
+            // Pointers, not lists, for the same reason project_org uses them: the bundle's own
+            // manifests already name every component. Only the ones that exist are pointed at — a
+            // LINT_BLOCKED or REJECTED_BY_ORG wave never reaches its post-projection, and a pointer to
+            // a file that was never written is a broken promise a later report has to handle.
+            const manifests = [];
+            for (const phase of ["pre", "post"]) {
+                const file = path.join(bundleDir, phase, "projection.json");
+                try {
+                    await fs.access(file);
+                    manifests.push(file);
+                }
+                catch {
+                    // Not written on this path. Absence is the honest record.
+                }
+            }
+            await appendReadRecord(sessionId, {
+                tool: "direct_apply",
+                orgId: binding.orgId ?? null,
+                orgAlias: targetOrg,
+                scope: `wave ${path.basename(bundleDir)}`,
+                pattern: "body",
+                keys: [],
+                manifests,
+                rows: edits.length + dels.length + facets.length,
+                durationMs: Date.now() - Date.parse(startedAt),
+                outcome: "ok"
+            });
+            const matchedCount = matchedComponentCount(result.intent ?? []);
+            const mismatchCount = (result.intent ?? []).reduce((sum, item) => sum + item.mismatches.length, 0);
+            emitDomainTelemetryEvent("deployment.wave_completed", {
+                waveLabel: path.basename(bundleDir),
+                attempt,
+                // Deduped: one wave naturally names the same requirement twice (two components, one
+                // requirement), and the ingest validator REJECTS duplicates — which would silently
+                // drop this event and mark the whole batch's requirement tracking incomplete.
+                requirementIds: [...new Set(requirementIds ?? [])],
+                dryRunOnly: dryRunOnly === true,
+                // The read-back backoff, measured rather than assumed — and the measurement came back
+                // ZERO on 28 of 28 waves, so the backoff is gone and this is now always 0. Still sent,
+                // because a field that simply stops arriving is indistinguishable in the ledger from an
+                // install too old to send it. `readbackSettled` is no longer sent at all: it answered
+                // "did waiting help", and nothing waits. The ingest validator treats it as optional.
+                readbackWaitMs: result.readbackWaitMs ?? 0,
+                checkOnlyStatus: result.dryRun?.status,
+                deployId: result.deploy?.id,
+                deployStatus: result.deploy?.status,
+                deployTimedOut: result.deploy?.timedOut ?? false,
+                readbackVerdict: result.verdict,
+                intendedCount: edits.length + dels.length + facets.length,
+                matchedCount,
+                mismatchCount,
+                sideChangeCount: result.sideChanges?.length ?? 0,
+                removalCount: result.removals?.length ?? 0,
+                // WHERE THIS WAVE'S ORG TIME WENT, measured rather than argued (core/orgCallMeter.ts).
+                //
+                // A Windows run was observed taking up to ~8 minutes per wave against a Mac's ~34s
+                // median, and the ledger could not apportion it. Counts and milliseconds, split by
+                // KIND — `sf` CLI children (three per wave) against jsforce round-trips (tens, and
+                // where a projection's time actually goes) — plus the first call of the wave on its
+                // own, so a startup cost can be told apart from per-call latency. Those have opposite
+                // fixes, and one number cannot distinguish them.
+                //
+                // Read HERE rather than carried on the result: the apply loop has five early returns
+                // and threading a measurement through all of them for one telemetry field would put an
+                // observability concern in the deploy path's control flow. The meter is cleared at the
+                // wave's entry, so what it holds now is this wave's.
+                //
+                // Absent on a wave that never reached the org — see orgCallMeterSnapshot.
+                ...orgCallMeterSnapshot(),
+                startedAt,
+                completedAt: new Date().toISOString()
+            }, {
+                stage: "deploy",
+                outcome: result.verdict === "DIFF_VERIFIED" || result.verdict === "VALIDATED"
+                    ? "confirmed"
+                    : result.verdict
+            });
+            const lines = [
+                `verdict: ${result.verdict}`,
+                `bundle: ${result.bundleDir}`,
+                // The mirror line is present whenever a state-changing wave ran, including when it
+                // recorded NOTHING — "no change to record" and "could not record" are different answers
+                // and a missing line would render both as silence.
+                ...(result.mirror
+                    ? [
+                        result.mirror.error
+                            ? `history: NOT RECORDED (${result.mirror.error})`
+                            : result.mirror.committed
+                                ? `history: recorded as ${result.mirror.sha?.slice(0, 12)} (direct_history to read it; the sha is a display alias, never store it)`
+                                : "history: nothing to record — this wave left the org exactly as the last one did"
+                    ]
+                    : []),
+                ...(result.mirror?.drifted?.length
+                    ? [`CHANGED OUTSIDE THIS MACHINE'S HISTORY: ${result.mirror.drifted.join(", ")}`]
+                    : []),
+                ...(result.lint.findings.length ? [`lint: ${result.lint.findings.length} finding(s)`] : []),
+                ...(result.dryRun ? [`dryRun: ${result.dryRun.status}`] : []),
+                ...(result.deploy ? [`deploy: ${result.deploy.status}${result.deploy.id ? ` (${result.deploy.id})` : ""}`] : []),
+                ...(result.facetUpdates ? result.facetUpdates.map((f) => `facets ${f.object}: ${f.status}`) : []),
+                ...(result.intent
+                    ? result.intent.map((r) => `intent ${r.component}: ${r.mismatches.length === 0 ? `MATCH (${r.matched} leaves${r.orderOnly ? `, ${r.orderOnly} order-only` : ""})` : `${r.mismatches.length} MISMATCH`}`)
+                    : []),
+                ...(result.sideChanges?.length ? [`SIDE CHANGES (unexpected): ${result.sideChanges.join(", ")}`] : []),
+                // Named on the summary line, not left to the notes: this is the class that shipped green
+                // on the EV-31…40 run, and a reader who only skims the first few lines must still see it.
+                ...(result.unstatedChanges?.length
+                    ? [`UNSTATED CHANGES (nobody asked for these): ${result.unstatedChanges.map((u) => u.component).join(", ")}`]
+                    : []),
+                ...notes,
+                ...result.notes
+            ];
+            return ok(lines.join("\n"), result);
+        }
+        catch (error) {
+            if (error instanceof GateError)
+                return fail(error.code, error.message);
+            // ORG_NOT_BOUND and ALIAS_REPOINTED are operator-actionable refusals with specific fixes.
+            // Collapsing them into INTERNAL_ERROR would hide the one message that says what to do.
+            if (error instanceof SessionOrgError)
+                return fail(error.code, error.message);
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            if (error instanceof OrgReaderUnavailableError)
+                return fail("ORG_READER_UNAVAILABLE", error.message);
+            return internalError(error);
+        }
+    });
+    server.registerTool("direct_history", {
+        description: "READ-ONLY history of everything IN2 has delivered to this session's org, from the local org mirror. No org contact, no gate, no writes. " +
+            "Every state-changing wave (DIFF_VERIFIED / DELIVERED_WITH_DRIFT / AMBIGUOUS_DELIVERY) records its post-image and the source XML it deployed here as one entry; " +
+            "LINT_BLOCKED, REJECTED_BY_ORG and VALIDATED (practice run) never do, because they changed nothing. A re-delivery that leaves the org exactly as it was records nothing either. " +
+            "`log` lists the entries newest-first, each with its verdict, requirement ids and any drift note (CHANGED OUTSIDE THIS MACHINE'S HISTORY / STALE PARENT / NOT COMPARABLE — the playbook says what each one means for the operator); " +
+            "`show` names the files one entry touched; `diff` returns the actual before/after patch. Pass `component` (\"CustomField:Account.Region__c\") to follow ONE component through its deliveries — the 'when did this field last change, and to what?' question. " +
+            "Every action flags an INCOMPLETE RECORD where one exists: a facet the read could not reach is DROPPED from the snapshot, so its absence is not evidence the org has nothing there — never author a full-file replacement from such a snapshot. " +
+            "`contamination` answers a different question — measurement validity: which components a PRIOR session delivered into this org did THIS session go on to read. It is positive-evidence-only and never returns a clean verdict. " +
+            "SCOPE, and it is narrow ON PURPOSE: this covers what THIS INSTALL delivered. A client admin's edit in Setup, and another consultant's wave from another machine, are both invisible here — they appear only as a component that had 'changed outside this machine's history' the next time IN2 touches it. " +
+            "It is also a REBUILDABLE CACHE derived from the evidence bundles: the `sha` values are display aliases for a conversation happening now, and a rebuild rewrites every one of them. Never store a sha, and never quote one to an operator as an identifier they can come back with — address a wave by (session, wave) instead.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .describe("The session whose org's history to read. The org is derived from the session, exactly as it is for direct_apply — there is no org to name and none to get wrong."),
+            action: z
+                .enum(["log", "show", "diff", "contamination"])
+                .optional()
+                .describe("log (default) = the entry list; show = the files one entry touched; diff = the patch for one entry; contamination = what this session read of what prior sessions delivered here."),
+            ref: z.string().optional().describe("Which entry, for show/diff: a sha from `log`. Defaults to the most recent entry."),
+            against: z.string().optional().describe("diff only: compare `ref` against this earlier entry instead of against its own parent."),
+            component: z
+                .string()
+                .optional()
+                .describe('Narrow to one component, as "TypeName:FullName" (e.g. "CustomField:Account.Region__c", "Layout:Account-Account Layout").'),
+            limit: z.number().optional().describe("log only: how many entries (default 25, max 500).")
+        }
+    }, async ({ sessionId, action, ref, against, component, limit }) => {
+        try {
+            // No `appendReadRecord` here, and the absence is deliberate: reads.jsonl records ORG reads
+            // (origin R9), and this tool reads a local cache of what this install already delivered. A
+            // record would inflate the read-set that the contamination metric (U5) intersects against
+            // prior arms — an install reading its own history is not evidence it saw the org.
+            const session = await loadSession(sessionId);
+            const { alias, orgId } = await resolveSessionOrg(session, "target", { verify: false });
+            if (!orgId) {
+                return fail("ORG_NOT_BOUND", `Session ${sessionId} is bound to alias ${JSON.stringify(alias)} but recorded no Org ID, and the mirror is keyed by org id. Re-bind the session (activate_session, or create_session { targetOrgAlias, targetOrgId }).`);
+            }
+            // U5 / origin R22. Read-only like the rest of this tool, and local like the rest of it: the
+            // report joins reads.jsonl against the mirror and goes nowhere near the ledger.
+            if (action === "contamination") {
+                const report = await computeContamination({ sessionId, orgId, orgAlias: alias });
+                // PERSIST, don't just answer. This path used to compute the report and return it as text
+                // only, so the one place the report could survive the conversation was the batch-close
+                // hook — which never ran (see close_batch). A report that exists solely in a transcript is
+                // one an operator cannot be handed and a bench harness cannot read, and the Arm A run's
+                // report had to be captured by hand for exactly that reason. Writing here also means an
+                // interrupted run keeps whatever it measured before it stopped.
+                const written = await writeContaminationArtifacts(report);
+                return ok(written
+                    ? `${renderContamination(report)}\n\nWritten to ${written.markdown}. The full batch-close report — this, plus the delivery log and the batch-level findings — comes from close_batch at the end of the run.`
+                    : renderContamination(report), report);
+            }
+            if ((action ?? "log") === "log") {
+                const entries = await historyLog({ orgId, limit: limit ?? 25, ...(component ? { component } : {}) });
+                if (entries.length === 0) {
+                    return ok(component
+                        ? `No delivery recorded for ${component} in this org. IN2 has either never touched it, or touched it without changing anything.`
+                        : "No deliveries recorded for this org yet.", { entries: [], orgId });
+                }
+                const lines = entries.map((e) => {
+                    // Distinct containers whose mirrored copy this history explained itself, from the
+                    // `<container> <- <child>` pairs the trailer records one per child.
+                    const staleParents = [...new Set(e.driftExplained.map((pair) => pair.split(" <- ")[0]))];
+                    const flags = [
+                        ...(e.ambiguous ? ["DELIVERY AMBIGUOUS — the post-image is partial"] : []),
+                        ...(e.orderingUnreliable ? ["position in this list is not evidence of when it happened"] : []),
+                        ...(e.revertOf ? [`rollback of ${e.revertOf}`] : []),
+                        ...(e.drifted.length ? [`changed outside this machine's history first: ${e.drifted.join(", ")}`] : []),
+                        ...(staleParents.length
+                            ? [
+                                `recorded shape of ${staleParents.join(", ")} was stale here — accounted for by this history's own delivery of ${e.driftExplained.length} child component(s), not an outside change`
+                            ]
+                            : []),
+                        // A check that could not run, printed beside the checks that did. Never folded into
+                        // the drift line: this history has no claim to make about these components.
+                        ...e.notComparable.map((entry) => `NOT COMPARABLE (no claim either way, NOT a clean result) — ${entry.split(" <> ")[0]}: ${entry.split(" <> ").slice(1).join("; ") || "reader changed"}`),
+                        // A bound on what this entry RECORDS, printed beside the findings drawn from it. The
+                        // facet is absent from the stored snapshot, so it cannot announce itself.
+                        ...e.incompleteFacets.map((entry) => `INCOMPLETE RECORD (never read, NOT empty) — ${entry.split(" <> ")[0]}: ${(entry.split(" <> ")[1] ?? "?")
+                            .split(",")
+                            .map((f) => `${f.trim()}: NOT READ at capture`)
+                            .join("; ")}`)
+                    ];
+                    return (`${e.sha.slice(0, 12)}  ${e.date}  ${e.wave ?? "?"}${e.attempt && e.attempt > 1 ? ` (attempt ${e.attempt})` : ""}  ${e.verdict ?? "?"}` +
+                        `${e.requirementIds.length ? `  [${e.requirementIds.join(", ")}]` : ""}` +
+                        `${flags.length ? `\n    ${flags.join("\n    ")}` : ""}`);
+                });
+                return ok(`${entries.length} deliver${entries.length === 1 ? "y" : "ies"} recorded for this org${component ? ` touching ${component}` : ""} (newest first).\n${lines.join("\n")}`, { entries, orgId });
+            }
+            const target = ref ?? (await historyLog({ orgId, limit: 1 }))[0]?.sha;
+            if (!target)
+                return ok("No deliveries recorded for this org yet.", { orgId });
+            if (action === "show") {
+                const shown = await historyShow({ orgId, ref: target });
+                const files = shown.files.map((f) => `${f.status}  ${f.path}`).join("\n");
+                return ok(`${shown.sha.slice(0, 12)}\n${shown.message.trim()}\n\n${files || "(no files)"}${renderIncompleteFacets(shown.incompleteFacets)}`, shown);
+            }
+            const patch = await historyDiff({
+                orgId,
+                ref: target,
+                ...(against ? { against } : {}),
+                ...(component ? { component } : {})
+            });
+            // The bound goes ABOVE the patch, not below it. The reader dropped the key it could not
+            // verify, so the facet is invisible in the diff by construction — a reader who scrolls a
+            // clean-looking patch and stops has been told something false.
+            const bounds = await historyIncompleteFacets({ orgId, ref: target });
+            const scoped = component ? bounds.filter((b) => b.component === component) : bounds;
+            const bound = renderIncompleteFacets(scoped).trimStart();
+            const body = patch.trim() || "(no changes in that entry for this scope)";
+            // `text` is set by hand to the BOUND ALONE, suppressing ok()'s full-text mirror: the patch
+            // is uncapped (raw `git show --patch`), it already rides `patch`, and mirroring the
+            // composed text would put a second full copy into the one channel the model reads —
+            // measured at 39 KB -> 80 KB of model-visible payload on a real diff. The warning must
+            // still reach the model (the dropped-facet caveat is the part a patch cannot carry), so it
+            // cannot simply opt out. Adversarial-review catch, 2026-08-21.
+            return ok(bound ? `${bound}\n\n${body}` : body, {
+                sha: target,
+                patch,
+                incompleteFacets: scoped,
+                text: bound
+                    ? `${bound}\n\n(the full patch is in \`patch\`)`
+                    : patch.trim()
+                        ? "(the full patch is in `patch`)"
+                        : body
+            });
+        }
+        catch (error) {
+            if (error instanceof OrgRepoError)
+                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("direct_rollback", {
+        description: "Undo a wave IN2 delivered, one component at a time, through the same apply loop that delivered it. GATED for execution (CC_MCP_DIRECT_WRITE=1 + allowlist); planning is read-only. " +
+            "ADDRESS THE WAVE BY (sessionId, wave) — never by a sha from direct_history. Those are display aliases and a mirror rebuild rewrites every one of them. " +
+            "THREE MODES, and the default changes nothing: `plan` (default) classifies and cards; `execute` deploys what is executable; `verify` is the wave that follows an undelete. " +
+            "PARTIAL BY DEFAULT: a component this refuses NEVER blocks the rest of the selection. Every selected component is classified before anything runs, and each class gets a different answer — a CREATE is undone by deleting it, a MODIFY by redeploying the pre-image the wave retrieved, and a change the Metadata API cannot undo is REFUSED, naming the limitation. " +
+            "A CustomField the wave DELETED under 15 days ago is NOT re-created as metadata at all — the operator gets an UNDELETE CARD, which carries the Setup path, the renamed API name, the remaining window and the post-undelete checklist, because an undelete restores the field AND ITS DATA while a re-create restores the definition, reports success, and throws every value away. A lapse the probe could not confirm is carded too, never acked. " +
+            "ACKS ARE PER COMPONENT AND NAMED: `ackComponents: [\"CustomField:Account.Region__c\"]`, the same explicit-override shape as `ackLints` — there is no bulk yes. Each held component is listed with the exact token that releases it. " +
+            "THE R16 PREFLIGHT runs when the org can be read: live state is compared against what the wave recorded, and a divergence blocks that component pending ack. The result reports what the preflight and the deleted-field probe actually ANSWERED, never merely that they were attempted — absence of a divergence is not evidence that live state agrees, and presence that was never measured is not absence. The undelete window is RE-CHECKED at execution, per component. " +
+            "Execution goes through the normal loop — lint, checkOnly, deploy, three-way diff, intent check, verdict — so the rollback earns its own evidence bundle and its commit is marked in the org mirror as a revert of the wave it undoes. " +
+            "LONG-RUNNING when it executes (the same typically 30-60s, up to 3 minutes, as direct_apply, plus the preflight read).",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .describe("The session that delivered the wave. The org is derived from it, exactly as for direct_apply — there is no org to pass and none to get wrong."),
+            wave: z
+                .string()
+                .describe("The wave label to undo — the label passed to direct_apply, which is also its bundle directory. NOT a sha."),
+            mode: z
+                .enum(["plan", "execute", "verify"])
+                .optional()
+                .describe("plan (default) = classify, card, change nothing. execute = deploy everything that is executable and acked. verify = after an operator undeletes a carded field in Setup, compare the restored field against the wave's own pre-image and report what the undelete did not restore."),
+            components: z
+                .array(z.string())
+                .optional()
+                .describe('Partial selection as "TypeName:FullName" (e.g. "CustomField:Account.Region__c"). Omit for the whole wave. Anything named that the wave did not touch is reported, not silently dropped.'),
+            ackComponents: z
+                .array(z.string())
+                .optional()
+                .describe('Component keys the operator has explicitly acknowledged, releasing them to execute. One key per decision — data loss, a drift the preflight found, an incomplete pre-image, an org-wide default recalculation. Recorded in the evidence bundle.'),
+            ackLints: z
+                .array(z.string())
+                .optional()
+                .describe("Lint rule names to override on the rollback's own deploy, exactly as on direct_apply. A pre-image is the org's own former state, so this is rarely needed."),
+            dryRunOnly: z
+                .boolean()
+                .optional()
+                .describe("Practice run: checkOnly for the redeploys and a destructive checkOnly for the deletes, writing nothing. Worth doing first when the rollback deletes anything — a destructive package rolls back WHOLE, so one refused member takes the clean ones with it."),
+            label: z.string().optional().describe("Evidence-bundle label for the ROLLBACK's own wave [A-Za-z0-9_-]{1,40}; default `revert-<wave>`. It must not be the target wave's label — that bundle is what the rollback reads its bytes from. If `revert-<wave>` would exceed 40 characters the call is REFUSED rather than truncated (a truncated default collides for any two waves sharing their first 33 characters, and the second rollback would then file itself as attempt 2 of the first) — pass one explicitly."),
+            apiVersion: z.string().optional()
+        }
+    }, async ({ sessionId, wave, mode, components, ackComponents, ackLints, dryRunOnly, label, apiVersion }) => {
+        const runMode = (mode ?? "plan");
+        try {
+            if (!LABEL_RE.test(wave))
+                return fail("INVALID_LABEL", `wave must match ${LABEL_RE}.`);
+            if (label && !LABEL_RE.test(label))
+                return fail("INVALID_LABEL", `label must match ${LABEL_RE}.`);
+            if (label === wave) {
+                return fail("INVALID_LABEL", `the rollback's bundle label cannot be the wave it is undoing (${wave}) — that bundle holds the pre-image this rollback deploys from, and reusing the label would overwrite it.`);
+            }
+            // WITH THE OTHER LABEL CHECKS, and before anything is looked up: this is a property of the
+            // two arguments alone, and a caller who has to name their own bundle should learn that from
+            // the same refusal shape as every other label mistake rather than after a wave lookup.
+            const bundleLabel = rollbackLabel(wave, label);
+            if (bundleLabel === null) {
+                return fail("INVALID_LABEL", `the default label for this rollback's own bundle, \`revert-${wave}\`, is ${`revert-${wave}`.length} characters — over the 40 every label is held to. ` +
+                    `It is not truncated, because truncation maps every wave sharing its first 33 characters onto ONE rollback bundle directory — and that directory is the identity: ` +
+                    `the second rollback would file itself as attempt 2 of the first one's, and its verdict, diff and evidence would land in the mirror under the wrong address. ` +
+                    `Pass an explicit \`label\` for this rollback (${LABEL_RE}), distinct from ${JSON.stringify(wave)}.`);
+            }
+            const session = await loadSession(sessionId);
+            const binding = await resolveSessionOrg(session, "target");
+            const targetOrg = binding.alias;
+            if (!binding.orgId) {
+                return fail("ORG_NOT_BOUND", `Session ${sessionId} is bound to alias ${JSON.stringify(targetOrg)} but recorded no Org ID, and both the mirror and the rollback's own commit are keyed by org id. Re-bind the session (activate_session, or create_session { targetOrgAlias, targetOrgId }).`);
+            }
+            const bundleDir = path.join(sessionDir(sessionId), "direct", wave);
+            try {
+                await fs.access(path.join(bundleDir, "verdict.json"));
+            }
+            catch {
+                const available = await availableWaveBundles(sessionId);
+                return fail("WAVE_NOT_FOUND", `no delivered wave "${wave}" in session ${sessionId} (expected ${bundleDir}).` +
+                    (available.length ? ` Waves recorded here: ${available.join(", ")}.` : " This session has delivered no waves.") +
+                    " A wave is addressed by the label direct_apply was called with, never by a sha.");
+            }
+            // WHICH pre/ THIS ROLLBACK MAY HONESTLY RESTORE. The earliest archived attempt that
+            // captured a pre-image holds the baseline from before the wave first touched the org
+            // (proven no-op attempts are skipped); a retried bundle with no completed archive predates
+            // that fix and refuses rather than guessing (see resolveRollbackBaseline).
+            const baseline = await resolveRollbackBaseline(bundleDir);
+            if (!baseline.ok)
+                return fail(baseline.code, baseline.message);
+            // THE BUNDLE'S OWN ORG vs THE SESSION'S. Both are on this machine and a session can be
+            // pointed at a different org than the one that produced a bundle sitting beside it; a
+            // rollback that missed that would deploy one org's former state into another org. Read from
+            // the resolved baseline, not unconditionally from bundleDir — for a retried wave that is
+            // attempt 1's archive, and it is the org that image actually came from.
+            const preManifest = await readJsonFile(path.join(baseline.preRoot, "pre", "projection.json"));
+            if (preManifest?.orgId && preManifest.orgId.slice(0, 15) !== binding.orgId.slice(0, 15)) {
+                return fail("ROLLBACK_ORG_MISMATCH", `wave ${wave} was delivered to org ${preManifest.orgId}, and this session is bound to ${binding.orgId}. Rolling it back here would deploy one org's former state into another. Open a session bound to ${preManifest.orgId} and run it there.`);
+            }
+            // The gate refuses an EXECUTE outright; on a plan it is reported instead, so an operator
+            // learns the rollback cannot land here while reading it rather than after building it.
+            let writeBlocked;
+            try {
+                await assertDirectWriteAllowed(targetOrg);
+            }
+            catch (error) {
+                if (!(error instanceof GateError))
+                    throw error;
+                if (runMode === "execute")
+                    return fail(error.code, error.message);
+                writeBlocked = `${error.code} — this org has no write authority on this install, so this plan can be read but not executed here.`;
+            }
+            const version = apiVersion?.trim() || DEFAULT_API_VERSION;
+            // FAIL-OPEN ON THE READER, and loudly. Without it there is no preflight and no deleted-field
+            // probe, and every claim that depends on them degrades to UNVERIFIED in the result — which
+            // is still a useful classification of the bundle, and is never mistaken for a clean one.
+            let reader;
+            let readerError;
+            try {
+                reader = await createLiveOrgReader(targetOrg, version);
+            }
+            catch (error) {
+                readerError = error instanceof Error ? error.message : String(error);
+            }
+            const rollbackBundleDir = path.join(sessionDir(sessionId), "direct", bundleLabel);
+            // Same attempt bookkeeping every wave gets: the mirror's sort key ends in attempt, so two
+            // runs of one rollback have to be two entries rather than one overwriting the other. And the
+            // SAME archive every wave gets, for the same reason: a rollback bundle IS a bundle — its own
+            // "wave" the next tool over can retry and, one day, roll back. Without this, executing one
+            // rollback twice left attempt 2 with no attempts/1/, and rolling back THAT bundle would
+            // refuse forever (resolveRollbackBaseline finds attempt > 1 and no archive).
+            if (runMode === "execute") {
+                const rollbackAttempt = await nextWaveAttempt(rollbackBundleDir);
+                if (rollbackAttempt > 1)
+                    await archivePriorAttempt(rollbackBundleDir, rollbackAttempt - 1);
+            }
+            // WHAT THE ROLLBACK IS FOR, carried from the wave it undoes. The requirement ids are the
+            // only thing in the mirror that answers "why did this change?", and a revert of a delivery
+            // is about the same requirements as the delivery.
+            const targetRequest = await readJsonFile(path.join(bundleDir, "request.json"));
+            const startedAt = new Date().toISOString();
+            const result = await runRollback({
+                mode: runMode,
+                sessionId,
+                wave,
+                orgId: binding.orgId,
+                orgAlias: targetOrg,
+                apiVersion: version,
+                bundleDir,
+                preImageRoot: baseline.preRoot,
+                rollbackBundleDir,
+                ...(components?.length ? { components } : {}),
+                ...(ackComponents?.length ? { ackComponents } : {}),
+                ...(ackLints?.length ? { ackLints } : {}),
+                ...(dryRunOnly ? { dryRunOnly: true } : {}),
+                ...(reader ? { reader } : {}),
+                ...(readerError ? { readerError } : {}),
+                ...(session.batchId ? { batchId: session.batchId } : {}),
+                ...(targetRequest?.requirementIds?.length ? { requirementIds: targetRequest.requirementIds } : {}),
+                ...(OPERATOR_IDENTITY ?? session.actors?.targetUsername
+                    ? { operator: OPERATOR_IDENTITY ?? session.actors?.targetUsername }
+                    : {}),
+                ...(writeBlocked ? { writeBlocked } : {})
+            });
+            // READ PROVENANCE (R9, R12). The preflight and the deleted-field probe are real org reads
+            // of real components, and a read-set that omitted them would understate what this session
+            // looked at — which is the one number the contamination metric cannot afford to flatter.
+            if (reader) {
+                const manifests = [];
+                for (const phase of ["preflight", "verify"]) {
+                    const file = path.join(rollbackBundleDir, phase, "projection.json");
+                    try {
+                        await fs.access(file);
+                        manifests.push(file);
+                    }
+                    catch {
+                        /* not written on this path — absence is the honest record */
+                    }
+                }
+                await appendReadRecord(sessionId, {
+                    tool: "direct_rollback",
+                    orgId: binding.orgId,
+                    orgAlias: targetOrg,
+                    scope: `rollback of wave ${wave} (${runMode})`,
+                    pattern: "body",
+                    keys: [],
+                    manifests,
+                    rows: result.dispositions?.length ?? result.verification?.findings.length ?? 0,
+                    durationMs: Date.now() - Date.parse(startedAt),
+                    outcome: "ok"
+                });
+            }
+            // BASELINE NOTE FIRST — an operator reading this rollback for a retried wave learns which
+            // attempt's pre-image it is restoring before anything else, not buried under the plan text.
+            //
+            // `text` is OVERRIDDEN in the structured payload, not left to ok()'s mirror:
+            // RollbackRunResult carries its own `text` field (the bare plan), which trips the
+            // don't-clobber guard in ok() — so the mirrored copy was the plan WITHOUT the baseline
+            // note, and on the one client we ship to (which drops the content channel, see
+            // core/result.ts) the sentence naming WHICH attempt is being restored never reached the
+            // model. Adversarial-review catch, 2026-08-21.
+            const text = baseline.note ? `${baseline.note}\n\n${result.text}` : result.text;
+            return ok(text, { ...result, text });
+        }
+        catch (error) {
+            // The classifier's three refusals are operator-readable sentences by construction. Letting
+            // them surface as INTERNAL_ERROR with a stack would replace an explanation of why this wave
+            // cannot be rolled back with a server fault the operator can do nothing about.
+            if (error instanceof RollbackError)
+                return fail(error.code, error.message);
+            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);
+            if (error instanceof OrgReaderUnavailableError)
+                return fail("ORG_READER_UNAVAILABLE", error.message);
+            return internalError(error);
+        }
+    });
+}
+async function readJsonFile(file) {
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}