@idleware/ringi 0.0.0-stage → 0.1.0

package/target/esm/lib/index.js

@@ -0,0 +1,202 @@
+// lib: helpers that know nothing of ringi: failing, notes, formatting, strict JSON, atomic files, the inter-process
+// lock.
+import fs from 'node:fs';
+export class Fail extends Error {
+}
+export const fail = (msg) => { throw new Fail(msg); };
+export const note = (s) => { process.stderr.write(`ringi: ${s}\n`); };
+export const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+export const when = (t) => `${new Date(t * 1000).toISOString().slice(0, 16).replace('T', ' ')}Z`;
+export const bytes = (n) => n < 1024 ? `${n} B` : n < 1 << 20 ? `${(n / 1024).toFixed(1)} KB` : `${(n / (1 << 20)).toFixed(1)} MB`;
+export const short = (id) => id.slice(0, 12);
+export const stamp = () => new Date().toISOString().slice(0, 19) + 'Z';
+export const words = (v) => v ? String(v).split(/[\s,]+/).filter(Boolean) : [];
+export const errno = (e) => e?.code;
+// --- JSON files ---
+export const writeJsonAtomic = (file, v) => {
+    const tmp = `${file}.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(v, null, 2));
+    fs.renameSync(tmp, file);
+};
+// JSON.parse silently keeps the last of duplicate fields; for contracts and authority that hides a second value.
+// This parser validates the structure first and refuses duplicates.
+export const strictJson = (text, label = 'JSON') => {
+    let at = 0;
+    const ws = () => { while (at < text.length && /\s/.test(text[at]))
+        at++; };
+    const bad = () => fail(`${label}: malformed or duplicate JSON field at ${at}`);
+    const str = () => {
+        const start = at++;
+        while (at < text.length && text[at] !== '"')
+            at += text[at] === '\\' ? 2 : 1;
+        if (text[at++] !== '"')
+            bad();
+        try {
+            return JSON.parse(text.slice(start, at));
+        }
+        catch {
+            return bad();
+        }
+    };
+    const value = () => {
+        ws();
+        const c = text[at];
+        if (c === '{') {
+            at++;
+            ws();
+            const keys = new Set();
+            if (text[at] === '}') {
+                at++;
+                return;
+            }
+            for (;;) {
+                ws();
+                if (text[at] !== '"')
+                    bad();
+                const k = str();
+                if (keys.has(k))
+                    bad();
+                keys.add(k);
+                ws();
+                if (text[at++] !== ':')
+                    bad();
+                value();
+                ws();
+                const n = text[at++];
+                if (n === '}')
+                    return;
+                if (n !== ',')
+                    bad();
+            }
+        }
+        if (c === '[') {
+            at++;
+            ws();
+            if (text[at] === ']') {
+                at++;
+                return;
+            }
+            for (;;) {
+                value();
+                ws();
+                const n = text[at++];
+                if (n === ']')
+                    return;
+                if (n !== ',')
+                    bad();
+            }
+        }
+        if (c === '"') {
+            str();
+            return;
+        }
+        const m = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(at));
+        if (!m)
+            bad();
+        at += m[0].length;
+    };
+    value();
+    ws();
+    if (at !== text.length)
+        bad();
+    return JSON.parse(text);
+};
+// --- the lock ---
+// A lock is a file holding its owner (pid and a random token), created by hard-linking a file already written: it
+// never exists without its owner and never replaces another lock. All acquisitions and the recovery of a dead
+// owner's lock pass one gate, so two contenders cannot both clear a lock just taken by a third. A lock is taken from
+// someone else only when that owner's process is gone, never by age; an unreadable owner is never taken over; only
+// the owner releases it. A gate abandoned by a dead process needs the operator: recovering the recoverer would need
+// yet another gate.
+const ownerAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return errno(e) !== 'ESRCH';
+    }
+};
+const ownerOf = (f) => {
+    try {
+        return fs.readFileSync(f, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+const deadOwner = (t) => {
+    const pid = Number(String(t ?? '').split('.')[0]);
+    return Number.isInteger(pid) && pid > 0 && !ownerAlive(pid);
+};
+const claim = (f, token) => {
+    const tmp = `${f}.${token}.tmp`;
+    fs.writeFileSync(tmp, token, { flag: 'wx', mode: 0o600 });
+    try {
+        fs.linkSync(tmp, f);
+        return true;
+    }
+    catch (e) {
+        if (errno(e) === 'EEXIST')
+            return false;
+        throw e;
+    }
+    finally {
+        fs.rmSync(tmp, { force: true });
+    }
+};
+const release = (f, token) => {
+    if (ownerOf(f) === token)
+        fs.rmSync(f, { force: true });
+};
+const lockWait = new Int32Array(new SharedArrayBuffer(4));
+export const locked = (file, fn, timeout = 120000) => {
+    const token = `${process.pid}.${Math.random().toString(36).slice(2)}`;
+    const gate = `${file}.recover`;
+    const until = Date.now() + timeout;
+    for (;;) {
+        if (claim(gate, token)) {
+            try {
+                if (deadOwner(ownerOf(file)))
+                    fs.rmSync(file, { force: true });
+                if (claim(file, token))
+                    break;
+            }
+            finally {
+                release(gate, token);
+            }
+        }
+        else if (deadOwner(ownerOf(gate))) {
+            fail(`${gate} was abandoned; if no ringi process runs, remove it`);
+        }
+        if (Date.now() >= until)
+            fail(`${file} is held by another process or an unknown owner; if no ringi process runs, remove it`);
+        Atomics.wait(lockWait, 0, 0, 25);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        release(file, token);
+    }
+};
+// --- writing where a sandbox may refuse ---
+export const SANDBOX = /Operation not permitted|Permission denied|Read-only file system|EPERM|EACCES|EROFS/;
+export const cannotWrite = (where, detail) => fail(`cannot write ${where}: ${detail}
+  An agent in a sandbox: re-run this same command with your host's sandbox escalation; the operator approves it.
+  The operator can instead add ${where} to the host's writable roots (Codex: [sandbox_workspace_write] writable_roots
+  in ~/.codex/config.toml) or point RINGI_HOME at a location the host already allows.`);
+export const guardWrite = (where, fn) => {
+    try {
+        return fn();
+    }
+    catch (e) {
+        if (e instanceof Fail)
+            throw e;
+        if (['EPERM', 'EACCES', 'EROFS'].includes(errno(e) ?? ''))
+            cannotWrite(where, `${errno(e)} on ${e.path ?? 'a file'}`);
+        throw e;
+    }
+};
+export const mkdirIn = (where, d) => { guardWrite(where, () => fs.mkdirSync(d, { recursive: true, mode: 0o700 })); };
+//# sourceMappingURL=index.js.map

package/target/esm/protocol/files.js

@@ -0,0 +1,19 @@
+// files: the paths a message may attach (core-1 §4).
+import { fail } from '../lib/index.js';
+export const CC_RE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/;
+const COMPONENT_BAD = (c) => !c || c === '.' || c === '..' || c === '.git' || Buffer.byteLength(c) > 255 || CC_RE.test(c) || /[\n\t]/.test(c);
+export const checkPath = (p) => {
+    if (p.startsWith('/') || p.split('/').some(COMPONENT_BAD))
+        fail(`bad file path ${p}`);
+    return p;
+};
+export const checkCollisions = (paths) => {
+    const seen = new Map();
+    for (const p of paths) {
+        const k = p.normalize('NFC').toLowerCase();
+        if (seen.has(k) && seen.get(k) !== p)
+            fail(`file paths collide: ${seen.get(k)} and ${p}`);
+        seen.set(k, p);
+    }
+};
+//# sourceMappingURL=files.js.map

package/target/esm/protocol/index.js

@@ -0,0 +1,217 @@
+// protocol: the message protocol, docs/spec/core-1.md (§3, §5–§7), independent of storage and of any task model. A store
+// turns its records into messages and hands them here: text, threads, inboxes and waking live in this file. What a
+// task is, which states it has and who may move it, is a profile (profile.ts), not part of the protocol.
+import { CC_RE } from './files.js';
+import { fail } from '../lib/index.js';
+export const ID_RE = /^(?=.{1,64}$)[a-z0-9]+(?:[._-][a-z0-9]+)*(?<!\.lock)$/;
+export const TOKEN_RE = /^[a-z][a-z0-9-]*$/;
+export const HOP_RE = /^(?:0|[1-9]\d{0,5})$/;
+export const TRAILER_RE = /^([A-Za-z][A-Za-z0-9-]*):[ \t]*(.*)$/;
+export const TEXT_MAX = 64 * 1024;
+// Trailers the protocol itself interprets; any other trailer belongs to an extension or a profile.
+export const KNOWN = new Set(['to', 're', 'kind', 'state', 'hop', 'assign', 'roles']);
+export const HEARTBEATS = new Set(['ping', 'pong']);
+// Kinds that are bookkeeping, never delivered to an inbox: heartbeats, usage receipts, cards, room records.
+export const HIDDEN = new Set(['ping', 'pong', 'usage', 'card', 'room']);
+export const one = (m, k) => m.trailers[k]?.[0] ?? null;
+// --- text (§3) ---
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+// Invalid text is dangerous bytes: readers treat the message as absent.
+export const decodeText = (buf) => {
+    let s;
+    try {
+        s = utf8.decode(buf);
+    }
+    catch {
+        return { invalid: 'not valid UTF-8' };
+    }
+    s = s.replace(/\r\n/g, '\n');
+    if (/\r/.test(s))
+        return { invalid: 'a CR not followed by LF' };
+    if (CC_RE.test(s))
+        return { invalid: 'control characters in the text' };
+    return { text: s };
+};
+// Parses well-formed and malformed text alike; `bad` names why a message routes nowhere. `isRef` is the store's
+// grammar for message ids in `Re`.
+export const parse = (raw, isRef) => {
+    const text = raw.replace(/\r\n/g, '\n').trimEnd();
+    const cut = text.lastIndexOf('\n\n');
+    const tail = cut < 0 ? [] : text.slice(cut + 2).split('\n');
+    const has = tail.length > 0 && tail.every(l => TRAILER_RE.test(l));
+    const trailers = {};
+    if (has) {
+        for (const l of tail) {
+            const [, k, v] = TRAILER_RE.exec(l);
+            const key = k.toLowerCase();
+            trailers[key] = [...(trailers[key] ?? []), v.trim()];
+        }
+    }
+    const head = has ? text.slice(0, cut) : text;
+    const nl = head.indexOf('\n');
+    const subject = (nl < 0 ? head : head.slice(0, nl)).trim();
+    const bad = [...KNOWN].filter(k => (trailers[k]?.length ?? 0) > 1).map(k => `duplicate ${k}`);
+    const get = (k) => trailers[k]?.[0] ?? null;
+    const ids = (v) => v === null ? null : [...new Set(v.split(',').map(x => x.trim()))];
+    const to = get('to') === '*' ? ['*'] : ids(get('to'));
+    const assign = ids(get('assign'));
+    // Roles: `<id>=<label>, …`; the label `none` clears one.
+    const pairs = get('roles') === null ? null : get('roles').split(',').map(x => x.trim().split('=').map(y => y.trim()));
+    if (pairs && !pairs.every(p => p.length === 2 && ID_RE.test(p[0]) && TOKEN_RE.test(p[1])))
+        bad.push('malformed Roles');
+    if (!subject)
+        bad.push('empty subject');
+    if (Buffer.byteLength(raw) > TEXT_MAX)
+        bad.push('text over 64 KiB');
+    if (!has)
+        bad.push('no trailer block');
+    else if (!to)
+        bad.push('no To');
+    else if (to[0] !== '*' && !to.every(x => ID_RE.test(x)))
+        bad.push('malformed To');
+    if (assign && !assign.every(x => ID_RE.test(x)))
+        bad.push('malformed Assign');
+    if (get('re') !== null && !isRef(get('re')))
+        bad.push('malformed Re');
+    if (get('hop') !== null && !HOP_RE.test(get('hop')))
+        bad.push('malformed Hop');
+    // A state is a token; whether the room's profile knows it is the store's check.
+    if (get('state') !== null && !TOKEN_RE.test(get('state')))
+        bad.push('malformed State');
+    if (get('kind') !== null && !TOKEN_RE.test(get('kind')))
+        bad.push('malformed Kind');
+    const ok = !bad.length;
+    return {
+        subject,
+        body: nl < 0 ? '' : head.slice(nl + 1).replace(/^\n+/, '').trimEnd(),
+        // A malformed message is read as if it had no trailers.
+        to: ok ? to : [],
+        assign: ok ? assign : null,
+        roles: ok && pairs ? Object.fromEntries(pairs) : null,
+        re: ok ? get('re') : null,
+        kind: ok ? get('kind') : null,
+        state: ok ? get('state') : null,
+        hop: ok && get('hop') !== null ? Number(get('hop')) : 0,
+        bad: bad.join(', ') || null,
+        trailers,
+    };
+};
+export const compose = (text, trailers) => `${text}\n\n${trailers.filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join('\n')}\n`;
+// A client refuses to write what readers would drop or ignore (§3).
+export const checkOutgoing = (text, isRef) => {
+    const d = decodeText(Buffer.from(text));
+    if (d.invalid !== undefined)
+        fail(`refusing to send: ${d.invalid}`);
+    const m = parse(d.text, isRef);
+    if (m.bad)
+        fail(`refusing to send a malformed message: ${m.bad}`);
+    return m;
+};
+// --- threads (§5) ---
+// Resolves Re and computes effective hops. Invalid messages are absent: a Re naming one does not resolve.
+export const link = (logs) => {
+    const all = new Map();
+    for (const msgs of logs.values())
+        for (const m of msgs)
+            if (!m.invalid)
+                all.set(m.id, m);
+    for (const m of all.values())
+        m.reId = m.re && all.has(m.re) ? m.re : null;
+    const eff = new Map();
+    for (const m of all.values()) {
+        const chain = [];
+        for (let x = m; x && !eff.has(x.id) && chain.length < 100000; x = x.reId ? all.get(x.reId) : undefined)
+            chain.push(x);
+        for (let i = chain.length - 1; i >= 0; i--) {
+            const c = chain[i];
+            eff.set(c.id, Math.max(c.hop, c.reId ? eff.get(c.reId) + 1 : c.re ? 1 : 0));
+        }
+        m.hopEff = eff.get(m.id);
+    }
+    return all;
+};
+// Kahn's order: the answered message before the answer, earlier before later within one log; among the ready ones,
+// the smallest (time, id) goes first.
+export const ordered = (list) => {
+    const byId = new Map(list.map(m => [m.id, m]));
+    const next = new Map(list.map(m => [m.id, []]));
+    const indeg = new Map(list.map(m => [m.id, 0]));
+    const edge = (a, b) => {
+        next.get(a.id).push(b);
+        indeg.set(b.id, indeg.get(b.id) + 1);
+    };
+    const last = new Map();
+    for (const m of [...list].sort((a, b) => a.seq - b.seq)) {
+        if (last.has(m.from))
+            edge(last.get(m.from), m);
+        last.set(m.from, m);
+        if (m.reId && byId.has(m.reId))
+            edge(byId.get(m.reId), m);
+    }
+    const ready = list.filter(m => !indeg.get(m.id));
+    const res = [];
+    while (ready.length) {
+        ready.sort((a, b) => a.time - b.time || (a.id < b.id ? -1 : 1));
+        const m = ready.shift();
+        res.push(m);
+        for (const n of next.get(m.id)) {
+            indeg.set(n.id, indeg.get(n.id) - 1);
+            if (!indeg.get(n.id))
+                ready.push(n);
+        }
+    }
+    return res;
+};
+export const chainHas = (all, m, top) => {
+    for (let x = m, i = 0; x && i < 10000; x = x.reId ? all.get(x.reId) : undefined, i++)
+        if (x === top)
+            return true;
+    return false;
+};
+export const rootOf = (all, m) => {
+    let x = m;
+    for (let i = 0; x.reId && all.has(x.reId) && i < 10000; i++)
+        x = all.get(x.reId);
+    return x;
+};
+export const under = (all, top) => ordered([...all.values()].filter(m => chainHas(all, m, top)));
+export const lookup = (all, ref) => {
+    const key = String(ref ?? '').toLowerCase();
+    if (all.has(key))
+        return all.get(key);
+    const hits = key.length >= 4 ? [...all.keys()].filter(k => k.startsWith(key)) : [];
+    if (hits.length === 1)
+        return all.get(hits[0]);
+    return fail(hits.length ? `ambiguous message id ${ref}` : `unknown message ${ref}`);
+};
+// --- reading (§6) and waking (§7) ---
+// Delivered: well-formed, not a hidden kind, addressed to `id` by name or `*`.
+export const visible = (m, id, hidden) => !m.invalid && !m.bad && !(m.kind && hidden.has(m.kind)) && (m.to.includes(id) || m.to.includes('*'));
+// Wakes: only a direct address. Broadcasts are read when the agent is awake for another reason.
+export const wakes = (m, id, hidden) => visible(m, id, hidden) && m.to.includes(id);
+// Messages for `id` after the per-log cursors; cursors advance only past what was shown.
+export const unread = (logs, id, cursors, limit = Infinity, hidden) => {
+    const fresh = [];
+    for (const [log, msgs] of logs) {
+        if (log === id)
+            continue;
+        const at = msgs.findIndex(m => m.id === cursors[log]);
+        fresh.push(...msgs.slice(at + 1).filter(m => visible(m, id, hidden)));
+    }
+    const queue = ordered(fresh);
+    const shown = queue.slice(0, limit);
+    const seen = new Set(shown.map(m => m.id));
+    const next = { ...cursors };
+    for (const [log, msgs] of logs) {
+        if (log === id)
+            continue;
+        const at = msgs.findIndex(m => m.id === cursors[log]);
+        for (const m of msgs.slice(at + 1)) {
+            if (visible(m, id, hidden) && !seen.has(m.id))
+                break;
+            next[log] = m.id;
+        }
+    }
+    return { msgs: shown, rest: queue.length - shown.length, cursors: next };
+};
+//# sourceMappingURL=index.js.map

package/target/esm/runtime/reader.js

@@ -0,0 +1,64 @@
+// reader: what one reader on this machine accepted of a room: heads, signals, cursors, alarms. Only history that
+// extends what it accepted before, verified by the store, is delivered (docs/spec/hub-1.md, Trust).
+import path from 'node:path';
+import * as Signals from '../domain/signals.js';
+import { HOME, locked, readJson, writeJson } from '../home/index.js';
+import { toMessage } from '../hub/index.js';
+import { fail, note, short } from '../lib/index.js';
+import { link } from '../protocol/index.js';
+export const readerFile = (R, reader) => path.join(HOME, 'readers', R.hub.name, R.genesis, `${reader}.json`);
+export const readerLock = (R, reader, fn) => locked(`reader-${R.hub.name}-${R.genesis.slice(0, 12)}-${reader}`, fn);
+export const loadState = (R, reader) => readJson(readerFile(R, reader), {});
+export const saveState = (R, reader, st) => writeJson(readerFile(R, reader), st);
+// Every log must keep extending what this reader accepted, and the store must verify it (a signed store: every entry
+// signed by the key the room admitted). A log that lost, rewrote or forked accepted history, or fails verification,
+// is quarantined: withheld, its accepted head pinned as evidence. Only `ringi forget` by the operator accepts a new
+// baseline.
+export const loadRoomUnlocked = (R, reader) => {
+    const st = loadState(R, reader);
+    const store = R.hub.store;
+    if (st.control && !store.extends(st.control, R.head)) {
+        fail(`ALARM room ${R.name}: its control history was rewritten (accepted ${short(st.control)}, now ${short(R.head)}). Nothing is delivered; the operator decides`);
+    }
+    st.control = R.head;
+    st.heads ??= {};
+    const alarms = [];
+    const logs = new Map();
+    for (const id of new Set([...store.logIds(R.s), ...Object.keys(st.heads)])) {
+        const cur = store.logHead(R.s, id);
+        const acc = st.heads[id];
+        const why = !cur ? `log ${id} was deleted after ${short(acc)}`
+            : acc && !store.extends(acc, cur) ? `log ${id} was rewritten: ${short(cur)} does not extend the accepted ${short(acc)}`
+                : !store.extends(R.genesis, cur) ? `log ${id} does not descend from the room's genesis`
+                    : store.verifyLog(R.s, id, cur);
+        if (why) {
+            alarms.push(why.startsWith('log ') ? why : `log ${id}: ${why}`);
+            continue;
+        }
+        if (acc !== cur) {
+            st.heads[id] = cur;
+            store.pin(R.s, reader, id, cur);
+        }
+        logs.set(id, store.messages(R.s, id, cur).map((x, seq) => toMessage(R, id, x, seq)));
+    }
+    const records = store.signals(R.s);
+    const checked = Signals.check(R, link(logs), records);
+    const signalPins = Signals.pins(records, checked, st.signals);
+    st.signals = signalPins.accepted;
+    alarms.push(...signalPins.alarms, ...checked.filter(x => !x.ok).map(x => `signal ${x.ref}: ${x.why}`));
+    const reported = new Set(st.alarms ?? []);
+    for (const a of alarms)
+        if (!reported.has(a))
+            note(`ALARM ${a}; ${a.startsWith('signal ')
+                ? 'the messages stay the truth; the author restores a missing signal with ringi agent signals --repair'
+                : `it is quarantined and withheld. Restore it, or the operator runs ringi forget ${R.name}/<log>`}`);
+    st.alarms = alarms;
+    saveState(R, reader, st);
+    return { logs, st };
+};
+export const loadRoom = (R, reader) => readerLock(R, reader, () => loadRoomUnlocked(R, reader));
+export const linked = (R, reader) => {
+    const { logs } = loadRoom(R, reader);
+    return { logs, all: link(logs) };
+};
+//# sourceMappingURL=reader.js.map

package/target/esm/runtime/session.js

@@ -0,0 +1,112 @@
+// session: which chat is which, and which seat it holds. A seat is one (hub, room genesis, agent); it ends only with
+// leave or the operator's explicit takeover. Every agent command passes `bound()` first.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { HOME, guard, locked, readJson, writeJson } from '../home/index.js';
+import { openHub, openRoom, roomNames } from '../hub/index.js';
+import { errno, fail, stamp } from '../lib/index.js';
+export const LEASE = 60 * 60 * 1000;
+const detectProduct = () => {
+    const env = process.env;
+    if (env.CLAUDECODE === '1' || env.CLAUDE_CODE_SESSION_ID)
+        return 'claude';
+    if (Object.keys(env).some(k => k.startsWith('CODEX_')))
+        return 'codex';
+    if (Object.keys(env).some(k => k.startsWith('CURSOR_')))
+        return 'cursor';
+    return null;
+};
+const ancestry = () => {
+    let pid = process.ppid;
+    for (let 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)
+            return null;
+        const comm = path.basename(m[2].trim()).toLowerCase();
+        if (/^(claude|codex|cursor|cursor-agent)$/.test(comm))
+            return { pid, product: comm.replace('-agent', '') };
+        pid = Number(m[1]);
+    }
+    return null;
+};
+// A chat is known by a stable handle: RINGI_SESSION, else the chat id the UI exposes, else the UI process as a last
+// resort (ps may be denied in a sandbox; then RINGI_SESSION is required).
+export const whoAmI = () => {
+    const env = process.env;
+    const product = detectProduct();
+    if (env.RINGI_SESSION)
+        return { handle: `env:${env.RINGI_SESSION}`, product, pid: null };
+    if (env.CLAUDE_CODE_SESSION_ID)
+        return { handle: `claude:${env.CLAUDE_CODE_SESSION_ID}`, product: 'claude', pid: Number(env.CLAUDE_PID) || null };
+    const a = ancestry() ?? fail('cannot tell which session this is: set RINGI_SESSION to a stable id of this chat (for Codex: its thread id) on every ringi command');
+    return { handle: `pid:${a.pid}`, product: product ?? a.product, pid: a.pid };
+};
+const sessionsDir = () => path.join(HOME, 'sessions');
+const sessionFile = (handle) => path.join(sessionsDir(), `${handle.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 100)}-${crypto.createHash('sha256').update(handle).digest('hex').slice(0, 10)}.json`);
+export const allSessions = () => {
+    let files = [];
+    try {
+        files = fs.readdirSync(sessionsDir()).filter(f => f.endsWith('.json'));
+    }
+    catch { }
+    return files.map(f => readJson(path.join(sessionsDir(), f), null)).filter((s) => !!s?.handle);
+};
+export const readSession = (handle) => {
+    const s = readJson(sessionFile(handle), null);
+    return s?.handle === handle ? s : null;
+};
+export const saveSession = (s) => writeJson(sessionFile(s.handle), s);
+export const dropSession = (handle) => { guard(() => fs.rmSync(sessionFile(handle), { force: true })); };
+export const pidAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return errno(e) === 'EPERM';
+    }
+};
+// active: in use within the lease by a living process; stopped: paused by the operator; gone: neither. A gone or
+// stopped binding keeps its seat and scope. A watcher is alive exactly while its process is: a run may outlast any
+// lease.
+export const liveness = (s) => s.state === 'stopped' ? 'stopped'
+    : s.product === 'watch' ? (s.pid && pidAlive(s.pid) ? 'active' : 'gone')
+        : Date.now() - Date.parse(s.lastSeen) < LEASE && (!s.pid || pidAlive(s.pid)) ? 'active' : 'gone';
+export const seatHolder = (hub, genesis, agent, except) => allSessions().find(s => s.hub === hub && s.genesis === genesis && s.agent === agent && s.handle !== except);
+// An explicit chat-to-watch handoff remembers only that chat; it never selects another chat's seat.
+export const ownSession = (handle) => readSession(handle)
+    ?? allSessions().find(s => s.product === 'watch' && s.takenFrom === handle) ?? null;
+// The binding, checked on every agent command: joined, not stopped, room alive and the same room, still a member.
+export const bound = () => {
+    const me = whoAmI();
+    const s = readSession(me.handle) ?? fail(`this session is not in a room. Take part only when the operator says so in this chat:
+  "join <room> as <id>" runs ringi join local <room> --as <id> --scope "<what they delegate>";
+  after a restart, "continue" runs ringi continue.`);
+    if (s.state === 'stopped')
+        fail('this session is stopped: the operator paused it. It reacts to nothing until the operator says "continue" (ringi continue)');
+    const H = openHub(s.hub);
+    const R = openRoom(H, s.room, { quiet: true });
+    if (!R || R.genesis !== s.genesis) {
+        const gone = roomNames(H, true).find(a => a === `${s.room}@${s.genesis.slice(0, 8)}`);
+        if (gone)
+            fail(`room ${s.room} was archived as ${gone}; nothing more happens there. Tell the operator`);
+        fail(R ? `room ${s.room} was deleted and created again; this session's binding ended with the old room. The operator joins it anew` : `room ${s.room} no longer exists in hub ${s.hub}. Tell the operator`);
+    }
+    if (!R.members[s.agent])
+        fail(`${s.agent} was removed from room ${s.room}; returning needs a fresh join by the operator`);
+    locked('sessions', () => {
+        const cur = readSession(me.handle) ?? fail('this session lost its seat');
+        if (cur.state !== 'active' || cur.genesis !== s.genesis || cur.agent !== s.agent)
+            fail('this session was stopped or its seat changed');
+        saveSession({ ...cur, lastSeen: stamp(), pid: me.pid ?? cur.pid });
+    });
+    return { s, H, R: R, me: s.agent };
+};
+export const parseSelector = (sel) => {
+    const m = /^(?:([a-z0-9._-]+):)?([^/]+)\/([^/]+)$/.exec(sel ?? '');
+    return m ? { hub: m[1] ?? null, room: m[2], agent: m[3] } : fail('a session is named <room>/<agent> or <hub>:<room>/<agent>');
+};
+//# sourceMappingURL=session.js.map