@idleware/ringi 0.5.0 → 0.6.1

package/target/esm/clients/cli/shared/budget.js

@@ -0,0 +1,50 @@
+// budget: `propose`, `stamp`, `decide`, `proposals`, `grants`.
+import * as Budget from '../../../core/hub/usecases/budget.js';
+import { fail, short, words } from '../../../lib/index.js';
+import { attachments, dump, flag, list, opt, out, textOf } from '../args.js';
+// --- decisions and budgets ---
+export const propose = (a, o) => {
+    const decider = opt(o, 'decider') ?? fail('--decider <id> is required: who decides (operator, or someone with authority in the hub contract)');
+    const r = Budget.propose(a, {
+        text: textOf(o), decider, reviewers: words(opt(o, 'reviewers')), budget: opt(o, 'budget'), due: opt(o, 'due'),
+        supersedes: opt(o, 'supersedes'), files: list(o, 'attach').flatMap(attachments)
+    });
+    out(`proposed ${short(r.id)} to ${r.to.join(', ') || 'the room'}; decider ${decider}${r.budget ? `, budget ${Budget.budgetText(r.budget)}` : ''}`);
+};
+export const stamp_ = (a, o) => {
+    const s = o._[1] ?? '';
+    if (!Budget.STAMPS.includes(s))
+        fail(`usage: stamp <proposal> ${Budget.STAMPS.join('|')} -m <reason>`);
+    const r = Budget.stamp(a, o._[0] ?? fail('name the proposal'), s, textOf(o));
+    out(`stamped ${short(r.proposal.id)} ${s}: ${short(r.id)}`);
+};
+export const decide = (a, o) => {
+    const d = o._[1] ?? '';
+    if (!Budget.DECISIONS.includes(d))
+        fail(`usage: decide <proposal> ${Budget.DECISIONS.join('|')} -m <reason>`);
+    const r = Budget.decide(a, o._[0] ?? fail('name the proposal'), d, textOf(o));
+    out(`${d} ${short(r.proposal.id)}: ${short(r.id)}${r.budget ? `; grant ${short(r.id)} with ${Budget.budgetText(r.budget)}. Work spends it with --grant ${short(r.id)}` : ''}`);
+};
+export const proposals = (a, o) => {
+    const { proposals: ps, views } = Budget.proposals(a, { all: flag(o, 'all') });
+    if (flag(o, 'json'))
+        return dump(views);
+    if (!ps.length)
+        return out(flag(o, 'all') ? 'no proposals' : 'no open proposals (proposals --all for everything)');
+    for (const x of ps) {
+        const st = x.reviewers.map(r => `${r}:${x.stamps[r]?.stamp ?? '-'}`).join(' ');
+        out(`${short(x.proposal.id)}  ${x.state.padEnd(10)} ${x.proposal.from} → ${x.decider}${x.budget ? `  [${Budget.budgetText(x.budget)}]` : ''}${st ? `  ${st}` : ''}  ${x.proposal.subject}`);
+    }
+};
+export const grants = (a, o) => {
+    const gs = Budget.grants(a);
+    if (flag(o, 'json'))
+        return dump(gs);
+    if (!gs.length)
+        return out('no grants');
+    for (const g of gs) {
+        const u = g.usage;
+        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}`);
+    }
+};
+//# sourceMappingURL=budget.js.map

package/target/esm/clients/cli/shared/files.js

@@ -0,0 +1,26 @@
+// files: `cat` and `get`, a message's attached files.
+import fs from 'node:fs';
+import path from 'node:path';
+import * as Room from '../../../core/hub/usecases/room.js';
+import { checkPath } from '../../../core/hub/usecases/room.js';
+import { fail, short } from '../../../lib/index.js';
+import { opt, out } from '../args.js';
+export const cat = (a, o) => {
+    const ref = o._[0] ?? fail('usage: cat <msg> [<path>]');
+    const p = o._[1] ?? (() => {
+        const { m } = Room.files(a, ref);
+        return m.files.length === 1 ? m.files[0].path : fail(`${short(m.id)} has ${m.files.length} files; name one: ${m.files.map(f => f.path).join(', ')}`);
+    })();
+    process.stdout.write(Room.files(a, ref, p).files[0].content);
+};
+export const get = (a, o) => {
+    const { m, files } = Room.files(a, o._[0] ?? fail('usage: get <msg> [-o <dir>]'));
+    const dir = path.resolve(opt(o, 'out') ?? short(m.id));
+    for (const f of files) {
+        const dest = path.join(dir, checkPath(f.path));
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, f.content);
+        out(dest);
+    }
+};
+//# sourceMappingURL=files.js.map

package/target/esm/clients/cli/shared/index.js

@@ -0,0 +1,10 @@
+// shared: the commands both run: `ringi send` acts as the operator, `ringi agent send` as the agent its session is
+// bound to; messages, files, work, signals, proposals and grants.
+export { decide, grants, proposals, propose, stamp_ } from './budget.js';
+export { cat, get } from './files.js';
+export { add, read, reply, send, thread } from './messages.js';
+export { profileCmd, who } from './profile.js';
+export { scopeLine, waiting } from './session.js';
+export { signals } from './signals.js';
+export { log, taskLine, tasks } from './work.js';
+//# sourceMappingURL=index.js.map

package/target/esm/clients/cli/shared/messages.js

@@ -0,0 +1,41 @@
+// messages: `add` (staging), `send`, `reply`, `read`, `thread`.
+import * as Room from '../../../core/hub/usecases/room.js';
+import { withSizes } from '../../../core/hub/usecases/room.js';
+import { asJson, render } from '../../../core/hub/usecases/view.js';
+import { bytes, fail, short, 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) => {
+    const { all, m, replies, marks } = Room.message(a, o._[0] ?? fail('usage: read <msg>'));
+    if (flag(o, 'json'))
+        return dump(asJson(m));
+    out(render(all, m, { files: () => withSizes(a.R, m) }));
+    if (replies.length)
+        out(`replies: ${replies.map(x => `${short(x.id)} (${x.from})`).join(', ')}`);
+    if (marks)
+        out(Object.entries(marks).map(([mark, who]) => `${mark} by: ${who.join(', ')}`).join('; '));
+};
+export const thread = (a, o) => {
+    const { all, msgs } = Room.thread(a, o._[0] ?? fail('usage: thread <msg>'));
+    if (flag(o, 'json'))
+        return dump(msgs.map(asJson));
+    out(msgs.map(m => render(all, m, { files: () => withSizes(a.R, m) })).join('\n\n'));
+};
+//# sourceMappingURL=messages.js.map

package/target/esm/clients/cli/shared/profile.js

@@ -0,0 +1,17 @@
+// profile: `profile` (what work is in the room) and `who` (its members and their cards).
+import * as Room from '../../../core/hub/usecases/room.js';
+import { dump, flag, out } from '../args.js';
+export const profileCmd = ({ R }, o) => {
+    if (flag(o, 'json'))
+        return dump(R.profile);
+    const P = R.profile;
+    out(`room ${R.name} follows profile ${P.name}${P.description ? `: ${P.description}` : ''}`);
+    out(`opens with Kind: ${P.opens}; states: ${P.states.join(', ')}; initial ${P.initial}; terminal ${P.terminal.join(', ')}${P.waiting ? `; waiting ${P.waiting}` : ''}`);
+    for (const [k, v] of Object.entries(P.rules))
+        out(`  ${k.padEnd(18)} ${(v ?? []).join(', ')}`);
+};
+export const who = (a) => {
+    for (const x of Room.members(a))
+        out(`${x.id.padEnd(12)} ${x.role.padEnd(7)} ${String(x.messages).padStart(4)} msg${x.card ? `  ${x.card}` : ''}`);
+};
+//# sourceMappingURL=profile.js.map

package/target/esm/clients/cli/shared/session.js

@@ -0,0 +1,8 @@
+// session: how a session's scope and a room still waiting for its quorum are shown.
+// 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=session.js.map

package/target/esm/clients/cli/shared/signals.js

@@ -0,0 +1,21 @@
+// signals: `signals`, the room's signals checked, and `--repair` for the actor's own.
+import * as Room from '../../../core/hub/usecases/room.js';
+import { note, short, when } from '../../../lib/index.js';
+import { dump, flag, opt, out } from '../args.js';
+export const signals = (a, o) => {
+    const res = Room.signals(a, { repair: flag(o, 'repair') });
+    if (res.repaired !== null)
+        out(`restored ${res.repaired} signal(s) of ${a.me}`);
+    for (const x of res.alarms)
+        note(`ALARM ${x}`);
+    if (flag(o, 'json'))
+        return dump(res.checked);
+    const at = (c) => res.all.get(c.target)?.time ?? 0;
+    const sorted = [...res.checked].sort((x, y) => at(x) - at(y));
+    const shown = flag(o, 'all') ? sorted : sorted.slice(-Number(opt(o, 'n') ?? 20));
+    if (!shown.length)
+        return out('no signals');
+    for (const c of shown)
+        out(`${short(c.target)}  ${when(at(c)).slice(5)}  ${c.actor.padEnd(10)} ${c.signal.padEnd(20)} ${c.ok ? res.all.get(c.target)?.subject ?? '' : `MISMATCH: ${c.why}`}`);
+};
+//# sourceMappingURL=signals.js.map

package/target/esm/clients/cli/shared/work.js

@@ -0,0 +1,26 @@
+// work: `tasks` and `log`, and one line per piece of work.
+import * as Room from '../../../core/hub/usecases/room.js';
+import { asJson, oneLine } from '../../../core/hub/usecases/view.js';
+import { short, when } from '../../../lib/index.js';
+import { dump, flag, opt, out } from '../args.js';
+export const taskLine = (t) => {
+    const roles = Object.keys(t.roles).length ? ` [${Object.entries(t.roles).map(([id, label]) => `${id}=${label}`).join(' ')}]` : '';
+    return `${short(t.id)}  ${t.state.padEnd(14)} ${t.requester} → ${t.assignees.join(',') || '(open)'}${roles}${t.taken.length ? ` taken by ${t.taken.join(',')}` : ''}${t.grant ? ` grant ${short(t.grant)}` : ''}  ${when(Date.parse(t.at) / 1000).slice(5)} by ${t.by}  ${t.subject}`;
+};
+export const tasks = (a, o) => {
+    const { views } = Room.tasks(a, { all: flag(o, 'all') });
+    if (flag(o, 'json'))
+        return dump(views);
+    if (!views.length)
+        return out(flag(o, 'all') ? 'no work' : `no open work (profile ${a.R.profile.name}; tasks --all for everything)`);
+    for (const t of views)
+        out(taskLine(t));
+};
+export const log = (a, o) => {
+    const msgs = Room.log(a, { agent: opt(o, 'agent'), all: flag(o, 'all'), n: Number(opt(o, 'n') ?? 20) });
+    if (flag(o, 'json'))
+        return dump(msgs.map(asJson));
+    for (const m of msgs)
+        out(oneLine(m));
+};
+//# sourceMappingURL=work.js.map

package/target/esm/clients/cli/skill/index.js

@@ -0,0 +1,40 @@
+// skill: the agents' manual for this same command line (src/main/resources/skill/), installed where each agent tool
+// reads skills (targets.ts), checked and removed again.
+import fs from 'node:fs';
+import path from 'node:path';
+import { about } from '../../../core/hub/usecases/context.js';
+import { sandboxHints } from '../../../core/agents/sessions/context.js';
+import { fail } from '../../../lib/index.js';
+import { flag, out } from '../args.js';
+import { SKILL, sameSkill, skillTargets } from './targets.js';
+export { SKILL, skillTargets } from './targets.js';
+const install = (o) => {
+    for (const dir of skillTargets(flag(o, 'project'))) {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.cpSync(SKILL, dir, { recursive: true });
+        out(`installed ${dir}`);
+    }
+    out([`ringi's home is ${about().home}. A sandboxed agent must be allowed to write it.`, ...sandboxHints(about().home).map(h => `  ${h}`),
+        'Otherwise agents re-run ringi commands with sandbox escalation, which you approve.'].join('\n'));
+};
+const status = () => {
+    for (const dir of [...skillTargets(false), ...skillTargets(true)]) {
+        const state = sameSkill(dir) ? 'ok      ' : fs.existsSync(dir) ? 'outdated' : 'missing ';
+        out(`${state} ${dir}`);
+    }
+};
+const uninstall = (o) => {
+    for (const dir of skillTargets(flag(o, 'project'))) {
+        if (!fs.existsSync(dir))
+            continue;
+        fs.rmSync(dir, { recursive: true });
+        out(`removed ${dir}`);
+    }
+};
+const show = () => { process.stdout.write(fs.readFileSync(path.join(SKILL, 'SKILL.md'), 'utf8')); };
+const COMMANDS = new Map([['install', install], ['status', status], ['uninstall', uninstall], ['show', show]]);
+export const skill = (o) => {
+    const run = COMMANDS.get(o._[0]) ?? fail('usage: ringi skill install [--project] | uninstall [--project] | status | show');
+    run(o);
+};
+//# sourceMappingURL=index.js.map

package/target/esm/clients/cli/skill/targets.js

@@ -0,0 +1,20 @@
+// targets: where the skill goes: each agent tool's skill directory under the user's home or the project.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { about } from '../../../core/hub/usecases/context.js';
+import { skillDirs } from '../../../core/agents/sessions/context.js';
+export const SKILL = path.join(about().resources, 'skill', 'ringi');
+export const skillTargets = (project) => {
+    const base = project ? process.cwd() : os.homedir();
+    return skillDirs(base);
+};
+export const sameSkill = (dir) => {
+    try {
+        return fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8') === fs.readFileSync(path.join(SKILL, 'SKILL.md'), 'utf8');
+    }
+    catch {
+        return false;
+    }
+};
+//# sourceMappingURL=targets.js.map

package/target/esm/composition/index.js

@@ -0,0 +1,34 @@
+// composition: the one place ringi is put together when a program starts: this build, the machine's state, the store
+// types, the agent tools it knows, its processes and keys. Importing it wires them into the ports (core/hub/ports,
+// core/agents/ports); nothing else imports an adapter.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { notesTo } from '../lib/index.js';
+import { wireHub } from '../core/hub/ports/index.js';
+import { wireAgents } from '../core/agents/ports/index.js';
+import { stateFs } from '../adapters/state-fs/index.js';
+import { claude } from '../adapters/tool-claude/index.js';
+import { codex } from '../adapters/tool-codex/index.js';
+import { cursor } from '../adapters/tool-cursor/index.js';
+import { hostPosix } from '../adapters/host-posix/index.js';
+import { keysFile } from '../adapters/keys-file/index.js';
+import { gitTransport } from '../adapters/transport-git/transport.js';
+import { kafka } from '../adapters/transport-kafka/index.js';
+import { temporal } from '../adapters/transport-temporal/index.js';
+// The package this file belongs to, run from its source (src/main/ts) or its build (target/esm).
+const packageOf = (dir) => fs.existsSync(path.join(dir, 'package.json')) ? dir : packageOf(path.dirname(dir));
+const PACKAGE = packageOf(path.dirname(fileURLToPath(import.meta.url)));
+export const build = {
+    version: JSON.parse(fs.readFileSync(path.join(PACKAGE, 'package.json'), 'utf8')).version,
+    resources: path.join(PACKAGE, 'src', 'main', 'resources'),
+};
+const root = path.resolve(process.env.RINGI_HOME || path.join(os.homedir(), '.ringi'));
+// The git store signs with keys kept as files under the home, made only for a signed hub.
+const transports = { git: gitTransport(root, { signer: () => keysFile(root) }), kafka, temporal };
+wireHub({ build, state: stateFs({ root, build }), transports, store: 'git' });
+// In the order a session is recognised by.
+wireAgents({ tools: [claude, codex, cursor], host: hostPosix() });
+notesTo(line => { process.stderr.write(line); });
+//# sourceMappingURL=index.js.map

package/target/esm/{heartbeat → core/agents/heartbeat}/index.js

@@ -1,18 +1,20 @@
 // 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';
+// model, so no tokens are spent on it. The facts: its process and process tree (ProcessHost, core/agents/ports/host.ts), the trace its tool
+// writes (tools.ts, from the tools this machine knows) and ringi's own session record. What to do about a silent or stuck agent is the orchestrator's.
+import { agentPorts } from '../ports/index.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 probe = (s, waits = null, rows = agentPorts().host.snapshot()) => {
+    const host = agentPorts().host, facts = s.pid ? host.inspect(s.pid, rows) : null;
+    return {
+        at: host.clock.wall() / 1000,
+        alive: facts?.alive ?? null,
+        cpu: s.product === 'watch' ? facts?.cpu ?? null : 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

package/target/esm/{app/heartbeat.js → core/agents/heartbeat/pulse.js}

@@ -1,14 +1,13 @@
 // 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';
+// model (index.ts). It reads session records only: it never binds a session, renews its lease or marks anything read.
+import * as HB from './index.js';
+import { agentPorts } from '../ports/index.js';
+import { hubPorts } from '../../hub/ports/index.js';
+import { claim, release } from './singleton.js';
+export { ensurePulse } from './singleton.js';
+import { openHub, openRoom, start } from '../../hub/rooms/index.js';
+import { sleep } from '../../../lib/index.js';
+import { allSessions } from '../sessions/index.js';
 // What the room keeps the session waiting for, if anything; a hub that cannot be read says nothing.
 const roomWaits = (s) => {
     try {
@@ -23,31 +22,14 @@ const roomWaits = (s) => {
 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()));
+    const first = ss.map((s, i) => HB.probe(s, waits[i], agentPorts().host.snapshot()));
     if (ss.some(s => s.product === 'watch'))
         await sleep(sample * 1000);
-    const rows = table();
+    const rows = agentPorts().host.snapshot();
     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();
+const beatAll = (prev, next) => {
+    const rows = agentPorts().host.snapshot();
     return allSessions().flatMap((s) => {
         try {
             const H = openHub(s.hub);
@@ -66,38 +48,32 @@ export const beatAll = (prev, next) => {
         }
     });
 };
+// Beats until no session is left twice in a row, or the home is gone; `once`: one round.
+const beatLoop = async (every, once, log) => {
+    const prev = new Map();
+    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 || !hubPorts().state.present())
+            return;
+        await sleep(every * 1000);
+    }
+};
 // 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;
-    });
+    const other = claim();
     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);
-        }
+        await beatLoop(every, once, log);
     }
     finally {
-        try {
-            if (Number(fs.readFileSync(PIDFILE(), 'utf8')) === process.pid)
-                fs.rmSync(PIDFILE());
-        }
-        catch { }
+        release();
     }
     return 0;
 };
@@ -107,4 +83,4 @@ export const published = (R) => (R.hub.store.heartbeats?.(R.s) ?? []).map(h => {
     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
+//# sourceMappingURL=pulse.js.map

package/target/esm/core/agents/heartbeat/singleton.js

@@ -0,0 +1,38 @@
+// singleton: one pulse for this machine, its process id kept in the state as `pulse`. Process facts and the detached
+// launch belong to ProcessHost; a corrupt record never invents an owner.
+import { agentPorts } from '../ports/index.js';
+import { hubPorts, locked } from '../../hub/ports/index.js';
+const PULSE = ['pulse'];
+const recorded = () => {
+    let v;
+    try {
+        v = hubPorts().state.read(PULSE, 0);
+    }
+    catch {
+        return 0;
+    }
+    return Number.isSafeInteger(v) && v > 0 ? v : 0;
+};
+const running = () => {
+    const pid = recorded();
+    return pid && pid !== process.pid && agentPorts().host.alive(pid) ? pid : null;
+};
+export const ensurePulse = (cli) => {
+    if (process.env.RINGI_PULSE === 'off' || running())
+        return;
+    agentPorts().host.start({ file: process.execPath, args: [cli, 'pulse'], env: process.env });
+};
+export const claim = () => locked('pulse', () => {
+    const pid = running();
+    if (!pid)
+        hubPorts().state.write(PULSE, process.pid);
+    return pid;
+});
+export const release = () => {
+    try {
+        if (recorded() === process.pid)
+            hubPorts().state.remove(PULSE);
+    }
+    catch { }
+};
+//# sourceMappingURL=singleton.js.map

package/target/esm/core/agents/heartbeat/tools.js

@@ -0,0 +1,24 @@
+// tools: which agent tool a session runs in, and when that tool last wrote the session's trace, asked of the tools
+// this machine knows (core/agents/ports/tools.ts). Its modification time is the session's own activity, unlike the CPU of an app
+// process that hosts many sessions. A ringi watcher writes no trace of its own: the CPU of its process tree speaks for
+// its turn (index.ts).
+import { agentPorts } from '../ports/index.js';
+const traced = (s) => {
+    for (const tool of agentPorts().tools) {
+        const id = tool.traceId?.(s);
+        if (id)
+            return { tool, id };
+    }
+    return null;
+};
+// The tool the session runs in and the id its trace is named by.
+export const toolOf = (s) => {
+    const t = traced(s);
+    return t && { tool: t.tool.id, id: t.id };
+};
+// 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 = traced(s);
+    return t?.tool.traceTime?.(t.id) ?? null;
+};
+//# sourceMappingURL=tools.js.map

package/target/esm/{app → core/agents}/overview.js

@@ -1,13 +1,14 @@
 // overview: where things stand for the operator: the hub, the room, who is in, open work and proposals, the latest
 // messages, and new ones as they land; and the sessions of this machine.
-import * as D from '../domain/decisions.js';
-import { OPERATOR, ensureHome, locked } from '../home/index.js';
-import { HIDDEN, openHub, room as roomOf } from '../hub/index.js';
-import { fail } from '../lib/index.js';
-import { ordered } from '../protocol/index.js';
-import { linked } from '../runtime/reader.js';
-import { allSessions, dropSession, liveness, readSession } from '../runtime/session.js';
-import { tasks } from './room.js';
+import * as D from '../hub/decisions/index.js';
+import { hubPorts, locked } from '../hub/ports/index.js';
+import { HIDDEN, OPERATOR, openHub, room as roomOf } from '../hub/rooms/index.js';
+import { fail } from '../../lib/index.js';
+import { ordered } from '../hub/protocol/index.js';
+import { linked } from '../hub/history/index.js';
+import { allSessions, dropSession, liveness, readSession } from './sessions/index.js';
+import { tasks } from '../hub/usecases/room.js';
+import { rooms } from '../hub/usecases/rooms.js';
 const sessionView = (s) => ({ ...s, liveness: liveness(s) });
 export const where = (H, name) => {
     if (!name)
@@ -26,8 +27,13 @@ export const arrived = (H, R, seen) => {
         seen.add(m.id);
     return { all, messages };
 };
+// The hub's rooms, each with how many of its sessions on this machine are active.
+export const roomsActive = (H, o = {}) => {
+    const ss = allSessions().filter(s => s.hub === H.name && liveness(s) === 'active');
+    return rooms(H, o).map(v => ({ ...v, active: ss.filter(s => s.genesis === v.genesis).length }));
+};
 export const sessions = () => {
-    ensureHome();
+    hubPorts().state.ensure();
     return allSessions().map(sessionView);
 };
 // The seat a session held becomes free.

package/target/esm/core/agents/ports/host.js

@@ -0,0 +1,4 @@
+// host: process facts and isolated launches, apart from any operating system or agent tool. A launch is held by an
+// opaque handle; only its host may stop it. A deadline uses the host's monotonic clock, dates its wall clock.
+export {};
+//# sourceMappingURL=host.js.map

package/target/esm/core/agents/ports/index.js

@@ -0,0 +1,7 @@
+// ports (agents): what running agents on this machine needs from it — the agent tools it knows — and where an
+// implementation plugs in. Code asks `agentPorts()`; composition/ wires them in when a program starts.
+import { fail } from '../../../lib/fail.js';
+let wired = null;
+export const wireAgents = (p) => { wired = p; };
+export const agentPorts = () => wired ?? fail('ringi is not wired: a program starts it through composition/');
+//# sourceMappingURL=index.js.map

package/target/esm/core/agents/ports/tools.js

@@ -0,0 +1,5 @@
+// tools: the agent tools ringi works with (Claude Code, Codex, …), as a port. Each says what it can: recognise that
+// this process runs in one of its sessions, name that session, find the trace it writes while it works, where it reads
+// skills, and what lets its sandbox write a path. A tool leaves out what it cannot do.
+export {};
+//# sourceMappingURL=tools.js.map