@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/cli/session-start/toolchain-parity.js

@@ -1,797 +0,0 @@
-// `harness session-start toolchain-parity` — SessionStart hook entrypoint,
-// third sibling of `harness session-start preflight` / `branch-check`.
-//
-// Anlass: the 2026-07-22 PATH-shim incident, where a machine ran an entire
-// session unnoticed on Node 22 + understanding-gate 0.4.6 instead of the
-// intended Node 26 + 0.4.9 — nothing on that machine ever compared its own
-// toolchain against any other machine's. This producer closes that gap,
-// purely advisorily:
-//
-//   (a) writes a toolchain snapshot of THIS machine to
-//       `<machineStateDir>/<ownProfile>.json` (owner-writes-only — every
-//       OTHER `*.json` in that directory is read-only input, never
-//       touched);
-//   (b) compares the local LIVE toolchain state against every peer
-//       snapshot file already in that directory;
-//   (c) reports drift as stderr warning lines plus a single
-//       `toolchain-parity:ok` / `toolchain-parity:drift:<n>` ledger fact,
-//       with a `:unparseable-peer:<n>` suffix appended whenever one or more
-//       peer files failed to parse as JSON (task 690fba7c, follow-up from
-//       the agent-memory 06d09cde incident: an unparseable peer snapshot is
-//       a real corruption/drift signal and must not vanish from `drift:N`
-//       as if it had been a complete comparison).
-//
-// Transport of the snapshot files BETWEEN machines is entirely
-// agent-memory-sync's job (agent-memory PR #64, already shipped) — this
-// module only ever reads/writes the local directory.
-//
-// SessionStart contract, same as the two siblings: `blocking:false`. Every
-// failure path (not configured, mkdir/write/read failure, a broken peer
-// file, a spawn timeout, a ledger-write failure) logs one line to stderr
-// and exits 0. There is no "gate" this producer can leave closed — it is
-// purely advisory, so degrading silently (well, LOUDLY on stderr, just
-// never blocking) is always the right move.
-import { execFile } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { readTopLevelMcpServers, resolveClaudeUserRegistryPath, } from "../../io/claude-mcp.js";
-import { assertNoRealSpawnInTests } from "../../runtime/hermetic-spawn-guard.js";
-import { resolveManifestLedgerWriter } from "../../runtime/ledger-writer.js";
-import { resolveReadSessionId, } from "../../runtime/session-id.js";
-import { loadManifest } from "../loader.js";
-import { classifySessionSource, explicitSessionId, FALLBACK_SESSION, malformedEventReason, readSessionStartEvent, resolveEventCwd, } from "./shared-options.js";
-const LEDGER_SOURCE = "harness-session-start-toolchain-parity";
-const SNAPSHOT_SCHEMA_VERSION = 1;
-// Individual spawn ceilings, not the expected duration: `node --version`
-// and `npm ls -g --depth=0 --json` run IN PARALLEL (Promise.all in
-// collectLocalSnapshot below), so the wall-time contribution of the two
-// spawns together is max(nodeTimeoutMs, npmTimeoutMs), not their sum.
-// Combined with two near-instant fs reads (OW-Kit version, MCP registry)
-// and a SEQUENTIAL ledger write afterwards, the worst-case wall-time this
-// hook needs against its configured `budget_ms` (and how much headroom
-// that leaves) is analyzed once, at the hook's own `budget_ms`
-// declaration in src/cli/init/templates.ts — search "toolchain-parity"
-// there. That comment is the single place the number lives; this one
-// deliberately does not restate it (task c1b5ade5 R2, closing a drift
-// between the two comments a prior round introduced).
-const DEFAULT_NODE_TIMEOUT_MS = 2_000;
-const DEFAULT_NPM_GLOBALS_TIMEOUT_MS = 4_000;
-/**
- * Profile names land in a filename; strip anything not filename-safe.
- * Exported (task 13919613) so `harness doctor`'s toolchain-parity section
- * can resolve the SAME own-profile filename this producer would, without
- * re-implementing the sanitization rule. Pure export, no behaviour change
- * to any call site in this module.
- */
-export function sanitizeProfileName(value) {
-    const cleaned = value.replace(/[^a-zA-Z0-9._-]/g, "-");
-    return cleaned.length > 0 ? cleaned : "profile";
-}
-function isRecordOfStrings(x) {
-    return (typeof x === "object" &&
-        x !== null &&
-        !Array.isArray(x) &&
-        Object.values(x).every((v) => typeof v === "string"));
-}
-/**
- * Parse a stored snapshot JSON. Rejects (`ok:false`) only on the shapes
- * that make comparison meaningless — not valid JSON, not an object,
- * missing/invalid `profile` or `timestamp`. Every other field degrades
- * leniently (missing/malformed -> empty/absent) rather than rejecting the
- * whole file, since a peer snapshot written by a future schema version
- * should still compare on the fields this version understands.
- */
-export function parseSnapshotJson(raw) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (err) {
-        return { ok: false, reason: `not valid JSON: ${err.message}` };
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return { ok: false, reason: "not a JSON object" };
-    }
-    const p = parsed;
-    if (typeof p["profile"] !== "string" || p["profile"].length === 0) {
-        return { ok: false, reason: "missing or invalid `profile` field" };
-    }
-    if (typeof p["timestamp"] !== "string" || Number.isNaN(Date.parse(p["timestamp"]))) {
-        return { ok: false, reason: "missing or invalid `timestamp` field" };
-    }
-    const snapshot = {
-        schemaVersion: SNAPSHOT_SCHEMA_VERSION,
-        profile: p["profile"],
-        timestamp: p["timestamp"],
-        npmGlobals: isRecordOfStrings(p["npmGlobals"]) ? p["npmGlobals"] : {},
-        mcpServers: Array.isArray(p["mcpServers"]) && p["mcpServers"].every((v) => typeof v === "string")
-            ? p["mcpServers"]
-            : [],
-    };
-    if (typeof p["node"] === "string")
-        snapshot.node = p["node"];
-    if (typeof p["nodeError"] === "string")
-        snapshot.nodeError = p["nodeError"];
-    if (typeof p["npmGlobalsError"] === "string")
-        snapshot.npmGlobalsError = p["npmGlobalsError"];
-    if (typeof p["owKitVersion"] === "string")
-        snapshot.owKitVersion = p["owKitVersion"];
-    if (typeof p["owKitError"] === "string")
-        snapshot.owKitError = p["owKitError"];
-    if (typeof p["mcpServersError"] === "string")
-        snapshot.mcpServersError = p["mcpServersError"];
-    return { ok: true, snapshot };
-}
-/**
- * Hermetic guard (mirrors `realNpmExec` in src/cli/doctor/npm-bin-path.ts):
- * asserts BEFORE touching `child_process` that we are not running under
- * vitest without a test having injected `runNodeVersion`. This function has
- * no try/catch around the assertion, and its only caller,
- * `collectLocalSnapshot`, calls it (via the `runNodeVersion` param, defaulted
- * to this function in `runSessionStartToolchainParity`) with no surrounding
- * try/catch either — see src/runtime/hermetic-spawn-guard.ts for why that
- * matters (a thrown `HermeticSpawnViolationError` must propagate, not be
- * folded into an ordinary "collection failed" outcome).
- *
- * PATH-resolved deliberately: `execFile("node", ...)` does a PATH lookup for
- * the literal string "node", NOT `process.execPath` — the entire point of
- * this collector is capturing the PATH state of the *shell* the session
- * runs in (the PATH-shim incident this task follows up on was exactly a
- * PATH pointing at the wrong node), which `process.version` (the node
- * running THIS harness process) would silently paper over.
- *
- * Exported (task 13919613) so `harness doctor`'s toolchain-parity section
- * can default its own `runNodeVersion` injection knob to the SAME real
- * collector this producer uses — the whole point of the reuse is that
- * doctor never re-implements this spawn/parse logic. No behaviour change:
- * this is the exact function every existing call site already used.
- */
-export function realNodeVersionSpawn(timeoutMs) {
-    assertNoRealSpawnInTests("node --version", "Inject a fake `runNodeVersion` (SessionStartToolchainParityOptions.runNodeVersion) instead of exercising the real spawn path.");
-    return new Promise((resolve) => {
-        execFile("node", ["--version"], { timeout: timeoutMs, encoding: "utf8" }, (err, stdout) => {
-            const text = (stdout ?? "").trim();
-            if (text.length > 0) {
-                resolve({ ok: true, version: text });
-                return;
-            }
-            if (err) {
-                const e = err;
-                if (e.code === "ENOENT") {
-                    resolve({ ok: false, reason: "`node` not on PATH" });
-                    return;
-                }
-                if (e.killed) {
-                    resolve({ ok: false, reason: `\`node --version\` timed out after ${timeoutMs}ms` });
-                    return;
-                }
-                resolve({ ok: false, reason: `\`node --version\` failed: ${e.message}` });
-                return;
-            }
-            resolve({ ok: false, reason: "`node --version` produced no output" });
-        });
-    });
-}
-/**
- * Hermetic guard, same shape/rationale as {@link realNodeVersionSpawn} —
- * see that function's doc. Tolerant of a non-zero exit the same way
- * `spawnPreflight` (session-start/index.ts) is tolerant of `preflight run`'s
- * exit code: `npm ls -g` can exit non-zero on an unrelated extraneous/
- * invalid global entry while still emitting a perfectly parseable
- * `dependencies` JSON block, so a parseable stdout wins over the exit code.
- *
- * Exported (task 13919613) for the same reuse reason as
- * {@link realNodeVersionSpawn} — `harness doctor`'s toolchain-parity
- * section defaults to this real collector rather than duplicating it.
- */
-export function realNpmGlobalsSpawn(timeoutMs) {
-    assertNoRealSpawnInTests("npm ls -g --depth=0 --json", "Inject a fake `runNpmGlobals` (SessionStartToolchainParityOptions.runNpmGlobals) instead of exercising the real spawn path.");
-    return new Promise((resolve) => {
-        execFile("npm", ["ls", "-g", "--depth=0", "--json"], { timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, encoding: "utf8" }, (err, stdout) => {
-            const text = (stdout ?? "").trim();
-            if (text.length > 0) {
-                try {
-                    const parsed = JSON.parse(text);
-                    const packages = {};
-                    for (const [name, entry] of Object.entries(parsed.dependencies ?? {})) {
-                        if (typeof entry?.version === "string")
-                            packages[name] = entry.version;
-                    }
-                    resolve({ ok: true, packages });
-                    return;
-                }
-                catch {
-                    /* fall through to the error path */
-                }
-            }
-            if (err) {
-                const e = err;
-                if (e.code === "ENOENT") {
-                    resolve({ ok: false, reason: "`npm` not on PATH" });
-                    return;
-                }
-                if (e.killed) {
-                    resolve({
-                        ok: false,
-                        reason: `\`npm ls -g --depth=0 --json\` timed out after ${timeoutMs}ms`,
-                    });
-                    return;
-                }
-                resolve({ ok: false, reason: `\`npm ls -g\` failed: ${e.message}` });
-                return;
-            }
-            resolve({ ok: false, reason: "`npm ls -g --depth=0 --json` produced no parseable JSON" });
-        });
-    });
-}
-/**
- * Read `<workspaceRoot>/.ai/workflow/manifest.json`'s `version` field
- * (the orchestrator-workflow kit's own version marker). A missing file is
- * the expected common case (most repos are not OW-kit-managed) and is
- * NOT an error — it degrades silently to `{}`. Malformed JSON or a
- * non-string `version` field on a manifest that DOES exist is noteworthy
- * (something is there but broken), so that degrades to `{ error }`.
- *
- * Exported (task 13919613) for the same reuse reason as
- * {@link realNodeVersionSpawn}.
- */
-export function realReadOwKitVersion(workspaceRoot) {
-    const manifestPath = path.join(workspaceRoot, ".ai", "workflow", "manifest.json");
-    let raw;
-    try {
-        raw = fs.readFileSync(manifestPath, "utf8");
-    }
-    catch (err) {
-        const e = err;
-        if (e.code === "ENOENT")
-            return {};
-        return { error: `cannot read ${manifestPath}: ${e.message}` };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (err) {
-        return { error: `${manifestPath} is not valid JSON: ${err.message}` };
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return { error: `${manifestPath} is not a JSON object` };
-    }
-    const version = parsed["version"];
-    if (typeof version !== "string" || version.length === 0) {
-        return { error: `${manifestPath} has no string \`version\` field` };
-    }
-    return { version };
-}
-/**
- * MCP server names from Claude Code's user-scope registry — a pure FILE
- * READ (never a spawn), reusing the exact primitive `harness doctor`'s
- * claude-mcp check ultimately compares against
- * (`resolveClaudeUserRegistryPath` + `readTopLevelMcpServers` in
- * src/io/claude-mcp.ts — the same functions `adopt`/`detect` use for the
- * same "read the effective registration from outside io/claude-mcp.ts"
- * purpose). Deliberately NOT `claude mcp list` (a spawn): the brief calls
- * for a file-read source for the NAMES here, and this is it.
- *
- * Exported (task 13919613) for the same reuse reason as
- * {@link realNodeVersionSpawn}.
- */
-export function realReadMcpServerNames() {
-    const registryPath = resolveClaudeUserRegistryPath();
-    const { servers, error } = readTopLevelMcpServers(registryPath);
-    if (error !== null)
-        return { names: [], error };
-    return { names: Object.keys(servers).sort() };
-}
-/**
- * Collect the local, LIVE toolchain snapshot. Never throws (every
- * collector above degrades to `{ok:false,reason}` / `{error}` instead of
- * rejecting/throwing) — a collection failure is reported both inline on
- * the returned snapshot (the matching `*Error` field) AND as a `notes`
- * line for the caller to log, but never stops the other collectors from
- * running. node/npm run in PARALLEL (see the timeout constants' comment
- * above for why).
- *
- * Exported (task 13919613): `harness doctor`'s toolchain-parity section
- * imports this directly as its Collector core — see that module's header
- * for the reuse rationale. No behaviour change to this function or any
- * existing call site.
- */
-export async function collectLocalSnapshot(opts) {
-    const notes = [];
-    const [nodeResult, npmResult] = await Promise.all([
-        opts.runNodeVersion(opts.nodeTimeoutMs),
-        opts.runNpmGlobals(opts.npmTimeoutMs),
-    ]);
-    const owKit = opts.readOwKitVersion(opts.workspaceRoot);
-    const mcp = opts.readMcpServerNames();
-    const snapshot = {
-        schemaVersion: SNAPSHOT_SCHEMA_VERSION,
-        profile: opts.profile,
-        timestamp: opts.now.toISOString(),
-        npmGlobals: {},
-        mcpServers: [],
-    };
-    if (nodeResult.ok) {
-        snapshot.node = nodeResult.version;
-    }
-    else {
-        snapshot.nodeError = nodeResult.reason;
-        notes.push(`node --version: ${nodeResult.reason}`);
-    }
-    if (npmResult.ok) {
-        snapshot.npmGlobals = npmResult.packages;
-    }
-    else {
-        snapshot.npmGlobalsError = npmResult.reason;
-        notes.push(`npm ls -g: ${npmResult.reason}`);
-    }
-    if (owKit.version !== undefined)
-        snapshot.owKitVersion = owKit.version;
-    if (owKit.error !== undefined) {
-        snapshot.owKitError = owKit.error;
-        notes.push(`OW-Kit version: ${owKit.error}`);
-    }
-    if (mcp.error !== undefined) {
-        snapshot.mcpServersError = mcp.error;
-        notes.push(`MCP server names: ${mcp.error}`);
-    }
-    else {
-        snapshot.mcpServers = mcp.names;
-    }
-    return { snapshot, notes };
-}
-// ---------------------------------------------------------------------
-// Snapshot write (own profile only) + peer comparison
-// ---------------------------------------------------------------------
-/**
- * Write ONLY `<machineStateDir>/<ownFileName>` (mkdir -p first). Never
- * touches any other file in the directory — the caller passes exactly
- * `sanitizeProfileName(profile) + ".json"`, so there is no path this
- * function could take that reaches a peer's file.
- */
-function writeOwnSnapshot(machineStateDir, ownFileName, snapshot) {
-    const filePath = path.join(machineStateDir, ownFileName);
-    try {
-        fs.writeFileSync(filePath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
-        return { ok: true, path: filePath };
-    }
-    catch (err) {
-        return { ok: false, reason: err.message };
-    }
-}
-/** `"just now"` / `"<n>m"` / `"<n>h"` / `"<n>d"` — coarse, human-scannable. */
-export function formatSnapshotAge(ageMs) {
-    if (ageMs < 60_000)
-        return "just now";
-    const minutes = Math.floor(ageMs / 60_000);
-    if (minutes < 60)
-        return `${minutes}m`;
-    const hours = Math.floor(minutes / 60);
-    if (hours < 48)
-        return `${hours}h`;
-    return `${Math.floor(hours / 24)}d`;
-}
-/**
- * Compare the local LIVE snapshot against one peer's stored snapshot.
- * Node / OW-Kit drift only fires when BOTH sides collected that field
- * successfully (an unavailable field reads as "unknown", not "match" or
- * "drift"). The npm-globals and MCP-name comparisons additionally gate on
- * the WHOLE field having collected without error on both sides — an
- * `npmGlobalsError`/`mcpServersError` on either side means that side's map
- * is "unknown", not "empty", and treating it as empty would fabricate a
- * wall of "missing on N packages" drift instead of the real gap (which the
- * caller's own note()s already surface separately, from collectLocalSnapshot's
- * `notes` and the peer-unreadable path).
- */
-export function compareToPeer(local, peer, now) {
-    const drift = [];
-    const peerProfile = peer.profile;
-    if (local.node !== undefined && peer.node !== undefined && local.node !== peer.node) {
-        drift.push({
-            kind: "node",
-            message: `node version: local ${local.node} vs peer ${peerProfile} ${peer.node}`,
-        });
-    }
-    if (local.owKitVersion !== undefined &&
-        peer.owKitVersion !== undefined &&
-        local.owKitVersion !== peer.owKitVersion) {
-        drift.push({
-            kind: "ow_kit",
-            message: `orchestrator-workflow kit version: local ${local.owKitVersion} vs peer ${peerProfile} ${peer.owKitVersion}`,
-        });
-    }
-    if (local.npmGlobalsError === undefined && peer.npmGlobalsError === undefined) {
-        const names = [...new Set([...Object.keys(local.npmGlobals), ...Object.keys(peer.npmGlobals)])].sort();
-        for (const name of names) {
-            const lv = local.npmGlobals[name];
-            const pv = peer.npmGlobals[name];
-            if (lv !== undefined && pv !== undefined) {
-                if (lv !== pv) {
-                    drift.push({
-                        kind: "npm_package_version",
-                        message: `npm global \`${name}\`: local ${lv} vs peer ${peerProfile} ${pv}`,
-                    });
-                }
-            }
-            else if (lv !== undefined) {
-                drift.push({
-                    kind: "npm_package_missing_peer",
-                    message: `npm global \`${name}\`: local ${lv}, missing on peer ${peerProfile}`,
-                });
-            }
-            else if (pv !== undefined) {
-                drift.push({
-                    kind: "npm_package_missing_local",
-                    message: `npm global \`${name}\`: missing locally, peer ${peerProfile} has ${pv}`,
-                });
-            }
-        }
-    }
-    if (local.mcpServersError === undefined && peer.mcpServersError === undefined) {
-        const localSet = new Set(local.mcpServers);
-        const peerSet = new Set(peer.mcpServers);
-        const names = [...new Set([...localSet, ...peerSet])].sort();
-        for (const name of names) {
-            if (localSet.has(name) && !peerSet.has(name)) {
-                drift.push({
-                    kind: "mcp_missing_peer",
-                    message: `mcp server \`${name}\`: registered locally, missing on peer ${peerProfile}`,
-                });
-            }
-            else if (!localSet.has(name) && peerSet.has(name)) {
-                drift.push({
-                    kind: "mcp_missing_local",
-                    message: `mcp server \`${name}\`: missing locally, registered on peer ${peerProfile}`,
-                });
-            }
-        }
-    }
-    const peerTimeMs = Date.parse(peer.timestamp);
-    const ageMs = Number.isFinite(peerTimeMs) ? Math.max(0, now.getTime() - peerTimeMs) : 0;
-    return { peerProfile, ageMs, drift };
-}
-/**
- * Exported (task 13919613) so `harness doctor`'s toolchain-parity section
- * resolves the SAME default machine-state directory this producer writes
- * to when `toolchain_parity.machine_state_dir` is omitted from the
- * manifest — reusing the constant instead of re-deriving it.
- */
-export function defaultMachineStateDir() {
-    return path.join(os.homedir(), ".harness", "machine-state");
-}
-export async function runSessionStartToolchainParity(opts = {}) {
-    const stdin = opts.stdin ?? process.stdin;
-    const stderr = opts.stderr ?? process.stderr;
-    const now = opts.now ?? new Date();
-    const nodeTimeoutMs = opts.nodeTimeoutMs ?? DEFAULT_NODE_TIMEOUT_MS;
-    const npmTimeoutMs = opts.npmTimeoutMs ?? DEFAULT_NPM_GLOBALS_TIMEOUT_MS;
-    const note = (msg) => {
-        // CR/LF strip, ONCE, at this choke point (task c1b5ade5 R2b, closing
-        // what R2's per-site sanitizeProfileName wraps left open): every
-        // note() call writes exactly one stderr line prefixed with
-        // "harness session-start toolchain-parity: ". Untrusted, cross-machine-
-        // synced content reaches a note() argument through roughly ten call
-        // sites below — a peer's `profile` field, a peer filename, and an
-        // npm/mcp/node/owKitVersion value embedded in a compareToPeer drift
-        // message — and R2 sanitized only 2 of them (the collision and stale
-        // notes), leaving the rest (the "ok against"/"drift:N against" lines,
-        // every individual drift message, and two of the three peer-file-read
-        // notes) able to have a crafted `\n` forge a standalone fake parity
-        // line. Stripping CR/LF here closes the whole class by construction,
-        // regardless of which site the untrusted string flows through or
-        // whether a future site remembers to sanitize its own argument.
-        stderr.write(`harness session-start toolchain-parity: ${msg.replace(/[\r\n]/g, " ")}\n`);
-    };
-    const done = (wrote, profile, peersCompared, driftCount, sessionId, sessionSource, reason, unparseablePeerCount = 0) => ({
-        exitCode: 0,
-        wrote,
-        profile,
-        peersCompared,
-        driftCount,
-        unparseablePeerCount,
-        sessionId,
-        sessionSource,
-        ...(reason !== undefined && { reason }),
-    });
-    let event;
-    try {
-        event = await readSessionStartEvent(stdin, {
-            onTimeout: note,
-            ...(opts.stdinIdleTimeoutMs !== undefined && { idleTimeoutMs: opts.stdinIdleTimeoutMs }),
-        });
-    }
-    catch (err) {
-        const reason = malformedEventReason(err);
-        note(reason);
-        return done(false, "", 0, 0, FALLBACK_SESSION, "default", reason);
-    }
-    const cwd = resolveEventCwd(opts.cwd, event);
-    // Session id resolution: same precedence chain as the two siblings, so
-    // all three producers stay symmetric.
-    const explicit = explicitSessionId(opts.session, event);
-    const resolveSession = opts.resolveSession ?? resolveReadSessionId;
-    // Defensive (task c1b5ade5): a session resolver that throws (real or
-    // injected) must degrade to the same FALLBACK_SESSION every OTHER "no
-    // session known" path already uses, not crash a producer whose whole
-    // contract is "never break the session loop". Unlike collectLocalSnapshot
-    // below, this call is NOT part of the hermetic-spawn-guard contract, so
-    // wrapping it here does not swallow a HermeticSpawnViolationError.
-    let sessionId;
-    // Task c1b5ade5 R2 (finding 3): a throw here always degrades sessionId to
-    // FALLBACK_SESSION below, but sessionSource's ternary was computed purely
-    // from `opts.session`/`event.session_id`/`sessionId` — so a stdin event
-    // that DID carry a `session_id` still reported sessionSource "stdin" even
-    // though the id actually recorded was "default" (the resolver never ran
-    // to completion). That both misrepresents the ledger fact's provenance
-    // and suppresses the AC5 "resolved to default" warning below, which only
-    // fires when sessionSource === "default". `resolverThrew` short-circuits
-    // sessionSource to "default" whenever the catch below fired, regardless
-    // of what `explicit`/`event.session_id` looked like.
-    let resolverThrew = false;
-    try {
-        sessionId = resolveSession(explicit, {});
-    }
-    catch (err) {
-        note(`session id resolution failed: ${err.message}; falling back to session "${FALLBACK_SESSION}"`);
-        sessionId = FALLBACK_SESSION;
-        resolverThrew = true;
-    }
-    const sessionSource = classifySessionSource(opts.session, event, sessionId, resolverThrew);
-    let manifest;
-    if (opts.manifest) {
-        manifest = opts.manifest;
-    }
-    else {
-        try {
-            manifest = loadManifest(opts).manifest;
-        }
-        catch (err) {
-            const reason = `manifest load failed: ${err.message}`;
-            note(reason);
-            return done(false, "", 0, 0, sessionId, sessionSource, reason);
-        }
-    }
-    const config = manifest.toolchain_parity;
-    if (!config.enabled) {
-        const reason = "not configured (add `toolchain_parity: { enabled: true }` to harness.yaml); skipping";
-        note(reason);
-        return done(false, "", 0, 0, sessionId, sessionSource, reason);
-    }
-    const machineStateDir = config.machine_state_dir ?? defaultMachineStateDir();
-    const profile = config.profile ?? sanitizeProfileName(os.hostname());
-    const workspaceRoot = config.workspace_root ?? cwd;
-    const sanitizedProfile = sanitizeProfileName(profile);
-    const ownFileName = `${sanitizedProfile}.json`;
-    // Advisory staleness threshold (AC3, task c1b5ade5): undefined disables
-    // the check entirely, matching the schema's default-off comment.
-    const staleAfterMs = config.stale_after_days !== undefined ? config.stale_after_days * 24 * 60 * 60 * 1000 : undefined;
-    try {
-        fs.mkdirSync(machineStateDir, { recursive: true });
-    }
-    catch (err) {
-        const reason = `cannot create/access machine-state dir ${machineStateDir}: ${err.message}`;
-        note(reason);
-        return done(false, profile, 0, 0, sessionId, sessionSource, reason);
-    }
-    // Lossy-sanitization advisory (task c1b5ade5): a `profile` configured
-    // with characters that are not filename-safe silently loses information
-    // when sanitizeProfileName strips/replaces them. That is invisible to an
-    // operator unless flagged — worse, two DIFFERENT configured profiles can
-    // sanitize to the SAME filename (e.g. "mac/mini" and "mac-mini" both land
-    // on "mac-mini.json"), in which case this run's write is about to
-    // silently overwrite what looked like a peer's snapshot. Both cases are
-    // advisory-only: this producer still writes its own snapshot and
-    // continues normally either way.
-    if (sanitizedProfile !== profile) {
-        note(`configured profile "${profile}" is not filename-safe; using sanitized "${sanitizedProfile}" for the snapshot file (${ownFileName})`);
-    }
-    // Collision check (task c1b5ade5 R2, finding 2): this must run on EVERY
-    // invocation, not only when THIS machine's own profile happens to be
-    // lossy — the collision is equally caused by a DIFFERENT (peer)
-    // machine's lossy profile landing on the SAME sanitized filename as
-    // this machine's own, already filename-safe, profile. Gating this read
-    // on `sanitizedProfile !== profile` meant only the lossy side of such a
-    // pair ever warned; the filename-safe side silently overwrote the lossy
-    // peer's snapshot with no signal at all (and that peer would then never
-    // show up in `peersCompared`). Only the "not filename-safe" note above
-    // stays scoped to the lossy case — it is about THIS profile, not about
-    // a collision.
-    try {
-        const existingRaw = fs.readFileSync(path.join(machineStateDir, ownFileName), "utf8");
-        const existingParsed = parseSnapshotJson(existingRaw);
-        if (existingParsed.ok && existingParsed.snapshot.profile !== profile) {
-            // The existing snapshot's `profile` field is untrusted, cross-machine
-            // synced content, shown RAW here (task c1b5ade5 R2b, reverting R2's
-            // sanitizeProfileName wrap at this site): note() now strips CR/LF at
-            // the choke point above, so a per-site sanitize is redundant AND
-            // would mangle a legitimate non-ASCII profile name into a label that
-            // no longer matches what actually collided. sanitizeProfileName
-            // stays reserved for the FILENAME path (ownFileName, writeOwnSnapshot
-            // below) — never for this stderr-display path.
-            note(`WARNING: sanitized filename "${ownFileName}" collides with an existing snapshot for a DIFFERENT profile ("${existingParsed.snapshot.profile}"); this run's write is about to overwrite it — set a distinct \`toolchain_parity.profile\` on one of the machines`);
-        }
-    }
-    catch (err) {
-        // No existing file for this sanitized name yet (first run for this
-        // profile/filename) is the expected common case — ENOENT stays a
-        // silent skip; writeOwnSnapshot below reports its own write failures
-        // separately. Anything else (EACCES, EISDIR, ...) means the collision
-        // check silently did NOT run, which is a different, noteworthy outcome
-        // from "no collision found" (task c1b5ade5 R2b, narrowing the
-        // previously-bare catch): re-noted as one line rather than swallowed.
-        const e = err;
-        if (e.code !== "ENOENT") {
-            note(`could not check for a profile-name collision on ${ownFileName}: ${e.message}`);
-        }
-    }
-    const runNodeVersion = opts.runNodeVersion ?? realNodeVersionSpawn;
-    const runNpmGlobals = opts.runNpmGlobals ?? realNpmGlobalsSpawn;
-    const readOwKitVersion = opts.readOwKitVersion ?? realReadOwKitVersion;
-    const readMcpServerNames = opts.readMcpServerNames ?? realReadMcpServerNames;
-    const { snapshot: localSnapshot, notes } = await collectLocalSnapshot({
-        profile,
-        now,
-        workspaceRoot,
-        nodeTimeoutMs,
-        npmTimeoutMs,
-        runNodeVersion,
-        runNpmGlobals,
-        readOwKitVersion,
-        readMcpServerNames,
-    });
-    for (const n of notes)
-        note(n);
-    const written = writeOwnSnapshot(machineStateDir, ownFileName, localSnapshot);
-    if (!written.ok) {
-        note(`could not write own snapshot: ${written.reason}`);
-    }
-    let entries;
-    try {
-        entries = fs.readdirSync(machineStateDir);
-    }
-    catch (err) {
-        const reason = `cannot list machine-state dir ${machineStateDir}: ${err.message}`;
-        note(reason);
-        return done(false, profile, 0, 0, sessionId, sessionSource, reason);
-    }
-    const peerFiles = entries.filter((name) => name.endsWith(".json") && name !== ownFileName).sort();
-    if (peerFiles.length === 0) {
-        const reason = `no peer snapshots found in ${machineStateDir}; nothing to compare (normal for the first machine, or before any peer has run this companion)`;
-        note(reason);
-        return done(false, profile, 0, 0, sessionId, sessionSource, reason);
-    }
-    let peersCompared = 0;
-    let driftTotal = 0;
-    // Peer files that were present but failed to parse as valid JSON —
-    // AC2 (task 690fba7c): these must not vanish silently from `drift:N`, so
-    // their (file-derived) labels are surfaced both as a distinct stderr tag
-    // and as a `:unparseable-peer:<n>` suffix on the ledger fact below.
-    const unparseablePeers = [];
-    for (const fileName of peerFiles) {
-        const filePath = path.join(machineStateDir, fileName);
-        let raw;
-        try {
-            raw = fs.readFileSync(filePath, "utf8");
-        }
-        catch (err) {
-            note(`peer snapshot ${fileName} unreadable: ${err.message}`);
-            continue;
-        }
-        const parsed = parseSnapshotJson(raw);
-        if (!parsed.ok) {
-            // The profile field itself failed to parse, so the filename (minus
-            // its `.json` suffix) is the best available peer identifier. Files
-            // this producer did NOT write are untrusted input (the machine-state
-            // dir is populated cross-machine by sync), but note() strips CR/LF
-            // at the choke point above (task c1b5ade5 R2b, reverting R2's
-            // sanitizeProfileName wrap at this site), so the label is shown RAW
-            // here — a crafted filename still cannot forge a standalone parity
-            // line, and sanitizeProfileName stays reserved for the FILENAME
-            // path, not this stderr-display one. The `|| fileName` keeps a
-            // degenerate name like a literal `.json` from producing an empty
-            // label.
-            const peerLabel = fileName.replace(/\.json$/, "") || fileName;
-            note(`peer snapshot ${fileName} is corrupt: ${parsed.reason}`);
-            note(`parity:unparseable-peer:${peerLabel}`);
-            unparseablePeers.push(peerLabel);
-            continue;
-        }
-        const comparison = compareToPeer(localSnapshot, parsed.snapshot, now);
-        peersCompared += 1;
-        driftTotal += comparison.drift.length;
-        const age = formatSnapshotAge(comparison.ageMs);
-        if (comparison.drift.length === 0) {
-            note(`ok against ${comparison.peerProfile} (snapshot age ${age})`);
-        }
-        else {
-            note(`drift:${comparison.drift.length} against ${comparison.peerProfile} (snapshot age ${age})`);
-            for (const item of comparison.drift)
-                note(`drift — ${item.message}`);
-        }
-        // AC3 (task c1b5ade5): a stale peer is a trustworthiness CAVEAT on the
-        // comparison above, not a drift finding — it never touches driftTotal.
-        // Only fires when `stale_after_days` is explicitly configured.
-        if (staleAfterMs !== undefined && comparison.ageMs > staleAfterMs) {
-            // comparison.peerProfile is untrusted, cross-machine synced content,
-            // shown RAW here for the same reason as the collision-warning note
-            // above (task c1b5ade5 R2b, reverting R2's sanitizeProfileName wrap
-            // at this site): note() strips CR/LF at the choke point, and this
-            // also keeps the label identical to the "ok against"/"drift:N
-            // against" line for the SAME peer just above, instead of showing two
-            // different sanitized-vs-raw spellings of one peer's name in the
-            // same run.
-            note(`peer ${comparison.peerProfile} snapshot is stale (age ${age}, exceeds the configured ${config.stale_after_days}d threshold); its comparison may not reflect that machine's CURRENT toolchain`);
-        }
-    }
-    if (peersCompared === 0) {
-        const reason = `no comparable peer snapshots (all ${peerFiles.length} peer file(s) in ${machineStateDir} were unreadable/corrupt)`;
-        note(reason);
-        return done(false, profile, 0, 0, sessionId, sessionSource, reason, unparseablePeers.length);
-    }
-    // AC2 (task 690fba7c): a non-zero `unparseablePeers` count means the
-    // comparison below is PARTIAL, so it is appended to the ledger fact
-    // itself — the artifact an operator is most likely to read after the
-    // fact via `harness audit` — not just to the stderr notes above. Absent
-    // any unparseable peer, `content` is byte-identical to the pre-existing
-    // format (AC3: no behaviour change for the all-valid-peers case).
-    const unparseableSuffix = unparseablePeers.length > 0 ? `:unparseable-peer:${unparseablePeers.length}` : "";
-    const content = (driftTotal === 0 ? "toolchain-parity:ok" : `toolchain-parity:drift:${driftTotal}`) + unparseableSuffix;
-    let writeLedger = opts.writeLedger;
-    if (!writeLedger) {
-        // No try/catch here (task c1b5ade5 R2, finding 4 — orchestrator
-        // decision): resolveManifestLedgerWriter is a pure function over an
-        // already-validated `manifest` with no throw path (findGroundingMcp is
-        // a plain array `.find`, mcpCommandList a plain string split) and no
-        // I/O seam to fail — unlike `resolveSession` above and `writeLedger`
-        // below, which DO wrap real I/O/spawn boundaries and stay caught. A
-        // try/catch here had no exercisable throw path and was dead,
-        // untested code (round-1 review finding); removed rather than built
-        // out into a fake seam.
-        const resolved = resolveManifestLedgerWriter(manifest, {
-            ...(opts.ledgerTimeoutMs !== undefined ? { ledgerTimeoutMs: opts.ledgerTimeoutMs } : {}),
-        });
-        if (!resolved.ok) {
-            const reason = `${resolved.reason}; cannot record ${content}`;
-            note(reason);
-            return done(false, profile, peersCompared, driftTotal, sessionId, sessionSource, reason, unparseablePeers.length);
-        }
-        writeLedger = resolved.write;
-    }
-    // Defensive (task c1b5ade5): an injected or real writeLedger that REJECTS
-    // instead of resolving to `{ ok: false, reason }` must degrade the same
-    // way the `!result.ok` branch below already does, not propagate as an
-    // unhandled rejection out of a SessionStart hook.
-    let result;
-    try {
-        result = await writeLedger({ sessionId, content, source: LEDGER_SOURCE });
-    }
-    catch (err) {
-        const reason = `ledger write threw: ${err.message}`;
-        note(reason);
-        return done(false, profile, peersCompared, driftTotal, sessionId, sessionSource, reason, unparseablePeers.length);
-    }
-    if (!result.ok) {
-        // `?? "unknown error"` is unreachable through any type-checked caller
-        // (`AddLedgerFactResult`'s `!ok` arm types `reason` as a non-optional
-        // string) — but unlike the try/catch removed around
-        // resolveManifestLedgerWriter above (a private, non-injectable pure
-        // function only ever called from this same typed module, so genuinely
-        // dead), `writeLedger` IS an injectable public seam
-        // (SessionStartToolchainParityOptions.writeLedger): a JS-level or
-        // otherwise untyped caller can hand back `{ ok: false }` with no
-        // `reason` at runtime, so this fallback stays (task c1b5ade5 R2b).
-        const reason = `ledger write failed: ${result.reason ?? "unknown error"}`;
-        note(reason);
-        return done(false, profile, peersCompared, driftTotal, sessionId, sessionSource, reason, unparseablePeers.length);
-    }
-    note(`recorded ${content} for session ${sessionId}`);
-    if (sessionSource === "default") {
-        note("WARNING: session resolved to the literal \"default\". This tag is audit-only (no gate " +
-            "consumes toolchain-parity: yet), but pipe SessionStart event JSON on stdin, export " +
-            "$CLAUDE_SESSION_ID, or pass --session <id> for manual / scripted use to keep the audit trail useful.");
-    }
-    return done(true, profile, peersCompared, driftTotal, sessionId, sessionSource, undefined, unparseablePeers.length);
-}
-//# sourceMappingURL=toolchain-parity.js.map