@manyoars/oars 0.5.3 → 0.5.5

package/dist/sessions/cells.js

@@ -160,7 +160,8 @@ const linesOf = (tools) => {
     }
     return [...lines.values()].map((line) => line.sort((a, b) => a.n - b.n));
 };
-export const deriveCells = (store, graph = NO_RECALLS) => {
+/** `deriveCells` as a fold: each `add` tallies one run of sessions into the same tallies, and `finish` sorts them. The runs must come in the order the whole store holds its rows, so sums of floats match. */
+export const cellFold = (graph = NO_RECALLS) => {
     const tallies = new Map();
     const motifs = new Map();
     const tallyAt = (motif, frameBucket, grain, day, exposure) => {
@@ -181,128 +182,138 @@ export const deriveCells = (store, graph = NO_RECALLS) => {
         // Fit's (name, platform, shell) cell: a week cell beside the versioned one, counting the same call.
         return isPlainCall(motif) ? [...tallies, tallyAt(motif, environmentBucketOf(frame), 'week', weekStartOf(day), exposure)] : tallies;
     };
-    const sessions = new Map([...store.sessions, ...store.subagents].map((session) => [session.session, session]));
-    const prompts = new Map(store.prompts.map((prompt) => [`${prompt.session}#${String(prompt.index)}`, prompt]));
-    for (const line of linesOf(store.tools)) {
-        const [first] = line;
-        const session = first === undefined ? undefined : sessions.get(first.session);
-        if (first === undefined || session === undefined)
-            continue;
-        const harness = harnessOf(session);
-        const version = first.harnessVersion ?? session.env.harness;
-        const prompt = prompts.get(`${first.session}#${String(first.prompt)}`);
-        const frame = prompt === undefined
-            ? (session.frame ?? oldFrame({ harness, version, model: mostUsedModel(session.models), effort: null, ts: first.ts ?? session.tsFirst, platform: session.env.os }))
-            : framedPrompt(prompt, harness, version, first.ts, session.env.os);
-        const placed = line.flatMap((tool) => graph.place(tool, stepsOfCall(tool, harness)));
-        const steps = placed.map(({ step }) => step);
-        for (const { motif, start } of motifsOf(steps)) {
-            const window = steps.slice(start, start + motif.steps.length);
-            const status = window.at(-1)?.status;
-            const covered = placed.slice(start, start + motif.steps.length);
-            for (const tally of talliesOf(motif, frame, exposureOf(covered.some(({ exposed }) => exposed), covered.some((step) => 'held' in step && step.held)))) {
-                tally.sessions.add(first.parent);
-                if (status === 'ok')
-                    tally.ok += 1;
-                if (status === 'error')
-                    tally.failed += 1;
-                for (const step of window) {
-                    // A step with no recorded cost has no tokens to count, so it joins neither the sum nor the coverage (its duration is still counted).
-                    if (step.tokens !== null) {
-                        tally.tokens += step.tokens;
-                        tally.recorded.add(first.parent);
-                        tally.recordedUnits += 1;
+    const add = (store) => {
+        const sessions = new Map([...store.sessions, ...store.subagents].map((session) => [session.session, session]));
+        const prompts = new Map(store.prompts.map((prompt) => [`${prompt.session}#${String(prompt.index)}`, prompt]));
+        for (const line of linesOf(store.tools)) {
+            const [first] = line;
+            const session = first === undefined ? undefined : sessions.get(first.session);
+            if (first === undefined || session === undefined)
+                continue;
+            const harness = harnessOf(session);
+            const version = first.harnessVersion ?? session.env.harness;
+            const prompt = prompts.get(`${first.session}#${String(first.prompt)}`);
+            const frame = prompt === undefined
+                ? (session.frame ?? oldFrame({ harness, version, model: mostUsedModel(session.models), effort: null, ts: first.ts ?? session.tsFirst, platform: session.env.os }))
+                : framedPrompt(prompt, harness, version, first.ts, session.env.os);
+            const placed = line.flatMap((tool) => graph.place(tool, stepsOfCall(tool, harness)));
+            const steps = placed.map(({ step }) => step);
+            for (const { motif, start } of motifsOf(steps)) {
+                const window = steps.slice(start, start + motif.steps.length);
+                const status = window.at(-1)?.status;
+                const covered = placed.slice(start, start + motif.steps.length);
+                for (const tally of talliesOf(motif, frame, exposureOf(covered.some(({ exposed }) => exposed), covered.some((step) => 'held' in step && step.held)))) {
+                    tally.sessions.add(first.parent);
+                    if (status === 'ok')
+                        tally.ok += 1;
+                    if (status === 'error')
+                        tally.failed += 1;
+                    for (const step of window) {
+                        // A step with no recorded cost has no tokens to count, so it joins neither the sum nor the coverage (its duration is still counted).
+                        if (step.tokens !== null) {
+                            tally.tokens += step.tokens;
+                            tally.recorded.add(first.parent);
+                            tally.recordedUnits += 1;
+                        }
+                        tally.durationMs += step.durationMs;
                     }
-                    tally.durationMs += step.durationMs;
                 }
             }
-        }
-        // What followed each failed call that has a code (t868): a week cell per (code, failed action, next action).
-        // A call is read by its first step's action, as a skeleton's is; a record captured before steps has the action its native name maps to.
-        const calls = line.map((call) => ({ side: call.side, prompt: call.prompt, status: call.status, steps: stepsOfCall(call, harness) }));
-        for (const [at, tool] of line.entries()) {
-            const followed = recoveryCallsOf(calls, at);
-            if (followed === null || tool.errorCode === undefined)
-                continue;
-            const code = ERROR_CODES.has(tool.errorCode) ? tool.errorCode : 'other';
-            const motif = classMotif(recoveryClass(code, calls[at]?.steps[0]?.action ?? 'other', followed.next[0] ?? NO_NEXT));
-            motifs.set(motif.motifId, motif);
-            const tally = tallyAt(motif, versionBucketOf(frame), 'week', weekStartOf(frame.day ?? UNKNOWN), 'unknown');
-            tally.sessions.add(first.parent);
-            tally.failed += 1;
-        }
-        // Each call's shape, by its first step's action: a week cell per facet it holds, counted by the call's own status.
-        for (const [at, tool] of line.entries()) {
-            const action = calls[at]?.steps[0]?.action ?? 'other';
-            for (const [facet, value] of shapeFacetsOf(tool)) {
-                const motif = classMotif(shapeClass(action, facet, value));
+            // What followed each failed call that has a code (t868): a week cell per (code, failed action, next action).
+            // A call is read by its first step's action, as a skeleton's is; a record captured before steps has the action its native name maps to.
+            const calls = line.map((call) => ({ side: call.side, prompt: call.prompt, status: call.status, steps: stepsOfCall(call, harness) }));
+            for (const [at, tool] of line.entries()) {
+                const followed = recoveryCallsOf(calls, at);
+                if (followed === null || tool.errorCode === undefined)
+                    continue;
+                const code = ERROR_CODES.has(tool.errorCode) ? tool.errorCode : 'other';
+                const motif = classMotif(recoveryClass(code, calls[at]?.steps[0]?.action ?? 'other', followed.next[0] ?? NO_NEXT));
                 motifs.set(motif.motifId, motif);
                 const tally = tallyAt(motif, versionBucketOf(frame), 'week', weekStartOf(frame.day ?? UNKNOWN), 'unknown');
                 tally.sessions.add(first.parent);
-                if (tool.status === 'ok')
-                    tally.ok += 1;
-                if (tool.status === 'error')
-                    tally.failed += 1;
+                tally.failed += 1;
             }
-        }
-        // The failed calls by their `errorCode` (t868). Rule 6: a day cell exists for a known day only.
-        const failedDay = frame.day ?? UNKNOWN;
-        for (const tool of failedDay === UNKNOWN ? [] : line) {
-            if (tool.status !== 'error' || tool.errorCode === undefined)
-                continue;
-            const code = ERROR_CODES.has(tool.errorCode) ? tool.errorCode : 'other';
-            for (const counted of stepsOfCall(tool, harness)) {
-                if (counted.status !== 'error')
+            // Each call's shape, by its first step's action: a week cell per facet it holds, counted by the call's own status.
+            for (const [at, tool] of line.entries()) {
+                const action = calls[at]?.steps[0]?.action ?? 'other';
+                for (const [facet, value] of shapeFacetsOf(tool)) {
+                    const motif = classMotif(shapeClass(action, facet, value));
+                    motifs.set(motif.motifId, motif);
+                    const tally = tallyAt(motif, versionBucketOf(frame), 'week', weekStartOf(frame.day ?? UNKNOWN), 'unknown');
+                    tally.sessions.add(first.parent);
+                    if (tool.status === 'ok')
+                        tally.ok += 1;
+                    if (tool.status === 'error')
+                        tally.failed += 1;
+                }
+            }
+            // The failed calls by their `errorCode` (t868). Rule 6: a day cell exists for a known day only.
+            const failedDay = frame.day ?? UNKNOWN;
+            for (const tool of failedDay === UNKNOWN ? [] : line) {
+                if (tool.status !== 'error' || tool.errorCode === undefined)
                     continue;
-                // The call's name at both levels: its action alone, and a named call (a flag or a pull would be a second dimension, so those steps are named by program and subcommand alone upstream).
-                for (const { motif: named } of motifsOf([counted])) {
-                    if (named.level === 'named' && counted.identity === null)
+                const code = ERROR_CODES.has(tool.errorCode) ? tool.errorCode : 'other';
+                for (const counted of stepsOfCall(tool, harness)) {
+                    if (counted.status !== 'error')
                         continue;
-                    const name = motifName(named);
-                    for (const [prefix, bucket] of [[ERROR_CLASS, `${frame.harness}/${NO_AXES}/${frame.model ?? UNKNOWN}`], [ERROR_VERSION_CLASS, versionBucketOf(frame)]]) {
-                        const motif = classMotif(`${prefix}${code}/${name}`);
-                        motifs.set(motif.motifId, motif);
-                        const tally = tallyAt(motif, bucket, 'day', failedDay, 'unknown');
-                        tally.sessions.add(first.parent);
-                        tally.failed += 1;
-                        if (counted.tokens !== null) {
-                            tally.tokens += counted.tokens;
-                            tally.recorded.add(first.parent);
-                            tally.recordedUnits += 1;
+                    // The call's name at both levels: its action alone, and a named call (a flag or a pull would be a second dimension, so those steps are named by program and subcommand alone upstream).
+                    for (const { motif: named } of motifsOf([counted])) {
+                        if (named.level === 'named' && counted.identity === null)
+                            continue;
+                        const name = motifName(named);
+                        for (const [prefix, bucket] of [[ERROR_CLASS, `${frame.harness}/${NO_AXES}/${frame.model ?? UNKNOWN}`], [ERROR_VERSION_CLASS, versionBucketOf(frame)]]) {
+                            const motif = classMotif(`${prefix}${code}/${name}`);
+                            motifs.set(motif.motifId, motif);
+                            const tally = tallyAt(motif, bucket, 'day', failedDay, 'unknown');
+                            tally.sessions.add(first.parent);
+                            tally.failed += 1;
+                            if (counted.tokens !== null) {
+                                tally.tokens += counted.tokens;
+                                tally.recorded.add(first.parent);
+                                tally.recordedUnits += 1;
+                            }
+                            tally.durationMs += counted.durationMs;
                         }
-                        tally.durationMs += counted.durationMs;
                     }
                 }
             }
         }
-    }
-    for (const prompt of store.prompts) {
-        const session = sessions.get(prompt.session);
-        const frame = framedPrompt(prompt, harnessOf(session ?? {}), session?.env.harness ?? null, null, session?.env.os ?? UNKNOWN);
-        const exposure = exposureOf(graph.exposedPrompt(prompt.session, prompt.index), statesExposure(graph) && graph.heldPrompt(prompt.session, prompt.index));
-        const effort = frame.effort === null ? [] : talliesOf(classMotif(effortClass(frame.effort, prompt.usage.thinking)), frame, exposure, NO_AXES);
-        for (const tally of [...talliesOf(classMotif(prompt.cls), frame, exposure), ...effort]) {
-            tally.sessions.add(prompt.session);
-            if (prompt.errors > 0)
-                tally.failed += 1;
-            else
-                tally.ok += 1;
-            // A prompt that recorded no input has no whole usage to count, and a category it never recorded is a placeholder zero, so neither enters the sum.
-            if (observesUsage(prompt, 'input')) {
-                tally.recorded.add(prompt.session);
-                tally.recordedUnits += 1;
-                for (const field of TOKEN_FIELDS)
-                    if (observesUsage(prompt, field))
-                        tally.tokens += prompt.usage[field];
+        for (const prompt of store.prompts) {
+            const session = sessions.get(prompt.session);
+            const frame = framedPrompt(prompt, harnessOf(session ?? {}), session?.env.harness ?? null, null, session?.env.os ?? UNKNOWN);
+            const exposure = exposureOf(graph.exposedPrompt(prompt.session, prompt.index), statesExposure(graph) && graph.heldPrompt(prompt.session, prompt.index));
+            const effort = frame.effort === null ? [] : talliesOf(classMotif(effortClass(frame.effort, prompt.usage.thinking)), frame, exposure, NO_AXES);
+            for (const tally of [...talliesOf(classMotif(prompt.cls), frame, exposure), ...effort]) {
+                tally.sessions.add(prompt.session);
+                if (prompt.errors > 0)
+                    tally.failed += 1;
+                else
+                    tally.ok += 1;
+                // A prompt that recorded no input has no whole usage to count, and a category it never recorded is a placeholder zero, so neither enters the sum.
+                if (observesUsage(prompt, 'input')) {
+                    tally.recorded.add(prompt.session);
+                    tally.recordedUnits += 1;
+                    for (const field of TOKEN_FIELDS)
+                        if (observesUsage(prompt, field))
+                            tally.tokens += prompt.usage[field];
+                }
+                tally.durationMs += (prompt.wallSec ?? 0) * 1000;
             }
-            tally.durationMs += (prompt.wallSec ?? 0) * 1000;
         }
-    }
-    const stated = statesExposure(graph);
-    const cells = [...tallies.values()]
-        .sort((a, b) => compare(a.motifId, b.motifId) || compare(a.frameBucket, b.frameBucket) || compare(a.grain, b.grain) || compare(a.day, b.day) || EXPOSURE_CODES[a.exposure] - EXPOSURE_CODES[b.exposure])
-        .map((tally) => ({ motifId: tally.motifId, frameBucket: tally.frameBucket, grain: tally.grain, day: tally.day, sessions: tally.sessions.size, clusters: ONE_OPERATOR, ok: tally.ok, failed: tally.failed, tokens: tally.recorded.size === 0 ? null : tally.tokens, tokenSessions: tally.recorded.size, tokenPrompts: tally.recordedUnits, durationMs: tally.durationMs, exposed: tally.exposure === 'shown', ...(stated ? { exposure: tally.exposure } : {}) }));
-    return { cells, motifs: [...motifs.values()].sort((a, b) => compare(a.motifId, b.motifId)) };
+    };
+    const finish = () => {
+        const stated = statesExposure(graph);
+        const cells = [...tallies.values()]
+            .sort((a, b) => compare(a.motifId, b.motifId) || compare(a.frameBucket, b.frameBucket) || compare(a.grain, b.grain) || compare(a.day, b.day) || EXPOSURE_CODES[a.exposure] - EXPOSURE_CODES[b.exposure])
+            .map((tally) => ({ motifId: tally.motifId, frameBucket: tally.frameBucket, grain: tally.grain, day: tally.day, sessions: tally.sessions.size, clusters: ONE_OPERATOR, ok: tally.ok, failed: tally.failed, tokens: tally.recorded.size === 0 ? null : tally.tokens, tokenSessions: tally.recorded.size, tokenPrompts: tally.recordedUnits, durationMs: tally.durationMs, exposed: tally.exposure === 'shown', ...(stated ? { exposure: tally.exposure } : {}) }));
+        return { cells, motifs: [...motifs.values()].sort((a, b) => compare(a.motifId, b.motifId)) };
+    };
+    return { add, finish };
+};
+export const deriveCells = (store, graph = NO_RECALLS) => {
+    const fold = cellFold(graph);
+    fold.add(store);
+    return fold.finish();
 };
 export const serializeCells = (cells) => cells.map((cell) => `${JSON.stringify(cell)}\n`).join('');
 /** The fields of an error row a recovery read depends on, as text: only those, so a change elsewhere is not a new pool, and sorted, so record order is not one either. */

package/dist/sessions/crew-mark.d.ts

@@ -0,0 +1,6 @@
+/** The crew number held for `account` on `server`, or undefined: no file, another pool or account, a file that is not ours, or an account that is not in the crew. */
+export declare const crewNumberOf: (storeDir: string, server: string, account: string) => Promise<number | undefined>;
+/** Keeps what the pool said, replacing the earlier answer: the number, or none when the account holds none. */
+export declare const keepCrewNumber: (storeDir: string, server: string, account: string, crewNumber: number | undefined) => Promise<void>;
+/** The card's words for a crew number. */
+export declare const crewMarkText: (crewNumber: number) => string;

package/dist/sessions/crew-mark.js

@@ -0,0 +1,22 @@
+// The founding crew number this machine last learned for a pool (t1229): `GET /v1/me` states it, and `oars pool invite` and `oars pool join` keep it here so the share card, which makes no network call, can show it. A number only; no count of members is ever stored or printed.
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isObject, numberIn } from './pool-replica.js';
+const fileOf = (storeDir) => join(storeDir, 'pool-crew.json');
+/** The crew number held for `account` on `server`, or undefined: no file, another pool or account, a file that is not ours, or an account that is not in the crew. */
+export const crewNumberOf = async (storeDir, server, account) => {
+    try {
+        const held = JSON.parse(await readFile(fileOf(storeDir), 'utf8'));
+        return isObject(held) && Reflect.get(held, 'server') === server && Reflect.get(held, 'account') === account ? numberIn(held, 'crewNumber') : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Keeps what the pool said, replacing the earlier answer: the number, or none when the account holds none. */
+export const keepCrewNumber = async (storeDir, server, account, crewNumber) => {
+    await mkdir(storeDir, { recursive: true });
+    await writeFile(fileOf(storeDir), JSON.stringify({ server, account, ...(crewNumber === undefined ? {} : { crewNumber }) }));
+};
+/** The card's words for a crew number. */
+export const crewMarkText = (crewNumber) => `founding crew #${String(crewNumber)}`;

package/dist/sessions/hook-index.d.ts

@@ -1,6 +1,7 @@
 import type { Read } from './read.js';
 import type { Position, RecoveryEdges } from './recall-next.js';
 import type { NextByFrame } from './recall-frames.js';
+import type { ReadFolds } from './read-folds.js';
 import { type RecallRead } from './recall-reads.js';
 import { type Store } from './store.js';
 /** A signature is "recurring" once it has been seen in this many sessions. */
@@ -47,7 +48,7 @@ export interface HookIndex {
         [frame: string]: Position[];
     };
 }
-export declare const buildIndex: (store: Store, redactDomains: readonly string[], at: string, reads?: readonly Read[], next?: NextByFrame) => HookIndex;
+export declare const buildIndex: (store: Store, redactDomains: readonly string[], at: string, reads?: readonly Read[], next?: NextByFrame, folds?: ReadFolds) => HookIndex;
 export declare const indexPath: (storeDir: string) => string;
 /** The index as written, or undefined when there is none (or it is torn): a hook then says nothing. */
 export declare const readIndex: (storeDir: string) => Promise<HookIndex | undefined>;

package/dist/sessions/hook-index.js

@@ -33,7 +33,7 @@ const repositoryOf = (projects) => {
         return bases.find((candidate) => base === candidate || base.startsWith(`${candidate}-`)) ?? base;
     };
 };
-export const buildIndex = (store, redactDomains, at, reads = [], next) => {
+export const buildIndex = (store, redactDomains, at, reads = [], next, folds) => {
     const projectOf = new Map(store.sessions.map((session) => [session.session, session.project]));
     // The latest 300 of each repository, not of the whole store: another repository's deposits must not move this one's ranking.
     const family = repositoryOf([...new Set(store.sessions.map((session) => session.project))]);
@@ -92,7 +92,7 @@ export const buildIndex = (store, redactDomains, at, reads = [], next) => {
         redactDomains: [...redactDomains],
         projects,
         signatures,
-        fit: Object.fromEntries(resolveReads(aboveBaseRate(store, fitReads(store, PUSH_FLOORS)), reads).map((read) => [toolShapeId(read.tool, read.keys), read])),
+        fit: Object.fromEntries(resolveReads(folds?.push ?? aboveBaseRate(store, fitReads(store, PUSH_FLOORS)), reads).map((read) => [toolShapeId(read.tool, read.keys), read])),
         ...(next === undefined ? {} : { recoveryByFrame: next.recovery, positionsByFrame: next.positions }),
     };
 };

package/dist/sessions/pool-command.d.ts

@@ -70,6 +70,7 @@ export declare const poolLogin: (deps: RunDeps, options: {
     server?: string | undefined;
     provider?: string | undefined;
     verbose?: boolean;
+    signal?: AbortSignal;
 }) => Promise<Outcome>;
 /**
  * `oars pool logout` (S8): revokes this machine's credential at the pool (`DELETE /v1/login`), then removes the local entry. A pool that cannot be reached does not keep the entry: the person asked to be signed out here, so the entry
@@ -117,6 +118,9 @@ export interface SendLock {
     times: Partial<LockTimes>;
     fs: LockFs;
 }
+/** What `--send-all` does with the pool's busy answers: a 429 or a 5xx is asked again, up to `SEND_ATTEMPTS` in all, after the wait the pool names in `retry-after` (seconds, at most 30) or else 1 second, then 2. Any other answer, and a request that never got one, goes up unchanged. A batch or a part sent again is harmless, so the retry covers every request alike. */
+export type Pause = (ms: number, signal?: AbortSignal) => Promise<void>;
+export declare const sleeps: Pause;
 /**
  * How long the pool gets to answer one request of a send (an interactive `--send` and the background sender) before the send ends. It is a deadline for the whole request, the upload and the answer together,
  * not an idle timeout: a batch is one session's skeleton, whose largest fixture is 887 KB (docs/pool.md), which a link of 240 kbit/s or better uploads inside 30 seconds. A slower link fails each try with the stall
@@ -131,6 +135,15 @@ export declare const waitingLine: ({ holder, ageMs, waitMs }: Waiting) => string
  * retry is certain once the lock has gone untouched for staleMs.
  */
 export declare const busyLine: ({ holder, local, ageMs, untouchedMs, waitedMs, staleMs }: BusyDetail) => string;
+/**
+ * `oars pool remove <hash>`: takes one batch out of this machine's outbox, the batch `oars pool outbox` printed under that hash. It takes the send lock without waiting, because a send in progress may be reading the very file, and refuses while another run holds it.
+ * It reads nothing from the pool and sends nothing, so it needs no sign-in, and it changes only files here. The session of a local batch goes on `removed.json`, which `poolDeposit` (and so the background sender) honors: nothing of it is built, queued, or sent until `--restore <hash>` takes it off. One a cloud session held is admitted again only by `oars pool hold pull`.
+ */
+export declare const poolRemove: (deps: RunDeps, hash: string, options: {
+    server?: string | undefined;
+    restore?: boolean | undefined;
+    lock?: SendLock | undefined;
+}) => Promise<Outcome>;
 /** The outbox key, and the skeleton `id`, of a machine's session: from the environment's session salt (per account, not per machine), else its own name standing in for the account, which a machine has none of. The holding route names its branch by the same key. */
 export declare const machineKeyOf: (machine: MachineConfig, session: string) => string;
 /**
@@ -143,16 +156,22 @@ export declare const poolDeposit: (deps: RunDeps, options: {
     acceptCovenant?: string | undefined;
     inEuEeaUk?: string | undefined;
     send?: string | undefined;
+    sendAll?: boolean | undefined;
+    pause?: Pause | undefined;
     via?: Sender | undefined;
     git?: Git | undefined;
     session?: string | undefined;
     covenant?: string | undefined;
     lock?: SendLock | undefined;
 }) => Promise<Outcome>;
-/** `oars pool outbox`: prints each batch as it would be sent (a batch past one request prints each part's request, in order), the request line and every header included, with the bearer credential as its size and nothing else masked, then its SHA-256, and records that it was shown. `--explain` adds each field's rule. */
+/**
+ * `oars pool outbox`: prints each batch as it would be sent (a batch past one request prints each part's request, in order), the request line and every header included, with the bearer credential as its size and nothing else masked, then its SHA-256, and records that it was shown. `--explain` adds each field's rule.
+ * With `print` each batch is written as soon as it is built and marked shown right after, and the outcome carries no text: an outbox of thousands of sessions is far past V8's string length as one string. Without it (`--json`) the document carries each batch's request, and `--json` writes it element by element.
+ */
 export declare const poolOutbox: (deps: RunDeps, options: {
     server?: string | undefined;
     explain?: boolean | undefined;
+    print?: ((chunk: string) => void) | undefined;
 }) => Promise<Outcome>;
 /** `oars pool fetch`: one harness's signed bundle at one version, kept only once the key pinned at login has verified it. It keeps the signed form, so the replica can be checked again later, and the ETag, so the next fetch asks only whether it changed. The request prints before it is sent. */
 export declare const poolFetch: (deps: RunDeps, options: {
@@ -160,6 +179,33 @@ export declare const poolFetch: (deps: RunDeps, options: {
     harness?: string | undefined;
     harnessVersion: string;
 }) => Promise<Outcome>;
+/**
+ * `oars pool join`: the first deposit in one run, each step by the handler its own command uses: sign-in (`login`), the region question, the exclusion term file (scaffolded empty, never filled in), the batch (`deposit`), what it holds (`outbox
+ * --explain`), the covenant (the screen and typed phrase `deposit --send` shows), and the send (`deposit --send <hash>` for each batch not yet sent), then `fetch` when a harness version is named. A step that stops ends the run with its own
+ * error. Run again, each step that stands is skipped: a held sign-in, terms in the file, a prepared batch, an accepted covenant, a batch in `sent.log`. Acceptance is the person's own: this never types the phrase, and off a terminal it stops.
+ * Each step's text prints as it finishes, so the explanation is on screen before the send asks anything: on stdout, or with `json` on stderr, so stdout holds the one document. One `join-step` event per step says which of the closed steps ran and
+ * what it did (done, skipped, or stopped), and nothing else.
+ */
+export declare const poolJoin: (deps: RunDeps, options: {
+    server?: string | undefined;
+    provider?: string | undefined;
+    verbose?: boolean;
+    acceptCovenant?: string | undefined;
+    inEuEeaUk?: string | undefined;
+    harness?: string | undefined;
+    harnessVersion?: string | undefined;
+    invite?: string | undefined;
+    json?: boolean;
+    plan?: boolean;
+}) => Promise<Outcome>;
+/** The one line an invitee runs. `<version>` stays a placeholder: the harness version is the invitee's own to name. */
+export declare const joinLineOf: (code: string) => string;
+/**
+ * `oars pool invite`: makes one invite code (`POST /v1/invites`, a founding or standing account, three open at most) and prints it once with the line to hand on and what the vouch gives. The code is the only secret here, so it is the one thing the pool never shows again.
+ */
+export declare const poolInvite: (deps: RunDeps, options: {
+    server?: string | undefined;
+}) => Promise<Outcome>;
 /** The raw prompt, in plain words: shown by `oars pool raw` until it is answered, and what the detached sender relies on. Redaction is best effort and the text says so. */
 export declare const RAW_PROMPT: string;
 /** What a person types to say yes to the raw prompt: consent is a statement made at a terminal (GDPR Articles 7 and 9(2)(a)), not a flag a script can pass. */