@sabaiway/agent-workflow-kit 1.25.0 → 1.27.0

package/tools/run-gates.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+// run-gates.mjs — the generic project gate runner behind `/agent-workflow-kit gates`.
+//
+// A project declares its verification gates ONCE in docs/ai/gates.json (seeded from
+// references/templates/gates.json — the orchestration.json pattern: bootstrap seeds it, upgrade
+// ensures-if-missing, the file stays hand-editable). This runner batches them: read the
+// declaration, run each gate as ONE bash command line from the project root, print a per-gate
+// PASS/FAIL table plus ONE machine-readable summary line, and exit 0 iff every selected gate is
+// green. A failing gate's own output is preserved verbatim (triage without re-running); a green
+// gate's output is not echoed — the table + summary line are the report. `--only <id>`
+// (repeatable) re-runs a subset; an unknown id is a loud usage error.
+//
+// The declaration names WHAT to check — never who executes it: the schema has no lane/model/
+// routing fields and rejects unknown keys loudly. Trust posture (stated in the template _README
+// too): the runner executes the project's OWN declared commands with the caller's privileges —
+// a batching convenience over commands the project already runs by hand, not a sandbox.
+//
+// Honest outcomes — each distinct, never a silent green (the exit-code table + the summary-line
+// schema are pinned by run-gates.test.mjs):
+//   0 ok · 1 gate failure · 2 usage · 3 missing declaration · 4 empty gates list ·
+//   5 malformed/invalid declaration · 6 bash unavailable. Gate `cmd` lines are BASH command
+//   lines (brace/glob expansion); a host without bash gets the loud exit-6 preflight error,
+//   never a silent reinterpretation under another shell.
+//
+// The runner itself WRITES NOTHING. Dependency-free, Node >= 18. No side effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+// The per-project declaration (strict JSON, hand-editable). cwd-relative — errors show a path the
+// user can open (the orchestration-config CONFIG_REL idiom).
+export const GATES_REL = 'docs/ai/gates.json';
+
+// The full exit-code table — one distinct code per honest outcome (never a silent green).
+export const EXIT = Object.freeze({
+  ok: 0,
+  fail: 1,
+  usage: 2,
+  missing: 3,
+  empty: 4,
+  malformed: 5,
+  noBash: 6,
+});
+
+// A tagged failure carrying its process exit code (the shared orchestration-config idiom).
+export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+const GATE_ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const GATE_KEYS = Object.freeze(['id', 'title', 'cmd']);
+const NO_FAILED_IDS = '-';
+const SPAWN_FAILED_CODE = -1;
+const MAX_GATE_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+const USAGE = [
+  'usage: run-gates.mjs [--cwd <dir>] [--only <id>]... [--help]',
+  '',
+  `Runs the gates declared in <cwd>/${GATES_REL} (one bash command line each, project root as cwd).`,
+  'Prints a per-gate PASS/FAIL table + one machine-readable summary line; exit 0 iff all green.',
+  `Exit codes: 0 ok · 1 gate failure · 2 usage · 3 missing declaration · 4 empty gates list ·`,
+  '5 malformed/invalid declaration · 6 bash unavailable.',
+].join('\n');
+
+// ── declaration validation (malformed → exit 5, loud `path: reason`) ─────────────────
+
+// Validate a parsed gates.json object. Strict: only `_README` (string) + `gates` (array of
+// { id, title, cmd }) are allowed; unknown keys anywhere are rejected loudly — the declaration
+// names WHAT to check, never lanes/models/routing. Returns the validated gates array.
+export const validateDeclaration = (parsed) => {
+  const reject = (reason) => {
+    throw fail(EXIT.malformed, `${GATES_REL}: ${reason}`);
+  };
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    reject('must be a JSON object { "_README"?: string, "gates": [{ id, title, cmd }, ...] }');
+  }
+  for (const key of Object.keys(parsed)) {
+    if (key !== '_README' && key !== 'gates') reject(`unknown top-level key "${key}" (allowed: _README, gates)`);
+  }
+  if (parsed._README !== undefined && typeof parsed._README !== 'string') reject('"_README" must be a string');
+  if (!Array.isArray(parsed.gates)) reject('"gates" must be an array of { id, title, cmd }');
+  const seenIds = new Set();
+  parsed.gates.forEach((gate, index) => {
+    const at = `gates[${index}]`;
+    if (gate === null || typeof gate !== 'object' || Array.isArray(gate)) {
+      reject(`${at}: must be an object { id, title, cmd }`);
+    }
+    for (const key of Object.keys(gate)) {
+      if (!GATE_KEYS.includes(key)) {
+        reject(`${at}: unknown key "${key}" (allowed: id, title, cmd — gates declare WHAT to check, never lane/model/routing)`);
+      }
+    }
+    for (const key of GATE_KEYS) {
+      if (typeof gate[key] !== 'string' || gate[key].trim() === '') {
+        reject(`${at}: "${key}" must be a non-empty string`);
+      }
+    }
+    if (/[\r\n]/.test(gate.cmd)) {
+      reject(`${at}: "cmd" must be ONE bash command line — embedded newlines (a multi-line script) are rejected; chain with && or move the script into a file`);
+    }
+    if (!GATE_ID_RE.test(gate.id)) reject(`${at}: id "${gate.id}" must be kebab-case (lowercase [a-z0-9] groups separated by "-")`);
+    if (seenIds.has(gate.id)) reject(`${at}: duplicate id "${gate.id}"`);
+    seenIds.add(gate.id);
+  });
+  return parsed.gates;
+};
+
+// ── declaration IO ────────────────────────────────────────────────────────────────────
+
+// Load the declaration from <cwd>/docs/ai/gates.json. A truly-absent file is the DISTINCT
+// `missing` outcome (exit 3 upstream, with the recovery named) — never an error throw; anything
+// present-but-unreadable / malformed / schema-invalid throws the loud exit-5 failure. lstat does
+// not follow links, so a dangling symlink reads as present and its read failure surfaces loudly
+// (no-silent-failures Hard Constraint — the loadConfig idiom).
+export const loadDeclaration = (cwd, { readFile = readFileSync, lstat = lstatSync } = {}) => {
+  const full = join(cwd, GATES_REL);
+  try {
+    lstat(full);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { outcome: 'missing' };
+    throw fail(EXIT.malformed, `${GATES_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let raw;
+  try {
+    raw = readFile(full, 'utf8');
+  } catch (err) {
+    throw fail(EXIT.malformed, `${GATES_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw fail(EXIT.malformed, `${GATES_REL}: malformed JSON (${err.message})`);
+  }
+  return { outcome: 'loaded', gates: validateDeclaration(parsed) };
+};
+
+// ── gate selection (--only) ───────────────────────────────────────────────────────────
+
+// Resolve the `--only` subset against the declared gates: declaration order is preserved,
+// duplicates collapse, an unknown id is a LOUD usage error naming the declared ids.
+export const selectGates = (gates, onlyIds) => {
+  if (onlyIds.length === 0) return gates;
+  const declared = new Set(gates.map((gate) => gate.id));
+  const unknown = onlyIds.filter((id) => !declared.has(id));
+  if (unknown.length > 0) {
+    throw fail(
+      EXIT.usage,
+      `--only: unknown gate id(s): ${unknown.join(', ')} (declared: ${gates.map((gate) => gate.id).join(', ')})`,
+    );
+  }
+  const wanted = new Set(onlyIds);
+  return gates.filter((gate) => wanted.has(gate.id));
+};
+
+// ── the bash spawn (the ONE real-process boundary; injectable for hermetic tests) ─────
+
+// Spawn one gate cmd via bash from the project root. `cmd` is a BASH command line by contract
+// (the declaration's _README states it): this repo's own gate matrix needs brace+glob expansion,
+// which /bin/sh does not perform — hence bash explicitly, never the platform default shell.
+export const spawnGateViaBash = (cmd, cwd) =>
+  spawnSync('bash', ['-c', cmd], { cwd, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
+
+// The command the bash preflight runs before ANY gate: proves bash itself spawns on this host,
+// so "no bash" is one loud exit-6 error up front — never a per-gate spawn-failure cascade.
+export const BASH_PROBE_CMD = 'true';
+
+// ── run + report ──────────────────────────────────────────────────────────────────────
+
+const formatSeconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+const trimTrailingNewline = (text) => text.replace(/\n$/, '');
+
+// Run the selected gates sequentially (declaration order). A green gate logs one PASS line; a
+// failing gate logs FAIL + its captured stdout/stderr VERBATIM (triage without re-running).
+export const runGates = (gates, { cwd, spawn = spawnGateViaBash, now = Date.now, log = console.log }) => {
+  const results = [];
+  for (const gate of gates) {
+    log(`── ${gate.id} — ${gate.title}`);
+    const startedAt = now();
+    const res = spawn(gate.cmd, cwd);
+    const elapsedMs = now() - startedAt;
+    const spawnError = res.error ? `spawn error: ${res.error.code || res.error.message}` : null;
+    const ok = spawnError === null && res.status === 0;
+    const code = spawnError === null ? res.status : SPAWN_FAILED_CODE;
+    results.push({ id: gate.id, title: gate.title, ok, code, elapsedMs });
+    if (ok) {
+      log(`   PASS (${formatSeconds(elapsedMs)})`);
+    } else {
+      log(`   FAIL exit=${code} (${formatSeconds(elapsedMs)})`);
+      if (res.stdout) log(trimTrailingNewline(res.stdout));
+      if (res.stderr) log(trimTrailingNewline(res.stderr));
+      if (spawnError) log(`   ${spawnError}`);
+    }
+  }
+  return results;
+};
+
+// The per-gate PASS/FAIL table (printed after every gate ran — failures never stop the matrix).
+export const formatTable = (results) => {
+  const idWidth = Math.max(...results.map((result) => result.id.length), 'gate'.length);
+  const pad = (text) => text + ' '.repeat(idWidth - text.length);
+  const lines = ['', `${pad('gate')}  result`];
+  for (const result of results) {
+    lines.push(`${pad(result.id)}  ${result.ok ? 'PASS' : `FAIL (exit ${result.code})`}`);
+  }
+  return lines;
+};
+
+// The ONE machine-readable summary line — always the LAST line printed for every non-usage
+// outcome. Schema (pinned by tests): status ∈ ok|fail|missing|empty|malformed|no-bash.
+export const composeSummaryLine = ({ status, results = [] }) => {
+  const passed = results.filter((result) => result.ok).length;
+  const failed = results.filter((result) => !result.ok);
+  const failedIds = failed.length > 0 ? failed.map((result) => result.id).join(',') : NO_FAILED_IDS;
+  return `[run-gates] status=${status} gates=${results.length} passed=${passed} failed=${failed.length} failed_ids=${failedIds}`;
+};
+
+// ── CLI ───────────────────────────────────────────────────────────────────────────────
+
+const parseArgs = (argv) => {
+  const opts = { cwd: null, only: [], help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg === '--cwd') {
+      i += 1;
+      if (argv[i] === undefined) throw fail(EXIT.usage, '--cwd requires a directory argument');
+      opts.cwd = argv[i];
+    } else if (arg === '--only') {
+      i += 1;
+      if (argv[i] === undefined) throw fail(EXIT.usage, '--only requires a gate id argument');
+      opts.only.push(argv[i]);
+    } else {
+      throw fail(EXIT.usage, `unknown argument "${arg}"\n${USAGE}`);
+    }
+  }
+  return opts;
+};
+
+// The full CLI, dependency-injected for hermetic tests. Returns the process exit code; the two
+// output sinks split human-facing report (log) from error channel (logError). The summary line is
+// emitted via `log` as the final line of every non-usage outcome.
+export const runCli = (argv, deps = {}) => {
+  const {
+    cwd = process.cwd(),
+    log = console.log,
+    logError = console.error,
+    spawn = spawnGateViaBash,
+    readFile,
+    lstat,
+    now,
+  } = deps;
+  try {
+    const opts = parseArgs(argv);
+    if (opts.help) {
+      log(USAGE);
+      return EXIT.ok;
+    }
+    const projectDir = opts.cwd ?? cwd;
+    const declaration = loadDeclaration(projectDir, { readFile, lstat });
+    if (declaration.outcome === 'missing') {
+      logError(`[run-gates] no gate declaration found at ${GATES_REL} — nothing was run.`);
+      logError(
+        `Recovery: create ${GATES_REL} from the gates.json template (references/templates/gates.json — ` +
+          'bootstrap seeds it; /agent-workflow-kit upgrade re-seeds a missing one), declare { id, title, cmd } gates, re-run.',
+      );
+      log(composeSummaryLine({ status: 'missing' }));
+      return EXIT.missing;
+    }
+    if (declaration.gates.length === 0) {
+      logError(`[run-gates] ${GATES_REL} declares an empty "gates" list — nothing to run (add { id, title, cmd } entries).`);
+      log(composeSummaryLine({ status: 'empty' }));
+      return EXIT.empty;
+    }
+    const selected = selectGates(declaration.gates, opts.only);
+    const probe = spawn(BASH_PROBE_CMD, projectDir);
+    if (probe.error && probe.error.code === 'ENOENT') {
+      logError(
+        '[run-gates] bash is not available on this host — gate cmd lines are BASH command lines ' +
+          '(brace/glob expansion); refusing to silently reinterpret them under another shell. Install bash and re-run.',
+      );
+      log(composeSummaryLine({ status: 'no-bash' }));
+      return EXIT.noBash;
+    }
+    const results = runGates(selected, { cwd: projectDir, spawn, log, now });
+    for (const line of formatTable(results)) log(line);
+    const allGreen = results.every((result) => result.ok);
+    log(composeSummaryLine({ status: allGreen ? 'ok' : 'fail', results }));
+    return allGreen ? EXIT.ok : EXIT.fail;
+  } catch (err) {
+    logError(`[run-gates] ${err.message}`);
+    if (err.exitCode === EXIT.malformed) log(composeSummaryLine({ status: 'malformed' }));
+    return err.exitCode ?? EXIT.fail;
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exitCode = runCli(process.argv.slice(2));

package/tools/semver-lite.mjs

@@ -0,0 +1,23 @@
+// semver-lite.mjs — the dependency-free semver LEAF shared by the npx installer (the never-downgrade
+// gate, bin/install.mjs) and the family registry (the bridge freshness probe).
+//
+// Parses the leading `x.y.z` only (prerelease/build ignored — family versions are plain).
+// compareSemver returns -1 | 0 | 1, or null when EITHER side is unparseable. The null contract is
+// load-bearing at both call sites: a legacy install predates any version stamp (→ no gate), and a
+// freshness probe that cannot parse a version must degrade to "unknown" — never to a false ordering
+// claim in either direction (INV-B). No `let`: a small functional comparison (AGENTS.md §2.3).
+//
+// Pure, no imports, no side effects, Node >= 18.
+
+export const parseSemver = (str) => {
+  const m = typeof str === 'string' ? str.trim().match(/^(\d+)\.(\d+)\.(\d+)/) : null;
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+};
+
+export const compareSemver = (a, b) => {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  const firstDiff = [0, 1, 2].map((i) => (pa[i] === pb[i] ? 0 : pa[i] < pb[i] ? -1 : 1)).find((c) => c !== 0);
+  return firstDiff ?? 0;
+};

package/tools/setup-backends.mjs

@@ -5,6 +5,12 @@
 // symlinks. Binary install + the interactive subscription login stay GUIDED (printed, never run) —
 // guideFor() supplies the exact commands. The read-only detector is the reader; this is the writer.
 //
+// Two write modes: plain setup (opt-in, in-agent — the ONLY path that ever PLACES a bridge) and the
+// refresh-only driver (`--refresh-placed` / refreshPlacedBridges, run by `init` and Mode: upgrade) —
+// it refreshes what setup already placed and re-links wrappers, states an absent bridge as a skip
+// (never a first placement), and never downgrades: a placed bridge newer than the kit-bundled mirror
+// is a stated skip naming the kit update (guarded again at the write boundary in placeSkill).
+//
 // Safety posture (AD-011): drive off the decoupled axes (a per-bindir wrapper check + an independent
 // skill-dir inspection), never the detector's collapsed readiness. REFRESH only a dir we provably own
 // (valid manifest, name+kind match) or one that is absent/empty; STOP on anything else (a marker fs
@@ -27,6 +33,7 @@ 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 { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
+import { compareSemver } from './semver-lite.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // bridges/ ships beside tools/ in both the repo and the installed kit, so this resolves in both.
@@ -215,11 +222,43 @@ const inspectDst = (dst, source, fs) => {
 
 // ── mutating primitives ───────────────────────────────────────────────────────
 
+// The one kit-update recovery the never-downgrade skip names (the bundle only gets newer via the kit).
+const KIT_UPDATE_RECOVERY = 'npx @sabaiway/agent-workflow-kit@latest init';
+
+// Crash-safe placed-version read for the downgrade guard: an unreadable placed version yields null →
+// compareSemver returns null → no ordering claim → the refresh stays allowed (legacy repair). The
+// guard forbids only a PROVEN downgrade; it never turns an unreadable stamp into a false refusal.
+const readPlacedVersionSafe = (skillDir, deps = {}) => {
+  const readVersion = deps.readVersion ?? readAuthoritativeVersion;
+  try {
+    return readVersion(skillDir).version ?? null;
+  } catch {
+    return null;
+  }
+};
+
+// Never-downgrade guard at the WRITE boundary (belt to planFor's braces — both read the versions
+// fresh): a placed bridge NEWER than the kit-bundled mirror (an older npx runner / a kit downgrade)
+// is a typed STOP naming the kit update, never a copy. Load-bearing once init/upgrade run the
+// refresh automatically.
+const downgradeReason = (placed, bundled) =>
+  `placed bridge is v${placed} but this kit bundles the older v${bundled} — refusing to downgrade; ` +
+  `update the kit first: ${KIT_UPDATE_RECOVERY}`;
+const assertNoDowngrade = (plan, deps = {}) => {
+  if (plan.action !== 'refresh') return;
+  const placed = readPlacedVersionSafe(plan.skillDir, deps);
+  const manifest = readBundledManifest(plan.bundleDir, deps);
+  const bundled = typeof manifest.version === 'string' ? manifest.version : null;
+  // `wouldDowngrade` lets a caller classify this STOP structurally (never by matching message text).
+  if (compareSemver(placed, bundled) === 1) throw stop(downgradeReason(placed, bundled), { skillDir: plan.skillDir, wouldDowngrade: true });
+};
+
 // Place/refresh the bundled bridge skill. Re-inspects before writing (never trusts a stale plan).
 export const placeSkill = (name, deps = {}) => {
   const entry = registryEntry(name);
   if (!entry) throw stop(`unknown backend: ${name}`);
   const plan = inspectSkillDir(entry, deps);
+  assertNoDowngrade(plan, deps);
   copyTreeRefresh(plan.bundleDir, plan.skillDir, plan.skillDir, fsDeps(deps));
   return plan;
 };
@@ -326,6 +365,17 @@ export const planFor = (backend, deps = {}) => {
     // setup never invents a second version reader. A place / absent-prior shows no arrow (never "vnull").
     version = typeof bundledManifest.version === 'string' ? bundledManifest.version : null;
     priorVersion = place.action === 'refresh' ? readVersion(skillDir).version ?? null : null;
+    // Never-downgrade (predicted here so a --dry-run is faithful and a real run stops before any
+    // write; placeSkill re-checks at the write boundary). An unparseable side → compareSemver null →
+    // no ordering claim → the refresh stays allowed (legacy repair). `wouldDowngrade` lets the
+    // refresh-only driver report this as a stated skip rather than a failure.
+    if (place.action === 'refresh' && compareSemver(priorVersion, version) === 1) {
+      return {
+        name: entry.name, skillDir, bindir, platform, place, links: [], guides: [], bindirHint: null,
+        outcome: 'stop', wouldDowngrade: true, version, priorVersion,
+        reason: downgradeReason(priorVersion, version),
+      };
+    }
     const derived = deriveLinks(bundledManifest, skillDir);
     // Preflight the BUNDLE sources (what we will copy → link). After place, the skill source IS the
     // bundle source, so checking it here makes a dry-run faithfully predict linkWrappers instead of
@@ -401,6 +451,77 @@ const formatBackend = (plan, applied) => {
   return lines.join('\n');
 };
 
+// ── the refresh-only driver (the init/upgrade delivery hook — refresh, never place) ──
+
+// Refresh-only apply: re-inspects at APPLY time and copies ONLY when the fresh inspection still says
+// `refresh` (TOCTOU: a dir gone absent between plan and apply is a reported skip, NEVER a first
+// placement — placement stays setup's opt-in step, AD-009/AD-011), and re-asserts the downgrade
+// guard against a freshly-read placed version (a NEWER bridge landing between plan and apply is a
+// typed STOP, never overwritten). No cross-process lock beyond that: like every mutating primitive
+// here (see applyBackend), concurrent writers are resolved by CONVERGE-ON-RE-RUN — the Phase-1
+// freshness probe flags any interleaving loser as behind and the next init/upgrade/setup repairs it;
+// a per-bridge lock file would be new machinery for a user-driven, self-healing race.
+const refreshSkillOnly = (entry, deps = {}) => {
+  const fresh = inspectSkillDir(entry, deps);
+  if (fresh.action !== 'refresh') return false;
+  assertNoDowngrade(fresh, deps);
+  copyTreeRefresh(fresh.bundleDir, fresh.skillDir, fresh.skillDir, fsDeps(deps));
+  return true;
+};
+
+const NOT_PLACED_LINE = 'skipped — not placed (placement is opt-in: /agent-workflow-kit setup)';
+const stripPrefix = (message) => message.replace('[agent-workflow-kit] ', '');
+
+// 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
+// pastes, never composes — deterministic-first). Outcomes: refreshed · already-current · not-placed
+// (absent — NEVER placed here) · kept-newer (INV-D stated skip) · unsupported (win32) · failed.
+export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) => b.name)) =>
+  names.map((name) => {
+    const canonical = resolveBackendName(name);
+    // The whole per-backend path is crash-proof, not just the apply: planFor itself can throw on a
+    // truly unexpected dependency error, and one broken backend must never abort the others' report.
+    try {
+      const plan = planFor(name, deps);
+      if (plan.outcome === 'unsupported') {
+        return { name: plan.name, outcome: 'unsupported', line: `  ${plan.name}: skipped — ${plan.reason}` };
+      }
+      if (plan.wouldDowngrade) {
+        return { name: plan.name, outcome: 'kept-newer', line: `  ${plan.name}: skipped — ${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}` };
+      }
+      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` };
+      }
+      if (!refreshSkillOnly(registryEntry(plan.name), deps)) {
+        return { name: plan.name, outcome: 'not-placed', line: `  ${plan.name}: ${NOT_PLACED_LINE}` };
+      }
+      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.
+      return {
+        name: plan.name,
+        outcome: current ? 'already-current' : 'refreshed',
+        line: `  ${plan.name}: ${current ? `already current${versionLabel(plan)} — files re-synced from the bundled copy` : `refreshed${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: 'failed', line: `  ${canonical}: could not refresh — ${stripPrefix(err.message)}; recover with /agent-workflow-kit setup` };
+    }
+  });
+
 // ── close-the-loop: surface versions + a proactive recipe offer ───────────────────
 
 // The closing pointer: setup surfaces only the bridge it touched; the full family + deployment version
@@ -438,23 +559,28 @@ export const proactiveReviewOffer = (before, after) => {
 
 // ── CLI ─────────────────────────────────────────────────────────────────────────
 
-const USAGE = `usage: setup-backends [<backend>] [--bindir <path>] [--dry-run] [--help]
+const USAGE = `usage: setup-backends [<backend>] [--bindir <path>] [--dry-run | --refresh-placed] [--help]
 
-  <backend>   codex | agy | antigravity | codex-cli-bridge | antigravity-cli-bridge   (default: all)
-  --bindir    where to link the wrappers                                              (default: ~/.local/bin)
-  --dry-run   print the plan; change nothing
-  --help, -h  this help
+  <backend>          codex | agy | antigravity | codex-cli-bridge | antigravity-cli-bridge   (default: all)
+  --bindir           where to link the wrappers                                              (default: ~/.local/bin)
+  --dry-run          print the plan; change nothing
+  --refresh-placed   refresh ONLY the already-placed bridges from the kit's bundled copies —
+                     an absent bridge is a stated skip (never placed), a placed bridge newer
+                     than the bundle is a stated skip (never downgraded). The refresh-only
+                     mode init/upgrade run; does not combine with --dry-run.
+  --help, -h         this help
 
 Places the bundled bridge skill + links its wrappers (idempotent; refuses to clobber a non-symlink).
 Binary install + the interactive subscription login stay manual — the printed guidance has the exact
 commands. The detector ("/agent-workflow-kit backends") stays read-only; this is the only writer.`;
 
 const parseArgs = (argv) => {
-  const out = { dryRun: false, help: false, bindir: undefined, backend: undefined, bad: null };
+  const out = { dryRun: false, refreshPlaced: false, help: false, bindir: undefined, backend: undefined, bad: null };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--help' || a === '-h') out.help = true;
     else if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--refresh-placed') out.refreshPlaced = true;
     else if (a === '--bindir') {
       // Do NOT greedily swallow a following flag (e.g. `--bindir --dry-run` must not become
       // bindir="--dry-run" and silently mutate); a missing or flag-like value is a usage error.
@@ -482,6 +608,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     log(USAGE);
     return 0;
   }
+  if (args.refreshPlaced && args.dryRun) args.bad = '--refresh-placed does not combine with --dry-run';
   if (args.bad) {
     errlog(args.bad);
     errlog(USAGE);
@@ -501,6 +628,16 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   }
 
   const runDeps = { ...deps, bindir: args.bindir ?? deps.bindir };
+
+  // Refresh-only mode: act on what setup already placed; never place, never downgrade. Every line is
+  // tool-composed — callers (init, Mode: upgrade) print/paste them verbatim.
+  if (args.refreshPlaced) {
+    log('agent-workflow placed-bridge refresh (refresh-only — placement stays opt-in: /agent-workflow-kit setup)');
+    const results = refreshPlacedBridges(runDeps, targets);
+    for (const r of results) log(r.line);
+    return results.some((r) => r.outcome === 'failed') ? 1 : 0;
+  }
+
   log(args.dryRun ? 'agent-workflow backend setup — DRY RUN (no changes)' : 'agent-workflow backend setup (link-only)');
   // Snapshot review readiness BEFORE applying, so we can offer the recipe only on a true readiness flip.
   const reviewBefore = args.dryRun ? null : reviewReadyCount(runDeps);

package/tools/view-model.mjs

@@ -21,6 +21,9 @@ const memberVm = (m) => {
     notes: m.notes ?? [], // the verbatim caveats — printed as ↳ sub-lines (INV-3: no dedupe)
     behind: Boolean(refresh.behind), // used ONLY for the headline count on the direct CLI (INV-3)
     recommend: refresh.recommend ?? null,
+    // The checked-vs-unknown freshness signal (INV-C): 'current' | 'behind' | 'unknown' | 'not-checked'.
+    // An envelope predating the field defaults to not-checked (behind stays behind) — never a claim.
+    freshness: refresh.freshness ?? (refresh.behind ? 'behind' : 'not-checked'),
   };
 };
 
@@ -82,7 +85,14 @@ export const toViewModel = (envelope = {}) => {
   return {
     deploymentHead: envelope.deploymentHead ?? null,
     members,
-    headline: { total: members.length, behind: members.filter((m) => m.behind).length },
+    headline: {
+      total: members.length,
+      behind: members.filter((m) => m.behind).length,
+      // The zero-behind verdict scope (INV-C): checked = a freshness probe RAN and concluded;
+      // unknown = it ran but could not conclude (INV-B — blocks the all-current verdict).
+      checked: members.filter((m) => m.freshness === 'current' || m.freshness === 'behind').length,
+      unknown: members.filter((m) => m.freshness === 'unknown').length,
+    },
     bridges: envelope.bridges ? envelope.bridges.map(bridgeVm) : null,
     project: projectVm(envelope.project),
   };