in2-agent-server 0.20260821.185429

package/dist/core/update.js

@@ -0,0 +1,363 @@
+// Self-update over npm: check the registry, and install with `npm install -g`.
+//
+// THE BESPOKE UPDATER IS GONE (2026-08-21, docs/plans/2026-08-07-017-npm-distribution-decision.md
+// resolved as Option B). Four distinct live-caught bugs came out of the download/checksum/unpack/
+// repoint/hot-swap machinery across two QA rounds; npm's installer is the one battle-tested piece
+// of infrastructure every consultant machine already has, because Node ships it. What this module
+// keeps is the part npm does not do: deciding WHEN an install is too old to run (the staleness
+// gate, live-caught in QA round 1), and running the npm install from inside a session.
+//
+// WHAT REPLACING FILES UNDER A RUNNING PROCESS MEANS NOW. The old system installed each release
+// into its own directory precisely so no file was ever replaced under an open process, then swapped
+// the tool surface live. npm installs IN PLACE. A running server has its module graph loaded, but
+// it lazy-imports several of its own dist files mid-run (crud.js, orgRepo.js, parcels.js, …) — an
+// install that replaces dist under a session mid-batch can hand a later dynamic import a DIFFERENT
+// build's module. So updates happen only at the EDGES of a run:
+//   - `stale` at activation → install, then STOP; the session was never going to proceed anyway.
+//   - `behind` at activation → noted, and close_batch installs it AFTER the evidence has shipped,
+//     when the process is about to exit and nothing will import anything again. The next session
+//     starts current without this one restarting — which preserves what the QA round 2 auto-apply
+//     was actually for (notices alone were read and ignored three times running).
+//   - `update_server {apply:true}` mid-session installs on request and SAYS the running session
+//     keeps its loaded build; a fresh conversation gets the new one.
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { PACKAGE_NAME, SERVER_ROOT, installedVersion, isNewer, isNpmInstall } from "./install.js";
+import { redactSecrets } from "./betaFeedback.js";
+const exec = promisify(execFile);
+// Updater errors are the one string that routinely carries the consultant's machine into
+// model-facing text: filesystem paths under their home directory (live-caught on the Windows QA
+// runs). Sanitized HERE, at the module boundary, because every consumer — update_server's
+// UPDATE_FAILED and activation's updateNotice — renders whatever this module hands them.
+export function sanitizeUpdateError(text) {
+    return redactSecrets(text
+        // A path SEGMENT ends at the next separator, not at whitespace — "Jane Doe" is one segment,
+        // and stopping early on the space between the two names leaked the surname verbatim.
+        .replace(/([A-Za-z]):\\Users\\[^\\/'"]+/g, "$1:\\Users\\<user>")
+        .replace(/\/(?:Users|home)\/[^\\/'"]+/g, (m) => m.slice(0, m.lastIndexOf("/") + 1) + "<user>"));
+}
+/**
+ * HOW OLD A BUILD MAY BE BEFORE THE RUN STOPS BEING WORTH STARTING.
+ *
+ * LIVE-CAUGHT (QA round 1, 2026-08-06). Two testers ran batches on builds two days stale. One hit
+ * `ORG_NOT_BOUND` at the Campfire writeback — step 8 of 9 — from a bug fixed ~21 hours after the
+ * build they were on was cut; the other's run produced no phase telemetry at all. Both saw an
+ * `UPDATE AVAILABLE` line at activation. Both ran anyway. A notice that competes with fourteen
+ * other lines of activation output is not a gate, and the cost of ignoring it was a wasted
+ * multi-hour run and a Salesforce org left half-configured.
+ *
+ * Days rather than version distance: releases are cut several times a day, so "12 releases behind"
+ * is noise, while "your build predates two days of fixes" is the thing that correlates with hitting
+ * an already-fixed bug.
+ *
+ * Override with `CC_MCP_STALE_AFTER_DAYS`. `0` disables the block entirely — for developing against
+ * an intentionally pinned build, which is the one legitimate reason to run knowingly old code.
+ */
+export const DEFAULT_STALE_AFTER_DAYS = 2;
+export function staleAfterDays(env = process.env) {
+    const raw = (env.CC_MCP_STALE_AFTER_DAYS ?? "").trim();
+    if (!raw)
+        return DEFAULT_STALE_AFTER_DAYS;
+    const parsed = Number(raw);
+    // A typo must not silently disable the gate — fall back to the default rather than to 0.
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_STALE_AFTER_DAYS;
+}
+/**
+ * The UTC instant a `0.YYYYMMDD.HHMMSS` version names, or null for anything else.
+ *
+ * A version is derived from its merge commit's UTC timestamp (see AGENTS.md), so the string IS the
+ * build date and no extra lookup is needed. The third component is HHMMSS **as a number** — semver
+ * forbids leading zeros, so `02:05:55` publishes as `.20555`, not `.020555` — and it is re-padded
+ * to six digits here before parsing. `0.0.0` (an unreadable package.json) and ordinary semver
+ * versions parse to null, which callers must treat as "cannot tell" rather than "not stale".
+ */
+export function versionStamp(version) {
+    const match = /^\d+\.(\d{4})(\d{2})(\d{2})\.(\d{1,6})$/.exec(version.trim());
+    if (!match)
+        return null;
+    const [, y, mo, d, hms] = match;
+    const padded = hms.padStart(6, "0");
+    const [h, mi, s] = [padded.slice(0, 2), padded.slice(2, 4), padded.slice(4, 6)];
+    const at = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s));
+    return Number.isFinite(at) ? new Date(at) : null;
+}
+/**
+ * Whole days the installed build is behind the published one. Null when either version is not a
+ * release stamp — a checkout reports no age rather than a fabricated one.
+ */
+export function daysBehind(current, latest) {
+    const [from, to] = [versionStamp(current), versionStamp(latest)];
+    if (!from || !to)
+        return null;
+    return Math.max(0, Math.floor((to.getTime() - from.getTime()) / 86_400_000));
+}
+export function classifyStaleness(check, thresholdDays = staleAfterDays()) {
+    if (!check.updateAvailable || !check.latestVersion)
+        return { staleness: "current" };
+    const behind = daysBehind(check.currentVersion, check.latestVersion);
+    if (behind === null)
+        return { staleness: "behind" };
+    // `0` disables the block; without this guard it would classify every update as stale.
+    const stale = thresholdDays > 0 && behind >= thresholdDays;
+    return { staleness: stale ? "stale" : "behind", behindDays: behind };
+}
+export function updateActionFor(check) {
+    if (!check.updateAvailable)
+        return "none";
+    if (!check.managed)
+        return "update-by-hand";
+    return check.staleness === "stale" ? "stop-and-update" : "update-at-close";
+}
+const REGISTRY = "https://registry.npmjs.org";
+/**
+ * The latest published version, from the npm registry's abbreviated metadata.
+ *
+ * `CC_MCP_REGISTRY` overrides the host (a mirror, or a test double) — never a launch-service URL:
+ * distribution and activation are separate concerns now, and only activation still needs
+ * CC_MCP_LAUNCH_URL.
+ */
+export async function fetchLatestVersion(registry) {
+    const base = (registry ?? process.env.CC_MCP_REGISTRY ?? REGISTRY).trim().replace(/\/$/, "");
+    const res = await fetch(`${base}/${PACKAGE_NAME}`, {
+        // The abbreviated document is ~50x smaller than the full packument and carries dist-tags.
+        headers: { accept: "application/vnd.npm.install-v1+json" },
+        signal: AbortSignal.timeout(20_000)
+    });
+    if (!res.ok)
+        throw new Error(`registry check failed: HTTP ${res.status}`);
+    const body = (await res.json());
+    const latest = body["dist-tags"]?.latest;
+    if (!latest)
+        throw new Error("registry response carries no dist-tags.latest");
+    return latest;
+}
+// Never throws. A version check is a convenience run on the way to doing real work, and an offline
+// laptop or a registry having a bad day must not turn into a failed activation.
+export async function checkForUpdate(registry) {
+    const currentVersion = installedVersion();
+    const managed = isNpmInstall();
+    try {
+        const latestVersion = await fetchLatestVersion(registry);
+        let reason;
+        if (!managed) {
+            const raw = `not an npm install (running from ${SERVER_ROOT})`;
+            console.error(raw);
+            reason = sanitizeUpdateError(raw);
+        }
+        const base = {
+            currentVersion,
+            latestVersion,
+            updateAvailable: isNewer(latestVersion, currentVersion),
+            managed,
+            ...(reason ? { reason } : {})
+        };
+        return { ...base, ...classifyStaleness(base) };
+    }
+    catch (error) {
+        return {
+            currentVersion,
+            updateAvailable: false,
+            managed,
+            // An unreachable registry says nothing about how old this build is, and guessing "stale"
+            // would block every offline run. Unknown is `current` by construction here.
+            staleness: "current",
+            reason: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+/**
+ * How to run npm — the npm that belongs to THIS node, wherever it is.
+ *
+ * `npm` cannot be assumed on PATH: MCP servers spawn with whatever minimal environment the client
+ * provides, and a PATH that resolves the right `node` (this process exists, so it did) still may
+ * not carry npm's shim directory. npm itself, though, ships inside every Node distribution at a
+ * fixed spot relative to the node binary — so the binary this process IS running is the one
+ * reliable anchor. PATH `npm` is the fallback, not the default.
+ *
+ * Exported for the doctor; the shape mirrors sfInvocation in spawn.ts for the same Windows reason
+ * (a .cmd shim cannot be spawned directly — CVE-2024-27980).
+ */
+export function npmInvocation(args) {
+    const nodeDir = path.dirname(process.execPath);
+    const candidates = process.platform === "win32"
+        ? [path.join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js")]
+        : [
+            path.join(nodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+            path.join(nodeDir, "..", "node_modules", "npm", "bin", "npm-cli.js")
+        ];
+    for (const cli of candidates) {
+        if (existsSync(cli))
+            return { command: process.execPath, args: [cli, ...args] };
+    }
+    // No npm beside the binary (a standalone node, or an unusual layout) — fall back to PATH. On
+    // Windows that must go through cmd.exe because the PATH entry is npm.cmd.
+    if (process.platform === "win32") {
+        return { command: "cmd.exe", args: ["/d", "/s", "/c", "npm", ...args] };
+    }
+    return { command: "npm", args };
+}
+/**
+ * The npm global prefix THIS install lives under, derived from where this module is.
+ *
+ * Derived and passed explicitly (`npm install -g --prefix …`) rather than left to npm's own
+ * resolution, because the two can disagree: the bootstrap installs under a private prefix
+ * (~/.in2-agent/npm-global) precisely so no machine ever needs sudo, while the npm on PATH — or
+ * beside a different node — defaults to the system prefix. An update that resolves the prefix
+ * itself would install a second copy somewhere else and leave the registered one stale, which
+ * reads as "the update said it worked and nothing changed".
+ *
+ * Layouts: <prefix>/lib/node_modules/<pkg> (posix) and <prefix>/node_modules/<pkg> (Windows).
+ */
+export function installPrefix() {
+    const parts = SERVER_ROOT.split(path.sep);
+    const idx = parts.lastIndexOf("node_modules");
+    if (idx < 0)
+        return undefined;
+    const above = parts.slice(0, idx);
+    if (above[above.length - 1] === "lib")
+        above.pop();
+    return above.join(path.sep) || undefined;
+}
+/**
+ * Start the install and DON'T wait for it — for the one caller that must not block: activation.
+ *
+ * The stale path installs at activation, but an awaited `npm install -g` can run for minutes on a
+ * cold cache, and the activation code was already redeemed (single-use) before the check ran — a
+ * client-side tool timeout mid-install reads as a failed activation whose retry is impossible.
+ * So the stale path fires npm detached and returns immediately: the session stops either way, the
+ * operator restarts, and if the install has not landed yet the next activation's gate simply fires
+ * again and retries. Self-healing by construction; nothing depends on this attempt succeeding.
+ *
+ * The registry read IS awaited (20 s cap): without a resolved version there is nothing to install,
+ * and its failure is worth reporting synchronously as the old imperative.
+ */
+export async function startDetachedInstall() {
+    if (!isNpmInstall()) {
+        const raw = `not an npm install (running from ${SERVER_ROOT})`;
+        console.error(raw);
+        return { ok: false, failure: "not-managed", error: sanitizeUpdateError(raw) };
+    }
+    try {
+        const latest = await fetchLatestVersion();
+        const prefix = installPrefix();
+        const { command, args } = npmInvocation([
+            "install",
+            "-g",
+            `${PACKAGE_NAME}@${latest}`,
+            ...(prefix ? [`--prefix=${prefix}`] : []),
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund"
+        ]);
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        child.unref();
+        return { ok: true, toVersion: latest };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        return { ok: false, failure: "failed", error: sanitizeUpdateError(message) };
+    }
+}
+/**
+ * A `behind` build noticed at activation, remembered until close.
+ *
+ * Installing mid-run is unsafe (in-place npm install vs. this process's lazy imports — module
+ * header), and QA rounds 1-2 proved a notice asking anyone to act later is a notice ignored. So
+ * activation records the intent and `close_batch` performs it after the evidence has shipped: the
+ * last tool call of the run, after which the process only exits. The next session starts current
+ * without this one restarting — the same outcome the hot-swap auto-apply bought, one session later.
+ *
+ * In-process state, deliberately: a pending update that outlives the process is just "an update is
+ * available", which the next activation's check rediscovers on its own.
+ */
+let pendingAtClose = false;
+export function scheduleUpdateAtClose() {
+    pendingAtClose = true;
+}
+/** Install the update activation deferred, if any. Called by close_batch; never throws. */
+export async function installPendingUpdate() {
+    if (!pendingAtClose)
+        return undefined;
+    pendingAtClose = false;
+    const result = await installUpdate();
+    if (result.ok && result.updated)
+        installedUnderThisProcess = result.toVersion;
+    return result;
+}
+/**
+ * The version an at-close install landed UNDER this still-running process, if any.
+ *
+ * Exists for the second-activation-same-chat case: close_batch installed the new build in place,
+ * the process lived on, and the operator pastes another code into the same conversation (the
+ * successor-batch pattern makes that legitimate). That session would run build-X callers against
+ * build-Y lazy imports — the exact mixed-build state the update timing exists to prevent — so
+ * activation checks this first and stops with a restart instead of starting the loop.
+ */
+let installedUnderThisProcess;
+export function updateInstalledUnderThisProcess() {
+    return installedUnderThisProcess;
+}
+/**
+ * Install the published release with `npm install -g`. Never throws.
+ *
+ * The RUNNING process keeps its loaded build regardless of what this writes to disk — Node's
+ * module cache holds what was imported, and nothing here can (or tries to) refresh it. Callers own
+ * the timing: this must only run when the session will not lazily import anything else that
+ * matters, which in practice means "at activation before a stop" or "at close_batch after the
+ * evidence has shipped". See the module header for why mid-run is unsafe.
+ *
+ * `force` reinstalls even when the published version is not newer — the documented repair path for
+ * a damaged install (`npm install -g pkg@latest` re-extracts unconditionally when told a version).
+ */
+export async function installUpdate(options = {}) {
+    const fromVersion = installedVersion();
+    const base = { ok: false, fromVersion, updated: false };
+    if (!isNpmInstall()) {
+        const raw = `not an npm install (running from ${SERVER_ROOT})`;
+        console.error(raw);
+        return { ...base, failure: "not-managed", error: sanitizeUpdateError(raw) };
+    }
+    try {
+        const latest = await fetchLatestVersion(options.registry);
+        if (!options.force && !isNewer(latest, fromVersion)) {
+            return { ...base, ok: true, toVersion: latest };
+        }
+        const spec = `${PACKAGE_NAME}@${latest}`;
+        const prefix = installPrefix();
+        const { command, args } = npmInvocation([
+            "install",
+            "-g",
+            spec,
+            // Into THIS install's prefix, explicitly — npm's own default can name a different one, and
+            // then the update lands as a second copy while the registered server stays stale.
+            ...(prefix ? [`--prefix=${prefix}`] : []),
+            // No scripts: the package needs none to install (skills/agents copy on first run instead),
+            // and an update path that executes arbitrary lifecycle hooks is a bigger surface than the
+            // convenience is worth. --no-audit/--no-fund for the same reason the old installer used
+            // them: an update must not stall on advisory network calls.
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund",
+            ...(options.registry ? [`--registry=${options.registry}`] : [])
+        ]);
+        await exec(command, args, { timeout: options.timeoutMs ?? 600_000 });
+        return { ...base, ok: true, updated: true, toVersion: latest };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        // "Nothing was changed" is a claim, so verify it. npm installs IN PLACE, and an npm killed
+        // mid-extract (the 10-minute timeout, a dropped connection) can leave the package directory
+        // half-replaced — at which point "the next activation will retry" is false, because the next
+        // conversation has no server to activate with. The one file whose absence proves that is the
+        // entry the registration points at.
+        const entryIntact = existsSync(path.join(SERVER_ROOT, "dist", "index.js"));
+        const detail = entryIntact
+            ? sanitizeUpdateError(message)
+            : `${sanitizeUpdateError(message)} — AND the install directory is now incomplete (dist/index.js is missing). The next conversation may fail to start; repair from a terminal with: npm install -g ${PACKAGE_NAME}@latest`;
+        return { ...base, failure: "failed", error: detail };
+    }
+}

package/dist/core/viewer.js

@@ -0,0 +1,117 @@
+// The read-only session viewer: start it if it isn't up, reuse it if it is.
+//
+// The viewer (`<install>/viewer/server.mjs`) is a dependency-free Node HTTP server that projects one
+// session directory into a localhost UI. It writes nothing and talks to nothing but the filesystem,
+// which is what makes this helper's whole failure policy "shrug": a viewer that never started costs
+// the operator a browser tab, never a delivery. Every path below therefore returns a WARN outcome
+// rather than throwing, and the caller appends a line either way.
+//
+// LIFECYCLE IS DELIBERATELY ABSENT. Nothing kills the viewer — not close_batch, not process exit.
+// It is read-only, so leaving it up showing the final report is the useful end state, and the next
+// activation's healthz probe adopts it. There is no PID file and no manager layer on purpose: the
+// port IS the registry.
+import { spawn as spawnChild } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { APP_ROOT, WORKSPACE_ROOT } from "./paths.js";
+/**
+ * Where the viewer lives.
+ *
+ * A plain join rather than the `existsSync ? shipped : repo` pattern SKILLS_DIR and the playbook
+ * need: the build artifact stages `viewer/` at the stage root and the repo keeps it at
+ * `apps/cc-mcp-server/viewer/`, and APP_ROOT resolves to each of those respectively — so the same
+ * relative path is correct in both, with nothing to disambiguate.
+ */
+export const VIEWER_SCRIPT = path.join(APP_ROOT, "viewer", "server.mjs");
+/** Must agree with `viewer/server.mjs`, which reads the same variable and defaults the same way. */
+export function viewerPort() {
+    const raw = Number(process.env.IN2_VIEWER_PORT);
+    return Number.isInteger(raw) && raw > 0 && raw < 65_536 ? raw : 4199;
+}
+export function viewerBaseUrl(port = viewerPort()) {
+    return `http://localhost:${port}`;
+}
+const PROBE_TIMEOUT_MS = 500;
+const POLL_BUDGET_MS = 2_000;
+const POLL_INTERVAL_MS = 150;
+async function defaultProbe(url, timeoutMs) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        return res.ok;
+    }
+    catch {
+        // Connection refused, DNS, timeout — all the same answer here: nothing is serving.
+        return false;
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Ensure a viewer is serving, and say which of the three things happened.
+ *
+ * Order matters: PROBE FIRST. Two sessions in a row, or two Claude Code windows, must not each
+ * spawn a server onto the same port — the second would die EADDRINUSE and the operator would be
+ * told a viewer started that isn't theirs. An answering healthz means someone else's process is
+ * already serving the same read-only projection, which is exactly what we want.
+ */
+export async function ensureViewer(deps = {}) {
+    const port = viewerPort();
+    const url = viewerBaseUrl(port);
+    const health = `${url}/healthz`;
+    const probe = deps.probe ?? defaultProbe;
+    const sleep = deps.sleep ?? defaultSleep;
+    const exists = deps.exists ?? existsSync;
+    const spawn = deps.spawn ?? spawnChild;
+    const script = deps.script ?? VIEWER_SCRIPT;
+    try {
+        if (await probe(health, PROBE_TIMEOUT_MS))
+            return { status: "reused", url, port };
+        // A repo checkout without a built artifact, or a partial install. Degrade rather than throw —
+        // this is a cosmetic convenience on the most important call of the session.
+        if (!exists(script)) {
+            return { status: "warn", url, port, detail: `no viewer at ${script}` };
+        }
+        // stdio "ignore" IS LOAD-BEARING, not tidiness. This server speaks MCP over its OWN stdio: a
+        // child that inherited the handles could write a startup banner straight into the JSON-RPC
+        // stream and desync the client mid-session. `detached` + `unref` then let the viewer outlive
+        // this process, which is the point — the operator keeps reading the final report after the
+        // conversation ends. Both flags behave the same way on Windows, where an inherited handle
+        // additionally keeps the console alive after the parent exits.
+        const child = spawn(process.execPath, [script, deps.sessionsRoot ?? WORKSPACE_ROOT], {
+            detached: true,
+            stdio: "ignore",
+            env: process.env
+        });
+        // A detached child that fails to launch emits 'error' ASYNCHRONOUSLY, and an 'error' event with
+        // no listener is an unhandled exception that takes the whole MCP server down. The poll below is
+        // the real verdict, so the event itself is deliberately swallowed.
+        child.on("error", () => undefined);
+        child.unref();
+        // The child binds its port before it can answer, so a single immediate probe would always say
+        // dead. Poll to a hard cap: activation must not sit here waiting on a browser convenience.
+        const budgetMs = deps.pollBudgetMs ?? POLL_BUDGET_MS;
+        const deadline = Date.now() + budgetMs;
+        while (Date.now() < deadline) {
+            await sleep(POLL_INTERVAL_MS);
+            if (await probe(health, PROBE_TIMEOUT_MS))
+                return { status: "started", url, port };
+        }
+        return { status: "warn", url, port, detail: `spawned but ${health} did not answer within ${budgetMs}ms` };
+    }
+    catch (error) {
+        return { status: "warn", url, port, detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * The activation lines. The session id is PINNED into the URL: the viewer defaults to the
+ * newest-mtime session, so two concurrent deliveries sharing one viewer would otherwise both point
+ * at whichever ran last.
+ */
+export function viewerNotice(outcome, sessionId) {
+    if (outcome.status === "warn") {
+        return [
+            "",
+            `WARN: the live progress viewer did not start (${outcome.detail ?? "unknown"}). This changes nothing about the delivery — the viewer is read-only. Do not retry it or mention it again.`
+        ];
+    }
+    return ["", `Live progress: ${outcome.url}/?session=${encodeURIComponent(sessionId)}`];
+}

package/dist/core/workspace.js

@@ -0,0 +1,92 @@
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { WORKSPACE_ROOT } from "./paths.js";
+import { OPAQUE_ID_RE } from "./ids.js";
+export class WorkspaceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "WorkspaceError";
+    }
+}
+export function assertWorkspaceId(kind, value) {
+    if (!OPAQUE_ID_RE.test(value)) {
+        throw new WorkspaceError("INVALID_ID", `${kind} must match ${OPAQUE_ID_RE} (got ${JSON.stringify(value)}).`);
+    }
+}
+export function sessionDir(sessionId) {
+    assertWorkspaceId("sessionId", sessionId);
+    return path.join(WORKSPACE_ROOT, sessionId);
+}
+export function sessionFile(sessionId) {
+    return path.join(sessionDir(sessionId), "session.json");
+}
+export function requirementDir(sessionId, extId) {
+    assertWorkspaceId("extId", extId);
+    return path.join(sessionDir(sessionId), "requirements", extId);
+}
+export function analysisCurrentFile(sessionId, extId) {
+    return path.join(requirementDir(sessionId, extId), "analysis", "current.json");
+}
+export function analysisCheckpointFile(sessionId, extId, revision) {
+    return path.join(requirementDir(sessionId, extId), "analysis", "checkpoints", `${String(revision).padStart(4, "0")}.json`);
+}
+export function planDir(sessionId) {
+    return path.join(sessionDir(sessionId), "plan");
+}
+/**
+ * One file per question round put to the operator (`0001.json`, `0002.json`, …).
+ *
+ * Lives here rather than in `tools/operator.ts`, which wrote it and owned the path: the round files
+ * are now read by `core/operatorQa.ts` to ship what was asked and answered, and `core` must not
+ * import from `tools` — the dependency runs the other way everywhere else.
+ */
+export function questionsDir(sessionId) {
+    return path.join(sessionDir(sessionId), "questions");
+}
+/**
+ * The append-only record of which chapter of the run this session is in (`core/phases.ts`).
+ *
+ * AT THE TOP OF THE SESSION DIRECTORY, beside `session.json`, rather than under a subdirectory:
+ * every other artifact here is produced BY a phase, and this one is about the phases themselves.
+ * A fresh session resuming a dead run reads this file first and the artifacts second.
+ */
+export function phaseLedgerFile(sessionId) {
+    return path.join(sessionDir(sessionId), "phases.jsonl");
+}
+export function dispositionsFile(sessionId) {
+    return path.join(sessionDir(sessionId), "dispositions", "dispositions.json");
+}
+export function writebackDir(sessionId) {
+    return path.join(sessionDir(sessionId), "writeback");
+}
+export async function ensureDir(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+export async function writeJsonAtomic(file, value) {
+    await ensureDir(path.dirname(file));
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    await fs.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await fs.rename(tmp, file);
+}
+export async function writeTextAtomic(file, text) {
+    await ensureDir(path.dirname(file));
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    await fs.writeFile(tmp, text, "utf8");
+    await fs.rename(tmp, file);
+}
+export async function readJson(file) {
+    const raw = await fs.readFile(file, "utf8");
+    return JSON.parse(raw);
+}
+export function fileExists(file) {
+    return existsSync(file);
+}
+export async function listDirs(dir) {
+    if (!existsSync(dir))
+        return [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}

package/dist/core/writeGrants.js

@@ -0,0 +1,93 @@
+// Activation-scoped write authority.
+//
+// The problem this solves: direct-tier write authority came only from CC_MCP_DIRECT_ALLOWLIST, an
+// env var fixed when the MCP server is spawned. An org's id is not knowable until someone has
+// logged into it, so a customer could never be pre-listed — which is why internal testing reached
+// for the `*` wildcard. That wildcard makes every authenticated org writable, and shipping it to a
+// consultant who also has their production org in the sf CLI is the single largest foreseeable
+// blast radius in this system.
+//
+// A grant is the alternative: activate_session authenticates exactly one org, VERIFIES that the org
+// the CLI landed on matches the one the launch service named (refusing otherwise), and records a
+// grant for that org id. Write authority then means "the org this install was activated against"
+// rather than "whatever the operator's machine happens to be logged into".
+//
+// Why a file rather than session state: direct_apply takes targetOrg, not sessionId, so the gate has
+// no session to consult. Threading a session id through every write tool would put the authority
+// decision in the model's hands — it could pass a different session than the one that granted
+// access. A grant keyed by org id, read straight from disk by the gate, cannot be argued with.
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { WORKSPACE_ROOT } from "./paths.js";
+export const GRANTS_SCHEMA_VERSION = "direct-write-grants-v1";
+// A grant outlives a single session on purpose — a consultant reasonably continues work in a new
+// conversation without re-clicking through Campfire. It does NOT outlive the engagement: an
+// abandoned laptop should not stay authorized against a client org indefinitely.
+const DEFAULT_GRANT_TTL_DAYS = 30;
+export function grantsFilePath() {
+    return path.join(WORKSPACE_ROOT, "..", "direct-write-grants.json");
+}
+function normalize(orgId) {
+    return orgId.slice(0, 15);
+}
+function grantTtlDays() {
+    const raw = Number(process.env.CC_MCP_GRANT_TTL_DAYS);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_GRANT_TTL_DAYS;
+}
+async function readGrantsFile() {
+    const file = grantsFilePath();
+    if (!existsSync(file))
+        return { schemaVersion: GRANTS_SCHEMA_VERSION, grants: [] };
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        return { schemaVersion: GRANTS_SCHEMA_VERSION, grants: Array.isArray(parsed.grants) ? parsed.grants : [] };
+    }
+    catch {
+        // A corrupt grants file must not become an accidental grant, and must not wedge the server
+        // either. Treat it as "no grants" — the operator re-activates, which is a recoverable state.
+        return { schemaVersion: GRANTS_SCHEMA_VERSION, grants: [] };
+    }
+}
+/** Non-expired grants, newest first. */
+export async function activeGrants(now = new Date()) {
+    const { grants } = await readGrantsFile();
+    return grants
+        .filter((g) => {
+        const expiry = Date.parse(g.expiresAt);
+        // An unparseable expiry is treated as expired, never as forever.
+        return Number.isFinite(expiry) && expiry > now.getTime();
+    })
+        .sort((a, b) => b.grantedAt.localeCompare(a.grantedAt));
+}
+export async function isOrgGranted(orgId, now = new Date()) {
+    const target = normalize(orgId);
+    return (await activeGrants(now)).some((g) => normalize(g.orgId) === target);
+}
+/**
+ * Record write authority for exactly one org. Called by activate_session AFTER it has confirmed the
+ * CLI authenticated the org the launch service named — never on the operator's say-so alone.
+ */
+export async function recordDirectWriteGrant(input, now = new Date()) {
+    const grant = {
+        orgId: normalize(input.orgId),
+        alias: input.alias,
+        grantedAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + grantTtlDays() * 86_400_000).toISOString(),
+        source: input.source,
+        ...(input.username ? { username: input.username } : {})
+    };
+    const { grants } = await readGrantsFile();
+    // Re-activating the same org refreshes rather than accumulates; other orgs are preserved so a
+    // consultant working across two clients does not lose one by activating the other.
+    const next = [grant, ...grants.filter((g) => normalize(g.orgId) !== grant.orgId)];
+    const file = grantsFilePath();
+    await mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, JSON.stringify({ schemaVersion: GRANTS_SCHEMA_VERSION, grants: next }, null, 2), {
+        encoding: "utf8",
+        mode: 0o600
+    });
+    await rename(tmp, file);
+    return grant;
+}