@sabaiway/agent-workflow-kit 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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.8.0 — Stale-version DX: `@latest` everywhere + a no-network never-downgrade gate
+
+A returning user ran the headline `npx @sabaiway/agent-workflow-kit init` and it quietly did nothing:
+a bare `npx <pkg> init` (no `@latest`) reuses the npx cache and re-runs an **older cached build** of
+the installer, which exits 0 and reports it "updated" — to the same stale version. This release makes
+that mistake hard to miss while **the installer itself stays 100% network-free** — the only thing
+that ever contacts npm is npx resolving `@latest`, exactly as it already does (the no-phone-home
+principle is preserved; see AD-012):
+
+- **`@latest` is the documented default everywhere.** Every prescribing surface (both READMEs, the
+  bridge `SKILL.md` files + their bundled mirrors, the installer `--help` / header) now shows
+  `npx @sabaiway/agent-workflow-kit@latest init`. A new drift guard
+  (`test/init-command-uses-latest.test.mjs`) fails the build if a bare form sneaks back in (historical
+  contexts — CHANGELOG / `releases/` / `migrations/` — are exempt).
+- **Never-downgrade gate (no network).** `init` reads the installed skill's version from
+  `SKILL.md` **before** writing; if the installed kit is **newer** than the version you ran (the exact
+  stale-cache signature), it **refuses** (nonzero) and points at `@latest`, rather than silently
+  overwriting a newer install with old code. `--force` overrides. A legacy install with no version
+  stamp still upgrades cleanly.
+- **No-op re-run hint.** When `init` refreshes the skill with the *same* version it already had, it
+  says so and points at `@latest` — the no-network signal that catches the reported scenario.
+- **In-agent skill** (`SKILL.md`): surfaces a one-line version status (project `docs/ai/.workflow-version`
+  vs the lineage head) + routes (bootstrap / upgrade / current), spells out the **two independent
+  version axes** (project deployment vs kit freshness — the latter is the npx installer's job, never
+  this skill's), and tells you to **restart the session** after refreshing the kit so the new skill
+  files load.
+
+New users are unaffected (an empty npx cache already fetches `latest`); this targets the returning-user
+trap. No `docs/ai` structural change → the deployment-lineage head stays **`1.3.0`**; no migration.
+
+## 1.7.0 — Link-only backend auto-setup; bridges bundled in the tarball
+
+The optional execution-backend bridges (`codex-cli-bridge` → `codex`, `antigravity-cli-bridge` →
+`agy`) can now be set up from the kit itself, via a new **opt-in, in-agent** mode —
+**`/agent-workflow-kit setup [backend]`** (`tools/setup-backends.mjs`). It owns only the two
+**deterministic, secret-free** steps and **guides** the rest (AD-011):
+
+- **Bridges are bundled in the kit's npm tarball** under `bridges/<name>/` — a **byte-identical
+  mirror** of the repo-root bridges, pinned by `test/bridges-mirror.test.mjs` (the same drift-guard
+  pattern as the methodology mirror). So `setup` places a bridge from local files, with **no network
+  fetch**. `init` (npx) bundles them but still **does not place** them — that stays the opt-in
+  `setup` job (preserving the honest `init` ≠ deploy claim).
+- **`setup` places/refreshes the bundled bridge skill**, but only into a dir that is **absent /
+  empty / proven-managed** (valid manifest, matching `name`+`kind`); a stub/foreign/invalid/
+  unsupported manifest, a marker fs-error, a non-empty unknown dir, or a symlinked dir → **STOP**,
+  never overwritten. Refresh re-runs on a managed dir so re-running `setup` delivers bundled fixes.
+- **It links the wrappers** (`codex-exec` / `codex-review`; `agy-run`) onto `PATH` (`~/.local/bin`,
+  override with `--bindir`) via **managed symlinks** — replacing only a symlink already pointing at
+  our source. It **preflights every target first**, so a conflict on one wrapper makes **zero**
+  changes; a non-symlink or a foreign symlink → STOP. Wrapper presence is judged **per-bindir**, not
+  PATH-wide. `--dry-run` prints the plan and changes nothing.
+- **The binary install + the interactive subscription login stay manual** — `setup` prints the exact
+  commands (the detector's axis-aware `guideFor`), never runs a subscription CLI, never commits. On
+  **Windows** it reports *unsupported — use WSL* and mutates nothing (the wrappers are POSIX `.sh`).
+- Internal: the symlink-traversal-safe copy/link primitives are now shared in `tools/fs-safe.mjs`
+  (the npx installer consumes them and gained an `isDirectRun` guard so importing it runs nothing).
+  The per-package publish workflow now gates the kit on its **whole** test suite, not just the
+  shipped enforcement scripts.
+
+No `docs/ai` structural change → the deployment-lineage head stays **`1.3.0`**; no migration.
+
 ## 1.6.0 — Methodology slot reconciliation; engine becomes the canonical methodology home
 
 The workflow methodology now has a **single canonical home** in `agent-workflow-engine`

package/README.md

@@ -18,7 +18,7 @@ decisions. Works with Claude Code, Codex, Cursor, and any agent that reads `AGEN
 **One command to start:**
 
 ```bash
-npx @sabaiway/agent-workflow-kit init
+npx @sabaiway/agent-workflow-kit@latest init
 ```
 
 <sub>This installs the **global skill** — deploying into a project is a separate step ([below](#-install)).</sub>
@@ -134,7 +134,7 @@ Hidden changes how the files are *tracked*, not where agents find them.
 ### 1. Install the global skill — once per machine
 
 ```bash
-npx @sabaiway/agent-workflow-kit init
+npx @sabaiway/agent-workflow-kit@latest init
 ```
 
 `init` installs/refreshes the skill at `~/.claude/skills/agent-workflow-kit/` and wires launchers for
@@ -216,6 +216,7 @@ command is printed).
 | `/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 |
 | `/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. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 
@@ -248,17 +249,20 @@ agent-workflow-kit  —  the composition root (installed via npx … init)
    ├─ delegates ─▶ memory substrate   (healthy copy, else bundled fallback)
    ├─ injects   ─▶ workflow methodology  (engine = future supplier; stub)
    ├─ deploys   ─▶ AGENTS.md + docs/ai/ + Node scripts + pre-commit hook
-   └─ detects   ─▶ optional backends     (codex / agy — not by init)
+   ├─ detects   ─▶ optional backends   (codex / agy, read-only)
+   └─ sets up   ─▶ a bridge (opt-in)   (place skill + link wrappers)
 ```
 
 - **Delegates** substrate deployment to **`@sabaiway/agent-workflow-memory`** when a healthy
   standalone copy is present, else uses its **bundled fallback** — same `docs/ai/` either way.
 - **Injects** the bounded workflow methodology into the deployed `AGENTS.md`. Its *future* home is
   **`agent-workflow-engine`** — today an `available: false` stub, never one of the shipped backends.
-- **Detects** the optional `codex` / `agy` **bridges** — agent skills with a manual once-per-machine
-  setup (not npm, not installed by `init`); `/agent-workflow-kit backends` reports readiness
-  read-only. A bridge reads the deployed memory only if it wins that tool's context-file priority,
-  and the bridges call third-party services (so "no telemetry" covers family code, not those).
+- **Detects & (opt-in) sets up** the optional `codex` / `agy` **bridges** — agent skills (not npm, not
+  installed by `init`). `/agent-workflow-kit backends` reports readiness **read-only**;
+  `/agent-workflow-kit setup` does the **link-only** part (place the bundled bridge skill + link its
+  wrappers), while the binary install + the subscription login stay manual. A bridge reads the deployed
+  memory only if it wins that tool's context-file priority, and the bridges call third-party services
+  (so "no telemetry" covers family code, not those).
 
 > Full member-by-member map + the whole-family story: the
 > **[family front door](https://github.com/sabaiway/agent-workflow#readme)** — this page stays the
@@ -295,7 +299,10 @@ agent-workflow-kit/
 │   ├── delegation.mjs        ← detect substrate · delegate-or-fall-back
 │   ├── inject-methodology.mjs ← write the methodology slot
 │   ├── detect-backends.mjs    ← read-only backend detector
+│   ├── setup-backends.mjs     ← link-only backend setup
+│   ├── fs-safe.mjs            ← symlink-safe copy/link
 │   └── release-scan.mjs       ← attribution / release gate
+├── bridges/         ← bundled bridge skill mirrors (codex / antigravity)
 ├── launchers/       ← Codex / Devin Desktop / Cursor entries
 └── migrations/      ← per-version upgrade steps
 ```

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.6.0'
+  version: '1.8.0'
 ---
 
 # agent-workflow-kit
@@ -83,6 +83,23 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit`** (default) — bootstrap a new or empty project. If `docs/ai/` already exists, stop and ask whether they meant `upgrade`.
 - **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
 - **`/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.
+
+### Version status & the two axes — surface this on every invocation
+
+Before acting, read `docs/ai/.workflow-version` (the project's stamp), state a one-line status, then route:
+
+- **absent** → bootstrap (a fresh deployment).
+- **stamp < `1.3.0`** (the deployment-lineage head) → `upgrade`.
+- **stamp == `1.3.0`** → already current; only the stamp-independent methodology-slot reconcile may run.
+- **stamp > head / unparseable** → STOP — never-downgrade gate (see *Mode: upgrade* step 2).
+
+**Two independent version axes — never conflate them:**
+
+1. **Project deployment** — `docs/ai/.workflow-version` vs the lineage head (`1.3.0`). This is the **only** axis this skill compares.
+2. **Kit freshness** — this skill's own files vs the published npm package. That is the **npx installer's** job: `npx @sabaiway/agent-workflow-kit@latest init` (it refuses a stale-cache downgrade by comparing the version on disk — **no network**). This skill never checks npm, and the package version (e.g. `1.x`) is **not** the lineage head.
+
+**Refreshed the kit but nothing changed?** The skill you are running is whatever was on disk when the session started. After `npx @sabaiway/agent-workflow-kit@latest init` updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files (the slash command + this `SKILL.md`).
 
 ### Mode: bootstrap
 
@@ -145,6 +162,26 @@ Read-only. Answers *"which optional execution-backends are set up vs missing, an
    - **"credentials present"** means the credential-marker **file** exists — it is **not** a live login check. The detector never runs `codex login status` / `agy` (that would spawn a paid, slow, networked subscription CLI).
    - The bridges' wrappers are **POSIX `.sh`** scripts. On Windows the detector still works, but the bridges themselves are **not promised to run** — say so rather than implying they will.
 
+### 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**.
+
+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).
+- `--help`, `-h` — usage.
+
+For each backend it:
+1. **Places / refreshes the bundled bridge skill** (from the kit's `bridges/<name>/` mirror) into its canonical dir — but only when that dir is **absent / empty / proven-managed** (valid manifest, matching `name`+`kind`). A `stub` / `foreign` / `invalid` / `unsupported` dir, a marker fs-error, or a symlinked dir → **STOP**, never overwritten. Refresh re-runs on a proven-managed dir so re-running `setup` delivers bundled fixes.
+2. **Links its wrappers** (`codex-exec` / `codex-review`; `agy-run`) onto `--bindir` via **managed symlinks** — replacing only a symlink that already points at our source. A non-symlink or a foreign symlink → **STOP**; it **preflights every target first**, so a conflict on one wrapper makes **zero** changes. If `--bindir` is not on `PATH`, it prints the one-line `export PATH=…` to add — it never edits a shell rc.
+3. **Guides the manual, secret-bearing steps it will NOT automate** — the binary install (each bridge's `setup/README.md` §1) and the one-time interactive subscription login (`codex login` / `agy`) — printing the exact command for whichever axis is still missing (axis-aware: it can ask for both the CLI and the login at once).
+
+**Windows:** the wrappers are POSIX `.sh`; on `win32` it reports *unsupported — use WSL* and mutates nothing.
+
+**Exit codes:** `0` = done / already set up / only manual steps remain (guidance is never a failure); **non-zero** = a STOP (a dir/symlink it refuses to clobber), a bad argument, a missing bundle, or a native fs error (the underlying reason is preserved in the message).
+
 ---
 
 ## Gotchas
@@ -214,6 +251,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), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is a byte-identical mirror of the `agent-workflow-engine` canon, pinned by `methodology-mirror.test.mjs`), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`), and `release-scan.mjs` (the attribution-off release gate). 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), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is a byte-identical mirror of the `agent-workflow-engine` canon, pinned by `methodology-mirror.test.mjs`), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`), `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 primitives both `setup-backends` and the npx installer use), 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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // One-shot installer for @sabaiway/agent-workflow-kit.
 //
-//   npx @sabaiway/agent-workflow-kit init
+//   npx @sabaiway/agent-workflow-kit@latest init
 //
 // Copies the kit into the canonical skill home (~/.claude/skills/agent-workflow-kit),
 // then runs the cross-agent launcher (auto-detects Codex / Devin Desktop — only touches tools
@@ -14,23 +14,30 @@
 // docs/ai deployment — see README "Use".
 //
 // No telemetry, no phone-home: adoption is the npm registry's public, passive per-version
-// download numbers (api.npmjs.org/downloads). Nothing here contacts a server.
+// download numbers (api.npmjs.org/downloads). Nothing here contacts a server — including the
+// stale-version defenses below, which compare the version already on disk (the installed SKILL.md)
+// against this runner's own version, never the registry. That is why `@latest` (above) is the
+// documented form: a bare `npx … init` can reuse an OLDER cached build of this installer, so a
+// returning user must bypass the cache to actually upgrade. See decisions.md AD-012.
 //
 // Dependency-free, Node >= 18.
 
-import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
+import { readFile, mkdir } from 'node:fs/promises';
 import { existsSync, lstatSync } from 'node:fs';
-import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { copyTreeRefresh } from '../tools/fs-safe.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
 
 // The deployable skill = everything except the npm wrapper (package.json, bin/).
 // capability.json (the family manifest) + tools/ (the family schema + validator the kit runs
-// as the memory detector) must land in the installed skill dir too.
+// as the memory detector) must land in the installed skill dir too. bridges/ carries the
+// byte-identical execution-backend skill mirrors (codex/antigravity) so `setup` can place a bridge
+// from the installed kit, with no network fetch (Plan B / AD-011).
 const PAYLOAD = [
   'SKILL.md',
   'README.md',
@@ -40,6 +47,7 @@ const PAYLOAD = [
   'launchers',
   'migrations',
   'tools',
+  'bridges',
 ];
 
 const tildify = (path) => path.replace(homedir(), '~');
@@ -53,6 +61,58 @@ 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.
+const metadataVersion = (frontmatter) => {
+  const lines = frontmatter.split(/\r?\n/);
+  const metaIdx = lines.findIndex((l) => /^metadata:[ \t]*$/.test(l));
+  if (metaIdx === -1) return null;
+  const after = lines.slice(metaIdx + 1);
+  const dedent = after.findIndex((l) => /^[^ \t]/.test(l)); // a column-0 line closes the metadata block
+  const block = dedent === -1 ? after : after.slice(0, dedent);
+  // Direct children share the first child's indent; a nested decoy is MORE indented, so a
+  // `<baseIndent>version:` prefix match excludes it. baseIndent is non-empty, so a top-level
+  // `version:` (column 0, and before `metadata:` anyway) is excluded too.
+  const baseIndent = block.length ? (block[0].match(/^[ \t]*/)?.[0] ?? '') : '';
+  const verLine = block.find((l) => l.startsWith(`${baseIndent}version:`));
+  return verLine?.match(/version:[ \t]*['"]?(\d+\.\d+\.\d+)['"]?/)?.[1] ?? null;
+};
+
+// The installed version is read from the target's SKILL.md frontmatter (`metadata.version`) — the
+// manifest's canonical `detect.installed.file`, present even on legacy installs that predate
+// capability.json. Returns the semver string, or null when ABSENT / has no parseable stamp (legacy
+// → no gate). A SKILL.md that EXISTS but cannot be read is NOT swallowed as "legacy": we fail closed
+// (throw) so the never-downgrade gate can never be silently bypassed (AGENTS.md: no silent failures).
+const readInstalledVersion = async (target) => {
+  const skill = resolve(target, 'SKILL.md');
+  if (!existsSync(skill)) return null; // absent → new/legacy install, nothing to compare
+  const text = await readFile(skill, 'utf8').catch((err) => {
+    throw new Error(
+      `[agent-workflow-kit] cannot read the installed SKILL.md (${tildify(skill)}): ${err.message}. ` +
+        `Refusing to install over an unreadable kit — fix permissions/contents or remove it, then re-run.`,
+    );
+  });
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return fm ? metadataVersion(fm[1]) : null;
+};
+
 // lstat without following symlinks; null when absent. existsSync FOLLOWS symlinks (so a
 // *dangling* symlink reads as absent) — lstat is what lets the guard catch a dangling dest symlink.
 const lstatNoFollow = (path) => {
@@ -64,42 +124,10 @@ const lstatNoFollow = (path) => {
   }
 };
 
-// Symlink-traversal guard: refuse to write *through* any symlink at or above `dest` within
-// `root` (root / intermediate dir / leaf, including a dangling one), or to a dest outside `root`.
-const assertContainedRealPath = (root, dest) => {
-  const rel = relative(root, dest);
-  if (rel.startsWith('..') || isAbsolute(rel)) {
-    throw new Error(`[agent-workflow-kit] refusing to write outside the target dir: ${dest}`);
-  }
-  if (lstatNoFollow(root)?.isSymbolicLink()) {
-    throw new Error(`[agent-workflow-kit] refusing to install into a symlinked target dir: ${root}`);
-  }
-  const walk = (acc, part) => {
-    const cur = join(acc, part);
-    if (lstatNoFollow(cur)?.isSymbolicLink()) {
-      throw new Error(`[agent-workflow-kit] refusing to write through a symlink at ${cur} (would escape ${root}).`);
-    }
-    return cur;
-  };
-  rel.split(sep).filter(Boolean).reduce(walk, root);
-};
-
-const copyRecursive = async (src, dest, root) => {
-  assertContainedRealPath(root, dest); // never write through a dest symlink (root/intermediate/leaf)
-  const stat = await lstat(src);
-  if (stat.isSymbolicLink()) {
-    if (existsSync(dest)) return; // additive: never delete/replace an existing entry
-    const linkTarget = await readlink(src);
-    await symlink(linkTarget, dest);
-  } else if (stat.isDirectory()) {
-    await mkdir(dest, { recursive: true });
-    const entries = await readdir(src);
-    await Promise.all(entries.map((entry) => copyRecursive(join(src, entry), join(dest, entry), root)));
-  } else {
-    await mkdir(dirname(dest), { recursive: true });
-    await copyFile(src, dest);
-  }
-};
+// The symlink-traversal guard + the recursive refresh copy now live in tools/fs-safe.mjs (shared,
+// dependency-injectable, unit-tested in isolation). install.mjs consumes copyTreeRefresh, which guards
+// every dest via assertContainedRealPath internally. The local lstatNoFollow above stays for the
+// pre-flight check on the target root itself (a nicer error than letting the copy throw).
 
 const parseArgs = (argv) => {
   const dirFlag = argv.indexOf('--dir');
@@ -108,6 +136,7 @@ const parseArgs = (argv) => {
     version: argv.includes('--version') || argv.includes('-v'),
     noLaunchers: argv.includes('--no-launchers'),
     force: argv.includes('--force'),
+    allowDowngrade: argv.includes('--allow-downgrade'),
     dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
   };
 };
@@ -122,15 +151,20 @@ const printHelp = (version) => {
   console.log(`agent-workflow-kit ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-kit init [--dir <path>] [--no-launchers] [--force]
-  npx @sabaiway/agent-workflow-kit --version
-  npx @sabaiway/agent-workflow-kit --help
+  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--force] [--allow-downgrade]
+  npx @sabaiway/agent-workflow-kit@latest --version
+  npx @sabaiway/agent-workflow-kit@latest --help
+
+Use the @latest form: a bare \`npx … init\` (no @latest) can reuse an OLDER cached
+  build of this installer, so a returning user must bypass the npx cache to upgrade.
 
 Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
   (override with --dir <path> or AGENT_WORKFLOW_KIT_DIR), then wires any
   Codex / Devin Desktop you have. --no-launchers skips that wiring; --force replaces a
   pre-existing non-kit launcher file (backed up first). init is additive — it never
-  deletes your settings.
+  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).
 
 After install, invoke the skill in your agent, inside a project:
   first time in the project  ->  /agent-workflow-kit
@@ -150,7 +184,15 @@ const main = async () => {
 
   // Critical payload must be present, or the install would silently ship a kit that can't run
   // its own detector (tools/) or family contract (capability.json). Fail loudly, don't filter away.
-  const REQUIRED = ['SKILL.md', 'capability.json', 'references', 'tools', 'migrations'];
+  const REQUIRED = [
+    'SKILL.md',
+    'capability.json',
+    'references',
+    'tools',
+    'migrations',
+    'bridges/codex-cli-bridge',
+    'bridges/antigravity-cli-bridge',
+  ];
   const missing = REQUIRED.filter((entry) => !existsSync(resolve(PKG_ROOT, entry)));
   if (missing.length > 0) {
     console.error(`[agent-workflow-kit] package payload incomplete — missing: ${missing.join(', ')} (corrupt install?)`);
@@ -163,14 +205,46 @@ const main = async () => {
     console.error(`[agent-workflow-kit] target dir is a symlink — refusing to write through it: ${tildify(target)}`);
     process.exit(1);
   }
+
+  // Stale-cache defenses (no network — version already on disk vs this runner). Read BEFORE any
+  // write so a refusal touches nothing. cmp is null on a legacy/unparseable install → no gate.
+  const installedVersion = wasPresent ? await readInstalledVersion(target) : null;
+  const cmp = installedVersion ? compareSemver(installedVersion, version) : null;
+
+  // Never-downgrade gate: a bare `npx … init` can run an OLDER cached build of this installer, which
+  // would overwrite a NEWER installed skill with old code. Refuse loudly (nonzero) unless the
+  // dedicated --allow-downgrade override is passed — surfacing the cache trap instead of silently
+  // regressing the install (AGENTS.md: no silent failures). The override is its OWN flag, NOT --force:
+  // --force means "replace a foreign launcher file" and is forwarded to the launcher; conflating them
+  // would let someone clearing the version gate also clobber launchers by accident.
+  if (cmp === 1 && !args.allowDowngrade) {
+    console.error(
+      `[agent-workflow-kit] refusing to downgrade: the installed kit is v${installedVersion}, but this ` +
+        `runner is the OLDER v${version}.\n` +
+        `  This is the classic npx cache serving a stale build. To get the newest kit, bypass the cache:\n` +
+        `    npx @sabaiway/agent-workflow-kit@latest init\n` +
+        `  (or pass --allow-downgrade to overwrite the newer install with v${version} anyway).`,
+    );
+    process.exit(1);
+  }
+
   await mkdir(target, { recursive: true });
-  await Promise.all(
-    PAYLOAD.filter((entry) => existsSync(resolve(PKG_ROOT, entry))).map((entry) =>
-      copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target),
-    ),
-  );
+  for (const entry of PAYLOAD.filter((e) => existsSync(resolve(PKG_ROOT, e)))) {
+    copyTreeRefresh(resolve(PKG_ROOT, entry), resolve(target, entry), target);
+  }
   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).
+  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` +
+        `    npx @sabaiway/agent-workflow-kit@latest init`,
+    );
+  }
+
   // Wire non-Claude agents — best-effort; the launcher only touches tools you have.
   const launcher = resolve(target, 'launchers/install-launchers.sh');
   if (args.noLaunchers) {
@@ -198,7 +272,12 @@ This command only installs/updates the kit itself (in ${tildify(target)}).
 To update the kit later, re-run:  npx @sabaiway/agent-workflow-kit@latest init`);
 };
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+// Run main() only when executed directly (npx / node bin/install.mjs), never on import — so tests
+// can import this module to assert it has no side effects. Same idiom as tools/detect-backends.mjs.
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/bin/install.test.mjs

@@ -1,16 +1,29 @@
 import { describe, it, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { mkdtemp, rm, mkdir, symlink, readdir } from 'node:fs/promises';
+import { mkdtemp, rm, mkdir, symlink, readdir, readFile, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const INSTALLER = join(dirname(fileURLToPath(import.meta.url)), 'install.mjs');
-// --no-launchers so the test never wires Codex/Devin on the host.
-const runInstaller = (target) =>
-  spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers'], { encoding: 'utf8' });
+const KIT_ROOT = dirname(dirname(INSTALLER));
+// --no-launchers so the test never wires Codex/Devin on the host. `extra` appends flags (e.g. --force).
+const runInstaller = (target, extra = []) =>
+  spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers', ...extra], { encoding: 'utf8' });
+
+// Rewrite / read the installed skill's frontmatter version — used to simulate "a newer kit is already
+// installed" (the stale-cache downgrade scenario). The installer reads exactly this field.
+const setInstalledVersion = async (target, v) => {
+  const p = join(target, 'SKILL.md');
+  const text = await readFile(p, 'utf8');
+  await writeFile(p, text.replace(/version:\s*['"]?\d+\.\d+\.\d+['"]?/, `version: '${v}'`));
+};
+const getInstalledVersion = async (target) =>
+  (await readFile(join(target, 'SKILL.md'), 'utf8')).match(/version:\s*['"]?(\d+\.\d+\.\d+)['"]?/)?.[1] ?? null;
+const pkgVersion = async () =>
+  JSON.parse(await readFile(join(KIT_ROOT, 'package.json'), 'utf8')).version;
 
 describe('kit installer — payload + symlink-traversal hardening', () => {
   let dir;
@@ -64,3 +77,123 @@ describe('kit installer — payload + symlink-traversal hardening', () => {
     assert.deepEqual(await readdir(real), []);
   });
 });
+
+describe('kit installer — module hygiene', () => {
+  it('importing install.mjs runs nothing (main() is guarded by isDirectRun)', () => {
+    // `node -e` has no argv[1], so isDirectRun is false → importing must not run main()
+    // (no FS writes, no exit). A child process keeps the assertion off the test runner's own state.
+    const url = JSON.stringify(pathToFileURL(INSTALLER).href);
+    const res = spawnSync(
+      process.execPath,
+      ['--input-type=module', '-e', `import(${url}).then(() => console.log('IMPORT_OK'));`],
+      { encoding: 'utf8' },
+    );
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /IMPORT_OK/);
+    assert.doesNotMatch(res.stdout, /installed v|updated the kit/);
+  });
+});
+
+describe('kit installer — stale-cache defenses (no network)', () => {
+  let dir;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'aw-kit-stale-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('a no-op re-run (same version) flags the likely npx cache and points at @latest', async () => {
+    const target = join(dir, 'agent-workflow-kit');
+    assert.equal(runInstaller(target).status, 0); // first install
+    const again = runInstaller(target); // second run: installed == running
+    assert.equal(again.status, 0, again.stderr);
+    assert.match(again.stdout, /no version change/i);
+    assert.match(again.stdout, /cache/i);
+    assert.match(again.stdout, /@latest/);
+  });
+
+  it('refuses to downgrade when the installed kit is NEWER, and writes nothing', async () => {
+    const target = join(dir, 'agent-workflow-kit');
+    assert.equal(runInstaller(target).status, 0);
+    await setInstalledVersion(target, '99.0.0'); // pretend a newer kit is already installed
+    const res = runInstaller(target); // running version < installed → downgrade
+    assert.notEqual(res.status, 0);
+    assert.match(res.stderr, /downgrade/i);
+    assert.match(res.stderr, /@latest/);
+    assert.equal(await getInstalledVersion(target), '99.0.0', 'newer install must be left untouched');
+  });
+
+  it('--allow-downgrade overrides the refusal and overwrites with the runner version', async () => {
+    const target = join(dir, 'agent-workflow-kit');
+    assert.equal(runInstaller(target).status, 0);
+    await setInstalledVersion(target, '99.0.0');
+    const res = runInstaller(target, ['--allow-downgrade']);
+    assert.equal(res.status, 0, res.stderr);
+    assert.equal(await getInstalledVersion(target), await pkgVersion());
+  });
+
+  it('--force alone does NOT override the downgrade gate (the override is its own flag)', async () => {
+    const target = join(dir, 'agent-workflow-kit');
+    assert.equal(runInstaller(target).status, 0);
+    await setInstalledVersion(target, '99.0.0');
+    const res = runInstaller(target, ['--force']); // launcher-clobber flag, not the gate override
+    assert.notEqual(res.status, 0, 'launcher --force must not silently clear the version gate');
+    assert.equal(await getInstalledVersion(target), '99.0.0', 'newer install must be left untouched');
+  });
+
+  it('reads the version under `metadata:`, never a top-level / nested decoy `version:`', async () => {
+    // A crafted SKILL.md whose REAL metadata.version (0.0.1) is OLDER than the runner, but with decoy
+    // `version:` lines that are NEWER. A naive "first version: in frontmatter" read would see 99.0.0
+    // and wrongly refuse; the correct read sees 0.0.1 → a normal upgrade (exit 0).
+    const target = join(dir, 'agent-workflow-kit');
+    await mkdir(target, { recursive: true });
+    const decoy = [
+      '---',
+      "version: '99.0.0'", // top-level decoy (column 0)
+      'name: agent-workflow-kit',
+      'metadata:',
+      '  nested:',
+      "    version: '98.0.0'", // deeper-nested decoy
+      "  version: '0.0.1'", // the authoritative direct child
+      '---',
+      '# decoy',
+      '',
+    ].join('\n');
+    await writeFile(join(target, 'SKILL.md'), decoy);
+    const res = runInstaller(target);
+    assert.equal(res.status, 0, `expected a normal upgrade (read 0.0.1), got: ${res.stderr}`);
+    assert.match(res.stdout, /updated the kit to/);
+  });
+
+  it('fails closed (does not silently treat as legacy) when an existing SKILL.md cannot be read', async () => {
+    // SKILL.md present but unreadable (a directory → EISDIR on read). The gate must NOT be bypassed:
+    // we refuse rather than overwrite a kit whose version we could not determine (no silent failure).
+    const target = join(dir, 'agent-workflow-kit');
+    await mkdir(join(target, 'SKILL.md'), { recursive: true });
+    const res = runInstaller(target);
+    assert.notEqual(res.status, 0);
+    assert.match(res.stderr, /cannot read the installed SKILL\.md/i);
+  });
+
+  it('a legacy install with no version stamp still upgrades (no false downgrade, no crash)', async () => {
+    const target = join(dir, 'agent-workflow-kit');
+    await mkdir(target, { recursive: true });
+    await writeFile(join(target, 'SKILL.md'), '---\nname: agent-workflow-kit\n---\n# legacy stub\n');
+    const res = runInstaller(target);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /updated the kit to/);
+  });
+});
+
+describe('kit installer — published tarball bundles the bridges', () => {
+  it('npm pack ships bridges/<name>/ (the execution-backend skill mirrors)', () => {
+    // The real `files` whitelist decides what publishes — assert against `npm pack`, not the source
+    // tree, so a dropped `bridges/` entry in package.json fails here (not silently at install time).
+    const res = spawnSync('npm', ['pack', '--dry-run', '--json'], { cwd: KIT_ROOT, encoding: 'utf8' });
+    assert.equal(res.status, 0, res.stderr || res.error?.message);
+    const paths = JSON.parse(res.stdout)[0].files.map((f) => f.path);
+    assert.ok(paths.includes('bridges/codex-cli-bridge/SKILL.md'), 'codex bridge SKILL.md not packed');
+    assert.ok(paths.includes('bridges/antigravity-cli-bridge/bin/agy.sh'), 'antigravity agy.sh not packed');
+  });
+});