@idleware/ringi 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idleware/ringi",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Distributed agent coordinator",
   "keywords": [
     "agents",

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/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,9 @@ export type Sent = {
     to: string[];
     files: number;
 };
+export declare const staged: ({ R, me }: Actor) => Staged[];
+export declare const stage: ({ R, me }: Actor, files: Entry[]) => Staged[];
+export declare const unstage: ({ R, me }: 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/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/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

@@ -57,6 +57,7 @@ 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): string;
     append(room: StoredRoom, who: string, text: string, entries: Entry[]): string;
     private onTop;
     verifyLog(room: StoredRoom, id: string, head: string): string | null;

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

@@ -75,6 +75,7 @@ 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): Rev;
     alarms?(room: StoredRoom): string[];
     verifyLog(room: StoredRoom, id: string, head: Rev): string | null;
     pin(room: StoredRoom, reader: string, id: string, rev: Rev): 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/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,33 @@ 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.
+export const staged = ({ R, me }) => loadState(R, me).staged ?? [];
+export const stage = ({ R, me }, files) => {
+    const taken = files.map(e => ({ path: e.path, blob: R.hub.store.blob(e.file ?? fail(`${e.path}: add takes files`)), mode: e.mode,
+        size: fs.statSync(e.file).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));
+        saveState(R, me, { ...st, staged: all });
+        return all;
+    });
+};
+// Unstages the given paths, or everything.
+export const unstage = ({ R, me }, paths) => readerLock(R, me, () => {
+    const st = loadState(R, me);
+    const missing = (paths ?? []).filter(p => !(st.staged ?? []).some(s => s.path === p));
+    if (missing.length)
+        fail(`not staged: ${missing.join(', ')}`);
+    const left = paths ? (st.staged ?? []).filter(s => !paths.includes(s.path)) : [];
+    saveState(R, me, { ...st, staged: left });
+    return left;
+});
 // 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 +78,10 @@ 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 ?? [];
+    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 +89,11 @@ export const send = ({ R, me }, x) => {
     ]);
     checkOutgoing(text, isRef(R));
     const id = append(R, me, text, entries);
+    if (stagedNow.length)
+        readerLock(R, me, () => {
+            const st = loadState(R, me);
+            saveState(R, me, { ...st, staged: (st.staged ?? []).filter(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();

package/target/esm/cli/agent.js

@@ -3,6 +3,7 @@ import * as Agent from '../app/agent.js';
 import { asJson, render } from '../app/view.js';
 import { fail, short, when } from '../lib/index.js';
 import { dump, flag, list, opt, out, textOf } from './args.js';
+import { scopeLine, waiting } from './shared.js';
 const options = (o) => ({ peek: flag(o, 'peek'), limit: opt(o, 'limit') ? Number(opt(o, 'limit')) : undefined });
 export const showInbox = ({ R, me, s }, res, o) => {
     if (flag(o, 'json'))
@@ -15,14 +16,19 @@ export const showInbox = ({ R, me, s }, res, o) => {
     if (res.rest)
         out(`\n(${res.rest} more: run ringi agent inbox again)`);
 };
-export const inbox = (a, o) => showInbox(a, Agent.inbox(a, options(o)), o);
+export const inbox = (a, o) => {
+    const st = Agent.started(a);
+    if (!st.started)
+        return out(waiting(a.R.name, st));
+    showInbox(a, Agent.inbox(a, options(o)), o);
+};
 export const take = (a, o) => {
     const { m, made } = Agent.take(a, o._[0] ?? fail('usage: ringi agent take <work>'));
     out(`${made ? 'took' : 'already took'} ${short(m.id)}: ${m.subject}`);
 };
 export const whoami = (a) => {
     const { session: s, profile, members } = Agent.whoami(a);
-    out(`${s.agent} in ${s.hub}/${s.room} (genesis ${short(s.genesis)}, profile ${profile}), session ${s.handle}, ${s.state}\nscope: ${s.scope ?? 'none recorded; ask the operator what to accept'}\nmembers: ${members.join(', ')}`);
+    out(`${s.agent} in ${s.hub}/${s.room} (genesis ${short(s.genesis)}, profile ${profile}), session ${s.handle}, ${s.state}\nscope: ${scopeLine(s, a.R.quorum !== null)}\nmembers: ${members.join(', ')}`);
 };
 export const card = (a, o) => out(`card ${short(Agent.card(a, textOf(o)))}`);
 export const ping = (a, o) => {

package/target/esm/cli/args.js

@@ -5,8 +5,8 @@ import { fail } from '../lib/index.js';
 import { checkPath } from '../app/room.js';
 export const out = (s = '') => { process.stdout.write(s.endsWith('\n') ? s : `${s}\n`); };
 export const dump = (v) => out(JSON.stringify(v, null, 2));
-const BOOLS = new Set(['task', 'peek', 'all', 'json', 'help', 'once', 'project', 'follow', 'short', 'yes', 'require-grant', 'md', 'archived', 'signed', 'repair', 'handoff']);
-const MULTI = new Set(['m', 'attach', 'set']);
+const BOOLS = new Set(['task', 'peek', 'all', 'json', 'help', 'once', 'project', 'follow', 'short', 'yes', 'require-grant', 'md', 'archived', 'signed', 'repair', 'handoff', 'clear']);
+const MULTI = new Set(['m', 'attach', 'set', 'drop']);
 const SHORT = { m: 'm', F: 'file', n: 'n', o: 'out', h: 'help' };
 export const parseArgs = (argv) => {
     const o = { _: [] };

package/target/esm/cli/index.js

@@ -8,7 +8,7 @@ import { card, inbox, ping, take, wait, whoami } from './agent.js';
 import { operatorCtx } from './context.js';
 import { forget, hub, roomCmd, sessions, where } from './operator.js';
 import { join, leave, resume, stop } from './session.js';
-import { cat, decide, get, grants, log, profileCmd, proposals, propose, read, reply, send, signals, stamp_, tasks, thread, who } from './shared.js';
+import { add, cat, decide, get, grants, log, profileCmd, proposals, propose, read, reply, send, signals, stamp_, tasks, thread, who } from './shared.js';
 import { skill } from './skill.js';
 // --- commands ---
 // [command, who runs it, what it does]: the one table behind `ringi help` and COMMANDS.md.
@@ -19,13 +19,13 @@ export const TABLE = [
     ['hub switch <name>', 'operator', 'change the terminal\'s current hub; agents stay where they are'],
     ['hub amend -m <subject> [--set <key>=<value>]... [--authority <file>] [--attach <file>:profiles/<name>.json]...', 'operator', 'refine the shared contract: version, capabilities, default profile, authority table, profiles'],
     ['room list [--archived]', 'operator', 'rooms of the current hub'],
-    ['room create <id> [--profile <name>]', 'operator', 'a room for one piece of work, following a profile; becomes the current room'],
+    ['room create <id> [--profile <name>] [--quorum <agents>]', 'operator', 'a room for one piece of work, following a profile; becomes the current room; --quorum: its work starts by itself once that many agents joined (1: at once)'],
     ['room migrate <id>', 'operator', 'local hubs: join the old room branches without changing message ids or sessions'],
     ['room switch <id>', 'operator', 'change the terminal\'s current room; agents stay where they are'],
     ['room admit <agent> <public key|file>', 'operator', 'signed hubs: admit the key an agent made on its own machine'],
     ['room remove <agent>', 'operator', 'local hubs: take an agent out of the current room'],
-    ['room archive <id>', 'operator', 'local hubs: read-only from now on; wakes nobody; its sessions end'],
-    ['room delete <id> --yes', 'operator', 'local hubs: erase a room and everything kept for it; its sessions leave on their own'],
+    ['room archive [<id>]', 'operator', 'local hubs: a room (default: the current one) is read-only from now on, wakes nobody; its sessions leave on their own'],
+    ['room delete [<id>] --yes', 'operator', 'local hubs: erase a room (default: the current one) and everything kept for it; its sessions leave on their own'],
     ['room rebase-contract <id>', 'operator', 'move a room onto the hub\'s current contract'],
     ['where [-n n] [--short] [--follow]', 'operator', 'hub, room, sessions (active, stopped, gone), open work and proposals, latest messages'],
     ['send -m <subject> [-m <body>]... [--to <ids>] [--task] [--re <msg>] [--state <s>] [--assign <ids>] [--roles <id>=<label>,...] [--grant <decision>] [--attach <src>[:<dest>]]...', 'operator', 'a message as operator; without --to it goes to the room and wakes nobody; --task opens work of the room\'s profile'],
@@ -33,6 +33,7 @@ export const TABLE = [
     ['stamp <proposal> approve|object|abstain -m <reason>', 'both', 'a named reviewer\'s stamp on that exact revision'],
     ['decide <proposal> approved|rejected|revoked -m <reason>', 'both', 'the named decider, with authority; an approval with a budget is a grant'],
     ['proposals [--all] | grants', 'both', 'open proposals with their stamps; grants with their usage'],
+    ['add <src>[:<dest>]... | add [--drop <path>]... [--clear]', 'both', 'stage files for your next message, like git add: their content is taken now; results and state travel only as attachments'],
     ['tasks [--all] | log [-n n] | read <msg> | thread <msg> | cat <msg> [<path>] | get <msg> [-o <dir>] | who', 'both', 'reading the room (agents: ringi agent …)'],
     ['signals [--all] [--repair]', 'both', 'what happened (signals) and where attention is (read and taken marks), each checked; --repair restores your missing signals'],
     ['profile', 'both', 'the room\'s profile: what a piece of work is, its states, who may move it'],
@@ -65,7 +66,7 @@ export const helpMarkdown = () => ['# ringi commands', '',
     '| command | who | what |', '|---|---|---|',
     ...TABLE.map(([cmd, w, what]) => `| \`ringi ${cmd.replace(/\|/g, '\\|')}\` | ${w} | ${what} |`), '',
     'Message ids are store revisions (git: commit shas), any unique prefix of 4+ characters. States and roles come from the room\'s profile (`ringi profile`).', ''].join('\n');
-const SHARED = { send, reply, read, thread, tasks, log, cat, get, who, signals, profile: profileCmd, propose, stamp: stamp_, decide, proposals, grants };
+const SHARED = { add, send, reply, read, thread, tasks, log, cat, get, who, signals, profile: profileCmd, propose, stamp: stamp_, decide, proposals, grants };
 const AGENT = { ...SHARED, inbox, whoami, status: whoami, card, ping, wait, take };
 // A reader that stops early (`ringi log | head`) closes the pipe: that ends the output, not the command's work.
 const quietPipe = (e) => { if (e.code === 'EPIPE')

package/target/esm/cli/operator.js

@@ -19,7 +19,9 @@ export const where = async (o) => {
     const R = w.room;
     if (!R)
         return out('no current room: ringi room create <id> | ringi room switch <id>');
-    out(`room ${R.name}${R.archived ? ' (archived, read-only)' : ''}, genesis ${short(R.genesis)}, profile ${R.profile.name}; members: ${Object.entries(R.members).map(([id, i]) => i.role === 'root' ? `${id} (root)` : id).join(', ')}`);
+    const agents = Object.values(R.members).filter(m => m.role !== 'root').length;
+    out(`room ${R.name}${R.archived ? ' (archived, read-only)' : ''}, genesis ${short(R.genesis)}, profile ${R.profile.name}; members: ${Object.entries(R.members).map(([id, i]) => i.role === 'root' ? `${id} (root)` : id).join(', ')}`
+        + (R.quorum === null ? '' : agents >= R.quorum ? `; started at its quorum of ${R.quorum} agents` : `; waiting for a quorum of ${R.quorum} agents, has ${agents}`));
     out(w.sessions.length ? `sessions:\n${w.sessions.map(s => `  ${sessionLine(s)}`).join('\n')}` : 'sessions: none joined');
     out(w.work.length ? `open work:\n${w.work.map(t => `  ${taskLine(t)}`).join('\n')}` : 'open work: none');
     if (w.proposals.length)
@@ -108,7 +110,10 @@ export const roomCmd = (o) => {
         return;
     }
     if (sub === 'create') {
-        const r = Rooms.create(H, arg ?? '', { profile: opt(o, 'profile') });
+        const quorum = opt(o, 'quorum');
+        const r = Rooms.create(H, arg ?? '', { profile: opt(o, 'profile'), quorum: quorum === undefined ? undefined : Number(quorum) });
+        if (quorum !== undefined)
+            return out(`created room ${arg} in hub ${H.name} with profile ${r.profile}; it is the current room. Its work starts by itself at a quorum of ${quorum} agent(s): in each chat that should take part, say "join ${arg} as <id>"`);
         return out(`created room ${arg} in hub ${H.name} with profile ${r.profile}; it is the current room. In each chat that should take part, say: "join ${arg} as <id>; <what to accept>"`);
     }
     if (sub === 'migrate') {
@@ -130,14 +135,15 @@ export const roomCmd = (o) => {
         return out(`removed ${arg} from ${R.name}: it can no longer write or be woken there; returning needs a fresh join`);
     }
     if (sub === 'archive') {
-        const R = Rooms.roomIn(H, arg ?? fail('usage: ringi room archive <id>'));
+        // Without an id, the room of the current context.
+        const R = Rooms.roomIn(H, arg ?? opt(o, 'room'));
         const name = Rooms.archive(H, R);
         return out(`archived ${R.name} as ${name}: read-only, wakes nobody; its sessions end. Read it with --room ${name}`);
     }
     if (sub === 'delete') {
-        const R = Rooms.roomIn(H, arg ?? fail('usage: ringi room delete <id> --yes'));
+        const R = Rooms.roomIn(H, arg ?? opt(o, 'room'));
         if (!flag(o, 'yes'))
-            fail(`deleting ${R.name} removes its history from the hub for good. Run again with --yes, or archive it instead`);
+            fail(`deleting ${R.name} in hub ${H.name} erases it and everything kept for it, for good. Run again with --yes, or archive it instead`);
         Rooms.erase(H, R);
         return out(`deleted room ${R.name}: its branch, signals, pins, evidence and readers' state. Sessions bound to it leave it on their next turn`);
     }

package/target/esm/cli/session.js

@@ -3,11 +3,16 @@ import * as Session from '../app/session.js';
 import { fail } from '../lib/index.js';
 import { opt, out } from './args.js';
 import { showInbox } from './agent.js';
-import { taskLine } from './shared.js';
+import { scopeLine, taskLine, waiting } from './shared.js';
 export const briefing = (s) => {
     const r = Session.briefing(s);
-    out(`${s.agent} in ${s.hub}/${s.room}; scope: ${s.scope ?? 'none recorded; ask the operator what to accept'}`);
+    const auto = r.start.quorum !== null;
+    out(`${s.agent} in ${s.hub}/${s.room}; scope: ${scopeLine(s, auto)}`);
     out('agent commands: ringi agent inbox | reply <id> … | send … | tasks | proposals | whoami. A turn: inbox, your part, replies, end the turn. Never block on a peer.');
+    if (!r.start.started)
+        return out(waiting(s.room, r.start));
+    if (auto)
+        out(`started: room ${s.room} has its quorum (${r.start.agents} of ${r.start.quorum} agents); your first turn starts now, on the work and inbox below; nothing to confirm with the operator`);
     if (!r.tasks.length)
         out(`no open work (profile ${r.actor.R.profile.name}; tasks --all for everything)`);
     for (const task of r.tasks)

package/target/esm/cli/shared.js

@@ -6,12 +6,22 @@ import * as Budget from '../app/budget.js';
 import * as Room from '../app/room.js';
 import { checkPath, withSizes } from '../app/room.js';
 import { asJson, oneLine, render } from '../app/view.js';
-import { fail, note, short, when, words } from '../lib/index.js';
+import { bytes, fail, note, short, when, words } from '../lib/index.js';
 import { attachments, dump, flag, list, opt, out, textOf } from './args.js';
 const sendInput = (o) => ({ text: textOf(o), to: words(opt(o, 'to')), all: flag(o, 'all'), task: flag(o, 'task'),
     state: opt(o, 'state'), assign: opt(o, 'assign') ? words(opt(o, 'assign')) : undefined, roles: opt(o, 'roles'), grant: opt(o, 'grant'),
     files: list(o, 'attach').flatMap(attachments) });
 const sent = (r) => out(`sent ${short(r.id)} to ${r.to.join(', ')}${r.files ? ` with ${r.files} file(s)` : ''}`);
+// Stages files for the actor's next message, like git add: their content is taken into the hub now. Without files it
+// lists what is staged; --drop <path> and --clear take files back out.
+export const add = (a, o) => {
+    if (flag(o, 'clear'))
+        Room.unstage(a, null);
+    else if (list(o, 'drop').length)
+        Room.unstage(a, list(o, 'drop'));
+    const staged = o._.length ? Room.stage(a, o._.flatMap(attachments)) : Room.staged(a);
+    out(staged.length ? `staged for your next message:\n${staged.map(s => `  ${s.path} (${bytes(s.size)})`).join('\n')}` : 'nothing staged');
+};
 export const send = (a, o) => sent(Room.send(a, { ...sendInput(o), re: opt(o, 're') }));
 export const reply = (a, o) => sent(Room.send(a, { ...sendInput(o), re: o._[0] ?? fail('usage: reply <msg> -m <text> …'), reply: true }));
 export const read = (a, o) => {
@@ -140,4 +150,10 @@ export const grants = (a, o) => {
         out(`${short(g.grant)}  ${g.revoked ? 'revoked ' : u.left ? 'active  ' : 'spent   '} runs ${u.runs}/${g.budget.runs}, open ${u.open}${u.uncertain ? `, uncertain ${u.uncertain}` : ''}, ${u.seconds}s used, ≤${g.budget['run-seconds']}s a run, concurrency ${g.budget.concurrency}  ${g.subject}`);
     }
 };
+// What the session may do on its own: the recorded scope; without one, in a room with a quorum the room's work for it,
+// in any other what the operator accepts when asked.
+export const scopeLine = (s, quorum = false) => s.scope
+    ?? (quorum ? 'none recorded; the room\'s work for you, split with the other members' : 'none recorded; ask the operator what to accept');
+// The line that keeps an agent of a room waiting for its quorum from doing anything yet.
+export const waiting = (room, st) => `waiting: room ${room} waits for a quorum of ${st.quorum} agents and has ${st.agents}; nothing to do yet, end the turn. Its work starts by itself at the quorum`;
 //# sourceMappingURL=shared.js.map

package/target/esm/hub/index.js

@@ -16,6 +16,11 @@ import { fail, short, strictJson } from '../lib/index.js';
 export const HUB_MAJOR = 1;
 export const CAPS = new Set(Object.keys(CAPABILITIES));
 export const RESERVED_ROOMS = new Set(['main', 'archive']);
+// Whether the room's work has started: it has the quorum of agents its genesis asked for (`Quorum`), or asked for none.
+export const start = (R) => {
+    const agents = Object.values(R.members).filter(m => m.role !== 'root').length;
+    return { quorum: R.quorum, agents, started: R.quorum === null || agents >= R.quorum };
+};
 // --- hubs ---
 export const hubNames = () => {
     try {
@@ -151,8 +156,15 @@ export const openRoom = (H, name, { quiet = false } = {}) => {
         ?? (baseProfile === DEFAULT_PROFILE ? readProfileResource(DEFAULT_PROFILE) : fail(`room ${name}: unknown profile ${baseProfile}`));
     const roster = H.store.roster(s);
     const members = roster?.members ?? strictJson(H.store.controlFile(s, 'members.json') ?? '{}', `room ${name}: members.json`);
+    // The root's control records set the quorum; the latest one counts.
+    let quorum = null;
+    for (const rec of s.control) {
+        const m = /^Quorum: ([1-9][0-9]?)$/m.exec(rec.text);
+        if (m)
+            quorum = Number(m[1]);
+    }
     return { hub: H, s, name, archived: s.archived, head: s.head, genesis: s.genesis, contractRev: current, contract, authorityAt,
-        profile: parseProfile(profileText, `room ${name}: profile`), members };
+        profile: parseProfile(profileText, `room ${name}: profile`), members, quorum };
 };
 export const room = (H, name) => openRoom(H, name);
 export const ROOM_MD = (name) => `# room ${name}\n\nA ringi room: members.json lists who takes part; profile.json is what a piece of work is here, fixed when the room was made.\n`;

package/target/esm/runtime/watch.js

@@ -4,7 +4,7 @@
 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 { HIDDEN, append, openHub, openRoom, pongText, start } 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';
@@ -137,6 +137,16 @@ export const watch = async (w, log = note) => {
             log(`watch: ${me} was removed from ${R0.name}; stopping`);
             return 0;
         }
+        // A room waiting for its quorum runs no turn yet.
+        const st = start(R);
+        if (!st.started) {
+            if (w.once) {
+                log(`watch: ${R0.name} waits for a quorum of ${st.quorum} agents and has ${st.agents}; nothing to do yet`);
+                return 0;
+            }
+            await sleep(interval);
+            continue;
+        }
         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, () => {

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

@@ -97,7 +97,7 @@ export class GitStore {
             if (drop.length)
                 this.git(['update-index', '--index-info'], { env, input: drop.map(p => `0 ${ZERO}\t${p}\n`).join('') });
             for (const e of entries) {
-                const sha = this.git(['hash-object', '-w', ...(e.file ? ['--', e.file] : ['--stdin'])], { input: e.content }).trim();
+                const sha = e.blob ?? 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();
@@ -514,6 +514,7 @@ export class GitStore {
                     files: files.filter(f => REGULAR.has(f.mode)), refused: [...refused, ...files.filter(f => !REGULAR.has(f.mode))] }];
         });
     }
+    blob(file) { return this.git(['hash-object', '-w', '--', file]).trim(); }
     // One message on top of the room's branch.
     append(room, who, text, entries) {
         if (room.archived)