@manyoars/oars 0.5.3 → 0.5.5

package/dist/sessions/pool-command.js

@@ -5,22 +5,24 @@ import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { emitOf } from '../telemetry/emit.js';
+import { JOIN_STEPS } from '../telemetry/words.js';
 import { CliError, exitCodeForProblem, ExitCode, unreachableError } from '../errors.js';
 import { compileAllow } from './allow.js';
 import { makeCoverage, readCoverageSetting, writeCoverageSetting } from './coverage.js';
 import { checkSession, exclusionPaths, lastWritten, loadTerms, transcriptFilesOf } from './exclusion.js';
 import { localNames, makeRedactor, REDACTION_VERSION, redactTranscript } from './redact.js';
 import { recordSend, recordWire, newTally, tallyBatch } from '../telemetry/wire.js';
-import { discardStale, FIELD_ROWS, fieldsOf, heldAcross, lockedAcross, rescanPulled, machineKeys, markShown, noteMachineKey, outboxFolder, partsOf, pulledAt, removeBatchesExcept, removeBatchOf, staleBatches, unchangedBytes, writeBatch } from './pool-outbox.js';
+import { discardStale, FIELD_ROWS, fieldsOf, heldAcross, lockedAcross, namesHeldAcross, shownHashes, wasShown, rescanPulled, machineKeys, markShown, noteMachineKey, outboxFolder, partsOf, pulledAt, readPulled, readRemoved, removeBatchesExcept, removeBatchOf, staleBatches, unchangedBytes, writeBatch, writePulled, writeRemoved } from './pool-outbox.js';
 import { deriveConsequences } from './recall-consequence.js';
 import { readRecalls } from './recall-object.js';
 import { HARNESSES, hasEnded, ORG_SIZES, REPO_VISIBILITIES, SESSION_IDLE_HOURS, isBundleVersion, isHarness, parseSkeleton, recommendationsOf, sessionsOf, skeletonOf, unpinnedKid, VOCAB_VERSION, verifyBundle } from './pool-wire.js';
-import { carriedDeltas, heldDeltas, keptDeltas, markDeltasSent, placedOf, sentDeltas } from './pool-delta.js';
+import { keepCrewNumber } from './crew-mark.js';
+import { carriedDeltasByWindow, heldDeltas, keptDeltas, markDeltasSent, placedOf, sentDeltas } from './pool-delta.js';
 import { Masker, printed, TRANSPORT_HEADERS, waitWords } from './pool-print.js';
 import { rawAllowed, rawStale, sendsOf } from './pool-choices.js';
 import { heldRaw, rawParts, removeRawExcept, writeRaw } from './pool-raw.js';
 import { SendInterrupted, SendLockBusy, watchInterrupt, withSendLock } from './pool-send-lock.js';
-import { markSent, retirePulled, sentLog } from './pool-sent.js';
+import { markSent, retirePulled, sentHashes, sentLog } from './pool-sent.js';
 import { shellReader } from './projection.js';
 import { isVocabularyExpired, REGISTRY_MAX_AGE_DAYS, VOCAB_SNAPSHOT_DATE } from './public-vocabulary.js';
 import { contentHash, FIRST_ORDER_FAMILIES } from './read.js';
@@ -29,7 +31,7 @@ import { CAPTURE_VERSION, harnessOf as sessionHarness } from './schema.js';
 import { machineIdOf } from './machine-ids.js';
 import { machineOf } from './machine.js';
 import { scanCache } from './machine-scan-cache.js';
-import { loadStore, localSalt, readRedactDomains, readSkeletons, readState, updatePoolChoices } from './store.js';
+import { loadStore, paths, scanLog, localSalt, readRedactDomains, readSkeletons, readState, updatePoolChoices } from './store.js';
 import { runGit } from './survival.js';
 import { vocabulary } from './vocab-load.js';
 import { mkdirOwnerOnly, writeOwnerOnly } from './owner-only.js';
@@ -37,6 +39,7 @@ const LOGIN = 'pool-login';
 const LOGOUT = 'pool-logout';
 export const DEPOSIT = 'pool-deposit';
 const OUTBOX = 'pool-outbox';
+const REMOVE = 'pool-remove';
 const POOL_DEPOSITS = '/v1/deposits';
 const FETCH = 'pool-fetch';
 const EXPORT = 'pool-export';
@@ -74,9 +77,14 @@ export const runtimeOf = (deps) => {
         throw new CliError('The session store is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
     return deps.sessions;
 };
-export const signedIn = async (deps, storeDir, server, step) => {
+/** The sign-in held for this server that has not expired, or undefined. */
+const heldSignIn = async (deps, storeDir, server, step) => {
     const found = (await loadSignIns(storeDir, step)).find((entry) => entry.server === server);
-    if (found === undefined || found.expiresAt <= deps.now())
+    return found === undefined || found.expiresAt <= deps.now() ? undefined : found;
+};
+export const signedIn = async (deps, storeDir, server, step) => {
+    const found = await heldSignIn(deps, storeDir, server, step);
+    if (found === undefined)
         throw new CliError(`Not signed in to ${server}. Run oars pool login first.`, ExitCode.AUTH, step);
     return found;
 };
@@ -105,19 +113,22 @@ export const ask = (deps, step, server, path, init, via) => {
 /** The pool took the request and then said nothing for `Guard.stallMs`. */
 class PoolStalled extends Error {
 }
-/** A newcomer's words for the network failures a stalled or restarted pool produces; the raw reason follows the sentence in parentheses. */
+/** A newcomer's words for the network failures a stalled or restarted pool produces; the raw reason follows the sentence in parentheses. The flag marks a failure that comes after the request began to go out, where the pool may hold the batch: a refused, unresolved, or connect-timed-out connection fails before any of it was sent, while ETIMEDOUT can also come from a retransmit timeout on an open socket after the body was written. */
 const PLAIN_REASONS = [
-    [/ECONNRESET|socket hang up|UND_ERR_SOCKET/, 'the connection was dropped before the pool answered'],
-    [/ECONNREFUSED/, 'nothing is listening there'],
-    [/ENOTFOUND|EAI_AGAIN/, 'that name did not resolve'],
-    [/ETIMEDOUT|UND_ERR_CONNECT_TIMEOUT/, 'the connection timed out'],
-    [/EPIPE/, 'the connection closed while the batch was going out'],
+    [/ECONNRESET|socket hang up|UND_ERR_SOCKET/, 'the connection was dropped before the pool answered', true],
+    [/ECONNREFUSED/, 'nothing is listening there', false],
+    [/ENOTFOUND|EAI_AGAIN/, 'that name did not resolve', false],
+    [/UND_ERR_CONNECT_TIMEOUT/, 'the connection timed out', false],
+    [/ETIMEDOUT/, 'the connection timed out', true],
+    [/EPIPE/, 'the connection closed while the batch was going out', true],
 ];
 const NOT_MARKED = 'Nothing was marked sent.';
 const TRY_AGAIN = 'Run the same command to try again.';
 const RETRY = `${NOT_MARKED} ${TRY_AGAIN}`;
 /** Said after a stop or a stall once the request carrying the batch had gone out: the pool may hold it even though nothing here saw the answer. */
 const MAY_HAVE_RECEIVED = 'The pool may already have received it.';
+/** How many sessions a build reads and writes at once: the most whose prompts and tools are in memory together. */
+const BUILD_CHUNK = 100;
 /** What `deposit` says after it writes the outbox: the covenant (the person's consent, docs/covenant 2.1) already lets the background sender send what is queued, with or without this command. A machine's batches are never sent by it. */
 const SENT_LATER = 'Nothing was sent yet. Once the covenant is accepted, oars sends what is queued automatically, in the background.';
 /**
@@ -131,16 +142,18 @@ export const stoppedText = (received) => [
     'To keep a folder out, run oars pool raw --folder <folder> --mode off.',
     'To stop this machine sending, run oars pool logout.',
 ].join('\n');
+/** The failure for a send the person or the launcher ended: Ctrl-C (SIGINT) exits 130, the shell convention, and any other way of stopping keeps the unexpected code. The text is the same for all of them. */
+const stopped = (step, cause, received) => new CliError(stoppedText(received), cause.signal === 'SIGINT' ? ExitCode.INTERRUPTED : ExitCode.UNEXPECTED, step);
 /** Why a guarded request ended without an answer, in plain words: a stall, an interrupt, or a network failure whose raw reason is kept after the sentence. The exit code is the unreachable one, as before. */
 const guardedFailure = (step, cause, origin, guard, received) => {
     if (cause instanceof PoolStalled)
         return new CliError(`The pool at ${origin} did not answer within ${String(guard.stallMs / 1000)} seconds. ${received ? `${NOT_MARKED} ${MAY_HAVE_RECEIVED} ${TRY_AGAIN}` : RETRY}`, ExitCode.UNREACHABLE, step);
     if (cause instanceof SendInterrupted)
-        return new CliError(stoppedText(received), ExitCode.UNEXPECTED, step);
+        return stopped(step, cause, received);
     const unreachable = unreachableError(step, cause, origin);
     const raw = unreachable.message.slice(`Cannot reach the server at ${origin}: `.length);
     const plain = PLAIN_REASONS.find(([pattern]) => pattern.test(raw));
-    return plain === undefined ? unreachable : new CliError(`Cannot reach the pool at ${origin}: ${plain[1]} (${raw}). ${RETRY}`, ExitCode.UNREACHABLE, step);
+    return plain === undefined ? unreachable : new CliError(`Cannot reach the pool at ${origin}: ${plain[1]} (${raw}). ${received && plain[2] ? `${NOT_MARKED} ${MAY_HAVE_RECEIVED} ${TRY_AGAIN}` : RETRY}`, ExitCode.UNREACHABLE, step);
 };
 /** Prints the request when asked to, then sends exactly those headers and that body. A guarded request also ends when its stall time passes or its signal aborts, and fails in plain words. */
 const send = async (deps, step, request, show, binary = false, guard) => {
@@ -218,15 +231,42 @@ const closedProof = (reply) => {
 ${proofLines(account, provedAt)}`;
     return new CliError(refused.message, refused.exitCode, LOGIN, { ...refused.problem, detail }, { account, provedAt });
 };
+/** A promise that rejects with the signal's reason once it aborts, so a wait can be raced against it, and the `dispose` that removes its listener once the wait has settled. */
+const abortion = (signal) => {
+    let dispose = () => undefined;
+    const promise = new Promise((_resolve, reject) => {
+        const why = () => (signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+        const onAbort = () => { reject(why()); };
+        if (signal.aborted)
+            reject(why());
+        else {
+            signal.addEventListener('abort', onAbort, { once: true });
+            dispose = () => { signal.removeEventListener('abort', onAbort); };
+        }
+    });
+    return { promise, dispose };
+};
 /** Polls the pool until the person approves, and returns the pool's answer with the credential. Time is counted in the waits asked for, so a machine that slept through the code still gets one poll that says it expired. */
-const awaitCredential = async (deps, server, started, show) => {
+const awaitCredential = async (deps, server, started, show, signal) => {
     let { intervalMs } = started;
     let failures = 0;
     let lastFailure;
     for (let waited = 0; waited < started.expiresMs;) {
         // A failed poll (a network error or a 5xx) is the provider or the network having a bad minute, not the person's answer: wait longer each time, up to the cap, and ask again until the code's own expiry.
         const wait = Math.min(intervalMs * 2 ** failures, Math.max(intervalMs, MAX_BACKOFF_MS));
-        await deps.sleep(wait);
+        if (signal === undefined)
+            await deps.sleep(wait);
+        else {
+            const aborted = abortion(signal);
+            try {
+                await Promise.race([deps.sleep(wait), aborted.promise]);
+            }
+            finally {
+                aborted.dispose();
+            }
+        }
+        // A sleep that finished first still ends the poll once the signal has fired.
+        signal?.throwIfAborted();
         waited += wait;
         // `ask` rejects only with the unreachable failure of `send`.
         const [settled] = await Promise.allSettled([ask(deps, LOGIN, server, '/v1/login/poll', { body: { handle: started.handle }, show })]);
@@ -290,7 +330,7 @@ export const poolLogin = async (deps, options) => {
     await deps.openBrowser(started.verificationUrl).catch(() => {
         deps.io.stderr('Could not open a browser; open the link above yourself.\n');
     });
-    const reply = await awaitCredential(deps, server, started, show);
+    const reply = await awaitCredential(deps, server, started, show, options.signal);
     const signIn = signInOf(isObject(reply.body) ? { ...reply.body, server } : undefined);
     if (signIn === undefined)
         throw new CliError('The pool answered a sign-in with no account, token, or signing key.', ExitCode.UNEXPECTED, LOGIN);
@@ -369,8 +409,23 @@ export const OFFER_BEFORE = [
     'The covenant is the whole deal. Its full text is linked below. Read it before you type.',
 ];
 export const OFFER_AFTER = ['Accepted. Sending your batch now.', 'Run oars pool fetch --help for your first pool download.'];
+const readerOf = (deps, signal) => {
+    const lines = createInterface({ input: runtimeOf(deps).stdin, terminal: false, ...(signal === undefined ? {} : { signal }) });
+    const iterator = lines[Symbol.asyncIterator]();
+    return {
+        next: async () => {
+            const next = await iterator.next();
+            if (signal?.aborted === true)
+                throw signal.reason;
+            return next.done === true ? undefined : next.value;
+        },
+        close: () => {
+            lines.close();
+        },
+    };
+};
 /** A send stops here when the server is closed or wants a covenant accepted, before the batch is read for the last time. */
-const openCovenant = async (deps, server, token, accept, region, via, signal) => {
+const openCovenant = async (deps, server, token, accept, region, via, signal, offTerminal = () => Promise.resolve('run this command from one'), refuseAtTerminal = false, shared) => {
     const reply = await ask(deps, DEPOSIT, server, '/v1/covenant', { token }, via);
     if (reply.status !== 200 || !isObject(reply.body))
         throw refusal(DEPOSIT, reply);
@@ -385,47 +440,48 @@ const openCovenant = async (deps, server, token, accept, region, via, signal) =>
     if (accept !== undefined && accept !== version)
         throw usage(`--accept-covenant names covenant ${accept}, but the covenant of this pool is ${version}. Nothing was accepted.`, DEPOSIT);
     if (Reflect.get(reply.body, 'accepted') === true)
-        return;
+        return false;
     const notAccepted = (title) => new CliError(title, ExitCode.AUTH, DEPOSIT, { code: 'covenant_not_accepted', title, status: 403 });
     const screen = screenIn(reply.body);
     if (screen === undefined)
         throw notAccepted(`The pool has no text for covenant ${version} yet, so there is nothing to show and nothing can be accepted. Nothing was accepted.`);
     // Assent is a person typing the phrase the screen states. A flag or a script on stdin is not one, so off a terminal nothing is asked and nothing is accepted.
-    if (!isTerminal(deps)) {
-        throw notAccepted(`Covenant ${version} is not accepted for this account. Accepting it takes a person at a terminal who reads it and types its phrase: run this command from one. Nothing was accepted.`);
+    // A bulk send never shows the screen: a person reads and accepts through the one-batch command, so a terminal is refused the same way.
+    if (refuseAtTerminal || !isTerminal(deps)) {
+        throw notAccepted(`Covenant ${version} is not accepted for this account. Accepting it takes a person at a terminal who reads it and types its phrase: ${await offTerminal()}. Nothing was accepted.`);
     }
     deps.io.stderr(`${OFFER_BEFORE.join('\n')}\n`);
     deps.io.stderr(`\n${screen.text}\n\n> `);
     emitOf(deps)('covenant-shown', { version });
-    // One reader for both lines: a second one opened after the first closed would lose a line the first had already taken from a pipe.
-    // A stop signal (Ctrl-C, a closed terminal) closes the reader, so a read that is waiting for the person ends with the signal's reason instead of holding the process open.
-    const lines = createInterface({ input: runtimeOf(deps).stdin, terminal: false, ...(signal === undefined ? {} : { signal }) });
-    const iterator = lines[Symbol.asyncIterator]();
-    const nextLine = async () => {
-        const next = await iterator.next();
-        if (signal?.aborted === true)
-            throw signal.reason;
-        return next.done === true ? undefined : next.value;
-    };
+    // One reader for both lines: a second one opened after the first closed would lose a line the first had already taken from a pipe. A join passes its own, which also served the questions before this one.
+    const lines = shared ?? readerOf(deps, signal);
     let answered = region;
     try {
-        const typed = await nextLine();
+        const typed = await lines.next();
         if (typed?.trim() !== screen.phrase)
             throw notAccepted(`${typed === undefined ? 'No phrase was typed' : 'That was not the phrase'}. To accept covenant ${version}, type exactly: ${screen.phrase}. Nothing was accepted.`);
         if (region === undefined) {
             deps.io.stderr(`${REGION_QUESTION} > `);
-            answered = regionOf(await nextLine());
+            answered = regionOf(await lines.next());
         }
     }
     finally {
-        lines.close();
+        if (shared === undefined)
+            lines.close();
     }
     if (answered === undefined)
         throw notAccepted('Answer yes or no: are you in the EU, the EEA, or the UK? Nothing was accepted.');
     const body = { version, textSha256: createHash('sha256').update(screen.text).digest('hex'), input: 'typed', client: `oars/${deps.version}`, euEeaUk: answered };
     const accepted = await ask(deps, DEPOSIT, server, '/v1/covenant/accept', { token, body }, via);
-    if (accepted.status !== 200)
-        throw refusal(DEPOSIT, accepted);
+    if (accepted.status !== 200) {
+        const refused = refusal(DEPOSIT, accepted);
+        // A join keeps the answer to the region question for its reruns, so a mistyped yes would be refused again every time: name the way to correct it.
+        if (shared === undefined || refused.problem.code !== 'region_closed')
+            throw refused;
+        // A no that was refused on the request's origin is not a mistake to correct.
+        const title = answered === 'yes' ? `${refused.message} If you answered yes by mistake, run oars pool join --in-eu-eea-uk no to correct it.` : refused.message;
+        throw new CliError(title, refused.exitCode, DEPOSIT, { code: 'region_closed', title, status: 403 });
+    }
     deps.io.stderr(`${OFFER_AFTER.join('\n')}\n`);
     // A yes to the raw prompt belongs to the covenant it was given under, and a covenant can change what that prompt covers: accepting another version asks the raw question again.
     const reset = { done: false };
@@ -438,6 +494,7 @@ const openCovenant = async (deps, server, token, accept, region, via, signal) =>
     });
     if (reset.done)
         deps.io.stderr('Your earlier yes to the raw prompt was given under another covenant, so it no longer applies. Run oars pool raw to read the prompt and answer again.\n');
+    return true;
 };
 const screenIn = (body) => {
     const screen = Reflect.get(body, 'screen');
@@ -570,7 +627,138 @@ const sendBatch = async (deps, options) => {
         if (error instanceof SendLockBusy)
             throw refuse('send_locked', busyLine(error.detail));
         if (error instanceof SendInterrupted)
-            throw new CliError(stoppedText(false), ExitCode.UNEXPECTED, DEPOSIT);
+            throw stopped(DEPOSIT, error, false);
+        throw error;
+    }
+    finally {
+        interrupt.stop();
+    }
+};
+const reasonOf = (signal) => (signal?.reason instanceof Error ? signal.reason : new Error('Interrupted.'));
+export const sleeps = (ms, signal) => new Promise((resolve, reject) => {
+    // Ctrl-C during a wait ends it with the interrupt, instead of being ignored until the wait is over.
+    if (signal?.aborted === true) {
+        reject(reasonOf(signal));
+        return;
+    }
+    const abort = () => {
+        clearTimeout(timer);
+        reject(reasonOf(signal));
+    };
+    const timer = setTimeout(() => {
+        signal?.removeEventListener('abort', abort);
+        resolve();
+    }, ms);
+    signal?.addEventListener('abort', abort, { once: true });
+});
+const retrying = (via, pause, signal) => async (request) => {
+    for (let attempt = 1;; attempt += 1) {
+        const reply = await via(request);
+        if ((reply.status !== 429 && reply.status < 500) || attempt >= SEND_ATTEMPTS)
+            return reply;
+        const named = Number(reply.headers.get('retry-after'));
+        await pause(Number.isFinite(named) && named > 0 ? Math.min(named, 30) * 1000 : 1000 * 2 ** (attempt - 1), signal);
+    }
+};
+/** Batches between two progress lines of `--send-all`. */
+const PROGRESS_EVERY = 100;
+/**
+ * `deposit --send-all`: the lock and the covenant of `--send`, once, then every batch of the outbox in name order, one file read at a time. A batch whose hash `sent.log` holds is not sent again, which is what makes a rerun send only what is left (the log is
+ * written after each batch, so a run that stops loses at most the one in flight, and the pool reads a batch sent again as the same deposit). A batch that `oars pool outbox` never printed, that changed on disk, or that a pulled-batch rule holds back is skipped and counted.
+ * The first batch that fails ends the run: the counts print, and the error goes up with its own exit code. Only counts and hashes print, never a session's content.
+ */
+const sendAll = async (deps, options) => {
+    const { outbox, server, token } = options;
+    const refuse = (code, title) => new CliError(title, ExitCode.CONFLICT, DEPOSIT, { code, title, status: 409 });
+    const interrupt = watchInterrupt();
+    const net = options.via ?? networkSender(deps, DEPOSIT, { stallMs: SEND_STALL_MS, signal: interrupt.signal });
+    const via = retrying(net, options.pause ?? sleeps, interrupt.signal);
+    try {
+        return await withSendLock(outbox, async () => {
+            const scan = await rescanPulled(outbox, await currentTerms(deps));
+            const done = await sentHashes(outbox);
+            const shown = await shownHashes(outbox);
+            // The one-batch command that shows the screen: the first batch that was shown and is not sent.
+            const oneBatch = async () => {
+                for await (const named of namesHeldAcross(outbox)) {
+                    if (shown.has(named.hash) && !done.has(named.hash) && !(named.pulled && !scan.open) && (await unchangedBytes(named.file, named.hash)) !== undefined)
+                        return `run oars pool deposit --send ${named.hash} at a terminal to read it and accept`;
+                }
+                return 'run oars pool deposit --send <hash> at a terminal to read it and accept';
+            };
+            await openCovenant(deps, server, token, options.acceptCovenant, options.region, via, interrupt.signal, oneBatch, true);
+            const tally = { sent: 0, skipped: 0, alreadySent: 0, failed: 0, left: 0 };
+            const handled = new Set();
+            const line = () => `${String(tally.sent)} sent, ${String(tally.skipped)} skipped, ${String(tally.alreadySent)} already sent, ${String(tally.failed)} failed, ${String(tally.left)} left`;
+            let ended;
+            try {
+                for await (const named of namesHeldAcross(outbox)) {
+                    handled.add(named.hash);
+                    if (done.has(named.hash)) {
+                        tally.alreadySent += 1;
+                    }
+                    else {
+                        // Read now, hashed again, and sent: the one batch in memory. A file that no longer hashes to its name is the "changed" case.
+                        const bytes = shown.has(named.hash) && !(named.pulled && !scan.open) ? await unchangedBytes(named.file, named.hash) : undefined;
+                        if (bytes === undefined) {
+                            tally.skipped += 1;
+                        }
+                        else {
+                            try {
+                                await postBatch(deps, { server, token, bytes, hash: named.hash, via });
+                            }
+                            catch (error) {
+                                tally.failed = 1;
+                                throw error;
+                            }
+                            await markSent(outbox, named.hash, deps.now());
+                            tally.sent += 1;
+                        }
+                    }
+                    const count = tally.sent + tally.skipped + tally.alreadySent;
+                    if (count % PROGRESS_EVERY === 0)
+                        deps.io.stderr(`${String(count)} batches handled: ${line()}.
+`);
+                }
+            }
+            catch (error) {
+                ended = { error };
+            }
+            // A pulled batch whose hash is in `sent.log` is done, however the run ended; an error of the loop wins over one of the retiring.
+            try {
+                await retirePulled(outbox, DEPOSIT);
+            }
+            catch (error) {
+                if (ended === undefined)
+                    throw error;
+            }
+            if (ended !== undefined) {
+                // Shown, not sent, not reached: counted by name alone, without reading a file. A batch a rerun would skip (never shown) is not left.
+                for await (const named of namesHeldAcross(outbox)) {
+                    if (!handled.has(named.hash) && !done.has(named.hash) && shown.has(named.hash) && !(named.pulled && !scan.open))
+                        tally.left += 1;
+                }
+                deps.io.stderr(`Stopped: ${line()}. Run the same command again to send what is left.
+`);
+                // The counts reach the --json failure document too, not only stderr.
+                if (ended.error instanceof CliError)
+                    throw new CliError(ended.error.message, ended.error.exitCode, ended.error.step, ended.error.problem, { ...ended.error.details, tally });
+                throw ended.error;
+            }
+            return { document: { ok: true, server, ...tally }, text: `Done: ${line()}.` };
+        }, options.lock?.times, options.lock?.fs, {
+            onWait: (waiting) => {
+                deps.io.stderr(`${waitingLine(waiting)}
+`);
+            },
+            signal: interrupt.signal,
+        });
+    }
+    catch (error) {
+        if (error instanceof SendLockBusy)
+            throw refuse('send_locked', busyLine(error.detail));
+        if (error instanceof SendInterrupted)
+            throw stopped(DEPOSIT, error, false);
         throw error;
     }
     finally {
@@ -604,6 +792,68 @@ export const busyLine = ({ holder, local, ageMs, untouchedMs, waitedMs, staleMs
         return `${held} A retry succeeds as soon as pid ${String(holder.pid)} ends.`;
     return `${held} Run the same command again once it ends. If it has hung, oars takes the lock over about ${span(Math.max(1, staleMs - untouchedMs))} from now.`;
 };
+/** The session id behind an outbox key, found by deriving the key of each session in the store the way `poolDeposit` does: under every account signed in to this server, or under the machine's environment. `undefined` when the store no longer holds the session. */
+const sessionOfKey = async (deps, storeDir, server, key) => {
+    const machine = machineOf(deps.env);
+    const accounts = machine === undefined ? (await loadSignIns(storeDir, REMOVE)).filter((entry) => entry.server === server).map((entry) => entry.account) : [];
+    const keysOf = (session) => (machine === undefined ? accounts.map((account) => contentHash([account, session])) : [machineKeyOf(machine, session)]);
+    return (await loadStore(storeDir)).sessions.map((observed) => observed.session).find((session) => keysOf(session).includes(key));
+};
+/**
+ * `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 const poolRemove = async (deps, hash, options) => {
+    const runtime = runtimeOf(deps);
+    const server = poolServer(deps.env, REMOVE, options.server);
+    if (!/^[0-9a-f]{64}$/.test(hash))
+        throw usage('remove takes the SHA-256 that oars pool outbox printed: 64 hexadecimal characters.', REMOVE);
+    const outbox = outboxFolder(runtime.storeDir, server);
+    const refuse = (code, title) => new CliError(title, ExitCode.CONFLICT, REMOVE, { code, title, status: 409 });
+    try {
+        return await withSendLock(outbox, async () => {
+            if (options.restore === true) {
+                const removed = await readRemoved(outbox, REMOVE);
+                const key = Object.keys(removed).find((candidate) => removed[candidate]?.hash === hash);
+                if (key === undefined)
+                    throw refuse('removal_unknown', 'No removed batch has that hash, so nothing was restored. The hash is the one oars pool remove printed when it removed the batch.');
+                Reflect.deleteProperty(removed, key);
+                await writeRemoved(outbox, removed);
+                return { document: { ok: true, server, hash, restored: true }, text: `Restored the session of batch ${hash} for ${server}. Nothing was sent. A later oars pool deposit builds it again while the session passes the gates.` };
+            }
+            const removed = await readRemoved(outbox, REMOVE);
+            const found = (await heldAcross(outbox)).batches.find((batch) => batch.hash === hash);
+            if (found === undefined)
+                throw refuse('batch_unknown', 'No batch with that hash is in the outbox, so nothing was removed. Run oars pool outbox to list them.');
+            // The session goes on the list first: the build pass would otherwise rebuild it on its next run, the background sender's included, and send what the person withdrew (GDPR Article 7(3)). A list that cannot be read has already failed above, with the batch untouched.
+            const session = found.pulled ? undefined : await sessionOfKey(deps, runtime.storeDir, server, found.key);
+            if (!found.pulled)
+                await writeRemoved(outbox, { ...removed, [found.key]: session === undefined ? { hash } : { hash, session } });
+            await rm(found.file, { force: true });
+            // The session's queued raw copies go in the same lock: the background sender posts every raw copy it holds without looking for its batch, and a batch the person withdrew must take the session's transcript with it (GDPR Article 7(3)). A pulled batch never had one here.
+            const rawGone = await removeRawExcept(outbox, new Set(), found.key);
+            if (found.pulled) {
+                const pulled = await readPulled(outbox, REMOVE);
+                Reflect.deleteProperty(pulled, found.key);
+                await writePulled(outbox, pulled);
+            }
+            const sentAt = (await sentLog(outbox)).get(hash);
+            const text = [
+                `Removed batch ${hash} from the outbox for ${server}. Nothing was sent, and nothing at the pool changed.`,
+                ...(rawGone === 0 ? [] : [`${String(rawGone)} queued raw ${rawGone === 1 ? 'copy' : 'copies'} of the same session went with it.`]),
+                ...(sentAt === undefined ? [] : [`It was already sent at ${sentAt}; removing it here does not take it back from the pool.`]),
+                ...(found.pulled ? ['It came from a cloud session: only oars pool hold pull admits it again.'] : [`Its session stays out of every later oars pool deposit, the background sender's included, until you run oars pool remove ${hash} --restore.`]),
+                ...(found.pulled || session !== undefined ? [] : ['No session in the store matches it, so the exclusion holds for this account and machine settings only.']),
+            ].join('\n');
+            return { document: { ok: true, server, hash, removed: true }, text };
+        }, { ...options.lock?.times, waitMs: 0 }, options.lock?.fs);
+    }
+    catch (error) {
+        if (error instanceof SendLockBusy)
+            throw refuse('send_locked', `Another oars run${error.detail.holder === undefined ? '' : ` (pid ${String(error.detail.holder.pid)})`} holds this outbox's send lock, so nothing was removed. Run the same command again once it ends.`);
+        throw error;
+    }
+};
 /** The covenant version the pool names, or `undefined` when it cannot be asked or names none. The route is public, so no credential goes with it. */
 const covenantOrUndefined = async (deps, server) => {
     try {
@@ -627,14 +877,21 @@ export const poolDeposit = async (deps, options) => {
     const server = poolServer(deps.env, DEPOSIT, options.server);
     // A machine (`OARS_HOST_CLASS`, see machine.ts) builds at every Stop and sends nothing from here, so it signs nobody in: the account part of its batch key is its own name, and the holding route's `id` replaces it.
     const machine = machineOf(deps.env);
-    if (machine !== undefined && options.send !== undefined)
-        throw usage('A machine builds batches into its outbox and sends none: --send is for a signed-in person.', DEPOSIT);
+    if (options.send !== undefined && options.sendAll === true)
+        throw usage('--send and --send-all together: --send sends the one batch whose hash you name, and --send-all sends every batch that oars pool outbox printed. Use one. Nothing was sent.', DEPOSIT);
+    if (machine !== undefined && (options.send !== undefined || options.sendAll === true))
+        throw usage('A machine builds batches into its outbox and sends none: --send and --send-all are for a signed-in person.', DEPOSIT);
     const { account, token } = machine === undefined ? await signedIn(deps, runtime.storeDir, server, DEPOSIT) : { account: machineAccount(machine), token: '' };
     // A client past `registry_max_age` builds no batch (spec Section 1.3): its sessions wait in `A` and nothing is lost. This comes before anything is written or sent.
     const expired = vocabularyExpired(deps);
     if (expired !== undefined)
         throw expired;
     // Accepting the covenant is a step of sending a batch: alone it would exit 0 as though something had been sent under it.
+    const accepting = 'accept with oars pool deposit --send <hash>, which shows the covenant screen';
+    if (options.sendAll === true && options.acceptCovenant !== undefined)
+        throw usage(`--accept-covenant belongs to --send: --send-all never accepts a covenant, so ${accepting}. Nothing was accepted.`, DEPOSIT);
+    if (options.sendAll === true && options.inEuEeaUk !== undefined)
+        throw usage(`${REGION_FLAG} belongs to --send: --send-all never accepts a covenant, so ${accepting}. Nothing was accepted.`, DEPOSIT);
     if (options.send === undefined && options.acceptCovenant !== undefined)
         throw usage('--accept-covenant belongs to --send: it names the covenant version expected when a person accepts before a send. Nothing was accepted.', DEPOSIT);
     if (options.send === undefined && options.inEuEeaUk !== undefined)
@@ -644,6 +901,8 @@ export const poolDeposit = async (deps, options) => {
         throw usage(`${REGION_FLAG} takes yes or no, not "${options.inEuEeaUk}". Nothing was accepted.`, DEPOSIT);
     const outbox = outboxFolder(runtime.storeDir, server);
     await mkdirOwnerOnly(outbox);
+    if (options.sendAll === true)
+        return sendAll(deps, { outbox, server, token, acceptCovenant: options.acceptCovenant, region, via: options.via, lock: options.lock, pause: options.pause });
     if (options.send !== undefined)
         return sendBatch(deps, { outbox, server, token, hash: options.send, acceptCovenant: options.acceptCovenant, region, via: options.via, lock: options.lock });
     const { terms } = exclusionPaths(runtime.projectsRoot, deps.env);
@@ -655,7 +914,7 @@ export const poolDeposit = async (deps, options) => {
     const injectedKey = `injected-block:${(await localSalt(runtime.storeDir)).salt}`;
     const allow = compileAllow(saved.allow);
     const discarded = await discardStale(outbox);
-    const counts = { sessions: 0, batched: 0, excluded: { folder: 0, term: 0, noRaw: 0, noTerms: 0, unreadable: 0 }, off: 0, raw: { copies: 0, bytes: 0, masked: 0 }, uncaptured: 0, notEnded: 0, refused: 0, refusedFields: [], discarded, withdrawn: 0 };
+    const counts = { sessions: 0, batched: 0, excluded: { folder: 0, term: 0, noRaw: 0, noTerms: 0, unreadable: 0 }, off: 0, raw: { copies: 0, bytes: 0, masked: 0 }, uncaptured: 0, removedByPerson: 0, notEnded: 0, refused: 0, refusedFields: [], discarded, withdrawn: 0 };
     // The one gate on a name: the operator's redactor and exclusion terms (t881). Everything else the pool classes itself.
     const termList = await loadTerms(terms);
     const gate = { redact: makeRedactor(await readRedactDomains(runtime.storeDir)), terms: termList };
@@ -669,6 +928,7 @@ export const poolDeposit = async (deps, options) => {
     const refusedFields = new Set();
     const roots = new Map((await readSkeletons(runtime.storeDir, undefined, true)).skeletons.map(({ session, merkleRoot, leaves }) => [session, { merkleRoot, leaves }]));
     // The sessions that pass both gates and have ended, in the order the store holds them: the windows of a delta are counted over these alone, and the batch of each is built after, once its deltas are known.
+    // Only the session records are held for the gates; a session's prompts and tools are read again when its window or its batch needs them (BUILD_CHUNK at a time), so the history is never in memory at once.
     const ready = [];
     // A session that fails a gate loses its earlier batch at once, so a later throw in this pass cannot leave one in the outbox.
     const withdraw = async (key) => {
@@ -677,7 +937,27 @@ export const poolDeposit = async (deps, options) => {
     };
     // The sessions a Stop does not name that still pass the read-only gates: they only fill the windows of a delta, and are never counted, withdrawn, or built.
     const history = [];
-    const localStore = await loadStore(runtime.storeDir);
+    // One scan of the log for the whole build: the head read and every chunk read take its revs, so a deposit reads the log's revs once, not once per chunk.
+    const { latest, spans, identity } = await scanLog(paths(runtime.storeDir).observations, undefined, true);
+    await runtime.afterScan?.();
+    const localStore = await loadStore(runtime.storeDir, undefined, { sessionsOnly: true, latest });
+    const childrenOf = new Map();
+    for (const agent of localStore.subagents) {
+        const parent = agent.parent ?? '';
+        const list = childrenOf.get(parent) ?? [];
+        list.push(agent.session);
+        childrenOf.set(parent, list);
+    }
+    // The full records of some sessions (and their subagents), read from the log with nothing else.
+    const readRecords = async (ids) => {
+        const store = await loadStore(runtime.storeDir, undefined, { latest, spans, identity, only: new Set([...ids].flatMap((id) => [id, ...(childrenOf.get(id) ?? [])])) });
+        return { store, records: new Map(sessionsOf(store, roots).map((records) => [records.main.session, records])) };
+    };
+    // A damaged list stops the pass before anything is built: it must never read as "nothing was removed".
+    const removedList = await readRemoved(outbox, DEPOSIT);
+    const removedKeys = new Set(Object.keys(removedList));
+    // By session id too: the key follows the account and the machine's environment, so a login under another account would otherwise build the same session again.
+    const removedSessions = new Set(Object.values(removedList).flatMap((entry) => (entry.session === undefined ? [] : [entry.session])));
     for (const records of sessionsOf(localStore, roots)) {
         // The Stop of a machine builds the one session that stopped: the others in the store belong to Stops of their own, so their batches stay as they are. They run the three read-only gates below and no more.
         const named = options.session === undefined || records.main.session === options.session;
@@ -685,6 +965,12 @@ export const poolDeposit = async (deps, options) => {
             counts.sessions += 1;
         // Hashed with the account, so a redeposit replaces its own batch and two accounts' copies of one session cannot be joined.
         const key = machine === undefined ? contentHash([account, records.main.session]) : machineKeyOf(machine, records.main.session);
+        // Withdrawn by the person with `oars pool remove`: nothing of the session is built, queued, or read for a window, and its batch and raw copies are already gone.
+        if (removedKeys.has(key) || removedSessions.has(records.main.session)) {
+            if (named)
+                counts.removedByPerson += 1;
+            continue;
+        }
         if (!allow.allows(records.main.project)) {
             if (named) {
                 counts.excluded.folder += 1;
@@ -728,50 +1014,56 @@ export const poolDeposit = async (deps, options) => {
     // A delta is built from the sessions that passed, carried by the batch of the session that filled its after window, and marked sent only once that batch is written: a deposit that stops first builds it again.
     // A cloud machine has no history of its own to compare a window against (every VM starts clean), so it carries none.
     const placed = machine?.hostClass === 'cloud' ? [] : [...ready.map(({ records }) => records), ...history].flatMap((records) => placedOf(records) ?? []);
-    const carried = carriedDeltas(account, placed, await sentDeltas(outbox));
+    const carried = await carriedDeltasByWindow(account, placed, await sentDeltas(outbox), async (ids) => (await readRecords(ids)).records, new Set(ready.map(({ records }) => records.main.session)));
     // The coverage bands (t871): the operator's two settings, read here, and the team band counted from the local git log. Nothing is looked up, and anything unread goes as unknown.
     const coverageOf = makeCoverage(runtime, await readCoverageSetting(runtime.storeDir), options.git ?? runGit);
     // The recommendations each session was shown or held back from, read from the local rows with their windows, so a shown row stays shown at the pool and a session with none sends none (the pool reads that as unknown).
-    const recalls = deriveConsequences(localStore, await readRecalls(runtime.storeDir));
-    for (const { records, key } of ready) {
-        const delta = carried.get(records.main.session);
-        // A machine builds the open session at every Stop and SessionEnd, so the one it names keeps what its own earlier batch carried and takes only what is new; any other deposit builds a session once.
-        const entries = machine !== undefined && options.session !== undefined ? keptDeltas(await heldDeltas(outbox, key), delta?.entries ?? []) : delta?.entries;
-        const skeleton = skeletonOf(records, key, shellReader(vocabulary()), contentHash, entries, gate, await coverageOf(records.main), recommendationsOf(recalls, records.main.session));
-        if (skeleton === null) {
-            counts.uncaptured += 1;
-            await withdraw(key);
-            continue;
-        }
-        const parsed = parseSkeleton(skeleton);
-        // The server reads a value outside its lists as `other` and keeps a field it does not know, so the parser no longer refuses either: the emitter is the privacy control, and a batch this client built holds neither.
-        const refusedAt = parsed.ok ? parsed.extensions[0]?.at : parsed.field;
-        if (!parsed.ok || refusedAt !== undefined) {
-            counts.refused += 1;
-            refusedFields.add(refusedAt ?? '');
-            await withdraw(key);
-            continue;
-        }
-        // Noted before the batch is written: a person's sweep that runs between the two lines would delete a batch it cannot yet tell is a machine's.
-        if (machine !== undefined)
-            await noteMachineKey(outbox, key);
-        builtBytes += (await writeBatch(outbox, key, parsed.skeleton)).bytes;
-        // The raw copy comes only after both gates and only with a yes to the raw prompt and a folder not at skeleton only: each transcript of the session, redacted here, before it is queued.
-        if (rawAllowed(saved.pool, records.main.project, covenant)) {
-            let place = 0;
-            for (const file of await transcriptFilesOf(runtime, records.main.project, records.main.session)) {
-                const redacted = redactTranscript(await readFile(file.path, 'utf8'), saved.redactDomains, names, injectedKey);
-                counts.raw.bytes += (await writeRaw(outbox, key, place, redacted.text)).bytes;
-                counts.raw.copies += 1;
-                counts.raw.masked += redacted.masked;
-                place += 1;
+    const recorded = await readRecalls(runtime.storeDir);
+    for (let from = 0; from < ready.length; from += BUILD_CHUNK) {
+        const chunk = ready.slice(from, from + BUILD_CHUNK);
+        const { store: chunkStore, records: full } = await readRecords(new Set(chunk.map(({ records }) => records.main.session)));
+        const recalls = deriveConsequences(chunkStore, recorded);
+        for (const { records: head, key } of chunk) {
+            const records = full.get(head.main.session);
+            const delta = carried.get(head.main.session);
+            // A machine builds the open session at every Stop and SessionEnd, so the one it names keeps what its own earlier batch carried and takes only what is new; any other deposit builds a session once.
+            const entries = machine !== undefined && options.session !== undefined ? keptDeltas(await heldDeltas(outbox, key), delta?.entries ?? []) : delta?.entries;
+            const skeleton = records === undefined ? null : skeletonOf(records, key, shellReader(vocabulary()), contentHash, entries, gate, await coverageOf(head.main), recommendationsOf(recalls, head.main.session));
+            if (skeleton === null) {
+                counts.uncaptured += 1;
+                await withdraw(key);
+                continue;
             }
-            rawKept.add(key);
+            const parsed = parseSkeleton(skeleton);
+            // The server reads a value outside its lists as `other` and keeps a field it does not know, so the parser no longer refuses either: the emitter is the privacy control, and a batch this client built holds neither.
+            const refusedAt = parsed.ok ? parsed.extensions[0]?.at : parsed.field;
+            if (!parsed.ok || refusedAt !== undefined) {
+                counts.refused += 1;
+                refusedFields.add(refusedAt ?? '');
+                await withdraw(key);
+                continue;
+            }
+            // Noted before the batch is written: a person's sweep that runs between the two lines would delete a batch it cannot yet tell is a machine's.
+            if (machine !== undefined)
+                await noteMachineKey(outbox, key);
+            builtBytes += (await writeBatch(outbox, key, parsed.skeleton)).bytes;
+            // The raw copy comes only after both gates and only with a yes to the raw prompt and a folder not at skeleton only: each transcript of the session, redacted here, before it is queued.
+            if (rawAllowed(saved.pool, head.main.project, covenant)) {
+                let place = 0;
+                for (const file of await transcriptFilesOf(runtime, head.main.project, head.main.session)) {
+                    const redacted = redactTranscript(await readFile(file.path, 'utf8'), saved.redactDomains, names, injectedKey);
+                    counts.raw.bytes += (await writeRaw(outbox, key, place, redacted.text)).bytes;
+                    counts.raw.copies += 1;
+                    counts.raw.masked += redacted.masked;
+                    place += 1;
+                }
+                rawKept.add(key);
+            }
+            tallyBatch(wireTally, parsed.skeleton);
+            await markDeltasSent(outbox, delta?.marks ?? []);
+            built.add(key);
+            counts.batched += 1;
         }
-        tallyBatch(wireTally, parsed.skeleton);
-        await markDeltasSent(outbox, delta?.marks ?? []);
-        built.add(key);
-        counts.batched += 1;
     }
     // The batch of a session or account this store no longer holds goes too. A machine builds one session at a time and nothing here has the others in hand, so it sweeps nothing: nothing is withdrawn but what a gate refused.
     if (machine === undefined) {
@@ -793,6 +1085,7 @@ export const poolDeposit = async (deps, options) => {
         ...(discarded === 0 ? [] : [`Discarded ${String(discarded)} ${discarded === 1 ? 'batch' : 'batches'} built under an older vocabulary, field list, or skeleton format.`]),
         `Raw copies queued: ${String(counts.raw.copies)} (${String(counts.raw.bytes)} bytes, ${String(counts.raw.masked)} values masked). ${rawNote(saved.pool.rawConsent)}`.trim(),
         ...(rawStale(saved.pool, covenant) ? [`Your yes to the raw prompt was given under covenant ${saved.pool.rawConsentVersion ?? 'none'}, not ${covenant ?? ''}, so no raw copy is queued. Run oars pool raw --consent yes to answer for the covenant now in force.`] : []),
+        ...(counts.removedByPerson === 0 ? [] : [`${String(counts.removedByPerson)} ${counts.removedByPerson === 1 ? 'session' : 'sessions'} you removed with oars pool remove: nothing of them is built, queued, or sent. oars pool remove <hash> --restore brings one back.`]),
         ...(counts.off === 0 ? [] : [`${String(counts.off)} ${counts.off === 1 ? 'session' : 'sessions'} in a folder switched off: nothing of them is queued.`]),
         ...(termList.length === 0 ? [termsHint(terms)] : []),
         'Run oars pool outbox to print exactly what would be sent.',
@@ -812,35 +1105,61 @@ const explained = (bytes) => {
     }
     return rows;
 };
-/** `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 const poolOutbox = async (deps, options) => {
     const runtime = runtimeOf(deps);
     const server = poolServer(deps.env, OUTBOX, options.server);
     const { token } = await signedIn(deps, runtime.storeDir, server, OUTBOX);
     const outbox = outboxFolder(runtime.storeDir, server);
-    const { batches, edited } = await heldAcross(outbox);
     const masker = new Masker();
     masker.add(token);
     const sent = await sentLog(outbox);
+    const { print } = options;
     const shown = [];
-    for (const batch of batches) {
+    // Blocks are separated by a blank line; each is written alone, so no string holds more than one batch.
+    const state = { wrote: false };
+    const put = (block) => {
+        print?.(`${state.wrote ? '\n\n' : ''}${block}`);
+        state.wrote = true;
+    };
+    // One batch is read at a time: the outbox of a 6,500-session history is gigabytes, far past what one array of them holds.
+    let edited = 0;
+    for await (const named of namesHeldAcross(outbox)) {
+        const bytes = await unchangedBytes(named.file, named.hash);
+        if (bytes === undefined) {
+            edited += 1;
+            continue;
+        }
+        const batch = { hash: named.hash, bytes };
         const fields = options.explain === true ? explained(batch.bytes) : undefined;
         // A batch past one request prints every part's request, in the order they are sent.
         const request = callsOf(token, batch.bytes, batch.hash).map((call) => printed(outgoing(deps, server, POOL_DEPOSITS, call), masker)).join('\n');
-        shown.push({ hash: batch.hash, request, ...(sent.has(batch.hash) ? { sent: sent.get(batch.hash) ?? '' } : {}), ...(fields === undefined ? {} : { fields }) });
+        const at = sent.get(batch.hash);
+        put([request, `sha256: ${batch.hash}`, ...(at === undefined ? [] : [`sent: ${at}`]), ...Object.entries(fields ?? {}).map(([field, row]) => `  ${field}: ${row}`)].join('\n'));
+        shown.push({ hash: batch.hash, ...(print === undefined ? { request } : {}), ...(at === undefined ? {} : { sent: at }), ...(fields === undefined ? {} : { fields }) });
+        await markShown(outbox, batch.hash, deps.now());
     }
     const { copies } = await heldRaw(outbox);
-    const rawBlocks = copies.flatMap((copy) => rawParts(copy.body).map((part, at, all) => [`raw part ${String(at + 1)}/${String(all.length)} sha256: ${copy.hash} bytes: ${String(Buffer.byteLength(part))}${sent.has(copy.hash) ? ` sent: ${sent.get(copy.hash) ?? ''}` : ''}`, ...(options.explain === true ? [part] : [])].join('\n')));
-    for (const { hash } of shown)
-        await markShown(outbox, hash, deps.now());
+    for (const copy of copies) {
+        const parts = rawParts(copy.body);
+        for (const [at, part] of parts.entries())
+            put([`raw part ${String(at + 1)}/${String(parts.length)} sha256: ${copy.hash} bytes: ${String(Buffer.byteLength(part))}${sent.has(copy.hash) ? ` sent: ${sent.get(copy.hash) ?? ''}` : ''}`, ...(options.explain === true ? [part] : [])].join('\n'));
+    }
     const stale = await staleBatches(outbox);
-    const blocks = shown.map(({ hash, request, sent: at, fields }) => [request, `sha256: ${hash}`, ...(at === undefined ? [] : [`sent: ${at}`]), ...Object.entries(fields ?? {}).map(([field, row]) => `  ${field}: ${row}`)].join('\n'));
     const notes = [
         ...(edited === 0 ? [] : [`${String(edited)} ${edited === 1 ? 'batch was' : 'batches were'} edited on disk since ${edited === 1 ? 'it was' : 'they were'} written and ${edited === 1 ? 'is' : 'are'} not printed or sent. Run oars pool deposit to build ${edited === 1 ? 'it' : 'them'} again.`]),
         ...(stale === 0 ? [] : [`${String(stale)} ${stale === 1 ? 'batch was' : 'batches were'} built under an older vocabulary, field list, or skeleton format and will never be sent.`]),
     ];
-    const text = shown.length === 0 && rawBlocks.length === 0 ? ['The outbox is empty. Run oars pool deposit first.', ...notes].join('\n') : [...blocks, ...rawBlocks, ...notes].join('\n\n');
-    return { document: { ok: true, server, batches: shown, raw: copies.map(({ hash, bytes }) => ({ hash, bytes, ...(sent.has(hash) ? { sent: sent.get(hash) ?? '' } : {}) })), edited, stale }, text };
+    if (!state.wrote)
+        put(['The outbox is empty. Run oars pool deposit first.', ...notes].join('\n'));
+    else
+        for (const note of notes)
+            put(note);
+    print?.('\n');
+    return { document: { ok: true, server, batches: shown, raw: copies.map(({ hash, bytes }) => ({ hash, bytes, ...(sent.has(hash) ? { sent: sent.get(hash) ?? '' } : {}) })), edited, stale }, text: '', output: print === undefined ? 'chunked' : 'streamed' };
 };
 /**
  * What the pool says it served a bundle at, printed as the bundle states it: the client holds no floor of its own and applies none (a floor is the pool's deploy setting), so a bundle that states none prints nothing.
@@ -949,6 +1268,291 @@ export const poolFetch = async (deps, options) => {
         text: `Fetched ${harness} ${harnessVersion}: ${String(reads.length)} reads, ${String(cells.length)} cells, and ${String(motifs.length)} motifs, verified against the pinned key and kept at ${file}.${floorSentence(floors)}`,
     };
 };
+const JOIN = 'pool-join';
+/** The join's invite step: `POST /v1/invites/redeem`. An account that joined on an invite already is a run repeated, which is not an error; any other refusal ends the run with the pool's own words. */
+const redeemInvite = async (deps, storeDir, server, code) => {
+    const { token } = await signedIn(deps, storeDir, server, JOIN);
+    const credential = new Masker();
+    credential.add(token);
+    const reply = await ask(deps, JOIN, server, '/v1/invites/redeem', { body: { code }, token, show: credential });
+    if (reply.status === 200)
+        return { redeemed: true };
+    if (reply.status === 409 && isObject(reply.body) && textIn(reply.body, 'error') === 'already_vouched')
+        return { skipped: true, reason: 'already_vouched' };
+    throw refusal(JOIN, reply);
+};
+const JOIN_AGAIN = 'Run oars pool join again to continue from here.';
+const INVITE_AGAIN = 'The invite code was not accepted, and running the same line again fails the same way. Run oars pool join again without --invite, or with a new code.';
+/** The steps `--plan` lists: the seven the join runs, in order, then the raw question, which `oars pool raw` asks and the join never does. */
+const PLAN_STEPS = [...JOIN_STEPS, 'raw'];
+/** The two steps only a person can do: typing the covenant phrase, and answering the raw prompt. Nothing here, no flag and no variable, does either for them. Region and terms are a person's too until a flag or the term file answers them. */
+const PERSON_STEPS = ['covenant', 'raw'];
+/** Whether the pool reports the covenant accepted for this sign-in. A pool that cannot be asked, or refuses, reads as not accepted: a plan states what it can see. */
+const covenantAccepted = async (deps, server, token) => {
+    try {
+        const reply = await ask(deps, JOIN, server, '/v1/covenant', { token });
+        return reply.status === 200 && isObject(reply.body) && Reflect.get(reply.body, 'accepted') === true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether this batch has been printed by `outbox` or sent: the proof `--send` asks for. */
+const batchSeen = async (outbox, hash, sent) => sent.has(hash) || (await wasShown(outbox, hash));
+/**
+ * `oars pool join --plan`: each step of the join and whether it stands, from the sign-in, the term file, the outbox, and (when signed in) one read of the covenant. It signs in to nothing, writes nothing, and sends nothing.
+ * `needs_person` marks the steps a person does: the typed covenant phrase and the raw prompt, and region and terms while no flag or file answers them.
+ */
+const joinPlan = async (deps, server, flagged) => {
+    const { storeDir } = runtimeOf(deps);
+    const outbox = outboxFolder(storeDir, server);
+    const held = await heldSignIn(deps, storeDir, server, JOIN);
+    const accepted = held !== undefined && (await covenantAccepted(deps, server, held.token));
+    const { batches } = await heldAcross(outbox);
+    const sent = await sentLog(outbox);
+    const seen = await Promise.all(batches.map(({ hash }) => batchSeen(outbox, hash, sent)));
+    const state = await readState(storeDir);
+    const standing = {
+        signin: held !== undefined,
+        region: accepted || state.pool.euEeaUk !== null,
+        terms: (await currentTerms(deps)).length > 0,
+        batch: batches.length > 0,
+        outbox: batches.length > 0 && seen.every(Boolean),
+        covenant: accepted,
+        send: batches.length > 0 && batches.every(({ hash }) => sent.has(hash)),
+        raw: state.pool.rawConsent === 'granted',
+    };
+    const steps = PLAN_STEPS.map((step) => ({ step, state: standing[step] ? 'done' : 'pending', needs_person: PERSON_STEPS.includes(step) || (!standing[step] && (step === 'terms' || (step === 'region' && !flagged))) }));
+    return { document: { ok: true, plan: true, server, steps }, text: steps.map(({ step, state, needs_person: person }) => `${step}: ${state}${person ? ' (a person does this)' : ''}`).join('\n') };
+};
+/**
+ * `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 const poolJoin = async (deps, options) => {
+    const { storeDir, projectsRoot } = runtimeOf(deps);
+    const server = poolServer(deps.env, JOIN, options.server);
+    if (options.plan === true)
+        return joinPlan(deps, server, options.inEuEeaUk !== undefined);
+    const say = (line) => {
+        deps.io.stderr(`${line}
+`);
+    };
+    const screen = options.json === true ? deps.io.stderr : deps.io.stdout;
+    const show = (outcome) => {
+        if (outcome.output !== 'streamed')
+            screen(`${outcome.text}
+`);
+        return outcome;
+    };
+    const outbox = outboxFolder(storeDir, server);
+    const unsent = async () => {
+        const sent = await sentLog(outbox);
+        return (await heldAcross(outbox)).batches.flatMap(({ hash }) => (sent.has(hash) ? [] : [hash]));
+    };
+    const emit = emitOf(deps);
+    let settled;
+    const record = (step, state) => {
+        settled = step;
+        emit('join-step', { step, state });
+    };
+    const state = { refused: false };
+    let current = 'signin';
+    let fetching = false;
+    // Ctrl-C reaches every step: the sign-in poll and the line reads take the signal, and each step begins by checking it.
+    const interrupt = watchInterrupt();
+    const begin = (step) => {
+        current = step;
+        interrupt.signal.throwIfAborted();
+    };
+    let reader;
+    const lines = () => (reader ??= readerOf(deps, interrupt.signal));
+    try {
+        const held = await heldSignIn(deps, storeDir, server, LOGIN);
+        let login = { skipped: true, account: held?.account };
+        if (held === undefined) {
+            say(`Signing in to ${server}.`);
+            login = show(await poolLogin(deps, { server, provider: options.provider, verbose: options.verbose, signal: interrupt.signal })).document;
+            record('signin', 'done');
+        }
+        else {
+            say(`Already signed in to ${server} as ${held.account}.`);
+            record('signin', 'skipped');
+        }
+        const { token } = await signedIn(deps, storeDir, server, JOIN);
+        const via = networkSender(deps, DEPOSIT, { stallMs: SEND_STALL_MS, signal: interrupt.signal });
+        let vouched = { skipped: true };
+        if (options.invite !== undefined) {
+            say('Using your invite code.');
+            try {
+                vouched = await redeemInvite(deps, storeDir, server, options.invite);
+            }
+            catch (error) {
+                state.refused = true;
+                throw error;
+            }
+        }
+        // The region question: asked plainly, once, of a person at a terminal whose covenant is not yet accepted, and sent with the acceptance. A flag answers it; off a terminal the covenant step is what stops.
+        begin('region');
+        let region = regionOf(options.inEuEeaUk);
+        if (options.inEuEeaUk !== undefined && region === undefined)
+            throw usage(`${REGION_FLAG} takes yes or no, not "${options.inEuEeaUk}". Nothing was accepted.`, JOIN);
+        // An answer given on an earlier run stands: the person is not asked twice, whatever stopped the run after the question.
+        if (region === undefined)
+            region = (await readState(storeDir)).pool.euEeaUk ?? undefined;
+        if (region === undefined && isTerminal(deps) && !(await covenantAccepted(deps, server, token))) {
+            say('Before the covenant screen, one question that goes with your acceptance.');
+            deps.io.stderr(`${REGION_QUESTION} > `);
+            region = regionOf(await lines().next());
+            if (region === undefined)
+                throw usage('Answer yes or no: are you in the EU, the EEA, or the UK? Nothing was accepted.', JOIN);
+            const answer = region;
+            await updatePoolChoices(storeDir, (choices) => {
+                choices.euEeaUk = answer;
+            });
+            record('region', 'done');
+        }
+        else {
+            record('region', 'skipped');
+        }
+        // The term file: the person's own list of names to keep out. Without a term every session stays out of the outbox, so an empty file stops the run here, with the file made for them to edit.
+        begin('terms');
+        if ((await currentTerms(deps)).length === 0) {
+            const file = exclusionPaths(projectsRoot, deps.env).terms;
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(file, '', { flag: 'a' });
+            say(`Your exclusion terms go in ${file}, one per line: a client, a project, or a person whose name must never leave your machine. Every session that mentions one stays out of the outbox. oars adds none for you.`);
+            if (isTerminal(deps)) {
+                say('Press Enter when you have saved the file.');
+                await lines().next();
+            }
+            if ((await currentTerms(deps)).length === 0) {
+                const title = `The exclusion term file ${file} still holds no term, so every session would stay out of the outbox. Add one term per line, save it, and run this again.`;
+                throw new CliError(title, ExitCode.INVALID, JOIN, { code: 'terms_missing', title });
+            }
+            record('terms', 'done');
+        }
+        else {
+            record('terms', 'skipped');
+        }
+        begin('batch');
+        let prepared = { skipped: true };
+        if ((await unsent()).length > 0) {
+            say('Your outbox already holds a prepared batch; not preparing it again.');
+            record('batch', 'skipped');
+        }
+        else {
+            say('Preparing your deposit in the outbox.');
+            prepared = show(await poolDeposit(deps, { server })).document;
+            record('batch', 'done');
+        }
+        begin('outbox');
+        say('Showing what will be sent, field by field.');
+        const shown = show(await poolOutbox(deps, { server, explain: true, print: screen })).document;
+        record('outbox', 'done');
+        const hashes = await unsent();
+        // The covenant, read from the pool and, if not accepted, shown for a person to type the phrase: before the first send, so its own step ends before the sends begin.
+        begin('covenant');
+        const nothingPrepared = (await heldAcross(outbox)).batches.length === 0;
+        if (hashes.length === 0) {
+            record('covenant', nothingPrepared ? 'none' : 'skipped');
+        }
+        else {
+            record('covenant', (await openCovenant(deps, server, token, options.acceptCovenant, region, via, interrupt.signal, undefined, false, reader)) ? 'done' : 'skipped');
+        }
+        begin('send');
+        const sends = [];
+        if (hashes.length === 0) {
+            say(nothingPrepared ? 'No session is ready to deposit yet; sending nothing.' : 'Everything prepared is already sent; sending nothing.');
+            record('send', nothingPrepared ? 'none' : 'skipped');
+        }
+        else {
+            say(`Sending ${plural(hashes.length, 'batch', 'batches')} to ${server}.`);
+            for (const hash of hashes)
+                sends.push(show(await poolDeposit(deps, { server, send: hash, acceptCovenant: options.acceptCovenant, inEuEeaUk: region })).document);
+            record('send', 'done');
+        }
+        await rememberCrew(deps, storeDir, server, token, JOIN);
+        let fetched;
+        if (options.harnessVersion !== undefined) {
+            fetching = true;
+            say(`Fetching the bundle for ${options.harness ?? 'your most used harness'} ${options.harnessVersion}.`);
+            fetched = show(await poolFetch(deps, { server, harness: options.harness, harnessVersion: options.harnessVersion }));
+        }
+        return {
+            document: { ok: true, server, login, invite: vouched, deposit: prepared, outbox: shown, sends, ...(fetched === undefined ? {} : { fetch: fetched.document }) },
+            text: `Joined ${server}: ${plural(sends.length, 'batch', 'batches')} sent this run${options.harnessVersion === undefined ? '' : `, and the ${options.harnessVersion} bundle is kept`}.`,
+        };
+    }
+    catch (error) {
+        // A step that threw is the one that stopped; the fetch after the sends is not one of the seven.
+        // A step already recorded done or skipped is not stopped as well: the failure came after it, in the code between steps.
+        if (!fetching && settled !== current)
+            record(current, 'stopped');
+        say(state.refused ? INVITE_AGAIN : JOIN_AGAIN);
+        // A signal ended the run (the readline read throws its own abort error, the poll and the steps throw the reason): exit as deposit does, 130 for Ctrl-C.
+        if (interrupt.signal.aborted && interrupt.signal.reason instanceof SendInterrupted)
+            throw stopped(JOIN, interrupt.signal.reason, false);
+        throw error;
+    }
+    finally {
+        interrupt.stop();
+        reader?.close();
+    }
+};
+const INVITE = 'pool-invite';
+/** Asks the pool for this account's crew number and keeps it for the card. Best effort: a refusal or a failed call leaves what was held, because nothing the person asked for depends on it. */
+const rememberCrew = async (deps, storeDir, server, token, step) => {
+    try {
+        const credential = new Masker();
+        credential.add(token);
+        const reply = await ask(deps, step, server, '/v1/me', { token, show: credential });
+        if (reply.status !== 200 || !isObject(reply.body))
+            return undefined;
+        const account = Reflect.get(reply.body, 'account');
+        if (typeof account === 'string')
+            await keepCrewNumber(storeDir, server, account, numberIn(reply.body, 'crewNumber'));
+        return numberIn(reply.body, 'vouchesGiven');
+    }
+    catch {
+        // The card shows the number when it is known and says nothing when it is not.
+        return undefined;
+    }
+};
+/** The one line an invitee runs. `<version>` stays a placeholder: the harness version is the invitee's own to name. */
+export const joinLineOf = (code) => `oars pool join --invite ${code} --harness-version <version>`;
+/**
+ * `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 const poolInvite = async (deps, options) => {
+    const { storeDir } = runtimeOf(deps);
+    const server = poolServer(deps.env, INVITE, options.server);
+    const { token } = await signedIn(deps, storeDir, server, INVITE);
+    const credential = new Masker();
+    credential.add(token);
+    const reply = await ask(deps, INVITE, server, '/v1/invites', { body: {}, token, show: credential });
+    if (reply.status !== 201)
+        throw refusal(INVITE, reply);
+    const code = isObject(reply.body) ? textIn(reply.body, 'code') : undefined;
+    const left = isObject(reply.body) ? numberIn(reply.body, 'invitesLeft') : undefined;
+    if (code === undefined)
+        throw new CliError('The pool answered an invite with no code.', ExitCode.UNEXPECTED, INVITE);
+    const given = await rememberCrew(deps, storeDir, server, token, INVITE);
+    const line = joinLineOf(code);
+    return {
+        document: { ok: true, server, code, join: line, ...(left === undefined ? {} : { invitesLeft: left }), ...(given === undefined ? {} : { vouchesGiven: given }) },
+        text: [
+            `Invite code: ${code}`,
+            'This is the only time the code is shown. It works once, for one person.',
+            `Send them this line: ${line}`,
+            `What you get: your vouch is recorded${given === undefined ? '' : ` (you have vouched for ${String(given)} so far)`}. What they get: once they have rowed two counting weeks, the next founding-crew grant lets them join the open board without waiting 90 days, unless you and they are the same operator, which gives neither of you anything.`,
+            ...(left === undefined ? [] : [`Open codes you can still make: ${String(left)}.`]),
+        ].join('\n'),
+    };
+};
 const RAW = 'pool-raw';
 /** 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 const RAW_PROMPT = [