@sabaiway/agent-workflow-kit 13.0.0 → 13.1.0

package/tools/exec-producer.mjs

@@ -1,29 +1,32 @@
 // exec-producer.mjs — the GIT-side metric producer for an exec return (delegation Plan 2, Phase 1).
 // It answers the two questions a return record cannot answer for itself: which objects the delegated
-// run touched and how many bytes they represent, and what the canonical integration bundle is. It
-// never writes, never appends and never spawns anything but git reads.
+// run touched and how many bytes they represent, and what the canonical integration bundle is.
+// Under a checkpoint base the walks use the leaf's own temporary index and forced-add blob objects;
+// the real index is never written, and head walks spawn only git reads.
 //
 // dispatch-record.mjs:74-76 named this module before it existed: "the metric's byte domains are
 // computed over STRUCTURED inputs handed in by a producer; the git-side producer is Plan 2, and it
 // owns minting a stable objectId".
 //
-// ONE DOMAIN, THREE LAYERS (D7). The enumeration walks HEAD → index → worktree, exactly the layers
+// ONE DOMAIN, THREE LAYERS (D7) under a head base. The enumeration walks HEAD → index → worktree, exactly the layers
 // the canonical payload concatenates — never the collapsed HEAD → worktree view. The difference is
 // not academic: a staged change reverted in the worktree keeps its bytes in the payload (and so in
 // the DENOMINATOR) while HEAD→worktree shows nothing at all, so the object would vanish from the
 // NUMERATOR and the two halves of one ratio would describe different change sets. The diff bytes are
-// computeFingerprintPayload's own bytes, imported rather than rebuilt.
+// computeFingerprintPayload's own bytes, imported rather than rebuilt. Under a checkpoint base the
+// walk is one layer against the base tree, through the leaf's temporary index.
 //
-// ONE OBJECT, ONE ENTRY. An object touched in both layers is a single entry, and its pre-image is
+// ONE OBJECT, ONE ENTRY. Under a head base an object touched in both layers is a single entry, and its pre-image is
 // always the HEAD blob — never the index blob: the numerator answers what the delegate could have
 // spared the ORCHESTRATOR, measured against the dispatch baseline, and a metric-eligible dispatch
-// starts from a clean tree where HEAD is that baseline.
+// starts from a clean tree where HEAD is that baseline. Under a checkpoint base the pre-image is the base blob.
 //
 // RENAMES ARE NOT RECONSTRUCTED, AND THAT IS THE DESIGN — a boundary, not an omission. git's OWN
 // rename detection is consumed where git offers it (`--raw -M` sees a staged `git mv` within a layer),
-// but a rename a delegate actually makes — the wrapper's git-write shim blocks every git write verb,
+// but under a head base a rename a delegate actually makes — the wrapper's git-write shim blocks every git write verb,
 // so every one arrives as a tracked deletion plus an UNTRACKED creation — is accounted as exactly
-// that: a deletion plus a creation.
+// that: a deletion plus a creation. Under a checkpoint base git's own rename detection applies inside
+// the single base-relative layer, and a detected rename is counted once as `renamed`.
 //
 // This module once matched those pairs by blob identity, and the machinery was SUBTRACTED after it
 // produced silent-error edges in four consecutive review rounds: hashing that read through symlinks
@@ -35,7 +38,7 @@
 // An identity heuristic buys accuracy on the ordinary refactor and pays for it in exactly that
 // currency, so the trade was refused.
 //
-// The cost is stated with its DIRECTION, per case, because the direction is NOT the same in all of
+// The head-base cost is stated with its DIRECTION, per case, because the direction is NOT the same in all of
 // them — and a blanket "always optimistic" would be a false reassurance about an accounting number.
 // Write O for the pre-image size:
 //   • A PLAIN RENAME `a→b` emits `deleted pre:a (O)` + `new new:b (O)` = 2O against a recognised O.
@@ -54,18 +57,11 @@
 // Every object here is one git can PROVE: a tracked path with a recorded blob, or an untracked path
 // that exists. Nothing is paired on a resemblance.
 //
-// CONFIG-HIDDEN PATHS ARE A STATED LIMIT, and the limit is the PAYLOAD's, not this module's. `git
-// diff` honours `diff.ignoreSubmodules` and skips index entries carrying assume-unchanged or
-// skip-worktree, so a path can be changed and stay invisible to both probes below. The kit already
-// owns a probe that sees them — computeWorkingState (core-evidence.mjs:341) forces
-// `--ignore-submodules=none` and folds in flaggedIndexLag — and `isTreeClean` consumes it, so a
-// dispatch opened over such a tree records baselineClean:false and its return is metric-INELIGIBLE by
-// name. What this module must NOT do is force those flags HERE: D7 binds the numerator to the byte
-// domain of computeFingerprintPayload, which uses the same plain `git diff` — forcing them on one
-// side only would let the numerator count objects the denominator cannot see, a worse failure than
-// the blindness. Closing it for real means changing the shared payload, which is a Plan-1-frozen
-// surface the review lane also consumes; that is queued as its own item, and Phase 2's `return` owns
-// the return-time guard.
+// CONFIG-HIDDEN PATHS ARE A STATED LIMIT, and not this module's to close. Under a head base `git
+// diff` skips index entries carrying assume-unchanged or skip-worktree, so a path can be changed and
+// stay invisible to both probes below; the doors refuse a concealing tree rather than measure it. The
+// checkpoint walks force `--ignore-submodules=none` because the checkpoint payload they are measured
+// against does.
 //
 // IDENTITY CARRIES ITS DOMAIN (D6). `pre:<path>` for an object with a pre-image (keyed by the name it
 // HAD) and `new:<path>` for a created one. The prefix is load-bearing: a rename a→b beside a
@@ -79,12 +75,12 @@
 // paying it zero would drop a whole object's bytes out of the numerator on a type change. Every OTHER
 // unknown size REFUSES — the fail-closed rule is never a silent zero.
 //
-// A TRANSIENT object (staged, then deleted from the worktree) counts its INDEX image once: the
+// Under a head base a TRANSIENT object (staged, then deleted from the worktree) counts its INDEX image once: the
 // delegate authored those bytes, the payload carries them in both layers, and dropping them would
 // credit the delegate with less than it wrote.
 //
-// Fail closed: outside a git work tree, on an unborn branch (no HEAD means no pre-image to attribute
-// bytes against), on any git read that fails, and on any size it cannot establish.
+// Fail closed: outside a git work tree, on an unborn branch (the inherited no-HEAD limit
+// applies to both bases), on any git read that fails, and on any size it cannot establish.
 
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
@@ -92,7 +88,8 @@ import {
   gitBuf, computeFingerprintPayload, isBinaryFile, isNeverCommittableStat, resolveBase,
 } from './core-evidence.mjs';
 import { lstatNoFollowRead } from './fs-read-nofollow.mjs';
-import { frameIntegrationBundle } from './dispatch-record.mjs';
+import { frameIntegrationBundle, HEAD_BASELINE } from './dispatch-record.mjs';
+import { runBaseDiff, computeBasePayload } from './dispatch-baseline.mjs';
 
 const refuse = (reason) => ({ ok: false, reason });
 
@@ -100,6 +97,8 @@ const GITLINK_MODE = '160000';
 const SYMLINK_MODE = '120000';
 const ABSENT_MODE = '000000';
 const SUBMODULE_BYTES = 0;
+const BASE_RAW_ARGS = ['--raw', '-z', '-M', '--no-abbrev', '--no-ext-diff', '--ignore-submodules=none'];
+const BASE_NUMSTAT_ARGS = ['--numstat', '-z', '-M', '--no-ext-diff', '--ignore-submodules=none'];
 
 export const PRE_IMAGE_ID_PREFIX = 'pre:';
 export const NEW_IMAGE_ID_PREFIX = 'new:';
@@ -229,7 +228,7 @@ export const parseNumstatMarkers = (buf, where) => {
 };
 
 // ── the object model ──────────────────────────────────────────────────────────────────────────────
-// One record per touched object: where it came from in HEAD, where it ended up, and every name it
+// One record per touched object: where it came from in the base tree, where it ended up, and every name it
 // wore in between (the names the binary oracle and the type probes are asked about).
 
 const makeObject = ({ headPath, headSha, headMode }) => ({
@@ -247,7 +246,7 @@ const kindForModes = (modes) => {
 
 const buildObjects = (staged, unstaged) => {
   const objects = [];
-  // HEAD → index. A staged record's DESTINATION name is how the unstaged layer will refer to it.
+  // Base tree → index. Under a head base the DESTINATION name links to the unstaged layer.
   const byIndexPath = new Map();
   for (const r of staged) {
     const hasHead = !isAbsentSha(r.srcSha) && r.srcMode !== ABSENT_MODE;
@@ -312,7 +311,7 @@ const entryForObject = (top, object, binary, lstat) => {
   if (typeKind !== null) {
     // The COUNTED image decides the size, even when the emitted kind comes from another layer. A
     // gitlink in ANY layer makes the kind `submodule` (TYPE beats STATUS, D6) — but a regular file
-    // REPLACED by a gitlink is still counted at its HEAD blob, and paying it the submodule's
+    // REPLACED by a gitlink is still counted at its base blob, and paying it the submodule's
     // deliberate zero would drop a whole object's bytes out of the numerator on a type change. Zero
     // belongs to a counted image that is ITSELF a gitlink: that is the case where the move costs this
     // repository no bytes.
@@ -359,6 +358,24 @@ const entryForUntracked = (top, rel, lstat) => {
     : { ok: true, entry: { kind: 'new', path: rel, objectId, postImageBytes: stat.size } };
 };
 
+const enumerateCheckpointObjects = (top, base, io) => {
+  const raw = runBaseDiff(top, base, BASE_RAW_ARGS, io);
+  if (raw === null) return refuse('git could not read the base-relative change set (fail closed)');
+  const parsed = parseRawRecords(raw, 'the base-relative change set');
+  if (!parsed.ok) return parsed;
+  const numstat = runBaseDiff(top, base, BASE_NUMSTAT_ARGS, io);
+  if (numstat === null) return refuse('git could not read the numstat binary markers (fail closed)');
+  const binary = parseNumstatMarkers(numstat, 'the base-relative binary markers');
+  if (!binary.ok) return binary;
+  const entries = [];
+  for (const object of buildObjects(parsed.records, [])) {
+    const built = entryForObject(top, object, binary.names, io.lstat);
+    if (!built.ok) return built;
+    entries.push(built.entry);
+  }
+  return { ok: true, entries };
+};
+
 // enumerateReturnedObjects(cwd, io?) → { ok: true, entries } | { ok: false, reason }. The entries are
 // the STRUCTURED input computeNumerator consumes; this module never computes the numerator itself, so
 // the closed vocabulary stays the single authority on what a component is. `io.lstat` and
@@ -370,6 +387,8 @@ export const enumerateReturnedObjects = (cwd = process.cwd(), io = {}) => {
   if (resolveBase(top) == null) {
     return refuse('the branch is unborn (no HEAD) — there is no pre-image to attribute delegated bytes against (fail closed)');
   }
+  const base = io.base ?? HEAD_BASELINE;
+  if (base.kind === 'checkpoint') return enumerateCheckpointObjects(top, base, io);
   // ABSENT and UNREADABLE are different answers. ENOENT means the path vanished between `ls-files`
   // and the stat, which the payload itself records name-only — mirroring it keeps numerator and
   // denominator over ONE object set. Every OTHER errno (EACCES, EIO, ENOTDIR, ELOOP on a parent) is
@@ -442,9 +461,10 @@ export const enumerateReturnedObjects = (cwd = process.cwd(), io = {}) => {
   return refusedProbe() ?? { ok: true, entries };
 };
 
-// computeReturnedDiff(cwd) → the canonical uncommitted-state payload BYTES, or a refusal. This is the
-// diff half of the integration bundle, and it is the very payload computeTreeFingerprint digests — so
-// the bytes the denominator counts and the digest the records bind describe one state. It refuses
+// computeReturnedDiff(cwd) → the payload BYTES the thread's own base fingerprint digests, or a refusal:
+// computeTreeFingerprint's under a head base, the leaf's base-relative payload under a checkpoint.
+// This is the diff half of the integration bundle, so the bytes the denominator counts and the
+// digest the records bind describe one state. It refuses
 // where the enumeration refuses: one entry point may not answer for a tree the other rejects. That
 // sentence used to hold only for the two SHARED preconditions below, which let an AMBIGUOUS rename
 // refuse the enumeration while the diff still handed back bytes — so the enumeration is run here and
@@ -457,18 +477,18 @@ export const computeReturnedDiff = (cwd = process.cwd(), io = {}) => {
   }
   const enumerated = enumerateReturnedObjects(cwd, io);
   if (!enumerated.ok) return enumerated;
-  // The payload builder guards its lstat but reads untracked file BYTES unguarded, so an unreadable
+  // The head payload builder guards its lstat but reads untracked file BYTES unguarded, so an unreadable
   // or vanishing untracked file throws out of it. This entry point promises a refusal object, and a
   // caller that framed a bundle around a thrown read would have no bytes and no reason either.
-  let payload;
   try {
-    payload = computeFingerprintPayload(cwd);
+    const base = io.base ?? HEAD_BASELINE;
+    const payload = base.kind === 'checkpoint' ? computeBasePayload(cwd, base, io) : computeFingerprintPayload(cwd);
+    return payload == null
+      ? refuse('the canonical payload could not be computed (fail closed)')
+      : { ok: true, diff: payload };
   } catch (err) {
     return refuse(`the canonical payload could not be read (${err?.code ?? err?.message ?? 'read failed'}) — the returned diff is refused rather than framed around a partial read (fail closed)`);
   }
-  return payload == null
-    ? refuse('the canonical payload could not be computed (fail closed)')
-    : { ok: true, diff: payload };
 };
 
 // assembleIntegrationBundle(diff, report) → the framed bundle with its digest and length. The framing

package/tools/held-session.mjs

@@ -1,10 +1,12 @@
 import { escapeForDisplay, isRenderableLine, shellQuoteArg } from './repo-lex.mjs';
 import { wrapperCmdFor } from './detect-backends.mjs';
 import { DISPLAY_ALIASES } from './recipes.mjs';
+import { readsBaseline, TERMINAL_RETURN_OUTCOMES } from './dispatch-record.mjs';
 
 const CODE_STEP = 'code';
 const FOLD_KIND = 'fold';
 const RETURN_KIND = 'return';
+const DEGRADE_KIND = 'degrade';
 const EXECUTE_BACKEND = 'codex-cli-bridge';
 const UNPOPULATED_HELD_ID = '<held id>';
 
@@ -24,6 +26,7 @@ const findsDispatch = (dispatches, nonce) => dispatches.find((dispatch) => dispa
 const findsReturn = (returns, nonce) => returns.find((returned) => returned.nonce === nonce) ?? null;
 const hasCoveredReplacement = (returned, degrades) =>
   degrades.some((degrade) => degrade.fingerprint === returned.postTreeDigest);
+const expectsSession = (dispatch, baseKind) => dispatch.baselineClean === false || baseKind === 'checkpoint';
 const collectsRetryChainNonces = (dispatches, nonce, collected = new Set()) => {
   if (nonce === null || collected.has(nonce)) return collected;
   const next = new Set(collected).add(nonce);
@@ -33,26 +36,28 @@ const collectsRetryChainNonces = (dispatches, nonce, collected = new Set()) => {
 const accumulatesFacts = (degrades) => (state, record) => {
   if (record.kind === 'dispatch' && state.epochNonces.has(record.nonce)) {
     const expectedId = state.heldId;
+    const baseKind = readsBaseline(record).kind;
     return {
       ...state,
       dispatches: [...state.dispatches, record],
-      threads: [...state.threads, { nonce: record.nonce, expectedId, actualId: null, status: 'OPEN' }],
-      open: record.baselineClean === false ? [...state.open, { nonce: record.nonce, expectedId }] : state.open,
+      threads: [...state.threads, { nonce: record.nonce, expectedId, actualId: null, status: 'OPEN', baseKind }],
+      open: expectsSession(record, baseKind) ? [...state.open, { nonce: record.nonce, expectedId }] : state.open,
     };
   }
   if (record.kind === RETURN_KIND && state.epochNonces.has(record.nonce)) {
     const dispatch = findsDispatch(state.dispatches, record.nonce);
     if (dispatch === null) return state;
+    const baseKind = readsBaseline(dispatch).kind;
     const expectedId = state.threads.find((thread) => thread.nonce === record.nonce)?.expectedId ?? null;
     const status = record.sessionId === null ? 'FAILED'
       : expectedId === null ? 'FIRST'
       : dispatch.retryOf !== null || record.sessionId === expectedId ? 'CONTINUED'
         : 'SUBSTITUTED';
-    const substitution = status === 'SUBSTITUTED' && dispatch.baselineClean === false
-      && !hasCoveredReplacement(record, degrades)
+    const substitution = status === 'SUBSTITUTED' && expectsSession(dispatch, baseKind)
+      && (baseKind === 'checkpoint' ? !TERMINAL_RETURN_OUTCOMES.includes(record.outcome) : !hasCoveredReplacement(record, degrades))
       ? {
         nonce: record.nonce, expectedId, actualId: record.sessionId,
-        postTreeDigest: record.postTreeDigest, folded: false,
+        postTreeDigest: record.postTreeDigest, folded: false, baseKind,
       }
       : null;
     return {
@@ -71,7 +76,7 @@ const accumulatesFacts = (degrades) => (state, record) => {
     if (dispatch === null || returned === null || returned.sessionId === null) return state;
     const establishes = state.heldId === null;
     const retries = dispatch.retryOf !== null;
-    const replaces = returned.sessionId !== state.heldId && hasCoveredReplacement(returned, degrades);
+    const replaces = readsBaseline(dispatch).kind === 'head' && returned.sessionId !== state.heldId && hasCoveredReplacement(returned, degrades);
     const retryChain = retries ? collectsRetryChainNonces(state.dispatches, dispatch.retryOf) : new Set();
     const foldedSubstitutions = state.substitutions.map((substitution) =>
       (substitution.nonce === record.nonce ? { ...substitution, folded: true } : substitution));
@@ -81,6 +86,10 @@ const accumulatesFacts = (degrades) => (state, record) => {
     if (establishes || retries || replaces) return { ...state, heldId: returned.sessionId, substitutions };
     return { ...state, substitutions };
   }
+  if (record.kind === DEGRADE_KIND && state.epochNonces.has(record.nonce)
+    && state.substitutions.some((substitution) => substitution.nonce === record.nonce && substitution.baseKind === 'checkpoint')) {
+    return { ...state, heldId: null, substitutions: state.substitutions.filter((substitution) => substitution.nonce !== record.nonce) };
+  }
   return state;
 };
 
@@ -109,11 +118,15 @@ export const judgeHeldSession = (records, { head, backend, degrades = [] }) => {
     heldId: accumulated.heldId,
     folds: countsHeldFolds(records, epochNonces, accumulated.heldId),
     substitution: accumulated.substitutions[0] ?? null,
-    threads: accumulated.threads,
+    threads: accumulated.threads.map((thread) => ({
+      ...thread, substituted: accumulated.substitutions.some((substitution) => substitution.nonce === thread.nonce),
+    })),
     open: accumulated.open,
   };
 };
 
+export const threadVerdict = (facts, nonce) => facts.threads.find((thread) => thread.nonce === nonce) ?? null;
+
 export const judgeLedger = (ledger, { backend, degrades = [] }) => {
   if (ledger.state === 'absent') {
     return { state: 'absent', heldId: null, folds: 0, substitution: null, threads: [], open: [] };
@@ -137,7 +150,7 @@ export const decideHeldSession = (facts) => {
     const reason = `delegated code thread "${nonce}" substituted held session "${escapeForDisplay(expectedId)}" with "${escapeForDisplay(actualId)}"`;
     return { code: 1, reason, line: `held session: SUBSTITUTED — ${reason}` };
   }
-  if (facts.heldId === null) return { code: 0, reason: 'no folded code thread in the commit epoch carries a session yet', line: 'held session: none' };
+  if (facts.heldId === null) return { code: 0, reason: 'no held session stands: no folded code thread established one in this commit epoch, or the last one was withdrawn by a checkpoint thread\'s ledger degrade', line: 'held session: none' };
   const heldId = escapeForDisplay(facts.heldId);
   return { code: 0, reason: `held session "${heldId}" is continuous`, line: `held session: ${heldId} — ${facts.folds} fold(s) rode it` };
 };
@@ -159,7 +172,7 @@ export const foldLaneLines = (facts) => {
     `  run:  ${HELD_EXECUTE_WRAPPER} --resume ${heldId} --nonce <nonce> <fold-brief>`,
     '  the fold brief is a dispatch file carrying the finding and the accepted fold; dispatch open precedes the run, then dispatch return and fold follow it',
     '  the orchestrator runs the suites, verifies the returned diff, re-mints the red-proofs and owns the commit',
-    '  a fresh session is a forbidden substitution; a retry of a failed thread or a recorded execute degrade is the exception; the wrapper sidecar is never read',
+    '  a fresh session is a forbidden substitution; a retry of a failed thread or, for a head base, a recorded execute degrade is the exception (a checkpoint thread\'s substitution closes by its ledger degrade); the wrapper sidecar is never read',
   ];
   return caveat === null ? lines : [...lines, `  caveat: ${caveat}`];
 };

package/tools/review-state.mjs

@@ -11,9 +11,10 @@
 // Normative `--check` exit contract (the single home of this list — SKILL.md points here):
 // Before the review-recipe exits, configured plan-execution.execute=delegated with a plan and a
 // dirty, fingerprintable tree audits the delegation ledger. An absent ledger is inert; an
-// unavailable ledger, a HEAD error or a SUBSTITUTED held session refuses unless a codex-exec degrade at the
-// substituted return's tree, standing after every later fold, accepts it, or the fold of that thread's
-// retry lifts it (codex never grants it).
+// unavailable ledger or a HEAD error refuses. A SUBSTITUTED held session refuses: for a head-base thread,
+// a codex-exec degrade at the substituted return's tree, standing after every later fold, accepts it,
+// or the fold of that thread's retry lifts it (codex never grants it); a checkpoint-based thread's
+// substitution closes only by its own ledger degrade.
 //   exit 0  when the CONFIGURED plan-execution.review recipe is solo (or the computed default is —
 //           absent config with no reviewer backend ready); when no plan is in flight (docs/plans/
 //           holds no top-level .md that is not queue.md and not scratch by the naming convention:
@@ -149,6 +150,7 @@ export {
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
 const CORE_EVIDENCE_TOOL = shellQuoteArg(join(dirname(fileURLToPath(import.meta.url)), 'core-evidence.mjs'));
+const DISPATCH_TOOL = shellQuoteArg(join(dirname(fileURLToPath(import.meta.url)), 'dispatch.mjs'));
 // --await (BUGFREE-3 / AD-049, item (d)) bounds + poll cadence. The default timeout is generous —
 // a real grounded bridge review can take minutes — and every value is overridable (--timeout / the
 // injectable clock) so hermetic tests never spend wall-clock.
@@ -531,6 +533,9 @@ const backendFailurePart = (b, state) => {
 const describesHeldRecovery = (state) => {
   const substitution = state.heldSession.substitution;
   if (substitution === null) return '';
+  if (substitution.baseKind === 'checkpoint') {
+    return ` — a checkpoint-based thread: no core-evidence degrade lifts it; record its ledger degrade (node ${DISPATCH_TOOL} degrade --wave <wave> --nonce ${shellQuoteArg(substitution.nonce)} --step-class code --rationale "...") then retry it (cap permitting) or open a new thread on the held session, and fold that`;
+  }
   const canRetry = substitution.folded === false;
   if (state.evidenceUnavailable === true) {
     const retry = canRetry ? '; or fold the retry of that thread' : '';
@@ -784,8 +789,7 @@ record (node core-evidence.mjs degrade) — and never all backends.
 below, a configured plan-execution.execute = delegated with a plan in flight and a dirty,
 fingerprintable tree audits the delegation ledger: an absent ledger is inert; an unreadable,
 malformed, foreign or audit-refused ledger, a failed HEAD read, or a SUBSTITUTED held session
-exits 1 (a substitution is lifted only by a codex-exec degrade at the substituted return's own
-tree, or the fold of that thread's retry). THEN: 0 for solo / no plan in flight /
+exits 1. THEN: 0 for solo / no plan in flight /
 a clean tree (under a non-solo review obligation the PASS names every plan in flight and its arm) /
 a cwd where git ITSELF answers not-a-repository (the only passing non-work-tree state; the four others exit 1 by name) / obligations satisfied (reviewed: >=1 ship-class attestation;
 council: every backend ship-class or degrade-recorded, >=1 real ship); 1 on a veto, an