skillrepo 3.2.0 → 4.0.0

package/src/test/lib/cli-config.test.mjs

@@ -4,8 +4,10 @@
  * Covers:
  *   • resolveFlags — every flag, the priority order (CLI flag > config
  *     file > env var > default), error paths
- *   • effectiveVendors — defaults, --global override, explicit list
- *   • parseVendorList edge cases (alias, all, empty, unknown)
+ *   • effectiveVendors — defaults, --global override, explicit list,
+ *     `--agent none` empty-array sentinel
+ *   • parseAgentList edge cases (token expansion, aliases, none, unknown)
+ *   • requireVendorTargets — rejects `--agent none` for write commands
  *
  * The cli-config helper is shared by all four PR2 commands and PR3a's
  * write commands, so coverage here is load-bearing.
@@ -17,7 +19,12 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { resolveFlags, effectiveVendors } from "../../lib/cli-config.mjs";
+import {
+  resolveFlags,
+  effectiveVendors,
+  requireVendorTargets,
+} from "../../lib/cli-config.mjs";
+import { AGENT_REGISTRY } from "../../lib/agent-registry.mjs";
 import { isTransientRunnerInvocation } from "../../lib/transient-runners.mjs";
 import { CliError, EXIT_AUTH, EXIT_VALIDATION } from "../../lib/errors.mjs";
 import {
@@ -236,73 +243,183 @@ describe("resolveFlags — flag parsing", () => {
     assert.equal(flags.serverUrl, "https://x");
   });
 
-  it("parses --ide claudeCode", () => {
+  it("parses --agent claudeCode", () => {
     process.env.SKILLREPO_ACCESS_KEY = "k";
-    const flags = resolveFlags(["--ide", "claudeCode"]);
+    const flags = resolveFlags(["--agent", "claudeCode"]);
     assert.deepEqual(flags.vendors, ["claudeCode"]);
   });
 
-  it("parses --ide alias 'claude' as claudeCode", () => {
+  it("parses --agent claude (canonical target shortcut) as claudeCode", () => {
     process.env.SKILLREPO_ACCESS_KEY = "k";
-    const flags = resolveFlags(["--ide", "claude"]);
+    const flags = resolveFlags(["--agent", "claude"]);
     assert.deepEqual(flags.vendors, ["claudeCode"]);
   });
 
-  it("parses --ide multi-vendor", () => {
+  it("parses --agent agents (cohort token) to every agentsProject vendor", () => {
+    // Asserts against the registry directly rather than a literal
+    // list, so adding a new `agentsProject` vendor updates this test
+    // automatically.
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--agent", "agents"]);
+    const expected = AGENT_REGISTRY
+      .filter((e) => e.projectTarget === "agentsProject")
+      .map((e) => e.key);
+    assert.deepEqual(flags.vendors, expected);
+    assert.ok(expected.length >= 6, "cohort must contain at least 6 vendors");
+  });
+
+  it("parses --agent claude,agents to claudeCode + every agentsProject vendor", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--agent", "claude,agents"]);
+    const cohort = AGENT_REGISTRY
+      .filter((e) => e.projectTarget === "agentsProject")
+      .map((e) => e.key);
+    assert.deepEqual(flags.vendors, ["claudeCode", ...cohort]);
+  });
+
+  it("parses --agent claude,cursor,gemini (mixed canonical + cohort vendor names)", () => {
     process.env.SKILLREPO_ACCESS_KEY = "k";
-    const flags = resolveFlags(["--ide", "claude,cursor,windsurf"]);
-    assert.deepEqual(flags.vendors, ["claudeCode", "cursor", "windsurf"]);
+    const flags = resolveFlags(["--agent", "claude,cursor,gemini"]);
+    assert.deepEqual(flags.vendors, ["claudeCode", "cursor", "gemini"]);
   });
 
-  it("parses --ide all as the full vendor list", () => {
+  it("parses --agent cursor (cohort vendor name as silent alias)", () => {
+    // A user typing a vendor name they know (cursor) gets that
+    // single vendor — they DON'T silently get expanded to the whole
+    // cohort. The cohort expansion is reserved for the explicit
+    // `agents` token.
     process.env.SKILLREPO_ACCESS_KEY = "k";
-    const flags = resolveFlags(["--ide", "all"]);
-    assert.deepEqual(flags.vendors, ["claudeCode", "cursor", "windsurf", "vscode"]);
+    const flags = resolveFlags(["--agent", "cursor"]);
+    assert.deepEqual(flags.vendors, ["cursor"]);
   });
 
-  it("rejects --ide cursor,all (mixing all with explicit vendors is ambiguous)", () => {
+  it("parses --agent claude-code (registry alias) as claudeCode", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--agent", "claude-code"]);
+    assert.deepEqual(flags.vendors, ["claudeCode"]);
+  });
+
+  it("parses --agent vscode (registry alias) as copilot", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--agent", "vscode"]);
+    assert.deepEqual(flags.vendors, ["copilot"]);
+  });
+
+  it("parses --agent none to the empty-array sentinel", () => {
+    // `none` is the explicit "no placement" token. Returns `[]`
+    // (frozen) so callers detect via `.length === 0`. The empty
+    // array distinguishes "user opted out" from `null` ("user
+    // didn't pass --agent at all → use the default").
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--agent", "none"]);
+    assert.ok(Array.isArray(flags.vendors));
+    assert.equal(flags.vendors.length, 0);
+  });
+
+  it("dedupes --agent claude,claude to a single vendor", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--agent", "claude,claude"]);
+    assert.deepEqual(flags.vendors, ["claudeCode"]);
+  });
+
+  it("dedupes --agent claude,claude-code (alias collapses to canonical)", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--agent", "claude,claude-code"]);
+    assert.deepEqual(flags.vendors, ["claudeCode"]);
+  });
+
+  it("rejects --agent claude,none (mixing none with other tokens is ambiguous)", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["--agent", "claude,none"]),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /cannot mix "none"/.test(err.message),
+    );
+  });
+
+  it("rejects --agent none,claude in the other order too", () => {
     process.env.SKILLREPO_ACCESS_KEY = "k";
     assert.throws(
-      () => resolveFlags(["--ide", "cursor,all"]),
-      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION && /cannot mix/.test(err.message),
+      () => resolveFlags(["--agent", "none,claude"]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
     );
   });
 
-  it("rejects --ide all,cursor in the other order too", () => {
+  it("rejects --agent all (the legacy --ide token is not supported)", () => {
+    // The old `--ide all` is intentionally dropped — `--agent
+    // claude,agents` is the new explicit way to get every target.
+    // Accepting `all` would be a deprecation alias, which the
+    // partner-mode rules forbid (no users to preserve).
     process.env.SKILLREPO_ACCESS_KEY = "k";
     assert.throws(
-      () => resolveFlags(["--ide", "all,cursor"]),
+      () => resolveFlags(["--agent", "all"]),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /Unknown --agent target/.test(err.message),
+    );
+  });
+
+  it("rejects --agent agents,all (the `all` token is gone in either position)", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["--agent", "agents,all"]),
       (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
     );
   });
 
-  it("accepts --ide all,all (degenerate case dedupes to the full set)", () => {
-    // The `all` token is hard-coded to mean the full vendor list. A
-    // user passing it twice is a degenerate input but unambiguous —
-    // both `all`s expand to the same set, so we accept it. This test
-    // locks the behavior so a future tightening of parseVendorList
-    // doesn't accidentally start rejecting it.
+  it("rejects unknown --agent target", () => {
     process.env.SKILLREPO_ACCESS_KEY = "k";
-    const flags = resolveFlags(["--ide", "all,all"]);
-    assert.deepEqual(flags.vendors, ["claudeCode", "cursor", "windsurf", "vscode"]);
+    assert.throws(
+      () => resolveFlags(["--agent", "jetbrains"]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
   });
 
-  it("rejects unknown --ide vendor", () => {
+  it("rejects empty --agent list (only commas)", () => {
     process.env.SKILLREPO_ACCESS_KEY = "k";
     assert.throws(
-      () => resolveFlags(["--ide", "jetbrains"]),
+      () => resolveFlags(["--agent", ","]),
       (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
     );
   });
 
-  it("rejects empty --ide list", () => {
+  it("rejects --agent with empty value", () => {
     process.env.SKILLREPO_ACCESS_KEY = "k";
     assert.throws(
-      () => resolveFlags(["--ide", ","]),
+      () => resolveFlags(["--agent", ""]),
       (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
     );
   });
 
+  it("gives an actionable error when --agent is the final argv with no value", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["--agent"]),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /Missing value for --agent/.test(err.message),
+    );
+  });
+
+  it("rejects the legacy --ide flag entirely", () => {
+    // No deprecation alias by design (partner-mode: no users to
+    // preserve). The old flag is rejected with a hint pointing the
+    // user at --agent so v2→v3 muscle-memory invocations get an
+    // actionable error rather than a generic "unknown argument."
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["--ide", "claude"]),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /--ide was renamed to --agent/.test(err.message),
+    );
+  });
+
   it("rejects unknown flag without acceptPositional", () => {
     process.env.SKILLREPO_ACCESS_KEY = "k";
     assert.throws(
@@ -390,27 +507,94 @@ describe("resolveFlags — positional callback", () => {
 // ── effectiveVendors ───────────────────────────────────────────────────
 
 describe("effectiveVendors", () => {
-  it("returns ['claudeCode'] by default", () => {
+  it("returns ['claudeCode'] by default (no flags)", () => {
     assert.deepEqual(effectiveVendors({ vendors: null, global: false }), ["claudeCode"]);
   });
 
-  it("returns undefined for global mode", () => {
-    assert.equal(effectiveVendors({ vendors: null, global: true }), undefined);
+  it("returns ['claudeCode'] for bare --global with no --agent", () => {
+    // Bare --global preserves the historical default of writing to
+    // ~/.claude/skills/. The user can override with `--global --agent X`.
+    assert.deepEqual(effectiveVendors({ vendors: null, global: true }), ["claudeCode"]);
   });
 
-  it("global overrides explicit vendors", () => {
-    assert.equal(
-      effectiveVendors({ vendors: ["cursor"], global: true }),
-      undefined,
+  it("preserves --agent under --global (does NOT discard the vendor list)", () => {
+    // Intent: `--global --agent windsurf` MUST resolve to ["windsurf"]
+    // so placementTargetsFor can map it to windsurfGlobal. The old
+    // bug was that --global silently dropped the vendor list,
+    // routing every --global invocation to claudeGlobal regardless
+    // of the user's explicit --agent choice.
+    assert.deepEqual(
+      effectiveVendors({ vendors: ["windsurf"], global: true }),
+      ["windsurf"],
+    );
+    assert.deepEqual(
+      effectiveVendors({ vendors: ["copilot"], global: true }),
+      ["copilot"],
+    );
+    assert.deepEqual(
+      effectiveVendors({ vendors: ["claudeCode", "cursor"], global: true }),
+      ["claudeCode", "cursor"],
     );
   });
 
-  it("returns explicit vendors when set", () => {
+  it("returns explicit vendors when set (no --global)", () => {
     assert.deepEqual(
       effectiveVendors({ vendors: ["claudeCode", "cursor"], global: false }),
       ["claudeCode", "cursor"],
     );
   });
+
+  it("returns the empty array verbatim for the --agent none sentinel", () => {
+    // The empty-array sentinel must NOT be coerced back to the
+    // ['claudeCode'] default — that would silently re-target a user
+    // who explicitly opted out via `--agent none`.
+    const result = effectiveVendors({ vendors: [], global: false });
+    assert.ok(Array.isArray(result));
+    assert.equal(result.length, 0);
+  });
+
+  it("preserves the --agent none sentinel under --global", () => {
+    // `--global --agent none` should still mean "no placement writes."
+    // Don't silently re-target.
+    const result = effectiveVendors({ vendors: [], global: true });
+    assert.ok(Array.isArray(result));
+    assert.equal(result.length, 0);
+  });
+});
+
+// ── requireVendorTargets ───────────────────────────────────────────────
+
+describe("requireVendorTargets", () => {
+  it("throws validationError when vendors is the empty array", () => {
+    assert.throws(
+      () => requireVendorTargets([], "add"),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /--agent none has no effect on `skillrepo add`/.test(err.message),
+    );
+  });
+
+  it("includes the command name in the error message", () => {
+    assert.throws(
+      () => requireVendorTargets([], "remove"),
+      (err) =>
+        err instanceof CliError &&
+        /--agent none has no effect on `skillrepo remove`/.test(err.message),
+    );
+  });
+
+  it("does not throw when vendors has entries", () => {
+    assert.doesNotThrow(() => requireVendorTargets(["claudeCode"], "add"));
+    assert.doesNotThrow(() => requireVendorTargets(["cursor", "gemini"], "get"));
+  });
+
+  it("does not throw when vendors is undefined (the --global case)", () => {
+    // `effectiveVendors` returns undefined under --global. Only an
+    // explicit empty array is rejected — undefined is the legitimate
+    // "use the Claude Code personal target" signal.
+    assert.doesNotThrow(() => requireVendorTargets(undefined, "add"));
+  });
 });
 
 // ── isTransientRunnerInvocation ───────────────────────────────────────────────────

package/src/test/lib/detect-agents.test.mjs

@@ -0,0 +1,336 @@
+/**
+ * Unit tests for src/lib/detect-agents.mjs (#1236, Phase 3 of #876).
+ *
+ * Coverage:
+ *   - Per-signal-type probes (env / home / project)
+ *   - OR semantics: any signal fires → detected
+ *   - Priority order: env > home > project (first-fire wins for the
+ *     human-readable `reason`)
+ *   - All seven registry agents produce a result (registry-driven)
+ *   - Cross-platform path resolution via sandbox-home
+ *   - Truthy-vs-empty env handling (empty string is NOT truthy)
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { detectAgents } from "../../lib/detect-agents.mjs";
+import { AGENT_REGISTRY } from "../../lib/agent-registry.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
+
+let sandbox;
+let originalCwd;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+/** @type {Record<string, string | undefined>} */
+let originalEnvVars;
+
+// Every env var the registry references as a detection signal. Each
+// test snapshots and restores these so a stray env var on the host
+// machine cannot leak into the assertions.
+const ENV_VAR_NAMES = Array.from(
+  new Set(
+    AGENT_REGISTRY.flatMap((entry) =>
+      entry.detectionSignals
+        .filter((s) => s.type === "env")
+        .map((s) => s.value),
+    ),
+  ),
+);
+
+function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-detect-agents-"));
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHomeEnv = captureHome();
+  // Snapshot every detection-relevant env var. Delete each so the
+  // baseline is "no signals firing" — individual tests opt-in to the
+  // env vars they want to set.
+  originalEnvVars = {};
+  for (const name of ENV_VAR_NAMES) {
+    originalEnvVars[name] = process.env[name];
+    delete process.env[name];
+  }
+  process.chdir(join(sandbox, "project"));
+  setSandboxHome(join(sandbox, "home"));
+}
+
+function teardown() {
+  process.chdir(originalCwd);
+  restoreHome(originalHomeEnv);
+  for (const name of ENV_VAR_NAMES) {
+    if (originalEnvVars[name] === undefined) delete process.env[name];
+    else process.env[name] = originalEnvVars[name];
+  }
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+function findResult(detections, key) {
+  return detections.find((d) => d.key === key);
+}
+
+// ── Baseline ────────────────────────────────────────────────────────
+
+describe("detectAgents — baseline", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("returns one result per registry entry, in registry order", () => {
+    const result = detectAgents();
+    assert.equal(result.length, AGENT_REGISTRY.length);
+    for (let i = 0; i < AGENT_REGISTRY.length; i++) {
+      assert.equal(result[i].key, AGENT_REGISTRY[i].key);
+      assert.equal(result[i].displayName, AGENT_REGISTRY[i].displayName);
+    }
+  });
+
+  it("returns detected=false and reason=null for every agent in a clean sandbox", () => {
+    const result = detectAgents();
+    for (const detection of result) {
+      assert.equal(
+        detection.detected,
+        false,
+        `${detection.key} should not be detected in a clean sandbox`,
+      );
+      assert.equal(detection.reason, null);
+    }
+  });
+});
+
+// ── Per-signal-type probes ──────────────────────────────────────────
+
+describe("detectAgents — env signal", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("detects Claude Code via CLAUDECODE env var", () => {
+    process.env.CLAUDECODE = "1";
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CLAUDECODE=1");
+  });
+
+  it("detects Cursor via CURSOR_AGENT env var", () => {
+    process.env.CURSOR_AGENT = "1";
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CURSOR_AGENT=1");
+  });
+
+  it("detects Cursor via CURSOR_CLI env var (fallback signal)", () => {
+    process.env.CURSOR_CLI = "1";
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CURSOR_CLI=1");
+  });
+
+  it("detects Gemini via GEMINI_CLI env var", () => {
+    process.env.GEMINI_CLI = "1";
+    const result = findResult(detectAgents(), "gemini");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "GEMINI_CLI=1");
+  });
+
+  it("detects Cline via CLINE_ACTIVE='true'", () => {
+    process.env.CLINE_ACTIVE = "true";
+    const result = findResult(detectAgents(), "cline");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CLINE_ACTIVE=true");
+  });
+
+  it("does NOT fire on empty-string env var (e.g., CLAUDECODE='')", () => {
+    process.env.CLAUDECODE = "";
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, false);
+    assert.equal(result.reason, null);
+  });
+
+  it("does NOT detect Codex via env var (Codex has no documented active-session env)", () => {
+    // Defensive lock: a future maintainer who adds CODEX_HOME as an
+    // env signal would silently produce false positives because
+    // CODEX_HOME is a config var Codex *reads*, not one it sets in
+    // spawned shells. This test holds the line.
+    process.env.CODEX_HOME = "/some/path";
+    const result = findResult(detectAgents(), "codex");
+    assert.equal(result.detected, false);
+  });
+});
+
+describe("detectAgents — home signal", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("detects Claude Code via ~/.claude/ directory", () => {
+    mkdirSync(join(process.env.HOME, ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.claude/");
+  });
+
+  it("detects Cursor via ~/.cursor/ directory", () => {
+    mkdirSync(join(process.env.HOME, ".cursor"), { recursive: true });
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.cursor/");
+  });
+
+  it("detects Windsurf via ~/.codeium/windsurf/ directory (Codeium prefix)", () => {
+    mkdirSync(join(process.env.HOME, ".codeium", "windsurf"), {
+      recursive: true,
+    });
+    const result = findResult(detectAgents(), "windsurf");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.codeium/windsurf/");
+  });
+
+  it("detects Codex via ~/.codex/ directory (HOME-only — no env signal)", () => {
+    mkdirSync(join(process.env.HOME, ".codex"), { recursive: true });
+    const result = findResult(detectAgents(), "codex");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.codex/");
+  });
+
+  it("detects Copilot via ~/.copilot/ directory", () => {
+    mkdirSync(join(process.env.HOME, ".copilot"), { recursive: true });
+    const result = findResult(detectAgents(), "copilot");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.copilot/");
+  });
+});
+
+describe("detectAgents — project signal", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("detects Claude Code via project .claude/ directory", () => {
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".claude/");
+  });
+
+  it("detects Cursor via project .cursor/ directory", () => {
+    mkdirSync(join(process.cwd(), ".cursor"), { recursive: true });
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".cursor/");
+  });
+
+  it("detects Windsurf via project .windsurf/ directory", () => {
+    mkdirSync(join(process.cwd(), ".windsurf"), { recursive: true });
+    const result = findResult(detectAgents(), "windsurf");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".windsurf/");
+  });
+
+  it("detects Gemini via project .gemini/ directory", () => {
+    mkdirSync(join(process.cwd(), ".gemini"), { recursive: true });
+    const result = findResult(detectAgents(), "gemini");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".gemini/");
+  });
+
+  it("detects Codex via project .codex/ directory", () => {
+    mkdirSync(join(process.cwd(), ".codex"), { recursive: true });
+    const result = findResult(detectAgents(), "codex");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".codex/");
+  });
+
+  it("detects Cline via project .cline/ directory", () => {
+    mkdirSync(join(process.cwd(), ".cline"), { recursive: true });
+    const result = findResult(detectAgents(), "cline");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".cline/");
+  });
+
+  it("detects Copilot via .github/skills/ directory", () => {
+    mkdirSync(join(process.cwd(), ".github", "skills"), { recursive: true });
+    const result = findResult(detectAgents(), "copilot");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".github/skills/");
+  });
+});
+
+// ── OR semantics + priority order ───────────────────────────────────
+
+describe("detectAgents — OR semantics + priority", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("fires when only one of multiple signals is present", () => {
+    // Cursor has env + home + project; only project is set here.
+    mkdirSync(join(process.cwd(), ".cursor"), { recursive: true });
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".cursor/");
+  });
+
+  it("env signal wins over home signal when both fire", () => {
+    process.env.CLAUDECODE = "1";
+    mkdirSync(join(process.env.HOME, ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    // env first by registry signal order — the formatted reason
+    // confirms the env signal won.
+    assert.equal(result.reason, "CLAUDECODE=1");
+  });
+
+  it("env signal wins over project signal when both fire", () => {
+    process.env.CLAUDECODE = "1";
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CLAUDECODE=1");
+  });
+
+  it("home signal wins over project signal when env is absent", () => {
+    mkdirSync(join(process.env.HOME, ".claude"), { recursive: true });
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.claude/");
+  });
+
+  it("primary env signal wins over fallback env signal (Cursor: CURSOR_AGENT > CURSOR_CLI)", () => {
+    process.env.CURSOR_AGENT = "1";
+    process.env.CURSOR_CLI = "1";
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.reason, "CURSOR_AGENT=1");
+  });
+});
+
+// ── Registry-driven coverage (the real durability win) ─────────────
+
+describe("detectAgents — registry-driven coverage", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("every agent has at least one detection signal declared", () => {
+    // Locks the registry contract: a future entry that forgets
+    // detectionSignals would silently never fire.
+    for (const entry of AGENT_REGISTRY) {
+      assert.ok(
+        Array.isArray(entry.detectionSignals) &&
+          entry.detectionSignals.length > 0,
+        `${entry.key} must have at least one detection signal`,
+      );
+    }
+  });
+
+  it("every agent's first signal is reachable (probe doesn't throw)", () => {
+    // Smoke test: detectAgents() must succeed regardless of which
+    // signal types the registry uses. A typo'd signal type would
+    // silently return null forever; this test catches that by
+    // proving a clean run completes.
+    assert.doesNotThrow(() => detectAgents());
+  });
+});