heyspex 0.1.0 → 0.2.1

package/spexharness/src/gates/vault-mirror-catchup.mjs

@@ -0,0 +1,124 @@
+// spexharness/src/gates/vault-mirror-catchup.mjs
+//
+// SessionStart catch-up for the cloud -> local vault mirror (diagnose HS-XJFQ, acceptance criterion 3:
+// "a Companion or MCP session start against a clone that is behind the cloud closes the gap before the
+// first tool call"). In cloud write mode the console is the system of record and the disk clone is a
+// mirror; this gate starts `hs pull --apply` in the BACKGROUND so the hook returns immediately.
+//
+// Fail-open and silent on every skip: local reliance, no vault root / no heyspex.yaml, kill switch
+// HEYSPEX_VAULT_MIRROR_CATCHUP_OFF=1, or a catch-up that already ran in the last 10 minutes (stamp file).
+// Never denies. Emits one line of additionalContext when it spawns.
+//
+// ctx (all optional, for tests): env, vaultRoot, writeMode, now, exists(p), statMtimeMs(p), mkdirp(p),
+// writeFile(p, s), openLog(p) -> fd, spawnDetached(cmd, args, opts), hsCommand() -> { command, args, shell }.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { defaultConfigRoot } from '../config-root.mjs';
+import { resolveDevMode } from '../../../scripts/lib/dev-mode.mjs';
+import { describeHsCommand } from '../../../scripts/lib/hs-command.mjs';
+
+export const id = 'vault-mirror-catchup';
+export const event = 'session_start';
+export const severity = 'info';
+
+export const KILL_ENV = 'HEYSPEX_VAULT_MIRROR_CATCHUP_OFF';
+export const FRESH_WINDOW_MS = 10 * 60 * 1000;
+export const LOG_REL = '.heyspex/vault-mirror-catchup.log';
+export const STAMP_REL = '.heyspex/vault-mirror-catchup.stamp';
+
+/** Resolve how to launch `hs pull --apply`: the PATH shim (shell on Windows) or `node <dispatcher>`. */
+export function defaultHsLaunch() {
+  const d = describeHsCommand();
+  if (d.onPath) return { command: 'hs', args: ['pull', '--apply'], shell: process.platform === 'win32' };
+  if (d.dispatcherPath) return { command: process.execPath, args: [d.dispatcherPath, 'pull', '--apply'], shell: false };
+  return { command: 'hs', args: ['pull', '--apply'], shell: process.platform === 'win32' };
+}
+
+/**
+ * Pure-ish decision: returns { spawn: false } or { spawn: true, vaultRoot, command, args, ... }.
+ * All I/O goes through injected deps.
+ */
+export function decideCatchup(deps = {}) {
+  const env = deps.env ?? process.env;
+  if (String(env[KILL_ENV] ?? '') === '1') return { spawn: false, reason: 'kill-switch' };
+  let writeMode = deps.writeMode;
+  if (!writeMode) {
+    try {
+      writeMode = resolveDevMode({ env }).vaultWriteMode;
+    } catch {
+      return { spawn: false, reason: 'dev-mode-unresolved' };
+    }
+  }
+  if (writeMode !== 'cloud') return { spawn: false, reason: 'local-reliance' };
+  let vaultRoot = deps.vaultRoot;
+  if (vaultRoot === undefined) {
+    try {
+      vaultRoot = defaultConfigRoot();
+    } catch {
+      vaultRoot = null;
+    }
+  }
+  if (!vaultRoot) return { spawn: false, reason: 'no-vault-root' };
+  const exists = deps.exists ?? fs.existsSync;
+  if (!exists(path.join(vaultRoot, 'heyspex.yaml'))) return { spawn: false, reason: 'no-heyspex-yaml' };
+
+  const now = (deps.now ?? Date.now)();
+  const stampPath = path.join(vaultRoot, STAMP_REL);
+  const mtime = (deps.statMtimeMs ?? ((p) => {
+    try {
+      return fs.statSync(p).mtimeMs;
+    } catch {
+      return null;
+    }
+  }))(stampPath);
+  if (typeof mtime === 'number' && now - mtime >= 0 && now - mtime < FRESH_WINDOW_MS) {
+    return { spawn: false, reason: 'stamp-fresh' };
+  }
+  const launch = (deps.hsCommand ?? defaultHsLaunch)();
+  return { spawn: true, vaultRoot, stampPath, logPath: path.join(vaultRoot, LOG_REL), ...launch };
+}
+
+/** Perform the detached spawn for a { spawn: true } decision. Throws on failure (caller fails open). */
+export function startCatchup(d, deps = {}) {
+  const mkdirp = deps.mkdirp ?? ((p) => fs.mkdirSync(p, { recursive: true }));
+  const writeFile = deps.writeFile ?? ((p, s) => fs.writeFileSync(p, s));
+  const openLog = deps.openLog ?? ((p) => fs.openSync(p, 'a'));
+  const spawnDetached = deps.spawnDetached ?? ((cmd, args, opts) => spawn(cmd, args, opts));
+  const env = deps.env ?? process.env;
+  mkdirp(path.dirname(d.logPath));
+  writeFile(d.stampPath, new Date((deps.now ?? Date.now)()).toISOString() + '\n');
+  const fd = openLog(d.logPath);
+  const child = spawnDetached(d.command, d.args, {
+    cwd: d.vaultRoot,
+    env: { ...env, HS_VAULT_ROOT: d.vaultRoot },
+    detached: true,
+    stdio: ['ignore', fd, fd],
+    windowsHide: true,
+    shell: d.shell === true,
+  });
+  child?.on?.('error', () => {});
+  child?.unref?.();
+  return child;
+}
+
+export function run(evt, ctx = {}) {
+  try {
+    const d = decideCatchup(ctx);
+    if (!d.spawn) return { decision: 'allow' };
+    startCatchup(d, ctx);
+    return {
+      decision: 'inject',
+      inject: {
+        additionalContext: `vault mirror catch-up: \`hs pull --apply\` started in the background for ${d.vaultRoot} (log: ${LOG_REL})`,
+        severity: 'info',
+      },
+    };
+  } catch {
+    return { decision: 'allow' };
+  }
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/vault-write-tier-guard.decide.mjs

@@ -0,0 +1,125 @@
+// spexharness/src/gates/vault-write-tier-guard.decide.mjs
+//
+// Pure decision for the vault-write-tier-guard PreToolUse gate (HS-FCNH).
+//
+// Problem: on a machine in prod / cloud reliance (`hs dev: prod`) the console
+// reads Neon, and the vault clone on disk is a MIRROR the console never reads
+// back. An agent that hand-edits `<vault>/specs/**/*.md` because a console
+// prompt said so writes into a place nobody reads. This gate denies those disk
+// writes in cloud write mode and names the cloud-routed tool to use instead.
+//
+// No process.exit / stdout here. `fs.existsSync` is the only I/O and is
+// injectable (`deps.exists`).
+//
+// call = { toolName, toolInput }
+// deps = { vaultRoot, writeMode, env, cwd?, exists?, platform? }
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { extractShellTargets } from './_shell-write-targets.mjs';
+
+export const KILL_ENV = 'HEYSPEX_VAULT_WRITE_TIER_GUARD_OFF';
+
+const FILE_TOOLS = new Set(['write', 'edit', 'multiedit', 'notebookedit']);
+const SHELL_TOOLS = new Set(['bash', 'powershell']);
+
+function norm(p, platform) {
+  const r = String(p);
+  return platform === 'win32' ? r.toLowerCase() : r;
+}
+
+/** True when `p` resolves to `<vaultRoot>/specs/**\/*.md` outside `.trash/`. */
+export function isGuardedVaultPath(p, { vaultRoot, cwd, platform = process.platform }) {
+  if (!p || typeof p !== 'string') return false;
+  let abs;
+  try {
+    abs = path.resolve(cwd ?? process.cwd(), p);
+  } catch {
+    return false;
+  }
+  const root = norm(path.resolve(vaultRoot), platform);
+  const target = norm(abs, platform);
+  const rel = path.relative(root, target);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
+  const segs = rel.split(/[\\/]+/);
+  if (segs[0] !== 'specs' || segs.length < 2) return false;
+  if (segs.includes('.trash')) return false;
+  return path.extname(target) === '.md';
+}
+
+function editTexts(toolInput) {
+  const out = [];
+  for (const k of ['new_string', 'content', 'new_source', 'command']) {
+    if (typeof toolInput?.[k] === 'string') out.push(toolInput[k]);
+  }
+  if (Array.isArray(toolInput?.edits)) {
+    for (const e of toolInput.edits) if (typeof e?.new_string === 'string') out.push(e.new_string);
+  }
+  return out;
+}
+
+function pickTool(toolInput) {
+  return editTexts(toolInput).some((t) => /^summary:/m.test(t))
+    ? 'heyspex_author_summary'
+    : 'heyspex_edit_file';
+}
+
+const ROWS = [
+  ['summary: field', 'heyspex_author_summary { spec_id, summary }  (load via heyspex_load_tools)', 'heyspex_author_summary'],
+  ['body / other frontmatter', 'heyspex_edit_file { file_path, content }      (cloud-routed in this mode)', 'heyspex_edit_file'],
+  ['status', 'heyspex_submit_for_review / heyspex_claim_spec — never hand-edit status', null],
+  ['new spec', 'heyspex_file_spec', null],
+];
+
+export function denyReason(target, tool) {
+  const rows = ROWS.map(([label, use, t]) => {
+    const mark = t === tool ? '=> ' : '   ';
+    return `${mark}${label.padEnd(24)} → ${use}`;
+  }).join('\n');
+  return (
+    `[vault-write-tier-guard] This machine writes the vault to the CLOUD (hs dev: prod). ` +
+    `${target} is a disk mirror the console never reads back (HS-FCNH).\n${rows}\n` +
+    `Break-glass for a human: ${KILL_ENV}=1.`
+  );
+}
+
+/**
+ * @param {{ toolName: string, toolInput: Record<string, unknown> }} call
+ * @param {{ vaultRoot?: string|null, writeMode?: string, env?: Record<string,string|undefined>,
+ *           cwd?: string, exists?: (p: string) => boolean, platform?: string }} deps
+ * @returns {{ allow: boolean, reason?: string, tool?: string }}
+ */
+export function decide(call, deps = {}) {
+  const env = deps.env ?? process.env;
+  if (deps.writeMode !== 'cloud') return { allow: true };
+  if (String(env[KILL_ENV] ?? '') === '1') return { allow: true };
+  const vaultRoot = deps.vaultRoot;
+  if (!vaultRoot || typeof vaultRoot !== 'string') return { allow: true };
+  const exists = deps.exists ?? ((p) => fs.existsSync(p));
+  if (!exists(path.join(vaultRoot, 'heyspex.yaml'))) return { allow: true };
+
+  const platform = deps.platform ?? process.platform;
+  const ctx = { vaultRoot, cwd: deps.cwd, platform };
+  const tool = String(call?.toolName ?? '').toLowerCase();
+  const input = call?.toolInput ?? {};
+
+  if (FILE_TOOLS.has(tool)) {
+    const fp = input.file_path ?? input.notebook_path ?? input.filePath;
+    if (isGuardedVaultPath(fp, ctx)) {
+      return { allow: false, tool: pickTool(input), reason: denyReason(String(fp), pickTool(input)) };
+    }
+    return { allow: true };
+  }
+
+  if (SHELL_TOOLS.has(tool)) {
+    const command = String(input.command ?? '');
+    if (!command) return { allow: true };
+    for (const t of extractShellTargets(command)) {
+      if (isGuardedVaultPath(t, ctx)) {
+        return { allow: false, tool: pickTool(input), reason: denyReason(t, pickTool(input)) };
+      }
+    }
+  }
+  return { allow: true };
+}

package/spexharness/src/gates/vault-write-tier-guard.mjs

@@ -0,0 +1,42 @@
+// spexharness/src/gates/vault-write-tier-guard.mjs
+//
+// Engine gate for HS-FCNH: in cloud write mode (`hs dev: prod`), deny agent
+// disk writes to `<vault>/specs/**/*.md` — the disk copy is a mirror the console
+// never reads back. Decision logic lives in ./vault-write-tier-guard.decide.mjs.
+//
+// Kill switch (human break-glass): HEYSPEX_VAULT_WRITE_TIER_GUARD_OFF=1.
+// Deliberately NOT in LEGACY_EXIT2_BANNER: it emits the modern
+// permissionDecision: deny JSON via the adapter.
+//
+// `ctx` (all optional): vaultRoot, writeMode, env, cwd, exists.
+
+import { defaultConfigRoot } from '../config-root.mjs';
+import { resolveDevMode } from '../../../scripts/lib/dev-mode.mjs';
+import { decide as legacyDecide, KILL_ENV } from './vault-write-tier-guard.decide.mjs';
+
+export const id = 'vault-write-tier-guard';
+export const event = 'before_tool';
+export const severity = 'block';
+
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[KILL_ENV] ?? '') === '1') return { decision: 'allow' };
+  let writeMode = ctx.writeMode;
+  if (!writeMode) {
+    try {
+      writeMode = resolveDevMode({ env }).vaultWriteMode;
+    } catch {
+      return { decision: 'allow' };
+    }
+  }
+  if (writeMode !== 'cloud') return { decision: 'allow' };
+  const vaultRoot = ctx.vaultRoot ?? defaultConfigRoot();
+  const verdict = legacyDecide(
+    { toolName: evt?.toolName, toolInput: evt?.toolInput ?? {} },
+    { vaultRoot, writeMode, env, cwd: ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), exists: ctx.exists },
+  );
+  if (verdict.allow) return { decision: 'allow' };
+  return { decision: 'deny', reason: verdict.reason };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/git-reflog-audit.mjs

@@ -0,0 +1,294 @@
+// spexharness/src/git-reflog-audit.mjs
+//
+// The SHARED session-close git audit — moved here verbatim from
+// scripts/claude-hooks/git-reflog-audit.mjs (task HS-610I-P3TJ, epic
+// HS-GG01-P3TJ) as wave 6 of [[HS-AZ61-NYPR]] turned that hook into a thin
+// shim over ./gates/git-reflog-audit.mjs. There is exactly ONE copy of the
+// reflog parsing in the tree: this one. The gate imports it; the Claude Code
+// shim reaches it through the gate; scripts/claude-hooks/git-reflog-audit.test.mjs
+// (the original regression suite, unchanged apart from its import path) drives
+// it directly.
+//
+// WHY the rule exists (kept from the original header): every other gate in this
+// family (git-stash-gate, protected-action-intent) works by INTERCEPTING a
+// destructive command as it is issued — bypassed, disabled, or routed around a
+// gap in coverage, the action leaves no independent trace. This is a WITNESS,
+// not a gate: it snapshots git state at session start and diffs it at session
+// close, so a stash or a reset/checkout/rebase that slipped past every other
+// control still shows up in .heyspex/guardrail-history.jsonl — a record
+// independent of the acting agent's honesty.
+//
+// SCOPE: warn only. Never blocks, never denies.
+//
+// Snapshot (session start): writes `{ stash_count, reflog_head_entry,
+// written_at }` to a SESSION-SCOPED file — the filename carries the session id
+// so concurrent sessions on the same working tree never clobber each other's
+// baseline — at `.heyspex/git-reflog-audit/<sessionId>.json`.
+//
+// Diff (stop / session end):
+//   - stash: any INCREASE in `git stash list`'s entry count since the snapshot
+//     names the new top entries (a push always lands at stash@{0}).
+//   - reflog: any HEAD reflog entry newer than the snapshot's recorded head
+//     entry whose action is reset/checkout/rebase is named. Plain commits newer
+//     than the snapshot are NOT flagged — that's normal work. Matching strips
+//     the `HEAD@{N}:` index label before comparing (that label shifts every time
+//     a new entry lands, even when the underlying hash+message didn't change) —
+//     see [[never-chain-cd-with-destructive-git-a]] for why a naive hash-only
+//     compare is not enough: `git stash push` logs its own internal
+//     `reset: moving to HEAD` entry against the SAME hash as the just-committed
+//     HEAD, so hash equality alone can't tell old from new.
+// A clean session (no stash growth, no reset/checkout/rebase reflog entries)
+// appends nothing.
+//
+// TEST ISOLATION: every git call here takes an explicit repoRootPath and shells
+// out as `git -C <repoRootPath> ...` — never a bare `git` relying on cwd, and
+// never a `cd X && git ...` chain.
+//
+// FAIL-SAFE: every exported function degrades to an inert value (null / [] /
+// false) on any git or filesystem failure rather than throwing — this must
+// never break a session start or a session close on its own bug.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { appendGuardrailEvent } from '../../scripts/claude-hooks/_guardrail-events.mjs';
+
+/** The `rule` id every row this module appends is stamped with. */
+export const RULE_ID = 'git-reflog-audit';
+
+/** spexharness/src/ → repo root is two levels up. */
+const DEFAULT_REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/** Env-first repo-root resolution, matching every pre-cutover hook's own helper. */
+export function repoRoot(env = process.env) {
+  const fromEnv = env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  return DEFAULT_REPO_ROOT;
+}
+
+function git(repoRootPath, args) {
+  try {
+    const res = spawnSync('git', ['-C', repoRootPath, ...args], { encoding: 'utf8', timeout: 5000 });
+    if (res.status !== 0) return null;
+    return typeof res.stdout === 'string' ? res.stdout : '';
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `git stash list`, newest first (`stash@{0}` is the top). [] on any failure
+ * (not a repo, git unavailable, etc.) — never throws.
+ */
+export function readStashList(repoRootPath) {
+  const out = git(repoRootPath, ['stash', 'list']);
+  if (out === null) return [];
+  return out.split(/\r?\n/).filter(Boolean);
+}
+
+/**
+ * `git reflog -n <limit>`, newest first. [] on any failure (including a
+ * brand-new repo with no commits yet, where HEAD has no reflog at all).
+ */
+export function readReflogLines(repoRootPath, limit = 50) {
+  const out = git(repoRootPath, ['reflog', '-n', String(limit)]);
+  if (out === null) return [];
+  return out.split(/\r?\n/).filter(Boolean);
+}
+
+/**
+ * Strip the `HEAD@{N}:` index label from a reflog line before comparing two
+ * lines captured at different times — the label shifts by one every time a new
+ * entry is pushed, even when the underlying hash+message is unchanged, so
+ * comparing raw lines would never match a genuinely-unchanged entry.
+ */
+export function normalizeReflogLine(line) {
+  return typeof line === 'string' ? line.replace(/HEAD@\{\d+\}:/, '').trim() : null;
+}
+
+/**
+ * The reflog "action" word for a line — the text right after `HEAD@{N}: ` and
+ * before the next space/colon/paren (`reset: moving to ...` → `reset`;
+ * `rebase (finish): ...` → `rebase`). null when the line doesn't have the
+ * expected shape — never throws.
+ */
+export function reflogAction(line) {
+  if (typeof line !== 'string') return null;
+  const m = /HEAD@\{\d+\}:\s*([a-zA-Z-]+)/.exec(line);
+  return m ? m[1].toLowerCase() : null;
+}
+
+const FLAGGED_REFLOG_ACTIONS = new Set(['reset', 'checkout', 'rebase']);
+
+/**
+ * Snapshot the git state this audit cares about. Never throws — a repo with no
+ * commits yet (empty reflog) or no stash entries yields zeros/nulls.
+ */
+export function captureGitState(repoRootPath) {
+  const stashLines = readStashList(repoRootPath);
+  const reflogLines = readReflogLines(repoRootPath, 1);
+  return {
+    stash_count: stashLines.length,
+    reflog_head_entry: reflogLines[0] ?? null,
+  };
+}
+
+function sanitizeSessionId(sessionId) {
+  const raw =
+    typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : 'unknown-session';
+  return raw.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120);
+}
+
+/** Default session-scoped snapshot path — `.heyspex/git-reflog-audit/<sessionId>.json`. */
+export function snapshotPathFor(repoRootPath, sessionId, snapshotDir = 'git-reflog-audit') {
+  return path.join(repoRootPath, '.heyspex', snapshotDir, `${sanitizeSessionId(sessionId)}.json`);
+}
+
+/**
+ * Session-start half: write the snapshot file. Returns the written snapshot
+ * object, or null on any failure (fail-safe — a write failure here must never
+ * break session start).
+ */
+export function writeSnapshot({ repoRootPath = repoRoot(), sessionId, snapshotPath } = {}) {
+  try {
+    const state = captureGitState(repoRootPath);
+    const snapshot = { ...state, written_at: new Date().toISOString() };
+    const filePath = snapshotPath || snapshotPathFor(repoRootPath, sessionId);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(snapshot));
+    return snapshot;
+  } catch {
+    return null;
+  }
+}
+
+/** Read a previously-written snapshot. null on any failure (missing/corrupt file). */
+export function readSnapshot(snapshotPath) {
+  try {
+    const raw = fs.readFileSync(snapshotPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Diff current git state against a snapshot. Returns
+ *   { newStashEntries: string[], flaggedReflogEntries: string[] }
+ * — both empty on a clean session.
+ */
+export function diffAgainstSnapshot(repoRootPath, snapshot) {
+  const result = { newStashEntries: [], flaggedReflogEntries: [] };
+  if (!snapshot || typeof snapshot !== 'object') return result;
+
+  // --- stash growth -------------------------------------------------------
+  const currentStash = readStashList(repoRootPath);
+  const priorCount = Number.isFinite(snapshot.stash_count) ? snapshot.stash_count : 0;
+  const grown = currentStash.length - priorCount;
+  if (grown > 0) {
+    result.newStashEntries = currentStash.slice(0, grown);
+  }
+
+  // --- reflog: reset/checkout/rebase entries newer than the snapshot ------
+  const priorEntry =
+    typeof snapshot.reflog_head_entry === 'string' ? snapshot.reflog_head_entry : null;
+  const currentReflog = readReflogLines(repoRootPath, 100);
+  if (currentReflog.length && currentReflog[0] !== priorEntry) {
+    const priorNormalized = normalizeReflogLine(priorEntry);
+    const idx =
+      priorNormalized === null
+        ? -1
+        : currentReflog.findIndex((line) => normalizeReflogLine(line) === priorNormalized);
+    // idx === -1 means no baseline (fresh repo) or the old entry fell outside
+    // the fetch window — bounded fallback: everything fetched is "new".
+    const newLines = idx === -1 ? currentReflog : currentReflog.slice(0, idx);
+    result.flaggedReflogEntries = newLines.filter((line) =>
+      FLAGGED_REFLOG_ACTIONS.has(reflogAction(line)),
+    );
+  }
+
+  return result;
+}
+
+/**
+ * The human-readable half of a flagged diff — `new stash: … ; reflog: …`, the
+ * exact `matchContext` string the guardrail-history row carries. Pure.
+ *
+ * @param {{ newStashEntries?: string[], flaggedReflogEntries?: string[] }} diff
+ * @returns {string} '' when nothing was flagged.
+ */
+export function describeDiff(diff) {
+  const parts = [];
+  if (diff?.newStashEntries?.length) parts.push(`new stash: ${diff.newStashEntries.join(' | ')}`);
+  if (diff?.flaggedReflogEntries?.length) {
+    parts.push(`reflog: ${diff.flaggedReflogEntries.join(' | ')}`);
+  }
+  return parts.join(' ; ');
+}
+
+/** True when a diff has anything worth warning about. Pure. */
+export function isFlagged(diff) {
+  return Boolean(diff?.newStashEntries?.length || diff?.flaggedReflogEntries?.length);
+}
+
+/**
+ * Stop / session-end half: read the snapshot, diff, and — only if something was
+ * flagged — append ONE warn row to guardrail-history.jsonl naming it. Returns
+ * the diff result (so a caller/test can assert on it), or null when there was
+ * no snapshot to compare against (nothing to do, no false-flag risk).
+ *
+ * @param {{ repoRootPath?: string, sessionId?: string, snapshotPath?: string,
+ *   append?: (row: object, repoRoot: string) => unknown }} [opts]
+ *   `append` — override the guardrail-history writer (tests, and any front that
+ *   wants the decision without the file write).
+ */
+export function runSessionEnd({
+  repoRootPath = repoRoot(),
+  sessionId,
+  snapshotPath,
+  append = appendGuardrailEvent,
+} = {}) {
+  const filePath = snapshotPath || snapshotPathFor(repoRootPath, sessionId);
+  const snapshot = readSnapshot(filePath);
+  if (!snapshot) return null;
+
+  const diff = diffAgainstSnapshot(repoRootPath, snapshot);
+  if (!isFlagged(diff)) return diff;
+
+  try {
+    append(
+      {
+        rule: RULE_ID,
+        surface: 'session-close',
+        severity: 'warn',
+        decision: 'warn',
+        matchContext: describeDiff(diff),
+      },
+      repoRootPath,
+    );
+  } catch {
+    // observability must never break the session close
+  }
+
+  return diff;
+}
+
+export default {
+  RULE_ID,
+  captureGitState,
+  describeDiff,
+  diffAgainstSnapshot,
+  isFlagged,
+  normalizeReflogLine,
+  readReflogLines,
+  readSnapshot,
+  readStashList,
+  reflogAction,
+  repoRoot,
+  runSessionEnd,
+  snapshotPathFor,
+  writeSnapshot,
+};