@manyoars/oars 0.5.2 → 0.5.4

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

@@ -207,8 +207,9 @@ Replay is local and read-only on your transcripts; it writes `crossings.jsonl` a
 
 ### pool
 
-`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` uses the Many Oars pool, `https://pool.manyoars.com`, which is live and open for deposits, or a pool server you name with `--server <url>` or `OARS_POOL_URL`. Every other command works without it.
 
+- `oars pool join --provider github|google --harness-version <version> [--harness <name>]` is the first way in: it signs you in, prepares your deposit, prints what would be sent with each field's rule, sends it, and fetches your first bundle, in one run. It is the five commands below in order, with the same prompts and the same checks, and one plain line says what each step is doing. If a step stops, it prints that step's own error and names the command to run again; running `oars pool join` again skips what already stands (a held sign-in, a prepared batch, a batch already sent). The commands below do the same step by step.
 - `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 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.
@@ -217,6 +218,7 @@ Replay is local and read-only on your transcripts; it writes `crossings.jsonl` a
 - `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.
 - On an enrolled machine the hook child activates its key before its first deposit, rotates it where the disk is durable (`vps`, `ci`; the key lives in `<store>/machine-key`, owner-only), deposits under it, sends the batches its outbox held once the covenant is accepted, and tells you at the next Stop when the key expires within 14 days, has expired, or was revoked (`oars pool machines` lists it). A `cloud` machine's key is held by the network proxy and the child sends no credential of its own. Details: `docs/pool.md`, "Machine keys".
 - `oars pool outbox` prints each batch exactly as it would be sent, with its SHA-256, and `--explain` adds each field's rule.
+- `oars pool remove <hash>` removes one batch from the outbox on this machine, with the queued raw copies of the same session, and says what it removed; nothing is sent and nothing at the pool changes. The session stays out of every later deposit, the background sender's included, until `oars pool remove <hash> --restore`, whichever account you sign in with. It refuses while a send holds the lock.
 - `oars pool fetch --harness-version <version>` fetches that version's signed bundle, verifies it against the key pinned at login, and keeps it locally. It prints the public and disclosure floors the bundle states (and any read family on a floor of its own) and holds no floor of its own: the pool sets them, so a change is a deploy and never a new release of oars.
 
 ### club
@@ -258,6 +260,7 @@ Exit codes:
 | 7 | rate limited |
 | 8 | the server could not be reached (the platform, the issuer, or a pool server) |
 | 10 | `pool fetch` hit the pool's weekly fetch cap; the bundle on disk is untouched, and the message says when to try again |
+| 130 | `pool deposit --send` was ended with Ctrl-C (SIGINT); the batch stays queued |
 
 ## Source
 

package/dist/cli.d.ts

@@ -32,6 +32,8 @@ export interface RunDeps {
 export interface Outcome {
     document: object;
     text: string;
+    /** `streamed`: the handler already wrote `text` as it went, so nothing is printed from it. `chunked`: `--json` falls back to writing the document one array element at a time when it is past V8's string length. */
+    output?: 'streamed' | 'chunked';
 }
 /** Runs one invocation (`argv` without the node and script entries) and returns the exit code. Telemetry records it afterward and cannot change it. */
 export declare const run: (argv: string[], deps: RunDeps) => Promise<ExitCode>;

package/dist/cli.js

@@ -19,7 +19,7 @@ import { githubVisibility, poolEnroll, poolMachineRevoke, poolMachines } from '.
 import { runNetGit } from './sessions/machine-hold.js';
 import { holdPull } from './sessions/machine-pull.js';
 import { runGit } from './sessions/survival.js';
-import { poolCoverage, poolDeposit, poolExport, poolFetch, poolLogin, poolLogout, poolOutbox, poolProve, poolRaw } from './sessions/pool-command.js';
+import { poolCoverage, poolDeposit, poolExport, poolFetch, poolJoin, poolLogin, poolLogout, poolOutbox, poolProve, poolRaw, poolRemove } from './sessions/pool-command.js';
 import { telemetryOff, telemetryOn, telemetryReport, telemetryShow, telemetryStatus } from './telemetry/command.js';
 import { cardLine } from './sessions/card-line.js';
 import { recordCrash } from './telemetry/crash.js';
@@ -52,7 +52,44 @@ const isoTime = (value) => {
         throw new InvalidArgumentError('it must be an ISO time such as 2026-11-01T16:00:00Z.');
     return new Date(parsed).toISOString();
 };
+/** The document as one string, or `undefined` when it is past V8's string length (`RangeError: Invalid string length`). */
+const stringified = (document) => {
+    try {
+        return JSON.stringify(document);
+    }
+    catch (error) {
+        if (error instanceof RangeError)
+            return undefined;
+        throw error;
+    }
+};
+/** `JSON.stringify(document)` plus a newline, in pieces: each top-level array goes out one element at a time, so no piece is longer than its largest element. */
+const jsonPieces = function* (document) {
+    yield '{';
+    for (const [at, [key, value]] of Object.entries(document).entries()) {
+        const head = `${at === 0 ? '' : ','}${JSON.stringify(key)}:`;
+        if (!Array.isArray(value)) {
+            yield `${head}${JSON.stringify(value)}`;
+            continue;
+        }
+        yield `${head}[`;
+        for (const [index, item] of value.entries())
+            yield `${index === 0 ? '' : ','}${JSON.stringify(item)}`;
+        yield ']';
+    }
+    yield '}\n';
+};
 const emit = (deps, json, outcome) => {
+    if (json && outcome.output === 'chunked') {
+        // One write when the document fits in a string, as every other command; past V8's string length, the pieces.
+        const whole = stringified(outcome.document);
+        for (const piece of whole === undefined ? jsonPieces(outcome.document) : [`${whole}
+`])
+            deps.io.stdout(piece);
+        return;
+    }
+    if (!json && outcome.output === 'streamed')
+        return;
     deps.io.stdout(`${json ? JSON.stringify(outcome.document) : outcome.text}\n`);
 };
 /**
@@ -462,9 +499,24 @@ const buildProgram = (deps, observed) => {
         .action(async (_options, command) => {
         emit(deps, flag(command.optsWithGlobals(), 'json'), await gateReport(sessionDeps(deps)));
     });
-    const pool = program.command('pool').description('sign in to a pool server, deposit session skeletons (a closed list of fields, each value redacted first) and, after a yes to the raw prompt, redacted raw copies, and fetch signed reads; local capture, recall, and reads need none of it. The covenant screen, where you type its phrase to accept, appears when you send a batch with oars pool deposit --send <hash> and have not accepted the covenant in force, not at sign-in');
+    const pool = program.command('pool').description('sign in to a pool server, deposit session skeletons (a closed list of fields, each value redacted first) and, after a yes to the raw prompt, redacted raw copies, and fetch signed reads; local capture, recall, and reads need none of it. The covenant screen, where you type its phrase to accept, appears when you send a batch with oars pool deposit --send <hash> or oars pool join and have not accepted the covenant in force, not at sign-in');
     const serverOption = '--server <url>';
     const serverHelp = 'the pool server, https or plain http to localhost (default: OARS_POOL_URL, else https://pool.manyoars.com)';
+    pool
+        .command('join')
+        .description('run login, deposit, outbox --explain, deposit --send, and fetch in one command. Run it again after a stop to continue from there')
+        .option('--provider <name>', 'github or google, for the sign-in step (not needed once signed in)')
+        .option('--verbose', 'print each sign-in request, headers and body, to stderr before it is sent (a credential shows as its size)')
+        .option('--accept-covenant <version>', 'name the covenant version you expect, as deposit --send takes it: on a terminal the screen is shown and you type its phrase yourself, and off a terminal this is refused')
+        .option('--in-eu-eea-uk <yes|no>', 'answer "Are you in the EU, the EEA, or the UK?" when you accept, as deposit --send takes it')
+        .option('--harness <name>', 'the harness whose bundle to fetch (default: the one your local store holds the most sessions of, claude-code when none leads)')
+        .requiredOption('--harness-version <version>', 'the public harness version whose bundle to fetch, as fetch takes it')
+        .option(serverOption, serverHelp)
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        const json = flag(options, 'json');
+        emit(deps, json, await poolJoin(deps, { server: text(options, 'server'), provider: text(options, 'provider'), verbose: flag(options, 'verbose'), acceptCovenant: text(options, 'acceptCovenant'), inEuEeaUk: text(options, 'inEuEeaUk'), harness: text(options, 'harness'), harnessVersion: text(options, 'harnessVersion') ?? '', json }));
+    });
     pool
         .command('logout')
         .description('revoke the credential held for this pool and remove it here; if the pool cannot be reached the local entry is still removed')
@@ -564,7 +616,17 @@ const buildProgram = (deps, observed) => {
         .option(serverOption, serverHelp)
         .action(async (_options, command) => {
         const options = command.optsWithGlobals();
-        emit(deps, flag(options, 'json'), await poolOutbox(deps, { server: text(options, 'server'), explain: flag(options, 'explain') }));
+        emit(deps, flag(options, 'json'), await poolOutbox(deps, { server: text(options, 'server'), explain: flag(options, 'explain'), ...(flag(options, 'json') ? {} : { print: deps.io.stdout }) }));
+    });
+    pool
+        .command('remove')
+        .argument('<hash>', 'the SHA-256 of a batch, as oars pool outbox prints it')
+        .description('remove one batch and its queued raw copies from the outbox on this machine; nothing is sent, and nothing at the pool changes. Its session stays out of every later oars pool deposit, the background sender included, until --restore. It refuses while a send holds the outbox lock')
+        .option('--restore', 'take the session of an earlier removal off the list, so a later oars pool deposit builds it again (the hash is the one remove printed)')
+        .option(serverOption, serverHelp)
+        .action(async (hash, _options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await poolRemove(deps, hash, { server: text(options, 'server'), restore: flag(options, 'restore') }));
     });
     pool
         .command('prove')

package/dist/errors.d.ts

@@ -12,6 +12,8 @@ export declare const ExitCode: {
     readonly UNREACHABLE: 8;
     /** `pool fetch` hit the pool's weekly cap: nothing is wrong, and the bundle on disk is untouched. */
     readonly CAPPED: 10;
+    /** A send the person ended with Ctrl-C (SIGINT): the shell convention, 128 plus the signal number. */
+    readonly INTERRUPTED: 130;
 };
 export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
 /** The exit code for a failed response. The problem's code (then its type) decides; the status covers what has none. Text is never read. */

package/dist/errors.js

@@ -10,6 +10,8 @@ export const ExitCode = {
     UNREACHABLE: 8,
     /** `pool fetch` hit the pool's weekly cap: nothing is wrong, and the bundle on disk is untouched. */
     CAPPED: 10,
+    /** A send the person ended with Ctrl-C (SIGINT): the shell convention, 128 plus the signal number. */
+    INTERRUPTED: 130,
 };
 const codes = (exit, ...names) => names.map((name) => [name, exit]);
 // Problem codes (or types) from spec 1 §13, T87 and T92. EXPIRED_TOKEN and ACCESS_DENIED are the device flow's own, raised locally.

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,34 @@ 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;
+/**
+ * `oars pool remove <hash>`: takes one batch out of this machine's outbox, the batch `oars pool outbox` printed under that hash. It takes the send lock without waiting, because a send in progress may be reading the very file, and refuses while another run holds it.
+ * It reads nothing from the pool and sends nothing, so it needs no sign-in, and it changes only files here. The session of a local batch goes on `removed.json`, which `poolDeposit` (and so the background sender) honors: nothing of it is built, queued, or sent until `--restore <hash>` takes it off. One a cloud session held is admitted again only by `oars pool hold pull`.
+ */
+export declare const poolRemove: (deps: RunDeps, hash: string, options: {
+    server?: string | undefined;
+    restore?: boolean | undefined;
+    lock?: SendLock | undefined;
+}) => Promise<Outcome>;
 /** The outbox key, and the skeleton `id`, of a machine's session: from the environment's session salt (per account, not per machine), else its own name standing in for the account, which a machine has none of. The holding route names its branch by the same key. */
 export declare const machineKeyOf: (machine: MachineConfig, session: string) => string;
 /**
@@ -110,11 +156,16 @@ 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. */
+/**
+ * `oars pool outbox`: prints each batch as it would be sent (a batch past one request prints each part's request, in order), the request line and every header included, with the bearer credential as its size and nothing else masked, then its SHA-256, and records that it was shown. `--explain` adds each field's rule.
+ * With `print` each batch is written as soon as it is built and marked shown right after, and the outcome carries no text: an outbox of thousands of sessions is far past V8's string length as one string. Without it (`--json`) the document carries each batch's request, and `--json` writes it element by element.
+ */
 export declare const poolOutbox: (deps: RunDeps, options: {
     server?: string | undefined;
     explain?: boolean | undefined;
+    print?: ((chunk: string) => void) | undefined;
 }) => Promise<Outcome>;
 /** `oars pool fetch`: one harness's signed bundle at one version, kept only once the key pinned at login has verified it. It keeps the signed form, so the replica can be checked again later, and the ETag, so the next fetch asks only whether it changed. The request prints before it is sent. */
 export declare const poolFetch: (deps: RunDeps, options: {
@@ -122,6 +173,21 @@ export declare const poolFetch: (deps: RunDeps, options: {
     harness?: string | undefined;
     harnessVersion: string;
 }) => Promise<Outcome>;
+/**
+ * `oars pool join`: the five commands of a first deposit in one run, each by the handler the command itself uses: `login`, `deposit`, `outbox --explain`, `deposit --send <hash>` for each batch not yet sent, then `fetch`. It asks and checks
+ * nothing they do not, and a step that stops ends the run with that step's own error. Run again it skips what stands: a held sign-in, a prepared batch not yet sent, a batch in `sent.log`.
+ * 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.
+ */
+export declare const poolJoin: (deps: RunDeps, options: {
+    server?: string | undefined;
+    provider?: string | undefined;
+    verbose?: boolean;
+    acceptCovenant?: string | undefined;
+    inEuEeaUk?: string | undefined;
+    harness?: string | undefined;
+    harnessVersion: string;
+    json?: boolean;
+}) => Promise<Outcome>;
 /** The raw prompt, in plain words: shown by `oars pool raw` until it is answered, and what the detached sender relies on. Redaction is best effort and the text says so. */
 export declare const RAW_PROMPT: string;
 /** What a person types to say yes to the raw prompt: consent is a statement made at a terminal (GDPR Articles 7 and 9(2)(a)), not a flag a script can pass. */