@sabaiway/agent-workflow-kit 10.6.0 → 11.0.0

package/tools/dispatch-store-read.mjs

@@ -1,18 +1,18 @@
 import { join, isAbsolute, normalize, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
+
 import {
   validateDelegationRecord, canonicalDelegationDigest, allowedSuccessorKinds,
   isThreadTerminalRecord,
 } from './dispatch-record.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 export const DELEGATION_STORE_STOP = 'DELEGATION_STORE_STOP';
 export const delegationStoreStop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'DelegationStoreStop', code: DELEGATION_STORE_STOP });
 const stop = delegationStoreStop;
 
 export const DELEGATION_STORE_BASENAME = 'agent-workflow-delegation.jsonl';
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
-
 const runGit = (args, cwd, spawn = spawnSync) => spawn('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
 const readGitLine = (args, cwd, spawn) => {
   const result = runGit(args, cwd, spawn);

package/tools/flow-check-git-lane.mjs

@@ -4,13 +4,14 @@
 // pure decision cores can never reach a git spawn through it.
 
 import { spawnSync } from 'node:child_process';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 const short = (digest) => `${digest.slice(0, 12)}…`;
 
 // computeChangedSurface exists for COVERAGE and excludes test files by design — the base-
 // intersection inputs come from these helpers instead: every changed path counts, tests included.
 const gitPathList = (args, cwd) => {
-  const r = spawnSync('git', args, { cwd, maxBuffer: 256 * 1024 * 1024, windowsHide: true });
+  const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;
   return r.stdout.toString('utf8').split('\0').filter(Boolean);
 };

package/tools/flow-delta-proof.mjs

@@ -13,15 +13,15 @@ import { createHash } from 'node:crypto';
 import { readFileSync, lstatSync, readlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 import { lstatNoFollow } from './atomic-write.mjs';
 import { FLOW_SCHEMA_VERSION, canonicalFlowDigest } from './flow-record.mjs';
-import { isNeverCommittableStat, isBinaryFile, lexicalRepoRelative, resolveBase } from './core-evidence.mjs';
+import { FINGERPRINT_CACHED_DIFF_ARGV, FINGERPRINT_UNSTAGED_DIFF_ARGV, isNeverCommittableStat, isBinaryFile, lexicalRepoRelative, resolveBase } from './core-evidence.mjs';
 import { flowStoreStop, gitLine, describeNonRegular } from './flow-store-read.mjs';
 import { appendFlowRecord } from './flow-append.mjs';
 
 const stop = flowStoreStop;
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 const gitBuf = (args, cwd) => {
   const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;
@@ -166,8 +166,8 @@ const untrackedEntryChunks = (top, rel, lstat) => {
 const captureFingerprintPieces = (cwd, { lstat = lstatSync } = {}) => {
   const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
   if (top == null) return null;
-  const staged = gitBuf(['diff', '--cached', '--no-ext-diff'], top);
-  const unstaged = gitBuf(['diff', '--no-ext-diff'], top);
+  const staged = gitBuf(FINGERPRINT_CACHED_DIFF_ARGV, top);
+  const unstaged = gitBuf(FINGERPRINT_UNSTAGED_DIFF_ARGV, top);
   const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top);
   if (staged == null || unstaged == null || untrackedZ == null) return null;
   const entries = untrackedZ.toString('utf8').split('\0').filter(Boolean)

package/tools/flow-record-shape.mjs

@@ -79,6 +79,7 @@ const FIELD_CHECKS = {
   attemptIndex: { ok: (v) => Number.isInteger(v) && v >= 1, want: 'a positive integer attempt index (monotonic per counting context)' },
   status: { ok: (v) => v === 'green' || v === 'red', want: 'the closed enum green | red' },
   diagnosis: { ok: isNonEmptyString, want: 'a non-empty diagnosis statement (Decision 8 — the recorded continuation past two reds)' },
+  walk: { ok: isPlainObject, want: 'the closed walk object' },
 };
 
 const CHAIN_COMMON_FIELDS = ['planId', 'cycle', 'round', 'commitEpoch', 'owner', 'base', 'timestamp'];
@@ -171,33 +172,54 @@ const validateDispatches = (label, list) => {
 // The per-finding disposition ledger (#13/#33): every council finding lands as exactly one of the
 // three closed arms, each carrying its proof (a consult-attestation/red-proof digest, a debt entry,
 // or a stated rejection reason).
+// The new arms are escalated with its override, and custody-lost keyed on receiptDigest with no findingDigest.
 const DISPOSITION_KEYS = {
   folded: ['findingDigest', 'action', 'proofKind', 'proofDigest'],
   queued: ['findingDigest', 'action', 'debtId', 'debtDigest'],
   rejected: ['findingDigest', 'action', 'reason'],
+  escalated: ['findingDigest', 'action', 'overrideDigest'],
+  'custody-lost': ['action', 'receiptDigest', 'findingManifestDigest', 'reason'],
 };
+const PROOF_KINDS = ['consult-attestation', 'red-proof'];
+const QUEUED_PROOF_KEYS = ['claim', 'proofKind', 'proofDigest'];
+const LOSS_REASONS = ['absent', 'foreign', 'error', 'malformed', 'foreign-identity', 'swapped'];
 
 const validateDispositions = (label, list) => {
   const seenFindings = new Set();
+  const seenLostReceipts = new Set();
   for (let i = 0; i < list.length; i += 1) {
     const d = list[i];
     const at = `${label}: dispositions[${i}]`;
     if (!isPlainObject(d)) return refuse(`${at} must be an object`);
-    const armKeys = Object.hasOwn(DISPOSITION_KEYS, d.action) ? DISPOSITION_KEYS[d.action] : undefined;
+    const baseKeys = Object.hasOwn(DISPOSITION_KEYS, d.action) ? DISPOSITION_KEYS[d.action] : undefined;
+    const armKeys = d.action === 'queued' && QUEUED_PROOF_KEYS.some((key) => key in d) ? [...baseKeys, ...QUEUED_PROOF_KEYS] : baseKeys;
     if (armKeys === undefined) return refuse(`${at}: action must be one of ${Object.keys(DISPOSITION_KEYS).join(' | ')} (got ${JSON.stringify(d.action)}) — an inherited prototype key never resolves an arm (fail closed)`);
     const stray = Object.keys(d).find((k) => !armKeys.includes(k));
     if (stray !== undefined) return refuse(`${at}: unknown field "${stray}" — the ${d.action} arm's key set is closed`);
     const missing = armKeys.find((k) => !(k in d));
     if (missing !== undefined) return refuse(`${at}: missing field "${missing}"`);
+    if (d.action === 'custody-lost') {
+      if (!isHex64(d.receiptDigest)) return refuse(`${at}: receiptDigest must be the 64-hex digest of the lost receipt`);
+      if (!isHex64(d.findingManifestDigest)) return refuse(`${at}: findingManifestDigest must be the 64-hex ledger digest of the lost manifest`);
+      if (!LOSS_REASONS.includes(d.reason)) return refuse(`${at}: reason must be one of ${LOSS_REASONS.join(' | ')}`);
+      if (seenLostReceipts.has(d.receiptDigest)) return refuse(`${at}: duplicate receiptDigest — one custody-lost entry per lost receipt`);
+      seenLostReceipts.add(d.receiptDigest);
+      continue;
+    }
     if (!isHex64(d.findingDigest)) return refuse(`${at}: findingDigest must be the 64-hex digest of the finding`);
     if (seenFindings.has(d.findingDigest)) return refuse(`${at}: duplicate findingDigest — every finding gets exactly one disposition, whichever the arm`);
     seenFindings.add(d.findingDigest);
     if (d.action === 'folded') {
-      if (d.proofKind !== 'consult-attestation' && d.proofKind !== 'red-proof') return refuse(`${at}: proofKind must be consult-attestation | red-proof (the fold's proof record class)`);
+      if (!PROOF_KINDS.includes(d.proofKind)) return refuse(`${at}: proofKind must be consult-attestation | red-proof (the fold's proof record class)`);
       if (!isHex64(d.proofDigest)) return refuse(`${at}: proofDigest must be the 64-hex digest of the proof record`);
     } else if (d.action === 'queued') {
       if (!isNonEmptyString(d.debtId)) return refuse(`${at}: debtId must be the non-empty stable debt-queue id`);
       if (!isHex64(d.debtDigest)) return refuse(`${at}: debtDigest must be the 64-hex digest of the debt entry`);
+      if ('claim' in d && !isNonEmptyString(d.claim)) return refuse(`${at}: claim must be a non-empty invariant`);
+      if ('proofKind' in d && !PROOF_KINDS.includes(d.proofKind)) return refuse(`${at}: proofKind must be consult-attestation | red-proof`);
+      if ('proofDigest' in d && !isHex64(d.proofDigest)) return refuse(`${at}: proofDigest must be the 64-hex digest of the proof record`);
+    } else if (d.action === 'escalated') {
+      if (!isHex64(d.overrideDigest)) return refuse(`${at}: overrideDigest must be the 64-hex digest of the maintainer override`);
     } else if (!isNonEmptyString(d.reason)) {
       return refuse(`${at}: reason must be a non-empty statement of why the finding is rejected`);
     }
@@ -205,6 +227,24 @@ const validateDispositions = (label, list) => {
   return { ok: true };
 };
 
+const validateWalk = (walk) => {
+  const keys = ['listVersion', 'rows', 'uncovered'];
+  if (!isPlainObject(walk)) return refuse('internal-attestation: walk must be an object');
+  const stray = Object.keys(walk).find((key) => !keys.includes(key));
+  if (stray !== undefined) return refuse(`internal-attestation: walk has unknown field "${stray}"`);
+  const missing = keys.find((key) => !(key in walk));
+  if (missing !== undefined) return refuse(`internal-attestation: walk is missing field "${missing}"`);
+  if (!Number.isInteger(walk.listVersion) || walk.listVersion < 1) return refuse('internal-attestation: walk.listVersion must be a positive integer');
+  for (const name of ['rows', 'uncovered']) {
+    if (!Array.isArray(walk[name])) return refuse(`internal-attestation: walk.${name} must be an array`);
+    const itemKeys = name === 'rows' ? ['id', 'class', 'checked'] : ['id', 'class'];
+    for (const [i, item] of walk[name].entries()) {
+      if (!isPlainObject(item) || Object.keys(item).length !== itemKeys.length || !itemKeys.every((key) => key in item && isNonEmptyString(item[key]))) return refuse(`internal-attestation: walk.${name}[${i}] must be the closed {${itemKeys.join(', ')}} string object`);
+    }
+  }
+  return { ok: true };
+};
+
 // The three-layer pre-state digest set (#60): HEAD entry, index entry, worktree bytes — null means
 // "no entry in that layer". tracked-ness is derived (a HEAD or index entry exists); the presence
 // class is the WORKTREE layer. The fingerprint domain (staged + unstaged + untracked) is exactly
@@ -272,8 +312,10 @@ export const validateFlowRecord = (record) => {
     }
     fieldToCheck.diagnosis = 'diagnosis';
   }
+  if (record.kind === 'internal-attestation' && 'walk' in record) fieldToCheck.walk = 'walk';
   const checked = checkFields(record.kind, record, fieldToCheck);
   if (!checked.ok) return checked;
+  if (record.kind === 'internal-attestation' && 'walk' in record) return validateWalk(record.walk);
   if (record.kind === 'down-mark') {
     if (!isCanonicalInstant(record.timestamp)) return refuse('down-mark: timestamp must be a canonical UTC ISO instant (toISOString round-trip) — the TTL window needs comparable instants');
     if (Date.parse(record.expiresAt) <= Date.parse(record.timestamp)) return refuse('down-mark: expiresAt must be strictly after timestamp — an already-expired mark is refused at the record level');

package/tools/flow-round-gates.mjs

@@ -0,0 +1,151 @@
+import { createHash } from 'node:crypto';
+import { escapeForDisplay } from './repo-lex.mjs';
+import { SIGNALS, signalFor } from './review-rounds.mjs';
+import { authoritativeFlowRecords, canonicalFlowDigest, flowRecordKey } from './flow-record.mjs';
+import { isNonEmptyString, isPlainObject, refuse } from './flow-vocabulary.mjs';
+import { isShipVerdict } from './core-evidence.mjs';
+
+const sha256 = (value) => createHash('sha256').update(value, typeof value === 'string' ? 'utf8' : undefined).digest('hex');
+const item = (text) => ({ text, digest: sha256(text) });
+const linesOf = (payload) => String(payload).split('\n').map((line) => line.replace(/\r$/, ''));
+const codexSchema = (payload) => {
+  let decoded;
+  try {
+    decoded = JSON.parse(payload);
+  } catch {
+    return null;
+  }
+  const severities = ['blocker', 'major', 'minor', 'nit'];
+  return isPlainObject(decoded)
+    && ['ship', 'revise', 'rethink'].includes(decoded.verdict)
+    && Array.isArray(decoded.findings)
+    && decoded.findings.every((finding) => isPlainObject(finding) && severities.includes(finding.severity))
+    ? decoded : null;
+};
+
+export const blockingItems = (backend, payload) => {
+  if (backend === 'codex') {
+    const decoded = codexSchema(payload);
+    if (decoded) {
+      const selected = decoded.findings.filter(({ severity }) => severity === 'blocker' || severity === 'major');
+      if (!selected.every(({ issue }) => isNonEmptyString(issue))) return refuse('codex schema blocking item issue is empty or not a string');
+      return { ok: true, mode: 'schema', items: selected.map(({ issue }) => item(issue)) };
+    }
+    return { ok: true, mode: 'text', items: linesOf(payload).filter((line) => /^\[(blocker|major)\](\s|$)/.test(line)).map(item) };
+  }
+  if (backend === 'agy') {
+    const lines = linesOf(payload);
+    const open = lines.findIndex((line) => /^### Blocking\s*$/.test(line));
+    const close = lines.findIndex((line, index) => index > open && /^### /.test(line));
+    const section = open < 0 ? [] : lines.slice(open + 1, close < 0 ? undefined : close);
+    return { ok: true, mode: 'text', items: section.filter((line) => /^[0-9]+[.)]/.test(line)).map(item) };
+  }
+  return refuse(`cannot enumerate backend ${JSON.stringify(backend)} — no blocking-item vocabulary predicate`);
+};
+
+export const findingQuoted = (backend, findings, quote) => findings.includes(quote)
+  || (backend === 'codex' && codexSchema(findings)?.findings.some(({ issue }) => issue === quote) === true);
+
+const landed = (head, receipts) => head.dispatches
+  .filter(({ receiptDigest }) => receiptDigest !== null)
+  .map((entry) => ({ entry, receipt: receipts.get(entry.receiptDigest) }))
+  .filter(({ receipt }) => receipt !== undefined);
+
+export const roundsForSignal = (heads, receipts) => {
+  const rounds = heads.map((head) => ({
+    fingerprint: head.fingerprint,
+    byBackend: Object.fromEntries(landed(head, receipts).map(({ entry, receipt }) => [entry.backend, receipt])),
+  }));
+  const backends = [...new Set((heads.length ? landed(heads.at(-1), receipts) : []).map(({ entry }) => entry.backend))];
+  return {
+    rounds,
+    obligation: backends.length ? { backends, perBackend: true, minShip: backends.length } : null,
+  };
+};
+
+const lossName = (read, expected) => {
+  if (read?.outcome !== 'ok') return read?.outcome ?? 'error';
+  return sha256(read.bytes) === expected ? null : 'swapped';
+};
+const quoteCovered = (ledger, digest) => ledger.some((entry) => entry.findingDigest === digest
+  && (['folded', 'rejected', 'escalated'].includes(entry.action)
+    || (entry.action === 'queued' && ['claim', 'proofKind', 'proofDigest'].every((key) => key in entry))));
+
+export const capIssue = ({ heads, receipts, readManifest }) => {
+  const { rounds, obligation } = roundsForSignal(heads, receipts);
+  if (obligation === null) return { issue: null, advisories: [] };
+  const signal = signalFor(rounds, obligation, '<artifact>');
+  if (signal !== SIGNALS.CAP_REACHED && signal !== SIGNALS.CROSSOVER) return { issue: null, advisories: [] };
+  const head = heads.at(-1);
+  const ledger = head.dispositions;
+  const advisories = [];
+  const issues = [];
+  const uncovered = [];
+  for (const { entry, receipt } of landed(head, receipts)) {
+    if (ledger.some((disposition) => disposition.action === 'custody-lost' && disposition.receiptDigest === entry.receiptDigest)) continue;
+    const needsFallbackDisposition = !isShipVerdict(receipt.verdict) && ledger.length === 0;
+    if (!Number.isInteger(receipt.blocking) || receipt.blocking < 0) {
+      const why = `blocking ${JSON.stringify(receipt.blocking)} is not a non-negative integer for backend ${JSON.stringify(entry.backend)}`;
+      advisories.push(`advisory: ${why}`);
+      if (needsFallbackDisposition) issues.push(`enumeration fallback requires at least one disposition in round ${head.round}: ${why}`);
+      continue;
+    }
+    if (receipt.blocking === 0) continue;
+    const read = readManifest(entry.backend, entry.dispatchNonce);
+    const loss = lossName(read, entry.findingManifestDigest);
+    if (loss !== null) {
+      const covered = ledger.some((d) => d.action === 'custody-lost' && d.receiptDigest === entry.receiptDigest);
+      if (!covered) issues.push(`lost receipt ${entry.receiptDigest} (${loss}); recovery: round-land --dispose custody-lost --receipt ${entry.receiptDigest}`);
+      continue;
+    }
+    const enumerated = blockingItems(entry.backend, read.manifest.findings);
+    if (!enumerated.ok || enumerated.items.length !== receipt.blocking) {
+      const why = !enumerated.ok ? enumerated.reason : `enumerated count ${enumerated.items.length} differs from blocking ${receipt.blocking} for backend ${JSON.stringify(entry.backend)}`;
+      advisories.push(`advisory: ${why}`);
+      if (ledger.length === 0) issues.push(`enumeration fallback requires at least one disposition in round ${head.round}: ${why}`);
+      continue;
+    }
+    for (const found of enumerated.items) if (!quoteCovered(ledger, found.digest)) uncovered.push(found);
+  }
+  if (uncovered.length) {
+    issues.push(`uncovered blocking items:\n${uncovered.map(({ digest, text }) => `${digest}  ${escapeForDisplay(text)}`).join('\n')}\nrecovery: round-land --dispose <folded|queued|rejected|escalated> --finding <the item text> on the SAME tree`);
+  }
+  return { issue: issues.length ? issues.join('\n') : null, advisories };
+};
+
+export const walkIssue = ({ records, planId, cycle, stepId, round, base, fingerprint }) => {
+  if (round <= 1) return null;
+  const coordinates = { kind: 'internal-attestation', planId, cycle, stepId, round: round - 1, base, fingerprint };
+  const wanted = flowRecordKey(coordinates);
+  const found = authoritativeFlowRecords(records).find((record) => flowRecordKey(record) === wanted);
+  return found?.walk ? null
+    : `round-open round ${round} requires an authoritative walk for round ${round - 1} at {planId=${planId}, cycle=${cycle}, stepId=${stepId}, round=${round - 1}, base=${base}, fingerprint=${fingerprint}}; recovery: internal-attestation ${planId} --walk <file> at the current tree, or --justification <text>`;
+};
+
+export const escalationIssue = ({ records, digest, planId, head }) => {
+  const override = records.find((record) => record.kind === 'maintainer-override' && canonicalFlowDigest(record) === digest);
+  if (!override) return { issue: `override digest ${digest} does not resolve to a maintainer-override`, dispatch: null };
+  const chain = records.find((record) => record.kind === 'chain' && canonicalFlowDigest(record) === override.chainRecord);
+  if (!chain || chain.planId !== planId) return { issue: `override ${digest} does not bind a chain record of plan ${planId}`, dispatch: null };
+  const dispatch = head.dispatches.find(({ receiptDigest }) => receiptDigest === override.vetoReceiptDigest);
+  return dispatch
+    ? { issue: null, dispatch }
+    : { issue: `override ${digest} does not bind a landed receipt of plan ${planId} round ${head.round}`, dispatch: null };
+};
+
+export const validateWalk = (walk, coverage) => {
+  if (!isPlainObject(walk) || Object.keys(walk).some((key) => !['listVersion', 'rows'].includes(key)) || !Array.isArray(walk.rows)) return refuse('walk must be the closed {listVersion, rows} object');
+  if (walk.listVersion !== coverage.listVersion) return refuse(`walk listVersion ${JSON.stringify(walk.listVersion)} does not match shipped listVersion ${coverage.listVersion}`);
+  for (const [i, entry] of walk.rows.entries()) {
+    if (!isPlainObject(entry) || Object.keys(entry).length !== 3 || !['id', 'class', 'checked'].every((key) => key in entry) || !isNonEmptyString(entry.id) || !isNonEmptyString(entry.class)) return refuse(`walk rows[${i}] must be the closed {id, class, checked} non-empty string object`);
+    if (!isNonEmptyString(entry.checked)) return refuse(`walk checked for ${entry.id}:${entry.class} must be a non-empty string`);
+  }
+  const judged = coverage.rows.filter((row) => !row.deleted && !row.absent);
+  for (const row of judged) {
+    for (const classId of new Set([...row.tagged, ...row.present])) {
+      if (!walk.rows.some((entry) => entry.id === row.id && entry.class === classId && isNonEmptyString(entry.checked))) return refuse(`walk is missing non-empty checked for ${row.id}:${classId}`);
+    }
+  }
+  const uncovered = judged.flatMap((row) => row.present.filter((classId) => !row.tagged.includes(classId)).map((classId) => ({ id: row.id, class: classId })));
+  return { ok: true, walk: { listVersion: coverage.listVersion, rows: walk.rows, uncovered } };
+};

package/tools/flow-store-read.mjs

@@ -13,6 +13,7 @@ import { join, isAbsolute, normalize, basename, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { validateFlowRecord, authoritativeFlowRecords } from './flow-record.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 export { lstatNoFollowRead, describeNonRegular, readRegularFileNoFollow, readFileBytesNoFollow } from './fs-read-nofollow.mjs';
 
@@ -23,7 +24,6 @@ export const flowStoreStop = (message) => Object.assign(new Error(`[agent-workfl
 export const FLOW_STORE_BASENAME = 'agent-workflow-flow.jsonl';
 export const FLOW_LOCK_SUFFIX = '.lock';
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 const gitBuf = (args, cwd) => {
   const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;