agents-can-communicate 0.1.12 → 0.1.14

package/docs/CAPABILITIES.md

@@ -44,6 +44,34 @@ should be re-run before claiming another platform.
 | `execution.resume` | no | no | no | no |
 | `execution.terminate` | no | no | no | no |
 
+## Resolving a client's pid is not universal either
+
+Not a capability above - no adapter method backs it, so it has no row in the matrix - but
+it is presence's other signal for telling a dead process from an idle one, and it does not
+reach every client.
+
+A session's recorded pid comes from walking its process ancestry until the adapter's own
+declared binary (`client.command`) turns up in `ps -o comm=`. That only works when the
+operating system's own name for the process actually is that binary: true for a native
+executable, false for a script run through an interpreter, where `comm` reports the
+interpreter's name rather than the script's.
+
+| Client | `client.command` | `ps -o comm=` reports | Pid resolves |
+|---|---|---|---|
+| `codex` | `codex` | `codex`, a native binary | yes |
+| `claude_code` | `claude` | `claude`, a native binary | yes |
+| `gemini_cli` | `gemini` | `node` - `gemini.js` starts `#!/usr/bin/env node` | **no** |
+| `kimi` | `kimi` | not installed on the machine this table was measured on; Kimi Code ships via npm as a Node.js CLI (`@moonshot-ai/kimi-code`), the same shape as Gemini CLI | **almost certainly no - not measured** |
+
+A Gemini session records `pid: null` for its whole life, and Kimi's is very likely the
+same, unconfirmed. `null` is the correct "nobody knows" answer and is handled identically
+wherever it is read - not a correctness bug. It does change what presence delivers, though:
+a confirmed-dead pid retires a session immediately and exactly, and today that is `codex`
+and `claude_code` only. `gemini_cli` and `kimi` fall back to the same age-based floor every
+session has for whenever a pid is unavailable - thirty minutes of silence - so their
+sessions still leave, just later and on a timer instead of on the fact. See
+[ARCHITECTURE.md](ARCHITECTURE.md#presence) for the full floor.
+
 ## What the yes values do not promise
 
 A capability says the client can do the thing. Several of them are conditional on how the
@@ -85,8 +113,10 @@ what the claim's owner asked for, and whether ACC can stop this session at all:
 Unenforceable is not the same as unknown - and neither is it the same as unclaimed.
 
 **`lifecycle.sessionEnd` on `kimi` is false and it matters.** Each `kimi -p` run leaves an
-attached session that only ages out on its declared 60s cadence, so a peer reading the
-roster inside that window sees sessions that have already exited. Interactive sessions
+attached session that never closes itself - it just stops taking turns. Presence retires it
+instead, most likely without ever resolving a pid (see above), which means the session
+reads `offline` - and disappears from the default `acc status` view - only after thirty
+minutes of silence, not on its declared 60s heartbeat cadence. Interactive sessions
 heartbeat and do not have this problem.
 
 **`lifecycle.heartbeat` is Kimi's alone.** It fires on a timer - observed at 60002, 120004

package/node_modules/@agents-can-communicate/adapter-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-claude-code",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-codex",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-gemini-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-gemini-cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-kimi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-kimi",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-sdk",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/core/src/claims.mjs

@@ -31,7 +31,7 @@ export function overlaps(left, right) {
 const isLive = (claim, now) => Date.parse(claim.expiresAt) > Date.parse(now);
 
 export function createClaimService(ports, sessions) {
-  const { store, clock, ids } = ports;
+  const { store, clock, ids, pidIsAlive } = ports;
 
   async function requireOwner(input, action) {
     const existing = await sessions.locateSession(input.sessionId, input.workspaceId);
@@ -52,7 +52,7 @@ export function createClaimService(ports, sessions) {
     // releases the claim on its own.
     const ownerPresence = ownerSession === undefined
       ? "offline"
-      : classifySessionPresence(ownerSession, now);
+      : classifySessionPresence(ownerSession, now, pidIsAlive);
     return new AccError(EXIT.CONFLICT, "the resource is already claimed", {
       claimId: existing.claimId,
       resource: existing.resource,

package/node_modules/@agents-can-communicate/core/src/index.mjs

@@ -2,6 +2,7 @@
 export { createCoordinationService } from "./service.mjs";
 export { assertPorts } from "./ports.mjs";
 export { classifySessionPresence } from "./sessions.mjs";
+export { defaultPidIsAlive } from "./pid.mjs";
 export { ATTENTION_PRIORITY, computeAttention } from "./sync.mjs";
 export { overlaps } from "./claims.mjs";
 export { wouldCycle } from "./tasks.mjs";

package/node_modules/@agents-can-communicate/core/src/pid.mjs

@@ -0,0 +1,33 @@
+/**
+ * Whether a process with this id exists.
+ *
+ * Signal 0 runs the existence and permission checks without delivering
+ * anything. `ESRCH` is the only answer that means gone: `EPERM` says the
+ * process is there and owned by somebody else, which is still there.
+ *
+ * Deliberately not shared with the writer lock's copy in the storage package.
+ * `core` may not import storage (tests/package-boundaries.test.mjs), and the two
+ * ask the question about different subjects - a lock owner mid-write, and a
+ * session that may have ended hours ago.
+ *
+ * `pid` must be a real, positive process id - the argument this function
+ * answers a question about. It is not where "nobody knows" is answered:
+ * `defaultPidIsAlive(null)` returns `false`, the same as a confirmed-dead pid,
+ * because a non-positive integer fails the `Number.isInteger` guard below the
+ * same way a made-up one would. The design this function serves requires the
+ * opposite reading for a session with no recorded pid - "cannot tell", never
+ * "dead" - so every call site in this repository guards on `pid !== null`
+ * before calling it. This is exported as the canonical liveness probe, so a
+ * caller reached from outside that guard must add its own, or a pid-less
+ * session will read as dead here regardless of how the rest of the system
+ * treats it.
+ */
+export function defaultPidIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code !== "ESRCH";
+  }
+}

package/node_modules/@agents-can-communicate/core/src/ports.mjs

@@ -52,5 +52,14 @@ export function assertPorts(ports) {
         { port: "store.ephemeral", method });
     }
   }
+  // A bare function, not an object with methods, so it does not fit REQUIRED
+  // above. Checked here for the same reason as everything else in this file: a
+  // core that constructed cleanly and only discovered the gap at the first
+  // presence check would raise a bare TypeError from deep inside sessions.mjs,
+  // not an AccError - invisible to the CLI's exit-code mapping.
+  if (typeof ports.pidIsAlive !== "function") {
+    throw new AccError(EXIT.USAGE, "the pidIsAlive port must be a function",
+      { port: "pidIsAlive" });
+  }
   return ports;
 }

package/node_modules/@agents-can-communicate/core/src/service.mjs

@@ -1,6 +1,7 @@
 import { createClaimService } from "./claims.mjs";
 import { createCommunicationService } from "./communication.mjs";
 import { createIntentService } from "./intents.mjs";
+import { defaultPidIsAlive } from "./pid.mjs";
 import { assertPorts } from "./ports.mjs";
 import { createSessionService } from "./sessions.mjs";
 import { createGuardStateService, createStatusService } from "./status.mjs";
@@ -13,10 +14,18 @@ import { createWorkstreamService } from "./workstreams.mjs";
  * randomness-dependent arrives through a port, so behaviour is reproducible and
  * no module reaches for a global.
  *
- * @param {{ store: object, clock: object, ids: object, policies?: object }} ports
+ * @param {{ store: object, clock: object, ids: object, pidIsAlive?: function,
+ *   policies?: object }} ports
  */
-export function createCoordinationService({ store, clock, ids, policies = {} }) {
-  const ports = assertPorts({ store, clock, ids });
+export function createCoordinationService({ store, clock, ids,
+  pidIsAlive = defaultPidIsAlive, policies = {} }) {
+  // Defaulted here, where the default is a real implementation, and required in
+  // the classifier, where a default could only be a lie. Passed into
+  // assertPorts rather than spread on afterward, so an explicit non-function -
+  // `null` included, since the default above only applies to `undefined` - is
+  // shape-checked at construction like every other port instead of surfacing
+  // as a raw TypeError the first time presence is classified.
+  const ports = assertPorts({ store, clock, ids, pidIsAlive });
   const sessions = createSessionService(ports);
   const intents = createIntentService(ports, sessions);
   const workstreams = createWorkstreamService(ports, sessions);

package/node_modules/@agents-can-communicate/core/src/sessions.mjs

@@ -9,14 +9,46 @@ import { writeWorkResponse } from "./notify.mjs";
 // rather than one global constant (docs/ARCHITECTURE.md, presence freshness).
 const STALE_CADENCE_MULTIPLE = 3;
 
+// Two floors, because they answer different questions and neither subsumes the
+// other. UNKNOWN_EXPIRY_MS is the "cannot tell" branch: records written before
+// pids were recorded, platforms with no process table, an ancestry that did not
+// resolve. HARD_EXPIRY_MS exists because pids are recycled - the hazard
+// writer-mutex.mjs:72 documents - so a session whose number was reissued to
+// something unrelated would otherwise read as alive forever.
+const UNKNOWN_EXPIRY_MS = 30 * 60_000;
+const HARD_EXPIRY_MS = 24 * 60 * 60_000;
+
+const ageBand = (session, age) =>
+  age <= session.heartbeatCadenceMs * STALE_CADENCE_MULTIPLE ? "online" : "stale";
+
 /**
+ * @param {{ state: string, heartbeatAt: string, heartbeatCadenceMs: number,
+ *   pid?: number | null }} session The record to classify. `pid` absent or
+ *   `null` means nobody knows whether the process is alive - never that it is
+ *   dead - so age alone judges it.
+ * @param {string} now An ISO timestamp, compared against `session.heartbeatAt`.
+ * @param {(pid: number) => boolean} pidIsAlive Required, not defaulted: the one
+ *   thing that lets `offline` be reached before the age floors do. Called only
+ *   when `session.pid` is a real pid, never with `null`.
  * @returns {"online" | "stale" | "offline"}
+ * @throws {AccError} EXIT.USAGE when pidIsAlive is not a function.
  */
-export function classifySessionPresence(session, now, probe = () => true) {
+export function classifySessionPresence(session, now, pidIsAlive) {
+  // Required rather than defaulted. A probe that defaults to "everyone is
+  // alive" turns a forgotten call site into a check that silently passes, which
+  // is the failure this repository has already shipped twice.
+  if (typeof pidIsAlive !== "function") {
+    throw new AccError(EXIT.USAGE, "classifySessionPresence requires a pidIsAlive probe",
+      { sessionId: session?.sessionId ?? null });
+  }
   if (session.state === "closed") return "offline";
-  if (!probe(session)) return "offline";
   const age = Date.parse(now) - Date.parse(session.heartbeatAt);
-  return age <= session.heartbeatCadenceMs * STALE_CADENCE_MULTIPLE ? "online" : "stale";
+  if (age > HARD_EXPIRY_MS) return "offline";
+  const pid = session.pid ?? null;
+  // A pid that answers outranks the unknown floor: a live but idle session is
+  // exactly what kimi looks like between turns.
+  if (pid !== null) return pidIsAlive(pid) ? ageBand(session, age) : "offline";
+  return age > UNKNOWN_EXPIRY_MS ? "offline" : ageBand(session, age);
 }
 
 const sessionRecord = (input, now, generation) => validateRecord("session", {
@@ -30,6 +62,7 @@ const sessionRecord = (input, now, generation) => validateRecord("session", {
   parentSessionId: input.parentSessionId ?? null,
   checkoutRoot: input.checkoutRoot ?? null,
   branch: input.branch ?? null,
+  pid: input.pid ?? null,
   // Both default to the weaker reading. A session that declares nothing is a
   // session nothing intercepts - an MCP client, or a CLI user - and claiming
   // otherwise would promise enforcement that is not there.
@@ -50,7 +83,7 @@ const participantRecord = (input, now) => validateRecord("participant", {
 });
 
 export function createSessionService(ports) {
-  const { store, clock, ids } = ports;
+  const { store, clock, ids, pidIsAlive } = ports;
   const workspaceOf = input => input.workspaceId ?? store.workspaceId;
 
   async function locate(sessionId, workspaceId) {
@@ -66,9 +99,16 @@ export function createSessionService(ports) {
   function assertReplaceable(existing, probe) {
     if (existing.record.state === "closed") return;
     // Presence staleness alone never replaces ownership: an idle-but-open
-    // session may resume at any moment. Only a liveness probe reporting the
-    // owner gone permits a replacement generation.
-    if (probe === undefined || probe(existing.record)) {
+    // session may resume at any moment, and a wrong "gone" verdict there
+    // self-corrects the moment that session next takes a turn. A wrong
+    // replacement does not self-correct - it takes the generation, and the
+    // original session's own heartbeats fail with CONFLICT from then on. So
+    // only a pid confirmed dead is authority to replace; "we cannot tell" -
+    // a session with no recorded pid - is never enough, however long the
+    // silence.
+    const live = probe ?? (record => (record.pid ?? null) === null
+      || pidIsAlive(record.pid));
+    if (live(existing.record)) {
       throw new AccError(EXIT.CONFLICT, "the session id is already live",
         { sessionId: existing.record.sessionId });
     }

package/node_modules/@agents-can-communicate/core/src/status.mjs

@@ -58,7 +58,7 @@ export function createGuardStateService(ports) {
 }
 
 export function createStatusService(ports, sessions) {
-  const { store, clock } = ports;
+  const { store, clock, pidIsAlive } = ports;
 
   async function collectStatus(input = {}) {
     const workspaceId = input.workspaceId ?? store.workspaceId;
@@ -72,9 +72,17 @@ export function createStatusService(ports, sessions) {
       ? snapshot.sessions
       : await store.ephemeral.list("session");
     const intents = durable ? snapshot.intents : await store.ephemeral.list("intent");
-    const live = sessionRecords
-      .map(session => ({ session, presence: classifySessionPresence(session, now) }))
-      .filter(item => item.presence !== "offline");
+    // Classified once, and reused everywhere below. `classifySessionPresence` now
+    // asks `pidIsAlive`, a real `process.kill(pid, 0)` syscall for a session with
+    // a recorded pid, so it is no longer pure given `now` - a client can exit
+    // between two calls inside the same response, and re-reading the same
+    // session later in this function can then disagree with what an earlier
+    // reading already said. One reading, taken once, is what keeps `counts.live`,
+    // the roster filter, and each listed session's `presence` describing the
+    // same instant rather than three independent guesses at it.
+    const classified = sessionRecords
+      .map(session => ({ session, presence: classifySessionPresence(session, now, pidIsAlive) }));
+    const live = classified.filter(item => item.presence !== "offline");
     const claims = snapshot.claims
       .filter(claim => Date.parse(claim.expiresAt) > Date.parse(now));
 
@@ -87,10 +95,9 @@ export function createStatusService(ports, sessions) {
       // the roster is where "which worktree was that agent in" is answered - so
       // after a month of work this listed sixty entries for one live session.
       // `acc status --all` is how the worktree-cleanup question is asked.
-      participants: sessionRecords
-        .filter(session => input.all === true
-          || classifySessionPresence(session, now) !== "offline")
-        .map(session => ({
+      participants: classified
+        .filter(item => input.all === true || item.presence !== "offline")
+        .map(({ session, presence }) => ({
         sessionId: session.sessionId,
         participantId: session.participantId,
         harness: session.harness,
@@ -99,7 +106,7 @@ export function createStatusService(ports, sessions) {
         branch: session.branch ?? null,
         enforcement: session.enforcement ?? "advisory",
         lifecycle: session.lifecycle ?? "manual",
-        presence: classifySessionPresence(session, now),
+        presence,
         intent: intents.find(intent => intent.sessionId === session.sessionId)?.summary ?? null,
       })),
       workstreams: snapshot.workstreams.map(workstream => ({
@@ -127,7 +134,7 @@ export function createStatusService(ports, sessions) {
         expiresAt: claim.expiresAt,
       })),
       attention: computeAttention(snapshot, { session: null,
-        participantId: input.participantId, now }),
+        participantId: input.participantId, now, pidIsAlive }),
       counts: {
         live: live.length,
         stale: live.filter(item => item.presence === "stale").length,

package/node_modules/@agents-can-communicate/core/src/sync.mjs

@@ -154,11 +154,18 @@ function unansweredQuestions(snapshot, participantId, onlineParticipants) {
   return items;
 }
 
-function stalledRequests(snapshot, participantId, now) {
+function stalledRequests(snapshot, participantId, now, pidIsAlive) {
+  // Classified once per session and reused below, for the same reason
+  // collectStatus takes one reading: classifySessionPresence calls pidIsAlive,
+  // a real process.kill(pid, 0) syscall for a session with a recorded pid, so
+  // it is not pure given `now` any more. A second classifying pass here could
+  // disagree with the first - a client exiting between them would leave `live`
+  // saying "online" while a freshly-computed `onlineParticipants` had already
+  // dropped it, inside one attention computation.
   const live = new Map((snapshot.sessions ?? [])
-    .map(session => [session.sessionId, classifySessionPresence(session, now)]));
+    .map(session => [session.sessionId, classifySessionPresence(session, now, pidIsAlive)]));
   const onlineParticipants = new Set((snapshot.sessions ?? [])
-    .filter(session => classifySessionPresence(session, now) === "online")
+    .filter(session => live.get(session.sessionId) === "online")
     .map(session => session.participantId));
   const goingNowhere = task => {
     // Taken by someone who has gone quiet.
@@ -191,20 +198,28 @@ function coordinatorGaps(snapshot) {
       sourceId: workstream.workstreamId, summary: workstream.title }));
 }
 
-export function computeAttention(snapshot, { session, participantId, now }) {
+export function computeAttention(snapshot, { session, participantId, now, pidIsAlive }) {
+  // Required unconditionally, not only when there happen to be sessions to
+  // classify: `stalledRequests` reaches `classifySessionPresence` only inside a
+  // map/filter over `snapshot.sessions`, so an empty or absent roster let a
+  // missing probe through with nothing to trip over it - the same silent pass
+  // the classifier's own required parameter exists to close, one layer up.
+  if (typeof pidIsAlive !== "function") {
+    throw new AccError(EXIT.USAGE, "computeAttention requires a pidIsAlive probe", {});
+  }
   return [
     ...directRequests(snapshot, participantId),
     ...claimConflicts(snapshot, session, now),
     ...expiredClaims(snapshot, session, now),
     ...unblockedTasks(snapshot, session, participantId),
     ...coordinatorGaps(snapshot),
-    ...stalledRequests(snapshot, participantId, now),
+    ...stalledRequests(snapshot, participantId, now, pidIsAlive),
   ].sort((left, right) => left.priority - right.priority
     || left.sourceId.localeCompare(right.sourceId));
 }
 
 export function createSyncService(ports, sessions) {
-  const { store, clock } = ports;
+  const { store, clock, pidIsAlive } = ports;
 
   /**
    * Any session may request the full Workspace scope. Peer equality is a
@@ -240,7 +255,7 @@ export function createSyncService(ports, sessions) {
     const page = await store.eventsSince(workspaceId, input.cursor ?? null,
       input.limit ?? DEFAULT_LIMIT);
     const attention = computeAttention(snapshot, { session,
-      participantId: session?.participantId ?? input.participantId, now });
+      participantId: session?.participantId ?? input.participantId, now, pidIsAlive });
 
     const roster = snapshot.sessions.map(item => ({
       sessionId: item.sessionId,
@@ -248,7 +263,7 @@ export function createSyncService(ports, sessions) {
       parentSessionId: item.parentSessionId,
       harness: item.harness,
       branch: item.branch ?? null,
-      presence: classifySessionPresence(item, now),
+      presence: classifySessionPresence(item, now, pidIsAlive),
     }));
 
     // Solo zero-overhead: one live session, no claims and

package/node_modules/@agents-can-communicate/core/src/tasks.mjs

@@ -84,7 +84,7 @@ export function writeTask(tx, { input, session, workspaceId, now, ids }) {
 }
 
 export function createTaskService(ports, workstreams) {
-  const { store, clock, ids } = ports;
+  const { store, clock, ids, pidIsAlive } = ports;
 
   async function createTask(input) {
     const session = await workstreams.requireOpenSession(input, "create a task");
@@ -120,13 +120,19 @@ export function createTaskService(ports, workstreams) {
         && existing.assigneeSessionId !== session.sessionId) {
         // A holder that is gone is not a holder. Closing a session hands its
         // work back, so this is the crash case: no session end ever arrived and
-        // presence has decayed. Staleness alone does not release it - that is
-        // the same rule claims follow, because an idle agent may be thinking
-        // rather than dead - but it can be taken over deliberately.
+        // presence has decayed. `stale` alone does not release it - the same
+        // rule claims follow, because an idle agent may be thinking rather than
+        // dead - and taking it over needs `force`. `offline` needs no force at
+        // all, silence-derived cases included: a session with no recorded pid,
+        // quiet past the unknown floor, reads offline exactly like one whose
+        // pid is confirmed dead, and either way the task is simply taken. That
+        // is acceptable here where it would not be for a session id: the
+        // participant guard below still refuses a different participant, and
+        // taking a task back is reversible where replacing an id is not.
         const holder = tx.get("session", existing.assigneeSessionId);
         const presence = holder === null
           ? "offline"
-          : classifySessionPresence(holder, now);
+          : classifySessionPresence(holder, now, pidIsAlive);
         if (presence === "online") {
           throw new AccError(EXIT.CONFLICT, "the task already has an assignee",
             { taskId: input.taskId, assigneeSessionId: existing.assigneeSessionId });

package/node_modules/@agents-can-communicate/core/src/workstreams.mjs

@@ -8,7 +8,7 @@ import { classifySessionPresence } from "./sessions.mjs";
 // coordinator lease, and the coordinator plans - it is never the transport,
 // the durable owner, or an information gatekeeper.
 export function createWorkstreamService(ports, sessions) {
-  const { store, clock, ids } = ports;
+  const { store, clock, ids, pidIsAlive } = ports;
 
   async function requireOpenSession(input, action) {
     const existing = await sessions.locateSession(input.sessionId, input.workspaceId);
@@ -63,7 +63,7 @@ export function createWorkstreamService(ports, sessions) {
       if (held !== null && held !== session.sessionId) {
         const holder = snapshot.sessions.find(item => item.sessionId === held);
         const presence = holder === undefined ? "offline"
-          : classifySessionPresence(holder, now);
+          : classifySessionPresence(holder, now, pidIsAlive);
         // A coordinator lease is replaced only when the holder is genuinely
         // gone or policy says so - not because a peer would like the role.
         if (presence !== "offline" && input.authority !== "human"

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/hook-runner/src/client-pid.mjs

@@ -0,0 +1,32 @@
+import path from "node:path";
+
+// Deep enough for a client that wraps its hook in a shell and a launcher, short
+// enough that a table which disagrees with itself cannot spin.
+const MAX_HOPS = 16;
+
+/**
+ * The pid of the client this hook is running for, or null when nobody knows.
+ *
+ * The hook is not the client's child. Measured on macOS, a process spawned by
+ * Claude Code has parent `/bin/zsh` and grandparent `claude`, so `process.ppid`
+ * names a shell that dies with the hook. Walking until the adapter's own
+ * declared binary appears is what makes the answer specific rather than a guess
+ * about which ancestors are "real".
+ *
+ * Null is a first-class answer: it means judge this session by age alone.
+ */
+export function resolveClientPid({ table, from, command, maxHops = MAX_HOPS }) {
+  const seen = new Set();
+  let current = from;
+  for (let hop = 0; hop < maxHops; hop += 1) {
+    const entry = table.get(current);
+    if (entry === undefined || seen.has(current)) return null;
+    seen.add(current);
+    // `ps` reports some entries bare (`claude`) and some with a path
+    // (`/bin/zsh`), so the comparison has to be on the basename.
+    if (path.basename(entry.comm) === command) return current;
+    if (entry.ppid === current || entry.ppid <= 1) return null;
+    current = entry.ppid;
+  }
+  return null;
+}

package/node_modules/@agents-can-communicate/hook-runner/src/process-table.mjs

@@ -0,0 +1,34 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+// A hook runs in front of someone's turn. Reading the table is worth a few
+// hundred milliseconds once per session and nothing at all if it is slow.
+const DEFAULT_TIMEOUT_MS = 1_000;
+
+const LINE = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/;
+
+/**
+ * Every process on this machine, as pid -> parent and executable.
+ *
+ * Returns an empty map rather than throwing when the platform has no `ps`
+ * (Windows) or the call fails. An empty table resolves no client, which is the
+ * "nobody knows" answer the caller already handles.
+ */
+export async function readProcessTable({ run: exec = run,
+  timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  try {
+    const { stdout } = await exec("ps", ["-o", "pid=,ppid=,comm=", "-A"],
+      { timeout: timeoutMs });
+    const table = new Map();
+    for (const line of stdout.split("\n")) {
+      const match = LINE.exec(line);
+      if (match === null) continue;
+      table.set(Number(match[1]), { ppid: Number(match[2]), comm: match[3] });
+    }
+    return table;
+  } catch {
+    return new Map();
+  }
+}

package/node_modules/@agents-can-communicate/hook-runner/src/runner.mjs

@@ -10,6 +10,9 @@ import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem"
 import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
   from "@agents-can-communicate/cli";
 
+import { resolveClientPid } from "./client-pid.mjs";
+import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
+
 // A hook runs in front of the user's turn, so it gets a hard ceiling. Better to
 // let a call through than to make someone's session sit waiting on us.
 const DEFAULT_BUDGET_MS = 5_000;
@@ -154,8 +157,14 @@ async function openContext({ cwd, dataHome, runtime, env }) {
 }
 
 const HANDLERS = {
-  async sessionStart({ event, context, adapter, adapterId, paths }) {
+  async sessionStart({ event, context, adapter, adapterId, paths, readProcessTable }) {
     const capabilities = adapter.capabilities ?? {};
+    // Once per session, never per turn. A client that cannot be found yields
+    // null, and the session is then judged by age alone - which is exactly the
+    // behaviour every session had before this existed.
+    const command = adapter.client?.command ?? null;
+    const pid = command === null ? null
+      : resolveClientPid({ table: await readProcessTable(), from: process.pid, command });
     const session = await context.service.openSession({
       workspaceId: context.descriptor.id,
       participantId: participantFor(adapterId, event.sessionId, context.env),
@@ -171,6 +180,7 @@ const HANDLERS = {
       // Which checkout this agent is in. One workspace spans every worktree of
       // a repository, so this is the only thing that distinguishes them.
       checkoutRoot: context.descriptor.git?.worktreeRoot ?? context.descriptor.roots[0],
+      pid,
       branch: context.descriptor.git?.branch ?? null,
       descriptor: context.descriptor,
     });
@@ -339,7 +349,8 @@ const HANDLERS = {
  * only thing this function refuses to do is fail closed.
  */
 export async function runHook({ adapterId, payload, adapters, dataHome, env,
-  runtime = defaultRuntime(), budgetMs = DEFAULT_BUDGET_MS }) {
+  runtime = defaultRuntime(), budgetMs = DEFAULT_BUDGET_MS,
+  readProcessTable = defaultReadProcessTable }) {
   const result = { stdout: "", exitCode: 0, decision: "allow", sessions: [] };
   let timer = null;
   try {
@@ -354,7 +365,8 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     const handler = HANDLERS[event.kind];
     const work = handler === undefined
       ? Promise.resolve({})
-      : handler({ event, context, adapter, adapterId, binding, paths: context.paths });
+      : handler({ event, context, adapter, adapterId, binding, paths: context.paths,
+        readProcessTable });
 
     // The loser of a race is not cancelled, so the timer is cleared explicitly:
     // an outstanding one keeps the process alive long past its answer.

package/node_modules/@agents-can-communicate/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": { ".": "./src/index.mjs" },

package/node_modules/@agents-can-communicate/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/protocol/src/schema.mjs

@@ -2,7 +2,7 @@ import { AccError, EXIT } from "./errors.mjs";
 import { flag, id, invalid, listOf, nullable, oneOf, plainObject, positiveInteger,
   resourceUri, sequence, text, timestamp } from "./fields.mjs";
 
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 
 const line = text();
 const prose = text({ max: 4000, multiline: true });
@@ -78,6 +78,10 @@ const RECORDS = Object.freeze({
   session: { sessionId: id, participantId: id, workspaceId: id, generation: id,
     harness: line, state: oneOf("open", "closed"), parentSessionId: nullable(id),
     checkoutRoot: nullable(line), branch: nullable(line),
+    // The process behind this session, when it can be named. Null means nobody
+    // knows - no process table, or an ancestry that did not resolve - and is
+    // read as "judge this one by age alone", never as "dead".
+    pid: nullable(positiveInteger),
     enforcement: oneOf("guarded", "advisory"), lifecycle: oneOf("managed", "manual"),
     heartbeatCadenceMs: positiveInteger, startedAt: timestamp, heartbeatAt: timestamp },
 

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/storage-filesystem/src/atomic-json.mjs

@@ -32,9 +32,9 @@ export function encode(value) {
   return Buffer.from(`${serialised}\n`, "utf8");
 }
 
-async function bytesIfPresent(filePath, root) {
+async function bytesIfPresent(filePath, root, openFile) {
   try {
-    return await readRegularNoFollow(filePath, root);
+    return await readRegularNoFollow(filePath, root, openFile);
   } catch (error) {
     if (error.code === "ENOENT") return null;
     throw error;
@@ -87,8 +87,10 @@ export async function publishAtomic(destination, bytes, { root, tmpDir, replace
   }
 }
 
-export async function readJsonIfPresent(filePath, root) {
-  const bytes = await bytesIfPresent(filePath, root);
+// The opener is the seam the race tests use, and stays last so callers that do
+// not care never see it.
+export async function readJsonIfPresent(filePath, root, openFile) {
+  const bytes = await bytesIfPresent(filePath, root, openFile);
   if (bytes === null) return null;
   try {
     return { value: JSON.parse(bytes.toString("utf8")), bytes };

package/node_modules/@agents-can-communicate/storage-filesystem/src/identity.mjs

@@ -4,7 +4,7 @@ import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protoc
 
 import { encode, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
 
-export const STORE_VERSION = 1;
+export const STORE_VERSION = 2;
 
 export function identityPath(paths) {
   return path.join(paths.root, "protocol.json");

package/node_modules/@agents-can-communicate/storage-filesystem/src/writer-mutex.mjs

@@ -22,9 +22,36 @@ function defaultPidIsAlive(pid) {
   }
 }
 
-async function readOwner(directory, root) {
-  const found = await readJsonIfPresent(path.join(directory, OWNER), root);
-  return found?.value ?? null;
+/**
+ * Who holds the lock, or nothing if it moved while we looked.
+ *
+ * Reads inside the store refuse a parent directory whose identity changed
+ * between the check and the open - the defence against a directory being
+ * swapped under a read. This lock is the one directory whose entire life is
+ * being created and removed: `mkdir` grants it, `rm` releases it, so its inode
+ * changes every time it passes from one process to the next. Reading its owner
+ * through the strict path meant a contended lock raised
+ * "record parent directory changed while opening" and the whole command failed -
+ * seen on Linux CI with four agents attaching to one fresh workspace, the
+ * ordinary way two people start work.
+ *
+ * Here that is not an anomaly, it is the answer: the lock moved. Null says so,
+ * and both callers already do the right thing with it - the acquiring loop waits
+ * and looks again, and the releasing branch declines to remove a directory that
+ * is no longer the one it created. The guard itself is untouched, and still
+ * refuses everywhere a parent has no business changing.
+ */
+async function readOwner(directory, root, openFile) {
+  try {
+    const found = await readJsonIfPresent(path.join(directory, OWNER), root, openFile);
+    return found?.value ?? null;
+  } catch (error) {
+    if (error instanceof AccError && error.code === EXIT.DATA
+      && /parent directory changed/.test(error.message)) {
+      return null;
+    }
+    throw error;
+  }
 }
 
 /**
@@ -58,7 +85,7 @@ async function takeStaleOwnership(directory, root, owner, now, pidIsAlive) {
 
 export async function withWriterMutex(paths, options, operation) {
   const { root, clock, pidIsAlive = defaultPidIsAlive, uuid = randomUUID,
-    attempts = 50, waitMs = 20 } = options;
+    attempts = 50, waitMs = 20, openFile } = options;
   const directory = path.join(paths.locks, "writer.lock");
   await ensureManagedDirectory(root, paths.locks);
   const token = uuid();
@@ -68,7 +95,7 @@ export async function withWriterMutex(paths, options, operation) {
       await mkdir(directory);
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
-      const owner = await readOwner(directory, root);
+      const owner = await readOwner(directory, root, openFile);
       if (!await takeStaleOwnership(directory, root, owner, clock.now(), pidIsAlive)) {
         await new Promise(resolve => { setTimeout(resolve, waitMs); });
       }
@@ -79,7 +106,7 @@ export async function withWriterMutex(paths, options, operation) {
     try {
       return await operation();
     } finally {
-      const current = await readOwner(directory, root);
+      const current = await readOwner(directory, root, openFile);
       if (current?.token === token) await rm(directory, { recursive: true, force: true });
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "type": "module",
   "description": "Local-first coordination for independently opened AI agent sessions.",
   "keywords": [