primitive 1.72.2 → 1.73.0

package/README.md

@@ -1090,8 +1090,8 @@ with status `ok`, `warn`, `fail` or `skip`; `action` (`login`, `install_cli`,
 and the command exits 0 only when every check is ok or skipped. Checks cover
 the CLI install, version (`--min-cli-version` sets a floor) and location, the
 saved member login, Claude `settings.json`, Primitive's Claude SessionStart,
-SessionEnd and per-session receive hooks (each present once, pointing at this
-CLI, with stale copies from older installs removed), the Codex SessionStart hook
+SessionEnd and receive hooks (each present once, pointing at this CLI, with
+stale copies from older installs removed), the Codex SessionStart hook
 in `$CODEX_HOME/hooks.json` (repaired in place without moving any other hook,
 since Codex keys approvals by hook position, and reported as `warn` until the
 approval Codex recorded matches the hook's current hash), a managed block in
@@ -1100,11 +1100,25 @@ content) and `~/.omp/agent/AGENTS.md`, the bundled primitive-connect skill, and
 saved agent profiles that were disconnected in Primitive (moved aside locally;
 nothing changes server side).
 
-`claude.hook.stop` names every per-session receive hook a repair would change
-in `items: [{profile, session, hook, state}]`, where `hook` is the Claude event
+Claude receives mail through one shared set of receive hooks per config
+directory (`Stop`, `SessionStart` on resume, and `PostToolUse`). Each run reads
+the session id from the hook input and looks up the profiles that session
+receives as in `<config>/agent-connections/claude-sessions/<session>.json`,
+which `agent connect`, `agent enroll` and `agent session-register` write and
+`agent disconnect` and `agent session-end` remove from. A session with no
+entry exits at once, so the hooks cost almost nothing in unrelated sessions.
+Earlier versions wrote one exact-session hook set per session; registering a
+session, connecting, or `machine doctor --fix` folds every such hook for the
+config directory into the shared set (recording its profile as a receiver)
+and drops hooks for profiles that are no longer connected. Hooks of other
+tools and of other config directories are left alone.
+
+`claude.hook.stop` names every receive hook a repair would change in
+`items: [{profile, session, hook, state}]`, where `hook` is the Claude event
 (`Stop`, `SessionStart` or `PostToolUse`) and `state` is `missing`, `stale`,
-`duplicate`, `outdated` or `old_address`; `profile` and `session` are null for
-hooks written by old CLI versions that did not record them. After `--fix` it
+`duplicate`, `outdated`, `old_address` or `per_session` (an exact-session hook
+to fold into the shared set); `profile` and `session` are null for the shared
+hooks and for hooks written by old CLI versions that did not record them. After `--fix` it
 also reports `changes`, the same fields plus `action` (`added`, `removed` or
 `updated`), for each hook it changed. `--profile <name>` (repeatable, with
 `--fix`) limits those per-session hook changes to the named profiles; combine it
@@ -1123,11 +1137,11 @@ The SessionStart hook runs `primitive agent session-register --runtime claude --
 It gives the session an address once, named `<runtime>-<repository>`, using the
 saved member login, and only re-verifies on resume; a session whose agent was
 disconnected or removed never gets a second address. The SessionEnd hook runs
-`primitive agent session-end`, which marks the session ended and removes its
-exact-session receive hooks, but keeps the agent's credential and profile, so
+`primitive agent session-end`, which marks the session ended and removes it
+from the receive hooks' session receivers, but keeps the agent's credential and profile, so
 closing a terminal does not cost the session its agent: resuming the session
-(for example `claude --resume <session>`) re-verifies the agent and reinstalls
-the hooks at the same address. Presence lapses on its own once the session
+(for example `claude --resume <session>`) re-verifies the agent and records it
+as the session's receiver again at the same address. Presence lapses on its own once the session
 stops running. Claude reports the same SessionEnd for a restart, a switch to
 another session and a real exit, so the hook waits five minutes first, and a
 start of the same session within that time cancels the end.
@@ -1348,6 +1362,23 @@ hooks print the same line as the live wake, including the load-the-skill line
 for verified mail (notices recorded by older CLI versions keep a shorter form
 with the same `to=` field and profile-selecting read command).
 
+Each email is announced to a session once. The hook that shows a notice first
+claims its id with `primitive listen pending --claim <email-id>`, under the
+profile's notice lock, so a Stop, resume or PostToolUse hook running at the
+same time skips it, and a later hook never repeats it, even when the session
+handled the mail without reading it through this CLI. The claimed ids are kept
+in `pending-mail-<session>.announced.json` next to the notices. A wake also
+reports the other mail the listener took meanwhile: after waking it keeps
+taking already queued mail for about a second and a half, and the hook lists
+every notice not yet announced with the wake's own line. A hook shows at most
+10 notices; a final line counts the rest, which the next hook announces. Past
+50 mail notices the oldest already announced one gives way to new mail; mail
+the session has not been shown is never dropped.
+
+`--timeout` bounds how long the listener waits for a delivery, not a delivery
+it already holds: that one is still handled and completed, so a short hook
+check never leaves a leased event to expire and count as a failed attempt.
+
 Mail in one thread is announced once, by its newest message. A message whose
 thread already has newer mail (`newer=` above zero) does not wake the session
 on its own: the listener moves on to the newer one, and wakes for the held

package/bin/claude-pending-mail.mjs

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import {
   existsSync,
@@ -24,18 +24,19 @@ const interactionPattern =
   /^(?:fyi|unknown|[a-z][a-z0-9._-]{0,63}\/[1-9][0-9]{0,3})$/;
 const relationships = ["owner", "member", "agent", "contact", "other"];
 const pollIntervalMs = 20_000;
-const announceIntervalMs = 60_000;
+/** The most notices one hook shows; the rest wait for the next hook. */
+export const SHOWN_LIMIT = 10;
 
 function profileDirectory(configDir, profile) {
   if (!profilePattern.test(profile)) return null;
   return join(resolve(configDir), "agent-connections", "profiles", profile);
 }
 
-function readJson(path) {
+function readJson(path, maxBytes = 65_536) {
   try {
     const stat = lstatSync(path);
     // A full pending list (mail cap plus status headroom) can pass 16 KiB.
-    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65_536)
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > maxBytes)
       return null;
     return JSON.parse(readFileSync(path, "utf8"));
   } catch {
@@ -134,7 +135,8 @@ const REPEAT_TICK = "repeat.tick/1";
  * A repeating message's tick that knows of newer mail in its thread is
  * superseded even when that newer tick has no notice yet, since the newer
  * one will arrive. Status notices and mail outside a thread are never
- * collapsed. A kept notice carries `covered`, how many it stands for.
+ * collapsed. A kept notice carries `covered`, how many it stands for, and
+ * `coveredIds`, their ids.
  * Order is kept, so the oldest remaining notice still comes first.
  */
 export function collapsePendingMail(notices) {
@@ -153,7 +155,10 @@ export function collapsePendingMail(notices) {
   const kept = notices.filter((notice, index) => {
     if (notice.kind === "status" || !notice.threadId) return true;
     if (newest.get(notice.threadId) !== index) {
-      covered.set(notice.threadId, (covered.get(notice.threadId) ?? 0) + 1);
+      covered.set(notice.threadId, [
+        ...(covered.get(notice.threadId) ?? []),
+        notice.emailId,
+      ]);
       return false;
     }
     return !(
@@ -164,7 +169,11 @@ export function collapsePendingMail(notices) {
   });
   return kept.map((notice) =>
     notice.kind !== "status" && notice.threadId && covered.get(notice.threadId)
-      ? { ...notice, covered: covered.get(notice.threadId) }
+      ? {
+          ...notice,
+          covered: covered.get(notice.threadId).length,
+          coveredIds: covered.get(notice.threadId),
+        }
       : notice,
   );
 }
@@ -334,17 +343,76 @@ function formatLiveMail(notice, receiver) {
   return `${skillFirst}Primitive mail arrived: ${notice.emailId}${recipientField(receiver.address)} from=${sender} relationship=${relationship} thread=${notice.threadId ?? "none"} in_thread=${notice.inThread ? "yes" : "no"} attachments=${notice.attachments ? "yes" : "no"}${newer}${interaction ? ` interaction=${interaction}` : ""}. Read with ${readCommand(notice.emailId, receiver.profile, receiver.cli)}.${interaction ? wakeSentence(interaction) : ""} ${authority}\n`;
 }
 
-export function clearDeliveredStatus(
-  cli,
+/**
+ * Ids already announced to the session, read without the writer lock (the
+ * CLI replaces the file atomically). The earlier repeat-timer file (version
+ * 1) also listed ids a hook selected but did not show past its first 10, so
+ * it proves nothing and is ignored: each of its notices is announced once
+ * more after an upgrade rather than possibly never.
+ */
+export function announcedPendingMail(configDir, profile, sessionId) {
+  const directory = profileDirectory(configDir, profile);
+  if (!directory || !uuid.test(sessionId)) return new Set();
+  const state = readJson(
+    join(directory, `pending-mail-${sessionId.toLowerCase()}.announced.json`),
+    262_144,
+  );
+  const ids =
+    state?.version === 2
+      ? state.ids
+      : state?.version === 1
+        ? state.times
+        : null;
+  return new Set(
+    ids && typeof ids === "object" && !Array.isArray(ids)
+      ? Object.keys(ids).map((id) => id.toLowerCase())
+      : [],
+  );
+}
+
+/**
+ * The notices this hook would show: those not yet announced, one per
+ * thread, at most SHOWN_LIMIT, leaving out `exclude` (a live wake's own
+ * email, announced by its own line). `ids` are what showing them claims: each
+ * shown notice and the older notices in its thread it stands for.
+ * `remaining` counts the unannounced notices left for a later hook.
+ */
+export function selectPendingMail(
   configDir,
   profile,
   sessionId,
   notices,
+  exclude = [],
 ) {
-  const ids = notices
-    .filter((notice) => notice.kind === "status")
-    .map((notice) => notice.emailId);
-  if (!ids.length) return;
+  const announced = announcedPendingMail(configDir, profile, sessionId);
+  const live = new Set(exclude);
+  // Threads are grouped with the live wake's own notice still in them, so
+  // the older mail it stands for is claimed with it rather than shown again.
+  const fresh = collapsePendingMail(
+    notices.filter((notice) => !announced.has(notice.emailId)),
+  );
+  const liveRows = fresh.filter((notice) => live.has(notice.emailId));
+  const others = fresh.filter((notice) => !live.has(notice.emailId));
+  const shown = others.slice(0, SHOWN_LIMIT);
+  return {
+    shown,
+    live: liveRows,
+    ids: [...liveRows, ...shown].flatMap((notice) => [
+      notice.emailId,
+      ...(notice.coveredIds ?? []),
+    ]),
+    remaining: others.length - shown.length,
+  };
+}
+
+/**
+ * Claim exact ids through the CLI, which takes the profile's writer lock, so
+ * each id is announced by one hook only. Returns the ids this call claimed,
+ * or null when the claim could not run (an older CLI, say); the caller then
+ * shows its notices anyway rather than risk never showing them.
+ */
+export function claimPendingMail(cli, configDir, profile, sessionId, ids) {
+  if (!ids.length) return new Set();
   const env = {
     ...process.env,
     PRIMITIVE_CONFIG_DIR: configDir,
@@ -352,55 +420,71 @@ export function clearDeliveredStatus(
   };
   delete env.PRIMITIVE_API_KEY;
   delete env.PRIMITIVE_KEY;
-  spawnSync(
-    process.execPath,
-    [
-      cli,
-      "listen",
-      "pending",
-      "--session",
-      sessionId,
-      ...ids.flatMap((id) => ["--clear", id]),
-    ],
-    {
-      env,
-      encoding: "utf8",
-      timeout: 8_000,
-      maxBuffer: 16_384,
-    },
-  );
+  try {
+    const result = spawnSync(
+      process.execPath,
+      [
+        cli,
+        "listen",
+        "pending",
+        "--session",
+        sessionId,
+        ...ids.flatMap((id) => ["--claim", id]),
+      ],
+      // PostToolUse hooks have 10 seconds in all: the mail check takes at
+      // most 5.5 and the claim 3, so a hook is never cut off after claiming
+      // notices it has not printed yet.
+      { env, encoding: "utf8", timeout: 3_000, maxBuffer: 262_144 },
+    );
+    if (result.status !== 0) return null;
+    const claimed = JSON.parse(result.stdout)?.claimed;
+    if (!Array.isArray(claimed)) return null;
+    return new Set(
+      claimed
+        .filter((id) => typeof id === "string" && uuid.test(id))
+        .map((id) => id.toLowerCase()),
+    );
+  } catch {
+    return null;
+  }
 }
 
-export function duePendingMail(configDir, profile, sessionId, notices) {
-  const directory = profileDirectory(configDir, profile);
-  if (!directory || !uuid.test(sessionId) || notices.length === 0) return [];
-  mkdirSync(directory, { recursive: true, mode: 0o700 });
-  const path = join(
-    directory,
-    `pending-mail-${sessionId.toLowerCase()}.announced.json`,
+/**
+ * Lines for the pending notices this hook claims, at most SHOWN_LIMIT, plus
+ * a count of those left for a later hook. `extraIds` (a live wake's own id)
+ * are claimed in the same call but not shown; `claimed` says which ids this
+ * hook won.
+ */
+export function announcePendingMail(
+  { cli, configDir, profile, address, sessionId, skillFile },
+  extraIds = [],
+) {
+  const { shown, live, ids, remaining } = selectPendingMail(
+    configDir,
+    profile,
+    sessionId,
+    readPendingMail(configDir, profile, sessionId),
+    extraIds,
   );
-  const state = readJson(path);
-  const previous =
-    state?.version === 1 && state.times && typeof state.times === "object"
-      ? state.times
-      : {};
-  const now = Date.now();
-  const due = notices.filter((notice) => {
-    const at = previous[notice.emailId];
-    return !Number.isFinite(at) || at > now || now - at >= announceIntervalMs;
-  });
-  if (due.length) {
-    const times = Object.fromEntries(
-      notices.map((notice) => [
-        notice.emailId,
-        due.some((item) => item.emailId === notice.emailId)
-          ? now
-          : (previous[notice.emailId] ?? now),
-      ]),
+  const wanted = [...new Set([...extraIds, ...ids])];
+  const claimed =
+    claimPendingMail(cli, configDir, profile, sessionId, wanted) ??
+    new Set(wanted);
+  const receiver = { profile, address, skillFile, cli };
+  const lines = [
+    // The live wake prints its own line; say which older mail it covers.
+    ...live
+      .filter((notice) => claimed.has(notice.emailId))
+      .map((notice) => coveredLine(notice)),
+    ...shown
+      .filter((notice) => claimed.has(notice.emailId))
+      .map((notice) => formatPendingMail(notice, receiver)),
+  ].filter(Boolean);
+  if (remaining > 0)
+    lines.push(
+      `${remaining} more pending ${remaining === 1 ? "message" : "messages"}; they are announced next.\n`,
     );
-    writeJson(path, { version: 1, times });
-  }
-  return due;
+  return { lines, claimed };
 }
 
 function pollDue(configDir, profile, sessionId) {
@@ -419,13 +503,8 @@ function pollDue(configDir, profile, sessionId) {
   return true;
 }
 
-function context(notices, receiver) {
-  if (notices.length === 0) return;
-  const lines = notices
-    .slice(0, 10)
-    .map((notice) => formatPendingMail(notice, receiver));
-  if (notices.length > 10)
-    lines.push(`${notices.length - 10} more pending messages.\n`);
+function context(lines) {
+  if (lines.length === 0) return;
   process.stdout.write(
     JSON.stringify({
       hookSpecificOutput: {
@@ -455,18 +534,130 @@ function tryLock(path) {
   return false;
 }
 
+/**
+ * The profiles a session receives as, from the config directory's session
+ * receivers (written when the session registers). Empty when it has none.
+ */
+export function readSessionReceivers(configDir, sessionId) {
+  if (!configDir || !uuid.test(sessionId ?? "")) return [];
+  const state = readJson(
+    join(
+      resolve(configDir),
+      "agent-connections",
+      "claude-sessions",
+      `${sessionId.toLowerCase()}.json`,
+    ),
+  );
+  if (
+    state?.version !== 1 ||
+    state.session_id !== sessionId.toLowerCase() ||
+    !Array.isArray(state.receivers)
+  )
+    return [];
+  return state.receivers.flatMap((row) =>
+    profilePattern.test(row?.profile ?? "") &&
+    addressPattern.test(row?.address ?? "")
+      ? [{ profile: row.profile, address: row.address.toLowerCase() }]
+      : [],
+  );
+}
+
+function runListener(cli, configDir, profile, address, sessionId) {
+  const env = {
+    ...process.env,
+    PRIMITIVE_CONFIG_DIR: configDir,
+    PRIMITIVE_AGENT_PROFILE: profile,
+    PRIMITIVE_HOOK_AGENT_ADDRESS: address.toLowerCase(),
+  };
+  delete env.PRIMITIVE_API_KEY;
+  delete env.PRIMITIVE_KEY;
+  return new Promise((done) => {
+    const child = spawn(
+      process.execPath,
+      [
+        cli,
+        "listen",
+        "--once",
+        "--wake",
+        "--hook-session",
+        "--events",
+        "email.received",
+        "--timeout",
+        "2",
+      ],
+      { env, stdio: ["pipe", "ignore", "ignore"] },
+    );
+    const timer = setTimeout(() => child.kill("SIGTERM"), 5_000);
+    child.once("error", () => {
+      clearTimeout(timer);
+      done();
+    });
+    child.once("close", () => {
+      clearTimeout(timer);
+      done();
+    });
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(
+      JSON.stringify({ hook_event_name: "Stop", session_id: sessionId }),
+    );
+  });
+}
+
+/**
+ * Claude Code stops a PostToolUse hook after 10 seconds. Mail checks run in
+ * parallel within 5 seconds; claims then run one profile at a time and none
+ * starts after this point, so a hook is never stopped between claiming
+ * notices and printing them. Notices left unclaimed go to the next hook.
+ */
+const CLAIM_CUTOFF_MS = 6_000;
+
+/**
+ * Start one profile's mail check after a tool call. Resolves with a release
+ * function once the check is done, or null when another hook holds it.
+ */
+async function checkProfile({ cli, configDir, profile, address, sessionId }) {
+  const directory = profileDirectory(configDir, profile);
+  if (!directory) return null;
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  writeJson(join(directory, `pending-mail-${sessionId}.fired.json`), {
+    version: 1,
+    at: new Date().toISOString(),
+  });
+  const lock = join(directory, `pending-mail-${sessionId}.lock`);
+  if (!tryLock(lock)) return null;
+  const release = () => {
+    try {
+      rmdirSync(lock);
+    } catch {
+      /* Fail open. */
+    }
+  };
+  try {
+    // A pending notice never stops the mail check: new mail keeps being
+    // fetched while an earlier notice waits to be read.
+    if (pollDue(configDir, profile, sessionId))
+      await runListener(cli, configDir, profile, address, sessionId);
+  } catch {
+    /* The claim below still runs. */
+  }
+  return release;
+}
+
 async function main() {
-  const [cli, configDir, profile, address, expectedSession, marker] =
-    process.argv.slice(2);
+  const args = process.argv.slice(2);
+  // The shared hook names only the CLI and config directory; a per-session
+  // hook from an earlier version also names its profile and session.
+  const shared = args.length === 3 && args[2] === "primitive-pending-mail-v2";
+  const [cli, configDir, profile, address, expectedSession, marker] = args;
   if (
-    marker !== "primitive-pending-mail-v1" ||
-    !cli ||
-    !configDir ||
-    !profilePattern.test(profile ?? "") ||
-    !addressPattern.test(address ?? "") ||
-    !uuid.test(expectedSession ?? "")
+    !shared &&
+    (marker !== "primitive-pending-mail-v1" ||
+      !profilePattern.test(profile ?? "") ||
+      !addressPattern.test(address ?? "") ||
+      !uuid.test(expectedSession ?? ""))
   )
     return;
+  if (!cli || !configDir) return;
   let raw = "";
   for await (const part of process.stdin) {
     raw += String(part);
@@ -478,79 +669,44 @@ async function main() {
   } catch {
     return;
   }
-  const sessionId = expectedSession.toLowerCase();
   if (
     input?.hook_event_name !== "PostToolUse" ||
     typeof input.session_id !== "string" ||
-    input.session_id.toLowerCase() !== sessionId
+    !uuid.test(input.session_id)
   )
     return;
-  const directory = profileDirectory(configDir, profile);
-  mkdirSync(directory, { recursive: true, mode: 0o700 });
-  writeJson(join(directory, `pending-mail-${sessionId}.fired.json`), {
-    version: 1,
-    at: new Date().toISOString(),
-  });
-  const lock = join(directory, `pending-mail-${sessionId}.lock`);
-  if (!tryLock(lock)) return;
+  const sessionId = input.session_id.toLowerCase();
+  if (!shared && sessionId !== expectedSession.toLowerCase()) return;
+  const receivers = shared
+    ? readSessionReceivers(configDir, sessionId)
+    : [{ profile, address }];
+  if (receivers.length === 0) return;
+  const started = Date.now();
+  const checks = await Promise.all(
+    receivers.map((receiver) =>
+      checkProfile({ cli, configDir, ...receiver, sessionId }).catch(
+        () => null,
+      ),
+    ),
+  );
+  const lines = [];
   try {
-    // A pending notice never stops the mail check: new mail keeps being
-    // fetched while an earlier notice waits to be read.
-    if (pollDue(configDir, profile, sessionId)) {
-      const env = {
-        ...process.env,
-        PRIMITIVE_CONFIG_DIR: configDir,
-        PRIMITIVE_AGENT_PROFILE: profile,
-        PRIMITIVE_HOOK_AGENT_ADDRESS: address.toLowerCase(),
-      };
-      delete env.PRIMITIVE_API_KEY;
-      delete env.PRIMITIVE_KEY;
-      spawnSync(
-        process.execPath,
-        [
+    receivers.forEach((receiver, index) => {
+      if (!checks[index] || Date.now() - started > CLAIM_CUTOFF_MS) return;
+      lines.push(
+        ...announcePendingMail({
           cli,
-          "listen",
-          "--once",
-          "--wake",
-          "--hook-session",
-          "--events",
-          "email.received",
-          "--timeout",
-          "2",
-        ],
-        {
-          input: JSON.stringify({
-            hook_event_name: "Stop",
-            session_id: sessionId,
-          }),
-          encoding: "utf8",
-          env,
-          timeout: 8_000,
-          maxBuffer: 16_384,
-        },
+          configDir,
+          ...receiver,
+          sessionId,
+          skillFile: claudeSkillFile(),
+        }).lines,
       );
-    }
-    const notices = collapsePendingMail(
-      readPendingMail(configDir, profile, sessionId),
-    );
-    if (notices.length) {
-      const due = duePendingMail(configDir, profile, sessionId, notices);
-      context(due, { profile, address, skillFile: claudeSkillFile(), cli });
-      clearDeliveredStatus(
-        cli,
-        configDir,
-        profile,
-        sessionId,
-        due.slice(0, 10),
-      );
-    }
+    });
   } finally {
-    try {
-      rmdirSync(lock);
-    } catch {
-      /* Fail open. */
-    }
+    for (const release of checks) release?.();
   }
+  context(lines);
 }
 
 if (