@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/collective/presence.mjs

@@ -23,10 +23,128 @@ import {
   readFileSync, unlinkSync, readdirSync, mkdirSync, existsSync,
 } from "node:fs";
 import { join, basename } from "node:path";
+import { execFileSync } from "node:child_process";
 import { writeJsonAtomic } from "../fs-atomic.mjs";
 
+// ---------------------------------------------------------------------------
+// Whose session is this? (the hook's owner, not the hook)
+// ---------------------------------------------------------------------------
+
+/**
+ * THE BUG THIS EXISTS FOR. `register()` defaults `pid` to `process.pid`, and
+ * the caller is a Claude Code HOOK (scripts/collective/hook-runner.mjs) — a
+ * node process that exits the moment it has written the record. `list()` then
+ * probes that pid, finds it dead, and reaps the record. So every interactive
+ * session on every machine registered itself and was deleted on the very next
+ * read: `who.mjs` said "No active Claude Code sessions" on a box with two of
+ * them open, and the "N other sessions active" digest line never fired. The
+ * presence registry was structurally empty from the day it shipped.
+ *
+ * The owner is up the process tree: hook → (a shell, sometimes) → the Claude
+ * Code / engine session that ran the hook. {@link owningSession} walks
+ * parents until it meets one, bounded, and reads its `--name` when it has one
+ * (a front door is `claude --name <first>-main`, a peer `--name <first>-<slug>`).
+ *
+ * `owningSession` is pure over an injected `readParent`; {@link readParentOf}
+ * is the `ps` reader. Fail-open: no owner found ⇒ `{pid:null}`, and `list()`
+ * treats an unknown pid as alive (liveness then rests on the heartbeat alone).
+ */
+
+/** Commands that ARE a session: Claude Code, an engine front door/peer, an engine run. */
+const OWNER_RE = /(^|\/|\s)claude(\s|$)|(^|\s)cohort-session:\S|\/lib\/engine\/cli\.mjs\s+(run|session)(\s|$)/;
+/** Claude Code's own infrastructure processes are never a session's owner. */
+const NOT_OWNER_RE = /\bbg-pty-host\b|\bbg-spare\b|(^|\s)claude\s+daemon\s+run\b/;
+
+/** `--name X` off a command line, or "". */
+export function sessionNameOf(command) {
+  const m = String(command || "").match(/(?:^|\s)--name(?:=|\s+)(\S+)/);
+  return m ? m[1] : "";
+}
+
+/**
+ * Walk parents from `startPid` to the session that owns it. PURE over
+ * `readParent(pid) → {ppid, command, elapsedSec?} | null`.
+ *
+ * `startedAt` is the OWNER PROCESS's start (its `ps etime`), when the reader
+ * supplies one: that is when the session opened, which is what a "since T"
+ * about it should mean — not the moment a hook last happened to write the
+ * record. `null` when the reader has no elapsed time.
+ *
+ * @param {number} startPid
+ * @param {(pid:number) => ({ppid:number, command:string, elapsedSec?:number}|null)} readParent
+ * @param {{maxHops?:number, now?:number}} [opts]
+ * @returns {{pid:number|null, name:string, command:string, startedAt:string|null}}
+ */
+export function owningSession(startPid, readParent, opts = {}) {
+  const maxHops = Number.isFinite(opts.maxHops) ? opts.maxHops : 8;
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  let pid = Number(startPid);
+  for (let hop = 0; hop < maxHops && Number.isFinite(pid) && pid > 1; hop++) {
+    let row = null;
+    try { row = readParent(pid); } catch { row = null; }
+    if (!row) break;
+    const cmd = String(row.command || "");
+    if (OWNER_RE.test(cmd) && !NOT_OWNER_RE.test(cmd)) {
+      const el = Number(row.elapsedSec);
+      const startedAt = Number.isFinite(el) && el >= 0 ? new Date(now - el * 1000).toISOString() : null;
+      return { pid, name: sessionNameOf(cmd), command: cmd.slice(0, 200), startedAt };
+    }
+    const ppid = Number(row.ppid);
+    if (!Number.isFinite(ppid) || ppid === pid) break;
+    pid = ppid;
+  }
+  return { pid: null, name: "", command: "", startedAt: null };
+}
+
+/**
+ * `ps etime` → seconds. The format is `[[dd-]hh:]mm:ss`; anything else is null.
+ * Exported for its test.
+ */
+export function parseElapsed(etime) {
+  const m = String(etime || "").trim().match(/^(?:(\d+)-)?(?:(\d+):)?(\d{1,2}):(\d{2})$/);
+  if (!m) return null;
+  const [, d, h, mi, s] = m;
+  return (Number(d || 0) * 86400) + (Number(h || 0) * 3600) + (Number(mi) * 60) + Number(s);
+}
+
+/** `ps` reader for {@link owningSession}: `{ppid, command, elapsedSec}` of one pid, or null. */
+export function readParentOf(pid) {
+  try {
+    const out = execFileSync("/bin/ps", ["-o", "ppid=,etime=,command=", "-p", String(pid)], { encoding: "utf8", timeout: 2000 });
+    const line = out.split("\n").map((l) => l.trim()).find(Boolean);
+    if (!line) return null;
+    const m = line.match(/^(\d+)\s+(\S+)\s+(.*)$/);
+    if (!m) return null;
+    const elapsedSec = parseElapsed(m[2]);
+    return { ppid: Number(m[1]), command: m[3], elapsedSec: elapsedSec === null ? undefined : elapsedSec };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The session that owns the CURRENT process (a hook). Starts at the parent —
+ * the hook itself is never the owner.
+ * @param {number} [fromPid] defaults to process.ppid
+ */
+export function resolveOwner(fromPid = process.ppid) {
+  return owningSession(fromPid, readParentOf);
+}
+
 const PRESENCE_REL = "state/collective/presence";
 const DEFAULT_STALE_SEC = 300;
+/**
+ * A record whose owner pid is KNOWN and ALIVE is not reaped for a stale
+ * heartbeat: the beat is a PostToolUse hook, so an open-but-idle interactive
+ * session stops beating after its last tool call and would otherwise vanish
+ * from every count five minutes later (and come back, re-registered, with a
+ * `startedAt` of "whenever the next beat happened"). Liveness for such a record
+ * is the pid probe. This cap is the one bound on that: a pid can be reused
+ * after a reboot, so a record that has not beaten in this long is reaped even
+ * if something answers at its pid. Two days is longer than any session a hook
+ * beats for and shorter than the gap in which a reused pid stays plausible.
+ */
+export const DEFAULT_IDLE_CAP_SEC = 48 * 3600;
 
 function presenceDir(agentRoot) {
   return join(agentRoot, PRESENCE_REL);
@@ -65,16 +183,26 @@ export function register(agentRoot, info = {}) {
   const path = join(dir, `${safeId(info.sessionId)}.json`);
   try {
     mkdirSync(dir, { recursive: true });
-    let startedAt = nowIso(info.nowMs);
+    // startedAt, in order of trust: the prior record's (a re-register keeps
+    // the original), then the OWNER PROCESS's start when the caller resolved
+    // one (a hook re-registering a session that lost its record still says
+    // when the session opened, not when this write happened), then now.
+    let startedAt = null;
     try {
       if (existsSync(path)) {
         const prev = JSON.parse(readFileSync(path, "utf8"));
         if (prev && prev.startedAt) startedAt = prev.startedAt;
       }
     } catch { /* ignore prior */ }
+    if (!startedAt && typeof info.startedAt === "string" && Number.isFinite(Date.parse(info.startedAt))) startedAt = info.startedAt;
+    if (!startedAt) startedAt = nowIso(info.nowMs);
     const rec = {
       sessionId: String(info.sessionId),
-      pid: Number.isFinite(info.pid) ? info.pid : process.pid,
+      // `null` is an honest "unknown owner" (the walk found nothing): list()
+      // then judges liveness by the heartbeat alone. Absent still means "me",
+      // which is right for a session registering itself, wrong for a hook —
+      // hooks pass what resolveOwner() found.
+      pid: info.pid === null ? null : Number.isFinite(info.pid) ? info.pid : process.pid,
       cwd: info.cwd || "",
       repo: info.repo || (info.cwd ? basename(info.cwd) : ""),
       agentName: info.agentName || "",
@@ -125,7 +253,14 @@ export function deregister(agentRoot, sessionId) {
  * entries as a side effect. Newest-heartbeat first.
  *
  * @param {string} agentRoot
- * @param {object} [opts] - { staleSec, nowMs, reap=true }
+ * THE RULE. A record with a KNOWN pid lives exactly as long as that pid does
+ * (bounded by `idleCapSec`, see {@link DEFAULT_IDLE_CAP_SEC}); a record with
+ * an UNKNOWN pid (`null` — the owner walk found nothing) lives as long as its
+ * heartbeat is within `staleSec`. The heartbeat is a tool-use hook, so it is
+ * evidence of activity, not of existence — and "is this session open" is the
+ * existence question.
+ *
+ * @param {object} [opts] - { staleSec, idleCapSec, nowMs, reap=true }
  * @returns {object[]}
  */
 export function list(agentRoot, opts = {}) {
@@ -133,6 +268,7 @@ export function list(agentRoot, opts = {}) {
   const dir = presenceDir(agentRoot);
   if (!existsSync(dir)) return [];
   const staleMs = (Number.isFinite(opts.staleSec) ? opts.staleSec : DEFAULT_STALE_SEC) * 1000;
+  const idleCapMs = (Number.isFinite(opts.idleCapSec) ? opts.idleCapSec : DEFAULT_IDLE_CAP_SEC) * 1000;
   const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now();
   const reap = opts.reap !== false;
   let files;
@@ -152,8 +288,9 @@ export function list(agentRoot, opts = {}) {
       continue;
     }
     const age = nowMs - Date.parse(rec.lastBeat || rec.startedAt || 0);
-    const stale = !Number.isFinite(age) || age > staleMs;
-    const dead = !isProcessRunning(rec.pid);
+    const pidKnown = Number.isFinite(rec.pid) && rec.pid > 0;
+    const dead = pidKnown && !isProcessRunning(rec.pid);
+    const stale = !Number.isFinite(age) || (pidKnown ? age > idleCapMs : age > staleMs);
     if (stale || dead) {
       if (reap) { try { unlinkSync(path); } catch { /* */ } }
       continue;