in2-agent-server 0.20260821.185429

package/dist/core/semanticHash.js

@@ -0,0 +1,89 @@
+// Stable content fingerprinting — the one thing cc-mcp used @in2/contracts for.
+//
+// @in2/contracts is a 3,191-line platform-wide schema package (zod schemas for the certified
+// pipeline's neutral protocol). The direct tier used exactly one function out of it. Carrying the
+// whole package — and zod with it — to get a sha256 of a sorted object was not a dependency, it was
+// an accident of where the code happened to live.
+//
+// Ported VERBATIM rather than simplified, deliberately. These hashes are truncated into session ids
+// (`ses_844e89ff…`) that are already persisted on disk, so any behavioural drift here silently
+// orphans existing sessions. semanticHash.test.ts pins the exact digests to catch that.
+import { createHash } from "node:crypto";
+/** Recursively sort object keys and drop undefined values, so key order cannot change a digest. */
+export function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortJson);
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, v]) => typeof v !== "undefined")
+            .sort(([a], [b]) => a.localeCompare(b));
+        const out = {};
+        for (const [k, v] of entries)
+            out[k] = sortJson(v);
+        return out;
+    }
+    return value;
+}
+export function stableStringify(value) {
+    return JSON.stringify(sortJson(value));
+}
+const NEUTRAL_PROTOCOL_SCHEMA_VERSION = "1.0.0";
+// Upstream shape table, kept intact. cc-mcp never constructs these records, so in practice this
+// only ever matters at depth 0 (where stripping is unconditional). It is retained anyway because
+// the cost is a dead lookup and the benefit is digest-for-digest identity with the original.
+const NEUTRAL_PROTOCOL_RECORD_SHAPES = [
+    ["requirementId", "currentRevisionId", "createdAt"],
+    ["revisionId", "requirementId", "revisionNumber", "source"],
+    ["batchId", "currentRevisionId", "sourceType"],
+    ["revisionId", "batchId", "requirementRevisionIds"],
+    ["subrequirementId", "currentRevisionId", "sourceRequirementIds"],
+    ["revisionId", "subrequirementId", "acceptanceConditions"],
+    ["resultId", "sessionId", "requirementRevisionId", "proposedSubrequirements"],
+    ["revisionId", "sessionId", "analyzerResultIds", "canonicalSubrequirements"],
+    ["sessionId", "requirementBatchRevisionId", "state", "executionMode"],
+    ["eventId", "sessionId", "sequence", "payload"],
+    ["planId", "planVersionId", "sessionId", "expectedOutcomes"],
+    ["approvalId", "sessionId", "coveredPlanVersionIds"],
+    ["observationId", "sessionId", "scope", "values"],
+    ["requestId", "sessionId", "executionUnit", "allowedOperationScope"],
+    ["receiptId", "requestId", "componentResults", "terminalTransportStatus"],
+    ["requestId", "subrequirementId", "expectedOutcomes", "observationScope"],
+    ["resultId", "requestId", "postObservationId", "comparisons"],
+    ["sessionId", "subrequirementId", "basisReferences", "settledAt"],
+    ["snapshotId", "sessionId", "counts", "rates"],
+    ["benchmarkId", "revisionId", "frozenDenominatorSubrequirementIds"],
+    ["attemptId", "benchmarkRevisionId", "engine"],
+    ["envelopeId", "payload", "redaction", "subjectReferences"]
+];
+function isNeutralProtocolRecord(record) {
+    return (record.schemaVersion === NEUTRAL_PROTOCOL_SCHEMA_VERSION &&
+        NEUTRAL_PROTOCOL_RECORD_SHAPES.some((shape) => shape.every((key) => Object.hasOwn(record, key))));
+}
+function semanticIdentityPayloadAtDepth(value, depth) {
+    if (Array.isArray(value))
+        return value.map((entry) => semanticIdentityPayloadAtDepth(entry, depth + 1));
+    if (value && typeof value === "object") {
+        const record = value;
+        const protocolRecord = depth === 0 || isNeutralProtocolRecord(record);
+        const output = {};
+        for (const [key, child] of Object.entries(record)) {
+            // Drop the envelope's own bookkeeping so stamping last run's hash onto a record does not
+            // change what the record means — the "semantic" in the name.
+            if (protocolRecord && (key === "nonFunctionalMetadata" || key === "contentHash"))
+                continue;
+            output[key] = semanticIdentityPayloadAtDepth(child, depth + 1);
+        }
+        return output;
+    }
+    return value;
+}
+export function semanticIdentityPayload(value) {
+    return semanticIdentityPayloadAtDepth(value, 0);
+}
+export function sha256Json(value) {
+    return createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+/** Stable 64-char hex fingerprint of a value, independent of key order. */
+export function semanticContentHash(value) {
+    return sha256Json(semanticIdentityPayload(value));
+}

package/dist/core/sessionOrg.js

@@ -0,0 +1,60 @@
+// Resolve WHICH org a tool acts on, from the session rather than from a caller-supplied alias.
+//
+// The session is the source of truth for an engagement: it owns the org binding that
+// activate_session verified, the imported requirements, the analysis, and the evidence. Tools that
+// took a bare `targetOrg` were asking the model to re-state something the session already knows,
+// and an alias is the weakest possible form of that answer — `org_login`'s own description says an
+// alias is "operator-controlled and can be repointed".
+//
+// So the alias is treated as a POINTER, and this module is where the pointer is checked against
+// what the session recorded. A repointed alias is the failure this exists to name: without the
+// check it surfaces as a confusing "org not allowlisted" (the grant no longer matches), which sends
+// someone hunting through gate config for what is actually a changed alias.
+import { GateError } from "./gate.js";
+import { defaultOrgIdResolver } from "./gate.js";
+export class SessionOrgError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SessionOrgError";
+    }
+}
+function bindingFor(session, role) {
+    return role === "target" ? session.targetOrg : session.campfireOrg ?? null;
+}
+/**
+ * The org this session is bound to for `role`, with the alias re-checked against the recorded id.
+ *
+ * `verify: false` skips the live check for read-only callers that would rather not pay an
+ * `sf org display` round-trip; writes always verify, because a repointed alias on a write is the
+ * case where being wrong is expensive.
+ */
+export async function resolveSessionOrg(session, role, opts = {}) {
+    const binding = bindingFor(session, role);
+    if (!binding?.alias) {
+        throw new SessionOrgError("ORG_NOT_BOUND", role === "target"
+            ? `Session ${session.sessionId} has no target org bound. Redeem a Campfire code with activate_session, or bind one with create_session { targetOrgAlias, targetOrgId }.`
+            : `Session ${session.sessionId} has no Campfire (consultant) org bound. Import from Campfire first — import_requirements { campfire: { consultantOrg, names } } records it.`);
+    }
+    if (opts.verify === false)
+        return binding;
+    // Verification compares the alias against a RECORDED id. Without one there is nothing to compare,
+    // and quietly returning would turn "unverified" into "verified" — so it refuses instead.
+    if (!binding.orgId) {
+        throw new SessionOrgError("ORG_NOT_BOUND", `Session ${session.sessionId} has alias ${JSON.stringify(binding.alias)} for its ${role} org but no recorded Org ID, so the binding cannot be verified. Refusing fail-closed.`);
+    }
+    const resolver = opts.resolveOrgId ?? defaultOrgIdResolver;
+    const live = await resolver(binding.alias);
+    if (!live) {
+        // Deliberately a GateError: the caller's fail-closed handling for "we cannot tell which org
+        // this is" already exists and is the correct response here too.
+        throw new GateError("ORG_ID_UNRESOLVED", `Session ${session.sessionId} is bound to alias ${JSON.stringify(binding.alias)} (org ${binding.orgId}), but that alias does not resolve — it may have been logged out. Re-authenticate it, then retry. Refusing fail-closed.`);
+    }
+    if (live.slice(0, 15) !== binding.orgId.slice(0, 15)) {
+        throw new SessionOrgError("ALIAS_REPOINTED", `Alias ${JSON.stringify(binding.alias)} now points at org ${live}, but session ${session.sessionId} was bound to ${binding.orgId}. Refusing — an alias is operator-controlled and can be repointed, and acting on the new one would apply this session's work to a different org than it was approved against.`);
+    }
+    // Return the session's recorded id, not the freshly resolved one: they are equal here, and using
+    // the recorded value keeps the session the single authority.
+    return binding;
+}

package/dist/core/sfQuery.js

@@ -0,0 +1,19 @@
+// `sf data query --json` exits 0 after silently capping results at SF_ORG_MAX_QUERY_LIMIT
+// (default 10,000): a truncated read is indistinguishable from a complete one by exit code, and
+// every call site that trusted `result.records` alone would report a short list as the whole
+// answer. The envelope's `done` and `totalSize` are the only truncation signals the CLI gives.
+//
+// Returns a human-readable verdict when the read is provably incomplete, null otherwise. The
+// guard acts only on a POSITIVE signal — an envelope that omits both counters (older plugin
+// shapes, some tooling-API arms) makes no claim, and refusing it would fail-closed on every read.
+export function sfQueryTruncation(parsed) {
+    const result = parsed?.result;
+    const records = result?.records ?? [];
+    const totalSize = result?.totalSize;
+    if (result?.done === false || (typeof totalSize === "number" && totalSize > records.length)) {
+        return (`query returned ${records.length} of ${typeof totalSize === "number" ? totalSize : "an unreported total"} records — ` +
+            `sf data query silently caps at SF_ORG_MAX_QUERY_LIMIT (default 10,000) and still exits 0. ` +
+            `The result is INCOMPLETE and must not be read as the full answer.`);
+    }
+    return null;
+}

package/dist/core/spawn.js

@@ -0,0 +1,182 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync, openSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { recordOrgCall } from "./orgCallMeter.js";
+// Environment for spawned `sf` CLI children. Two hazards, both live-caught:
+// (1) .env.local names (SF_CLIENT_ID etc.) collide with sf CLI config vars and
+//     break auth resolution (documented in the writeback runbook);
+// (2) the CLI's update check / telemetry do network I/O at startup and have been
+//     observed stalling a child past its kill timeout inside the MCP server.
+export function sfCliEnv() {
+    const env = { ...process.env };
+    delete env.SF_CLIENT_ID;
+    delete env.SF_CLIENT_SECRET;
+    delete env.SF_LOGIN_URL;
+    delete env.SF_REDIRECT_URI;
+    delete env.NODE_ENV;
+    env.SF_DISABLE_AUTOUPDATE = "true";
+    env.SF_AUTOUPDATE_DISABLE = "true";
+    env.SF_SKIP_NEW_VERSION_CHECK = "true";
+    env.SF_DISABLE_TELEMETRY = "true";
+    return env;
+}
+// On Windows, `sf` is not an executable. Every way it lands on a machine — the private npm prefix
+// this payload installs, a consultant's own `npm i -g`, or Salesforce's Windows installer — puts a
+// cmd shim (sf.cmd) on PATH, and a cmd shim cannot be spawned directly: CreateProcess resolves only
+// .exe/.com, and Node refuses .cmd/.bat without a shell outright (CVE-2024-27980). shell:true is
+// not the fix — cmd.exe would re-tokenise every argument, and sf arguments carry SOQL with quotes
+// and spaces. So the shim is resolved to the JavaScript entry it wraps and run with THIS process's
+// node, which changes nothing about how sf behaves and everything about whether it starts.
+//
+// CC_MCP_SF_ENTRY (set by the generated Windows launcher) short-circuits the scan; without it the
+// PATH is walked for sf.exe (runnable as-is) or a parseable sf.cmd.
+export function jsEntryFromCmdShim(shimText, shimDir) {
+    // npm's cmd-shim invokes `"%_prog%"  "%dp0%\node_modules\<pkg>\bin\run.js" %*` (older shims spell
+    // it %~dp0); oclif's Windows installer invokes `"%~dp0\..\client\bin\node.exe" "...\run.js"`.
+    // Both name the entry as a "-quoted .js path relative to the shim's own directory.
+    const m = /"%(?:~)?dp0%?\\?([^"]+\.js)"/i.exec(shimText);
+    if (!m)
+        return undefined;
+    return path.resolve(shimDir, m[1]);
+}
+let cachedSf = null;
+function resolveWindowsSf() {
+    const entry = process.env.CC_MCP_SF_ENTRY?.trim();
+    if (entry && existsSync(entry))
+        return { command: process.execPath, prefixArgs: [entry] };
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const exe = path.join(dir, "sf.exe");
+        if (existsSync(exe))
+            return { command: exe, prefixArgs: [] };
+        const shim = path.join(dir, "sf.cmd");
+        if (!existsSync(shim))
+            continue;
+        try {
+            const target = jsEntryFromCmdShim(readFileSync(shim, "utf8"), dir);
+            if (target && existsSync(target))
+                return { command: process.execPath, prefixArgs: [target] };
+        }
+        catch {
+            // Unreadable or unparseable shim — keep scanning; a later PATH entry may carry a usable one.
+        }
+    }
+    // Nothing resolved: return the bare name and let the spawn fail with ENOENT, which every caller
+    // already surfaces as a clear "sf is not available" error.
+    return { command: "sf", prefixArgs: [] };
+}
+export function sfInvocation(args) {
+    // CC_MCP_SF_ENTRY is honored on EVERY platform, not only Windows. `in2 setup` installs
+    // @salesforce/cli into a private prefix (~/.in2-agent/tools) when the machine has no sf, and the
+    // server's spawn environment — fixed by the MCP client, not by setup's shell — has no reason to
+    // carry that directory on PATH. The registered entry is the one channel that reliably reaches
+    // this process, so a bare-name resolution here would pass setup's own probe and then ENOENT on
+    // the first real deploy (adversarial review, 2026-08-21).
+    const entry = process.env.CC_MCP_SF_ENTRY?.trim();
+    if (entry && existsSync(entry))
+        return { command: process.execPath, args: [entry, ...args] };
+    if (process.platform !== "win32")
+        return { command: "sf", args };
+    if (!cachedSf)
+        cachedSf = resolveWindowsSf();
+    return { command: cachedSf.command, args: [...cachedSf.prefixArgs, ...args] };
+}
+const MAX_BUFFER = 64 * 1024 * 1024;
+// Fire-and-forget child that OUTLIVES this call. `sf org login web` blocks until the human
+// finishes the browser round-trip, which an MCP tool call cannot wait on (a client timeout
+// would kill the login mid-flow and leave no auth file). So we detach it, tee its output to a
+// log the status tool can read, and let the CLI's own localhost callback listener do its job.
+// Returns the pid; the AUTHORITY on whether login succeeded is always a fresh `sf org display`.
+export function spawnDetached(command, args, options) {
+    if (command === "sf")
+        ({ command, args } = sfInvocation(args));
+    const fd = openSync(options.logFile, "a");
+    const child = spawn(command, args, {
+        env: options.env ?? process.env,
+        detached: true,
+        stdio: ["ignore", fd, fd]
+    });
+    child.unref();
+    return { pid: child.pid };
+}
+export function runProcess(command, args, options) {
+    // METERED HERE, before resolution, for the same reason resolution itself is centralised here:
+    // this is the one funnel every `sf` launch passes through, and on Windows the resolved command is
+    // `node` (an sf.cmd shim cannot be spawned directly — see sfInvocation), so a meter reading the
+    // RESOLVED name would count zero sf spawns on precisely the platform whose spawn cost is the
+    // question. The caller's own word is the reliable signal.
+    const meterAsSf = command === "sf";
+    // Centralised here so nine call sites across five modules keep saying `runProcess("sf", …)` and
+    // never learn what sf resolves to on this platform.
+    if (command === "sf")
+        ({ command, args } = sfInvocation(args));
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        // `encoding: "buffer"` makes execFile hand back Buffers, which is the only way to keep an exact
+        // byte count; the text form is then decoded from the same bytes so every existing caller sees
+        // precisely what it saw before. Off by default so the common path allocates one string, not two.
+        const binary = options.binary === true;
+        const child = execFile(command, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            timeout: options.timeoutMs,
+            killSignal: "SIGKILL",
+            maxBuffer: MAX_BUFFER,
+            ...(binary ? { encoding: "buffer" } : { encoding: "utf8" })
+        }, (error, rawStdout, rawStderr) => {
+            const durationMs = Date.now() - startedAt;
+            const stdoutBuffer = binary ? rawStdout : undefined;
+            const stdout = binary ? (stdoutBuffer?.toString("utf8") ?? "") : (rawStdout ?? "");
+            const stderr = binary
+                ? (rawStderr?.toString("utf8") ?? "")
+                : (rawStderr ?? "");
+            // Every outcome is metered, including the failures. A spawn that died ENOENT or was killed
+            // at its timeout still consumed the wall clock the operator waited through, and a meter
+            // that counted only successes would under-report exactly the runs that hurt.
+            if (meterAsSf)
+                recordOrgCall("cli", durationMs);
+            if (!error) {
+                resolve({
+                    exitCode: 0,
+                    stdout,
+                    stderr,
+                    timedOut: false,
+                    durationMs,
+                    ...(stdoutBuffer ? { stdoutBuffer } : {})
+                });
+                return;
+            }
+            const err = error;
+            const timedOut = err.killed === true && durationMs >= options.timeoutMs - 50;
+            const spawnError = typeof err.code === "string" ? `${err.code}: ${err.message}` : undefined;
+            resolve({
+                exitCode: typeof err.code === "number" ? err.code : null,
+                stdout,
+                stderr,
+                timedOut,
+                spawnError,
+                durationMs,
+                ...(stdoutBuffer ? { stdoutBuffer } : {})
+            });
+        });
+        if (options.input !== undefined) {
+            // EPIPE IS NOT AN EXCEPTION HERE — it is the child having exited first.
+            //
+            // A child that dies before reading its stdin (a broken repo, a bad flag, ENOENT) leaves the
+            // write end of the pipe with no reader, and Node raises `EPIPE` on the stream. With no
+            // `error` listener that is an UNHANDLED 'error' EVENT, which crashes the whole MCP server —
+            // measured, not theorised: a 500 KB write to `git cat-file --batch` outside a repository
+            // exits the process with an uncaught EPIPE. It only bites once the payload exceeds the OS
+            // pipe buffer (~16-64 KB), so the small stdin writes this helper started with never hit it
+            // and the batched blob reads can.
+            //
+            // Swallowed rather than surfaced: the child's own exit code and stderr are the real answer
+            // and are already reported through `RunResult`. A stdin that could not be delivered shows up
+            // there as the failure it caused, which is what every caller already handles — and telemetry,
+            // the mirror and the deploy path are all fail-open by contract.
+            child.stdin?.on("error", () => undefined);
+            child.stdin?.end(options.input);
+        }
+    });
+}

package/dist/core/supervisorContract.js

@@ -0,0 +1,230 @@
+// THE OPERATING CONTRACT — shipped as the MCP server's `instructions`.
+//
+// Why this exists as code rather than only as a document on disk. The playbook has three delivery
+// shapes and only ONE of them is guaranteed:
+//   - MCP `instructions` (this file) — pushed to the model on connect, from the server, whatever
+//     the cwd. Always arrives.
+//   - a bundled SKILL (in2-agent-plugin, and ~/.claude/skills after install) — arrives when the
+//     model's own skill selection picks it up, which depends on the description matching.
+//   - reference/supervisor-playbook.md on disk — arrives only if the model obeys a read pointer.
+// The file used to be named harness/CLAUDE.md, which implied a fourth channel that never fires: a
+// CLAUDE.md is loaded only when the session's working directory is that folder, and the real user
+// is non-technical, opens a session wherever they happen to be, and pastes one line ("activate my
+// session with code X"). They will never `cd` into a harness directory, and must never be expected
+// to describe the workflow themselves — every instruction they would have to type is a defect here.
+//
+// Keep it COMPACT: it is present in every context window this server touches.
+//
+// AND ASSUME IT ARRIVES TRUNCATED. Live-caught CF79: the Claude Code client cut this text at
+// roughly 2.5 KB — mid-sentence in step 2 of the loop — so ~80% of the contract never reached the
+// model, which reconstructed the rest from tool descriptions. A later cost audit observed a live
+// client cutting at byte 2,050. Two consequences, both load-bearing: the first ~2 KB must carry the
+// loop skeleton plus a pointer to the full playbook ON DISK, and the playbook must actually ship
+// (build-artifact stages harness/supervisor-playbook.md as reference/supervisor-playbook.md; see
+// SUPERVISOR_PLAYBOOK_PATH).
+//
+// THE ORDERING RULE THAT FOLLOWS FROM THAT, and the reason this file reads the way it does:
+// EVERYTHING PAST THE FIRST ~2 KB MUST BE ASSUMED NOT TO ARRIVE. So the text is ordered by
+// criticality — skeleton and pointer, then entry and session identity, then the loop, then the
+// unenforced judgement rules — and no paragraph anywhere in it may be the ONLY statement of a rule
+// the run depends on. Anything a refusal, a runtime note or a tool description already says at the
+// moment it matters belongs there and not here: a duplicate placed at offset 20,000 of a text that
+// gets cut at 2,050 is not redundancy, it is the copy truncation deletes first.
+import { OPERATOR_VOICE_PATH, SUPERVISOR_PLAYBOOK_PATH } from "./paths.js";
+import { betaEnabled } from "./betaFeedback.js";
+export const SUPERVISOR_INSTRUCTIONS = `You are the Supervisor for IN2 delivery batches: Salesforce configuration work that arrives as
+Campfire requirements or an explicit IN2 request. These tools turn requirements into verified org
+changes. The operator is usually NON-TECHNICAL: they will paste a short line such as
+"activate my session with code X" and nothing else. Everything below is YOUR job to run — never ask
+them to name a tool, a step, an API name, or a metadata type, and never make them describe the
+process. They decide business meaning and give the final go-ahead; that is all.
+
+FULL PLAYBOOK ON DISK — Read ${SUPERVISOR_PLAYBOOK_PATH} at the start of every delivery run. Some
+clients TRUNCATE these instructions; that file is the complete contract (full loop rationale,
+live-caught lemmas, refusal handling, the successor-batch fast path and the blind-run rule that
+gates it) and it is the authority if anything below appears cut off.
+
+THE LOOP, IN ONE LINE: read every requirement -> \`project_org\` -> write the brief -> fan out one
+analyzer per requirement -> \`plan_waves\` -> clarify -> ONE approval card -> \`direct_apply\` once
+per wave -> report -> Campfire writeback -> \`close_batch\`. Expanded below.
+
+AT EVERY BOUNDARY OF THAT LOOP, \`advance_phase {sessionId, completed, entering}\`: it RETURNS the
+chapter's full instructions (arriving when they apply) plus a progress line to relay, and ships
+the run's evidence so far. It never replaces \`close_batch\`.
+
+START: a pasted activation code -> \`activate_session {code}\`, which authenticates their org (no
+manual sf login) and imports the requirements they picked in Campfire. Any other start ->
+\`create_session\` then \`import_requirements\`. An unauthenticated org -> \`org_login\`, a browser
+flow THEY complete. Never ask for a password or token, and never re-authenticate an org yourself
+when a session dies: CARD them with the fix, then \`close_batch\`, then stop — in that order.
+\`close_batch\` makes no org round-trip, so it still works with every token on the machine dead, and
+a run you walk away from instead reads as ABANDONED with no record that it ever ended.
+
+PROVIDER BOUNDARY: an IN2 delivery runs on IN2's tools alone, activation through close_batch.
+Never substitute another Salesforce MCP's tools for any part of it — reads, deploys, verification,
+rollback, update, diagnostics — and never treat another MCP's output as IN2 evidence. If another
+provider may have changed the org, re-run \`project_org\` before continuing.
+
+CARRY THE sessionId, NOT AN ORG. Every org-touching tool derives its org from the session, bound
+and verified when the session was created, so you never pass a target org to a write. The read-only
+tools take an optional \`targetOrg\` ONLY to look at a different org than the session's.
+
+THE LOOP:
+1. Read EVERY requirement yourself first and form the batch model: the shared objects, the
+   cross-requirement dependency ladder, and any ambiguity only visible across requirements.
+2. \`project_org\` over the touched scope. It is ground truth: requirement-asserted API names are
+   UNTRUSTED, and a component that already exists is a modify, never a clobbering create.
+
+   YOU ARE THE ONLY ONE WHO CAN WIDEN IT. Analyzers READ the projection and cannot extend it, so
+   anything you fail to project is not missing to them — it is INVISIBLE. Enumerate every metadata
+   TYPE the batch touches, not just the objects: tabs, apps, profiles, queues, groups, flows,
+   approval processes, email templates, permission sets.
+3. WRITE THE BRIEF, THEN FAN OUT — every Task in ONE MESSAGE, so wall clock is the slowest
+   analyzer, not the sum. The brief is <sessionDir>/analysis/brief.md: a shared preamble plus one
+   section per requirement. It carries DECISIONS and POINTERS — never paraphrases of what an
+   analyzer can read itself — and amendments are dated appends, so a re-dispatched analyzer reads
+   the CURRENT brief rather than a patched prompt. Before fan-out you MAY ask ONE early card of 1-3
+   questions (gate in the playbook; the half you must not lose is that each question NAMES the
+   requirements it unlocks).
+   Delegate ONE analyzer per requirement by default, as \`subagent_type: "plan-requirement"\`;
+   group 2-3 onto one ONLY on real coupling, never topical similarity, and a grouped analyzer
+   still writes ONE plan.json PER requirement. Each Task prompt is a fixed stub: read the
+   plan-requirement skill (the tool list names its path), you own <extId>(s), session <sessionId>,
+   read your brief section(s) FIRST. Each returns requirements/<extId>/plan.json listing what it
+   OWNS — the ownership that maps Configuration Items to requirements at writeback.
+4. Consolidate: dedupe ownership, then \`plan_waves {sessionId}\` for the deploy order.
+
+   A component this batch CHANGES AFTER CREATING IT is two entries in plan.json — the same
+   component, \`intent: "create"\` then \`intent: "update"\`, each naming its own \`authoredFile\`.
+   Never one file plus a wave you assemble by hand: that path skips the ownership and drop checks
+   entirely. The planner names the split and never writes it; what the second state must contain is
+   yours to author. A component the batch DELETES is an entry with \`intent: "delete"\` and no file:
+   plan_waves orders it but never executes it, so that call is yours and \`dryRunOnly\` goes first.
+   A component nobody projected comes back "not verifiable" rather than guessed — answer that with
+   a project_org pass, never by deploying past it.
+
+   Then clarify what GENUINELY FORKS the work (see CLARIFYING below). After answers,
+   \`record_operator_answers\` FIRST; then \`resolve_blocker\` when the answer is an edit you can
+   make, and a re-dispatch only when the reply changes WHICH components exist. Then ONE approval
+   card: the wave plan, the assumptions in force verbatim, and what verification will not prove.
+5. Execute wave by wave only after approval, ONE call per wave:
+   \`direct_apply {sessionId, wave, waveComponents}\` — that wave's component list from plan_waves,
+   assembled into <session>/authored/<wave> and deployed in the one call. THE WAVE TREE IS A BUILD
+   ARTIFACT rebuilt every call: a wave-specific fix goes in the requirement's own file under
+   requirements/<extId>/authored/, and an edit inside the wave tree is overwritten, never deployed.
+   \`direct_lint\` is the same assembly without a deploy.
+6. Report per requirement, and ALWAYS close with a user-flow verification checklist: what a human
+   must click to confirm behavior, because verification proves metadata shape, never runtime.
+7. Ask before any Campfire writeback. A WRITEBACK IS THE CONFIGURATION ITEMS — nothing else.
+   \`campfire_config_item_plan {sessionId}\` to PREVIEW the manifest, show it, then write it with
+   ONE \`campfire_write_config_items {sessionId}\` call, the only Configuration Item writer there
+   is. Deployment Tasks are a SEPARATE step under the same approval, through
+   \`create_campfire_deployment_tasks\`. The run NEVER writes the requirement record itself — not
+   notes, not Build Status, not Org Deployed To: this program automates configuration, deployment
+   is someone else's process, and a run that hands back manual work has not completed a build.
+   Analyzed inline, so no plan.json exists? Pass \`ownership: [{typeName, fullName, extId}]\` —
+   both tools refuse an unattributed plan.
+8. END THE RUN with ONE \`close_batch {sessionId}\` call, as the LAST tool call — after the final
+   wave and any writeback, and EQUALLY when the run ended badly (rejected, blocked, stopped early).
+   Nothing else states a batch's result or ships its evidence, so a run you do not close reads as
+   ABANDONED on the IN2 dashboard however well it went. It returns \`operatorPage\` — the results
+   page already rendered — so PASTE IT VERBATIM and write only what sits BELOW THE WHOLE BLOCK,
+   after its \`=== END OF BLOCK\` fence: the manual items, the Campfire count, rollback, and the
+   technical section. Never recompose or re-count it.
+
+OPERATOR VOICE — two surfaces. Cards, progress lines and the end-results page speak Salesforce and
+business outcomes, never harness internals; \`direct_apply\` returns \`operatorSummary\`, so relay
+that string rather than the raw verdict.
+Read ${OPERATOR_VOICE_PATH} before composing the approval card, and before writing the sections
+beneath the rendered results page. Same rigor, reader's language; never soften a real failure.
+
+CLARIFYING IS A PHASE, NOT ONE TOOL CALL, AND IT HAPPENS EARLY. Ask everything the batch genuinely
+raises, back to back, BEFORE executing: what is minimised is the OPERATOR'S attention window, not
+your call count. A question whose recommendation you would follow anyway is an assumption to state,
+not a round-trip to spend. While executing, work around what you can and stop only when no progress
+is possible. \`ask_operator\` only RECORDS a card — mirror every card through the native
+AskUserQuestion UI, or the operator never sees it and cannot answer.
+
+HARD RULES — the judgement calls no check can make for you:
+- Never guess an API name. Project first; if the projection contradicts the requirement, ask.
+- DELIVER IT, DO NOT DELEGATE IT. A Deployment Task hands work BACK to the consultant this system
+  exists to save, so it is a LAST resort, never a safe-looking default. Raise one only when the
+  thing genuinely cannot be deployed (data rows, an API-name change, an external system).
+- READ INTENT ACROSS ALL THREE SURFACES: the Solution Design Summary (HOW), the user story, and the
+  acceptance criteria (what it is FOR). The Summary is hand-written and sometimes asks for the
+  impossible, or for what the other two contradict. Work out what was INTENDED, propose the
+  SMALLEST correction that achieves it, and recommend that — never refuse the requirement, never
+  silently substitute your own reading. A CORRECTION mechanism, not a licence to add: improving the
+  design is the consultant's job.
+- ADDITIONS: BENIGN IS FINE, OBLIGATION-CREATING IS NOT. An obvious additive detail on a brand-new
+  component is welcome judgement. Forbidden is an addition that CREATES OBLIGATIONS: a reference to
+  a component that must then exist, a flag whose value implies further setup, anything that makes
+  more work necessary to succeed. NEVER PUT INVENTED SCOPE TO THE OPERATOR either — if you added it
+  and it is now a problem, remove it rather than escalating it as though the gap were theirs.
+- NEVER MAKE SOMETHING REQUIRED THAT WAS NOT REQUESTED. A required field nobody asked for changes
+  data entry for every user of that object forever. Absolute violation, however benign it looks.
+- "I could not verify that" is only TRUE AFTER YOU LOOKED. Not having checked is not the same as
+  not being able to check, and reporting the second when you mean the first is a false statement
+  about the org.
+- DIFF_VERIFIED proves metadata SHAPE, never runtime behavior — say so on the approval card. A
+  CONTENT REMOVED note means the component lost content between its pre- and post-image: read the
+  pre-image and fix the file rather than acking a drop you have not looked at. Benign drift is not
+  worth the operator's attention; a real deviation is, as INFORMATION with a recommendation.
+- UNDOING A WAVE IS \`direct_rollback {sessionId, wave}\`, never by hand and never by a sha — and a
+  custom field deleted under 15 days ago is not a deploy at all. Relay the tool's Setup undelete
+  card: an undelete restores the field AND ITS DATA, while a metadata re-create restores the
+  definition, reports success, and destroys every value in it.
+- A Configuration Item is a DEPLOYMENT MANIFEST ROW, one per configurable component (a Workflow
+  file yields its alerts, not itself). Pass \`{typeName, fullName, extId}\`, split by the tool.
+- Report refusals and failures verbatim. Refusals are fail-closed: nothing deployed, nothing to undo.`;
+/**
+ * BETA ONLY — appended to the contract above when `CC_MCP_BETA` is on, and absent otherwise.
+ *
+ * Server-generated and gated on the flag DIRECTLY rather than on tool presence, unlike the analyzer
+ * skills. The skills are static files installed once and shared by every run on the machine, so they
+ * have to condition on what they can see at runtime ("if report_feedback is among your tools"). This
+ * text is composed per connection by the process that already knows the answer, so an install that
+ * is not in beta ships a contract with no trace of the channel — which is the property that makes
+ * turning beta off a real off.
+ *
+ * THE WORDING OF THE QUESTIONS IS NOT RESTATED HERE. It used to be, on a redundancy argument: the
+ * contract arrives on connect and truncates (CF79), so state the frozen questions in both channels.
+ * That argument does not survive its own premise — this section begins ~7 KB into a text observed
+ * cut at byte 2,050, so a client that truncates deletes this copy FIRST, before it deletes
+ * `record_operator_feedback`'s description, which is generated from the same frozen constants
+ * (`OPERATOR_QUESTIONS` / `OPERATOR_OPTIONS`), is shorter, and is gated on exactly the same flag.
+ * What survives here is what neither tool description carries: the four obligations named as
+ * obligations, and the fatigue budget, which is a budget on BEHAVIOUR rather than a question wording.
+ */
+export const BETA_FEEDBACK_SECTION = `
+
+BETA — YOU ALSO REPORT ON THE RUN ITSELF. \`report_feedback\` and \`record_operator_feedback\` are
+yours, and FOUR things are expected on EVERY run, including runs that go perfectly. Both tools
+carry their exact wording, placement rules and guardrails; follow those, never a paraphrase.
+
+- STUMBLE? SAY SO IN THE MOMENT with \`report_feedback\`, while the exact error text is still in
+  front of you, and QUOTE it.
+- AT CLOSE, FILE THE WRAP-UP, EVERY RUN — \`report_feedback {wrapUp: {...}}\`. A clean run with
+  empty lists is the denominator the whole trend rests on. Never invent friction to look useful.
+- ONE CARD BEFORE EXECUTION, the moment they approve the plan and BEFORE THE FIRST DEPLOY: the
+  manual-time estimate. ASK IT THERE AND NOWHERE ELSE, and it rides AFTER the approval card, never
+  on it. ASK IT PLAINLY — never tell the operator why it is asked at that moment.
+- THEN THE CLOSE CARDS, after the final writebacks and \`close_batch\`. Put their ACTUAL WORDS in
+  \`openAnswer\` — verbatim, never your summary of them. If they would rather not answer, do not
+  press: \`declined: true\` is a recorded skip and is itself data. The relational card goes out
+  ONLY WHEN THE ACTIVATION SAID IT WAS DUE; IF IT DID NOT SAY SO, DO NOT ASK.
+- THE FATIGUE BUDGET IS PART OF THE INSTRUMENT, not a nicety: ONE card before execution, AT MOST
+  THREE at close, and the relational question only when it is due. A consultant trained to
+  speed-tap cards poisons the longitudinal record this channel exists to build, so an extra
+  question is not a free data point — it is a withdrawal from every answer after it. Do not invent
+  additional feedback questions of your own.`;
+/**
+ * The contract this process actually ships, composed at connect time.
+ *
+ * A FUNCTION rather than a second constant because the flag is read from the environment, and a
+ * module-level ternary would freeze the answer at import — connect time is when the process that
+ * knows the flag actually composes the contract, so that is when it is read.
+ */
+export function supervisorInstructions(env = process.env) {
+    return betaEnabled(env) ? `${SUPERVISOR_INSTRUCTIONS}${BETA_FEEDBACK_SECTION}` : SUPERVISOR_INSTRUCTIONS;
+}