@sabaiway/agent-workflow-kit 1.6.0 → 1.8.0

package/bridges/codex-cli-bridge/setup/README.md

@@ -0,0 +1,78 @@
+# Setting up OpenAI Codex CLI (`codex`) on a clean machine
+
+This setup is **secret-free**. `codex` itself is **not** bundled — it requires a binary install and a
+one-time interactive sign-in with your own ChatGPT subscription. Do this once per machine, then the
+skill works in any git repository that has a root `AGENTS.md`.
+
+## 1. Install the binary
+
+Install the official OpenAI Codex CLI using the current official channel for your platform, then
+confirm it is on `PATH`:
+
+```bash
+npm install -g @openai/codex     # or: brew install codex  (use the current official channel)
+codex --version                  # this skill was verified with codex-cli 0.140.0 or newer
+```
+
+The binary is **`codex`**. If `codex --version` works but the wrappers can't find it, fix your
+`PATH`. If the installed binary's help disagrees with this skill's references, the live binary wins.
+
+## 2. Sign in once (subscription only)
+
+Run `codex login` once and complete the **ChatGPT** sign-in:
+
+```bash
+codex login
+codex login status               # expect: Logged in using ChatGPT
+```
+
+This caches credentials under `CODEX_HOME` (`~/.codex`, e.g. `~/.codex/auth.json`). That directory is
+**personal** — never copy, commit, package, print, or share it. This skill needs **no API keys** and
+must not be configured with api-key billing; both wrappers unset every `*_API_KEY` (and
+`OPENAI_BASE_URL`) and pass `--ignore-user-config`, so billing can never silently fall back to
+pay-as-you-go and a personal `~/.codex/config.toml` can never change behaviour.
+
+## 3. Put the wrappers on `PATH`
+
+The skill ships two wrappers: `bin/codex-exec.sh` and `bin/codex-review.sh`. Expose them on `PATH`
+under the stable names `codex-exec` / `codex-review` via idempotent managed symlinks (refuse to
+clobber a non-symlink):
+
+```bash
+mkdir -p "$HOME/.local/bin"
+skill_dir="$HOME/.claude/skills/codex-cli-bridge"   # adjust if installed elsewhere
+for w in codex-exec codex-review; do
+  src="$skill_dir/bin/$w.sh"
+  dst="$HOME/.local/bin/$w"
+  if [ -e "$dst" ] && [ ! -L "$dst" ]; then
+    echo "STOP: $dst exists and is not a symlink"; exit 1
+  fi
+  chmod +x "$src"
+  ln -sfn "$src" "$dst"
+done
+export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc / ~/.zshrc to persist
+command -v codex-exec && command -v codex-review
+```
+
+## 4. Smoke test
+
+```bash
+codex --version                                          # version prints
+env -u OPENAI_API_KEY -u CODEX_API_KEY -u OPENAI_BASE_URL codex login status
+```
+
+Expected: the version prints, and login status includes exactly `Logged in using ChatGPT` (the
+`env -u …` mirrors the wrappers, so stray keys can't mask the real auth mode). If the status does not
+include that text, redo step 2. If a wrapper reports `'codex' not found`, fix your `PATH` (step 1);
+if it reports a missing git work tree or root `AGENTS.md`, run it from a project root that has them.
+
+## Notes
+
+- The wrappers are **subscription-only** by design and will not use api-key billing.
+- `codex-exec` runs a **workspace-write** sandbox with **network OFF**; `codex-review` runs
+  **read-only**. See [`../references/sandbox-and-flags.md`](../references/sandbox-and-flags.md).
+- `codex exec` requires a git repository, and the wrappers also require a root `AGENTS.md`. The
+  orchestrator commits, not codex. Re-run `codex login` only when the cached login expires or the
+  account changes.
+- On Linux, install `bubblewrap` (`sudo apt install bubblewrap` or equivalent) to silence the
+  "could not find bubblewrap" warning; codex otherwise uses a bundled copy.

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.6.0",
+  "version": "1.8.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",
@@ -49,7 +49,8 @@
     "references/",
     "launchers/",
     "migrations/",
-    "tools/"
+    "tools/",
+    "bridges/"
   ],
   "engines": {
     "node": ">=18"

package/tools/detect-backends.mjs

@@ -58,6 +58,9 @@ export const KNOWN_BACKENDS = [
     credential: { env: 'CODEX_HOME', default: '~/.codex', file: 'auth.json' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/codex-cli-bridge/setup/README.md',
     setupPathLocal: 'setup/README.md',
+    // The short canonical guided commands. Binary-install is platform-variant and longer, so it is
+    // REFERENCED via setupRef (§1 of that README), never duplicated here (would drift with the README).
+    guide: { setupRef: 'codex-cli-bridge/setup/README.md', loginCmd: 'codex login', verifyCmd: 'codex login status' },
   },
   {
     name: 'antigravity-cli-bridge',
@@ -66,6 +69,7 @@ export const KNOWN_BACKENDS = [
     credential: { env: null, default: '~/.gemini/antigravity-cli', file: 'antigravity-oauth-token' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/antigravity-cli-bridge/setup/README.md',
     setupPathLocal: 'setup/README.md',
+    guide: { setupRef: 'antigravity-cli-bridge/setup/README.md', loginCmd: 'agy', verifyCmd: 'echo "say OK" | agy-run -' },
   },
 ];
 
@@ -257,6 +261,38 @@ export const detectBackend = (entry, deps = {}) => {
 
 export const detectBackends = (deps = {}) => KNOWN_BACKENDS.map((entry) => detectBackend(entry, deps));
 
+// ── guidance (axis-aware, for the `setup` flow) ───────────────────────────────
+
+const registryEntry = (name) => KNOWN_BACKENDS.find((b) => b.name === name);
+
+// The skill axis can't be auto-fixed in every state: an absent dir IS placeable from the bundled
+// kit; any other non-ok state (stub/foreign/invalid/unsupported, or an `unknown` marker fs error)
+// is a STOP — never overwrite a dir we don't provably own.
+const skillHint = (status, guide) =>
+  status.manifestState === NOT_INSTALLED
+    ? `place the bundled bridge skill — run \`/agent-workflow-kit setup ${status.name}\``
+    : `bridge skill dir is "${status.manifestState}" — STOP and inspect ${status.skillDir ?? 'the skill dir'} (see ${guide?.setupRef ?? status.setupHint?.url})`;
+
+// guideFor inspects the manifest/cli/credentials axes INDEPENDENTLY (never the collapsed readiness)
+// and returns an ORDERED list of the manual steps still owed — possibly several at once (e.g. a
+// fresh machine needs both the CLI and a login). `[]` ⇒ nothing manual left (the linker handles the
+// wrappers). Each step is `{ need: 'skill'|'cli'|'credentials', hint }`. Pure; no fs, no side effects.
+export const guideFor = (status) => {
+  const guide = registryEntry(status.name)?.guide;
+  const out = [];
+  if (status.manifestState !== OK) out.push({ need: 'skill', hint: skillHint(status, guide) });
+  if (status.cli.state !== PRESENT) {
+    out.push({ need: 'cli', hint: `install the "${status.cli.bin}" CLI — see ${guide?.setupRef ?? status.setupHint?.url} §1` });
+  }
+  if (status.credentials.state !== PRESENT) {
+    out.push({
+      need: 'credentials',
+      hint: `sign in once (subscription): ${guide?.loginCmd ?? 'see the setup README'}  (verify: ${guide?.verifyCmd ?? 'see the setup README'})`,
+    });
+  }
+  return out;
+};
+
 // ── report ───────────────────────────────────────────────────────────────────
 
 const MARK = { [PRESENT]: '✓', [MISSING]: '✗', [UNKNOWN]: '?' };

package/tools/detect-backends.test.mjs

@@ -12,6 +12,7 @@ import {
   detectBackend,
   detectBackends,
   formatReport,
+  guideFor,
   KNOWN_BACKENDS,
 } from './detect-backends.mjs';
 
@@ -340,3 +341,104 @@ describe('detectBackends — live shape on this machine', () => {
     }
   });
 });
+
+// ── guideFor (axis-aware manual steps) ────────────────────────────────────────
+
+// A status with all axes satisfied; override per-case to drive each axis independently.
+const okStatus = (over = {}) => ({
+  name: 'codex-cli-bridge',
+  manifestState: 'ok',
+  manifestReason: 'ok',
+  skillDir: '/skills/codex-cli-bridge',
+  cli: { bin: 'codex', state: 'present', path: '/usr/bin/codex' },
+  credentials: { state: 'present', path: '/home/u/.codex/auth.json' },
+  wrappers: [{ name: 'codex-exec', state: 'present' }, { name: 'codex-review', state: 'present' }],
+  readiness: 'ready',
+  setupHint: { local: 'setup/README.md', url: 'https://example.test/codex' },
+  ...over,
+});
+
+describe('guideFor — axis-aware manual steps', () => {
+  it('returns [] when the backend is ready', () => {
+    assert.deepEqual(guideFor(okStatus()), []);
+  });
+
+  it('returns [] for a degraded backend (wrappers are the linker\'s job, not a manual step)', () => {
+    const s = okStatus({ readiness: 'degraded', wrappers: [{ name: 'codex-exec', state: 'missing' }] });
+    assert.deepEqual(guideFor(s), []);
+  });
+
+  it('returns BOTH cli and credentials steps when both are missing (multiple simultaneous)', () => {
+    const s = okStatus({
+      cli: { bin: 'codex', state: 'missing', path: null },
+      credentials: { state: 'missing', path: '/c/auth.json' },
+    });
+    const needs = guideFor(s).map((g) => g.need);
+    assert.deepEqual(needs, ['cli', 'credentials']);
+  });
+
+  it('credentials step carries the canonical loginCmd + verifyCmd from the registry', () => {
+    const s = okStatus({ credentials: { state: 'missing', path: '/c/auth.json' } });
+    const step = guideFor(s).find((g) => g.need === 'credentials');
+    assert.match(step.hint, /codex login/);
+    assert.match(step.hint, /codex login status/);
+  });
+
+  it('cli step references the setup README (no duplicated install channels)', () => {
+    const s = okStatus({ cli: { bin: 'codex', state: 'missing', path: null } });
+    const step = guideFor(s).find((g) => g.need === 'cli');
+    assert.match(step.hint, /codex-cli-bridge\/setup\/README\.md/);
+  });
+
+  it('manifestState not-installed → a placeable bundled-skill hint (+ any cli/creds owed)', () => {
+    const s = okStatus({ manifestState: 'not-installed', skillDir: null });
+    const skill = guideFor(s).find((g) => g.need === 'skill');
+    assert.ok(skill, 'expected a skill step');
+    assert.match(skill.hint, /bundled bridge skill/);
+    assert.match(skill.hint, /setup codex-cli-bridge/);
+  });
+
+  it('manifestState foreign/stub → a STOP hint (never auto-overwritten)', () => {
+    for (const state of ['foreign', 'stub', 'invalid-manifest', 'unsupported-schema', 'unknown']) {
+      const skill = guideFor(okStatus({ manifestState: state })).find((g) => g.need === 'skill');
+      assert.ok(skill, `expected a skill step for ${state}`);
+      assert.match(skill.hint, /STOP/);
+      assert.match(skill.hint, new RegExp(state.replace(/[-]/g, '\\$&')));
+    }
+  });
+
+  it('every step is {need, hint} with a non-empty hint', () => {
+    const s = okStatus({
+      manifestState: 'not-installed',
+      skillDir: null,
+      cli: { bin: 'codex', state: 'missing', path: null },
+      credentials: { state: 'missing', path: '/c/auth.json' },
+    });
+    const steps = guideFor(s);
+    assert.equal(steps.length, 3);
+    for (const step of steps) {
+      assert.ok(typeof step.need === 'string' && step.need.length > 0);
+      assert.ok(typeof step.hint === 'string' && step.hint.length > 0);
+    }
+  });
+});
+
+describe('KNOWN_BACKENDS — each entry exposes a guide', () => {
+  it('guide carries setupRef + loginCmd + verifyCmd (non-empty strings)', () => {
+    for (const entry of KNOWN_BACKENDS) {
+      assert.ok(entry.guide, `${entry.name} missing guide`);
+      for (const key of ['setupRef', 'loginCmd', 'verifyCmd']) {
+        assert.ok(
+          typeof entry.guide[key] === 'string' && entry.guide[key].length > 0,
+          `${entry.name}.guide.${key} must be a non-empty string`,
+        );
+      }
+    }
+  });
+
+  it('guide.setupRef points at a real file in the repo', () => {
+    for (const entry of KNOWN_BACKENDS) {
+      assert.ok(existsSync(join(REPO, entry.guide.setupRef)), `${entry.guide.setupRef} (${entry.name})`);
+    }
+  });
+});

package/tools/fs-safe.mjs

@@ -0,0 +1,129 @@
+// fs-safe.mjs — pure, dependency-injectable filesystem-safety primitives shared by the kit installer
+// (bin/install.mjs) and the backend linker (tools/setup-backends.mjs). Importing this module has NO
+// side effects: it runs nothing. Every fs primitive is injectable via `deps.*` so the guards are
+// unit-testable without touching the real filesystem; the defaults are Node's SYNC fs (matching the
+// tools/ detector style). Dependency-free, Node >= 18.
+//
+// Three primitives:
+//   assertContainedRealPath — refuse to write through/into a symlink, or to a dest outside a root.
+//   copyTreeRefresh         — recursive copy that OVERWRITES regular files (refresh), SKIPS a symlink
+//                             whose dest already exists (additive), and guards every dest component.
+//   linkManaged             — create/keep ONLY a symlink we own; STOP (typed ManagedLinkConflict) on
+//                             a foreign symlink or a non-symlink dest; refuse a symlinked source.
+
+import {
+  lstatSync, existsSync, mkdirSync, readdirSync, copyFileSync, readlinkSync, symlinkSync,
+} from 'node:fs';
+import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
+
+// A managed-link conflict is a distinct, expected outcome (a foreign/non-symlink dest we refuse to
+// clobber) — callers branch on `.code`. Modelled as a tagged Error (no classes — §agent_rules 2.3),
+// the same `Object.assign(new Error(), { code })` idiom the codebase already uses for typed errors.
+export const MANAGED_LINK_CONFLICT = 'MANAGED_LINK_CONFLICT';
+const managedLinkConflict = (message, fields = {}) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), {
+    name: 'ManagedLinkConflict',
+    code: MANAGED_LINK_CONFLICT,
+    ...fields,
+  });
+
+// lstat without following symlinks; null when absent. A non-ENOENT fs error (EACCES/EIO) must NOT
+// fail open (be read as "not a symlink") — it propagates so the guard can never be bypassed.
+const lstatNoFollow = (path, lstat) => {
+  try {
+    return lstat(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+// 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`.
+export const assertContainedRealPath = (root, dest, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const ln = (p) => lstatNoFollow(p, lstat);
+  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 (ln(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 (ln(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);
+};
+
+// Recursive refresh copy. Guards every dest via assertContainedRealPath first, then:
+//   symlink src   → additive: skip if dest exists, else mirror the link target.
+//   directory src → mkdir -p dest, recurse.
+//   regular file  → mkdir -p parent, copyFile (OVERWRITE = refresh to the bundled version).
+export const copyTreeRefresh = (src, dest, root, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const exists = deps.exists ?? existsSync;
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync(p, { recursive: true }));
+  const readdir = deps.readdir ?? readdirSync;
+  const copyFile = deps.copyFile ?? copyFileSync;
+  const readlink = deps.readlink ?? readlinkSync;
+  const symlink = deps.symlink ?? symlinkSync;
+
+  assertContainedRealPath(root, dest, deps);
+  const stat = lstat(src);
+  if (stat.isSymbolicLink()) {
+    if (exists(dest)) return;
+    symlink(readlink(src), dest);
+  } else if (stat.isDirectory()) {
+    mkdir(dest);
+    for (const entry of readdir(src)) {
+      copyTreeRefresh(join(src, entry), join(dest, entry), root, deps);
+    }
+  } else {
+    mkdir(dirname(dest));
+    copyFile(src, dest);
+  }
+};
+
+// Create/keep ONLY a symlink we own. `src` must be a real regular file (never a symlink); `dest`
+// must stay within `root`. Outcomes: 'linked' (created), 'noop' (already points at our src), or a
+// thrown ManagedLinkConflict (a non-symlink, or a symlink pointing elsewhere — never clobbered).
+export const linkManaged = (src, dest, root, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync(p, { recursive: true }));
+  const readlink = deps.readlink ?? readlinkSync;
+  const symlink = deps.symlink ?? symlinkSync;
+
+  const srcStat = lstat(src);
+  if (srcStat.isSymbolicLink()) {
+    throw new Error(`[agent-workflow-kit] refusing to link a symlinked source (would escape our ownership): ${src}`);
+  }
+  if (!srcStat.isFile()) {
+    throw new Error(`[agent-workflow-kit] link source is not a regular file: ${src}`);
+  }
+
+  // Guard the PARENT chain (root + intermediate dirs), not the leaf: managing the leaf symlink is
+  // exactly this function's job, so it inspects the leaf itself rather than letting the traversal
+  // guard reject every symlinked dest. `dirname(dest)` within `root` ⇒ `dest` within `root` too.
+  assertContainedRealPath(root, dirname(dest), deps);
+  const existing = lstatNoFollow(dest, lstat);
+  if (existing === null) {
+    mkdir(dirname(dest));
+    symlink(src, dest);
+    return 'linked';
+  }
+  if (!existing.isSymbolicLink()) {
+    throw managedLinkConflict(`refusing to replace a non-symlink at ${dest}`, { dest, found: 'file' });
+  }
+  const target = readlink(dest);
+  const resolvedTarget = isAbsolute(target) ? target : resolve(dirname(dest), target);
+  if (resolvedTarget === resolve(src)) return 'noop';
+  throw managedLinkConflict(
+    `refusing to replace a foreign symlink at ${dest} (points at ${target}, not our ${src})`,
+    { dest, expected: src, found: target },
+  );
+};

package/tools/fs-safe.test.mjs

@@ -0,0 +1,200 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync, readlinkSync, readFileSync, existsSync, lstatSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  assertContainedRealPath,
+  copyTreeRefresh,
+  linkManaged,
+  MANAGED_LINK_CONFLICT,
+} from './fs-safe.mjs';
+
+// All three primitives are SYNC and operate on real tmp dirs here (the symlink behaviours are
+// fiddly enough that real fs is the honest test). The out-of-root case needs no fs at all.
+let dir;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'awf-fs-safe-'));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ── assertContainedRealPath ───────────────────────────────────────────────────
+
+describe('assertContainedRealPath', () => {
+  it('rejects a dest outside the root (no fs needed — the relative check fires first)', () => {
+    assert.throws(() => assertContainedRealPath('/root', '/root/../etc/passwd'), /outside/);
+    assert.throws(() => assertContainedRealPath('/root', '/etc/passwd'), /outside/);
+  });
+
+  it('rejects writing INTO a symlinked root', () => {
+    const real = join(dir, 'real');
+    const root = join(dir, 'root');
+    mkdirSync(real);
+    symlinkSync(real, root);
+    assert.throws(() => assertContainedRealPath(root, join(root, 'x')), /symlink/i);
+  });
+
+  it('rejects writing THROUGH a symlinked intermediate component', () => {
+    const root = join(dir, 'root');
+    const elsewhere = join(dir, 'elsewhere');
+    mkdirSync(root);
+    mkdirSync(elsewhere);
+    symlinkSync(elsewhere, join(root, 'sub'));
+    assert.throws(() => assertContainedRealPath(root, join(root, 'sub', 'file')), /symlink/i);
+  });
+
+  it('rejects a symlinked leaf dest', () => {
+    const root = join(dir, 'root');
+    mkdirSync(root);
+    symlinkSync(join(dir, 'target'), join(root, 'leaf'));
+    assert.throws(() => assertContainedRealPath(root, join(root, 'leaf')), /symlink/i);
+  });
+
+  it('accepts a clean dest within the root', () => {
+    const root = join(dir, 'root');
+    mkdirSync(root);
+    assert.doesNotThrow(() => assertContainedRealPath(root, join(root, 'a', 'b', 'c')));
+  });
+
+  it('lstat is injectable (closes the install.mjs injectability gap)', () => {
+    let seen = 0;
+    const lstat = (p) => { seen += 1; return { isSymbolicLink: () => false }; };
+    assert.doesNotThrow(() => assertContainedRealPath('/root', '/root/a/b', { lstat }));
+    assert.ok(seen > 0, 'the injected lstat was used');
+  });
+});
+
+// ── copyTreeRefresh ───────────────────────────────────────────────────────────
+
+describe('copyTreeRefresh', () => {
+  it('overwrites an existing regular file (refresh)', () => {
+    const root = join(dir, 'dest');
+    mkdirSync(root);
+    const src = join(dir, 'src.txt');
+    const dest = join(root, 'f.txt');
+    writeFileSync(src, 'new');
+    writeFileSync(dest, 'old');
+    copyTreeRefresh(src, dest, root);
+    assert.equal(readFileSync(dest, 'utf8'), 'new');
+  });
+
+  it('copies a nested directory tree', () => {
+    const src = join(dir, 'src');
+    const root = join(dir, 'dest');
+    mkdirSync(join(src, 'a'), { recursive: true });
+    writeFileSync(join(src, 'top.txt'), 'T');
+    writeFileSync(join(src, 'a', 'deep.txt'), 'D');
+    mkdirSync(root);
+    copyTreeRefresh(src, join(root, 'src'), root);
+    assert.equal(readFileSync(join(root, 'src', 'top.txt'), 'utf8'), 'T');
+    assert.equal(readFileSync(join(root, 'src', 'a', 'deep.txt'), 'utf8'), 'D');
+  });
+
+  it('skips a symlink whose dest already exists (additive — never replace)', () => {
+    const root = join(dir, 'dest');
+    mkdirSync(root);
+    const linkSrc = join(dir, 'link');
+    symlinkSync(join(dir, 'whatever'), linkSrc); // src IS a symlink
+    const dest = join(root, 'f');
+    writeFileSync(dest, 'keep');
+    copyTreeRefresh(linkSrc, dest, root);
+    assert.equal(readFileSync(dest, 'utf8'), 'keep'); // untouched
+    assert.equal(lstatSync(dest).isSymbolicLink(), false);
+  });
+
+  it('STOPs on a symlinked dest component (never writes through it)', () => {
+    const root = join(dir, 'root');
+    const elsewhere = join(dir, 'elsewhere');
+    mkdirSync(root);
+    mkdirSync(elsewhere);
+    symlinkSync(elsewhere, join(root, 'sub'));
+    const src = join(dir, 's.txt');
+    writeFileSync(src, 'x');
+    assert.throws(() => copyTreeRefresh(src, join(root, 'sub', 'f.txt'), root), /symlink/i);
+    assert.equal(existsSync(join(elsewhere, 'f.txt')), false); // no leak
+  });
+});
+
+// ── linkManaged ───────────────────────────────────────────────────────────────
+
+describe('linkManaged', () => {
+  const makeSrc = () => {
+    const src = join(dir, 'src.sh');
+    writeFileSync(src, '#!/bin/sh\n');
+    return src;
+  };
+
+  it('creates a symlink when the dest is absent', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    const result = linkManaged(src, dest, root);
+    assert.equal(result, 'linked');
+    assert.equal(lstatSync(dest).isSymbolicLink(), true);
+    assert.equal(readlinkSync(dest), src);
+  });
+
+  it('creates the parent bindir if absent (mkdir -p)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'base');
+    mkdirSync(root);
+    const dest = join(root, 'newbin', 'cmd');
+    linkManaged(src, dest, root);
+    assert.equal(readlinkSync(dest), src);
+  });
+
+  it('is idempotent — a second call is a no-op', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    linkManaged(src, dest, root);
+    const again = linkManaged(src, dest, root);
+    assert.equal(again, 'noop');
+    assert.equal(readlinkSync(dest), src);
+  });
+
+  it('STOPs on a non-symlink dest (typed ManagedLinkConflict)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    writeFileSync(dest, 'someone-elses-file');
+    assert.throws(() => linkManaged(src, dest, root), (err) => err.code === MANAGED_LINK_CONFLICT);
+    assert.equal(readFileSync(dest, 'utf8'), 'someone-elses-file'); // untouched
+  });
+
+  it('STOPs on a foreign symlink (points elsewhere)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    const foreign = join(dir, 'foreign.sh');
+    writeFileSync(foreign, '#!/bin/sh\n');
+    symlinkSync(foreign, dest);
+    assert.throws(() => linkManaged(src, dest, root), (err) => err.code === MANAGED_LINK_CONFLICT);
+    assert.equal(readlinkSync(dest), foreign); // untouched
+  });
+
+  it('refuses a symlinked source (never links through a symlink)', () => {
+    const realSrc = makeSrc();
+    const linkSrc = join(dir, 'link.sh');
+    symlinkSync(realSrc, linkSrc);
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    assert.throws(() => linkManaged(linkSrc, join(root, 'cmd'), root), /symlink/i);
+  });
+
+  it('refuses a non-regular-file source (e.g. a directory)', () => {
+    const srcDir = join(dir, 'src-dir');
+    mkdirSync(srcDir);
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    assert.throws(() => linkManaged(srcDir, join(root, 'cmd'), root), /regular file/i);
+  });
+});