@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/collective/global-config.mjs

@@ -200,14 +200,25 @@ export function buildIdentityClaudeMd(agentJson, o = {}) {
  * Default command is the bare `cohort-mcp` (the global npm install); a caller
  * that knows it is not on PATH passes `{command, args}` (e.g. the current node
  * + this package's bin/cohort-mcp.mjs) so the server still starts. Pure.
+ *
+ * `inheritEnv` (CF-22, W5-B): the Cohort Engine gives no MCP server a
+ * credential its entry does not name, so the entry names the org credential
+ * cohort-mcp resolves from the environment (lib/org/client.mjs, both brands —
+ * bin/cohort-mcp.mjs bridges NEOLITH_* at boot). An enrolled seat's cohort-mcp
+ * reads its token from config/org.yaml first; the list keeps an env-only seat
+ * working. The claude binary tolerates the key; `claude mcp add-json` drops it,
+ * so global-setup's verify step falls back to the JSON merge, which keeps it.
  * @param {string} agentRoot @param {{command?:string, args?:string[]}} [o]
  */
 export function cohortMcpEntry(agentRoot, o = {}) {
   const command = o.command ? String(o.command) : "cohort-mcp";
   const args = Array.isArray(o.args) ? o.args.map(String) : [];
-  return { command, args, env: { COHORT_AGENT_ROOT: String(agentRoot || "") } };
+  return { command, args, env: { COHORT_AGENT_ROOT: String(agentRoot || "") }, inheritEnv: [...COHORT_MCP_INHERIT_ENV] };
 }
 
+/** The org credential names cohort-mcp's entry inherits (= lib/engine/context/child-env.mjs ORG_CREDENTIAL_ENV). */
+export const COHORT_MCP_INHERIT_ENV = Object.freeze(["COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "NEOLITH_API_TOKEN", "NEOLITH_TOKEN", "NEOLITH_API_KEY"]);
+
 function clone(v) { return JSON.parse(JSON.stringify(v)); }
 function isObj(v) { return v && typeof v === "object" && !Array.isArray(v); }
 
@@ -305,6 +316,57 @@ export function mergeSessionSettings(settings, o = {}) {
   return { settings: out, changes };
 }
 
+// ---------------------------------------------------------------------------
+// State-YAML gates (2026-09): the two hooks that keep an agent's state/queues,
+// state/dashboards and state/indexes YAML parseable and un-clobbered. They live
+// in the SEAT's .claude/settings.json (commands are seat-relative and only make
+// sense inside an agent repo), never in ~/.claude. A hand edit to that file does
+// not survive a fresh checkout (the scaffold copy is what `create` ships) or an
+// upgrade (settings.json is not on the upgrade path), so the scaffold carries
+// them for new seats and `global-setup` — which `upgrade` runs as a post-step —
+// merges them onto existing ones with this helper. Pure; I/O is in bin/maestro.
+// ---------------------------------------------------------------------------
+
+/** The two hook groups, in the exact shape the scaffold .claude/settings.json carries. */
+export const STATE_YAML_GATE_HOOKS = Object.freeze([
+  Object.freeze({
+    event: "PreToolUse",
+    matcher: "Write|Edit",
+    marker: "scripts/hooks/pre-write-yaml-validate.mjs",
+    command: "node ./scripts/hooks/pre-write-yaml-validate.mjs",
+  }),
+  Object.freeze({
+    event: "PostToolUse",
+    matcher: "Bash|Write|Edit",
+    marker: "scripts/hooks/validate-state-yaml.sh",
+    command: "./scripts/hooks/validate-state-yaml.sh",
+  }),
+]);
+
+/**
+ * Merge the state-YAML gate hook groups into a seat's settings.json object, once.
+ * Presence is judged by the script marker anywhere under the event (any matcher),
+ * so an operator who already wired the script by hand is left alone. Existing
+ * groups, permissions and every other key are preserved. Idempotent. Pure.
+ *
+ * @param {object} settings  parsed .claude/settings.json ({} / null when absent)
+ * @returns {{ settings: object, added: string[] }}  added = "PreToolUse:pre-write-yaml-validate" ...
+ */
+export function mergeStateYamlGateHooks(settings) {
+  const out = isObj(settings) ? clone(settings) : {};
+  const added = [];
+  if (!isObj(out.hooks)) out.hooks = {};
+  for (const g of STATE_YAML_GATE_HOOKS) {
+    if (!Array.isArray(out.hooks[g.event])) out.hooks[g.event] = [];
+    const present = out.hooks[g.event].some((grp) =>
+      grp && Array.isArray(grp.hooks) && grp.hooks.some((h) => h && typeof h.command === "string" && h.command.includes(g.marker)));
+    if (present) continue;
+    out.hooks[g.event].push({ matcher: g.matcher, hooks: [{ type: "command", command: g.command }] });
+    added.push(`${g.event}:${basename(g.marker).replace(/\.(mjs|sh)$/, "")}`);
+  }
+  return { settings: out, added };
+}
+
 /** Build the machine pointer object. */
 export function buildPointer(repoRoot, agentName, nowMs) {
   return {

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;