glassbox-trace 0.11.0 → 0.12.0

package/src/fence.mjs

@@ -15,6 +15,9 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 import { findSessions, subagentFiles, resolveTarget, claudeHome } from './cli.mjs';
+import { constants as BUF } from 'node:buffer';
+import { streamBytes } from './jsonl.mjs';
+import { readTextFile } from './textfile.mjs';
 const require = createRequire(import.meta.url);
 const core = require('./trace-core.js');
 
@@ -64,10 +67,24 @@ export function mask(v) { const s = String(v); if (/-----BEGIN/.test(s)) return
 // `re` must have the g flag; `value(m)` picks the secret out of the match (default: the whole match).
 // In raw JSONL a newline inside a string is the two characters \n, so a key at the start of a line sits right after
 // an "n"; B is the word boundary that also accepts an escaped \n, \r or \t before the match.
+// A PEM / PGP body: header lines (Proc-Type:, DEK-Info:, Comment:, Version:) and line breaks — real, or the escaped
+// \n / \r\n of a JSON string — removed, what's left is base64 and at least 64 characters long.
+// Keys arrive with line numbers too: the Read tool's `12\t…` and `cat -n`'s padded `    12\t…` (a literal tab, or
+// \t once JSON-escaped, or \\t twice), and a key that sat inside a JSON file (service-account.json) carries its
+// newlines as \\n — so any run of backslashes before r / n is a line break here (0.12 review).
+export function isKeyBlock(v) {
+  const body = String(v).replace(/^-----BEGIN[^-]*-----/, '').replace(/-----END[^-]*-----$/, '');
+  const lines = body.split(/\r?\n|(?:\\+[rn])+/).map((l) => l.replace(/^\s*\d+(?:\\+t|\t|\u2192)/, '').trim().replace(/^"|",?$/g, '')).filter((l) => l && !/^[A-Za-z][\w-]*:\s/.test(l));
+  const b64 = lines.join('');
+  return b64.length >= 64 && /^[A-Za-z0-9+/=]+$/.test(b64);
+}
 const B = String.raw`(?:(?<![A-Za-z0-9_])|(?<=\\[nrt]))`;
 const R = (src, flags = 'g') => new RegExp(B + src, flags);
 export const DETECTORS = [
-  { id: 'private-key', severity: 'error', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/g, what: 'a private key' },
+  // The body is bounded (16,384 chars; an RSA-4096 PEM is ~3.3 KB) and can't contain another marker, and it must be
+  // a key: after the header lines and line breaks (real or JSON-escaped), base64 only. 0.11 matched from a BEGIN in
+  // one tool result to an END megabytes later. DESIGN.md §21.
+  { id: 'private-key', severity: 'error', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----(?:(?!-----)[\s\S]){1,16384}?-----END (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/g, ok: isKeyBlock, what: 'a private key' },
   { id: 'aws-access-key', severity: 'error', re: R(String.raw`(?:AKIA|ASIA)[0-9A-Z]{16}\b`), what: 'an AWS access key id' },
   { id: 'github-token', severity: 'error', re: R(String.raw`(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})\b`), what: 'a GitHub token' },
   { id: 'anthropic-key', severity: 'error', re: R(String.raw`sk-ant-[A-Za-z0-9_-]{20,}`), what: 'an Anthropic API key' },
@@ -82,6 +99,43 @@ export const DETECTORS = [
   { id: 'jwt', severity: 'warn', re: R(String.raw`eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b`), what: 'a JWT' },
   { id: 'generic-secret', severity: 'warn', re: R(String.raw`(?:(?:api[_-]?key|secret[_-]?key|client[_-]?secret|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|token|passwd|password|pwd)\b(?:\\?["']?\s*[:=]\s*\\?["']?)|bearer\s+)([A-Za-z0-9_\-/+=.]{16,})`, 'gi'), value: (m) => m[1], ok: (v) => !PLACEHOLDER.test(v) && /[0-9]/.test(v) && /[A-Za-z]/.test(v) && entropy(v) >= 3.5, what: 'a secret named by its context' },
 ];
+
+// Export-control and classification markings: opt-in with --markings, because a conversation *about* ITAR is not a
+// spill. Each pattern is the marking as it is printed on a document (banner, legend, distribution statement), not
+// the word in prose. A marking is not a secret, so the preview is the marking itself; and it is never shredded:
+// removing the marking would leave the controlled text in the transcript, unmarked.
+// Each starts with B (defined above): in a transcript a marking at the start of a line follows a JSON "\n",
+// where \b would see the n as a word character and miss it.
+export const MARKINGS = [
+  { id: 'classification-banner', severity: 'error', re: R(String.raw`(?:(?:TOP SECRET|SECRET|CONFIDENTIAL)\/\/[A-Z][A-Z0-9/ ,-]{1,40}|NOFORN\b)`), what: 'a classification banner' },
+  { id: 'itar-marking', severity: 'error', re: R(String.raw`ITAR[- ](?:CONTROLLED|RESTRICTED)\b`), what: 'an ITAR marking' },
+  { id: 'itar-marking', severity: 'error', re: /subject to the International Traffic in Arms Regulations|export is restricted by the Arms Export Control Act/gi, what: 'the ITAR / AECA export legend' },
+  { id: 'cui-marking', severity: 'error', re: R(String.raw`(?:CUI\/\/[A-Z][A-Z0-9/-]*|CONTROLLED UNCLASSIFIED INFORMATION\b)`), what: 'a CUI marking' },
+  { id: 'distribution-statement', severity: 'error', re: R(String.raw`DISTRIBUTION STATEMENT [B-F]\b`), what: 'a DoD distribution statement (B–F)' },
+  { id: 'export-controlled', severity: 'warn', re: R(String.raw`EXPORT[- ]CONTROLLED\b`), what: 'an export-controlled marking' },
+  { id: 'export-controlled', severity: 'warn', re: /subject to the Export Administration Regulations/gi, what: 'the EAR export legend' },
+  { id: 'eccn', severity: 'warn', re: R(String.raw`ECCN[:\s#]{0,3}[0-9][A-E][0-9]{3}(?:\.[a-z0-9.]{1,8})?\b`, 'gi'), what: 'an export classification number' },
+  { id: 'ear99', severity: 'info', re: R(String.raw`EAR99\b`), what: 'an EAR99 classification' },
+];
+export const MARKING_ADVICE = 'Text marked as controlled reached the model and this disk. Treat it as a possible spill and follow your export-compliance procedure. --shred leaves markings alone: removing one would leave the controlled text unmarked.';
+export const isMarking = (rule, list = MARKINGS) => list.some((d) => d.id === rule);
+
+// A company's own markings: --markings-file FILE, a JSON list of { id, pattern, flags?, severity? }.
+export function loadMarkings(file) {
+  let json; try { json = JSON.parse(readTextFile(String(file))); } catch (e) { throw new Error(`--markings-file ${file}: ${e.code === 'ENOENT' ? 'no such file' : 'not valid JSON'}`); }
+  if (!Array.isArray(json)) throw new Error(`--markings-file ${file}: expected a list of { "id": …, "pattern": … }`);
+  const taken = new Set([...DETECTORS.map((d) => d.id), ...MARKINGS.map((d) => d.id), 'credential-file-read']);
+  return json.map((m, i) => {
+    if (!m || typeof m.id !== 'string' || !/^[a-z0-9][a-z0-9-]{0,40}$/.test(m.id)) throw new Error(`--markings-file ${file}: entry ${i + 1} needs an "id" of lower-case letters, digits and dashes`);
+    if (taken.has(m.id)) throw new Error(`--markings-file ${file}: "${m.id}" is already a built-in rule; pick another id`);
+    if (typeof m.pattern !== 'string' || !m.pattern) throw new Error(`--markings-file ${file}: "${m.id}" needs a "pattern"`);
+    const sev = m.severity || 'warn'; if (!(sev in SEV)) throw new Error(`--markings-file ${file}: "${m.id}" severity must be error, warn or info`);
+    let re; try { re = new RegExp(m.pattern, String(m.flags || '').replace(/g/g, '') + 'g'); } catch (e) { throw new Error(`--markings-file ${file}: "${m.id}" pattern is not a valid regular expression (${e.message})`); }
+    taken.add(m.id);
+    return { id: m.id, severity: sev, re, what: m.what || `the "${m.id}" marking` };
+  });
+}
+
 export const ADVICE = {
   'private-key': 'Generate a new key pair and remove the old public key everywhere it is authorised; then shred.',
   'aws-access-key': 'Deactivate the key in IAM and issue a new one; check CloudTrail for use; then shred.',
@@ -139,21 +193,25 @@ export function scanText(text, opts = {}) {
   const hits = [];
   const spans = []; // [start, end] of accepted hits, for overlap suppression
   const overlaps = (a, b) => spans.some(([x, y]) => a < y && b > x);
-  for (const d of DETECTORS) {
+  const marks = opts.markings || [];
+  for (const d of DETECTORS.concat(marks)) {
+    const marking = marks.includes(d);
     d.re.lastIndex = 0; let m;
     while ((m = d.re.exec(text))) {
+      if (!m[0]) { d.re.lastIndex++; continue; } // a custom pattern that can match nothing must not spin
       const value = d.value ? d.value(m) : m[0];
       const start = d.value ? m.index + m[0].length - value.length : m.index, end = start + value.length;
       if (d.ok && !d.ok(value)) continue;
       if (overlaps(start, end)) continue;
       spans.push([start, end]);
-      hits.push({ rule: d.id, severity: d.severity, start, end, value, preview: mask(value), fingerprint: fp(value), line: lineAt(starts, start) });
+      hits.push({ rule: d.id, severity: d.severity, start, end, value, preview: marking ? value.replace(/\\[nrt]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80) : mask(value), fingerprint: fp(value), line: lineAt(starts, start), marking });
     }
   }
   hits.sort((a, b) => a.start - b.start);
   // Attribution needs the record; parse each line once, and walk every line for tool_use ids (results come after calls)
   // and for credential-file reads.
-  const tools = new Map(); const parsed = new Map(); const fileReads = [];
+  // opts.state carries the tool_use map from one segment of a big file to the next (results come after their calls).
+  const tools = opts.state ? (opts.state.tools || (opts.state.tools = new Map())) : new Map(); const parsed = new Map(); const fileReads = [];
   const hitLines = new Set(hits.map((h) => h.line));
   for (let n = 1; n <= starts.length; n++) {
     const raw = lineText(text, starts, n); if (!raw.trim()) continue;
@@ -164,7 +222,9 @@ export function scanText(text, opts = {}) {
     if (hitLines.has(n)) parsed.set(n, loc);
   }
   for (const h of hits) Object.assign(h, opts.where ? { where: opts.where } : parsed.get(h.line) || { where: 'other' });
-  return hits.concat(fileReads).sort((a, b) => a.start - b.start || SEV[a.severity] - SEV[b.severity]);
+  const all = hits.concat(fileReads).sort((a, b) => a.start - b.start || SEV[a.severity] - SEV[b.severity]);
+  if (opts.lineOffset) for (const h of all) h.line += opts.lineOffset;
+  return all;
 }
 
 // Text Glassbox keeps for later (memory notes, session digests): every value a detector recognises becomes
@@ -192,19 +252,57 @@ function rows(hits) {
   const map = new Map();
   for (const h of hits) {
     const k = [h.rule, h.fingerprint, h.where, h.tool || '', h.path || ''].join('|');
-    if (map.has(k)) { const r = map.get(k); r.count++; r.spans.push([h.start, h.end]); continue; }
-    map.set(k, Object.defineProperties({ rule: h.rule, severity: h.severity, where: h.where, tool: h.tool, path: h.path, line: h.line, preview: h.preview, fingerprint: h.fingerprint, count: 1 }, {
-      value: { value: h.value, enumerable: false }, spans: { value: h.value == null ? [] : [[h.start, h.end]], enumerable: false },
+    if (map.has(k)) { const r = map.get(k); r.count++; if (h.value != null && !h.marking) r.spans.push([h.start, h.end]); continue; } // a credential-file read has no value, a marking is never shredded
+    map.set(k, Object.defineProperties(Object.assign({ rule: h.rule, severity: h.severity, where: h.where, tool: h.tool, path: h.path, line: h.line, preview: h.preview, fingerprint: h.fingerprint, count: 1 }, h.marking ? { marking: true } : {}), {
+      // a marking has no spans, so shred never touches it
+      value: { value: h.value, enumerable: false }, spans: { value: h.value == null || h.marking ? [] : [[h.start, h.end]], enumerable: false },
     }));
   }
   return [...map.values()];
 }
 
+// A big file in segments of whole lines (≤ segmentBytes, 32 MiB by default), each decoded on its own: the whole
+// file never becomes one string (V8's limit is ~512 MB). fn(text, lineOffset, raw) per segment. DESIGN.md §21.
+export const SEGMENT_BYTES = 32 * 1048576;
+export function forEachSegment(file, segBytes, fn) {
+  const fd = fs.openSync(file, 'r'); const chunk = Buffer.allocUnsafe(Math.max(Math.min(segBytes, 8 * 1048576), 4096));
+  let carry = Buffer.alloc(0), lineOffset = 0;
+  const emit = (seg) => {
+    if (seg.length > BUF.MAX_STRING_LENGTH) throw new Error(`a single line of ${seg.length} bytes is too large to scan`);
+    fn(seg.toString('utf8'), lineOffset, seg);
+    let n = 0; for (let i = seg.indexOf(10); i >= 0; i = seg.indexOf(10, i + 1)) n++;
+    lineOffset += n;
+  };
+  try {
+    for (;;) {
+      const got = fs.readSync(fd, chunk, 0, chunk.length, null); if (!got) break;
+      carry = carry.length ? Buffer.concat([carry, chunk.subarray(0, got)]) : Buffer.from(chunk.subarray(0, got));
+      if (carry.length < segBytes) continue;
+      const cut = carry.lastIndexOf(10); if (cut < 0) continue; // one line longer than a segment: keep reading
+      const seg = carry.subarray(0, cut + 1); carry = Buffer.from(carry.subarray(cut + 1));
+      emit(seg);
+    }
+    if (carry.length) emit(carry);
+  } finally { fs.closeSync(fd); }
+}
+
+function scanFileSegmented(file, meta) {
+  const state = {}, hits = []; let lines = 0;
+  forEachSegment(file, meta.segmentBytes || SEGMENT_BYTES, (text, off) => {
+    for (const h of scanText(text, { key: meta.key, where: meta.where, markings: meta.markings, state, lineOffset: off })) hits.push(h);
+    lines = off + text.split('\n').length;
+  });
+  const findings = rows(meta.store ? hits.filter((h) => h.rule !== 'credential-file-read') : hits).map((r) => Object.assign(r, {
+    file, session: meta.store ? meta.session || undefined : meta.session || path.basename(file).replace(/\.jsonl$/, ''), project: meta.project || undefined, store: meta.store || undefined }));
+  return { file, bytes: fs.statSync(file).size, lines, findings, streamed: true };
+}
+
 export function scanFile(file, meta = {}) {
+  if (!meta.store && fs.statSync(file).size > streamBytes()) return scanFileSegmented(file, meta);
   const buf = fs.readFileSync(file);
   if (meta.store && isBinary(buf)) return { file, bytes: buf.length, skipped: 'binary file', findings: [] };
   const text = buf.toString('utf8');
-  const hits = scanText(text, { key: meta.key, where: meta.where });
+  const hits = scanText(text, { key: meta.key, where: meta.where, markings: meta.markings });
   const findings = rows(meta.store ? hits.filter((h) => h.rule !== 'credential-file-read') : hits).map((r) => Object.assign(r, {
     file, session: meta.store ? meta.session || undefined : meta.session || path.basename(file).replace(/\.jsonl$/, ''), project: meta.project || undefined, store: meta.store || undefined }));
   return { file, bytes: buf.length, lines: text.split('\n').length, findings, text, raw: buf };
@@ -215,6 +313,7 @@ export function scanFile(file, meta = {}) {
 // anything is written; on failure the file is left as it was.
 export function shredFile(file, findings, opts = {}) {
   const replacer = opts.replacer || ((f) => `[FENCED:${f.rule}:${f.fingerprint}]`);
+  if (opts.raw == null && opts.text == null && fs.statSync(file).size > streamBytes()) return shredFileSegmented(file, findings, replacer, opts);
   const raw = opts.raw || fs.readFileSync(file);
   const text = opts.text != null ? opts.text : raw.toString('utf8');
   const json = opts.json != null ? opts.json : /\.jsonl$/i.test(file);
@@ -235,6 +334,38 @@ export function shredFile(file, findings, opts = {}) {
   return { written: true, values: spans.length };
 }
 
+// The big-file rewrite: scan each segment again with the same key (so fingerprints match), replace every hit whose
+// rule and fingerprint were reported, check the segment the way the small path checks the file, and write it to the
+// temp file; rename only when every segment passed. Same guarantees as the small path, one segment in memory.
+function shredFileSegmented(file, findings, replacer, opts) {
+  // Markings are never shredded (removing one would leave controlled text unmarked), so they are not wanted here.
+  const want = new Map(); for (const f of findings) if (f.rule !== 'credential-file-read' && !f.marking) want.set(f.rule + '|' + f.fingerprint, f);
+  if (!want.size) return { written: false, values: 0, reason: 'nothing to shred' };
+  const json = opts.json != null ? opts.json : /\.jsonl$/i.test(file);
+  const tmp = file + '.glassbox-shred~'; const mode = fs.statSync(file).mode & 0o777;
+  const fd = fs.openSync(tmp, 'w', mode); const state = {}; let values = 0, failed = null;
+  try {
+    forEachSegment(file, opts.segmentBytes || SEGMENT_BYTES, (text, off, raw) => {
+      if (failed) return;
+      if (!Buffer.from(text, 'utf8').equals(raw)) { failed = 'not plain UTF-8 text; nothing written'; return; }
+      const hits = scanText(text, { key: opts.key, state }).filter((h) => h.value != null && want.has(h.rule + '|' + h.fingerprint));
+      let out = text;
+      if (hits.length) {
+        out = ''; let pos = 0;
+        for (const h of hits) { if (h.start < pos) continue; out += text.slice(pos, h.start) + replacer(want.get(h.rule + '|' + h.fingerprint)); pos = h.end; values++; }
+        out += text.slice(pos);
+        const before = text.split('\n'), after = out.split('\n');
+        if (before.length !== after.length) { failed = 'line count changed; nothing written'; return; }
+        if (json) for (let i = 0; i < after.length; i++) { if (after[i] === before[i]) continue; const l = after[i].replace(/\r$/, ''); if (!l.trim()) continue; try { JSON.parse(l); } catch (e) { failed = `line ${off + i + 1} would not parse after the rewrite; nothing written`; return; } }
+      }
+      fs.writeSync(fd, out);
+    });
+  } catch (e) { failed = e.message; } finally { fs.closeSync(fd); }
+  if (failed || !values) { try { fs.unlinkSync(tmp); } catch (e) { } return { written: false, values, reason: failed || 'nothing to shred' }; }
+  fs.renameSync(tmp, file);
+  return { written: true, values };
+}
+
 // Which files to scan. opts: { home, target, since (ms epoch), project, sessionsOnly }.
 export function targets(opts = {}) {
   const home = opts.home || claudeHome();
@@ -275,16 +406,18 @@ export function fence(opts = {}) {
   const home = opts.home || claudeHome();
   const keyFile = opts.keyFile ? path.resolve(opts.keyFile) : defaultKeyFile(home);
   const key = opts.keyFile ? loadKey(keyFile) : ensureKey(keyFile);
+  // --markings: the built-in export-control set; --markings-file adds a company's own (and implies --markings).
+  const markings = opts.markings || opts.markingsFile ? MARKINGS.concat(opts.markingsFile ? loadMarkings(opts.markingsFile) : []) : [];
   const files = [], findings = [], skipped = []; let bytes = 0; const sessions = new Set();
   const shredded = { files: 0, values: 0, refused: [] };
   for (const t of tg.list) {
     if (t.store && fs.statSync(t.file).size > STORE_MAX_BYTES) { skipped.push({ file: t.file, reason: `larger than ${STORE_MAX_BYTES / 1048576} MB` }); continue; }
-    let r; try { r = scanFile(t.file, { session: t.session, project: t.project, store: t.store, where: t.where, key }); } catch (e) { shredded.refused.push({ file: t.file, reason: e.message }); continue; }
+    let r; try { r = scanFile(t.file, { session: t.session, project: t.project, store: t.store, where: t.where, key, markings }); } catch (e) { shredded.refused.push({ file: t.file, reason: e.message }); continue; }
     if (r.skipped) { skipped.push({ file: t.file, reason: r.skipped }); continue; }
-    files.push({ file: t.file, session: t.session || undefined, store: t.store, bytes: r.bytes, findings: r.findings.length });
+    files.push({ file: t.file, session: t.session || undefined, store: t.store, bytes: r.bytes, findings: r.findings.length, streamed: r.streamed || undefined });
     bytes += r.bytes; if (!t.store) sessions.add(t.session);
     findings.push(...r.findings);
-    if (opts.shred) { const s = shredFile(t.file, r.findings, { text: r.text, raw: r.raw }); if (s.written) { shredded.files++; shredded.values += s.values; } else if (s.reason !== 'nothing to shred') shredded.refused.push({ file: t.file, reason: s.reason }); }
+    if (opts.shred) { const s = shredFile(t.file, r.findings, r.streamed ? { key } : { text: r.text, raw: r.raw }); if (s.written) { shredded.files++; shredded.values += s.values; } else if (s.reason !== 'nothing to shred') shredded.refused.push({ file: t.file, reason: s.reason }); }
   }
   findings.sort((a, b) => SEV[a.severity] - SEV[b.severity] || a.file.localeCompare(b.file) || a.line - b.line);
   // Files actually scanned per store (skipped ones are listed under scanned.skipped); undefined when stores were not in scope.
@@ -292,12 +425,15 @@ export function fence(opts = {}) {
   const bySeverity = { error: 0, warn: 0, info: 0 }; for (const f of findings) bySeverity[f.severity]++;
   const byRule = {}; for (const f of findings) byRule[f.rule] = (byRule[f.rule] || 0) + f.count;
   const secretMap = new Map();
-  for (const f of findings) { if (f.rule === 'credential-file-read') continue; const k = f.fingerprint; if (!secretMap.has(k)) secretMap.set(k, { fingerprint: k, rule: f.rule, severity: f.severity, preview: f.preview, sessions: new Set(), files: new Set(), occurrences: 0, advice: ADVICE[f.rule] }); const s = secretMap.get(k); if (f.session && !f.store) s.sessions.add(f.session); s.files.add(f.file); s.occurrences += f.count; }
-  const secrets = [...secretMap.values()].map((s) => Object.assign(s, { sessions: s.sessions.size, files: s.files.size })).sort((a, b) => SEV[a.severity] - SEV[b.severity] || b.sessions - a.sessions || b.occurrences - a.occurrences);
+  const markMap = new Map();
+  for (const f of findings) { if (f.rule === 'credential-file-read') continue; const map = f.marking ? markMap : secretMap; const k = f.marking ? f.rule + '|' + f.preview : f.fingerprint; if (!map.has(k)) map.set(k, { fingerprint: f.fingerprint, rule: f.rule, severity: f.severity, preview: f.preview, sessions: new Set(), files: new Set(), occurrences: 0, advice: f.marking ? MARKING_ADVICE : ADVICE[f.rule] }); const s = map.get(k); if (f.session && !f.store) s.sessions.add(f.session); s.files.add(f.file); s.occurrences += f.count; }
+  const spread = (m) => [...m.values()].map((s) => Object.assign(s, { sessions: s.sessions.size, files: s.files.size })).sort((a, b) => SEV[a.severity] - SEV[b.severity] || b.sessions - a.sessions || b.occurrences - a.occurrences);
+  const secrets = spread(secretMap), marked = spread(markMap);
   const rep = { glassbox: core.VERSION, kind: 'fence', schema: 2, generated: new Date().toISOString(), mode: tg.mode, home: tg.home, dir: tg.dir, since: opts.since ? new Date(opts.since).toISOString() : undefined,
     fingerprint: { alg: 'hmac-sha256', chars: 8, key: keyFile },
     scanned: { files: files.length, sessions: sessions.size, bytes, stores: storeCounts, storesNote: tg.storesNote, skipped },
-    summary: { bySeverity, byRule, filesWithFindings: files.filter((f) => f.findings).length, distinctSecrets: secrets.length, secrets },
+    summary: { bySeverity, byRule, filesWithFindings: files.filter((f) => f.findings).length, distinctSecrets: secrets.length, secrets, markings: markings.length ? marked : undefined },
+    markings: markings.length ? { rules: [...new Set(markings.map((d) => d.id))], custom: opts.markingsFile ? path.resolve(opts.markingsFile) : undefined } : undefined,
     findings, files };
   if (opts.shred) rep.shredded = shredded;
   return rep;
@@ -317,17 +453,25 @@ export function fenceText(rep) {
   const nStore = rep.scanned.stores ? Object.values(rep.scanned.stores).reduce((a, b) => a + b, 0) : 0;
   L.push(`Glassbox fence · ${what}${nStore ? ` + ${storeLine(rep.scanned.stores)}` : ''} · ${fmtBytes(rep.scanned.bytes)}${rep.since ? ` · since ${rep.since.slice(0, 10)}` : ''}`);
   if (rep.scanned.storesNote) L.push(`  (${rep.scanned.storesNote})`);
-  if (!rep.findings.length) { L.push('  nothing found — no known credential formats, no secrets named by context, no credential-file reads'); }
+  if (rep.markings) L.push(`  export-control markings: on (${rep.markings.rules.length} rules${rep.markings.custom ? `, including ${rep.markings.custom}` : ''})`);
+  if (!rep.findings.length) { L.push(`  nothing found — no known credential formats, no secrets named by context, no credential-file reads${rep.markings ? ', no export-control markings' : ''}`); }
   else {
-    L.push(`  ${s.error} error · ${s.warn} warn · ${s.info} info · ${rep.summary.distinctSecrets} distinct secret${rep.summary.distinctSecrets === 1 ? '' : 's'} in ${rep.summary.filesWithFindings} of ${rep.scanned.files} files`, '');
+    L.push(`  ${s.error} error · ${s.warn} warn · ${s.info} info · ${rep.summary.distinctSecrets} distinct secret${rep.summary.distinctSecrets === 1 ? '' : 's'}${rep.summary.markings ? ` · ${rep.summary.markings.length} marking${rep.summary.markings.length === 1 ? '' : 's'}` : ''} in ${rep.summary.filesWithFindings} of ${rep.scanned.files} files`, '');
     let last = null;
     for (const f of rep.findings) {
       if (f.file !== last) { L.push(`  ${f.file}${f.session && !f.file.includes(f.session) ? `  (session ${f.session.slice(0, 8)})` : ''}`); last = f.file; }
-      L.push(`    ${f.severity.toUpperCase().padEnd(5)} ${f.rule.padEnd(21)} line ${String(f.line).padStart(6)}  ${f.preview}${f.count > 1 ? `  ×${f.count}` : ''}  — ${place(f)}`);
+      L.push(`    ${f.severity.toUpperCase().padEnd(5)} ${f.rule.padEnd(22)} line ${String(f.line).padStart(6)}  ${f.preview}${f.count > 1 ? `  ×${f.count}` : ''}  — ${place(f)}`);
+    }
+    if (rep.summary.secrets.length) {
+      L.push('', '  Secrets, by how far they spread:');
+      for (const x of rep.summary.secrets.slice(0, 20)) L.push(`    ${x.severity.toUpperCase().padEnd(5)} ${x.rule.padEnd(22)} ${x.fingerprint}  ${x.preview}  in ${x.sessions} session${x.sessions === 1 ? '' : 's'}, ${x.occurrences} place${x.occurrences === 1 ? '' : 's'}`);
+      L.push('', '  A secret that reached a transcript reached a disk: rotate it, then run again with --shred to overwrite it in place.');
+    }
+    if (rep.summary.markings && rep.summary.markings.length) {
+      L.push('', '  Export-control markings, by how far they spread:');
+      for (const x of rep.summary.markings.slice(0, 20)) L.push(`    ${x.severity.toUpperCase().padEnd(5)} ${x.rule.padEnd(22)} "${x.preview}"  in ${x.sessions} session${x.sessions === 1 ? '' : 's'}, ${x.occurrences} place${x.occurrences === 1 ? '' : 's'}`);
+      L.push('', '  ' + MARKING_ADVICE);
     }
-    L.push('', '  Secrets, by how far they spread:');
-    for (const x of rep.summary.secrets.slice(0, 20)) L.push(`    ${x.severity.toUpperCase().padEnd(5)} ${x.rule.padEnd(21)} ${x.fingerprint}  ${x.preview}  in ${x.sessions} session${x.sessions === 1 ? '' : 's'}, ${x.occurrences} place${x.occurrences === 1 ? '' : 's'}`);
-    L.push('', '  A secret that reached a transcript reached a disk: rotate it, then run again with --shred to overwrite it in place.');
   }
   if (rep.scanned.skipped && rep.scanned.skipped.length) L.push(`  skipped ${rep.scanned.skipped.length} file${rep.scanned.skipped.length === 1 ? '' : 's'} (binary or too large)`);
   L.push(`  fingerprints: HMAC-SHA256 under ${rep.fingerprint.key} (keep that file on this machine)`);
@@ -339,11 +483,20 @@ export function fenceMarkdown(rep) {
   const L = [`# Glassbox fence — ${rep.generated.slice(0, 10)}`, '', `Scanned ${rep.scanned.files} file${rep.scanned.files === 1 ? '' : 's'} (${rep.scanned.sessions} session${rep.scanned.sessions === 1 ? '' : 's'}${rep.scanned.stores && Object.keys(rep.scanned.stores).length ? ` + ${storeLine(rep.scanned.stores)}` : ''}, ${fmtBytes(rep.scanned.bytes)})${rep.since ? ` written since ${rep.since.slice(0, 10)}` : ''}. Previews are masked and fingerprints are the first 8 hex of HMAC-SHA256 under a key kept on this machine; this report holds no secret values.`, ''];
   if (rep.scanned.storesNote) L.push(`_${rep.scanned.storesNote}._`, '');
   const s = rep.summary.bySeverity;
-  if (!rep.findings.length) { L.push('**Nothing found.** No known credential formats, no secrets named by context, no credential-file reads.'); return L.join('\n') + '\n'; }
-  L.push(`**${s.error} error · ${s.warn} warn · ${s.info} info** — ${rep.summary.distinctSecrets} distinct secret${rep.summary.distinctSecrets === 1 ? '' : 's'} in ${rep.summary.filesWithFindings} of ${rep.scanned.files} files.`, '');
-  L.push('## Secrets, by how far they spread', '', '| severity | rule | fingerprint | preview | sessions | places | do |', '|---|---|---|---|---:|---:|---|');
-  for (const x of rep.summary.secrets) L.push(`| ${x.severity} | \`${x.rule}\` | \`${x.fingerprint}\` | ${x.preview} | ${x.sessions} | ${x.occurrences} | ${x.advice} |`);
-  L.push('', '## Where, file by file', '');
+  if (rep.markings) L.push(`Export-control markings were checked (${rep.markings.rules.map((r) => `\`${r}\``).join(', ')}).`, '');
+  if (!rep.findings.length) { L.push(`**Nothing found.** No known credential formats, no secrets named by context, no credential-file reads${rep.markings ? ', no export-control markings' : ''}.`); return L.join('\n') + '\n'; }
+  L.push(`**${s.error} error · ${s.warn} warn · ${s.info} info** — ${rep.summary.distinctSecrets} distinct secret${rep.summary.distinctSecrets === 1 ? '' : 's'}${rep.summary.markings ? `, ${rep.summary.markings.length} marking${rep.summary.markings.length === 1 ? '' : 's'}` : ''} in ${rep.summary.filesWithFindings} of ${rep.scanned.files} files.`, '');
+  if (rep.summary.secrets.length) {
+    L.push('## Secrets, by how far they spread', '', '| severity | rule | fingerprint | preview | sessions | places | do |', '|---|---|---|---|---:|---:|---|');
+    for (const x of rep.summary.secrets) L.push(`| ${x.severity} | \`${x.rule}\` | \`${x.fingerprint}\` | ${x.preview} | ${x.sessions} | ${x.occurrences} | ${x.advice} |`);
+    L.push('');
+  }
+  if (rep.summary.markings && rep.summary.markings.length) {
+    L.push('## Export-control markings, by how far they spread', '', '| severity | rule | marking | sessions | places |', '|---|---|---|---:|---:|');
+    for (const x of rep.summary.markings) L.push(`| ${x.severity} | \`${x.rule}\` | ${x.preview.replace(/\|/g, '\\|')} | ${x.sessions} | ${x.occurrences} |`);
+    L.push('', MARKING_ADVICE, '');
+  }
+  L.push('## Where, file by file', '');
   const byFile = new Map(); for (const f of rep.findings) { if (!byFile.has(f.file)) byFile.set(f.file, []); byFile.get(f.file).push(f); }
   for (const [file, list] of byFile) {
     L.push(`### ${file}`, '', list[0].store ? `${STORE_WORDS[list[0].store] || list[0].store}${list[0].session ? ` · session \`${list[0].session}\`` : ''}` : `session \`${list[0].session}\`${list[0].project ? ` · project ${list[0].project}` : ''}`, '', '| rule | severity | line | preview | where |', '|---|---|---:|---|---|');

package/src/guard.mjs

@@ -5,8 +5,8 @@
 //  - only failures count (denied-by-the-human and interrupted calls don't; they have their own flow);
 //  - the chain is broken by anything that could have changed the outcome: an edit, another command,
 //    any non-read call, a success, or a new human prompt. Re-running tests after a fix is never blocked;
-//  - calls are compared on what they do, not how they're labelled: Bash/PowerShell `description`,
-//    `timeout` and `run_in_background` are ignored, because the agent often rewords them on a retry.
+//  - calls are compared on what they do, not how they're labelled: a Bash/PowerShell `description` is ignored,
+//    because the agent often rewords it on a retry; a changed `timeout` or `run_in_background` is a change.
 // It never approves anything: when it has nothing to say it prints nothing, which leaves Claude Code's
 // normal permission flow in charge ("allow" would skip the user's permission prompts).
 import fs from 'node:fs';
@@ -15,7 +15,9 @@ const require = createRequire(import.meta.url);
 const core = require('./trace-core.js');
 
 export const GUARD_DEFAULTS = { maxFailures: 2, tailBytes: 4 * 1048576 };
-const IGNORED_KEYS = new Set(['description', 'timeout', 'run_in_background']);
+// Only the label. A longer timeout or a background run after a timeout is a real change (0.12 review: the guard is
+// on by default in the plugin now, so a false block costs more than a missed loop).
+const IGNORED_KEYS = new Set(['description']);
 
 export function guardKey(name, input) {
   const i = {};

package/src/jsonl.mjs

@@ -0,0 +1,104 @@
+// Reading transcripts of any size. V8 caps a string at buffer.constants.MAX_STRING_LENGTH (536,870,888 characters
+// on Node 22), so readFileSync(file, 'utf8') throws ERR_STRING_TOO_LONG on a transcript past ~512 MB before a single
+// line is parsed — an outside review found a 1.26 GB session that broke `check` outright. Files at or under
+// streamBytes() are read exactly as before; bigger ones line by line, keeping the parsed record and dropping the
+// line string at once. Synchronous on purpose: the callers (check, the Stop hook, fence) are synchronous.
+// DESIGN.md §21.
+import fs from 'node:fs';
+import { constants } from 'node:buffer';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const core = require('./trace-core.js');
+
+export const STREAM_BYTES = 64 * 1048576;
+export const CHUNK_BYTES = 8 * 1048576;
+export function streamBytes() { const n = Number(process.env.GLASSBOX_STREAM_BYTES); return Number.isFinite(n) && n > 0 ? n : STREAM_BYTES; }
+
+// fn(line, n) for every line, 1-based, CRLF and a leading BOM removed — the lines text.split(/\r?\n/) would give.
+// A line longer than maxLine bytes is never decoded: fn(null, n, bytes). Lines are cut on the 0x0A byte, which
+// never occurs inside a UTF-8 multi-byte sequence, so a character split across two chunks is never split here.
+export function forEachLine(file, fn, opts = {}) {
+  const chunkBytes = opts.chunkBytes || CHUNK_BYTES;
+  const maxLine = opts.maxLine || constants.MAX_STRING_LENGTH;
+  const fd = fs.openSync(file, 'r');
+  const buf = Buffer.allocUnsafe(chunkBytes);
+  let parts = [], partBytes = 0, n = 0, first = true, tooLong = false;
+  const emit = (line) => {
+    n++;
+    if (tooLong || line.length > maxLine) { fn(null, n, tooLong ? partBytes : line.length); return; }
+    let s = line.toString('utf8');
+    if (first && s.charCodeAt(0) === 0xfeff) s = s.slice(1);
+    if (s.charCodeAt(s.length - 1) === 13) s = s.slice(0, -1);
+    fn(s, n);
+  };
+  try {
+    for (;;) {
+      const got = fs.readSync(fd, buf, 0, chunkBytes, null);
+      if (!got) break;
+      let at = 0;
+      for (;;) {
+        const nl = buf.indexOf(10, at);
+        if (nl < 0 || nl >= got) {
+          if (at < got) { partBytes += got - at; if (partBytes > maxLine) { tooLong = true; parts = []; } else parts.push(Buffer.from(buf.subarray(at, got))); }
+          break;
+        }
+        const piece = buf.subarray(at, nl);
+        const line = parts.length ? Buffer.concat([...parts, piece]) : piece;
+        if (tooLong) partBytes += piece.length;
+        emit(line); first = false;
+        parts = []; partBytes = 0; tooLong = false; at = nl + 1;
+      }
+    }
+    // The last line when the file doesn't end in \n. (After a final \n, split() would add an empty line; it is blank,
+    // so no caller sees it either way.)
+    if (parts.length || tooLong) emit(parts.length ? Buffer.concat(parts) : Buffer.alloc(0));
+  } finally { fs.closeSync(fd); }
+  return n;
+}
+
+// The records of one transcript file, as core.parseLines would give them from its text.
+export const SLIM_LINE = 262144;
+export function readRecords(file, name, opts = {}) {
+  const records = [], problems = [];
+  const slim = opts.slim !== false, keep = opts.keep || 32768;
+  const bytes = fs.statSync(file).size;
+  forEachLine(file, (line, n, len) => {
+    if (line == null) { problems.push({ file: name, line: n, reason: `line too long (${len} bytes); skipped` }); return; }
+    const t = line.trim(); if (!t) return;
+    try {
+      const r = JSON.parse(t);
+      // A long line's huge strings become head + marker + tail (core.charsOf still gives their size): holding every
+      // multi-MB tool result of a 1 GB session at once would run Node out of heap after the string limit was solved.
+      // The JSON round trip matters as much as the cut: V8's JSON.parse and slice() can hand back strings that point
+      // into the source, so even a uuid kept from a 4 MB line would keep the whole line alive. A copy owns its text.
+      if (r && typeof r === 'object') records.push(core.normaliseLoose(slim && t.length > SLIM_LINE ? JSON.parse(JSON.stringify(core.slimRecord(r, keep))) : r, n, name));
+      else problems.push({ file: name, line: n, reason: 'not an object' });
+    } catch (e) { problems.push({ file: name, line: n, reason: 'bad JSON: ' + String(e.message).slice(0, 80) }); }
+  }, opts);
+  return { name, records, problems, bytes };
+}
+
+// One file for parseTrace: { name, text } as before, or { name, records, problems, bytes } past the threshold.
+// A whole-file JSON array or a .meta.json is always text (they can't be read line by line; a JSON array past the
+// string limit is reported, not thrown).
+export function readTranscript(file, name, opts = {}) {
+  const size = fs.statSync(file).size;
+  if (size <= (opts.streamBytes || streamBytes()) || /\.meta\.json$/.test(name)) return { name, text: fs.readFileSync(file, 'utf8') };
+  // The first non-blank character decides; read until there is one (a JSON array can follow a long run of blanks).
+  const fd = fs.openSync(file, 'r'); const head = Buffer.alloc(65536); let first = '';
+  try { for (let pos = 0; ;) { const got = fs.readSync(fd, head, 0, head.length, pos); if (!got) break; const t = head.subarray(0, got).toString('latin1').replace(/^\xef\xbb\xbf/, '').replace(/^\s+/, ''); if (t) { first = t[0]; break; } pos += got; } } finally { fs.closeSync(fd); }
+  if (first === '[') {
+    if (size < constants.MAX_STRING_LENGTH / 2) return { name, text: fs.readFileSync(file, 'utf8') };
+    return { name, records: [], problems: [{ file: name, line: 0, reason: `a JSON array of ${size} bytes is too large to read; convert it to JSONL (one record per line)` }], bytes: size };
+  }
+  return readRecords(file, name, opts);
+}
+
+// Does the file contain `needle` (already lowercased)? Line by line, so it works on any size.
+export function fileIncludes(file, needle) {
+  if (fs.statSync(file).size <= streamBytes()) return fs.readFileSync(file, 'utf8').toLowerCase().includes(needle);
+  let hit = false;
+  try { forEachLine(file, (line) => { if (!hit && line && line.toLowerCase().includes(needle)) { hit = true; throw STOP; } }); } catch (e) { if (e !== STOP) throw e; }
+  return hit;
+}
+const STOP = Symbol('stop');

package/src/managed-paths.mjs

@@ -0,0 +1,32 @@
+// Where Claude Code's managed settings live, and which hook commands they already run. Kept apart from managed.mjs
+// (which imports the CLI) so the plugin's PreToolUse guard can ask "is Glassbox already installed for every user?"
+// without loading anything heavy. Claude Code reads managed-settings.json, then managed-settings.d/*.json by name.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function managedDir(platform = process.platform, env = process.env) {
+  if (env.GLASSBOX_MANAGED_DIR) return env.GLASSBOX_MANAGED_DIR;
+  return platform === 'win32' ? 'C:\\Program Files\\ClaudeCode' : platform === 'darwin' ? '/Library/Application Support/ClaudeCode' : '/etc/claude-code';
+}
+export const dropInFile = (dir) => path.join(dir || managedDir(), 'managed-settings.d', 'glassbox.json');
+
+export function managedFiles(dir = managedDir()) {
+  const out = [path.join(dir, 'managed-settings.json')];
+  try { for (const n of fs.readdirSync(path.join(dir, 'managed-settings.d')).filter((x) => /\.json$/i.test(x)).sort()) out.push(path.join(dir, 'managed-settings.d', n)); } catch (e) { }
+  return out.filter((f) => { try { return fs.statSync(f).isFile(); } catch (e) { return false; } });
+}
+
+// Every hook command in the managed settings (and in any extra settings files given), for the events asked.
+export function hookCommands(files, events) {
+  const out = [];
+  for (const f of files) {
+    let j; try { j = JSON.parse(fs.readFileSync(f, 'utf8').replace(/^\ufeff/, '')); } catch (e) { continue; }
+    const hooks = (j && j.hooks) || {};
+    for (const [ev, list] of Object.entries(hooks)) {
+      if (events && !events.includes(ev)) continue;
+      if (!Array.isArray(list)) continue;
+      for (const entry of list) for (const h of (entry && Array.isArray(entry.hooks) ? entry.hooks : [])) if (h && typeof h.command === 'string') out.push(h.command);
+    }
+  }
+  return out;
+}

package/src/managed.mjs

@@ -0,0 +1,76 @@
+// glassbox managed — Glassbox for every user on a machine, through Claude Code's managed settings, and the
+// temp-folder policy that goes with it.
+//
+// Claude Code reads managed settings from a fixed folder per OS (C:\Program Files\ClaudeCode,
+// /Library/Application Support/ClaudeCode, /etc/claude-code): managed-settings.json, plus every *.json in
+// managed-settings.d/ beside it (2.1.278). Glassbox writes its own drop-in, managed-settings.d/glassbox.json,
+// and never edits the organisation's managed-settings.json. Writing there needs an administrator; printing the
+// fragment doesn't (DESIGN.md §24). Nothing leaves the machine.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { hookEntries } from './cli.mjs';
+import { readTextFile } from './textfile.mjs';
+
+import { managedDir, dropInFile } from './managed-paths.mjs';
+export { managedDir, dropInFile };
+
+// ---------------------------------------------------------------------------
+// The temp-folder policy: what `open` may write to the temp folder without --out.
+//   allow  (default) the full transcript, as before
+//   redact every prompt, tool input, result and assistant text blanked first («N chars»)
+//   deny   nothing: `open` needs --out, a place the user chose
+// From GLASSBOX_TEMP, else from `env.GLASSBOX_TEMP` in the managed settings (where IT already sets Claude Code's
+// env for every user), else allow.
+// ---------------------------------------------------------------------------
+export const TEMP_POLICIES = ['allow', 'redact', 'deny'];
+export function readManagedEnv(dir) {
+  dir = dir || managedDir();
+  const files = [path.join(dir, 'managed-settings.json')];
+  const d = path.join(dir, 'managed-settings.d');
+  try { for (const f of fs.readdirSync(d).filter((f) => f.endsWith('.json')).sort()) files.push(path.join(d, f)); } catch (e) { }
+  const env = {};
+  for (const f of files) { try { const j = JSON.parse(readTextFile(f)); if (j && j.env && typeof j.env === 'object') Object.assign(env, j.env); } catch (e) { } }
+  return env;
+}
+export function tempPolicy(env = process.env, dir) {
+  const v = env.GLASSBOX_TEMP != null ? env.GLASSBOX_TEMP : readManagedEnv(dir).GLASSBOX_TEMP;
+  const p = String(v == null ? 'allow' : v).toLowerCase();
+  if (!TEMP_POLICIES.includes(p)) throw new Error(`GLASSBOX_TEMP must be allow, redact or deny (got "${v}")`);
+  return { policy: p, from: env.GLASSBOX_TEMP != null ? 'GLASSBOX_TEMP' : v != null ? 'managed settings' : 'default' };
+}
+
+// ---------------------------------------------------------------------------
+// The drop-in
+// ---------------------------------------------------------------------------
+// opts: { command, hook, feedback, context, guard, failOn, statusline, noColor, temp }
+export function managedFragment(opts = {}) {
+  if (!opts.hook && !opts.statusline && !opts.temp) throw new Error('managed needs at least one of --hook, --statusline or --temp allow|redact|deny');
+  if (opts.temp && !TEMP_POLICIES.includes(opts.temp)) throw new Error(`--temp must be allow, redact or deny (got "${opts.temp}")`);
+  const out = {};
+  if (opts.hook) { const h = hookEntries({ command: opts.command, feedback: opts.feedback, context: opts.context, memory: opts.memory, guard: opts.guard, failOn: opts.failOn }); out.hooks = {}; for (const ev of h.events) out.hooks[ev] = [h.entries[ev]]; }
+  if (opts.statusline) out.statusLine = { type: 'command', command: `${opts.command} statusline${opts.noColor ? ' --no-color' : ''}`, padding: 0 };
+  if (opts.temp) out.env = { GLASSBOX_TEMP: opts.temp };
+  return out;
+}
+
+// A path under one user's profile can't be run by the machine's other users, and managed settings apply to all.
+export function userScoped(command, home = os.homedir()) {
+  const norm = (s) => String(s).replace(/\\/g, '/').toLowerCase();
+  return !!home && norm(command).includes(norm(home));
+}
+
+export function writeDropIn(fragment, opts = {}) {
+  const file = opts.file || dropInFile(opts.dir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (fs.existsSync(file)) fs.copyFileSync(file, file + '.glassbox-backup');
+  // No comment key: Claude Code validates settings files, and the file's name already says whose it is.
+  fs.writeFileSync(file, JSON.stringify(fragment, null, 2) + '\n');
+  return { file };
+}
+export function removeDropIn(opts = {}) {
+  const file = opts.file || dropInFile(opts.dir);
+  if (!fs.existsSync(file)) return { file, removed: false };
+  fs.unlinkSync(file);
+  return { file, removed: true };
+}

package/src/memory-audit.mjs

@@ -115,6 +115,18 @@ function gitRoot(dir) {
 }
 function settingsOf(home) { try { return JSON.parse(readTextFile(path.join(home, 'settings.json'))) || {}; } catch (e) { return {}; } }
 
+// The project's auto memory folder, as Claude Code resolves it: settings.autoMemoryDirectory (with ~), else
+// <claude home>/projects/<git root, encoded>/memory. dir is null when no such folder exists; enabled is false when
+// settings.autoMemoryEnabled is false. Shared by the audit and by the Stop hook's lessons block (0.12).
+export function autoMemoryDir(opts = {}) {
+  const project = path.resolve(opts.project || process.cwd());
+  const home = opts.home || claudeHome();
+  const userHome = opts.userHome || os.homedir();
+  const settings = settingsOf(home);
+  const dirs = opts.dir ? [opts.dir] : settings.autoMemoryDirectory ? [String(settings.autoMemoryDirectory).replace(/^~(?=\/|\\|$)/, userHome)] : encodings(gitRoot(project) || project).map((e) => path.join(home, 'projects', e, 'memory'));
+  return { dir: dirs.find(isDir) || null, enabled: settings.autoMemoryEnabled !== false };
+}
+
 export function auditMemory(opts = {}) {
   const project = path.resolve(opts.project || process.cwd());
   const home = opts.home || claudeHome();
@@ -158,10 +170,8 @@ export function auditMemory(opts = {}) {
     }
   }
   // 3. Auto memory: the first 200 lines or 25 KB of MEMORY.md at launch; topic files when Claude reads them.
-  const settings = settingsOf(home);
-  const autoOff = settings.autoMemoryEnabled === false;
-  const memDirs = opts.autoMemoryDir ? [opts.autoMemoryDir] : settings.autoMemoryDirectory ? [String(settings.autoMemoryDirectory).replace(/^~(?=\/|\\|$)/, userHome)] : encodings(gitRoot(project) || project).map((e) => path.join(home, 'projects', e, 'memory'));
-  const memDir = memDirs.find(isDir);
+  const { dir: memDir, enabled } = autoMemoryDir({ project, home, userHome, dir: opts.autoMemoryDir });
+  const autoOff = !enabled;
   if (memDir && !autoOff) {
     const cut = (t) => { let out = t.split(/\r?\n/).slice(0, L.memoryLines).join('\n'); if (Buffer.byteLength(out) > L.memoryBytes) out = Buffer.from(out).subarray(0, L.memoryBytes).toString('utf8'); return out; };
     const idx = add(path.join(memDir, 'MEMORY.md'), 'auto-memory', 'auto memory index (first 200 lines / 25 KB)', { limitTo: cut });