@sabaiway/agent-workflow-kit 1.10.0 → 1.12.0

package/tools/family-registry.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// family-registry.mjs — the unified, kit-owned registry over EVERY agent-workflow family member.
+//
+// Until now "who the members are" was split across three disjoint kit-owned tables: KNOWN_BACKENDS
+// (the 2 bridges, detect-backends.mjs), KIT_OWN_PATHS/KNOWN_FOOTPRINT (the hidden-mode paths,
+// known-footprint.mjs), and the 5 per-member capability.json files. This module is the single
+// authoritative aggregation: it answers "what is installed, what version, what kind" (the SKILL
+// axis) and "what is deployed in this project" (the deploy axis). It is the substrate the read-only
+// `/agent-workflow-kit status` mode and the guarded `/agent-workflow-kit uninstall` both consume.
+//
+// Source of truth = the in-tool FAMILY_MEMBERS table (the AD-008 KNOWN_BACKENDS precedent): a member
+// that is NOT installed has no manifest on disk to read, so the enumeration + detect/install facts
+// must live here. A drift-guard test (family-registry.test.mjs) pins FAMILY_MEMBERS to the 5 in-repo
+// capability.json files, so the table cannot silently drift from the manifests it mirrors.
+//
+// Pure, dependency-injectable (fs/env/home/validator are deps), dependency-free, Node >= 18. No
+// side effects on import (the isDirectRun idiom) — tests import the helpers with nothing run.
+
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import os from 'node:os';
+import { resolveDir } from './detect-backends.mjs';
+import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
+import { START_MARKER, excludePath } from './hide-footprint.mjs';
+
+// ── manifestState values (the detect-backends precedence, generalized to any member kind) ──────────
+export const NOT_INSTALLED = 'not-installed';
+export const UNSUPPORTED_SCHEMA = 'unsupported-schema';
+export const INVALID_MANIFEST = 'invalid-manifest';
+export const STUB = 'stub';
+export const FOREIGN = 'foreign';
+export const OK = 'ok';
+// The marker could not be probed (a non-ENOENT fs error — EACCES/EIO). Surfaced explicitly instead of
+// being masked as not-installed (no silent failure); uninstall treats it as "do not touch" (skip).
+export const UNKNOWN = 'unknown';
+
+// ── 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);
+// `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
+// (AD-013): no capability.json, not in the kit tarball, not in the role vocabulary.
+export const FAMILY_MEMBERS = [
+  {
+    name: 'agent-workflow-kit',
+    kind: 'composition-root',
+    installed: { env: 'AGENT_WORKFLOW_KIT_DIR', default: '~/.claude/skills/agent-workflow-kit', file: 'SKILL.md' },
+    deployed: { file: 'docs/ai/.workflow-version' },
+    npm: '@sabaiway/agent-workflow-kit',
+    wrapperCmds: [],
+  },
+  {
+    name: 'agent-workflow-memory',
+    kind: 'memory-substrate',
+    installed: { env: 'AGENT_WORKFLOW_MEMORY_DIR', default: '~/.claude/skills/agent-workflow-memory', file: 'SKILL.md' },
+    deployed: { file: 'docs/ai/.memory-version' },
+    npm: '@sabaiway/agent-workflow-memory',
+    wrapperCmds: [],
+  },
+  {
+    name: 'agent-workflow-engine',
+    kind: 'methodology-engine',
+    installed: { env: 'AGENT_WORKFLOW_ENGINE_DIR', default: '~/.claude/skills/agent-workflow-engine', file: 'SKILL.md' },
+    deployed: null,
+    npm: '@sabaiway/agent-workflow-engine',
+    wrapperCmds: [],
+  },
+  {
+    name: 'codex-cli-bridge',
+    kind: 'execution-backend',
+    installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
+    deployed: null,
+    npm: null,
+    wrapperCmds: ['codex-exec', 'codex-review'],
+  },
+  {
+    name: 'antigravity-cli-bridge',
+    kind: 'execution-backend',
+    installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
+    deployed: null,
+    npm: null,
+    wrapperCmds: ['agy-run'],
+  },
+];
+
+// A GLOBAL skill (lives under ~/.claude/skills) may be shared by other projects on the host — the
+// uninstaller warns before removing one (there is no cross-project dependency tracking). All current
+// members are global skills; the field is explicit so the warning is data-driven, not hardcoded.
+export const isGlobalSkill = (member) => member.kind !== undefined; // every member is a global skill today
+
+// ── pure probes ──────────────────────────────────────────────────────────────────
+// Wrapped marker probe → 'present' (a regular file) | 'absent' (ENOENT / not a file) | 'unknown' (a
+// non-ENOENT fs error, e.g. EACCES). 'unknown' is NOT collapsed to 'absent': a permission error must
+// surface, never be masked as not-installed (no silent failure) — and uninstall then leaves it alone.
+const probeMarker = (path, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const stat = deps.stat ?? statSync;
+  try {
+    if (!exists(path)) return 'absent';
+    return stat(path).isFile() ? 'present' : 'absent';
+  } catch (err) {
+    return err && err.code === 'ENOENT' ? 'absent' : 'unknown';
+  }
+};
+
+// Pure manifestState classifier — the detect-backends precedence, generalized to a member's own
+// expected name + kind: not-installed → unsupported-schema → invalid-manifest → stub → foreign → ok.
+const classifyState = (markerPresent, report, member) => {
+  if (!markerPresent) return NOT_INSTALLED;
+  if (report.result === UNSUPPORTED) return UNSUPPORTED_SCHEMA;
+  if (report.result === INVALID) return INVALID_MANIFEST;
+  if (report.available === false) return STUB;
+  if (report.kind !== member.kind || report.name !== member.name) return FOREIGN;
+  return OK;
+};
+
+// ── the SKILL axis ─────────────────────────────────────────────────────────────
+// classifyMember → { name, kind, installed, skillDir, manifestState, version }. Reuses resolveDir
+// (detect-backends), validateManifest + readAuthoritativeVersion (the manifest validator) — one
+// authoritative version reader, no second drifting source. `version` is set only for an `ok` member.
+export const classifyMember = (member, deps = {}) => {
+  const validate = deps.validate ?? validateManifest;
+  const readVersion = deps.readVersion ?? readAuthoritativeVersion;
+  const getenv = deps.getenv ?? process.env;
+  const home = deps.home ?? os.homedir();
+
+  const skillDir = resolveDir({ env: member.installed.env, default: member.installed.default }, getenv, home);
+  const marker = probeMarker(join(skillDir, member.installed.file), deps);
+  // A marker we cannot probe (EACCES/EIO) → 'unknown': reported, but NOT installed (so uninstall never
+  // removes a dir whose ownership it could not verify). Distinct from 'not-installed' (genuinely absent).
+  if (marker === 'unknown') {
+    return { name: member.name, kind: member.kind, installed: false, skillDir, manifestState: UNKNOWN, version: null };
+  }
+  const markerPresent = marker === 'present';
+  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;
+
+  return { name: member.name, kind: member.kind, installed, skillDir: installed ? skillDir : null, manifestState, version };
+};
+
+export const surveyFamily = (deps = {}) => FAMILY_MEMBERS.map((member) => classifyMember(member, deps));
+
+// ── the DEPLOY axis ──────────────────────────────────────────────────────────────
+// Read a one-line semver stamp (docs/ai/.workflow-version etc.). Returns the trimmed version or null.
+const readStamp = (path, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const read = deps.readFile ?? readFileSync;
+  try {
+    if (!exists(path)) return null;
+    const v = String(read(path, 'utf8')).trim();
+    return v.length ? v : null;
+  } catch {
+    return null;
+  }
+};
+
+// Is our hidden-mode managed fence present? Resolve the exclude file via the SAME git-path-aware path
+// hide-footprint uses (`git rev-parse --git-path info/exclude`), so a linked worktree / submodule is
+// handled correctly (not the hardcoded `.git/info/exclude`). If git is unavailable or this is not a
+// repo, fall back to the conventional path; any read error → not present (best-effort, read-only).
+const hasHiddenFence = (projectDir, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const read = deps.readFile ?? readFileSync;
+  const ep = (() => {
+    try {
+      return excludePath(deps, projectDir);
+    } catch {
+      return join(projectDir, '.git', 'info', 'exclude');
+    }
+  })();
+  try {
+    return exists(ep) && String(read(ep, 'utf8')).includes(START_MARKER);
+  } catch {
+    return false;
+  }
+};
+
+// surveyProject → the deploy axis for a target project dir: the per-member deployment stamps, whether
+// docs/ai/ exists, and whether the hidden-mode fence is present. Pure (fs reads only, all injectable),
+// no git subprocess — the read-only `status` view must never mutate or spawn anything.
+export const surveyProject = (projectDir, deps = {}) => {
+  const exists = deps.exists ?? existsSync;
+  const dir = resolve(projectDir);
+  const stamps = FAMILY_MEMBERS
+    .filter((m) => m.deployed)
+    .map((m) => ({ name: m.name, file: m.deployed.file, version: readStamp(join(dir, m.deployed.file), deps) }));
+  const docsAiPresent = (() => {
+    try {
+      return exists(join(dir, 'docs', 'ai'));
+    } catch {
+      return false;
+    }
+  })();
+  const deployed = stamps.some((s) => s.version != null) || docsAiPresent;
+  return { dir, deployed, docsAiPresent, hiddenFence: hasHiddenFence(dir, deps), stamps };
+};
+
+// ── report ───────────────────────────────────────────────────────────────────────
+const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
+
+export const formatStatus = (family, project = null) => {
+  const lines = ['agent-workflow family — installed skills (skill axis)', ''];
+  for (const m of family) {
+    const ver = m.version ? `v${m.version}` : '—';
+    lines.push(`  ${pad(m.name, 26)}[${pad(m.manifestState, 16)}] ${pad(ver, 10)} ${m.kind}`);
+  }
+  if (project) {
+    lines.push('', `project deployment (${project.dir})`, '');
+    if (!project.deployed) {
+      lines.push('  no agent-workflow deployment detected here (no docs/ai, no version stamp).');
+    } else {
+      for (const s of project.stamps) {
+        lines.push(`  ${pad(s.file, 26)}${s.version ?? '—'}`);
+      }
+      lines.push(`  ${pad('docs/ai present', 26)}${project.docsAiPresent ? 'yes' : 'no'}`);
+      lines.push(`  ${pad('hidden-mode fence', 26)}${project.hiddenFence ? 'present' : 'absent'}`);
+    }
+  }
+  return lines.join('\n');
+};
+
+// ── CLI ────────────────────────────────────────────────────────────────────────
+const parseArgs = (argv) => {
+  const dirFlag = argv.indexOf('--dir');
+  return { help: argv.includes('--help') || argv.includes('-h'), dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined };
+};
+
+const main = (argv) => {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(`family-registry — read-only view of the agent-workflow family.
+
+Usage:
+  node family-registry.mjs [--dir <project>]   # skill axis always; deploy axis when --dir is given
+
+Detection only — never writes, never commits, never runs a subscription CLI.`);
+    return;
+  }
+  const family = surveyFamily();
+  const project = args.dir ? surveyProject(args.dir) : null;
+  console.log(formatStatus(family, project));
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main(process.argv.slice(2));

package/tools/family-registry.test.mjs

@@ -0,0 +1,189 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  FAMILY_MEMBERS,
+  classifyMember,
+  surveyFamily,
+  surveyProject,
+  NOT_INSTALLED,
+  UNSUPPORTED_SCHEMA,
+  INVALID_MANIFEST,
+  STUB,
+  FOREIGN,
+  OK,
+  UNKNOWN,
+} from './family-registry.mjs';
+import { VALID, INVALID, UNSUPPORTED } from './manifest/validate.mjs';
+import { START_MARKER } from './hide-footprint.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '../..'); // agent-workflow-kit/tools → repo root
+
+// Build classifyMember deps that present the marker, with an injectable validate/readVersion.
+const installedDeps = ({ report, version = '9.9.9', home = '/home/test' }) => ({
+  exists: () => true,
+  stat: () => ({ isFile: () => true }),
+  getenv: {},
+  home,
+  validate: () => report,
+  readVersion: () => ({ version }),
+});
+
+const KIT = FAMILY_MEMBERS.find((m) => m.name === 'agent-workflow-kit');
+
+// ── classifyMember ───────────────────────────────────────────────────────────────
+
+describe('classifyMember', () => {
+  it('marks an absent marker as not-installed (no skillDir, no version)', () => {
+    const r = classifyMember(KIT, { exists: () => false, getenv: {}, home: '/home/test' });
+    assert.equal(r.manifestState, NOT_INSTALLED);
+    assert.equal(r.installed, false);
+    assert.equal(r.skillDir, null);
+    assert.equal(r.version, null);
+  });
+
+  it('classifies a valid matching manifest as ok and reports the authoritative version', () => {
+    const r = classifyMember(KIT, installedDeps({
+      report: { result: VALID, name: 'agent-workflow-kit', kind: 'composition-root', available: true },
+      version: '1.12.0',
+    }));
+    assert.equal(r.manifestState, OK);
+    assert.equal(r.installed, true);
+    assert.equal(r.version, '1.12.0');
+    assert.match(r.skillDir, /\.claude\/skills\/agent-workflow-kit$/);
+  });
+
+  it('classifies a wrong name/kind as foreign (never ours, never removed by uninstall)', () => {
+    const r = classifyMember(KIT, installedDeps({
+      report: { result: VALID, name: 'something-else', kind: 'composition-root', available: true },
+    }));
+    assert.equal(r.manifestState, FOREIGN);
+    assert.equal(r.version, null); // version only for ok
+  });
+
+  it('classifies available:false as a stub', () => {
+    const r = classifyMember(KIT, installedDeps({
+      report: { result: VALID, name: 'agent-workflow-kit', kind: 'composition-root', available: false },
+    }));
+    assert.equal(r.manifestState, STUB);
+  });
+
+  it('maps validator INVALID → invalid-manifest and UNSUPPORTED → unsupported-schema', () => {
+    assert.equal(classifyMember(KIT, installedDeps({ report: { result: INVALID } })).manifestState, INVALID_MANIFEST);
+    assert.equal(classifyMember(KIT, installedDeps({ report: { result: UNSUPPORTED } })).manifestState, UNSUPPORTED_SCHEMA);
+  });
+
+  it('surfaces an EACCES marker probe as "unknown" — never masked as not-installed', () => {
+    const eacces = () => { throw Object.assign(new Error('EACCES'), { code: 'EACCES' }); };
+    const r = classifyMember(KIT, { exists: eacces, getenv: {}, home: '/home/test' });
+    assert.equal(r.manifestState, UNKNOWN);
+    assert.equal(r.installed, false); // not removed — ownership could not be verified
+  });
+
+  it('resolves the skill dir from the env override when set (resolveDir reuse)', () => {
+    const r = classifyMember(KIT, {
+      exists: () => true,
+      stat: () => ({ isFile: () => true }),
+      getenv: { AGENT_WORKFLOW_KIT_DIR: '/custom/kit' },
+      home: '/home/test',
+      validate: () => ({ result: VALID, name: 'agent-workflow-kit', kind: 'composition-root', available: true }),
+      readVersion: () => ({ version: '1.12.0' }),
+    });
+    assert.equal(r.skillDir, '/custom/kit');
+  });
+});
+
+describe('surveyFamily', () => {
+  it('returns one row per member; all not-installed when no markers present', () => {
+    const rows = surveyFamily({ exists: () => false, getenv: {}, home: '/home/test' });
+    assert.equal(rows.length, FAMILY_MEMBERS.length);
+    assert.ok(rows.every((r) => r.manifestState === NOT_INSTALLED));
+  });
+});
+
+// ── surveyProject ────────────────────────────────────────────────────────────────
+
+describe('surveyProject', () => {
+  const projectDeps = ({ files }) => ({
+    exists: (p) => Object.prototype.hasOwnProperty.call(files, p) || Object.keys(files).some((k) => k === p),
+    readFile: (p) => {
+      if (!Object.prototype.hasOwnProperty.call(files, p)) throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+      return files[p];
+    },
+  });
+
+  it('reports deployed + stamps + docs/ai + hidden fence', () => {
+    const dir = '/proj';
+    const files = {
+      [join(dir, 'docs/ai/.workflow-version')]: '1.3.0\n',
+      [join(dir, 'docs/ai/.memory-version')]: '1.1.1\n',
+      [join(dir, 'docs', 'ai')]: '',
+      [join(dir, '.git', 'info', 'exclude')]: `# user rule\n${START_MARKER}\n/AGENTS.md\n`,
+    };
+    const r = surveyProject(dir, projectDeps({ files }));
+    assert.equal(r.deployed, true);
+    assert.equal(r.docsAiPresent, true);
+    assert.equal(r.hiddenFence, true);
+    assert.deepEqual(
+      r.stamps.map((s) => [s.name, s.version]),
+      [['agent-workflow-kit', '1.3.0'], ['agent-workflow-memory', '1.1.1']],
+    );
+  });
+
+  it('reports not-deployed when there is no docs/ai and no stamp', () => {
+    const r = surveyProject('/empty', projectDeps({ files: {} }));
+    assert.equal(r.deployed, false);
+    assert.equal(r.hiddenFence, false);
+    assert.ok(r.stamps.every((s) => s.version === null));
+  });
+});
+
+// ── drift-guard: FAMILY_MEMBERS ⟷ the 5 in-repo capability.json (the AD-008 lockstep pattern) ──────
+
+describe('FAMILY_MEMBERS drift-guard', () => {
+  const readManifest = (memberName) =>
+    JSON.parse(readFileSync(resolve(REPO_ROOT, memberName, 'capability.json'), 'utf8'));
+
+  // deduped roles[].cmd, in first-seen order (mirrors detect-backends' wrapperCmds derivation).
+  const dedupedCmds = (manifest) => {
+    const seen = new Set();
+    const out = [];
+    for (const role of Object.values(manifest.roles ?? {})) {
+      if (role && typeof role.cmd === 'string' && !seen.has(role.cmd)) {
+        seen.add(role.cmd);
+        out.push(role.cmd);
+      }
+    }
+    return out;
+  };
+
+  it('has exactly the five family members and no release skills', () => {
+    assert.equal(FAMILY_MEMBERS.length, 5);
+    const names = FAMILY_MEMBERS.map((m) => m.name);
+    assert.ok(!names.includes('release-engineering'));
+    assert.ok(!names.includes('release-marketing'));
+  });
+
+  for (const member of FAMILY_MEMBERS) {
+    it(`${member.name}: name/kind/detect.installed/deployed/npm/wrapperCmds match the in-repo manifest`, () => {
+      const m = readManifest(member.name);
+      assert.equal(m.name, member.name);
+      assert.equal(m.kind, member.kind);
+
+      assert.equal(m.detect.installed.env, member.installed.env);
+      assert.equal(m.detect.installed.default, member.installed.default);
+      assert.equal(m.detect.installed.file, member.installed.file);
+
+      if (member.deployed) assert.equal(m.detect.deployed.file, member.deployed.file);
+      else assert.equal(m.detect?.deployed ?? null, null);
+
+      if (member.npm) assert.equal(m.install.npm, member.npm);
+      else assert.equal(m.install?.npm ?? null, null);
+
+      assert.deepEqual(dedupedCmds(m), member.wrapperCmds);
+    });
+  }
+});

package/tools/fs-safe.mjs

@@ -4,15 +4,20 @@
 // 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:
+// Five 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.
+//   removeTreeManaged       — the inverse of copyTreeRefresh: recursively remove a dir/file ONLY when
+//                             it (and its path) is not reached through a symlink and stays within root.
+//   unlinkManaged           — the inverse of linkManaged: remove ONLY a symlink whose target is ours;
+//                             STOP (typed ManagedLinkConflict) on a foreign symlink or a non-symlink.
 
 import {
   lstatSync, existsSync, mkdirSync, readdirSync, copyFileSync, readlinkSync, symlinkSync,
+  rmSync, unlinkSync,
 } from 'node:fs';
 import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
 
@@ -44,7 +49,10 @@ 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)) {
+  // A true escape is `..` exactly or a `..`-prefixed PATH SEGMENT (`../x`) — NOT any string starting
+  // with the two chars "..": a legitimately-contained child literally named `..foo` has rel `..foo`,
+  // which the old `rel.startsWith('..')` wrongly rejected (Issue-004 — same fix as the engine/memory installers).
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     throw new Error(`[agent-workflow-kit] refusing to write outside the target dir: ${dest}`);
   }
   if (ln(root)?.isSymbolicLink()) {
@@ -127,3 +135,47 @@ export const linkManaged = (src, dest, root, deps = {}) => {
     { dest, expected: src, found: target },
   );
 };
+
+// Recursively remove a managed dir/file — the inverse of copyTreeRefresh. `assertContainedRealPath`
+// guards `target` first: it refuses a `target` outside `root`, and refuses when `root`, any
+// intermediate component, OR `target` itself is a symlink — so we never delete *through* or *at* a
+// symlink (a symlinked skill dir is a STOP, not a follow-and-delete). A recursive `rm` does NOT
+// follow symlinks *inside* the tree (Node unlinks a symlink entry rather than recursing into its
+// target), so an internal symlink is removed safely without touching what it points at. Outcomes:
+// 'removed', or 'noop' when the target is already absent. Dependency-injected (lstat / rm).
+export const removeTreeManaged = (target, root, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const rm = deps.rm ?? ((p) => rmSync(p, { recursive: true, force: true }));
+  assertContainedRealPath(root, target, deps);
+  if (lstatNoFollow(target, lstat) === null) return 'noop';
+  rm(target);
+  return 'removed';
+};
+
+// Remove ONLY a symlink we own — the inverse of linkManaged. Guards the PARENT chain (root +
+// intermediate dirs) the same way linkManaged does (the leaf IS the managed symlink, so it is
+// inspected, not traversal-rejected). Outcomes: 'unlinked' (a symlink whose resolved target is our
+// `expectedSrc` — including a dangling-but-ours link), 'noop' (dest absent), or a thrown
+// ManagedLinkConflict (a non-symlink, or a symlink pointing elsewhere — never removed).
+export const unlinkManaged = (dest, expectedSrc, root, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const readlink = deps.readlink ?? readlinkSync;
+  const unlink = deps.unlink ?? unlinkSync;
+
+  assertContainedRealPath(root, dirname(dest), deps);
+  const existing = lstatNoFollow(dest, lstat);
+  if (existing === null) return 'noop';
+  if (!existing.isSymbolicLink()) {
+    throw managedLinkConflict(`refusing to remove a non-symlink at ${dest}`, { dest, found: 'file' });
+  }
+  const target = readlink(dest);
+  const resolvedTarget = isAbsolute(target) ? target : resolve(dirname(dest), target);
+  if (resolvedTarget !== resolve(expectedSrc)) {
+    throw managedLinkConflict(
+      `refusing to remove a foreign symlink at ${dest} (points at ${target}, not our ${expectedSrc})`,
+      { dest, expected: expectedSrc, found: target },
+    );
+  }
+  unlink(dest);
+  return 'unlinked';
+};