portawhip 0.1.0

package/scripts/link/link-hooks.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+// Sync native lifecycle hooks across agent hosts from hooks.manifest.yaml.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { detectHosts } from "../hosts.mjs";
+import { HOOK_TARGETS, LOGICAL_HOOKS, LOGICAL_EVENT_TO_MANIFEST, hookTargetForHost } from "../../core/surface/hook-targets.mjs";
+
+const VALID_COMMANDS = new Set(["status", "install", "remove"]);
+const VALID_SCOPES = new Set(["project", "global"]);
+const RUNNER = resolve("adapters", "hooks", "universal-hook.mjs");
+const MARKER = "universal-hook.mjs";
+
+// HARNESS_ROUTER_STUB_HOME override exists only so tests can point this at a
+// tmp dir instead of touching the real home directory.
+const STUB_HOME = process.env.HARNESS_ROUTER_STUB_HOME || homedir();
+const STUB_PATH = resolve(STUB_HOME, ".harness-router", "hook-stub.mjs");
+
+function ensureStub() {
+  const source = readFileSync(resolve("adapters", "hooks", "hook-stub.mjs"), "utf8");
+  mkdirSync(dirname(STUB_PATH), { recursive: true });
+  const current = existsSync(STUB_PATH) ? readFileSync(STUB_PATH, "utf8") : null;
+  if (current !== source) writeFileSync(STUB_PATH, source);
+}
+
+function parseArgs(argv) {
+  const args = { command: argv[2] ?? "status", scope: "project", json: false };
+  for (let i = 3; i < argv.length; i += 1) {
+    if (argv[i] === "--scope") {
+      args.scope = argv[i + 1];
+      i += 1;
+    } else if (argv[i] === "--json") {
+      args.json = true;
+    } else {
+      throw new Error(`unknown argument: ${argv[i]}`);
+    }
+  }
+  if (!VALID_COMMANDS.has(args.command)) {
+    throw new Error("usage: link-hooks.mjs <status|install|remove> [--scope project|global]");
+  }
+  if (!VALID_SCOPES.has(args.scope)) throw new Error(`invalid scope "${args.scope}"`);
+  return args;
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return {};
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function commandFor(hostId, logicalEvent, nativeEvent) {
+  return `"${process.execPath}" "${STUB_PATH}" --target "${RUNNER}" --host ${hostId} --event ${logicalEvent} --nativeEvent ${nativeEvent}`;
+}
+
+function hookObject(hostId, logicalEvent, nativeEvent, timeout) {
+  return {
+    type: "command",
+    command: commandFor(hostId, logicalEvent, nativeEvent),
+    timeout,
+    statusMessage: `harness-router ${logicalEvent}`,
+  };
+}
+
+function eventGroup(hostId, logicalEvent, nativeEvent, format) {
+  const base = {
+    matcher: logicalEvent === "post_tool" ? "*" : undefined,
+    hooks: [hookObject(hostId, logicalEvent, nativeEvent, format === "gemini-settings-json" ? 5000 : 30)],
+  };
+  if (format === "gemini-settings-json") {
+    base.hooks[0].name = `harness-router-${logicalEvent}`;
+    const manifestKey = LOGICAL_EVENT_TO_MANIFEST[logicalEvent];
+    if (manifestKey) base.hooks[0].description = LOGICAL_HOOKS[manifestKey].description;
+    base.sequential = false;
+  }
+  return Object.fromEntries(Object.entries(base).filter(([, value]) => value !== undefined));
+}
+
+function hasHook(config, nativeEvent) {
+  return (config.hooks?.[nativeEvent] ?? []).some((group) =>
+    (group.hooks ?? []).some((hook) => typeof hook.command === "string" && hook.command.includes(MARKER)),
+  );
+}
+
+function removeHook(config, nativeEvent) {
+  if (!config.hooks?.[nativeEvent]) return false;
+  const before = JSON.stringify(config.hooks[nativeEvent]);
+  config.hooks[nativeEvent] = config.hooks[nativeEvent]
+    .map((group) => ({
+      ...group,
+      hooks: (group.hooks ?? []).filter(
+        (hook) => !(typeof hook.command === "string" && hook.command.includes(MARKER)),
+      ),
+    }))
+    .filter((group) => (group.hooks ?? []).length > 0);
+  if (config.hooks[nativeEvent].length === 0) delete config.hooks[nativeEvent];
+  return JSON.stringify(config.hooks[nativeEvent] ?? []) !== before;
+}
+
+export function installJsonHooks(hostId, target) {
+  ensureStub();
+  const config = readJson(target.path);
+  config.hooks = config.hooks ?? {};
+  let changed = false;
+
+  for (const [logicalEvent, nativeEvent] of Object.entries(target.events)) {
+    if (!nativeEvent) continue;
+    if (hasHook(config, nativeEvent)) continue;
+    config.hooks[nativeEvent] = config.hooks[nativeEvent] ?? [];
+    config.hooks[nativeEvent].push(eventGroup(hostId, logicalEvent, nativeEvent, target.format));
+    changed = true;
+  }
+
+  if (changed) writeJson(target.path, config);
+  return changed;
+}
+
+export function removeJsonHooks(target) {
+  if (!existsSync(target.path)) return false;
+  const config = readJson(target.path);
+  let changed = false;
+  for (const nativeEvent of Object.values(target.events)) {
+    if (nativeEvent) changed = removeHook(config, nativeEvent) || changed;
+  }
+  if (changed) writeJson(target.path, config);
+  return changed;
+}
+
+export function statusJsonHooks(target) {
+  if (!existsSync(target.path)) return { linked: false, details: [] };
+  const config = readJson(target.path);
+  const details = Object.entries(target.events)
+    .filter(([, nativeEvent]) => nativeEvent)
+    .map(([logicalEvent, nativeEvent]) => `${logicalEvent}:${hasHook(config, nativeEvent) ? "linked" : "missing"}`);
+  return { linked: details.length > 0 && details.every((item) => item.endsWith(":linked")), details };
+}
+
+function opencodePluginSource() {
+  const runner = RUNNER.replace(/\\/g, "\\\\");
+  return `// Generated by portable-harness-v2. Do not hand-edit unless you also update scripts/link-hooks.mjs.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+function run(event, payload) {
+  if (!existsSync("${runner}")) return; // harness repo deleted - silent no-op, not an error
+  spawnSync(process.execPath, ["${runner}", "--host", "opencode", "--event", event, "--nativeEvent", event], {
+    input: JSON.stringify(payload ?? {}),
+    encoding: "utf8",
+  });
+}
+
+export const HarnessRouterPlugin = async () => ({
+  "tool.execute.after": async (input, output) => {
+    run("post_tool", {
+      tool_name: input?.tool,
+      tool_input: output?.args,
+      session_id: input?.sessionID ?? null,
+    });
+  },
+});
+`;
+}
+
+function applyTarget(command, hostId, target) {
+  if (target.kind === "plugin-file") {
+    if (command === "status") return { action: existsSync(target.path) ? "linked" : "missing" };
+    if (command === "remove") {
+      return { action: existsSync(target.path) ? "manual-remove" : "no-op" };
+    }
+    mkdirSync(dirname(target.path), { recursive: true });
+    const next = opencodePluginSource();
+    const changed = !existsSync(target.path) || readFileSync(target.path, "utf8") !== next;
+    if (changed) writeFileSync(target.path, next);
+    return { action: changed ? "changed" : "no-op" };
+  }
+
+  if (command === "status") {
+    const status = statusJsonHooks(target);
+    return { action: status.linked ? "linked" : "missing", details: status.details };
+  }
+  const changed = command === "install" ? installJsonHooks(hostId, target) : removeJsonHooks(target);
+  return { action: changed ? "changed" : "no-op" };
+}
+
+export async function collectHookLinks({ command = "status", scope = "project" } = {}) {
+  const hosts = await detectHosts();
+  const hostIds = hosts.mcpHosts;
+  const rows = [];
+
+  for (const hostId of hostIds) {
+    const target = hookTargetForHost(hostId, { scope });
+    if (!target) {
+      rows.push({
+        type: "hook",
+        hostId,
+        scope,
+        supported: false,
+        action: "unsupported",
+        status: "unsupported",
+        path: null,
+        details: [],
+        note: null,
+      });
+      continue;
+    }
+    const result = applyTarget(command, hostId, target);
+    rows.push({
+      type: "hook",
+      hostId,
+      scope,
+      supported: true,
+      action: result.action,
+      status: result.action,
+      path: resolve(target.path),
+      details: result.details ?? [],
+      note: target.note ?? null,
+    });
+  }
+
+  return { command, scope, hostIds, rows };
+}
+
+async function main() {
+  const { command, scope, json } = parseArgs(process.argv);
+  const result = await collectHookLinks({ command, scope });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`hook command: ${command}`);
+  console.log(`scope: ${scope}`);
+  console.log(`detected MCP hosts: ${result.hostIds.join(", ") || "(none)"}`);
+  console.log("\n== hook links ==");
+
+  for (const row of result.rows) {
+    if (!row.supported) {
+      console.log(`${row.hostId}: hooks:unsupported`);
+      continue;
+    }
+    const detail = row.details.length ? ` (${row.details.join(", ")})` : "";
+    const note = row.note ? `; ${row.note}` : "";
+    console.log(`${row.hostId}: hooks:${row.action}; ${row.path}${detail}${note}`);
+  }
+}
+
+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-hooks.test.mjs

@@ -0,0 +1,112 @@
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+// Must be set before link-hooks.mjs is imported (STUB_HOME is read once at
+// module load) so ensureStub() never touches the real home directory.
+const stubHome = mkdtempSync(join(tmpdir(), "harness-stub-home-"));
+process.env.HARNESS_ROUTER_STUB_HOME = stubHome;
+after(() => rmSync(stubHome, { recursive: true, force: true }));
+
+const { installJsonHooks, removeJsonHooks, statusJsonHooks } = await import("./link-hooks.mjs");
+
+function fakeTarget(path, overrides = {}) {
+  return {
+    path,
+    events: { user_prompt: "UserPromptSubmit", post_tool: "PostToolUse" },
+    format: "claude-code",
+    ...overrides,
+  };
+}
+
+test("link-hooks: install writes a hook containing the universal-hook marker", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-hooks-"));
+  const path = join(dir, "settings.json");
+  try {
+    const target = fakeTarget(path);
+    const changed = installJsonHooks("test-host", target);
+    assert.equal(changed, true);
+    const config = JSON.parse(readFileSync(path, "utf8"));
+    assert.ok(config.hooks.UserPromptSubmit[0].hooks[0].command.includes("universal-hook.mjs"));
+    assert.ok(config.hooks.PostToolUse[0].hooks[0].command.includes("universal-hook.mjs"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("link-hooks: install routes the command through the outside-repo stub, not the repo file directly", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-hooks-"));
+  const path = join(dir, "settings.json");
+  try {
+    const target = fakeTarget(path);
+    installJsonHooks("test-host", target);
+    const config = JSON.parse(readFileSync(path, "utf8"));
+    const command = config.hooks.UserPromptSubmit[0].hooks[0].command;
+
+    const stubPath = resolve(stubHome, ".harness-router", "hook-stub.mjs");
+    assert.ok(command.includes(stubPath), "command should invoke the stub path");
+    assert.ok(command.includes("--target"), "command should pass the real runner via --target");
+
+    const stubContent = readFileSync(stubPath, "utf8");
+    const sourceContent = readFileSync(resolve("adapters", "hooks", "hook-stub.mjs"), "utf8");
+    assert.equal(stubContent, sourceContent);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("link-hooks: install is idempotent (second run is a no-op)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-hooks-"));
+  const path = join(dir, "settings.json");
+  try {
+    const target = fakeTarget(path);
+    installJsonHooks("test-host", target);
+    const before = readFileSync(path, "utf8");
+    const changedAgain = installJsonHooks("test-host", target);
+    assert.equal(changedAgain, false);
+    assert.equal(readFileSync(path, "utf8"), before);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("link-hooks: status reflects install/remove transitions", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-hooks-"));
+  const path = join(dir, "settings.json");
+  try {
+    const target = fakeTarget(path);
+    assert.equal(statusJsonHooks(target).linked, false);
+    installJsonHooks("test-host", target);
+    assert.equal(statusJsonHooks(target).linked, true);
+    removeJsonHooks(target);
+    assert.equal(statusJsonHooks(target).linked, false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("link-hooks: remove only strips our hook, leaves unrelated hooks in the same event untouched", () => {
+  const dir = mkdtempSync(join(tmpdir(), "harness-hooks-"));
+  const path = join(dir, "settings.json");
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify({
+        hooks: {
+          UserPromptSubmit: [{ hooks: [{ type: "command", command: "some-other-hook.mjs" }] }],
+        },
+      }),
+    );
+    const target = fakeTarget(path);
+    installJsonHooks("test-host", target);
+    removeJsonHooks(target);
+    const config = JSON.parse(readFileSync(path, "utf8"));
+    const commands = config.hooks.UserPromptSubmit.flatMap((g) => g.hooks.map((h) => h.command));
+    assert.deepEqual(commands, ["some-other-hook.mjs"]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/scripts/link/link-surfaces.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// Managed-copy fan-out for slash commands + subagent defs (Phase S2 write).
+//
+// mise/asm don't install these surfaces, so this lane copies each canonical
+// command/agent markdown file into every markdown-compatible host's native
+// dir, exactly the link-hooks pattern: a managed marker makes install
+// idempotent and remove precise, and hosts whose format differs (gemini TOML)
+// are reported unsupported instead of fed a file that wouldn't load.
+//
+// Canonical source = command/agent entries in the resolved recipe set
+// (recipe.yaml + recipes/imported.yaml + bundles) that carry a `path`. The
+// file already living under one host's dir is never copied back onto itself.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { readActiveSelection, resolveRecipePaths } from "../../core/state/bundle-state.mjs";
+import { readRawEntries } from "../../core/registry/registry.mjs";
+import { SURFACE_COPY_TARGETS } from "../../core/surface/surface-copy-targets.mjs";
+import { detectHosts } from "../hosts.mjs";
+
+// Present hosts = whatever add-mcp detects plus the extra hosts we detect
+// ourselves, as a Set for the copy-target presence gate.
+export async function presentHostSet() {
+  const hosts = await detectHosts();
+  return new Set([...(hosts.mcpHosts ?? []), ...(hosts.extraHosts ?? [])]);
+}
+
+const VALID_COMMANDS = new Set(["status", "install", "remove"]);
+const VALID_SCOPES = new Set(["project", "global"]);
+const SURFACE_TYPES = ["command", "agent"];
+export const MARKER = "portawhip-managed";
+
+function markerLine(id) {
+  return `<!-- ${MARKER}: ${id} -->`;
+}
+
+// Pure: canonical command/agent entries (with a source path) from raw recipe
+// entries. Deduped first-seen, matching the rest of the registry.
+export function canonicalSurfaceEntries(rawEntries) {
+  const seen = new Map();
+  for (const entry of rawEntries) {
+    if (!SURFACE_TYPES.includes(entry.type)) continue;
+    if (!entry.path) continue; // nothing to copy without a source file
+    if (!seen.has(entry.id)) seen.set(entry.id, entry);
+  }
+  return [...seen.values()];
+}
+
+// Pure: does this target dir already contain the source file (i.e. this is the
+// host the file came from)? Then it's the source, never a copy destination.
+export function isSourceDir(sourcePath, targetDir) {
+  const src = resolve(sourcePath).replace(/\\/g, "/");
+  const dir = resolve(targetDir).replace(/\\/g, "/");
+  return src.startsWith(`${dir}/`);
+}
+
+// Pure: the file content with a managed marker injected right after the
+// frontmatter block (or at the very top if there is none). Idempotent — an
+// already-marked file is returned unchanged.
+export function withMarker(content, id) {
+  if (content.includes(markerLine(id)) || content.includes(`<!-- ${MARKER}:`)) return content;
+  const fm = content.match(/^(---\r?\n[\s\S]*?\r?\n---\r?\n)/);
+  if (fm) return `${fm[1]}${markerLine(id)}\n${content.slice(fm[1].length)}`;
+  return `${markerLine(id)}\n${content}`;
+}
+
+export function isManaged(content) {
+  return typeof content === "string" && content.includes(`<!-- ${MARKER}:`);
+}
+
+function targetFileFor(dir, sourcePath) {
+  return join(dir, basename(sourcePath));
+}
+
+// One (entry x host x target) plan row. Pure given fs facts injected.
+function planRow({ entry, hostId, type, target }) {
+  const row = { hostId, type, id: entry.id, scope: target.scope, dir: target.dir ?? null };
+  if (target.unsupported) return { ...row, status: "unsupported", format: target.format };
+  if (isSourceDir(entry.path, target.dir)) return { ...row, status: "source" };
+  const file = targetFileFor(target.dir, entry.path);
+  const present = existsSync(file) && isManaged(safeRead(file));
+  return { ...row, file, status: present ? "linked" : "missing" };
+}
+
+function safeRead(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+export function collectSurfaceLinks({
+  command = "status",
+  scope = "global",
+  root = resolve("."),
+  targets = SURFACE_COPY_TARGETS,
+  entries = null,
+  presentHosts = null,
+} = {}) {
+  const surfaceEntries =
+    entries ??
+    canonicalSurfaceEntries(
+      resolveRecipePaths(root, readActiveSelection(root)).flatMap((p) => (existsSync(p) ? readRawEntries(p) : [])),
+    );
+  const rows = [];
+
+  for (const entry of surfaceEntries) {
+    for (const hostId of Object.keys(targets)) {
+      // Only fan out to hosts actually present, so we never create a config
+      // dir (e.g. ~/.pi) for a host that isn't installed. null = don't gate
+      // (tests inject their own targets and want every row).
+      if (presentHosts && !presentHosts.has(hostId)) continue;
+      const perType = (targets[hostId]?.[entry.type] ?? []).filter((t) => t.scope === scope);
+      for (const target of perType) {
+        const row = planRow({ entry, hostId, type: entry.type, target });
+        if ((command === "install" || command === "remove") && row.file) {
+          applySurface(command, entry, row);
+        }
+        rows.push(row);
+      }
+    }
+  }
+  return { root, command, scope, rows };
+}
+
+function applySurface(command, entry, row) {
+  if (row.status === "source" || row.status === "unsupported") return;
+  if (command === "install") {
+    if (row.status === "linked") return; // idempotent
+    mkdirSync(dirname(row.file), { recursive: true });
+    writeFileSync(row.file, withMarker(safeRead(entry.path), entry.id));
+    row.status = "linked";
+    row.changed = true;
+  } else if (command === "remove") {
+    if (existsSync(row.file) && isManaged(safeRead(row.file))) {
+      rmSync(row.file, { force: true });
+      row.status = "missing";
+      row.changed = true;
+    }
+  }
+}
+
+function parseArgs(argv) {
+  const args = { command: argv[2] ?? "status", scope: "global", json: false };
+  for (let i = 3; i < argv.length; i += 1) {
+    if (argv[i] === "--scope") {
+      args.scope = argv[i + 1];
+      i += 1;
+    } else if (argv[i] === "--json") {
+      args.json = true;
+    } else {
+      throw new Error(`unknown argument: ${argv[i]}`);
+    }
+  }
+  if (!VALID_COMMANDS.has(args.command)) throw new Error("usage: link-surfaces.mjs <status|install|remove> [--scope project|global]");
+  if (!VALID_SCOPES.has(args.scope)) throw new Error(`invalid scope "${args.scope}"`);
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const result = collectSurfaceLinks({
+    command: args.command,
+    scope: args.scope,
+    presentHosts: await presentHostSet(),
+  });
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`link-surfaces ${result.command} (${result.scope}): ${result.rows.length} target(s)`);
+    for (const r of result.rows) {
+      console.log(`${r.status.padEnd(11)} ${r.type} ${r.id} -> ${r.hostId} ${r.dir ?? r.format ?? ""}`);
+    }
+  }
+  const ok = result.rows.every((r) => r.status !== "error");
+  process.exitCode = ok ? 0 : 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/link/link-surfaces.test.mjs

@@ -0,0 +1,76 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  canonicalSurfaceEntries,
+  collectSurfaceLinks,
+  isManaged,
+  isSourceDir,
+  withMarker,
+} from "./link-surfaces.mjs";
+
+test("canonicalSurfaceEntries: only command/agent with a path, deduped", () => {
+  const out = canonicalSurfaceEntries([
+    { id: "a", type: "command", path: "/x/a.md" },
+    { id: "a", type: "command", path: "/y/a.md" }, // dup id -> first wins
+    { id: "b", type: "agent", path: "/x/b.md" },
+    { id: "c", type: "cli" }, // wrong type
+    { id: "d", type: "command" }, // no path
+  ]);
+  assert.deepEqual(out.map((e) => e.id), ["a", "b"]);
+  assert.equal(out[0].path, "/x/a.md");
+});
+
+test("isSourceDir: a file under the target dir is its own source", () => {
+  assert.equal(isSourceDir("/home/.claude/commands/a.md", "/home/.claude/commands"), true);
+  assert.equal(isSourceDir("/home/.codex/prompts/a.md", "/home/.claude/commands"), false);
+});
+
+test("withMarker/isManaged: injects after frontmatter, idempotent", () => {
+  const md = "---\nname: a\n---\n# body\n";
+  const marked = withMarker(md, "a");
+  assert.ok(isManaged(marked));
+  assert.match(marked, /---\r?\n<!-- portawhip-managed: a -->/);
+  assert.equal(withMarker(marked, "a"), marked, "second pass is a no-op");
+  assert.ok(!isManaged(md));
+});
+
+test("withMarker: prepends when there is no frontmatter", () => {
+  const marked = withMarker("# just a heading\n", "x");
+  assert.match(marked, /^<!-- portawhip-managed: x -->/);
+});
+
+test("install then remove roundtrip via injected temp catalog (no host writes)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "link-surfaces-"));
+  const srcDir = join(dir, "src");
+  const destDir = join(dir, "codex", "agents");
+  mkdirSync(srcDir, { recursive: true });
+  writeFileSync(join(srcDir, "reviewer.md"), "---\nname: reviewer\n---\n# reviewer\n");
+
+  const entries = [{ id: "reviewer", type: "agent", path: join(srcDir, "reviewer.md") }];
+  const targets = {
+    "claude-code": { agent: [{ scope: "global", dir: srcDir, format: "md" }] }, // source host
+    codex: { agent: [{ scope: "global", dir: destDir, format: "md" }] },
+    "gemini-cli": { agent: [{ scope: "global", format: "unknown", unsupported: true }] },
+  };
+
+  const status = collectSurfaceLinks({ command: "status", scope: "global", entries, targets });
+  const byHost = Object.fromEntries(status.rows.map((r) => [r.hostId, r.status]));
+  assert.equal(byHost["claude-code"], "source", "source host is not a copy target");
+  assert.equal(byHost.codex, "missing");
+  assert.equal(byHost["gemini-cli"], "unsupported");
+
+  collectSurfaceLinks({ command: "install", scope: "global", entries, targets });
+  const destFile = join(destDir, "reviewer.md");
+  assert.ok(existsSync(destFile), "copied to codex dir");
+  assert.ok(isManaged(readFileSync(destFile, "utf8")), "copy carries the managed marker");
+
+  // idempotent install
+  const again = collectSurfaceLinks({ command: "install", scope: "global", entries, targets });
+  assert.ok(again.rows.every((r) => !r.changed), "second install is a no-op");
+
+  collectSurfaceLinks({ command: "remove", scope: "global", entries, targets });
+  assert.ok(!existsSync(destFile), "remove strips the managed copy");
+});