in2-agent-server 0.20260821.185429

package/dist/tools/auth.js

@@ -0,0 +1,915 @@
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { fail, internalError, ok } from "../core/result.js";
+import { checkForUpdate, scheduleUpdateAtClose, startDetachedInstall, updateInstalledUnderThisProcess, updateActionFor } from "../core/update.js";
+import { recordDirectWriteGrant } from "../core/writeGrants.js";
+import { opaqueId, isoNow } from "../core/ids.js";
+import { ensureDir, fileExists, readJson, sessionDir, sessionFile, writeJsonAtomic } from "../core/workspace.js";
+import { SESSION_SCHEMA_VERSION, composeCampfireProse, importRequirementEntries, producerIdentity } from "./session.js";
+import { WORKSPACE_ROOT } from "../core/paths.js";
+import { ensureViewer, viewerBaseUrl, viewerNotice, viewerPort } from "../core/viewer.js";
+import { runProcess, sfCliEnv, spawnDetached } from "../core/spawn.js";
+import { campfireAllowlistedOrgIds } from "../core/gate.js";
+import { installId } from "../core/telemetry.js";
+import { installedVersion } from "../core/install.js";
+import { bindBatchContext, emitDomainTelemetryEvent, processTelemetryIdentity } from "../core/telemetryContext.js";
+// Interactive org authentication for the START of a session, so an operator can point the
+// harness at any org they can log into rather than a pre-provisioned alias.
+//
+// WHY THE sf CLI IS THE WHOLE ANSWER: every org path in this server authenticates through the
+// CLI's stored auth — deploys shell out to `sf`, and the jsforce reader / CRUD facet writer use
+// `Org.create({aliasOrUsername})`, which reads the same `~/.sf` auth files. No token, client
+// secret or redirect URI ever passes through this process. And `sf org login web` IS a full
+// callback-included OAuth flow: it starts a localhost listener, opens the browser to Salesforce's
+// authorize endpoint with redirect_uri=http://localhost:<port>/OauthRedirect, exchanges the code
+// and writes the auth file. The bespoke OAuth plumbing that in2-console and the older
+// vfp-configuration-project needed exists because those are WEB apps — browser/server code
+// cannot shell to a CLI on the end user's machine and must own the token lifecycle. This server
+// is a local stdio subprocess on the user's own machine, so it inherits the CLI's store.
+//
+// The human authenticates directly with Salesforce in their own browser. This tool never asks
+// for, receives, or stores a username, password, or token — it only launches the flow.
+const ALIAS_RE = /^[A-Za-z][A-Za-z0-9._-]{0,59}$/;
+function authLogPath(alias) {
+    return path.join(WORKSPACE_ROOT, "..", "auth", `login-${alias}.log`);
+}
+async function readOrgDisplay(alias) {
+    const run = await runProcess("sf", ["org", "display", "--target-org", alias, "--json"], {
+        env: sfCliEnv(),
+        timeoutMs: 60_000
+    });
+    if (run.timedOut)
+        return { ok: false, detail: "sf org display timed out" };
+    try {
+        const parsed = JSON.parse(run.stdout);
+        if (parsed.result?.id)
+            return { ok: true, result: parsed.result };
+        return { ok: false, detail: parsed.message ?? parsed.name ?? `exit ${run.exitCode}` };
+    }
+    catch {
+        return { ok: false, detail: run.stderr.slice(-300) || run.stdout.slice(-300) || `exit ${run.exitCode}` };
+    }
+}
+/**
+ * The local sf alias pointing at a given Org ID, or null.
+ *
+ * activate_session knows the requirements came FROM Campfire — the launch service read them there —
+ * but the payload names only the TARGET org, so the consultant org was never recorded. That made
+ * activation, the product's primary path, the one path from which Campfire writeback was impossible
+ * (live-caught: a Campfire writeback refused ORG_NOT_BOUND on a fully successful delivery).
+ *
+ * The Campfire org is not a guess: it is the org on the Campfire write allowlist, by definition.
+ * What is machine-specific is the ALIAS, so it is resolved from the CLI's own org list rather than
+ * assumed. A miss leaves the binding absent, and the existing refusal still names the fix.
+ */
+async function aliasForOrgId(orgId) {
+    const run = await runProcess("sf", ["org", "list", "--json"], { env: sfCliEnv(), timeoutMs: 60_000 });
+    if (run.exitCode !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(run.stdout);
+        const want = orgId.slice(0, 15);
+        for (const group of Object.values(parsed.result ?? {})) {
+            if (!Array.isArray(group))
+                continue;
+            for (const org of group) {
+                const id = typeof org.orgId === "string" ? org.orgId : "";
+                const alias = typeof org.alias === "string" ? org.alias : "";
+                if (id.slice(0, 15) === want && alias)
+                    return alias;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export async function resolveCampfireBinding(campfireOrgId, deps) {
+    if (!campfireOrgId)
+        return { status: "unknown_org" };
+    const alias = await deps.aliasForOrgId(campfireOrgId);
+    if (!alias)
+        return { status: "not_authenticated", orgId: campfireOrgId };
+    // CONNECTED is the only state that counts as authenticated, exactly as `org_login` reads it. A
+    // readable alias whose status is anything else still needs a login, and a read that fails at all
+    // is indistinguishable from an unauthenticated alias from here — both are "this will not work at
+    // writeback", which is the only thing the operator needs told.
+    const display = await deps.readOrgDisplay(alias);
+    if (!display.ok)
+        return { status: "expired", alias, orgId: campfireOrgId, detail: display.detail };
+    if (display.result.connectedStatus !== "Connected") {
+        return {
+            status: "expired",
+            alias,
+            orgId: display.result.id ?? campfireOrgId,
+            detail: display.result.connectedStatus ?? "not connected",
+            ...(display.result.instanceUrl ? { instanceUrl: display.result.instanceUrl } : {})
+        };
+    }
+    return {
+        status: "bound",
+        alias,
+        orgId: display.result.id ?? campfireOrgId,
+        ...(display.result.instanceUrl ? { instanceUrl: display.result.instanceUrl } : {})
+    };
+}
+/** VF-partial's login host, so the remedy below is copy-pasteable rather than a shape to fill in. */
+const CAMPFIRE_DEFAULT_INSTANCE_URL = "https://vfp--vfpartial.sandbox.my.salesforce.com";
+/**
+ * Whether to log a launch-service-minted Campfire credential into the CLI, and under which alias.
+ *
+ * The launch service can now authenticate the Campfire org in the same browser round-trip as the
+ * target org and hand the credential back on the activation payload. That closes the structural
+ * hole: the product MINTS the credential rather than hoping a human made one by hand.
+ *
+ * TWO RULES, both of which are about not making things worse:
+ *
+ * 1. A LIVE local binding is never replaced. That alias may be the consultant's own
+ *    `sf org login web` sign-in, which lives under VF-partial's session policy and in practice
+ *    outlives an activation-minted token by a wide margin. Swapping a durable credential for a
+ *    shorter-lived one is a downgrade, and it would be an invisible one.
+ * 2. An EXPIRED local alias is reused by NAME. Two aliases for one org is how an operator ends up
+ *    re-authenticating the one the session is not using.
+ *
+ * Absence changes nothing anywhere: no credential, or no known Campfire org to verify it against,
+ * means this does nothing and the run falls back to the minute-zero card.
+ */
+/**
+ * The activation-minted alias for the TARGET org — named after the ORG, never after Campfire.
+ *
+ * The old shape was `campfire-<orgId>`, which put the word "campfire" on the one org in
+ * `sf org list` that is NOT the Campfire org — the delivery target. Anyone (or any model) reading
+ * the org list to answer "which org is Campfire?" picked the delivery org, which is exactly the
+ * mistake campfire.ts's field-cap comment records happening: the DELIVERY org was described in
+ * place of the consultant org and the measurement was wrong for days. An opaque org id tells a
+ * human nothing; the MyDomain label — `tpinto12122025`, `vfp--vfpartial.sandbox` — is the name
+ * people actually use for an org, it is globally unique by construction, and it survives in the
+ * instance URL every activation payload already carries.
+ *
+ * `in2-` prefixed so activation-minted aliases stay recognizable (and deletable) as a family, and
+ * so the alias can never collide with a hand-made login for the same org (rule 1 of
+ * campfireLoginPlan: a live human-made binding is never replaced). The 15-char org id rides as a
+ * SUFFIX — `in2-tpinto12122025-00Dfn00000BFjbB` — so the alias stays unambiguous even if two orgs
+ * ever share a readable label (a refreshed sandbox, a renamed MyDomain): the name half is for the
+ * human, the id half is the ground truth. With no usable URL the label half is simply absent.
+ */
+export function targetOrgAlias(instanceUrl, orgId) {
+    const ALIAS_MAX = 60;
+    const id = orgId.slice(0, 15);
+    let label = "";
+    try {
+        const host = new URL(instanceUrl ?? "").hostname;
+        // Everything before the platform suffix is the org's own name: `tpinto12122025` from
+        // `tpinto12122025.my.salesforce.com`, `vfp--vfpartial.sandbox` from the sandbox form.
+        label = host.replace(/\.(my\.)?salesforce(?:liveagent|-setup)?\.com$/i, "").replace(/\.my$/i, "");
+        // A dot would survive the alias grammar but reads as structure; keep the sandbox qualifier
+        // visible without it.
+        label = label.replace(/\.sandbox$/i, "").replace(/[^A-Za-z0-9._-]/g, "-");
+    }
+    catch {
+        label = "";
+    }
+    // The id suffix is non-negotiable; when the whole thing would overflow, the LABEL is what gives.
+    const room = ALIAS_MAX - "in2-".length - id.length - 1;
+    const trimmed = label.slice(0, Math.max(0, room));
+    const alias = trimmed ? `in2-${trimmed}-${id}` : `in2-${id}`;
+    return ALIAS_RE.test(alias) ? alias : `in2-${id}`;
+}
+export function campfireLoginPlan(binding, minted, campfireOrgId) {
+    const alias = "alias" in binding && binding.alias ? binding.alias : `campfire-org-${(campfireOrgId ?? "").slice(0, 15)}`;
+    if (!minted?.authUrl || !campfireOrgId)
+        return { login: false, alias };
+    if (binding.status === "bound")
+        return { login: false, alias };
+    return { login: true, alias };
+}
+/**
+ * What activation TELLS the operator about a Campfire org that will not work, at minute zero.
+ *
+ * The consequence is the half a supervisor cannot infer and the half that makes this worth saying
+ * early: nothing fails now. Analysis, approval and every wave will run exactly as they would with a
+ * live binding. Only the last step of the run breaks, and by then the org has been changed.
+ */
+export function campfireBindingNotice(binding) {
+    if (binding.status === "bound")
+        return [];
+    const alias = "alias" in binding ? binding.alias : "campfire";
+    const instanceUrl = ("instanceUrl" in binding && binding.instanceUrl) || CAMPFIRE_DEFAULT_INSTANCE_URL;
+    const org = "orgId" in binding && binding.orgId ? binding.orgId : "unknown — nothing in this activation named one";
+    const cause = binding.status === "expired"
+        ? `The Campfire (consultant) org's local sign-in has EXPIRED — alias ${alias} no longer authenticates (${binding.detail}).`
+        : binding.status === "not_authenticated"
+            ? `The Campfire (consultant) org is NOT authenticated on this machine — no local sf alias points at org ${org}.`
+            : "This activation named no Campfire (consultant) org, and none is configured on this install.";
+    return [
+        "",
+        `CAMPFIRE ORG: ${cause}`,
+        `Campfire org: ${org}`,
+        "Campfire writeback will NOT be possible from this machine until that is fixed. Everything else in this run works:",
+        "analysis, approval and every deploy wave will succeed, and only the final writeback step will refuse — after the org",
+        "has already been changed. Card this to the operator NOW, at the start, not at the end.",
+        "The fix, either way (they complete the browser sign-in; you never handle a password or token):",
+        `  org_login {alias: "${alias}", instanceUrl: "${instanceUrl}", mode: "restart"}`,
+        `  or the same flow by hand: sf org login web --alias ${alias} --instance-url ${instanceUrl}`,
+        "Then re-run activate_session, or bind it with create_session, so the session records the live alias."
+    ];
+}
+/**
+ * What activation says once it has ALREADY installed the stale-path update, rather than asking.
+ *
+ * Only the `stale` path installs at activation — the run was never going to start on this build,
+ * so nothing is in flight for an in-place npm install to skew. Two outcomes:
+ *   - the install failed  → fall back to the round-1 imperative, naming the error. Activation
+ *                           must not fail because an update did, and must not pretend either.
+ *   - the install landed  → the disk is current and THIS conversation is not. There is no hot
+ *                           swap any more, so the restart is unconditional: tell the operator to
+ *                           start a new chat, then STOP.
+ */
+function installedNotice(update, installed) {
+    if (!installed.ok) {
+        return [
+            "",
+            `THIS BUILD IS TOO OLD TO START A BATCH, AND THE AUTOMATIC UPDATE FAILED: this server is ${installed.fromVersion}, the published release is ${update.latestVersion}.`,
+            `The install did not happen: ${installed.error ?? "unknown error"}`,
+            "This server is UNCHANGED and still on the old build. Do NOT begin the delivery loop. Card the operator:",
+            "ask them to run `npm install -g in2-agent-server@latest` in a terminal, then start a new chat and paste",
+            "their activation prompt again. If they cannot, let them decide whether to continue on the old build."
+        ];
+    }
+    // ok but not updated: the registry no longer offered a newer build between the check's fetch and
+    // the install's (npm replication lag, or a dist-tag rollback). Nothing was installed, so "TOOLS
+    // UPDATING" + a restart would loop the operator straight back to this same build reporting the
+    // same false success. The structured field maps this to `current` (updateStructuredFields), and
+    // the prose must agree with it.
+    if (!installed.updated) {
+        return [
+            "",
+            `Note: activation's version check saw ${update.latestVersion} published, but the registry no longer offers a build newer than ${installed.fromVersion} — nothing was installed, and nothing needs restarting. If this persists across sessions, the registry may still be replicating a fresh release.`
+        ];
+    }
+    return [
+        "",
+        `TOOLS UPDATING AUTOMATICALLY: version ${installed.toVersion} is installing in the background (this conversation started on ${installed.fromVersion}, which is too old to run a batch).`,
+        "THIS conversation keeps running the old build regardless — an npm install cannot replace code a running",
+        "process has loaded. Tell the operator, in their words, that the tools are being updated and this chat",
+        "cannot use the new version: they must START A NEW CHAT (give the install a minute or two) and paste",
+        "their activation prompt again. Their requirements and this activation are unaffected — nothing is lost",
+        "by restarting. If the new chat still reports an old build, the background install had not finished or",
+        "failed; it re-runs automatically at that activation.",
+        "Then STOP. Do not read requirements, do not project the org, do not deploy anything in this session."
+    ];
+}
+/**
+ * What activation TELLS the supervisor about a build that is behind the published release.
+ *
+ * THREE REGISTERS, because "an update exists", "the update will land by itself", and "this build
+ * predates two days of fixes" are different facts and must not read the same. LIVE-CAUGHT
+ * (QA round 1, 2026-08-06): two testers were shown an `UPDATE AVAILABLE` line at activation, ran
+ * anyway, and one of them lost a multi-hour run to a bug fixed ~21 hours after their build was cut
+ * — failing at step 8 of 9, with the org already changed. The notice was true, competed with
+ * fourteen other lines, and changed nothing.
+ *
+ * So under npm distribution: `behind` is one informational line with NOTHING for anyone to do —
+ * close_batch installs it and the next session is current. `stale` installs immediately (nothing
+ * was going to run on this build anyway) and reports what happened via installedNotice, which
+ * carries the unconditional restart instruction — there is no hot swap, so a chat can never pick
+ * up an installed update.
+ */
+/**
+ * The version facts as structured FIELDS, beside the prose the notice carries.
+ *
+ * QA round 4 (2026-08-20, session e6ec08ce): the whole update notice lived in the text channel,
+ * the client dropped it (see ok()'s header in core/result.ts), and a tester activated on a
+ * 5-day-stale build with the model reporting the activation result "only contained sessionId,
+ * batchId… no update-related line". The text mirror fixes the notice; these fields make the facts
+ * keyable regardless of which channel a client renders.
+ *
+ * `serverVersion` is the build THIS CONVERSATION'S ANSWERS COME FROM — always the running build:
+ * with the hot swap gone, no install can change what this session answers from, and reporting an
+ * installed toVersion here would make serverVersion === latestVersion read as "current" on the
+ * exact path whose prose says START A NEW CHAT.
+ *
+ * `updateStatus`, exhaustively: `current` (no update), `unknown` (the check itself failed —
+ * checkForUpdate's catch returns updateAvailable:false with a `reason` and no latestVersion, and
+ * asserting `current` there is a false positive for a build that may be days stale),
+ * `installed-restart-required` (the stale path installed the new build; this session cannot use
+ * it), `install-failed`, and the pre-install verdicts from `updateActionFor` (`update-at-close`,
+ * `stop-and-update`, `update-by-hand`).
+ */
+export function updateStructuredFields(update, installed) {
+    const running = update.currentVersion;
+    if (!update.updateAvailable) {
+        const checkFailed = update.reason !== undefined && update.latestVersion === undefined;
+        return { serverVersion: running, updateStatus: checkFailed ? "unknown" : "current" };
+    }
+    const status = !installed
+        ? updateActionFor(update)
+        : !installed.ok
+            ? "install-failed"
+            : !installed.updated
+                ? "current"
+                : "installed-restart-required";
+    return { serverVersion: running, updateStatus: status, latestVersion: update.latestVersion };
+}
+export function updateNotice(update, installed) {
+    if (!update.updateAvailable)
+        return [];
+    if (installed)
+        return installedNotice(update, installed);
+    const age = update.behindDays !== undefined
+        ? ` — ${update.behindDays} day${update.behindDays === 1 ? "" : "s"} of fixes behind`
+        : "";
+    const versions = `this server is ${update.currentVersion}, the published release is ${update.latestVersion}${age}.`;
+    // Not managed: the updater cannot help, so the words must not tell anyone to run it.
+    if (!update.managed) {
+        return [
+            "",
+            `${update.staleness === "stale" ? "STOP — THIS BUILD IS TOO OLD TO START A BATCH" : "UPDATE AVAILABLE"}: ${versions}`,
+            "This install is not npm-managed (a repo checkout updates with git pull, not the updater).",
+            ...(update.staleness === "stale"
+                ? [
+                    "Card that to the operator and STOP. Do not begin the delivery loop on this build — a run started",
+                    "here can fail at the last step with the org already changed, which is the expensive way to find out."
+                ]
+                : [])
+        ];
+    }
+    // `stale` without an install result should not happen — activation installs before composing
+    // this notice — but the function must stay honest for any caller: a build too old to run gets a
+    // stop, never a "pending" line that reads as permission.
+    if (update.staleness === "stale") {
+        return [
+            "",
+            `STOP — THIS BUILD IS TOO OLD TO START A BATCH: ${versions}`,
+            "A build this far behind has repeatedly cost a whole run: the failure lands at the LAST step, after the",
+            "org has been changed, from a bug that was already fixed. Run `update_server {apply: true}`, then tell",
+            "the operator to START A NEW CHAT and paste their activation prompt again — nothing is lost by restarting.",
+            "Do not begin the delivery loop in this session.",
+            `(Deliberate exception — developing against a pinned build: set CC_MCP_STALE_AFTER_DAYS=0 to disable this block.)`
+        ];
+    }
+    // `behind` — informational, and deliberately actionless: every imperative wording of this line
+    // was ignored three QA rounds running, so the action moved to close_batch where no one can skip it.
+    return [
+        "",
+        `UPDATE PENDING: ${versions}`,
+        "Nothing to do now — it installs automatically when this batch closes, and the NEXT session runs it.",
+        "Do not run update_server mid-batch."
+    ];
+}
+/**
+ * Browser flows this process has launched, by alias.
+ *
+ * This is what lets ONE tool both start a login and report on one: with no flow outstanding the
+ * call means "log this org in", and with a flow outstanding the same call means "how is it going".
+ *
+ * Deliberately in-process and not on disk. A restarted server has no browser window of its own to
+ * poll and no way to know whether the one it never opened is still alive, so launching again is the
+ * right answer there — which is exactly what the two-tool surface did, since `org_login` relaunched
+ * on every call. `mode: "restart"` is the escape hatch for a window that died within one process.
+ */
+const pendingLogins = new Map();
+/** The login log's tail, for a status report that has to explain a flow that did not finish. */
+async function loginLogTail(alias) {
+    try {
+        const log = await fs.readFile(authLogPath(alias), "utf8");
+        return `\n\nlogin log tail:\n${log.slice(-800)}`;
+    }
+    catch {
+        return "";
+    }
+}
+// org_login registers UNCONDITIONALLY. It used to be gated behind CC_MCP_ORG_LOGIN=1.
+//
+// The gating argument (2026-07-28, a412d3c) was that the tool had never fired across CF73-76 and
+// that unused tool surface is a per-call cost. The argument that beat it is that the case this tool
+// was kept for — named in the gating comment itself as "a session whose org auth expires mid-run,
+// with no fresh code to hand" — then fired twice and killed both runs, while CC_MCP_ORG_LOGIN was
+// set NOWHERE outside its own test: not in setup.sh's generated launcher, not in run-server.sh. The
+// tool was therefore off in 100% of real installs at the exact moment both resident doctrine
+// surfaces were telling the model to call it, the playbook routing `ORG_ID_UNRESOLVED` / "No
+// authorization information found" — the error a dead Campfire binding actually produces — straight
+// at it. Doctrine naming a tool the server does not register is worse than either half alone; the
+// model improvises into the vacuum, and on both incidents it improvised "start a new session".
+//
+// Both recoveries the doctrine now offers run through here: the target org's activation token, which
+// expires in about a day, and the Campfire org, whose credential this product never mints at all.
+// `authRegistration.test.ts` pins the unconditional registration against the doctrine that names it.
+export function registerAuthTools(server) {
+    server.registerTool("org_login", {
+        description: "The whole org-authentication lifecycle for one alias: START the interactive Salesforce OAuth login (sf CLI web-server flow), and REPORT where it stands. With `mode` omitted it starts a flow when the alias is not connected and none is already pending, and reports otherwise — so the operator flow is: call it, they finish the login in their browser, call it again until it says CONNECTED. The operator authenticates directly with Salesforce; this tool never asks for or handles a username, password, or token. NON-BLOCKING: the flow is launched detached and the call returns immediately. A CONNECTED result names the orgId/username/instance behind the alias AND whether direct_apply may write to that org — which makes `mode: \"status\"` the right check BEFORE any write, since an alias is operator-controlled and can be repointed. When the org is connected but NOT on the direct-write allowlist, the result carries the exact re-registration command the operator needs, because server env is fixed at spawn. CONNECTED is the only status that counts as authenticated — an expired alias gets a fresh flow. Sandboxes/My Domain: pass instanceUrl (e.g. https://test.salesforce.com or the My Domain URL). Nothing about the org is read or changed here; the login only creates local CLI auth.",
+        inputSchema: {
+            alias: z.string().describe("Local alias to store the auth under, e.g. mytest. Used as targetOrg everywhere else."),
+            mode: z
+                .enum(["auto", "status", "restart"])
+                .optional()
+                .describe("auto (default): launch only if the alias is not connected and no flow from this server is pending; otherwise report. status: never launch — poll a flow already running, or confirm which org an alias points at before a write. restart: always launch a fresh browser flow, even if the alias is already connected — re-authenticates an alias whose auth expired or whose window died."),
+            instanceUrl: z
+                .string()
+                .optional()
+                .describe("Login host for sandboxes / My Domain, e.g. https://test.salesforce.com. Defaults to production login."),
+            setDefault: z.boolean().optional().describe("Also set this org as the CLI's default target org.")
+        }
+    }, async ({ alias, mode, instanceUrl, setDefault }) => {
+        try {
+            if (!ALIAS_RE.test(alias)) {
+                return fail("INVALID_ALIAS", `alias must match ${ALIAS_RE} (letter first, then letters/digits/._-).`);
+            }
+            if (instanceUrl !== undefined) {
+                let parsed;
+                try {
+                    parsed = new URL(instanceUrl);
+                }
+                catch {
+                    return fail("INVALID_INSTANCE_URL", `instanceUrl is not a URL: ${instanceUrl}`);
+                }
+                if (parsed.protocol !== "https:") {
+                    return fail("INVALID_INSTANCE_URL", "instanceUrl must be https — refusing to start an OAuth flow over a non-TLS host.");
+                }
+            }
+            const launch = async () => {
+                const logFile = authLogPath(alias);
+                await fs.mkdir(path.dirname(logFile), { recursive: true });
+                await fs.writeFile(logFile, `--- org_login ${alias} @ ${new Date().toISOString()} ---\n`, "utf8");
+                const args = [
+                    "org",
+                    "login",
+                    "web",
+                    "--alias",
+                    alias,
+                    ...(instanceUrl ? ["--instance-url", instanceUrl] : []),
+                    ...(setDefault ? ["--set-default"] : [])
+                ];
+                const { pid } = spawnDetached("sf", args, { env: sfCliEnv(), logFile });
+                pendingLogins.set(alias, { ...(pid !== undefined ? { pid } : {}), startedAt: new Date().toISOString() });
+                return ok([
+                    `Browser OAuth flow LAUNCHED for alias ${alias}${instanceUrl ? ` (instance ${instanceUrl})` : ""} — pid ${pid ?? "unknown"}.`,
+                    "",
+                    "The operator must now complete the login in the browser window that just opened (Salesforce login + Allow).",
+                    "This tool does not wait. Call org_login { alias } again to check — poll until it reports CONNECTED.",
+                    `Login output is teed to ${logFile} (a not-yet-connected report shows its tail).`,
+                    "",
+                    "If no browser opened: the operator can run the same flow themselves —",
+                    `  sf org login web --alias ${alias}${instanceUrl ? ` --instance-url ${instanceUrl}` : ""}`
+                ].join("\n"), { alias, pid, logFile, launched: true, connected: false });
+            };
+            // Restart is answered BEFORE the org is read, because it is the one mode whose whole point
+            // is to re-authenticate an alias that already looks fine — a connected short-circuit would
+            // make it unreachable in exactly the case (an alias pointing at the wrong org) it exists for.
+            if (mode === "restart")
+                return await launch();
+            const display = await readOrgDisplay(alias);
+            // CONNECTED is the only state that counts as authenticated. A readable alias whose status
+            // is anything else (expired, revoked) still needs a login, and the tool this merged with
+            // launched one for exactly that case — only a Connected alias short-circuited it.
+            const connected = display.ok && display.result.connectedStatus === "Connected";
+            if (connected)
+                pendingLogins.delete(alias);
+            const pending = pendingLogins.get(alias);
+            if (!connected && mode !== "status" && !pending)
+                return await launch();
+            if (!display.ok) {
+                // A failed read and an unauthenticated alias are the same answer from `sf org display`,
+                // so neither may ever be reported as connected. The log tail is what distinguishes them
+                // for a human.
+                return ok([
+                    `alias ${alias}: NOT yet authenticated (${display.detail}).`,
+                    pending
+                        ? `A browser flow launched by this server is still outstanding (pid ${pending.pid ?? "unknown"}, started ${pending.startedAt}) — the operator has not finished it yet. Poll again, or pass mode:"restart" to open a fresh one.`
+                        : "If a browser flow is in progress, the operator has not finished it yet — poll again.",
+                    await loginLogTail(alias)
+                ].join("\n"), {
+                    alias,
+                    connected: false,
+                    launched: false,
+                    ...(pending ? { pending: true } : {}),
+                    detail: display.detail
+                });
+            }
+            const r = display.result;
+            const { directAllowlistedOrgIds, directAllowlistOpen, isConsultantOrg } = await import("../core/gate.js");
+            const allow = directAllowlistedOrgIds();
+            const short = (r.id ?? "").slice(0, 15);
+            const consultant = isConsultantOrg(r.id ?? "");
+            const wildcard = directAllowlistOpen();
+            const writeReady = !consultant && (wildcard || allow.includes(short));
+            return ok([
+                `alias ${alias}: ${connected ? "CONNECTED — no login needed" : `status ${r.connectedStatus ?? "unknown"}`}`,
+                `orgId: ${r.id}`,
+                `username: ${r.username}`,
+                `instance: ${r.instanceUrl}`,
+                "",
+                writeReady
+                    ? `direct-write: OK — this org is writable by direct_apply${wildcard ? " (allowlist is WIDE OPEN via CC_MCP_DIRECT_ALLOWLIST=*)" : ""}.`
+                    : consultant
+                        ? "direct-write: HARD-REFUSED — this is the REAL shared consultant org. The direct tier refuses it by org id no matter what the allowlist says, and no re-registration changes that. Reads are fine; Campfire writes ride their own CC_MCP_CAMPFIRE_WRITE gate."
+                        : [
+                            "direct-write allowlist: NOT LISTED — reads (project_org, sf_read) work now, but direct_apply will refuse.",
+                            "Server env is fixed at spawn, so the operator must re-register and start a fresh session:",
+                            `  claude mcp add cc-mcp --scope user --env CC_MCP_DIRECT_WRITE=1 --env CC_MCP_DIRECT_ALLOWLIST=${r.id} -- <node24> <path>/apps/cc-mcp-server/dist/index.js`
+                        ].join("\n")
+            ].join("\n"), {
+                alias,
+                connected,
+                // Retained from the tool this merged with, where it meant "no browser window was
+                // opened for you". `launched: false` says the same thing; both ship so a caller
+                // keying on either still reads correctly.
+                ...(connected ? { alreadyConnected: true } : {}),
+                launched: false,
+                ...(pending ? { pending: true } : {}),
+                orgId: r.id,
+                username: r.username,
+                instanceUrl: r.instanceUrl,
+                directWriteAllowlisted: writeReady,
+                consultantOrgRefused: consultant
+            });
+        }
+        catch (error) {
+            return internalError(error);
+        }
+    });
+}
+/**
+ * What DELIVERY needs from an activation: an auth URL to log the CLI in with, and an org to bind
+ * the session to. Nothing else. Everything the ledger wants is enrichment, so an older launch
+ * service, a rolled-back deploy, or an unreachable reporting database cannot stop a consultant.
+ */
+export function activationIsUsable(payload) {
+    return Boolean(payload.authUrl && payload.orgId);
+}
+export function activationEnrichment(payload) {
+    return {
+        ...(payload.batchId ? { batchId: payload.batchId } : {}),
+        actors: {
+            ...(payload.campfireUserId ? { campfireUserId: payload.campfireUserId } : {}),
+            ...(payload.campfireOrgId ? { campfireOrgId: payload.campfireOrgId } : {}),
+            ...(payload.targetUserId ? { targetUserId: payload.targetUserId } : {}),
+            targetUsername: payload.username
+        },
+        bindable: Boolean(payload.batchId && payload.telemetryGrant?.credential),
+        pmfDue: payload.pmfDue === true
+    };
+}
+// The launch service must be reached over TLS — the response body carries a refresh token.
+// localhost is exempted so the flow can be developed and tested without certificates.
+export function assertSafeLaunchUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`launchUrl is not a URL: ${raw}`);
+    }
+    const isLocal = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if (url.protocol !== "https:" && !isLocal) {
+        throw new Error(`launchUrl must be https (got ${url.protocol}//) — the activation response carries a refresh token and must not cross the network in plaintext.`);
+    }
+    return url;
+}
+// Campfire requirement -> the same prose shape composeCampfireProse produces locally, so a
+// Campfire-started session and a locally-imported one are byte-identical. The launch payload is
+// camelCase (it crossed Apex), so map it back onto the SOQL field names the composer expects.
+export function proseFromActivation(req) {
+    return composeCampfireProse({
+        Id: req.id ?? "",
+        Name: req.reqId,
+        Requirement_Name__c: req.requirementName,
+        User_Story__c: req.userStory,
+        User_Story_Action__c: req.userStoryAction,
+        User_Story_Such_That__c: req.userStorySuchThat,
+        User_Story_Description__c: req.userStoryDescription,
+        Acceptance_Criteria_Given__c: req.acceptanceCriteriaGiven,
+        Acceptance_Criteria_When__c: req.acceptanceCriteriaWhen,
+        Acceptance_Criteria_Then__c: req.acceptanceCriteriaThen,
+        Solution_Design_Summary__c: req.solutionDesignSummary,
+        Requirement_Details__c: req.requirementDetails,
+        Solution_Details__c: req.solutionDetails
+    });
+}
+export function registerActivationTools(server) {
+    server.registerTool("activate_session", {
+        description: "Start a session from a Campfire activation code. The operator clicked 'Configure in external org' in Campfire, authenticated THEIR target org in the browser, and pasted a prompt containing a single-use code. This redeems it: authenticates the org into the sf CLI (no manual `sf` login), creates the session workspace, and imports the requirements they selected — replacing create_session + import_requirements for that flow. Codes are single-use and expire in minutes; a refused code means it was already redeemed, expired, or wrong, and the operator must re-send from Campfire. Reports which Salesforce USER the session will act as — surface that to the operator, it is the identity every org change will be attributed to. ALSO REPORTS THE CAMPFIRE ORG'S CONDITION, and a `CAMPFIRE ORG:` line in the result is a CARD YOU RAISE IMMEDIATELY: that org is never authenticated by this product, so a machine that has not signed into it will deliver every wave normally and then refuse the final writeback, thirty minutes in, with the org already changed. The result names the fix; relay it before starting the loop.",
+        inputSchema: {
+            code: z.string().describe("The activation code from the pasted starting prompt."),
+            launchUrl: z
+                .string()
+                .optional()
+                .describe("Base URL of the launch service. Defaults to CC_MCP_LAUNCH_URL. Must be https (localhost exempt)."),
+            alias: z.string().optional().describe("Local sf alias to store the org under. Default: in2-<mydomain>-<orgId15>."),
+            sessionId: z.string().optional().describe("Session id to create/reopen. Generated when omitted.")
+        }
+    }, async ({ code, launchUrl, alias, sessionId }) => {
+        try {
+            const base = (launchUrl ?? process.env.CC_MCP_LAUNCH_URL ?? "").trim();
+            if (!base) {
+                return fail("LAUNCH_URL_NOT_CONFIGURED", "No launch service URL. Pass launchUrl, or start the server with CC_MCP_LAUNCH_URL set.");
+            }
+            let endpoint;
+            try {
+                endpoint = assertSafeLaunchUrl(base);
+            }
+            catch (error) {
+                return fail("INVALID_LAUNCH_URL", error instanceof Error ? error.message : String(error));
+            }
+            // The session identity exists before redemption so the launch service can bind the
+            // activation, install, process, and local workspace in one authenticated exchange.
+            // Minted BEFORE redemption so the launch service can bind install/process/session in the
+            // one exchange the activation code authenticates. That moves the id earlier than it used
+            // to be, so its entropy can no longer come from the not-yet-known org — a random source
+            // replaces it, which is strictly stronger than the old timestamp+orgId pair.
+            const id = sessionId?.trim() || opaqueId("ses", { at: isoNow(), entropy: randomBytes(16).toString("hex") });
+            const processIdentity = processTelemetryIdentity() ?? {
+                installId: installId(),
+                runId: `run_uninstrumented_${process.pid}`,
+                serverVersion: installedVersion()
+            };
+            // 1. Redeem — exactly once, server-side.
+            const activateUrl = new URL("/api/activate", endpoint).toString();
+            let payload;
+            try {
+                const res = await fetch(activateUrl, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({
+                        code,
+                        installId: processIdentity.installId,
+                        runId: processIdentity.runId,
+                        sessionId: id,
+                        serverVersion: processIdentity.serverVersion
+                    }),
+                    signal: AbortSignal.timeout(30_000)
+                });
+                const json = (await res.json().catch(() => ({})));
+                if (!res.ok) {
+                    return fail("ACTIVATION_REFUSED", json.error ?? `The launch service refused the code (HTTP ${res.status}). Re-send the requirements from Campfire to get a fresh one.`);
+                }
+                payload = json;
+            }
+            catch (error) {
+                return fail("LAUNCH_SERVICE_UNREACHABLE", `Could not reach the launch service at ${activateUrl}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (!activationIsUsable(payload)) {
+                return fail("ACTIVATION_INCOMPLETE", "The launch service returned no auth URL or org id.");
+            }
+            const enrichment = activationEnrichment(payload);
+            // 2. Authenticate the CLI. STDIN only — argv is visible in `ps`, and a temp file can
+            //    outlive a crash.
+            const orgAlias = alias?.trim() || targetOrgAlias(payload.instanceUrl, payload.orgId);
+            if (!ALIAS_RE.test(orgAlias))
+                return fail("INVALID_ALIAS", `derived alias ${orgAlias} is not valid.`);
+            const login = await runProcess("sf", 
+            // --sfdx-url-stdin MUST come last. oclif types it as a value flag (`--sfdx-url-stdin=<value>`)
+            // even though the documented usage is `echo url | sf org login sfdx-url --sfdx-url-stdin`,
+            // so anything after it gets swallowed as its value — live-caught: it ate `--alias` and the
+            // alias became a stray positional (exit 2). Last position leaves nothing to consume.
+            ["org", "login", "sfdx-url", "--alias", orgAlias, "--json", "--sfdx-url-stdin"], { env: sfCliEnv(), timeoutMs: 120_000, input: payload.authUrl });
+            if (login.exitCode !== 0) {
+                // Never echo the auth URL, even on failure.
+                return fail("ORG_LOGIN_FAILED", `sf org login sfdx-url failed (exit ${login.exitCode}). The activation code was consumed, so a retry needs a fresh one from Campfire.\n${login.stderr.slice(-400) || login.stdout.slice(-400)}`);
+            }
+            // 3. Confirm the CLI really landed on the org the launch service asserted. A mismatch
+            //    means the payload was not what it claimed — refuse rather than deliver elsewhere.
+            const display = await readOrgDisplay(orgAlias);
+            if (!display.ok) {
+                return fail("ORG_VERIFY_FAILED", `Authenticated but could not read the org back: ${display.detail}`);
+            }
+            const landed = (display.result.id ?? "").slice(0, 15);
+            if (landed !== payload.orgId.slice(0, 15)) {
+                return fail("ORG_ID_MISMATCH", `The launch service said org ${payload.orgId} but the CLI authenticated ${display.result.id}. Refusing fail-closed.`);
+            }
+            // 3b. Grant direct-tier write authority to EXACTLY this org.
+            //
+            // This is the only place a grant is minted, and it sits deliberately after the mismatch
+            // check above: authority is issued against an org id the CLI actually authenticated and
+            // that the launch service independently named. Neither the operator nor the model chooses
+            // it, which is what makes it a safe replacement for CC_MCP_DIRECT_ALLOWLIST=* — that
+            // wildcard authorizes every org the machine is logged into, including, for a consultant,
+            // their own production org.
+            const grant = await recordDirectWriteGrant({
+                orgId: display.result.id ?? payload.orgId,
+                alias: orgAlias,
+                source: "campfire-activation",
+                ...(display.result.username ? { username: display.result.username } : {})
+            });
+            // 3c. Bind the Campfire org too, and SAY SO WHEN IT CANNOT BE BOUND. The requirements in
+            // this session CAME from Campfire, so the session genuinely has a consultant org — recording
+            // it here is what makes writeback possible from an activated session without the operator
+            // restating an alias.
+            //
+            // The result now carries the condition rather than only the success case. This used to
+            // record null on a miss and say nothing, which is how a fresh machine reached step 8 of 9
+            // before discovering that writeback was never possible (see resolveCampfireBinding).
+            const campfireOrgId = payload.campfireOrgId ?? campfireAllowlistedOrgIds()[0];
+            let campfire = await resolveCampfireBinding(campfireOrgId, { aliasForOrgId, readOrgDisplay });
+            // The launch service may have minted a Campfire credential in the same browser round-trip
+            // that authenticated the target org. Log it in exactly as the target org's was — STDIN
+            // only, never argv, never disk — and then RE-READ the binding rather than assuming the
+            // login worked. "We logged something in" and "writeback will work" are different claims,
+            // and only the second is worth reporting.
+            //
+            // Every failure here is non-fatal: the delivery does not depend on this org, and the
+            // notice below already names the manual fix.
+            const plan = campfireLoginPlan(campfire, payload.campfireAuthUrl ? { authUrl: payload.campfireAuthUrl, ...(payload.campfireInstanceUrl ? { instanceUrl: payload.campfireInstanceUrl } : {}) } : undefined, campfireOrgId);
+            if (plan.login && ALIAS_RE.test(plan.alias)) {
+                const campfireLogin = await runProcess("sf", 
+                // --sfdx-url-stdin LAST, for the same oclif reason as the target-org login above: it is
+                // typed as a value flag and swallows whatever follows it.
+                ["org", "login", "sfdx-url", "--alias", plan.alias, "--json", "--sfdx-url-stdin"], { env: sfCliEnv(), timeoutMs: 120_000, input: payload.campfireAuthUrl });
+                if (campfireLogin.exitCode === 0) {
+                    campfire = await resolveCampfireBinding(campfireOrgId, { aliasForOrgId, readOrgDisplay });
+                }
+                // A failed Campfire login is never echoed — the auth URL carries a refresh token, and the
+                // CLI's error text can quote its own argv.
+            }
+            const campfireBinding = campfire.status === "bound" ? { alias: campfire.alias, orgId: campfire.orgId } : null;
+            // 4. Session + requirements, through the SAME path a local import uses.
+            const file = sessionFile(id);
+            let session;
+            if (fileExists(file)) {
+                session = await readJson(file);
+                // First batch wins. Re-activating an existing session into a different batch is a
+                // reporting ambiguity, not a delivery problem, so the original attribution is kept and
+                // the activation proceeds exactly as it did before the ledger existed.
+                if (!session.batchId && enrichment.batchId)
+                    session.batchId = enrichment.batchId;
+                session.actors = enrichment.actors;
+                // Written on both branches, and STICKY on a re-activation: once a session has been told
+                // the question is due, a second activation that could not reach the ledger must not
+                // silently retract it. The flag can only be cleared by recording an answer.
+                if (enrichment.pmfDue)
+                    session.pmfDue = true;
+                if (campfireBinding && !session.campfireOrg?.alias) {
+                    session.campfireOrg = campfireBinding;
+                }
+                await writeJsonAtomic(file, session);
+            }
+            else {
+                session = {
+                    schemaVersion: SESSION_SCHEMA_VERSION,
+                    sessionId: id,
+                    ...(enrichment.batchId ? { batchId: enrichment.batchId } : {}),
+                    actors: enrichment.actors,
+                    requirementBatchRevisionId: opaqueId("rbrev", { sessionId: id }),
+                    ...(enrichment.pmfDue ? { pmfDue: true } : {}),
+                    targetOrg: { alias: orgAlias, orgId: display.result.id ?? payload.orgId },
+                    ...(campfireBinding ? { campfireOrg: campfireBinding } : {}),
+                    producer: await producerIdentity(),
+                    createdAt: isoNow()
+                };
+                await ensureDir(sessionDir(id));
+                await writeJsonAtomic(file, session);
+            }
+            const entries = payload.requirements.map((r) => ({
+                extId: r.reqId,
+                title: r.requirementName ?? r.reqId,
+                text: proseFromActivation(r),
+                ...(r.id ? { campfireId: r.id } : {})
+            }));
+            const imported = entries.length > 0 ? await importRequirementEntries(id, session, entries) : [];
+            // No batch id or no grant means no correlated destination, so nothing is bound and nothing
+            // is emitted. The run continues exactly as it would have before the ledger existed.
+            if (enrichment.bindable && session.batchId) {
+                bindBatchContext({
+                    // The session's own attribution, so events and the session record cannot disagree.
+                    batchId: session.batchId,
+                    installId: processIdentity.installId,
+                    runId: processIdentity.runId,
+                    sessionId: id,
+                    serverVersion: processIdentity.serverVersion,
+                    credential: payload.telemetryGrant.credential,
+                    expiresAt: payload.telemetryGrant.expiresAt,
+                    endpoint: new URL("/api/telemetry/v2", endpoint).toString()
+                });
+                emitDomainTelemetryEvent("requirements.imported", {
+                    requirements: imported.flatMap((requirement) => requirement.inputContentHash
+                        ? [{
+                                externalRequirementId: requirement.extId,
+                                requirementRevisionId: requirement.requirementRevisionId,
+                                inputContentHash: requirement.inputContentHash
+                            }]
+                        : [])
+                }, { stage: "intake", outcome: "imported" });
+                emitDomainTelemetryEvent("batch.activated", { requirementCount: imported.length }, { stage: "intake", outcome: "activated" });
+            }
+            // Preflight. This is the one moment a stale install can be caught cheaply: it is the first
+            // call of every session, the machine is demonstrably online (a code was just redeemed), and
+            // nothing has been read or written yet — so acting on the answer costs the operator
+            // nothing. Discovering it later means a half-finished delivery run on old code.
+            // checkForUpdate never throws; an offline machine simply reports nothing to do.
+            const update = await checkForUpdate();
+            // AND ACT ON IT, rather than mentioning it. LIVE-CAUGHT (QA round 2, 2026-08-06): a tester
+            // ran a full batch on a build 41.6 hours old after being shown `UPDATE AVAILABLE` here, then
+            // updated by hand in a later session — the third time across two QA rounds that this line was
+            // read and not acted on. Under npm distribution the acting splits by staleness:
+            //   stale  — install NOW. The run must not start on this build anyway (the round-1 gate), so
+            //            nothing is in flight for an in-place npm install to skew, and the operator's
+            //            restart lands on the new version instead of on the same stale one.
+            //   behind — safe to run, so nothing installs mid-run (an in-place install can hand a later
+            //            lazy import a different build's module). close_batch installs it after the
+            //            evidence ships, so the NEXT session is current with no one asked to do anything.
+            // A build close_batch installed UNDER this still-running process poisons any further
+            // activation here: the disk (and installedVersion's memo notwithstanding, every future
+            // lazy import) is the new build while the loaded modules are the old one. The successor
+            // batch is legitimate — in a NEW conversation. Say so instead of starting the loop.
+            const installedUnder = updateInstalledUnderThisProcess();
+            const restartNotice = installedUnder
+                ? [
+                    "",
+                    `STOP — A SERVER UPDATE (${installedUnder}) WAS INSTALLED WHEN THE PREVIOUS BATCH CLOSED, and this conversation is still running the build before it.`,
+                    "Running another batch here would mix two builds' code. Tell the operator to START A NEW CHAT and",
+                    "paste this activation prompt again — the activation itself succeeded and nothing is lost. Then STOP."
+                ]
+                : [];
+            const action = updateActionFor(update);
+            let installed;
+            if (action === "stop-and-update") {
+                // DETACHED, not awaited. The activation code was redeemed (single-use) several steps
+                // ago, and an awaited `npm install -g` can hold this tool call for minutes on a cold
+                // cache — a client timeout then reads as a failed activation whose retry is impossible.
+                // The session stops on this path either way, so npm runs in the background and the next
+                // session's gate re-checks; a start that failed silently just fires the gate again.
+                const started = await startDetachedInstall();
+                installed = started.ok
+                    ? { ok: true, fromVersion: update.currentVersion, toVersion: started.toVersion, updated: true }
+                    : { ok: false, fromVersion: update.currentVersion, updated: false, failure: started.failure, error: started.error };
+            }
+            else if (action === "update-at-close") {
+                scheduleUpdateAtClose();
+            }
+            // The live-progress viewer. Read-only, spawned detached, and reused when one is already
+            // serving — see src/core/viewer.ts for why nothing here can fail the activation. Awaited
+            // rather than fired-and-forgotten only because the result text needs to know whether to
+            // print a URL or a WARN, and the whole thing is capped at ~2s.
+            const viewer = await ensureViewer().catch((error) => ({
+                status: "warn",
+                url: viewerBaseUrl(),
+                port: viewerPort(),
+                detail: error instanceof Error ? error.message : String(error)
+            }));
+            return ok([
+                `Session ${id} ACTIVATED from Campfire.`,
+                "",
+                `Acting as: ${payload.username} (every org change will be attributed to this user)`,
+                `Target org: ${display.result.id} — alias ${orgAlias}`,
+                `Instance: ${display.result.instanceUrl}`,
+                // Say what authority was just granted, and how narrow it is. An operator should never
+                // have to infer which orgs this install can write to.
+                `Write authority: THIS org only (${grant.orgId}), until ${grant.expiresAt.slice(0, 10)}. No other org is writable by this install.`,
+                // Provider narrowness belongs beside org narrowness: a machine that also carries another
+                // Salesforce MCP must be told, at the same moment it learns which org is writable, which
+                // MCP is doing the writing.
+                `Provider: this batch runs on the IN2 MCP alone. Do not use any other Salesforce MCP for its reads, deploys, verification, rollback, or close.`,
+                `Requirements imported: ${imported.length}`,
+                ...imported.map((e) => `  ${e.extId} — ${e.title}`),
+                // Placed ABOVE the update notice and the next-steps block deliberately: it is the one
+                // thing in this result that is cheap to fix now and expensive to discover in thirty
+                // minutes. Empty when the Campfire org is live, which is the normal case.
+                ...campfireBindingNotice(campfire),
+                ...restartNotice,
+                ...updateNotice(update, installed),
+                // The one line the operator wants immediately: where to watch. Relayed verbatim —
+                // never invent a URL, and never a different session's.
+                ...viewerNotice(viewer, id),
+                "",
+                // The operator's prompt is one line; they will not describe the workflow. State the
+                // next steps outright rather than pointing at "the standard loop" — the model may
+                // never have seen that document, since it only loads from a specific directory.
+                "The org is authenticated in the sf CLI; no manual login is needed.",
+                "",
+                "NEXT, without asking the operator how to proceed:",
+                "  1. Read all imported requirements above and form the batch model (shared objects, the dependency ladder between them, cross-requirement ambiguity).",
+                "  2. `project_org` ONCE over the touched scope — it is ground truth, and requirement-asserted API names are untrusted until confirmed there.",
+                "  3. Fan out one plan-requirement analyzer per requirement against that projection; each writes its plan.json ownership (which is what maps Configuration Items to requirements later).",
+                "  4. Come back with ONE clarification card, then ONE approval card. Change nothing in the org before they approve.",
+                ...(enrichment.pmfDue
+                    ? [
+                        "",
+                        // The one run-scoped instruction the static contract cannot carry: it is composed
+                        // at connect time from the environment, long before any activation happened, so
+                        // this is the only channel that can tell THIS session the ask is due.
+                        "FEEDBACK: the relational question is DUE for this operator on this batch. At close, after the three usual cards, ask ONE more: \"How would you feel if you could no longer use IN2?\" — Very disappointed / Somewhat disappointed / Not disappointed / I no longer use IN2 — and record it with `record_operator_feedback {pmfAnswer}`. It is due because of THEIR batch history, not this run's; never ask it on a session that was not told to."
+                    ]
+                    : [])
+            ].join("\n"), {
+                sessionId: id,
+                ...(enrichment.batchId ? { batchId: enrichment.batchId } : {}),
+                orgAlias,
+                orgId: display.result.id,
+                ...(enrichment.actors.targetUserId ? { targetUserId: enrichment.actors.targetUserId } : {}),
+                username: payload.username,
+                // Structured too, so a caller keying on the field sees the same answer as the prose.
+                campfireOrgStatus: campfire.status,
+                ...("alias" in campfire ? { campfireOrgAlias: campfire.alias } : {}),
+                ...(viewer.status === "warn" ? {} : { viewerUrl: `${viewer.url}/?session=${encodeURIComponent(id)}` }),
+                ...updateStructuredFields(update, installed),
+                imported: imported
+            });
+        }
+        catch (error) {
+            return internalError(error);
+        }
+    });
+}