@idleware/ringi 0.3.0 → 0.5.0

package/target/esm/cli/agent.js

@@ -3,6 +3,7 @@ import * as Agent from '../app/agent.js';
 import { asJson, render } from '../app/view.js';
 import { fail, short, when } from '../lib/index.js';
 import { dump, flag, list, opt, out, textOf } from './args.js';
+import { scopeLine, waiting } from './shared.js';
 const options = (o) => ({ peek: flag(o, 'peek'), limit: opt(o, 'limit') ? Number(opt(o, 'limit')) : undefined });
 export const showInbox = ({ R, me, s }, res, o) => {
     if (flag(o, 'json'))
@@ -15,14 +16,19 @@ export const showInbox = ({ R, me, s }, res, o) => {
     if (res.rest)
         out(`\n(${res.rest} more: run ringi agent inbox again)`);
 };
-export const inbox = (a, o) => showInbox(a, Agent.inbox(a, options(o)), o);
+export const inbox = (a, o) => {
+    const st = Agent.started(a);
+    if (!st.started)
+        return out(waiting(a.R.name, st));
+    showInbox(a, Agent.inbox(a, options(o)), o);
+};
 export const take = (a, o) => {
     const { m, made } = Agent.take(a, o._[0] ?? fail('usage: ringi agent take <work>'));
     out(`${made ? 'took' : 'already took'} ${short(m.id)}: ${m.subject}`);
 };
 export const whoami = (a) => {
     const { session: s, profile, members } = Agent.whoami(a);
-    out(`${s.agent} in ${s.hub}/${s.room} (genesis ${short(s.genesis)}, profile ${profile}), session ${s.handle}, ${s.state}\nscope: ${s.scope ?? 'none recorded; ask the operator what to accept'}\nmembers: ${members.join(', ')}`);
+    out(`${s.agent} in ${s.hub}/${s.room} (genesis ${short(s.genesis)}, profile ${profile}), session ${s.handle}, ${s.state}\nscope: ${scopeLine(s, a.R.quorum !== null)}\nmembers: ${members.join(', ')}`);
 };
 export const card = (a, o) => out(`card ${short(Agent.card(a, textOf(o)))}`);
 export const ping = (a, o) => {

package/target/esm/cli/args.js

@@ -5,8 +5,8 @@ import { fail } from '../lib/index.js';
 import { checkPath } from '../app/room.js';
 export const out = (s = '') => { process.stdout.write(s.endsWith('\n') ? s : `${s}\n`); };
 export const dump = (v) => out(JSON.stringify(v, null, 2));
-const BOOLS = new Set(['task', 'peek', 'all', 'json', 'help', 'once', 'project', 'follow', 'short', 'yes', 'require-grant', 'md', 'archived', 'signed', 'repair', 'handoff']);
-const MULTI = new Set(['m', 'attach', 'set']);
+const BOOLS = new Set(['task', 'peek', 'all', 'json', 'help', 'once', 'project', 'follow', 'short', 'yes', 'require-grant', 'md', 'archived', 'signed', 'repair', 'handoff', 'clear', 'published']);
+const MULTI = new Set(['m', 'attach', 'set', 'drop']);
 const SHORT = { m: 'm', F: 'file', n: 'n', o: 'out', h: 'help' };
 export const parseArgs = (argv) => {
     const o = { _: [] };

package/target/esm/cli/index.js

@@ -6,9 +6,9 @@ import { flag, opt, out, parseArgs } from './args.js';
 import { watch } from '../app/agent.js';
 import { card, inbox, ping, take, wait, whoami } from './agent.js';
 import { operatorCtx } from './context.js';
-import { forget, hub, roomCmd, sessions, where } from './operator.js';
+import { forget, heartbeats, hub, pulse, roomCmd, sessions, where } from './operator.js';
 import { join, leave, resume, stop } from './session.js';
-import { cat, decide, get, grants, log, profileCmd, proposals, propose, read, reply, send, signals, stamp_, tasks, thread, who } from './shared.js';
+import { add, cat, decide, get, grants, log, profileCmd, proposals, propose, read, reply, send, signals, stamp_, tasks, thread, who } from './shared.js';
 import { skill } from './skill.js';
 // --- commands ---
 // [command, who runs it, what it does]: the one table behind `ringi help` and COMMANDS.md.
@@ -19,13 +19,13 @@ export const TABLE = [
     ['hub switch <name>', 'operator', 'change the terminal\'s current hub; agents stay where they are'],
     ['hub amend -m <subject> [--set <key>=<value>]... [--authority <file>] [--attach <file>:profiles/<name>.json]...', 'operator', 'refine the shared contract: version, capabilities, default profile, authority table, profiles'],
     ['room list [--archived]', 'operator', 'rooms of the current hub'],
-    ['room create <id> [--profile <name>]', 'operator', 'a room for one piece of work, following a profile; becomes the current room'],
+    ['room create <id> [--profile <name>] [--quorum <agents>]', 'operator', 'a room for one piece of work, following a profile; becomes the current room; --quorum: its work starts by itself once that many agents joined (1: at once)'],
     ['room migrate <id>', 'operator', 'local hubs: join the old room branches without changing message ids or sessions'],
     ['room switch <id>', 'operator', 'change the terminal\'s current room; agents stay where they are'],
     ['room admit <agent> <public key|file>', 'operator', 'signed hubs: admit the key an agent made on its own machine'],
     ['room remove <agent>', 'operator', 'local hubs: take an agent out of the current room'],
-    ['room archive <id>', 'operator', 'local hubs: read-only from now on; wakes nobody; its sessions end'],
-    ['room delete <id> --yes', 'operator', 'local hubs: erase a room and everything kept for it; its sessions leave on their own'],
+    ['room archive [<id>]', 'operator', 'local hubs: a room (default: the current one) is read-only from now on, wakes nobody; its sessions leave on their own'],
+    ['room delete [<id>] --yes', 'operator', 'local hubs: erase a room (default: the current one) and everything kept for it; its sessions leave on their own'],
     ['room rebase-contract <id>', 'operator', 'move a room onto the hub\'s current contract'],
     ['where [-n n] [--short] [--follow]', 'operator', 'hub, room, sessions (active, stopped, gone), open work and proposals, latest messages'],
     ['send -m <subject> [-m <body>]... [--to <ids>] [--task] [--re <msg>] [--state <s>] [--assign <ids>] [--roles <id>=<label>,...] [--grant <decision>] [--attach <src>[:<dest>]]...', 'operator', 'a message as operator; without --to it goes to the room and wakes nobody; --task opens work of the room\'s profile'],
@@ -33,10 +33,13 @@ export const TABLE = [
     ['stamp <proposal> approve|object|abstain -m <reason>', 'both', 'a named reviewer\'s stamp on that exact revision'],
     ['decide <proposal> approved|rejected|revoked -m <reason>', 'both', 'the named decider, with authority; an approval with a budget is a grant'],
     ['proposals [--all] | grants', 'both', 'open proposals with their stamps; grants with their usage'],
+    ['add <src>[:<dest>]... | add [--drop <path>]... [--clear]', 'both', 'stage files for your next message, like git add: their content is taken now; results and state travel only as attachments'],
     ['tasks [--all] | log [-n n] | read <msg> | thread <msg> | cat <msg> [<path>] | get <msg> [-o <dir>] | who', 'both', 'reading the room (agents: ringi agent …)'],
     ['signals [--all] [--repair]', 'both', 'what happened (signals) and where attention is (read and taken marks), each checked; --repair restores your missing signals'],
     ['profile', 'both', 'the room\'s profile: what a piece of work is, its states, who may move it'],
     ['sessions | sessions forget <handle>', 'operator', 'the chats the CLI remembers; drop a stale one'],
+    ['heartbeats [--json] | heartbeats --published [--room <id>]', 'operator', 'each session\'s pulse on this machine, from its process and its tool\'s trace, without the model: working, waiting (for what) or gone; --published: the room\'s heartbeat tags as an orchestrator reads them'],
+    ['pulse [--beat <s>] [--once]', 'operator', 'beat for every session here: sync its hub, put its heartbeat tag on the last pulled commit of its room; join and continue start it (RINGI_PULSE=off: not)'],
     ['forget <room>/<log>', 'operator', 'after a changed-history alarm: accept a new baseline for that log'],
     ['watch [<hub>:]<room>/<agent> --exec <cmd> [--handoff] [--scope <text>] [--once] [--require-grant] [--from <ids>] [--max-hop n] [--max-runs n] [--window s] [--interval s]', 'operator', 'headless turns for one agent: answers pings, spends grants, writes usage receipts; --handoff, run from the agent\'s own chat, moves its seat and scope to the watcher; exits with the failed turn\'s status'],
     ['skill install [--project] | uninstall | status | show', 'operator', 'the skill for Claude Code, Codex and Cursor'],
@@ -65,7 +68,7 @@ export const helpMarkdown = () => ['# ringi commands', '',
     '| command | who | what |', '|---|---|---|',
     ...TABLE.map(([cmd, w, what]) => `| \`ringi ${cmd.replace(/\|/g, '\\|')}\` | ${w} | ${what} |`), '',
     'Message ids are store revisions (git: commit shas), any unique prefix of 4+ characters. States and roles come from the room\'s profile (`ringi profile`).', ''].join('\n');
-const SHARED = { send, reply, read, thread, tasks, log, cat, get, who, signals, profile: profileCmd, propose, stamp: stamp_, decide, proposals, grants };
+const SHARED = { add, send, reply, read, thread, tasks, log, cat, get, who, signals, profile: profileCmd, propose, stamp: stamp_, decide, proposals, grants };
 const AGENT = { ...SHARED, inbox, whoami, status: whoami, card, ping, wait, take };
 // A reader that stops early (`ringi log | head`) closes the pipe: that ends the output, not the command's work.
 const quietPipe = (e) => { if (e.code === 'EPIPE')
@@ -98,6 +101,10 @@ export const main = async (argv = process.argv.slice(2)) => {
         return where(o);
     if (cmd === 'sessions')
         return sessions(o);
+    if (cmd === 'heartbeats')
+        return heartbeats(o);
+    if (cmd === 'pulse')
+        return pulse(o);
     if (cmd === 'forget')
         return forget(o);
     if (cmd === 'watch') {

package/target/esm/cli/operator.js

@@ -2,6 +2,7 @@
 // arguments, calls app operations and prints the result.
 import fs from 'node:fs';
 import * as Hubs from '../app/hubs.js';
+import * as Heartbeat from '../app/heartbeat.js';
 import * as Overview from '../app/overview.js';
 import * as Rooms from '../app/rooms.js';
 import { oneLine, render } from '../app/view.js';
@@ -19,7 +20,9 @@ export const where = async (o) => {
     const R = w.room;
     if (!R)
         return out('no current room: ringi room create <id> | ringi room switch <id>');
-    out(`room ${R.name}${R.archived ? ' (archived, read-only)' : ''}, genesis ${short(R.genesis)}, profile ${R.profile.name}; members: ${Object.entries(R.members).map(([id, i]) => i.role === 'root' ? `${id} (root)` : id).join(', ')}`);
+    const agents = Object.values(R.members).filter(m => m.role !== 'root').length;
+    out(`room ${R.name}${R.archived ? ' (archived, read-only)' : ''}, genesis ${short(R.genesis)}, profile ${R.profile.name}; members: ${Object.entries(R.members).map(([id, i]) => i.role === 'root' ? `${id} (root)` : id).join(', ')}`
+        + (R.quorum === null ? '' : agents >= R.quorum ? `; started at its quorum of ${R.quorum} agents` : `; waiting for a quorum of ${R.quorum} agents, has ${agents}`));
     out(w.sessions.length ? `sessions:\n${w.sessions.map(s => `  ${sessionLine(s)}`).join('\n')}` : 'sessions: none joined');
     out(w.work.length ? `open work:\n${w.work.map(t => `  ${taskLine(t)}`).join('\n')}` : 'open work: none');
     if (w.proposals.length)
@@ -40,6 +43,33 @@ export const where = async (o) => {
             show(now.all, m);
     }
 };
+// Each session's pulse on this machine, judged without the model.
+export const heartbeats = async (o) => {
+    if (flag(o, 'published')) {
+        const R = Rooms.roomIn(Hubs.hubOf(opt(o, 'hub')), opt(o, 'room'));
+        const hs = Heartbeat.published(R);
+        if (flag(o, 'json'))
+            return dump(hs);
+        if (!hs.length)
+            return out(`no heartbeats in ${R.name}`);
+        for (const h of hs)
+            out(`${h.agent.padEnd(12)} ${(h.waits ? `${h.state} (${h.waits})` : h.state).padEnd(22)} ${h.age}s ago${h.overdue ? ', overdue' : ''}  on ${short(h.target)}`);
+        return;
+    }
+    const ps = await Heartbeat.heartbeats();
+    if (flag(o, 'json'))
+        return dump(ps);
+    if (!ps.length)
+        return out('no sessions');
+    for (const { session: s, tool, beat: b } of ps) {
+        const state = b.waits ? `${b.state} (${b.waits})` : b.state;
+        out(`${s.agent.padEnd(12)} ${`${s.hub}/${s.room}`.padEnd(24)} ${state.padEnd(22)} alive ${b.alive === null ? '?' : b.alive ? 'yes' : 'no'}  quiet ${b.quiet}s${b.cpu === null ? '' : `  cpu ${b.cpu.toFixed(1)}s`}  ${tool}  ${s.handle}`);
+    }
+};
+// The process that beats for every session here; `join` and `continue` start it.
+export const pulse = async (o) => {
+    process.exitCode = await Heartbeat.pulse({ every: Number(opt(o, 'beat') ?? 30), once: flag(o, 'once'), log: s => process.stderr.write(`ringi: ${s}\n`) });
+};
 export const sessions = (o) => {
     if (o._[0] === 'forget') {
         const handle = o._[1] ?? fail('usage: ringi sessions forget <handle>');
@@ -108,7 +138,10 @@ export const roomCmd = (o) => {
         return;
     }
     if (sub === 'create') {
-        const r = Rooms.create(H, arg ?? '', { profile: opt(o, 'profile') });
+        const quorum = opt(o, 'quorum');
+        const r = Rooms.create(H, arg ?? '', { profile: opt(o, 'profile'), quorum: quorum === undefined ? undefined : Number(quorum) });
+        if (quorum !== undefined)
+            return out(`created room ${arg} in hub ${H.name} with profile ${r.profile}; it is the current room. Its work starts by itself at a quorum of ${quorum} agent(s): in each chat that should take part, say "join ${arg} as <id>"`);
         return out(`created room ${arg} in hub ${H.name} with profile ${r.profile}; it is the current room. In each chat that should take part, say: "join ${arg} as <id>; <what to accept>"`);
     }
     if (sub === 'migrate') {
@@ -130,14 +163,15 @@ export const roomCmd = (o) => {
         return out(`removed ${arg} from ${R.name}: it can no longer write or be woken there; returning needs a fresh join`);
     }
     if (sub === 'archive') {
-        const R = Rooms.roomIn(H, arg ?? fail('usage: ringi room archive <id>'));
+        // Without an id, the room of the current context.
+        const R = Rooms.roomIn(H, arg ?? opt(o, 'room'));
         const name = Rooms.archive(H, R);
         return out(`archived ${R.name} as ${name}: read-only, wakes nobody; its sessions end. Read it with --room ${name}`);
     }
     if (sub === 'delete') {
-        const R = Rooms.roomIn(H, arg ?? fail('usage: ringi room delete <id> --yes'));
+        const R = Rooms.roomIn(H, arg ?? opt(o, 'room'));
         if (!flag(o, 'yes'))
-            fail(`deleting ${R.name} removes its history from the hub for good. Run again with --yes, or archive it instead`);
+            fail(`deleting ${R.name} in hub ${H.name} erases it and everything kept for it, for good. Run again with --yes, or archive it instead`);
         Rooms.erase(H, R);
         return out(`deleted room ${R.name}: its branch, signals, pins, evidence and readers' state. Sessions bound to it leave it on their next turn`);
     }

package/target/esm/cli/session.js

@@ -1,13 +1,19 @@
 // Session interface: the operator's words become typed app requests.
+import * as Heartbeat from '../app/heartbeat.js';
 import * as Session from '../app/session.js';
 import { fail } from '../lib/index.js';
 import { opt, out } from './args.js';
 import { showInbox } from './agent.js';
-import { taskLine } from './shared.js';
+import { scopeLine, taskLine, waiting } from './shared.js';
 export const briefing = (s) => {
     const r = Session.briefing(s);
-    out(`${s.agent} in ${s.hub}/${s.room}; scope: ${s.scope ?? 'none recorded; ask the operator what to accept'}`);
+    const auto = r.start.quorum !== null;
+    out(`${s.agent} in ${s.hub}/${s.room}; scope: ${scopeLine(s, auto)}`);
     out('agent commands: ringi agent inbox | reply <id> … | send … | tasks | proposals | whoami. A turn: inbox, your part, replies, end the turn. Never block on a peer.');
+    if (!r.start.started)
+        return out(waiting(s.room, r.start));
+    if (auto)
+        out(`started: room ${s.room} has its quorum (${r.start.agents} of ${r.start.quorum} agents); your first turn starts now, on the work and inbox below; nothing to confirm with the operator`);
     if (!r.tasks.length)
         out(`no open work (profile ${r.actor.R.profile.name}; tasks --all for everything)`);
     for (const task of r.tasks)
@@ -25,9 +31,14 @@ export const join = (o) => {
         return;
     }
     out(`joined ${r.hub}/${r.room} as ${r.agent}`);
+    Heartbeat.ensurePulse(process.argv[1]);
     briefing(r.session);
 };
-export const resume = (o) => briefing(Session.resume(o._[0]));
+export const resume = (o) => {
+    const s = Session.resume(o._[0]);
+    Heartbeat.ensurePulse(process.argv[1]);
+    briefing(s);
+};
 export const stop = () => {
     const s = Session.stop();
     out(`stopped: ${s.agent} keeps its seat in ${s.hub}/${s.room} and reacts to nothing until the operator says "continue"`);

package/target/esm/cli/shared.js

@@ -6,12 +6,22 @@ import * as Budget from '../app/budget.js';
 import * as Room from '../app/room.js';
 import { checkPath, withSizes } from '../app/room.js';
 import { asJson, oneLine, render } from '../app/view.js';
-import { fail, note, short, when, words } from '../lib/index.js';
+import { bytes, fail, note, short, when, words } from '../lib/index.js';
 import { attachments, dump, flag, list, opt, out, textOf } from './args.js';
 const sendInput = (o) => ({ text: textOf(o), to: words(opt(o, 'to')), all: flag(o, 'all'), task: flag(o, 'task'),
     state: opt(o, 'state'), assign: opt(o, 'assign') ? words(opt(o, 'assign')) : undefined, roles: opt(o, 'roles'), grant: opt(o, 'grant'),
     files: list(o, 'attach').flatMap(attachments) });
 const sent = (r) => out(`sent ${short(r.id)} to ${r.to.join(', ')}${r.files ? ` with ${r.files} file(s)` : ''}`);
+// Stages files for the actor's next message, like git add: their content is taken into the hub now. Without files it
+// lists what is staged; --drop <path> and --clear take files back out.
+export const add = (a, o) => {
+    if (flag(o, 'clear'))
+        Room.unstage(a, null);
+    else if (list(o, 'drop').length)
+        Room.unstage(a, list(o, 'drop'));
+    const staged = o._.length ? Room.stage(a, o._.flatMap(attachments)) : Room.staged(a);
+    out(staged.length ? `staged for your next message:\n${staged.map(s => `  ${s.path} (${bytes(s.size)})`).join('\n')}` : 'nothing staged');
+};
 export const send = (a, o) => sent(Room.send(a, { ...sendInput(o), re: opt(o, 're') }));
 export const reply = (a, o) => sent(Room.send(a, { ...sendInput(o), re: o._[0] ?? fail('usage: reply <msg> -m <text> …'), reply: true }));
 export const read = (a, o) => {
@@ -140,4 +150,10 @@ export const grants = (a, o) => {
         out(`${short(g.grant)}  ${g.revoked ? 'revoked ' : u.left ? 'active  ' : 'spent   '} runs ${u.runs}/${g.budget.runs}, open ${u.open}${u.uncertain ? `, uncertain ${u.uncertain}` : ''}, ${u.seconds}s used, ≤${g.budget['run-seconds']}s a run, concurrency ${g.budget.concurrency}  ${g.subject}`);
     }
 };
+// What the session may do on its own: the recorded scope; without one, in a room with a quorum the room's work for it,
+// in any other what the operator accepts when asked.
+export const scopeLine = (s, quorum = false) => s.scope
+    ?? (quorum ? 'none recorded; the room\'s work for you, split with the other members' : 'none recorded; ask the operator what to accept');
+// The line that keeps an agent of a room waiting for its quorum from doing anything yet.
+export const waiting = (room, st) => `waiting: room ${room} waits for a quorum of ${st.quorum} agents and has ${st.agents}; nothing to do yet, end the turn. Its work starts by itself at the quorum`;
 //# sourceMappingURL=shared.js.map

package/target/esm/heartbeat/index.js

@@ -0,0 +1,41 @@
+// heartbeat: whether an agent is alive, and working or waiting, judged from what its machine shows without asking the
+// model, so no tokens are spent on it. The facts: its process and process tree (platform.ts), the trace its tool
+// writes (tools.ts) and ringi's own session record. What to do about a silent or stuck agent is the orchestrator's.
+import { SUPPORTED, alive, table, treeCpu } from './platform.js';
+import { toolOf, traceTime } from './tools.js';
+// The facts of one session now; `rows` lets one `ps` call serve many sessions.
+export const probe = (s, waits = null, rows = SUPPORTED ? table() : null) => ({
+    at: Date.now() / 1000,
+    alive: s.pid && SUPPORTED ? alive(s.pid) : null,
+    cpu: s.pid && s.product === 'watch' ? treeCpu(s.pid, rows) : null,
+    trace: traceTime(s),
+    seen: Date.parse(s.lastSeen) / 1000,
+    stopped: s.state === 'stopped',
+    waits,
+});
+export const tracedBy = (s) => toolOf(s)?.tool ?? (s.product === 'watch' ? 'watch' : 'none');
+// working: its process tree used CPU since the previous look, or its trace or a ringi command is younger than
+// `active` seconds; waiting: alive but neither, or kept waiting by the operator or its room; gone: its process is
+// known to have ended.
+export const judge = (cur, prev = null, { active = 120, next = 30 } = {}) => {
+    const quiet = Math.max(0, Math.round(cur.at - Math.max(cur.seen, cur.trace ?? 0)));
+    const base = { alive: cur.alive, quiet, cpu: cur.cpu, next };
+    if (cur.alive === false)
+        return { ...base, state: 'gone', waits: null };
+    if (cur.stopped)
+        return { ...base, state: 'waiting', waits: 'stopped' };
+    if (cur.waits)
+        return { ...base, state: 'waiting', waits: cur.waits };
+    const spent = prev?.cpu != null && cur.cpu != null && cur.cpu - prev.cpu >= 0.05;
+    return spent || quiet < active ? { ...base, state: 'working', waits: null } : { ...base, state: 'waiting', waits: 'inbox' };
+};
+// The text of a heartbeat: facts as trailers, no word of the work itself.
+export const body = (b) => [
+    `State: ${b.state}`,
+    ...(b.waits ? [`Waits: ${b.waits}`] : []),
+    `Alive: ${b.alive === null ? 'unknown' : b.alive ? 'yes' : 'no'}`,
+    `Quiet: ${b.quiet}`,
+    ...(b.cpu === null ? [] : [`CPU: ${b.cpu.toFixed(1)}`]),
+    `Next: ${b.next}`,
+].join('\n') + '\n';
+//# sourceMappingURL=index.js.map

package/target/esm/heartbeat/platform.js

@@ -0,0 +1,83 @@
+// platform: what the operating system says about a process, on macOS and Linux (Ubuntu). Elsewhere every probe says
+// nothing (null) rather than guess.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+export const SUPPORTED = process.platform === 'darwin' || process.platform === 'linux';
+// Whether the process exists; a process of another user that we may not signal still exists.
+export const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+};
+// `ps` cumulative CPU time: `[DD-][HH:]MM:SS[.ss]` on both systems.
+export const seconds = (time) => {
+    const [days, rest] = time.includes('-') ? [Number(time.split('-')[0]), time.split('-')[1]] : [0, time];
+    return days * 86400 + rest.split(':').reduce((acc, part) => acc * 60 + Number(part), 0);
+};
+// One line of /proc/<pid>/stat: the parent and the CPU seconds (user + system, in clock ticks of 1/100 s). The command
+// name is in parentheses and may hold spaces, so the fields are counted after the last `)`.
+export const procStat = (line) => {
+    const f = line.slice(line.lastIndexOf(')') + 2).split(' ');
+    const ppid = Number(f[1]), cpu = (Number(f[11]) + Number(f[12])) / 100;
+    return Number.isFinite(ppid) && Number.isFinite(cpu) ? { ppid, cpu } : null;
+};
+// Linux: /proc gives CPU to the hundredth of a second, where `ps` rounds to whole seconds.
+const proc = () => {
+    let pids;
+    try {
+        pids = fs.readdirSync('/proc').filter(d => /^\d+$/.test(d));
+    }
+    catch {
+        return null;
+    }
+    const rows = new Map();
+    for (const pid of pids) {
+        try {
+            const row = procStat(fs.readFileSync(`/proc/${pid}/stat`, 'utf8'));
+            if (row)
+                rows.set(Number(pid), row);
+        }
+        catch { /* the process ended meanwhile */ }
+    }
+    return rows.size ? rows : null;
+};
+// Every process with its parent and CPU seconds: /proc on Linux, else one `ps` call.
+export const table = () => {
+    if (!SUPPORTED)
+        return null;
+    if (process.platform === 'linux') {
+        const rows = proc();
+        if (rows)
+            return rows;
+    }
+    const r = spawnSync('ps', ['-A', '-o', 'pid=,ppid=,time='], { encoding: 'utf8', timeout: 10000 });
+    if (r.status !== 0)
+        return null;
+    const rows = new Map();
+    for (const line of r.stdout.split('\n')) {
+        const [pid, ppid, time] = line.trim().split(/\s+/);
+        if (pid && time)
+            rows.set(Number(pid), { ppid: Number(ppid), cpu: seconds(time) });
+    }
+    return rows;
+};
+// CPU seconds the process and all its descendants used so far: a turn's model client, its tools and their children.
+export const treeCpu = (pid, rows = table()) => {
+    if (!rows?.has(pid))
+        return null;
+    const children = new Map();
+    for (const [p, { ppid }] of rows)
+        children.set(ppid, [...children.get(ppid) ?? [], p]);
+    let sum = 0;
+    for (const stack = [pid]; stack.length;) {
+        const p = stack.pop();
+        sum += rows.get(p)?.cpu ?? 0;
+        stack.push(...children.get(p) ?? []);
+    }
+    return sum;
+};
+//# sourceMappingURL=platform.js.map

package/target/esm/heartbeat/tools.js

@@ -0,0 +1,68 @@
+// tools: the trace each agent tool writes of a session while it works, found by the session's id. Its modification
+// time is the session's own activity, unlike the CPU of an app process that hosts many sessions.
+//   Claude Code   $CLAUDE_CONFIG_DIR (or ~/.claude)/projects/<dir>/<session id>.jsonl, the session's transcript
+//   Codex         $CODEX_HOME (or ~/.codex)/sessions/<yyyy>/<mm>/<dd>/rollout-<time>-<thread id>.jsonl
+// A ringi watcher writes no trace of its own: the CPU of its process tree speaks for its turn (platform.ts).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const UUID = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+const dirs = (d) => { try {
+    return fs.readdirSync(d).sort().reverse();
+}
+catch {
+    return [];
+} };
+const mtime = (f) => { try {
+    return fs.statSync(f).mtimeMs / 1000;
+}
+catch {
+    return null;
+} };
+const claude = (id) => {
+    const root = path.join(process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), '.claude'), 'projects');
+    for (const d of dirs(root))
+        if (fs.existsSync(path.join(root, d, `${id}.jsonl`)))
+            return path.join(root, d, `${id}.jsonl`);
+    return null;
+};
+const codex = (id) => {
+    const root = path.join(process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex'), 'sessions');
+    for (const y of dirs(root))
+        for (const m of dirs(path.join(root, y)))
+            for (const d of dirs(path.join(root, y, m))) {
+                const f = dirs(path.join(root, y, m, d)).find(n => n.startsWith('rollout-') && n.endsWith(`-${id}.jsonl`));
+                if (f)
+                    return path.join(root, y, m, d, f);
+            }
+    return null;
+};
+// A trace once found keeps its path; only its time is read again.
+const found = new Map();
+// Which tool a session runs and the id its trace is named by: Claude Code sessions are `claude:<id>`; a Codex chat
+// names itself with RINGI_SESSION=codex-<thread id>.
+export const toolOf = (s) => {
+    const id = UUID.exec(s.handle)?.[1];
+    if (!id)
+        return null;
+    if (s.handle.startsWith('claude:') || s.product === 'claude')
+        return { tool: 'claude', id };
+    if (s.product === 'codex' || s.handle.startsWith('env:codex-'))
+        return { tool: 'codex', id };
+    return null;
+};
+// When the session's tool last wrote its trace (unix seconds), or null: no tool known, or no trace found.
+export const traceTime = (s) => {
+    const t = toolOf(s);
+    if (!t)
+        return null;
+    const key = `${t.tool}:${t.id}`;
+    if (!found.has(key)) {
+        const f = t.tool === 'claude' ? claude(t.id) : codex(t.id);
+        if (!f)
+            return null;
+        found.set(key, f);
+    }
+    return mtime(found.get(key));
+};
+//# sourceMappingURL=tools.js.map

package/target/esm/hub/index.js

@@ -16,6 +16,11 @@ import { fail, short, strictJson } from '../lib/index.js';
 export const HUB_MAJOR = 1;
 export const CAPS = new Set(Object.keys(CAPABILITIES));
 export const RESERVED_ROOMS = new Set(['main', 'archive']);
+// Whether the room's work has started: it has the quorum of agents its genesis asked for (`Quorum`), or asked for none.
+export const start = (R) => {
+    const agents = Object.values(R.members).filter(m => m.role !== 'root').length;
+    return { quorum: R.quorum, agents, started: R.quorum === null || agents >= R.quorum };
+};
 // --- hubs ---
 export const hubNames = () => {
     try {
@@ -151,8 +156,15 @@ export const openRoom = (H, name, { quiet = false } = {}) => {
         ?? (baseProfile === DEFAULT_PROFILE ? readProfileResource(DEFAULT_PROFILE) : fail(`room ${name}: unknown profile ${baseProfile}`));
     const roster = H.store.roster(s);
     const members = roster?.members ?? strictJson(H.store.controlFile(s, 'members.json') ?? '{}', `room ${name}: members.json`);
+    // The root's control records set the quorum; the latest one counts.
+    let quorum = null;
+    for (const rec of s.control) {
+        const m = /^Quorum: ([1-9][0-9]?)$/m.exec(rec.text);
+        if (m)
+            quorum = Number(m[1]);
+    }
     return { hub: H, s, name, archived: s.archived, head: s.head, genesis: s.genesis, contractRev: current, contract, authorityAt,
-        profile: parseProfile(profileText, `room ${name}: profile`), members };
+        profile: parseProfile(profileText, `room ${name}: profile`), members, quorum };
 };
 export const room = (H, name) => openRoom(H, name);
 export const ROOM_MD = (name) => `# room ${name}\n\nA ringi room: members.json lists who takes part; profile.json is what a piece of work is here, fixed when the room was made.\n`;

package/target/esm/runtime/watch.js

@@ -4,7 +4,7 @@
 import { spawn } from 'node:child_process';
 import * as D from '../domain/decisions.js';
 import { HOME, OPERATOR, config, locked } from '../home/index.js';
-import { HIDDEN, append, openHub, openRoom, pongText } from '../hub/index.js';
+import { HIDDEN, append, openHub, openRoom, pongText, start } from '../hub/index.js';
 import { loadRoomUnlocked, loadState, readerLock, saveState } from './reader.js';
 import { isOpen, taskFor, taskOf } from '../domain/profiles.js';
 import { compose, link, unread, wakes } from '../protocol/index.js';
@@ -137,6 +137,16 @@ export const watch = async (w, log = note) => {
             log(`watch: ${me} was removed from ${R0.name}; stopping`);
             return 0;
         }
+        // A room waiting for its quorum runs no turn yet.
+        const st = start(R);
+        if (!st.started) {
+            if (w.once) {
+                log(`watch: ${R0.name} waits for a quorum of ${st.quorum} agents and has ${st.agents}; nothing to do yet`);
+                return 0;
+            }
+            await sleep(interval);
+            continue;
+        }
         const P = R.profile;
         // Lock order throughout planning and dispatch: grant, reader, sessions (then the store's own writes).
         const plan = locked(`grant-${H.name}`, () => readerLock(R, me, () => {