@sabaiway/agent-workflow-kit 1.24.0 → 1.26.0

package/tools/recipes.mjs

@@ -283,21 +283,43 @@ export const resolveActivityRecipe = ({ config = {}, readiness = [], activity, s
   };
 };
 
+// ── the one-line backend status (deterministic-first: the tool speaks, the agent pastes) ───────────
+
+// composeStatusLine(detection, recommendation) → the ENTIRE one-line backend-status summary the
+// bootstrap/upgrade report footers print. Machine-composed so the agent pastes it verbatim and
+// composes NOTHING factual (this closes the realistic-example contamination class: a session once
+// echoed SKILL.md's canonical example while the detector said otherwise). Display names come from
+// DISPLAY_ALIASES — the ONE alias table the recommendation clause already uses; ordering is the
+// deterministic BACKEND_PRIORITY (codex before agy), independent of detection emission order.
+// Always exactly one line: no part may carry a newline (pinned by tests).
+export const composeStatusLine = (detection, recommendation) => {
+  const backends = [...detection]
+    .sort((a, b) => priorityIndex(a.name) - priorityIndex(b.name))
+    .map((b) => `${DISPLAY_ALIASES[b.name] ?? b.name} ${b.readiness === READY ? '✓' : '✗'} ${b.readiness}`)
+    .join(' · ');
+  return `backends: ${backends} — run /agent-workflow-kit backends · recipes: ${recommendation.clause} — see /agent-workflow-kit recipes`;
+};
+
 // ── report + CLI ─────────────────────────────────────────────────────────────────
 
-// The structured report behind `--json` — the recipes, the recommendation, and a plan per recipe.
-export const buildReport = (detection) => ({
-  recipes: RECIPES.map(({ id, title, role, minBackends, degradesTo, summary }) => ({
-    id,
-    title,
-    role,
-    minBackends,
-    degradesTo,
-    summary,
-  })),
-  recommendation: recommendRecipe(detection),
-  plans: RECIPES.map((r) => planRecipe(r.id, detection)),
-});
+// The structured report behind `--json` — the recipes, the recommendation, a plan per recipe, and
+// (additive) the pasteable one-line backend status composed from the same detection.
+export const buildReport = (detection) => {
+  const recommendation = recommendRecipe(detection);
+  return {
+    recipes: RECIPES.map(({ id, title, role, minBackends, degradesTo, summary }) => ({
+      id,
+      title,
+      role,
+      minBackends,
+      degradesTo,
+      summary,
+    })),
+    recommendation,
+    plans: RECIPES.map((r) => planRecipe(r.id, detection)),
+    statusLine: composeStatusLine(detection, recommendation),
+  };
+};
 
 // formatRecipes(detection) → deterministic human advisor text: the four recipes, the recommendation,
 // and the per-recipe plan for the current environment (degradation reasons + dispatch + notes).
@@ -320,20 +342,37 @@ export const formatRecipes = (detection) => {
   return lines.join('\n');
 };
 
+// The full argv vocabulary — anything else rejects LOUDLY. The old parse silently routed unknown
+// args into the multi-line human render; with `--status-line` (whose output is pasted as fact) a
+// mistyped flag masquerading as a mode would be a silent failure, so the parse is strict now.
+const KNOWN_ARGS = new Set(['--help', '-h', '--json', '--status-line']);
+
 const main = (argv) => {
   if (argv.includes('--help') || argv.includes('-h')) {
     console.log(`recipes — read-only orchestration-recipe advisor for the agent-workflow family.
 
 Usage:
-  node recipes.mjs [--json]
+  node recipes.mjs [--json | --status-line]
 
 Lists the four recipes (Solo / Reviewed / Council / Delegated) and, from the read-only backend
-detector, plans + recommends one for the current environment. Detection only — never writes, never
-commits, never runs a subscription CLI.`);
+detector, plans + recommends one for the current environment. --status-line prints exactly ONE
+line — the machine-composed backend-status summary the bootstrap/upgrade reports paste verbatim.
+--json emits the structured report (incl. the same line as \`statusLine\`); the two are mutually
+exclusive. Detection only — never writes, never commits, never runs a subscription CLI.`);
     return;
   }
+  const unknown = argv.find((a) => !KNOWN_ARGS.has(a));
+  if (unknown !== undefined) {
+    console.error(`[agent-workflow-kit] unknown argument: ${unknown}`);
+    process.exit(1);
+  }
+  if (argv.includes('--json') && argv.includes('--status-line')) {
+    console.error('[agent-workflow-kit] --json and --status-line are mutually exclusive — pick one output');
+    process.exit(1);
+  }
   const detection = detectBackends();
-  if (argv.includes('--json')) console.log(JSON.stringify(buildReport(detection), null, 2));
+  if (argv.includes('--status-line')) console.log(composeStatusLine(detection, recommendRecipe(detection)));
+  else if (argv.includes('--json')) console.log(JSON.stringify(buildReport(detection), null, 2));
   else console.log(formatRecipes(detection));
 };
 

package/tools/renderers.mjs

@@ -34,7 +34,18 @@ const renderMembers = (vm, { color, glyph }) => {
   // refresh.behind drives a HEADLINE COUNT only — the recovery command stays in the verbatim notes
   // above (the direct CLI never dedupes, never re-prints it). Omitted when nothing is behind.
   if (vm.headline.behind > 0) {
-    lines.push(`  ${vm.headline.behind} member(s) need a refresh (see the ${glyph.note} notes above).`);
+    // A mixed behind+unknown state must not swallow the unknown count (INV-B): append it here so an
+    // uncheckable member never disappears behind the refresh headline.
+    const unknownTail = vm.headline.unknown > 0 ? ` · ${vm.headline.unknown} could not be checked` : '';
+    lines.push(`  ${vm.headline.behind} member(s) need a refresh (see the ${glyph.note} notes above)${unknownTail}.`);
+  } else if (vm.headline.unknown > 0) {
+    // INV-B × INV-C: an uncheckable member BLOCKS the all-current verdict — state the split, never a
+    // blanket freshness claim in either direction.
+    lines.push(`  freshness: ${vm.headline.checked} member(s) checked and current · ${vm.headline.unknown} could not be checked.`);
+  } else if (vm.headline.checked > 0) {
+    // INV-C: the zero-behind verdict is composed by the TOOL, scoped to what was actually checked —
+    // the agent has no gap to fill with an "everything is fresh" gloss.
+    lines.push(`  freshness: all ${vm.headline.checked} checked member(s) are current.`);
   }
   return lines;
 };

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),
   };