portawhip 0.1.0

package/scripts/bundles.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Bundle selector - opt-in only, never forced (agreed 2026-07-05). foundry =
+// whipforaweeb's recommended core (user may opt out); roles = whipforaweeb's
+// role-based add-ons (tick zero, one, or many). Selecting a bundle just
+// changes which recipe files feed BOTH install (scripts/load.mjs) and
+// routing (router-cli/mcp-server/universal-hook) - the same list, so nothing
+// can end up "installed but never routed" (see recipes/foundry.yaml's header
+// for the predecessor-project gripe this avoids).
+
+import { resolve } from "node:path";
+import {
+  listCatalog,
+  readActiveSelection,
+  resolveBundlePaths,
+  resolveRecipePaths,
+  writeActiveSelection,
+} from "../core/state/bundle-state.mjs";
+import { mergeRawEntries } from "../core/registry/registry.mjs";
+import { detectHosts } from "./hosts.mjs";
+import { installEntries } from "./load.mjs";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i].startsWith("--")) {
+      const key = argv[i].slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : true;
+      args[key] = value;
+      if (value !== true) i += 1;
+    }
+  }
+  return args;
+}
+
+function cmdList(root) {
+  const { foundry, roles } = listCatalog(root);
+  console.log("== foundry (recommended core; opt-out anytime with `select --none`) ==");
+  console.log(
+    foundry
+      ? `${foundry.id}: ${foundry.description ?? "(no description)"} - entries: ${foundry.entryIds.join(", ")}`
+      : "(none defined yet - recipes/foundry.yaml missing)",
+  );
+  console.log("\n== roles (opt-in, pick any number) ==");
+  if (roles.length === 0) console.log("(none defined yet - recipes/roles/*.yaml missing)");
+  for (const role of roles) {
+    console.log(`${role.id}: ${role.description ?? "(no description)"} - entries: ${role.entryIds.join(", ")}`);
+  }
+}
+
+function cmdStatus(root) {
+  const selection = readActiveSelection(root);
+  const paths = resolveRecipePaths(root, selection);
+  console.log(`foundry: ${selection.foundry ? "on" : "off"}`);
+  console.log(`roles: ${selection.roles.length ? selection.roles.join(", ") : "(none)"}`);
+  console.log("\nresolved recipe files (precedence: foundry -> roles -> this project's recipe.yaml):");
+  for (const p of paths) console.log(` - ${p}`);
+  if (paths.length === 0) console.log(" (none - nothing to route or install)");
+}
+
+// select does not just record intent — it installs the newly selected
+// bundle(s) right away (agreed 2026-07-05: "select bundle นี่คือต้องโหลด
+// tools ให้เลย"). Scoped to resolveBundlePaths (foundry + selected roles
+// only), not the project's own recipe.yaml, so re-selecting doesn't
+// reinstall everything that was already there before bundles existed.
+// Installs are idempotent (mise/add-mcp/asm already re-verified this in
+// Step 1), so re-running select with the same selection is a safe no-op.
+async function cmdSelect(root, args) {
+  if (args.none) {
+    writeActiveSelection(root, { foundry: false, roles: [] });
+    console.log("selection cleared - back to just this project's recipe.yaml.");
+    return;
+  }
+  const selection = {
+    foundry: Boolean(args.foundry),
+    roles:
+      typeof args.role === "string"
+        ? args.role
+            .split(",")
+            .map((r) => r.trim())
+            .filter(Boolean)
+        : [],
+  };
+  writeActiveSelection(root, selection);
+  console.log(`selection saved: foundry=${selection.foundry}, roles=${selection.roles.join(",") || "(none)"}`);
+
+  const bundlePaths = resolveBundlePaths(root, selection);
+  if (bundlePaths.length === 0) {
+    console.log("\nnothing to install (no matching recipes/foundry.yaml or recipes/roles/*.yaml found).");
+    cmdStatus(root);
+    return;
+  }
+
+  const scope = args.scope === "project" ? "project" : "global";
+  console.log(`\n== installing selected bundle(s) (cli scope: ${scope}) ==`);
+  const entries = mergeRawEntries(bundlePaths);
+  const hosts = await detectHosts();
+  console.log(`detected MCP hosts:   ${hosts.mcpHosts.join(", ") || "(none)"}`);
+  console.log(`detected skill hosts: ${hosts.skillHosts.join(", ") || "(none)"}`);
+  const results = installEntries(entries, hosts, scope);
+
+  console.log("\n== install summary ==");
+  for (const r of results) console.log(`${r.ok ? "OK  " : "FAIL"} ${r.id}`);
+
+  console.log("");
+  cmdStatus(root);
+}
+
+async function main() {
+  const [, , command, ...rest] = process.argv;
+  const args = parseArgs(rest);
+  const root = resolve(".");
+
+  if (command === "list") return cmdList(root);
+  if (command === "status") return cmdStatus(root);
+  if (command === "select") return cmdSelect(root, args);
+
+  console.error(
+    "usage: bundles.mjs <list|status|select [--foundry] [--role a,b] [--scope project|global] | select --none>",
+  );
+  process.exitCode = 1;
+}
+
+import { pathToFileURL } from "node:url";
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/doctor.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Unified status across 3 backends — proves "load however, verify one way."
+// No re-implemented health logic: each check just calls that backend's
+// own list/audit command and reports pass/fail.
+
+import spawnSync from "cross-spawn";
+import { collectSurfaceMatrix } from "../core/surface/surface-matrix.mjs";
+
+function parseArgs(argv) {
+  return { json: argv.includes("--json"), heavy: argv.includes("--heavy") };
+}
+
+function cellText(cell) {
+  const count = cell.count != null ? `(${cell.count})` : "";
+  return `${cell.status}${count}`;
+}
+
+function capture(cmd, args) {
+  const result = spawnSync.sync(cmd, args, { encoding: "utf8" });
+  return { ok: result.status === 0, output: (result.stdout || "") + (result.stderr || "") };
+}
+
+function checkMcp() {
+  const r = capture("npx", ["--yes", "add-mcp", "list", "-g"]);
+  const found = r.output.includes("context7");
+  return { label: "context7 (mcp via add-mcp)", ok: r.ok && found };
+}
+
+function checkCli() {
+  const r = capture("mise", ["ls", "ripgrep"]);
+  const found = r.output.includes("ripgrep");
+  return { label: "ripgrep (cli via mise)", ok: r.ok && found };
+}
+
+function checkSkill() {
+  const r = capture("npx", ["--yes", "agent-skill-manager", "inspect", "pdf", "--json"]);
+  return { label: "pdf (skill via asm)", ok: r.ok };
+}
+
+// Router/hooks/connectors added later than the 3 checks above (Step 1) —
+// this file went stale until this pass. Same pattern: shell out to each
+// piece's own authoritative command, don't re-implement its logic here.
+function checkRouter() {
+  const r = capture(process.execPath, ["core/router/router-cli.mjs", "list"]);
+  let entries = [];
+  try {
+    entries = JSON.parse(r.output);
+  } catch {
+    entries = [];
+  }
+  return { label: "router registry (recipe + live discovery)", ok: r.ok && Array.isArray(entries) && entries.length > 0 };
+}
+
+// Both scopes, not just global — collapsing to one bool at global scope hid
+// per-host detail that link-hooks.mjs/link-connectors.mjs status already
+// print (path + linked/missing per host). Doctor's job is to surface that,
+// not re-summarize it into a single OK/FAIL.
+function checkHooks(scope) {
+  const r = capture(process.execPath, ["scripts/link/link-hooks.mjs", "status", "--scope", scope]);
+  return { label: `native hooks (link-hooks.mjs, ${scope} scope)`, ok: r.ok, detail: r.output.trim() };
+}
+
+function checkConnectors(scope) {
+  const r = capture(process.execPath, ["scripts/link/link-connectors.mjs", "status", "--scope", scope]);
+  return { label: `instruction connectors (link-connectors.mjs, ${scope} scope)`, ok: r.ok, detail: r.output.trim() };
+}
+
+const { json, heavy } = parseArgs(process.argv.slice(2));
+
+const checks = [
+  checkMcp(),
+  checkCli(),
+  checkSkill(),
+  checkRouter(),
+  checkHooks("project"),
+  checkHooks("global"),
+  checkConnectors("project"),
+  checkConnectors("global"),
+];
+
+// Surface coverage matrix (Phase S0): live-probed read/write lane status per
+// portable surface. Light by default so `doctor` stays fast; `--heavy` runs
+// the full mcp/skill discovery counts.
+const matrix = await collectSurfaceMatrix({ heavy });
+
+if (json) {
+  const ok = checks.every((c) => c.ok);
+  console.log(JSON.stringify({ status: ok ? "ok" : "fail", checks, matrix }, null, 2));
+  process.exitCode = ok ? 0 : 1;
+  process.exit();
+}
+
+console.log("\n== doctor: unified status ==");
+for (const c of checks) console.log(`${c.ok ? "OK  " : "FAIL"} ${c.label}`);
+
+console.log("\n== per-host detail (source of truth for what's loaded where) ==");
+for (const c of checks) {
+  if (!c.detail) continue;
+  console.log(`\n--- ${c.label} ---`);
+  console.log(c.detail);
+}
+
+console.log("\n== surface coverage matrix (read=import, write=fan-out) ==");
+for (const row of matrix.rows) {
+  console.log(`${row.label.padEnd(34)} read: ${cellText(row.read).padEnd(20)} write: ${cellText(row.write)}`);
+}
+if (matrix.summary.attention.length) {
+  console.log(`\nAttention (no lane / backend missing): ${matrix.summary.attention.join(", ")}`);
+}
+
+console.log(
+  "\nNote: add-mcp / agent-skill-manager entries are managed by those tools, not by\n" +
+    "this harness. `doctor` reports on them but `scripts/uninstall-all.mjs` cannot\n" +
+    "remove them — use each tool's own uninstall if you want those gone too.",
+);
+
+process.exitCode = checks.every((c) => c.ok) ? 0 : 1;

package/scripts/embedded-hooks.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// View the embedded-hook inventory (Phase S3, mode B). Read-only: lists hooks
+// bundled inside installed skills/plugins so a human can see what runs on
+// lifecycle events. Does NOT link or execute anything.
+
+import { discoverEmbeddedHooks, summarizeEmbeddedHooks } from "../core/surface/discover-hooks.mjs";
+
+function main() {
+  const json = process.argv.includes("--json");
+  const entries = discoverEmbeddedHooks();
+  const summary = summarizeEmbeddedHooks(entries);
+  if (json) {
+    console.log(JSON.stringify({ summary, entries }, null, 2));
+    return;
+  }
+  console.log(`embedded hooks: ${summary.total} (active ${summary.active}, templates ${summary.templates})`);
+  console.log(`by host: ${JSON.stringify(summary.byHost)}`);
+  console.log(`by package: ${JSON.stringify(summary.byPackage)}`);
+  console.log("\n(inventory only — these are NOT linked; run each package's own installer to activate)\n");
+  for (const e of entries) {
+    const tag = e.template ? " [template]" : "";
+    console.log(`${e.host} · ${e.package} · ${e.event}${e.matcher ? `/${e.matcher}` : ""}${tag}`);
+    console.log(`   ${e.commandPreview}`);
+  }
+}
+
+main();

package/scripts/hosts.mjs

@@ -0,0 +1,60 @@
+// Single source of truth for "which agent hosts exist on this machine."
+// Both load.mjs and doctor.mjs import this — no host list is hardcoded
+// in either of them.
+//
+// add-mcp's detectGlobalAgents() does real filesystem detection (checks
+// for each agent's actual home config dir), so this list grows/shrinks
+// automatically as the user installs/removes agent CLIs — no manual
+// catalog maintenance.
+
+import { detectGlobalAgents } from "add-mcp";
+import spawnSync from "cross-spawn";
+import { detectExtraHosts } from "../core/surface/extra-hosts.mjs";
+
+// add-mcp and asm are independent projects that each picked their own id
+// strings for the same real-world tool. This table is unavoidable glue
+// data (not decision logic) translating one id space to the other; it
+// only needs an entry for hosts that carry skill content, so it will
+// always be shorter than add-mcp's full agent list.
+const ADD_MCP_TO_ASM = {
+  "claude-code": "claude",
+  codex: "codex",
+  cursor: "cursor",
+  "gemini-cli": "gemini",
+  opencode: "opencode",
+  windsurf: "windsurf",
+  zed: "zed",
+  antigravity: "antigravity",
+  cline: "cline",
+  "cline-cli": "cline",
+  "github-copilot-cli": "copilot",
+};
+
+function asmEnabledProviders() {
+  const result = spawnSync.sync("npx", ["--yes", "agent-skill-manager", "config", "show"], {
+    encoding: "utf8",
+  });
+  if (result.status !== 0) return [];
+  try {
+    const config = JSON.parse(result.stdout);
+    return config.providers.filter((p) => p.enabled).map((p) => p.name);
+  } catch {
+    return [];
+  }
+}
+
+export async function detectHosts() {
+  const mcpHosts = await detectGlobalAgents(); // e.g. ["claude-code","codex","cursor",...]
+  const asmProviders = asmEnabledProviders();
+  const skillHosts = mcpHosts
+    .map((id) => ADD_MCP_TO_ASM[id])
+    .filter((name) => name && asmProviders.includes(name));
+
+  // Hosts add-mcp doesn't catalogue yet (Pi, Amp, …), detected by their own
+  // config dir. Kept in a separate field so add-mcp's MCP-linking path is
+  // never handed a host it doesn't know; the instruction/command lanes that
+  // opt in read this explicitly.
+  const extraHosts = detectExtraHosts();
+
+  return { mcpHosts, skillHosts, extraHosts };
+}

package/scripts/link/link-connectors.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// Cross-host connector linker for harness-router.
+//
+// This does not install MCP servers itself; add-mcp remains the delegated
+// installer. The script verifies the MCP link and upserts the small instruction
+// connector block into every known host instruction surface for a selected
+// scope (project by default, global when explicitly requested).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { listInstalledServers } from "add-mcp";
+import { detectHosts } from "../hosts.mjs";
+import { blockForVariant, removeBlock, upsertBlock } from "../../adapters/instructions/generate.mjs";
+import { CONNECTOR_TARGETS, targetsForHost } from "../../core/surface/connector-targets.mjs";
+
+const VALID_COMMANDS = new Set(["status", "install", "remove"]);
+const VALID_SCOPES = new Set(["project", "global"]);
+
+function parseArgs(argv) {
+  const args = { command: argv[2] ?? "status", scope: "project", json: false };
+  for (let i = 3; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--scope") {
+      args.scope = argv[i + 1];
+      i += 1;
+    } else if (arg === "--all-scopes") {
+      args.scope = "all";
+    } else if (arg === "--json") {
+      args.json = true;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  if (!VALID_COMMANDS.has(args.command)) {
+    throw new Error(`usage: link-connectors.mjs <status|install|remove> [--scope project|global|--all-scopes]`);
+  }
+  if (args.scope !== "all" && !VALID_SCOPES.has(args.scope)) {
+    throw new Error(`invalid scope "${args.scope}"`);
+  }
+  return args;
+}
+
+function hasHarnessBlock(path) {
+  if (!existsSync(path)) return false;
+  const content = readFileSync(path, "utf8");
+  return content.includes("<!-- harness-router:start -->") && content.includes("<!-- harness-router:end -->");
+}
+
+function normalizeTarget(target) {
+  return { ...target, path: resolve(target.path) };
+}
+
+function targetsForScope(hostId, scope) {
+  if (scope === "all") {
+    return CONNECTOR_TARGETS[hostId]?.instructionTargets.map(normalizeTarget) ?? [];
+  }
+  return targetsForHost(hostId, { scope }).map(normalizeTarget);
+}
+
+function rowHasHarnessRouter(row) {
+  return row.servers.some(
+    (server) => server.name === "harness-router" || server.serverName === "harness-router",
+  );
+}
+
+async function mcpLinkedByHost(hostIds) {
+  const localRows = await listInstalledServers({ global: false, agents: hostIds, cwd: process.cwd() });
+  const globalRows = await listInstalledServers({ global: true, agents: hostIds, cwd: process.cwd() });
+  const linked = new Map(hostIds.map((hostId) => [hostId, false]));
+  for (const row of [...localRows, ...globalRows]) {
+    linked.set(row.agentType, linked.get(row.agentType) || rowHasHarnessRouter(row));
+  }
+  return linked;
+}
+
+// A dedicated, harness-owned rule file (cursor .mdc, windsurf .md) carries
+// frontmatter BEFORE the marker block, so marker-upsert is wrong for it:
+// upsertBlock preserves the pre-marker preamble AND re-adds the block's own
+// preamble, duplicating the frontmatter on every re-run. Own the whole file
+// instead — install writes it verbatim (idempotent), remove deletes it (no
+// orphan always-on rule left behind on uninstall).
+function applyOwnedTarget(command, target) {
+  if (command === "remove") {
+    if (!existsSync(target.path)) return { changed: false, linked: false };
+    rmSync(target.path);
+    return { changed: true, linked: false };
+  }
+  mkdirSync(dirname(target.path), { recursive: true });
+  const next = `${blockForVariant(target.variant)}\n`;
+  const current = existsSync(target.path) ? readFileSync(target.path, "utf8") : null;
+  const changed = current !== next;
+  if (changed) writeFileSync(target.path, next);
+  return { changed, linked: true };
+}
+
+export function applyTarget(command, target) {
+  if (command === "status") return { changed: false, linked: hasHarnessBlock(target.path) };
+  if (target.owned) return applyOwnedTarget(command, target);
+  mkdirSync(dirname(target.path), { recursive: true });
+  const changed =
+    command === "install" ? upsertBlock(target.path, blockForVariant(target.variant)) : removeBlock(target.path);
+  return { changed, linked: hasHarnessBlock(target.path) };
+}
+
+export async function collectConnectorLinks({ command = "status", scope = "project" } = {}) {
+  const hosts = await detectHosts();
+  const hostIds = hosts.mcpHosts;
+  const mcpLinks = await mcpLinkedByHost(hostIds);
+  const rows = [];
+
+  for (const hostId of hostIds) {
+    const targets = targetsForScope(hostId, scope);
+    const mcpLinked = Boolean(mcpLinks.get(hostId));
+    const mcpStatus = mcpLinked ? "linked" : "missing";
+    if (targets.length === 0) {
+      rows.push({
+        type: "connector",
+        hostId,
+        scope,
+        mcpStatus,
+        instructionStatus: "mcp-only",
+        path: null,
+        supported: true,
+      });
+      continue;
+    }
+    for (const target of targets) {
+      const result = applyTarget(command, target);
+      const instructionStatus =
+        command === "status" ? (result.linked ? "linked" : "missing") : result.changed ? "changed" : "no-op";
+      rows.push({
+        type: "connector",
+        hostId,
+        scope,
+        mcpStatus,
+        instructionStatus,
+        path: target.path,
+        supported: true,
+      });
+    }
+  }
+
+  // Extra hosts add-mcp doesn't catalogue (Pi, Amp, …), present on this
+  // machine: instruction linking only. mcpStatus is "n/a" — we never hand
+  // these to add-mcp's MCP linker, which doesn't know them.
+  for (const hostId of hosts.extraHosts ?? []) {
+    const targets = targetsForScope(hostId, scope);
+    for (const target of targets) {
+      const result = applyTarget(command, target);
+      const instructionStatus =
+        command === "status" ? (result.linked ? "linked" : "missing") : result.changed ? "changed" : "no-op";
+      rows.push({ type: "connector", hostId, scope, mcpStatus: "n/a", instructionStatus, path: target.path, supported: true });
+    }
+  }
+
+  return { command, scope, hostIds, extraHostIds: hosts.extraHosts ?? [], rows };
+}
+
+async function main() {
+  const { command, scope, json } = parseArgs(process.argv);
+  const result = await collectConnectorLinks({ command, scope });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`connector command: ${command}`);
+  console.log(`scope: ${scope}`);
+  console.log(`detected MCP hosts: ${result.hostIds.join(", ") || "(none)"}`);
+  console.log("\n== connector links ==");
+
+  for (const row of result.rows) {
+    const mcpStatus = `mcp:${row.mcpStatus}`;
+    if (row.instructionStatus === "mcp-only") {
+      console.log(`${row.hostId}: ${mcpStatus}; instruction:mcp-only`);
+      continue;
+    }
+    console.log(`${row.hostId}: ${mcpStatus}; instruction:${row.instructionStatus}; ${row.path}`);
+  }
+}
+
+import { pathToFileURL } from "node:url";
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/link/link-connectors.test.mjs

@@ -0,0 +1,111 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { applyTarget } from "./link-connectors.mjs";
+
+test("link-connectors: install writes the harness-router marker block", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-connectors-"));
+  const path = join(dir, "AGENTS.md");
+  try {
+    const result = applyTarget("install", { path, variant: "generic" });
+    assert.equal(result.changed, true);
+    assert.equal(result.linked, true);
+    const content = readFileSync(path, "utf8");
+    assert.ok(content.includes("harness-router:start"));
+    assert.ok(content.includes("route(task summary)"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("link-connectors: install is idempotent", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-connectors-"));
+  const path = join(dir, "AGENTS.md");
+  try {
+    applyTarget("install", { path, variant: "generic" });
+    const before = readFileSync(path, "utf8");
+    const result = applyTarget("install", { path, variant: "generic" });
+    assert.equal(result.changed, false);
+    assert.equal(readFileSync(path, "utf8"), before);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("link-connectors: status reports linked/missing without mutating the file", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-connectors-"));
+  const path = join(dir, "AGENTS.md");
+  try {
+    assert.equal(applyTarget("status", { path, variant: "generic" }).linked, false);
+    applyTarget("install", { path, variant: "generic" });
+    assert.equal(applyTarget("status", { path, variant: "generic" }).linked, true);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("link-connectors: remove strips the block and preserves surrounding content", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-connectors-"));
+  const path = join(dir, "AGENTS.md");
+  try {
+    writeFileSync(path, "# My project\n\nSome existing notes.\n");
+    applyTarget("install", { path, variant: "generic" });
+    applyTarget("remove", { path, variant: "generic" });
+    const content = readFileSync(path, "utf8");
+    assert.ok(!content.includes("harness-router:start"));
+    assert.ok(content.includes("Some existing notes."));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// Owned dedicated rule files (cursor .mdc, windsurf .md) carry frontmatter
+// BEFORE the marker block. Regression guard for the bug where marker-upsert
+// duplicated that frontmatter on every re-run (see applyOwnedTarget).
+test("link-connectors: owned cursor-rule install is idempotent (no duplicate frontmatter)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-connectors-"));
+  const path = join(dir, "harness-router.mdc");
+  try {
+    const target = { path, variant: "cursor-rule", owned: true };
+    assert.equal(applyTarget("install", target).changed, true);
+    assert.equal(applyTarget("install", target).changed, false);
+    applyTarget("install", target);
+    const content = readFileSync(path, "utf8");
+    assert.equal((content.match(/alwaysApply: true/g) || []).length, 1);
+    assert.ok(content.includes("harness-router:start"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("link-connectors: owned remove deletes the file, leaving no orphan always-on rule", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-connectors-"));
+  const path = join(dir, "harness-router.mdc");
+  try {
+    const target = { path, variant: "cursor-rule", owned: true };
+    applyTarget("install", target);
+    assert.ok(existsSync(path));
+    const result = applyTarget("remove", target);
+    assert.equal(result.changed, true);
+    assert.equal(existsSync(path), false);
+    // remove on an already-absent owned file is a clean no-op
+    assert.equal(applyTarget("remove", target).changed, false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("link-connectors: owned windsurf-rule writes always_on frontmatter as the first bytes", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-connectors-"));
+  const path = join(dir, "harness-router.md");
+  try {
+    applyTarget("install", { path, variant: "windsurf-rule", owned: true });
+    const content = readFileSync(path, "utf8");
+    assert.ok(content.startsWith("---\ntrigger: always_on\n---"));
+    assert.ok(content.includes("route(task summary)"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});