in2-agent-server 0.20260821.185429

package/dist/tools/campfire.js

@@ -0,0 +1,1742 @@
+import os from "node:os";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, promises as fs } from "node:fs";
+import { z } from "zod";
+import { isoNow } from "../core/ids.js";
+import { decodeHtmlEntities, escapeRichText, richTextFragment } from "../core/richText.js";
+import { emitDomainTelemetryEvent } from "../core/telemetryContext.js";
+import { fail, internalError, ok, stdoutTail } from "../core/result.js";
+import { WorkspaceError } from "../core/workspace.js";
+import { SessionOrgError, resolveSessionOrg } from "../core/sessionOrg.js";
+import { loadSession } from "./session.js";
+import { sessionFile, sessionDir as sessionWorkspaceDir } from "../core/workspace.js";
+import { GateError, assertCampfireWriteAllowed, assertTargetOrg } from "../core/gate.js";
+import { runProcess, sfCliEnv } from "../core/spawn.js";
+import { sfQueryTruncation } from "../core/sfQuery.js";
+import { appendReadRecord } from "../core/readsLog.js";
+import { writeWritebackManifest, writebackManifestRows } from "../core/writebackManifest.js";
+import { corpusToolsEnabled } from "../core/betaFeedback.js";
+import { DELIVERY_TRUTH_REMEDY, UnknownWaveError, configItemsForSession, heldForDeliveryTruth, ownershipRefusal } from "../campfire/deriveFromBundle.js";
+import { describeConfigItem } from "../campfire/configItemDescription.js";
+// Campfire (VF-partial) read/write tools. The consultant org is REAL and SHARED —
+// every write here: (1) rides the dedicated CC_MCP_CAMPFIRE_WRITE gate + org-id
+// allowlist, (2) touches only allowlisted fields/objects, (3) is idempotent where
+// a record is created (External_ID__c query-then-update), and (4) is read back
+// after writing so the result reports org truth, not request intent.
+const API = "v61.0";
+const CAMPFIRE_NAME_RE = /^(REQ|EXT)-\d{1,10}$/;
+// Concurrent Configuration Item writes. Modest on purpose: each one launches an sf CLI process and
+// Salesforce applies per-org concurrency limits, so this is about not paying full latency 25 times
+// over rather than about saturating anything.
+const WRITE_CONCURRENCY = 5;
+const SF_ID_RE = /^[a-zA-Z0-9]{15,18}$/;
+const EXTERNAL_ID_RE = /^[A-Za-z0-9_-]{1,18}$/;
+function soqlEscape(value) {
+    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+async function query(consultantOrg, soql) {
+    const args = ["data", "query", "-q", soql, "--target-org", consultantOrg, "--json"];
+    let run = await runProcess("sf", args, { env: sfCliEnv(), timeoutMs: 90_000 });
+    if (run.timedOut) {
+        // Read-only — one retry on a stalled CLI child is safe (live-caught intermittent hang).
+        run = await runProcess("sf", args, { env: sfCliEnv(), timeoutMs: 90_000 });
+    }
+    if (run.exitCode !== 0) {
+        const detail = run.timedOut ? "killed at timeout" : `exit ${run.exitCode}`;
+        throw new Error(`Campfire SOQL failed (${detail}): ${stdoutTail(run.stdout || run.stderr, 6)}`);
+    }
+    const parsed = JSON.parse(run.stdout);
+    const truncation = sfQueryTruncation(parsed);
+    if (truncation) {
+        // Thrown, not returned short: every caller treats the record list as the whole answer (missing-
+        // name checks, read-backs), and a capped list would let absence of data read as absence of rows.
+        throw new Error(`Campfire SOQL truncated: ${truncation}`);
+    }
+    return parsed.result?.records ?? [];
+}
+// Salesforce marks every OTHER row in a rolled-back batch with this. It is a consequence, never the
+// cause — surfacing it alongside the real error would bury the one line that says what to fix.
+const ROLLBACK_CODE = "ALL_OR_NONE_OPERATION_ROLLED_BACK";
+/**
+ * POST/PATCH a Composite sObject Collections request and REFUSE unless every record succeeded.
+ *
+ * `label(i)` names row i the way the operator does (REQ-15356), so the error points at a
+ * requirement rather than an array index.
+ */
+export function collectionFailure(raw, method, label) {
+    if (!Array.isArray(raw)) {
+        // A collections call ALWAYS answers with an array. Anything else means the shape changed under
+        // us, and silently assuming success is how this failed the first time.
+        return `Campfire batch ${method} returned an unexpected response shape (expected a per-record array, got ${JSON.stringify(raw).slice(0, 200)}). Nothing is confirmed — READ the records before retrying.`;
+    }
+    const failures = raw
+        .map((row, i) => ({ row, i }))
+        .filter(({ row }) => row.success !== true)
+        .map(({ row, i }) => ({
+        label: label(i),
+        errors: (row.errors ?? []).filter((e) => e.statusCode !== ROLLBACK_CODE)
+    }));
+    if (failures.length === 0)
+        return null;
+    // Lead with rows carrying a REAL error. Every other row in a rolled-back batch is stamped
+    // ALL_OR_NONE_OPERATION_ROLLED_BACK, and in the CF63 case that was 14 of 15 — listing those
+    // first would bury the single line that says what to fix.
+    const real = failures.filter((f) => f.errors.length > 0);
+    const shown = real.length > 0 ? real : failures;
+    const detail = shown
+        .slice(0, 6)
+        .map((f) => `${f.label}: ${f.errors.map((e) => `${e.statusCode ?? "ERROR"}${e.fields?.length ? ` on ${e.fields.join(", ")}` : ""} — ${e.message ?? ""}`).join("; ") ||
+        "rolled back because another row in this batch was invalid"}`)
+        .join("\n  ");
+    return (`Campfire batch ${method} wrote NOTHING — allOrNone rolled the whole batch back because ${shown.length} row(s) were rejected:\n  ${detail}` +
+        `${shown.length > 6 ? `\n  …and ${shown.length - 6} more` : ""}` +
+        `\nNo append was applied, so fixing the named value(s) and re-running this call is safe and will NOT duplicate anything.`);
+}
+async function restCollections(consultantOrg, method, records, label, 
+// Defaults to the plain collections endpoint. Pass the UPSERT form
+// (/composite/sobjects/<Object>/<ExternalIdField>) to make idempotency the org's job instead of
+// a read-then-write race — the response shape is identical either way.
+endpoint = `/services/data/${API}/composite/sobjects`) {
+    const raw = await restWrite(consultantOrg, method, endpoint, {
+        allOrNone: true,
+        records
+    });
+    const failure = collectionFailure(raw, method, label);
+    if (failure)
+        throw new Error(failure);
+}
+async function restWrite(consultantOrg, method, endpoint, body) {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "cc-mcp-cf-"));
+    const bodyFile = path.join(dir, "body.json");
+    try {
+        await fs.writeFile(bodyFile, JSON.stringify(body), "utf8");
+        const run = await runProcess("sf", ["api", "request", "rest", endpoint, "-X", method, "--body", `@${bodyFile}`, "--target-org", consultantOrg], { env: sfCliEnv(), timeoutMs: 90_000 });
+        const out = run.stdout.trim();
+        if (run.timedOut) {
+            // Live-caught: a PATCH child killed at timeout had already sent its request —
+            // the org processed the write ~30s AFTER the kill. Timeout on a write is
+            // AMBIGUOUS, never a confirmed failure.
+            throw new Error(`Campfire ${method} ${endpoint} killed at timeout — AMBIGUOUS: the write may still have landed. READ the record before any retry; an append-mode retry against a landed write duplicates the note block.`);
+        }
+        // Salesforce REST errors arrive as a JSON array with errorCode even on exit 0.
+        // The REST error body is on stdout — surface it first, never let CLI warnings mask it.
+        if (run.exitCode !== 0 || /"errorCode"/.test(out)) {
+            throw new Error(`Campfire ${method} ${endpoint} failed: ${stdoutTail(out || run.stderr, 8)}`);
+        }
+        if (!out)
+            return null; // PATCH returns 204 empty
+        try {
+            return JSON.parse(out);
+        }
+        catch {
+            return null;
+        }
+    }
+    finally {
+        await fs.rm(dir, { recursive: true, force: true });
+    }
+}
+async function resolveRequirement(consultantOrg, requirement) {
+    const trimmed = requirement.trim();
+    if (SF_ID_RE.test(trimmed) && !CAMPFIRE_NAME_RE.test(trimmed)) {
+        const rows = await query(consultantOrg, `SELECT Id, Name FROM Campfire_Requirement__c WHERE Id = '${soqlEscape(trimmed)}'`);
+        const row = rows.length === 1 ? rows[0] : undefined;
+        return row ? { id: String(row.Id), name: String(row.Name) } : null;
+    }
+    if (!CAMPFIRE_NAME_RE.test(trimmed))
+        return null;
+    const name = trimmed.replace(/^EXT-/, "REQ-");
+    const rows = await query(consultantOrg, `SELECT Id, Name FROM Campfire_Requirement__c WHERE Name = '${name}'`);
+    const row = rows.length === 1 ? rows[0] : undefined;
+    return row ? { id: String(row.Id), name: String(row.Name) } : null;
+}
+/**
+ * Bucket requirement references by the COLUMN each must be looked up on, keeping every caller
+ * spelling that points at one record.
+ *
+ * Both maps key to a LIST of references, because two different strings can name one record: EXT-####
+ * and REQ-#### are the same requirement, and so are the 15- and 18-character forms of one Id. A
+ * one-to-one map silently dropped whichever arrived first, so a batch naming a record two ways got
+ * one of them back and reported the other unresolved — a refusal on the write path.
+ *
+ * Ids key on the 15-character prefix because SOQL always ANSWERS with the 18-character form: a
+ * caller who passed the short form could never match its own row, which the single-reference
+ * resolver (a direct `WHERE Id =` comparison) accepted without complaint.
+ *
+ * Pure, so the reference algebra is testable without an org.
+ */
+export function groupRequirementRefs(requirements) {
+    const byId = new Map(); // 15-char sf id -> original reference(s)
+    const byName = new Map(); // REQ-name -> original reference(s)
+    const unusable = [];
+    const add = (map, key, reference) => {
+        const list = map.get(key);
+        if (list)
+            list.push(reference);
+        else
+            map.set(key, [reference]);
+    };
+    for (const reference of requirements) {
+        const trimmed = reference.trim();
+        if (SF_ID_RE.test(trimmed) && !CAMPFIRE_NAME_RE.test(trimmed))
+            add(byId, trimmed.slice(0, 15), reference);
+        else if (CAMPFIRE_NAME_RE.test(trimmed))
+            add(byName, trimmed.replace(/^EXT-/, "REQ-"), reference);
+        else
+            unusable.push(reference);
+    }
+    return { byId, byName, unusable };
+}
+/**
+ * Resolve MANY requirement references in at most two queries, instead of two per reference.
+ *
+ * The single-reference resolver costs one round trip per requirement, and the supervisor reads
+ * EVERY requirement before it plans anything — so a twelve-requirement batch opened with twenty-four
+ * sequential SOQL calls before any work began. `probe` is the largest stage in the ledger (9.5
+ * minutes across 40 calls on the live batch), and this is a large part of why.
+ *
+ * Ids and Names are separated because they are different columns; both branches are one IN() query.
+ * Ambiguity is preserved rather than flattened: a reference matching zero or several rows is
+ * reported unresolved, exactly as the single resolver refuses anything that is not exactly one.
+ */
+async function resolveRequirements(consultantOrg, requirements) {
+    const resolved = new Map();
+    const { byId, byName, unusable } = groupRequirementRefs(requirements);
+    const unresolved = [...unusable];
+    const inList = (values) => [...values].map((value) => `'${soqlEscape(value)}'`).join(", ");
+    // Count matches per reference so "two rows share this Name" stays a refusal rather than a
+    // silent pick — the single-reference path requires exactly one and this must not be laxer.
+    const hits = new Map();
+    const collect = (rows, keys) => {
+        for (const row of rows) {
+            for (const reference of keys(row)) {
+                const list = hits.get(reference) ?? [];
+                list.push({ id: String(row.Id), name: String(row.Name) });
+                hits.set(reference, list);
+            }
+        }
+    };
+    if (byId.size > 0) {
+        const rows = await query(consultantOrg, `SELECT Id, Name FROM Campfire_Requirement__c WHERE Id IN (${inList(byId.keys())})`);
+        collect(rows, (row) => byId.get(String(row.Id).slice(0, 15)) ?? []);
+    }
+    if (byName.size > 0) {
+        const rows = await query(consultantOrg, `SELECT Id, Name FROM Campfire_Requirement__c WHERE Name IN (${inList(byName.keys())})`);
+        collect(rows, (row) => byName.get(String(row.Name)) ?? []);
+    }
+    for (const reference of [...byId.values(), ...byName.values()].flat()) {
+        const found = hits.get(reference) ?? [];
+        if (found.length === 1)
+            resolved.set(reference, found[0]);
+        else
+            unresolved.push(reference);
+    }
+    return { resolved, unresolved };
+}
+// Everything read_campfire_requirements returns.
+//
+// This list omitted Solution_Design_Summary__c until 2026-07-31 — the field that carries the ACTUAL
+// specification on every corpus we run (CF-series, SM3, EV). Reading a requirement therefore showed
+// its user story and acceptance criteria with every solution field null, and the design summary —
+// the component list, the API names, the exact error strings — simply absent. A supervisor
+// grounding itself with this tool would have seen an empty requirement and had nothing to say so.
+//
+// Same class as the hollow mirror: a field list that omits the field carrying the content. The test
+// below now ties this list to MIRROR_COPIED_FIELDS so the three lists (import, mirror, read) cannot
+// drift apart again — the next field added to one is a failing test until it is added to all.
+export const READ_FIELDS = [
+    "Id", "Name", "Requirement_Name__c", "Requirement_Stage__c", "Build_Status__c",
+    "Blocked_Reason__c", "Org_Deployed_To__c", "Deployment_Notes__c", "PM_Notes__c",
+    "Requirement_Details__c", "User_Story__c", "User_Story_Action__c", "User_Story_Such_That__c",
+    // Derived and refused on INSERT (hence its exemption from MIRROR_COPIED_FIELDS), but perfectly
+    // readable — and the import pulls it. Omitting it here meant re-reading a requirement returned
+    // LESS than importing it did, which is its own quiet inconsistency. Caught by the invariant test
+    // below the moment it was written.
+    "User_Story_Description__c",
+    "Acceptance_Criteria_Given__c", "Acceptance_Criteria_When__c", "Acceptance_Criteria_Then__c",
+    "Expected_Results__c", "Solution_Design_Summary__c", "Solution_Details__c", "Pre_Requisite__c",
+    "Number_of_Configuration_Items__c", "Number_of_Deployment_Tasks__c", "LastModifiedDate"
+];
+// Writable requirement fields — a deliberate ALLOWLIST, never arbitrary fields on the
+// shared org. Notes fields default to APPEND (timestamped block) so nothing human-written
+// is ever clobbered; replace must be asked for explicitly.
+// Legal picklist values, carried HERE rather than discovered per run.
+//
+// The tool used to say which fields you may set and never which values are legal, so a run had to
+// find out for itself: PicklistValueInfo is not queryable through this passthrough (INVALID_TYPE),
+// so the supervisor fell back to GROUP BY over live records to infer the vocabulary of a field it
+// was about to write on the REAL SHARED org — several round-trips to learn something fixed.
+//
+// Validation matters MORE for the open picklists than the restricted ones, which is the opposite of
+// the intuition. A RESTRICTED picklist is defended by the org: a wrong value is rejected loudly.
+// An OPEN one accepts anything, so a plausible-but-wrong Build_Status__c ("Deployed", "Done") lands
+// silently and corrupts a field consultants read. Both are checked here so the error arrives before
+// the write, naming the legal set.
+//
+// Verified live against the Campfire org 2026-07-28. If Campfire adds a value this list will refuse
+// it wrongly — the refusal says so and names the read that shows the current set, so the fix is one
+// call rather than an investigation.
+// EVERY content field a requirement can carry, not just the ones the CF-series corpus happened
+// to use. mirror_requirements' original copy list carried Solution_Design_Summary__c alone, and
+// the Pinsley-style records keep their entire design in Solution_Details__c — so the mirror
+// silently produced HOLLOW copies (user story only, null solution design), and a whole test run
+// executed against ~5% of its spec before anyone noticed (live-caught 2026-07-29, NewPinsleyTest
+// set). Rule: if the import composes from a field (see session.ts CAMPFIRE_IMPORT_FIELDS), the
+// mirror must copy it. The test suite holds this list against that rule.
+export const MIRROR_COPIED_FIELDS = [
+    "Requirement_Name__c",
+    "User_Story__c",
+    "User_Story_Action__c",
+    "User_Story_Such_That__c",
+    // NOT User_Story_Description__c: readable (the import queries it) but the org REFUSES it on
+    // insert (INVALID_FIELD_FOR_INSERT_UPDATE, live-caught on the NewPinsleyTest2 re-mint) — it is
+    // derived from the three user-story parts above, which ARE copied, so the clone recomputes it.
+    "Acceptance_Criteria_Given__c",
+    "Acceptance_Criteria_When__c",
+    "Acceptance_Criteria_Then__c",
+    "Expected_Results__c",
+    "Solution_Design_Summary__c",
+    "Requirement_Details__c",
+    "Solution_Details__c",
+    "Pre_Requisite__c"
+];
+const PICKLISTS = {
+    Build_Status__c: {
+        restricted: false,
+        values: ["Not Started", "In Progress", "In Progress - At Risk", "Build Complete", "Blocked", "Complete", "Withdrawn"]
+    },
+    Org_Deployed_To__c: {
+        restricted: true,
+        multi: true,
+        values: ["Development", "Partial Sandbox", "Full Sandbox", "Production"]
+    }
+};
+// Campfire_Deployment_Task__c's three RESTRICTED picklists, verified live 2026-07-28. Declared as
+// enums rather than prose: the value set then rides in the tool SCHEMA, so it is known without
+// reading a description and cannot be guessed. These were plain z.string() with descriptions that
+// named no values at all ("Pre_Post_Deployment__c picklist value."), and a run duly guessed, planned
+// to "retry without that field if needed", and burned calls sampling live records to find out.
+const DEPLOYMENT_TASK_TYPE = z.enum([
+    "Conga",
+    "Data Creation / Update / Deletion",
+    "Feature Console",
+    "Flow Activation / Deactivation",
+    "Navigation Builder",
+    "Page Layout / Record Page Update",
+    "Page Layout Assignment",
+    "Permission Controls",
+    "Permission Group / Set Assignment",
+    "Scheduled Job",
+    "Report / Dashboard Folder - Sharing / Unsharing",
+    "Public Group / Queue - Adding / Removing Users",
+    "Activation / Deactivation",
+    "Other"
+]);
+/**
+ * §9.4 — the KIND OF LABOUR a handed-back task is, which is a different question from what
+ * Salesforce artefact it touches.
+ *
+ * `DEPLOYMENT_TASK_TYPE` above is the org's own restricted picklist and answers "what is this
+ * thing"; this answers "what is someone going to have to DO", which is what an automation-lever
+ * analysis groups on. Six values, deliberately coarse — a taxonomy fine enough to argue about is
+ * one nobody classifies consistently, and the whole value here is that two runs on two machines
+ * put the same work in the same bucket.
+ *
+ * IT NEVER REACHES CAMPFIRE. This rides the `manual_work.recorded` event, which is shape-only, and
+ * the ledger refuses any value outside this set. The supervisor stamps it at creation because that
+ * is the one moment the answer is known for free: it just decided it could not automate this.
+ */
+const MANUAL_TASK_KIND = z.enum(["config", "verification", "data", "release", "external", "other"]);
+/**
+ * Absolute path to a shipped reference doc.
+ *
+ * Both places that pointed at the Configuration Items guide used a RELATIVE path, and they
+ * disagreed — "harness/reference/..." (true only in the repo) and "reference/..." (true only from
+ * the package root). On a real install the package sits wherever npm's global prefix put it, and the
+ * session cwd is somewhere else entirely, so NEITHER resolved and the guide the supervisor is told
+ * to read before finalising a writeback could not be opened. Same failure class as the skill that
+ * shipped nowhere: an instruction that silently cannot be followed.
+ *
+ * Resolved from this module's own location, so it is correct in the repo, in the tarball, and in
+ * every installed version.
+ */
+export function referenceDoc(file) {
+    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+    // Package layout (the tarball, and every installed version) puts reference/ beside dist/.
+    const packaged = path.join(root, "reference", file);
+    if (existsSync(packaged))
+        return packaged;
+    // Repo layout keeps it under harness/. Checked second so an install never pays a stat for a path
+    // that cannot exist there, and so dev and production resolve to the same FILE either way.
+    const inRepo = path.join(root, "harness", "reference", file);
+    return existsSync(inRepo) ? inRepo : packaged;
+}
+const CI_GUIDE = () => referenceDoc("campfire-configuration-items-guide.md");
+const UPDATABLE_FIELDS = {
+    Deployment_Notes__c: { rich: true, appendable: true },
+    PM_Notes__c: { rich: true, appendable: true },
+    Build_Status__c: { rich: false, appendable: false },
+    Blocked_Reason__c: { rich: false, appendable: false },
+    Org_Deployed_To__c: { rich: false, appendable: false }
+};
+/**
+ * Field caps this tool KNOWS, so an oversize value is refused locally instead of taking a whole
+ * all-or-nothing batch down with it.
+ *
+ * The retro that produced this named the asymmetry exactly: the schema documents picklist values
+ * meticulously ("do not query the org to discover them") and said nothing about length, and length
+ * is what broke the CF63 writeback. Same class of knowledge, one of them written down.
+ *
+ * MEASURED, not guessed: `sf sobject describe Campfire_Requirement__c --target-org vfppartial`,
+ * 2026-07-31. (An earlier attempt described the DELIVERY org by mistake — its own lesser
+ * `Campfire_Requirement__c` has 15 fields and none of these — so the caps went unmeasured for a
+ * while and only `Blocked_Reason__c` was known, from the org's own STRING_TOO_LONG. Describe the
+ * CONSULTANT org, `vfppartial`. The target org's minted alias used to be `campfire-<orgid>`,
+ * which is exactly how the wrong org got described — it is `in2-<mydomain>` now, named after the
+ * org itself; see `targetOrgAlias`.)
+ *
+ * The two picklists are omitted deliberately: `checkPicklist` constrains them to an enumerated set,
+ * which is strictly tighter than their 255 / 4099 storage caps, so a length rule there would only
+ * ever be dead code.
+ *
+ * The notes fields matter MORE than their size suggests, because they are APPEND-mode: each run
+ * adds a timestamped block, so the value that gets written is the accumulated history plus the new
+ * note. That is why the cap is checked against the COMPOSED body rather than the caller's input —
+ * a note that is fine on its own can still overflow a field that is already nearly full, and on an
+ * all-or-nothing batch that one row refuses every row.
+ */
+const MAX_LENGTHS = {
+    Blocked_Reason__c: 255,
+    Deployment_Notes__c: 32_768,
+    PM_Notes__c: 32_768
+};
+/**
+ * Everything about a deployment-task batch that can be known WITHOUT the org.
+ *
+ * Checked up front because the write is all-or-nothing: naming every problem at once beats
+ * discovering them one org round trip at a time, and a local refusal has written nothing to a
+ * shared org. Returns one line per problem; empty means the batch is worth sending.
+ */
+export function checkDeploymentTasks(tasks) {
+    const problems = [];
+    const seen = new Set();
+    tasks.forEach((t, i) => {
+        const at = `tasks[${i}] (${t.externalId || t.requirement})`;
+        if (!EXTERNAL_ID_RE.test(t.externalId))
+            problems.push(`${at}: externalId must match ${EXTERNAL_ID_RE}`);
+        // A duplicate key inside ONE upsert batch is not idempotency, it is the batch racing itself —
+        // Salesforce rejects it, and catching it here says so in terms the caller can act on.
+        if (seen.has(t.externalId))
+            problems.push(`${at}: externalId ${t.externalId} appears more than once — an upsert batch cannot race itself`);
+        seen.add(t.externalId);
+        if (!t.description.trim())
+            problems.push(`${at}: description is empty — it is the task's only headline`);
+        // Live-caught FIELD_CUSTOM_VALIDATION_EXCEPTION on the singular tool. One row like this refuses
+        // the whole batch, so it is worth a local check.
+        if (t.type === "Other" && !t.otherType?.trim()) {
+            problems.push(`${at}: type 'Other' REQUIRES otherType (org validation rejects it otherwise)`);
+        }
+    });
+    return problems;
+}
+/**
+ * What changed on a confirmed write, without shipping the field contents back.
+ *
+ * Appendable rich-text fields grow by a timestamped block per run, so echoing before AND after
+ * returns every earlier run's notes twice on every write. Report the DELTA instead: for an append,
+ * how much was added; for a replace, a short head of the new value. The correctness question was
+ * already settled by readBackMatches before this is called.
+ */
+export function summarizeWrite(names, before, after, 
+// Append-vs-replace is KNOWN at the call site (the field's allowlist entry plus the caller's
+// mode). Inferring it from the value growing is wrong the moment a replace happens to be longer
+// than what it replaced — "Not Started" -> "Build Complete" reported "appended 3 chars", which is
+// both false and useless. Caught by its own test.
+wasAppend) {
+    const len = (v) => (typeof v === "string" ? v.length : v === undefined || v === null ? 0 : String(v).length);
+    return names.map((field) => {
+        const a = len(after[field]);
+        if (wasAppend(field))
+            return { field, change: `appended ${a - len(before[field])} chars (now ${a})` };
+        const head = String(after[field] ?? "").slice(0, 80);
+        return { field, change: `set to ${JSON.stringify(head)}${a > 80 ? ` …(${a} chars)` : ""}` };
+    });
+}
+/** Reject an oversize value before it reaches the shared org. Returns an error message, or null. */
+export function checkLength(field, value, appended = false) {
+    const cap = MAX_LENGTHS[field];
+    if (cap === undefined || value.length <= cap)
+        return null;
+    return (`${field} is capped at ${cap} characters and the value to be written is ${value.length}. ` +
+        (appended
+            ? `This field APPENDS, so that total is the accumulated history plus your new block — the field is full, not your note. ` +
+                `Write with mode 'replace' carrying only what still matters, or prune the record first.`
+            : `Put the detail in Deployment_Notes__c (32,768 chars) and keep this field to a one-line summary.`) +
+        ` The org would reject it with STRING_TOO_LONG, and because the batch writer is all-or-nothing, one oversize value refuses EVERY row in the call.`);
+}
+/** Reject a picklist value before it reaches the shared org. Returns an error message, or null. */
+export function checkPicklist(field, value) {
+    const def = PICKLISTS[field];
+    if (!def)
+        return null;
+    // A multipicklist arrives semicolon-separated; every member must be legal.
+    const parts = def.multi ? value.split(";").map((v) => v.trim()).filter(Boolean) : [value];
+    const bad = parts.filter((v) => !def.values.includes(v));
+    if (bad.length === 0)
+        return null;
+    return (`${field} does not accept ${bad.map((b) => JSON.stringify(b)).join(", ")}. Legal value(s): ${def.values.join(" | ")}` +
+        `${def.multi ? " (semicolon-separated for more than one)" : ""}. ` +
+        (def.restricted
+            ? "This picklist is RESTRICTED, so the org would reject the write anyway."
+            : "This picklist is OPEN, so the org would have ACCEPTED a wrong value silently — which is why it is checked here.") +
+        ` Verified 2026-07-28; if Campfire has changed since, describe_object {targetOrg: "campfire", objectApiName: "Campfire_Requirement__c", match: "${field.replace(/__c$/, "")}"} shows the current set.`);
+}
+// Salesforce normalizes rich-text HTML on save (e.g. <br/> becomes <br>, entity forms
+// shift) — live-caught as a false WRITE_NOT_CONFIRMED. Rich fields compare by text
+// content; only non-rich fields compare verbatim. Exported for tests.
+//
+// Markup is stripped BEFORE entities are decoded, so an escaped `&lt;b&gt;` in the caller's text
+// survives as the literal characters `<b>` instead of being stripped as if it were a tag.
+export function normalizeRichText(value) {
+    return decodeHtmlEntities(value.replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, ""))
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function readBackMatches(written, stored, rich) {
+    const w = String(written ?? "");
+    const s = String(stored ?? "");
+    return rich ? normalizeRichText(w) === normalizeRichText(s) : w === s;
+}
+/** Compare the exact Configuration Item rows we wrote against a fresh Campfire read. */
+export function configItemReadBackProblems(expected, stored) {
+    const byExternalId = new Map(stored.map((row) => [String(row.External_ID__c ?? ""), row]));
+    const fields = [
+        "Requirement__c",
+        "Configuration_Item_API_Name__c",
+        "Object_API_Name__c",
+        "Report_Folder_API_Name__c",
+        "Type__c",
+        "Description__c"
+    ];
+    const display = (value) => (value === null || value === undefined ? "" : String(value));
+    const problems = [];
+    for (const item of expected) {
+        const row = byExternalId.get(item.externalId);
+        if (!row) {
+            problems.push({
+                externalId: item.externalId,
+                metadataKey: item.metadataKey,
+                field: "row",
+                expected: "(present)",
+                observed: "(missing)"
+            });
+            continue;
+        }
+        for (const field of fields) {
+            const rich = field === "Description__c";
+            if (readBackMatches(item.body[field], row[field], rich))
+                continue;
+            problems.push({
+                externalId: item.externalId,
+                metadataKey: item.metadataKey,
+                field,
+                expected: display(item.body[field]),
+                observed: display(row[field])
+            });
+        }
+    }
+    return problems;
+}
+export function appendBlock(existing, addition, rich) {
+    const stamp = `[cc-mcp ${isoNow()}]`;
+    if (rich) {
+        // Only the ADDITION is escaped. `existing` came back from the org already escaped, so escaping
+        // it again would turn every prior run's `&lt;` into `&amp;lt;` and its `<br>` into visible text
+        // — the accumulated note history degrading a little further on every single write.
+        const block = `<b>${stamp}</b><br/>${richTextFragment(addition)}`;
+        return existing && String(existing).trim() ? `${existing}<br/><br/>${block}` : block;
+    }
+    // Plain text is NOT escaped: nothing sanitizes it, so entities would be stored as literal
+    // ampersand-l-t rather than rendering as a `<`.
+    const block = `${stamp} ${addition}`;
+    return existing && String(existing).trim() ? `${existing}\n\n${block}` : block;
+}
+/**
+ * The SOQL that finds UNKEYED rows this write would otherwise duplicate. Rows written by anything
+ * other than this writer carry no External_ID__c, so the org's external-id upsert cannot see them
+ * — it finds nothing and inserts a second row alongside. Live-measured in the vfppartial Campfire
+ * org: 10,700 of 11,831 Configuration Items are unkeyed, so this is the dominant duplication
+ * vector, not the write race (QA2-012 Cause B).
+ *
+ * Identity deliberately includes the parent (e.g. Requirement__c): the unkeyed population is
+ * mostly the CLIENT's historical rows for other requirements — `PermissionSet
+ * QTC_System_Administrator` alone has 107 of them. Matching on type+name without the parent would
+ * stamp our external id onto a client record and overwrite its description.
+ */
+export function orphanIdentitySoql(objectApiName, identity) {
+    const where = Object.entries(identity)
+        .map(([field, value]) => (value === null ? `${field} = null` : `${field} = '${soqlEscape(value)}'`))
+        .join(" AND ");
+    return `SELECT Id FROM ${objectApiName} WHERE External_ID__c = null AND ${where}`;
+}
+async function upsertByExternalId(consultantOrg, objectApiName, externalId, body, 
+// Identity fields that name the SAME component a pre-existing unkeyed row would carry. When
+// provided, exactly one matching orphan is ADOPTED (external id stamped onto it) instead of a
+// second row being created beside it. Omitted → no adoption pass (callers whose objects have no
+// unkeyed population).
+adoptIdentity) {
+    const upsertEndpoint = `/services/data/${API}/sobjects/${objectApiName}/External_ID__c/${externalId}`;
+    if (adoptIdentity) {
+        const orphans = await query(consultantOrg, orphanIdentitySoql(objectApiName, adoptIdentity));
+        if (orphans.length > 1) {
+            // More than one unkeyed row claiming the same identity is ALREADY corrupted data — adopting
+            // one at random would bless an arbitrary survivor and hide the rest. Cleanup is a human call.
+            throw new Error(`${orphans.length} ${objectApiName} rows with no External_ID__c match the same component identity ` +
+                `(${Object.entries(adoptIdentity)
+                    .map(([k, v]) => `${k}=${v ?? "null"}`)
+                    .join(", ")}): ${orphans.map((r) => String(r.Id)).join(", ")} — refusing to adopt or add a row. ` +
+                `These are pre-existing duplicates; deduplicate them in Campfire first.`);
+        }
+        const orphan = orphans[0];
+        if (orphan) {
+            const id = String(orphan.Id);
+            try {
+                // Stamping the external id IS the adoption: from here on, every session's upsert resolves
+                // to this row instead of inserting beside it.
+                await restWrite(consultantOrg, "PATCH", `/services/data/${API}/sobjects/${objectApiName}/${id}`, {
+                    ...body,
+                    External_ID__c: externalId
+                });
+                return { id, action: "adopted" };
+            }
+            catch (error) {
+                // Another session created a keyed row for this component between our query and our PATCH
+                // (the field is org-enforced Unique). That row is now the canonical one — fall through and
+                // let the atomic upsert update it.
+                if (!(error instanceof Error && error.message.includes("DUPLICATE_VALUE")))
+                    throw error;
+            }
+        }
+    }
+    try {
+        // PATCH on the external-id resource is Salesforce's ATOMIC upsert: insert-or-update is decided
+        // org-side under the field's unique index, so two concurrent sessions writing the same id
+        // cannot both insert — the loser's request resolves to an update of the winner's row. The old
+        // query-then-write here was the race QA2-012 named (both query, both see nothing, both insert).
+        // External_ID__c is verified Unique + External ID in the Campfire schema.
+        const result = await restWrite(consultantOrg, "PATCH", upsertEndpoint, body);
+        const id = result && typeof result.id === "string" ? result.id : "";
+        if (!result || !id)
+            throw new Error(`upsert returned no id: ${JSON.stringify(result)}`);
+        return { id, action: result.created === true ? "created" : "updated" };
+    }
+    catch (error) {
+        // A write killed at timeout is AMBIGUOUS — the org may have processed it after the kill
+        // (live-caught: ~30s after). The record READ resolves the ambiguity mechanically instead of
+        // leaving the instruction in an error message for the caller to maybe follow.
+        if (error instanceof Error && error.message.includes("AMBIGUOUS")) {
+            const rows = await query(consultantOrg, `SELECT Id FROM ${objectApiName} WHERE External_ID__c = '${soqlEscape(externalId)}'`);
+            const landed = rows[0];
+            if (rows.length === 1 && landed) {
+                // The write landed. These bodies are full replacements (not appends), so the row holds
+                // exactly what this call sent; create-vs-update is indistinguishable post hoc and is
+                // reported as the conservative "updated".
+                return { id: String(landed.Id), action: "updated" };
+            }
+            throw new Error(`Campfire upsert of ${objectApiName} '${externalId}' timed out and a read-back found no row — the write did NOT land. Retrying this call is safe.`);
+        }
+        throw error;
+    }
+}
+// A STABLE Configuration Item key, derived from the component itself.
+//
+// Hand-picked external ids are the reason a bulk writer could not exist: they live in the model's
+// head, so every row needed a separate call with a separate invented key, and re-running a
+// writeback would duplicate rather than update. Deriving from the metadata key makes the same
+// component produce the same id in every session, which is what makes the write idempotent
+// ACROSS runs and not merely within one.
+//
+// 12 hex characters of sha256 is 48 bits — ample against collision for a batch's component set,
+// and it fits the Text(18) field with the prefix.
+function configItemExternalId(metadataKey) {
+    return `CI-${createHash("sha256").update(metadataKey).digest("hex").slice(0, 12)}`;
+}
+/**
+ * The Configuration Item description generator now lives in its own module — see
+ * `campfire/configItemDescription.ts` for the rule that governs what a description may assert.
+ * Re-exported here because this module is the tool surface every caller already imports.
+ */
+export const configItemDescription = describeConfigItem;
+/**
+ * A deployment task's only text surface: `description` as the bold first line, `richDescription` as
+ * the body. Extracted from the batch writer so the escaping it depends on is testable without an
+ * org — it is one of the three rich-text bodies this file composes.
+ */
+export function deploymentTaskRichDescription(description, richDescription) {
+    const richBody = richDescription ? `<br/>${richTextFragment(richDescription)}` : "";
+    // The headline is one line by construction, so its newlines collapse to spaces rather than <br/>.
+    return `<b>${escapeRichText(description.replace(/\n/g, " "))}</b>${richBody}`;
+}
+export function registerCampfireTools(server) {
+    // ONE read tool, taking an array. There used to be a singular sibling, and it was the default a
+    // run reached for — so the loop's first step (read every requirement) opened a twelve-requirement
+    // batch with twenty-four sequential round trips. Reading one requirement is an array of one.
+    server.registerTool("read_campfire_requirements", {
+        title: "Read Campfire requirements in one call",
+        description: "Read Campfire requirements in full (content fields + Build_Status, Blocked_Reason, Org_Deployed_To, Deployment/PM notes, and the Configuration Item / Deployment Task ROLL-UP COUNTERS). Those two counters are DISPLAY ONLY and must never be used to verify a writeback: they are derived fields that lag their children (observed stale seconds after a write, live-caught 2026-08-03), and Campfire's own org automation files Deployment Tasks of its own off Configuration Item manifest rows, so the total is not yours to reconcile. Check what you wrote by querying the child records by `External_ID__c`. Read-only SOQL on the consultant org, at most THREE queries however many are named. USE THIS AT THE START OF EVERY BATCH — read them all in one call; one requirement is an array of one. Partial results are returned rather than refused: a read cannot corrupt anything, so a reference matching zero or several rows is reported by name in `unresolved` while the rest come back in full. Ambiguity is never flattened — exactly one match, or unresolved.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .describe("The session whose Campfire org to read. Bound when requirements were imported from Campfire (import_requirements { campfire }), so the consultant alias never has to be restated."),
+            requirements: z
+                .array(z.string())
+                .min(1)
+                .max(100)
+                .describe("REQ-####, EXT-####, or 15/18-char record Ids. Duplicates are collapsed.")
+        }
+    }, async ({ sessionId, requirements }) => {
+        try {
+            const campfire = await resolveSessionOrg(await loadSession(sessionId), "campfire", { verify: false });
+            const consultantOrg = campfire.alias;
+            assertTargetOrg(consultantOrg);
+            const startedAt = Date.now();
+            const asked = [...new Set(requirements.map((r) => r.trim()).filter(Boolean))];
+            // READ PROVENANCE (R9, R11-R12). This is the ONE probe that reads the CONSULTANT org, and
+            // recording that faithfully is the point: the contamination join is ORG-KEYED, so a
+            // requirement read filed under the deploy target would manufacture overlap out of work that
+            // never touched the client's org at all.
+            //
+            // No component keys, and this is not an opaque read. Opaque means "reached the org and its
+            // identities did not derive" — the number that bounds a clean claim. A requirement is a
+            // DATA record, not a metadata component, so there was never a component key to derive.
+            // Campfire org ids are frequently unrecorded (the binding is made at import, where an
+            // `sf org display` for an id nothing needed would be pure cost), so the record joins by
+            // alias and says so with a null id rather than inventing one.
+            const recordRead = async (rowCount, outcome) => appendReadRecord(sessionId, {
+                tool: "read_campfire_requirements",
+                orgId: campfire.orgId ?? null,
+                orgAlias: consultantOrg,
+                // Requirement names are identifiers (REQ-####/record ids), not org content.
+                scope: `Campfire_Requirement__c ${asked.join(",")}`,
+                object: "Campfire_Requirement__c",
+                pattern: "targeted",
+                keys: [],
+                rows: rowCount,
+                durationMs: Date.now() - startedAt,
+                outcome
+            });
+            // `query` THROWS on a non-zero exit — that is this tool's designed failure signal, not an
+            // internal error — so a bare append after the reads would skip the record on exactly the
+            // path where a call did reach the org and come back empty-handed. Recorded once either way.
+            let resolved;
+            let unresolved;
+            try {
+                ({ resolved, unresolved } = await resolveRequirements(consultantOrg, asked));
+            }
+            catch (error) {
+                await recordRead(0, "failed");
+                throw error;
+            }
+            if (resolved.size === 0) {
+                await recordRead(0, "failed");
+                return fail("REQUIREMENT_NOT_FOUND", `none of ${asked.length} reference(s) resolved to exactly one Campfire_Requirement__c: ${unresolved.join(", ")}`);
+            }
+            const ids = [...resolved.values()].map((r) => `'${soqlEscape(r.id)}'`).join(", ");
+            let rows;
+            try {
+                rows = await query(consultantOrg, `SELECT ${READ_FIELDS.join(", ")} FROM Campfire_Requirement__c WHERE Id IN (${ids})`);
+            }
+            catch (error) {
+                await recordRead(0, "failed");
+                throw error;
+            }
+            await recordRead(rows.length, "ok");
+            // Ordered as ASKED, not as the org returned them. The supervisor reads these against a
+            // requirement ladder it already has in mind, and a reordered list makes it re-sort by hand.
+            const byId = new Map(rows.map((row) => [String(row.Id), row]));
+            const records = [...resolved.values()].map((r) => byId.get(r.id)).filter(Boolean);
+            const summary = [
+                `read ${records.length} of ${asked.length} requirement(s)`,
+                ...records.map((record) => `${record.Name} — ${record.Requirement_Name__c ?? ""} | stage: ${record.Requirement_Stage__c ?? "-"} | buildStatus: ${record.Build_Status__c ?? "-"} | CIs: ${record.Number_of_Configuration_Items__c ?? 0} | tasks: ${record.Number_of_Deployment_Tasks__c ?? 0}`),
+                // The counters are printed because they are useful context and refused as EVIDENCE in the
+                // same breath. Live-caught 2026-08-03 (RV batch): a run verifying its writeback found them
+                // stale, and found two Deployment Tasks it had not written sitting beside the ones it had —
+                // created by Campfire's own automation off the Configuration Item manifest rows, seconds
+                // after the write and with no external ids. Both readings of a total are wrong there.
+                "CIs/tasks are Campfire's own ROLL-UP COUNTERS — they lag their children, and Campfire's automation" +
+                    " files Deployment Tasks of its own. Never reconcile a writeback against them: query the child" +
+                    " records by External_ID__c, which is the only key that identifies rows YOU wrote.",
+                ...(unresolved.length
+                    ? [`UNRESOLVED (${unresolved.length}): ${unresolved.join(", ")} — each must match exactly one requirement.`]
+                    : [])
+            ].join("\n");
+            return ok(summary, { records, unresolved });
+        }
+        catch (error) {
+            if (error instanceof UnknownWaveError)
+                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);
+            return internalError(error);
+        }
+    });
+    // ---- requirement writeback ------------------------------------------------------------------
+    //
+    // ONE write tool, taking an array. SM301 retro: end-of-run writeback issued TEN sequential
+    // single-record PATCHes — ten separate timeout exposures, and one DID hit the ambiguous-timeout
+    // path mid-series, costing a manual read-before-retry. sObject Collections turns the same work
+    // into ONE request with all-or-none semantics, so the batch either lands whole or not at all, and
+    // read-back verifies every row in one query. Updating one requirement is an array of one.
+    server.registerTool("update_campfire_requirements", {
+        title: "Update allowlisted fields on Campfire requirements",
+        description: "NOT PART OF A DELIVERY RUN — the delivery loop never calls this. A writeback is the Configuration Items (campfire_write_config_items); this tool exists for OPERATOR-DIRECTED updates to the requirement record, when a human explicitly asks for one. Do not call it to record a delivery: notes, Build Status, Blocked Reason and Org Deployed To are human-owned or belong to deployment, which this program does not perform. GATED (Campfire write + consultant-org allowlist — the org is REAL and SHARED). Update ALLOWLISTED fields on Campfire requirements; any other field refuses. Notes fields APPEND a timestamped block by default (replace only when mode: replace), so nothing human-written is ever clobbered. Executed as ONE all-or-none sObject-Collections call — one requirement is an array of one, and a ten-requirement writeback is one timeout exposure instead of ten. Every row is validated before anything is written, and any row the ORG rejects is reported by requirement name with Salesforce's own error code and field. One read-back verifies every row and the result reports what CHANGED per field, not the field contents.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .describe("The session this writeback belongs to. The Campfire consultant org comes FROM the session — bound at import — so a write cannot be aimed at the wrong org by restating an alias."),
+            updates: z
+                .array(z.object({
+                requirement: z.string().describe("REQ-####, EXT-####, or record Id."),
+                fields: z
+                    .record(z.string(), z.string())
+                    .describe("Field API name -> value. Allowlist: Deployment_Notes__c, PM_Notes__c (both rich text, appended by default), Blocked_Reason__c (free text, HARD CAP 255 CHARACTERS — measured; longer refuses locally, and would otherwise take the whole all-or-nothing batch down with it, so keep it to a one-line summary and put the detail in Deployment_Notes__c), and two PICKLISTS whose legal values are fixed: " +
+                    "Build_Status__c = Not Started | In Progress | In Progress - At Risk | Build Complete | Blocked | Complete | Withdrawn (a human sets this; a delivery run never does); " +
+                    "Org_Deployed_To__c = Development | Partial Sandbox | Full Sandbox | Production (multi-select, semicolon-separated). " +
+                    "Both are validated before the write — do not query the org to discover them."),
+                mode: z.enum(["append", "replace"]).optional().describe("For notes fields: append (default) or replace.")
+            }))
+                .min(1)
+                .max(50)
+                .describe("One entry per requirement. A requirement may appear only once per call.")
+        }
+    }, async ({ sessionId, updates }) => {
+        try {
+            const { alias: consultantOrg } = await resolveSessionOrg(await loadSession(sessionId), "campfire", { verify: false });
+            await assertCampfireWriteAllowed(consultantOrg);
+            // Validate EVERYTHING before touching the org — a batch that half-validates is a batch
+            // that half-writes.
+            const problems = [];
+            const allFields = new Set();
+            const seen = new Set();
+            for (const [i, u] of updates.entries()) {
+                const names = Object.keys(u.fields);
+                if (names.length === 0)
+                    problems.push(`updates[${i}] (${u.requirement}): no fields`);
+                for (const [name, value] of Object.entries(u.fields)) {
+                    if (!(name in UPDATABLE_FIELDS)) {
+                        problems.push(`updates[${i}] (${u.requirement}): field ${name} is not allowlisted`);
+                        continue;
+                    }
+                    const bad = checkPicklist(name, value);
+                    if (bad)
+                        problems.push(`updates[${i}] (${u.requirement}): ${bad}`);
+                    // Length is NOT checked here. For a replace-mode field the input is what gets written,
+                    // but for an append the written value is the record's accumulated history plus this
+                    // block — unknowable until the before-image is read. Checking the raw input would pass
+                    // the case that actually overflows, so the check lives at composition instead. Both
+                    // still refuse before anything is written.
+                    allFields.add(name);
+                }
+                const key = u.requirement.trim().toUpperCase().replace(/^EXT-/, "REQ-");
+                if (seen.has(key))
+                    problems.push(`updates[${i}]: ${u.requirement} appears more than once — append composition cannot race itself`);
+                seen.add(key);
+            }
+            if (problems.length > 0)
+                return fail("BATCH_INVALID", `Nothing written. Fix:\n${problems.map((p) => `  ${p}`).join("\n")}`);
+            // Resolve every target in one query.
+            const ids = updates.map((u) => u.requirement.trim()).filter((r) => SF_ID_RE.test(r));
+            const names = updates
+                .map((u) => u.requirement.trim().replace(/^EXT-/, "REQ-"))
+                .filter((r) => CAMPFIRE_NAME_RE.test(r));
+            const fieldList = [...allFields];
+            const where = [
+                ids.length ? `Id IN (${ids.map((x) => `'${x}'`).join(",")})` : null,
+                names.length ? `Name IN (${names.map((x) => `'${x}'`).join(",")})` : null
+            ].filter(Boolean).join(" OR ");
+            const rows = await query(consultantOrg, `SELECT Id, Name, ${fieldList.join(", ")} FROM Campfire_Requirement__c WHERE ${where}`);
+            const byName = new Map(rows.map((r) => [String(r.Name), r]));
+            const byId = new Map(rows.map((r) => [String(r.Id), r]));
+            const resolvedRows = updates.map((u) => {
+                const raw = u.requirement.trim();
+                return SF_ID_RE.test(raw) ? byId.get(raw) : byName.get(raw.toUpperCase().replace(/^EXT-/, "REQ-"));
+            });
+            const missing = updates.filter((_, i) => !resolvedRows[i]).map((u) => u.requirement);
+            if (missing.length > 0)
+                return fail("REQUIREMENT_NOT_FOUND", `Nothing written. Not found: ${missing.join(", ")}.`);
+            // Compose per-row bodies (append against the just-read before-image) and write ONCE.
+            const overlong = [];
+            const records = updates.map((u, i) => {
+                const before = resolvedRows[i];
+                const body = { attributes: { type: "Campfire_Requirement__c" }, Id: before.Id };
+                for (const [name, value] of Object.entries(u.fields)) {
+                    const spec = UPDATABLE_FIELDS[name];
+                    const appended = spec.appendable && (u.mode ?? "append") === "append";
+                    // REPLACE goes through the same escaping as APPEND. The field is rich text either way,
+                    // so a `<` in the caller's value is swallowed by the sanitizer either way — the mode
+                    // only decides whether the prior history stays, not whether the value is HTML.
+                    body[name] = appended
+                        ? appendBlock(before[name], value, spec.rich)
+                        : spec.rich
+                            ? richTextFragment(value)
+                            : value;
+                    // COMPOSED, not the caller's input — see checkLength. This is the check that most
+                    // needs to be here rather than in the pre-validation loop above: the append target is
+                    // only known after the before-image is read, and on an all-or-nothing batch a single
+                    // overflowing row refuses all the others.
+                    const tooLong = checkLength(name, String(body[name]), appended);
+                    if (tooLong)
+                        overlong.push(`${String(before.Name)}: ${tooLong}`);
+                }
+                return body;
+            });
+            if (overlong.length > 0) {
+                return fail("FIELD_VALUE_TOO_LONG", `Nothing written. ${overlong.length} row(s) would exceed a field cap:\n  ${overlong.join("\n  ")}`);
+            }
+            await restCollections(consultantOrg, "PATCH", records, (i) => String(resolvedRows[i]?.Name ?? updates[i]?.requirement ?? `row ${i}`));
+            // One read-back for the whole batch — and if the READ fails, the PATCH still landed.
+            // Reporting that as a plain failure is how an append gets applied twice: a blind retry
+            // composes a second timestamped block on top of the one already stored (live-caught).
+            let after;
+            try {
+                after = await query(consultantOrg, `SELECT Id, Name, ${fieldList.join(", ")} FROM Campfire_Requirement__c WHERE Id IN (${records.map((r) => `'${String(r.Id)}'`).join(",")})`);
+            }
+            catch (readBackError) {
+                return fail("WRITE_LANDED_READBACK_FAILED", `The batch PATCH succeeded for all ${records.length} requirement(s) (${resolvedRows.map((r) => String(r.Name)).join(", ")}) but the confirmation read failed. Do NOT blindly retry — an append-mode retry would duplicate the note block on every row. Read those records first, then reconcile. Read error: ${readBackError instanceof Error ? readBackError.message : String(readBackError)}`);
+            }
+            const afterById = new Map(after.map((r) => [String(r.Id), r]));
+            const drift = [];
+            for (const [i, u] of updates.entries()) {
+                const a = afterById.get(String(records[i].Id)) ?? {};
+                for (const name of Object.keys(u.fields)) {
+                    if (!readBackMatches(records[i][name], a[name], UPDATABLE_FIELDS[name]?.rich ?? false)) {
+                        drift.push(`${String(resolvedRows[i].Name)}.${name}`);
+                    }
+                }
+            }
+            if (drift.length > 0) {
+                // This claim is now EARNED. Reaching here means restCollections saw success:true on every
+                // record, so the write really did land and the appends really are applied — which is why
+                // "do not retry" is the right advice. It used to be asserted on a response nobody read,
+                // and it was false in the one case it ever fired.
+                return fail("WRITE_NOT_CONFIRMED", `Salesforce accepted every row, but the read-back does not match for: ${drift.join(", ")} — so something transformed the value AFTER the write (org automation, a formula, a workflow). The appends ARE applied: do NOT re-run this call, or the note block will be duplicated. Read those records and reconcile.`);
+            }
+            // A SUMMARY, not the payload. Returning the full before AND after of every field written
+            // means Deployment_Notes__c — a rich-text field that ACCUMULATES a timestamped block per
+            // run — comes back twice per row; by CF63 it already carried three prior runs' notes, so a
+            // fifteen-requirement writeback would echo that history thirty times for no added value.
+            // The correctness question was settled by the read-back above; what a caller can act on is
+            // what CHANGED and by how much. The record is one read away if the full text is wanted.
+            const written = updates.map((u, i) => {
+                const names = Object.keys(u.fields);
+                const wasAppend = (f) => Boolean(UPDATABLE_FIELDS[f]?.appendable) && (u.mode ?? "append") === "append";
+                return {
+                    id: String(resolvedRows[i].Id),
+                    name: String(resolvedRows[i].Name),
+                    fields: summarizeWrite(names, resolvedRows[i], afterById.get(String(records[i].Id)) ?? {}, wasAppend)
+                };
+            });
+            return ok([`updated ${updates.length} requirement(s) in one call — read-back confirmed:`, ...written.map((w) => `  ${w.name}: ${w.fields.map((f) => `${f.field} ${f.change}`).join("; ")}`)].join("\n"), { updated: updates.length, requirements: written });
+        }
+        catch (error) {
+            if (error instanceof GateError)
+                return fail(error.code, error.message);
+            if (error instanceof SessionOrgError)
+                return fail(error.code, error.message);
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+    // ---- corpus authoring — TEST HARNESS ONLY, off unless CC_MCP_CORPUS_TOOLS says otherwise ------
+    //
+    // The two tools below stand up and clone the CF-series MASTER CORPORA we run the product against.
+    // Neither has any role in delivering a real client's batch: a consultant session reads the
+    // requirements Campfire sent it, it never authors or mirrors them. So they are gated the same way
+    // the beta feedback tools are — THE FLAG IS THE REGISTRATION — and a delivery install ships with
+    // no trace of them.
+    //
+    // The saving is not the point of the tools, it is the point of the gate: a tool definition is
+    // resident in EVERY context this server is connected to before turn one, and these two are ~1.5 KB
+    // of description plus their schemas, paid by every delivery session AND by every analyzer subagent
+    // fanned out from one — none of which may write to the consultant org at all.
+    //
+    // The write gate (CC_MCP_CAMPFIRE_WRITE + allowlist) is unchanged and still applies on top. This
+    // decides only whether the model is TOLD the tools exist.
+    if (corpusToolsEnabled())
+        registerCorpusTools(server);
+    registerConfigItemTools(server);
+}
+/**
+ * The corpus-authoring pair, split out so the flag check above reads as one line.
+ *
+ * Standing up the SM3M masters required a raw `sf data import tree` because nothing on the tool
+ * surface CREATES requirements — import_requirements imports into a session and mirror_requirements
+ * clones records that already exist. This is that missing first step, for authoring NEW master
+ * content the operator supplies.
+ */
+function registerCorpusTools(server) {
+    server.registerTool("create_campfire_requirements", {
+        title: "Create new Campfire requirement records in batch",
+        description: "GATED (Campfire write + consultant-org allowlist — the org is REAL and SHARED). Create NEW Campfire_Requirement__c records from supplied content — the authoring step mirror_requirements cannot do (it only clones records that already exist). Used to stand up master corpora (the SM3M set needed a raw CLI tree-import for exactly this). Every record gets Requirement_Stage__c 'Definition & Design' and Build_Status__c 'Not Started'. Refuses if ANY requirementName already exists (exact match) — re-running cannot duplicate a corpus. dryRun defaults TRUE and reports exactly what would be created; the real write is ONE all-or-none sObject-Collections call.",
+        inputSchema: {
+            sessionId: z.string().describe("The session whose Campfire consultant org to write to."),
+            records: z
+                .array(z.object({
+                requirementName: z.string().min(1).describe("Requirement_Name__c — the human-visible name, e.g. 'SM3M - R1 - …'."),
+                userStory: z.string().optional().describe("User_Story__c, e.g. 'As a service desk manager'."),
+                userStoryAction: z.string().optional().describe("User_Story_Action__c — 'I want …'."),
+                userStorySuchThat: z.string().optional().describe("User_Story_Such_That__c — 'such that …'."),
+                acceptanceCriteriaGiven: z.string().optional(),
+                acceptanceCriteriaWhen: z.string().optional(),
+                acceptanceCriteriaThen: z.string().optional(),
+                solutionDesignSummary: z.string().optional().describe("Solution_Design_Summary__c — the PRIMARY content field the import composes from."),
+                solutionDetails: z.string().optional().describe("Solution_Details__c — Pinsley-style long design body."),
+                requirementDetails: z.string().optional().describe("Requirement_Details__c (legacy content field)."),
+                expectedResults: z.string().optional(),
+                preRequisite: z.string().optional()
+            }))
+                .min(1)
+                .max(50),
+            dryRun: z.boolean().optional().describe("Default TRUE — returns what would be created without writing.")
+        }
+    }, async ({ sessionId, records, dryRun }) => {
+        try {
+            const { alias: consultantOrg } = await resolveSessionOrg(await loadSession(sessionId), "campfire", { verify: false });
+            const names = records.map((r) => r.requirementName.trim());
+            const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+            if (dupes.length > 0)
+                return fail("BATCH_INVALID", `Duplicate requirementName(s) in the batch: ${[...new Set(dupes)].join(", ")}.`);
+            const existing = await query(consultantOrg, `SELECT Name, Requirement_Name__c FROM Campfire_Requirement__c WHERE Requirement_Name__c IN (${names.map((n) => `'${soqlEscape(n)}'`).join(",")})`);
+            if (existing.length > 0) {
+                return fail("TARGET_EXISTS", `Refusing: ${existing.length} name(s) already exist: ${existing.map((r) => `${String(r.Requirement_Name__c)} (${String(r.Name)})`).join(", ")}. A duplicated corpus in the shared org is tedious to unpick.`);
+            }
+            if (dryRun !== false) {
+                return ok([`DRY RUN — would create ${records.length} requirement(s) in ${consultantOrg}:`, ...names.map((n) => `  ${n}`), "", "Re-run with dryRun: false to create them."].join("\n"), { dryRun: true, wouldCreate: records.length, names });
+            }
+            await assertCampfireWriteAllowed(consultantOrg);
+            // NOT ESCAPED, and that is an OPEN QUESTION rather than a decision.
+            //
+            // The rich-text escaping added after the REQ-15736 swallow (see core/richText.ts) covers the
+            // three bodies whose fields are KNOWN rich text: the two notes fields, Configuration Item
+            // Description__c, and Deployment Task Description_Rich__c. These eleven CONTENT fields have
+            // never been type-described — MAX_LENGTHS' describe of 2026-07-31 measured lengths, not
+            // types — and the read side (session.ts stripRichText) runs HTML stripping over all of them
+            // DEFENSIVELY, which is evidence of nothing either way.
+            //
+            // Escaping is not the safe default here: on a plain Long Text Area it would store a literal
+            // `&lt;` where the author wrote `<`, which is the same corruption pointed the other way. So
+            // settle it before changing it — `describe_object {targetOrg: "campfire", objectApiName:
+            // "Campfire_Requirement__c"}` names each field's type — and escape exactly the ones that
+            // come back richtext. Corpus prose has not yet been seen to carry a `<`, which is why this
+            // is a recorded gap and not an incident.
+            const payload = records.map((r) => ({
+                attributes: { type: "Campfire_Requirement__c" },
+                Requirement_Stage__c: "Definition & Design",
+                Build_Status__c: "Not Started",
+                Requirement_Name__c: r.requirementName.trim(),
+                User_Story__c: r.userStory ?? null,
+                User_Story_Action__c: r.userStoryAction ?? null,
+                User_Story_Such_That__c: r.userStorySuchThat ?? null,
+                Acceptance_Criteria_Given__c: r.acceptanceCriteriaGiven ?? null,
+                Acceptance_Criteria_When__c: r.acceptanceCriteriaWhen ?? null,
+                Acceptance_Criteria_Then__c: r.acceptanceCriteriaThen ?? null,
+                Solution_Design_Summary__c: r.solutionDesignSummary ?? null,
+                Solution_Details__c: r.solutionDetails ?? null,
+                Requirement_Details__c: r.requirementDetails ?? null,
+                Expected_Results__c: r.expectedResults ?? null,
+                Pre_Requisite__c: r.preRequisite ?? null
+            }));
+            await restCollections(consultantOrg, "POST", payload, (i) => names[i] ?? `row ${i}`);
+            const created = await query(consultantOrg, `SELECT Name, Requirement_Name__c FROM Campfire_Requirement__c WHERE Requirement_Name__c IN (${names.map((n) => `'${soqlEscape(n)}'`).join(",")}) ORDER BY Name`);
+            // The read-back COUNTS rows, so "found none" and "created none" are the same number. Saying
+            // "created 0 requirement(s) — read-back confirmed" on a total failure is the create path's
+            // version of the batch-update lie, and it would have gone unnoticed for exactly as long.
+            if (created.length !== payload.length) {
+                return fail("WRITE_NOT_CONFIRMED", `Wrote ${payload.length} requirement(s) but read back ${created.length}. Missing: ${names.filter((n) => !created.some((r) => String(r.Requirement_Name__c) === n)).join(", ") || "(none by name — check for a rename)"}. Inspect before retrying; a blind retry risks duplicates for the ones that DID land.`);
+            }
+            return ok([`created ${created.length} requirement(s) — read-back confirmed:`, ...created.map((r) => `  ${String(r.Name)}  ${String(r.Requirement_Name__c)}`)].join("\n"), { created: created.length, requirements: created.map((r) => ({ name: String(r.Name), requirementName: String(r.Requirement_Name__c) })) });
+        }
+        catch (error) {
+            if (error instanceof GateError)
+                return fail(error.code, error.message);
+            if (error instanceof SessionOrgError)
+                return fail(error.code, error.message);
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+    // mirror_requirements — clone a whole test corpus under a new token.
+    //
+    // This exists because it kept being done BY HAND. Seven corpora (CF72 → CF78) were each produced
+    // by querying the previous set, substituting the token, and inserting the copies through the CLI —
+    // and doing it by hand is how a contaminant gets in: selecting the source by Name RANGE
+    // (REQ-15502..REQ-15516) once swept in an unrelated record that merely fell inside those bounds.
+    //
+    // Selecting by the CONTENT token instead is inherently safer: a record that does not carry the
+    // token is not part of the set, whatever its record Name happens to be.
+    server.registerTool("mirror_requirements", {
+        title: "Clone a requirement set under a new token",
+        description: "GATED (Campfire write + consultant-org allowlist — the org is REAL and SHARED). Copy every Campfire requirement whose Requirement_Name__c contains `from` into a NEW set with `from` replaced by `to` everywhere (name, user story, acceptance criteria, solution design). Used to stand up the next test corpus as a faithful mirror of the last, so two runs differ only by the build under test. Copies CONTENT only: stage resets to 'Definition & Design', status to 'Not Started', and no notes, Configuration Items or Deployment Tasks come across. Selects by CONTENT TOKEN, never by record-name range — a range sweeps in anything that happens to fall inside it. Refuses if any target already exists, so it cannot half-create a set or silently duplicate one. Run with dryRun first: it returns exactly what would be created.",
+        inputSchema: {
+            sessionId: z.string().describe("Session whose Campfire consultant org to write to."),
+            from: z.string().describe("Token identifying the SOURCE set, e.g. \"CF78\". Matched against Requirement_Name__c."),
+            to: z.string().describe("Token for the new set, e.g. \"CF79\". Replaced everywhere it appears in the copied text."),
+            alsoReplace: z
+                .array(z.object({ from: z.string(), to: z.string() }))
+                .optional()
+                .describe("Additional token pairs to substitute, e.g. [{from: \"IN78\", to: \"IN79\"}] for a second object family in the same corpus."),
+            dryRun: z.boolean().optional().describe("Default TRUE. Returns what would be created without writing. Pass false to actually create.")
+        }
+    }, async ({ sessionId, from, to, alsoReplace, dryRun }) => {
+        try {
+            const { alias: consultantOrg } = await resolveSessionOrg(await loadSession(sessionId), "campfire", { verify: false });
+            const pairs = [{ from, to }, ...(alsoReplace ?? [])];
+            const sub = (v) => {
+                if (v === null || v === undefined)
+                    return null;
+                let out = String(v);
+                for (const p of pairs)
+                    out = out.split(p.from).join(p.to);
+                return out;
+            };
+            const COPIED = MIRROR_COPIED_FIELDS;
+            const source = await query(consultantOrg, 
+            // External_ID__c comes along, but NOT via COPIED — it is unique, so it needs a rule the
+            // other fields do not have. See the guard below.
+            `SELECT Name, External_ID__c, ${COPIED.join(", ")} FROM Campfire_Requirement__c WHERE Requirement_Name__c LIKE '%${soqlEscape(from)}%' ORDER BY Name`);
+            if (source.length === 0) {
+                return fail("SOURCE_SET_EMPTY", `No Campfire requirement has ${JSON.stringify(from)} in its Requirement_Name__c. Nothing to mirror.`);
+            }
+            const existing = await query(consultantOrg, `SELECT Name, Requirement_Name__c FROM Campfire_Requirement__c WHERE Requirement_Name__c LIKE '%${soqlEscape(to)}%'`);
+            if (existing.length > 0) {
+                // Fail closed: a partial or duplicated corpus is worse than no corpus, and both are
+                // tedious to unpick in a shared org.
+                return fail("TARGET_SET_EXISTS", `${existing.length} requirement(s) already carry ${JSON.stringify(to)}: ${existing.slice(0, 5).map((r) => String(r.Name)).join(", ")}${existing.length > 5 ? ", …" : ""}. Refusing to create a second set. Pick a different token, or delete those first.`);
+            }
+            const planned = source.map((r) => {
+                const body = { Requirement_Stage__c: "Definition & Design", Build_Status__c: "Not Started" };
+                for (const f of COPIED)
+                    body[f] = sub(r[f]);
+                const sourceExtId = r.External_ID__c === null || r.External_ID__c === undefined ? null : String(r.External_ID__c);
+                const extId = sourceExtId === null ? null : sub(sourceExtId);
+                if (extId !== null)
+                    body.External_ID__c = extId;
+                return { sourceName: String(r.Name), name: String(body.Requirement_Name__c), sourceExtId, extId, body };
+            });
+            // EXTERNAL ID IS THE CORPUS IDENTITY, and the mirror used to drop it.
+            //
+            // Every requirement in a real corpus carries one (the EV battery is BLE-A-EV-01…50) and the
+            // Campfire list views key on it — so a mirrored set arrived with External_ID__c null and was
+            // invisible to every list, which is why the SM302 corpus sat in no list at all despite being
+            // minted correctly in every other respect.
+            //
+            // It cannot ride along in COPIED, because unlike every other copied field it is UNIQUE. Two
+            // rules follow, and both must fail closed:
+            const unchanged = planned.filter((p) => p.sourceExtId !== null && p.extId === p.sourceExtId);
+            if (unchanged.length > 0) {
+                // The token does not appear in the External ID, so copying it verbatim would either be
+                // rejected by the org as a duplicate or — worse, if the field is not enforced unique —
+                // silently produce two corpora sharing an identity.
+                return fail("EXTERNAL_ID_NOT_TOKENIZED", `${unchanged.length} source requirement(s) have an External ID that ${JSON.stringify(from)} does not appear in, ` +
+                    `so mirroring cannot make it unique: ${unchanged.slice(0, 5).map((p) => `${p.sourceName} (${p.sourceExtId})`).join(", ")}${unchanged.length > 5 ? ", …" : ""}. ` +
+                    `Add an alsoReplace pair covering the External ID's own token (e.g. {from: "BLE-A", to: "BLE-B"}), or the mirrored set will collide with its source.`);
+            }
+            const wantedExtIds = planned.map((p) => p.extId).filter((x) => Boolean(x));
+            if (wantedExtIds.length > 0) {
+                const taken = await query(consultantOrg, `SELECT Name, External_ID__c FROM Campfire_Requirement__c WHERE External_ID__c IN (${wantedExtIds.map((x) => `'${soqlEscape(x)}'`).join(", ")})`);
+                if (taken.length > 0) {
+                    return fail("TARGET_EXTERNAL_IDS_EXIST", `${taken.length} External ID(s) the mirror would create are already in use: ${taken.slice(0, 5).map((r) => String(r.External_ID__c)).join(", ")}${taken.length > 5 ? ", …" : ""}. ` +
+                        `The name check passed, so this is a set that was renamed without re-tokenizing its External IDs. Refusing rather than creating a second corpus under an identity that already means something.`);
+                }
+            }
+            if (dryRun !== false) {
+                return ok([
+                    `DRY RUN — would create ${planned.length} requirement(s) in ${consultantOrg} by mirroring ${from} -> ${to}${(alsoReplace ?? []).map((p) => ` and ${p.from} -> ${p.to}`).join("")}:`,
+                    ...planned.map((p) => `  ${p.sourceName} -> ${p.name}${p.extId ? `  [${p.sourceExtId} -> ${p.extId}]` : "  [no External ID on source]"}`),
+                    "",
+                    "Content only: stage resets to 'Definition & Design', status to 'Not Started'; no notes, Configuration Items or Deployment Tasks are copied.",
+                    "Re-run with dryRun: false to create them."
+                ].join("\n"), { dryRun: true, wouldCreate: planned.length, names: planned.map((p) => p.name) });
+            }
+            await assertCampfireWriteAllowed(consultantOrg);
+            const created = [];
+            const failed = [];
+            for (const p of planned) {
+                try {
+                    const res = await restWrite(consultantOrg, "POST", `/services/data/${API}/sobjects/Campfire_Requirement__c`, p.body);
+                    created.push(`${p.name} (${String(res?.id ?? "created")})`);
+                }
+                catch (error) {
+                    // Reported, not aborted: a half-created set is easier to finish than to diagnose.
+                    failed.push({ name: p.name, error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            return ok([
+                `Mirrored ${from} -> ${to}: ${created.length} created, ${failed.length} failed.`,
+                ...created.map((c) => `  ${c}`),
+                ...(failed.length ? ["", "FAILED:", ...failed.map((f) => `  ${f.name}: ${f.error}`)] : []),
+                "",
+                "Select them in Campfire and use Send to Target Org to start a run."
+            ].join("\n"), { created: created.length, failed, names: planned.map((p) => p.name) });
+        }
+        catch (error) {
+            if (error instanceof GateError)
+                return fail(error.code, error.message);
+            if (error instanceof SessionOrgError)
+                return fail(error.code, error.message);
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+}
+/**
+ * The Configuration Item / Deployment Task writeback surface — always registered.
+ *
+ * Split from `registerCampfireTools` only because the corpus pair above it is conditional; keeping
+ * these in one function with an `if` in the middle would put every tool after the flag inside the
+ * branch. Nothing here is gated by `CC_MCP_CORPUS_TOOLS`.
+ */
+function registerConfigItemTools(server) {
+    server.registerTool("campfire_config_item_plan", {
+        description: "DETERMINISTIC Configuration Item plan from direct_apply evidence bundles — no org contact, no gate, no guessing. The CI list and each row's description are COMPUTED from the submitted metadata, verdict, pre/post diff and independent post-org read. Every delivery of one component is retained in order; a matched read's derivation records the exact stated configuration, a mismatch records the OBSERVED org value, and a delivery with no authoritative read-back marks its row HELD — so nothing is ever published with the request standing in as fact. Crucially it EXPANDS CONTAINERS: a Configuration Item is one configurable COMPONENT, not one deployed FILE. It also returns requirementDisclosures: the observed-vs-approved deviations, grouped by requirement, FOR THE OPERATOR REVIEW — speak them, do not write them anywhere. Each one is scoped to that component's final delivery, the same rule the Configuration Item row's own description follows, so the two never disagree about what the record says. Takes the SAME sessionId as campfire_write_config_items: run this first, show the operator, then write the whole manifest with that one call.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .optional()
+                .describe("The session to plan. THE NORMAL INPUT — everything else is derived from it: the evidence bundles, and each requirement's plan.json ownership. Same value campfire_write_config_items takes, so preview and write are called identically."),
+            waves: z
+                .array(z.string())
+                .optional()
+                .describe("Restrict to these evidence-bundle LABELS (the `label` you passed direct_apply) — for INCREMENTAL writeback after each wave. Omit at end of run to cover the whole session. This matters: Campfire increments the requirement's Configuration Item counter on EVERY save, so re-deriving the full session after each wave inflates the counter on every requirement. An unknown label is an error, never a silent empty contribution."),
+            bundleDirs: z
+                .array(z.string())
+                .optional()
+                .describe("ESCAPE HATCH: explicit absolute bundle paths. Prefer `waves` (labels)."),
+            sessionDir: z
+                .string()
+                .optional()
+                .describe("ESCAPE HATCH: an explicit session workspace path, for a session directory that is not where sessionId would resolve. Prefer sessionId."),
+            ownership: z
+                .array(z.object({
+                typeName: z.string().describe("Metadata type as the deploy names it, e.g. CustomObject, CustomField."),
+                fullName: z.string().describe("Component fullName, e.g. IN72_Test_Console__c.Priority__c."),
+                extId: z.string().describe("The requirement that OWNS it, e.g. REQ-15412.")
+            }))
+                .optional()
+                .describe("Explicit component→requirement mapping, for components no plan.json claims (a batch run without per-requirement analyzers leaves none, and plan.json is what normally files each Configuration Item), and to resolve a reported OWNERSHIP_CONFLICT by naming ONE claiming requirement. Naming a requirement none of the claiming plans mentions is reported, not obeyed.")
+        }
+    }, async ({ sessionId, waves, bundleDirs, sessionDir, ownership }) => {
+        try {
+            // sessionId is the normal input; sessionDir stays an override. This tool used to take ONLY
+            // the path, while its writer took sessionId — so the documented "preview then write" pair
+            // could not be called with the same argument, and calling the preview the way the writer
+            // documents it returned NO_INPUT. Live-caught during the CF72 writeback.
+            const resolvedSessionDir = sessionDir ?? (sessionId ? sessionWorkspaceDir(sessionId) : undefined);
+            if (!bundleDirs?.length && !resolvedSessionDir) {
+                return fail("NO_INPUT", "Provide sessionId (bundles and ownership are discovered from it), or explicit bundleDirs.");
+            }
+            const derivation = await configItemsForSession({ sessionDir: resolvedSessionDir, bundleDirs, waves, ownership });
+            const { rows, unmapped, notes, ownershipGaps, ownershipSource, ownershipConflicts, bundlesRead, requirementDisclosures } = derivation;
+            // Fail closed on contested or unattributed rows. A Configuration Item filed against the wrong
+            // requirement (or none) is worse than no row at all: Campfire's manifest is what a consultant
+            // later reads to know what a requirement delivered, and a confidently wrong one is not
+            // self-correcting. CI accuracy is a measured success metric, so this refuses rather than
+            // emitting a list whose attribution someone has to reconstruct by hand. The refusal is the
+            // SAME function the write uses, so the preview cannot pass something the write will reject.
+            const refusal = ownershipRefusal({ rows, ownershipConflicts, ownershipSource });
+            if (refusal)
+                return fail(refusal.code, refusal.message);
+            // Delivery truth gates PER ROW, not per batch — the same split the write applies, so the
+            // preview shows exactly which rows will write and which will hold, with the remedy inline.
+            const held = heldForDeliveryTruth(rows);
+            const lines = [
+                // bundlesRead, NOT the bundleDirs input: on the recommended sessionDir path the input is
+                // empty because bundles are discovered, and echoing it read "derived from 0 bundle(s)"
+                // exactly when the most evidence had been consulted.
+                `${rows.length} Configuration Item(s) derived from ${bundlesRead.length} bundle(s) — attribution: ${ownershipSource.toUpperCase()}${ownershipSource === "supervisor" ? " (asserted by the supervisor, not computed from plan.json)" : ""}`,
+                ...rows.map((r) => {
+                    const parts = [`Type=${r.type}`, `API=${r.apiName}`];
+                    if (r.objectApiName)
+                        parts.push(`Object=${r.objectApiName}`);
+                    if (r.folderApiName)
+                        parts.push(`Folder=${r.folderApiName}`);
+                    if (r.destructive)
+                        parts.push("DESTRUCTIVE");
+                    if (r.origin !== "deployed")
+                        parts.push(r.origin.toUpperCase());
+                    else if (!r.verified)
+                        parts.push("UNVERIFIED");
+                    if (r.expandedFrom)
+                        parts.push(`from ${r.expandedFrom}`);
+                    if (r.deliveries?.length) {
+                        parts.push(`observed=${r.deliveries.map((delivery) => `${delivery.bundle}:${delivery.action}/${delivery.readBack}`).join(",")}`);
+                    }
+                    return `  - [${r.requirement ?? "UNOWNED"}] ${parts.join(" | ")}`;
+                }),
+                ...(unmapped.length ? ["", `UNMAPPED (${unmapped.length}) — resolve with the operator, never guess a Type:`, ...unmapped.map((u) => `  - ${u.component} [${u.bundle}]: ${u.reason}`)] : []),
+                ...(ownershipGaps.length ? ["", `OWNERSHIP GAPS (${ownershipGaps.length}):`, ...ownershipGaps.map((g) => `  - ${g.component}`)] : []),
+                ...(notes.length ? ["", "NOTES:", ...notes.map((n) => `  - ${n}`)] : []),
+                ...(requirementDisclosures.length
+                    ? [
+                        "",
+                        "DEVIATIONS TO RAISE IN THE REVIEW — each is already on its Configuration Item row; do not write these anywhere:",
+                        ...requirementDisclosures.map((disclosure) => `  - ${disclosure.requirement}: ${disclosure.text}`)
+                    ]
+                    : []),
+                "",
+                // An ABSOLUTE path, because the two places that named this guide used relative paths that
+                // resolve in the repo and nowhere else — so the doc the supervisor is told to read before
+                // finalising a writeback could not actually be opened from a session.
+                `Type mapping, field split and DEPENDENCY rules (what must ride along vs become a Deployment Task):`,
+                `  ${CI_GUIDE()}`,
+                "Read it before writing: a permission set granting FLS needs its fields in the same deployment,",
+                "reports and dashboards need their folders, an approval process needs its field updates and alerts.",
+                ...(held.length > 0
+                    ? [
+                        "",
+                        `HELD — ${held.length} row(s) whose delivery truth is unconfirmed will NOT be written by campfire_write_config_items (the rest write normally):`,
+                        ...held.map(({ row, reason }) => `  - ${row.metadataKey}: ${reason}`),
+                        DELIVERY_TRUTH_REMEDY
+                    ]
+                    : [])
+            ];
+            return ok(lines.join("\n"), {
+                rows,
+                heldForDeliveryTruth: held.map(({ row, reason }) => ({ metadataKey: row.metadataKey, reason })),
+                guide: CI_GUIDE(),
+                unmapped,
+                notes,
+                ownershipGaps,
+                ownershipSource,
+                ownershipConflicts,
+                requirementDisclosures
+            });
+        }
+        catch (error) {
+            if (error instanceof UnknownWaveError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+    server.registerTool("campfire_write_config_items", {
+        description: "GATED (Campfire write + allowlist). Write the ENTIRE evidence-derived Configuration Item manifest for a session in ONE call. campfire_config_item_plan is the exact preview: run it first, show the operator, then call this with the same sessionId/ownership. Each description states the component's identity, an observed projection of its final delivered configuration, any deviations from what was approved, and — for a row this run did not deploy — why it carries no delivery; it is a computed summary, not a log of every observed delivery or the full configuration the org holds. A HELD row is skipped and reported with its remedy while every confirmed row writes, so one ambiguous wave never strands the manifest. Stable component-derived External_ID__c values make re-runs update rather than duplicate. After every upsert, this tool re-reads the Campfire rows by external id and compares Requirement, Type, API/Object/Folder names and the full Description before reporting them confirmed. Per-row write or confirmation failures are named. This is the ONLY Configuration Item writer; corrections are re-derived, never hand-keyed.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .describe("The session to write back. The Campfire org and the evidence bundles both come from it."),
+            ownership: z
+                .array(z.object({
+                typeName: z.string(),
+                fullName: z.string(),
+                extId: z.string()
+            }))
+                .optional()
+                .describe("Same explicit component→requirement mapping campfire_config_item_plan accepts — for components no plan.json claims, and to resolve an OWNERSHIP_CONFLICT by naming one of the claiming requirements."),
+            waves: z
+                .array(z.string())
+                .optional()
+                .describe("Restrict to these evidence-bundle LABELS (the `label` you passed direct_apply) — for INCREMENTAL writeback after each wave. Omit at end of run to cover the whole session. This matters: Campfire increments the requirement's Configuration Item counter on EVERY save, so re-deriving the full session after each wave inflates the counter on every requirement. An unknown label is an error, never a silent empty contribution."),
+            skipExternalIds: z
+                .array(z.string())
+                .optional()
+                .describe("External ids to leave alone — use when some rows were already written under different keys and you do not want duplicates.")
+        }
+    }, async ({ sessionId, waves, ownership, skipExternalIds }) => {
+        try {
+            const session = await loadSession(sessionId);
+            const { alias: consultantOrg } = await resolveSessionOrg(session, "campfire", { verify: false });
+            await assertCampfireWriteAllowed(consultantOrg);
+            const sessionDir = path.dirname(sessionFile(sessionId));
+            const { rows: derivedRows, ownershipGaps, ownershipConflicts, ownershipSource, notes, requirementDisclosures } = await configItemsForSession({
+                sessionDir,
+                waves,
+                ownership
+            });
+            // Literally the same fail-closed contract as the preview — the same function, so the two
+            // cannot drift apart in what they consider writable, or in how they say why it is not.
+            const refusal = ownershipRefusal({ rows: derivedRows, ownershipConflicts, ownershipSource });
+            if (refusal)
+                return fail(refusal.code, refusal.message);
+            // Delivery truth holds PER ROW — one ambiguous wave must not strand every confirmed row in
+            // the session (the write loop's own doctrine, applied one gate earlier). Held rows are
+            // excluded from the write and reported with the remedy; everything confirmed writes.
+            const heldRows = heldForDeliveryTruth(derivedRows);
+            const heldKeys = new Set(heldRows.map(({ row }) => row.metadataKey));
+            const rows = derivedRows.filter((row) => !heldKeys.has(row.metadataKey));
+            const skip = new Set(skipExternalIds ?? []);
+            // `skip` is keyed by external id; the manifest counts rows, which are keyed by metadataKey.
+            const skippedKeys = rows.filter((row) => skip.has(configItemExternalId(row.metadataKey))).map((row) => row.metadataKey);
+            const written = [];
+            const failures = [];
+            let created = 0;
+            let updated = 0;
+            // A pre-existing row that carried no external id and was claimed by stamping ours onto it.
+            // Counted apart from created/updated because it is the visible trace of QA2-012 Cause B:
+            // adoptions mean unkeyed producers still exist somewhere.
+            let adopted = 0;
+            // Structured alongside the prose, because the prose alone does not reach every caller.
+            // Live-caught CF75: this returned {created:24, updated:0, failed:1, total:25} and nothing
+            // else — the failing row WAS named in the text, but a client rendering structuredContent
+            // showed only the counts. Identifying the row then took a per-requirement counter comparison
+            // and a scoped re-run, and it only worked because a first write makes count equal rows.
+            // Same defect class as sf_read putting query rows in text alone.
+            const failed = [];
+            // Requirements are looked up once, not once per row. 25 rows spread across 14 requirements
+            // meant 11 identical SOQL round-trips, and every one is an sf CLI process launch.
+            const resolveCache = new Map();
+            const resolveOnce = (requirement) => {
+                const hit = resolveCache.get(requirement);
+                if (hit)
+                    return hit;
+                const p = resolveRequirement(consultantOrg, requirement);
+                resolveCache.set(requirement, p);
+                return p;
+            };
+            // Rows are written CONCURRENTLY. Measured across four runs this tool was 27.6% of all time
+            // inside tools — 190s per call, ~7.6s per row — because each row cost a resolve query, an
+            // existence query and an upsert, serially, each one an sf CLI launch.
+            //
+            // Safe to parallelise: every row targets a DIFFERENT Configuration Item, keyed by an external
+            // id derived from its own component key, so no two rows contend. resolveRequirement and
+            // upsertByExternalId hold no mutable state between calls.
+            //
+            // Results are collected BY INDEX and rendered in the original order afterwards, so the report
+            // does not become non-deterministic just because the writes are not.
+            const slots = new Array(rows.length);
+            const expectedWrites = new Array(rows.length);
+            let cursor = 0;
+            const worker = async () => {
+                for (;;) {
+                    const i = cursor++;
+                    const row = rows[i];
+                    if (!row)
+                        return;
+                    const externalId = configItemExternalId(row.metadataKey);
+                    if (skip.has(externalId)) {
+                        slots[i] = { line: `  skipped  ${externalId}  ${row.metadataKey}` };
+                        continue;
+                    }
+                    try {
+                        const resolved = await resolveOnce(row.requirement);
+                        if (!resolved) {
+                            const reason = `requirement ${row.requirement} did not resolve`;
+                            failures.push(`  ${row.metadataKey}: ${reason}`);
+                            failed.push({ metadataKey: row.metadataKey, requirement: row.requirement, reason });
+                            continue;
+                        }
+                        const body = {
+                            Requirement__c: resolved.id,
+                            Configuration_Item_API_Name__c: row.apiName,
+                            // Null is load-bearing on UPDATE: a row that used to be object-specific or foldered
+                            // must not retain the old value when the delivered component is now global/bare.
+                            Object_API_Name__c: row.objectApiName ?? null,
+                            Report_Folder_API_Name__c: row.folderApiName ?? null,
+                            Type__c: row.type,
+                            Description__c: configItemDescription(row)
+                        };
+                        // The adoption identity mirrors the body's own component identity INCLUDING the
+                        // requirement parent — the unkeyed population is dominated by the client's
+                        // historical rows for other requirements, which must never be adopted.
+                        const result = await upsertByExternalId(consultantOrg, "Campfire_Configuration_Item__c", externalId, body, {
+                            Requirement__c: resolved.id,
+                            Type__c: String(row.type),
+                            Configuration_Item_API_Name__c: String(row.apiName),
+                            Object_API_Name__c: row.objectApiName ? String(row.objectApiName) : null
+                        });
+                        expectedWrites[i] = { externalId, metadataKey: row.metadataKey, body };
+                        slots[i] = {
+                            ok: result.action,
+                            line: `  ${result.action.padEnd(8)} ${externalId}  [${resolved.name}] ${row.type}/${row.apiName}`
+                        };
+                    }
+                    catch (error) {
+                        // One bad row must not strand the rest — the same reasoning as the projection fix.
+                        const reason = error instanceof Error ? error.message : String(error);
+                        failures.push(`  ${row.metadataKey}: ${reason}`);
+                        failed.push({ metadataKey: row.metadataKey, requirement: row.requirement, externalId, reason });
+                    }
+                }
+            };
+            // Per-requirement progress for the session viewer, BEFORE the first upsert: the loop runs
+            // concurrently over minutes, so without this every requirement reads as "not started" until
+            // the whole call returns. Rows a requirement will not get (held, skipped) are excluded from
+            // its count, so a requirement with nothing writable stays `pending` rather than claiming a
+            // write it never attempts. Fail-open — see core/writebackManifest.ts.
+            await writeWritebackManifest(sessionId, writebackManifestRows({
+                rows: derivedRows,
+                held: heldKeys,
+                skipped: skippedKeys,
+                at: isoNow()
+            }));
+            await Promise.all(Array.from({ length: Math.min(WRITE_CONCURRENCY, rows.length) }, worker));
+            // The target-org read-back established what was delivered; this second read establishes
+            // that Campfire now says the same thing. A successful PATCH is only a claim until every CI
+            // field — especially the evidence-derived Description__c — is observed back by external id.
+            const expected = expectedWrites.filter((item) => Boolean(item));
+            if (expected.length > 0) {
+                let stored = [];
+                let readError;
+                try {
+                    for (let i = 0; i < expected.length; i += 100) {
+                        const chunk = expected.slice(i, i + 100);
+                        stored = stored.concat(await query(consultantOrg, `SELECT External_ID__c, Requirement__c, Configuration_Item_API_Name__c, Object_API_Name__c, Report_Folder_API_Name__c, Type__c, Description__c ` +
+                            `FROM Campfire_Configuration_Item__c WHERE External_ID__c IN (${chunk.map((item) => `'${soqlEscape(item.externalId)}'`).join(",")})`));
+                    }
+                }
+                catch (error) {
+                    readError = error instanceof Error ? error.message : String(error);
+                }
+                const problems = readError
+                    ? expected.map((item) => ({
+                        externalId: item.externalId,
+                        metadataKey: item.metadataKey,
+                        field: "read-back",
+                        expected: "(confirmed)",
+                        observed: readError
+                    }))
+                    : configItemReadBackProblems(expected, stored);
+                const byExternalId = new Map();
+                for (const problem of problems) {
+                    const list = byExternalId.get(problem.externalId) ?? [];
+                    list.push(problem);
+                    byExternalId.set(problem.externalId, list);
+                }
+                for (const [externalId, rowProblems] of byExternalId) {
+                    const i = expectedWrites.findIndex((item) => item?.externalId === externalId);
+                    const row = i >= 0 ? rows[i] : undefined;
+                    const fields = rowProblems.map((problem) => problem.field).join(", ");
+                    const reason = `write landed but Campfire read-back did not confirm: ${fields}`;
+                    failures.push(`  ${row?.metadataKey ?? externalId}: ${reason}`);
+                    failed.push({ metadataKey: row?.metadataKey ?? externalId, requirement: row?.requirement, externalId, reason });
+                    if (i >= 0)
+                        slots[i] = { line: `  unconfirmed ${externalId}  ${row?.metadataKey ?? ""}  (${fields})` };
+                }
+            }
+            // The closing pass, after the read-back — an upsert that returned 200 is only a claim until
+            // Campfire is observed saying the same thing, so `written` cannot be asserted any earlier.
+            await writeWritebackManifest(sessionId, writebackManifestRows({
+                rows: derivedRows,
+                held: heldKeys,
+                skipped: skippedKeys,
+                failedRequirements: failed.map((f) => String(f.requirement ?? "")).filter(Boolean),
+                done: true,
+                at: isoNow()
+            }));
+            for (const slot of slots) {
+                if (!slot)
+                    continue;
+                if (slot.ok === "created")
+                    created += 1;
+                else if (slot.ok === "updated")
+                    updated += 1;
+                else if (slot.ok === "adopted")
+                    adopted += 1;
+                if (slot.line)
+                    written.push(slot.line);
+            }
+            const lines = [
+                `${created} created, ${updated} updated${adopted ? `, ${adopted} adopted (pre-existing unkeyed rows claimed by external id)` : ""}, ${failures.length} failed of ${rows.length} writable row(s)${heldRows.length ? ` (+${heldRows.length} held)` : ""} — attribution: ${ownershipSource.toUpperCase()}`,
+                ...written,
+                ...(failures.length ? ["", `FAILED (${failures.length}) — these rows are absent or NOT CONFIRMED in Campfire:`, ...failures] : []),
+                ...(heldRows.length
+                    ? [
+                        "",
+                        `HELD (${heldRows.length}) — delivery truth unconfirmed, NOT written (every other row wrote normally):`,
+                        ...heldRows.map(({ row, reason }) => `  - ${row.metadataKey}: ${reason}`),
+                        DELIVERY_TRUTH_REMEDY
+                    ]
+                    : []),
+                ...(ownershipGaps.length ? ["", `ownership gaps: ${ownershipGaps.length}`] : []),
+                ...(notes.length ? ["", "NOTES:", ...notes.map((n) => `  - ${n}`)] : []),
+                ...(requirementDisclosures.length
+                    ? [
+                        "",
+                        "DEVIATIONS TO RAISE IN THE REVIEW — each is already on its Configuration Item row; do not write these anywhere:",
+                        ...requirementDisclosures.map((disclosure) => `  - ${disclosure.requirement}: ${disclosure.text}`)
+                    ]
+                    : [])
+            ];
+            // WHAT LANDED IN CAMPFIRE, per write. The ledger previously saw only aggregate counts on
+            // the tool call, so "24 created, 1 failed" could not be turned into "which requirement is
+            // short a configuration item" — the first thing an operator asks. Identifiers only; no note
+            // bodies, no field values.
+            emitDomainTelemetryEvent("writeback.completed", {
+                created,
+                updated,
+                adopted,
+                failed: failures.length,
+                total: rows.length,
+                ...(failed.length > 0
+                    ? {
+                        failedRows: failed.slice(0, 200).map((f) => ({
+                            ...(f.metadataKey !== undefined ? { metadataKey: String(f.metadataKey) } : {}),
+                            ...(f.requirement !== undefined ? { requirement: String(f.requirement) } : {}),
+                            ...(f.externalId !== undefined ? { externalId: String(f.externalId) } : {})
+                        }))
+                    }
+                    : {}),
+                ...(heldRows.length > 0
+                    ? { heldRows: heldRows.slice(0, 200).map(({ row }) => ({ metadataKey: String(row.metadataKey) })) }
+                    : {}),
+                // `.map((g) => g.component)`, NOT `.map(String)`. A gap is `{component, reason}`, so
+                // stringifying the object recorded the literal "[object Object]" for every one of them
+                // — a legal 15-character string that passes the shape check cleanly, so the ledger
+                // filled with an identical meaningless token and nothing failed. The `reason` is prose
+                // and stays off the wire; the component key is the identifier this event exists to
+                // carry. The operator-facing render one screen up already did this correctly.
+                ...(ownershipGaps.length > 0
+                    ? { ownershipGaps: ownershipGaps.slice(0, 200).map((gap) => gap.component) }
+                    : {})
+            }, { stage: "writeback", outcome: failures.length === 0 && heldRows.length === 0 ? "ok" : "partial" });
+            return ok(lines.join("\n"), {
+                created,
+                updated,
+                adopted,
+                failed: failures.length,
+                total: rows.length,
+                // The rows themselves, not merely how many. A count of failures you cannot identify is
+                // indistinguishable from a count you cannot trust.
+                ...(failed.length > 0 ? { failures: failed } : {}),
+                ...(heldRows.length > 0
+                    ? {
+                        heldForDeliveryTruth: heldRows.map(({ row, reason }) => ({ metadataKey: row.metadataKey, reason })),
+                        remedy: DELIVERY_TRUTH_REMEDY
+                    }
+                    : {}),
+                ...(ownershipGaps.length > 0 ? { ownershipGaps } : {}),
+                ...(requirementDisclosures.length > 0 ? { requirementDisclosures } : {})
+            });
+        }
+        catch (error) {
+            if (error instanceof UnknownWaveError)
+                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);
+            return internalError(error);
+        }
+    });
+    // ONE task writer, taking an array. The CF63 run wrote NINE tasks one at a time at the very end
+    // of a long session — nine round trips, nine timeout exposures, and nine chances to stop
+    // half-done with the manual work only partly recorded. Manual work is the single most important
+    // output for a delivery firm (it is what a human still has to do), so a partial write there is
+    // the worst place to have one. Filing one task is an array of one.
+    //
+    // Upsert through /composite/sobjects/<Object>/<ExternalIdField>, so idempotency is the ORG's job
+    // rather than a read-then-write race: re-running the same batch updates in place.
+    server.registerTool("create_campfire_deployment_tasks", {
+        title: "File Campfire Deployment Tasks for work a human must do",
+        description: "GATED (Campfire write + allowlist). Create/update Campfire_Deployment_Task__c rows — the todo surface for work a human must do (manual verifications, unset defaults, dependency wiring the toolchain can't deploy). Idempotent via External_ID__c (<=18 chars), executed as ONE all-or-none sObject-Collections UPSERT; the manual-work list is normally written in one go at the end of a delivery, and one task is an array of one. Re-running an identical batch is a no-op update, not a duplicate. The task's only text surface is Description_Rich__c (Name is an auto-number): `description` becomes its bold first line, `richDescription` the body. Every row is validated locally before anything is written; refuses on `TASKS_INVALID` / `REQUIREMENT_NOT_FOUND`. FILE A TASK ONLY FOR WHAT YOU COULD NOT DEPLOY — check the post projection rather than assuming.",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .describe("The session this writeback belongs to. The Campfire consultant org comes FROM the session — bound at import — so a write cannot be aimed at the wrong org by restating an alias."),
+            tasks: z
+                .array(z.object({
+                requirement: z.string().describe("REQ-####, EXT-####, or record Id the task belongs to."),
+                externalId: z.string().describe("Idempotency key, <=18 chars [A-Za-z0-9_-]. Must be unique WITHIN this batch too."),
+                description: z.string().describe("Short one-line summary — the bold first line of Description_Rich__c."),
+                richDescription: z.string().optional().describe("Full instructions (steps, evidence links) — the body of Description_Rich__c."),
+                type: DEPLOYMENT_TASK_TYPE.optional().describe("Type__c (RESTRICTED picklist, 14 active values, verified live). Pick the value that NAMES the work; prefer a specific one over 'Other' (which then REQUIRES otherType)."),
+                otherType: z.string().optional().describe("Other_Type__c — REQUIRED by org validation when type is 'Other' (live-caught FIELD_CUSTOM_VALIDATION_EXCEPTION)."),
+                prePost: z
+                    .enum(["-N/A-", "Post-Deployment", "Pre-Deployment"])
+                    .optional()
+                    .describe("Pre_Post_Deployment__c. 'Pre-Deployment' for work that must happen BEFORE the metadata lands (Certinia data-backed components); 'Post-Deployment' for wiring after it (assignments, activations, memberships)."),
+                status: z
+                    .enum(["Not Started", "In Progress", "Blocked", "Complete", "Deprecated"])
+                    .optional()
+                    .describe("Status__c. A task this run is handing to a human starts 'Not Started'."),
+                taskKind: MANUAL_TASK_KIND.optional().describe("WHAT KIND OF LABOUR this is, for the automation-lever analysis — NOT the Salesforce artefact (`type` already names that). config = Setup clicks producing configuration; verification = someone confirming something by looking; data = creating/editing/loading records; release = activation, sequencing, release mechanics; external = work in another system; other = none of those. Not written to Campfire; it rides the telemetry event, and nobody can recover it later from a description."),
+                expectedMinutes: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(2_400)
+                    .optional()
+                    .describe("YOUR estimate of how long this task takes a human, in minutes. It is the denominator of the lever analysis (frequency x minutes by kind), so a rough honest number beats an omission — but do not invent one for work you cannot size. Not written to Campfire; it rides the telemetry event."),
+                sequence: z.number().optional()
+            }))
+                .min(1)
+                .describe("The tasks to file. One call per delivery is the intended shape.")
+        }
+    }, async ({ sessionId, tasks }) => {
+        try {
+            const { alias: consultantOrg } = await resolveSessionOrg(await loadSession(sessionId), "campfire", { verify: false });
+            await assertCampfireWriteAllowed(consultantOrg);
+            const problems = checkDeploymentTasks(tasks);
+            if (problems.length > 0)
+                return fail("TASKS_INVALID", `Nothing written. ${problems.length} problem(s):\n  ${problems.join("\n  ")}`);
+            // Resolve every requirement in at most TWO queries — the same helper the batch read uses.
+            // This used to loop the single-reference resolver once per distinct requirement while a
+            // comment above it claimed one query, which is two sf CLI launches per requirement on the
+            // one write a run makes at the very end of a long session.
+            const { resolved } = await resolveRequirements(consultantOrg, [...new Set(tasks.map((t) => t.requirement))]);
+            // Keyed off membership in `resolved` rather than the reported unresolved list, so a
+            // reference that fell out for ANY reason refuses the whole batch instead of being filed
+            // against the wrong requirement.
+            const unresolvedRefs = [...new Set(tasks.map((t) => t.requirement).filter((r) => !resolved.has(r)))];
+            if (unresolvedRefs.length > 0) {
+                return fail("REQUIREMENT_NOT_FOUND", `Nothing written. Did not resolve to exactly one Campfire_Requirement__c: ${unresolvedRefs.join(", ")}.`);
+            }
+            const records = tasks.map((t) => {
+                return {
+                    attributes: { type: "Campfire_Deployment_Task__c" },
+                    External_ID__c: t.externalId,
+                    Campfire_Requirement__c: resolved.get(t.requirement).id,
+                    Description_Rich__c: deploymentTaskRichDescription(t.description, t.richDescription),
+                    ...(t.type ? { Type__c: t.type } : {}),
+                    ...(t.otherType ? { Other_Type__c: t.otherType } : {}),
+                    ...(t.prePost ? { Pre_Post_Deployment__c: t.prePost } : {}),
+                    ...(t.status ? { Status__c: t.status } : {}),
+                    ...(t.sequence !== undefined ? { Sequence__c: t.sequence } : {})
+                };
+            });
+            await restCollections(consultantOrg, "PATCH", records, (i) => `${tasks[i]?.externalId ?? `row ${i}`} (${resolved.get(tasks[i]?.requirement ?? "")?.name ?? "?"})`, `/services/data/${API}/composite/sobjects/Campfire_Deployment_Task__c/External_ID__c`);
+            // One read-back for the whole batch, by the key the org upserted on.
+            const back = await query(consultantOrg, `SELECT Id, External_ID__c FROM Campfire_Deployment_Task__c WHERE External_ID__c IN (${tasks.map((t) => `'${soqlEscape(t.externalId)}'`).join(",")})`);
+            const byExt = new Map(back.map((r) => [String(r.External_ID__c), String(r.Id)]));
+            const missing = tasks.filter((t) => !byExt.has(t.externalId)).map((t) => t.externalId);
+            if (missing.length > 0) {
+                return fail("WRITE_NOT_CONFIRMED", `Salesforce accepted the batch but ${missing.length} task(s) did not read back: ${missing.join(", ")}. Inspect before retrying.`);
+            }
+            // One manual-work event per task — this is the only writer (the singular twin was merged
+            // away in #5), and it is what makes the outstanding-manual-work inventory reconstructable
+            // at all. `taskKind` and `expectedMinutes` are shape, never prose: the enum and the bounded
+            // integer are refused by `convex/lib/events.ts` if they are anything else.
+            for (const t of tasks) {
+                emitDomainTelemetryEvent("manual_work.recorded", {
+                    taskId: byExt.get(t.externalId) ?? "",
+                    requirementId: resolved.get(t.requirement).name,
+                    ...(t.type ? { componentType: t.type } : {}),
+                    ...(t.taskKind ? { taskKind: t.taskKind } : {}),
+                    ...(t.expectedMinutes !== undefined ? { expectedMinutes: t.expectedMinutes } : {})
+                }, { stage: "writeback", outcome: "recorded" });
+            }
+            return ok([`filed ${tasks.length} deployment task(s) in one call — read-back confirmed:`, ...tasks.map((t) => `  ${resolved.get(t.requirement).name}  ${t.externalId}: ${t.description}`)].join("\n"), { filed: tasks.length, tasks: tasks.map((t) => ({ externalId: t.externalId, id: byExt.get(t.externalId), requirement: resolved.get(t.requirement).name })) });
+        }
+        catch (error) {
+            if (error instanceof UnknownWaveError)
+                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);
+            return internalError(error);
+        }
+    });
+}