in2-agent-server 0.20260821.185429

package/dist/direct/waveDerivation.js

@@ -0,0 +1,152 @@
+// What `plan_waves` DERIVED, kept where the next call can check itself against it.
+//
+// THE DEFECT THIS EXISTS FOR. `plan_waves` is advisory — deliberately, and that stays true: a
+// supervisor who splits a wave further for a reason the planner cannot see is doing the right
+// thing, and hand-authoring a wave is legitimate. What was missing is that NOTHING NOTICED when the
+// submitted wave bore no relation to any derived one. The planner ran, returned N waves, and the
+// supervisor then passed `direct_apply` a component list of its own; the two were never compared,
+// so a hand-order that was a mistake looked exactly like a hand-order that was a judgement call.
+//
+// LIVE CASE (the Windows run): the supervisor hand-listed every component rather than lifting the
+// planner's waves, and the wave count inflated. Each extra wave costs two deploys — a ~45s checkOnly
+// and the real one — plus two projections. That is the single biggest lever on run time
+// (`direct_apply` is 44.6% of all time spent inside tools) being pushed the wrong way, silently.
+//
+// SO: WARN, NEVER REFUSE. The submitted `waveComponents` are compared against every derived wave and
+// the divergence is NAMED. It cannot block — the planner has no standing to overrule an operator who
+// knows something it does not — but it can make the deviation visible at the moment it costs money,
+// which is the one thing nothing did before.
+//
+// It is also FAIL-OPEN in every direction. No derivation on disk (the supervisor never ran
+// plan_waves, or ran it before this shipped) means no claim: silence, not a warning. An unreadable
+// file is the same. A wave that cannot compare itself to a plan still deploys — this is a note on a
+// deploy, never a gate in front of one.
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { sessionDir, writeJsonAtomic } from "../core/workspace.js";
+/** Where a session's derivation lives. One file per session — the planner's latest answer. */
+export function derivationFile(sessionId) {
+    return path.join(sessionDir(sessionId), "analysis", "wave-derivation.json");
+}
+/**
+ * The comparison key. `path` is part of identity, not decoration: two revisions of one component
+ * are two different things to deploy, and a wave that swapped one for the other has diverged even
+ * though the type and name match.
+ */
+const keyOf = (c) => `${c.typeName}:${c.fullName}${c.path ? `@${c.path}` : ""}`;
+/** Persist the planner's answer. FAIL-OPEN: a session that cannot record it still gets its plan. */
+export async function writeWaveDerivation(sessionId, waves, groundedAgainst) {
+    try {
+        const derivation = {
+            schemaVersion: "wave-derivation-v1",
+            derivedAt: new Date().toISOString(),
+            waves,
+            groundedAgainst
+        };
+        await writeJsonAtomic(derivationFile(sessionId), derivation);
+        return true;
+    }
+    catch {
+        // Bookkeeping never blocks a plan. The consequence is one missing warning later, not a failure.
+        return false;
+    }
+}
+/** Read it back, or null for "no claim to make" — never a throw, never a partial answer. */
+export async function readWaveDerivation(sessionId) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(derivationFile(sessionId), "utf8"));
+        if (parsed?.schemaVersion !== "wave-derivation-v1" || !Array.isArray(parsed.waves))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare one submitted wave against the whole derivation.
+ *
+ * "Corresponds to a derived wave" is deliberately generous: the nearest wave is the one sharing the
+ * most components, and an exact match on that wave's contents is a clean pass. Everything else is
+ * DESCRIBED rather than judged — which components the planner never ordered at all, which it put in
+ * other waves, and which of the nearest wave's own members were left out. That is the information a
+ * supervisor needs to say "yes, I meant that" in one line, or to notice they did not.
+ *
+ * A submission that touches NO derived component at all gets `nearestWave: null` — the honest
+ * answer, and the shape of the live defect: a hand-listed batch that corresponds to nothing.
+ */
+export function compareToDerivation(submitted, derivation) {
+    const want = new Set(submitted.map(keyOf));
+    // Where the planner put each component. Built over the whole derivation, because "you deployed
+    // this early" is only answerable by knowing which OTHER wave it belongs to.
+    const waveOf = new Map();
+    derivation.waves.forEach((wave, i) => {
+        for (const c of wave)
+            if (!waveOf.has(keyOf(c)))
+                waveOf.set(keyOf(c), i);
+    });
+    let nearest = -1;
+    let bestOverlap = 0;
+    derivation.waves.forEach((wave, i) => {
+        const overlap = wave.filter((c) => want.has(keyOf(c))).length;
+        if (overlap > bestOverlap) {
+            bestOverlap = overlap;
+            nearest = i;
+        }
+    });
+    const unplanned = [...want].filter((k) => !waveOf.has(k)).sort();
+    if (nearest < 0) {
+        return {
+            nearestWave: null,
+            unplanned,
+            missingFromWave: [],
+            fromOtherWaves: [...want]
+                .filter((k) => waveOf.has(k))
+                .map((k) => ({ component: k, derivedWave: waveOf.get(k) + 1 }))
+                .sort((a, b) => a.component.localeCompare(b.component)),
+            matches: false
+        };
+    }
+    const nearestKeys = new Set(derivation.waves[nearest].map(keyOf));
+    const missingFromWave = [...nearestKeys].filter((k) => !want.has(k)).sort();
+    const fromOtherWaves = [...want]
+        .filter((k) => !nearestKeys.has(k) && waveOf.has(k))
+        .map((k) => ({ component: k, derivedWave: waveOf.get(k) + 1 }))
+        .sort((a, b) => a.component.localeCompare(b.component));
+    return {
+        nearestWave: nearest + 1,
+        unplanned,
+        missingFromWave,
+        fromOtherWaves,
+        matches: unplanned.length === 0 && missingFromWave.length === 0 && fromOtherWaves.length === 0
+    };
+}
+/**
+ * The warning text, or null when there is nothing to say.
+ *
+ * Written to be actionable in one read: what diverged, what it costs, and the fact that proceeding
+ * is allowed. The last part is not a courtesy — a warning that reads like a refusal gets worked
+ * around, and working around this one means hand-copying files past the ownership checks.
+ */
+export function renderDivergence(report, derivation) {
+    if (report.matches)
+        return null;
+    const lines = [];
+    if (report.nearestWave === null) {
+        lines.push(`WAVE NOT DERIVED — this component list corresponds to NO wave plan_waves derived (it ordered ${derivation.waves.length} wave(s) at ${derivation.derivedAt}).`);
+    }
+    else {
+        lines.push(`WAVE DIVERGES FROM THE DERIVED PLAN — closest is derived wave ${report.nearestWave} of ${derivation.waves.length} (derived ${derivation.derivedAt}), and this submission is not it:`);
+    }
+    if (report.unplanned.length > 0) {
+        lines.push(`  ${report.unplanned.length} component(s) plan_waves ordered into NO wave — check they are in a plan.json and were not left unplaced or refused:`, ...report.unplanned.map((c) => `      ${c}`));
+    }
+    if (report.fromOtherWaves.length > 0) {
+        lines.push(`  ${report.fromOtherWaves.length} component(s) the planner put in a DIFFERENT wave — merging across a dependency edge is the one merge that is never safe:`, ...report.fromOtherWaves.map((f) => `      ${f.component}   (derived wave ${f.derivedWave})`));
+    }
+    if (report.missingFromWave.length > 0) {
+        lines.push(`  ${report.missingFromWave.length} component(s) of derived wave ${report.nearestWave} are NOT in this submission — they will need a wave of their own:`, ...report.missingFromWave.map((c) => `      ${c}`));
+    }
+    lines.push("", "NOT A REFUSAL, and nothing here has been changed: hand-ordering is legitimate and the planner cannot see", "every reason to split. What it can see is the cost — every extra wave is two org round-trips (a ~45s", "checkOnly and the deploy) plus two projections, and a batch listed by hand rather than lifted from", "plan_waves is how a 4-wave plan becomes a 7-wave run. If this split was deliberate, say so when you", "report the wave. If it was not, re-run plan_waves and pass its wave list through unedited.");
+    return lines.join("\n");
+}

package/dist/direct/waveGrade.js

@@ -0,0 +1,185 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+/** `edit|CustomField:PV_Asset__c.PV_Critical__c` — the join key coverage is decided on. */
+function scopeKey(op, typeName, fullName) {
+    return `${op}|${typeName}:${fullName}`;
+}
+const DELIVERED = new Set(["DIFF_VERIFIED", "DELIVERED_WITH_DRIFT"]);
+/**
+ * Read every bundle this session left on disk.
+ *
+ * Deliberately the SAME directory scan both graders used separately, so a report that disagreed
+ * with the terminal event about how many waves delivered is no longer expressible.
+ */
+export function readWaveBundles(directDir) {
+    if (!existsSync(directDir))
+        return [];
+    const bundles = [];
+    for (const entry of readdirSync(directDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const bundle = path.join(directDir, entry.name);
+        const verdictFile = path.join(bundle, "verdict.json");
+        if (!existsSync(verdictFile))
+            continue;
+        let verdict;
+        try {
+            verdict = String(JSON.parse(readFileSync(verdictFile, "utf8")).verdict ?? "UNKNOWN");
+        }
+        catch {
+            // An unreadable bundle is not a verdict; skip rather than mis-grade the batch.
+            continue;
+        }
+        bundles.push({ wave: entry.name, verdict, ...readRequest(bundle) });
+    }
+    return bundles.sort((a, b) => a.wave.localeCompare(b.wave));
+}
+/**
+ * `dryRunOnly` and the touched scope, from the request the caller actually made.
+ *
+ * FAILS CLOSED on an unreadable request: `dryRunOnly: false` means the bundle grades as a real
+ * wave, so a refusal surfaces rather than being written off as practice. The two directions are not
+ * symmetric — a wrong `true` hides a wave that did not deliver, which is the failure the grade
+ * exists to catch, while a wrong `false` costs one over-reported wave a reader can check.
+ */
+function readRequest(bundle) {
+    try {
+        const request = JSON.parse(readFileSync(path.join(bundle, "request.json"), "utf8"));
+        return {
+            dryRunOnly: request.dryRunOnly === true,
+            scope: [
+                ...(request.edits ?? []).map((e) => scopeKey("edit", e.typeName, e.fullName)),
+                ...(request.deletes ?? []).map((d) => scopeKey("delete", d.typeName, d.fullName)),
+                ...(request.facetUpdates ?? []).map((f) => scopeKey("facet", "CustomObject", f.objectApiName))
+            ]
+        };
+    }
+    catch {
+        return { dryRunOnly: false, scope: null };
+    }
+}
+/**
+ * Grade the batch from its bundles. Pure — every input is already on disk and read.
+ *
+ * THE RULE FOR A BLOCKED PRACTICE RUN, which is the only genuinely contestable call here.
+ *
+ * A refused practice check is, in a normal run, exactly what a human should look at before the real
+ * wave — it is the mechanism working. But in PV Arm B it was a DELIBERATE demonstration of the
+ * block, and the two fields the org refused to delete there were deleted for real by `w4` minutes
+ * later. Blessing all rejected dry runs would hide the first case; counting all of them would keep
+ * reporting the second as unfinished business that finished.
+ *
+ * So the batch's own evidence decides: a blocked practice run stops being attention-worthy when a
+ * DELIVERING wave in the same batch performed the SAME OPERATION on EVERY component it named — the
+ * org accepted, and verified, precisely what it had refused in practice.
+ *
+ * Four limits, stated rather than papered over:
+ *   - This is a SCOPE claim, not a causal one. It establishes that the same operation on the same
+ *     components succeeded in this batch; it does not prove the reason for the refusal was
+ *     understood. That is why a covered run is still REPORTED, by name, with its covering waves
+ *     named too — the grade drops the alarm, the report never drops the fact.
+ *   - The scope key is `(operation, typeName:fullName)`, which is COMPONENT identity — and under the
+ *     component revision model one batch may deliver two STATES of one component, in two waves, with
+ *     the same key. So a practice run blocked on an early state of a component is cleared by a later
+ *     state of it delivering, even though the two waves carried different files. That is the widest
+ *     this claim reaches, and it is ACCEPTED rather than fixed: narrowing the key to a revision would
+ *     mean importing the revision model into a module that is deliberately synchronous and
+ *     dependency-free (`finalizeBatch` may run inside a signal handler, where async work does not
+ *     survive), to sharpen an alarm that is already only advisory and already names its own evidence.
+ *     A reader who wants the stronger claim has the covering wave's name and the delivery log.
+ *   - It makes NO temporal claim. "Later" is not derivable here: bundle directories sort by label,
+ *     not by time, and the delivery log carries an `orderingUnreliable` flag precisely because
+ *     position is not evidence of when. Same-batch coverage needs no ordering to be true.
+ *   - Operation kind must MATCH. A practice run refused a delete; an unrelated later edit of the
+ *     same field is not that delete succeeding.
+ */
+export function gradeWaves(bundles) {
+    const delivering = bundles.filter((b) => !b.dryRunOnly && DELIVERED.has(b.verdict));
+    const deliveredScope = new Map();
+    for (const b of delivering) {
+        for (const key of b.scope ?? []) {
+            const waves = deliveredScope.get(key) ?? [];
+            waves.push(b.wave);
+            deliveredScope.set(key, waves);
+        }
+    }
+    const waves = bundles.map((bundle) => {
+        if (!bundle.dryRunOnly) {
+            const delivered = DELIVERED.has(bundle.verdict);
+            return {
+                ...bundle,
+                classification: delivered ? "delivered" : "problem",
+                resolvedBy: null,
+                needsAttention: !delivered
+            };
+        }
+        if (bundle.verdict === "VALIDATED") {
+            return { ...bundle, classification: "practice-accepted", resolvedBy: null, needsAttention: false };
+        }
+        // Every other dry-run verdict is a BLOCK — the org refused it, our lint refused it, or it is a
+        // verdict this vocabulary does not know. The unknown case lands here rather than with the
+        // accepted ones on purpose: a verdict nobody recognises is not evidence that anything passed.
+        const resolvedBy = coveringWaves(bundle.scope, deliveredScope);
+        return {
+            ...bundle,
+            classification: "practice-blocked",
+            resolvedBy,
+            needsAttention: resolvedBy === null
+        };
+    });
+    const deliveredWaves = waves.filter((w) => w.classification === "delivered").length;
+    const problemWaves = waves.filter((w) => w.needsAttention).length;
+    const practiceRuns = waves.length - deliveredWaves - problemWaves;
+    return {
+        result: gradeResult(waves.length, deliveredWaves, problemWaves),
+        waves,
+        deliveredWaves,
+        problemWaves,
+        practiceRuns,
+        reason: gradeReason(waves.length, deliveredWaves, problemWaves, practiceRuns)
+    };
+}
+/** The waves that covered every component this bundle named, or null when any went uncovered. */
+function coveringWaves(scope, deliveredScope) {
+    // A scope that could not be read establishes nothing, and an EMPTY scope is vacuously covered —
+    // both would silently clear a block. Neither is allowed to.
+    if (!scope || scope.length === 0)
+        return null;
+    const covering = new Set();
+    for (const key of scope) {
+        const waves = deliveredScope.get(key);
+        if (!waves)
+            return null;
+        for (const wave of waves)
+            covering.add(wave);
+    }
+    return [...covering].sort();
+}
+/**
+ * COMPLETE / NEEDS_ATTENTION / FAILED / NO_WAVES.
+ *
+ * `NO_WAVES` covers two runs that look different and mean the same thing: one that never deployed,
+ * and one whose only bundles were accepted practice runs. Neither changed the org, so neither has a
+ * DELIVERY result to state, and `COMPLETE` on a run that delivered nothing would call a batch
+ * finished that never started. `finalizeBatch` sends no terminal event in that case, exactly as it
+ * has always done for a read-only run.
+ */
+function gradeResult(total, delivered, problems) {
+    if (total === 0)
+        return "NO_WAVES";
+    if (problems === 0)
+        return delivered === 0 ? "NO_WAVES" : "COMPLETE";
+    return delivered === 0 ? "FAILED" : "NEEDS_ATTENTION";
+}
+/** The counted status line — never a narrative, never an org's error text, bounded well under 200. */
+function gradeReason(total, delivered, problems, practice) {
+    const practiceNote = practice > 0 ? `; ${practice} practice run(s), none needing review` : "";
+    if (total === 0)
+        return "no wave verdicts on disk";
+    if (problems === 0) {
+        return delivered === 0
+            ? `no wave delivered — ${practice} practice run(s) only, all accepted`
+            : `all ${delivered} wave(s) delivered${practiceNote}`;
+    }
+    return `${problems} of ${total} wave(s) need review${practiceNote}`;
+}

package/dist/index.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { log } from "./core/result.js";
+import { Telemetry } from "./core/telemetry.js";
+import { supervisorInstructions } from "./core/supervisorContract.js";
+import { betaEnabled } from "./core/betaFeedback.js";
+import { REPO_ROOT, WORKSPACE_ROOT } from "./core/paths.js";
+import { campfireAllowlistedOrgIds, campfireWriteEnabled, directAllowlistOpen, directWriteEnabled } from "./core/gate.js";
+import { activeGrants } from "./core/writeGrants.js";
+import { registerSessionTools } from "./tools/session.js";
+import { registerActivationTools, registerAuthTools } from "./tools/auth.js";
+import { registerOperatorTools } from "./tools/operator.js";
+import { registerCampfireTools } from "./tools/campfire.js";
+import { registerOrgTools } from "./tools/org.js";
+import { registerProjectionTools } from "./tools/projection.js";
+import { registerDirectTools } from "./tools/direct.js";
+import { registerUpdateTools } from "./tools/update.js";
+import { registerAnalyzeTools } from "./tools/analyze.js";
+import { registerWaveTools } from "./tools/waves.js";
+import { registerPhaseTools } from "./tools/phase.js";
+import { registerCloseBatchTools } from "./tools/closeBatch.js";
+import { registerFeedbackTools } from "./tools/feedback.js";
+import { instrumentRegistration, registeredToolNames } from "./core/registration.js";
+import { installClaudeAssets } from "./core/claudeAssets.js";
+import { installedVersion, isNpmInstall } from "./core/install.js";
+const server = new McpServer({ name: "cc-mcp-server", version: "0.1.0" }, 
+// Shipped to the model on connect regardless of cwd — the only channel that does not depend on
+// the operator opening a particular directory or describing the workflow themselves. Carries the
+// beta feedback section only when CC_MCP_BETA is on; an install that is not in beta ships a
+// contract with no trace of the channel.
+{ instructions: supervisorInstructions() });
+// Telemetry wraps registerTool ONCE, before any registration, so every tool — present and
+// future — is timed without each module having to remember. Never throws; CC_MCP_TELEMETRY=0
+// disables it.
+const telemetry = new Telemetry();
+instrumentRegistration(server, telemetry);
+// Default surface = the direct working tier and everything it needs. Fixed for the life of the
+// process — the tool surface no longer swaps live (the hot-swap updater is gone with the move to
+// npm distribution; an update lands for the NEXT conversation).
+registerSessionTools(server);
+registerAuthTools(server);
+registerActivationTools(server);
+registerOperatorTools(server);
+registerCampfireTools(server);
+registerOrgTools(server);
+registerProjectionTools(server);
+registerDirectTools(server);
+registerUpdateTools(server);
+registerAnalyzeTools(server);
+registerWaveTools(server);
+registerPhaseTools(server);
+registerCloseBatchTools(server);
+// Registers nothing unless CC_MCP_BETA is on — the flag lives inside the registrar.
+registerFeedbackTools(server);
+// Keep ~/.claude/skills and ~/.claude/agents in step with THIS build. Best-effort by contract and
+// awaited before the transport connects, so a session never races its own instructions.
+await installClaudeAssets();
+log(`repo root: ${REPO_ROOT}`);
+log(`workspace root: ${WORKSPACE_ROOT}`);
+log(`telemetry: ${process.env.CC_MCP_TELEMETRY === "0" ? "disabled (CC_MCP_TELEMETRY=0)" : `run ${telemetry.runId}`}`);
+// Which orgs this install can actually write to is the highest-consequence fact about it, so it is
+// stated plainly at every start rather than left to be inferred from env vars.
+const grants = await activeGrants().catch(() => []);
+log(`direct write: ${directWriteEnabled()
+    ? directAllowlistOpen()
+        ? "ENABLED, allowlist WIDE OPEN (CC_MCP_DIRECT_ALLOWLIST=*) — every authenticated org is writable; consultant org still refused. INTERNAL DEV ONLY, must not ship."
+        : "ENABLED, authority from activation grants + per-org allowlist"
+    : "closed (default)"}`);
+log(grants.length > 0
+    ? `activation grants: ${grants.map((g) => `${g.orgId} (${g.alias}, expires ${g.expiresAt.slice(0, 10)})`).join("; ")}`
+    : "activation grants: none — no org is writable by grant until a Campfire code is redeemed with activate_session");
+// Stated at start for the same reason as direct write, and for one more: this gate is checked at
+// the END of a run. A closed Campfire gate costs nothing until writeback, and by then the session
+// has spent half an hour and the fix (different server env) needs a restart the operator cannot
+// perform. Saying it here turns a late, expensive refusal into something the supervisor can card
+// on turn one — while re-registering is still cheap.
+log(`campfire write: ${campfireWriteEnabled()
+    ? `ENABLED for allowlisted consultant org(s) [${campfireAllowlistedOrgIds().join(", ")}]`
+    : "CLOSED (default) — writeback will refuse CAMPFIRE_WRITE_NOT_AUTHORIZED at the END of the run. Set CC_MCP_CAMPFIRE_WRITE=1 and restart if this session is expected to write Configuration Items back."}`);
+log(`version: ${installedVersion()}${isNpmInstall() ? " (npm — update_server / in2 update install the next version)" : " (checkout — updates come from git, not npm)"}`);
+// Beta mode changes the tool surface AND the operating contract, so it is stated at every start for
+// the same reason direct write is: a machine in beta must never be mistakable for one that is not.
+// The announcement itself (what leaves, and how to stop it) is announceBeta's, called from Telemetry
+// beside the other content-channel lines; this is the one-word status beside the other capabilities.
+log(`beta: ${betaEnabled() ? "ON (CC_MCP_BETA) — report_feedback and record_operator_feedback are registered" : "off (default)"}`);
+log(`tool surface: direct tier only (${registeredToolNames().length} tools)`);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+log("cc-mcp-server ready (stdio)");

package/dist/orgread/customFieldSnapshot.js

@@ -0,0 +1,48 @@
+// Dedicated CustomField snapshot. Ported from sf-config-verifier
+// (src/snapshots/customFieldSnapshot.ts).
+//
+// Carries EVERY facet the Metadata API returned, coercing the typed ones at the READ boundary so a
+// comparison never has to care that the API hands back XML leaves as strings.
+//
+// It used to carry a ~16-facet allowlist instead, and that was a defect, not a design. Any facet an
+// author stated that fell outside the list — <unique>, <externalId>, <caseSensitive>, and 40-odd
+// others the schema knows — was dropped by THIS reader before the comparison ever ran, so the
+// intent check reported it as intended-but-absent: false drift on a field the org had stored
+// exactly as asked. Worse, the evidence could not distinguish the two explanations, because a facet
+// our reader discarded and a facet the org omitted look identical downstream. A snapshot that
+// silently narrows what it observed cannot be the substrate for a drift verdict.
+//
+// The shared normalizer does the coercion (fieldMetadata.normalizeCustomFieldMetadata — the same
+// one the generic CustomField path and the intent side already use, so all three compare
+// like-with-like); this reader adds only what is specific to reading ONE named field.
+import { normalizeCustomFieldMetadata, valueSetDefaultValue } from "./fieldMetadata.js";
+import { snapshot } from "./snapshotTypes.js";
+export async function readCustomFieldSnapshot(org, fullName) {
+    // Upstream destructured `[result]` and dereferenced it directly, which throws if the reader hands
+    // back an empty array. cc-mcp compiles with noUncheckedIndexedAccess and surfaced it; an empty
+    // response is treated as not-found, which is what the caller can actually act on.
+    const rows = await org.metadataRead("CustomField", [fullName]);
+    const result = rows[0] ?? { typeName: "CustomField", fullName, found: false, errors: ["metadataRead returned no rows"] };
+    const normalized = result.found ? normalizeCustomFieldMetadata(result.metadata) : null;
+    let metadata = null;
+    if (normalized) {
+        // The wire carries the UNQUALIFIED field name (`CF63_Notes__c`); this reader answers for the
+        // name it was asked about (`CF63_Intake__c.CF63_Notes__c`), which is the key every caller holds.
+        metadata = { ...normalized, fullName };
+        const defaultValue = asDefaultValue(normalized.defaultValue) ?? valueSetDefaultValue(normalized.valueSet);
+        if (defaultValue !== undefined)
+            metadata.defaultValue = defaultValue;
+    }
+    const state = { metadata };
+    return snapshot("customField", "CustomField", fullName, "metadata.read", state, result.errors);
+}
+// EXT-2040: the CustomField <defaultValue> element is a formula-syntax STRING (e.g. "false" for a
+// checkbox default-unchecked, `"West"` for a text literal, TODAY() for a date). Some XML parsers
+// coerce a bare `<defaultValue>false</defaultValue>` to a boolean and `<defaultValue>5</defaultValue>`
+// to a number (the same coercion class) — normalize both back to the string form so a comparison on
+// the stated literal matches byte-for-byte. A Picklist carries NO top-level <defaultValue>; its
+// default is derived from the valueSet per-value <default> flag (valueSetDefaultValue, at the call
+// site above).
+function asDefaultValue(v) {
+    return typeof v === "string" ? v : typeof v === "boolean" || typeof v === "number" ? String(v) : undefined;
+}

package/dist/orgread/fieldMetadata.js

@@ -0,0 +1,178 @@
+/**
+ * CustomField metadata normalization — the record of how Salesforce's Metadata API ACTUALLY
+ * serializes a field, as opposed to what you asked it to store.
+ *
+ * Ported verbatim from sf-config-verifier (src/snapshots/customFieldMetadata.ts). Every rule below
+ * was caught against a live org, usually as a family that scored zero after a byte-perfect deploy.
+ * The EXT ids are load-bearing: they are the only record of why each line exists, so keep them with
+ * the code they explain.
+ *
+ * This is not cosmetic. direct/applyLoop.ts compares pre- and post-deploy reads through these
+ * functions, so a missing rule here does not produce a slightly-off report — it produces a false
+ * failure on correct work, or a false green on incorrect work.
+ *
+ * Applied by BOTH the dedicated customField snapshot and the generic-metadata path
+ * (picklistDependency / formula / rollupSummary / lookupRelationship / masterDetailRelationship all
+ * resolve to a CustomField). Keeping it in one place fixes F11: a picklist value set was normalized
+ * only on the dedicated path, so an EXT-531-style `picklistDependency` family (which routes through
+ * the generic verifier) saw a raw `<valueSet>` and failed `$.metadata.valueSet.values` — a
+ * false-fail.
+ */
+/**
+ * Normalize a parsed `<valueSet>` so callers can read a flat `valueSet.values: string[]` (the
+ * inline picklist value API names, in document order) instead of navigating
+ * `valueSetDefinition.value[].fullName` — which is also brittle because a single <value> parses to
+ * an object, not an array. The raw structure is preserved; `values`, normalized `restricted`, and a
+ * global-value-set `valueSetName` are added on top. Returns the input unchanged for non-picklist
+ * (non-object) values.
+ */
+export function normalizeValueSet(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const vs = raw;
+    const out = { ...vs };
+    if (typeof vs.valueSetName === "string")
+        out.valueSetName = vs.valueSetName;
+    if (vs.restricted !== undefined)
+        out.restricted = vs.restricted === true || vs.restricted === "true";
+    const def = vs.valueSetDefinition;
+    const rawValues = def?.value;
+    const valueList = rawValues === undefined ? [] : Array.isArray(rawValues) ? rawValues : [rawValues];
+    const values = valueList
+        .map((v) => (v && typeof v === "object" ? v.fullName : v))
+        .filter((v) => typeof v === "string");
+    if (values.length > 0)
+        out.values = values;
+    // D5 (registry v11, live-caught EXT-15346): canonicalize the dependent-picklist valid-for matrix
+    // so a valueSettings comparison (sorted [{value, controllingFieldValues[]}]) can hold under a
+    // strict deep equality. Wire shape per entry: {valueName, controllingFieldValue: string|string[]}
+    // with the usual single-element object/array collapse. Entries without a valueName are dropped
+    // (never guessed).
+    const rawSettings = vs.valueSettings;
+    if (rawSettings !== undefined) {
+        const settingsList = Array.isArray(rawSettings) ? rawSettings : [rawSettings];
+        const canonical = settingsList
+            .flatMap((entry) => {
+            if (!entry || typeof entry !== "object")
+                return [];
+            const record = entry;
+            if (typeof record.valueName !== "string")
+                return [];
+            const rawControlling = record.controllingFieldValue;
+            const controllingFieldValues = (rawControlling === undefined ? [] : Array.isArray(rawControlling) ? rawControlling : [rawControlling])
+                .filter((c) => typeof c === "string")
+                .sort();
+            return [{ value: record.valueName, controllingFieldValues }];
+        })
+            .sort((a, b) => a.value.localeCompare(b.value));
+        if (canonical.length > 0)
+            out.valueSettings = canonical;
+    }
+    return out;
+}
+/**
+ * EXT-2040 (the Picklist wire shape): a Picklist default is NOT a top-level CustomField
+ * `<defaultValue>` on the wire — the Metadata API carries it as the per-value `<default>` flag
+ * inside `valueSet.valueSetDefinition.value[]` (exactly where the sf-cli-wrapper deploys it).
+ * Return the default-flagged value's API name (fullName) so the snapshot can project it to
+ * `$.metadata.defaultValue`; undefined when no value is flagged (a global value set, or simply no
+ * default — never fabricated). Handles the single-`<value>` object collapse and the parser handing
+ * the flag back as the string 'true' or a real boolean.
+ */
+export function valueSetDefaultValue(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const def = raw.valueSetDefinition;
+    const rawValues = def?.value;
+    const valueList = rawValues === undefined ? [] : Array.isArray(rawValues) ? rawValues : [rawValues];
+    for (const v of valueList) {
+        if (!v || typeof v !== "object")
+            continue;
+        const entry = v;
+        if ((entry.default === true || entry.default === "true") && typeof entry.fullName === "string")
+            return entry.fullName;
+    }
+    return undefined;
+}
+/**
+ * Named numeric CustomField facets. XML leaves parse as STRINGS ("0"); the dedicated customField
+ * snapshot coerced these through a private asNumber of its own, but the generic-metadata path
+ * (formula / rollupSummary / picklistDependency / lookupRelationship / masterDetailRelationship)
+ * did not — so an equality check on `$.metadata.scale` compared 0 against "0" and false-failed
+ * (live-caught EXT-15347, a Number formula field with scale 0 scoring the family to 0 after a
+ * byte-perfect deploy). Both paths now share THIS, which is what keeps them from drifting apart
+ * again. Coerce at the read boundary, named keys only — never blanket-coerce (the
+ * customObjectSnapshot rule).
+ *
+ * This is EVERY member `@salesforce/types` declares as a number on CustomField (queried against
+ * src/direct/metadataSchema.generated.json), not the subset some family happened to hit. The old
+ * five-key list was that subset, and a snapshot is only as trustworthy as its narrowest coercion.
+ */
+const NUMERIC_FACET_KEYS = [
+    "length",
+    "precision",
+    "relationshipOrder",
+    "scale",
+    "startingNumber",
+    "visibleLines"
+];
+/**
+ * Named boolean CustomField facets — same read-boundary rule as the numerics, same provenance
+ * (every member the schema artifact declares `boolean` on CustomField).
+ *
+ * `required` was the only one of these ever coerced, because it was the only one the dedicated
+ * snapshot bothered to project. Widening the snapshot to carry every facet the org returns makes
+ * the rest reachable, and an uncoerced `unique: "true"` would land in the comparison substrate as a
+ * STRING — the exact class of defect EXT-966 and EXT-15347 exist for.
+ *
+ * `defaultValue` is deliberately NOT here: it is an xsd:string carrying formula syntax, so a
+ * checkbox default is legitimately the STRING "false" (see asDefaultValue in customFieldSnapshot).
+ * Coercing it would undo EXT-2040 rather than help it.
+ */
+const BOOLEAN_FACET_KEYS = [
+    "caseSensitive",
+    "deprecated",
+    "escapeMarkup",
+    "externalId",
+    "isAIPredictionField",
+    "isConvertLeadDisabled",
+    "isFilteringDisabled",
+    "isNameField",
+    "isSortingDisabled",
+    "populateExistingRows",
+    "reparentableMasterDetail",
+    "required",
+    "restrictedAdminField",
+    "stripMarkup",
+    "trackFeedHistory",
+    "trackHistory",
+    "trackTrending",
+    "translateData",
+    "unique",
+    "writeRequiresMasterRead"
+];
+/** Apply CustomField-level normalization (valueSet flattening + typed facet coercion) to a raw metadata object. */
+export function normalizeCustomFieldMetadata(md) {
+    if (!md || typeof md !== "object")
+        return md ?? null;
+    const out = { ...md };
+    if (md.valueSet !== undefined)
+        out.valueSet = normalizeValueSet(md.valueSet);
+    for (const key of NUMERIC_FACET_KEYS) {
+        const v = out[key];
+        if (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v)))
+            out[key] = Number(v);
+    }
+    for (const key of BOOLEAN_FACET_KEYS) {
+        if (out[key] === "true")
+            out[key] = true;
+        else if (out[key] === "false")
+            out[key] = false;
+    }
+    // LongTextArea omits <required> from the wire entirely — the platform forbids required long text
+    // areas — so the guaranteed value is projected instead of undefined (live-caught EXT-15345: the
+    // customField family false-failed `required == false` against an absent leaf).
+    if (out.required === undefined && out.type === "LongTextArea")
+        out.required = false;
+    return out;
+}