@sabaiway/agent-workflow-kit 5.6.0 → 5.8.0

package/tools/refresh-parity.mjs

@@ -0,0 +1,263 @@
+// refresh-parity.mjs — the ONE bundle↔placed comparison walk, plus the POST-FAILURE parity reading
+// of its result (feedback-hardening Plan 1 F3 / D3+D4).
+//
+// Two callers read the SAME walk for two different questions, so there is exactly one scanner:
+//   • the refresh itself asks "what did my overwrite replace?" — it scans BEFORE copying, and an
+//     absent placed file is a pure ADD (nothing local to lose), so it is not reported;
+//   • the read-only degrade asks "does the placed tree still MATCH the bundle?" — it scans AFTER the
+//     write was refused, and an absent placed file is exactly the drift a writable rerun repairs.
+// The walk therefore reports FOUR buckets (drifted / unreadable / absent / conflicts) and each
+// caller decides what they mean. A second scanner would be a second definition of "the same".
+//
+// Why the honesty bar (D4): the read-only skip line used to claim, unconditionally, that the tree
+// "may be PARTIALLY updated" and that "any remaining drift persists" — two claims about post-state
+// that nothing had checked. Every clause a line here composes binds to a state PROVEN this run: the
+// verdict is computed from a real re-scan, and anything the re-scan could not read WITHHOLDS the calm
+// claim (reported as could-not-verify) instead of being rendered as clean.
+//
+// The wrapper axis is part of the claim on purpose: the degrade returns before the caller's
+// linkWrappers step, so a "nothing to repair" that only looked at files would be an unproven claim
+// about a reconcile that never ran.
+//
+// Pure of process state and of the kit's own writers — a LEAF (fs is injected, nothing is imported
+// from the caller). Read-only: never writes, never spawns. Dependency-free, Node >= 22.
+
+import { join, resolve, relative, dirname, isAbsolute, sep } from 'node:path';
+
+// The CLOSED parity verdict vocabulary — the three states the read-only skip line may report.
+// doc-parity binds every value into the setup + upgrade mode contracts, so a doc that drops or
+// renames an outcome fails a declared gate instead of describing a verdict the tool never emits.
+export const PARITY = Object.freeze({
+  clean: 'clean-parity',
+  drifted: 'drifted',
+  unverifiable: 'unverifiable',
+});
+
+// The recovery every read-only outcome points at: the in-session `setup` would hit the same read-only
+// dir, so the only real repair is a writable session. Shared by the skip line and the (unchanged)
+// version-behind failure line, so the two can never drift apart.
+export const READONLY_RERUN_HINT = 're-run the refresh from a writable session (e.g. outside the read-only sandbox)';
+
+// The mode a managed wrapper source carries — the ONE definition, imported by the link step that
+// chmods it and by the parity check that reads it back. "Executable enough" is not parity: a rerun
+// sets exactly this, so any other mode is a state the rerun would change.
+export const WRAPPER_MODE = 0o755;
+
+// lstat NO-FOLLOW, classified: the Stats object | 'absent' (ENOENT) | 'error' (any other fs failure).
+// Never reads THROUGH the node — a symlinked placed path is a "could not compare", never a read of
+// whatever it points at.
+const probe = (path, fs) => {
+  try {
+    return fs.lstat(path);
+  } catch (err) {
+    return err && err.code === 'ENOENT' ? 'absent' : 'error';
+  }
+};
+
+// The reconcile-set walk: every bundle-owned node, classified by WHAT THE REFRESH COULD DO TO IT —
+// not by whether this scanner could read it. The distinction is the whole point: "I could not compare
+// this" and "the refresh cannot bring this to the required state" are different facts with different
+// recoveries, and the earlier shape collapsed them.
+//
+// The writer's own policy decides the partition. copyTreeRefresh guards EVERY dest through
+// assertContainedRealPath, whose walk includes the LEAF — so any placed symlink on a node in the
+// reconcile-set is refused before the copy dispatch is even reached. Past that guard: a bundled
+// symlink is ADDITIVE (created when the dest is absent, otherwise left alone — an explicit no-op, not
+// a comparison), a bundled directory is mkdir -p (EEXIST over a file), a bundled file is copyFile
+// (EISDIR over a directory; a device or FIFO may be WRITTEN INTO or block rather than be replaced).
+// The BUNDLE read is our own shipped artifact — a failure there is a loud corrupt-kit error upstream
+// (never swallowed here); only the PLACED read is caught. Buckets, each sorted:
+//   drifted    — placed bytes differ from the bundle; a rerun overwrites them
+//   absent     — the bundle ships it and the placed tree does not; a rerun creates it
+//   conflicts  — a rerun cannot be GUARANTEED to converge this node under the writer's no-follow /
+//                ownership policy (any placed symlink; an incompatible shape). Labeled with the cause
+//   unreadable — a genuine read/stat error, and nothing else
+// Plus `modes`: the placed mode of every node the walk actually reached as a regular file. It exists
+// so the wrapper axis can judge a source's mode WITHOUT a second lstat of its own — a separate stat
+// could traverse a symlinked ancestor this walk already refused, and produce a contradicting verdict.
+export const scanBundleOwnedDrift = (bundleDir, skillDir, fs) => {
+  const drifted = [];
+  const unreadable = [];
+  const absent = [];
+  const conflicts = [];
+  const modes = new Map();
+  const refuse = (rel, cause) => conflicts.push(`${rel} (${cause})`);
+  const walk = (rel) => {
+    const src = join(bundleDir, rel);
+    const dest = join(skillDir, rel);
+    const st = fs.lstat(src);
+    const placed = rel === '' ? null : probe(dest, fs);
+    // The skill dir itself (rel '') is the caller's own inspected root — it proved that node is a real
+    // directory before any of this ran. Every node BELOW it meets the containment guard first, and the
+    // guard refuses a symlink at the leaf just as it does at an ancestor.
+    if (placed === 'error') {
+      unreadable.push(rel);
+      return;
+    }
+    if (placed !== null && placed !== 'absent' && placed.isSymbolicLink()) {
+      refuse(rel, 'a symlink is in the way');
+      return;
+    }
+    if (st.isSymbolicLink()) {
+      // ADDITIVE by contract: created when absent, otherwise left alone WITHOUT comparison. A node
+      // left alone is outside every claim this scan makes — it is neither drift nor a finding.
+      if (placed === 'absent') absent.push(rel);
+      return;
+    }
+    if (st.isDirectory()) {
+      if (placed !== null && placed !== 'absent' && !placed.isDirectory()) {
+        refuse(rel, 'a non-directory is in the way');
+        return;
+      }
+      const entries = fs.readdir(src);
+      // An EMPTY bundled dir names nothing below it, so its absence would go unreported — record the
+      // dir itself. A NON-empty one is already named by its children; recording it too would
+      // double-report one absence.
+      if (placed === 'absent' && entries.length === 0) absent.push(rel);
+      for (const entry of entries) walk(rel ? join(rel, entry) : entry);
+      return;
+    }
+    if (placed === 'absent') {
+      absent.push(rel);
+      return;
+    }
+    if (!placed.isFile()) {
+      refuse(rel, 'a node of the wrong kind is in the way');
+      return;
+    }
+    if (typeof placed.mode === 'number') modes.set(rel, placed.mode);
+    const srcBytes = fs.readFile(src);
+    const destBytes = (() => {
+      try {
+        return fs.readFile(dest);
+      } catch {
+        unreadable.push(rel);
+        return null;
+      }
+    })();
+    if (destBytes === null) return;
+    if (!Buffer.from(srcBytes).equals(Buffer.from(destBytes))) drifted.push(rel);
+  };
+  walk('');
+  return {
+    drifted: drifted.sort(), unreadable: unreadable.sort(), absent: absent.sort(), conflicts: conflicts.sort(), modes,
+  };
+};
+
+// A wrapper has TWO axes the link step touches — the LINK, which lives outside the bundle tree, and
+// the SOURCE, which does not. Each outcome is `null` (nothing to say) or a `[bucketName, cause]`
+// tuple the caller files under that bucket, labeled by axis: a wrapper broken on one axis and
+// unknown on the other rides BOTH lists rather than losing a fact the re-scan proved.
+const WRAPPER_CLEAN = null;
+
+// The link: absent is repairable (the link step creates it); anything else standing there is a
+// refusal (linkManaged replaces ONLY a symlink already pointing at our source). Never follows a
+// foreign link — readlink, then a string compare against the SAME physical base the writer uses:
+// linkWrappers canonicalises the bindir through realpath before linking, so a relative target read
+// from a symlinked bindir must resolve against the real directory or the two would disagree. A
+// realpath failure is could-not-verify with NO lexical fallback — falling back could call a foreign
+// link ours.
+const wrapperDstOutcome = (link, fs) => {
+  const dstStat = probe(link.dst, fs);
+  if (dstStat === 'error') return ['unverifiable', 'its link could not be read'];
+  if (dstStat === 'absent') return ['drifted', 'not linked'];
+  if (!dstStat.isSymbolicLink()) return ['conflicts', 'a non-symlink is in the way'];
+  let target;
+  try {
+    target = fs.readlink(link.dst);
+  } catch {
+    return ['unverifiable', 'its link target could not be read'];
+  }
+  let resolved;
+  if (isAbsolute(target)) resolved = target;
+  else {
+    try {
+      resolved = resolve(fs.realpath(dirname(link.dst)), target);
+    } catch {
+      return ['unverifiable', 'its link directory could not be resolved'];
+    }
+  }
+  return resolved === resolve(link.source) ? WRAPPER_CLEAN : ['conflicts', 'a foreign symlink is in the way'];
+};
+
+// The source is a BUNDLE-OWNED file (deriveLinks resolves it inside the skill dir and planFor proves
+// the bundle ships it), so the reconcile-set walk already classified its existence and its shape and
+// already named it if anything was wrong. This axis therefore owns exactly ONE fact the walk does not
+// compare: the mode. A node the walk never reached — absent, refused, or unreadable — yields nothing
+// here, so one broken file is never reported twice under two different names.
+const wrapperSourceOutcome = (link, skillDir, modes) => {
+  const rel = relative(skillDir, link.source).split(sep).join('/');
+  if (!modes.has(rel)) return WRAPPER_CLEAN;
+  return (modes.get(rel) & 0o7777) === WRAPPER_MODE ? WRAPPER_CLEAN : ['drifted', 'its source mode differs'];
+};
+
+export const scanWrapperParity = (links, fs, { skillDir, modes }) => {
+  const out = { drifted: [], conflicts: [], unverifiable: [] };
+  for (const link of links ?? []) {
+    for (const outcome of [wrapperDstOutcome(link, fs), wrapperSourceOutcome(link, skillDir, modes)]) {
+      if (outcome === WRAPPER_CLEAN) continue;
+      const [bucket, cause] = outcome;
+      out[bucket].push(`wrapper ${link.cmd} (${cause})`);
+    }
+  }
+  return { drifted: out.drifted.sort(), conflicts: out.conflicts.sort(), unverifiable: out.unverifiable.sort() };
+};
+
+// The ONE verdict the line is composed from. `clean-parity` requires EVERY list empty — any node the
+// re-scan could not compare withholds the calm claim rather than being counted as equal. `drifted` is
+// the headline whenever something is provably wrong (repairable or refused): a proven break outranks
+// an unknown, and the line still names every list, so no proven fact is collapsed into another.
+export const parityVerdict = ({ scan, wrappers }) => {
+  const drifted = [...scan.drifted, ...scan.absent, ...wrappers.drifted].sort();
+  const conflicts = [...scan.conflicts, ...wrappers.conflicts].sort();
+  const unverifiable = [...scan.unreadable, ...wrappers.unverifiable].sort();
+  const broken = drifted.length > 0 || conflicts.length > 0;
+  const state = broken ? PARITY.drifted : unverifiable.length > 0 ? PARITY.unverifiable : PARITY.clean;
+  return { state, drifted, conflicts, unverifiable };
+};
+
+// The verdict a caller reports when the re-scan itself could not run (a corrupt/unreadable bundle,
+// any fs failure raised out of the walk). Could-not-verify is the honest floor — never a false clean.
+export const unverifiableParity = (item) => ({ state: PARITY.unverifiable, drifted: [], conflicts: [], unverifiable: [item] });
+
+const count = (items) => `${items.length} item(s)`;
+
+// The read-only skip line (outcome `skipped-readonly`, exit 0 — the stated skip). Two clauses are
+// proven by the caller before it composes: the versions are KNOWN equal, and the failure was tagged
+// at a WRITE boundary. Every remaining clause comes from the verdict — no clause without its check,
+// and every item the verdict carries is NAMED (a count alone would not tell the user what to look at).
+export const readonlySkipLine = (name, version, verdict) => {
+  const head = `  ${name}: already current${version ? ` (v${version})` : ''} — the file re-sync could not write: ` +
+    'the skills directory is read-only this session.';
+  if (verdict.state === PARITY.clean) {
+    // The claim is scoped to what the refresh MANAGES, and it names each checked axis rather than
+    // generalising: a rerun would still rewrite byte-equal files (so "nothing would change" would be
+    // false), a placed-only extra is preserved and never in scope, and an additive node the writer
+    // leaves alone is outside the comparison by contract.
+    return `${head} A read-only re-scan found no refresh-managed difference to repair: every file the ` +
+      'refresh would overwrite already matches, every node it would add is present, and every wrapper ' +
+      'link and source mode is in place.';
+  }
+  // One sentence per non-empty list, each carrying the recovery that actually applies to it: the
+  // writable rerun REPAIRS the drifted set, and REFUSES the conflicting set — one blanket "re-run to
+  // repair" over both would promise a repair that never happens.
+  const said = [];
+  if (verdict.drifted.length > 0) {
+    said.push(`A read-only re-scan found ${count(verdict.drifted)} still differing from the bundled copy: ` +
+      `${verdict.drifted.join(', ')} — ${READONLY_RERUN_HINT} to repair.`);
+  }
+  if (verdict.conflicts.length > 0) {
+    said.push(`${said.length > 0 ? 'It also found' : 'A read-only re-scan found'} ${count(verdict.conflicts)} a ` +
+      `writable rerun would REFUSE rather than repair: ${verdict.conflicts.join(', ')} — resolve each by hand, ` +
+      'then re-run the refresh.');
+  }
+  if (verdict.unverifiable.length > 0) {
+    // The unknown-need clause and its recovery ride EVERY unverifiable outcome, not only the one
+    // that happens to open the line: a reader who already saw a drift sentence would otherwise be
+    // left with a list of names and no statement of what is unknown about them or what to do.
+    const lead = said.length > 0 ? 'It could not verify a further' : 'A read-only re-scan could NOT verify';
+    said.push(`${lead} ${count(verdict.unverifiable)}: ${verdict.unverifiable.join(', ')} — whether those ` +
+      `still need repair is unknown; ${READONLY_RERUN_HINT}.`);
+  }
+  return `${head} ${said.join(' ')}`;
+};

package/tools/run-gates.mjs

@@ -140,7 +140,7 @@ const USAGE = [
   'exported to every gate child, and STRIPPED from the inherited environment first — a host-set',
   'value never stands in for a computed one. A selected gate referencing a producer variable this',
   'run will not set is refused BEFORE anything spawns (exit 1), naming the gate, the variable, and',
-  'the remedy — never left to expand to empty and fail far from its cause.',
+  'the remedy — never left to run without the runner-produced value.',
   'Sandbox-safe: the runner itself needs no network and writes only repo-local state — the D4 sandbox',
   'lane; each DECLARED gate command is the project\'s own, so ITS sandbox-safety is command-shape',
   'dependent (first try the sandbox-safe shape — cache under $TMPDIR, offline/notifier off).',
@@ -197,9 +197,12 @@ export const spawnGateViaBash = (cmd, cwd, extraEnv = {}) => {
   return spawnSync('bash', ['-c', cmd], { cwd, env: { ...env, ...extraEnv }, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
 };
 
-// A `$VAR` / `${VAR}` reference to a producer variable. A `${VAR:-default}` form is deliberately NOT
-// matched — a cmd carrying its own fallback does not depend on the injection.
-const referencesProducer = (cmd, name) => new RegExp(`\\$\\{${name}\\}|\\$${name}(?![A-Za-z0-9_])`).test(cmd);
+// A `$VAR` / `${VAR}` / `${VAR:?word}` reference to a producer variable. The required-parameter form
+// is the canonical producer destination: it makes an uninjected expansion fail BY NAME instead of
+// writing under an empty prefix, and it still depends on the injection — so it must refuse here,
+// pre-spawn, rather than dying inside a gate child far from its cause. A `${VAR:-default}` form
+// stays deliberately unmatched — a cmd carrying its own fallback does not depend on the injection.
+const referencesProducer = (cmd, name) => new RegExp(`\\$\\{${name}(?:\\}|:\\?)|\\$${name}(?![A-Za-z0-9_])`).test(cmd);
 
 const PRODUCER_RECOVERY = Object.freeze({
   AW_GIT_DIR: 'run from inside a git work tree — the runner resolves the git dir there and exports it to every gate.',
@@ -609,7 +612,7 @@ export const runCli = (argv, deps = {}) => {
     const unmet = findUnmetProducerRefs(selected, injectedEnv);
     if (unmet.length > 0) {
       for (const { id, name } of unmet) {
-        logError(`[run-gates] gate "${id}" references $${name}, which this run will not set — it would expand to empty and fail far from its cause.`);
+        logError(`[run-gates] gate "${id}" references $${name}, which this run will not set — the child would run without the runner-produced value.`);
         logError(`   Recovery: ${PRODUCER_RECOVERY[name]}`);
       }
       releaseSubsetRunLock();

package/tools/setup-backends.mjs

@@ -32,6 +32,10 @@ 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, isReadonlyWriteBoundary } from './fs-safe.mjs';
+import {
+  READONLY_RERUN_HINT, WRAPPER_MODE, scanBundleOwnedDrift, scanWrapperParity, parityVerdict,
+  unverifiableParity, readonlySkipLine,
+} from './refresh-parity.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { compareSemver } from './semver-lite.mjs';
 
@@ -113,62 +117,16 @@ const probeMarker = (file, fs) => {
 const SETTINGS_FILE_HINT = '${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf';
 const SETTINGS_CMD_HINT = '/agent-workflow-kit bridge-settings';
 
-// Bundle-owned regular files whose PLACED copy differs from the bundle (a local edit an equal-version
-// refresh would overwrite) or cannot be read (indeterminate — an honest degrade). Mirrors
-// copyTreeRefresh's src dispatch so it flags EXACTLY the files the overwrite touches: a symlink src is
-// additive (copyTreeRefresh skips an existing dest — never overwritten) and a dir recurses; a
-// bundled-only file (no placed copy) is a pure add, no loss. The BUNDLE read is our own shipped
-// artifact — a failure there is a loud corrupt-kit error upstream (never swallowed here); only the
-// PLACED read is caught (EACCES/EIO → 'unreadable', and the refresh still proceeds). Sorted output is
-// deterministic for the stated line. Exported for a direct unit test (the full driver cannot observe a
-// symlinked placed file — copyTreeRefresh refuses to overwrite one, so the refresh fails before any line).
-export const scanBundleOwnedDrift = (bundleDir, skillDir, fs) => {
-  const drifted = [];
-  const unreadable = [];
-  const walk = (rel) => {
-    const src = join(bundleDir, rel);
-    const dest = join(skillDir, rel);
-    const st = fs.lstat(src);
-    if (st.isSymbolicLink()) return;
-    if (st.isDirectory()) {
-      for (const entry of fs.readdir(src)) walk(rel ? join(rel, entry) : entry);
-      return;
-    }
-    // lstat the PLACED path NO-FOLLOW first — never read THROUGH a symlink (copyTreeRefresh's
-    // assertContainedRealPath would refuse to overwrite a symlinked dest, so reading its target here
-    // would be both unsafe and moot). Absent → a bundled-only addition (no local loss); a symlink /
-    // non-regular / unreadable placed node → "could not compare" without a read-through.
-    const destStat = (() => {
-      try {
-        return fs.lstat(dest);
-      } catch (err) {
-        return err && err.code === 'ENOENT' ? 'absent' : 'error';
-      }
-    })();
-    if (destStat === 'absent') return;
-    if (destStat === 'error' || destStat.isSymbolicLink() || !destStat.isFile()) {
-      unreadable.push(rel);
-      return;
-    }
-    const srcBytes = fs.readFile(src);
-    const destBytes = (() => {
-      try {
-        return fs.readFile(dest);
-      } catch {
-        unreadable.push(rel);
-        return null;
-      }
-    })();
-    if (destBytes === null) return;
-    if (!Buffer.from(srcBytes).equals(Buffer.from(destBytes))) drifted.push(rel);
-  };
-  walk('');
-  return { drifted: drifted.sort(), unreadable: unreadable.sort() };
-};
+// The bundle↔placed comparison walk lives in refresh-parity.mjs — ONE scanner, two readings (this
+// module's refresh-time drift report below, and the read-only degrade's post-failure parity verdict).
+// Re-exported so the scan's own unit tests and any consumer keep importing it from the writer they
+// already know. In THIS reading a bundled-only file (the scan's `absent` bucket) is a pure add — no
+// local loss — so `driftSummary` ignores it; the parity reading is the one that calls it drift.
+export { scanBundleOwnedDrift };
 
 // One user-facing sentence naming what an equal-version re-sync overwrote — or null when nothing local
 // was lost. Callers apply their own indent; the pointer names the settings file that survives a refresh.
-const driftSummary = (drift) => {
+export const driftSummary = (drift) => {
   if (!drift) return null;
   const parts = [];
   if (drift.drifted.length) parts.push(`overwrote ${drift.drifted.length} locally-changed file(s): ${drift.drifted.join(', ')}`);
@@ -284,6 +242,10 @@ export const deriveLinks = (manifest, skillDir) => {
 };
 
 // Classify a wrapper dst per-bindir (NOT PATH-wide): absent | ours (symlink → our source) | conflict.
+// A RELATIVE target resolves against the dst's PHYSICAL parent, because linkWrappers canonicalises the
+// bindir through realpath before it links: under a symlinked bindir (a common dotfiles setup) a
+// lexical base would answer a different question than the one the writer asks. A realpath failure is
+// a conflict, never a lexical fallback — the fallback could call a foreign link ours.
 const inspectDst = (dst, source, fs) => {
   const st = lstatNoFollow(dst, fs.lstat);
   if (st === null) return { state: 'absent' };
@@ -294,7 +256,15 @@ const inspectDst = (dst, source, fs) => {
   } catch (err) {
     return { state: 'conflict', reason: `unreadable symlink (${err.code ?? 'fs error'})` };
   }
-  const resolved = isAbsolute(target) ? target : resolve(dirname(dst), target);
+  let resolved;
+  if (isAbsolute(target)) resolved = target;
+  else {
+    try {
+      resolved = resolve(fs.realpath(dirname(dst)), target);
+    } catch (err) {
+      return { state: 'conflict', reason: `cannot resolve the link's directory (${err.code ?? 'fs error'})` };
+    }
+  }
   return resolved === resolve(source) ? { state: 'ours' } : { state: 'conflict', reason: `foreign symlink → ${target}` };
 };
 
@@ -378,7 +348,7 @@ export const linkWrappers = (skillDir, manifest, opts = {}) => {
   const realBindir = fs.realpath(bindir);
   const links = [];
   for (const { cmd, source } of derived) {
-    fs.chmod(source, 0o755);
+    fs.chmod(source, WRAPPER_MODE);
     const action = linkManaged(source, join(realBindir, cmd), realBindir, fs); // 'linked' | 'noop'
     links.push({ cmd, source, dst: join(bindir, cmd), action });
   }
@@ -586,19 +556,56 @@ const refreshSkillOnly = (entry, deps = {}) => {
 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}.`;
+// The read-only degrade wording (D1, honesty-split per D4). The STATED-skip line is composed in
+// refresh-parity.mjs from a POST-FAILURE re-scan: the old line asserted "PARTIALLY updated" and "any
+// remaining drift persists" unconditionally — two claims about post-state that nothing had checked.
+// It still never claims a re-sync RAN (that is already-current's line). 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 readonlyRefreshFailedLine = (name, message) =>
   `  ${name}: could not refresh — ${stripPrefix(message)}; the skills directory is read-only this session — ${READONLY_RERUN_HINT}`;
 
+// The per-bridge refresh outcome lines, one pure composer per outcome — the composed-lines guard
+// (test/composed-lines-ux.test.mjs) renders every key against the L2 user-grade invariants. `label`
+// is the pre-rendered version suffix (versionLabel); reasons arrive already prefix-stripped.
+export const REFRESH_LINES = Object.freeze({
+  unsupported: (name, reason) => `  ${name}: skipped — ${reason}`,
+  'kept-newer': (name, reason) => `  ${name}: skipped — ${reason}`,
+  'not-placed': (name) => `  ${name}: ${NOT_PLACED_LINE}`,
+  failed: (name, reason) => `  ${name}: could not refresh — ${reason}; recover with /agent-workflow-kit setup`,
+  'failed-readonly': readonlyRefreshFailedLine,
+  [SKIPPED_READONLY]: readonlySkipLine,
+  'already-current': (name, label, summary) => {
+    const base = `  ${name}: already current${label} — files re-synced from the bundled copy`;
+    return summary ? `${base}\n     ↳ ${summary}` : base;
+  },
+  refreshed: (name, label) => `  ${name}: refreshed${label}`,
+});
+
+// The post-failure parity verdict behind that line (D3): a read-only re-scan of the bundle-owned
+// files AND the wrapper links, run AFTER the write refusal, so every clause binds to state proven
+// THIS run. The degrade returns before linkWrappers, so the wrapper axis is genuinely unreconciled —
+// a calm claim that skipped it would be unproven. Any failure raised out of the walk itself (the
+// bundle read is deliberately uncaught in there) collapses to could-not-verify: the calm claim is
+// withheld, never inverted into a false clean, and a re-scan problem never turns the stated skip
+// into a reported failure.
+const readonlyParity = (plan, deps) => {
+  const fs = fsDeps(deps);
+  try {
+    // ONE walk feeds both halves: the wrapper axis judges a source's mode from what the walk already
+    // reached, never from a second stat that could traverse an ancestor the walk refused.
+    const scan = scanBundleOwnedDrift(plan.place.bundleDir, plan.skillDir, fs);
+    return parityVerdict({
+      scan,
+      wrappers: scanWrapperParity(plan.links, fs, { skillDir: plan.skillDir, modes: scan.modes }),
+    });
+  } catch (err) {
+    // The catch cannot know WHICH side raised (the walk reads the bundle and the placed tree), so it
+    // names the comparison, never a side — attributing it would be the same unproven claim one layer down.
+    return unverifiableParity(`the bundle/placed comparison (${err.code ?? 'fs error'})`);
+  }
+};
+
 // 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
@@ -612,55 +619,59 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
     try {
       const plan = planFor(name, deps);
       if (plan.outcome === 'unsupported') {
-        return { name: plan.name, outcome: 'unsupported', line: `  ${plan.name}: skipped — ${plan.reason}` };
+        return { name: plan.name, outcome: 'unsupported', line: REFRESH_LINES.unsupported(plan.name, plan.reason) };
       }
       if (plan.wouldDowngrade) {
-        return { name: plan.name, outcome: 'kept-newer', line: `  ${plan.name}: skipped — ${stripPrefix(plan.reason)}` };
+        return { name: plan.name, outcome: 'kept-newer', line: REFRESH_LINES['kept-newer'](plan.name, stripPrefix(plan.reason)) };
       }
       // An absent/empty skill dir is `not placed` REGARDLESS of any later plan trouble (a foreign
       // wrapper conflict, a bundle-source problem): the refresh-only driver skips an unplaced bridge
       // before those axes matter, so it must never claim "could not refresh" what it would not touch.
       if (plan.place && plan.place.action !== 'refresh') {
-        return { name: plan.name, outcome: 'not-placed', line: `  ${plan.name}: ${NOT_PLACED_LINE}` };
+        return { name: plan.name, outcome: 'not-placed', line: REFRESH_LINES['not-placed'](plan.name) };
       }
       if (plan.outcome === 'stop' || plan.outcome === 'error') {
-        return { name: plan.name, outcome: 'failed', line: `  ${plan.name}: could not refresh — ${stripPrefix(plan.reason)}; recover with /agent-workflow-kit setup` };
+        return { name: plan.name, outcome: 'failed', line: REFRESH_LINES.failed(plan.name, stripPrefix(plan.reason)) };
       }
       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) };
+        return {
+          name: plan.name,
+          outcome: SKIPPED_READONLY,
+          line: REFRESH_LINES[SKIPPED_READONLY](plan.name, refresh.version, readonlyParity(plan, deps)),
+        };
       }
       if (!refresh.refreshed) {
-        return { name: plan.name, outcome: 'not-placed', line: `  ${plan.name}: ${NOT_PLACED_LINE}` };
+        return { name: plan.name, outcome: 'not-placed', line: REFRESH_LINES['not-placed'](plan.name) };
       }
       const manifest = readBundledManifest(plan.place.bundleDir, deps);
       linkWrappers(plan.skillDir, manifest, { ...deps, bindir: plan.bindir, platform: plan.platform });
       const current = plan.version !== null && plan.priorVersion === plan.version;
       // The equal-version line still states the copy that ran (repair-on-rerun) — the tool never
       // reports a mutation-free "already current" while it re-synced files underneath.
-      const base = `  ${plan.name}: ${current ? `already current${versionLabel(plan)} — files re-synced from the bundled copy` : `refreshed${versionLabel(plan)}`}`;
       // Overwrite honesty (D5): only an EQUAL-version re-sync can prove a byte diff is a LOCAL edit —
       // a version upgrade's diffs are the version delta, which the (vOld → vNew) arrow already states.
-      const summary = current ? driftSummary(refresh.drift) : null;
       return {
         name: plan.name,
         outcome: current ? 'already-current' : 'refreshed',
-        line: summary ? `${base}\n     ↳ ${summary}` : base,
+        line: current
+          ? REFRESH_LINES['already-current'](plan.name, versionLabel(plan), driftSummary(refresh.drift))
+          : REFRESH_LINES.refreshed(plan.name, versionLabel(plan)),
       };
     } catch (err) {
       // A downgrade STOP raised at the write boundary (a newer bridge landed between plan and apply)
       // is the same stated skip as the planned one — classified structurally via the typed field.
       if (err.wouldDowngrade) {
-        return { name: canonical, outcome: 'kept-newer', line: `  ${canonical}: skipped — ${stripPrefix(err.message)}` };
+        return { name: canonical, outcome: 'kept-newer', line: REFRESH_LINES['kept-newer'](canonical, 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: REFRESH_LINES['failed-readonly'](canonical, err.message) };
       }
-      return { name: canonical, outcome: 'failed', line: `  ${canonical}: could not refresh — ${stripPrefix(err.message)}; recover with /agent-workflow-kit setup` };
+      return { name: canonical, outcome: 'failed', line: REFRESH_LINES.failed(canonical, stripPrefix(err.message)) };
     }
   });
 

package/tools/source-size-check.mjs

@@ -26,10 +26,9 @@
 // Exit codes: 0 green / 1 violation or refusal / 2 usage, config or enumeration error.
 // Dependency-free, Node >= 22. No side effects on import.
 
-import { fileURLToPath } from 'node:url';
-import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { assertDocsAiDeployment, writeDocsAiFileAtomic } from './atomic-write.mjs';
+import { isDirectRun, sameFile } from './direct-run.mjs';
 import {
   AUTHORED_KEYS,
   SOURCE_SIZE_CONFIG_REL,
@@ -299,20 +298,11 @@ export const main = (argv, ctx = {}) => {
   }
 };
 
-// Compared by REAL path, not lexically: ESM resolves a symlinked entry point to its target, so a
-// lexical comparison is false whenever the tool is invoked through a link — and a gate whose cmd
-// names a link would then exit 0 having run nothing, which reads as PASS.
-// Exported as a test seam (the coverage-check keyFor idiom): the unresolvable arm cannot be reached
-// through the CLI, where an existing entry point is a precondition of getting this far.
-export const sameFile = (a, b) => {
-  try {
-    return realpathSync(a) === realpathSync(b);
-  } catch {
-    return false;
-  }
-};
-const isDirectRun = Boolean(process.argv[1]) && sameFile(fileURLToPath(import.meta.url), process.argv[1]);
-if (isDirectRun) {
+// The realpath-compare direct-run predicate now lives in tools/direct-run.mjs (the fix this file
+// carried first, extracted so every module shares one implementation); `sameFile` stays exported here
+// because this module's tests bind it as a seam.
+export { sameFile };
+if (isDirectRun(import.meta.url)) {
   const result = main(process.argv.slice(2));
   if (result.stdout) process.stdout.write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
   if (result.stderr) process.stderr.write(result.stderr.endsWith('\n') ? result.stderr : `${result.stderr}\n`);

package/tools/source-size-core.mjs

@@ -7,7 +7,8 @@
 //   • source-size-refusal.mjs  — the two exit classes, and the absolute config path every refusal names
 //   • source-size-config.mjs   — the config file: its grammar, its four states, its reader
 //   • source-size-scope.mjs    — which files are judged (D-6) and how big each one is (D-7)
-//   • source-size-gate-cmd.mjs — whether a declared gate cmd IS this checker (the canonical matcher)
+//   • source-size-gate-cmd.mjs — whether a declared gate cmd IS this checker (the canonical matcher),
+//                                and which of the three tool claims it makes when it is not
 //
 // Re-export only: a consumer imports the practice, never a particular half, so a later split moves
 // code without touching a single call site.
@@ -48,6 +49,11 @@ export {
 export {
   SOURCE_SIZE_GATE_ID,
   SOURCE_SIZE_TOOL_PATH,
+  classifySourceSizeGate,
   dqUnsafePath,
   matchesSourceSizeGate,
 } from './source-size-gate-cmd.mjs';
+
+// The claim vocabulary itself — a consumer naming an outcome imports the name, never a string
+// literal it could misspell into a silently-never-true comparison.
+export { CHECKER_CLAIM } from './checker-claim.mjs';