@staix/agent-hub 0.12.3 → 0.12.5

package/src/hub/child-process.ts

@@ -11,13 +11,108 @@ export function childEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.Proces
   return env;
 }
 
+/** One process: its identity is the pid with its start time (`lstart`, which exec keeps); group and command are evidence. */
+export interface ProcRow {
+  pid: number;
+  ppid: number;
+  pgid: number;
+  started: string;
+  command: string;
+}
+
+/**
+ * `ps -axo pid=,ppid=,pgid=,stat=,lstart=,command=` output (unlimited width when not on a terminal), read in the C
+ * locale. A zombie is left out: it has exited, and only its parent's wait is missing.
+ */
+export function parseProcessTable(text: string): ProcRow[] {
+  return text.split("\n").flatMap((line) => {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\w{3} \w{3} [ \d]\d \d\d:\d\d:\d\d \d{4})\s+(.*)$/.exec(line);
+    return m && !m[4]!.startsWith("Z") ? [{ pid: Number(m[1]), ppid: Number(m[2]), pgid: Number(m[3]), started: m[5]!, command: m[6]! }] : [];
+  });
+}
+
+const PS = ["ps", "-axo", "pid=,ppid=,pgid=,stat=,lstart=,command="];
+// `lstart` is local time: one zone for every reader, or a reader in another zone sees every identity as changed.
+const PS_OPTIONS = { env: { ...process.env, LC_ALL: "C", TZ: "UTC" }, detached: true } as const;
+/** The rows of one read, or undefined when they do not show the reader: a parse that found nothing is not a table. */
+const own = (text: string) => { const rows = parseProcessTable(text); return rows.some((row) => row.pid === process.pid) ? rows : undefined; };
+
+/**
+ * The process table, or undefined when it cannot be read or does not show this process: a parse that found nothing
+ * (a localized `lstart`, a changed `ps`) is not an empty table. Read with LC_ALL=C for that reason (and TZ=UTC, so
+ * start times compare across readers), by a `ps` in a
+ * process group of its own (a Ctrl-C to the caller's group would kill it), bounded, and tried twice.
+ */
+export function processTable(): ProcRow[] | undefined {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const r = Bun.spawnSync(PS, { ...PS_OPTIONS, stdout: "pipe", stderr: "pipe", timeout: 10_000 });
+      const rows = r.exitCode === 0 ? own(r.stdout.toString()) : undefined;
+      if (rows) return rows;
+    } catch {
+      // tried again below
+    }
+  }
+  return undefined;
+}
+
+/** `processTable`, without blocking the event loop: a hub stop reads the table many times while it keeps serving. */
+export async function readProcessTable(): Promise<ProcRow[] | undefined> {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const p = Bun.spawn(PS, { ...PS_OPTIONS, stdout: "pipe", stderr: "ignore" });
+      const timer = setTimeout(() => p.kill("SIGKILL"), 10_000);
+      const [text, code] = await Promise.all([new Response(p.stdout).text(), p.exited]).finally(() => clearTimeout(timer));
+      const rows = code === 0 ? own(text) : undefined;
+      if (rows) return rows;
+    } catch {
+      // tried again below
+    }
+  }
+  return undefined;
+}
+
+/** Every descendant of `pid` in `rows`, by parent links. */
+export function descendantsOf(rows: ProcRow[], pid: number): ProcRow[] {
+  const out: ProcRow[] = [];
+  const parents = new Set([pid]);
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const row of rows) {
+      if (parents.has(row.ppid) && !parents.has(row.pid)) {
+        parents.add(row.pid);
+        out.push(row);
+        grew = true;
+      }
+    }
+  }
+  return out;
+}
+
 /**
  * Stop a child owned by this hub and confirm that it exited. A timeout is an
  * incomplete shutdown, even after SIGKILL, because callers must not reuse a
  * port or claim ownership while the old process may still be alive.
+ *
+ * `group`: the child was spawned `detached` and leads its own process group; see `stopGroup`. `table` replaces the
+ * process table read (tests).
  */
-export async function stopOwnedProcess(proc: ChildProcess, termMs = 1_000, killMs = 2_000): Promise<void> {
-  if (proc.exitCode !== null || proc.signalCode !== null || proc.pid === undefined) return;
+export async function stopOwnedProcess(proc: ChildProcess, { termMs = 1_000, killMs = 2_000, group = false, table = readProcessTable }: { termMs?: number; killMs?: number; group?: boolean; table?: () => ProcRow[] | undefined | Promise<ProcRow[] | undefined> } = {}): Promise<void> {
+  if (proc.exitCode !== null || proc.signalCode !== null || proc.pid === undefined) {
+    // ponytail: a leader that exited before the stop (its launcher killed from outside) is not swept, as its pid may be
+    // reused once its group empties; its pipes are dropped so a survivor cannot keep the hub alive, and a group that
+    // still has members fails the stop instead of reading as done. Record the leader's start time at spawn to sweep it.
+    if (!group || proc.pid === undefined) return;
+    dropPipes(proc);
+    if (emptied.has(proc)) return; // its group was seen gone since: the id may be someone else's now
+    // A pid is not given out while a group with that id exists: a live process with the leader's pid means the group was
+    // emptied and the id is someone else's now. Members without it are what the leader left (zombies are not listed).
+    const rows = await table();
+    const members = rows ? (rows.some((r) => r.pid === proc.pid) ? [] : rows.filter((r) => r.pgid === proc.pid)) : undefined;
+    if (members ? members.length : !groupGone(proc.pid)) throw new Error(`owned child ${proc.pid} exited before the stop and its process group still has members${members ? ` (${members.map((r) => r.pid).join(", ")})` : ""}: not signalled; stop them to restart it`);
+    return;
+  }
+  if (group) return stopGroup(proc, proc.pid, termMs, killMs, table);
 
   const waitForExit = (timeoutMs: number): Promise<boolean> =>
     new Promise((resolve) => {
@@ -53,3 +148,129 @@ export async function stopOwnedProcess(proc: ChildProcess, termMs = 1_000, killM
   if (proc.exitCode !== null || proc.signalCode !== null || (await waitForExit(killMs))) return;
   throw new Error(`owned child ${proc.pid} shutdown incomplete after SIGKILL`);
 }
+
+const dropPipes = (proc: ChildProcess) => {
+  proc.stdout?.destroy();
+  proc.stderr?.destroy();
+};
+
+const emptied = new WeakSet<ChildProcess>();
+/**
+ * Follows the group of a child spawned `detached` after the child exits, until the group is gone: a later stop then
+ * never inspects the group id, which can be reused once the group is empty (issue #113).
+ */
+export function trackGroup(proc: ChildProcess): void {
+  proc.once("exit", () => {
+    const pid = proc.pid;
+    if (pid === undefined) return;
+    const check = () => { if (groupGone(pid)) emptied.add(proc); else setTimeout(check, 1_000).unref(); };
+    check();
+  });
+}
+
+/** Whether no process is left in group `pgid` (macOS answers EPERM for a group of zombies). */
+function groupGone(pgid: number): boolean {
+  try { process.kill(-pgid, 0); return false; } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    return code === "ESRCH" || (code === "EPERM" && process.platform === "darwin");
+  }
+}
+
+/**
+ * Stops a child that leads its own process group, with everything it started (issue #113). A launcher that forwards
+ * signals to a native child (Codex's `codex.js`) otherwise dies alone at SIGKILL while its child, still at work, is
+ * re-parented to init with the launcher's pipes and keeps the hub alive; and the native child starts processes that
+ * lead groups of their own (Codex's MCP servers and tool commands), which no group signal reaches.
+ *
+ * SIGTERM to the group, a grace period in which what the tree starts is recorded while its parent still runs, then
+ * freeze, enumerate, kill: what is left is stopped (SIGSTOP) before the table is read again, because a stopped process
+ * starts nothing, so that read sees all of it; then SIGKILL. A snapshot taken while the tree runs misses what it starts
+ * next (three review rounds found such a gap). Done means the table shows none of it; without any table, the group's
+ * own answer (ESRCH, or EPERM on macOS for a group of zombies) is used, which cannot see groups below it.
+ */
+async function stopGroup(proc: ChildProcess, pid: number, termMs: number, killMs: number, table: () => ProcRow[] | undefined | Promise<ProcRow[] | undefined>): Promise<void> {
+  const key = (r: { pid: number; started: string }) => `${r.pid}@${r.started}`;
+  const found = new Map<string, ProcRow>();
+  const exited = () => proc.exitCode !== null || proc.signalCode !== null;
+  let leader: ProcRow | undefined;
+  const live = (rows: ProcRow[], f: ProcRow) => rows.some((r) => r.pid === f.pid && r.started === f.started);
+  /** Reads the table and records what runs below the leader or anything recorded that still runs. */
+  const look = async (): Promise<ProcRow[] | undefined> => {
+    const rows = await table();
+    if (!rows) return undefined;
+    if (!leader && !exited()) leader = rows.find((r) => r.pid === pid); // never a pid taken over after the leader exited
+    const roots = [...(leader && live(rows, leader) ? [leader] : []), ...[...found.values()].filter((f) => live(rows, f))];
+    for (const root of roots) for (const r of descendantsOf(rows, root.pid)) found.set(key(r), r);
+    // A group is followed while it is known to be the same one: its leader or a recorded member still in it.
+    for (const id of [pid, ...[...found.values()].filter((f) => f.pgid === f.pid).map((f) => f.pid)]) {
+      // Current rows, never a recorded pgid: a member may have left the group since it was recorded.
+      const known = (id === pid && leader && live(rows, leader)) || rows.some((r) => r.pgid === id && r.pid !== id && found.has(key(r))) || rows.some((r) => r.pid === id && r.pgid === id && found.has(key(r)));
+      if (known) for (const r of rows) if (r.pgid === id && r.pid !== pid) found.set(key(r), r);
+    }
+    return rows;
+  };
+  const left = (rows: ProcRow[]) => [...found.values()].filter((f) => live(rows, f));
+  /**
+   * Running in the leader's group, or the group of a recorded process, without being recorded: after an empty moment the
+   * group id can be someone else's, so it is never signalled, but the stop is not done while it runs.
+   */
+  const unproven = (rows: ProcRow[]) => {
+    const ids = new Set([pid, ...[...found.values()].filter((f) => f.pgid === f.pid).map((f) => f.pid)]);
+    return rows.filter((r) => ids.has(r.pgid) && r.pid !== process.pid && !found.has(key(r)) && !(leader && r.pid === leader.pid && r.started === leader.started));
+  };
+  // Errors are not results here: the table read back decides. A sent signal says the target existed at that moment.
+  const signal = (target: number, sig: NodeJS.Signals) => { try { process.kill(target, sig); return true; } catch { return false; } };
+  const each = (rows: ProcRow[], sig: NodeJS.Signals) => rows.filter((r) => signal(r.pgid === r.pid ? -r.pid : r.pid, sig));
+  /** A read that takes longer than `ms` is given up: a frozen tree must not wait on a slow `ps` for its SIGKILL. */
+  const within = (ms: number) => Promise.race([look(), Bun.sleep(ms).then(() => undefined)]);
+  // What leads a group of its own (an MCP server, a tool command) gets a SIGTERM of its own and the same grace period:
+  // a git process stopped by SIGKILL leaves its index lock behind.
+  const termed = new Set<string>();
+  const term = (rows: ProcRow[] | undefined) => {
+    for (const r of rows ? left(rows) : []) if (r.pgid === r.pid && !termed.has(key(r))) { termed.add(key(r)); signal(-r.pid, "SIGTERM"); }
+  };
+  try {
+    const first = await look();
+    if (!exited()) signal(-pid, "SIGTERM"); // a reaped leader's group id is not proven any more
+    term(first);
+    // The grace period, for the leader and for what it started: what they start meanwhile is recorded while its parent
+    // still runs.
+    for (const end = Date.now() + termMs; Date.now() < end; ) {
+      await Bun.sleep(100);
+      const rows = await look();
+      term(rows);
+      if (exited() && rows && !left(rows).length) break;
+    }
+    // Freeze, enumerate, kill: a stopped process starts nothing, so a read after the freeze sees all of it.
+    for (const end = Date.now() + killMs; ; ) {
+      const rows = await look();
+      const rest = rows ? left(rows) : undefined;
+      const strangers = rows ? unproven(rows) : [];
+      if (exited() && !strangers.length && (rest ? !rest.length : !found.size && groupGone(pid))) return;
+      if (Date.now() >= end) {
+        throw new Error(`owned child ${pid}: ${rest ? `${rest.length + strangers.length} process(es) of its group or below it still running${strangers.length ? `, ${strangers.length} not proven its own and left alone` : ""}` : "the process table cannot be read to confirm what it started is gone"}`);
+      }
+      // What is stopped is killed or continued, never left frozen: the group by whether its STOP was sent (its id stays
+      // reserved while a member lives), each process by whether the read after the freeze still shows it. What a read
+      // after the freeze shows for the first time (started between the read and the STOPs, in a group of its own) is
+      // frozen too, and read again, before anything is killed.
+      const groupStopped = !exited() && signal(-pid, "SIGSTOP");
+      const stopped = new Map<string, ProcRow>();
+      let frozen: ProcRow[] | undefined;
+      for (let todo = rest ?? [], round = 0; ; round++) {
+        for (const r of each(todo, "SIGSTOP")) stopped.set(key(r), r);
+        frozen = await within(1_000);
+        todo = frozen ? left(frozen).filter((r) => !stopped.has(key(r))) : [];
+        if (!todo.length || round >= 4) break;
+      }
+      // Without a read after the freeze, only what the STOP reached is killed: a stopped process keeps its pid.
+      const kill = frozen ? left(frozen) : [...stopped.values()];
+      each(kill, "SIGKILL");
+      if (groupStopped) signal(-pid, "SIGKILL");
+      for (const r of stopped.values()) if (!kill.some((k) => k.pid === r.pid && k.started === r.started)) signal(r.pgid === r.pid ? -r.pid : r.pid, "SIGCONT");
+      await Bun.sleep(50);
+    }
+  } finally {
+    dropPipes(proc); // a process that left the tree between two reads may still hold them: it must not keep the hub alive
+  }
+}

package/src/hub/cohorts.ts

@@ -0,0 +1,308 @@
+import type { Task } from "./board.ts";
+import type { PeerId } from "./envelope.ts";
+
+/**
+ * Turn-free cohorts (issue #107): the owners of overlapping tasks, frozen into one group from the moment the overlap is
+ * found until each of them has stopped after its task closed. Whether a cohort is silent is decided when it is formed
+ * (turn-free on, no PII, every owner's context path verified) and never switched on later; it is lifted when an owner
+ * that cannot receive facts joins, a path is lost, or a PII task opens. Membership does not end when the board closes a
+ * task: a member stays in until its native turn has ended after that, so a late final answer is still the cohort's.
+ * That settlement is recorded when it happens and never undone: a settled member's later turns are new work.
+ *
+ * Completion is two-step. Each member's done is an intent. The member whose intent completes the set is selected, in
+ * one synchronous step, to integrate: it is asked to check its work against the others before its done is recorded,
+ * and its next done is accepted only for the same target (owner generation, cohort revision, files) once every other
+ * member has settled. Anything that changes the target asks again, a bounded number of times; past that the outcome is
+ * recorded as unresolved, never as integrated.
+ */
+
+/** Integration requests for one cohort revision before the outcome is recorded as unresolved. */
+export const MAX_REQUESTS = 3;
+/** A done this soon after an integration request is a retry of a lost answer, not a check of the work. */
+export const RETRY_MS = 2000;
+
+export interface Member {
+  task: number;
+  owner: PeerId;
+  /** Changes whenever the task changes hands. */
+  gen: number;
+  /** When its owner was handed the task: its writes count for the integration target from here until it settles. */
+  since: number;
+  /** When the task left the open states for its owner. */
+  closedAt?: number;
+  /** When its owner's native turn first ended after that (or the task closed while the owner was idle). */
+  settledAt?: number;
+  /** When its owner's native turn first ended after its current intent: its writes for the task have stopped. */
+  stoppedAt?: number;
+}
+
+export interface Integration {
+  task: number;
+  owner: PeerId;
+  gen: number;
+  revision: number;
+  /** The files as they were at the last request: the next done is accepted only for this target. */
+  tree: string;
+  requests: number;
+  /** When the last request went out: a done right after it is a retry, not a confirmation. */
+  at: number;
+  /** The fact offer that went out with the last request: the next done acknowledges it. */
+  offer?: string;
+  confirmed?: boolean;
+  /** The outcome was recorded as unresolved: this revision asks nothing more, and the member's check counts as usual. */
+  closed?: boolean;
+}
+
+export interface Cohort {
+  id: number;
+  /** Bumps on every change of membership or owner, when an intent is withdrawn, and when the cohort is lifted. */
+  revision: number;
+  members: Map<number, Member>;
+  silent: boolean;
+  intents: Map<number, { gen: number; at: number }>;
+  integration?: Integration;
+  /** Members whose completed-change notice the silence withheld: what replaces it if no integration runs. */
+  held: Set<number>;
+}
+
+export interface CohortDeps {
+  /** Whether these owners may work without messages: turn-free on, no PII, every owner's context path verified. */
+  silence: (owners: PeerId[]) => boolean;
+  /**
+   * Whether `peer` is between native turns now (Codex not busy; Claude's last tool call started before its last Stop).
+   * Evidence is a native turn end, never a task approval or a delivery acknowledgement.
+   */
+  idle: (peer: PeerId) => boolean;
+}
+
+export type Completion =
+  | { action: "proceed"; integrated?: boolean }
+  | { action: "request"; why: string; requests: number; cohort: Cohort }
+  | { action: "unresolved"; why: string; cohort: Cohort };
+
+export class Cohorts {
+  private readonly live: Cohort[] = [];
+  private next = 1;
+
+  constructor(private readonly d: CohortDeps) {}
+
+  /** The live cohort `task` is in. A cohort is over the moment its members have all finished, whoever asks. */
+  of(task: number): Cohort | undefined {
+    this.gc();
+    return this.live.find((c) => c.members.has(task));
+  }
+
+  list(): Cohort[] {
+    this.gc();
+    return [...this.live];
+  }
+
+  /**
+   * `task` overlaps `others` (open tasks of other owners): from now on they are one cohort. Merges cohorts the tasks were
+   * in, records owner changes (each bumps the revision and voids that member's intent), and lifts a silent cohort that
+   * an owner without verified facts joins. Returns what happened, for the notices.
+   */
+  join(task: Task, others: Task[], gen: (t: Task) => number, handed: (t: Task) => number = () => Date.now()): { cohort: Cohort; formed: boolean; lifted: boolean } | undefined {
+    this.gc();
+    const all = [task, ...others].filter((t) => t.owner);
+    const found = [...new Set(all.map((t) => this.of(t.id)).filter((c): c is Cohort => !!c))];
+    if (!found.length && all.length < 2) return undefined;
+    const wasSilent = found.some((c) => c.silent);
+    let cohort = found[0];
+    const formed = !cohort;
+    if (!cohort) {
+      cohort = { id: this.next++, revision: 0, members: new Map(), silent: false, intents: new Map(), held: new Set() };
+      this.live.push(cohort);
+    }
+    let changed = formed;
+    for (const other of found.slice(1)) {
+      for (const [id, m] of other.members) cohort.members.set(id, m);
+      for (const [id, i] of other.intents) cohort.intents.set(id, i);
+      for (const id of other.held) cohort.held.add(id);
+      cohort.silent &&= other.silent;
+      this.live.splice(this.live.indexOf(other), 1);
+      changed = true;
+    }
+    for (const t of all) {
+      const m = cohort.members.get(t.id);
+      const g = gen(t);
+      if (m && m.owner === t.owner && m.gen === g) continue;
+      cohort.members.set(t.id, { task: t.id, owner: t.owner!, gen: g, since: handed(t) });
+      cohort.intents.delete(t.id);
+      changed = true;
+    }
+    if (changed) cohort.revision++;
+    const owners = [...new Set([...cohort.members.values()].map((m) => m.owner))];
+    if (formed) cohort.silent = this.d.silence(owners);
+    else if (cohort.silent && changed && !this.d.silence(owners)) cohort.silent = false;
+    // Lifted: a silent cohort (or a silent one merged into this) is no longer silent, and its members must hear it.
+    return { cohort, formed, lifted: wasSilent && !cohort.silent };
+  }
+
+  /** An owner lost its context path: every silent cohort it is in speaks again. */
+  lift(peer: PeerId): Cohort[] {
+    return this.liftWhere((c) => [...c.members.values()].some((m) => m.owner === peer));
+  }
+
+  /** A PII task opened: every silent cohort speaks again, at once (issue #108). */
+  liftAll(): Cohort[] {
+    return this.liftWhere(() => true);
+  }
+
+  private liftWhere(pick: (c: Cohort) => boolean): Cohort[] {
+    this.gc(); // a finished cohort is not lifted: a peer leaving after the work (a benchmark's teardown) changes nothing
+    const out = this.live.filter((c) => c.silent && pick(c));
+    for (const c of out) {
+      c.silent = false;
+      c.revision++;
+    }
+    return out;
+  }
+
+  /**
+   * The silent cohort that makes a message from `from` to `to` cohort coordination: `from` is a member that has not
+   * settled since its task closed, and `to` is a member too. A settled member works on something else now.
+   */
+  silenced(from: PeerId, to: PeerId): Cohort | undefined {
+    this.gc();
+    return this.live.find((c) => {
+      if (!c.silent) return false;
+      const members = [...c.members.values()];
+      return members.some((m) => m.owner === from && m.settledAt === undefined) && members.some((m) => m.owner === to);
+    });
+  }
+
+  /** The task left the open states for its owner (done, approved, in review); an idle owner settles at once. */
+  closed(task: number, at = Date.now()): void {
+    const m = this.of(task)?.members.get(task);
+    if (!m) return;
+    m.closedAt ??= at;
+    if (m.settledAt === undefined && this.d.idle(m.owner)) m.settledAt = at;
+  }
+
+  /** `peer`'s native turn ended: its members whose tasks closed before settle, and those with an intent stop, for good. */
+  turnEnded(peer: PeerId, at = Date.now()): void {
+    for (const c of this.live) {
+      for (const m of c.members.values()) {
+        if (m.owner !== peer) continue;
+        if (m.closedAt !== undefined && m.closedAt <= at && m.settledAt === undefined) m.settledAt = at;
+        const intent = c.intents.get(m.task);
+        if (intent && intent.gen === m.gen && intent.at <= at && m.stoppedAt === undefined) m.stoppedAt = at;
+      }
+    }
+  }
+
+  /**
+   * The task is open again for its owner (a failed check, changes requested, a reopen): its intent is void, and while
+   * its cohort is live it is that cohort's work again. A cohort that is over stays over.
+   */
+  withdraw(task: number): void {
+    const c = this.of(task);
+    if (!c) return;
+    const m = c.members.get(task);
+    if (m) {
+      delete m.closedAt;
+      delete m.settledAt;
+      delete m.stoppedAt;
+    }
+    c.intents.delete(task);
+    c.revision++;
+  }
+
+  /**
+   * A done of `task` that selects nobody and asks nothing: the console finishing a member (issue #107). It still counts
+   * as that member's intent, so the member whose done completes the set integrates.
+   */
+  intent(c: Cohort, task: Task, gen: number): void {
+    if (c.intents.has(task.id) && c.intents.get(task.id)!.gen === gen) return;
+    c.intents.set(task.id, { gen, at: Date.now() });
+    const m = c.members.get(task.id);
+    if (!m) return;
+    // An owner between turns (the console finished the task, say) has stopped already; one in a turn stops when it ends.
+    if (this.d.idle(m.owner)) m.stoppedAt = Date.now();
+    else delete m.stoppedAt;
+  }
+
+  /** Whether this done of the integrating member is a retry of a lost answer: then nothing counts or is acknowledged. */
+  isRetry(c: Cohort, task: Task, gen: number): boolean {
+    const ig = c.integration;
+    return !!ig && ig.task === task.id && ig.gen === gen && ig.owner === task.owner && ig.revision === c.revision && !ig.confirmed && Date.now() - ig.at < RETRY_MS;
+  }
+
+  /**
+   * `task`'s owner called done in silent cohort `c`. Records its intent; then either it proceeds (others are still at
+   * work, another member integrates this revision, or its integration is confirmed), or it is asked to integrate (first
+   * request, or the target moved), or, past MAX_REQUESTS, the outcome is unresolved.
+   */
+  completion(c: Cohort, task: Task, now: { gen: number; tree: string; factsCurrent: boolean; handed?: number }): Completion {
+    const m = c.members.get(task.id);
+    if (!m || m.owner !== task.owner || m.gen !== now.gen) {
+      c.members.set(task.id, { task: task.id, owner: task.owner!, gen: now.gen, since: now.handed ?? Date.now() });
+      c.revision++;
+    }
+    this.intent(c, task, now.gen);
+    const missing = [...c.members.values()].filter((x) => c.intents.get(x.task)?.gen !== x.gen);
+    if (missing.length) return { action: "proceed" };
+    const ig = c.integration;
+    if (ig && ig.revision === c.revision && ig.task !== task.id) return { action: "proceed" }; // another member integrates
+    if (!ig || ig.revision !== c.revision || ig.task !== task.id || ig.gen !== now.gen || ig.owner !== task.owner) {
+      c.integration = { task: task.id, owner: task.owner!, gen: now.gen, revision: c.revision, tree: now.tree, requests: 1, at: Date.now() };
+      return { action: "request", why: "", requests: 1, cohort: c };
+    }
+    if (ig.closed) return { action: "proceed" }; // recorded as unresolved: nothing more is asked of this revision
+    // Its next done: accepted only for the same target, once every other member has settled. A later turn of a settled
+    // member that touches these files moves the target, which the file hash catches.
+    // Other owners only: the integrating owner's own other tasks in the cohort stop with this very turn.
+    const running = [...c.members.values()].filter((x) => x.owner !== task.owner && x.stoppedAt === undefined).map((x) => x.owner);
+    let why = "";
+    if (running.length) why = `${[...new Set(running)].join(", ")} has not stopped since its done, so its changes may not be final`;
+    else if (now.tree !== ig.tree) why = "the files changed since the last request";
+    else if (!now.factsCurrent) why = "there are changes you have not been shown yet";
+    if (!why) {
+      ig.confirmed = true;
+      return { action: "proceed", integrated: true };
+    }
+    if (ig.requests >= MAX_REQUESTS) {
+      ig.closed = true;
+      return { action: "unresolved", why, cohort: c };
+    }
+    ig.requests++;
+    ig.tree = now.tree;
+    ig.at = Date.now();
+    delete ig.offer;
+    delete ig.confirmed; // asked again: a done right after this is a retry, and only a later one can confirm
+    return { action: "request", why, requests: ig.requests, cohort: c };
+  }
+
+  /**
+   * Whether a check that passed for `task` counts: always, unless `task` is the confirmed integrating member of its
+   * cohort's current revision, whose check counts only for the target it confirmed. A member that stopped being the
+   * last to finish (the revision moved) is an earlier finisher again, and its own check counts.
+   */
+  holds(task: number, gen: number, tree: string): boolean {
+    const c = this.of(task);
+    const ig = c?.integration;
+    if (!c || !c.silent || !ig || ig.task !== task || ig.revision !== c.revision || ig.closed) return true;
+    return !!ig.confirmed && ig.gen === gen && ig.tree === tree;
+  }
+
+  /** The task lost its owner (released, unassigned): it leaves the cohort, and the revision moves on. */
+  leave(task: number): void {
+    const c = this.of(task);
+    if (!c) return;
+    c.members.delete(task);
+    c.intents.delete(task);
+    c.revision++;
+  }
+
+  /**
+   * A cohort is over once every member closed its task and settled (silent), or closed it (not silent: nothing is held
+   * back, so nothing waits for a turn end).
+   */
+  private gc(): void {
+    for (const c of [...this.live]) {
+      const members = [...c.members.values()];
+      if (members.every((m) => (c.silent ? m.settledAt !== undefined : m.closedAt !== undefined))) this.live.splice(this.live.indexOf(c), 1);
+    }
+  }
+}

package/src/hub/control-client.ts

@@ -6,10 +6,10 @@ export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
 }
 
-/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets. The plugin is installed apart from the daemon, so they can drift. */
-export const PROTOCOL = 12;
+/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). The plugin is installed apart from the daemon, so they can drift. */
+export const PROTOCOL = 13;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
-export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, PROTOCOL] as const;
+export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, PROTOCOL] as const;
 
 export interface Hello {
   /** `tools`: acts for `peer` (task tools, hub_send) without being a delivery target: the MCP server Kimi and Codex run. */