adversarial-review-gate 2.0.0

package/src/cli/check.js

@@ -0,0 +1,74 @@
+// `adversarial-review check` — run the gate against the current workspace.
+//
+// Loads the effective config, captures a fresh baseline, runs evaluateGate, and
+// reports the decision. `--json` emits the decision as machine-readable JSON.
+// Exit code is 1 on block, 0 on allow. The whole evaluation is wrapped in the
+// fail-closed catch (HARDENING #2): an unexpected throw with edit evidence
+// blocks in enforced/strict rather than silently allowing.
+
+import { evaluateGate } from "../core/gate.js";
+import { captureBaseline } from "../core/diff.js";
+import { loadEffectiveConfig, resolveStateDir } from "../core/load-config.js";
+import { buildHostRouting } from "./host-map.js";
+import { failClosedDecision } from "./fail-closed.js";
+import { sessionStateKey } from "./hook.js";
+
+/**
+ * @param {string[]} argv
+ * @param {object} io  - { stdin, stdout, stderr, env, cwd }
+ */
+export async function checkCommand(argv, io) {
+  const json = argv.includes("--json");
+  const host = parseHost(argv) || "cli";
+  const cwd = io.cwd;
+  const env = io.env || process.env;
+
+  const config = await loadEffectiveConfig(cwd, io);
+  const stateDir = resolveStateDir(env);
+  const { hostDescriptor, reviewerRunner } = buildHostRouting(host, config, env);
+
+  let decision;
+  try {
+    const baseline = await captureBaseline(cwd);
+    decision = await evaluateGate({
+      config,
+      cwd,
+      baseline,
+      transcript: "",
+      transcriptPath: "",
+      host: hostDescriptor,
+      reviewerRunner,
+      // Compose the synthetic session id with the canonical workspace root so the
+      // gate's block-counter/cache are keyed per-workspace, consistent with the
+      // hook's composite keying (distinct workspaces never share state).
+      sessionId: sessionStateKey(`check-${host}`, cwd),
+      stateDir,
+    });
+  } catch (err) {
+    // HARDENING #2: fail closed. `check` has no transcript, so edit evidence is
+    // whatever the live diff shows; failClosedDecision recomputes that.
+    decision = await failClosedDecision({ config, cwd, err, io });
+  }
+
+  if (json) {
+    io.stdout.write(`${JSON.stringify(decision)}\n`);
+  } else {
+    if (decision.action === "block") {
+      io.stderr.write(`BLOCK: ${decision.reason || "review required"}\n`);
+    } else if (decision.systemMessage) {
+      io.stdout.write(`${decision.systemMessage}\n`);
+    } else {
+      io.stdout.write(`allow: ${decision.reason || "ok"}\n`);
+    }
+  }
+
+  process.exitCode = decision.action === "block" ? 1 : 0;
+  return decision;
+}
+
+// Parse `--host <name>` if present.
+function parseHost(argv) {
+  const i = argv.indexOf("--host");
+  if (i >= 0 && argv[i + 1]) return argv[i + 1];
+  return null;
+}

package/src/cli/doctor.js

@@ -0,0 +1,261 @@
+// `adversarial-review doctor` — diagnostics for config, hosts, and reviewers.
+//
+// Reads (never writes) all config sources, checks reviewer availability, and
+// reports a human-readable (or --json) summary with explicit WARNINGS for
+// wrapper/advisory hosts.
+//
+// Exit codes:
+//   0 - all checks passed (or completed with warnings)
+//   1 - a fatal error was encountered (corrupt package.json, etc.)
+
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+import { HOSTS } from "../hosts/index.js";
+import { createReviewer } from "../reviewers/index.js";
+import { loadEffectiveConfig } from "../core/load-config.js";
+
+// Paths relative to home / cwd.
+const PROJECT_CONFIG_REL = path.join(".adversarial-review", "config.json");
+const USER_CONFIG_REL = path.join(".adversarial-review", "config.json");
+const USER_POLICY_REL = path.join(".adversarial-review", "policy.json");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve home from env, falling back to os.homedir(). Honors
+ * ADVERSARIAL_REVIEW_HOME so doctor reports the SAME user-level base that
+ * loadEffectiveConfig (the gate's loader) uses. */
+function homeDir(env) {
+  if (env) {
+    const fromEnv = env.ADVERSARIAL_REVIEW_HOME || env.HOME || env.USERPROFILE;
+    if (fromEnv) return fromEnv;
+  }
+  return os.homedir();
+}
+
+/** Read package.json to get the package version. */
+async function readPackageVersion() {
+  try {
+    // Walk up from this file to find package.json.
+    const thisFile = fileURLToPath(import.meta.url);
+    const pkgPath = path.join(path.dirname(thisFile), "..", "..", "package.json");
+    const raw = await readFile(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+    return pkg.version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/** Check whether a reviewer is available; return { ok, resolvedPath, version, capabilities, reason }. */
+async function checkReviewer(reviewerId, config, env) {
+  if (reviewerId === "none") {
+    return { ok: true, note: "native self-review (no external process)" };
+  }
+  try {
+    const adapter = createReviewer(reviewerId, config);
+    return adapter.verify(env);
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main doctor command
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string[]} argv
+ * @param {object} io  - { stdin, stdout, stderr, env, cwd }
+ */
+export async function doctorCommand(argv, io) {
+  const json = argv.includes("--json");
+  const cwd = io.cwd || process.cwd();
+  const env = io.env || process.env;
+  const home = homeDir(env);
+
+  // Read package version.
+  const version = await readPackageVersion();
+
+  // Locate config files.
+  const projectConfigPath = path.join(cwd, PROJECT_CONFIG_REL);
+  const userConfigPath = path.join(home, USER_CONFIG_REL);
+  const userPolicyPath = path.join(home, USER_POLICY_REL);
+
+  const projectConfigExists = existsSync(projectConfigPath);
+  const userConfigExists = existsSync(userConfigPath);
+  const userPolicyExists = existsSync(userPolicyPath);
+
+  // Validate project config (simple validity check).
+  let projectConfigValid = false;
+  if (projectConfigExists) {
+    try {
+      const raw = await readFile(projectConfigPath, "utf8");
+      const parsed = JSON.parse(raw);
+      projectConfigValid = parsed && typeof parsed === "object" && !Array.isArray(parsed);
+    } catch {
+      projectConfigValid = false;
+    }
+  }
+
+  // Effective config — use the SAME loader the gate uses so the report matches
+  // runtime reality: DEFAULT < user config (~/.adversarial-review/config.json) <
+  // project config, then the user policy floor applied on top. (The old doctor
+  // loader ignored the user-level config.json and under-reported configured
+  // hosts.)
+  const effectiveConfig = await loadEffectiveConfig(cwd, io);
+
+  // Enumerate configured hosts.
+  const configuredHostIds = Object.keys(effectiveConfig.hosts || {});
+  const hostReports = [];
+  const warnings = [];
+
+  for (const hostId of configuredHostIds) {
+    const hostInfo = HOSTS[hostId];
+    const hostConfig = effectiveConfig.hosts[hostId] || {};
+    const reviewerId = hostConfig.reviewer || "none";
+
+    // Check reviewer.
+    const reviewerResult = await checkReviewer(reviewerId, effectiveConfig, env);
+
+    const hostReport = {
+      id: hostId,
+      enforcement: hostInfo ? hostInfo.enforcement : "unknown",
+      capabilities: hostInfo || null,
+      reviewer: reviewerId,
+      reviewerAvailable: reviewerResult.ok,
+      reviewerPath: reviewerResult.resolvedPath || null,
+      reviewerVersion: reviewerResult.version || null,
+      reviewerCapabilities: reviewerResult.capabilities || null,
+      reviewerNote: reviewerResult.note || null,
+      reviewerReason: reviewerResult.reason || null,
+    };
+    hostReports.push(hostReport);
+
+    // Warn about wrapper/advisory hosts.
+    if (hostInfo && hostInfo.enforcement === "wrapper-enforced") {
+      warnings.push(
+        `WARNING: Host "${hostId}" is wrapper-enforced. Enforcement depends on the user ` +
+          `always invoking ${hostId} through \`adversarial-review run --host ${hostId}\`. ` +
+          `Bypassing the wrapper skips the review gate entirely. ` +
+          `This is NOT equivalent to native enforcement.`
+      );
+    }
+    if (!reviewerResult.ok && reviewerId !== "none") {
+      warnings.push(
+        `WARNING: Reviewer "${reviewerId}" for host "${hostId}" is unavailable: ` +
+          `${reviewerResult.reason || "unknown"}`
+      );
+    }
+  }
+
+  // Effective enforcement level.
+  const hasNativeHost = hostReports.some((h) => h.enforcement === "native-enforced");
+  const hasWrapperOnlyHosts =
+    hostReports.length > 0 && hostReports.every((h) => h.enforcement === "wrapper-enforced");
+  const effectiveEnforcement = hasNativeHost
+    ? "native-enforced"
+    : hasWrapperOnlyHosts
+      ? "wrapper-enforced (advisory)"
+      : "none";
+
+  // Build the report object.
+  const report = {
+    version,
+    projectConfigPath,
+    projectConfigExists,
+    projectConfigValid: projectConfigExists ? projectConfigValid : null,
+    userConfigPath,
+    userConfigExists,
+    userPolicyPath,
+    userPolicyExists,
+    privacyMode: effectiveConfig.privacy?.externalReview || "allow",
+    policyMode: effectiveConfig.policy?.mode || "enforced",
+    effectiveEnforcement,
+    allowAdvisoryHosts: effectiveConfig.policy?.allowAdvisoryHosts ?? false,
+    hosts: hostReports,
+    warnings,
+  };
+
+  if (json) {
+    io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    printHumanReport(report, io);
+  }
+
+  process.exitCode = 0;
+}
+
+// ---------------------------------------------------------------------------
+// Human-readable printer
+// ---------------------------------------------------------------------------
+
+function printHumanReport(report, io) {
+  const w = (s) => io.stdout.write(s);
+
+  w(`adversarial-review v${report.version}\n`);
+  w(`\nProject config: ${report.projectConfigPath}\n`);
+  if (!report.projectConfigExists) {
+    w(`  (not found — using defaults)\n`);
+  } else if (!report.projectConfigValid) {
+    w(`  ERROR: file exists but is not valid JSON\n`);
+  } else {
+    w(`  (valid)\n`);
+  }
+
+  w(`\nUser config (machine-wide defaults): ${report.userConfigPath}\n`);
+  if (!report.userConfigExists) {
+    w(`  (not found — no machine-wide host/reviewer defaults)\n`);
+  } else {
+    w(`  (present)\n`);
+  }
+
+  w(`\nUser policy floor: ${report.userPolicyPath}\n`);
+  if (!report.userPolicyExists) {
+    w(`  (not found — no user-level floor enforced)\n`);
+  } else {
+    w(`  (present)\n`);
+  }
+
+  w(`\nEffective policy:\n`);
+  w(`  mode:                ${report.policyMode}\n`);
+  w(`  enforcement:         ${report.effectiveEnforcement}\n`);
+  w(`  allowAdvisoryHosts:  ${report.allowAdvisoryHosts}\n`);
+  w(`  privacyMode:         ${report.privacyMode}\n`);
+
+  if (report.hosts.length === 0) {
+    w(`\nHosts: (none configured)\n`);
+  } else {
+    w(`\nHosts:\n`);
+    for (const h of report.hosts) {
+      w(`  ${h.id} (${h.enforcement})\n`);
+      w(`    reviewer: ${h.reviewer}\n`);
+      if (h.reviewer === "none") {
+        w(`    reviewer status: native self-review\n`);
+      } else if (h.reviewerAvailable) {
+        w(`    reviewer status: available\n`);
+        if (h.reviewerPath) w(`    reviewer path:   ${h.reviewerPath}\n`);
+        if (h.reviewerVersion) w(`    reviewer version: ${h.reviewerVersion}\n`);
+        if (h.reviewerCapabilities) {
+          w(`    reviewer capabilities: ${JSON.stringify(h.reviewerCapabilities)}\n`);
+        }
+      } else {
+        w(`    reviewer status: UNAVAILABLE (${h.reviewerReason || "unknown"})\n`);
+      }
+    }
+  }
+
+  if (report.warnings.length > 0) {
+    w(`\nWarnings:\n`);
+    for (const warning of report.warnings) {
+      w(`  ${warning}\n`);
+    }
+  } else {
+    w(`\nNo warnings.\n`);
+  }
+}

package/src/cli/fail-closed.js

@@ -0,0 +1,74 @@
+// Shared fail-closed decision helper (HARDENING #2).
+//
+// `evaluateGate` may throw (e.g. a writeSessionState IO error, or an injected
+// failure). When that happens the CLI entrypoints MUST NOT silently allow: if
+// there is evidence of a real edit, they FAIL CLOSED — block in enforced/strict,
+// and follow `onInternalError` in soft. The original error is surfaced on stderr.
+
+import { block, advisory, allow } from "../core/gate.js";
+import { buildReviewDiff } from "../core/diff.js";
+import { internalErrorAction } from "../core/policy.js";
+import { parseJsonl, scanKeys } from "../core/transcript.js";
+
+/**
+ * Decide what to do after evaluateGate threw.
+ *
+ * @param {object} args
+ * @param {object} args.config
+ * @param {string} args.cwd
+ * @param {object} [args.baseline]    - recorded baseline, if available.
+ * @param {string} [args.transcript]  - transcript text, if available.
+ * @param {Error}  args.err
+ * @param {object} args.io            - { stderr }
+ * @returns {Promise<object>} decision
+ */
+export async function failClosedDecision({ config, cwd, baseline, transcript, err, io }) {
+  if (io?.stderr) {
+    io.stderr.write(
+      `adversarial-review: gate evaluation failed (failing closed): ${err?.stack || err}\n`
+    );
+  }
+
+  const hasEvidence = await hasEditEvidence({ cwd, baseline, transcript });
+
+  // No evidence of a change: nothing to protect, allow.
+  if (!hasEvidence) {
+    return allow({ reason: "fail_open_no_evidence", internalError: String(err?.message || err) });
+  }
+
+  // Evidence present: follow onInternalError (allow only in soft when so set).
+  const action = internalErrorAction(config, true);
+  if (action === "allow") {
+    return advisory(
+      "Gate evaluation failed; allowed per soft onInternalError policy.",
+      { internalError: String(err?.message || err) }
+    );
+  }
+  return block(
+    "Adversarial review could not complete due to an internal error (fail-closed).",
+    { internalError: String(err?.message || err) }
+  );
+}
+
+// Best-effort edit-evidence detection: a non-empty review diff, OR edit/edited
+// paths in the transcript. Tolerant of further failures (treats them as "no
+// extra evidence" from that source).
+async function hasEditEvidence({ cwd, baseline, transcript }) {
+  if (transcript) {
+    try {
+      const { lastEditKey, editedPaths } = scanKeys(parseJsonl(transcript));
+      if (lastEditKey > 0 || editedPaths.size > 0) return true;
+    } catch {
+      // Ignore transcript-scan failures.
+    }
+  }
+  if (baseline) {
+    try {
+      const diff = await buildReviewDiff(cwd, baseline);
+      if (diff && (diff.changedFiles?.length > 0 || diff.text)) return true;
+    } catch {
+      // Diff unbuildable from this baseline: fall through.
+    }
+  }
+  return false;
+}

package/src/cli/hook.js

@@ -0,0 +1,267 @@
+// `adversarial-review hook` — run as a native host lifecycle hook.
+//
+// Currently supports the Claude Code host (--host claude-code) with two events:
+//   --event session-start : capture + persist the workspace baseline (no output).
+//   --event stop (default) : run the gate and emit Claude Stop-hook JSON.
+//
+// The Stop event reads the host payload from stdin (JSON), loads the baseline
+// recorded at SessionStart, builds the gate input, runs evaluateGate, and maps
+// the decision to the Claude Stop hook protocol:
+//   block            -> {"decision":"block","reason":"..."}
+//   advisory message -> {"systemMessage":"..."}
+//   silent allow     -> no stdout output
+//
+// HARDENING #1: state lives at a user-level path (resolveStateDir), never
+// repo-relative. HARDENING #2: gate evaluation is wrapped in a fail-closed
+// try/catch that blocks on edit evidence in enforced/strict.
+
+import { readFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { evaluateGate, block } from "../core/gate.js";
+import { captureBaseline } from "../core/diff.js";
+import { loadEffectiveConfig, resolveStateDir } from "../core/load-config.js";
+import { readSessionState, writeSessionState } from "../core/state.js";
+import { isStrict } from "../core/policy.js";
+import { parseJsonl, scanKeys, isSubagentTranscript } from "../core/transcript.js";
+import { buildHostRouting } from "./host-map.js";
+import { failClosedDecision } from "./fail-closed.js";
+
+/**
+ * @param {string[]} argv
+ * @param {object} io  - { stdin, stdout, stderr, env, cwd }
+ */
+export async function hookCommand(argv, io) {
+  const host = parseFlag(argv, "--host") || "claude-code";
+  const event = parseFlag(argv, "--event") || "stop";
+  const env = io.env || process.env;
+
+  const payload = await readStdinJson(io.stdin);
+  // The host payload carries the authoritative cwd; fall back to the process cwd.
+  const cwd = (payload && typeof payload.cwd === "string" && payload.cwd) || io.cwd;
+  const sessionId = (payload && payload.session_id) || "default";
+  const stateDir = resolveStateDir(env);
+  // Key state by session id AND canonical workspace root so distinct workspaces
+  // never share a baseline even when they share a session_id (cross-workspace
+  // baseline-collision bypass). This composite key is used both for direct
+  // readSessionState/writeSessionState here AND as the evaluateGate sessionId.
+  const stateKey = sessionStateKey(sessionId, cwd);
+
+  if (event === "session-start") {
+    return sessionStart({ cwd, stateKey, stateDir, io });
+  }
+  return stopEvent({ argv, host, env, payload, cwd, sessionId, stateKey, stateDir, io });
+}
+
+// ---------------------------------------------------------------------------
+// session-start: record the baseline. No blocking output.
+// ---------------------------------------------------------------------------
+
+async function sessionStart({ cwd, stateKey, stateDir, io }) {
+  try {
+    const baseline = await captureBaseline(cwd);
+    const prev = await readSessionState(stateDir, stateKey);
+    await writeSessionState(stateDir, stateKey, {
+      ...prev,
+      baseline,
+      // Store the CANONICAL workspace root so the Stop event can validate that
+      // the baseline belongs to the workspace it is being evaluated against.
+      workspaceRoot: canonicalWorkspaceRoot(cwd),
+      updatedAt: Date.now(),
+    });
+  } catch (err) {
+    // SessionStart is best-effort; a failure here is surfaced but never blocks.
+    // The Stop event will detect the missing baseline and fail closed there.
+    io.stderr.write(`adversarial-review: session-start baseline capture failed: ${err.message}\n`);
+  }
+  // No stdout output for SessionStart.
+  process.exitCode = 0;
+}
+
+// ---------------------------------------------------------------------------
+// stop: evaluate the gate and emit Claude Stop-hook JSON.
+// ---------------------------------------------------------------------------
+
+async function stopEvent({ host, env, payload, cwd, sessionId, stateKey, stateDir, io }) {
+  const config = await loadEffectiveConfig(cwd, io);
+  const enforced = config.policy.mode === "enforced" || isStrict(config);
+
+  const transcriptPath =
+    (payload && typeof payload.transcript_path === "string" && payload.transcript_path) || "";
+  const stopHookActive = Boolean(payload && payload.stop_hook_active);
+
+  // Subagent transcripts never trigger the gate (avoid serializing pipelines).
+  // The gate also checks this, but short-circuit here to avoid any state IO.
+  if (isSubagentTranscript(transcriptPath, sessionId)) {
+    return emit(null, io); // silent allow
+  }
+
+  // Read the transcript text (tolerant: unreadable -> "").
+  let transcript = "";
+  if (transcriptPath) {
+    transcript = await readFile(transcriptPath, "utf8").catch(() => "");
+  }
+
+  // Load the baseline recorded at SessionStart (keyed by session id AND
+  // canonical workspace root).
+  const state = await readSessionState(stateDir, stateKey);
+
+  // Defense-in-depth: even with the composite state key, never trust a baseline
+  // whose recorded workspaceRoot does not match the workspace we are evaluating.
+  // If it differs (or is somehow stale/mismatched), treat the baseline as ABSENT
+  // so we route into the missing-baseline path (block in enforced/strict; NOW
+  // baseline with a disclosed limitation in soft) rather than silently reusing a
+  // foreign repo's baseline.
+  const canonicalCwd = canonicalWorkspaceRoot(cwd);
+  const workspaceMatches =
+    !state.workspaceRoot || state.workspaceRoot === canonicalCwd;
+  let baseline = workspaceMatches ? state.baseline || null : null;
+
+  // Detect edit evidence so we can fail closed on a missing baseline.
+  const { lastEditKey, editedPaths } = scanKeys(parseJsonl(transcript));
+  const transcriptEditEvidence = lastEditKey > 0 || editedPaths.size > 0;
+
+  if (!baseline) {
+    if (transcriptEditEvidence && enforced) {
+      // HARDENING: edit evidence but NO recorded baseline in enforced/strict.
+      // We cannot trust an after-the-fact baseline to cover the change, so block
+      // and advise reinstalling the SessionStart hook.
+      const decision = block(
+        "Adversarial review could not verify this change: no SessionStart baseline was " +
+          "recorded for this session, so the full change scope is unknown. Reinstall the " +
+          "adversarial-review SessionStart hook (it records the baseline) and retry."
+      );
+      return emit(decision, io);
+    }
+    // Soft (or no edit evidence): fall back to a current-git/filesystem baseline.
+    // This is a disclosed limitation — only changes since NOW are visible.
+    baseline = await captureBaseline(cwd).catch(() => null);
+  }
+
+  const { hostDescriptor, reviewerRunner } = buildHostRouting(host, config, env);
+
+  let decision;
+  try {
+    decision = await evaluateGate({
+      config,
+      cwd,
+      baseline,
+      transcript,
+      transcriptPath,
+      host: hostDescriptor,
+      reviewerRunner,
+      // Use the composite key so the gate's block-counter/cache are also keyed
+      // per-workspace, consistent with the baseline state above.
+      sessionId: stateKey,
+      stateDir,
+      stopHookActive,
+    });
+  } catch (err) {
+    decision = await failClosedDecision({ config, cwd, baseline, transcript, err, io });
+  }
+
+  // When we fell back to a NOW baseline — either no recorded SessionStart
+  // baseline, or one rejected because it belongs to a different workspace — and
+  // there is edit evidence, disclose the limitation on whatever message we emit:
+  // only changes still present in the workspace were reviewable.
+  if ((!state.baseline || !workspaceMatches) && transcriptEditEvidence) {
+    const note =
+      " (Limitation: no SessionStart baseline was recorded; only changes still present in the " +
+      "workspace were reviewable. Reinstall the SessionStart hook for full coverage.)";
+    if (decision.systemMessage) {
+      decision = { ...decision, systemMessage: decision.systemMessage + note };
+    } else if (decision.action === "block" && decision.reason) {
+      decision = { ...decision, reason: decision.reason + note };
+    }
+  }
+
+  return emit(decision, io);
+}
+
+// ---------------------------------------------------------------------------
+// Output mapping
+// ---------------------------------------------------------------------------
+
+// Emit Claude Stop-hook JSON for a decision. block -> decision/reason;
+// advisory (allow + systemMessage) -> systemMessage; silent allow -> nothing.
+function emit(decision, io) {
+  process.exitCode = 0;
+  if (!decision) return decision;
+  if (decision.action === "block") {
+    io.stdout.write(JSON.stringify({ decision: "block", reason: decision.reason || "" }));
+    return decision;
+  }
+  if (decision.systemMessage) {
+    io.stdout.write(JSON.stringify({ systemMessage: decision.systemMessage }));
+    return decision;
+  }
+  // Silent allow: no stdout output.
+  return decision;
+}
+
+// ---------------------------------------------------------------------------
+// Workspace-scoped state keying
+// ---------------------------------------------------------------------------
+
+// Resolve a stable, canonical absolute path for a workspace root. realpathSync
+// resolves symlinks so two different paths pointing at the same directory key
+// the same state; if it throws (e.g. the path does not yet exist) we fall back
+// to path.resolve so we still get an absolute, normalized key.
+export function canonicalWorkspaceRoot(cwd) {
+  try {
+    return realpathSync(cwd);
+  } catch {
+    return resolve(cwd);
+  }
+}
+
+// Compose the session-state key from BOTH the host session id AND the canonical
+// workspace root. Without the workspace component, two different workspaces that
+// happen to share a session_id would collide on a single state file — letting
+// repo A's baseline be used to evaluate repo B (a silent bypass). Including the
+// canonical root makes the on-disk state file distinct per workspace, and keeps
+// the gate's block-counter/cache consistent under the same composite key.
+export function sessionStateKey(sessionId, cwd) {
+  return `${sessionId || ""} ${canonicalWorkspaceRoot(cwd)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// Parse a `--flag <value>` pair from argv.
+function parseFlag(argv, flag) {
+  const i = argv.indexOf(flag);
+  if (i >= 0 && argv[i + 1]) return argv[i + 1];
+  return null;
+}
+
+// Read all of stdin and parse it as JSON. Tolerant: empty/unreadable/malformed
+// input yields `{}` so a malformed payload with no edit evidence fails open.
+async function readStdinJson(stdin) {
+  const text = await readStream(stdin);
+  if (!text || !text.trim()) return {};
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+// Drain a readable stream to a string. Accepts a Node Readable, an async
+// iterable, or a plain string (tests may inject any of these).
+async function readStream(stdin) {
+  if (stdin == null) return "";
+  if (typeof stdin === "string") return stdin;
+  const chunks = [];
+  try {
+    for await (const chunk of stdin) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+  } catch {
+    return chunks.length ? Buffer.concat(chunks).toString("utf8") : "";
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}