portawhip 0.1.0

package/scripts/uninstall-all.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// One command to fully retract the harness from every detected host and
+// scope. Does not reimplement removal logic — shells out to link-hooks.mjs
+// and link-connectors.mjs "remove" (marker-based, so only harness-owned
+// entries are touched; the rest of each host's config is untouched) and
+// then re-runs doctor to confirm nothing harness-owned is left.
+//
+// Does NOT touch add-mcp / agent-skill-manager state — those are separate
+// tools with their own install/uninstall; see doctor.mjs's closing note.
+
+import spawnSync from "cross-spawn";
+
+function run(cmd, args) {
+  const result = spawnSync.sync(process.execPath, [cmd, ...args], { encoding: "utf8" });
+  process.stdout.write(result.stdout || "");
+  process.stderr.write(result.stderr || "");
+  return result.status === 0;
+}
+
+const scopes = ["project", "global"];
+let ok = true;
+
+for (const scope of scopes) {
+  console.log(`\n== removing native hooks (${scope}) ==`);
+  ok = run("scripts/link/link-hooks.mjs", ["remove", "--scope", scope]) && ok;
+}
+
+for (const scope of scopes) {
+  console.log(`\n== removing instruction connectors (${scope}) ==`);
+  ok = run("scripts/link/link-connectors.mjs", ["remove", "--scope", scope]) && ok;
+}
+
+console.log("\n== verifying via doctor ==");
+run("scripts/doctor.mjs", []);
+
+if (!ok) {
+  console.error("\nuninstall-all: one or more remove steps exited non-zero — check output above.");
+  process.exitCode = 1;
+}

package/server/mcp-server.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Pull mode (PLAN.md Phase 2): exposes the same core/registry.mjs +
+// core/scorer.mjs used by router-cli.mjs, as an MCP server any host can
+// call directly — no per-host code beyond this one stdio process.
+
+import { fileURLToPath } from "node:url";
+import { dirname, join, isAbsolute } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadIndex } from "../core/registry/registry.mjs";
+import { listAll } from "../core/router/scorer.mjs";
+import { explainRoute } from "../core/router/route-entry.mjs";
+import { loadConfig } from "../core/state/config.mjs";
+import { computeFactors, logEvent } from "../core/state/feedback.mjs";
+import { stackFactors, combineFactors } from "../core/state/stack-detect.mjs";
+import { readActiveSelection, resolveRecipePaths } from "../core/state/bundle-state.mjs";
+import { warmDense, setDenseCachePath, primeDocCache } from "../core/router/dense-embedder.mjs";
+import { buildCapabilityDocs } from "../core/registry/capability-docs.mjs";
+
+// This server is registered globally (add-mcp may promote project scope to
+// global depending on the host), so a caller can invoke it from ANY cwd —
+// recipe.yaml/router.config.yaml must resolve to this repo, never the
+// caller's working directory.
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+// Integration tests and embedded deployments may isolate outcome state from
+// the repository's live dogfood log. Capability/config discovery still uses
+// ROOT; only feedback events are redirected.
+const FEEDBACK_ROOT = process.env.PORTAWHIP_FEEDBACK_ROOT || ROOT;
+// Whatever bundles were opted into via `scripts/bundles.mjs select` (foundry
+// + roles), resolved in front of this repo's own recipe.yaml — defaults to
+// just recipe.yaml when nothing has been selected (today's behavior).
+const RECIPE_PATHS = resolveRecipePaths(ROOT, readActiveSelection(ROOT));
+const CONFIG_PATH = join(ROOT, "router.config.yaml");
+
+const server = new McpServer({ name: "harness-router", version: "0.0.1" });
+
+server.tool(
+  "route",
+  "Look up which installed capability (MCP tool, skill, or CLI) fits a task before you start it. " +
+    "State only the positively requested action and its direct object; do not copy the raw prompt. " +
+    "Drop chit-chat, venting, background, and any rejected, negated, or hypothetical option. " +
+    "If a request is buried in chat, route only the request; if the message names several distinct actions, call route once per action. " +
+    "Example: 'ugh CI is flaky, anyway find where we parse the auth token' -> query 'find the code that parses the auth token'. " +
+    "Returns pointers, not full content. An empty result is expected and means nothing installed fits.",
+  { query: z.string(), k: z.number().optional() },
+  async ({ query, k }) => {
+    const index = await loadIndex(RECIPE_PATHS);
+    const config = loadConfig(CONFIG_PATH);
+    // Same class of bug fixed earlier for recipe.yaml/router.config.yaml:
+    // graphPath in config is written as a repo-relative string, which
+    // silently resolves against the CALLER's cwd, not this repo, when this
+    // server is invoked from elsewhere (which is the whole point of
+    // installing it globally).
+    const graphPath =
+      config.graphPath && !isAbsolute(config.graphPath) ? join(ROOT, config.graphPath) : config.graphPath;
+    const factors = combineFactors(computeFactors(FEEDBACK_ROOT), stackFactors(index, process.cwd()));
+    // denseBlock:false - this is the interactive tier. A cold dense-model load
+    // must never block a route() call (it would time the MCP client out; see
+    // core/dense-embedder.mjs). Early calls are sparse-only and dense joins in
+    // once the background warm (started at server boot below) finishes.
+    const result = await explainRoute(index, query, {
+      ...config,
+      graphPath,
+      k: k ?? config.k,
+      factors,
+      denseBlock: false,
+      mode: "pull",
+    });
+    logEvent(FEEDBACK_ROOT, {
+      type: "route",
+      engine: config.engine,
+      queryLength: query.length,
+      resultCount: result.results.length,
+      suppressedCount: result.suppressed.length,
+      topIds: result.results.slice(0, 3).map((hit) => hit.id),
+      latencyMs: result.latency_ms,
+      emptyReason: result.negative_evidence?.reason ?? null,
+    });
+    // Pull results join the trust loop as boost-only signal (2026-07-09):
+    // source:"pull" marks these so computeFactors credits a follow-up "used"
+    // (Claude asked, got an answer, acted on it - the strongest possible
+    // relevance signal) but never counts an unused pull result as an
+    // "ignored" outcome. Pull is recall-generous by design; punishing
+    // unclicked results would recreate the noise-decay bug at this layer.
+    for (const hit of result.results) {
+      // The reasoned summary may contain sensitive task context. Outcome
+      // attribution only needs capability id + source, so never persist it.
+      logEvent(FEEDBACK_ROOT, { type: "suggested", id: hit.id, source: "pull" });
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  },
+);
+
+server.tool(
+  "list_all",
+  "List every installed capability known to the harness registry, " +
+    "optionally filtered by type (mcp | cli | skill).",
+  { type: z.string().optional() },
+  async ({ type }) => {
+    const index = await loadIndex(RECIPE_PATHS);
+    const result = listAll(index, type);
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  },
+);
+
+// Start the (slow) dense model load in the background at boot, so it overlaps
+// the idle time before the first route() call rather than blocking it. Safe
+// to call unconditionally: it's fire-and-forget and a no-op when the model
+// can't be loaded (dense degrades to sparse-only). If dense is disabled in
+// config, the warm still completes harmlessly and simply never gets used.
+warmDense();
+
+// Doc-embedding cache: persisted to disk (survives this process restarting,
+// which happens every session) AND primed here at boot, in the background,
+// overlapping the model load above - so the FIRST interactive route() call
+// after warm doesn't land on 559 uncached docs being embedded one-by-one in
+// its own request (found live: 67-104s route() latency from exactly this -
+// denseBlock:false only ever guarded the model load, never this). Fire and
+// forget: no client is waiting on server boot, and denseRetrieve's own
+// on-demand embed path still covers any doc this background pass hasn't
+// reached yet.
+setDenseCachePath(join(ROOT, ".hp-state", "dense-cache.json"));
+loadIndex(RECIPE_PATHS)
+  .then((index) => primeDocCache(buildCapabilityDocs(index)))
+  .catch(() => {});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/server/mcp-server.test.mjs

@@ -0,0 +1,175 @@
+import { after, test } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, mkdtempSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+
+// Live integration test - spawns the REAL MCP server and calls route() over
+// real stdio JSON-RPC, no mocks. The unit tests in core/router.test.mjs inject
+// a fake extractor, which by design mocks away the exact thing that broke in
+// production: the real BGE-M3 cold load blocking the first route() call for
+// ~73s, past the MCP client timeout, leaving route() uncallable for a whole
+// session (found live 2026-07-07). A mock can't catch that; only spawning the
+// real server with dense enabled (the default) and timing a real call can.
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const SERVER = join(ROOT, "server", "mcp-server.mjs");
+const TEST_FEEDBACK_ROOT = mkdtempSync(join(tmpdir(), "portawhip-mcp-feedback-"));
+const FEEDBACK_PATH = join(TEST_FEEDBACK_ROOT, ".hp-state", "feedback", "events.jsonl");
+
+after(() => rmSync(TEST_FEEDBACK_ROOT, { recursive: true, force: true }));
+
+// The server logs a real "route" event to this repo's live feedback log.
+// Snapshot and restore it so running tests never destroys real dogfood
+// history - same discipline as adapters/hooks/universal-hook.test.mjs.
+let feedbackBackup;
+function snapshotFeedback() {
+  feedbackBackup = existsSync(FEEDBACK_PATH) ? readFileSync(FEEDBACK_PATH, "utf8") : null;
+}
+function restoreFeedback() {
+  if (existsSync(FEEDBACK_PATH)) rmSync(FEEDBACK_PATH);
+  if (feedbackBackup != null) {
+    mkdirSync(dirname(FEEDBACK_PATH), { recursive: true });
+    writeFileSync(FEEDBACK_PATH, feedbackBackup);
+  }
+}
+
+// Spawn the server, do the MCP initialize handshake, then send one request.
+// Resolves with the round-trip time of the request itself (t0 is
+// set right before it is sent, so server boot / index load is excluded - we
+// are measuring the route() latency the client would feel, which is what the
+// non-blocking guarantee is about). MCP stdio framing is newline-delimited
+// JSON-RPC.
+function callMcp(method, params, { timeoutMs = 25000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const srv = spawn(process.execPath, [SERVER], {
+      stdio: ["pipe", "pipe", "pipe"],
+      cwd: ROOT,
+      env: { ...process.env, PORTAWHIP_FEEDBACK_ROOT: TEST_FEEDBACK_ROOT },
+    });
+    let buf = "";
+    let t0 = null;
+    const done = (fn, arg) => {
+      clearTimeout(timer);
+      srv.kill();
+      fn(arg);
+    };
+    const timer = setTimeout(
+      () => done(reject, new Error(`route() did not respond within ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    srv.stdout.on("data", (chunk) => {
+      buf += chunk.toString();
+      let idx;
+      while ((idx = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, idx);
+        buf = buf.slice(idx + 1);
+        if (!line.trim()) continue;
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (msg.id === 2) {
+          const ms = Date.now() - t0;
+          const payload = method === "tools/call" ? JSON.parse(msg.result.content[0].text) : msg.result;
+          done(resolve, { ms, result: payload });
+        }
+      }
+    });
+    srv.on("error", (err) => done(reject, err));
+    const send = (obj) => srv.stdin.write(`${JSON.stringify(obj)}\n`);
+    send({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "mcp-server-test", version: "1" },
+      },
+    });
+    // Give initialize a moment to be processed before firing the tool call.
+    setTimeout(() => {
+      send({ jsonrpc: "2.0", method: "notifications/initialized" });
+      t0 = Date.now();
+      send({ jsonrpc: "2.0", id: 2, method, params });
+    }, 500);
+  });
+}
+
+function callRoute(query, options) {
+  return callMcp("tools/call", { name: "route", arguments: { query } }, options);
+}
+
+function listTools(options) {
+  return callMcp("tools/list", {}, options);
+}
+
+test("mcp-server: route tool asks for a reasoned requested-action summary", async () => {
+  const { result } = await listTools();
+  const routeTool = result.tools.find((tool) => tool.name === "route");
+  assert.ok(routeTool, "route tool must be listed");
+  assert.match(routeTool.description, /requested action/i);
+  assert.match(routeTool.description, /not (?:repeat|copy) the raw (?:prompt|topic)/i);
+  assert.deepEqual(Object.keys(routeTool.inputSchema.properties).sort(), ["k", "query"]);
+});
+
+test("mcp-server: concise router-analysis actions can still abstain", async () => {
+  const summaries = [
+    "compare capability-router architecture choices",
+    "analyze router context-efficiency principles",
+  ];
+  for (const summary of summaries) {
+    const { result } = await callRoute(summary);
+    assert.equal(result.decision, "abstain", summary);
+    assert.deepEqual(result.results, [], summary);
+  }
+});
+
+test("mcp-server: reasoned actionable summary still routes the curated capability", async () => {
+  const { result } = await callRoute("import an installed CLI and synchronize it across agent hosts");
+  assert.equal(result.decision, "route");
+  const portawhip = result.results.find((hit) => hit.id === "portawhip");
+  assert.ok(portawhip);
+  assert.equal(portawhip.intentEvidence.mode, "pull");
+});
+
+test("mcp-server: pull feedback never persists the reasoned summary text", async () => {
+  snapshotFeedback();
+  const summary = "import a sensitive internal CLI and synchronize it across agent hosts";
+  try {
+    await callRoute(summary);
+    const events = readFileSync(FEEDBACK_PATH, "utf8")
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+    assert.ok(!readFileSync(FEEDBACK_PATH, "utf8").includes(summary));
+    for (const event of events.filter((item) => item.source === "pull")) {
+      assert.ok(!("query" in event));
+      assert.ok(!("prompt" in event));
+    }
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("mcp-server (live): route() answers fast, never blocking on the dense model cold-load", async () => {
+  snapshotFeedback();
+  try {
+    const { ms, result } = await callRoute("convert this pdf file to markdown text");
+    // The regressed behavior blocked ~73s here (dense cold load) and timed the
+    // client out. Non-blocking dense must answer in seconds regardless of
+    // whether the model is cached, downloading, or unreachable - it returns
+    // sparse-only until the background warm finishes. 15s is far below the
+    // 73s failure and well under any MCP client timeout, so it cleanly
+    // separates healthy from regressed without being flaky on a cold index.
+    assert.ok(ms < 15000, `route() took ${ms}ms - expected a fast, non-blocking answer (regression blocked ~73s)`);
+    assert.ok(result && typeof result.status === "string", "route() must return a structured decision object");
+    assert.ok(Array.isArray(result.results), "decision must carry a results array (possibly empty)");
+  } finally {
+    restoreFeedback();
+  }
+});

package/skills/portawhip/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: portawhip
+description: >-
+  Manage portawhip's cross-host capability sync — import newly-installed
+  tools/skills/MCP/commands/agents into the shared canonical set, enrich them,
+  check coverage, and fan them out to every AI host. Use when the user wants to
+  import a capability, share tools across Claude Code / Codex / Gemini / Cursor,
+  check what's synced, see the surface coverage matrix, or run/inspect the
+  loader, router, connectors, or hooks.
+---
+
+# portawhip — cross-host capability manager
+
+portawhip loads capabilities into whatever AI hosts + OS the user has, and
+routes the right one at the right moment. Two directions:
+
+- **import** (manual): promote a capability that's installed *somewhere* into
+  the shared canonical set (`recipes/imported.yaml` for CLI/skill/command/
+  agent, `.agents/agents.json` for MCP). Auto-enriched so it routes on natural
+  phrasing, not just its own name.
+- **fan-out** (automatic on session start, or manual): push canonical
+  capabilities out to every detected host.
+
+Run everything from the repo root. All commands are safe to preview first;
+nothing installs or writes across hosts without an explicit apply/sync.
+
+## Import a newly-installed capability
+
+```bash
+npm run import                 # grouped status: what's installed but not yet canonical
+npm run import:preview         # same, framed as a plan
+# apply — narrow by surface or pick one; hand-curated recipe.yaml always wins:
+node scripts/import-surfaces.mjs apply --apply --type cli,mcp
+node scripts/import-surfaces.mjs apply --apply --include skill:pdf
+```
+
+- Default view groups by surface (cli / mcp / skill / command / agent) with
+  real counts; large groups are sampled with an import hint. Nothing hidden.
+- CLI entries are auto-enriched on apply (mise registry → package registry →
+  tldr → --help). A CLI that can't be enriched at all is held back.
+- Import is idempotent: re-running proposes only what's genuinely new.
+
+## Fan out to all hosts
+
+```bash
+npm run sync-surfaces sync     # push canonical -> every detected host (idempotent)
+npm run sync-surfaces check    # dry-run: what would change
+```
+
+Session start also fires this automatically in the background (throttled) via
+the auto-sync hook — see `router.config.yaml`'s `autoSync`. It only ever
+propagates already-canonical entries, never auto-imports.
+
+## Check coverage and health
+
+```bash
+npm run doctor                 # unified status + surface coverage matrix (light)
+node scripts/doctor.mjs --heavy   # matrix with full discovery counts
+npm run surface                # detailed inventory (capabilities/hooks/connectors)
+npm run tui -- --summary       # one-screen attention summary
+```
+
+The surface matrix (`surface-matrix.yaml` + `core/surface-matrix.mjs`) shows,
+per surface, whether the read (import) and write (fan-out) lanes are covered,
+missing, or partial — live-probed, not asserted.
+
+## Routing (surface the right capability at the right time)
+
+```bash
+node core/router-cli.mjs route --prompt "..."   # what would route for a prompt
+node core/router-cli.mjs list                   # everything in the index
+node core/router-cli.mjs enrich                 # refresh tool descriptions/triggers
+```
+
+## Notes
+
+- Removing an imported entry (`forget`) is not built yet — edit
+  `recipes/imported.yaml` / `.agents/agents.json` by hand for now.
+- Design + rationale: `VISION.md`, `docs/sync-connector-plan.md`, and the
+  `docs/phaseS*-verify.md` records.

package/surface-matrix.yaml

@@ -0,0 +1,93 @@
+# Surface coverage matrix — DATA ONLY (Phase S0).
+#
+# Rows = the portable surfaces the connector is meant to sync. For each
+# direction (read=import from hosts, write=fan-out to hosts) this file
+# declares WHICH backend owns the lane, or a declared gap (missing/
+# unsupported) where no lane exists yet. It never asserts a live status:
+# core/surface-matrix.mjs live-probes every declared owner and reports what
+# it actually finds (VISION.md: live-probe, never overclaim). The host axis
+# stays dynamic — resolved at runtime from detectHosts(), never listed here.
+#
+# probe kinds interpreted by surface-matrix.mjs:
+#   command        : run argv; covered if the backend command resolves + exits 0
+#   discover       : call core/discover.mjs <fn>; covered if it returns items
+#                    (count reported; 0 = lane works but nothing found)
+#   link-hooks     : scripts/link/link-hooks.mjs status; covered if any host linked
+#   link-connectors: scripts/link/link-connectors.mjs status; covered if any linked
+#   none           : no probe; status is the declared `gap`
+#
+# gap values: missing (no lane, planned) | unsupported (no host API) | partial
+
+surfaces:
+  - id: mcp
+    label: MCP servers
+    read:
+      owner: "discover.mjs:discoverMcp"
+      probe: { kind: discover, fn: mcp, heavy: true }
+    write:
+      owner: "add-mcp + agents-dotdir"
+      probe: { kind: command, argv: [agents, --version] }
+
+  - id: cli
+    label: CLI tools
+    read:
+      owner: "discover.mjs:discoverCli (mise ls)"
+      probe: { kind: discover, fn: cli }
+    write:
+      owner: "mise (via load.mjs)"
+      probe: { kind: command, argv: [mise, --version] }
+
+  - id: skill
+    label: Skills
+    read:
+      owner: "discover.mjs:discoverSkills"
+      probe: { kind: discover, fn: skills, heavy: true }
+    write:
+      owner: "agent-skill-manager (via load.mjs)"
+      probe: { kind: command, argv: [agent-skill-manager, --version] }
+
+  - id: command
+    label: Slash commands
+    read:
+      owner: "discover.mjs:discoverCommands (+ host-native dirs)"
+      probe: { kind: discover, fn: commands }
+    write:
+      owner: "link-surfaces.mjs (managed-copy)"
+      probe: { kind: command, argv: [node, scripts/link/link-surfaces.mjs, status] }
+
+  - id: agent
+    label: Subagent defs
+    read:
+      owner: "discover.mjs:discoverAgents (+ host-native dirs)"
+      probe: { kind: discover, fn: agents }
+    write:
+      owner: "link-surfaces.mjs (managed-copy; gemini unsupported)"
+      probe: { kind: command, argv: [node, scripts/link/link-surfaces.mjs, status] }
+
+  - id: hook-declared
+    label: Hooks (declared)
+    read:
+      owner: "hooks.manifest.yaml (curated)"
+      probe: { kind: command, argv: [node, scripts/link/link-hooks.mjs, status] }
+    write:
+      owner: "link-hooks.mjs (native-hook hosts)"
+      probe: { kind: link-hooks }
+
+  - id: hook-embedded
+    label: Hooks (embedded in skills/plugins)
+    read:
+      owner: "discover-hooks.mjs:discoverEmbeddedHooks"
+      probe: { kind: discover, fn: embeddedHooks, heavy: true }
+    write:
+      owner: null
+      gap: missing
+      note: "Inventory only (Phase S3 mode B). Linking embedded hooks is deferred until a proven need (S3 full)."
+
+  - id: instruction
+    label: Instructions / router link
+    read:
+      owner: "ai-config-sync (claude<->codex)"
+      probe: { kind: command, argv: [node, scripts/link/link-connectors.mjs, status] }
+    write:
+      owner: "ai-config-sync + link-connectors.mjs"
+      probe: { kind: link-connectors }