@sabaiway/agent-workflow-kit 13.0.0 → 13.2.0

package/tools/checkpoint-core.mjs

@@ -0,0 +1,118 @@
+// spec:checkpoint — docs/ai/specs/kit/checkpoint/index.md
+import { lstatSync, mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { snapshotScope } from './dispatch-baseline.mjs';
+import { isNeverCommittableStat } from './core-evidence.mjs';
+import { isThreadTerminalRecord } from './dispatch-record.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, withGitPath } from './git-env.mjs';
+
+export const CHECKPOINT_REF_PREFIX = 'refs/agent-workflow/checkpoints/';
+const ACCEPT = 0;
+const REFUSE = 1;
+const INCREMENT = 1;
+const EMPTY = '';
+const SPACE = ' ';
+const NEWLINE = '\n';
+const UTF8 = 'utf8';
+const TEMP_PREFIX = 'aw-checkpoint-';
+const INDEX_NAME = 'index';
+const LITERAL_PATHSPECS = '1';
+const WORK_TREE = 'work-tree';
+const MISSING_PATH_CODES = ['ENOENT', 'ENOTDIR'];
+const OID_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const NAMES = { scope: 'scope', sequence: 'sequence' };
+const DISPATCH_KIND = 'dispatch';
+const CHECKPOINT_KIND = 'checkpoint';
+const LOCATION_ERROR = 'checkpoint requires a git work tree';
+const SEQUENCE_ERROR = 'expected contiguous numbered refs on trees';
+const STAT_ERROR = 'cannot classify path';
+const TYPE_ERROR = 'present path is not a regular file, symlink or directory';
+const OID_ERROR = 'git did not return a tree oid';
+const GIT = 'git';
+const GIT_ARGS = {
+  refs: ['for-each-ref', '--format=%(refname) %(objectname)'],
+  empty: ['read-tree', '--empty'],
+  add: ['add', '-f', '--'],
+  tree: ['write-tree'],
+};
+
+export const refuse = (reason, code = REFUSE) => ({ ok: false, code, reason });
+const defaultRunGit = (args, cwd, input, env) => spawnSync(GIT, args, {
+  cwd, input, env: withGitPath(env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true,
+});
+export const makeRunner = ({ runGit = defaultRunGit, env = process.env } = {}) => (args, cwd, input, override = env) => {
+  try { return runGit(args, cwd, input, override); }
+  catch (error) { return { error, status: null, stdout: Buffer.alloc(ACCEPT) }; }
+};
+export const readGitBytes = ({ run, top, env }, args, override = env) => {
+  const result = run(args, top, undefined, override);
+  if (result == null || result.error || result.signal || result.status !== ACCEPT || result.stdout == null) {
+    throw new Error(`${GIT} ${args.join(SPACE)} failed: ${result?.error?.message ?? String(result?.stderr ?? EMPTY).trim()}`);
+  }
+  return Buffer.from(result.stdout);
+};
+export const readGit = (context, args, override = context.env) => readGitBytes(context, args, override).toString(UTF8).trimEnd();
+export const withRepository = (cwd, io, action) => {
+  try {
+    const env = io.env ?? process.env;
+    const run = makeRunner({ ...io, env });
+    const location = resolveGitLocation(cwd, { env,
+      spawn: (command, args, options) => run(args, options.cwd, undefined, options.env) });
+    if (location.state !== WORK_TREE) return refuse(location.cause ?? LOCATION_ERROR);
+    return action({ cwd, top: location.top, env, run, io: { ...io, env, runGit: run } });
+  } catch (error) {
+    return refuse(error.message);
+  }
+};
+export const readCheckpointRefs = (context, prefix = CHECKPOINT_REF_PREFIX) => {
+  const lines = readGit(context, [...GIT_ARGS.refs, prefix]).split(NEWLINE).filter(Boolean);
+  return lines.map((line) => {
+    const [ref, oid, extra] = line.split(SPACE);
+    if (!ref.startsWith(prefix) || !OID_PATTERN.test(oid) || extra !== undefined) {
+      throw new Error(`${NAMES.sequence}: ${SEQUENCE_ERROR}`);
+    }
+    return { ref, oid };
+  });
+};
+export const withTemporaryIndex = (env, action) => {
+  const directory = mkdtempSync(join(tmpdir(), TEMP_PREFIX));
+  try {
+    return action({ ...env, GIT_INDEX_FILE: join(directory, INDEX_NAME), GIT_LITERAL_PATHSPECS: LITERAL_PATHSPECS });
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+};
+export const readScopeStat = (context, path) => {
+  try {
+    const stat = (context.io.lstat ?? lstatSync)(join(context.top, path));
+    if (stat == null) throw new Error(STAT_ERROR);
+    return stat;
+  } catch (error) {
+    if (MISSING_PATH_CODES.includes(error.code)) return null;
+    throw new Error(`${NAMES.scope}: ${path}: ${error.message}`);
+  }
+};
+export const writeSnapshot = (context, baseTreeOid) => {
+  const scope = snapshotScope(context.top, { baseTreeOid }, context.io);
+  if (!scope.ok) return refuse(scope.reason);
+  const paths = scope.paths.filter((path) => {
+    const stat = readScopeStat(context, path);
+    if (stat === null) return false;
+    if (isNeverCommittableStat(stat) || !(stat.isFile() || stat.isSymbolicLink() || stat.isDirectory())) {
+      throw new Error(`${NAMES.scope}: ${path}: ${TYPE_ERROR}`);
+    }
+    return stat.isFile() || stat.isSymbolicLink();
+  });
+  return withTemporaryIndex(context.env, (env) => {
+    readGit(context, GIT_ARGS.empty, env);
+    for (const path of paths) readGit(context, [...GIT_ARGS.add, path], env);
+    const oid = readGit(context, GIT_ARGS.tree, env);
+    if (!OID_PATTERN.test(oid)) return refuse(`${NAMES.scope}: ${OID_ERROR}`);
+    return { ok: true, oid };
+  });
+};
+export const findOpenCheckpointThread = (records, held) => records.find((record, index) =>
+  record.kind === DISPATCH_KIND && record.baseline?.kind === CHECKPOINT_KIND && held.has(record.baseline.treeOid)
+  && !records.slice(index + INCREMENT).some((successor) => successor.nonce === record.nonce && isThreadTerminalRecord(successor)));

package/tools/checkpoint-restore.mjs

@@ -0,0 +1,126 @@
+// spec:checkpoint — docs/ai/specs/kit/checkpoint/restore.md
+import { unlinkSync, rmdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { resolveTreeObject, snapshotScope } from './dispatch-baseline.mjs';
+import { readDelegationLedger } from './dispatch-store-read.mjs';
+import { CHECKPOINT_REF_PREFIX, withRepository, readGit, readGitBytes, readCheckpointRefs,
+  withTemporaryIndex, readScopeStat, writeSnapshot, findOpenCheckpointThread } from './checkpoint-core.mjs';
+
+const REFUSE = 1;
+const START = 0;
+const NEXT = 1;
+const LAST = -1;
+const SLASH = '/';
+const NUL = '\0';
+const UTF8 = 'utf8';
+const ROOT = '.';
+const FORBIDDEN_SEGMENTS = ['', '.', '..', '.git'];
+const ENTRY_PATTERN = /^([0-9]{6}) [^ ]+ [0-9a-f]+\t([\s\S]+)$/;
+const SEQUENCE_REF_PATTERN = /^[^/]+\/(?:0|[1-9][0-9]*)$/;
+const ALLOWED_MODES = ['100644', '100755', '120000'];
+const LEDGER_ABSENT = 'absent';
+const LEDGER_OK = 'ok';
+const NONEMPTY_CODES = ['ENOTEMPTY', 'EEXIST'];
+const NAMES = { scope: 'target-scope', ledger: 'ledger', open: 'open-thread', conflict: 'type-conflict' };
+const ENCODING_ERROR = 'target tree paths are not lossless UTF-8';
+const ENTRY_ERROR = 'unreadable target tree entry';
+const UNREFERENCED_ERROR = 'no checkpoint sequence carries target';
+const MISMATCH = 'checkpoint restore mismatch';
+const GIT_ARGS = {
+  resolve: ['rev-parse', '--verify'],
+  entries: ['ls-tree', '-r', '-z'],
+  read: ['read-tree'],
+  checkout: ['checkout-index', '-a', '-f'],
+};
+
+const refuse = (reason) => ({ ok: false, code: REFUSE, reason });
+const readTargetEntries = (context, target) => {
+  const bytes = readGitBytes(context, [...GIT_ARGS.entries, target]);
+  const text = bytes.toString(UTF8);
+  if (!Buffer.from(text, UTF8).equals(bytes)) throw new Error(`${NAMES.scope}: ${ENCODING_ERROR}`);
+  return text.split(NUL).filter(Boolean).map((entry) => {
+    const parsed = ENTRY_PATTERN.exec(entry);
+    if (parsed === null) throw new Error(`${NAMES.scope}: ${ENTRY_ERROR}`);
+    const [, mode, path] = parsed;
+    if (!ALLOWED_MODES.includes(mode) || path.split(SLASH).some((segment) => FORBIDDEN_SEGMENTS.includes(segment))) {
+      throw new Error(`${NAMES.scope}: ${path}`);
+    }
+    return path;
+  });
+};
+const readHeldSet = (context, target) => {
+  const refs = readCheckpointRefs(context).filter(({ ref }) => SEQUENCE_REF_PATTERN.test(ref.slice(CHECKPOINT_REF_PREFIX.length)));
+  const sequences = new Set(refs.filter(({ oid }) => oid === target).map(({ ref }) => dirname(ref)));
+  if (sequences.size === START) throw new Error(`${NAMES.scope}: ${UNREFERENCED_ERROR}: ${target}`);
+  return new Set([target, ...refs.filter(({ ref }) => sequences.has(dirname(ref))).map(({ oid }) => oid)]);
+};
+const checkLedger = (context, held) => {
+  const ledger = readDelegationLedger(context.cwd, context.env);
+  if (ledger.state !== LEDGER_ABSENT && ledger.state !== LEDGER_OK) return refuse(`${NAMES.ledger}: ${ledger.reason}`);
+  const open = findOpenCheckpointThread(ledger.records ?? [], held);
+  return open === undefined ? { ok: true } : refuse(`${NAMES.open}: ${open.nonce}`);
+};
+const listParents = (path) => {
+  const parts = path.split(SLASH).slice(START, LAST);
+  return parts.map((part, index) => parts.slice(START, index + NEXT).join(SLASH));
+};
+const checkTypes = (context, paths) => {
+  for (const path of paths) {
+    for (const parent of listParents(path)) {
+      const stat = readScopeStat(context, parent);
+      if (stat === null) break;
+      if (!stat.isDirectory()) return refuse(`${NAMES.conflict}: ${parent}: ${path}`);
+    }
+    if (readScopeStat(context, path)?.isDirectory()) return refuse(`${NAMES.conflict}: ${path}`);
+  }
+  return { ok: true };
+};
+const removeEmptyParents = (context, path) => {
+  const parent = dirname(path);
+  if (parent === ROOT) return;
+  const stat = readScopeStat(context, parent);
+  if (stat === null || !stat.isDirectory()) return;
+  try {
+    rmdirSync(join(context.top, parent));
+  } catch (error) {
+    if (!NONEMPTY_CODES.includes(error.code)) throw error;
+    return;
+  }
+  removeEmptyParents(context, parent);
+};
+const removeExtras = (context, domain, targets) => {
+  for (const path of domain) {
+    if (targets.has(path) || path.split(SLASH).some((segment) => FORBIDDEN_SEGMENTS.includes(segment))) continue;
+    if (!listParents(path).every((parent) => readScopeStat(context, parent)?.isDirectory())) continue;
+    const stat = readScopeStat(context, path);
+    if (stat === null || !(stat.isFile() || stat.isSymbolicLink())) continue;
+    unlinkSync(join(context.top, path));
+    removeEmptyParents(context, path);
+  }
+};
+
+export const restoreCheckpoint = (cwd, oid, io = {}) => withRepository(cwd, io, (context) => {
+  const tree = resolveTreeObject(context.top, oid, context.io);
+  if (!tree.ok) return refuse(tree.reason);
+  const target = readGit(context, [...GIT_ARGS.resolve, oid]);
+  const entries = readTargetEntries(context, target);
+  const scope = snapshotScope(context.top, { baseTreeOid: target }, context.io);
+  if (!scope.ok) return refuse(scope.reason);
+  const domain = new Set(scope.paths);
+  const outside = entries.find((path) => !domain.has(path));
+  if (outside !== undefined) return refuse(`${NAMES.scope}: ${outside}`);
+  const held = readHeldSet(context, target);
+  const ledger = checkLedger(context, held);
+  if (!ledger.ok) return ledger;
+  const types = checkTypes(context, entries);
+  if (!types.ok) return types;
+  withTemporaryIndex(context.env, (env) => {
+    readGit(context, [...GIT_ARGS.read, target], env);
+    readGit(context, GIT_ARGS.checkout, env);
+  });
+  removeExtras(context, scope.paths, new Set(entries));
+  const snapshot = writeSnapshot(context, target);
+  if (!snapshot.ok) return snapshot;
+  return snapshot.oid === target ? { ok: true, target, proof: snapshot.oid }
+    : refuse(`${MISMATCH}: ${target} ${snapshot.oid}`);
+});

package/tools/checkpoint.mjs

@@ -0,0 +1,146 @@
+// spec:checkpoint — docs/ai/specs/kit/checkpoint/index.md
+import { lstatSync, readFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { resolveTreeObject } from './dispatch-baseline.mjs';
+import { readDelegationLedger } from './dispatch-store-read.mjs';
+import { PLANS_REL, isScratchPlanName } from './plan-files.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { CHECKPOINT_REF_PREFIX, refuse, withRepository, readGit, readCheckpointRefs, writeSnapshot,
+  findOpenCheckpointThread } from './checkpoint-core.mjs';
+import { restoreCheckpoint } from './checkpoint-restore.mjs';
+
+export { CHECKPOINT_REF_PREFIX } from './checkpoint-core.mjs';
+const ACCEPT = 0;
+const REFUSE = 1;
+const USAGE = 2;
+const FIRST_NUMBER = 0;
+const INCREMENT = 1;
+const LAST = -1;
+const EMPTY = '';
+const NEWLINE = '\n';
+const SLASH = '/';
+const STRING = 'string';
+const MARKDOWN = '.md';
+const NUMBER_PATTERN = /^(0|[1-9][0-9]*)$/;
+const VERBS = { mint: 'mint', newest: 'newest', verify: 'verify', prune: 'prune', restore: 'restore' };
+const NAMES = { stem: 'stem', sequence: 'sequence', ledger: 'ledger', open: 'open-thread', empty: 'no-checkpoint' };
+const CHECKPOINT_KIND = 'checkpoint';
+const LEDGER_ABSENT = 'absent';
+const LEDGER_OK = 'ok';
+const CLEAN = 'CLEAN';
+const DIRTY = 'DIRTY';
+const PROOF = 'proof';
+const PLAN_FLAG = '--plan';
+const PLAN_ARG_COUNT = 3;
+const OID_ARG_COUNT = 2;
+const ARGV_OFFSET = 2;
+const USAGE_TEXT = 'usage: checkpoint mint|newest|prune --plan <plan> | verify|restore <oid>';
+const PLAN_ERROR = 'expected a readable regular plan directly under docs/plans';
+const SEQUENCE_ERROR = 'expected contiguous numbered refs on trees';
+const GIT_ARGS = {
+  checkRef: ['check-ref-format'],
+  resolve: ['rev-parse', '--verify'],
+  update: ['update-ref', '--no-deref'],
+  remove: ['update-ref', '--no-deref', '-d'],
+};
+
+const readPlan = (context, planPath) => {
+  try {
+    if (typeof planPath !== STRING || isAbsolute(planPath)) return refuse(`${NAMES.stem}: ${PLAN_ERROR}`);
+    const path = resolve(context.cwd, planPath);
+    const parent = relative(context.top, dirname(path)).split(sep).join(SLASH);
+    const name = basename(path);
+    if (parent !== PLANS_REL || !name.endsWith(MARKDOWN) || isScratchPlanName(name)
+      || !(context.io.lstat ?? lstatSync)(path).isFile()) return refuse(`${NAMES.stem}: ${PLAN_ERROR}`);
+    readFileSync(path);
+    const stem = name.slice(FIRST_NUMBER, -MARKDOWN.length);
+    readGit(context, [...GIT_ARGS.checkRef, `${CHECKPOINT_REF_PREFIX}${stem}/${FIRST_NUMBER}`]);
+    return { ok: true, stem };
+  } catch (error) {
+    return refuse(`${NAMES.stem}: ${error.message}`);
+  }
+};
+const readSequence = (context, stem) => {
+  const prefix = `${CHECKPOINT_REF_PREFIX}${stem}${SLASH}`;
+  const refs = readCheckpointRefs(context, prefix).map(({ ref, oid }) => {
+    const suffix = ref.slice(prefix.length);
+    if (!NUMBER_PATTERN.test(suffix)) {
+      throw new Error(`${NAMES.sequence}: ${SEQUENCE_ERROR}`);
+    }
+    return { ref, oid, n: Number(suffix), stem };
+  }).sort((left, right) => left.n - right.n);
+  for (const [index, checkpoint] of refs.entries()) {
+    if (!Number.isSafeInteger(checkpoint.n) || checkpoint.n !== index) throw new Error(`${NAMES.sequence}: ${SEQUENCE_ERROR}`);
+    const tree = resolveTreeObject(context.top, checkpoint.oid, context.io);
+    if (!tree.ok) throw new Error(tree.reason);
+  }
+  return refs;
+};
+const withSequence = (cwd, planPath, io, action) => withRepository(cwd, io, (context) => {
+  const plan = readPlan(context, planPath);
+  if (!plan.ok) return plan;
+  return action(context, plan.stem, readSequence(context, plan.stem));
+});
+
+export const mintCheckpoint = (cwd, planPath, io = {}) => withSequence(cwd, planPath, io, (context, stem, refs) => {
+  const newest = refs.at(LAST);
+  const snapshot = writeSnapshot(context, newest?.oid ?? null);
+  if (!snapshot.ok) return snapshot;
+  if (snapshot.oid === newest?.oid) return { ok: true, ...newest };
+  const n = newest === undefined ? FIRST_NUMBER : newest.n + INCREMENT;
+  const ref = `${CHECKPOINT_REF_PREFIX}${stem}/${n}`;
+  readGit(context, [...GIT_ARGS.update, ref, snapshot.oid]);
+  return { ok: true, stem, n, ref, oid: snapshot.oid };
+});
+
+export const newestCheckpoint = (cwd, planPath, io = {}) => withSequence(cwd, planPath, io, (context, stem, refs) => {
+  const newest = refs.at(LAST);
+  return newest === undefined ? refuse(`${NAMES.empty}: ${stem}`) : { ok: true, ...newest };
+});
+
+export const verifyCheckpoint = (cwd, oid, io = {}) => withRepository(cwd, io, (context) => {
+  const tree = resolveTreeObject(context.top, oid, context.io);
+  if (!tree.ok) return refuse(tree.reason);
+  const target = readGit(context, [...GIT_ARGS.resolve, oid]);
+  const snapshot = writeSnapshot(context, target);
+  if (!snapshot.ok) return snapshot;
+  return { ok: true, clean: target === snapshot.oid, target, oid: snapshot.oid };
+});
+
+export const pruneCheckpoints = (cwd, planPath, io = {}) => withSequence(cwd, planPath, io, (context, stem, refs) => {
+  const ledger = readDelegationLedger(context.cwd, context.env);
+  if (ledger.state !== LEDGER_ABSENT && ledger.state !== LEDGER_OK) return refuse(`${NAMES.ledger}: ${ledger.reason}`);
+  const records = ledger.records ?? [];
+  const held = new Set(refs.map(({ oid }) => oid));
+  const open = findOpenCheckpointThread(records, held);
+  if (open !== undefined) return refuse(`${NAMES.open}: ${open.nonce}`);
+  for (const { ref } of [...refs].reverse()) readGit(context, [...GIT_ARGS.remove, ref]);
+  return { ok: true };
+});
+
+const PLAN_OPERATIONS = { [VERBS.mint]: mintCheckpoint, [VERBS.newest]: newestCheckpoint, [VERBS.prune]: pruneCheckpoints };
+const formatRef = ({ stem, n, oid }) => `${CHECKPOINT_KIND} ${stem}/${n} ${oid}${NEWLINE}`;
+const formatRefusal = ({ code, reason }) => ({ code, stdout: EMPTY, stderr: `${reason}${NEWLINE}` });
+export const main = (argv = process.argv.slice(ARGV_OFFSET), deps = {}) => {
+  const [verb, operand, planPath] = argv;
+  const planVerb = Object.hasOwn(PLAN_OPERATIONS, verb);
+  const oidVerb = verb === VERBS.verify || verb === VERBS.restore;
+  if (!(planVerb && argv.length === PLAN_ARG_COUNT && operand === PLAN_FLAG && planPath)
+    && !(oidVerb && argv.length === OID_ARG_COUNT && operand)) return formatRefusal(refuse(USAGE_TEXT, USAGE));
+  const cwd = deps.cwd ?? process.cwd();
+  const operation = verb === VERBS.restore ? restoreCheckpoint : verifyCheckpoint;
+  const result = planVerb ? PLAN_OPERATIONS[verb](cwd, planPath, deps) : operation(cwd, operand, deps);
+  if (!result.ok) return formatRefusal(result);
+  if (verb === VERBS.restore) return { code: ACCEPT,
+    stdout: `${CHECKPOINT_KIND} ${VERBS.restore} ${result.target} ${PROOF} ${result.proof}${NEWLINE}`, stderr: EMPTY };
+  if (verb === VERBS.verify) return { code: result.clean ? ACCEPT : REFUSE,
+    stdout: `${result.clean ? CLEAN : DIRTY} ${result.target} ${result.oid}${NEWLINE}`, stderr: EMPTY };
+  return { code: ACCEPT, stdout: verb === VERBS.prune ? EMPTY : formatRef(result), stderr: EMPTY };
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main();
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  process.exitCode = result.code;
+}

package/tools/dispatch-baseline.mjs

@@ -0,0 +1,172 @@
+// dispatch-baseline.mjs — snapshotScope, computeBasePayload, computeBaseFingerprint,
+// isCleanAgainstBase, runBaseDiff and resolveTreeObject; spec:dispatch-baseline.
+// Writes only its own temporary indexes and the blob objects stored by forced adds.
+// Head measurements delegate unchanged to core-evidence without a temporary index.
+// runBaseDiff returns null for head; callers must use their existing head diff path.
+
+import { mkdtempSync, rmSync, lstatSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, basename, relative } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { computeFingerprintPayload, isTreeClean, isNeverCommittableStat } from './core-evidence.mjs';
+import { KIT_OWN_PATHS, KNOWN_FOOTPRINT, patternToProbe, isDirPattern, expandGlob, isGlobPattern } from './known-footprint.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, withGitPath } from './git-env.mjs';
+
+const TEMP_PREFIX = 'aw-dispatch-baseline-';
+const INDEX_NAME = 'index';
+const HASH_ALGORITHM = 'sha256';
+const PAYLOAD_DIFF_ARGS = ['--no-ext-diff', '--no-textconv', '--ignore-submodules=none'];
+const SCOPE_EXCLUSIONS = ['/docs/plans/', '/.claude/settings.json', '/.claude/settings.local.json', '/.mcp.json'];
+const MISSING_PATH_CODES = ['ENOENT', 'ENOTDIR'];
+const ABSENT_HEAD_STATUS = 1;
+const splitPaths = (bytes) => {
+  const text = bytes.toString('utf8');
+  if (!Buffer.from(text).equals(bytes)) throw new Error('git path names are not lossless UTF-8');
+  return text.split('\0').filter(Boolean).map((path) => path.replace(/\/$/, ''));
+};
+const defaultRunGit = (args, cwd, input, env) => spawnSync('git', args, {
+  cwd, input, env: withGitPath(env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true,
+});
+const makeRunner = ({ runGit = defaultRunGit, env = process.env } = {}) => (args, cwd, input, override = env) => {
+  try { return runGit(args, cwd, input, override); }
+  catch (error) { return { error, status: null, stdout: Buffer.alloc(0) }; }
+};
+const readGit = (run, args, top, env) => {
+  const result = run(args, top, undefined, env);
+  if (result == null || result.error || result.signal || result.status !== 0 || result.stdout == null) {
+    throw new Error(`git ${args.join(' ')} failed: ${result?.error?.message ?? String(result?.stderr ?? '').trim()}`);
+  }
+  return Buffer.from(result.stdout);
+};
+const locateTop = (cwd, run, env) => {
+  const location = resolveGitLocation(cwd, { env, spawn: (command, args, options) => run(args, options.cwd, undefined, options.env) });
+  if (location.state !== 'work-tree') throw new Error(location.cause ?? 'not inside a git work tree');
+  return location.top;
+};
+const withTemporaryIndex = (env, action) => {
+  const directory = mkdtempSync(join(tmpdir(), TEMP_PREFIX));
+  try {
+    return action({ ...env, GIT_INDEX_FILE: join(directory, INDEX_NAME), GIT_LITERAL_PATHSPECS: '1' });
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+};
+const readStat = (path, lstat) => {
+  try {
+    const stat = lstat(path);
+    if (stat == null) throw new Error(`cannot stat ${path}`);
+    return stat;
+  } catch (error) {
+    if (MISSING_PATH_CODES.includes(error.code)) return null;
+    throw error;
+  }
+};
+const readTreePaths = (run, top, treeOid, env) => splitPaths(readGit(run, ['ls-tree', '-r', '--name-only', '-z', treeOid], top, env));
+const readHeadPaths = (run, top, env) => {
+  const head = run(['rev-parse', '--verify', '--quiet', 'HEAD'], top, undefined, env);
+  if (head && !head.error && !head.signal && head.status === ABSENT_HEAD_STATUS) return [];
+  if (!head || head.error || head.signal || head.status !== 0) throw new Error('cannot resolve HEAD');
+  return readTreePaths(run, top, 'HEAD', env);
+};
+const excludePatterns = (top, paths) => [
+  ...SCOPE_EXCLUSIONS,
+  ...KNOWN_FOOTPRINT.flatMap(({ pattern }) => isGlobPattern(pattern)
+    ? expandGlob(pattern, {
+      dir: top,
+      readdir: (parent) => paths.filter((path) => dirname(path) === relative(top, parent).split('\\').join('/')).map((path) => basename(path)),
+      stat: () => ({ isFile: () => true }),
+    })
+    : [pattern]),
+];
+const collectScope = (top, baseTreeOid, run, lstat, env) => withTemporaryIndex(env, (indexEnv) => {
+  readGit(run, ['read-tree', '--empty'], top, indexEnv);
+  const paths = new Set(splitPaths(readGit(run, ['ls-files', '--others', '--exclude-standard', '-z'], top, indexEnv)));
+  for (const pattern of KIT_OWN_PATHS) {
+    const probe = patternToProbe(pattern);
+    const stat = readStat(join(top, probe), lstat);
+    if (stat === null) continue;
+    if (isDirPattern(pattern) && stat.isDirectory()) {
+      for (const path of splitPaths(readGit(run, ['ls-files', '--others', '-z', '--', probe], top, indexEnv))) paths.add(path);
+    } else paths.add(probe.replace(/\/$/, ''));
+  }
+  for (const path of readHeadPaths(run, top, indexEnv)) paths.add(path);
+  if (baseTreeOid !== null) for (const path of readTreePaths(run, top, baseTreeOid, indexEnv)) paths.add(path);
+  const exclusions = excludePatterns(top, [...paths]).map((pattern) => ({ probe: patternToProbe(pattern), directory: isDirPattern(pattern) }));
+  return [...paths].filter((path) => !path.split('/').includes('node_modules')
+    && !exclusions.some(({ probe, directory }) => directory ? path === probe.slice(0, -1) || path.startsWith(probe) : path === probe)).sort();
+});
+
+export const snapshotScope = (cwd, { baseTreeOid = null } = {}, io = {}) => {
+  try {
+    const env = io.env ?? process.env;
+    const run = makeRunner(io);
+    const top = locateTop(cwd, run, env);
+    return { ok: true, paths: collectScope(top, baseTreeOid, run, io.lstat ?? lstatSync, env) };
+  } catch (error) {
+    return { ok: false, reason: `snapshot scope: ${error.message}` };
+  }
+};
+
+export const resolveTreeObject = (cwd, oid, io = {}) => {
+  try {
+    const env = io.env ?? process.env;
+    const run = makeRunner(io);
+    const top = locateTop(cwd, run, env);
+    const type = readGit(run, ['cat-file', '-t', oid], top, env).toString('utf8').trim();
+    return type === 'tree' ? { ok: true } : { ok: false, reason: `${oid} names a ${type}, not a tree` };
+  } catch (error) {
+    return { ok: false, reason: `${oid} is an unresolvable tree object: ${error.message}` };
+  }
+};
+
+export const runBaseDiff = (cwd, base, args, io = {}) => {
+  if (base.kind !== 'checkpoint') return null;
+  try {
+    const env = io.env ?? process.env;
+    const run = makeRunner(io);
+    const top = locateTop(cwd, run, env);
+    if (!resolveTreeObject(top, base.treeOid, io).ok) return null;
+    const scope = snapshotScope(top, { baseTreeOid: base.treeOid }, io);
+    if (!scope.ok) return null;
+    const basePaths = readTreePaths(run, top, base.treeOid, env);
+    const present = [];
+    const removed = [];
+    for (const path of scope.paths) {
+      const stat = readStat(join(top, path), io.lstat ?? lstatSync);
+      const baseHoldsPath = basePaths.includes(path);
+      const neverCommittable = stat !== null && isNeverCommittableStat(stat);
+      const materialized = stat !== null && !neverCommittable && (stat.isFile() || stat.isSymbolicLink());
+      if (neverCommittable && baseHoldsPath) throw new Error(`base path ${path} is no longer committable`);
+      if (materialized) present.push(path);
+      if (!materialized && !neverCommittable && (stat === null || baseHoldsPath)) removed.push(path);
+    }
+    const excludedBasePaths = basePaths.filter((path) => !scope.paths.includes(path));
+    const conflict = present.find((path) => excludedBasePaths.some((excluded) =>
+      path.startsWith(`${excluded}/`) || excluded.startsWith(`${path}/`)));
+    if (conflict !== undefined) throw new Error(`live path ${conflict} conflicts with an excluded base path`);
+    return withTemporaryIndex(env, (indexEnv) => {
+      readGit(run, ['read-tree', base.treeOid], top, indexEnv);
+      if (removed.length > 0) readGit(run, ['update-index', '--remove', '--', ...removed], top, indexEnv);
+      if (present.length > 0) readGit(run, ['add', '-f', '--', ...present], top, indexEnv);
+      return readGit(run, ['diff', '--cached', base.treeOid, ...args], top, indexEnv);
+    });
+  } catch {
+    return null;
+  }
+};
+
+export const computeBasePayload = (cwd, base, io = {}) => base.kind === 'head'
+  ? computeFingerprintPayload(cwd, io)
+  : runBaseDiff(cwd, base, PAYLOAD_DIFF_ARGS, io);
+
+export const computeBaseFingerprint = (cwd, base, io) => {
+  const payload = computeBasePayload(cwd, base, io);
+  return payload === null ? null : createHash(HASH_ALGORITHM).update(payload).digest('hex');
+};
+
+export const isCleanAgainstBase = (cwd, base, io) => {
+  if (base.kind === 'head') return isTreeClean(cwd, io);
+  const payload = computeBasePayload(cwd, base, io);
+  return payload === null ? null : payload.length === 0;
+};

package/tools/dispatch-record.mjs

@@ -131,13 +131,21 @@ const short = (v) => {
 // ── the closed vocabulary ─────────────────────────────────────────────────────────────────────────
 
 export const DELEGATION_SCHEMA_VERSION = 1;
+export const BASELINE_KINDS = deepFreeze(['head', 'checkpoint']);
+export const HEAD_BASELINE = deepFreeze({ kind: 'head', treeOid: null });
+export const OPTIONAL_FIELDS = deepFreeze({ dispatch: ['baseline'] });
+const TREE_OID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+export const isTreeOid = (v) => typeof v === 'string' && TREE_OID_RE.test(v);
+export const readsBaseline = (dispatch) => Object.hasOwn(dispatch, 'baseline')
+  ? { kind: dispatch.baseline.kind, treeOid: dispatch.baseline.treeOid }
+  : { ...HEAD_BASELINE };
 
 export const DELEGATION_KINDS = deepFreeze(['pre-registration', 'dispatch', 'return', 'fold', 'observation', 'degrade']);
 
 // The closed key set per kind (schema + kind are implicit on every record).
 export const DELEGATION_KEY_SETS = deepFreeze({
   'pre-registration': ['waveId', 'stepClasses', 'pairingKey', 'minPerClass', 'meanLThreshold', 'firstPassNum', 'firstPassDen', 'timestamp'],
-  dispatch: ['waveId', 'nonce', 'stepClass', 'vehicle', 'backend', 'contractDigest', 'preTreeDigest', 'baselineClean', 'deadlineS', 'retryOf', 'retryIndex', 'retryCap', 'rationale', 'timestamp'],
+  dispatch: ['waveId', 'nonce', 'stepClass', 'vehicle', 'backend', 'contractDigest', 'preTreeDigest', 'baselineClean', 'deadlineS', 'retryOf', 'retryIndex', 'retryCap', 'rationale', 'timestamp', 'baseline'],
   return: ['role', 'backend', 'nonce', 'contractDigest', 'preTreeDigest', 'postTreeDigest', 'diffDigest', 'diffLength', 'reportDigest', 'reportLength', 'bundleDigest', 'bundleLength', 'metric', 'outcome', 'exitStatus', 'sessionId', 'wrapperVersion', 'posture', 'timestamp'],
   fold: ['nonce', 'returnDigest', 'treeDigestAtFold', 'verdict', 'timestamp'],
   observation: ['waveId', 'stepClass', 'scope', 'metric', 'planId', 'phase', 'timestamp'],
@@ -217,6 +225,7 @@ const namesAnObject = (kind) => kind !== 'gate-output';
 // ── nested closed forms ───────────────────────────────────────────────────────────────────────────
 
 const VEHICLE_KEYS = ['requested', 'selected'];
+const BASELINE_KEYS = ['kind', 'treeOid'];
 const POSTURE_KEYS = ['model', 'effort', 'tier'];
 const METRIC_KEYS = ['numeratorBytes', 'denominatorBytes', 'components', 'provenance', 'eligible', 'ineligibleReason'];
 const COMPONENT_KEYS = ['kind', 'path', 'objectId', 'bytes'];
@@ -235,6 +244,18 @@ const checkClosedKeys = (at, value, keys) => {
   return { ok: true };
 };
 
+const validateBaseline = (at, baseline) => {
+  const closed = checkClosedKeys(at, baseline, BASELINE_KEYS);
+  if (!closed.ok) return closed;
+  if (!BASELINE_KINDS.includes(baseline.kind)) return refuse(`${at}: unknown kind ${short(baseline.kind)} — expected ${BASELINE_KINDS.join(' | ')}`);
+  if (baseline.treeOid !== null && (typeof baseline.treeOid !== 'string' || !TREE_OID_RE.test(baseline.treeOid))) {
+    return refuse(`${at}: treeOid must be null or exactly 40 or 64 lowercase hex characters (got ${short(baseline.treeOid)})`);
+  }
+  if (baseline.kind === 'head' && baseline.treeOid !== null) return refuse(`${at}: head requires treeOid null`);
+  if (baseline.kind === 'checkpoint' && baseline.treeOid === null) return refuse(`${at}: checkpoint requires treeOid to be non-null`);
+  return { ok: true };
+};
+
 const validateVehicle = (at, vehicle) => {
   const closed = checkClosedKeys(at, vehicle, VEHICLE_KEYS);
   if (!closed.ok) return closed;
@@ -324,6 +345,7 @@ const FIELD_CHECKS = {
   firstPassNum: { ok: isByteCount, want: 'a non-negative integer first-pass numerator' },
   firstPassDen: { ok: (v) => Number.isSafeInteger(v) && v >= 1, want: 'a positive integer first-pass denominator' },
   vehicle: { ok: isPlainObject, want: 'the closed vehicle pair {requested, selected}' },
+  baseline: { ok: isPlainObject, want: 'the closed baseline pair {kind, treeOid}' },
   // The safe token grammar, not merely non-empty: the backend NAMES an artifact beside the store
   // (the exec receipt and its report), so a name outside this grammar records a dispatch whose own
   // receipt could never be written. One grammar on both sides, or the ledger accepts what the
@@ -375,6 +397,7 @@ const checkFields = (kind, record) => {
     return refuse(`${kind}: unknown field "${stray}" — the key set is closed (the canonical digest is identity; a stray key would fork it)`);
   }
   for (const field of fields) {
+    if (!Object.hasOwn(record, field) && (OPTIONAL_FIELDS[kind] ?? []).includes(field)) continue;
     if (!own.includes(field)) {
       return refuse(`${kind}: missing field "${field}" — every field of the closed set is pinned as an OWN ENUMERABLE key (the digest domain)`);
     }
@@ -492,6 +515,10 @@ export const validateDelegationRecord = (record) => {
   }
   if (record.kind === 'dispatch') {
     const vehicle = validateVehicle('dispatch: vehicle', record.vehicle);
+    if (Object.hasOwn(record, 'baseline')) {
+      const baseline = validateBaseline('dispatch: baseline', record.baseline);
+      if (!baseline.ok) return baseline;
+    }
     return vehicle.ok ? validateDispatchCrossFields(record) : vehicle;
   }
   if (record.kind === 'return') return validateReturnCrossFields(record);

package/tools/dispatch-store-read.mjs

@@ -3,7 +3,7 @@ import { spawnSync } from 'node:child_process';
 
 import {
   validateDelegationRecord, canonicalDelegationDigest, allowedSuccessorKinds,
-  isThreadTerminalRecord,
+  isThreadTerminalRecord, readsBaseline,
 } from './dispatch-record.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 import { GIT_MAX_BUFFER } from './git-env.mjs';
@@ -175,6 +175,11 @@ export const delegationSemanticPreflight = ({ records, snapshot, storePath }) =>
       if (snapshot.stepClass !== prior.dispatch.stepClass) {
         throw stop(`refusing a retry: it declares step class "${snapshot.stepClass}" but its retry origin "${snapshot.retryOf}" was dispatched as "${prior.dispatch.stepClass}" — the pairing key is the step class, so a chain that changes it mid-way would split one attempt's accounting across two classes; nothing was written`);
       }
+      const base = readsBaseline(snapshot);
+      const priorBase = readsBaseline(prior.dispatch);
+      if (base.kind !== priorBase.kind || base.treeOid !== priorBase.treeOid) {
+        throw stop(`refusing a retry: its base {kind "${base.kind}", treeOid ${base.treeOid}} differs from its retry origin "${snapshot.retryOf}"'s {kind "${priorBase.kind}", treeOid ${priorBase.treeOid}} — a retry chain is measured against ONE base; nothing was written`);
+      }
       const origin = findRetryChainOrigin(records, prior.dispatch);
       if (snapshot.retryIndex > origin.retryCap) {
         throw stop(`refusing a retry: retryIndex ${snapshot.retryIndex} exceeds the retryCap ${origin.retryCap} recorded on the thread's ORIGIN dispatch ("${origin.nonce}") — a fresh contract never manufactures a fresh retry budget; nothing was written`);