@popoverinstall/cli 0.9.0 → 0.10.0

package/plugin/scripts/nudge-vault.mjs

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+// Says out loud that a task just landed, at the moment it lands.
+//
+// The skill file carries the disposition — when you finish, vault before you report
+// completion (docs/vaults.md §3, and the standing rule in skills/popover/SKILL.md). Doctrine
+// alone loses to attention: an agent that has just spent forty turns building something is
+// thinking about the report it owes the user, not about an archive, and the moment §3 is
+// about is precisely the one you are too deep in the work to notice. This hook is the
+// reinforcement that arrives *at* the moment rather than in a paragraph read an hour earlier.
+//
+// It is registered synchronously on Stop and answers with
+// `hookSpecificOutput.additionalContext`, which Claude Code delivers as non-error feedback
+// that continues the conversation. That timing is the whole reason the script has this shape:
+//
+//   - `async: true` delivers `additionalContext` a model call late (measured). A nudge that
+//     lands one turn after completion arrives while the user is already asking about
+//     something else, which is where a signal goes to become noise. So this one is
+//     synchronous, and the existing async emit-event.mjs entry on Stop is left alone.
+//   - `Stop` does not fire when the turn was interrupted by the user — official behaviour,
+//     verified on 2.1.252. So the interrupted-turn exclusion is free, and there is
+//     deliberately no attempt here to detect interruption from the payload: there is no field
+//     for it, and inventing one would only produce a guess.
+//
+// What qualifies as "a task landed" is deliberately narrow: a machine-verifiable fact about
+// work that git has already recorded. Two tiers, and nothing else — a push, and behind it a
+// commit. Neither is inferred from the shape of the conversation, because the shape of a
+// conversation cannot carry that weight.
+//
+// A third tier was written, tested and cut, and it is worth knowing why before anyone adds it
+// back: files changed earlier in the session, and none changed this turn. That reads like a
+// task which has just finished, and it is exactly as much like the user stopping the agent to
+// ask a question — the turn after a burst of editing looks identical either way, and the
+// difference lives in the user's head where no hook can reach it. `Stop` firing tells you the
+// *turn* completed. It does not tell you the *task* did, and that gap is the whole distance
+// between the two tiers here and the one that is not. Cut outright rather than left behind a
+// flag: a branch nobody exercises rots, and git remembers the code.
+//
+// What it must never do, in the order the damage would be worst:
+//
+//   - Nudge on nothing. A line that fires when no task finished teaches the user, in one
+//     sitting, that the line means nothing — and after that the turn where it was right looks
+//     exactly like the turns where it was wrong. announce-roster.mjs records the same failure
+//     for the roster line and the same rule follows: silence beats a false positive, every
+//     time. Everything below that looks over-cautious is this.
+//   - Nudge twice for the same work. Deduped per session by what landed, not by time.
+//   - Break a session. Every path fails open: no git, no daemon, a wedged spawn, a malformed
+//     payload — exit 0, print nothing.
+//   - Spin the agent. `stop_hook_active` is true when Claude Code is already continuing
+//     because of a stop hook. Feeding it more context then is how you get a loop, so that
+//     case exits before doing any work at all.
+//   - Talk over a colleague. A message waiting for this session wins the turn
+//     (docs/messages.md §7) and this hook yields to it — without spending its dedupe key, so
+//     the nudge it swallowed comes back on the next turn.
+//
+// Every timeout inside is sized so that the worst case — slow stdin, a slow `git status`, a
+// tip lookup, a commit count and a degraded daemon, all in one turn — still adds up to less
+// than the 5-second timeout hooks.json gives it. Being killed by that timeout would only cost
+// a nudge, which is survivable, but it could also truncate the state file mid-write and cost
+// the session its baseline. The ordinary turn is one `git status` and nothing else.
+//
+// It does not vault anything and it holds no opinion about whether this conversation deserves
+// to be vaulted. That judgement is the agent's — §3 gives it the authority deliberately, and
+// a hook that decided for it would be an automatic disclosure wearing a nudge's clothes. The
+// job here is to put an accurate factual statement in front of the model and stop.
+
+import { spawnSync } from "node:child_process";
+import {
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import {
+  callerSessionId,
+  inboxWaitingSince,
+  popoverHome,
+  readStdin,
+  request,
+} from "./_ipc.mjs";
+
+// A fork answering a teammate's question must not be nudged to publish anything. It is a
+// throwaway session whose output goes back to whoever asked, its "completion" is answering
+// one question, and the repo it happens to run in is not its own — see the header of
+// emit-event.mjs for what forks running the plugin's hooks unguarded did to the roster.
+if (process.env.CLAUDE_CODE_ENTRYPOINT === "popover-fork") process.exit(0);
+
+/** At most this many nudges in one session, whatever lands. The wallpaper ceiling. */
+const MAX_NUDGES = 3;
+
+try {
+  // The payload is not optional here the way it is in deliver-messages.mjs:
+  // `stop_hook_active` exists only in it, and without that flag there is no loop guard. An
+  // unreadable payload therefore means silence.
+  const payload = JSON.parse(await readStdin(400));
+  const sessionId = payload?.session_id || callerSessionId();
+  const cwd = payload?.cwd || process.cwd();
+
+  if (sessionId) {
+    if (payload?.hook_event_name === "SessionStart") {
+      recordBaseline(sessionId, cwd);
+    } else if (!payload?.stop_hook_active) {
+      await onStop(sessionId, cwd);
+    }
+  }
+} catch {
+  // Fail open, always. A wedged hook at the end of every turn would be worse than no hook.
+}
+
+process.exit(0);
+
+/**
+ * Everything a Stop needs to decide, and then the state for the next one.
+ *
+ * Ordering matters: the tier is judged against the *previous* stop's state, and the new state
+ * is written afterwards whether or not anything was said. Two things have to be recorded even
+ * by a silent stop: that this session was once ahead of its upstream, which is one of the two
+ * routes to recognising a push, and which keys have already been nudged. Writing also keeps
+ * the file's mtime fresh, which is what the week-old sweep below prunes on.
+ */
+async function onStop(sessionId, cwd) {
+  const snap = snapshot(cwd);
+  if (!snap) return; // Not a git repo, no commits yet, or git took too long.
+
+  const state = readState(sessionId);
+  if (!state) {
+    // No baseline: the plugin was installed mid-session, the SessionStart hook failed, or
+    // POPOVER_HOME moved. Start the clock now and say nothing — a session whose beginning is
+    // unknown cannot honestly claim that anything advanced during it.
+    writeState(sessionId, freshState(snap, cwd));
+    return;
+  }
+
+  const next = {
+    ...state,
+    // Sticky: once this session has held an unpushed commit, the later disappearance of that
+    // gap is a push even if HEAD never moved — see classify().
+    wasAhead: state.wasAhead || snap.ahead > 0,
+  };
+
+  try {
+    // A waiting message outranks anything this hook has to say — docs/messages.md §7. The two
+    // do not share a budget (that hook injects on PostToolBatch, this one continues a Stop)
+    // but they compete for one turn, and the tie-break is not close: a vault nudge can wait,
+    // because its dedupe key is keyed on the commit and will fire again next turn, while a
+    // colleague blocked on a reply cannot.
+    //
+    // Note where this sits — inside the try, so the `finally` below still records `wasAhead`,
+    // and before classify(), so `nudged` is never appended to. Yielding must not cost the
+    // nudge its key; a yield that silently consumed it would turn "wait a turn" into "never".
+    if (inboxWaitingSince(sessionId) !== null) return;
+
+    const tier = classify(state, snap, cwd);
+    const already = state.nudged ?? [];
+    if (tier && !already.includes(tier.key) && already.length < MAX_NUDGES) {
+      if (await popoverUsable(sessionId, cwd)) {
+        emit(tier.text);
+        next.nudged = [...already, tier.key];
+      }
+    }
+  } finally {
+    writeState(sessionId, next);
+  }
+}
+
+/**
+ * Which of the two signals fired, stronger first, or null for silence.
+ *
+ * The order is not a preference, it is what the signals actually mean:
+ *
+ *   1. **A push landed.** The work has left the machine and become the team's, irreversibly,
+ *      and it is the moment teammates start meeting this code without this conversation
+ *      attached to it. Nothing else available to a hook is that unambiguous.
+ *   2. **A commit landed.** Real, but private and revertible, and as often a checkpoint as a
+ *      finish. Worth stating; not worth stating as completion.
+ *
+ * Both are facts git can be asked for and will answer the same way twice. There is no weaker
+ * rung under them, and silence is the default — the header records what used to be there and
+ * why it is not.
+ *
+ * The identity and timestamp tests exist to keep a `git pull` from reading as a push: a
+ * fast-forward advances HEAD and closes the gap to upstream exactly as a push does, and the
+ * only cheap thing that separates them is whose commit is at the tip and when it was made.
+ */
+function classify(state, snap, cwd) {
+  const advanced = Boolean(snap.head) && snap.head !== state.baseHead;
+
+  // Only spawn for the tip commit when a tier is actually in play. On an ordinary turn this
+  // whole function costs nothing beyond the one `git status` already taken.
+  const tip = advanced || state.wasAhead ? tipCommit(cwd) : null;
+
+  // Unknown identity on either side degrades to the timestamp test rather than blocking: a
+  // repo can be configured without user.email, and a hook that silently stops working
+  // because of a config gap is the failure announce-roster.mjs took a release to notice.
+  const identity =
+    tip?.email && state.email ? tip.email.toLowerCase() === state.email.toLowerCase() : null;
+  const ours = Boolean(tip) && identity !== false;
+  // 120s of slack for skew between the committer's clock and this process's.
+  const madeThisSession = ours && tip.at >= (state.startedAt ?? 0) - 120;
+
+  if (
+    snap.upstream &&
+    snap.ahead === 0 &&
+    snap.behind === 0 &&
+    ((advanced && madeThisSession) || (state.wasAhead && ours))
+  ) {
+    return { key: `push:${snap.head}`, text: pushText(state, snap, cwd) };
+  }
+
+  // A commit that is still local. `ahead > 0` is what keeps this from firing a second time on
+  // the same work after the push tier already has — and a repo with no upstream at all can
+  // never reach the push tier, so it qualifies here on its own.
+  if (advanced && madeThisSession && (!snap.upstream || snap.ahead > 0)) {
+    return { key: `commit:${snap.head}`, text: commitText(state, snap, cwd) };
+  }
+
+  return null;
+}
+
+/*
+ * The two statements.
+ *
+ * Written as statements on purpose. The hook docs warn that text reading as an injected
+ * system instruction can trip Claude's prompt-injection defences and be surfaced to the user
+ * as a suspicious string instead of acted on — which would turn a nudge into a support
+ * question. So each of these says what just happened and what exists, names the judgement as
+ * the agent's, and never issues an order. `additionalContext` is capped at 10,000 characters;
+ * both of these sit well under a thousand, and the shortness is also deliberate — the model
+ * has to read this at the end of a long turn.
+ */
+
+/**
+ * Shared closing. Both tiers need the same three facts: what the tool is, that the call is a
+ * judgement rather than a reflex, and that a conversation already vaulted needs nothing. The
+ * last sentence is the one announce-roster.mjs learned the hard way: without it the model
+ * reports the notice to the user as news.
+ *
+ * Deliberately short, and deliberately does not restate what is worth vaulting. That rule
+ * lives in the popover skill's `description`, which is in context on every turn of every
+ * session — so a second copy here would not be reaching an agent that lacked it, it would be
+ * a second place the rule has to be edited, and the two would drift the first time one of
+ * them changed. The disclosure that a vault is readable by the service is likewise already
+ * on `vault_create` itself, which an agent has necessarily read by the time it can call it.
+ * What this text is for is the part the skill cannot know: that it is being said now, and
+ * why now.
+ *
+ * A function and not a `const`, which is not a style choice. The top-level `await` that runs
+ * this script sits above every declaration down here, and a `const` read from inside it is in
+ * its temporal dead zone — so the first nudge threw a ReferenceError straight into the
+ * fail-open catch and the hook printed nothing, forever, in silence. Function declarations
+ * hoist; that is the whole difference, and it is the exact failure this file's fail-open
+ * posture is worst at showing you.
+ */
+function tail() {
+  return (
+    "popover's vault_create tool publishes this conversation to the team's archive, where " +
+    "anyone on the team can ask it once this session no longer exists. Whether this " +
+    "particular conversation is one of those is a judgement that is yours to make, on the " +
+    "standing rule you already carry, and a conversation already vaulted needs nothing " +
+    "further. This notice is only worth mentioning to the user if it turns out to be " +
+    "relevant."
+  );
+}
+
+function pushText(state, snap, cwd) {
+  const made = commitsSince(cwd, state.baseHead);
+  const what =
+    made > 0
+      ? `${made} commit${made === 1 ? "" : "s"} made in this session ` +
+        `${made === 1 ? "is" : "are"} now on ${snap.upstream}`
+      : `the commits this branch was holding are now on ${snap.upstream}`;
+
+  return (
+    `[popover] A push landed during this session: ${what}, with HEAD at ` +
+    `${short(snap.head)}. The work has left this machine and teammates encounter this code ` +
+    `from here on, while the reasoning behind it exists only in this conversation, which is ` +
+    `deleted when the session ends. docs/vaults.md §3 names this — the completion of a task ` +
+    `— as the moment a vault belongs to, and the standing rule in the popover skill is to ` +
+    `vault before reporting completion rather than after it. ${tail()}`
+  );
+}
+
+/**
+ * Two numbers, not one, and the second is why: the branch's ahead count alone was
+ * ambiguous. A branch can be carrying unpushed commits this session never made — a test run
+ * caught it reading "6 commits ahead" at a session that had made exactly one — and a nudge
+ * whose first factual clause overstates what just happened is the kind of thing an agent
+ * repeats to the user. So the session's own count leads and the branch's gap follows.
+ */
+function commitText(state, snap, cwd) {
+  const made = commitsSince(cwd, state.baseHead);
+  const mine =
+    made > 0
+      ? `${made} commit${made === 1 ? "" : "s"} made in this session`
+      : "a commit made in this session";
+  const where = snap.upstream
+    ? `${mine}, with the branch now ${snap.ahead} ahead of ${snap.upstream}`
+    : `${mine}, on a branch with no upstream to push to`;
+
+  return (
+    `[popover] A commit landed during this session: ${short(snap.head)} — ${where}. This ` +
+    `is a weaker signal than a push — a commit is private, revertible, and as often a ` +
+    `checkpoint as a finish — so it is stated as a fact and not as a claim that anything ` +
+    `is done. If the work is in fact done, this is the moment docs/vaults.md §3 is about: ` +
+    `your grasp of it is as good as it is going to get, and the user is about to move on. ` +
+    `${tail()}`
+  );
+}
+
+/** The one line of stdout this script is allowed to write. Anything else here is a bug. */
+function emit(additionalContext) {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: { hookEventName: "Stop", additionalContext },
+    })}\n`,
+  );
+}
+
+/**
+ * Is popover actually in a position to accept a vault right now?
+ *
+ * Checked because the alternative is telling an agent a tool is available when calling it
+ * will fail — and a nudge that leads straight into an error is worse than no nudge, since the
+ * agent then reports the failure to a user who never asked for any of this. `roster.ok`
+ * coming back means the daemon is up and the machine is signed in; anything else means it is
+ * not, or the backend is unreachable, and both are reasons to stay quiet. `local` was the
+ * cheaper candidate and is the wrong one: it answers without credentials by design.
+ *
+ * Paid only on a turn where a tier has already matched, which is at most three turns a
+ * session.
+ */
+async function popoverUsable(sessionId, cwd) {
+  const reply = await request(
+    { t: "roster", id: "hook", refresh: false, fromSessionId: sessionId, cwd },
+    { timeoutMs: 1200 },
+  );
+  return reply?.t === "roster.ok";
+}
+
+/**
+ * One `git status --porcelain=v2 --branch --untracked-files=no`, and the three facts both
+ * tiers need are all in its header: the HEAD sha, the upstream name, and the ahead/behind
+ * counts. `rev-parse HEAD`, `rev-parse @{u}` and a `rev-list` would cost three process spawns
+ * for the same thing, and on Windows a spawn is tens of milliseconds out of a budget that is
+ * spent at the end of every single turn.
+ *
+ * `--untracked-files=no` is what keeps that one spawn cheap. Hunting for untracked files is
+ * the expensive half of `git status` — a full walk of the working tree — and it was only ever
+ * here to fingerprint the dirty set for the tier that was cut. Nothing reads the file entries
+ * now, so they are not asked for. The call is still bounded and still gives up rather than
+ * holding up the end of a turn.
+ */
+function snapshot(cwd) {
+  const args = ["status", "--porcelain=v2", "--branch", "--untracked-files=no"];
+  const out = git(args, cwd, 1200);
+  if (out === null) return null;
+
+  const snap = { head: "", upstream: "", ahead: 0, behind: 0 };
+
+  for (const line of out.split("\n")) {
+    if (line.startsWith("# branch.oid ")) snap.head = line.slice(13).trim();
+    else if (line.startsWith("# branch.upstream ")) snap.upstream = line.slice(18).trim();
+    else if (line.startsWith("# branch.ab ")) {
+      const [a, b] = line.slice(12).trim().split(/\s+/);
+      snap.ahead = Math.abs(Number.parseInt(a, 10) || 0);
+      snap.behind = Math.abs(Number.parseInt(b, 10) || 0);
+    }
+  }
+
+  // `(initial)` before the first commit. Nothing here can advance from nothing.
+  if (!snap.head || snap.head === "(initial)") return null;
+
+  return snap;
+}
+
+/** Committer email and commit time of the tip, for the "is this ours, and is it new" test. */
+function tipCommit(cwd) {
+  const out = git(["log", "-1", "--format=%ce%n%ct"], cwd, 800);
+  if (out === null) return null;
+  const [email, at] = out.split("\n");
+  const seconds = Number.parseInt((at ?? "").trim(), 10);
+  if (!Number.isFinite(seconds)) return null;
+  return { email: (email ?? "").trim(), at: seconds };
+}
+
+/** How many commits this session added, for the push line. Zero is a legitimate answer. */
+function commitsSince(cwd, baseHead) {
+  if (!baseHead) return 0;
+  const out = git(["rev-list", "--count", `${baseHead}..HEAD`], cwd, 800);
+  const n = Number.parseInt((out ?? "").trim(), 10);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function localEmail(cwd) {
+  return (git(["config", "--get", "user.email"], cwd, 800) ?? "").trim();
+}
+
+/**
+ * git, with every way it can hurt a session closed off.
+ *
+ * `timeout` kills a spawn that hangs — a network-mounted repo or a stale index lock must not
+ * hold up the end of a turn. stderr is discarded rather than inherited, because a hook that
+ * prints git's complaints puts them in front of the user as if they were popover's.
+ */
+function git(args, cwd, timeoutMs) {
+  try {
+    const r = spawnSync("git", args, {
+      cwd,
+      timeout: timeoutMs,
+      encoding: "utf8",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (r.error || r.status !== 0 || typeof r.stdout !== "string") return null;
+    return r.stdout;
+  } catch {
+    return null;
+  }
+}
+
+function short(sha) {
+  return (sha ?? "").slice(0, 7);
+}
+
+/*
+ * Per-session state.
+ *
+ * Same shape as announce-roster.mjs's signature file and in the same directory, so there is
+ * one place to look and one thing to sweep. Per session rather than per machine because the
+ * whole question is "did this land during *this* session", and because a new session should
+ * get its own single nudge.
+ */
+function stateFile(id) {
+  return path.join(popoverHome(), "announced", `${id}.vault.json`);
+}
+
+function readState(id) {
+  try {
+    const state = JSON.parse(readFileSync(stateFile(id), "utf8"));
+    return state?.v === 1 ? state : null; // A future shape is ignored, not guessed at.
+  } catch {
+    return null;
+  }
+}
+
+function writeState(id, state) {
+  try {
+    mkdirSync(path.join(popoverHome(), "announced"), { recursive: true });
+    writeFileSync(stateFile(id), JSON.stringify(state), "utf8");
+  } catch {
+    // An unwritable state file means this session never nudges: every stop reads no baseline
+    // and starts the clock again. Degraded into silence, which is the right direction.
+  }
+}
+
+/**
+ * Six fields, and every one of them is read by classify() or by the dedupe. Kept that way
+ * deliberately: this file briefly carried a stop counter, two tree fingerprints and a
+ * `lastHead` that nothing consulted any more, and a state field which is written but never
+ * read is a claim about how the detector works that has quietly stopped being true.
+ */
+function freshState(snap, cwd) {
+  return {
+    v: 1,
+    startedAt: Math.floor(Date.now() / 1000),
+    email: localEmail(cwd),
+    baseHead: snap.head,
+    wasAhead: snap.ahead > 0,
+    nudged: [],
+  };
+}
+
+/**
+ * The session's starting line, taken at SessionStart so that a task finished in the very
+ * first turn is still detectable. Doing this lazily on the first Stop instead would make
+ * "commit and push this fix" — a whole task in one turn — the one shape that could never
+ * fire.
+ *
+ * An existing file is never overwritten. SessionStart also fires on resume and on compaction,
+ * and re-baselining there would move the starting line forward past the very commits it
+ * exists to notice.
+ */
+function recordBaseline(sessionId, cwd) {
+  if (readState(sessionId)) return;
+  const snap = snapshot(cwd);
+  if (!snap) return;
+  writeState(sessionId, freshState(snap, cwd));
+  sweepOldState();
+}
+
+/**
+ * Drop state files older than a week.
+ *
+ * announce-roster.mjs left this as a loose end — a session id is a uuid, nothing prunes the
+ * directory, and a heavy user accretes an entry per session forever. This sweeps both kinds,
+ * since they share the directory, once per session, on the one event already paying for a
+ * process spawn. It is still the second-best fix: the daemon knows when a session ends and
+ * could drop the file then, where this can only guess with a clock.
+ */
+function sweepOldState() {
+  const week = 7 * 24 * 60 * 60 * 1000;
+  try {
+    const dir = path.join(popoverHome(), "announced");
+    for (const name of readdirSync(dir)) {
+      const file = path.join(dir, name);
+      try {
+        if (Date.now() - statSync(file).mtimeMs > week) rmSync(file, { force: true });
+      } catch {
+        // Raced with another session, or not ours to delete. Leave it.
+      }
+    }
+  } catch {
+    // No directory yet, which is the common case on a first run.
+  }
+}