@idleware/ringi 0.3.0 → 0.5.0

package/README.md

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

package/package.json

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

package/src/main/resources/skill/ringi/SKILL.md

@@ -22,6 +22,7 @@ With no words: `ringi agent whoami` if this chat is joined; otherwise say how th
 Several chats may be open in a project. Take part only if the operator says so in this chat. Their words map to session commands:
 
 - *"join fix-badge as codex; review tasks from claude; no commits"* → `ringi join local fix-badge --as codex --scope "review tasks from claude; no commits"`. Record what they delegate in `--scope`.
+- A room may have a quorum (`ringi room create … --quorum 2`; `--quorum 1`: start at once). While join or inbox says `waiting:`, do nothing and end the turn. When it says `started:`, take your first turn right away on what it shows (open work, inbox), without asking the operator to confirm anything: with no scope, the room's work for you is yours, and you agree the split with the other members yourselves. Still ask before commits or pushes, publishing, outside accounts or spending that the scope does not cover. The same after *"continue"*.
 - *"continue"* (after a restart, or a pause) → `ringi continue`. If it lists candidates, ask the operator which one, then `ringi continue <room>/<agent>`.
 - *"stop"* (the operator leaves for a while) → `ringi stop`. You keep your seat and react to nothing.
 - *"leave"* → `ringi leave`.
@@ -34,15 +35,17 @@ Everything you do as an agent goes through `ringi agent`, always in your own roo
 
 ```sh
 ringi agent inbox                                   # what is new for you; marks it seen
-ringi agent reply <id> -m "Done: tests pass" --state completed --attach report.md
+ringi agent add report.md patch.diff:files/fix.diff  # stage files for your next message, like git add
+ringi agent reply <id> -m "Done: tests pass" --state completed   # carries what you staged (or --attach …)
 ringi agent send --to claude --task -m "Review the parser" -m "acceptance: …"
 ringi agent tasks | proposals | grants | signals | profile | thread <id> | read <id> | cat <id> <path>
 ringi agent whoami                                  # room, scope, members
 ```
 
-- The first `-m` is the subject; the rest is the body; anything long goes into files with `--attach`.
+- The first `-m` is the subject; the rest is the body; anything long goes into files.
+- Results and state travel only as attachments: `ringi agent add <file>` takes the file's content now for your next message (`add` alone lists what is staged, `--drop <path>` takes one back), or `--attach` on the message. Read a peer's with `ringi agent cat` / `get`. Never leave drafts or results in the project directory or any shared disk for others to pick up, and never pick them up there: peers may be on other machines, and only the room carries them. Keep your own drafts outside the project.
 - Answer the message you act on (`reply <id>`): only these links order the room.
-- What a piece of work is in your room, its states and who may move it, is the room's **profile**: run `ringi agent profile` once per room before you set states. Do not assume the A2A states; a room may use any. `--task` opens a piece of work of that profile. Results travel as files.
+- What a piece of work is in your room, its states and who may move it, is the room's **profile**: run `ringi agent profile` once per room before you set states. Do not assume the A2A states; a room may use any. `--task` opens a piece of work of that profile.
 - When you start on a piece of work, `ringi agent take <id>`: a mark others see, not a state change. Reading your inbox leaves read marks on what was delivered; `--peek` leaves none.
 - `--roles id=label` labels mean only what the profile's rules say. A label you give in a message authorizes nothing in that same message.
 

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

@@ -7,6 +7,11 @@ export type InboxOptions = {
     peek?: boolean;
     limit?: number;
 };
+export declare const started: ({ R }: Actor) => {
+    quorum: number | null;
+    agents: number;
+    started: boolean;
+};
 export declare const inbox: ({ R, me }: Actor, { peek, limit }?: InboxOptions) => {
     rest: number;
     cursors: {

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

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

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

@@ -3,6 +3,7 @@ import * as Signals from '../domain/signals.ts';
 import type { Room } from '../hub/index.ts';
 import type { Entry } from '../protocol/files.ts';
 import type { All, Message } from '../protocol/index.ts';
+import type { Staged } from '../runtime/reader.ts';
 import type { TaskView } from './view.ts';
 export type Actor = {
     R: Room;
@@ -27,6 +28,10 @@ export type Sent = {
     to: string[];
     files: number;
 };
+export declare const FILE_MAX: number;
+export declare const staged: ({ R, me }: Actor) => Staged[];
+export declare const stage: ({ R, me }: Actor, files: Entry[]) => Staged[];
+export declare const unstage: (a: Actor, paths: string[] | null) => Staged[];
 export declare const send: ({ R, me }: Actor, x: SendInput) => Sent;
 export declare const marks: (R: Room, all: All) => Map<string, Record<string, string[]>>;
 export declare const message: ({ R, me }: Actor, ref: string) => {

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

@@ -12,8 +12,9 @@ export type RoomView = {
 export declare const rooms: (H: Hub, { archived }?: {
     archived?: boolean;
 }) => RoomView[];
-export declare const create: (H: Hub, name: string, { profile }?: {
+export declare const create: (H: Hub, name: string, { profile, quorum }?: {
     profile?: string;
+    quorum?: number;
 }) => {
     profile: string;
 };

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

@@ -5,6 +5,11 @@ export type { Session } from '../runtime/session.ts';
 export declare const briefing: (s: Session) => {
     session: Session;
     actor: import("../runtime/session.ts").Bound;
+    start: {
+        quorum: number | null;
+        agents: number;
+        started: boolean;
+    };
     tasks: import("./view.ts").TaskView[];
     inbox: {
         rest: number;
@@ -35,7 +40,7 @@ export declare const briefing: (s: Session) => {
             hopEff: number;
             files: import("../protocol/index.ts").FileRef[];
         }[];
-    };
+    } | null;
 };
 export type JoinInput = {
     hub: string;

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

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

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

@@ -1,6 +1,8 @@
 import type { TaskView } from '../app/view.ts';
 import type { Opts } from './args.ts';
 import type { Ctx } from './context.ts';
+import type { Session } from '../app/session.ts';
+export declare const add: (a: Ctx, o: Opts) => void;
 export declare const send: (a: Ctx, o: Opts) => void;
 export declare const reply: (a: Ctx, o: Opts) => void;
 export declare const read: (a: Ctx, o: Opts) => void;
@@ -18,3 +20,8 @@ export declare const stamp_: (a: Ctx, o: Opts) => void;
 export declare const decide: (a: Ctx, o: Opts) => void;
 export declare const proposals: (a: Ctx, o: Opts) => void;
 export declare const grants: (a: Ctx, o: Opts) => void;
+export declare const scopeLine: (s: Session, quorum?: boolean) => string;
+export declare const waiting: (room: string, st: {
+    quorum: number | null;
+    agents: number;
+}) => string;

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

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

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

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

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

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

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

@@ -39,6 +39,12 @@ export type Room = {
     authorityAt: D.AuthorityAt;
     profile: Profile;
     members: Record<string, Member>;
+    quorum: number | null;
+};
+export declare const start: (R: Pick<Room, 'members' | 'quorum'>) => {
+    quorum: number | null;
+    agents: number;
+    started: boolean;
 };
 export declare const hubNames: () => string[];
 export declare const createHub: (name: string, { signed, url }?: {

package/target/dts/protocol/files.d.ts

@@ -3,6 +3,7 @@ export type Entry = {
     path: string;
     file?: string;
     content?: string;
+    blob?: string;
     mode: string;
 };
 export declare const checkPath: (p: string) => string;

package/target/dts/runtime/reader.d.ts

@@ -15,6 +15,13 @@ export type ReaderState = {
     runs?: number[];
     exhausted?: Record<string, boolean>;
     signals?: Record<string, string>;
+    staged?: Staged[];
+};
+export type Staged = {
+    path: string;
+    blob: string;
+    mode: string;
+    size: number;
 };
 export declare const readerFile: (R: Room, reader: string) => string;
 export declare const readerLock: <T>(R: Room, reader: string, fn: () => T) => T;

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

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

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

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

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

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

package/target/esm/app/agent.js

@@ -1,5 +1,5 @@
 // Agent operations return data; the runtime owns readers, seats and headless turns.
-import { HIDDEN, append, pongText, withSizes } from '../hub/index.js';
+import { HIDDEN, append, pongText, start, withSizes } from '../hub/index.js';
 import * as Signals from '../hub/signals.js';
 import { fail, sleep } from '../lib/index.js';
 import { ID_RE, checkOutgoing, compose, link, lookup, unread } from '../protocol/index.js';
@@ -8,6 +8,8 @@ import { bound } from '../runtime/session.js';
 import { isRef } from './room.js';
 export { bound } from '../runtime/session.js';
 export { watch } from '../runtime/watch.js';
+// Whether the agent's room has its quorum and started its work; a room that has not is not read.
+export const started = ({ R }) => start(R);
 export const inbox = ({ R, me }, { peek = false, limit = 20 } = {}) => {
     if (!Number.isSafeInteger(limit) || limit < 1)
         fail('inbox limit must be a positive integer');

package/target/esm/app/heartbeat.js

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

package/target/esm/app/room.js

@@ -1,5 +1,6 @@
 // room: what any participant (the operator or an agent) does in a room: write messages and read them, follow work,
 // check signals. Each operation takes who acts and typed input, and returns data; interfaces print it.
+import fs from 'node:fs';
 import * as D from '../domain/decisions.js';
 import { isOpen, tasksIn } from '../domain/profiles.js';
 import * as Signals from '../domain/signals.js';
@@ -12,6 +13,51 @@ import { ID_RE, TOKEN_RE, checkOutgoing, compose, link, lookup, ordered, rootOf,
 import { linked, loadRoomUnlocked, loadState, readerLock, saveState } from '../runtime/reader.js';
 import { taskView } from './view.js';
 export const isRef = (R) => (x) => R.hub.store.isRef(x);
+// Staging, like git's index: add takes a file's content into the store now, and the actor's next message carries it,
+// whatever happens to the file meanwhile. Results and state travel only so, never through a shared directory. The store
+// keeps staged contents reachable (`retain`); it grows before the list does and shrinks after, so a crash in between
+// leaks an object rather than loses one.
+export const FILE_MAX = 64 << 20;
+const tooBig = (path, size) => size > FILE_MAX && fail(`${path} is ${Math.ceil(size / (1 << 20))} MiB; an attachment is at most ${FILE_MAX >> 20} MiB`);
+// What retain keeps: each staged content once, named by its id, so two snapshots of one path both stay.
+const kept = (all) => [...new Set(all.map(s => s.blob))].map(blob => ({ path: blob, blob, mode: '100644' }));
+export const staged = ({ R, me }) => loadState(R, me).staged ?? [];
+export const stage = ({ R, me }, files) => {
+    const taken = files.map(e => {
+        if (!e.file)
+            fail(`${e.path}: add takes files`);
+        tooBig(e.path, fs.statSync(e.file).size);
+        const b = R.hub.store.blob(e.file);
+        tooBig(e.path, b.size);
+        return { path: e.path, blob: b.id, mode: e.mode, size: b.size };
+    });
+    return readerLock(R, me, () => {
+        const st = loadState(R, me);
+        const next = new Map((st.staged ?? []).map(s => [s.path, s]));
+        for (const s of taken)
+            next.set(s.path, s);
+        const all = [...next.values()];
+        checkCollisions(all.map(s => s.path));
+        R.hub.store.retain(R.s, me, kept([...all, ...st.staged ?? []]));
+        saveState(R, me, { ...st, staged: all });
+        R.hub.store.retain(R.s, me, kept(all));
+        return all;
+    });
+};
+const shrink = ({ R, me }, keep) => {
+    const st = loadState(R, me);
+    const left = (st.staged ?? []).filter(keep);
+    saveState(R, me, { ...st, staged: left });
+    R.hub.store.retain(R.s, me, kept(left));
+    return left;
+};
+// Unstages the given paths, or everything.
+export const unstage = (a, paths) => readerLock(a.R, a.me, () => {
+    const missing = (paths ?? []).filter(p => !staged(a).some(s => s.path === p));
+    if (missing.length)
+        fail(`not staged: ${missing.join(', ')}`);
+    return shrink(a, s => paths !== null && !paths.includes(s.path));
+});
 // A message from the actor. The operator may omit `to`: the room, or the assignees when there are any.
 export const send = ({ R, me }, x) => {
     const P = R.profile;
@@ -50,7 +96,13 @@ export const send = ({ R, me }, x) => {
             fail(`grant ${short(g.id)} was revoked`);
         grant = g.id;
     }
-    const entries = x.files ?? [];
+    // What the actor staged goes along, an explicit attachment of the same path in its place.
+    const stagedNow = staged({ R, me }), explicit = x.files ?? [];
+    for (const e of explicit)
+        if (e.file)
+            tooBig(e.path, fs.statSync(e.file).size);
+    const named = new Set(explicit.map(e => e.path));
+    const entries = [...stagedNow.filter(s => !named.has(s.path)).map(s => ({ path: s.path, blob: s.blob, mode: s.mode })), ...explicit];
     checkCollisions(entries.map(e => e.path));
     const text = compose(x.text, [
         ['To', to.join(', ')], ['Re', re?.id], ['Kind', x.task && P.opens], ['State', x.state], ['Assign', assign?.join(', ')],
@@ -58,6 +110,8 @@ export const send = ({ R, me }, x) => {
     ]);
     checkOutgoing(text, isRef(R));
     const id = append(R, me, text, entries);
+    if (stagedNow.length)
+        readerLock(R, me, () => shrink({ R, me }, s => !stagedNow.some(t => t.path === s.path && t.blob === s.blob)));
     if (to.length === 1 && to[0] === '*')
         note(`addressed to the whole room: this ${x.task ? P.opens : 'message'} wakes nobody; name recipients (--to or --assign) to start work`);
     return { id, to, files: entries.length };

package/target/esm/app/rooms.js

@@ -36,9 +36,12 @@ export const rooms = (H, { archived = false } = {}) => {
     return [...live, ...gone];
 };
 // A room carries its profile from the start: later changes to the hub's profiles do not reach it.
-export const create = (H, name, { profile } = {}) => {
+// `quorum`: the room's work starts by itself once it has that many agents; until then a join waits.
+export const create = (H, name, { profile, quorum } = {}) => {
     if (!ID_RE.test(name) || RESERVED_ROOMS.has(name))
-        fail(`usage: ringi room create <id> [--profile <name>] (an id like fix-badge; not ${[...RESERVED_ROOMS].join(', ')})`);
+        fail(`usage: ringi room create <id> [--profile <name>] [--quorum <agents>] (an id like fix-badge; not ${[...RESERVED_ROOMS].join(', ')})`);
+    if (quorum !== undefined && !(Number.isSafeInteger(quorum) && quorum >= 1 && quorum <= 99))
+        fail('--quorum takes a number of agents, 1 to 99');
     const p = profile ?? H.contract.profile ?? DEFAULT_PROFILE;
     const text = profileText(H, p) ?? fail(`hub ${H.name} carries no profile ${p}; add it with ringi hub amend -m "<why>" --attach <file>:profiles/${p}.json`);
     parseProfile(text, `profile ${p}`);
@@ -48,7 +51,8 @@ export const create = (H, name, { profile } = {}) => {
         if (H.signed)
             files.allowed_signers = H.store.rootRoster?.() ?? fail(`hub ${H.name}: its store cannot start a signed roster`);
         // The genesis names the room; a random id makes it unique, so a room deleted and created again is a different room.
-        H.store.createRoom(name, OPERATOR, compose(`room ${name}`, [['To', '*'], ['Kind', 'room'], ['Room-Id', crypto.randomBytes(16).toString('hex')]]), files);
+        H.store.createRoom(name, OPERATOR, compose(`room ${name}`, [['To', '*'], ['Kind', 'room'], ['Room-Id', crypto.randomBytes(16).toString('hex')],
+            ...(quorum ? [['Quorum', String(quorum)]] : [])]), files);
     });
     setConfig({ hub: H.name, room: name });
     return { profile: p };

package/target/esm/app/session.js

@@ -1,15 +1,17 @@
 // Session use cases preserve the operator's identity, seat and delegated scope.
 import { OPERATOR, ensureHome, locked } from '../home/index.js';
-import { controlChange, openHub, room as roomOf } from '../hub/index.js';
+import { controlChange, openHub, room as roomOf, start } from '../hub/index.js';
 import { AGENT_RE } from '../protocol/index.js';
 import { allSessions, bound, dropSession, liveness, ownSession, parseSelector, pidAlive, readSession, saveSession, seatHolder, whoAmI } from '../runtime/session.js';
 import { fail, note, stamp } from '../lib/index.js';
 import { inbox } from './agent.js';
 import { tasks } from './room.js';
 export { bound } from '../runtime/session.js';
+// A room still waiting for its agents is not read: nothing is marked seen before its work starts.
 export const briefing = (s) => {
     const actor = bound();
-    return { session: s, actor, tasks: tasks(actor).views, inbox: inbox(actor) };
+    const st = start(actor.R);
+    return { session: s, actor, start: st, tasks: st.started ? tasks(actor).views : [], inbox: st.started ? inbox(actor) : null };
 };
 export const join = ({ hub, room, agent: id, scope }) => {
     const me = whoAmI();