@clear-capabilities/agentic-security-scanner 0.74.0

package/src/posture/.agentic-security/streak.json

@@ -0,0 +1,24 @@
+{
+  "firstScanDate": "2026-05-13T19:07:35.663Z",
+  "lastScanDate": "2026-05-20T15:34:20.296Z",
+  "totalScans": 223,
+  "daysCleanCritical": 0,
+  "lastCleanDate": "2026-05-19",
+  "lastCriticalDate": "2026-05-20",
+  "hasEverHadCritical": true,
+  "bestDaysCleanCritical": 2,
+  "totalFindingsAtFirstScan": 28,
+  "totalFindingsAtLastScan": 257,
+  "totalFixesInferred": 1,
+  "lastGrade": "C",
+  "bestGrade": "A",
+  "launchCheckPassedAt": null,
+  "achievements": [
+    "first-fix",
+    "first-scan",
+    "grade-a",
+    "scan-veteran-100",
+    "scan-veteran-25"
+  ],
+  "previousGrade": "C"
+}

package/src/posture/CLAUDE.md

@@ -0,0 +1,42 @@
+# scanner/src/posture/
+
+Annotators that run **after** every detector has emitted, plus state stores read by slash commands. 90+ modules — almost all small. Pattern: each module exports a function the engine wires into the annotation pipeline (`annotateX(findings, ctx)`), or a state-read/write helper (`loadX(scanRoot)`).
+
+## What goes where (categories, not exhaustive)
+
+**Annotation pipeline (mutate findings in place — order matters in `engine.js`)**
+`finding-defaults` → `stable-id` → `clustering` → `reachability-filter` → `confidence` → `calibration` → `exploitability` → `mitigation-composite` → `persona-prioritization` → `why-fired`. The order is encoded in `engine.js`; if you add an annotator, decide whether it consumes upstream signals (confidence, family, parser) and place it after those.
+
+**Calibration + held-out evaluation** — `calibration.js`, `calibration-drift.js`, `validator-metrics.js`, `holdout-eval.js`. The seed corpus lives at `calibration-seed.json`; held-out labels are taken via `loadLabeledJsonl`. Brier and ECE both live in `holdout-eval.js`; never reintroduce a "fit-on-the-table" version.
+
+**Cross-language taint** — `cross-lang-{openapi,grpc,graphql,orm,queues,meta}.js`. Each parses a contract artifact (`openapi.json`, `*.proto`, `*.graphql`, queue config) and emits a chain finding when the same data crosses a language boundary into another module's finding.
+
+**Risk amplification** — `epss.js`, `kev` (in `version.js`), `blast-radius.js`, `crown-jewels.js`, `exploitability.js`, `bounty-prediction.js`, `risk-in-dollars` (lives in `scripts/`, not here).
+
+**Production-posture ingest** — `auth-posture-import.js`, `network-policy-import.js`, `telemetry-ingest.js`, `waf-ingest.js`, `feature-flags.js`. These read customer-side YAML and convert to mitigation flags consumed by `mitigation-composite.js`.
+
+**Fix lifecycle** — `fix-history.js` (apply + backup + recover), `fix-verify.js` (closed-loop re-scan + lint), `fix-plan.js` (oversized-patch fallback), `regression-test-gen.js`.
+
+**Agentic verification** — `verifier.js`, `verifier-target.js`, `verifier-ephemeral.js`, `harness-discovery.js`, `adversary-agent.js`, `defender-agent.js`, `auditor-agent.js`, `three-agent-pipeline.js`.
+
+**Integrity + signing** — `integrity.js` (per-install HMAC for `last-scan.json`), `rule-pack-signing.js`. The HMAC key lives at `$XDG_CONFIG_HOME/agentic-security/scan-key`; override via `$AGENTIC_SECURITY_HMAC_KEY`. Premortem-derived; do not regress to hostname-derived.
+
+**Rule lifecycle** — `custom-rules.js` (YAML pattern DSL), `rule-overrides.js` (`disable:` gated on signature), `rule-packs.js`, `rule-synthesis.js` (proposes suppressions from triage feedback), `ruleset-version.js`.
+
+**Posture artifacts** — `sbom.js`, `aibom.js`, `api-inventory.js`, `threat-model.js`, `trust-boundary-diagram.js`, `stack-playbook.js`, `deploy-platform.js`, `license-policy.js`, `material-change.js`, `mttr.js`, `streak.js`, `scorecard.js`, `security-trend.js`.
+
+**Why this fired** — `why-fired.js`. Runs LAST so it reflects every annotation. Customer-facing provenance.
+
+## Conventions
+
+- **Mutate or copy?** Annotators that set finding fields mutate in place. Helpers that derive a *new* finding list (clustering, dead-code) return a new array.
+- **State files.** All state goes under `.agentic-security/` (scan root) or `~/.config/agentic-security/` (per-install). Never write to the scanner source tree.
+- **Annotation order matters.** If your annotator reads `f.confidence`, run it after `annotateConfidence`. If it reads `f.exploitability`, run it after `annotateExploitability`. Wire in `engine.js`, not in `index.js`.
+- **No throwing.** Every annotation in `engine.js` is wrapped `try { … } catch (_) {}`. Your annotator must degrade gracefully — set `null` on the field and continue.
+- **Dead-module test.** `npm run test:lifecycle` fails the build if you export a public symbol from a posture module that no other source file imports. Wire it in `engine.js` (or allowlist it with a written reason in `test/no-dead-modules.test.js`).
+
+## Gotchas
+
+- The seed `calibration-seed.json` is small (n < 30 for several families). Don't treat it as a held-out set — that's `holdout-eval.js`'s job, against an externally-supplied JSONL.
+- `learning.js` (active-learning loop) is **opt-in** behind `AGENTIC_SECURITY_LEARN=1` and has a quorum gate. Do not lower the quorum default without thinking about what a malicious-PR-author could suppress.
+- `why-fired.js` is the provenance surface customers screenshot. If you change its shape, downstream reports break — bump a version string and migrate consumers.

package/src/posture/adversarial-self-test.js

@@ -0,0 +1,114 @@
+// FR-LEARN-8 — Adversarial self-test (mutation harness).
+//
+// Generate adversarial source-code variants from known-vuln fixtures and
+// re-scan them. Variants that the scanner FAILS to detect (false negatives)
+// are surfaced as `rule-gap` records for review and prioritization in the
+// next rule-pack release. Variants that the scanner still catches confirm
+// robustness.
+//
+// This module exposes:
+//   mutateSnippet(code, family)  — produces 1..N adversarial variants of `code`
+//                                  intended to defeat the family's detector
+//   buildMutationCorpus(fixtures) — applies mutations across the fixture set
+//
+// It does NOT run the scanner itself — that's a CLI / bench-runner concern.
+// The orchestrator is `scripts/run-self-test.mjs` (created separately).
+//
+// Mutation strategies per family:
+//   sql-injection:
+//     - rename `query` → `q`, `db` → `client` (identifier obfuscation)
+//     - wrap concat in `String(x)` or `${x}` (template-literal obfuscation)
+//     - reorder: build the string in a helper that returns it
+//   command-injection:
+//     - swap `exec` → `execSync` → `spawn` (variant API surface)
+//     - introduce a no-op `sanitize(x)` that doesn't sanitize
+//   xss:
+//     - swap `innerHTML` for `outerHTML`, `insertAdjacentHTML`, `document.write`
+//   path-traversal:
+//     - introduce a noop `path.normalize` (allowed under the regex but still
+//       traversable when input is `..%2F` style)
+//   ssrf:
+//     - swap `fetch` for `axios`, `got`, `node-fetch`
+//   prototype-pollution:
+//     - swap `__proto__` for `["__proto__"]`, then for `["__pro" + "to__"]`
+
+const STRATEGIES = {
+  'sql-injection': [
+    (code) => code.replace(/\bquery\b/g, 'q').replace(/\bdb\b/g, 'client'),
+    (code) => code.replace(/'.*?\+.*?'/g, (m) => '`' + m.replace(/'/g, '') + '`'),
+    (code) => 'function buildQ(x) { return ' + JSON.stringify(code) + '; } buildQ(userInput);',
+  ],
+  'command-injection': [
+    (code) => code.replace(/\bexec\b/g, 'execSync'),
+    (code) => code.replace(/\bexec\b/g, 'spawn'),
+    (code) => `function sanitize(x) { return x; }\n${code.replace(/exec\(([^)]+)\)/, 'exec(sanitize($1))')}`,
+  ],
+  'xss': [
+    (code) => code.replace(/\.innerHTML\s*=/g, '.outerHTML ='),
+    (code) => code.replace(/\.innerHTML\s*=\s*(\w+)/, '.insertAdjacentHTML("beforeend", $1)'),
+    (code) => code.replace(/\.innerHTML\s*=\s*(\w+)/, 'document.write($1)'),
+  ],
+  'path-traversal': [
+    (code) => `const path = require('path');\n${code.replace(/readFile\(/, 'readFile(path.normalize(')}`,
+  ],
+  'ssrf': [
+    (code) => code.replace(/\bfetch\b/g, 'axios.get'),
+    (code) => code.replace(/\bfetch\b/g, 'require("got")'),
+    (code) => code.replace(/\bfetch\b/g, 'require("node-fetch")'),
+  ],
+  'prototype-pollution': [
+    (code) => code.replace(/__proto__/g, '["__proto__"]'),
+    (code) => code.replace(/__proto__/g, '["__pro" + "to__"]'),
+  ],
+  'webhook-no-signature': [
+    (code) => `${code}\nfunction verify(){ return true; }`,
+  ],
+};
+
+export function mutateSnippet(code, family) {
+  if (!code || typeof code !== 'string') return [];
+  const strategies = STRATEGIES[family] || [];
+  const variants = [];
+  for (const fn of strategies) {
+    try {
+      const v = fn(code);
+      if (v && v !== code) variants.push(v);
+    } catch {}
+  }
+  return variants;
+}
+
+// Build a mutation corpus from a fixture record { id, family, code }.
+// Returns array of { fixtureId, family, originalCode, mutations: [{ strategy, code }] }.
+export function buildMutationCorpus(fixtures) {
+  if (!Array.isArray(fixtures)) return [];
+  const out = [];
+  for (const fx of fixtures) {
+    if (!fx || !fx.family || !fx.code) continue;
+    const muts = mutateSnippet(fx.code, fx.family);
+    out.push({
+      fixtureId: fx.id || `${fx.family}-${fx.file || 'inline'}`,
+      family: fx.family,
+      originalCode: fx.code,
+      mutations: muts.map((c, i) => ({ strategy: `mut-${i + 1}`, code: c })),
+    });
+  }
+  return out;
+}
+
+// Format a self-test report given a list of mutation runs and detector hits.
+// Each run: { fixtureId, family, mutation, detectedByScanner }. The report
+// lists ungapped strategies (still detected) and gaps (missed mutations).
+export function summarizeSelfTest(runs) {
+  if (!Array.isArray(runs)) return { gaps: [], confirmed: [], totalRuns: 0 };
+  const gaps = runs.filter(r => r.detectedByScanner === false).map(r => ({
+    family: r.family,
+    fixtureId: r.fixtureId,
+    strategy: r.mutation?.strategy,
+    suggestion: `Add a fixture pair in scanner/test/fixtures/ that captures this mutation, then strengthen the ${r.family} detector to match.`,
+  }));
+  const confirmed = runs.filter(r => r.detectedByScanner === true).map(r => ({
+    family: r.family, fixtureId: r.fixtureId, strategy: r.mutation?.strategy,
+  }));
+  return { gaps, confirmed, totalRuns: runs.length };
+}

package/src/posture/adversary-agent.js

@@ -0,0 +1,204 @@
+// FR-ADV-1 — Multi-step adversary-agent skeleton.
+//
+// Given ONE finding and a live target URL (from FR-LIVE-HARNESS), an LLM
+// agent operates with a bounded tool-call budget and emits a transcript
+// showing what an attacker would actually DO with the finding.
+//
+// Tools available to the agent (each gated by an ACL — there is no shell,
+// no filesystem write, no real DB. The agent operates against a sandboxed
+// COPY of the target.):
+//
+//   http.get(path, headers?)             — read against the sandbox URL
+//   http.post(path, body, headers?)      — write against the sandbox URL
+//   db.read_sandbox_copy(query)          — read against the sandbox DB
+//   record_outcome(outcomeType, evidence) — terminate run, emit verdict
+//
+// Each tool call is hash-chained into the transcript so the trace is
+// tamper-evident. Budget enforcement: ≤ MAX_CALLS calls, ≤ MAX_WALL_MS ms.
+//
+// This module is a SKELETON. It defines the transcript shape, the tool ACL,
+// and the budget/timeout enforcement. It does NOT call any LLM endpoint by
+// default — that wiring lives in the runner / `agentic-security verify
+// --adversary-agent` CLI, which reads AGENTIC_SECURITY_LLM_ENDPOINT.
+//
+// When no LLM endpoint is configured, `runAgent` short-circuits with verdict
+// `unverified-no-llm-endpoint` and the transcript records only the seed input.
+
+import * as crypto from 'node:crypto';
+
+const MAX_CALLS_DEFAULT = 50;
+const MAX_WALL_MS_DEFAULT = 15 * 60 * 1000;
+
+const TOOL_ACL = new Set([
+  'http.get',
+  'http.post',
+  'db.read_sandbox_copy',
+  'record_outcome',
+]);
+
+const OUTCOMES = [
+  'data-exfil',
+  'priv-esc',
+  'account-takeover',
+  'financial-loss',
+  'cleanup-traces',
+  'failed',
+  'aborted-budget',
+  'aborted-timeout',
+];
+
+function chainHash(prev, entry) {
+  const h = crypto.createHash('sha256');
+  h.update(prev || '');
+  h.update(JSON.stringify(entry));
+  return h.digest('hex').slice(0, 16);
+}
+
+export function startTranscript(finding, target) {
+  const seed = {
+    seedFinding: {
+      stableId: finding?.stableId || null,
+      file: finding?.file || null,
+      line: finding?.line || null,
+      vuln: finding?.vuln || null,
+      family: finding?.family || null,
+    },
+    target: target || null,
+    startedAt: new Date().toISOString(),
+    entries: [],
+    chainHead: '',
+  };
+  seed.chainHead = chainHash('', seed.seedFinding);
+  return seed;
+}
+
+export function appendEntry(transcript, entry) {
+  if (!transcript || !entry) return;
+  if (entry.tool && !TOOL_ACL.has(entry.tool)) {
+    entry = { ...entry, refused: true, refusedReason: `tool '${entry.tool}' is not in ACL` };
+  }
+  transcript.chainHead = chainHash(transcript.chainHead, entry);
+  transcript.entries.push({ ...entry, hash: transcript.chainHead });
+}
+
+export function isExceeded(transcript, budget) {
+  const calls = transcript.entries.filter(e => e.tool).length;
+  if (calls >= (budget.maxCalls ?? MAX_CALLS_DEFAULT)) return 'aborted-budget';
+  const startedAt = Date.parse(transcript.startedAt);
+  if (Number.isFinite(startedAt) && Date.now() - startedAt > (budget.maxWallMs ?? MAX_WALL_MS_DEFAULT)) {
+    return 'aborted-timeout';
+  }
+  return null;
+}
+
+// Default llmInvoke — calls AGENTIC_SECURITY_LLM_ENDPOINT with the transcript
+// and parses the response as a single tool-call request. The endpoint is
+// expected to follow an OpenAI-style chat-completions shape; we extract a
+// JSON object of `{ tool, args }` from the model's reply.
+export async function defaultLlmInvoke(transcript) {
+  const endpoint = process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
+  if (!endpoint) return null;
+  const model = process.env.AGENTIC_SECURITY_LLM_MODEL || 'gpt-4o-mini';
+  const apiKey = process.env.AGENTIC_SECURITY_LLM_API_KEY || process.env.OPENAI_API_KEY || '';
+  const headers = { 'Content-Type': 'application/json' };
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+  const tools = [...TOOL_ACL].map(t => ({ tool: t, description: TOOL_HELP[t] || '' }));
+  const body = {
+    model,
+    messages: [
+      { role: 'system', content: `You are an authorized security tester. You may ONLY call tools from this list: ${[...TOOL_ACL].join(', ')}. Reply with a single JSON object of the shape {"tool":"<name>","args":{...}}. Stop when you have evidence sufficient to call record_outcome.` },
+      { role: 'user', content: `Seed finding: ${JSON.stringify(transcript.seedFinding)}\nTarget: ${transcript.target}\nPrior entries: ${JSON.stringify(transcript.entries.slice(-8))}\nAvailable tools: ${JSON.stringify(tools)}` },
+    ],
+    max_tokens: 256,
+    temperature: 0.1,
+  };
+  let res;
+  try {
+    res = await fetch(endpoint, { method: 'POST', headers, body: JSON.stringify(body) });
+  } catch (e) {
+    return null;
+  }
+  if (!res.ok) return null;
+  let json;
+  try { json = await res.json(); } catch { return null; }
+  const text = json?.choices?.[0]?.message?.content ?? json?.message?.content ?? '';
+  if (!text) return null;
+  const m = /\{[\s\S]*\}/.exec(text);
+  if (!m) return null;
+  try { return JSON.parse(m[0]); } catch { return null; }
+}
+
+const TOOL_HELP = {
+  'http.get': 'GET a path against the sandbox target URL',
+  'http.post': 'POST a body to a path against the sandbox target URL',
+  'db.read_sandbox_copy': 'Read-only query against the sandboxed DB copy',
+  'record_outcome': 'Terminate the run with a verdict (outcome: one of OUTCOMES)',
+};
+
+// Default executeTool — wraps http.get / http.post against `transcript.target`.
+// Falls back to refusal when the tool is db.read_sandbox_copy (we do not ship
+// a sandboxed DB by default; the caller must supply one).
+export async function defaultExecuteTool(call, transcript) {
+  if (!call || !TOOL_ACL.has(call.tool)) return { refused: true };
+  if (call.tool === 'http.get') {
+    const url = (transcript?.target || '').replace(/\/$/, '') + (call.args?.path || '/');
+    try {
+      const r = await fetch(url, { method: 'GET', headers: call.args?.headers || {} });
+      const body = await r.text();
+      return { status: r.status, headers: Object.fromEntries(r.headers), body: body.slice(0, 4000) };
+    } catch (e) { return { error: String(e?.message || e) }; }
+  }
+  if (call.tool === 'http.post') {
+    const url = (transcript?.target || '').replace(/\/$/, '') + (call.args?.path || '/');
+    try {
+      const r = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...(call.args?.headers || {}) },
+        body: typeof call.args?.body === 'string' ? call.args.body : JSON.stringify(call.args?.body || {}),
+      });
+      const body = await r.text();
+      return { status: r.status, headers: Object.fromEntries(r.headers), body: body.slice(0, 4000) };
+    } catch (e) { return { error: String(e?.message || e) }; }
+  }
+  return { refused: true, reason: `tool ${call.tool} not implemented by defaultExecuteTool` };
+}
+
+// Run the agent loop. Without an `llmInvoke` callback AND without
+// AGENTIC_SECURITY_LLM_ENDPOINT, this short-circuits to
+// `unverified-no-llm-endpoint`. With either, it loops bounded by the budget.
+export async function runAgent(finding, opts = {}) {
+  const transcript = startTranscript(finding, opts.target);
+  const budget = { maxCalls: opts.maxCalls, maxWallMs: opts.maxWallMs };
+
+  const llmInvoke = opts.llmInvoke || (process.env.AGENTIC_SECURITY_LLM_ENDPOINT ? defaultLlmInvoke : null);
+  const executeTool = opts.executeTool || (transcript.target ? (call) => defaultExecuteTool(call, transcript) : null);
+
+  if (typeof llmInvoke !== 'function' || typeof executeTool !== 'function') {
+    appendEntry(transcript, { phase: 'init', reason: 'no llmInvoke/executeTool supplied and AGENTIC_SECURITY_LLM_ENDPOINT not set' });
+    return { transcript, outcome: 'unverified-no-llm-endpoint' };
+  }
+
+  let outcome = null;
+  while (!outcome) {
+    const reason = isExceeded(transcript, budget);
+    if (reason) { outcome = reason; break; }
+    let next;
+    try { next = await llmInvoke(transcript); }
+    catch (e) { appendEntry(transcript, { phase: 'llm-error', error: String(e?.message || e) }); outcome = 'failed'; break; }
+    if (!next || !next.tool) { outcome = 'failed'; appendEntry(transcript, { phase: 'no-tool', value: next }); break; }
+    if (!TOOL_ACL.has(next.tool)) { appendEntry(transcript, { tool: next.tool, refused: true }); continue; }
+    if (next.tool === 'record_outcome') {
+      const o = OUTCOMES.includes(next.args?.outcome) ? next.args.outcome : 'failed';
+      appendEntry(transcript, { tool: 'record_outcome', args: next.args || {} });
+      outcome = o; break;
+    }
+    let res;
+    try { res = await executeTool(next); }
+    catch (e) { res = { error: String(e?.message || e) }; }
+    appendEntry(transcript, { tool: next.tool, args: next.args, result: res });
+  }
+
+  return { transcript, outcome: outcome || 'failed' };
+}
+
+export { TOOL_ACL, OUTCOMES };

package/src/posture/agents-memory.js

@@ -0,0 +1,135 @@
+// AGENTS.md — writable continual-learning memory (harness-anatomy #2).
+//
+// LangChain post:
+//   "Harnesses support memory file standards like AGENTS.md which get
+//    injected into context on agent start. As agents add and edit this file,
+//    harnesses load the updated file into context. This is a form of
+//    continual learning where agents durably store knowledge from one
+//    session and inject that knowledge into future sessions."
+//
+// Distinct from CLAUDE.md:
+//   - CLAUDE.md = human-authored project conventions, gotchas, layout.
+//   - AGENTS.md = agent-authored notes ("what worked / didn't work / I'd try
+//                  differently next time"). Append-only. Bounded.
+//
+// Lives at `<project>/.agentic-security/AGENTS.md`.
+//
+// Bounds:
+//   - MAX_BYTES (default 20 KB) — past this, the oldest entries rotate to
+//     `AGENTS.md.archive` (also bounded; oldest archive entries are dropped).
+//   - MAX_ENTRY_BYTES (default 2 KB) — caps a single appendage.
+//   - Entries are append-only with an ISO timestamp + section divider, so
+//     readers can grep / slice by date without parsing.
+//
+// We deliberately avoid tying AGENTS.md to a session-id namespace. The post's
+// recommendation is FLAT continual learning — the whole project's agents see
+// each other's notes. Subagents that want session-scoped scratch use the
+// agent-scratchpad surface instead.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const MEMORY_FILE = '.agentic-security/AGENTS.md';
+const ARCHIVE_FILE = '.agentic-security/AGENTS.md.archive';
+const MAX_BYTES = 20 * 1024;
+const MAX_ENTRY_BYTES = 2 * 1024;
+const ARCHIVE_MAX_BYTES = 200 * 1024;
+const HEADER = '# AGENTS.md\n\nAgent-authored continual-learning notes. Each entry: timestamp + agent name + one short paragraph. New entries appended at the bottom; oldest entries rotate to AGENTS.md.archive when this file exceeds 20 KB.\n\n';
+
+function _resolve(scanRoot) { return path.join(scanRoot, MEMORY_FILE); }
+function _archivePath(scanRoot) { return path.join(scanRoot, ARCHIVE_FILE); }
+
+export function readAgentsMemory(scanRoot) {
+  const fp = _resolve(scanRoot);
+  if (!fs.existsSync(fp)) return '';
+  try { return fs.readFileSync(fp, 'utf8'); } catch { return ''; }
+}
+
+export function appendAgentsMemory(scanRoot, { agent, body }) {
+  if (typeof agent !== 'string' || !agent.length) {
+    return { ok: false, reason: 'agent: required string' };
+  }
+  if (!/^[A-Za-z0-9_.-]{1,64}$/.test(agent)) {
+    return { ok: false, reason: 'agent: must match [A-Za-z0-9_.-]{1,64}' };
+  }
+  if (typeof body !== 'string' || !body.trim().length) {
+    return { ok: false, reason: 'body: required non-empty string' };
+  }
+  let snippet = body.trim();
+  // Strip control chars and cap.
+  snippet = snippet.replace(/[\x00-\x08\x0b-\x0c\x0e-\x1f\x7f]/g, ' ');
+  if (snippet.length > MAX_ENTRY_BYTES) {
+    snippet = snippet.slice(0, MAX_ENTRY_BYTES) + '…';
+  }
+  const ts = new Date().toISOString();
+  const entry = `\n## ${ts}  agent: ${agent}\n\n${snippet}\n`;
+  try {
+    const fp = _resolve(scanRoot);
+    fs.mkdirSync(path.dirname(fp), { recursive: true });
+    if (!fs.existsSync(fp)) fs.writeFileSync(fp, HEADER);
+    fs.appendFileSync(fp, entry);
+    _maybeRotate(scanRoot);
+    const stat = fs.statSync(fp);
+    return { ok: true, entryBytes: entry.length, fileSize: stat.size };
+  } catch (e) {
+    return { ok: false, reason: `write-failed: ${e.message}` };
+  }
+}
+
+function _maybeRotate(scanRoot) {
+  const fp = _resolve(scanRoot);
+  let body;
+  try { body = fs.readFileSync(fp, 'utf8'); } catch { return; }
+  if (body.length <= MAX_BYTES) return;
+  // Split on the `## ` entry headers. Keep the most-recent N until the head
+  // (everything before the cut) drops below MAX_BYTES/2; move the head to
+  // the archive.
+  const head = HEADER;
+  const trailing = body.slice(head.length);
+  const sections = trailing.split(/(?=\n## )/g).filter(s => s.length);
+  // Walk from the end, accumulating until we have roughly MAX_BYTES/2 of
+  // recent entries. Everything else goes to the archive.
+  let kept = '', archive = '', accum = 0;
+  for (let i = sections.length - 1; i >= 0; i--) {
+    if (accum + sections[i].length <= MAX_BYTES / 2) {
+      kept = sections[i] + kept;
+      accum += sections[i].length;
+    } else {
+      archive = sections.slice(0, i + 1).join('') + archive;
+      break;
+    }
+  }
+  try {
+    fs.writeFileSync(fp, head + kept);
+    if (archive.length) {
+      const arcFp = _archivePath(scanRoot);
+      let existing = '';
+      try { existing = fs.existsSync(arcFp) ? fs.readFileSync(arcFp, 'utf8') : ''; } catch {}
+      let next = existing + archive;
+      if (next.length > ARCHIVE_MAX_BYTES) {
+        // Drop oldest entries until under cap.
+        const oldestSplit = next.split(/(?=\n## )/g).filter(s => s.length);
+        while (oldestSplit.length && next.length > ARCHIVE_MAX_BYTES) {
+          oldestSplit.shift();
+          next = oldestSplit.join('');
+        }
+      }
+      fs.writeFileSync(arcFp, next);
+    }
+  } catch { /* best-effort rotation */ }
+}
+
+// Public summary helper for the SessionStart hook. Returns a tail aligned
+// to a section header (no leading partial entry, no leading newline).
+export function summarizeForSession(scanRoot, { maxBytes = 6 * 1024 } = {}) {
+  const body = readAgentsMemory(scanRoot);
+  if (!body) return null;
+  if (body.length <= maxBytes) return body;
+  const tail = body.slice(-maxBytes);
+  const firstSection = tail.indexOf('\n## ');
+  if (firstSection < 0) return tail;
+  // Slice past the leading `\n` so the result starts with `## `.
+  return tail.slice(firstSection + 1);
+}
+
+export const _internals = { MAX_BYTES, MAX_ENTRY_BYTES, MEMORY_FILE, ARCHIVE_FILE };