@manyoars/oars 0.5.1 → 0.5.3

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 Switchyard Software Company
+   Copyright 2026 Many Oars Co.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -209,9 +209,9 @@ Replay is local and read-only on your transcripts; it writes `crossings.jsonl` a
 
 `oars pool` uses the Many Oars pool, `https://pool.manyoars.com`, which is live (deposits there are closed until its covenant is published), or a pool server you name with `--server <url>` or `OARS_POOL_URL`. Every other command works without it.
 
-- `oars pool login --provider github|google` asks the pool to start the provider's device flow, prints the user code and link, and polls the pool until you approve; with `--verbose`, every request prints before it is sent. The pool holds the OAuth client and its secret, so the CLI needs no client ID or secret, and the provider's tokens never reach this machine.
+- `oars pool login --provider github|google` asks the pool to start the provider's device flow, prints the user code and link, and polls the pool until you approve (a failed poll is retried with a longer wait until the code expires; the output names the exclusion-terms file when there is none, and the first `pool deposit` needs it); with `--verbose`, every request prints before it is sent. The pool holds the OAuth client and its secret, so the CLI needs no client ID or secret, and the provider's tokens never reach this machine.
 - `oars pool logout` revokes this machine's credential at the pool, then removes the local sign-in. If the pool cannot be reached it still removes the local sign-in and says the credential was not revoked there.
-- `oars pool deposit` writes a batch of session skeletons (a closed list of fields, each value redacted first; a host is hashed by the pool on arrival) to an outbox for each session that passes your folder allowlist and the exclusion check, and stops: no session data is sent. `--send <hash>` sends one batch that `outbox` printed and that is unchanged on disk, once this account has accepted the pool covenant (a person types the phrase the covenant screen states, at a terminal; `--accept-covenant <version>` only names the version expected and accepts nothing; the screen then asks "Are you in the EU, the EEA, or the UK? (yes/no)" and sends the answer, and `--in-eu-eea-uk <yes|no>` answers it without asking; while the pool is closed to those regions a yes, or a request from them, is refused with `region_closed` and nothing is accepted); before that it reads the covenant, sends no batch, and exits 3 with `covenant_not_accepted`. A hash that was never shown, or a batch that changed, is refused before any request. The detached sender is the other sender: after the pool says your account accepted its covenant, it sends new batches, and raw copies only if you said yes to the raw prompt (`oars pool raw --consent yes`, answered by typing the phrase `I consent to sending raw copies` at a terminal; a yes also tells the pool, and `--consent no` tells it to stop accepting raw copies, whatever a later request states (a machine that held a yes and is signed out exits nonzero: the pool was not told), and the pool's nightly job then erases the raw copies it already holds, starting that night; a large account can take more than one night). With no sign-in, no acceptance, or an unreachable server it sends nothing.
+- `oars pool deposit` writes a batch of session skeletons (a closed list of fields, each value redacted first; a host is hashed by the pool on arrival) to an outbox for each session that passes your folder allowlist and the exclusion check and whose last line is over 6 hours old, and stops: no session data is sent. `--send <hash>` sends one batch that `outbox` printed and that is unchanged on disk, once this account has accepted the pool covenant (a person types the phrase the covenant screen states, at a terminal; `--accept-covenant <version>` only names the version expected and accepts nothing; the screen then asks "Are you in the EU, the EEA, or the UK? (yes/no)" and sends the answer, and `--in-eu-eea-uk <yes|no>` answers it without asking; while the pool is closed to those regions a yes, or a request from them, is refused with `region_closed` and nothing is accepted); before that it reads the covenant, sends no batch, and exits 3 with `covenant_not_accepted`. A hash that was never shown, or a batch that changed, is refused before any request. The detached sender is the other sender: after the pool says your account accepted its covenant, it sends new batches, and raw copies only if you said yes to the raw prompt (`oars pool raw --consent yes`, answered by typing the phrase `I consent to sending raw copies` at a terminal; a yes also tells the pool, and `--consent no` tells it to stop accepting raw copies, whatever a later request states (a machine that held a yes and is signed out exits nonzero: the pool was not told), and the pool's nightly job then erases the raw copies it already holds, starting that night; a large account can take more than one night). With no sign-in, no acceptance, or an unreachable server it sends nothing.
 - `deposit`, `outbox`, `export`, and `fetch` need `oars pool login` first; without it they exit 3 and name the server.
 - `oars pool coverage [--org-size <band>] [--repo-visibility public|private|unknown]` sets the two coverage bands only you can state, read locally and never from the network; an unset band goes on the wire as `unknown`.
 - `oars pool export --out <folder> [--raw]` saves a copy of what the pool holds about your account (GDPR Articles 15(3) and 20), as JSON, one file a page, readable by you only. It covers your account row (with your raw consent record), when your sign-ins end (never the credential), your covenant acceptances, your machines (without their keys, with the day of each one's last deposit and its key days), your repository keys, your deposit hours, your deposits as they now read (with the machine, host class, and launcher each came from, and the host class and launcher the batch claimed), your raw ledger, your staged deposit parts, your erasure audit rows, and your telemetry days. `--raw` also saves each raw transcript you deposited that has not been erased, checked against its hash. It needs `oars pool login`, writes nothing to the pool, prints what it saved, and exits nonzero naming any page or object that failed; a rerun overwrites the same files. Totals the pool derives from many accounts are not yours to export and are not in it.

package/dist/cli.js

@@ -151,7 +151,7 @@ const buildProgram = (deps, observed) => {
         const period = flag(options, 'year') ? 'year' : flag(options, 'month') ? 'month' : 'week';
         emit(deps, flag(options, 'json'), await sessionsCard(sessionDeps(deps), { period, text: flag(options, 'text'), out: text(options, 'out'), noCost: options.cost === false }, deps.env));
     });
-    const sessions = program.command('sessions').description("deposit and recall your own coding-agent session logs, locally (these commands make no model call and no network call, except `gold arms`, which asks your own Claude subscription; telemetry is separate: oars telemetry)");
+    const sessions = program.command('sessions').description("deposit and recall your own coding-agent session logs, locally; try it on made-up sessions: oars sessions try (these commands make no model call and no network call, except `gold arms`, which asks your own Claude subscription; telemetry is separate: oars telemetry)");
     sessions
         .command('deposit')
         .description('read session logs into the local observation log, from every folder unless --allow names some or --deny keeps some out; idempotent. Subagent transcripts under each session (<project>/<session>/subagents/) are deposited with their parent, and each raw transcript is hard-linked or copied into the oars archive beside the store')

package/dist/sessions/empty-state.d.ts

@@ -1,7 +1,7 @@
 import type { Source } from './sources.js';
 import type { DepositResult, SessionsRuntime } from './store.js';
 /** `recall` over a store with no sessions in it. */
-export declare const EMPTY_RECALL = "Your store is empty, so there is nothing to recall. See it work on made-up sessions with `oars sessions try`, or fill it with `oars sessions deposit`, which reads this machine's coding-agent session logs into a local store and archives a copy of each transcript.";
+export declare const EMPTY_RECALL = "Your store is empty, so there is nothing to recall. See it work on made-up sessions with `oars sessions try`, or fill it with `oars sessions deposit`, which reads this machine's coding-agent session logs into a local store and archives a copy of each transcript. It reads your own session history, not made-up sessions.";
 /** `books` over a store with no sessions in it; `what` is "prompts" or "pulls". */
 export declare const emptyBooks: (what: string) => string;
 /**

package/dist/sessions/empty-state.js

@@ -1,7 +1,7 @@
 // What `deposit`, `recall`, and `books` say when there is nothing to show, so a first run reads as "nothing found here" and not as a broken tool.
 import { compileAllow, isDenial } from './allow.js';
 /** The two commands that get someone out of an empty store: watch it work on made-up sessions first with `sessions try`, or fill it from their own sessions with `sessions deposit`. */
-const WAYS_OUT = "See it work on made-up sessions with `oars sessions try`, or fill it with `oars sessions deposit`, which reads this machine's coding-agent session logs into a local store and archives a copy of each transcript.";
+const WAYS_OUT = "See it work on made-up sessions with `oars sessions try`, or fill it with `oars sessions deposit`, which reads this machine's coding-agent session logs into a local store and archives a copy of each transcript. It reads your own session history, not made-up sessions.";
 /** `recall` over a store with no sessions in it. */
 export const EMPTY_RECALL = `Your store is empty, so there is nothing to recall. ${WAYS_OUT}`;
 /** `books` over a store with no sessions in it; `what` is "prompts" or "pulls". */

package/dist/sessions/injected.js

@@ -76,6 +76,31 @@ const mapContent = (content, text, result, definition) => {
     });
     return items.some((item, at) => item !== content[at]) ? items : content;
 };
+// Harness text a request blob of the system role carries, by what it opens with or names. The whole block is marked, under the kind (and so the hash) its
+// attachment record gets, because it is the same text. First match wins. A system text with none of these forms is left to the other rules.
+const SYSTEM_FORMS = [
+    [/\bSessionStart(?::[\w-]+)? hook\b|\bhook additional context\b/, 'hook-additional-context'],
+    [/following skills are available for use with the Skill tool/i, 'skill-listing'],
+    [/Available agent types/i, 'agent-listing-delta'],
+    [/^\s*#{1,3} MCP Server Instructions\b|following MCP servers have provided instructions/m, 'mcp-instructions-delta'],
+    [/^\s*#{1,3} Environment\s*$|^\s*You have been invoked in the following environment/m, 'environment'],
+    [/Contents of [^\n]*?[\\/]\.claude[\\/]rules[\\/][^\n]*\.md\b|Contents of [^\n]*?(?:CLAUDE|AGENTS|MEMORY)(?:\.local)?\.md\b/, 'instructions'],
+];
+// A memory file: an instruction file, the memory index, a note under a `memory` folder, or a rules file.
+const MEMORY_PATH = /(?:^|[\\/])(?:CLAUDE|AGENTS|MEMORY)(?:\.local)?\.md$|[\\/]memory[\\/][^\\/]+\.md$|[\\/]\.claude[\\/]rules[\\/][^\\/]+\.md$/i;
+const MEMORY_MENTION = /(?:CLAUDE|AGENTS|MEMORY)(?:\.local)?\.md\b|[\\/]memory[\\/][^\s"'`\\/]+\.md\b/i;
+const CHANGED = /changed on disk|was modified/i;
+/** The kind of harness text a system-role string is, or undefined: one of the forms above, or a note that a memory file changed. */
+const systemKindOf = (text) => {
+    const form = SYSTEM_FORMS.find(([shape]) => shape.test(text));
+    if (form !== undefined)
+        return form[1];
+    return MEMORY_MENTION.test(text) && CHANGED.test(text) ? 'memory-file' : undefined;
+};
+const systemText = (key) => (text) => {
+    const kind = text.trim() === '' || MARKER.test(text.trim()) ? undefined : systemKindOf(text);
+    return kind === undefined ? text : markerOf(key, kind, text);
+};
 const messageRule = (key, position, known) => {
     const whole = (text) => (text.trim() === '' || MARKER.test(text.trim()) ? text : markerOf(key, 'meta', text));
     const leading = (text) => {
@@ -91,13 +116,25 @@ const messageRule = (key, position, known) => {
         return content === message['content'] || content === undefined ? message : { ...message, content };
     };
 };
-const withMessage = (line, field, rule) => {
+const withMessage = (line, field, rule, role = 'user') => {
     const message = line[field];
-    if (!isObject(message) || message['role'] !== 'user')
+    if (!isObject(message) || message['role'] !== role)
         return line;
     const next = rule(message);
     return next === message ? line : { ...line, [field]: next };
 };
+/** The rule for a request blob of the system role: the harness's own forms first, then the text other lines repeat. */
+const systemMessage = (key, known) => {
+    const mark = systemText(key);
+    const text = (value) => {
+        const next = mark(value);
+        return next !== value || !known.has(normalize(value)) ? next : markerOf(key, 'meta', value);
+    };
+    return (message) => {
+        const content = mapContent(message['content'], text, text, (tool) => tool);
+        return content === message['content'] || content === undefined ? message : { ...message, content };
+    };
+};
 const withField = (line, field, change) => {
     const value = line[field];
     if (value === undefined)
@@ -168,6 +205,8 @@ export const injectedRule = (key, known = new Set()) => {
     const userMessage = messageRule(key, 'typed', known);
     const metaMessage = messageRule(key, 'meta', known);
     const blobMessage = messageRule(key, 'blob', known);
+    const systemBlob = systemMessage(key, known);
+    const memory = blocksIn(key, 'memory-file');
     // A meta line's `origin` says where the injected text came from; its `body` and `handback` are that text again, while `kind` stays readable.
     const originText = (origin) => {
         if (!isObject(origin))
@@ -179,10 +218,16 @@ export const injectedRule = (key, known = new Set()) => {
             case 'user':
                 return line['isMeta'] === true ? withField(withMessage(line, 'message', metaMessage), 'origin', originText) : withMessage(line, 'message', userMessage);
             case 'api-request-blob':
-                return withMessage(line, 'message', blobMessage);
+                return withMessage(withMessage(line, 'message', blobMessage), 'message', systemBlob, 'system');
             case 'attachment': {
                 const attachment = line['attachment'];
                 const kind = isObject(attachment) ? attachment['type'] : undefined;
+                // A memory file the model edited or that changed on disk: the snippet (and the message it was shown in) is the file's text.
+                const file = isObject(attachment) ? attachment['filename'] : undefined;
+                if (kind === 'edited_text_file' && typeof file === 'string' && MEMORY_PATH.test(file)) {
+                    const snippet = (value) => (isObject(value) ? withField(value, 'snippet', (text) => mapStrings(text, 'snippet', memory)) : value);
+                    return withField(withField(line, 'attachment', snippet), 'rendered', (value) => mapStrings(value, 'rendered', memory));
+                }
                 if (typeof kind !== 'string' || !INJECTED_ATTACHMENTS.has(kind))
                     return line;
                 // The record repeats its text as the message the model was shown (`rendered`), so that is the same block again.
@@ -197,9 +242,12 @@ export const injectedRule = (key, known = new Set()) => {
                 });
             case 'system':
                 // The hook output a stop-hook summary carries: what a hook printed, its error text, and the command line it ran.
-                return line['subtype'] === 'stop_hook_summary'
-                    ? HOOK_SUMMARY_FIELDS.reduce((acc, name) => withField(acc, name, (value) => mapStrings(value, name, blocksIn(key, 'hook-summary'))), line)
-                    : line;
+                if (line['subtype'] === 'stop_hook_summary')
+                    return HOOK_SUMMARY_FIELDS.reduce((acc, name) => withField(acc, name, (value) => mapStrings(value, name, blocksIn(key, 'hook-summary'))), line);
+                // Any other system text is the harness speaking (a changed memory file, a notice), except the echo of a command the operator ran: that is operator output, not an instruction.
+                if (line['subtype'] === 'local_command')
+                    return line;
+                return withField(line, 'content', (value) => (typeof value === 'string' ? systemText(key)(value) : value));
             case 'session_meta':
             case 'turn_context':
                 return withField(line, 'payload', (payload) => (isObject(payload) ? codexFields(key, payload) : payload));

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

@@ -1,6 +1,7 @@
 import type { Outcome, RunDeps } from '../cli.js';
 import { CliError } from '../errors.js';
 import { Masker, type Outgoing } from './pool-print.js';
+import { type BusyDetail, type LockFs, type LockTimes, type Waiting } from './pool-send-lock.js';
 import { isObject, loadSignIns, textIn, type SignIn } from './pool-replica.js';
 import { type MachineConfig } from './machine.js';
 import { type SessionsRuntime } from './store.js';
@@ -46,8 +47,19 @@ interface Call {
 export type Sender = (request: Outgoing) => Promise<Reply>;
 /** One call to the pool. A redirect is an error: it could carry a batch or a token somewhere the checks on the named server never saw. */
 export declare const ask: (deps: RunDeps, step: string, server: string, path: string, init: Call, via?: Sender) => Promise<Reply>;
-/** The sender `deposit --send` uses when none is given: the request goes out over the network as built. The loopback test passes it to read what reaches the socket. */
-export declare const networkSender: (deps: RunDeps, step: string) => Sender;
+/** What a guarded send runs under: the longest the pool gets to answer one request, and (for an interactive `--send`) the signal that ends the request when the person, or the program that launched the send, ends the run. The background sender has no one to interrupt it. */
+export interface Guard {
+    stallMs: number;
+    signal?: AbortSignal;
+}
+/**
+ * What a person reads after a send they stopped (Ctrl-C, a closed terminal, a launcher that died): the batch stays queued, and the background sender (hook-bin.js nightly, started by a later oars command
+ * or the end of a session, about once an hour at most, not on a timer) sends it once the covenant is accepted, whether or not this command ever finishes. The second line is added only when a request carrying the batch had gone out.
+ * The folder switch and the sign-out are the two real ways to stop that: the sender builds the outbox again first, which withdraws a folder that is off, and it sends nothing without a sign-in.
+ */
+export declare const stoppedText: (received: boolean) => string;
+/** The sender `deposit --send` uses when none is given: the request goes out over the network as built. The loopback test passes it to read what reaches the socket. An interactive send passes a `Guard`. */
+export declare const networkSender: (deps: RunDeps, step: string, guard?: Guard) => Sender;
 /** The server's named refusal, as a failure: its `error` is the problem's code in `--json`. */
 export declare const refusal: (step: string, { status, body }: Reply) => CliError;
 /**
@@ -66,6 +78,12 @@ export declare const poolLogin: (deps: RunDeps, options: {
 export declare const poolLogout: (deps: RunDeps, options: {
     server?: string | undefined;
 }) => Promise<Outcome>;
+/**
+ * The CLI's own words around the covenant screen, never inside it: the screen text and the hash of it that the pool records stay exactly what the pool served. They say what a deposit gives and what to run next, and
+ * they promise only access, as covenant 2.1 does ("What you get" and Section 4.3). The third line points at the full text because Part A is a summary and Section 16.2 makes the full covenant the whole agreement.
+ */
+export declare const OFFER_BEFORE: readonly string[];
+export declare const OFFER_AFTER: readonly string[];
 /** A person is here when input and the screen's stream are both terminals: a typed phrase counts only for a text that reached a screen. */
 export declare const isTerminal: (deps: RunDeps) => boolean;
 /** The next line a person types, or `undefined` when the input ends first. The interface is closed after it, so the terminal is released. */
@@ -94,6 +112,25 @@ export declare const postRaw: (deps: RunDeps, options: {
 }) => Promise<void>;
 /** The exclusion terms in force now, re-read from the term file each time it is asked: empty when the file is missing or unreadable. */
 export declare const currentTerms: (deps: RunDeps) => Promise<string[]>;
+/** What a test replaces in the send lock: its times and its clock, pause, and process checks, so a wait runs on driven time. */
+export interface SendLock {
+    times: Partial<LockTimes>;
+    fs: LockFs;
+}
+/**
+ * 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
+ * sentence; resetting the timer once headers arrive would not help it, because the upload is what is slow.
+ */
+export declare const SEND_STALL_MS = 30000;
+/** What the person reads within a second of a send that has to wait: whose lock it is, how old it is, and how long this run waits. */
+export declare const waitingLine: ({ holder, ageMs, waitMs }: Waiting) => string;
+/**
+ * What a send that gave up says: nothing was sent, who held the lock, and when a retry can succeed. A live holder on this host touches the lock every quarter of staleMs, even while it waits on a stalled pool, so the clock
+ * never frees its lock: the true condition is its end (a dead holder is taken over at once). Only a holder the lock does not name, or one on another host, whose liveness cannot be read, is decided by the clock: a
+ * retry is certain once the lock has gone untouched for staleMs.
+ */
+export declare const busyLine: ({ holder, local, ageMs, untouchedMs, waitedMs, staleMs }: BusyDetail) => string;
 /** 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;
 /**
@@ -110,6 +147,7 @@ export declare const poolDeposit: (deps: RunDeps, options: {
     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. */
 export declare const poolOutbox: (deps: RunDeps, options: {

package/dist/sessions/pool-command.js

@@ -19,7 +19,7 @@ import { carriedDeltas, heldDeltas, keptDeltas, markDeltasSent, placedOf, sentDe
 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 { SendLockBusy, withSendLock } from './pool-send-lock.js';
+import { SendInterrupted, SendLockBusy, watchInterrupt, withSendLock } from './pool-send-lock.js';
 import { markSent, retirePulled, sentLog } from './pool-sent.js';
 import { shellReader } from './projection.js';
 import { isVocabularyExpired, REGISTRY_MAX_AGE_DAYS, VOCAB_SNAPSHOT_DATE } from './public-vocabulary.js';
@@ -47,6 +47,8 @@ const DEFAULT_INTERVAL_SEC = 5;
 const DEFAULT_EXPIRY_SEC = 900;
 /** RFC 8628: a `slow_down` adds five seconds to every poll after it. */
 const SLOW_DOWN_MS = 5000;
+/** The longest wait between polls after failed ones. */
+const MAX_BACKOFF_MS = 60_000;
 export { isObject, loadSignIns, textIn };
 const usage = (message, step) => new CliError(message, ExitCode.USAGE, step);
 /** The Many Oars pool, used when neither `--server` nor `OARS_POOL_URL` names another. */
@@ -100,29 +102,92 @@ export const ask = (deps, step, server, path, init, via) => {
     const request = outgoing(deps, server, path, init);
     return via === undefined ? send(deps, step, request, init.show, init.binary === true) : via(request);
 };
-/** Prints the request when asked to, then sends exactly those headers and that body. */
-const send = async (deps, step, request, show, binary = false) => {
+/** 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. */
+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'],
+];
+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.';
+/** 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.';
+/**
+ * What a person reads after a send they stopped (Ctrl-C, a closed terminal, a launcher that died): the batch stays queued, and the background sender (hook-bin.js nightly, started by a later oars command
+ * or the end of a session, about once an hour at most, not on a timer) sends it once the covenant is accepted, whether or not this command ever finishes. The second line is added only when a request carrying the batch had gone out.
+ * The folder switch and the sign-out are the two real ways to stop that: the sender builds the outbox again first, which withdraws a folder that is off, and it sends nothing without a sign-in.
+ */
+export const stoppedText = (received) => [
+    'Stopped. This batch stays queued, and once the covenant is accepted oars sends it automatically in the background.',
+    ...(received ? [MAY_HAVE_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');
+/** 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);
+    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);
+};
+/** 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) => {
     if (show !== undefined)
         deps.io.stderr(`${printed(request, show)}
 `);
-    let response;
-    try {
-        response = await fetch(request.url, { method: request.method, headers: request.headers, redirect: 'error', ...(request.body === undefined ? {} : { body: request.body }) });
-    }
-    catch (error) {
-        throw unreachableError(step, error, request.url.origin);
-    }
-    let body;
+    const stop = new AbortController();
+    const relay = () => {
+        stop.abort(guard?.signal?.reason);
+    };
+    guard?.signal?.addEventListener('abort', relay, { once: true });
+    if (guard?.signal?.aborted === true)
+        relay();
+    const timer = guard === undefined ? undefined : setTimeout(() => {
+        stop.abort(new PoolStalled());
+    }, guard.stallMs);
+    // Whether the batch itself had gone out when the run ended: only the deposit request carries it, and only when it went out before the run was stopped.
+    let started = false;
+    const failure = (error) => (guard === undefined ? unreachableError(step, error, request.url.origin) : guardedFailure(step, stop.signal.aborted ? stop.signal.reason : error, request.url.origin, guard, started && request.url.pathname === POOL_DEPOSITS));
     try {
-        body = binary && response.status === 200 ? new Uint8Array(await response.arrayBuffer()) : await response.json();
+        let response;
+        try {
+            started = !stop.signal.aborted;
+            response = await fetch(request.url, { method: request.method, headers: request.headers, redirect: 'error', ...(guard === undefined ? {} : { signal: stop.signal }), ...(request.body === undefined ? {} : { body: request.body }) });
+        }
+        catch (error) {
+            throw failure(error);
+        }
+        let body;
+        try {
+            body = binary && response.status === 200 ? new Uint8Array(await response.arrayBuffer()) : await response.json();
+        }
+        catch (error) {
+            // An answer that began and then stalled is no answer; one that ended badly is read as no body, as before.
+            if (stop.signal.aborted)
+                throw failure(error);
+            body = undefined;
+        }
+        return { status: response.status, body, headers: response.headers };
     }
-    catch {
-        body = undefined;
+    finally {
+        clearTimeout(timer);
+        guard?.signal?.removeEventListener('abort', relay);
     }
-    return { status: response.status, body, headers: response.headers };
 };
-/** The sender `deposit --send` uses when none is given: the request goes out over the network as built. The loopback test passes it to read what reaches the socket. */
-export const networkSender = (deps, step) => (request) => send(deps, step, request, undefined);
+/** The sender `deposit --send` uses when none is given: the request goes out over the network as built. The loopback test passes it to read what reaches the socket. An interactive send passes a `Guard`. */
+export const networkSender = (deps, step, guard) => (request) => send(deps, step, request, undefined, false, guard);
 /** The server's named refusal, as a failure: its `error` is the problem's code in `--json`. */
 export const refusal = (step, { status, body }) => {
     const code = isObject(body) ? textIn(body, 'error') : undefined;
@@ -156,9 +221,30 @@ ${proofLines(account, provedAt)}`;
 /** 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) => {
     let { intervalMs } = started;
-    for (let waited = 0; waited < started.expiresMs; waited += intervalMs) {
-        await deps.sleep(intervalMs);
-        const reply = await ask(deps, LOGIN, server, '/v1/login/poll', { body: { handle: started.handle }, show });
+    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);
+        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 })]);
+        // A rejection that is not the unreachable failure is a bug, not a bad minute: it ends the login as itself.
+        if (settled.status === 'rejected') {
+            if (!(settled.reason instanceof CliError) || settled.reason.exitCode !== ExitCode.UNREACHABLE)
+                throw settled.reason;
+            lastFailure = settled.reason;
+        }
+        const reply = settled.status === 'fulfilled' ? settled.value : undefined;
+        if (reply !== undefined && reply.status >= 500)
+            lastFailure = refusal(LOGIN, reply);
+        if (reply === undefined || reply.status >= 500) {
+            failures += 1;
+            continue;
+        }
+        failures = 0;
+        lastFailure = undefined;
         if (reply.status !== 200 || !isObject(reply.body))
             throw closedProof(reply) ?? refusal(LOGIN, reply);
         const status = textIn(reply.body, 'status');
@@ -175,6 +261,9 @@ const awaitCredential = async (deps, server, started, show) => {
         else if (status !== 'pending')
             throw new CliError('The pool answered a sign-in poll with a state this client does not know.', ExitCode.UNEXPECTED, LOGIN);
     }
+    // Out of time with the last poll still failing: the failure is the truth (exit 8), not an expiry nobody saw.
+    if (lastFailure !== undefined)
+        throw lastFailure;
     const title = 'The sign-in code expired. Run oars pool login again.';
     throw new CliError(title, ExitCode.AUTH, LOGIN, { code: 'EXPIRED_TOKEN', title });
 };
@@ -223,7 +312,11 @@ export const poolLogin = async (deps, options) => {
     const pinned = { ...signIn, signingKeys: known === undefined ? signIn.signingKeys : held };
     await mkdirOwnerOnly(storeDir);
     await writeOwnerOnly(signInsFile(storeDir), `${JSON.stringify([...saved.filter((entry) => entry !== known), pinned])}\n`);
-    return { document: { ok: true, server, account: signIn.account, expiresAt: signIn.expiresAt }, text: `Signed in to ${server} as ${signIn.account}.` };
+    // The first deposit stops without a term file, so the login that precedes it says so.
+    const { terms: termsFile } = exclusionPaths(runtimeOf(deps).projectsRoot, deps.env);
+    const bare = (await loadTerms(termsFile)).length === 0;
+    return { document: { ok: true, server, account: signIn.account, expiresAt: signIn.expiresAt, ...(bare ? { termsFile } : {}) }, text: `Signed in to ${server} as ${signIn.account}.${bare ? `
+${termsHint(termsFile)}` : ''}` };
 };
 /** The pool is not answering: it could not be reached, or a gateway in front of it says so. */
 const poolDown = (status) => status === 502 || status === 503 || status === 504;
@@ -266,8 +359,18 @@ const regionOf = (text) => {
     const answer = text?.trim().toLowerCase();
     return answer === 'yes' || answer === 'no' ? answer : undefined;
 };
+/**
+ * The CLI's own words around the covenant screen, never inside it: the screen text and the hash of it that the pool records stay exactly what the pool served. They say what a deposit gives and what to run next, and
+ * they promise only access, as covenant 2.1 does ("What you get" and Section 4.3). The third line points at the full text because Part A is a summary and Section 16.2 makes the full covenant the whole agreement.
+ */
+export const OFFER_BEFORE = [
+    'Depositing gives your account access to the pool.',
+    'A counting deposit lifts the weekly limit on pool fetches for 90 days.',
+    '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.'];
 /** 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) => {
+const openCovenant = async (deps, server, token, accept, region, via, signal) => {
     const reply = await ask(deps, DEPOSIT, server, '/v1/covenant', { token }, via);
     if (reply.status !== 200 || !isObject(reply.body))
         throw refusal(DEPOSIT, reply);
@@ -291,13 +394,17 @@ const openCovenant = async (deps, server, token, accept, region, via) => {
     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.`);
     }
+    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.
-    const lines = createInterface({ input: runtimeOf(deps).stdin, terminal: false });
+    // 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;
     };
     let answered = region;
@@ -319,6 +426,7 @@ const openCovenant = async (deps, server, token, accept, region, via) => {
     const accepted = await ask(deps, DEPOSIT, server, '/v1/covenant/accept', { token, body }, via);
     if (accepted.status !== 200)
         throw refusal(DEPOSIT, accepted);
+    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 };
     await updatePoolChoices(runtimeOf(deps).storeDir, (choices) => {
@@ -414,13 +522,17 @@ export const postRaw = async (deps, options) => {
 const rawNote = (consent) => consent === 'granted' ? '' : consent === 'declined' ? 'You answered no to the raw prompt; oars pool raw --consent yes changes it.' : 'None is queued until you answer the raw prompt with oars pool raw --consent yes.';
 /** The exclusion terms in force now, re-read from the term file each time it is asked: empty when the file is missing or unreadable. */
 export const currentTerms = (deps) => loadTerms(exclusionPaths(runtimeOf(deps).projectsRoot, deps.env).terms);
+/** The one line a person with no exclusion terms needs: where the file goes and what names another. The deposit stays fail-closed without it (the A38 exclusion rule), so the first run says so before the deposit has to. */
+const termsHint = (file) => `No exclusion terms file at ${file}: until it holds a term, one per line, every session stays out of the outbox. Create it there, or set OARS_EXCLUSION_TERMS to the file of your own.`;
 /** `deposit --send <hash>`: the send lock the detached sender (hook-bin.js nightly) takes too, then a skip for a hash already in `sent.log`, then the batch lock, then the covenant (accepted here or before, or nothing is sent), then the request. The body is read and hashed again just before the request. */
 const sendBatch = async (deps, options) => {
     const { outbox, server, token, hash } = options;
-    const via = options.via ?? networkSender(deps, DEPOSIT);
     if (!/^[0-9a-f]{64}$/.test(hash))
         throw usage('--send takes the SHA-256 that oars pool outbox printed: 64 hexadecimal characters.', DEPOSIT);
     const refuse = (code, title) => new CliError(title, ExitCode.CONFLICT, DEPOSIT, { code, title, status: 409 });
+    // Ctrl-C, a kill, a closed terminal, or a launcher that died ends the wait for the lock and the request in flight, so a send the person gave up on cannot finish later.
+    const interrupt = watchInterrupt();
+    const via = options.via ?? networkSender(deps, DEPOSIT, { stallMs: SEND_STALL_MS, signal: interrupt.signal });
     try {
         return await withSendLock(outbox, async () => {
             // The rule the nightly follows: a hash `sent.log` holds is not posted again. Read under the lock, so two runs cannot both see it unsent.
@@ -438,21 +550,59 @@ const sendBatch = async (deps, options) => {
                 throw refuse(locked.code, lockMessages[locked.code]);
             if (!scan.open && (await heldAcross(outbox)).batches.some((batch) => batch.hash === hash && batch.pulled))
                 throw refuse('terms_missing', 'This batch was held by a cloud session, and your exclusion term file is missing or empty, so it cannot be checked and was not sent.');
-            await openCovenant(deps, server, token, options.acceptCovenant, options.region, via);
+            await openCovenant(deps, server, token, options.acceptCovenant, options.region, via, interrupt.signal);
             const bytes = await unchangedBytes(locked.file, hash);
             if (bytes === undefined)
                 throw refuse('batch_changed', lockMessages.batch_changed);
+            deps.io.stderr(`Sending batch ${hash.slice(0, 12)} to ${server}...\n`);
             await postBatch(deps, { server, token, bytes, hash, via });
             await markSent(outbox, hash, deps.now());
             await retirePulled(outbox, DEPOSIT);
             return { document: { ok: true, server, hash, sent: true }, text: `Sent batch ${hash} to ${server}.` };
+        }, options.lock?.times, options.lock?.fs, {
+            onWait: (waiting) => {
+                deps.io.stderr(`${waitingLine(waiting)}\n`);
+            },
+            signal: interrupt.signal,
         });
     }
     catch (error) {
         if (error instanceof SendLockBusy)
-            throw refuse('send_locked', 'Another oars run is sending from this outbox. Try again in a minute.');
+            throw refuse('send_locked', busyLine(error.detail));
+        if (error instanceof SendInterrupted)
+            throw new CliError(stoppedText(false), ExitCode.UNEXPECTED, DEPOSIT);
         throw error;
     }
+    finally {
+        interrupt.stop();
+    }
+};
+/**
+ * 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
+ * sentence; resetting the timer once headers arrive would not help it, because the upload is what is slow.
+ */
+export const SEND_STALL_MS = 30_000;
+/** A span in words a person can plan around: seconds under two minutes, else whole minutes. */
+const span = (ms) => {
+    const seconds = Math.max(1, Math.round(ms / 1000));
+    return seconds < 120 ? `${String(seconds)} second${seconds === 1 ? '' : 's'}` : `${String(Math.round(seconds / 60))} minutes`;
+};
+/** What the person reads within a second of a send that has to wait: whose lock it is, how old it is, and how long this run waits. */
+export const waitingLine = ({ holder, ageMs, waitMs }) => holder === undefined
+    ? `Another oars run holds this outbox's send lock (the lock does not name its process; it was last touched ${span(ageMs)} ago). Waiting up to ${span(waitMs)} for it; Ctrl-C stops this run.`
+    : `Another oars run (pid ${String(holder.pid)}) took this outbox's send lock ${span(ageMs)} ago and is still sending. Waiting up to ${span(waitMs)} for it; Ctrl-C stops this run.`;
+/**
+ * What a send that gave up says: nothing was sent, who held the lock, and when a retry can succeed. A live holder on this host touches the lock every quarter of staleMs, even while it waits on a stalled pool, so the clock
+ * never frees its lock: the true condition is its end (a dead holder is taken over at once). Only a holder the lock does not name, or one on another host, whose liveness cannot be read, is decided by the clock: a
+ * retry is certain once the lock has gone untouched for staleMs.
+ */
+export const busyLine = ({ holder, local, ageMs, untouchedMs, waitedMs, staleMs }) => {
+    const who = holder === undefined ? 'Another oars run' : `Another oars run (pid ${String(holder.pid)})`;
+    const held = `${who} has held this outbox's send lock for ${span(ageMs)} and was still sending after the ${span(waitedMs)} this run waited, so nothing was sent.`;
+    if (holder !== undefined && local)
+        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 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) => {
@@ -495,7 +645,7 @@ export const poolDeposit = async (deps, options) => {
     const outbox = outboxFolder(runtime.storeDir, server);
     await mkdirOwnerOnly(outbox);
     if (options.send !== undefined)
-        return sendBatch(deps, { outbox, server, token, hash: options.send, acceptCovenant: options.acceptCovenant, region, via: options.via });
+        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);
     const saved = await readState(runtime.storeDir);
     // A yes to the raw prompt counts only for the covenant it was given under, so an interactive build asks the pool which is in force; the nightly already knows and passes it. A pool that cannot be asked, or names none, leaves it unknown and the build goes on as before.
@@ -568,7 +718,7 @@ export const poolDeposit = async (deps, options) => {
             continue;
         }
         // The batch of a session is built once the session and its subagents have ended; a session still in progress waits, and an earlier batch of it is withdrawn. A machine's Stop is the end of a turn, not of a session: its VM may be reclaimed before the session ends, so it builds the open session as it stands.
-        if (machine === undefined && !hasEnded(records, deps.now(), await lastWritten(runtime, records.main.project, records.main.session))) {
+        if (machine === undefined && !hasEnded(records, deps.now(), await lastWritten(runtime, records.main.project, records.main.session), undefined, options.covenant !== undefined)) {
             counts.notEnded += 1;
             await withdraw(key);
             continue;
@@ -636,7 +786,7 @@ export const poolDeposit = async (deps, options) => {
     // Counts only: how many sessions each gate kept out, never a folder, a term, or a name.
     emitOf(deps)('deposit', { step: 'build', sessions: counts.sessions, batched: counts.batched, bytes: builtBytes, excludedFolder: folder, excludedTerm: term, excludedNoRaw: noRaw, excludedNoTerms: noTerms, excludedUnreadable: unreadable, notEnded: counts.notEnded, uncaptured: counts.uncaptured, refused: counts.refused, withdrawn: counts.withdrawn, discarded });
     const lines = [
-        `Wrote ${String(counts.batched)} of ${String(counts.sessions)} sessions to the outbox for ${server}. Nothing was sent.`,
+        `Wrote ${String(counts.batched)} of ${String(counts.sessions)} sessions to the outbox for ${server}. ${machine === undefined ? SENT_LATER : 'Nothing was sent.'}`,
         `Kept out by the session gates, never built: ${String(folder)} in a folder not on the allowlist, ${String(term)} for a term, ${String(noRaw)} with no raw to scan, ${String(noTerms)} with no term file, ${String(unreadable)} unreadable.`,
         `Not built: ${String(counts.uncaptured)} captured before steps and frames or with no root, ${String(counts.notEnded)} not ended (a transcript gained a line within ${String(SESSION_IDLE_HOURS)} hours), ${String(counts.refused)} refused by the vocabulary${counts.refusedFields.length === 0 ? '' : ` (${counts.refusedFields.join(', ')})`}.`,
         ...(counts.withdrawn === 0 ? [] : [`Removed ${String(counts.withdrawn)} ${counts.withdrawn === 1 ? 'batch' : 'batches'} of sessions that no longer pass the gates, have not ended, or are no longer in the store.`]),
@@ -644,9 +794,10 @@ export const poolDeposit = async (deps, options) => {
         `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.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.',
     ];
-    return { document: { ok: true, server, ...counts }, text: lines.join('\n') };
+    return { document: { ok: true, server, ...counts, ...(termList.length === 0 ? { termsFile: terms } : {}) }, text: lines.join('\n') };
 };
 /** Each field of a batch, at any depth, with its row. A field with no row fails the command rather than printing blank. */
 const explained = (bytes) => {