@popoverinstall/cli 0.7.2 → 0.8.1

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

@@ -30,16 +30,30 @@ const sessionId = callerSessionId();
 
 try {
   // No stdin read at all. deliver-messages.mjs spends 150ms on the payload because a missed
-  // tell is a real loss; here the environment variable is enough, and 150ms would be a
-  // sixth of the whole budget.
+  // tell is a real loss; here the environment variable is enough, and 150ms of latency the
+  // user pays on every prompt buys nothing this cannot get for free.
   if (!sessionId) process.exit(0);
 
-  // `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.
+  // `refresh: false` means "do not force a refresh". It does NOT mean "do not use the
+  // network", which is what a comment here used to claim: the daemon caches a roster for 5s,
+  // and past that this call awaits a cloud fetch measuring ~355ms. Since a human types
+  // prompts minutes apart, nearly every one of these went to the cloud — so the 250ms budget
+  // this used to carry lost the race almost every time, failed open, and printed nothing. A
+  // hook that silently does not fire is indistinguishable from having no teammates, which is
+  // why it went unnoticed for a release.
+  //
+  // 2000ms is a ceiling on how long a *degraded* backend may hold up a prompt, not a target:
+  // the happy path is 2ms cached or ~355ms fetched. It must stay in step with
+  // ROSTER_HOOK_TIMEOUT_MS in @popoverinstall/shared, which this dependency-free script
+  // cannot import — packages/shared/test/roster-cache.test.ts fails if they drift.
+  //
+  // `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 },
-    { timeoutMs: 250 },
+    { t: "roster", id: "hook", refresh: false, fromSessionId: sessionId, cwd: process.cwd() },
+    { timeoutMs: 2000 },
   );
 
   // Daemon down, or signed out. Silence is right: the skill tells an agent how to read a

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
 
@@ -119,11 +130,19 @@ match, relay that instead of trying a different agent.
 
 A fork hands over **this entire conversation**, frozen, and the recipient continues it in
 their own session. Nothing comes back. That includes the contents of every file read into the
-context, so it is a far larger disclosure than an ask, and it is only ever something the user
-asks for in as many words — never something you suggest doing on their behalf and then do.
+context, so it is a far larger disclosure than an ask.
+
+**Creating one is the user's alone.** It happens when they ask for it in as many words, never
+on their behalf — and "that would be useful" is not a yes.
+
+Saying that a fork would fit is a different act from making one, and it is worth doing once.
+The moment for a fork is one the user is usually too deep in the work to notice: they are going
+off shift, or about to re-explain an hour of debugging to a colleague by hand, or trading asks
+back and forth on what was never really one question. Say so plainly, say what the fork would
+include, and leave it there. If they pass, do not raise it again.
 
 When the user wants an *answer* rather than to hand over the whole conversation, an ask is the
-cheaper and more private thing. Offer it.
+cheaper and more private thing. Offer that instead.
 
 ## When it does not work
 
@@ -139,7 +158,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.