@idleware/ringi 0.5.0 → 0.6.0

package/target/esm/adapters/host-posix/launch.js

@@ -0,0 +1,80 @@
+// host-posix launch: an isolated shell turn settles its group before its result, as the watcher did before this
+// adapter. Detached argv launches leave the caller's event loop. Only this module knows POSIX group signals.
+import { spawn } from 'node:child_process';
+import { sleep } from '../../lib/index.js';
+import { groupAlive } from './groups.js';
+const GRACE = 5000;
+const signalGroup = (pid, sig) => {
+    if (pid)
+        try {
+            process.kill(-pid, sig);
+        }
+        catch { }
+};
+const detachedSettlement = async (pid) => {
+    while (pid && groupAlive(pid))
+        await new Promise(resolve => { setTimeout(resolve, 50).unref(); });
+};
+const settle = async (pid) => {
+    if (!pid)
+        return;
+    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);
+};
+const detached = (r, clock) => {
+    const at = clock.wall(), child = spawn(r.file, [...r.args], { stdio: 'ignore', env: r.env, detached: true });
+    let finished = false;
+    const done = new Promise((resolve, reject) => {
+        child.once('error', e => { finished = true; reject(e); });
+        child.once('exit', (code, signal) => {
+            void detachedSettlement(child.pid).then(() => {
+                finished = true;
+                resolve({ code, signal, timedOut: false, seconds: Math.round((clock.wall() - at) / 1000) });
+            }, reject);
+        });
+    });
+    child.unref();
+    // Fire-and-forget launches still handle spawn failures without an unhandled rejection.
+    void done.catch(() => { });
+    return { done, stop: () => { if (!finished)
+            signalGroup(child.pid, 'SIGTERM'); } };
+};
+const shell = (r, clock) => {
+    const at = clock.wall(), child = spawn('sh', ['-c', r.shell], { stdio: 'inherit', env: r.env, detached: true });
+    let timedOut = false, finished = false;
+    const stop = () => { if (!finished)
+        signalGroup(child.pid, 'SIGTERM'); };
+    const done = new Promise((resolve, reject) => {
+        let hard;
+        const timer = r.timeout ? setTimeout(() => {
+            timedOut = true;
+            signalGroup(child.pid, 'SIGTERM');
+            hard = setTimeout(() => signalGroup(child.pid, 'SIGKILL'), GRACE);
+        }, r.timeout * 1000) : undefined;
+        const cleanup = () => {
+            clearTimeout(timer);
+            clearTimeout(hard);
+            process.removeListener('SIGINT', stop);
+            process.removeListener('SIGTERM', stop);
+        };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        child.once('error', e => { finished = true; cleanup(); reject(e); });
+        child.once('exit', (code, signal) => {
+            cleanup();
+            void settle(child.pid).then(() => {
+                finished = true;
+                resolve({ code, signal, timedOut, seconds: Math.round((clock.wall() - at) / 1000) });
+            }, reject);
+        });
+    });
+    return { done, stop };
+};
+export const launch = (request, clock) => 'shell' in request ? shell(request, clock) : detached(request, clock);
+//# sourceMappingURL=launch.js.map

package/target/esm/adapters/host-posix/probes.js

@@ -0,0 +1,66 @@
+// host-posix probes: process existence, ancestry and CPU samples on macOS/Linux. Unavailable CPU probes stay null.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { procStat, seconds } from './stats.js';
+export const supported = process.platform === 'darwin' || process.platform === 'linux';
+export const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+};
+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;
+};
+export const snapshot = () => {
+    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;
+};
+export const ancestors = (first) => {
+    const result = [];
+    for (let pid = first, i = 0; i < 12 && pid > 1; i++) {
+        const r = spawnSync('ps', ['-o', 'ppid=,comm=', '-p', String(pid)], { encoding: 'utf8' });
+        const m = r.status === 0 ? /^\s*(\d+)\s+(.*)$/.exec(String(r.stdout ?? '').trim()) : null;
+        if (!m)
+            break;
+        result.push({ pid, name: path.basename(m[2].trim()).toLowerCase() });
+        pid = Number(m[1]);
+    }
+    return result;
+};
+//# sourceMappingURL=probes.js.map

package/target/esm/adapters/host-posix/stats.js

@@ -0,0 +1,27 @@
+// host-posix stats: parsing and folding of process CPU samples; no probes, files or platform selection.
+// Cumulative CPU time: [DD-][HH:]MM:SS[.ss].
+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);
+};
+// A parenthesized command may itself contain spaces or parentheses; fields follow its last closing parenthesis.
+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;
+};
+export const treeCpu = (pid, rows) => {
+    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=stats.js.map

package/target/esm/adapters/keys-file/index.js

@@ -0,0 +1,68 @@
+// keys-file: the existing headless SSH key custody behind Signer. Construction does no I/O; only an explicit
+// resolve(create) makes a key. Public identity is derived from the private key, never from a mutable .pub sidecar.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { Fail } from '../../lib/index.js';
+import { guardWrite, mkdirIn } from '../fs/index.js';
+const refusal = (reason, message) => Object.assign(new Fail(message), { reason });
+const name = (value) => {
+    if (!value || value === '.' || value === '..' || /[/\\\0]/.test(value))
+        throw refusal('denied', 'invalid key owner');
+    return value;
+};
+const command = (args, input = '', timeout = 30000) => {
+    const r = spawnSync('ssh-keygen', args, { encoding: 'utf8', input, timeout, maxBuffer: 64 * 1024 * 1024,
+        env: { ...process.env, SSH_ASKPASS_REQUIRE: 'never' } });
+    if (r.error?.code === 'ETIMEDOUT')
+        throw refusal('timeout', 'key signing timed out');
+    if (r.error || r.status !== 0) {
+        const detail = String(r.stderr || r.error?.message || r.signal || 'failed').trim().split('\n').at(-1);
+        throw refusal(/passphrase/i.test(detail || '') ? 'interaction-required' : 'unavailable', `ssh-keygen: ${detail}`);
+    }
+    return r.stdout;
+};
+const identity = (file, timeout = 30000) => {
+    const [algorithm, bytes] = command(['-y', '-P', '', '-f', file], '', timeout).trim().split(/\s+/);
+    return { key: `${algorithm} ${bytes}`, fingerprint: 'SHA256:' + crypto.createHash('sha256').update(Buffer.from(bytes, 'base64')).digest('base64').replace(/=+$/, '') };
+};
+const remaining = (r) => {
+    const ms = r.deadline - performance.now();
+    if (!Number.isFinite(ms) || ms <= 0)
+        throw refusal('timeout', 'key signing deadline expired');
+    if (!r.namespace || /[\r\n\0]/.test(r.namespace))
+        throw refusal('denied', 'invalid signature namespace');
+    return Math.max(1, Math.min(30000, Math.floor(ms)));
+};
+export const keysFile = (home) => {
+    const files = new Map();
+    const refs = new Map();
+    const keyFile = (key) => files.get(key) ?? (() => { throw refusal('denied', 'key reference belongs to another signer'); })();
+    const custody = (hub, principal) => path.join(home, 'keys', name(hub), name(principal));
+    return {
+        custody,
+        resolve: (hub, principal, create = false) => {
+            const file = custody(hub, principal);
+            if (!fs.existsSync(file)) {
+                if (!create)
+                    throw refusal('unavailable', `no private key for ${principal} on this machine; ${principal === 'operator' ? 'root keys are never obtained from a hub' : 'join here to generate one, then ask the root to admit its public key'}`);
+                mkdirIn(home, path.dirname(file));
+                guardWrite(home, () => command(['-q', '-t', 'ed25519', '-N', '', '-C', `${principal}@ringi`, '-f', file]));
+            }
+            const ref = refs.get(file) ?? crypto.randomUUID();
+            files.set(ref, file);
+            refs.set(file, ref);
+            return ref;
+        },
+        signer: {
+            publicIdentity: ref => identity(keyFile(ref)),
+            sign: r => {
+                const file = keyFile(r.key), publicKey = identity(file, remaining(r));
+                const bytes = command(['-Y', 'sign', '-n', r.namespace, '-f', file], Buffer.from(r.payload), remaining(r));
+                return { format: 'ssh', bytes: Buffer.from(bytes), fingerprint: publicKey.fingerprint, namespace: r.namespace };
+            },
+        },
+    };
+};
+//# sourceMappingURL=index.js.map

package/target/esm/adapters/state-fs/index.js

@@ -0,0 +1,79 @@
+// state-fs: the machine's state as files under one directory ($RINGI_HOME, default ~/.ringi). A key path is a path
+// below it and a record is `<key>.json`, written atomically; a lock is a file under `locks/`. The directory is made on
+// first use; one of another version, or anything else there, is refused. A write the sandbox denies fails with one fixed instruction (adapters/fs/write.ts).
+import fs from 'node:fs';
+import path from 'node:path';
+import { errno, fail, strictJson } from '../../lib/index.js';
+import { guardWrite, locked as lockFile, mkdirIn, writeJsonAtomic } from '../fs/index.js';
+const HOME_VERSION = 3;
+// State fails closed: unreadable JSON is an error, never a silent fresh start.
+const readJson = (f, dflt) => {
+    let raw;
+    try {
+        raw = fs.readFileSync(f, 'utf8');
+    }
+    catch (e) {
+        if (errno(e) === 'ENOENT')
+            return dflt;
+        throw e;
+    }
+    try {
+        JSON.parse(raw);
+    }
+    catch (e) {
+        return fail(`${f} is not valid JSON (${e.message}); refusing to continue with lost state`);
+    }
+    // A field written twice hides a value (a second root pin, say): refused, not read as the last one.
+    return strictJson(raw, f);
+};
+// A key's segment as a name in its directory: nothing that leaves it or names it twice.
+const segment = (s) => !s || s === '.' || s === '..' || /[/\\\0]/.test(s) ? fail(`bad state key segment ${JSON.stringify(s)}`) : s;
+export const stateFs = ({ root, build }) => {
+    const guard = (fn) => guardWrite(root, fn);
+    const dir = (key) => path.join(root, ...key.map(segment));
+    const file = (key) => `${dir(key)}.json`;
+    const marker = path.join(root, 'home.json');
+    const state = {
+        root,
+        present: () => fs.existsSync(root),
+        ensure: () => {
+            if (fs.existsSync(marker)) {
+                const v = readJson(marker, {}).version;
+                if (v !== HOME_VERSION)
+                    fail(`${root} is a ringi home of version ${v}; this ringi ${build.version} needs version ${HOME_VERSION}: set RINGI_HOME to a new directory for a fresh home; ringi does not migrate`);
+                return;
+            }
+            if (fs.existsSync(root) && fs.readdirSync(root).length)
+                fail(`${root} exists and is not a ringi home (no home.json); move it away or set RINGI_HOME`);
+            mkdirIn(root, root);
+            state.write(['home'], { version: HOME_VERSION });
+        },
+        locked: (name, fn) => {
+            state.ensure();
+            return guard(() => lockFile(path.join(state.place(['locks']), `${name}.lock`), fn));
+        },
+        read: (key, dflt) => readJson(file(key), dflt),
+        write: (key, value) => guard(() => {
+            mkdirIn(root, path.dirname(file(key)));
+            writeJsonAtomic(file(key), value);
+        }),
+        remove: key => guard(() => {
+            fs.rmSync(file(key), { force: true });
+            fs.rmSync(dir(key), { recursive: true, force: true });
+        }),
+        list: key => {
+            let names = [];
+            try {
+                names = fs.readdirSync(dir(key));
+            }
+            catch { }
+            return [...new Set(names.map(n => n.replace(/\.json$/, '')))].sort();
+        },
+        place: key => {
+            mkdirIn(root, dir(key));
+            return dir(key);
+        },
+    };
+    return state;
+};
+//# sourceMappingURL=index.js.map

package/target/esm/adapters/tool-claude/index.js

@@ -0,0 +1,32 @@
+// tool-claude: Claude Code. A session says so in its environment (CLAUDECODE, CLAUDE_CODE_SESSION_ID) and is known by
+// its session id, `claude:<id>`. While it works it writes its transcript
+// $CLAUDE_CONFIG_DIR (or ~/.claude)/projects/<dir>/<session id>.jsonl; it reads skills from .claude/skills.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { UUID, mtime, newestFirst } from '../tool-traces/index.js';
+const transcript = (id) => {
+    const root = path.join(process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), '.claude'), 'projects');
+    const dir = newestFirst(root).find(d => fs.existsSync(path.join(root, d, `${id}.jsonl`)));
+    return dir ? path.join(root, dir, `${id}.jsonl`) : null;
+};
+// A transcript once found keeps its path; only its time is read again.
+const found = new Map();
+export const claude = {
+    id: 'claude',
+    detect: env => env.CLAUDECODE === '1' || !!env.CLAUDE_CODE_SESSION_ID,
+    processes: ['claude'],
+    session: env => env.CLAUDE_CODE_SESSION_ID ? { handle: `claude:${env.CLAUDE_CODE_SESSION_ID}`, pid: Number(env.CLAUDE_PID) || null } : null,
+    traceId: s => s.handle.startsWith('claude:') || s.product === 'claude' ? UUID.exec(s.handle)?.[1] ?? null : null,
+    traceTime: id => {
+        if (!found.has(id)) {
+            const f = transcript(id);
+            if (!f)
+                return null;
+            found.set(id, f);
+        }
+        return mtime(found.get(id));
+    },
+    skillDirs: base => [path.join(base, '.claude', 'skills', 'ringi')],
+};
+//# sourceMappingURL=index.js.map

package/target/esm/adapters/tool-codex/index.js

@@ -0,0 +1,38 @@
+// tool-codex: Codex. A session says so in its environment (CODEX_*); a chat names itself on every ringi command with
+// RINGI_SESSION=codex-<thread id>. While it works it writes its rollout
+// $CODEX_HOME (or ~/.codex)/sessions/<yyyy>/<mm>/<dd>/rollout-<time>-<thread id>.jsonl; it reads skills from
+// .agents/skills, and its sandbox writes where its writable roots allow.
+import os from 'node:os';
+import path from 'node:path';
+import { UUID, mtime, newestFirst } from '../tool-traces/index.js';
+const rollout = (id) => {
+    const root = path.join(process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex'), 'sessions');
+    for (const y of newestFirst(root))
+        for (const m of newestFirst(path.join(root, y)))
+            for (const d of newestFirst(path.join(root, y, m))) {
+                const f = newestFirst(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 rollout once found keeps its path; only its time is read again.
+const found = new Map();
+export const codex = {
+    id: 'codex',
+    detect: env => Object.keys(env).some(k => k.startsWith('CODEX_')),
+    processes: ['codex'],
+    traceId: s => s.product === 'codex' || s.handle.startsWith('env:codex-') ? UUID.exec(s.handle)?.[1] ?? null : null,
+    traceTime: id => {
+        if (!found.has(id)) {
+            const f = rollout(id);
+            if (!f)
+                return null;
+            found.set(id, f);
+        }
+        return mtime(found.get(id));
+    },
+    skillDirs: base => [path.join(base, '.agents', 'skills', 'ringi')],
+    sandboxHint: where => `Codex: the narrowest grant is [sandbox_workspace_write] writable_roots = ["${where}"] in ~/.codex/config.toml.`,
+};
+//# sourceMappingURL=index.js.map

package/target/esm/adapters/tool-cursor/index.js

@@ -0,0 +1,8 @@
+// tool-cursor: Cursor, recognised only: a session says so in its environment (CURSOR_*) or by its process. It names no
+// session, writes no trace ringi reads, and gets no skill.
+export const cursor = {
+    id: 'cursor',
+    detect: env => Object.keys(env).some(k => k.startsWith('CURSOR_')),
+    processes: ['cursor', 'cursor-agent'],
+};
+//# sourceMappingURL=index.js.map

package/target/esm/adapters/tool-traces/index.js

@@ -0,0 +1,18 @@
+// tool-traces: what the tool adapters share to find a session's trace: a session id at the end of a name, directories
+// newest first, and when a file was last written.
+import fs from 'node:fs';
+export const UUID = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+export const newestFirst = (d) => { try {
+    return fs.readdirSync(d).sort().reverse();
+}
+catch {
+    return [];
+} };
+// Unix seconds, or null when the file is gone.
+export const mtime = (f) => { try {
+    return fs.statSync(f).mtimeMs / 1000;
+}
+catch {
+    return null;
+} };
+//# sourceMappingURL=index.js.map

package/target/esm/adapters/transport-git/branches.js

@@ -0,0 +1,155 @@
+// branches: a room is one linear branch from its genesis. What its commits are (messages or control records), the
+// room's control files, and the room's life: create, archive, delete.
+import { fail } from '../../lib/index.js';
+import * as Remote from './remote.js';
+import { ZERO } from './run.js';
+import { Repo } from './repo.js';
+import { ID_RE, parse } from '../../core/hub/protocol/index.js';
+// The root's principal, and the files only its control records may change.
+const ROOT = 'operator';
+export const CONTROL_FILES = new Set(['ROOM.md', 'members.json', 'profile.json', 'allowed_signers']);
+export class Branches extends Repo {
+    ref(name) { return name.includes('@') ? `refs/archive/${name}` : `refs/heads/${name}`; }
+    tip(name) { return this.rev(this.ref(name)); }
+    // Every branch but the contract's, by name.
+    roomBranches() {
+        return this.git(['for-each-ref', '--format=%(refname:lstrip=2)', 'refs/heads/']).split('\n').filter(b => b && b !== 'main');
+    }
+    // Every branch but the contract's is a room; an archive is `<room>@<genesis8>`.
+    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))
+            .filter(n => ID_RE.test(n.split('@')[0]) && n !== 'main' && n.includes('@') === archived);
+        return names.sort();
+    }
+    // A control record: the room's genesis, or a root commit of Kind: room.
+    isControl(room, sha, author, text) {
+        return sha === room.genesis || (author === ROOT && parse(text, x => this.isRef(x)).kind === 'room');
+    }
+    // The room's branch, oldest first, from its genesis. The last scan of each room is kept and grown by what the tip
+    // added on top of it.
+    scanned = new Map();
+    entries(room, tip) {
+        const last = this.scanned.get(room.genesis);
+        if (last?.tip === tip)
+            return last.entries;
+        const added = last ? this.scan(room, tip, last.tip) : [];
+        const entries = last && added.length && added[0].parent === last.tip ? [...last.entries, ...added] : this.scan(room, tip);
+        const judged = this.judged(room, tip, entries);
+        this.scanned.set(room.genesis, { tip, entries: judged });
+        return judged;
+    }
+    // On a signed hub the branch's verification says which commits are control records, and why the others that are no
+    // valid message are skipped; a commit off the branch's first parents is never a message (remote.ts).
+    judged(room, tip, entries) {
+        if (this.trust !== 'signed' || room.archived)
+            return entries;
+        const b = Remote.branch(this.h, { name: room.name, ref: this.ref(room.name), genesis: room.genesis }, tip);
+        const control = new Set(b.control);
+        return entries.map(e => ({ ...e, control: control.has(e.sha),
+            skipped: control.has(e.sha) || b.authors.has(e.sha) ? undefined : b.skipped.get(e.sha) ?? 'not on the room\'s branch' }));
+    }
+    scan(room, tip, after) {
+        const shas = this.git(['rev-list', '--topo-order', '--reverse', tip, '--not', after ?? `${room.genesis}^@`]).trim().split('\n').filter(Boolean);
+        return Remote.readCommits(this.h, shas).map(c => {
+            const text = c.body.toString('utf8');
+            return { sha: c.sha, parent: c.parents[0], author: c.author, text, control: this.isControl(room, c.sha, c.author, text) };
+        });
+    }
+    room(name) {
+        const ref = this.ref(name);
+        const tip = this.tip(name);
+        if (!tip)
+            return null;
+        const genesis = this.git(['rev-list', '--first-parent', '--reverse', tip, '^refs/heads/main']).split('\n')[0]
+            || this.git(['rev-list', '--first-parent', '--reverse', tip]).split('\n').filter(Boolean).at(-1);
+        const archived = name.includes('@');
+        if (this.trust === 'signed' && !archived && this.h.remoteAlarms?.[ref])
+            fail(`ALARM ${this.h.remoteAlarms[ref]}; room ${name} is quarantined`);
+        const control = this.entries({ name, genesis, archived }, tip).filter(e => e.control).map(e => ({ rev: e.sha, text: e.text }));
+        return { name, archived, head: control.at(-1).rev, genesis, tip, base: this.rev(`${genesis}^`) ?? ZERO, control };
+    }
+    // Control files are read at a control record, never at the branch's tip.
+    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}`;
+        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;
+    }
+    // A control record on top of the branch: the control files come from the last control record, never from the tip,
+    // and the messages' files are kept.
+    updateControl(room, who, text, files) {
+        const kept = [...CONTROL_FILES].flatMap(n => { const c = this.controlFile(room, n); return c === null ? [] : [[n, c]]; });
+        const all = { ...Object.fromEntries(kept), ...files };
+        return this.onTop(room, who, text, Object.entries(all).map(([p, c]) => ({ path: p, content: c, mode: '100644' })), [...CONTROL_FILES]);
+    }
+    refsUnder(prefix) {
+        return this.git(['for-each-ref', '--format=%(refname) %(objectname)', prefix]).split('\n').filter(Boolean).map(l => l.split(' '));
+    }
+    // The branch moves under the archive; its signals stay where they are, on its commits.
+    archiveRoom(room, as) {
+        const tip = this.rev(this.ref(room.name)) ?? fail(`room ${room.name} is gone`);
+        this.git(['update-ref', `refs/archive/${as}`, tip, ZERO]);
+        this.git(['update-ref', '-d', this.ref(room.name), tip]);
+    }
+    // Every ref of the room in one transaction: its branch (or archive), every tag on its commits (signals, heartbeats,
+    // anyone's), what the store keeps under its genesis (pins, evidence) and its unpublished commits. Objects are left to
+    // the repository.
+    deleteRoom(room) {
+        const commits = this.commitsOf(room);
+        const tags = this.git(['for-each-ref', '--format=%(refname) %(objectname) %(*objectname)', 'refs/tags/']).split('\n').filter(Boolean)
+            .map(l => l.split(' ')).filter(([, object, target]) => commits.has(target || object)).map(([ref]) => ref);
+        const kept = this.refsUnder('refs/ringi/').map(([ref]) => ref).filter(ref => {
+            const [, , kind, key] = ref.split('/');
+            return key === room.genesis || (kind === 'unpublished' && commits.has(key));
+        });
+        const refs = [this.ref(room.name), ...tags, ...kept];
+        this.git(['update-ref', '--stdin'], { input: ['start', ...refs.map(r => `delete ${r}`), 'prepare', 'commit', ''].join('\n') });
+    }
+    remote(room) {
+        return { name: room.name, ref: this.ref(room.name), head: room.head, genesis: room.genesis, archived: room.archived };
+    }
+    roster(room) {
+        if (this.trust !== 'signed' || room.archived)
+            return null;
+        const v = Remote.verifyRoom(this.h, this.remote(room));
+        return { members: v.members, signers: v.entries };
+    }
+    // Logs are read at the branch's live tip, as a reader sees the room now.
+    live(room) {
+        const tip = this.tip(room.name);
+        return tip ? this.entries(room, tip).filter(e => !e.control && !e.skipped) : [];
+    }
+    // What a signed hub skips in the room's branch, as alarms; the room reads on without it.
+    alarms(room) {
+        const tip = this.tip(room.name);
+        return tip ? this.entries(room, tip).filter(e => e.skipped).map(e => `commit ${e.sha.slice(0, 12)} by ${e.author || '(none)'}: ${e.skipped}`) : [];
+    }
+    // A commit on the branch's tip, compare-and-swap: when another writer got there first, it is made again on the new tip.
+    onTop(room, who, text, entries, drop = []) {
+        const ref = this.ref(room.name);
+        for (let i = 0; i < 8; i++) {
+            const tip = this.rev(ref) ?? fail(`room ${room.name} is gone`);
+            if (drop.length && this.room(room.name)?.head !== room.head)
+                fail('room control moved while writing; retry the operation');
+            const tree = entries.length || drop.length ? this.tree(`${tip}^{tree}`, entries, drop) : this.git(['rev-parse', `${tip}^{tree}`]).trim();
+            const sha = this.commit(who, text, tree, [tip]);
+            if (this.advance(ref, sha, tip))
+                return sha;
+        }
+        return fail(`room ${room.name} kept moving while writing; retry`);
+    }
+    // Every commit of the room's branch: a signal belongs to the room whose branch holds its message.
+    commitsOf(room) {
+        const tip = this.tip(room.name);
+        return new Set(tip ? this.entries(room, tip).map(e => e.sha) : []);
+    }
+}
+//# sourceMappingURL=branches.js.map

package/target/esm/adapters/transport-git/files.js

@@ -0,0 +1,48 @@
+// files: which files a message carries — the explicit Ringi-Files list, or for records without one the paths its
+// commit adds or changes — and which it refuses.
+import { checkCollisions, checkPath } from '../../core/hub/protocol/files.js';
+import { parse } from '../../core/hub/protocol/index.js';
+import { splitBuf } from './run.js';
+const REGULAR = new Set(['100644', '100755']);
+const RAW = /^:\d{6} (\d{6}) \S+ \S+ ([A-Z])\d*\t(.*)$/;
+const TREE = /^(\d+) \w+ [0-9a-f]+\t(.*)$/s;
+const INVALID = { path: 'Ringi-Files', mode: 'invalid', why: 'expected one JSON array of safe, distinct file paths' };
+// The paths a commit adds or changes over its parent (`git log --raw`).
+const changed = (raw) => raw.split('\n').map(l => RAW.exec(l)).filter((x) => !!x)
+    .filter(([, , status]) => status !== 'D').map(([, mode, , p]) => ({ path: p, mode }));
+// The Ringi-Files list's paths, or null when it is not one JSON array of safe, distinct paths.
+const declaredPaths = (declared) => {
+    try {
+        const paths = JSON.parse(declared[0]);
+        if (declared.length !== 1 || !Array.isArray(paths) || !paths.every(p => typeof p === 'string'))
+            return null;
+        const names = paths.map(checkPath);
+        checkCollisions(names);
+        return new Set(names).size === names.length ? names : null;
+    }
+    catch {
+        return null;
+    }
+};
+// The declared paths as the commit's tree holds them; one the tree lacks is `missing`.
+const inTree = (names, tree) => {
+    const wanted = new Set(names);
+    const found = splitBuf(tree, 0).map(b => TREE.exec(b.toString('utf8'))).filter((x) => !!x)
+        .map(([, mode, p]) => ({ path: p, mode })).filter(f => wanted.has(f.path));
+    for (const f of found)
+        wanted.delete(f.path);
+    return [...found, ...[...wanted].map(p => ({ path: p, mode: 'missing' }))];
+};
+const listed = (declared, sha, lsTree) => {
+    const names = declaredPaths(declared);
+    if (!names)
+        return { all: [], refused: [INVALID] };
+    return { all: names.length ? inTree(names, lsTree(sha)) : [], refused: [] };
+};
+// A message's regular files, and what it refuses: an invalid list, a link, a missing file.
+export const messageFiles = (body, rest, sha, isRef, lsTree) => {
+    const declared = parse(body.toString('utf8'), isRef).trailers['ringi-files'];
+    const { all, refused } = declared ? listed(declared, sha, lsTree) : { all: changed(rest.toString('utf8')), refused: [] };
+    return { files: all.filter(f => REGULAR.has(f.mode)), refused: [...refused, ...all.filter(f => !REGULAR.has(f.mode))] };
+};
+//# sourceMappingURL=files.js.map