portawhip 0.1.0

package/core/surface/config-sync-backends.mjs

@@ -0,0 +1,224 @@
+import spawnSync from "cross-spawn";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const BACKEND_ALIASES = {
+  ai: "ai-config-sync",
+  "ai-config": "ai-config-sync",
+  "ai-config-sync-manager": "ai-config-sync",
+  asm: "agent-skill-manager",
+  "agent-skills": "agent-skill-manager",
+  agents: "agents-dotdir",
+  ".agents": "agents-dotdir",
+};
+
+const MAX_OUTPUT_CHARS = 12000;
+
+export const CONFIG_SYNC_BACKENDS = {
+  "ai-config-sync": {
+    id: "ai-config-sync",
+    label: "ai-config-sync-manager",
+    command: "ai-config-sync",
+    npxPackage: "ai-config-sync-manager",
+    installHint: "npm install -g ai-config-sync-manager",
+    supports: {
+      status: true,
+      preview: true,
+      apply: true,
+    },
+    description: "Bidirectional Claude Code/Codex sync for instructions, skills, agents, MCP, hooks, and permissions.",
+  },
+  "agent-skill-manager": {
+    id: "agent-skill-manager",
+    label: "agent-skill-manager",
+    command: "agent-skill-manager",
+    npxPackage: "agent-skill-manager",
+    installHint: "npm install agent-skill-manager or run through npx --yes agent-skill-manager",
+    supports: {
+      status: true,
+      preview: false,
+      apply: false,
+    },
+    description: "Skill provider inventory/probe backend already used by the loader for skill installs.",
+  },
+  "agents-dotdir": {
+    id: "agents-dotdir",
+    label: "@agents-dev/cli",
+    command: "agents",
+    npxPackage: "@agents-dev/cli",
+    installHint: "npm install -g @agents-dev/cli",
+    supports: {
+      status: true,
+      preview: true,
+      apply: true,
+    },
+    description: "Project .agents/ source-of-truth sync for MCP servers, skills, and instructions across many hosts.",
+  },
+};
+
+export function normalizeBackendId(id) {
+  const raw = id ?? "ai-config-sync";
+  return BACKEND_ALIASES[raw] ?? raw;
+}
+
+export function backendById(id) {
+  const normalized = normalizeBackendId(id);
+  const backend = CONFIG_SYNC_BACKENDS[normalized];
+  if (!backend) {
+    throw new Error(`unknown backend "${id}". valid: ${Object.keys(CONFIG_SYNC_BACKENDS).join(", ")}`);
+  }
+  return backend;
+}
+
+export function buildBackendArgs(backendId, action, options = {}) {
+  const backend = backendById(backendId);
+  if (!backend.supports[action]) {
+    throw new Error(`${backend.id} does not support ${action}; use status for probe-only backends`);
+  }
+
+  const scope = options.scope && options.scope !== "all" ? ["--scope", options.scope] : [];
+  const selectors = [
+    ...(options.include ? ["--include", options.include] : []),
+    ...(options.exclude ? ["--exclude", options.exclude] : []),
+  ];
+  const direction = [
+    ...(options.from ? ["--from", options.from] : []),
+    ...(options.to ? ["--to", options.to] : []),
+  ];
+
+  if (backend.id === "ai-config-sync") {
+    if (action === "status") return ["status", "--json", ...scope, ...selectors];
+    if (action === "preview") return ["sync", "--dry-run", "--plan-json", ...direction, ...scope, ...selectors];
+    return [
+      "sync",
+      "--apply",
+      "--ledger-json",
+      ...direction,
+      ...scope,
+      ...selectors,
+    ];
+  }
+
+  if (backend.id === "agent-skill-manager") {
+    return ["config", "show"];
+  }
+
+  if (backend.id === "agents-dotdir") {
+    if (action === "status") return ["status", "--fast"];
+    if (action === "preview") return ["sync", "--check"];
+    return ["sync"];
+  }
+
+  throw new Error(`unhandled backend ${backend.id}`);
+}
+
+export function runBackend(backendId, action, options = {}, runner = spawnSync.sync) {
+  const backend = backendById(backendId);
+  const args = buildBackendArgs(backend.id, action, options);
+  const invocation = resolveBackendInvocation(backend, args, options);
+  const result = runner(invocation.command, invocation.args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+  });
+  const errorText = result.error ? `${result.error.code || "ERROR"}: ${result.error.message}` : "";
+  const rawOutput = `${result.stdout || ""}${result.stderr || ""}${errorText ? `${errorText}\n` : ""}`;
+  const output = trimOutput(rawOutput);
+  const parsed = parseLeadingJson(rawOutput);
+  const innerErrors = parsed?.summary?.error ?? 0;
+  const plannedChanges = isPlannedChangeExit(backend.id, action, result.status, rawOutput);
+  const ok = (result.status === 0 || plannedChanges) && innerErrors === 0;
+  return {
+    backend: backend.id,
+    label: backend.label,
+    action,
+    command: [invocation.command, ...invocation.args],
+    ok,
+    status: plannedChanges ? "changed" : ok ? "success" : "error",
+    summary: ok
+      ? plannedChanges
+        ? `${backend.label} ${action} found planned changes`
+        : `${backend.label} ${action} completed`
+      : innerErrors > 0
+        ? `${backend.label} ${action} reported ${innerErrors} inner error(s)`
+        : `${backend.label} ${action} failed`,
+    output,
+    outputTruncated: output.length < rawOutput.length,
+    parsedSummary: parsed?.summary ?? null,
+    installHint: ok || innerErrors > 0 ? null : backend.installHint,
+    next_actions: ok
+      ? nextActionsForSuccess(backend.id, action)
+      : innerErrors > 0
+        ? ["Inspect the backend ledger/output; the command ran but reported failed operations."]
+        : [`Install or expose the backend command: ${backend.installHint}`, "Re-run sync-config status after install."],
+    artifacts: [],
+  };
+}
+
+function isPlannedChangeExit(backendId, action, status, output) {
+  return (
+    backendId === "agents-dotdir" &&
+    action === "preview" &&
+    status !== 0 &&
+    /\bWould (create|update|remove) \d+ item\(s\):/.test(output)
+  );
+}
+
+function trimOutput(output) {
+  if (output.length <= MAX_OUTPUT_CHARS) return output;
+  return `${output.slice(0, MAX_OUTPUT_CHARS)}\n...[truncated ${output.length - MAX_OUTPUT_CHARS} chars]`;
+}
+
+function parseLeadingJson(output) {
+  const text = String(output ?? "").trimStart();
+  if (!text.startsWith("{")) return null;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === "\"") {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === "\"") {
+      inString = true;
+    } else if (ch === "{") {
+      depth += 1;
+    } else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        try {
+          return JSON.parse(text.slice(0, i + 1));
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function resolveBackendInvocation(backend, args, options = {}) {
+  const suffix = process.platform === "win32" ? ".cmd" : "";
+  const local = resolve("node_modules", ".bin", `${backend.command}${suffix}`);
+  if (existsSync(local)) return { command: local, args };
+  if (options.allowNpx || process.env.PORTAWHIP_ALLOW_NPX === "1") {
+    return { command: "npx", args: ["--yes", backend.npxPackage, ...args] };
+  }
+  return { command: backend.command, args };
+}
+
+function nextActionsForSuccess(backendId, action) {
+  if (backendId === "agent-skill-manager") {
+    return ["Use load.mjs for actual skill installs; this backend is probe-only here."];
+  }
+  if (action === "status") return ["Run preview before apply to inspect drift."];
+  if (action === "preview") return ["Review the plan, then run apply only if the changes are intended."];
+  return ["Run status again to confirm drift is gone."];
+}

package/core/surface/connector-targets.mjs

@@ -0,0 +1,205 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOME = homedir();
+
+function homePath(...parts) {
+  return join(HOME, ...parts);
+}
+
+function projectPath(...parts) {
+  return join(...parts);
+}
+
+// Connector targets are data, not decision logic. MCP installation is still
+// delegated to add-mcp; this table only records the instruction surfaces we
+// can safely upsert for hosts that need a reminder to call harness-router.
+export const CONNECTOR_TARGETS = {
+  "claude-code": {
+    instructionTargets: [
+      {
+        scope: "global",
+        path: homePath(".claude", "CLAUDE.md"),
+        variant: "claude-code",
+        note: "Claude Code can defer MCP tool schemas, so this block names the ToolSearch fallback.",
+      },
+      {
+        scope: "project",
+        path: projectPath("CLAUDE.md"),
+        variant: "claude-code",
+      },
+    ],
+  },
+  codex: {
+    instructionTargets: [
+      {
+        scope: "global",
+        path: homePath(".codex", "AGENTS.md"),
+        variant: "generic",
+      },
+      {
+        scope: "project",
+        path: projectPath("AGENTS.md"),
+        variant: "generic",
+      },
+    ],
+  },
+  "gemini-cli": {
+    instructionTargets: [
+      {
+        scope: "global",
+        path: homePath(".gemini", "GEMINI.md"),
+        variant: "generic",
+      },
+      {
+        scope: "project",
+        path: projectPath("GEMINI.md"),
+        variant: "generic",
+      },
+    ],
+  },
+  cursor: {
+    instructionTargets: [
+      {
+        scope: "project",
+        path: projectPath(".cursor", "rules", "harness-router.mdc"),
+        variant: "cursor-rule",
+        owned: true,
+        note: "Cursor project rules live under .cursor/rules; this rule is always applied.",
+      },
+      {
+        scope: "project",
+        path: projectPath("AGENTS.md"),
+        variant: "generic",
+        note: "Cursor also documents AGENTS.md support; keep this as a shared fallback.",
+      },
+    ],
+  },
+  // opencode already carries a native hook target (hook-targets.mjs); it also
+  // reads AGENTS.md at the project root and a personal global at
+  // ~/.config/opencode/AGENTS.md. Both are shared user files -> marker-upsert.
+  opencode: {
+    instructionTargets: [
+      {
+        scope: "global",
+        path: homePath(".config", "opencode", "AGENTS.md"),
+        variant: "generic",
+      },
+      {
+        scope: "project",
+        path: projectPath("AGENTS.md"),
+        variant: "generic",
+      },
+    ],
+  },
+  // Zed reads AGENTS.md as its primary instruction file (project + a personal
+  // global alongside settings at ~/.config/zed/AGENTS.md). No documented
+  // lifecycle hook API -> reported unsupported by link-hooks, not faked.
+  zed: {
+    instructionTargets: [
+      {
+        scope: "global",
+        path: homePath(".config", "zed", "AGENTS.md"),
+        variant: "generic",
+      },
+      {
+        scope: "project",
+        path: projectPath("AGENTS.md"),
+        variant: "generic",
+      },
+    ],
+  },
+  // Windsurf: a dedicated always-on workspace rule under .windsurf/rules
+  // (harness-owned whole file, frontmatter trigger: always_on), plus AGENTS.md
+  // as the shared project fallback, plus the always-on personal global memories
+  // file. No documented lifecycle hook API -> reported unsupported.
+  windsurf: {
+    instructionTargets: [
+      {
+        scope: "project",
+        path: projectPath(".windsurf", "rules", "harness-router.md"),
+        variant: "windsurf-rule",
+        owned: true,
+        note: "Windsurf workspace rule; trigger: always_on.",
+      },
+      {
+        scope: "project",
+        path: projectPath("AGENTS.md"),
+        variant: "generic",
+        note: "Windsurf also reads AGENTS.md; keep this as a shared fallback.",
+      },
+      {
+        scope: "global",
+        path: homePath(".codeium", "windsurf", "memories", "global_rules.md"),
+        variant: "generic",
+        note: "Windsurf global memories file is always on.",
+      },
+    ],
+  },
+  // Cline combines every .md/.txt file under .clinerules/ into its always-on
+  // rule set, so a dedicated harness-owned file drops in cleanly without a
+  // frontmatter activation mode. No documented lifecycle hook API.
+  cline: {
+    instructionTargets: [
+      {
+        scope: "project",
+        path: projectPath(".clinerules", "harness-router.md"),
+        variant: "generic",
+        owned: true,
+        note: "Cline reads all files under .clinerules/ as active rules.",
+      },
+    ],
+  },
+  "cline-cli": {
+    instructionTargets: [
+      {
+        scope: "project",
+        path: projectPath(".clinerules", "harness-router.md"),
+        variant: "generic",
+        owned: true,
+        note: "Cline CLI shares the .clinerules/ convention.",
+      },
+    ],
+  },
+  "github-copilot-cli": {
+    instructionTargets: [
+      {
+        scope: "project",
+        path: projectPath(".github", "copilot-instructions.md"),
+        variant: "generic",
+      },
+    ],
+  },
+  // Pi (earendil-works/pi): reads AGENTS.md walking up from cwd, plus a global
+  // ~/.pi/agent/AGENTS.md. Both are shared instruction files -> marker upsert.
+  // Source: https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md
+  pi: {
+    instructionTargets: [
+      { scope: "global", path: homePath(".pi", "agent", "AGENTS.md"), variant: "generic" },
+      { scope: "project", path: projectPath("AGENTS.md"), variant: "generic" },
+    ],
+  },
+  // Sourcegraph Amp: reads project AGENTS.md and a personal ~/.config/AGENTS.md.
+  // Source: https://ampcode.com/manual
+  amp: {
+    instructionTargets: [
+      { scope: "global", path: homePath(".config", "AGENTS.md"), variant: "generic" },
+      { scope: "project", path: projectPath("AGENTS.md"), variant: "generic" },
+    ],
+  },
+  vscode: {
+    instructionTargets: [
+      {
+        scope: "project",
+        path: projectPath(".github", "copilot-instructions.md"),
+        variant: "generic",
+      },
+    ],
+  },
+};
+
+export function targetsForHost(hostId, { scope = "project" } = {}) {
+  const targets = CONNECTOR_TARGETS[hostId]?.instructionTargets ?? [];
+  return targets.filter((target) => target.scope === scope);
+}
+

package/core/surface/discover-hooks.mjs

@@ -0,0 +1,151 @@
+// Embedded-hook inventory (Phase S3, mode B — scan + inventory only, NO
+// linking). Hooks bundled inside skills/plugins run third-party commands on
+// lifecycle events; today they are invisible to portawhip's own hook sync.
+// This module finds them and reports what/where they are so a later,
+// per-item-approved link step (S3 full) has something concrete to act on.
+//
+// Owns no linking and executes nothing — it only reads hooks.json files and
+// extracts each declared command. Command bodies are surfaced verbatim
+// (truncated for display, full source path kept) precisely because a human
+// must see the exact command before ever choosing to activate it.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOOK_SCAN_MAX_DEPTH = 9;
+const SKIP_DIRS = new Set([".git", "node_modules"]);
+const COMMAND_PREVIEW_CHARS = 160;
+
+export function defaultHookScanRoots() {
+  return [
+    join(homedir(), ".claude", "plugins", "cache"),
+    join(homedir(), ".claude", "plugins", "marketplaces"),
+    join(homedir(), ".claude", "skills"),
+    join(homedir(), ".codex", "skills"),
+  ];
+}
+
+// Pure: which host a hooks.json belongs to + whether it looks like a live
+// hook or a shipped template, inferred from its path segments (data, not a
+// decision that changes behavior — inventory metadata only).
+export function classifyHookPath(sourcePath) {
+  const segs = String(sourcePath).split(/[\\/]/);
+  const host = segs.includes(".codex")
+    ? "codex"
+    : segs.includes(".cursor")
+      ? "cursor"
+      : segs.includes(".gemini")
+        ? "gemini-cli"
+        : "claude-code";
+  const template = segs.includes("scaffolds") || segs.includes("templates") || segs.includes("schemas");
+  const pkg = inferPackage(segs);
+  return { host, template, pkg };
+}
+
+function inferPackage(segs) {
+  const i = segs.lastIndexOf("plugins");
+  if (i !== -1 && segs[i + 1]) {
+    // .../plugins/cache/<pkg>/... or .../plugins/marketplaces/<mp>/plugins/<pkg>/...
+    const after = segs.slice(i + 1).filter((s) => s !== "cache" && s !== "marketplaces");
+    return after[0] ?? "unknown";
+  }
+  const s = segs.lastIndexOf("skills");
+  if (s !== -1 && segs[s + 1]) return segs[s + 1];
+  return "unknown";
+}
+
+function truncate(text, max = COMMAND_PREVIEW_CHARS) {
+  const t = String(text ?? "").replace(/\s+/g, " ").trim();
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+// Pure: extract every command hook from a parsed hooks.json object.
+export function parseEmbeddedHooks(json, sourcePath) {
+  if (!json || typeof json.hooks !== "object" || json.hooks === null) return [];
+  const { host, template, pkg } = classifyHookPath(sourcePath);
+  const out = [];
+  for (const [event, groups] of Object.entries(json.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      const matcher = group?.matcher ?? null;
+      for (const hook of group?.hooks ?? []) {
+        if (hook?.type !== "command" || typeof hook.command !== "string") continue;
+        out.push({
+          id: group?.id ?? `${pkg}:${event}${matcher ? `:${matcher}` : ""}`,
+          package: pkg,
+          host,
+          event,
+          matcher,
+          template,
+          commandPreview: truncate(hook.command),
+          commandLength: hook.command.length,
+          timeout: hook.timeout ?? null,
+          source: sourcePath,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function hookJsonFilesUnder(root, maxDepth = HOOK_SCAN_MAX_DEPTH) {
+  const found = [];
+  if (!existsSync(root)) return found;
+  const stack = [{ dir: root, depth: 0 }];
+  while (stack.length > 0) {
+    const { dir, depth } = stack.pop();
+    let dirents;
+    try {
+      dirents = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const dirent of dirents) {
+      const path = join(dir, dirent.name);
+      if (dirent.isFile() && dirent.name === "hooks.json") {
+        found.push(path);
+        continue;
+      }
+      if (!dirent.isDirectory() && !dirent.isSymbolicLink()) continue;
+      if (SKIP_DIRS.has(dirent.name)) continue;
+      if (depth >= maxDepth) continue;
+      stack.push({ dir: path, depth: depth + 1 });
+    }
+  }
+  return found;
+}
+
+// Inventory across all roots. Deduped by (source-relative) identity so the
+// same package mirrored in cache + marketplaces isn't double-counted.
+export function discoverEmbeddedHooks(roots = defaultHookScanRoots()) {
+  const seen = new Map();
+  for (const root of roots) {
+    for (const file of hookJsonFilesUnder(root)) {
+      let json;
+      try {
+        json = JSON.parse(readFileSync(file, "utf8"));
+      } catch {
+        continue; // a malformed hooks.json must not break the whole scan
+      }
+      for (const entry of parseEmbeddedHooks(json, file)) {
+        const key = `${entry.package}:${entry.host}:${entry.event}:${entry.matcher ?? ""}:${entry.commandPreview}`;
+        if (!seen.has(key)) seen.set(key, entry);
+      }
+    }
+  }
+  return [...seen.values()];
+}
+
+// Compact summary for doctor / surface matrix.
+export function summarizeEmbeddedHooks(entries = discoverEmbeddedHooks()) {
+  const byPackage = {};
+  const byHost = {};
+  let templates = 0;
+  for (const e of entries) {
+    byPackage[e.package] = (byPackage[e.package] ?? 0) + 1;
+    byHost[e.host] = (byHost[e.host] ?? 0) + 1;
+    if (e.template) templates += 1;
+  }
+  return { total: entries.length, active: entries.length - templates, templates, byHost, byPackage };
+}

package/core/surface/discover-hooks.test.mjs

@@ -0,0 +1,63 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseEmbeddedHooks, classifyHookPath, summarizeEmbeddedHooks } from "./discover-hooks.mjs";
+
+const HOOKS_JSON = {
+  description: "demo",
+  hooks: {
+    PreToolUse: [
+      {
+        matcher: "Bash",
+        id: "pre:bash",
+        hooks: [{ type: "command", command: "node dispatch.js", timeout: 30 }],
+      },
+    ],
+    UserPromptSubmit: [
+      { hooks: [{ type: "command", command: "bash remind.sh" }, { type: "other", command: "ignored" }] },
+    ],
+  },
+};
+
+test("parseEmbeddedHooks: extracts command hooks with id/event/matcher, skips non-command", () => {
+  const out = parseEmbeddedHooks(HOOKS_JSON, "/home/.claude/plugins/cache/ecc/ecc/2.0.0/hooks/hooks.json");
+  assert.equal(out.length, 2);
+  const pre = out.find((h) => h.event === "PreToolUse");
+  assert.equal(pre.id, "pre:bash");
+  assert.equal(pre.matcher, "Bash");
+  assert.equal(pre.package, "ecc");
+  assert.equal(pre.host, "claude-code");
+  assert.equal(pre.commandPreview, "node dispatch.js");
+  // synthesized id when none is declared
+  const ups = out.find((h) => h.event === "UserPromptSubmit");
+  assert.equal(ups.id, "ecc:UserPromptSubmit");
+});
+
+test("parseEmbeddedHooks: no hooks key or non-object -> empty", () => {
+  assert.deepEqual(parseEmbeddedHooks({}, "/x/hooks.json"), []);
+  assert.deepEqual(parseEmbeddedHooks(null, "/x/hooks.json"), []);
+});
+
+test("classifyHookPath: host + template + package from path segments", () => {
+  assert.equal(classifyHookPath("/h/.codex/hooks.json").host, "codex");
+  assert.equal(classifyHookPath("/h/.cursor/x/hooks.json").host, "cursor");
+  assert.equal(classifyHookPath("/h/.claude/plugins/cache/ecc/ecc/2.0.0/hooks/hooks.json").host, "claude-code");
+  assert.equal(classifyHookPath("/h/.claude/plugins/cache/ecc/ecc/2.0.0/scaffolds/cursor/hooks.json").template, true);
+  assert.equal(
+    classifyHookPath("/h/.claude/plugins/marketplaces/claude-plugins-official/plugins/hookify/hooks/hooks.json").pkg,
+    "hookify",
+  );
+});
+
+test("summarizeEmbeddedHooks: counts total/active/templates and groups", () => {
+  const entries = [
+    { package: "a", host: "claude-code", template: false },
+    { package: "a", host: "claude-code", template: false },
+    { package: "b", host: "codex", template: true },
+  ];
+  const s = summarizeEmbeddedHooks(entries);
+  assert.equal(s.total, 3);
+  assert.equal(s.active, 2);
+  assert.equal(s.templates, 1);
+  assert.deepEqual(s.byPackage, { a: 2, b: 1 });
+  assert.deepEqual(s.byHost, { "claude-code": 2, codex: 1 });
+});

package/core/surface/discover-surface.test.mjs

@@ -0,0 +1,49 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { discoverCommands, discoverAgents, defaultCommandRoots, defaultAgentRoots } from "../registry/discover.mjs";
+import { homedir } from "node:os";
+
+function fixtureRoot() {
+  return mkdtempSync(join(tmpdir(), "discover-surface-"));
+}
+
+test("discoverCommands: reads a host-native leaf dir directly (basename == segment)", () => {
+  const root = fixtureRoot();
+  const commandsDir = join(root, "commands");
+  mkdirSync(commandsDir, { recursive: true });
+  writeFileSync(join(commandsDir, "deploy.md"), "---\nname: deploy\ndescription: Ship it\n---\n# deploy\n");
+  const found = discoverCommands([commandsDir]);
+  const deploy = found.find((c) => c.id === "deploy");
+  assert.ok(deploy, "leaf-dir command discovered");
+  assert.equal(deploy.type, "command");
+  assert.ok(deploy.route.triggers.includes("/deploy"));
+});
+
+test("discoverAgents: reads a host-native leaf dir directly", () => {
+  const root = fixtureRoot();
+  const agentsDir = join(root, "agents");
+  mkdirSync(agentsDir, { recursive: true });
+  writeFileSync(join(agentsDir, "reviewer.md"), "---\nname: reviewer\ndescription: Reviews code\n---\n");
+  const found = discoverAgents([agentsDir]);
+  assert.ok(found.find((a) => a.id === "reviewer" && a.type === "agent"));
+});
+
+test("discoverCommands: still finds a segment dir nested under a plugin root", () => {
+  const root = fixtureRoot();
+  const nested = join(root, "someplugin", "commands");
+  mkdirSync(nested, { recursive: true });
+  writeFileSync(join(nested, "build.md"), "---\nname: build\ndescription: Build it\n---\n");
+  const found = discoverCommands([root]);
+  assert.ok(found.find((c) => c.id === "build"), "nested segment-walk still works");
+});
+
+test("defaultCommandRoots/defaultAgentRoots include host-native claude dirs", () => {
+  const cmd = defaultCommandRoots();
+  const ag = defaultAgentRoots();
+  assert.ok(cmd.some((p) => p.endsWith(join(".claude", "commands"))));
+  assert.ok(cmd.some((p) => p === join(homedir(), ".claude", "commands")));
+  assert.ok(ag.some((p) => p.endsWith(join(".claude", "agents"))));
+});