@popoverinstall/cli 0.7.1 → 0.8.0

package/plugin/README.md

@@ -4,15 +4,23 @@ Installed into Claude Code; see the repo root README for the whole system.
 
 ```
 .claude-plugin/plugin.json   metadata only
-commands/team.md             the /team command
+commands/team.md             the /team command — the roster
+commands/ask.md              the /ask command
+commands/tell.md             the /tell command
 commands/fork.md             the /fork command
+skills/popover/SKILL.md      when to reach for any of them unprompted
 hooks/hooks.json             status feed (auto-discovered)
 .mcp.json                    bundled MCP server (auto-discovered)
 mcp/index.mjs                team_list + team_ask + team_tell, zero dependencies
 scripts/                     hook handlers, zero dependencies
 ```
 
-`/team` reaches the daemon through the MCP server. `/fork` deliberately does not: it shells
+`/team`, `/ask` and `/tell` are one command per thing spent — the roster costs nothing, an ask
+costs the teammate's tokens, a tell costs their attention. They were one command with a
+subword until 0.8.0, which put the cheapest and the most intrusive behind the same first word;
+`/team ask …` and `/team tell …` still work and say so once.
+
+They reach the daemon through the MCP server. `/fork` deliberately does not: it shells
 out to the `popover` binary instead, because opening a fork has to work for someone who is
 not signed in and may have no daemon running at all. That also means it adds nothing to the
 IPC protocol, and cannot regress asks, tells, or the roster.

package/plugin/commands/ask.md

@@ -0,0 +1,65 @@
+---
+description: Ask a teammate's agent a question and wait for the answer — it runs on their machine, at their cost
+# Quoted because an unquoted value starting with `[` is parsed as a YAML flow sequence,
+# which fails and silently drops EVERY field here, allowed-tools included.
+argument-hint: "[agent-handle] <question>"
+allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popover__team_ask, AskUserQuestion
+---
+
+# Ask a teammate's agent
+
+The user ran `/popover:ask`. Arguments, which may be empty: **$ARGUMENTS**
+
+Only agents working in **this repo** are reachable. A teammate running Claude Code in a
+different repository is neither listed nor askable, so "nobody to ask" means nobody else is
+working *here* — not that the team is idle. Say it that way if it comes up.
+
+## No arguments
+
+Call `mcp__plugin_popover_popover__team_list`, print what it returns **verbatim** in a fenced
+block, and show the form:
+
+`/popover:ask B1 why did you rule out redis?`
+
+Stop there. Do not ask anything on the user's behalf.
+
+## A handle and a question
+
+Call `mcp__plugin_popover_popover__team_ask` with:
+
+- `target`: the handle or name they used, exactly as typed
+- `question`: the rest of their message, as a **self-contained** question. The answering agent
+  has none of this conversation — it cannot see the file you are looking at or the error you
+  just read. Expand every pronoun and vague reference ("that bug" → "the token refresh bug in
+  the auth service"), name files by path, and say what the user is trying to do rather than
+  only what they want to know. One well-formed question, not three exploratory ones: you get
+  one round trip for the price.
+
+When the answer comes back, show it clearly attributed:
+
+> **B1** (Bob Chen, api-server): …answer…
+
+Then say how it bears on what you are working on, if it does.
+
+## A question with no handle
+
+Call `mcp__plugin_popover_popover__team_list` first. Then:
+
+- If exactly one agent plausibly fits, use it and say which one you chose and why.
+- If several fit, call `AskUserQuestion` with up to 4 of them as options (label = the handle,
+  description = owner, repo, and what it is doing). Then use the chosen one.
+- If none fit, say so and show the roster instead.
+
+## Rules
+
+- **Never invent a handle.** Only use ones `team_list` returned. A handle from earlier in this
+  conversation may since have gone out of scope; if the tool says it does not match, relay that
+  rather than guessing at another agent.
+- **One agent per question.** Never fan out across the roster to see who answers best.
+- An answer comes from a **read-only copy** of their session. Their live session is not
+  interrupted and cannot be modified by an ask. It costs the teammate tokens on their own
+  machine, and nothing else.
+- If the tool errors or times out, relay it plainly. Do not silently re-ask, and do not retry
+  a different agent unless the user asks.
+- If the user is trying to hand a colleague *work* rather than get an answer, say plainly that
+  popover does not do that — the copy that answers cannot act — and let them message the human.

package/plugin/commands/fork.md

@@ -110,7 +110,7 @@ asked for in as many words.
 - Never print a code the user has not seen; it is the entire credential and the decryption
   key for the conversation behind it.
 - A fork is one-way. If the user seems to want an answer rather than to hand over the whole
-  conversation, say that `/popover:team ask` is the cheaper thing and offer it instead.
+  conversation, say that `/popover:ask` is the cheaper thing and offer it instead.
 - Do not run `create` and then immediately `open` the result to "test" it. Every open counts
   against what the sharer sees, and the fork is already verified by the command exiting
   cleanly.

package/plugin/commands/team.md

@@ -1,87 +1,60 @@
 ---
-description: See your team's active Claude Code agents in this repo, ask one a question, or tell one something
-# Quoted because an unquoted value starting with `[` is parsed as a YAML flow sequence,
-# which fails and silently drops EVERY field here, allowed-tools included.
-argument-hint: "[ask|tell] [agent-handle] [question or message]"
+description: Show which of your teammates' Claude Code agents are active in this repo right now
+# No argument-hint: this command takes none. The ask/tell tools are still allowed below
+# because `/popover:team ask …` was the only form before 0.8.0 and is still carried out.
 allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popover__team_ask, mcp__plugin_popover_popover__team_tell, AskUserQuestion
 ---
 
 # Team agents
 
-The user ran `/popover:team`. Arguments, which may be empty: **$ARGUMENTS**
+The user ran `/popover:team`. Arguments, which are usually empty: **$ARGUMENTS**
 
-Only agents working in **this repo** are visible. A teammate running Claude Code in a
-different repository is neither listed nor reachable, so an empty roster means nobody else is
-working *here* — not that the team is idle. Say it that way if it comes up.
+This command shows the roster. Asking and telling are their own commands now — `/popover:ask`
+and `/popover:tell` — because they cost different things and deserve to be chosen, not reached
+by a subword.
 
-The first word of the arguments chooses what to do. Follow exactly one of these paths.
-
-## 1. No arguments — show the roster
+## The roster
 
 Call `mcp__plugin_popover_popover__team_list`, then print what it returns **verbatim** in a
 fenced block. Do not reformat it, re-sort it, or add agents that are not in it.
 
-Then add one short line showing both forms:
-`/popover:team ask B1 why did you rule out redis?` · `/popover:team tell B1 the migration is applied`
-
-Stop there. Do not ask or tell anything on the user's behalf.
-
-## 2. `ask <handle> <question>` — ask it and wait
-
-Call `mcp__plugin_popover_popover__team_ask` with:
-
-- `target`: the handle or name they used, exactly as typed
-- `question`: the rest of their message, as a self-contained question — the answering
-  agent has none of this conversation's context, so expand pronouns and vague references
-  ("that bug" → "the token refresh bug in the auth service")
+Only agents working in **this repo** are visible. A teammate running Claude Code in a different
+repository is neither listed nor reachable, so an empty roster means nobody else is working
+*here* — not that the team is idle. Say it that way; the tool's own text already knows the
+difference, so relay it rather than paraphrasing it into "your team is idle".
 
-When the answer comes back, show it clearly attributed:
+Then add one short line showing where to go next:
 
-> **B1** (Bob Chen, api-server): …answer…
+`/popover:ask B1 why did you rule out redis?` · `/popover:tell B1 the migration is applied`
 
-Then say how it bears on what you are working on, if it does. If the tool returns an
-error, relay it plainly — do not retry a different agent unless the user asks.
-
-## 3. `tell <handle> <message>` — send it, expect nothing back
-
-Call `mcp__plugin_popover_popover__team_tell` with:
-
-- `target`: the handle or name they used, exactly as typed
-- `message`: the rest of their message, made self-contained the same way — it arrives with
-  no context of its own, so name the thing rather than referring to it
-
-There is no answer. Confirm what was sent and to whom, in one line, and stop:
-
-> Told **B1** (Bob Chen): the repo_keys migration is applied on prod.
+Stop there. Do not ask or tell anything on the user's behalf.
 
-A tell is for facts about shared state that would otherwise cause a collision. If the user
-is trying to give another agent instructions or hand it work, say that a tell does not do
-that — the receiving agent is told to treat it as information rather than a directive — and
-offer to ask instead.
+## If they typed `ask` or `tell` anyway
 
-## 4. A question or message with no clear target — pick one
+`/popover:team ask …` and `/popover:team tell …` were the only forms before 0.8.0, so they are
+still muscle memory. Do not answer with a correction and nothing else — carry it out, then
+mention the shorter command once at the end in a single line. The user gets what they asked for
+and learns the new name.
 
-Call `mcp__plugin_popover_popover__team_list` first. Then:
+**`ask <handle> <question>`** — call `mcp__plugin_popover_popover__team_ask` with `target` set
+to the handle exactly as typed and `question` set to the rest, rewritten to stand alone: the
+answering agent has none of this conversation, so expand every pronoun and vague reference
+("that bug" → "the token refresh bug in the auth service") and name files by path. Show the
+answer attributed — `> **B1** (Bob Chen, api-server): …` — then say how it bears on the work in
+hand, if it does.
 
-- If exactly one agent plausibly fits, use it and say which one you chose and why.
-- If several fit, call `AskUserQuestion` with up to 4 of them as options (label = the
-  handle, description = owner, repo, and what it is doing). Then use the chosen one.
-- If none fit, say so and show the roster instead.
+**`tell <handle> <message>`** — call `mcp__plugin_popover_popover__team_tell` with `target` and
+`message`, made self-contained the same way. Nothing comes back; confirm in one line what was
+sent and to whom, and stop. A tell is information, not a directive — if the user is trying to
+hand over work, say so and offer an ask instead.
 
-If it is unclear whether the user meant to ask or to tell, prefer **ask** — it interrupts
-nobody and costs only the answering machine some tokens, whereas a tell puts text into a
-colleague's context and notifies them.
+If the tool errors or times out, relay it plainly rather than retrying or trying another agent.
 
 ## Rules
 
-- Never invent a handle. Only use ones `team_list` returned. A handle from earlier in this
-  conversation may since have gone out of scope; if the tool says it does not match, relay
-  that rather than guessing at another agent.
-- Asking costs the *teammate* money and runs on *their* machine. Telling costs their
-  attention and notifies them. One per request either way; do not fan out to several agents
-  unless explicitly asked.
-- An answer comes from a read-only copy of their session. Their live session is not
-  interrupted and cannot be modified by an ask.
-- A tell **is** delivered into their live session, before its next prompt. That is the one
-  thing in popover that reaches a running agent, so treat it as something the user should have
-  meant to do.
+- Never invent a handle. Only use ones `team_list` returned.
+- Asking costs the *teammate* money and runs on *their* machine. Telling costs their attention
+  and notifies them. One agent per request either way.
+- An answer comes from a read-only copy of their session. Their live session is not interrupted
+  and cannot be modified by an ask. A tell **is** delivered into their live session, before its
+  next prompt — that is the one thing in popover that reaches a running agent.

package/plugin/commands/tell.md

@@ -0,0 +1,66 @@
+---
+description: Send a short heads-up into a teammate's live session — no answer comes back, and they are notified
+# Quoted because an unquoted value starting with `[` is parsed as a YAML flow sequence,
+# which fails and silently drops EVERY field here, allowed-tools included.
+argument-hint: "[agent-handle] <message>"
+allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popover__team_tell, AskUserQuestion
+---
+
+# Tell a teammate's agent
+
+The user ran `/popover:tell`. Arguments, which may be empty: **$ARGUMENTS**
+
+A tell is the one thing in popover that reaches a **running** agent: it is delivered into a
+teammate's live session before its next prompt, and their user is notified. It costs a
+colleague's attention rather than their tokens, which is why it is its own command and why the
+bar for sending one is higher than for an ask.
+
+Only agents working in **this repo** are reachable.
+
+## No arguments
+
+Call `mcp__plugin_popover_popover__team_list`, print what it returns **verbatim** in a fenced
+block, and show the form:
+
+`/popover:tell B1 the repo_keys migration is applied on prod`
+
+Stop there. Do not send anything on the user's behalf.
+
+## A handle and a message
+
+Call `mcp__plugin_popover_popover__team_tell` with:
+
+- `target`: the handle or name they used, exactly as typed
+- `message`: the rest of their message, made **self-contained** — it arrives with no context of
+  its own, so name the thing rather than referring to it. One or two sentences.
+
+Nothing comes back. Confirm what was sent and to whom, in one line, and stop:
+
+> Told **B1** (Bob Chen): the repo_keys migration is applied on prod.
+
+## A message with no handle
+
+Call `mcp__plugin_popover_popover__team_list`, then **confirm the recipient with
+`AskUserQuestion` before sending** — up to 4 candidates, label = the handle, description =
+owner, repo, and what it is doing. Do this even when only one agent plausibly fits.
+
+Naming a handle is how the user says *which colleague to interrupt*; if they did not name one,
+that choice has not been made yet and it is not yours to make. This is the one place a tell
+differs from an ask, which may pick its own target because the only thing it spends is tokens.
+
+If none fit, show the roster instead. Never broadcast to several agents.
+
+## Rules
+
+- **What a tell is for:** facts about shared state that would otherwise cause a collision — a
+  migration you just applied, a branch you force-pushed, a file you are about to rewrite that
+  their agent is working in right now.
+- **What it is not for:** instructions or handing over work. The receiving agent is explicitly
+  told to treat the message as information rather than a directive. If the user is trying to
+  give another agent a task, say so and offer `/popover:ask` instead — or suggest they message
+  the human.
+- **Never invent a handle**, and do not fan out to several agents unless asked in as many words.
+- Rate limited to 10 messages an hour to any one agent, which is a hint about its intended
+  frequency. If the limit is hit, relay that rather than retrying.
+- If it is genuinely ambiguous whether the user meant to ask or tell, prefer **`/popover:ask`**
+  — it interrupts nobody.

package/plugin/scripts/announce-roster.mjs

@@ -37,8 +37,12 @@ try {
   // `refresh: false` is what makes the tight timeout survivable — this reads whatever the
   // daemon already has, so it costs one socket round trip and no network. A hook sitting
   // between a keystroke and the model must never be the thing that calls the cloud.
+  // `cwd` matters most here of anywhere: this fires on the first prompt of a session, which
+  // is exactly when the daemon may not yet have resolved that session's repo — and the line
+  // it prints claims the agents are "in this repo". Without the hint an unplaceable caller
+  // is scoped by recency across the whole machine, so the claim could be false.
   const reply = await request(
-    { t: "roster", id: "hook", refresh: false, fromSessionId: sessionId },
+    { t: "roster", id: "hook", refresh: false, fromSessionId: sessionId, cwd: process.cwd() },
     { timeoutMs: 250 },
   );
 

package/plugin/scripts/emit-event.mjs

@@ -13,6 +13,23 @@
 
 import { readStdin, sendFireAndForget } from "./_ipc.mjs";
 
+/*
+ * Stay silent inside a fork — the same guard deliver-messages.mjs and announce-roster.mjs
+ * carry, and for a sharper reason than either of them.
+ *
+ * A fork is a real Claude Code session with its own session id, and it runs the plugin's
+ * hooks like any other. Without this, every answered ask reported PreToolUse, PostToolUse and
+ * Stop for that throwaway session, and the daemon created a session for it — so every ask put
+ * a ghost agent on the team roster, in the answering machine's repo, that nobody could reach
+ * and that never went away until it was reaped.
+ *
+ * Worse, it poisoned attribution. `SessionStore.resolveCaller` infers who is calling from the
+ * highest `lastEventAt`, and a fork that has just finished answering is by construction the
+ * most recent thing to have emitted an event on this machine — so a tell sent moments after
+ * answering an ask was recorded as coming from the fork.
+ */
+if (process.env.CLAUDE_CODE_ENTRYPOINT === "popover-fork") process.exit(0);
+
 try {
   const raw = await readStdin();
   const payload = JSON.parse(raw);

package/plugin/scripts/ensure-daemon.mjs

@@ -12,6 +12,16 @@ import { daemonAddress, popoverHome, readStdin, request, sendFireAndForget } fro
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
+/*
+ * A fork has nothing to do here, and doing it is actively harmful.
+ *
+ * The daemon spawns forks itself, so a daemon demonstrably exists — and registering the
+ * fork's session id would put a ghost agent on the team roster for every ask answered. Same
+ * guard, same reason, as emit-event.mjs; see its header for what the ghost then does to
+ * attribution.
+ */
+if (process.env.CLAUDE_CODE_ENTRYPOINT === "popover-fork") process.exit(0);
+
 async function main() {
   const raw = await readStdin().catch(() => "");
   let payload = null;
@@ -22,7 +32,12 @@ async function main() {
   }
 
   const alive = await ping();
-  if (!alive) {
+  // `updateInProgress()` is the interlock, not an optimisation. `popover update` stops the
+  // daemon and hands npm up to five minutes to replace the global install; a daemon started
+  // in that window runs out of the tree being replaced and holds its files open, so npm's
+  // rename fails EPERM/EBUSY on Windows and the update aborts half-done. Every session on the
+  // machine runs this hook, so without the check one of them wins that race almost every time.
+  if (!alive && !updateInProgress()) {
     const entry = resolveDaemonEntry();
     if (entry) {
       launch(entry);
@@ -95,6 +110,31 @@ function resolveDaemonEntry() {
   return null;
 }
 
+/**
+ * Whether `popover update` is replacing the install tree right now.
+ *
+ * Written by `beginUpdateLock` in packages/cli/src/daemon-lock.ts, which holds the readable
+ * version of why this exists. Duplicated here rather than imported for the same reason
+ * `resolveDaemonEntry` duplicates its path: this file must resolve no imports beyond the ones
+ * it already has, because a hook that throws breaks every session on the machine. Keep the
+ * two in step.
+ *
+ * Every branch fails towards starting the daemon. A marker with no deadline, or one whose
+ * deadline has passed, is a crashed update rather than a running one, and refusing to start
+ * on that basis would leave a machine permanently without a daemon and nothing on screen to
+ * explain it. Only a marker that is present, readable and unexpired holds us back.
+ */
+function updateInProgress() {
+  try {
+    const file = path.join(popoverHome(), "update.lock");
+    if (!existsSync(file)) return false;
+    const deadline = Number(JSON.parse(readFileSync(file, "utf8")).deadline);
+    return Number.isFinite(deadline) && Date.now() < deadline;
+  } catch {
+    return false;
+  }
+}
+
 function launch(entry) {
   try {
     // Detached with stdio to a log file: the daemon must outlive this hook, this session,

package/plugin/scripts/roster.mjs

@@ -18,6 +18,11 @@ const reply = await request(
     id: "cli",
     refresh: true,
     ...(callerSessionId() ? { fromSessionId: callerSessionId() } : {}),
+    // Fallback for the window where the daemon has not yet resolved this session's repo —
+    // the same hint the MCP server sends. Without it an unplaceable caller falls through to
+    // pure recency across every session on the machine, so `/popover:team` run in one repo
+    // could print the roster for another, under a heading claiming it was this one.
+    cwd: process.cwd(),
   },
   { timeoutMs: 8000 },
 );

package/plugin/skills/popover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: popover
-description: Reach a teammate's Claude Code agent working in this same repo. Use when a question is about what a colleague decided, already ruled out, or is changing right now — why the code is the way it is when the repo does not say, whether work you are about to start is already in flight, or why something you did not touch is broken. Also covers handing this whole conversation to a teammate as a fork.
+description: "Judgment for reaching a teammate's Claude Code agent *without being asked to* — when it is worth spending their tokens, and which of /popover:team, /popover:ask, /popover:tell and /popover:fork fits. Nothing to invoke by hand: use it when a question turns on what a colleague decided, ruled out, or is changing right now — why the code is the way it is when the repo does not say, whether work about to start is already in flight, or why something nobody touched is broken."
 ---
 
 # popover
@@ -10,10 +10,21 @@ accumulated context you do not have: the alternatives they rejected, the constra
 forced an awkward shape, what they changed twenty minutes ago and have not pushed. popover
 lets you reach those agents.
 
-The reason this skill exists is that the moment to use popover rarely announces itself. The
+**This skill is not a command, and there is nothing here for a user to invoke.** The four
+commands are the things a user types:
+
+| | |
+| --- | --- |
+| `/popover:team` | who is working in this repo right now |
+| `/popover:ask` | one question to one agent, and you wait for the answer |
+| `/popover:tell` | a heads-up into a teammate's live session; nothing comes back |
+| `/popover:fork` | hand this whole conversation to a teammate |
+
+This file is the judgment around them: when reaching for one is worth it, which one fits, and
+what each one spends. It exists because the moment to use popover rarely announces itself. The
 user asks why something is the way it is, and the honest answer is that the repo does not
-record it — but a colleague's agent worked it out this morning. Nobody will type
-`/popover:team` for you. Noticing is your job.
+record it — but a colleague's agent worked it out this morning. Nobody will type `/popover:ask`
+for you. Noticing is your job.
 
 ## The three tools
 
@@ -139,7 +150,11 @@ The tools return errors as text; relay them rather than retrying with different
 
 ## The user-facing commands
 
-`/popover:team` and `/popover:fork` carry the full flows for when the user drives this
-explicitly, including how to present a roster and how to take delivery of a fork. Do not
-restate their steps here or work around them — when the user invokes a command, follow it.
-This skill is for the case where nobody invoked anything and you noticed the moment yourself.
+The four commands carry the full flows for when the user drives this explicitly — how to
+present a roster, how to word an ask, how to take delivery of a fork. Do not restate their
+steps here or work around them: **when the user invokes a command, follow that command.** This
+skill is for the other case, where nobody invoked anything and you noticed the moment yourself.
+
+When you act on your own, prefer naming the command you are standing in for — "I'll run the
+equivalent of `/popover:ask B1`" — so the user learns the surface they can drive directly next
+time.