@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/context/summary-store.js

@@ -0,0 +1,655 @@
+'use strict';
+
+// Scoped compact summaries and grants (078 IC-010, IC-012, IC-013 in process; DEC-002, DEC-012).
+// Run directly by Node native type-stripping.
+//
+// The TypeScript twin of `policies/summary-store.sh`: the same layout, record format, rename
+// claims, 65536-byte bounded reads and grant-fits rule, so a summary written by either side is
+// claimed by the other. Layout under stateDir() (`<config home>/doflow/session-env`; with no config home
+// there is no store and every read finds nothing):
+//   summaries/<worktreeKey>/<run>/<lineage>/summary.md            one pending summary per scope
+//   summaries/<worktreeKey>/<run>/<lineage>/.summary.XXXXXX       write temporary
+//   summaries/<worktreeKey>/<run>/<lineage>/.claimed.<unitId>     claim temporary
+//   grants/<run>/<lineage>/<summaryId>.md                         grant addressed to a recipient
+//   grants/<run>/<lineage>/.grant.XXXXXX                          grant write temporary
+//   grants/<run>/<lineage>/.claimed.<unitId>.<summaryId>          claim temporary
+// Records are read as bytes (latin1 strings, one character per byte), as the bash store does under
+// LC_ALL=C, so byte counts match it on any input, valid UTF-8 or not.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { ID_PATTERN, cwdHash, stateDir } = require('./identity.js');
+
+                                              
+
+const SUMMARY_ID_PATTERN = /^s-[0-9]{8}T[0-9]{6}Z-[A-Za-z0-9]{6}$/;
+/** A unit id (L.<run>.<lineage>.<attempt> or a harness session id) is one path segment. */
+const UNIT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const MAX_BYTES_PATTERN = /^[1-9][0-9]{0,9}$/;
+const READ_BOUND = 65536;
+const DEFAULT_GRANT_MAX_BYTES = 16384;
+const SUFFIX_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+/** IC-013 exits: not found, legacy or already granted 1, usage 2, over budget 3. */
+const GRANT_EXIT = {
+  'summary-not-found': 1,
+  'summary-legacy': 1,
+  'grant-exists': 1,
+  usage: 2,
+  'over-budget': 3,
+}         ;
+                                              
+
+class SummaryStoreError extends Error {
+  code                ;
+  exitCode        ;
+  constructor(code                , message        ) {
+    super(message);
+    this.name = 'SummaryStoreError';
+    this.code = code;
+    this.exitCode = GRANT_EXIT[code];
+  }
+}
+
+function idOk(value                    )                  {
+  return typeof value === 'string' && ID_PATTERN.test(value);
+}
+
+function regularFile(file        )          {
+  try {
+    return fs.lstatSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** The file's first `limit` bytes (all of it when limit is omitted) as a latin1 string, or null. */
+function readBytes(file        , limit         )                {
+  try {
+    if (limit === undefined) return fs.readFileSync(file).toString('latin1');
+    const fd = fs.openSync(file, 'r');
+    try {
+      const buffer = Buffer.alloc(limit);
+      let length = 0;
+      while (length < limit) {
+        const n = fs.readSync(fd, buffer, length, limit - length, null);
+        if (n === 0) break;
+        length += n;
+      }
+      return buffer.subarray(0, length).toString('latin1');
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+
+function fileSize(file        )                {
+  try {
+    return fs.statSync(file).size;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * emission.jq's parse_record over a byte string: `\r` removed, trailing newlines dropped, fields
+ * from the lines between the first two `---` lines (first match wins, leading spaces of a value
+ * dropped), body from the first non-empty line after the second `---`, trailing newlines dropped.
+ */
+function parseRecord(raw        )                                                   {
+  const lines = raw.replace(/\r/g, '').replace(/\n+$/, '').split('\n');
+  const fields                         = Object.create(null);
+  const body           = [];
+  let fences = 0;
+  let started = false;
+  for (const line of lines) {
+    if (fences < 2 && line === '---') { fences += 1; continue; }
+    if (fences === 1) {
+      const colon = line.indexOf(':');
+      if (colon > 0) {
+        const key = line.slice(0, colon);
+        if (!(key in fields)) fields[key] = line.slice(colon + 1).replace(/^ */, '');
+      }
+    } else if (fences >= 2 && (started || line !== '')) {
+      started = true;
+      body.push(line);
+    }
+  }
+  return { fields, body: body.join('\n').replace(/\n+$/, '') };
+}
+
+/** The frontmatter fields of a record from its first 65536 bytes (the bash store's bounded head read). */
+function readHead(file        )                         {
+  const raw = readBytes(file, READ_BOUND);
+  return raw === null ? Object.create(null) : parseRecord(raw).fields;
+}
+
+/** emission.jq's `known`: `]` removed, then empty when it is "unknown". */
+function known(value                    )         {
+  const v = (value ?? '').replace(/\]/g, '');
+  return v === 'unknown' ? '' : v;
+}
+
+/** render_grant's header line, `]` included, over byte strings. */
+function grantHeader(fromLineage                    , compactedAt                    , branch                    )         {
+  const at = known(compactedAt);
+  const br = known(branch);
+  return `[Granted summary from lineage ${fromLineage ?? ''}${at ? `, compacted ${at}` : ''}${br ? ` on branch ${br}` : ''}]`;
+}
+
+/** A frontmatter value is one line: an embedded line break would forge a key. */
+function oneLine(value        )         {
+  return value.replace(/[\r\n]/g, ' ');
+}
+
+function utf8(value        )         {
+  return Buffer.from(value, 'latin1').toString('utf8');
+}
+
+/** `mktemp <dir>/<prefix>XXXXXX`: an exclusively created 0600 file with a six-character suffix. */
+function makeTemp(dir        , prefix        )                                   {
+  for (let tries = 0; tries < 100; tries++) {
+    const bytes = crypto.randomBytes(6);
+    let suffix = '';
+    for (const b of bytes) suffix += SUFFIX_CHARS[b % SUFFIX_CHARS.length];
+    const file = path.join(dir, `${prefix}${suffix}`);
+    try {
+      fs.closeSync(fs.openSync(file, 'wx', 0o600));
+      return { file, suffix };
+    } catch (error     ) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+  }
+  throw new Error(`cannot create a temporary file in ${dir}`);
+}
+
+function removeQuietly(file        )       {
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+    // Best effort, as `rm -f ... || true`.
+  }
+}
+
+/**
+ * `doflow_summary_scope`: summaries/<worktreeKey>/<run>/<lineage> under stateDir(), or null when run
+ * or lineage is not an id, the lineage is `solo` (no scope directory), the worktree is empty or there
+ * is no config home.
+ */
+function summaryScope(worktree        , run        , lineage        , env      = process.env)                {
+  if (!idOk(run) || !idOk(lineage) || lineage === 'solo' || !worktree) return null;
+  const root = stateDir(env);
+  return root === null ? null : path.join(root, 'summaries', cwdHash(worktree), run, lineage);
+}
+
+                                                   
+
+/**
+ * `doflow_summary_peek` (IC-012 owner steps 1 and 2): `none` when the scope holds no regular,
+ * non-symlink summary.md, `own-write` when its frontmatter session_id is this session's, else
+ * `pending`; file is its path when not `none`.
+ */
+function peekSummary(worktree        , run        , lineage        , sessionId        , env      = process.env)                                                                 {
+  const scope = summaryScope(worktree, run, lineage, env);
+  if (scope === null) return { own: 'none', file: null, scope: null };
+  const file = path.join(scope, 'summary.md');
+  if (!regularFile(file)) return { own: 'none', file: null, scope };
+  const session = readHead(file).session_id ?? '';
+  const own             = sessionId && utf8(session) === sessionId ? 'own-write' : 'pending';
+  return { own, file, scope };
+}
+
+/**
+ * `doflow_summary_claim` (IC-012 owner steps 1 to 3): peek, then rename summary.md to
+ * `.claimed.<unitId>`; a summary written after the rename is a new summary.md and survives. The
+ * claimed copy is cut to its first 65536 bytes. claimed is set only when this caller claimed it;
+ * bytes is the claimed file's full size before the cut; origin is the summary.md it came from. The
+ * caller removes the claimed file, or gives it back with releaseClaim().
+ */
+function claimSummary(worktree        , run        , lineage        , unitId        , sessionId        , env      = process.env)                                                                              {
+  const peek = peekSummary(worktree, run, lineage, sessionId, env);
+  if (peek.own !== 'pending' || peek.file === null || peek.scope === null) return { own: peek.own, claimed: null, bytes: 0 };
+  if (!UNIT_PATTERN.test(unitId)) return { own: peek.own, claimed: null, bytes: 0 };
+  const claimed = path.join(peek.scope, `.claimed.${unitId}`);
+  try {
+    fs.renameSync(peek.file, claimed);
+  } catch {
+    return { own: 'none', claimed: null, bytes: 0 };
+  }
+  const bytes = fileSize(claimed) ?? 0;
+  if (bytes > READ_BOUND) {
+    try {
+      fs.truncateSync(claimed, READ_BOUND);
+    } catch {
+      removeQuietly(claimed);
+      return { own: peek.own, claimed: null, bytes };
+    }
+  }
+  return { own: peek.own, claimed, bytes, origin: peek.file };
+}
+
+                                           
+
+                     
+                    
+                      
+                    
+                                                                                                      
+                       
+ 
+
+/**
+ * `doflow_grant_peek` (IC-012 grant steps 1 and 2): the oldest grants/<run>/<lineage>/<summaryId>.md
+ * by name among regular, non-symlink files whose name matches the summary id pattern. It fits
+ * exactly when the UTF-8 bytes of render_grant's segment "<header>\n<body>" are at most maxBytes.
+ */
+function peekGrant(run        , lineage        , maxBytes                 , env      = process.env)            {
+  const none            = { grant: 'none', file: null, id: null, bytes: null };
+  if (!idOk(run) || !idOk(lineage)) return none;
+  const max = String(maxBytes);
+  if (!MAX_BYTES_PATTERN.test(max)) return none;
+  const root = stateDir(env);
+  if (root === null) return none;
+  const dir = path.join(root, 'grants', run, lineage);
+  let names          ;
+  try {
+    if (!fs.lstatSync(dir).isDirectory()) return none;
+    names = fs.readdirSync(dir);
+  } catch {
+    return none;
+  }
+  // The glob `s-*.md` in C collation: byte order, which for these ASCII names is code-unit order.
+  const candidates = names.filter((n) => n.startsWith('s-') && n.endsWith('.md')).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  let file                = null;
+  let id                = null;
+  for (const name of candidates) {
+    const stem = name.slice(0, -3);
+    if (!SUMMARY_ID_PATTERN.test(stem)) continue;
+    const f = path.join(dir, name);
+    if (!regularFile(f)) continue;
+    file = f;
+    id = stem;
+    break;
+  }
+  if (file === null) return none;
+  const size = fileSize(file);
+  // A frontmatter needs far less than 65536 bytes: anything larger than that plus the budget is over.
+  if (size === null || size > Number(max) + READ_BOUND) return { grant: 'over', file, id, bytes: null };
+  const raw = readBytes(file);
+  if (raw === null) return { grant: 'over', file, id, bytes: null };
+  const bytes = parseRecord(raw).body.length;
+  const head = readHead(file);
+  const header = grantHeader(head.from_lineage, head.compacted_at, head.branch);
+  return { grant: header.length + 1 + bytes <= Number(max) ? 'fits' : 'over', file, id, bytes };
+}
+
+/**
+ * `doflow_grant_claim` (IC-012 grant step 3) for one grant the caller already peeked and fitted
+ * (DEC-034): rename exactly grants/<run>/<lineage>/<summaryId>.md to
+ * `.claimed.<unitId>.<summaryId>`. A grant that vanished, is no longer a regular file, or a bad id
+ * is `none` with claimed null; no other grant is ever taken in its place. The caller removes the
+ * claimed file after rendering, or puts it back with releaseClaim().
+ */
+function claimGrant(run        , lineage        , unitId        , summaryId        , env      = process.env)                                                                                          {
+  const none = { grant: 'none'              , id: null, claimed: null, origin: null };
+  if (!idOk(run) || !idOk(lineage) || !UNIT_PATTERN.test(unitId) || !SUMMARY_ID_PATTERN.test(summaryId)) return none;
+  const root = stateDir(env);
+  if (root === null) return none;
+  const origin = path.join(root, 'grants', run, lineage, `${summaryId}.md`);
+  if (!regularFile(origin)) return none;
+  const claimed = path.join(path.dirname(origin), `.claimed.${unitId}.${summaryId}`);
+  try {
+    fs.renameSync(origin, claimed);
+  } catch {
+    return none;
+  }
+  return { grant: 'fits', id: summaryId, claimed, origin };
+}
+
+/**
+ * Give a claimed summary or grant back to the name it was claimed from (DEC-038), never replacing
+ * a file that appeared there since: a hard link that refuses to replace, then an unlink of the
+ * claimed name. True when the content is back under `origin`. Without hard links, or when a newer
+ * file holds the name, the claimed file is left where it is.
+ */
+function releaseClaim(claimed        , origin        )          {
+  try {
+    fs.linkSync(claimed, origin);
+  } catch {
+    return false;
+  }
+  removeQuietly(claimed);
+  return true;
+}
+
+// ── IC-014: the pre-078 project summary (DEC-043) ───────────────────────────────────────────────
+
+/**
+ * The pre-078 project summary under projects/<cwdHash cwd>/ when it exists as a regular file and
+ * not a symlink, else null. This and adoptLegacy() are the TypeScript side's only use of the name.
+ */
+function legacySummary(cwd        , env      = process.env)                {
+  const root = stateDir(env);
+  if (!cwd || root === null) return null;
+  const old = path.join(root, 'projects', cwdHash(cwd), 'last-compact-summary.md');
+  return regularFile(old) ? old : null;
+}
+
+/**
+ * `doflow_summary_adopt_legacy` (IC-014, action `adopt` only): move the legacy summary once into
+ * summaries/<worktreeKey>/local/main/summary.md, frontmatter kept. The legacy file is first claimed
+ * by a rename to `.adopting.<pid>`, so of two concurrent adopters exactly one proceeds; the loser
+ * returns false and changes nothing. The claimed file is then hard-linked to summary.md, which
+ * refuses to replace: a summary already pending there is newer by construction and the legacy copy
+ * is retired instead. Only when the link fails with summary.md absent (no hard links on this
+ * filesystem) is it renamed into place after a re-check; that fallback is check-then-rename and so
+ * can replace a summary written in the same instant (the ceiling it accepts). The `.adopting` name
+ * is unlinked last. True when this call adopted or retired the legacy file.
+ */
+function adoptLegacy(cwd        , worktree        , env      = process.env)          {
+  const old = legacySummary(cwd, env);
+  if (old === null) return false;
+  const scope = summaryScope(worktree || cwd, 'local', 'main', env);
+  if (scope === null) return false;
+  try {
+    fs.mkdirSync(scope, { recursive: true });
+  } catch {
+    return false;
+  }
+  const adopting = `${old}.adopting.${process.pid}`;
+  try {
+    fs.renameSync(old, adopting);
+  } catch {
+    return false;
+  }
+  const target = path.join(scope, 'summary.md');
+  try {
+    fs.linkSync(adopting, target);
+  } catch {
+    if (!present(target)) {
+      try {
+        fs.renameSync(adopting, target);
+        return true;
+      } catch {
+        // Neither a link nor a rename: the file is left under its .adopting name for a later
+        // cleanup; the retired legacy path is never written again (G38.4).
+        return false;
+      }
+    }
+  }
+  removeQuietly(adopting);
+  return true;
+}
+
+function present(file        )          {
+  try {
+    fs.lstatSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+                        
+                                                                              
+                  
+                
+                    
+                                                             
+                        
+                                             
+                   
+                                                
+                       
+                                                              
+                             
+            
+             
+ 
+
+/**
+ * IC-013 in process: copy one summary's body into grants/<toRun>/<toLineage>/<summaryId>.md,
+ * written atomically and refusing when that file exists; the owner's summary is untouched. Every
+ * refusal happens before any write and throws a SummaryStoreError whose exitCode is the verb's exit.
+ */
+function grantSummary(options              )                                                     {
+  const env = options.env ?? process.env;
+  const fromWorktree = options.fromWorktree ?? (env.DOFLOW_WORKTREE || process.cwd());
+  const fromRun = options.fromRun ?? (env.DOFLOW_RUN_ID || 'local');
+  const fromLineage = options.fromLineage ?? (env.DOFLOW_LINEAGE_ID || 'main');
+  const max = String(options.maxBytes ?? DEFAULT_GRANT_MAX_BYTES);
+  const wanted = options.summary;
+
+  if (typeof wanted !== 'string' || (wanted !== 'pending' && !SUMMARY_ID_PATTERN.test(wanted))) {
+    throw new SummaryStoreError('usage', '--summary must be `pending` or a summary id');
+  }
+  if (!idOk(options.toRun) || !idOk(options.toLineage)) throw new SummaryStoreError('usage', '--to-run and --to-lineage must be ids');
+  // DEC-039: grants are read only by launched identities, so a recipient no launched unit can be
+  // (lineage solo, or the default main scope local/main) would reach unrelated sessions instead.
+  if (options.toLineage === 'solo') throw new SummaryStoreError('usage', '--to-lineage solo is not a launched recipient');
+  if (options.toRun === 'local' && options.toLineage === 'main') {
+    throw new SummaryStoreError('usage', '--to-run local --to-lineage main is the default main scope, not a launched recipient');
+  }
+  if (!MAX_BYTES_PATTERN.test(max)) throw new SummaryStoreError('usage', '--max-bytes must be a positive integer');
+  const root = stateDir(env);
+  if (root === null) throw new SummaryStoreError('usage', 'no config home resolves (set HOME or an absolute XDG_CONFIG_HOME), so there is no session store to grant into');
+  const scope = summaryScope(fromWorktree, fromRun, fromLineage, env);
+  if (scope === null) throw new SummaryStoreError('usage', 'the source scope needs a worktree, a run id and a non-solo lineage id');
+
+  const source = path.join(scope, 'summary.md');
+  if (!regularFile(source)) throw new SummaryStoreError('summary-not-found', `no pending summary in ${scope}`);
+  const head = readHead(source);
+  const summaryId = head.summary_id;
+  if (summaryId === undefined || !SUMMARY_ID_PATTERN.test(summaryId)) {
+    throw new SummaryStoreError('summary-legacy', 'the pending summary has no summary_id and cannot be granted');
+  }
+  if (wanted !== 'pending' && wanted !== summaryId) throw new SummaryStoreError('summary-not-found', `summary ${wanted} is not pending in ${scope}`);
+
+  // Byte strings throughout, so the header counted here is the one peekGrant() counts on the copy.
+  const compactedAt = head.compacted_at ?? 'unknown';
+  const branch = head.branch ?? 'unknown';
+  const header = grantHeader(fromLineage, compactedAt, branch);
+  const size = fileSize(source);
+  const raw = size === null || size > Number(max) + READ_BOUND ? null : readBytes(source);
+  const body = raw === null ? null : parseRecord(raw).body;
+  if (body === '') throw new SummaryStoreError('summary-not-found', 'the pending summary has an empty body');
+  if (body === null || header.length + 1 + body.length > Number(max)) {
+    throw new SummaryStoreError('over-budget', `the granted summary exceeds the ${max}-byte budget`);
+  }
+
+  const dir = path.join(root, 'grants', options.toRun, options.toLineage);
+  const target = path.join(dir, `${summaryId}.md`);
+  if (fs.existsSync(target) || isLink(target)) throw new SummaryStoreError('grant-exists', `grant ${summaryId} already present for ${options.toRun}/${options.toLineage}`);
+
+  const grantedAt = (options.now ?? new Date()).toISOString().replace(/\.[0-9]{3}Z$/, 'Z');
+  const record = '---\n'
+    + `summary_id: ${summaryId}\n`
+    + `granted_at: ${grantedAt}\n`
+    + `from_worktree: ${Buffer.from(oneLine(fromWorktree), 'utf8').toString('latin1')}\n`
+    + `from_run: ${fromRun}\n`
+    + `from_lineage: ${fromLineage}\n`
+    + `to_run: ${options.toRun}\n`
+    + `to_lineage: ${options.toLineage}\n`
+    + `compacted_at: ${compactedAt}\n`
+    + `branch: ${branch}\n`
+    + `bytes: ${body.length}\n`
+    + '---\n\n'
+    + `${body}\n`;
+  fs.mkdirSync(dir, { recursive: true });
+  const { file: tmp } = makeTemp(dir, '.grant.');
+  try {
+    fs.writeFileSync(tmp, Buffer.from(record, 'latin1'));
+    publishNoReplace(tmp, target, summaryId, options.toRun, options.toLineage);
+  } finally {
+    removeQuietly(tmp);
+  }
+  return { summaryId, path: target, bytes: body.length };
+}
+
+function isLink(file        )          {
+  try {
+    return fs.lstatSync(file).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** A hard link refuses to replace an existing grant; without hard links, re-check and rename. */
+function publishNoReplace(tmp        , target        , summaryId        , toRun        , toLineage        )       {
+  try {
+    fs.linkSync(tmp, target);
+    return;
+  } catch (error     ) {
+    if (error?.code === 'EEXIST') throw new SummaryStoreError('grant-exists', `grant ${summaryId} already present for ${toRun}/${toLineage}`);
+  }
+  if (fs.existsSync(target) || isLink(target)) throw new SummaryStoreError('grant-exists', `grant ${summaryId} already present for ${toRun}/${toLineage}`);
+  fs.renameSync(tmp, target);
+}
+
+// ── 080 IC-014: the run scope's persisted context, read only (DEC-010) ──────────────────────────
+
+                        
+               
+                           
+                        
+                        
+                          
+                             
+ 
+                                                       
+                      
+               
+                    
+                        
+                        
+                              
+                             
+ 
+                                                                                                      
+
+/** A recorded header value as UTF-8, or null when absent, empty or `unknown` (emission.jq's `known`). */
+function recorded(value                    )                {
+  const v = known(value);
+  return v ? utf8(v) : null;
+}
+
+function listNames(dir        )           {
+  try {
+    if (!fs.lstatSync(dir).isDirectory()) return [];
+    return fs.readdirSync(dir).sort((a        , b        ) => (a < b ? -1 : a > b ? 1 : 0));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * IC-014: the pending summary, leftover `.claimed.<unitId>` copies of the summary scope, and the
+ * grants addressed to (run, lineage), each with what its header records. Headers are read with the
+ * bounded readHead(); nothing is renamed, removed or written. Empty when summaryScope() is null.
+ * 078 headers record no commit today, so `commit` is null unless a header carries a `commit` field.
+ */
+function scopeContext(worktree        , run        , lineage        , env      = process.env)               {
+  const empty               = { pending: null, claimed: [], grants: [] };
+  const scope = summaryScope(worktree, run, lineage, env);
+  if (scope === null) return empty;
+
+  let pending                      = null;
+  const claimed                 = [];
+  for (const name of listNames(scope)) {
+    const file = path.join(scope, name);
+    if (name === 'summary.md') {
+      if (!regularFile(file)) continue;
+      const head = readHead(file);
+      const id = head.summary_id;
+      pending = {
+        path: file,
+        summaryId: id !== undefined && SUMMARY_ID_PATTERN.test(id) ? id : null,
+        branch: recorded(head.branch),
+        commit: recorded(head.commit),
+        worktree: recorded(head.worktree),
+        compactedAt: recorded(head.compacted_at),
+      };
+    } else if (name.startsWith('.claimed.')) {
+      const unitId = name.slice('.claimed.'.length);
+      if (UNIT_PATTERN.test(unitId) && regularFile(file)) claimed.push({ path: file, unitId });
+    }
+  }
+
+  const grants               = [];
+  const root = stateDir(env);
+  const dir = path.join(root ?? '', 'grants', run, lineage);
+  for (const name of root === null ? [] : listNames(dir)) {
+    if (!name.endsWith('.md')) continue;
+    const summaryId = name.slice(0, -3);
+    const file = path.join(dir, name);
+    if (!SUMMARY_ID_PATTERN.test(summaryId) || !regularFile(file)) continue;
+    const head = readHead(file);
+    grants.push({
+      path: file,
+      summaryId,
+      branch: recorded(head.branch),
+      commit: recorded(head.commit),
+      fromWorktree: recorded(head.from_worktree),
+      compactedAt: recorded(head.compacted_at),
+    });
+  }
+  return { pending, claimed, grants };
+}
+
+                                                                                                                        
+                                                                                                           
+
+/**
+ * IC-014's comparison, pure: the caller probes the current branch (null when HEAD is detached or
+ * unreadable) and commit outside any lock. Both branches known: compare them. Both sides detached,
+ * with a recorded and a current commit: compare commits (critic A m9). Otherwise `branch-unknown`.
+ * A recorded worktree that is not the current one adds `worktree-differs`. Leftover claimed copies
+ * are always `claimed-not-consumed`. Returns every stale item, pending first, then claimed, then grants.
+ */
+function compareScopeContext(context              , current                                                                    )              {
+  const reasonsFor = (branch               , commit               , worktree               )                => {
+    const reasons                = [];
+    if (branch !== null && current.branch) {
+      if (branch !== current.branch) reasons.push('branch-differs');
+    } else if (branch === null && !current.branch && commit !== null && current.commit) {
+      if (commit !== current.commit) reasons.push('commit-differs');
+    } else {
+      reasons.push('branch-unknown');
+    }
+    if (worktree !== null && worktree !== current.worktree) reasons.push('worktree-differs');
+    return reasons;
+  };
+  const stale              = [];
+  const p = context.pending;
+  if (p !== null) {
+    const reasons = reasonsFor(p.branch, p.commit, p.worktree);
+    if (reasons.length) stale.push({ kind: 'summary', path: p.path, reasons });
+  }
+  for (const c of context.claimed) stale.push({ kind: 'claimed-summary', path: c.path, reasons: ['claimed-not-consumed'] });
+  for (const g of context.grants) {
+    const reasons = reasonsFor(g.branch, g.commit, g.fromWorktree);
+    if (reasons.length) stale.push({ kind: 'grant', path: g.path, reasons });
+  }
+  return stale;
+}
+
+module.exports = {
+  DEFAULT_GRANT_MAX_BYTES,
+  GRANT_EXIT,
+  SUMMARY_ID_PATTERN,
+  SummaryStoreError,
+  adoptLegacy,
+  claimGrant,
+  claimSummary,
+  compareScopeContext,
+  grantSummary,
+  legacySummary,
+  peekGrant,
+  peekSummary,
+  releaseClaim,
+  scopeContext,
+  summaryScope,
+};