@manyoars/oars 0.3.0 → 0.4.1

package/dist/sessions/pool-nightly-deps.js

@@ -0,0 +1,11 @@
+export const nightlyPoolDeps = (env, sessions, version, now) => ({
+    env,
+    io: { stdout: () => undefined, stderr: () => undefined },
+    store: { read: () => Promise.resolve(undefined), write: () => Promise.resolve(), delete: () => Promise.resolve() },
+    version,
+    sleep: () => Promise.resolve(),
+    random: () => 0,
+    now,
+    openBrowser: () => Promise.resolve(),
+    sessions,
+});

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

@@ -0,0 +1,10 @@
+import type { RunDeps } from '../cli.js';
+import { type Sender } from './pool-command.js';
+export type NightlyOutcome = 'no-server' | 'not-signed-in' | 'not-accepted' | 'failed' | 'sent';
+export interface NightlyPool {
+    outcome: NightlyOutcome;
+    /** Batches and raw copies this night sent. */
+    batches: number;
+    raw: number;
+}
+export declare const nightlyPoolSend: (deps: RunDeps, via?: Sender) => Promise<NightlyPool>;

package/dist/sessions/pool-nightly.js

@@ -0,0 +1,85 @@
+// The nightly send (t884 Item 4). After the person has accepted the pool's covenant, the nightly task builds the outbox and sends what is new: skeleton batches, and, only after a yes to the raw prompt, the locally redacted raw copies.
+// Acceptance is the consent: this module never accepts a covenant, and with an unusable server URL, no sign-in, or no acceptance it makes one request at most (the covenant read) and sends nothing. `oars pool outbox` still prints everything that is queued.
+// It never throws, and what it records is counts and an outcome word, never a path, a host, or a byte of a transcript.
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ask, DEPOSIT, isObject, networkSender, poolDeposit, poolServer, postBatch, postRaw, runtimeOf, signedIn, textIn, vocabularyExpired } from './pool-command.js';
+import { heldBatches, lockedBatch, outboxFolder } from './pool-outbox.js';
+import { heldRaw } from './pool-raw.js';
+import { withSendLock } from './pool-send-lock.js';
+import { markSent, sentHashes } from './pool-sent.js';
+import { readState } from './store.js';
+const record = async (storeDir, result, at) => {
+    // A note that cannot be written changes nothing about the night.
+    await writeFile(join(storeDir, 'pool-nightly.json'), `${JSON.stringify({ at: new Date(at).toISOString(), ...result })}\n`, 'utf8').catch(() => undefined);
+};
+/** Whether the pool says this account has accepted the covenant now in force. Anything else, a closed pool and a refusal included, is no. */
+const accepted = async (deps, server, token, via) => {
+    const reply = await ask(deps, DEPOSIT, server, '/v1/covenant', { token }, via);
+    return reply.status === 200 && isObject(reply.body) && textIn(reply.body, 'version') !== undefined && Reflect.get(reply.body, 'accepted') === true;
+};
+const night = async (deps, net, tally) => {
+    const none = (outcome) => ({ outcome, batches: 0, raw: 0 });
+    let server;
+    try {
+        server = poolServer(deps.env, DEPOSIT);
+    }
+    catch {
+        return none('no-server');
+    }
+    const { storeDir } = runtimeOf(deps);
+    let token;
+    try {
+        ({ token } = await signedIn(deps, storeDir, server, DEPOSIT));
+    }
+    catch {
+        return none('not-signed-in');
+    }
+    if (vocabularyExpired(deps) !== undefined)
+        return none('failed');
+    if (!(await accepted(deps, server, token, net)))
+        return none('not-accepted');
+    const outbox = outboxFolder(storeDir, server);
+    tally.outcome = 'sent';
+    // One sender at a time per outbox, the lock `deposit --send` takes: a second run waits, then finds `sent.log` full and sends nothing twice.
+    await withSendLock(outbox, async () => {
+        // The outbox is built only for an account that has accepted, then sent: the same gates `oars pool deposit` runs, so nothing queues that a person could not print.
+        await poolDeposit(deps, { server });
+        const done = await sentHashes(outbox);
+        for (const batch of (await heldBatches(outbox)).batches) {
+            if (done.has(batch.hash))
+                continue;
+            // Acceptance is the consent, so nothing was printed first; the file is still read and hashed again just before the request.
+            const locked = await lockedBatch(outbox, batch.hash, { requireShown: false });
+            if (!locked.ok)
+                continue;
+            await postBatch(deps, { server, token, bytes: locked.bytes, hash: batch.hash, via: net });
+            await markSent(outbox, batch.hash, deps.now());
+            tally.batches += 1;
+        }
+        // Raw goes only with its own yes, read again here so an answer changed since the build wins.
+        if ((await readState(storeDir)).pool.rawConsent === 'granted') {
+            for (const copy of (await heldRaw(outbox)).copies) {
+                if (done.has(copy.hash) || copy.bytes === 0)
+                    continue;
+                await postRaw(deps, { server, token, hash: copy.hash, body: copy.body, bytes: copy.bytes, via: net });
+                await markSent(outbox, copy.hash, deps.now());
+                tally.raw += 1;
+            }
+        }
+    });
+    return tally;
+};
+export const nightlyPoolSend = async (deps, via) => {
+    // The tally is filled as sends land, so a night that fails halfway still records what it did send.
+    const tally = { outcome: 'failed', batches: 0, raw: 0 };
+    let result;
+    try {
+        result = await night(deps, via ?? networkSender(deps, DEPOSIT), tally);
+    }
+    catch {
+        result = { ...tally, outcome: 'failed' };
+    }
+    await record(runtimeOf(deps).storeDir, result, deps.now());
+    return result;
+};

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

@@ -1,5 +1,11 @@
 /** The batch as one canonical JSON line: sorted keys, no optional whitespace, UTF-8 when written, and a newline at the end. These are the bytes that are hashed, printed, and sent. */
 export declare const canonicalBytes: (batch: unknown) => string;
+/** The most bytes one request of a deposit carries. The pool refuses a request past 1 MiB, so a batch past this goes in parts, each of them under that cap. */
+export declare const PART_BYTES: number;
+/**
+ * The batch cut into parts of at most `limit` UTF-8 bytes, never inside a character, so the parts join back to exactly the bytes that were hashed. A batch within the limit is one part.
+ */
+export declare const partsOf: (bytes: string, limit?: number) => string[];
 export declare const batchHash: (bytes: string) => string;
 /**
  * `oars pool outbox --explain`: one row for each field name a batch holds, at any depth, saying what admits its values. A field with no row fails the command, so a field added to the batch adds its row here.
@@ -21,6 +27,7 @@ export declare const outboxFolder: (storeDir: string, server: string) => string;
 export declare const writeBatch: (outbox: string, key: string, batch: unknown, stamp?: string) => Promise<{
     hash: string;
     folder: string;
+    bytes: number;
 }>;
 export declare const isMissing: (error: unknown) => boolean;
 /** Removes every batch under this stamp whose session is not in `kept`, and returns how many went. A session that fails a gate, leaves the allowlist, or is gone from the store never enters the outbox, so an earlier pass's batch of it cannot stay. */
@@ -44,8 +51,14 @@ export declare const heldBatches: (outbox: string, stamp?: string) => Promise<{
 /** Records that this hash was printed, one line for each print: the lock below sends only a hash that appears here. */
 export declare const markShown: (outbox: string, hash: string, at: number) => Promise<void>;
 export type LockRefusal = 'batch_unknown' | 'batch_not_shown' | 'batch_changed';
-/** The lock on `deposit --send`: a batch goes only if it is in the outbox, its hash was printed, and its file still hashes to that hash. The first check that fails names why. */
-export declare const lockedBatch: (outbox: string, hash: string, stamp?: string) => Promise<{
+/**
+ * The lock on a send: a batch goes only if it is in the outbox, its hash was printed, and its file still hashes to that hash. The first check that fails names why. The nightly task sends with `requireShown: false`,
+ * because covenant acceptance is its consent and it prints nothing; the other two checks still hold.
+ */
+export declare const lockedBatch: (outbox: string, hash: string, options?: {
+    stamp?: string;
+    requireShown?: boolean;
+}) => Promise<{
     ok: true;
     file: string;
     bytes: string;

package/dist/sessions/pool-outbox.js

@@ -24,6 +24,28 @@ const canonical = (value) => {
 };
 /** The batch as one canonical JSON line: sorted keys, no optional whitespace, UTF-8 when written, and a newline at the end. These are the bytes that are hashed, printed, and sent. */
 export const canonicalBytes = (batch) => `${canonical(batch)}\n`;
+/** The most bytes one request of a deposit carries. The pool refuses a request past 1 MiB, so a batch past this goes in parts, each of them under that cap. */
+export const PART_BYTES = 512 * 1024;
+/**
+ * The batch cut into parts of at most `limit` UTF-8 bytes, never inside a character, so the parts join back to exactly the bytes that were hashed. A batch within the limit is one part.
+ */
+export const partsOf = (bytes, limit = PART_BYTES) => {
+    const parts = [];
+    let part = '';
+    let size = 0;
+    for (const character of bytes) {
+        const width = Buffer.byteLength(character, 'utf8');
+        if (size + width > limit) {
+            parts.push(part);
+            part = '';
+            size = 0;
+        }
+        part += character;
+        size += width;
+    }
+    parts.push(part);
+    return parts;
+};
 export const batchHash = (bytes) => createHash('sha256').update(Buffer.from(bytes, 'utf8')).digest('hex');
 /**
  * `oars pool outbox --explain`: one row for each field name a batch holds, at any depth, saying what admits its values. A field with no row fails the command, so a field added to the batch adds its row here.
@@ -32,8 +54,10 @@ export const batchHash = (bytes) => createHash('sha256').update(Buffer.from(byte
 export const FIELD_ROWS = {
     action: 'The canonical action of a step, one of a closed list this client holds; never the harness tool text.',
     agentType: 'The type of the subagent whose run holds a step: a built-in type of the harness, else the word custom; null on a step of the main run.',
-    cacheRead: 'A bucket of the tokens read from the cache in a prompt, a number.',
-    cacheWrite: 'A bucket of the tokens written to the cache in a prompt, a number.',
+    allocated: 'Whether the step\'s token figure was divided among the calls of one model response (true) rather than measured for the call alone; absent when measured. A flag only, never a count.',
+    argClass: 'The kinds of value a call\'s arguments held, a sorted set of a closed list: path, url, pattern, command, number, flag, text, and none; never a value.',
+    cacheRead: 'A bucket of the tokens read from the cache in a prompt, a number, or null when the source never recorded it.',
+    cacheWrite: 'A bucket of the tokens written to the cache in a prompt, a number, or null when the source never recorded it.',
     change: 'How far a delta moved, a signed bucket of its metric (a lower bound) in a number from -7 to 7 for calls per session and from -11 to 11 for thinking tokens; never the exact count.',
     cls: 'The class of a prompt, one of a closed list of eight, computed from the kinds of tools it used; never its words.',
     day: 'The UTC calendar day of the session as YYYY-MM-DD, or null; never a time of day.',
@@ -41,19 +65,30 @@ export const FIELD_ROWS = {
     deltas: 'The changes the client found between its own before and after windows, each sent once with the session that filled the after window: a kind, a field, a name, a registry, a metric, and a bucketed change; never a session id, a root, a date, or an exact value.',
     durationMs: 'The time of one tool call in milliseconds, exact, a number or null.',
     effort: 'The effort level the model ran at, only when it is a public one; else the literal placeholder.',
+    errorCode: 'Why a tool call failed, one class of a closed list: an exit class (0, 1, 2, 126, 127, signal), an HTTP status class, a harness class (user-rejected, interrupted, permission-denied, input-validation, tool-use-error, timeout), or other; null on a call that did not fail or whose harness records no class. Never result text.',
+    editFollowed: 'Whether one of the calls that followed a failed call wrote a file, true or false: what followed, never that the failure was fixed.',
     errors: 'A bucket of how many tool calls failed in a prompt, a number.',
     explore: 'A bucket of how many steps of a prompt only looked (read a file, searched files, searched the web, or fetched a page), a number or null; never the exact count.',
     field: 'What a delta is about, one of plugin, package, permissionMode, and effort: the field alone, never its value.',
-    flags: 'The flags of a shell command, each a public flag or a short flag; never an argument.',
+    flags: 'The flags of a shell command, each a flag name, never its value: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. Capture still drops a subcommand or flag off the pinned vocabulary of its program, so a real session sends no off-list subcommand (null) and no off-list flag; a subcommand or flag the vocabulary lists goes as its name. A multi-letter single-dash flag no public list holds (`-race`) is dropped.',
+    fieldsVersion: 'The version of the field list this client builds a batch from: a constant of this client, never a value from a session.',
     format: 'The skeleton format number: a constant of this client, never a value from a session.',
-    frame: 'Where a session ran: the harness and its version, the model, the effort, the day, the platform, the shell, and the stack, every value checked against the closed vocabulary.',
+    filled: 'Whether the harness recorded a setup or a tool funnel for the session, true or false; false means the lists beside it are empty because nothing was recorded, not because no tool was in reach.',
+    frame: 'Where a session ran: the harness and its version, the model, the effort, the day, the platform, the shell, and the stack, each checked against its closed list, and the reach of the session (see `reach`). On a step it is a number, the position of the frame its call ran in, in the transcript list of frames.',
+    edges: 'The edges arriving at a step, each a kind and the position of the step it names, in the same transcript or, for a spawned edge, in the transcript that spawned this one; absent when none arrive.',
+    frames: 'The distinct frames a transcript\'s steps ran in, each as a frame above with the reach of the session; a step names one by position.',
     frameworks: 'The frameworks of the project, each from a closed public list; never a path or a name of yours.',
     harness: 'Which harness wrote the session, one of a closed list.',
-    harnessVersion: 'The harness version, only when it is a public release; else the literal placeholder.',
-    host: 'The host of a web fetch or search, only when it is on the public list; else private, or null when the step names no host.',
+    harnessVersion: 'The harness version: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. A transcript or prompt frame carries the value capture closed it to (the public name, else `<literal>`), sent as it is; the version of a call, which capture keeps as its line names it, goes as the string after the gate.',
+    host: 'The host of a web fetch or search, the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters; null when the step names no host. Capture keeps the host as the address names it, without credentials, path, or query. The pool replaces a host with a keyed hash on arrival and serves it only once enough accounts report it.',
+    hour: 'The UTC hour of day, 0 to 23, beside the day; never a minute, a second, or an offset.',
     id: "A hash the client computes per account from the account and the session, so a redeposit replaces and two accounts' sessions cannot be joined. Never the session id.",
-    identity: 'What a step called, in closed vocabulary: a shell program with its subcommand and flags, an MCP server and tool, a skill, or a web host; null for an action with none.',
-    input: 'A bucket of the input tokens in a prompt, a number.',
+    identity: 'What a step called: a shell program with its subcommand and flags, an MCP server and tool, a skill, or a web host, each a name after redaction or `private`; null for an action with none.',
+    input: 'A bucket of the input tokens in a prompt, a number, or null when the source never recorded it.',
+    kind: 'How an edge came about, one of a closed list: next, spawned, retried, or after-error.',
+    keys: 'The input key names of a call, sorted: a public tool\'s from its published list and any other tool\'s only when each passes the name gate; none for a tool that went as private. Names only, never a value.',
+    keysDropped: 'A bucket of the key names of a call that were not sent, off a public tool\'s list or kept private by the gate, a number; never the names.',
+    intervention: 'Whether a human stepped in after a prompt\'s work and how, one of a closed list: none, after-error (the prompt\'s last call failed), redo (the next prompt edited the same file), revert (the next prompt undid the edit), user-stop (the human rejected a call or interrupted the turn), or unknown; absent when the prompt predates the signal. An outcome row, not a grade; never the next prompt\'s words.',
     language: 'A programming language of the project, from a closed public list, or other for any language off the list, beside its share bucket.',
     languageShare: 'How much of the files a session touched are in one language, one of four buckets: none, under 10 percent, 10 up to 50, or 50 and over; never a count of files.',
     languageShares: 'The share bucket of each language of the project whose share is known; a language with no share is in the languages list alone.',
@@ -61,36 +96,51 @@ export const FIELD_ROWS = {
     leaves: 'How many lines of a transcript its root covers, a count.',
     merkleRoot: 'The Merkle root of a transcript: a SHA-256 over the hashes of its lines, one root for each transcript, the main one first; never a line.',
     metric: 'What a delta measures, calls per session or thinking tokens, one of a closed list the field fixes.',
-    model: 'The model name, only when it is a public one; else the literal placeholder.',
+    model: 'The model name: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. A transcript or prompt frame carries the value capture closed it to (the public name, else `<literal>`), sent as it is; the model of a call, which capture keeps as its line names it, goes as the string after the gate.',
     ms: 'A bucket of the milliseconds a step took (a lower bound), a number or null; never the exact time.',
-    name: 'The name of a package a shell command pulled or a delta removed, only when it is on the public list; else private. A plugin in a delta is always private, and null when a delta names its field alone.',
-    native: "The name the harness gave the tool, only when it is in this client's action table; else private.",
-    output: 'A bucket of the output tokens in a prompt, a number.',
-    parent: 'The position of the main-run call that spawned this step, a number, or null (also null for a subagent a subagent spawned).',
+    name: 'The name of a package a shell command pulled or a delta removed, as capture kept it: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. A plugin in a delta is always private, and null when a delta names its field alone.',
+    native: 'The name the harness gave the tool: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters.',
+    next: 'The actions of up to the next 5 calls of the same prompt after a failed call, each one of the closed list of canonical actions: what followed, never a fix; no command, path, or text.',
+    output: 'A bucket of the output tokens in a prompt, a number, or null when the source never recorded it.',
+    parent: 'The position of the call that spawned this step, in the tools of the transcript that spawnedIn names, a number, or null.',
     platform: 'The operating system family, one of a closed list.',
-    program: 'The program a shell command ran, when it is on the public list; else the word private.',
+    program: 'The program a shell command ran, its basename only: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters.',
     prompt: 'Which prompt of the batch a tool call follows, a position in this batch, or null.',
     prompts: 'The prompts of a transcript: each a class, bucketed counts and tokens, and a frame; never their words.',
     pulls: 'The packages a shell command pulled from a registry: the registry, the public package name, and its version.',
+    recoveryCalls: 'For a failed call, what followed it: the actions of up to its next 5 calls and whether one wrote a file. Absent on a call that did not fail; never a signature or text.',
     registry: 'Which registry a pull or a removed package came from, one of a closed list; null for a delta whose name is private or absent.',
-    remainingTokens: 'A bucket of the tokens the run spent after a step (a lower bound), a number: the bucket of the exact sum, with the subagent runs a main-run step spawned later in the session.',
-    server: 'The MCP server a call went to, only when it is on the public list; else private.',
+    remainingTokens: 'A bucket of the tokens the run spent after a step (a lower bound), a number, or null when steps follow and none reported tokens: the bucket of the exact sum, with the subagent runs a main-run step spawned later in the session.',
+    server: 'The MCP server a call went to: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters.',
     shell: 'The shell a command ran in, one of a closed list, or null.',
     side: 'Whether a tool call ran as a side call, true or false.',
+    spawnedIn: 'The position, among the transcripts of the batch, of the transcript that spawned this one, a number; null for the main run and for a subagent whose spawner the batch does not hold.',
     size: 'A size class of the repository, one of a closed list, or null; never a count of files.',
-    skill: 'The skill a step ran, only when it is on the public list; else private.',
+    mcp: 'The MCP servers in reach of a session (offered, loaded, or called), each the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters, sorted; never a tool, an argument, or a path.',
+    orgSize: 'How many people the operator\'s organization has, one of a closed list of bands or unknown; set by the operator on this machine, never looked up.',
+    plugins: 'The plugins in reach of a session, each the word private, since no plugin list is pinned; their number, never their names.',
+    reach: 'The MCP servers, skills, and plugins in reach of a session, and whether the harness recorded them; every name is the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters (a plugin is always private).',
+    repoKey: "A hash of the repository salted with this store's salt: one store's sessions in one repository share it; one account on two machines gets two keys until the account salt lands. 16 hex characters; never a path, a remote, or a name.",
+    repoVisibility: 'Whether the repository is public or private, or unknown; set by the operator on this machine, never looked up.',
+    skill: 'The skill a step ran (a skill-run name capture keeps as it is after redaction), or the skill whose run the step\'s call sat in, the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. Absent on a step outside a skill\'s run.',
+    skills: 'The skills in reach of a session (called in it), each the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters, sorted.',
     stack: 'The languages, frameworks, and size class of the project.',
     status: 'Whether a tool call or a step succeeded: ok, error, or none.',
     steps: 'The steps of a tool call, each an action in closed vocabulary with its bucketed cost and spawner.',
-    sub: 'The subcommand of a shell program, only when it is on the public list for that program; else null.',
-    thinking: 'A bucket of the thinking tokens in a prompt, a number.',
+    team: 'Whether the repository\'s local git log shows one commit author or several, or unknown; a count taken on this machine and dropped, never an author.',
+    sub: 'The subcommand of a shell program, or null: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. Capture still drops a subcommand or flag off the pinned vocabulary of its program, so a real session sends no off-list subcommand (null) and no off-list flag; a subcommand or flag the vocabulary lists goes as its name.',
+    thinking: 'A bucket of the thinking tokens in a prompt, a number, or null when the source never recorded it.',
+    target: 'The position of the step an edge names, a number counted over the steps of one transcript in call order.',
+    targetClass: 'The class of the path a call touched, one of a closed list: source, test, config, doc, lockfile, generated, data, none, other; never the path or its name.',
     timingPrint: 'A hash of the call durations of the main transcript in the order they ran, or null under 50 timed calls; the calls of a subagent are not in it.',
     tokens: 'A bucket of tokens (a lower bound of the count), a number or null; a step holds one, never the exact count.',
-    tool: 'The tool of an MCP call, only when it is on the public list for that server; else the literal placeholder.',
+    tool: 'The tool of an MCP call: the name as it is after redaction, beside a server that is not private and in a harness whose spelling delimits the server; else the literal placeholder.',
     tools: 'The tool calls of a transcript, each a status and duration and its steps, in the order they ran; never their targets or arguments.',
-    transcripts: 'The main transcript, then each subagent: its frame, prompts, and tool calls, every value checked against the closed vocabulary before the batch is built.',
+    transcripts: 'The main transcript, then each subagent: its frame, prompts, and tool calls, every value checked against its field\'s list or the name shape before the batch is built.',
     usage: 'The tokens of a prompt as buckets (lower bounds): input, cache write, cache read, output, and thinking.',
+    usageResponses: 'A bucket of the responses of a prompt that reported usage, what a partial usage sum covers; left out only for a record captured before the coverage existed (capture version 20).',
     version: 'The version of a pulled package, only when it is a registry version; else the literal placeholder or null.',
+    vocabVersion: 'The version of the closed vocabulary this client built the batch under: a constant of this client, never a value from a session.',
     wallSec: 'A bucket of the seconds a prompt took, or null.',
 };
 /**
@@ -116,7 +166,7 @@ export const writeBatch = async (outbox, key, batch, stamp = currentStamp()) =>
             await rm(join(folder, name), { force: true });
     }
     await writeFile(join(folder, `${key}.${hash}.jsonl`), bytes, 'utf8');
-    return { hash, folder };
+    return { hash, folder, bytes: Buffer.byteLength(bytes) };
 };
 export const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
 /** A path that is missing, or has a file where a folder should be, holds nothing. */
@@ -195,13 +245,16 @@ const wasShown = async (outbox, hash) => {
         throw error;
     }
 };
-/** The lock on `deposit --send`: a batch goes only if it is in the outbox, its hash was printed, and its file still hashes to that hash. The first check that fails names why. */
-export const lockedBatch = async (outbox, hash, stamp = currentStamp()) => {
-    const folder = join(outbox, stamp);
+/**
+ * The lock on a send: a batch goes only if it is in the outbox, its hash was printed, and its file still hashes to that hash. The first check that fails names why. The nightly task sends with `requireShown: false`,
+ * because covenant acceptance is its consent and it prints nothing; the other two checks still hold.
+ */
+export const lockedBatch = async (outbox, hash, options = {}) => {
+    const folder = join(outbox, options.stamp ?? currentStamp());
     const name = (await namesIn(folder)).find((entry) => BATCH_FILE.exec(entry)?.[2] === hash);
     if (name === undefined)
         return { ok: false, code: 'batch_unknown' };
-    if (!(await wasShown(outbox, hash)))
+    if (options.requireShown !== false && !(await wasShown(outbox, hash)))
         return { ok: false, code: 'batch_not_shown' };
     const file = join(folder, name);
     const bytes = await unchangedBytes(file, hash);

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

@@ -1,6 +1,6 @@
 /** One request as it will leave this machine. */
 export interface Outgoing {
-    method: 'GET' | 'POST';
+    method: 'GET' | 'POST' | 'PUT';
     url: URL;
     /** Every header this code sets. The HTTP layer adds `host`, `connection`, and `content-length` itself, and `printed` lists those too. */
     headers: Array<[string, string]>;

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

@@ -0,0 +1,27 @@
+/** Parts of a raw copy, each at most this many bytes: under the pool's 1 MB per request. */
+export declare const RAW_PART_BYTES: number;
+/** The folder of the raw copies this client builds now; one built under another redaction or capture version is never sent. */
+export declare const rawStamp: () => string;
+export declare const rawHash: (bytes: string) => string;
+/** Writes one redacted transcript for a session, replacing an earlier copy of the same place. */
+export declare const writeRaw: (outbox: string, key: string, place: number, bytes: string) => Promise<{
+    hash: string;
+    bytes: number;
+}>;
+export interface HeldRaw {
+    key: string;
+    place: number;
+    hash: string;
+    file: string;
+    body: string;
+    bytes: number;
+}
+/** The raw copies under the current stamp that still hash to their names; `edited` counts those that no longer do, which are neither printed nor sent. */
+export declare const heldRaw: (outbox: string) => Promise<{
+    copies: HeldRaw[];
+    edited: number;
+}>;
+/** Removes every raw copy whose session key is not in `kept` (all of them when none is), and returns how many went. A folder switched off, a consent withdrawn, or a session no longer passing the gates leaves nothing queued. */
+export declare const removeRawExcept: (outbox: string, kept: ReadonlySet<string>, only?: string) => Promise<number>;
+/** The parts a raw copy goes in, in order. */
+export declare const rawParts: (body: string) => string[];

package/dist/sessions/pool-raw.js

@@ -0,0 +1,68 @@
+// The raw part of the outbox (t884): one redacted copy of each transcript of a session that passed the gates, in the same outbox as the batches and printed by the same command. A copy is named for its
+// session key, its place among the session's transcripts (0 is the main one), and the SHA-256 of its redacted bytes, which is the hash the pool's `/v1/raw/:sha256` routes take.
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { partsOf } from './pool-outbox.js';
+import { REDACTION_VERSION } from './redact.js';
+import { CAPTURE_VERSION } from './schema.js';
+const RAW_FILE = /^([0-9a-f]{16})\.(\d+)\.([0-9a-f]{64})\.redacted$/;
+/** Parts of a raw copy, each at most this many bytes: under the pool's 1 MB per request. */
+export const RAW_PART_BYTES = 512 * 1024;
+/** The folder of the raw copies this client builds now; one built under another redaction or capture version is never sent. */
+export const rawStamp = () => `raw-r${REDACTION_VERSION}-c${CAPTURE_VERSION}`;
+export const rawHash = (bytes) => createHash('sha256').update(Buffer.from(bytes, 'utf8')).digest('hex');
+const namesIn = async (folder) => {
+    try {
+        return (await readdir(folder)).sort();
+    }
+    catch {
+        return [];
+    }
+};
+/** Writes one redacted transcript for a session, replacing an earlier copy of the same place. */
+export const writeRaw = async (outbox, key, place, bytes) => {
+    const folder = join(outbox, rawStamp());
+    const hash = rawHash(bytes);
+    await mkdir(folder, { recursive: true });
+    for (const name of await namesIn(folder)) {
+        const found = RAW_FILE.exec(name);
+        if (found?.[1] === key && Number(found[2]) === place && found[3] !== hash)
+            await rm(join(folder, name), { force: true });
+    }
+    await writeFile(join(folder, `${key}.${String(place)}.${hash}.redacted`), bytes, 'utf8');
+    return { hash, bytes: Buffer.byteLength(bytes) };
+};
+/** The raw copies under the current stamp that still hash to their names; `edited` counts those that no longer do, which are neither printed nor sent. */
+export const heldRaw = async (outbox) => {
+    const folder = join(outbox, rawStamp());
+    const copies = [];
+    let edited = 0;
+    for (const name of await namesIn(folder)) {
+        const found = RAW_FILE.exec(name);
+        if (found === null)
+            continue;
+        const file = join(folder, name);
+        const body = await readFile(file, 'utf8');
+        if (rawHash(body) === found[3])
+            copies.push({ key: found[1] ?? '', place: Number(found[2]), hash: found[3], file, body, bytes: Buffer.byteLength(body) });
+        else
+            edited += 1;
+    }
+    return { copies, edited };
+};
+/** Removes every raw copy whose session key is not in `kept` (all of them when none is), and returns how many went. A folder switched off, a consent withdrawn, or a session no longer passing the gates leaves nothing queued. */
+export const removeRawExcept = async (outbox, kept, only) => {
+    const folder = join(outbox, rawStamp());
+    let removed = 0;
+    for (const name of await namesIn(folder)) {
+        const found = RAW_FILE.exec(name);
+        if (found !== null && !kept.has(found[1] ?? '') && (only === undefined || found[1] === only)) {
+            await rm(join(folder, name), { force: true });
+            removed += 1;
+        }
+    }
+    return removed;
+};
+/** The parts a raw copy goes in, in order. */
+export const rawParts = (body) => partsOf(body, RAW_PART_BYTES);

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

@@ -0,0 +1,35 @@
+import { type Bundle, type PinnedKey } from './pool-wire.js';
+import type { Harness } from './schema.js';
+export declare const textIn: (value: object, key: string) => string | undefined;
+export declare const numberIn: (value: object, key: string) => number | undefined;
+export declare const isObject: (value: unknown) => value is object;
+/** One server's sign-in, as `login` saved it. */
+export interface SignIn {
+    server: string;
+    account: string;
+    token: string;
+    expiresAt: number;
+    /** Pinned at the first login to this server; every bundle is checked against it. */
+    signingKey: PinnedKey;
+}
+export declare const signInOf: (value: unknown) => SignIn | undefined;
+export declare const signInsFile: (storeDir: string) => string;
+/** Every saved sign-in. A file that cannot be read stops the command: treating it as empty would forget a pin and trust whatever key the server names next. */
+export declare const loadSignIns: (storeDir: string, step: string) => Promise<SignIn[]>;
+/** One folder per harness under the server's, so a fetch for one harness never overwrites another's bundle of the same version. */
+export declare const replicaFile: (storeDir: string, server: string, harness: Harness, harnessVersion: string) => string;
+/** What an earlier fetch kept: the bundle, checked again against the pinned key, and the ETag the pool sent with it. Nothing readable and verified is nothing kept, and the next fetch is then an ordinary one. */
+export declare const keptReplica: (file: string, key: PinnedKey, harness: Harness, harnessVersion: string) => Promise<{
+    etag: string | undefined;
+    bundle: Bundle;
+} | undefined>;
+/** A session's harness and the version it runs, as a hook input, a transcript, or the store states them. */
+export interface Setup {
+    harness: Harness;
+    harnessVersion: string;
+}
+/**
+ * The kept bundle for a session's own harness and version, from the first signed-in server that kept one which still verifies; undefined otherwise. It never throws: a damaged
+ * sign-in file, a missing or corrupt replica, or one signed for another harness all mean the caller answers from the local store alone, and a hook must not fail on any of them.
+ */
+export declare const sessionBundle: (storeDir: string, setup: Setup | undefined) => Promise<Bundle | undefined>;

package/dist/sessions/pool-replica.js

@@ -0,0 +1,91 @@
+// The kept pool bundle: where `oars pool fetch` keeps one harness version's signed bundle, the sign-ins whose pinned keys verify it, and the one reader every caller uses (t926).
+// `poolFetch` reads it for its ETag, and recall, the MCP tool, and the hooks read it for the session's own harness and version. A reader for recall is fail-open: no bundle,
+// one for another harness, or one that does not verify means local reads only, and nothing is printed.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { isMissing } from './pool-outbox.js';
+import { isBundleVersion, verifyBundle } from './pool-wire.js';
+import { contentHash } from './read.js';
+export const textIn = (value, key) => {
+    const found = Reflect.get(value, key);
+    return typeof found === 'string' && found !== '' ? found : undefined;
+};
+export const numberIn = (value, key) => {
+    const found = Reflect.get(value, key);
+    return typeof found === 'number' && Number.isFinite(found) ? found : undefined;
+};
+export const isObject = (value) => typeof value === 'object' && value !== null;
+const keyOf = (value) => {
+    if (!isObject(value))
+        return undefined;
+    const [kty, crv, x] = [textIn(value, 'kty'), textIn(value, 'crv'), textIn(value, 'x')];
+    return kty === 'OKP' && crv === 'Ed25519' && x !== undefined ? { kty, crv, x } : undefined;
+};
+export const signInOf = (value) => {
+    if (!isObject(value))
+        return undefined;
+    const [server, account, token, expiresAt] = [textIn(value, 'server'), textIn(value, 'account'), textIn(value, 'token'), numberIn(value, 'expiresAt')];
+    const signingKey = keyOf(Reflect.get(value, 'signingKey'));
+    return server === undefined || account === undefined || token === undefined || expiresAt === undefined || signingKey === undefined ? undefined : { server, account, token, expiresAt, signingKey };
+};
+export const signInsFile = (storeDir) => join(storeDir, 'pool-accounts.json');
+/** Every saved sign-in. A file that cannot be read stops the command: treating it as empty would forget a pin and trust whatever key the server names next. */
+export const loadSignIns = async (storeDir, step) => {
+    const file = signInsFile(storeDir);
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return [];
+        throw error;
+    }
+    const damaged = new CliError(`${file} cannot be read. Remove it, then run oars pool login again.`, ExitCode.INVALID, step);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw damaged;
+    }
+    if (!Array.isArray(parsed))
+        throw damaged;
+    const entries = parsed;
+    return entries.map((entry) => {
+        const signIn = signInOf(entry);
+        if (signIn === undefined)
+            throw damaged;
+        return signIn;
+    });
+};
+/** One folder per harness under the server's, so a fetch for one harness never overwrites another's bundle of the same version. */
+export const replicaFile = (storeDir, server, harness, harnessVersion) => join(storeDir, 'pool-replica', contentHash(server), harness, `${encodeURIComponent(harnessVersion)}.json`);
+/** What an earlier fetch kept: the bundle, checked again against the pinned key, and the ETag the pool sent with it. Nothing readable and verified is nothing kept, and the next fetch is then an ordinary one. */
+export const keptReplica = async (file, key, harness, harnessVersion) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const verified = await verifyBundle(parsed, key, harness, harnessVersion);
+    return verified.ok ? { etag: isObject(parsed) ? textIn(parsed, 'etag') : undefined, bundle: verified.bundle } : undefined;
+};
+/**
+ * The kept bundle for a session's own harness and version, from the first signed-in server that kept one which still verifies; undefined otherwise. It never throws: a damaged
+ * sign-in file, a missing or corrupt replica, or one signed for another harness all mean the caller answers from the local store alone, and a hook must not fail on any of them.
+ */
+export const sessionBundle = async (storeDir, setup) => {
+    if (setup === undefined || !isBundleVersion(setup.harnessVersion))
+        return undefined;
+    const signIns = await loadSignIns(storeDir, 'recall').catch(() => []);
+    for (const { server, signingKey } of signIns) {
+        const kept = await keptReplica(replicaFile(storeDir, server, setup.harness, setup.harnessVersion), signingKey, setup.harness, setup.harnessVersion);
+        if (kept !== undefined)
+            return kept.bundle;
+    }
+    return undefined;
+};

package/dist/sessions/pool-send-lock.d.ts

@@ -0,0 +1,20 @@
+import { type FileHandle } from 'node:fs/promises';
+export interface LockTimes {
+    /** A lock file untouched for longer than this was left by a run that died; its holder touches it every quarter of this. */
+    staleMs: number;
+    /** How long a run waits for the lock before it gives up. */
+    waitMs: number;
+    pollMs: number;
+}
+/** What a test replaces: `stat` to read a lock as stale at the moment a waiter looks, `open` to make the create fail the way Windows does, `platform` to pick the platform's rules. */
+export interface LockFs {
+    stat: (path: string) => Promise<{
+        mtimeMs: number;
+    }>;
+    open?: (path: string, flags: 'wx') => Promise<FileHandle>;
+    platform?: NodeJS.Platform;
+}
+export declare class SendLockBusy extends Error {
+    constructor();
+}
+export declare const withSendLock: <T>(outbox: string, run: () => Promise<T>, times?: Partial<LockTimes>, fs?: LockFs) => Promise<T>;