@popoverinstall/cli 0.9.0 → 0.9.1

package/plugin/mcp/index.mjs

@@ -1,585 +1,765 @@
-#!/usr/bin/env node
-// Popover MCP server — lets an agent see and ask its teammates' agents.
-//
-// Implemented directly against the JSON-RPC stdio protocol rather than the MCP SDK. The
-// plugin is distributed through a marketplace and installed into a cache directory where
-// dependency installation is conditional and can fail; a server with zero dependencies
-// simply cannot fail that way. The protocol surface we need is small — initialize,
-// tools/list, tools/call — so the SDK buys us little here.
-//
-// All real work happens in the daemon. This process is a thin bridge to it.
-
-import { readFileSync } from "node:fs";
-import { callerSessionId, request } from "../scripts/_ipc.mjs";
-
-const PROTOCOL_VERSION = "2025-06-18";
-
-// Read from the plugin manifest, which Claude Code copies into its cache alongside this
-// file — so the relative path survives the severing copy that breaks everything else.
-const SERVER_INFO = {
-  name: "popover",
-  version: JSON.parse(
-    readFileSync(new URL("../.claude-plugin/plugin.json", import.meta.url), "utf8"),
-  ).version,
-};
-
-
-const TOOLS = [
-  {
-    name: "team_list",
-    description:
-      "List your teammates' currently-active Claude Code agents in THIS repo: who owns " +
-      "each one, what it is doing right now, and its short handle (e.g. B1). Only agents " +
-      "working in the same repository as you are visible — agents your teammates are " +
-      "running in other repos are not listed and cannot be asked. Use this before " +
-      "team_ask to find out which agent to ask. Read-only.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false },
-    annotations: { readOnlyHint: true, openWorldHint: true, title: "List team agents" },
-  },
-  {
-    name: "team_ask",
-    description:
-      "Ask a teammate's Claude Code agent a question and wait for the answer. A " +
-      "read-only copy of that agent answers from its full accumulated context; the " +
-      "teammate's live session is never interrupted or modified. Use this when a " +
-      "teammate's agent already knows something that would take you a long time to " +
-      "work out — why a decision was made, what they already ruled out, how a service " +
-      "they own behaves. Only agents working in the same repository as you can be asked. " +
-      "Answering costs the teammate tokens and takes up to ~90s, so ask one well-formed " +
-      "question rather than several exploratory ones.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        target: {
-          type: "string",
-          description:
-            "Which agent to ask: a handle from team_list such as 'B1', or a teammate's " +
-            "name, or a repo name.",
-        },
-        question: {
-          type: "string",
-          description:
-            "A self-contained question. The answering agent has none of your " +
-            "conversation's context, so expand pronouns and vague references.",
-        },
-        timeout_seconds: {
-          type: "number",
-          description: "How long to wait for an answer. Default 90, max 300.",
-          minimum: 5,
-          maximum: 300,
-        },
-      },
-      required: ["target", "question"],
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: true, openWorldHint: true, title: "Ask a teammate's agent" },
-  },
-  {
-    name: "team_tell",
-    description:
-      "Send a short heads-up to a teammate's agent working in this repo. Unlike team_ask " +
-      "there is no answer: the message is delivered into that agent's context before its " +
-      "next prompt, and nothing comes back. Use it for facts about shared state that would " +
-      "otherwise cause a collision — \"the migration is applied on prod\", \"I am rewriting " +
-      "globals.css, leave it alone\". Do not use it to give another agent instructions or " +
-      "assign it work: the receiving agent is told to treat your message as information " +
-      "from outside its conversation, not as a directive, and its user is notified that you " +
-      "sent it. Only agents in the same repository can be told, and you are limited to 10 " +
-      "messages an hour to any one agent.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        target: {
-          type: "string",
-          description:
-            "Which agent to tell: a handle from team_list such as 'B1', or a teammate's " +
-            "name, or a repo name.",
-        },
-        message: {
-          type: "string",
-          description:
-            "The heads-up, in one or two sentences. It arrives with no context of its own, " +
-            "so name the thing you are talking about rather than referring to it.",
-        },
-      },
-      required: ["target", "message"],
-      additionalProperties: false,
-    },
-    // Not read-only: this writes into someone else's context and notifies a person.
-    annotations: { readOnlyHint: false, openWorldHint: true, title: "Tell a teammate's agent" },
-  },
-  {
-    name: "vault_search",
-    description:
-      "Search your team's vaults. A vault is a conversation somebody on your team froze " +
-      "deliberately and published: it does not expire, it is not a live session, and its " +
-      "author does not have to be online — or still at the company — for you to use it. " +
-      "This searches the index only. It is free, it runs no model, it resumes nothing, and " +
-      "it costs neither you nor anybody else a token, so use it freely. Each result carries " +
-      "the questions that vault says it can answer, when it was frozen, who froze it, and " +
-      "how much of the code it discussed has changed since — a vault whose files nobody has " +
-      "touched is current however old it is, and one whose files have churned is suspect " +
-      "even if it is recent. Unlike team_list this is not limited to agents in your repo or " +
-      "to people who are working right now: every vault on every team you belong to is " +
-      "searchable. ALWAYS call this before vault_ask, and read what comes back: asking is " +
-      "the expensive half and this is how you spend it on the right vault.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: {
-          type: "string",
-          description:
-            "What you want to know, phrased as a question. Vaults are indexed by the " +
-            "questions they can answer rather than by a summary, so a question matches far " +
-            "better than keywords do. Omit it to list the most recently frozen vaults.",
-        },
-        repo: {
-          type: "string",
-          description:
-            "Narrow to one repo label. Display-level filtering only — vaults are visible " +
-            "across every repo your team works in, so leave this off unless the user asked " +
-            "for one repo specifically.",
-        },
-        limit: {
-          type: "number",
-          description: "How many to return. Default 20, max 50.",
-          minimum: 1,
-          maximum: 50,
-        },
-      },
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: true, openWorldHint: true, title: "Search team vaults" },
-  },
-  {
-    name: "vault_ask",
-    description:
-      "Ask one vault one question and wait for the answer. **This costs a full context " +
-      "load and real money** — the frozen conversation is resumed in its entirety on THIS " +
-      "machine, on your user's account, at roughly $0.50 and up to 90 seconds per call. " +
-      "Call vault_search first and ask the one vault that fits; never fan out across " +
-      "several to see which answers best, and never call this on a vault you have not seen " +
-      "in a search result. The vault answers from its frozen context and has no tools at " +
-      "all: it cannot read a file, run a command, or look at the repository as it stands " +
-      "today, which is deliberate — it is authoritative about what was decided and why, and " +
-      "explicitly unreliable about what the code currently looks like. Report what comes " +
-      "back as the vault's claim, attributed and dated, never as a bare fact merged into " +
-      "your own reasoning: a vault can hold a hypothesis the team later disproved. Nothing " +
-      "you do here reaches the vault's author, changes the vault, or costs them anything.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        vault_id: {
-          type: "string",
-          description: "The `id` of a vault from a vault_search result. Never guess one.",
-        },
-        question: {
-          type: "string",
-          description:
-            "A self-contained question. The vault has none of your conversation and has " +
-            "been frozen for weeks or months, so expand every pronoun, name files by path, " +
-            "and ask about decisions and reasoning rather than about the current code.",
-        },
-        timeout_seconds: {
-          type: "number",
-          description: "How long to wait for an answer. Default 90, max 300.",
-          minimum: 5,
-          maximum: 300,
-        },
-      },
-      required: ["vault_id", "question"],
-      additionalProperties: false,
-    },
-    // Read-only: it resumes a copy and writes nothing back. It is not free, which the
-    // description says at length, because an annotation cannot say "and it costs money".
-    annotations: { readOnlyHint: true, openWorldHint: true, title: "Ask a team vault" },
-  },
-];
-
-// ---------------------------------------------------------------------------
-// Tool implementations
-// ---------------------------------------------------------------------------
-
-async function callTeamList() {
-  // Sent so the daemon can mark which line is this agent's own, and so it can scope the
-  // roster to the repo this session is working in. Absent outside a session, in which case
-  // the roster comes back unmarked rather than failing.
-  const reply = await request(
-    {
-      t: "roster",
-      id: rpcId(),
-      refresh: true,
-      ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
-      // Fallback for the narrow window where the daemon has not seen this session yet. The
-      // session is authoritative when known; this is only ever consulted when it is not.
-      cwd: process.cwd(),
-    },
-    { timeoutMs: 15000 },
-  );
-
-  if (!reply) return errorText(daemonDownMessage());
-  if (reply.t === "error") return errorText(explain(reply));
-  if (reply.t !== "roster.ok") return errorText("The popover daemon returned an unexpected response.");
-
-  if (!reply.entries || reply.entries.length === 0) {
-    // The daemon's own text, because only it knows whether the answer is "nobody on your
-    // team is working" or "nobody is working in this repo" — and those lead a model to say
-    // very different things.
-    return text(
-      reply.rendered ||
-        "No teammates currently have active Claude Code sessions. Nobody is available to ask right now.",
-    );
-  }
-  // Returned as text rather than structuredContent on purpose: setting
-  // structuredContent suppresses text blocks, and the rendered table is both easier for
-  // the model to read and directly presentable to the user.
-  return text(reply.rendered);
-}
-
-async function callTeamAsk(args) {
-  const target = typeof args?.target === "string" ? args.target.trim() : "";
-  const question = typeof args?.question === "string" ? args.question.trim() : "";
-
-  if (!target) return errorText("`target` is required — call team_list to see the options.");
-  if (!question) return errorText("`question` is required.");
-
-  const timeoutSeconds = clamp(Number(args?.timeout_seconds) || 90, 5, 300);
-
-  const reply = await request(
-    {
-      t: "ask",
-      id: rpcId(),
-      req: {
-        target,
-        question,
-        timeoutSeconds,
-        // Lets the audit log show that an agent asked, not a human, and scopes the target
-        // to this session's repo.
-        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
-      },
-      cwd: process.cwd(),
-    },
-    // Outlast the daemon's own wait so its specific error wins over a generic timeout.
-    { timeoutMs: timeoutSeconds * 1000 + 15000 },
-  );
-
-  if (!reply) return errorText(daemonDownMessage());
-  if (reply.t === "error") return errorText(explain(reply));
-  if (reply.t !== "ask.ok") return errorText("The popover daemon returned an unexpected response.");
-
-  const { answer } = reply;
-  const by = answer.answeredBy;
-  const attribution = by ? `${by.handle} (${by.ownerName}, ${by.repo})` : "a teammate's agent";
-  const cost =
-    answer.costUsd != null && answer.durationMs != null
-      ? `\n\n_(answered in ${(answer.durationMs / 1000).toFixed(1)}s, cost $${answer.costUsd.toFixed(3)} on their account)_`
-      : "";
-
-  return text(`Answer from ${attribution}:\n\n${answer.answer}${cost}`);
-}
-
-async function callTeamTell(args) {
-  const target = typeof args?.target === "string" ? args.target.trim() : "";
-  const message = typeof args?.message === "string" ? args.message.trim() : "";
-
-  if (!target) return errorText("`target` is required — call team_list to see the options.");
-  if (!message) return errorText("`message` is required.");
-
-  const reply = await request(
-    {
-      t: "tell",
-      id: rpcId(),
-      req: {
-        target,
-        message,
-        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
-      },
-      cwd: process.cwd(),
-    },
-    { timeoutMs: 15000 },
-  );
-
-  if (!reply) return errorText(daemonDownMessage());
-  if (reply.t === "error") return errorText(explain(reply));
-  if (reply.t !== "tell.ok") return errorText("The popover daemon returned an unexpected response.");
-
-  // Says delivered-to, never read-by: a sender is deliberately told nothing about what
-  // happened to their message afterwards.
-  return text(
-    `Sent to ${reply.handle} (${reply.ownerName}). It will reach that agent before its next ` +
-      `prompt; there is no reply.`,
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Vaults — the cheap half and the costly half, deliberately two tools
-// ---------------------------------------------------------------------------
-
-async function callVaultSearch(args) {
-  const query = typeof args?.query === "string" ? args.query.trim() : "";
-  const repo = typeof args?.repo === "string" ? args.repo.trim() : "";
-  const limit = clamp(Number(args?.limit) || 20, 1, 50);
-
-  const reply = await request(
-    {
-      t: "vaults",
-      id: rpcId(),
-      req: {
-        limit,
-        ...(query ? { query } : {}),
-        ...(repo ? { repo } : {}),
-      },
-      // Not a filter. The daemon uses it to diff each vault's files against the tree in front
-      // of you, which is what the staleness figure in each result is.
-      cwd: process.cwd(),
-    },
-    { timeoutMs: 20000 },
-  );
-
-  if (!reply) return errorText(daemonDownMessage());
-  if (reply.t === "error") return errorText(explain(reply));
-  if (reply.t !== "vaults.ok") return errorText("The popover daemon returned an unexpected response.");
-
-  const vaults = reply.vaults ?? [];
-  if (vaults.length === 0) {
-    return text(
-      query
-        ? `No vault on your teams answers anything like "${query}". Nothing was spent looking. ` +
-            "Do not call vault_ask — there is no vault to ask."
-        : "Your teams have not published any vaults yet.",
-    );
-  }
-
-  const lines = vaults.map((vault, index) => {
-    const facts = [
-      vault.authorLabel,
-      `frozen ${friendlyDate(vault.frozenAt)}`,
-      vault.repoLabel ? `repo ${vault.repoLabel}` : null,
-      vault.noteCount > 0 ? `${vault.noteCount} note${vault.noteCount === 1 ? "" : "s"}` : null,
-      describeStaleness(vault.staleness),
-    ].filter(Boolean);
-
-    const answers = (vault.answers ?? []).map((a) => `     - ${a}`).join("\n");
-    return (
-      `${index + 1}. ${vault.title}  (${vault.name})\n` +
-      `   id: ${vault.id}\n` +
-      `   ${facts.join(" · ")}\n` +
-      (answers ? `   Says it can answer:\n${answers}\n` : "")
-    );
-  });
-
-  return text(
-    `${vaults.length} vault${vaults.length === 1 ? "" : "s"} on your teams:\n\n` +
-      lines.join("\n") +
-      "\nThis search cost nothing. Asking one of these costs a full context load and real " +
-      "money on your user's account, so pick the single best fit — or none, if none of them " +
-      "claims to answer the question.",
-  );
-}
-
-async function callVaultAsk(args) {
-  const vaultId = typeof args?.vault_id === "string" ? args.vault_id.trim() : "";
-  const question = typeof args?.question === "string" ? args.question.trim() : "";
-
-  if (!vaultId) return errorText("`vault_id` is required — call vault_search to find one.");
-  if (!question) return errorText("`question` is required.");
-
-  const timeoutSeconds = clamp(Number(args?.timeout_seconds) || 90, 5, 300);
-
-  const reply = await request(
-    {
-      t: "vaultAsk",
-      id: rpcId(),
-      req: {
-        vaultId,
-        question,
-        timeoutSeconds,
-        // Carries the per-session budget. Without it the daemon cannot tell one agent asking
-        // six vaults from six agents asking one each.
-        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
-      },
-      cwd: process.cwd(),
-    },
-    // Outlast the daemon's own wait so its specific error wins over a generic timeout.
-    { timeoutMs: timeoutSeconds * 1000 + 15000 },
-  );
-
-  if (!reply) return errorText(daemonDownMessage());
-  if (reply.t === "error") return errorText(explain(reply));
-  if (reply.t !== "vaultAsk.ok") return errorText("The popover daemon returned an unexpected response.");
-
-  const { answer } = reply;
-  // Attribution first, and not optional. A human reading a vault's answer supplies the
-  // skepticism unprompted; a model will not unless the format forces it, and a vault can hold
-  // a hypothesis the team later disproved.
-  const at = answer.gitSha ? ` at commit ${answer.gitSha}` : "";
-  const cost =
-    answer.costUsd != null && answer.durationMs != null
-      ? ` Answered in ${(answer.durationMs / 1000).toFixed(1)}s, cost $${answer.costUsd.toFixed(3)} on your own account.`
-      : "";
-
-  return text(
-    `The "${answer.title}" vault, frozen ${friendlyDate(answer.frozenAt)}${at}, says:\n\n` +
-      `${answer.answer}\n\n` +
-      `_(That is a frozen conversation, not the current code. Treat it as authoritative ` +
-      `about what was decided and why, and check anything it says about how the repository ` +
-      `looks today. Attribute it to the vault when you pass it on.${cost})_`,
-  );
-}
-
-/** ISO timestamp to something a person reads, without pulling in a formatter. */
-function friendlyDate(iso) {
-  const at = new Date(iso);
-  if (Number.isNaN(at.getTime())) return iso;
-  const months = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
-  return `${at.getUTCDate()} ${months[at.getUTCMonth()]} ${at.getUTCFullYear()}`;
-}
-
-/**
- * The staleness figure in words.
- *
- * Absent when the daemon had no working tree to diff against, or the vault recorded no paths.
- * Silence is correct there: "0% changed" and "we could not check" are different claims, and
- * only one of them is evidence that the vault is still current.
- */
-function describeStaleness(staleness) {
-  if (typeof staleness !== "number") return null;
-  if (staleness === 0) return "none of its files have changed since";
-  return `${Math.round(staleness * 100)}% of its files have changed since`;
-}
-
-function explain(errorReply) {
-  switch (errorReply.code) {
-    // The daemon knows whether credentials are missing or merely unusable; relaying its
-    // message avoids telling an already signed-in user to sign in again.
-    case "not_authenticated":
-    case "target_offline":
-    case "unknown_target":
-    case "timeout":
-    case "fork_failed":
-    case "bad_request":
-      return errorReply.message;
-    // A vault that is gone is gone: they are never edited and never expire, so this means the
-    // id was wrong or it has been archived. Retrying it, or trying a neighbouring id, cannot
-    // help — searching again can.
-    case "vault_not_found":
-      return `${errorReply.message} Call vault_search again rather than trying another id.`;
-    case "cloud_unreachable":
-      return `Could not reach the popover backend: ${errorReply.message}`;
-    default:
-      return errorReply.message || "The request failed.";
-  }
-}
-
-function daemonDownMessage() {
-  return (
-    "The popover daemon is not running on this machine, so teammate agents are not " +
-    "reachable. Start it with `popover daemon start`, or run `popover doctor` to diagnose."
-  );
-}
-
-// ---------------------------------------------------------------------------
-// JSON-RPC plumbing
-// ---------------------------------------------------------------------------
-
-function text(value) {
-  return { content: [{ type: "text", text: value }] };
-}
-
-function errorText(message) {
-  // isError tells the model the call failed while still handing it a readable reason,
-  // which is far more useful than a transport-level error.
-  return { content: [{ type: "text", text: message }], isError: true };
-}
-
-function clamp(n, lo, hi) {
-  return Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : lo;
-}
-
-let counter = 0;
-function rpcId() {
-  counter += 1;
-  return `mcp-${process.pid}-${counter}`;
-}
-
-function send(message) {
-  process.stdout.write(`${JSON.stringify(message)}\n`);
-}
-
-function reply(id, result) {
-  send({ jsonrpc: "2.0", id, result });
-}
-
-function replyError(id, code, message) {
-  send({ jsonrpc: "2.0", id, error: { code, message } });
-}
-
-async function handle(message) {
-  const { id, method, params } = message;
-
-  // Notifications have no id and must never be answered.
-  const isNotification = id === undefined || id === null;
-
-  switch (method) {
-    case "initialize":
-      return reply(id, {
-        protocolVersion: PROTOCOL_VERSION,
-        capabilities: { tools: {} },
-        serverInfo: SERVER_INFO,
-      });
-
-    case "notifications/initialized":
-    case "notifications/cancelled":
-      return;
-
-    case "ping":
-      return reply(id, {});
-
-    case "tools/list":
-      return reply(id, { tools: TOOLS });
-
-    case "tools/call": {
-      const name = params?.name;
-      try {
-        if (name === "team_list") return reply(id, await callTeamList());
-        if (name === "team_ask") return reply(id, await callTeamAsk(params?.arguments ?? {}));
-        if (name === "team_tell") return reply(id, await callTeamTell(params?.arguments ?? {}));
-        if (name === "vault_search") return reply(id, await callVaultSearch(params?.arguments ?? {}));
-        if (name === "vault_ask") return reply(id, await callVaultAsk(params?.arguments ?? {}));
-        return replyError(id, -32602, `Unknown tool: ${name}`);
-      } catch (err) {
-        // A thrown handler must not kill the server; report it as a failed tool call.
-        return reply(id, errorText(`popover failed: ${err?.message ?? String(err)}`));
-      }
-    }
-
-    default:
-      if (!isNotification) replyError(id, -32601, `Method not found: ${method}`);
-      return;
-  }
-}
-
-let buffer = "";
-process.stdin.setEncoding("utf8");
-process.stdin.on("data", (chunk) => {
-  buffer += chunk;
-  let idx = buffer.indexOf("\n");
-  while (idx !== -1) {
-    const line = buffer.slice(0, idx).trim();
-    buffer = buffer.slice(idx + 1);
-    if (line) {
-      let message;
-      try {
-        message = JSON.parse(line);
-      } catch {
-        idx = buffer.indexOf("\n");
-        continue;
-      }
-      void handle(message);
-    }
-    idx = buffer.indexOf("\n");
-  }
-});
-
-process.stdin.on("end", () => process.exit(0));
-process.on("uncaughtException", () => {});
+#!/usr/bin/env node
+// Popover MCP server — lets an agent see and ask its teammates' agents.
+//
+// Implemented directly against the JSON-RPC stdio protocol rather than the MCP SDK. The
+// plugin is distributed through a marketplace and installed into a cache directory where
+// dependency installation is conditional and can fail; a server with zero dependencies
+// simply cannot fail that way. The protocol surface we need is small — initialize,
+// tools/list, tools/call — so the SDK buys us little here.
+//
+// All real work happens in the daemon. This process is a thin bridge to it.
+
+import { readFileSync } from "node:fs";
+import { callerSessionId, request } from "../scripts/_ipc.mjs";
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+// Read from the plugin manifest, which Claude Code copies into its cache alongside this
+// file — so the relative path survives the severing copy that breaks everything else.
+const SERVER_INFO = {
+  name: "popover",
+  version: JSON.parse(
+    readFileSync(new URL("../.claude-plugin/plugin.json", import.meta.url), "utf8"),
+  ).version,
+};
+
+
+const TOOLS = [
+  {
+    name: "team_list",
+    description:
+      "List your teammates' currently-active Claude Code agents in THIS repo: who owns " +
+      "each one, what it is doing right now, and its short handle (e.g. B1). Only agents " +
+      "working in the same repository as you are visible — agents your teammates are " +
+      "running in other repos are not listed and cannot be asked. Use this before " +
+      "team_ask to find out which agent to ask. Read-only.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: true, title: "List team agents" },
+  },
+  {
+    name: "team_ask",
+    description:
+      "Ask a teammate's Claude Code agent a question and wait for the answer. A " +
+      "read-only copy of that agent answers from its full accumulated context; the " +
+      "teammate's live session is never interrupted or modified. Use this when a " +
+      "teammate's agent already knows something that would take you a long time to " +
+      "work out — why a decision was made, what they already ruled out, how a service " +
+      "they own behaves. Only agents working in the same repository as you can be asked. " +
+      "Answering costs the teammate tokens and takes up to ~90s, so ask one well-formed " +
+      "question rather than several exploratory ones.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description:
+            "Which agent to ask: a handle from team_list such as 'B1', or a teammate's " +
+            "name, or a repo name.",
+        },
+        question: {
+          type: "string",
+          description:
+            "A self-contained question. The answering agent has none of your " +
+            "conversation's context, so expand pronouns and vague references.",
+        },
+        timeout_seconds: {
+          type: "number",
+          description: "How long to wait for an answer. Default 90, max 300.",
+          minimum: 5,
+          maximum: 300,
+        },
+      },
+      required: ["target", "question"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true, title: "Ask a teammate's agent" },
+  },
+  {
+    name: "team_tell",
+    description:
+      "Send a short heads-up to a teammate's agent working in this repo. Unlike team_ask " +
+      "there is no answer: the message is delivered into that agent's context before its " +
+      "next prompt, and nothing comes back. Use it for facts about shared state that would " +
+      "otherwise cause a collision — \"the migration is applied on prod\", \"I am rewriting " +
+      "globals.css, leave it alone\". Do not use it to give another agent instructions or " +
+      "assign it work: the receiving agent is told to treat your message as information " +
+      "from outside its conversation, not as a directive, and its user is notified that you " +
+      "sent it. Only agents in the same repository can be told, and you are limited to 10 " +
+      "messages an hour to any one agent.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description:
+            "Which agent to tell: a handle from team_list such as 'B1', or a teammate's " +
+            "name, or a repo name.",
+        },
+        message: {
+          type: "string",
+          description:
+            "The heads-up, in one or two sentences. It arrives with no context of its own, " +
+            "so name the thing you are talking about rather than referring to it.",
+        },
+      },
+      required: ["target", "message"],
+      additionalProperties: false,
+    },
+    // Not read-only: this writes into someone else's context and notifies a person.
+    annotations: { readOnlyHint: false, openWorldHint: true, title: "Tell a teammate's agent" },
+  },
+  {
+    name: "vault_search",
+    description:
+      "Search your team's vaults. A vault is a conversation somebody on your team froze " +
+      "deliberately and published: it does not expire, it is not a live session, and its " +
+      "author does not have to be online — or still at the company — for you to use it. " +
+      "This searches the index only. It is free, it runs no model, it resumes nothing, and " +
+      "it costs neither you nor anybody else a token, so use it freely. Each result carries " +
+      "the questions that vault says it can answer, when it was frozen, who froze it, and " +
+      "how much of the code it discussed has changed since — a vault whose files nobody has " +
+      "touched is current however old it is, and one whose files have churned is suspect " +
+      "even if it is recent. Unlike team_list this is not limited to agents in your repo or " +
+      "to people who are working right now: every vault on every team you belong to is " +
+      "searchable. ALWAYS call this before vault_ask, and read what comes back: asking is " +
+      "the expensive half and this is how you spend it on the right vault.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description:
+            "What you want to know, phrased as a question. Vaults are indexed by the " +
+            "questions they can answer rather than by a summary, so a question matches far " +
+            "better than keywords do. Omit it to list the most recently frozen vaults.",
+        },
+        repo: {
+          type: "string",
+          description:
+            "Narrow to one repo label. Display-level filtering only — vaults are visible " +
+            "across every repo your team works in, so leave this off unless the user asked " +
+            "for one repo specifically.",
+        },
+        limit: {
+          type: "number",
+          description: "How many to return. Default 20, max 50.",
+          minimum: 1,
+          maximum: 50,
+        },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true, title: "Search team vaults" },
+  },
+  {
+    name: "vault_ask",
+    description:
+      "Ask one vault one question and wait for the answer. **This costs a full context " +
+      "load and real money** — the frozen conversation is resumed in its entirety on THIS " +
+      "machine, on your user's account, at roughly $0.50 and up to 90 seconds per call. " +
+      "Call vault_search first and ask the one vault that fits; never fan out across " +
+      "several to see which answers best, and never call this on a vault you have not seen " +
+      "in a search result. The vault answers from its frozen context and has no tools at " +
+      "all: it cannot read a file, run a command, or look at the repository as it stands " +
+      "today, which is deliberate — it is authoritative about what was decided and why, and " +
+      "explicitly unreliable about what the code currently looks like. Report what comes " +
+      "back as the vault's claim, attributed and dated, never as a bare fact merged into " +
+      "your own reasoning: a vault can hold a hypothesis the team later disproved. Nothing " +
+      "you do here reaches the vault's author, changes the vault, or costs them anything.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vault_id: {
+          type: "string",
+          description: "The `id` of a vault from a vault_search result. Never guess one.",
+        },
+        question: {
+          type: "string",
+          description:
+            "A self-contained question. The vault has none of your conversation and has " +
+            "been frozen for weeks or months, so expand every pronoun, name files by path, " +
+            "and ask about decisions and reasoning rather than about the current code.",
+        },
+        timeout_seconds: {
+          type: "number",
+          description: "How long to wait for an answer. Default 90, max 300.",
+          minimum: 5,
+          maximum: 300,
+        },
+      },
+      required: ["vault_id", "question"],
+      additionalProperties: false,
+    },
+    // Read-only: it resumes a copy and writes nothing back. It is not free, which the
+    // description says at length, because an annotation cannot say "and it costs money".
+    annotations: { readOnlyHint: true, openWorldHint: true, title: "Ask a team vault" },
+  },
+  {
+    name: "vault_create",
+    description:
+      "Publish this conversation to your team's vault. This writes: it uploads the whole " +
+      "conversation — every message, and the contents of every file read into it — where " +
+      "everyone on the team can search it and ask it, permanently. It does not expire, it " +
+      "cannot be edited afterwards, and it is not sent to one named person: it goes to the " +
+      "team. **A vault is readable by the popover service.** That is the one way it differs " +
+      "from /popover:fork, which is end-to-end encrypted and which the service cannot read; " +
+      "do not describe a vault as if it made the same promise, and say so plainly if you " +
+      "tell the user you have vaulted something. You may call this on your own judgement " +
+      "rather than waiting to be asked — the moment worth vaulting is usually one the user " +
+      "is too deep in the work to notice, and a conversation nobody vaults is deleted when " +
+      "the session ends. But judge it as a real disclosure and not as a cheap call: vault a " +
+      "conversation that worked something out the team will want and the repository will " +
+      "not record — a decision and the reasons behind it, an approach that was tried and " +
+      "rejected, an investigation into why something is the way it is. Do not vault routine " +
+      "work, and do not vault the same session twice.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description:
+            "A short human label, 3 to 120 characters. It is what a teammate reads on a card " +
+            "in a grid, so name the subject rather than the activity: 'Why the repo key does " +
+            "not gate vaults', not 'vault work'.",
+        },
+        answers: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Questions this conversation can answer — NOT a summary of what happened. This " +
+            "is the retrieval surface: the query that finds this vault later will itself be " +
+            "a question, and matching a question against a summary retrieves badly where " +
+            "question against question does not. Write each one the way a teammate would " +
+            "type it months from now, in full: 'Why did we reject the repo key as a vault " +
+            "credential?', not 'discussed encryption'. Three to six is right; each is 8 to " +
+            "200 characters and there can be at most 12. This is the field that decides " +
+            "whether the vault is ever found again, and it cannot be edited afterwards.",
+          minItems: 1,
+          maxItems: 12,
+        },
+        name: {
+          type: "string",
+          description:
+            "Optional slug, lowercase letters, digits and hyphens. It appears in URLs and in " +
+            "the command teammates type. Derived from the title when omitted, which is " +
+            "usually right — pass one only when the title makes an awkward slug or when a " +
+            "name collision has been reported.",
+        },
+      },
+      required: ["title", "answers"],
+      additionalProperties: false,
+    },
+    // Not read-only, and the only vault tool that is not. This publishes a conversation to a
+    // whole team, permanently, and there is no edit and no undo — `archive` retires a vault
+    // without erasing the record that it was made.
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: true,
+      title: "Publish this conversation to the team",
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Tool implementations
+// ---------------------------------------------------------------------------
+
+async function callTeamList() {
+  // Sent so the daemon can mark which line is this agent's own, and so it can scope the
+  // roster to the repo this session is working in. Absent outside a session, in which case
+  // the roster comes back unmarked rather than failing.
+  const reply = await request(
+    {
+      t: "roster",
+      id: rpcId(),
+      refresh: true,
+      ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+      // Fallback for the narrow window where the daemon has not seen this session yet. The
+      // session is authoritative when known; this is only ever consulted when it is not.
+      cwd: process.cwd(),
+    },
+    { timeoutMs: 15000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "roster.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  if (!reply.entries || reply.entries.length === 0) {
+    // The daemon's own text, because only it knows whether the answer is "nobody on your
+    // team is working" or "nobody is working in this repo" — and those lead a model to say
+    // very different things.
+    return text(
+      reply.rendered ||
+        "No teammates currently have active Claude Code sessions. Nobody is available to ask right now.",
+    );
+  }
+  // Returned as text rather than structuredContent on purpose: setting
+  // structuredContent suppresses text blocks, and the rendered table is both easier for
+  // the model to read and directly presentable to the user.
+  return text(reply.rendered);
+}
+
+async function callTeamAsk(args) {
+  const target = typeof args?.target === "string" ? args.target.trim() : "";
+  const question = typeof args?.question === "string" ? args.question.trim() : "";
+
+  if (!target) return errorText("`target` is required — call team_list to see the options.");
+  if (!question) return errorText("`question` is required.");
+
+  const timeoutSeconds = clamp(Number(args?.timeout_seconds) || 90, 5, 300);
+
+  const reply = await request(
+    {
+      t: "ask",
+      id: rpcId(),
+      req: {
+        target,
+        question,
+        timeoutSeconds,
+        // Lets the audit log show that an agent asked, not a human, and scopes the target
+        // to this session's repo.
+        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+      },
+      cwd: process.cwd(),
+    },
+    // Outlast the daemon's own wait so its specific error wins over a generic timeout.
+    { timeoutMs: timeoutSeconds * 1000 + 15000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "ask.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  const { answer } = reply;
+  const by = answer.answeredBy;
+  const attribution = by ? `${by.handle} (${by.ownerName}, ${by.repo})` : "a teammate's agent";
+  const cost =
+    answer.costUsd != null && answer.durationMs != null
+      ? `\n\n_(answered in ${(answer.durationMs / 1000).toFixed(1)}s, cost $${answer.costUsd.toFixed(3)} on their account)_`
+      : "";
+
+  return text(`Answer from ${attribution}:\n\n${answer.answer}${cost}`);
+}
+
+async function callTeamTell(args) {
+  const target = typeof args?.target === "string" ? args.target.trim() : "";
+  const message = typeof args?.message === "string" ? args.message.trim() : "";
+
+  if (!target) return errorText("`target` is required — call team_list to see the options.");
+  if (!message) return errorText("`message` is required.");
+
+  const reply = await request(
+    {
+      t: "tell",
+      id: rpcId(),
+      req: {
+        target,
+        message,
+        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+      },
+      cwd: process.cwd(),
+    },
+    { timeoutMs: 15000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "tell.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  // Says delivered-to, never read-by: a sender is deliberately told nothing about what
+  // happened to their message afterwards.
+  return text(
+    `Sent to ${reply.handle} (${reply.ownerName}). It will reach that agent before its next ` +
+      `prompt; there is no reply.`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Vaults — the cheap half and the costly half, deliberately two tools
+// ---------------------------------------------------------------------------
+
+async function callVaultSearch(args) {
+  const query = typeof args?.query === "string" ? args.query.trim() : "";
+  const repo = typeof args?.repo === "string" ? args.repo.trim() : "";
+  const limit = clamp(Number(args?.limit) || 20, 1, 50);
+
+  const reply = await request(
+    {
+      t: "vaults",
+      id: rpcId(),
+      req: {
+        limit,
+        ...(query ? { query } : {}),
+        ...(repo ? { repo } : {}),
+      },
+      // Not a filter. The daemon uses it to diff each vault's files against the tree in front
+      // of you, which is what the staleness figure in each result is.
+      cwd: process.cwd(),
+    },
+    { timeoutMs: 20000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "vaults.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  const vaults = reply.vaults ?? [];
+  if (vaults.length === 0) {
+    return text(
+      query
+        ? `No vault on your teams answers anything like "${query}". Nothing was spent looking. ` +
+            "Do not call vault_ask — there is no vault to ask."
+        : "Your teams have not published any vaults yet.",
+    );
+  }
+
+  const lines = vaults.map((vault, index) => {
+    const facts = [
+      vault.authorLabel,
+      `frozen ${friendlyDate(vault.frozenAt)}`,
+      vault.repoLabel ? `repo ${vault.repoLabel}` : null,
+      vault.noteCount > 0 ? `${vault.noteCount} note${vault.noteCount === 1 ? "" : "s"}` : null,
+      describeStaleness(vault.staleness),
+    ].filter(Boolean);
+
+    const answers = (vault.answers ?? []).map((a) => `     - ${a}`).join("\n");
+    return (
+      `${index + 1}. ${vault.title}  (${vault.name})\n` +
+      `   id: ${vault.id}\n` +
+      `   ${facts.join(" · ")}\n` +
+      (answers ? `   Says it can answer:\n${answers}\n` : "")
+    );
+  });
+
+  return text(
+    `${vaults.length} vault${vaults.length === 1 ? "" : "s"} on your teams:\n\n` +
+      lines.join("\n") +
+      "\nThis search cost nothing. Asking one of these costs a full context load and real " +
+      "money on your user's account, so pick the single best fit — or none, if none of them " +
+      "claims to answer the question.",
+  );
+}
+
+async function callVaultAsk(args) {
+  const vaultId = typeof args?.vault_id === "string" ? args.vault_id.trim() : "";
+  const question = typeof args?.question === "string" ? args.question.trim() : "";
+
+  if (!vaultId) return errorText("`vault_id` is required — call vault_search to find one.");
+  if (!question) return errorText("`question` is required.");
+
+  const timeoutSeconds = clamp(Number(args?.timeout_seconds) || 90, 5, 300);
+
+  const reply = await request(
+    {
+      t: "vaultAsk",
+      id: rpcId(),
+      req: {
+        vaultId,
+        question,
+        timeoutSeconds,
+        // Carries the per-session budget. Without it the daemon cannot tell one agent asking
+        // six vaults from six agents asking one each.
+        ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+      },
+      cwd: process.cwd(),
+    },
+    // Outlast the daemon's own wait so its specific error wins over a generic timeout.
+    { timeoutMs: timeoutSeconds * 1000 + 15000 },
+  );
+
+  if (!reply) return errorText(daemonDownMessage());
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "vaultAsk.ok") return errorText("The popover daemon returned an unexpected response.");
+
+  const { answer } = reply;
+  // Attribution first, and not optional. A human reading a vault's answer supplies the
+  // skepticism unprompted; a model will not unless the format forces it, and a vault can hold
+  // a hypothesis the team later disproved.
+  const at = answer.gitSha ? ` at commit ${answer.gitSha}` : "";
+  const cost =
+    answer.costUsd != null && answer.durationMs != null
+      ? ` Answered in ${(answer.durationMs / 1000).toFixed(1)}s, cost $${answer.costUsd.toFixed(3)} on your own account.`
+      : "";
+
+  return text(
+    `The "${answer.title}" vault, frozen ${friendlyDate(answer.frozenAt)}${at}, says:\n\n` +
+      `${answer.answer}\n\n` +
+      `_(That is a frozen conversation, not the current code. Treat it as authoritative ` +
+      `about what was decided and why, and check anything it says about how the repository ` +
+      `looks today. Attribute it to the vault when you pass it on.${cost})_`,
+  );
+}
+
+/**
+ * Publish this conversation. The one tool here that writes something permanent.
+ *
+ * ## Why this is an IPC verb and not `popover vault create`
+ *
+ * The pipeline it drives is the CLI's, tested and unchanged — find the transcript, settle it,
+ * sanitize, collect touched paths, upload. The obvious implementation is therefore to spawn
+ * `popover vault create --json` and relay what it prints. It is not what happens, and the
+ * reason is Windows.
+ *
+ * `popover` on Windows is a `.cmd` shim, and Node refuses to spawn a `.cmd` without a shell.
+ * With `shell: true` the arguments are pasted into a `cmd.exe` command line, where `&`, `|`,
+ * `^` and `>` are operators — and every argument here is written by a model: a title, a list
+ * of questions, a slug. That is untrusted-input-into-a-shell, on the machine this is being
+ * built on, to save a wire format. The escape hatches are worse than the problem: locating the
+ * CLI's real `.js` inside the shim is guesswork about npm's layout, and hand-quoting for
+ * `cmd.exe` is a thing to get wrong quietly.
+ *
+ * So it goes over the pipe the other four tools already use. The daemon needs nothing new to
+ * be reachable, holds the device token already, and already POSTs to the vault routes; the
+ * shared decisions — `planVault`, `collectToolPaths`, `packBody` — moved into
+ * @popoverinstall/shared so the terminal and the daemon build byte-identical payloads. No
+ * child process, nothing to quote, and the same code path on every platform.
+ */
+async function callVaultCreate(args) {
+  const title = typeof args?.title === "string" ? args.title.trim() : "";
+  const name = typeof args?.name === "string" ? args.name.trim() : "";
+  const answers = Array.isArray(args?.answers)
+    ? args.answers.filter((a) => typeof a === "string" && a.trim()).map((a) => a.trim())
+    : [];
+
+  if (!title) return errorText("`title` is required — a vault needs a short human label.");
+  if (answers.length === 0) {
+    return errorText(
+      "`answers` is required, and it holds questions this conversation can answer rather " +
+        "than a summary of it. A vault with no questions is one nobody will ever find.",
+    );
+  }
+
+  // Never from the model. The session being frozen is the one this process belongs to, and a
+  // caller that could name any session could publish a conversation it was never part of.
+  const sessionId = callerSessionId();
+  if (!sessionId) {
+    return errorText(
+      "There is no Claude Code session here to vault. This tool freezes the conversation it " +
+        "is running inside, and outside a session there is nothing to freeze.",
+    );
+  }
+
+  const reply = await request(
+    {
+      t: "vaultCreate",
+      id: rpcId(),
+      req: { sessionId, title, answers, ...(name ? { name } : {}) },
+      // Where git runs: it decides the recorded commit and the uncommitted half of the
+      // touched-path list. Not a filter, and never a permission.
+      cwd: process.cwd(),
+    },
+    // Generous: the daemon waits for the transcript to stop moving, runs git, and then
+    // uploads a whole gzipped conversation, which is megabytes rather than bytes.
+    { timeoutMs: 60000 },
+  );
+
+  // Not `daemonDownMessage()`. Silence here has a second cause the other tools do not have:
+  // a daemon older than this plugin does not know the verb, and drops a request its schema
+  // refuses without answering it. Telling somebody to start a daemon that is already running
+  // sends them after the wrong problem, so both possibilities are named and neither is
+  // asserted. Nothing was published either way — the upload is the last thing that happens.
+  if (!reply) {
+    return errorText(
+      "The popover daemon did not answer, so nothing was published. Either it is not " +
+        "running on this machine, or it is older than this plugin and does not know how to " +
+        "publish a vault. Run `popover doctor` to find out which, and `popover update` if it " +
+        "is the second.",
+    );
+  }
+  if (reply.t === "error") return errorText(explain(reply));
+  if (reply.t !== "vaultCreate.ok") {
+    return errorText("The popover daemon returned an unexpected response.");
+  }
+
+  const vault = reply.vault;
+  const answered = (vault.answers ?? []).map((a) => `  - ${a}`).join("\n");
+  const sha = vault.gitSha ? ` at commit ${vault.gitSha.slice(0, 7)}` : "";
+
+  return text(
+    `Published "${vault.title}" to your team as \`${vault.name}\`.\n\n` +
+      `${vault.entryCount} messages, frozen at the last completed turn ` +
+      `(${friendlyDate(vault.frozenAt)}${sha}). Nothing said from here is in it.\n\n` +
+      `It says it can answer:\n${answered}\n\n` +
+      `Anyone on the team can ask it, on their own machine and at their own cost:\n` +
+      `  popover vault ask ${vault.name} "…"\n\n` +
+      // Said every time, in the same register the CLI's confirmation uses. Anyone who has
+      // internalized /popover:fork being end-to-end will assume this is too, and it is not.
+      `Tell the user you did this, and tell them plainly that a vault is readable by the ` +
+      `popover service — a fork is end-to-end and this is not. It does not expire and cannot ` +
+      `be edited; \`popover vault archive ${vault.name}\` retires it without erasing the ` +
+      `record that it was made.`,
+  );
+}
+
+/** ISO timestamp to something a person reads, without pulling in a formatter. */
+function friendlyDate(iso) {
+  const at = new Date(iso);
+  if (Number.isNaN(at.getTime())) return iso;
+  const months = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
+  return `${at.getUTCDate()} ${months[at.getUTCMonth()]} ${at.getUTCFullYear()}`;
+}
+
+/**
+ * The staleness figure in words.
+ *
+ * Absent when the daemon had no working tree to diff against, or the vault recorded no paths.
+ * Silence is correct there: "0% changed" and "we could not check" are different claims, and
+ * only one of them is evidence that the vault is still current.
+ */
+function describeStaleness(staleness) {
+  if (typeof staleness !== "number") return null;
+  if (staleness === 0) return "none of its files have changed since";
+  return `${Math.round(staleness * 100)}% of its files have changed since`;
+}
+
+/**
+ * The daemon's own words for a failure, plus whatever it said to do about it.
+ *
+ * `hints` arrives on refusals that have an answer — a title too short, a name already taken,
+ * a conversation over the size limit — and is relayed verbatim rather than summarised. Those
+ * sentences are the difference between a second attempt that works and one that fails
+ * identically, and they are written where the constraint is, which is not here.
+ */
+function explain(errorReply) {
+  const hints = Array.isArray(errorReply.hints) ? errorReply.hints.filter(Boolean) : [];
+  const said = describe(errorReply);
+  return hints.length ? `${said}\n\n${hints.join("\n")}` : said;
+}
+
+function describe(errorReply) {
+  switch (errorReply.code) {
+    // The daemon knows whether credentials are missing or merely unusable; relaying its
+    // message avoids telling an already signed-in user to sign in again.
+    case "not_authenticated":
+    case "target_offline":
+    case "unknown_target":
+    case "timeout":
+    case "fork_failed":
+    case "bad_request":
+      return errorReply.message;
+    // A vault that is gone is gone: they are never edited and never expire, so this means the
+    // id was wrong or it has been archived. Retrying it, or trying a neighbouring id, cannot
+    // help — searching again can.
+    case "vault_not_found":
+      return `${errorReply.message} Call vault_search again rather than trying another id.`;
+    case "cloud_unreachable":
+      return `Could not reach the popover backend: ${errorReply.message}`;
+    default:
+      return errorReply.message || "The request failed.";
+  }
+}
+
+function daemonDownMessage() {
+  return (
+    "The popover daemon is not running on this machine, so teammate agents are not " +
+    "reachable. Start it with `popover daemon start`, or run `popover doctor` to diagnose."
+  );
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC plumbing
+// ---------------------------------------------------------------------------
+
+function text(value) {
+  return { content: [{ type: "text", text: value }] };
+}
+
+function errorText(message) {
+  // isError tells the model the call failed while still handing it a readable reason,
+  // which is far more useful than a transport-level error.
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+function clamp(n, lo, hi) {
+  return Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : lo;
+}
+
+let counter = 0;
+function rpcId() {
+  counter += 1;
+  return `mcp-${process.pid}-${counter}`;
+}
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+async function handle(message) {
+  const { id, method, params } = message;
+
+  // Notifications have no id and must never be answered.
+  const isNotification = id === undefined || id === null;
+
+  switch (method) {
+    case "initialize":
+      return reply(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: SERVER_INFO,
+      });
+
+    case "notifications/initialized":
+    case "notifications/cancelled":
+      return;
+
+    case "ping":
+      return reply(id, {});
+
+    case "tools/list":
+      return reply(id, { tools: TOOLS });
+
+    case "tools/call": {
+      const name = params?.name;
+      try {
+        if (name === "team_list") return reply(id, await callTeamList());
+        if (name === "team_ask") return reply(id, await callTeamAsk(params?.arguments ?? {}));
+        if (name === "team_tell") return reply(id, await callTeamTell(params?.arguments ?? {}));
+        if (name === "vault_search") return reply(id, await callVaultSearch(params?.arguments ?? {}));
+        if (name === "vault_ask") return reply(id, await callVaultAsk(params?.arguments ?? {}));
+        if (name === "vault_create") return reply(id, await callVaultCreate(params?.arguments ?? {}));
+        return replyError(id, -32602, `Unknown tool: ${name}`);
+      } catch (err) {
+        // A thrown handler must not kill the server; report it as a failed tool call.
+        return reply(id, errorText(`popover failed: ${err?.message ?? String(err)}`));
+      }
+    }
+
+    default:
+      if (!isNotification) replyError(id, -32601, `Method not found: ${method}`);
+      return;
+  }
+}
+
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let idx = buffer.indexOf("\n");
+  while (idx !== -1) {
+    const line = buffer.slice(0, idx).trim();
+    buffer = buffer.slice(idx + 1);
+    if (line) {
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        idx = buffer.indexOf("\n");
+        continue;
+      }
+      void handle(message);
+    }
+    idx = buffer.indexOf("\n");
+  }
+});
+
+process.stdin.on("end", () => process.exit(0));
+process.on("uncaughtException", () => {});