@sabaiway/agent-workflow-kit 1.25.0 → 1.26.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.26.0 — Deterministic bridge freshness & delivery; machine-composed status line; honest installer messaging
+
+A **feature** release (ships the bundled bridges unchanged at **2.1.0**). One architecture across
+four fixes: **the registry computes, the tools speak, the agent pastes** — no factual line on these
+surfaces is agent-composed anymore.
+
+- **Bridge freshness is now visible.** `family-registry` compares each placed bridge against the
+  kit-bundled mirror (both local files — nothing checks npm): behind → a plain caveat + the runnable
+  `/agent-workflow-kit setup` recommend + `refresh.behind:true` in `--json`, reaching the
+  bootstrap/upgrade footers and the welcome mat (priority 1 is now caveat-generic and quotes the
+  firing note's OWN recovery verbatim); uncheckable → an explicit unknown note (never "current",
+  never "behind"); zero-behind → the TOOL prints a checked-scope verdict (`all N checked members are
+  current` — any unknown blocks the all-current claim). New dependency-free `tools/semver-lite.mjs`.
+- **Placed bridges refresh on `init` and `upgrade`.** A refresh-only driver in `setup-backends.mjs`
+  (`--refresh-placed`) refreshes proven-managed placed bridges and NEVER places an absent one —
+  placement stays opt-in via `/agent-workflow-kit setup`. `npx … init` calls it best-effort (a miss
+  is a loud warning + a recovery command composed from the resolved install target + exit 0;
+  `--no-bridges` opts out; win32 is a stated skip); `Mode: upgrade` runs it as a fourth
+  stamp-independent reconcile and pastes the output verbatim. **Never-downgrade:** a placed bridge
+  NEWER than the bundle is a stated keep + "update the kit", enforced at both the plan and the write
+  boundary (TOCTOU re-inspect at apply); an unparseable version is treated as legacy repair, stated.
+- **The one-line backend status is machine-composed.** `tools/recipes.mjs --status-line` emits the
+  exact line (deterministic order, one alias table; additive `statusLine` in `--json`; strict argv —
+  an unknown flag exits loudly instead of masquerading as the human render); SKILL.md now says run
+  the tool and paste its line verbatim — the realistic example that once got echoed as fact is
+  replaced by an explicitly-placeholder template.
+- **The installer speaks facts.** The final verb is keyed on the OBSERVED version comparison
+  (installed / updated / refreshed-the-already-current / downgraded-under-`--allow-downgrade`); the
+  same-version note states that the copy ran (a re-run repairs locally modified files) + a
+  CONDITIONAL `@latest` hint; the false "npx likely served a cached build" accusation is gone. One
+  message contract with the engine installer (engine `1.9.0`).
+- Lens sync everywhere — "placed by `setup` (opt-in), refreshed by `init`/`upgrade` once placed" —
+  across SKILL.md, both READMEs and `family-members.mjs`, guarded by the new region+token
+  `test/init-refresh-lens.test.mjs` (non-vacuous, injected red→green proven).
+
 ## 1.25.0 — The bridge driving contract at the point of use (advisor render + wrapper `--help`)
 
 A **feature** release (additive; ships the bundled bridges at **2.1.0**). An agent told to run a

package/README.md

@@ -139,8 +139,9 @@ npx @sabaiway/agent-workflow-kit@latest init
 ```
 
 `init` installs/refreshes the skill at `~/.claude/skills/agent-workflow-kit/` and wires launchers for
-any Claude Code / Codex / Devin Desktop it finds. It **does not** deploy into a project, and **does
-not** install the optional bridges.
+any Claude Code / Codex / Devin Desktop it finds. It **does not** deploy into a project, and **never
+places** the optional bridges — **once placed** (by `/agent-workflow-kit setup`) it **refreshes** them
+from its bundled copies (never a downgrade; skip with `--no-bridges`).
 
 ### 2. Deploy into a project — once per repo
 
@@ -202,11 +203,13 @@ refreshes the other npm core members so a returning `init` leaves **no stale cor
 | `~/.claude/skills/agent-workflow-kit/` | the kit itself (refreshed on every `init`) |
 | `~/.claude/skills/agent-workflow-memory/` | the **memory substrate**, refreshed via `npx @sabaiway/agent-workflow-memory@latest init` — **best-effort:** a failure is a **loud degraded success** (warning + the exact recovery command + exit 0), never silent; skip with `--no-memory` |
 | `~/.claude/skills/agent-workflow-engine/` | the **methodology engine** the kit reads live, refreshed via `npx @sabaiway/agent-workflow-engine@latest init` — **required** (the live read STOPs without it); skip with `--no-engine` |
+| `~/.claude/skills/{codex,antigravity}-cli-bridge/` | the placed **bridges**, refreshed from the kit's bundled copies (local files, no network) — **only if `/agent-workflow-kit setup` already placed them**: an absent bridge is never placed, a newer one never downgraded; skip with `--no-bridges` |
 | `~/.codex/skills/agent-workflow-kit` | a symlink — only if you have Codex |
 | `…/global_workflows/agent-workflow-kit.md` | a managed file — only if you have Devin Desktop |
 
-The **execution-backend bridges** (`codex` / `agy`) are **not** installed by `init` — set one up on
-demand with `/agent-workflow-kit setup`. Your other Codex skills and Devin Desktop workflows are
+The **execution-backend bridges** (`codex` / `agy`) are never first **placed** by `init` — set one up
+on demand with `/agent-workflow-kit setup`; after that, a returning `init` keeps the placed copy
+fresh (the table row above). Your other Codex skills and Devin Desktop workflows are
 never touched. If one of those exact slots already holds a file the kit didn't write, it is **left
 alone** and you're told — re-run with `--force` to replace it (the original is first copied to
 `*.bak.<timestamp>` and the restore command is printed).
@@ -222,7 +225,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | Command | When | What happens |
 |---------|------|--------------|
 | `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** + **agent attribution** (default off) → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → installs enforcement → **asks before committing** |
-| `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps — then prints a **read-only** one-line backend-status line (what's set up vs missing); never installs a bridge — set one up with `/agent-workflow-kit setup` |
+| `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps — then prints a **read-only** one-line backend-status line (what's set up vs missing); refreshes the already-placed bridges from the kit's bundled copies (never installs a new one — set one up with `/agent-workflow-kit setup`) |
 | `/agent-workflow-kit help` | any time | **read-only command index** — every command, grouped (Inspect / Configure / Orchestrate / Lifecycle) and tagged read-only / writer / guarded. The discoverable entry point, and where any unrecognized invocation lands (always read-only — a garbage invocation never writes). Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
 | `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
@@ -274,8 +277,9 @@ agent-workflow-kit  —  the composition root (installed via npx … init)
   **orchestration recipes** (Solo / Reviewed / Council / Delegated) — read **live** from the installed
   **`agent-workflow-engine`** (the canonical narrative; a published member, never one of the shipped
   backends). `/agent-workflow-kit recipes` surfaces + plans a recipe for your environment, read-only.
-- **Detects & (opt-in) sets up** the optional `codex` / `agy` **bridges** — agent skills (not npm, not
-  installed by `init`). They plug into the workflow's **execute** and **review** phases — for *what
+- **Detects & (opt-in) sets up** the optional `codex` / `agy` **bridges** — agent skills (not npm;
+  never first placed by `init` — `setup` places them, and once placed `init`/`upgrade` refresh
+  them). They plug into the workflow's **execute** and **review** phases — for *what
   each adds and why*, see the
   [family front door](https://github.com/sabaiway/agent-workflow#readme). `/agent-workflow-kit backends`
   reports readiness **read-only**;

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.25.0'
+  version: '1.26.0'
 ---
 
 # agent-workflow-kit
@@ -31,7 +31,10 @@ runtime dependency placed by `init` and read live; see *Methodology slot reconci
 `init` also **refreshes the installed memory substrate** (best-effort — a miss is a loud DEGRADED
 success: a warning with the exact recovery command + exit 0, never silent, never the engine's hard
 STOP; `--no-memory` skips it), so a returning `init` leaves **no stale core member**. The
-execution-backend bridges are still **not** installed by `init` (placed on demand by `setup`).
+execution-backend bridges are still never **placed** by `init` (placed on demand by `setup`, opt-in);
+**once placed**, `init` **refreshes** them from the kit's own bundled copies (refresh-only, local
+files, never a downgrade; `--no-bridges` skips it) — so a returning `init` leaves no stale placed
+bridge either.
 
 **Detection (kit-owned, decided BEFORE any project write).** Run the kit's **own shipped**
 validator — `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs <memory-skill-dir>` — never a
@@ -108,7 +111,7 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
 - **`/agent-workflow-kit help`** — read-only **command index**: enumerate every command, grouped (Inspect / Configure / Orchestrate / Lifecycle) and tagged read-only / writer / guarded. The single discoverable entry point, and the landing spot for any unrecognized invocation. Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit backends`** — read-only environment check: which optional **execution-backends** (the `codex` / `agy` bridges) are set up vs missing. Never writes, never commits, never runs a subscription CLI.
-- **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never *places* bridges; once placed, `init`/`upgrade` refresh them (refresh-only). The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit status`** — read-only view of the **whole family**: which members (kit / memory / engine / the two bridges) are installed, at what version, and — in a project — what is deployed (`docs/ai`, the version stamps, the hidden-mode fence). Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit recipes`** — read-only **orchestration advisor**: present the four recipes (Solo / Reviewed / Council / Delegated) over the bridges' role vocabulary, plan + recommend one for the current environment, and offer the choice. **The orchestrator executes the chosen recipe via the bridge skills and always commits** — the kit only surfaces/selects/plans it; it never executes a recipe, never runs a subscription CLI, never commits.
 - **`/agent-workflow-kit procedures <activity>`** — read-only **activity-procedures advisor**: print the ordered steps of a named activity (`plan-authoring` / `plan-execution`) read **live** from the installed engine (`references/procedures.md`), and the **resolved effective recipe per slot** from the per-project `docs/ai/orchestration.json` (strict JSON; agent-writable via `set-recipe` or hand-edit) + backend readiness (default = Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated; graceful default vs loud override degradation) — plus, for every dispatched backend, the **full driving contract at the point of use**: the exact copy-pasteable invocation descriptor(s), the grounding levers (agy `--facts`/`--decided`), the round-2 `--continue` delta, and the guarded passthrough tiers, rendered verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same contract). A per-run `--override <slot>=<recipe>` overrides one slot. Composes with `recipes` (which stays read-only); never writes, never commits, never runs a subscription CLI.
@@ -137,29 +140,32 @@ Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide
 ### The one-line backend-status line (shared by bootstrap + upgrade)
 
 Bootstrap (step 11) and **every** successful `upgrade` exit (steps 4 + 8) print the **same**
-read-only, one-line summary of the optional execution-backends. Run the **backend detector** —
-`node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs` — and compose one line from its per-backend
-readiness, then **append an actionable recipe recommendation** from the recipe planner
-(`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --json` → `recommendation.clause`, P2-rich). Canonical format:
-`backends: codex ✓ ready · antigravity ✗ needs-credentials — run /agent-workflow-kit backends · recipes: Reviewed available (via codex) — see /agent-workflow-kit recipes`
-
+read-only, one-line summary of the optional execution-backends. The line is **machine-composed** —
+run the status-line composer and **paste its single emitted line verbatim**:
+`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --status-line`
+The tool runs the backend detector and appends the recipe recommendation itself
+(`composeStatusLine`); the agent **composes nothing factual** — no readiness token, no glyph, no
+recipe clause of its own, ever.
+
+- **Placeholder template (structure only — never copy this example; paste the tool's line):**
+  `backends: <alias> <✓|✗> <readiness> · <alias> <✓|✗> <readiness> — run /agent-workflow-kit backends · recipes: <recommendation clause> — see /agent-workflow-kit recipes`
 - The **`recipes:` clause is appended after** the `— run /agent-workflow-kit backends` pointer (never
   replacing it) and routes to the read-only `recipes` mode (`see /agent-workflow-kit recipes`). It is
   **never blank**: both backends ready → *"Council available, Reviewed the everyday default"*; one
   ready → *"Reviewed available (via …)"*; **none installed → *"Solo — run /agent-workflow-kit setup to
   add a backend"***; a backend present-but-not-ready → Solo with that backend's specific remedy.
-  (Matches `recommendRecipe`.)
+  (Composed by `recommendRecipe` inside the same tool run — never by the agent.)
 - **Invariants:** **read-only · never blocks the commit gate · never runs a subscription CLI · the
   pointer is the in-agent `backends` mode, never a network fetch · the appended `recipes:` clause
-  routes to the in-agent `recipes` mode the same way · `init`/npx is unaffected (it never places
-  bridges, AD-011 §5).**
-- **Detector unavailable → skip with a stated reason, never silently.** The detector is a Node script
+  routes to the in-agent `recipes` mode the same way · `init`/npx never *places* bridges (it
+  refreshes only what `setup` already placed, AD-011 §5).**
+- **Composer unavailable → skip with a stated reason, never silently.** The composer is a Node script
   the **agent host** runs (not the target project), so the only skip condition is "**the agent host
-  can't run it**" — `node` is not on the agent's PATH, or the detector itself errors — **not** "the
+  can't run it**" — `node` is not on the agent's PATH, or the tool itself errors — **not** "the
   project has no Node runtime". On that condition, skip the line and say so **with the concrete
-  reason**, e.g. *"Couldn't run the backend detector here (node is not on the agent host PATH), so
-  I'm skipping the backend-status line."* — never a silent skip (Hard Constraint — no silent
-  failures).
+  reason**, e.g. *"Couldn't run the backend status-line composer here (node is not on the agent host
+  PATH), so I'm skipping the backend-status line."* — never a silent skip (Hard Constraint — no
+  silent failures).
 
 ### The version block + welcome mat (shared by bootstrap + upgrade)
 
@@ -206,8 +212,12 @@ the rest of the report — and the commit gate — proceeds.
 line, print *"Run `/agent-workflow-kit help` to see every command."* then **one** recommended next
 step, chosen **caveat-aware** from signals already in hand (the version block's notes + the
 backend-status line — no new helper call) in this priority order:
-1. a member is **behind** (an `installed[].notes` caveat fired — memory/engine) → *refresh the behind
-   member first* (its `npx …@latest init` + restart the session);
+1. a member is **behind** (a behind-class `installed[].notes` caveat fired — any member, the bridges
+   included) → *refresh the behind member first*, quoting **that note's own recovery command
+   verbatim** (a memory/engine note carries its `npx …@latest init` + restart the session; a bridge
+   note carries `/agent-workflow-kit setup`). An **uncheckable** member ("couldn't be checked" — an
+   unknown-freshness note) is **never** a refresh trigger: only a behind note fires this step — the
+   uncheckable note already appears in the version block, add nothing more;
 2. else **no backend is ready** (the backend-status line shows none ready) → *set one up with
    `/agent-workflow-kit setup`*;
 3. else **a backend is ready but the orchestration config is still all-Solo** (no `reviewed` /
@@ -316,15 +326,27 @@ Fill strategy:
    **Hidden-mode footprint reconcile — stamp-independent, same gate, BEFORE the equal-head short-circuit (D9 / AD-014).** A deployment does not record whether it chose `hidden`, so first **infer visibility**: `node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile --dry-run` (writes **zero bytes**). It reports one of — **visible** (the entry point is tracked) → nothing to do; **ambiguous** (untracked but not ignored — could be a fresh uncommitted repo, or a hide that broke) → **ASK** the user which it is, never guess; **hidden** → re-run without `--dry-run` to migrate any older **machine-global** hide to the **project-local** `.git/info/exclude` (one managed block; folds in the legacy `.claude/skills/` line), idempotently (a clean re-run is zero-diff). Handle its surfaced paths exactly as bootstrap step 9 (already-committed → show `git rm --cached`, ask before `--include`; generic-name present file → ask; **leftover machine-wide ignore block → ASK before `--remove-global`**, default keep + report). No Node on the agent host / Windows → as step 9. This runs on **every** hidden upgrade, like the methodology slot — no lineage-head bump, no migration file.
 
    **Orchestration config ensure (seed-or-refresh) — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Ensure `docs/ai/orchestration.json` exists **and its onboarding note is current**: **create it from the template if missing**; **if it already exists, preserve every activity/slot the user set, and refresh ONLY the `_README` note when the existing one still matches a known prior canonical** — the tested `refreshIfCanonical` / `refreshReadme` in `tools/orchestration-config.mjs` is the source of truth for that decision (normalize CRLF/whitespace before comparing; a *customized* `_README` is preserved verbatim; a *malformed* existing config is **preserved + a loud warning**, never clobbered or silently skipped). The current note points at `/agent-workflow-kit set-recipe` (the config is now agent-writable — no more "never written for you"). **The refresh helper is kit-owned** — in the **delegated** path memory only seeds/preserves the file (memory upgrade step 2) and the **kit** then applies the `_README` refresh; in the **fallback** path the kit seeds-or-refreshes directly from `${CLAUDE_SKILL_DIR}/references/templates/orchestration.json`. (Memory stays standalone — it never depends on this helper.) Like the pointer slots + the footprint reconcile, this reaches an equal-head (`1.3.0`) deployment **without a lineage-head bump or a migration file** (it is a `.json`, inherently outside the docs cap-validator). Report it in the step 4 / step 8 success report (config *seeded* / *note refreshed* / *already current* / *customized — preserved*).
+
+   **Placed-bridge refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Run
+   `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed` and **paste its per-bridge
+   output lines verbatim** — every outcome line is composed by the tool (*refreshed* / *already
+   current* / *skipped — not placed* / *could not refresh* + its recovery); you compose nothing
+   factual. It is **refresh-only**: it refreshes a bridge **`setup` already placed** from this kit's
+   bundled copies and re-links its wrappers; an **absent** bridge is a stated skip, **never a first
+   placement** (placement stays the opt-in *Mode: setup* — AD-009/AD-011 honesty intact), and a
+   placed bridge **newer** than the bundled copy is a stated skip naming the kit update (**never a
+   downgrade**). Like the other three reconciles it runs on **every** upgrade — including an
+   equal-head one — with no lineage-head bump. A *could not refresh* line is non-fatal: relay it
+   plainly with its recovery and continue the upgrade.
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the methodology-slot **and** hidden-mode footprint reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
-   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (Gotcha: never leak kit internals).
+   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / *could not refresh* + recovery); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (Gotcha: never leak kit internals).
    - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
    - **Print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above; rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity`).
    - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, give the plain **settings already current — no update needed** message (the *Success state* contract) and still print the read-only version block (installed package versions) + backend line — but **no `docs/ai` structure version and no two-axes note** (nothing changed, so the number is inert here).
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
 6. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
 7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
-8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure*, on demand only). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing**.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 **placed-bridge refresh** lines (pasted verbatim) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure*, on demand only). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing**.
 
 ### Mode: backends
 
@@ -338,13 +360,19 @@ Read-only. Answers *"which optional execution-backends are set up vs missing, an
 
 ### Mode: setup
 
-The **only writer** among the backend modes, and **opt-in / in-agent only** — it is **never** part of `init`. The npx installer deploys the *kit* and bundles the bridge skills in its tarball, but **does not place** them (that honesty claim is load-bearing — see `decisions.md` AD-009 / AD-011). `setup` owns exactly the two deterministic, secret-free steps and **guides** the rest. It **never commits and never runs a subscription CLI**.
+The **only writer** among the backend modes, and **opt-in / in-agent only** — **placement** is **never** part of `init`. The npx installer deploys the *kit* and bundles the bridge skills in its tarball, but **does not place** them (that honesty claim is load-bearing — see `decisions.md` AD-009 / AD-011); **once placed** by `setup`, `init` and *Mode: upgrade* keep the placed copy fresh via the refresh-only `--refresh-placed` (below) — **never a first placement, never a downgrade**. `setup` owns exactly the two deterministic, secret-free steps and **guides** the rest. It **never commits and never runs a subscription CLI**.
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs [<backend>] [--bindir <path>] [--dry-run]`:
 
 - `<backend>` — `codex` | `agy` | `antigravity` | `codex-cli-bridge` | `antigravity-cli-bridge`; omit for **all**.
 - `--bindir <path>` — where to link the wrappers (default `~/.local/bin`).
 - `--dry-run` — print the per-backend plan and change **nothing** (run this first).
+- `--refresh-placed` — the **refresh-only** mode (what `init` runs automatically and *Mode: upgrade*
+  runs as its fourth stamp-independent reconcile): refresh every bridge `setup` **already placed**
+  from the kit's bundled copies + re-link its wrappers; an absent bridge is a stated skip (**never**
+  placed), a placed bridge newer than the bundle is a stated skip naming the kit update (**never**
+  downgraded), and every outcome line is composed by the tool — paste verbatim. Does not combine
+  with `--dry-run`.
 - `--help`, `-h` — usage.
 
 For each backend it:
@@ -367,7 +395,7 @@ Read-only. The **single answer to "versions + deployment + settings + bridges"**
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json [--dir <project>]` and render it **compact**, in the user's conversational language — **never paste the JSON or any internal field name** (no-leak rule). Map the **`installed[].state`** token via the value→plain-language map under *The version block + welcome mat* (the `visibility` and wrapper states have their own phrasings, below). Present, each area on its own line(s), routing detail to its domain mode:
 
-1. **Versions — a status-only render from `installed[]` + `deploymentHead`** (this is **NOT** the shared notes-based version block — see the separation note below): the **`docs/ai` structure version** (named as such, never "lineage head"), then each member by its `display` showing its `version` (or, when there is no version, the plain phrase for its `state`, mapped above), plus the two-axes disambiguation. **Freshness comes from `installed[].refresh`, not from `notes`:** for each member whose **`refresh.behind`** is `true`, show a **localized "needs refresh"** label and the **verbatim `refresh.recommend`** command **exactly once** (the command/package name stays source-language; **do not also paste the English `notes` caveats** — `refresh.recommend` is the single source of the recovery step, so the command is never duplicated on this surface). Lead with a one-line **headline count** derived from `installed[].state` + `refresh.behind` (e.g. *"5 members installed · 1 needs a refresh"*).
+1. **Versions — a status-only render from `installed[]` + `deploymentHead`** (this is **NOT** the shared notes-based version block — see the separation note below): the **`docs/ai` structure version** (named as such, never "lineage head"), then each member by its `display` showing its `version` (or, when there is no version, the plain phrase for its `state`, mapped above), plus the two-axes disambiguation. **Freshness comes from `installed[].refresh`, not from `notes`:** for each member whose **`refresh.behind`** is `true`, show a **localized "needs refresh"** label and the **verbatim `refresh.recommend`** command **exactly once** (the command/package name stays source-language; **do not also paste the English `notes` caveats** — `refresh.recommend` is the single source of the recovery step, so the command is never duplicated on this surface). A member whose **`refresh.freshness`** is **`unknown`** is surfaced too — a localized *"couldn't be checked"* label; it is **never counted as current and never as behind** (its `notes` caveat carries the detail on the notes-based surfaces; here the label is enough). Lead with a one-line **headline count** derived from `installed[].state` + `refresh.behind` + `refresh.freshness` (e.g. *"5 members installed · 1 needs a refresh · 1 couldn't be checked"* — omit a zero count).
 
 > **Status reads `refresh`; the shared version block + the bootstrap/upgrade footers stay `notes`-based (unchanged this release).** *Mode: status* has its OWN status-only render (above), keyed on `installed[].refresh.behind` / `refresh.recommend`. The shared **version block** (under *The version block + welcome mat*) and the bootstrap (step 11) + every upgrade (steps 4 / 8) report footer still consume `installed[].notes` verbatim — that wiring is deliberately **untouched** here (their migration onto `refresh` is deferred). Do not rewrite those footers onto `refresh`.
 2. **Deployment (`--dir`)** (from `project`): whether `docs/ai/` is deployed + the deploy stamps by `display`; and **visibility** — render `project.visibility.state` in **user-safe words only**: *visible (tracked)* / *hidden (git-ignored, local-only)* / *unclear (uncommitted or partially set up)* — **never** the words "hidden fence" or any marker term. A `visibility.error` → surface it plainly.
@@ -554,6 +582,6 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
 - [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
-- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `commands.mjs` (the canonical **command catalog** + the pure `routeInvocation` router behind `/agent-workflow-kit help` and the safe unknown-invocation routing rule — one source of truth for the command surface, drift-guarded against the `### Mode:` headers), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded **two-slot** reconciliation — ensure-slot / inject-if-empty / cap for the `workflow:methodology` **and** `workflow:orchestration` pointers; both fragments read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` (`deps.rel` selects which) — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent, orchestration soft-skipped when it would bust the cap), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`; exports the readiness consts the planner reuses), `recipes.mjs` (the read-only **recipe planner** behind `/agent-workflow-kit recipes` — `RECIPES` / `planRecipe` / `recommendRecipe` over the bridges' role vocabulary, drift-guarded against `provides`/`cost`/`quota` + an engine↔kit recipe-name parity guard; pure, never runs a subscription CLI; also exports the pure `ACTIVITIES` / `resolveActivityRecipe` activity-procedures resolver), `procedures.mjs` (the read-only **activity-procedures advisor** behind `/agent-workflow-kit procedures` — reads `references/procedures.md` live from the engine via `engine-source.mjs`, reads + validates the agent-writable `docs/ai/orchestration.json` via `orchestration-config.mjs`, and prints the steps + the resolved effective recipe per slot; drift-guarded activity/slot table vs the canon; read-only, never imports the writer, never runs a subscription CLI), `orchestration-config.mjs` (the config **schema/read/pure-transform core** — `loadConfig`/`validateConfig`/the shared slot-recipe validity + `parseOp`/`applySetOps`/`serializeConfig`/the canonical-refresh helpers; no fs writes), `orchestration-write.mjs` (the **only** config fs-writer — a deployment-gated, atomic, symlink/TOCTOU-safe `writeConfig`; imported by `set-recipe` alone, never by `procedures`), `set-recipe.mjs` (the **config writer** behind `/agent-workflow-kit set-recipe` — validate → merge → preview-by-default → write; never runs a backend, never commits), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
+- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `commands.mjs` (the canonical **command catalog** + the pure `routeInvocation` router behind `/agent-workflow-kit help` and the safe unknown-invocation routing rule — one source of truth for the command surface, drift-guarded against the `### Mode:` headers), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded **two-slot** reconciliation — ensure-slot / inject-if-empty / cap for the `workflow:methodology` **and** `workflow:orchestration` pointers; both fragments read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` (`deps.rel` selects which) — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent, orchestration soft-skipped when it would bust the cap), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`; exports the readiness consts the planner reuses), `recipes.mjs` (the read-only **recipe planner** behind `/agent-workflow-kit recipes` — `RECIPES` / `planRecipe` / `recommendRecipe` over the bridges' role vocabulary, drift-guarded against `provides`/`cost`/`quota` + an engine↔kit recipe-name parity guard; pure, never runs a subscription CLI; also exports the pure `ACTIVITIES` / `resolveActivityRecipe` activity-procedures resolver and the machine-composed one-line backend status — `composeStatusLine` behind `--status-line`, pasted verbatim by the bootstrap/upgrade report footers), `procedures.mjs` (the read-only **activity-procedures advisor** behind `/agent-workflow-kit procedures` — reads `references/procedures.md` live from the engine via `engine-source.mjs`, reads + validates the agent-writable `docs/ai/orchestration.json` via `orchestration-config.mjs`, and prints the steps + the resolved effective recipe per slot; drift-guarded activity/slot table vs the canon; read-only, never imports the writer, never runs a subscription CLI), `orchestration-config.mjs` (the config **schema/read/pure-transform core** — `loadConfig`/`validateConfig`/the shared slot-recipe validity + `parseOp`/`applySetOps`/`serializeConfig`/the canonical-refresh helpers; no fs writes), `orchestration-write.mjs` (the **only** config fs-writer — a deployment-gated, atomic, symlink/TOCTOU-safe `writeConfig`; imported by `set-recipe` alone, never by `procedures`), `set-recipe.mjs` (the **config writer** behind `/agent-workflow-kit set-recipe` — validate → merge → preview-by-default → write; never runs a backend, never commits), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
 - [`capability.json`](capability.json) — the kit's own `agent-workflow` family manifest (`kind: composition-root`).
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/bin/install.mjs

@@ -23,8 +23,10 @@
 // member — the memory substrate (`npx @sabaiway/agent-workflow-memory@latest init`, best-effort: a
 // failure is a loud DEGRADED success, never silent — skippable with `--no-memory`) and the
 // methodology engine the kit reads live (`npx @sabaiway/agent-workflow-engine@latest init`, fatal —
-// the live read STOPs without it — skippable with `--no-engine`). The bridges are NOT installed by
-// `init` (placed by `/agent-workflow-kit setup`). No tracking either way.
+// the live read STOPs without it — skippable with `--no-engine`). The bridges are never PLACED by
+// `init` (first placement stays `/agent-workflow-kit setup`, opt-in); once placed, `init` REFRESHES
+// them from this package's own bundled copies — a purely LOCAL copy, no third server contact —
+// skippable with `--no-bridges`. No tracking either way.
 //
 // Dependency-free, Node >= 18.
 
@@ -35,11 +37,22 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { copyTreeRefresh } from '../tools/fs-safe.mjs';
+// Dependency-free semver, shared with the family registry's bridge freshness probe (one leaf, no
+// second drifting copy). The null-on-unparseable contract is load-bearing here: legacy installs
+// predate any version stamp, so an unparseable side means "no gate", never a false ordering.
+import { compareSemver } from '../tools/semver-lite.mjs';
 // The ONE registry of family members (npm packages, kinds). The init-refresh cascade derives its
 // membership from this table — no second source of "who gets refreshed" — so it can't drift from the
 // manifests (a drift-guard test pins the derivation). Imported from the DATA LEAF (family-members.mjs),
-// NOT family-registry.mjs, so the npx cold-start path stays lean (no status/presenter graph pulled in).
+// NOT family-registry.mjs. Leanness note: the bridge-refresh driver below does pull in the backend
+// detector + the manifest validator (setup-backends' imports), but still NOT the status/presenter
+// graph (family-registry, renderers, recipes) — the npx cold-start path stays presenter-free.
 import { FAMILY_MEMBERS } from '../tools/family-members.mjs';
+// The refresh-only bridge driver (shared with `/agent-workflow-kit setup --refresh-placed` and the
+// upgrade reconcile): refreshes ONLY a bridge `setup` already placed — an absent bridge is a stated
+// skip (never a first placement, AD-009/AD-011) and a placed bridge newer than this kit's bundled
+// mirror is a stated skip too (never a downgrade). Every line it returns is tool-composed.
+import { refreshPlacedBridges } from '../tools/setup-backends.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -81,22 +94,6 @@ const readVersion = async () => {
   }
 };
 
-// Dependency-free semver: parse the leading `x.y.z` (prerelease/build ignored — kit versions are
-// plain). compareSemver returns -1 | 0 | 1, or null when either side is unparseable (legacy installs
-// predate any version stamp). No `let`: a small functional comparison (AGENTS.md §2.3).
-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;
-};
-
-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;
-};
-
 // Extract the version that is a DIRECT child of the top-level `metadata:` key — never a top-level
 // or deeper-nested decoy `version:` (mirrors the manifest validator's rigor; the kit ships manifest
 // fixtures that probe exactly those decoys). Pure string walk over the frontmatter block, no deps.
@@ -157,6 +154,7 @@ const parseArgs = (argv) => {
     noLaunchers: argv.includes('--no-launchers'),
     noMemory: argv.includes('--no-memory'),
     noEngine: argv.includes('--no-engine'),
+    noBridges: argv.includes('--no-bridges'),
     force: argv.includes('--force'),
     allowDowngrade: argv.includes('--allow-downgrade'),
     dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
@@ -278,7 +276,7 @@ const printHelp = (version) => {
   console.log(`agent-workflow-kit ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--no-memory] [--no-engine] [--force] [--allow-downgrade]
+  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--no-memory] [--no-engine] [--no-bridges] [--force] [--allow-downgrade]
   npx @sabaiway/agent-workflow-kit@latest --version
   npx @sabaiway/agent-workflow-kit@latest --help
 
@@ -294,8 +292,10 @@ Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
   stale, refresh it yourself + restart — a miss is otherwise a non-fatal degraded success,
   never the engine's hard STOP); --no-engine skips the engine install (the live methodology
   read then STOPs until you install it by hand); --force replaces a pre-existing non-kit
-  launcher file (backed up first). The bridges are NOT installed by init (placed by
-  /agent-workflow-kit setup). init is additive — it never deletes your settings. If the
+  launcher file (backed up first). The bridges are never PLACED by init (first placement
+  stays /agent-workflow-kit setup, opt-in); once placed, init refreshes them from the kit's
+  own bundled copies — local files only, never a downgrade — and --no-bridges skips that
+  refresh. init is additive — it never deletes your settings. If the
   installed kit is newer than the version you ran, init refuses (no network — it compares
   the version on disk) and points you at @latest; --allow-downgrade overrides that
   refusal (distinct from --force, which is launcher-only).
@@ -376,15 +376,26 @@ const main = async () => {
       console.log(`[agent-workflow-kit] removed retired file ${tildify(retired)} (now read live from the engine).`);
     }
   }
-  console.log(`[agent-workflow-kit] ${wasPresent ? 'updated the kit to' : 'installed'} v${version} -> ${tildify(target)}`);
-
-  // No-op re-run: the install just refreshed the skill with the SAME version it already had. For a
-  // user who ran `init` expecting an upgrade, that almost always means npx reused a cached build —
-  // say so explicitly and point at @latest (the no-network signal that catches the reported scenario).
+  // Verb keyed on the OBSERVED version relation (cmp), never on mere presence: null (fresh install,
+  // or a legacy/unstamped one whose prior version is unknowable) → "installed"; -1 → a real update;
+  // 0 → already current (the copy still ran — see the note below); 1 is reachable only under
+  // --allow-downgrade (the gate above refused otherwise) and says so plainly. One message contract
+  // with the engine installer (same shapes, member noun differs).
+  const verb =
+    cmp === 0 ? 'refreshed the already-current kit'
+    : cmp === 1 ? 'downgraded the kit to'
+    : cmp === -1 ? 'updated the kit to'
+    : 'installed';
+  console.log(`[agent-workflow-kit] ${verb} v${version} -> ${tildify(target)}`);
+
+  // Same-version re-run: state observable facts only. The copy DID run (repair-on-rerun is a feature —
+  // it restores locally modified/deleted files), and whether npx served a cached build is NOT
+  // observable here (no network), so the note never claims it; the @latest hint is conditional.
   if (cmp === 0) {
     console.log(
-      `[agent-workflow-kit] note: no version change — the kit was already v${version}. If you expected ` +
-        `an update, npx likely served a cached build; re-run bypassing the cache:\n` +
+      `[agent-workflow-kit] note: the kit was already v${version} — the copy still ran, restoring ` +
+        `any locally modified or deleted kit file to this version's packaged contents. If you ` +
+        `expected a NEWER version, invoke the @latest tag explicitly:\n` +
         `    npx @sabaiway/agent-workflow-kit@latest init`,
     );
   }
@@ -404,6 +415,40 @@ const main = async () => {
     }
   }
 
+  // Placed-bridge refresh — AFTER the kit copy (the bundled bridges/ just landed), BEFORE the two
+  // network cascade steps (this one is LOCAL files only: bundle → placed copy). Refresh-only, so the
+  // AD-009/AD-011 honesty claim survives as "init never PLACES bridges; it refreshes what setup
+  // already placed" — an absent bridge is a stated skip, a placed-newer one a stated skip too (never
+  // a downgrade). Best-effort in the memory DEGRADED shape: any miss is a loud warning + a
+  // host-runnable recovery composed from the RESOLVED target (a --dir / AGENT_WORKFLOW_KIT_DIR
+  // install must get a line that runs) + exit 0 — never silent, never the engine's hard STOP.
+  const bridgeRefreshCmd = `node ${tildify(resolve(target, 'tools/setup-backends.mjs'))} --refresh-placed`;
+  if (args.noBridges) {
+    console.log(
+      `[agent-workflow-kit] --no-bridges: skipped refreshing the placed bridges. If one is stale, ` +
+        `refresh it yourself:\n    ${bridgeRefreshCmd}`,
+    );
+  } else if (process.platform === 'win32') {
+    console.log('[agent-workflow-kit] Windows: skipped the placed-bridge refresh (POSIX wrappers — refresh under WSL).');
+  } else {
+    console.log('[agent-workflow-kit] refreshing the bridges setup already placed (an absent bridge is never placed here):');
+    try {
+      const results = refreshPlacedBridges();
+      for (const r of results) console.log(r.line);
+      if (results.some((r) => r.outcome === 'failed')) {
+        console.warn(
+          `[agent-workflow-kit] could not refresh every placed bridge — continuing; the kit itself IS ` +
+            `installed and works. Re-run the refresh yourself:\n    ${bridgeRefreshCmd}`,
+        );
+      }
+    } catch (err) {
+      console.warn(
+        `[agent-workflow-kit] could not refresh the placed bridges (${err.message}) — continuing; the ` +
+          `kit itself IS installed and works. Re-run the refresh yourself:\n    ${bridgeRefreshCmd}`,
+      );
+    }
+  }
+
   // Memory substrate refresh — AFTER the kit + launchers, BEFORE the (fatal) engine and the success
   // block, so a returning `init` leaves no stale memory. Unlike the engine, a memory miss is a
   // DEGRADED success: warn with the exact recovery command + the on-disk version (read crash-proof)

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/tools/family-members.mjs

@@ -13,7 +13,8 @@
 // ── the unified registry ───────────────────────────────────────────────────────
 // One entry per family member. `installed` is the detect.installed spec (env + home-relative default
 // + marker file); `deployed` is the project-relative stamp a deploy writes (kit + memory only);
-// `npm` is the install package (null for the bridges, which are placed by `setup`, not npm);
+// `npm` is the install package (null for the bridges — placed by `setup`, and once placed refreshed
+// by `init`/`upgrade` from the kit's bundled copies, never npm);
 // `wrapperCmds` is the deduped roles[].cmd set the `setup` linker creates on PATH (bridges only).
 // Kept in lockstep with the 5 in-repo capability.json by the drift-guard test. The two release skills
 // (release-engineering / release-marketing) are deliberately NOT here — they are not family members

package/tools/family-registry.mjs

@@ -17,10 +17,13 @@
 // side effects on import (the isDirectRun idiom) — tests import the helpers with nothing run.
 
 import { existsSync, statSync, readFileSync, lstatSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve, dirname } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import os from 'node:os';
 import { resolveDir, detectBackends, findOnPath } from './detect-backends.mjs';
+// The ONE dependency-free semver (shared with bin/install.mjs) — the bridge freshness probe compares
+// the placed version against the kit-bundled mirror; null-on-unparseable maps to 'unknown' (INV-B).
+import { parseSemver, compareSemver } from './semver-lite.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
 import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
@@ -57,6 +60,10 @@ import {
   VISIBILITY_PUBLIC,
   DISPLAY_NAMES,
   displayOf,
+  FRESH_CURRENT,
+  FRESH_BEHIND,
+  FRESH_UNKNOWN,
+  FRESH_NOT_CHECKED,
 } from './labels.mjs';
 // The capability-adaptive direct-CLI presenter (Plan §4.2/§4.5): the surface detector, the
 // envelope→ViewModel transform, and the plain/ansi renderers. main() composes them; the agent-mediated
@@ -135,7 +142,18 @@ export const classifyMember = (member, deps = {}) => {
   const report = markerPresent ? validate(skillDir) : { result: NOT_INSTALLED };
   const manifestState = classifyState(markerPresent, report, member);
   const installed = manifestState !== NOT_INSTALLED;
-  const version = manifestState === OK ? readVersion(skillDir).version ?? null : null;
+  // Crash-safe version read: readAuthoritativeVersion THROWS on a present-but-unreadable SKILL.md
+  // (stat needs no read permission, readFileSync does — a TOCTOU/EACCES window after validate).
+  // The read-only survey must never crash on it: degrade to null, which the bridge freshness probe
+  // then reports as 'unknown' (INV-B), never as a throw and never as a silent claim.
+  const version = (() => {
+    if (manifestState !== OK) return null;
+    try {
+      return readVersion(skillDir).version ?? null;
+    } catch {
+      return null;
+    }
+  })();
 
   return { name: member.name, kind: member.kind, installed, skillDir: installed ? skillDir : null, manifestState, version };
 };
@@ -165,6 +183,51 @@ export const MEMORY_ORCH_TEMPLATE_REL = 'references/templates/orchestration.json
 const MEMORY_BEHIND_NOTE =
   "the memory installed here doesn't include the current orchestration template — refresh it with `npx @sabaiway/agent-workflow-memory@latest init`, then restart the session.";
 
+// ── the bridge freshness probe (deterministic-first — INV-A / INV-B) ─────────────
+// The bridges are not npm packages: their ONLY delivery channel is the copy bundled inside this kit
+// (`bridges/<name>/`, placed by `/agent-workflow-kit setup`). A placed bridge therefore has exactly
+// one authoritative freshness comparison — its installed version (readAuthoritativeVersion, already
+// on the row) vs the kit-bundled mirror's capability.json. BOTH are local files, so the "never
+// checks npm" invariant holds. The probe sets the internal row field `freshness`
+// ('behind' | 'current' | 'unknown'); refreshOf derives the public refresh block STRUCTURALLY from
+// that field (INV-2 — never parsed from caveat text). INV-B: an unreadable/unparseable version on
+// EITHER side degrades to 'unknown' + a plain-language note — never a false claim in either direction.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// bridges/ ships beside tools/ in both the repo and the installed kit (the setup-backends.mjs
+// resolution), so this resolves in both. Injectable via deps.bundleRoot for tests.
+const BUNDLE_ROOT = resolve(__dirname, '..', 'bridges');
+
+// Crash-safe on the bundled side: an absent / unreadable / malformed bundle manifest → null (INV-B
+// 'unknown'), never a throw — the read-only survey must survive a broken kit install.
+const readBundledBridgeVersion = (name, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const root = deps.bundleRoot ?? BUNDLE_ROOT;
+  try {
+    const manifest = JSON.parse(String(read(join(root, name, 'capability.json'), 'utf8')));
+    return typeof manifest.version === 'string' ? manifest.version : null;
+  } catch {
+    return null;
+  }
+};
+
+const bridgeBehindNote = (display, placed, bundled) =>
+  `the ${display} installed here (v${placed}) is older than the copy bundled with this kit (v${bundled}) — refresh it with \`/agent-workflow-kit setup\`.`;
+// The recovery differs per failing SIDE: `setup` re-places FROM the bundle, so it can repair an
+// unreadable INSTALLED copy but can never repair an unreadable BUNDLED copy — that needs a kit
+// refresh first (the npx installer), then `setup`.
+const bridgeUnknownNote = (display, side, recovery) =>
+  `couldn't compare the ${display} installed here with the copy bundled with this kit (${side}), so its freshness is unknown — ${recovery}.`;
+const UNKNOWN_SIDES = Object.freeze({
+  placed: {
+    side: 'the installed copy has no readable version',
+    recovery: '`/agent-workflow-kit setup` re-places the bundled copy',
+  },
+  bundled: {
+    side: "the kit's bundled copy has no readable version",
+    recovery: 'refresh the kit first (`npx @sabaiway/agent-workflow-kit@latest init`), then `/agent-workflow-kit setup`',
+  },
+});
+
 export const surveyFamily = (deps = {}) =>
   FAMILY_MEMBERS.map((member) => {
     const row = classifyMember(member, deps);
@@ -184,8 +247,30 @@ export const surveyFamily = (deps = {}) =>
     // Only attach when it is provably ABSENT (a non-ENOENT probe error → 'unknown' → skip, never a
     // false "missing" claim). Mirrors the engine-caveat SHAPE; keyed on the Step-2.4 required asset.
     if (row.kind === 'memory-substrate' && row.manifestState === OK && row.skillDir) {
-      if (probeMarker(join(row.skillDir, MEMORY_ORCH_TEMPLATE_REL), deps) === 'absent') {
+      const templateProbe = probeMarker(join(row.skillDir, MEMORY_ORCH_TEMPLATE_REL), deps);
+      if (templateProbe === 'absent') {
         row.caveats = [...(row.caveats ?? []), MEMORY_BEHIND_NOTE];
+      } else if (templateProbe === 'unknown') {
+        // Could not verify → this row must not be counted "checked, current" by the verdict (INV-B).
+        row.freshness = FRESH_UNKNOWN;
+      }
+    }
+    // Bridge freshness probe (INV-A / INV-B): only for a provably-OURS placed bridge (manifestState
+    // OK). Compares two LOCAL files; a non-OK / absent bridge is out of scope ('not-checked').
+    if (row.kind === 'execution-backend' && row.manifestState === OK && row.skillDir) {
+      const bundled = readBundledBridgeVersion(row.name, deps);
+      const cmp = compareSemver(row.version, bundled);
+      if (cmp === null) {
+        const { side, recovery } = parseSemver(row.version) === null ? UNKNOWN_SIDES.placed : UNKNOWN_SIDES.bundled;
+        row.freshness = FRESH_UNKNOWN;
+        row.caveats = [...(row.caveats ?? []), bridgeUnknownNote(displayOf(row.name), side, recovery)];
+      } else if (cmp < 0) {
+        row.freshness = FRESH_BEHIND;
+        row.caveats = [...(row.caveats ?? []), bridgeBehindNote(displayOf(row.name), row.version, bundled)];
+      } else {
+        // Equal OR newer-than-bundled → not behind. A newer placed bridge is a Phase-2 concern for
+        // the refresh DRIVER (INV-D never-downgrade skip); the read-only status axis never flags it.
+        row.freshness = FRESH_CURRENT;
       }
     }
     return row;
@@ -376,18 +461,31 @@ export const surveyBridges = (deps = {}) => {
   });
 };
 
-// INV-2 (structural refresh — additive, derived, never parsed from a caveat string). A member is
-// `behind` when it is a refreshable CORE member (memory / engine) carrying a refresh-recommending
-// caveat — surveyFamily attaches caveats ONLY to those two kinds, and today every such caveat is
-// refresh-recommending. `recommend` is composed from the member's npm package in the ONE registry
-// (FAMILY_MEMBERS[].npm), never extracted from the caveat text. The kit (composition-root) + the two
-// bridges (execution-backend) never carry such a caveat, so they derive { behind:false, recommend:null }
-// — gated by the CAVEAT, not by npm-nullness (the kit's npm is non-null; only the bridges are null).
+// INV-2 (structural refresh — additive, derived, never parsed from a caveat string), per KIND:
+//   • memory / engine (REFRESHABLE_KINDS): `behind` ⟷ an OK row carrying a refresh-recommending
+//     caveat (surveyFamily attaches caveats to those kinds only then, and every such caveat is
+//     refresh-recommending); `recommend` is composed from FAMILY_MEMBERS[].npm — never the caveat text.
+//   • execution-backend: `behind` ⟷ the bridge freshness probe's row field (freshness === 'behind');
+//     `recommend` is composed PER-KIND — bridges have npm:null (placed by `setup`, never npx), so the
+//     runnable recovery is `/agent-workflow-kit setup`, never an npx composition.
+//   • composition-root (the kit): no freshness probe exists on this surface (the two-axes doctrine —
+//     kit freshness is the npx installer's axis) → never behind, 'not-checked'.
+// `freshness` is the checked-vs-unknown signal the zero-behind verdict scopes itself with (INV-C):
+// behind:false alone cannot distinguish "checked, current" from "could not be checked".
 const REFRESHABLE_KINDS = new Set(['memory-substrate', 'methodology-engine']);
 const npmOf = (name) => FAMILY_MEMBERS.find((m) => m.name === name)?.npm ?? null;
+export const BRIDGE_REFRESH_RECOMMEND = '/agent-workflow-kit setup';
 const refreshOf = (m) => {
+  if (m.kind === 'execution-backend') {
+    const freshness = m.freshness ?? FRESH_NOT_CHECKED;
+    const behind = freshness === FRESH_BEHIND;
+    return { behind, recommend: behind ? BRIDGE_REFRESH_RECOMMEND : null, freshness };
+  }
   const behind = REFRESHABLE_KINDS.has(m.kind) && Boolean(m.caveats?.length);
-  return { behind, recommend: behind ? `npx ${npmOf(m.name)}@latest init` : null };
+  const freshness = REFRESHABLE_KINDS.has(m.kind) && m.manifestState === OK
+    ? m.freshness ?? (behind ? FRESH_BEHIND : FRESH_CURRENT)
+    : FRESH_NOT_CHECKED;
+  return { behind, recommend: behind ? `npx ${npmOf(m.name)}@latest init` : null, freshness };
 };
 
 export const buildEnvelope = (family, project = null, extras = {}) => {
@@ -399,7 +497,7 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
       state: STATE_PUBLIC[m.manifestState] ?? STATE_PUBLIC[UNKNOWN],
     };
     if (m.caveats?.length) entry.notes = m.caveats; // plain-language observations (Steps 2.2 / engine)
-    entry.refresh = refreshOf(m); // additive (INV-1): always present; { behind, recommend } (INV-2)
+    entry.refresh = refreshOf(m); // additive (INV-1): always present; { behind, recommend, freshness } (INV-2)
     return entry;
   });
   const envelope = { deploymentHead: EXPECTED_WORKFLOW_VERSION, installed };

package/tools/labels.mjs

@@ -41,6 +41,19 @@ export const STATE_PUBLIC = Object.freeze({
 // "hidden fence" / marker terms. ('hidden' here is the PUBLIC visibility word, not the internal fence.)
 export const VISIBILITY_PUBLIC = Object.freeze({ visible: 'visible', hidden: 'hidden', ambiguous: 'unclear' });
 
+// ── refresh freshness tokens (PUBLIC — the envelope's installed[].refresh.freshness) ────────────────
+// The checked-vs-unknown signal the zero-behind verdict scopes itself with (INV-C): `behind:false`
+// alone cannot distinguish "checked, current" from "could not be checked".
+//   'current' / 'behind' — a freshness probe RAN and concluded (these two are the "checked" scope);
+//   'unknown'            — a probe ran but could not conclude (INV-B: never collapsed to a claim
+//                          in either direction);
+//   'not-checked'        — no freshness probe exists for this member/state (e.g. the kit itself:
+//                          its freshness is the npx installer's axis, never checked here).
+export const FRESH_CURRENT = 'current';
+export const FRESH_BEHIND = 'behind';
+export const FRESH_UNKNOWN = 'unknown';
+export const FRESH_NOT_CHECKED = 'not-checked';
+
 // Short, user-facing labels for the version block (kit · memory · engine · codex-bridge · …), so the
 // render is deterministic and the agent never invents a label.
 export const DISPLAY_NAMES = Object.freeze({

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