@sabaiway/agent-workflow-kit 1.48.0 → 2.0.0

package/tools/review-state.mjs

@@ -30,6 +30,18 @@
 // Informational receipts NEVER satisfy (nor fail) the tree check: plan/diff-mode receipts
 // (artifact ≠ "code") and continuations (fresh:false — agy --continue/--conversation cannot attest
 // a folded tree; only a fresh grounded re-run mints a gate-satisfying receipt).
+// PROBE receipts never satisfy either (BRIDGE-MODES-CATALOG, D3): a CODEX_PROBE=1 / AGY_PROBE=1
+// review runs with the frontier-model/max-effort guard OFF, so the wrappers stamp `probe:true` and
+// this checker drops those receipts — PER RECEIPT, so a normal receipt at the same fingerprint still
+// satisfies, and a backend whose ONLY current receipts are probes fails with its own stated reason
+// (never the stale one). Every receipt from a marker-aware wrapper SELF-DECLARES — `probe` is written
+// on every successful review, true or false — so a NON-BOOLEAN or ABSENT marker is rejected
+// fail-closed: silence is not a declaration, and the probe status of an unmarked receipt is
+// untrustworthy whoever wrote it (the pre-D3 wrappers honoured the probe env vars while writing no
+// marker; a hand-written line is no better evidence). Deliberately NOT keyed on wrapperVersion: the
+// version bumps in a different release phase than the marker lands, so a version floor would reject
+// the very receipts the current wrappers write. Accepted cost (maintainer, 2026-07-15): a pre-D3
+// receipt stops satisfying — re-run the review with a marker-aware bridge.
 //
 // The fingerprint is the ONE canonical uncommitted-state identity — sha256 over: staged diff +
 // unstaged diff + untracked-not-ignored file contents (binary untracked files, symlinks, and
@@ -61,7 +73,14 @@ import { resolveActivityRecipe, planRecipe, DISPLAY_ALIASES } from './recipes.mj
 import { CONFIG_REL, fail, loadConfig } from './orchestration-config.mjs';
 // The NEUTRAL ledger read-core (AD-050): review-state reads the review-ledger ONLY for the degraded
 // exemption, through the neutral core — never review-ledger.mjs (which imports THIS module, the cycle).
-import { resolveLedgerPath, resolveBase, readLedger, filterSegmentRecords, roundSequenceIntact } from './review-ledger-core.mjs';
+import {
+  resolveLedgerPath,
+  resolveBase,
+  readLedger,
+  filterSegmentRecords,
+  roundSequenceIntact,
+  summarizeReviewReceiptsForTree,
+} from './review-ledger-core.mjs';
 
 export const RECEIPTS_BASENAME = 'agent-workflow-review-receipts.jsonl';
 export const PLANS_REL = 'docs/plans';
@@ -290,29 +309,35 @@ export const readReceipts = (path, readFile = readFileSync) => {
   return { receipts, malformed };
 };
 
-// A receipt that can satisfy the tree check: a FRESH code-mode receipt for the current fingerprint.
-// Plan/diff-mode receipts and continuations are informational-only (see the header contract).
-const satisfies = (receipt, fingerprint) =>
-  receipt.fresh === true && receipt.artifact === 'code' && receipt.fingerprint === fingerprint;
-
-// Per-backend receipt status for the current fingerprint:
-//   current    — a satisfying receipt with grounded:true exists (its latest verdict reported);
-//   ungrounded — current-fingerprint fresh receipts exist but every one carries grounded:false;
+// Per-backend receipt status for the current fingerprint, over the ONE shared attesting-receipt
+// predicate (review-ledger-core) that the round cross-check and the round writer read too — two
+// gates disagreeing about what counts as an attestation is the class AD-050 closed:
+//   current    — an ATTESTING receipt exists (fresh code, probe:false, grounded) — its verdict rides;
+//   ungrounded — real (probe:false) current receipts exist but every one carries grounded:false;
+//   probe      — current receipts exist and EVERY one is a well-formed probe (D3);
+//   rejected   — current receipts exist, none attests, and >=1 marker was malformed or absent;
 //   stale      — this backend has receipts, none for the current fingerprint (edited after review);
-//   missing    — no usable receipt from this backend at all.
+//   missing    — no receipt from this backend at all.
+// The counts state what was dropped, so a PASS over a partially-excluded set still says so
+// (No-silent-failures) and the --json surface can show it.
 export const backendReceiptStatus = (receipts, backend, fingerprint) => {
   const own = receipts.filter((r) => r.backend === backend);
-  const current = own.filter((r) => satisfies(r, fingerprint));
-  const grounded = current.filter((r) => r.grounded === true);
-  if (grounded.length > 0) {
-    const latest = grounded[grounded.length - 1];
-    return { state: 'current', verdict: latest.verdict ?? 'unknown', grounded: true, timestamp: latest.timestamp ?? null };
+  const summary = summarizeReviewReceiptsForTree(own, fingerprint);
+  const counts = {
+    probeExcluded: summary.probeExcluded,
+    markerRejected: summary.markerRejected,
+    unmarkedRejected: summary.unmarkedRejected,
+  };
+  if (summary.state === 'current') {
+    return { state: 'current', verdict: summary.receipt.verdict ?? 'unknown', grounded: true, timestamp: summary.receipt.timestamp ?? null, ...counts };
   }
-  if (current.length > 0) {
-    const latest = current[current.length - 1];
-    return { state: 'ungrounded', verdict: latest.verdict ?? 'unknown', grounded: false, timestamp: latest.timestamp ?? null };
+  if (summary.state === 'ungrounded') {
+    return { state: 'ungrounded', verdict: summary.receipt.verdict ?? 'unknown', grounded: false, timestamp: summary.receipt.timestamp ?? null, ...counts };
   }
-  return { state: own.length > 0 ? 'stale' : 'missing', verdict: null, grounded: null, timestamp: null };
+  if (summary.state === 'probe' || summary.state === 'rejected') {
+    return { state: summary.state, verdict: null, grounded: null, timestamp: null, ...counts };
+  }
+  return { state: own.length > 0 ? 'stale' : 'missing', verdict: null, grounded: null, timestamp: null, ...counts };
 };
 
 // ── the degraded exemption (AD-050): read the review-ledger for a recorded current-tree degrade ────
@@ -411,6 +436,17 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, ls
   };
 };
 
+// Why a backend's current-tree receipts were all rejected — the two causes read differently and
+// have different recoveries (fix the file vs refresh the bridge), so they are never collapsed.
+const rejectionCause = (b) => {
+  const parts = [];
+  if (b.markerRejected > 0) parts.push(`${b.markerRejected} with a malformed probe marker`);
+  if (b.unmarkedRejected > 0) {
+    parts.push(`${b.unmarkedRejected} with no probe marker — silence is not a declaration, so the probe status is untrustworthy; re-run the review with a bridge that marks its runs`);
+  }
+  return parts.join(' + ');
+};
+
 // The normative --check decision (the header contract, in order). → { code, reason }.
 export const decideCheck = (state) => {
   // A DETECTOR FAILURE is unknown state, not "no reviewer ready" — the advisory tools warn and
@@ -449,23 +485,37 @@ export const decideCheck = (state) => {
   // stays verdict-blind: the exemption proves the degrade was RECORDED, never that the tree converged.
   const exempt = new Set(state.degradedExempt);
   const failing = state.backends.filter((b) => b.state !== 'current' && !exempt.has(b.backend));
+  // A receipt dropped for an untrustworthy probe marker is never silently dropped either (D3): it
+  // cannot fail a tree that other receipts satisfy, but a report over a partially-rejected set says
+  // so. It counts only the exclusions NOT already named per backend — a FAILING `rejected` backend
+  // prints its own cause below, and repeating it in the summary is noise. Every other exclusion (a
+  // partial one on a satisfied backend, or one on a degraded-exempt backend) still needs a voice.
+  const namedPerBackend = new Set(failing.filter((b) => b.state === 'rejected').map((b) => b.backend));
+  const untrustedTotal = state.backends
+    .filter((b) => !namedPerBackend.has(b.backend))
+    .reduce((n, b) => n + (b.markerRejected ?? 0) + (b.unmarkedRejected ?? 0), 0);
+  const markerNote = untrustedTotal > 0
+    ? ` — ${untrustedTotal} receipt(s) rejected: an untrustworthy probe marker (malformed, or absent — silence is not a declaration) — fail-closed; inspect ${state.receiptsPath}`
+    : '';
   if (failing.length === 0) {
     if (exempt.size === 0) {
-      return { code: 0, reason: `every recipe-named backend has a fresh grounded receipt for the current tree (${state.requiredBackends.join(' + ')})${malformedNote}${ledgerNote}` };
+      return { code: 0, reason: `every recipe-named backend has a fresh grounded receipt for the current tree (${state.requiredBackends.join(' + ')})${markerNote}${malformedNote}${ledgerNote}` };
     }
-    return { code: 0, reason: `every recipe-named backend reviewed the current tree (${state.requiredBackends.join(' + ')}) — degraded-exempt (recorded degraded for the current tree in the review ledger): ${[...exempt].join(', ')}${malformedNote}${ledgerNote}` };
+    return { code: 0, reason: `every recipe-named backend reviewed the current tree (${state.requiredBackends.join(' + ')}) — degraded-exempt (recorded degraded for the current tree in the review ledger): ${[...exempt].join(', ')}${markerNote}${malformedNote}${ledgerNote}` };
   }
   const parts = failing.map((b) => {
     if (b.state === 'ungrounded') return `${b.backend}: only ungrounded receipts for the current tree — re-run grounded (--facts)`;
+    if (b.state === 'probe') return `${b.backend}: only probe receipts for the current tree (CODEX_PROBE=1 / AGY_PROBE=1 relaxes the quality guards) — a probe review never attests; re-run a real one`;
+    if (b.state === 'rejected') return `${b.backend}: current-tree receipts rejected — ${rejectionCause(b)} (fail-closed); inspect ${state.receiptsPath}`;
     if (b.state === 'stale') return `${b.backend}: receipts exist but none matches the current tree (edited after review) — run a fresh review`;
     return `${b.backend}: no receipt — run its review wrapper`;
   });
-  return { code: 1, reason: `${parts.join('; ')}${malformedNote}${ledgerNote}` };
+  return { code: 1, reason: `${parts.join('; ')}${markerNote}${malformedNote}${ledgerNote}` };
 };
 
 // ── rendering ───────────────────────────────────────────────────────────────────────
 
-const STATE_GLYPH = { current: '✓', ungrounded: '✗', stale: '✗', missing: '✗' };
+const STATE_GLYPH = { current: '✓', ungrounded: '✗', probe: '✗', rejected: '✗', stale: '✗', missing: '✗' };
 
 const formatHuman = (state, check) => {
   const src = state.resolved.source === 'config' ? `from ${CONFIG_REL}` : 'computed default';
@@ -488,10 +538,17 @@ const formatHuman = (state, check) => {
         ? `current (verdict: ${b.verdict}, grounded, ${b.timestamp ?? '?'})`
         : b.state === 'ungrounded'
           ? `ungrounded for the current tree (verdict: ${b.verdict}) — a grounded fresh run is required`
-          : b.state === 'stale'
-            ? 'stale — no receipt matches the current tree (edited after review)'
-            : 'missing — no receipt from this backend';
-    lines.push(`    ${exempt.has(b.backend) ? '⊘' : STATE_GLYPH[b.state]} ${b.backend}: ${detail}${exemptTag}`);
+          : b.state === 'probe'
+            ? 'only probe receipts for the current tree (quality guards relaxed) — a probe review never attests'
+            : b.state === 'rejected'
+              ? `current-tree receipts rejected — ${rejectionCause(b)} (fail-closed)`
+              : b.state === 'stale'
+                ? 'stale — no receipt matches the current tree (edited after review)'
+                : 'missing — no receipt from this backend';
+    const excludedTag = b.probeExcluded || b.markerRejected || b.unmarkedRejected
+      ? ` [excluded: ${b.probeExcluded} probe, ${b.markerRejected} malformed-marker, ${b.unmarkedRejected} unmarked]`
+      : '';
+    lines.push(`    ${exempt.has(b.backend) ? '⊘' : STATE_GLYPH[b.state]} ${b.backend}: ${detail}${excludedTag}${exemptTag}`);
   }
   lines.push(`  check: ${check.code === 0 ? 'PASS' : 'FAIL'} — ${check.reason}`);
   return lines.join('\n');
@@ -507,7 +564,11 @@ recomputes the canonical uncommitted-state fingerprint (staged + unstaged + untr
 the review-payload domain), reads the receipt file the review wrappers append to
 (<git dir>/${RECEIPTS_BASENAME}; AW_REVIEW_RECEIPTS overrides), and reports per-backend receipt
 presence + verdict + grounding for the CURRENT tree. Plan/diff-mode receipts and continuations
-(fresh:false) are informational-only — they never satisfy the tree check.
+(fresh:false) are informational-only — they never satisfy the tree check, and neither does a PROBE
+receipt (probe:true — a CODEX_PROBE=1 / AGY_PROBE=1 run has the quality guards off). The probe
+filter is per receipt, so a real receipt at the same fingerprint still satisfies. Every marker-aware
+wrapper writes the probe field on EVERY review (true or false), so a malformed OR absent marker is
+rejected fail-closed — silence is not a declaration.
 
 --check exits 0/1 per the normative contract in the tool header: 0 for solo / no plan in flight /
 a clean tree / not-a-git-tree / all recipe-named backends receipted-current-and-grounded OR

package/tools/setup-backends.mjs

@@ -31,7 +31,7 @@ import { join, resolve, relative, dirname, isAbsolute } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import os from 'node:os';
 import { KNOWN_BACKENDS, detectBackend, detectBackends, resolveDir, guideFor, READY } from './detect-backends.mjs';
-import { copyTreeRefresh, linkManaged } from './fs-safe.mjs';
+import { copyTreeRefresh, linkManaged, isReadonlyWriteBoundary } from './fs-safe.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { compareSemver } from './semver-lite.mjs';
 
@@ -54,6 +54,12 @@ export const SETUP_STOP = 'SETUP_STOP';
 const stop = (message, fields = {}) =>
   Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'SetupStop', code: SETUP_STOP, ...fields });
 
+// A refresh-only outcome (REFRESH-EROFS-HONESTY / AD-056): an equal-version repair-on-rerun whose
+// write hit a READ-ONLY skills dir. A STATED skip (exit 0), never a false "could not refresh" — the
+// versions are already current and `setup` would hit the same read-only dir. Doc-parity binds this
+// token into references/modes/setup.md + upgrade.md so the mode contracts track the constant.
+export const SKIPPED_READONLY = 'skipped-readonly';
+
 // ── injectable fs ──────────────────────────────────────────────────────────────
 
 const fsDeps = (deps = {}) => ({
@@ -557,13 +563,42 @@ const refreshSkillOnly = (entry, deps = {}) => {
   const fresh = inspectSkillDir(entry, deps);
   if (fresh.action !== 'refresh') return { refreshed: false, drift: null };
   assertNoDowngrade(fresh, deps);
-  const drift = copyBridgeWithHonesty('refresh', fresh.bundleDir, fresh.skillDir, deps);
-  return { refreshed: true, drift };
+  // D1b: version equality for the read-only degrade is decided from the APPLY-TIME fresh inspection's
+  // fields (never the stale pre-apply plan) — both versions KNOWN and equal; two unknowns are not equal.
+  // assertNoDowngrade just read the bundled manifest, so this read cannot throw here; a versionless
+  // manifest yields null (never "equal" → no false skip).
+  const bundledManifest = readBundledManifest(fresh.bundleDir, deps);
+  const bundledVersion = typeof bundledManifest.version === 'string' ? bundledManifest.version : null;
+  const placedVersion = readPlacedVersionSafe(fresh.skillDir, deps);
+  const currentEqual = bundledVersion !== null && placedVersion === bundledVersion;
+  try {
+    const drift = copyBridgeWithHonesty('refresh', fresh.bundleDir, fresh.skillDir, deps);
+    return { refreshed: true, drift };
+  } catch (err) {
+    // D1/D1a: ONLY a read-only WRITE-boundary failure at an EQUAL version is a repair-on-rerun that
+    // cannot run — a STATED skip, never a false "could not refresh". Every other failure stays loud
+    // (a read-side / source-side / EIO failure, or a version-behind upgrade, re-throws here).
+    if (currentEqual && isReadonlyWriteBoundary(err)) return { refreshed: false, skippedReadonly: true, version: bundledVersion };
+    throw err;
+  }
 };
 
 const NOT_PLACED_LINE = 'skipped — not placed (placement is opt-in: /agent-workflow-kit setup)';
 const stripPrefix = (message) => message.replace('[agent-workflow-kit] ', '');
 
+// The read-only degrade wording (D1). The STATED-skip line: version current + the re-sync
+// skipped/incomplete + the read-only cause + the residual — it never claims a re-sync RAN (that is
+// already-current's line) nor file integrity (a partial copy may have happened before the throw). The
+// FAILED line (a version-behind upgrade blocked by the same read-only dir) stays loud, but its
+// recovery points at a writable rerun — the in-session `setup` would hit the same read-only dir.
+const READONLY_RERUN_HINT = 're-run the refresh from a writable session (e.g. outside the read-only sandbox)';
+const skippedReadonlyLine = (name, version) =>
+  `  ${name}: already current${version ? ` (v${version})` : ''} — the re-sync was skipped/incomplete: ` +
+  `the skills directory is read-only this session (the tree may be PARTIALLY updated). Repair-on-rerun cannot ` +
+  `run here; any remaining drift persists until you ${READONLY_RERUN_HINT}.`;
+const readonlyRefreshFailedLine = (name, message) =>
+  `  ${name}: could not refresh — ${stripPrefix(message)}; the skills directory is read-only this session — ${READONLY_RERUN_HINT}`;
+
 // Refresh every ALREADY-PLACED bridge from the kit's bundled copies and re-link its wrappers (a newer
 // bridge can add one). One reported outcome per backend — never a crash; a per-backend STOP/error
 // becomes a `failed` result. `line` is the tool-composed sentence callers print VERBATIM (the agent
@@ -592,6 +627,11 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
         return { name: plan.name, outcome: 'failed', line: `  ${plan.name}: could not refresh — ${stripPrefix(plan.reason)}; recover with /agent-workflow-kit setup` };
       }
       const refresh = refreshSkillOnly(registryEntry(plan.name), deps);
+      // A read-only skills dir at an EQUAL version is a STATED skip (repair-on-rerun cannot run here) —
+      // never a false "could not refresh" and never a failure exit (D1/AD-056).
+      if (refresh.skippedReadonly) {
+        return { name: plan.name, outcome: SKIPPED_READONLY, line: skippedReadonlyLine(plan.name, refresh.version) };
+      }
       if (!refresh.refreshed) {
         return { name: plan.name, outcome: 'not-placed', line: `  ${plan.name}: ${NOT_PLACED_LINE}` };
       }
@@ -615,6 +655,11 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
       if (err.wouldDowngrade) {
         return { name: canonical, outcome: 'kept-newer', line: `  ${canonical}: skipped — ${stripPrefix(err.message)}` };
       }
+      // A read-only WRITE failure on a version-BEHIND (upgrade) refresh stays a loud failure — but the
+      // in-session "recover with setup" would hit the same read-only dir, so point at a writable rerun.
+      if (isReadonlyWriteBoundary(err)) {
+        return { name: canonical, outcome: 'failed', line: readonlyRefreshFailedLine(canonical, err.message) };
+      }
       return { name: canonical, outcome: 'failed', line: `  ${canonical}: could not refresh — ${stripPrefix(err.message)}; recover with /agent-workflow-kit setup` };
     }
   });