@idleware/ringi 0.0.0-stage → 0.0.0

package/target/esm/runtime/watch.js

@@ -0,0 +1,303 @@
+// watch: headless turns for one agent of one room (core-1 §7). It holds that agent's seat, answers heartbeats in
+// code, and spends only within a grant (decisions-1) or its own run budget. Usage receipts are written here, by the
+// runner, never by the model.
+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 { loadRoomUnlocked, loadState, readerLock, saveState } from './reader.js';
+import { isOpen, taskFor, taskOf } from '../domain/profiles.js';
+import { compose, link, unread, wakes } from '../protocol/index.js';
+import { dropSession, liveness, parseSelector, pidAlive, readSession, saveSession, seatHolder, whoAmI } from './session.js';
+import { fail, note, short, sleep, stamp } from '../lib/index.js';
+// One turn: the command runs in a process group of its own (POSIX). At the deadline, or when the command itself
+// ends, whatever is left of the group is asked to stop and, after a grace, killed; the turn ends when the group is
+// empty, so no descendant outlives the run it was counted as.
+const GRACE = 5000;
+const groupAlive = (pid) => {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+};
+const signalGroup = (pid, sig) => {
+    try {
+        process.kill(-pid, sig);
+    }
+    catch { }
+};
+const turn = (cmd, seconds, env) => new Promise(resolve => {
+    const t0 = Date.now();
+    const child = spawn('sh', ['-c', cmd], { stdio: 'inherit', env, detached: true });
+    const pid = child.pid;
+    let timedOut = false;
+    let exit = null;
+    const end = async () => {
+        signalGroup(pid, 'SIGTERM');
+        const until = Date.now() + GRACE;
+        while (groupAlive(pid) && Date.now() < until)
+            await sleep(50);
+        if (groupAlive(pid))
+            signalGroup(pid, 'SIGKILL');
+        while (groupAlive(pid))
+            await sleep(50);
+        resolve({ code: exit?.code ?? null, signal: exit?.signal ?? null, timedOut, seconds: Math.round((Date.now() - t0) / 1000) });
+    };
+    // At the deadline: SIGTERM to the group, and SIGKILL after the grace even if the shell ignores it.
+    let hard;
+    const timer = seconds ? setTimeout(() => {
+        timedOut = true;
+        signalGroup(pid, 'SIGTERM');
+        hard = setTimeout(() => signalGroup(pid, 'SIGKILL'), GRACE);
+    }, seconds * 1000) : undefined;
+    const stopAll = () => signalGroup(pid, 'SIGTERM');
+    process.once('SIGINT', stopAll);
+    process.once('SIGTERM', stopAll);
+    child.on('exit', (code, signal) => {
+        exit = { code, signal };
+        clearTimeout(timer);
+        clearTimeout(hard);
+        process.removeListener('SIGINT', stopAll);
+        process.removeListener('SIGTERM', stopAll);
+        void end();
+    });
+});
+export const watch = async (w, log = note) => {
+    for (const [name, value] of [['interval', w.interval], ['window', w.window]])
+        if (value !== undefined && (!Number.isFinite(value) || value <= 0))
+            fail(`watch ${name} must be positive seconds`);
+    for (const [name, value] of [['max-runs', w.maxRuns], ['max-hop', w.maxHop]])
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+            fail(`watch ${name} must be a nonnegative integer`);
+    const sel = parseSelector(w.seat);
+    const cmd = w.exec;
+    const H0 = openHub(sel.hub ?? w.hub ?? config().hub);
+    const R0 = openRoom(H0, sel.room);
+    const me = sel.agent;
+    if (R0.archived)
+        fail(`${R0.name} is archived`);
+    if (!R0.members[me])
+        fail(`${me} is not a member of ${R0.name}; the operator adds it with a join, or watch another agent`);
+    // Each watcher process is its own session, so two of them can never share one seat record.
+    const raw = `watch-${H0.name}-${R0.genesis.slice(0, 8)}-${me}-${process.pid}`;
+    const handle = `env:${raw}`;
+    locked('sessions', () => {
+        const holder = seatHolder(H0.name, R0.genesis, me, handle);
+        const handoff = w.handoff && holder?.product !== 'watch' && holder?.handle === whoAmI().handle;
+        if (w.handoff && !handoff)
+            fail('watch --handoff needs the invoking chat to own this seat');
+        if (handoff && holder.state === 'stopped')
+            fail('this chat is stopped; continue it before a handoff');
+        if (holder && !handoff && (holder.product !== 'watch' || (holder.pid && pidAlive(holder.pid))))
+            fail(`${R0.name}/${me} is held by session ${holder.handle} (${liveness(holder)}); one seat per agent. Its chat may use watch --handoff`);
+        if (holder)
+            dropSession(holder.handle);
+        saveSession({ handle, product: 'watch', hub: H0.name, room: R0.name, genesis: R0.genesis, agent: me, scope: w.scope ?? holder?.scope ?? null,
+            state: holder?.state === 'stopped' ? 'stopped' : 'active', since: stamp(), lastSeen: stamp(), pid: process.pid,
+            takenFrom: handoff ? holder.handle : holder?.takenFrom });
+    });
+    const interval = (w.interval ?? 5) * 1000;
+    const allow = w.from ? new Set(w.from) : null;
+    const maxHop = w.maxHop ?? 8;
+    const maxRuns = w.maxRuns ?? 10;
+    const span = w.window ?? 86400;
+    let runSeq = 0;
+    for (;;) {
+        const s = locked('sessions', () => {
+            const cur = readSession(handle);
+            if (cur?.state === 'active')
+                saveSession({ ...cur, lastSeen: stamp(), pid: process.pid });
+            return cur;
+        });
+        if (!s) {
+            log(`watch: the seat of ${me} was released or taken over; stopping`);
+            return 0;
+        }
+        if (s.state === 'stopped') {
+            if (w.once) {
+                log('watch: stopped by the operator');
+                return 0;
+            }
+            await sleep(interval);
+            continue;
+        }
+        const H = openHub(H0.name, { refresh: true });
+        const R = openRoom(H, R0.name, { quiet: true });
+        if (!R || R.genesis !== R0.genesis || !R.members[me]) {
+            log(`watch: ${R0.name} is gone, recreated or archived, or ${me} was removed; stopping`);
+            return 0;
+        }
+        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, () => {
+            const { logs, st } = loadRoomUnlocked(R, me);
+            if (st.inflight) {
+                st.seen = st.inflight.seen;
+                st.inflight = undefined;
+                saveState(R, me, st);
+            }
+            const all = link(logs);
+            // Heartbeats: one pong per allowed ping, in code; a separate durable cursor, never a model run.
+            const heartbeatSeen = { ...st.heartbeatSeen };
+            const answered = new Set((logs.get(me) ?? []).filter(m => m.kind === 'pong').map(m => m.reId));
+            for (const [id, msgs] of logs) {
+                if (id === me)
+                    continue;
+                const at = msgs.findIndex(m => m.id === heartbeatSeen[id]);
+                for (const m of msgs.slice(at + 1)) {
+                    if (m.bad || m.kind !== 'ping' || !m.to.includes(me) || answered.has(m.id) || m.hopEff >= maxHop || (allow && !allow.has(m.from)))
+                        continue;
+                    append(R, me, pongText(me, m, 'has a watcher'));
+                    note(`watch: answered heartbeat ${short(m.id)} from ${m.from}`);
+                }
+                if (msgs.length)
+                    heartbeatSeen[id] = msgs.at(-1).id;
+            }
+            const { msgs: fresh, cursors } = unread(logs, me, st.watched ?? st.seen ?? {}, Infinity, HIDDEN);
+            const retry = (st.pending ?? []).flatMap(id => {
+                const m = all.get(id);
+                if (!m)
+                    return [];
+                const task = taskFor(all, m, P);
+                return !task || isOpen(taskOf(all, task, P), P) ? [m] : [];
+            });
+            const msgs = [...new Map([...retry, ...fresh].map(m => [m.id, m])).values()];
+            const go = msgs.filter(m => wakes(m, me, HIDDEN) && m.hopEff < maxHop && (!allow || allow.has(m.from)));
+            for (const m of msgs)
+                if (!go.includes(m))
+                    note(`watch: not waking for ${short(m.id)} from ${m.from} (to ${m.to.join(',')}, hop ${m.hopEff})`);
+            // Group by the grant of each message's work; a message outside a grant spends the watcher's own budget.
+            const groups = new Map();
+            for (const m of go) {
+                const task = taskFor(all, m, P);
+                const g = task ? taskOf(all, task, P).grant : null;
+                if (!groups.has(g))
+                    groups.set(g, { grant: g, msgs: [], task });
+                groups.get(g).msgs.push(m);
+            }
+            const runs = [];
+            let hold = false;
+            const now = Date.now() / 1000;
+            let ownRuns = (st.runs ?? []).filter(t => t > now - span);
+            const exhausted = { ...st.exhausted };
+            for (const grp of groups.values()) {
+                if (!grp.grant) {
+                    if (w.requireGrant) {
+                        for (const m of grp.msgs)
+                            note(`watch: ${short(m.id)} is outside any grant; --require-grant: not starting a turn`);
+                        continue;
+                    }
+                    if (ownRuns.length >= maxRuns) {
+                        hold = true;
+                        note(`watch: own run budget spent (${maxRuns} per ${span}s); ${grp.msgs.length} message(s) wait`);
+                        continue;
+                    }
+                    ownRuns = [...ownRuns, now];
+                    runs.push({ ...grp, timeout: null });
+                    continue;
+                }
+                // The grant lock covers reservation and decisions on this machine.
+                const r = (() => {
+                    // Fence: only the watcher that holds the seat reserves.
+                    if (readSession(handle)?.pid !== process.pid)
+                        return { why: 'this watcher no longer holds the seat', lost: true };
+                    const gr = D.grantOf(all, R.authorityAt, grp.grant);
+                    if (!gr)
+                        return { why: `grant ${short(grp.grant)} is not an approved decision with a budget` };
+                    if (gr.revoked)
+                        return { why: `grant ${short(gr.id)} was revoked`, exhausted: true, gr };
+                    const u = D.usageOf(all, gr);
+                    if (u.left <= 0)
+                        return { why: `grant ${short(gr.id)} is spent: ${u.runs}/${gr.budget.runs} runs`, exhausted: true, gr };
+                    if (u.open >= gr.budget.concurrency)
+                        return { why: `grant ${short(gr.id)} has ${u.open} run(s) open, concurrency ${gr.budget.concurrency}`, wait: true };
+                    const run = `${raw}.${process.pid}.${Date.now().toString(36)}.${runSeq++}`;
+                    append(R, me, compose(`usage: reserve a run of ${me}`, [['To', OPERATOR], ['Kind', 'usage'], ['Grant', gr.id], ['Usage', 'reserve'], ['Run', run]]));
+                    return { gr, run };
+                })();
+                if (r.lost)
+                    return { runs: [], hold: true, lost: true };
+                if (r.wait) {
+                    hold = true;
+                    note(`watch: ${r.why}; waiting`);
+                    continue;
+                }
+                if (r.why) {
+                    note(`watch: ${r.why}`);
+                    const key = `${grp.task?.id}/${grp.grant}`;
+                    if (r.exhausted && grp.task && !exhausted[key]) {
+                        exhausted[key] = true;
+                        const t = taskOf(all, grp.task, P);
+                        const last = grp.msgs.at(-1);
+                        // The profile names its waiting state, if it has one; otherwise the answer carries no state.
+                        if (isOpen(t, P))
+                            append(R, me, compose(`${r.why}; waiting for a new grant`, [['To', [...new Set([t.requester, OPERATOR])].join(', ')], ['Re', last.id], ['State', P.waiting], ['Hop', String(last.hopEff + 1)]]));
+                    }
+                    continue;
+                }
+                runs.push({ ...grp, run: r.run, timeout: r.gr.budget['run-seconds'] });
+            }
+            const pending = [...new Set([...retry.map(m => m.id), ...runs.flatMap(r => r.msgs.map(m => m.id))])];
+            saveState(R, me, { ...loadState(R, me), heartbeatSeen, exhausted, pending, runs: ownRuns,
+                ...(hold ? {} : { watched: cursors }) });
+            return { runs, hold, lost: false };
+        }));
+        if (plan.lost) {
+            log(`watch: the seat of ${me} was taken over; stopping`);
+            return 0;
+        }
+        let exitCode = 0;
+        const settle = (run, seconds, exit, why) => append(R, me, compose(`usage: settle a run of ${me}${why ? ` (${why})` : ''}`, [['To', OPERATOR], ['Kind', 'usage'], ['Grant', run.grant], ['Usage', 'settle'], ['Run', run.run], ['Seconds', String(seconds)], ['Exit', String(exit)]]));
+        for (const run of plan.runs) {
+            // Spawn under the same locks as revocation and stop; wait for the turn after releasing them.
+            const next = locked(`grant-${H.name}`, () => {
+                if (run.grant) {
+                    const { logs } = readerLock(R, me, () => loadRoomUnlocked(R, me));
+                    const gr = D.grantOf(link(logs), R.authorityAt, run.grant);
+                    if (!gr || gr.revoked)
+                        return { why: !gr ? 'its grant is no longer valid' : 'its grant was revoked' };
+                }
+                readerLock(R, me, () => {
+                    const st = loadState(R, me);
+                    saveState(R, me, { ...st, inflight: { seen: st.seen ?? {} } });
+                });
+                return locked('sessions', () => {
+                    const cur = readSession(handle);
+                    if (!cur || cur.pid !== process.pid)
+                        return { why: 'the seat was taken over' };
+                    if (cur.state !== 'active')
+                        return { why: 'the watcher was stopped' };
+                    note(`watch: ${run.msgs.length} new${run.grant ? ` under grant ${short(run.grant)}` : ''}: ${cmd}`);
+                    return { done: turn(cmd, run.timeout, { ...process.env, RINGI_HOME: HOME, RINGI_SESSION: raw, RINGI_MSGS: run.msgs.map(m => m.id).join('\n'), RINGI_GRANT: run.grant ?? '' }) };
+                });
+            });
+            if (next.why) {
+                note(`watch: not starting the next turn: ${next.why}`);
+                if (run.run)
+                    settle(run, 0, 125, `not started: ${next.why}`);
+                continue;
+            }
+            const r = await next.done;
+            note(`watch: exit ${r.code ?? r.signal}${r.timedOut ? ' (stopped at the grant\'s run-seconds)' : ''} after ${r.seconds}s`);
+            // Settled only once the whole turn, descendants included, has ended.
+            if (run.run)
+                settle(run, r.seconds, r.code ?? 128);
+            readerLock(R, me, () => {
+                const st = loadState(R, me), delivered = new Set(run.msgs.map(m => m.id));
+                // A deadline is an intentional budget stop, not a delivery failure to spend another run on.
+                const deliveredTurn = r.code === 0 || r.timedOut;
+                saveState(R, me, { ...st, inflight: undefined, ...(deliveredTurn
+                        ? { pending: (st.pending ?? []).filter(id => !delivered.has(id)) }
+                        : { seen: st.inflight?.seen ?? st.seen }) });
+            });
+            if (r.code !== 0 || r.timedOut)
+                exitCode ||= r.code || 128;
+        }
+        if (w.once)
+            return exitCode || (plan.hold ? 4 : 0);
+        await sleep(interval);
+    }
+};

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

@@ -0,0 +1,345 @@
+// git-store: the Store port on git. The store directory holds one bare repository (`store/.git`):
+//   refs/heads/main                       the shared contract, one commit per amendment
+//   refs/heads/<room>/control             the room's control record; its first commit is the room's genesis
+//   refs/heads/<room>/log/<agent>         one log per member; each message is a commit
+//   refs/tags/ringi/<genesis>/<agent>/<message>.<signal>   signals, annotated tags in their author's namespace
+//   refs/archive/<room>@<genesis8>/…      an archived room, read-only
+//   refs/ringi/accepted/<genesis>/<reader>/<log>   readers' pins of accepted heads
+// A signed hub signs every commit and tag with its author's key and verifies what it fetches (remote.ts).
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { cannotWrite, mkdirIn, SANDBOX } from '../../lib/index.js';
+import * as Remote from './remote.js';
+import { fail, note } from '../../lib/index.js';
+import { TEXT_MAX, checkOutgoing, parse } from '../../protocol/index.js';
+import { checkCollisions, checkPath } from '../../protocol/files.js';
+const ZERO = '0'.repeat(40);
+const ident = (id) => ({ GIT_AUTHOR_NAME: id, GIT_AUTHOR_EMAIL: `${id}@ringi`, GIT_COMMITTER_NAME: id, GIT_COMMITTER_EMAIL: `${id}@ringi` });
+export const runGit = (args, o = {}) => {
+    const r = spawnSync('git', args, { input: o.input, encoding: 'utf8', env: Remote.gitEnv(o.env), maxBuffer: 1 << 30, timeout: Remote.gitTimeout() });
+    return check(args, r, o.where).stdout;
+};
+const runGitOk = (args, o = {}) => {
+    const r = spawnSync('git', args, { input: o.input, encoding: 'utf8', env: Remote.gitEnv(o.env), maxBuffer: 1 << 30, timeout: Remote.gitTimeout() });
+    Remote.checkGitTimeout(r.error);
+    return r;
+};
+const runGitRaw = (args, where) => {
+    const r = spawnSync('git', args, { encoding: 'buffer', env: Remote.gitEnv(), maxBuffer: 1 << 30, timeout: Remote.gitTimeout() });
+    return check(args, r, where).stdout;
+};
+function check(args, r, where = 'the hub store') {
+    Remote.checkGitTimeout(r.error);
+    if (r.error)
+        throw r.error;
+    if (r.status !== 0) {
+        const err = String(r.stderr ?? '').trim();
+        if (SANDBOX.test(err))
+            cannotWrite(where, err.split('\n').at(-1));
+        fail(`git ${args.find(a => !a.startsWith('-') && !a.includes('/')) ?? ''}: ${err.split('\n').at(-1)}`);
+    }
+    return r;
+}
+const splitBuf = (b, sep) => {
+    const parts = [];
+    let at = 0;
+    for (let i = b.indexOf(sep); i >= 0; i = b.indexOf(sep, at)) {
+        parts.push(b.subarray(at, i));
+        at = i + 1;
+    }
+    parts.push(b.subarray(at));
+    return parts;
+};
+const REGULAR = new Set(['100644', '100755']);
+export class GitStore {
+    type = 'git';
+    trust;
+    dir;
+    d;
+    home;
+    // The handle remote.ts works on: the repository and what it learned on the last sync.
+    h;
+    constructor(hubDir, d, home) {
+        this.d = d;
+        this.home = home;
+        this.trust = d.trust;
+        this.dir = path.join(hubDir, d.store.path, '.git');
+        this.h = { name: d.name, dir: this.dir, d };
+        if (!fs.existsSync(this.dir))
+            fail(`hub ${d.name}: no git store at ${this.dir}`);
+    }
+    args(a) { return ['--git-dir', this.dir, ...a]; }
+    git(a, o) { return runGit(this.args(a), { ...o, where: this.home }); }
+    gitOk(a, o) { return runGitOk(this.args(a), o); }
+    rev(ref) {
+        const r = this.gitOk(['rev-parse', '-q', '--verify', `${ref}^{commit}`]);
+        return r.status === 0 ? r.stdout.trim() : null;
+    }
+    isAncestor(a, b) { return this.gitOk(['merge-base', '--is-ancestor', a, b]).status === 0; }
+    isRef(s) { return /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(s ?? ''); }
+    extends(older, newer) { return older === newer || this.isAncestor(older, newer); }
+    // --- writing ---
+    emptyTree() { return this.git(['hash-object', '-w', '-t', 'tree', '--stdin'], { input: '' }).trim(); }
+    // A tree from a base tree with entries put on top; nested paths are fine.
+    tree(base, entries) {
+        const idx = path.join(this.home, 'tmp', `index.${process.pid}.${crypto.randomBytes(4).toString('hex')}`);
+        mkdirIn(this.home, path.dirname(idx));
+        const env = { GIT_INDEX_FILE: idx };
+        try {
+            this.git(['read-tree', ...(base ? [base] : ['--empty'])], { env });
+            for (const e of entries) {
+                const sha = this.git(['hash-object', '-w', ...(e.file ? ['--', e.file] : ['--stdin'])], { input: e.content }).trim();
+                this.git(['update-index', '--add', '--cacheinfo', `${e.mode},${sha},${e.path}`], { env });
+            }
+            return this.git(['write-tree'], { env }).trim();
+        }
+        finally {
+            fs.rmSync(idx, { force: true });
+        }
+    }
+    // Every commit is made here: on a signed hub, signed by its author's key on this machine.
+    commit(who, text, tree, parents) {
+        return this.git(['commit-tree', ...Remote.sign(this.h, who, this.home), tree, ...parents.flatMap(p => ['-p', p])], { input: text, env: ident(who) }).trim();
+    }
+    advance(ref, sha, old) {
+        if (this.gitOk(['update-ref', ref, sha, old ?? ZERO]).status !== 0)
+            return false;
+        // A signed hub publishes at once; a rejected push keeps the commit here and alarms (remote.ts).
+        Remote.push(this.h, ref);
+        return true;
+    }
+    static create(hubDir, d, home, contract, text) {
+        const dir = path.join(hubDir, d.store.path, '.git');
+        // 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 });
+        }
+        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' }))), []);
+        if (d.trust === 'signed')
+            d.genesis = sha;
+        if (!s.advance('refs/heads/main', sha, null))
+            fail(`hub ${d.name}: main already exists`);
+        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 });
+        return Remote.setupSigned({ name: d.name, dir, d }, home, d.store.remote).root;
+    }
+    sync() {
+        Remote.sync(this.h);
+    }
+    // --- the contract ---
+    contractHead() { return this.rev('refs/heads/main') ?? fail(`hub ${this.d.name} has no contract (main)`); }
+    contractFile(rev, name) {
+        const r = this.gitOk(['show', `${rev}:${name}`]);
+        return r.status === 0 ? r.stdout : null;
+    }
+    contractFiles(rev) { return this.git(['ls-tree', '-r', '--name-only', rev]).split('\n').filter(Boolean); }
+    amendContract(who, text, files) {
+        const head = this.contractHead();
+        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');
+        return sha;
+    }
+    // --- rooms ---
+    base(name) { return name.includes('@') ? `refs/archive/${name}` : `refs/heads/${name}`; }
+    roomNames(archived) {
+        const re = archived ? /^refs\/archive\/([^/]+)\/control$/ : /^refs\/heads\/([^/]+)\/control$/;
+        return this.git(['for-each-ref', '--format=%(refname)', archived ? 'refs/archive/' : 'refs/heads/']).split('\n').map(r => re.exec(r)?.[1]).filter((x) => !!x).sort();
+    }
+    room(name) {
+        const control = `${this.base(name)}/control`;
+        const head = this.rev(control);
+        if (!head)
+            return null;
+        const genesis = this.git(['rev-list', '--reverse', control, '^refs/heads/main']).split('\n')[0]
+            || this.git(['rev-list', '--reverse', control]).split('\n').filter(Boolean).at(-1);
+        const recs = this.git(['log', '--reverse', '--format=%H%x1f%B%x1e', control, `^${genesis}^`]).split('\x1e').map(s => s.trim()).filter(Boolean);
+        return { name, archived: name.includes('@'), head, genesis, base: this.git(['rev-parse', `${genesis}^`]).trim(),
+            control: recs.map(r => {
+                const [rev, text = ''] = r.split('\x1f');
+                return { rev: rev.trim(), text };
+            }) };
+    }
+    controlFile(room, name, rev) {
+        const r = this.gitOk(['show', `${rev ?? room.head}:${name}`]);
+        return r.status === 0 ? r.stdout : null;
+    }
+    createRoom(name, who, text, files) {
+        const ref = `refs/heads/${name}/control`;
+        if (this.rev(ref))
+            fail(`room ${name} exists in hub ${this.d.name}`);
+        const sha = this.commit(who, text, this.tree(null, Object.entries(files).map(([p, c]) => ({ path: p, content: c, mode: '100644' }))), [this.contractHead()]);
+        if (!this.advance(ref, sha, null))
+            fail(`room ${name} was created meanwhile`);
+        return sha;
+    }
+    // Every other file of the control tree (a signed room's allowed_signers) is kept.
+    updateControl(room, who, text, files) {
+        const ref = `${this.base(room.name)}/control`;
+        const sha = this.commit(who, text, this.tree(`${room.head}^{tree}`, Object.entries(files).map(([p, c]) => ({ path: p, content: c, mode: '100644' }))), [room.head]);
+        if (!this.advance(ref, sha, room.head))
+            fail(`room ${room.name}: its control moved; retry`);
+        return sha;
+    }
+    refsUnder(prefix) {
+        return this.git(['for-each-ref', '--format=%(refname) %(objectname)', prefix]).split('\n').filter(Boolean).map(l => l.split(' '));
+    }
+    archiveRoom(room, as) {
+        const moves = [[`${this.base(room.name)}/`, `refs/archive/${as}/`], [`refs/tags/ringi/${room.genesis}/`, `refs/archive/${as}/signals/`]];
+        for (const [from, to] of moves) {
+            for (const [ref, sha] of this.refsUnder(from)) {
+                this.git(['update-ref', `${to}${ref.slice(from.length)}`, sha, ZERO]);
+                this.git(['update-ref', '-d', ref, sha]);
+            }
+        }
+    }
+    deleteRoom(room) {
+        for (const prefix of [`${this.base(room.name)}/`, `refs/ringi/accepted/${room.genesis}/`, `refs/tags/ringi/${room.genesis}/`]) {
+            for (const [ref] of this.refsUnder(prefix))
+                this.git(['update-ref', '-d', ref]);
+        }
+    }
+    legacy(room) {
+        const base = this.base(room.name);
+        return { name: room.name, head: room.head, genesis: room.genesis, archived: room.archived, control: `${base}/control`, log: (who) => `${base}/log/${who}` };
+    }
+    roster(room) {
+        if (this.trust !== 'signed' || room.archived)
+            return null;
+        const v = Remote.verifyRoom(this.h, this.legacy(room));
+        return { members: v.members, signers: v.entries };
+    }
+    // --- logs ---
+    logIds(room) {
+        const prefix = `${this.base(room.name)}/log/`;
+        return this.git(['for-each-ref', '--format=%(refname)', prefix]).split('\n').filter(Boolean).map(r => r.slice(prefix.length));
+    }
+    logHead(room, id) { return this.rev(`${this.base(room.name)}/log/${id}`); }
+    // The log's commits after the genesis, oldest first, read as bytes: the text is the commit message, the files are
+    // the explicit Ringi-Files list, or the changed paths for records without it.
+    messages(room, id, head) {
+        const raw = runGitRaw(this.args(['log', '--topo-order', '--reverse', '--no-renames', '--raw', '--no-abbrev', '--format=%x1e%H%x1f%P%x1f%ct%x1f%B%x1f', head, `^${room.genesis}`]), this.home);
+        return splitBuf(raw, 0x1e).filter(b => b.length).map(rec => {
+            const [sha, parent, ct, body, rest = Buffer.alloc(0)] = splitBuf(rec, 0x1f);
+            let files = rest.toString('utf8').split('\n').map(l => /^:\d{6} (\d{6}) \S+ \S+ ([A-Z])\d*\t(.*)$/.exec(l)).filter((x) => !!x)
+                .filter(([, , status]) => status !== 'D').map(([, mode, , p]) => ({ path: p, mode }));
+            const declared = parse(body.toString('utf8'), s => this.isRef(s)).trailers['ringi-files'];
+            const refused = [];
+            if (declared) {
+                let names = [];
+                try {
+                    const paths = JSON.parse(declared[0]);
+                    if (declared.length !== 1 || !Array.isArray(paths) || !paths.every(p => typeof p === 'string'))
+                        fail('invalid attachment list');
+                    names = paths.map(checkPath);
+                    if (new Set(names).size !== names.length)
+                        fail('duplicate attachment path');
+                    checkCollisions(names);
+                }
+                catch {
+                    refused.push({ path: 'Ringi-Files', mode: 'invalid', why: 'expected one JSON array of safe, distinct file paths' });
+                }
+                const wanted = new Set(names);
+                files = names.length && !refused.length ? splitBuf(runGitRaw(this.args(['ls-tree', '-r', '-z', sha.toString()]), this.home), 0)
+                    .map(b => /^(\d+) \w+ [0-9a-f]+\t(.*)$/s.exec(b.toString('utf8'))).filter((x) => !!x)
+                    .map(([, mode, p]) => ({ path: p, mode })).filter(f => wanted.has(f.path)) : [];
+                for (const f of files)
+                    wanted.delete(f.path);
+                if (!refused.length)
+                    for (const p of wanted)
+                        files.push({ path: p, mode: 'missing' });
+            }
+            return { id: sha.toString(), parent: parent.toString() || null, time: Number(ct.toString()), text: body,
+                files: files.filter(f => REGULAR.has(f.mode)), refused: [...refused, ...files.filter(f => !REGULAR.has(f.mode))] };
+        });
+    }
+    // One commit on the author's log, compare-and-swap, so two writers of one log retry instead of forking it.
+    append(room, who, text, entries) {
+        if (room.archived)
+            fail(`room ${room.name} is archived: read-only`);
+        if (checkOutgoing(text, s => this.isRef(s)).trailers['ringi-files'])
+            fail('Ringi-Files is store metadata; supply attachments instead');
+        if (entries.length)
+            text = `${text.trimEnd()}\nRingi-Files: ${JSON.stringify([...new Set(entries.map(e => e.path))])}\n`;
+        if (Buffer.byteLength(text) > TEXT_MAX)
+            fail('attachment list makes the message exceed 64 KiB; use fewer or shorter paths');
+        checkOutgoing(text, s => this.isRef(s));
+        const ref = `${this.base(room.name)}/log/${who}`;
+        for (let i = 0; i < 8; i++) {
+            const head = this.rev(ref);
+            const base = head ? `${head}^{tree}` : null;
+            const tree = entries.length ? this.tree(base, entries) : base ? this.git(['rev-parse', base]).trim() : this.emptyTree();
+            const sha = this.commit(who, text, tree, [head ?? room.genesis]);
+            if (this.advance(ref, sha, head))
+                return sha;
+        }
+        return fail(`the log ${who} kept moving while writing; retry`);
+    }
+    verifyLog(room, id, head) {
+        return this.trust === 'signed' ? Remote.verify(this.h, this.legacy(room), id, head) : null;
+    }
+    pin(room, reader, id, rev) {
+        if (!room.archived)
+            this.git(['update-ref', `refs/ringi/accepted/${room.genesis}/${reader}/${id}`, rev]);
+    }
+    unpin(room, reader, id) {
+        this.gitOk(['update-ref', '-d', `refs/ringi/accepted/${room.genesis}/${reader}/${id}`]);
+    }
+    file(rev, p) { return runGitRaw(this.args(['show', `${rev}:${p}`]), this.home); }
+    sizes(rev, paths) {
+        if (!paths.length)
+            return new Map();
+        const wanted = new Set(paths);
+        return new Map(splitBuf(runGitRaw(this.args(['ls-tree', '-r', '-l', '-z', rev]), this.home), 0)
+            .map(b => /^\d+ blob [0-9a-f]+ +(\d+)\t(.*)$/s.exec(b.toString('utf8'))).filter((x) => !!x)
+            .filter(([, , p]) => wanted.has(p)).map(([, n, p]) => [p, Number(n)]));
+    }
+    // --- signals ---
+    // An annotated tag in its author's namespace under the room's genesis (a room recreated under the same name is
+    // another namespace), signed on a signed hub. Writing the same signal twice is a no-op.
+    signal(room, who, target, name, text) {
+        const tag = `ringi/${room.genesis}/${who}/${name}`;
+        const ref = `refs/tags/${tag}`;
+        if (this.gitOk(['rev-parse', '-q', '--verify', ref]).status === 0) {
+            Remote.push(this.h, ref);
+            return;
+        }
+        const sign = Remote.sign(this.h, who, this.home);
+        const key = sign[0]?.slice(2);
+        this.git([...(key ? ['-c', `user.signingkey=${key}`] : []), 'tag', key ? '-s' : '-a', '-F', '-', tag, target], { input: text, env: ident(who) });
+        Remote.push(this.h, ref);
+    }
+    signals(room) {
+        const prefix = room.archived ? `refs/archive/${room.name}/signals/` : `refs/tags/ringi/${room.genesis}/`;
+        const raw = this.git(['for-each-ref', '--format=%(refname)%1f%(objectname)%1f%(objecttype)%1f%(*objectname)%1f%(taggername)%1f%(contents)%1e', prefix]);
+        const records = raw.split('\x1e').map(s => s.replace(/^\n/, '')).filter(Boolean).map(rec => {
+            const [ref, object, type, target, tagger, text = ''] = rec.split('\x1f');
+            const [actor, ...rest] = ref.slice(prefix.length).split('/');
+            // Only an annotated tag on a commit is a signal; anything else points nowhere.
+            return { ref, object, name: rest.join('/'), actor, target: type === 'tag' ? target : '', tagger, text };
+        });
+        if (this.trust !== 'signed' || room.archived)
+            return records;
+        return Remote.withVerification(this.h, () => records.filter(s => {
+            const why = Remote.verifySignal(this.h, this.legacy(room), s.ref, s.object);
+            if (why)
+                note(`ALARM signal ${s.ref}: ${why}; quarantined and withheld`);
+            return !why;
+        }));
+    }
+    // --- signed stores ---
+    admit(room, who, key) { return Remote.roomAdmit(this.h, this.legacy(room), who, key, this.home); }
+    joinKey(room, who) { return Remote.join(this.h, this.legacy(room), who, this.home); }
+    forgetLog(room, id) { Remote.forget(this.h, this.legacy(room), id); }
+    rootKey() { return this.d.root ?? fail(`hub ${this.d.name} has no pinned root`); }
+    rootRoster() { return Remote.rootRoster(this.h); }
+}