@idleware/ringi 0.4.0 → 0.5.0

package/README.md

@@ -22,7 +22,7 @@ npm i -g @idleware/ringi
 ringi skill install
 ```
 
-Node.js 16 or later.
+macOS or Linux, Node.js 16 or later, git 2.28 or later.
 
 ## Local: one machine, several agents
 

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@idleware/ringi",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Distributed agent coordinator",
+  "os": [
+    "darwin",
+    "linux"
+  ],
   "keywords": [
     "agents",
     "multi-agent",

package/target/dts/app/heartbeat.d.ts

@@ -0,0 +1,33 @@
+import * as HB from '../heartbeat/index.ts';
+import type { Room } from '../hub/index.ts';
+import type { Session } from '../runtime/session.ts';
+export type Pulse = {
+    session: Session;
+    tool: string;
+    beat: HB.Beat;
+};
+export declare const heartbeats: ({ sample }?: {
+    sample?: number;
+}) => Promise<Pulse[]>;
+export declare const ensurePulse: (cli: string) => void;
+export type Beaten = {
+    session: Session;
+    beat?: HB.Beat;
+    error?: string;
+};
+export declare const beatAll: (prev: Map<string, HB.Facts>, next: number) => Beaten[];
+export declare const pulse: ({ every, once, log }: {
+    every?: number;
+    once?: boolean;
+    log: (s: string) => void;
+}) => Promise<number>;
+export declare const published: (R: Room) => {
+    agent: string;
+    target: import("../index.ts").Rev;
+    time: number;
+    text: string;
+    state: string;
+    waits: string | null;
+    age: number;
+    overdue: boolean;
+}[];

package/target/dts/app/room.d.ts

@@ -28,9 +28,10 @@ export type Sent = {
     to: string[];
     files: number;
 };
+export declare const FILE_MAX: number;
 export declare const staged: ({ R, me }: Actor) => Staged[];
 export declare const stage: ({ R, me }: Actor, files: Entry[]) => Staged[];
-export declare const unstage: ({ R, me }: Actor, paths: string[] | null) => Staged[];
+export declare const unstage: (a: Actor, paths: string[] | null) => Staged[];
 export declare const send: ({ R, me }: Actor, x: SendInput) => Sent;
 export declare const marks: (R: Room, all: All) => Map<string, Record<string, string[]>>;
 export declare const message: ({ R, me }: Actor, ref: string) => {

package/target/dts/cli/operator.d.ts

@@ -2,6 +2,8 @@ import type { SessionView } from '../app/overview.ts';
 import type { Opts } from './args.ts';
 export declare const sessionLine: (s: SessionView) => string;
 export declare const where: (o: Opts) => Promise<void>;
+export declare const heartbeats: (o: Opts) => Promise<void>;
+export declare const pulse: (o: Opts) => Promise<void>;
 export declare const sessions: (o: Opts) => void;
 export declare const forget: (o: Opts) => void;
 export declare const hub: (o: Opts) => void;

package/target/dts/heartbeat/index.d.ts

@@ -0,0 +1,35 @@
+export type Facts = {
+    at: number;
+    alive: boolean | null;
+    cpu: number | null;
+    trace: number | null;
+    seen: number;
+    stopped: boolean;
+    waits: string | null;
+};
+export type State = 'working' | 'waiting' | 'gone';
+export type Beat = {
+    state: State;
+    waits: string | null;
+    alive: boolean | null;
+    quiet: number;
+    cpu: number | null;
+    next: number;
+};
+export type SessionLike = {
+    handle: string;
+    product: string | null;
+    pid: number | null;
+    lastSeen: string;
+    state: string;
+};
+export declare const probe: (s: SessionLike, waits?: string | null, rows?: Map<number, {
+    ppid: number;
+    cpu: number;
+}> | null) => Facts;
+export declare const tracedBy: (s: Pick<SessionLike, 'handle' | 'product'>) => string;
+export declare const judge: (cur: Facts, prev?: Facts | null, { active, next }?: {
+    active?: number;
+    next?: number;
+}) => Beat;
+export declare const body: (b: Beat) => string;

package/target/dts/heartbeat/platform.d.ts

@@ -0,0 +1,15 @@
+export declare const SUPPORTED: boolean;
+export declare const alive: (pid: number) => boolean;
+export declare const seconds: (time: string) => number;
+export declare const procStat: (line: string) => {
+    ppid: number;
+    cpu: number;
+} | null;
+export declare const table: () => Map<number, {
+    ppid: number;
+    cpu: number;
+}> | null;
+export declare const treeCpu: (pid: number, rows?: Map<number, {
+    ppid: number;
+    cpu: number;
+}> | null) => number | null;

package/target/dts/heartbeat/tools.d.ts

@@ -0,0 +1,11 @@
+export declare const toolOf: (s: {
+    handle: string;
+    product: string | null;
+}) => {
+    tool: 'claude' | 'codex';
+    id: string;
+} | null;
+export declare const traceTime: (s: {
+    handle: string;
+    product: string | null;
+}) => number | null;

package/target/dts/store/git/index.d.ts

@@ -15,6 +15,8 @@ export declare class GitStore implements Store {
     readonly home: string;
     readonly h: Remote.Handle;
     constructor(hubDir: string, d: Descriptor, home: string);
+    private openable;
+    private checkout;
     private args;
     private git;
     private gitOk;
@@ -57,7 +59,11 @@ export declare class GitStore implements Store {
     logIds(room: StoredRoom): string[];
     logHead(room: StoredRoom, id: string): string | null;
     messages(room: StoredRoom, id: string, head: string): StoredMessage[];
-    blob(file: string): string;
+    blob(file: string): {
+        id: string;
+        size: number;
+    };
+    retain(room: StoredRoom, who: string, entries: Entry[]): void;
     append(room: StoredRoom, who: string, text: string, entries: Entry[]): string;
     private onTop;
     verifyLog(room: StoredRoom, id: string, head: string): string | null;
@@ -65,6 +71,13 @@ export declare class GitStore implements Store {
     unpin(room: StoredRoom, reader: string, id: string): void;
     file(rev: string, p: string): Buffer;
     sizes(rev: string, paths: string[]): Map<string, number>;
+    heartbeat(room: StoredRoom, who: string, target: string, text: string): string;
+    heartbeats(room: StoredRoom): Array<{
+        agent: string;
+        target: string;
+        time: number;
+        text: string;
+    }>;
     signal(room: StoredRoom, who: string, target: string, name: string): void;
     private tags;
     private tagObjects;

package/target/dts/store/git/remote.d.ts

@@ -6,6 +6,7 @@ export type Handle = {
     d: Descriptor;
     main?: string;
     remoteAlarms?: Record<string, string>;
+    heartbeatErrors?: Record<string, string>;
     bootstrap?: boolean;
 };
 export type Room = {
@@ -65,6 +66,13 @@ export declare const readCommits: (H: Handle, shas: string[]) => Raw[];
 export declare const branch: (H: Handle, R: Pick<Room, 'name' | 'ref' | 'genesis'>, tip: string) => Branch;
 export declare const verifyRoom: (H: Handle, R: Room) => VerifiedRoom;
 export declare const verify: (H: Handle, R: Room, who: string, head: string) => string | null;
+export declare const heartbeatName: (ref: string) => {
+    actor: string;
+    genesis12: string;
+} | null;
+export declare const heartbeatRef: (who: string, genesis: string) => string;
+export declare const verifyHeartbeat: (H: Handle, R: Room, ref: string, sha: string) => string | null;
+export declare const makeHeartbeat: (H: Handle, R: Room, who: string, target: string, text: string, home: string) => string;
 export declare const verifySignal: (H: Handle, R: Room, ref: string, sha: string) => string | null;
 export declare const sync: (H: Handle) => Handle;
 export declare const hubAdd: ({ home, name, url, root, genesis }: {
@@ -83,4 +91,5 @@ export declare const roomAdmit: (H: Handle, R: Room, who: string, publicKey: str
 export declare const push: (H: Handle, ref: string, { behind }?: {
     behind?: boolean;
 }) => boolean;
+export declare const pushHeartbeat: (H: Handle, R: Room, who: string, sha: string, expected: string | null) => boolean;
 export declare const forget: (H: Handle, R: Room) => void;

package/target/dts/store/index.d.ts

@@ -75,7 +75,11 @@ export interface Store {
     extends(older: Rev, newer: Rev): boolean;
     messages(room: StoredRoom, id: string, head: Rev): StoredMessage[];
     append(room: StoredRoom, who: string, text: string, entries: Entry[]): Rev;
-    blob(file: string): Rev;
+    blob(file: string): {
+        id: Rev;
+        size: number;
+    };
+    retain(room: StoredRoom, who: string, entries: Entry[]): void;
     alarms?(room: StoredRoom): string[];
     verifyLog(room: StoredRoom, id: string, head: Rev): string | null;
     pin(room: StoredRoom, reader: string, id: string, rev: Rev): void;
@@ -84,6 +88,13 @@ export interface Store {
     sizes(rev: Rev, paths: string[]): Map<string, number>;
     signal(room: StoredRoom, who: string, target: Rev, name: string): void;
     signals(room: StoredRoom): SignalRecord[];
+    heartbeat?(room: StoredRoom, who: string, target: Rev, text: string): Rev;
+    heartbeats?(room: StoredRoom): Array<{
+        agent: string;
+        target: Rev;
+        time: number;
+        text: string;
+    }>;
     admit?(room: StoredRoom, who: string, key: string): Rev;
     joinKey?(room: StoredRoom, who: string): JoinKey;
     forgetLog?(room: StoredRoom, id: string): void;

package/target/esm/app/heartbeat.js

@@ -0,0 +1,110 @@
+// heartbeat: the pulse of every session this machine holds, judged from its process and its tool's trace without the
+// model (heartbeat/). It reads session records only: it never binds a session, renews its lease or marks anything read.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as HB from '../heartbeat/index.js';
+import { alive, table } from '../heartbeat/platform.js';
+import { HOME, locked } from '../home/index.js';
+import { openHub, openRoom, start } from '../hub/index.js';
+import { sleep } from '../lib/index.js';
+import { allSessions } from '../runtime/session.js';
+// What the room keeps the session waiting for, if anything; a hub that cannot be read says nothing.
+const roomWaits = (s) => {
+    try {
+        const R = openRoom(openHub(s.hub), s.room, { quiet: true });
+        return R && R.genesis === s.genesis && !start(R).started ? 'quorum' : null;
+    }
+    catch {
+        return null;
+    }
+};
+// Two looks `sample` seconds apart when a watcher is among them, so the CPU its turn spent shows.
+export const heartbeats = async ({ sample = 1 } = {}) => {
+    const ss = allSessions();
+    const waits = ss.map(roomWaits);
+    const first = ss.map((s, i) => HB.probe(s, waits[i], table()));
+    if (ss.some(s => s.product === 'watch'))
+        await sleep(sample * 1000);
+    const rows = table();
+    return ss.map((s, i) => ({ session: s, tool: HB.tracedBy(s), beat: HB.judge(HB.probe(s, waits[i], rows), first[i]) }));
+};
+// --- pulse: the process that beats for every session here, with no model in it ---
+const PIDFILE = () => path.join(HOME, 'pulse.pid');
+const running = () => {
+    try {
+        const pid = Number(fs.readFileSync(PIDFILE(), 'utf8'));
+        return pid && pid !== process.pid && alive(pid) ? pid : null;
+    }
+    catch {
+        return null;
+    }
+};
+// Starts the pulse in the background unless one runs (or RINGI_PULSE=off): join and continue call it.
+export const ensurePulse = (cli) => {
+    if (process.env.RINGI_PULSE === 'off' || running())
+        return;
+    spawn(process.execPath, [cli, 'pulse'], { detached: true, stdio: 'ignore', env: process.env }).unref();
+};
+export const beatAll = (prev, next) => {
+    const rows = table();
+    return allSessions().flatMap((s) => {
+        try {
+            const H = openHub(s.hub);
+            const R = openRoom(H, s.room, { quiet: true });
+            // A gone room: the session leaves it on its own; nothing to beat for.
+            if (!R || R.genesis !== s.genesis || !H.store.heartbeat)
+                return [];
+            const f = HB.probe(s, start(R).started ? null : 'quorum', rows);
+            const b = HB.judge(f, prev.get(s.handle) ?? null, { next });
+            prev.set(s.handle, f);
+            H.store.heartbeat(R.s, s.agent, R.s.tip, HB.body(b));
+            return [{ session: s, beat: b }];
+        }
+        catch (e) {
+            return [{ session: s, error: e.message }];
+        }
+    });
+};
+// The loop: one pulse per home, beating every `every` seconds until no session is left or the home is gone.
+export const pulse = async ({ every = 30, once = false, log }) => {
+    // Claimed under the home's lock, so two starts at once leave one pulse.
+    const other = locked('pulse', () => {
+        const pid = running();
+        if (!pid)
+            fs.writeFileSync(PIDFILE(), String(process.pid));
+        return pid;
+    });
+    if (other) {
+        log(`pulse: already running (pid ${other})`);
+        return 0;
+    }
+    const prev = new Map();
+    try {
+        for (let idle = 0; idle < 2;) {
+            const beats = beatAll(prev, every);
+            for (const b of beats)
+                if (b.error)
+                    log(`pulse: ${b.session.agent} in ${b.session.hub}/${b.session.room}: ${b.error}`);
+            idle = beats.length ? 0 : idle + 1;
+            if (once || !fs.existsSync(HOME))
+                break;
+            await sleep(every * 1000);
+        }
+    }
+    finally {
+        try {
+            if (Number(fs.readFileSync(PIDFILE(), 'utf8')) === process.pid)
+                fs.rmSync(PIDFILE());
+        }
+        catch { }
+    }
+    return 0;
+};
+// What the room's published heartbeats say, as an orchestrator would read them: whose, how old, overdue or not.
+export const published = (R) => (R.hub.store.heartbeats?.(R.s) ?? []).map(h => {
+    const next = Number(/^Next: (\d+)$/m.exec(h.text)?.[1] ?? NaN);
+    const age = Math.max(0, Math.round(Date.now() / 1000 - h.time));
+    return { ...h, state: /^State: (\w+)$/m.exec(h.text)?.[1] ?? '?', waits: /^Waits: (.+)$/m.exec(h.text)?.[1] ?? null, age, overdue: Number.isFinite(next) && age > next * 2 };
+});
+//# sourceMappingURL=heartbeat.js.map

package/target/esm/app/room.js

@@ -14,11 +14,23 @@ import { linked, loadRoomUnlocked, loadState, readerLock, saveState } from '../r
 import { taskView } from './view.js';
 export const isRef = (R) => (x) => R.hub.store.isRef(x);
 // Staging, like git's index: add takes a file's content into the store now, and the actor's next message carries it,
-// whatever happens to the file meanwhile. Results and state travel only so, never through a shared directory.
+// whatever happens to the file meanwhile. Results and state travel only so, never through a shared directory. The store
+// keeps staged contents reachable (`retain`); it grows before the list does and shrinks after, so a crash in between
+// leaks an object rather than loses one.
+export const FILE_MAX = 64 << 20;
+const tooBig = (path, size) => size > FILE_MAX && fail(`${path} is ${Math.ceil(size / (1 << 20))} MiB; an attachment is at most ${FILE_MAX >> 20} MiB`);
+// What retain keeps: each staged content once, named by its id, so two snapshots of one path both stay.
+const kept = (all) => [...new Set(all.map(s => s.blob))].map(blob => ({ path: blob, blob, mode: '100644' }));
 export const staged = ({ R, me }) => loadState(R, me).staged ?? [];
 export const stage = ({ R, me }, files) => {
-    const taken = files.map(e => ({ path: e.path, blob: R.hub.store.blob(e.file ?? fail(`${e.path}: add takes files`)), mode: e.mode,
-        size: fs.statSync(e.file).size }));
+    const taken = files.map(e => {
+        if (!e.file)
+            fail(`${e.path}: add takes files`);
+        tooBig(e.path, fs.statSync(e.file).size);
+        const b = R.hub.store.blob(e.file);
+        tooBig(e.path, b.size);
+        return { path: e.path, blob: b.id, mode: e.mode, size: b.size };
+    });
     return readerLock(R, me, () => {
         const st = loadState(R, me);
         const next = new Map((st.staged ?? []).map(s => [s.path, s]));
@@ -26,19 +38,25 @@ export const stage = ({ R, me }, files) => {
             next.set(s.path, s);
         const all = [...next.values()];
         checkCollisions(all.map(s => s.path));
+        R.hub.store.retain(R.s, me, kept([...all, ...st.staged ?? []]));
         saveState(R, me, { ...st, staged: all });
+        R.hub.store.retain(R.s, me, kept(all));
         return all;
     });
 };
-// Unstages the given paths, or everything.
-export const unstage = ({ R, me }, paths) => readerLock(R, me, () => {
+const shrink = ({ R, me }, keep) => {
     const st = loadState(R, me);
-    const missing = (paths ?? []).filter(p => !(st.staged ?? []).some(s => s.path === p));
-    if (missing.length)
-        fail(`not staged: ${missing.join(', ')}`);
-    const left = paths ? (st.staged ?? []).filter(s => !paths.includes(s.path)) : [];
+    const left = (st.staged ?? []).filter(keep);
     saveState(R, me, { ...st, staged: left });
+    R.hub.store.retain(R.s, me, kept(left));
     return left;
+};
+// Unstages the given paths, or everything.
+export const unstage = (a, paths) => readerLock(a.R, a.me, () => {
+    const missing = (paths ?? []).filter(p => !staged(a).some(s => s.path === p));
+    if (missing.length)
+        fail(`not staged: ${missing.join(', ')}`);
+    return shrink(a, s => paths !== null && !paths.includes(s.path));
 });
 // A message from the actor. The operator may omit `to`: the room, or the assignees when there are any.
 export const send = ({ R, me }, x) => {
@@ -80,6 +98,9 @@ export const send = ({ R, me }, x) => {
     }
     // What the actor staged goes along, an explicit attachment of the same path in its place.
     const stagedNow = staged({ R, me }), explicit = x.files ?? [];
+    for (const e of explicit)
+        if (e.file)
+            tooBig(e.path, fs.statSync(e.file).size);
     const named = new Set(explicit.map(e => e.path));
     const entries = [...stagedNow.filter(s => !named.has(s.path)).map(s => ({ path: s.path, blob: s.blob, mode: s.mode })), ...explicit];
     checkCollisions(entries.map(e => e.path));
@@ -90,10 +111,7 @@ export const send = ({ R, me }, x) => {
     checkOutgoing(text, isRef(R));
     const id = append(R, me, text, entries);
     if (stagedNow.length)
-        readerLock(R, me, () => {
-            const st = loadState(R, me);
-            saveState(R, me, { ...st, staged: (st.staged ?? []).filter(s => !stagedNow.some(t => t.path === s.path && t.blob === s.blob)) });
-        });
+        readerLock(R, me, () => shrink({ R, me }, s => !stagedNow.some(t => t.path === s.path && t.blob === s.blob)));
     if (to.length === 1 && to[0] === '*')
         note(`addressed to the whole room: this ${x.task ? P.opens : 'message'} wakes nobody; name recipients (--to or --assign) to start work`);
     return { id, to, files: entries.length };

package/target/esm/cli/args.js

@@ -5,7 +5,7 @@ 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', 'clear']);
+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) => {

package/target/esm/cli/index.js

@@ -6,7 +6,7 @@ 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 { 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';
@@ -38,6 +38,8 @@ export const TABLE = [
     ['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'],
@@ -99,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';
@@ -42,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>');

package/target/esm/cli/session.js

@@ -1,4 +1,5 @@
 // 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';
@@ -30,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/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/store/git/index.js

@@ -56,6 +56,9 @@ const splitBuf = (b, sep) => {
     return parts;
 };
 const REGULAR = new Set(['100644', '100755']);
+// The store is a repository whose work tree holds the contract (`main`) as it is now, so Git clients (SourceTree, IDEs)
+// open `store/` without errors, on the contract, with every room's branch beside it; `git status` stays clean.
+const init = (dir, home) => runGit(['init', '-q', '-b', 'main', path.dirname(dir)], { where: home });
 // The root's principal, and the files only its control records may change.
 const ROOT = 'operator';
 const CONTROL_FILES = new Set(['ROOM.md', 'members.json', 'profile.json', 'allowed_signers']);
@@ -75,6 +78,30 @@ export class GitStore {
         this.h = { name: d.name, dir: this.dir, d };
         if (!fs.existsSync(this.dir))
             fail(`hub ${d.name}: no git store at ${this.dir}`);
+        this.openable();
+    }
+    // A store made bare before, or a replica fetched bare, gets its work tree once (and loses the `_ringi` branch of an unreleased build).
+    openable() {
+        let changed = false;
+        if (/^\s*bare\s*=\s*true\s*$/m.test(fs.readFileSync(path.join(this.dir, 'config'), 'utf8'))) {
+            this.git(['config', 'core.bare', 'false']);
+            changed = true;
+        }
+        if (fs.readFileSync(path.join(this.dir, 'HEAD'), 'utf8') !== 'ref: refs/heads/main\n') {
+            this.git(['symbolic-ref', 'HEAD', 'refs/heads/main']);
+            changed = true;
+        }
+        if (fs.existsSync(path.join(this.dir, 'refs', 'heads', '_ringi'))) {
+            this.gitOk(['update-ref', '-d', 'refs/heads/_ringi']);
+            changed = true;
+        }
+        if (changed)
+            this.checkout();
+    }
+    // The work tree and the index follow the contract, so a Git client sees the store clean.
+    checkout() {
+        if (this.rev('refs/heads/main'))
+            this.git(['--work-tree', path.dirname(this.dir), 'read-tree', '-u', '--reset', 'refs/heads/main']);
     }
     args(a) { return ['--git-dir', this.dir, ...a]; }
     git(a, o) { return runGit(this.args(a), { ...o, where: this.home }); }
@@ -121,7 +148,7 @@ export class GitStore {
         // A signed hub's repository already exists: rootFor made it with the root key.
         if (!fs.existsSync(dir)) {
             mkdirIn(home, path.dirname(dir));
-            runGit(['init', '--bare', '-q', '-b', 'main', dir], { where: home });
+            init(dir, home);
         }
         const s = new GitStore(hubDir, d, home);
         const sha = s.commit('operator', text, s.tree(null, Object.entries(contract).map(([p, c]) => ({ path: p, content: c, mode: '100644' }))), []);
@@ -129,17 +156,21 @@ export class GitStore {
             d.genesis = sha;
         if (!s.advance('refs/heads/main', sha, null))
             fail(`hub ${d.name}: main already exists`);
+        s.checkout();
         return s;
     }
     // A new signed hub: the root key is generated on this machine and pinned in the descriptor.
     static rootFor(hubDir, d, home) {
         const dir = path.join(hubDir, d.store.path, '.git');
         mkdirIn(home, path.dirname(dir));
-        runGit(['init', '--bare', '-q', '-b', 'main', dir], { where: home });
+        init(dir, home);
         return Remote.setupSigned({ name: d.name, dir, d }, home, d.store.remote).root;
     }
     sync() {
+        const main = this.rev('refs/heads/main');
         Remote.sync(this.h);
+        if (this.rev('refs/heads/main') !== main)
+            this.checkout();
     }
     // --- the contract ---
     contractHead() { return this.rev('refs/heads/main') ?? fail(`hub ${this.d.name} has no contract (main)`); }
@@ -153,6 +184,7 @@ export class GitStore {
         const sha = this.commit(who, text, this.tree(`${head}^{tree}`, Object.entries(files).map(([p, c]) => ({ path: p, content: c, mode: '100644' }))), [head]);
         if (!this.advance('refs/heads/main', sha, head))
             fail('the contract moved while amending; retry');
+        this.checkout();
         return sha;
     }
     // --- rooms ---
@@ -163,7 +195,7 @@ export class GitStore {
     roomNames(archived) {
         const prefix = archived ? 'refs/archive/' : 'refs/heads/';
         const names = this.git(['for-each-ref', '--format=%(refname)', prefix]).split('\n').filter(Boolean).map(r => r.slice(prefix.length))
-            .map(n => n.replace(/\/control$/, '')).filter(n => !n.includes('/') && n !== 'main' && n.includes('@') === archived);
+            .map(n => n.replace(/\/control$/, '')).filter(n => ID_RE.test(n.split('@')[0]) && n !== 'main' && n.includes('@') === archived);
         return [...new Set(names)].sort();
     }
     // A control record: the room's genesis, or a root commit of Kind: room.
@@ -514,7 +546,19 @@ export class GitStore {
                     files: files.filter(f => REGULAR.has(f.mode)), refused: [...refused, ...files.filter(f => !REGULAR.has(f.mode))] }];
         });
     }
-    blob(file) { return this.git(['hash-object', '-w', '--', file]).trim(); }
+    blob(file) {
+        const id = this.git(['hash-object', '-w', '--', file]).trim();
+        return { id, size: Number(this.git(['cat-file', '-s', id]).trim()) };
+    }
+    // A tree of the staged files under refs/ringi/staged/<genesis>/<who>: git keeps what a ref reaches.
+    retain(room, who, entries) {
+        const ref = `refs/ringi/staged/${room.genesis}/${who}`;
+        if (!entries.length) {
+            this.gitOk(['update-ref', '-d', ref]);
+            return;
+        }
+        this.git(['update-ref', ref, this.tree(null, entries)]);
+    }
     // One message on top of the room's branch.
     append(room, who, text, entries) {
         if (room.archived)
@@ -565,6 +609,35 @@ export class GitStore {
             .filter(([, , p]) => wanted.has(p)).map(([, n, p]) => [p, Number(n)]));
     }
     // --- signals ---
+    // The heartbeat of `who` in the room: a tag `<who>.heartbeat.<genesis12>` on the room's last commit here, its text the
+    // facts of the beat (heartbeat/). Each beat replaces the object under the same name, compare-and-swap on the one it
+    // read, so two writers do not overwrite each other blindly. No reader pins it; its replacement is no alarm.
+    // On a signed hub the object is signed by `who` and published with the OID it replaced; a newer beat there wins, and
+    // this one is taken back here (remote.ts).
+    heartbeat(room, who, target, text) {
+        const ref = Remote.heartbeatRef(who, room.genesis), name = ref.slice('refs/tags/'.length);
+        const old = this.rev(`${ref}^{tag}`) ? this.git(['rev-parse', ref]).trim() : null;
+        const obj = this.trust === 'signed' ? Remote.makeHeartbeat(this.h, this.remote(room), who, target, text, this.home)
+            : this.git(['mktag'], { input: `object ${target}\ntype commit\ntag ${name}\ntagger ${who} <${who}@ringi> ${Math.floor(Date.now() / 1000)} +0000\n\n${text}` }).trim();
+        if (this.gitOk(['update-ref', ref, obj, old ?? ZERO]).status !== 0)
+            fail(`${name} moved meanwhile; the next beat writes it`);
+        if (this.trust === 'signed' && !Remote.pushHeartbeat(this.h, this.remote(room), who, obj, old))
+            this.gitOk(['update-ref', ...(old ? [ref, old, obj] : ['-d', ref, obj])]);
+        return obj;
+    }
+    // The room's heartbeats as they stand: whose, on which commit, when, and what they say.
+    heartbeats(room) {
+        const g12 = room.genesis.slice(0, 12);
+        const tags = this.git(['for-each-ref', '--format=%(refname) %(objectname) %(objecttype)', 'refs/tags/']).split('\n')
+            .map(l => l.split(' ')).filter(([ref, , type]) => type === 'tag' && Remote.heartbeatName(ref ?? '')?.genesis12 === g12);
+        const objects = this.tagObjects(tags.map(([, object]) => object));
+        // On a signed hub only a verified beat shows.
+        const ok = (ref, object) => this.trust !== 'signed' || !Remote.verifyHeartbeat(this.h, this.remote(room), ref, object);
+        return tags.flatMap(([ref, object]) => {
+            const o = objects.get(object);
+            return o && ok(ref, object) ? [{ agent: Remote.heartbeatName(ref).actor, target: o.target, time: o.time, text: o.text }] : [];
+        });
+    }
     // An annotated tag without text in its author's namespace, on the message's commit, signed on a signed hub. The
     // message's id in the name keeps it unique, so writing the same signal twice is a no-op.
     signal(room, who, target, name) {
@@ -584,7 +657,8 @@ export class GitStore {
         return this.git(['for-each-ref', '--format=%(refname) %(objectname) %(objecttype)', 'refs/tags/']).split('\n').flatMap(line => {
             const [ref, object, type] = line.split(' ');
             const m = /^refs\/tags\/([a-z0-9]+(?:[_-][a-z0-9]+)*)\.([a-z][a-z0-9.-]*\.[0-9a-f]{12})$/.exec(ref ?? '');
-            return m ? [{ ref, actor: m[1], name: m[2], object, type }] : [];
+            // A heartbeat is no signal: it is replaced on every beat, and readers judge it apart (heartbeats()).
+            return m && !Remote.heartbeatName(ref) ? [{ ref, actor: m[1], name: m[2], object, type }] : [];
         });
     }
     // Annotated tag objects read whole, size-framed: their target, tagger and text are never split on bytes they hold.
@@ -605,7 +679,8 @@ export class GitStore {
             const hdr = body.subarray(0, split < 0 ? body.length : split).toString('utf8');
             const text = split < 0 ? '' : body.subarray(split + 2).toString('utf8').split('-----BEGIN SSH SIGNATURE-----')[0];
             const target = /^object ([0-9a-f]+)\ntype commit$/m.exec(hdr)?.[1] ?? '';
-            out.set(sha, { target, tagger: /^tagger (.*?) <[^>\n]*> \d+ [+-]\d{4}$/m.exec(hdr)?.[1] ?? '', text });
+            const tagger = /^tagger (.*?) <[^>\n]*> (\d+) [+-]\d{4}$/m.exec(hdr);
+            out.set(sha, { target, tagger: tagger?.[1] ?? '', time: Number(tagger?.[2] ?? NaN), text });
         }
         return out;
     }

package/target/esm/store/git/remote.js

@@ -382,8 +382,113 @@ export const verify = (H, R, who, head) => {
         return reason(e);
     }
 };
+// Heartbeats deliberately share the tag transport, but never the immutable signal acceptance.
+// Only this exact namespace is mutable; e.g. `actor.opened.heartbeat.<id>` is still a signal.
+const HEARTBEAT_NAME = /^([a-z0-9]+(?:[_-][a-z0-9]+)*)\.heartbeat\.([0-9a-f]{12})$/;
+export const heartbeatName = (ref) => {
+    const m = ref.startsWith(TAGS) && HEARTBEAT_NAME.exec(ref.slice(TAGS.length));
+    return m ? { actor: m[1], genesis12: m[2] } : null;
+};
+export const heartbeatRef = (who, genesis) => {
+    if (!SHA.test(genesis))
+        C.fail('heartbeat requires a full room genesis');
+    const ref = `${TAGS}${who}.heartbeat.${genesis.slice(0, 12)}`;
+    if (!heartbeatName(ref))
+        C.fail('malformed heartbeat actor');
+    return ref;
+};
+const heartbeatBody = (text) => {
+    if (Buffer.byteLength(text) > 16384)
+        C.fail('heartbeat body exceeds 16 KiB');
+    const decoded = P.decodeText(Buffer.from(text));
+    if (decoded.invalid)
+        C.fail(`heartbeat body is ${decoded.invalid}`);
+    const lines = decoded.text.trimEnd().split('\n');
+    const fields = new Map();
+    for (const line of lines) {
+        const m = /^([A-Z][A-Za-z]*): (.+)$/.exec(line) ?? C.fail('heartbeat body must contain only facts as trailers');
+        if (fields.has(m[1]))
+            C.fail(`duplicate heartbeat field ${m[1]}`);
+        fields.set(m[1], m[2]);
+    }
+    const genesis = fields.get('Room') ?? C.fail('heartbeat must name its full room genesis');
+    if (!SHA.test(genesis))
+        C.fail('heartbeat must name its full room genesis');
+    if (!/^(working|waiting|gone)$/.test(fields.get('State') ?? ''))
+        C.fail('invalid heartbeat State');
+    if (!/^(yes|no|unknown)$/.test(fields.get('Alive') ?? ''))
+        C.fail('invalid heartbeat Alive');
+    const next = Number(fields.get('Next'));
+    if (!Number.isFinite(next) || next <= 0)
+        C.fail('heartbeat Next must be positive seconds');
+    return genesis;
+};
+const heartbeatObject = (H, ref, sha) => {
+    const s = heartbeatName(ref) ?? C.fail('malformed heartbeat namespace');
+    if (!SHA.test(sha) || git(H, ['cat-file', '-t', sha]).trim() !== 'tag')
+        C.fail('heartbeat must be an annotated tag');
+    if (Number(git(H, ['cat-file', '-s', sha])) > 32768)
+        C.fail('heartbeat object exceeds 32 KiB');
+    const decoded = P.decodeText(git(H, ['cat-file', 'tag', sha], { raw: true }));
+    if (decoded.invalid)
+        C.fail(`heartbeat tag is ${decoded.invalid}`);
+    const [header, ...rest] = decoded.text.split('\n\n');
+    const target = /^object ([0-9a-f]+)\ntype commit\ntag ([^\n]+)\ntagger ([^<\n]+) <[^\n]*> (\d+) [+-]\d{4}\n?$/.exec(header) ?? C.fail('malformed heartbeat tag headers');
+    if (!SHA.test(target[1]) || target[2] !== ref.slice(TAGS.length) || target[3].trim() !== s.actor)
+        C.fail('heartbeat tag name or actor disagrees');
+    const text = rest.join('\n\n').split('-----BEGIN SSH SIGNATURE-----')[0];
+    const genesis = heartbeatBody(text);
+    if (!genesis.startsWith(s.genesis12))
+        C.fail('heartbeat tag name and room genesis disagree');
+    return { ...s, genesis, target: target[1], time: Number(target[4]), text };
+};
+const checkHeartbeat = (H, R, ref, sha) => {
+    const s = heartbeatObject(H, ref, sha);
+    if (s.genesis !== R.genesis)
+        C.fail('heartbeat belongs to another room genesis');
+    const b = branch(H, R, rev(H, R.ref) ?? C.fail('heartbeat room has no branch here'));
+    // It is a replica's sync position, not a claim to author or execute the target message.
+    if (!b.control.includes(s.target) && !b.authors.has(s.target) && !b.skipped.has(s.target))
+        C.fail('heartbeat target is not on this room branch');
+    const signer = b.entries.find(e => e.principal === s.actor) ?? C.fail(`unadmitted heartbeat principal ${s.actor}`);
+    checkSignature(H, sha, s.actor, signer.key, 'tag');
+};
+export const verifyHeartbeat = (H, R, ref, sha) => {
+    if (!isRemote(H))
+        return null;
+    if (H.remoteAlarms?.[ref])
+        return H.remoteAlarms[ref];
+    if (H.heartbeatErrors?.[ref])
+        return H.heartbeatErrors[ref];
+    try {
+        checkHeartbeat(H, R, ref, sha);
+        return null;
+    }
+    catch (e) {
+        return reason(e);
+    }
+};
+// Make an object without moving its ref. The caller performs local CAS before publishing with the same old OID.
+export const makeHeartbeat = (H, R, who, target, text, home) => {
+    const ref = heartbeatRef(who, R.genesis);
+    if (!SHA.test(target))
+        C.fail('heartbeat target must be a full commit id');
+    if (/^Room:/m.test(text))
+        C.fail('heartbeat Room is transport metadata');
+    const body = `Room: ${R.genesis}\n${text.trimEnd()}\n`;
+    heartbeatBody(body);
+    const raw = `object ${target}\ntype commit\ntag ${ref.slice(TAGS.length)}\ntagger ${who} <${who}@ringi> ${Math.floor(Date.now() / 1000)} +0000\n\n${body}`;
+    const key = sign(H, who, home)[0]?.slice(2);
+    const signature = key ? command('ssh-keygen', ['-Y', 'sign', '-n', 'git', '-f', key], { input: raw }) : '';
+    const sha = git(H, ['mktag'], { input: raw + signature }).trim();
+    if (isRemote(H))
+        checkHeartbeat(H, R, ref, sha);
+    return sha;
+};
 const SIGNAL_NAME = /^([a-z0-9]+(?:[_-][a-z0-9]+)*)\.([a-z][a-z0-9.-]*)\.([0-9a-f]{12})$/;
 const signalName = (ref) => {
+    if (heartbeatName(ref))
+        C.fail('heartbeat is not an immutable signal');
     const m = ref.startsWith(TAGS) && SIGNAL_NAME.exec(ref.slice(TAGS.length));
     if (!m)
         return C.fail('malformed signal tag namespace');
@@ -479,6 +584,7 @@ const promote = (H, ref, sha) => {
 };
 const syncUnlocked = (H) => {
     H.remoteAlarms = { ...pushAlarms(H) };
+    H.heartbeatErrors = {};
     const url = origin(H);
     if (!url) {
         if (rev(H, 'refs/heads/main'))
@@ -523,7 +629,34 @@ const syncUnlocked = (H) => {
         }
     }
     const tags = refs(H, TAG_TRACK), pinned = refs(H, TAG_ACCEPT);
+    // Include local beats to remove disappeared remote telemetry; unlike signals, nothing is pinned.
+    for (const ref of refs(H, TAGS).keys())
+        if (heartbeatName(ref) && !tags.has(TAG_TRACK + ref.slice(TAGS.length))) {
+            if (pinned.has(TAG_ACCEPT + ref.slice(TAGS.length)))
+                continue; // never waive previously accepted history
+            git(H, ['update-ref', '-d', ref]);
+        }
     for (const name of new Set([...tags.keys()].map(r => r.slice(TAG_TRACK.length)).concat([...pinned.keys()].map(r => r.slice(TAG_ACCEPT.length))))) {
+        const beatRef = TAGS + name;
+        if (heartbeatName(beatRef)) {
+            if (pinned.has(TAG_ACCEPT + name)) {
+                H.remoteAlarms[beatRef] = 'heartbeat namespace overlaps a previously accepted signal; operator review required';
+                continue;
+            }
+            try {
+                const sha = tags.get(TAG_TRACK + name) ?? C.fail('heartbeat is absent from the remote');
+                const b = heartbeatObject(H, beatRef, sha);
+                const R = byGenesis.get(b.genesis) ?? C.fail('heartbeat room is missing or quarantined');
+                checkHeartbeat(H, R, beatRef, sha);
+                git(H, ['update-ref', beatRef, sha]);
+            }
+            catch (e) {
+                H.heartbeatErrors[beatRef] = reason(e);
+                git(H, ['update-ref', '-d', beatRef]);
+                note(`heartbeat ${name}: ${reason(e)}; withheld`);
+            }
+            continue;
+        }
         // Other tags, including the old room-scoped namespace, are not signals.
         if (!SIGNAL_NAME.test(name))
             continue;
@@ -665,6 +798,8 @@ const validateRef = (H, ref, sha) => {
 // Publish one ref. With `behind`, a room's branch the remote has moved on is not an alarm: push returns false and the
 // caller makes its commit again on the new tip.
 export const push = (H, ref, { behind = false } = {}) => {
+    if (heartbeatName(ref))
+        C.fail('heartbeat publication requires its actor and expected object id (pushHeartbeat)');
     if (!isRemote(H))
         return true;
     return locked(H, () => {
@@ -728,6 +863,41 @@ export const push = (H, ref, { behind = false } = {}) => {
         return true;
     });
 };
+// Publish only the actor's exact heartbeat with an explicit old OID. A racing beat is ordinary contention, never a
+// signal rewrite alarm. Neither success nor failure changes immutable acceptance pins or budget/history state.
+export const pushHeartbeat = (H, R, who, sha, expected) => {
+    const ref = heartbeatRef(who, R.genesis);
+    if (!SHA.test(sha) || (expected !== null && !SHA.test(expected)))
+        C.fail('heartbeat publication requires full object ids');
+    if (!isRemote(H))
+        return true;
+    return locked(H, () => {
+        if (object(H, ref) !== sha)
+            return false; // a newer local beat already won
+        if (object(H, TAG_ACCEPT + ref.slice(TAGS.length)))
+            C.fail('heartbeat namespace overlaps previously accepted signal history');
+        checkHeartbeat(H, R, ref, sha);
+        const url = origin(H);
+        if (!url)
+            return true;
+        checkUrl(url);
+        const r = git(H, ['push', '-q', '--porcelain', `--force-with-lease=${ref}:${expected ?? ''}`, url, `${sha}:${ref}`], { ok: true });
+        if (r.status !== 0) {
+            // A lost acknowledgement is safe to reconcile: equality proves no second beat is needed.
+            const observed = git(H, ['ls-remote', '--refs', url, ref], { ok: true });
+            const got = observed.status === 0 ? observed.stdout.trim().split(/\s+/) : [];
+            if (got[0] !== sha || got[1] !== ref) {
+                if (/\[rejected\].*\(stale info\)/.test(r.stdout))
+                    return false;
+                C.fail(`heartbeat push failed for ${ref.slice(TAGS.length)}: ${String(r.stderr || r.stdout || 'transport error').trim().split('\n').at(-1)}`);
+            }
+        }
+        git(H, ['update-ref', TAG_TRACK + ref.slice(TAGS.length), sha]);
+        if (H.heartbeatErrors)
+            delete H.heartbeatErrors[ref];
+        return true;
+    });
+};
 // Only the operator command calls this after reviewing a room's transport alarm: the room's branch as the remote has
 // it becomes the accepted baseline, and the displaced local branch is kept as evidence. Nothing is waived: the branch
 // must verify, and its invalid commits stay skipped.