@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/pi.js

@@ -0,0 +1,353 @@
+// The Pi source: a Pi coding agent session file becomes the same capture records a Claude Code transcript does.
+//
+// FIXTURE-DERIVED: written from the public source and docs of the agent (github.com/badlogic/pi-mono, now earendil-works/pi, @ 085c84e98e7f4c950f2be606466fff4f75d8fe7c,
+// packages/coding-agent/, npm `@earendil-works/pi-coding-agent` 1.5.0; the earlier `@mariozechner/pi-coding-agent` wrote the same files), not from a live store. Nothing was copied; the
+// reader is original. No vendor text promises the format (docs/session-format.md names the file version and says an older file is migrated when loaded, and sends programs to the SDK),
+// so `docs/sessions-store.md` says what a live run would still have to prove.
+//
+// Where it reads from (`piRoot`): `$PI_CODING_AGENT_DIR`, else `~/.pi/agent` (`%USERPROFILE%\.pi\agent` on Windows) (src/config.ts:610, :613-614, :630-636, docs/environment-variables.md:81). A session is
+// `sessions/--<cwd with its leading separator removed and / \ : turned into ->--/<ISO time with : . turned into ->_<session id>.jsonl` (docs/session-format.md:10-14,
+// session-manager.ts:590-593). The sessions folder can be moved by `--session-dir`, `PI_CODING_AGENT_SESSION_DIR`, or a setting (docs/sessions.md:60); this reader does not follow those.
+// A file is written only once a conversation exists, then appended to (session-manager.ts:1176-1190). Line 1 is the header and every later line is an entry:
+//   session           {version, id, timestamp, cwd, parentSession?}: `version` is the FILE format's (1 linear, 2 tree, 3 `hookMessage` renamed `custom`), not Pi's; no app version is recorded.
+//                     The session's cwd is fixed (docs/sessions.md:15): a `cd` inside a command is not tracked, and a resume from another folder runs in this one.
+//   message           {id, parentId, timestamp (ISO), message}: `message.timestamp` is Unix ms (docs/message-types.md:5). Roles read here: `user` (content a string or text/image
+//                     blocks), `assistant` (content text/thinking/toolCall blocks, `model`, `responseModel?`, `usage`, `stopReason`), `toolResult` (toolCallId, content text blocks,
+//                     `isError`), and `bashExecution` (the operator's own `!cmd`: command, output, exitCode, cancelled). Every other role (`custom`, `hookMessage`, `branchSummary`,
+//                     `compactionSummary`, `system`) is an extension's or the harness's text, not a prompt.
+//   every other type  `model_change`, `thinking_level_change`, `usage`, `compaction`, `branch_summary`, `custom`, `custom_message`, `context_edit`, `label`, `session_info`: not read. The usage
+//                     on a `compaction`, a `branch_summary`, and a `usage` entry is model work that is not a response, and a tool result's `usage` and `nestedCalls` are nested work
+//                     (docs/message-types.md:177): none is a response of this session.
+// Entries form a tree (`id`, `parentId`) and the leaf is the LAST entry in the file (session-manager.ts:1104-1112), so the branch the session is on is the path from the last entry to its
+// root; that path is what is read, and an abandoned branch is not. A version 1 file has no ids and is one chain in file order (session-manager.ts:287-313). A fork or clone is a new file
+// that starts with its parent's path and keeps the old entry times (createBranchedSession, session-manager.ts:1643-1735); its header names `parentSession` and carries the time the
+// copy was made, so an entry timed before that is the parent's and is not this session's.
+// `usage.input` is the uncached part already: Pi takes the cache reads and writes out of the provider's prompt count (packages/ai/src/api/openai-completions.ts:1536-1550, packages/ai/src/api/openai-responses-shared.ts:636-642;
+// Anthropic's `input_tokens` is disjoint), and `reasoning` is inside `output` (docs/message-types.md:90), so the figures map one for one onto capture's disjoint fields. A response that
+// ended in an error or an abort with every figure zero never reached the provider's count (packages/ai/src/api/anthropic-messages.ts:824 starts them at zero), so it has no usage rather than a zero one.
+// Pi has no sub-agent in core (README.md:19); the example extension runs `pi --no-session` (examples/extensions/subagent/index.ts:389), which writes no file, so the parent's call is the record.
+import { open, readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, posix, win32 } from 'node:path';
+/** The Pi agent folder for an environment; a test passes its own so it never reads the real one. */
+export const piRoot = (env, home = homedir()) => {
+    const set = env.PI_CODING_AGENT_DIR;
+    if (set === undefined || set === '')
+        return join(home, '.pi', 'agent');
+    // Pi expands a leading ~ (config.ts:614).
+    return set === '~' ? home : /^~[/\\]/.test(set) ? join(home, set.slice(2)) : set;
+};
+const isObj = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const str = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+const parse = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const SAFE_ID = /^(?!\.+$)[A-Za-z0-9._-]+$/;
+/** The tools that run a command (docs/cli.md:144-146); `bashExecution` is the operator's own. */
+const SHELL_TOOLS = new Set(['bash', 'powershell']);
+/** The tools that change a file; each names it in `path` (tools/edit.ts:29-31, tools/write.ts:10-12). */
+const EDIT_TOOLS = new Set(['edit', 'write']);
+/** What a non-zero exit appends to the output (tools/bash.ts:436). */
+const EXIT_SUFFIX = /(?:^|\n\n)Command exited with code (-?\d+)$/;
+/** The header is one short line; a file whose first 64 KiB hold no line end is not a Pi file. */
+const HEADER_BYTES = 65536;
+/** An error's message with `file` cut to its base name, so a reason that is logged names no folder. */
+const reasonOf = (error, file) => (error instanceof Error ? error.message : String(error)).split(file).join(basename(file));
+const missing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+/** The non-blank lines that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
+export const piBadLines = (text) => text.split('\n').filter((raw) => raw.trim() !== '' && parse(raw) === undefined);
+/** A time in milliseconds, or undefined when it is not an absolute time after 2000. */
+const MIN_MS = Date.parse('2000-01-01T00:00:00Z');
+const absoluteMs = (ms) => (ms !== undefined && ms >= MIN_MS ? ms : undefined);
+const isoMs = (value) => {
+    const text = str(value);
+    return text === undefined ? undefined : absoluteMs(Date.parse(text) || undefined);
+};
+/** An entry's time: its ISO `timestamp`, else the message's own Unix ms. */
+const timeOf = (entry) => isoMs(entry.timestamp) ?? (isObj(entry.message) ? absoluteMs(num(entry.message.timestamp)) : undefined);
+/** A failed shell call's error line: a nonzero exit says so first, then the output. */
+const failureOf = (exit, output) => (exit < 0 && output.trim() !== '' ? output : `Exit code ${String(exit)}${output === '' ? '' : `\n${output}`}`);
+/** The text of a content value: a string, or the text blocks of an array joined by line ends. */
+const textOf = (content) => {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.flatMap((block) => (isObj(block) && block.type === 'text' && typeof block.text === 'string' ? [block.text] : [])).join('\n');
+};
+/** A path the model named, made absolute against the session's folder; the folder's own style (POSIX or Windows) decides the join. */
+const absolute = (path, cwd) => {
+    if (cwd === undefined || posix.isAbsolute(path) || win32.isAbsolute(path))
+        return path;
+    return (cwd.startsWith('/') ? posix : win32).join(cwd, path);
+};
+/** The entries on the branch the session is on, in order: the path from the last entry to its root (version 2 and later), or every entry (version 1, which has no ids). */
+const activePath = (header, body) => {
+    const version = num(header?.version) ?? 1;
+    if (version < 2)
+        return body;
+    const byId = new Map();
+    for (const entry of body) {
+        const id = str(entry.id);
+        if (id !== undefined)
+            byId.set(id, entry);
+    }
+    const path = [];
+    const seen = new Set();
+    // The leaf is the last entry written (session-manager.ts:1104-1112); an id seen twice ends a cycle, and a parent that is gone ends a broken chain.
+    let current = body.findLast((entry) => str(entry.id) !== undefined);
+    while (current !== undefined) {
+        const id = str(current.id);
+        if (id === undefined || seen.has(id))
+            break;
+        seen.add(id);
+        path.push(current);
+        const parent = str(current.parentId);
+        current = parent === undefined ? undefined : byId.get(parent);
+    }
+    return path.reverse();
+};
+/** One session as the lines `captureSession` reads. */
+export const piLines = (text, fallbackId) => {
+    const nonblank = text.split('\n').filter((raw) => raw.trim() !== '');
+    if (nonblank.length > 0 && !nonblank.some((raw) => isObj(parse(raw))))
+        throw new Error('no parseable line');
+    const entries = nonblank.map(parse).filter(isObj);
+    const header = entries.find((entry) => entry.type === 'session');
+    const headerMs = isoMs(header?.timestamp);
+    // A fork or clone starts with its parent's path, which keeps the old times; the header's time is when the copy was made (session-manager.ts:1643-1735).
+    const copiedBefore = str(header?.parentSession) === undefined ? undefined : headerMs;
+    const kept = activePath(header, entries.filter((entry) => entry.type !== 'session')).filter((entry) => {
+        const when = timeOf(entry);
+        return copiedBefore === undefined || when === undefined || when >= copiedBefore;
+    });
+    const cwd = str(header?.cwd);
+    const base = { sessionId: str(header?.id) ?? fallbackId, ...(cwd === undefined ? {} : { cwd }) };
+    const lines = [];
+    const calls = new Map();
+    const settled = new Set();
+    let sequence = 0;
+    let at = headerMs ?? 0;
+    // The last assistant line since the last prompt, which the operator's own `!cmd` joins rather than counting as a response of its own.
+    let lastResponse;
+    const stamp = (entry) => {
+        const when = timeOf(entry);
+        // A missing or earlier time says nothing about when: the latest time so far stands.
+        if (when !== undefined && when > at)
+            at = when;
+        return at === 0 ? undefined : new Date(at).toISOString();
+    };
+    const result = (id, when, failure, output = '') => {
+        sequence += 1;
+        lines.push({
+            ...base,
+            type: 'user',
+            uuid: `${fallbackId}-r${String(sequence)}`,
+            ...(when === undefined ? {} : { timestamp: when }),
+            // The result is stamped with its own time, but the call's start is not paired to it here, so no duration is claimed.
+            noDuration: true,
+            // The output follows an `Exit code 0` line, the shape a Claude Code Bash result has, so a `[branch sha]` line is still found for commit survival.
+            message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, is_error: failure !== undefined, content: failure ?? (output === '' ? '' : `Exit code 0\n${output}`) }] },
+        });
+    };
+    const response = (when, content, extra = {}, message = {}) => {
+        sequence += 1;
+        lines.push({
+            ...base,
+            type: 'assistant',
+            uuid: `${fallbackId}-a${String(sequence)}`,
+            // Every assistant line carries a requestId (`verify --strict` needs one), and each response has its own, so its usage counts once.
+            requestId: `${fallbackId}-resp${String(sequence)}`,
+            ...(when === undefined ? {} : { timestamp: when }),
+            ...extra,
+            message: { role: 'assistant', content, ...message },
+        });
+        lastResponse = { content };
+    };
+    const toolUse = (block) => {
+        const id = str(block.id) ?? '';
+        const name = str(block.name) ?? '?';
+        const input = isObj(block.arguments) ? block.arguments : {};
+        if (SHELL_TOOLS.has(name)) {
+            calls.set(id, { shell: true });
+            const command = str(input.command);
+            return { type: 'tool_use', id, name: 'Bash', native: name, input: command === undefined ? {} : { command } };
+        }
+        calls.set(id, { shell: false });
+        if (EDIT_TOOLS.has(name)) {
+            const path = str(input.path);
+            return { type: 'tool_use', id, name: 'Edit', native: name, input: path === undefined ? {} : { file_path: absolute(path, cwd) } };
+        }
+        return { type: 'tool_use', id, name, input };
+    };
+    /** The usage a response reported; undefined when it reported none, or errored before the provider counted anything. */
+    const usageOf = (message) => {
+        const raw = message.usage;
+        if (!isObj(raw))
+            return undefined;
+        const figures = { input: num(raw.input), read: num(raw.cacheRead), write: num(raw.cacheWrite), output: num(raw.output), thinking: num(raw.reasoning) };
+        const stopped = message.stopReason === 'error' || message.stopReason === 'aborted';
+        if (stopped && [figures.input, figures.read, figures.write, figures.output].every((figure) => (figure ?? 0) === 0))
+            return undefined;
+        return {
+            ...(figures.input === undefined ? {} : { input_tokens: figures.input }),
+            ...(figures.read === undefined ? {} : { cache_read_input_tokens: figures.read }),
+            ...(figures.write === undefined ? {} : { cache_creation_input_tokens: figures.write }),
+            ...(figures.output === undefined ? {} : { output_tokens: figures.output }),
+            ...(figures.thinking === undefined ? {} : { output_tokens_details: { thinking_tokens: figures.thinking } }),
+        };
+    };
+    for (const entry of kept) {
+        if (entry.type !== 'message' || !isObj(entry.message))
+            continue;
+        const message = entry.message;
+        const role = str(message.role);
+        const when = stamp(entry);
+        if (role === 'user') {
+            const body = textOf(message.content);
+            const image = Array.isArray(message.content) && message.content.some((block) => isObj(block) && block.type === 'image');
+            if (body === '' && !image)
+                continue;
+            sequence += 1;
+            lastResponse = undefined;
+            // An image-only prompt keeps its line (an image block with no data); capture counts a turn only for a prompt with text, so it is not a counted turn.
+            lines.push({ ...base, type: 'user', uuid: `${fallbackId}-u${String(sequence)}`, ...(when === undefined ? {} : { timestamp: when }), message: { role: 'user', content: [body === '' ? { type: 'image' } : { type: 'text', text: body }] } });
+        }
+        else if (role === 'assistant') {
+            const content = [];
+            for (const block of Array.isArray(message.content) ? message.content : []) {
+                if (!isObj(block))
+                    continue;
+                if (block.type === 'text' && str(block.text) !== undefined)
+                    content.push({ type: 'text', text: String(block.text) });
+                else if (block.type === 'toolCall')
+                    content.push(toolUse(block));
+            }
+            const model = str(message.model);
+            const reported = str(message.responseModel);
+            const usage = usageOf(message);
+            response(when, content, model === undefined ? {} : { requestedModel: model }, { ...(reported === undefined ? {} : { model: reported }), ...(usage === undefined ? {} : { usage }) });
+        }
+        else if (role === 'toolResult') {
+            const id = str(message.toolCallId);
+            const call = id === undefined ? undefined : calls.get(id);
+            if (id === undefined || call === undefined || settled.has(id))
+                continue;
+            settled.add(id);
+            const output = textOf(message.content);
+            if (message.isError !== true) {
+                result(id, when, undefined, call.shell ? output : '');
+            }
+            else if (call.shell) {
+                // A non-zero exit ends the text with the code (tools/bash.ts:434-440), the one place the persisted result keeps it; an abort, a timeout, and a spawn error carry no such suffix and stand as written.
+                const exit = EXIT_SUFFIX.exec(output);
+                result(id, when, exit === null ? (output === '' ? 'tool failed' : output) : failureOf(Number(exit[1]), output.slice(0, exit.index)));
+            }
+            else {
+                result(id, when, output === '' ? 'tool failed' : output);
+            }
+        }
+        else if (role === 'bashExecution') {
+            // The operator's own `!cmd`: a real exit code, no model behind it.
+            sequence += 1;
+            const id = `${fallbackId}-bang${String(sequence)}`;
+            const command = str(message.command);
+            const block = { type: 'tool_use', id, name: 'Bash', native: 'bash', input: command === undefined ? {} : { command } };
+            if (lastResponse === undefined)
+                response(when, [block]);
+            else
+                lastResponse.content.push(block);
+            const output = typeof message.output === 'string' ? message.output : '';
+            const exit = num(message.exitCode);
+            let failure;
+            if (message.cancelled === true)
+                failure = output === '' ? 'Command cancelled' : output;
+            else if (exit === undefined)
+                failure = output === '' ? 'Command ended without an exit code' : output;
+            else if (exit !== 0)
+                failure = failureOf(exit, output);
+            result(id, when, failure, output);
+        }
+    }
+    return lines;
+};
+/** The first line of a file, read from its first 64 KiB; undefined when the file is empty. */
+const firstLine = async (file) => {
+    const handle = await open(file, 'r');
+    try {
+        const buffer = Buffer.alloc(HEADER_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, HEADER_BYTES, 0);
+        const text = buffer.subarray(0, bytesRead).toString('utf8');
+        const line = text.split('\n', 1)[0] ?? '';
+        return line.trim() === '' ? undefined : line;
+    }
+    finally {
+        await handle.close();
+    }
+};
+export const openPiStore = async (root) => {
+    const base = join(root, 'sessions');
+    const unreadable = [];
+    let folders;
+    try {
+        folders = await readdir(base, { withFileTypes: true });
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        return { sessions: [], transcript: () => Promise.reject(new Error('no sessions')), rejected: 0, unreadable: [{ file: base, reason: reasonOf(error, base) }] };
+    }
+    const sessions = [];
+    let rejected = 0;
+    for (const folder of folders.filter((candidate) => candidate.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+        let files;
+        try {
+            files = await readdir(join(base, folder.name), { withFileTypes: true });
+        }
+        catch (error) {
+            unreadable.push({ file: join(base, folder.name), reason: reasonOf(error, join(base, folder.name)) });
+            continue;
+        }
+        for (const entry of files.filter((candidate) => candidate.isFile() && candidate.name.endsWith('.jsonl')).sort((a, b) => a.name.localeCompare(b.name))) {
+            // `<timestamp>_<id>.jsonl`: the timestamp has no underscore, so the id is everything after the first one (docs/session-format.md:11-14).
+            const stem = entry.name.slice(0, -'.jsonl'.length);
+            const id = stem.includes('_') ? stem.slice(stem.indexOf('_') + 1) : stem;
+            if (!SAFE_ID.test(id)) {
+                rejected += 1;
+                continue;
+            }
+            const file = join(base, folder.name, entry.name);
+            try {
+                const first = await firstLine(file);
+                const header = first === undefined ? undefined : parse(first);
+                if (!isObj(header) || header.type !== 'session') {
+                    unreadable.push({ file, reason: 'no session header on the first line' });
+                    continue;
+                }
+                const info = await stat(file);
+                sessions.push({ id, folder: str(header.cwd) ?? null, file, size: info.size, mtimeMs: Math.floor(info.mtimeMs) });
+            }
+            catch (error) {
+                if (!missing(error))
+                    unreadable.push({ file, reason: reasonOf(error, file) });
+            }
+        }
+    }
+    sessions.sort((a, b) => a.mtimeMs - b.mtimeMs || a.id.localeCompare(b.id));
+    return {
+        sessions,
+        rejected,
+        unreadable,
+        transcript: async (session) => {
+            const text = await readFile(session.file, 'utf8');
+            const lines = [...piLines(text, session.id).map((line) => JSON.stringify(line)), ...piBadLines(text)];
+            return lines.join('\n') + (lines.length === 0 ? '' : '\n');
+        },
+    };
+};

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

@@ -0,0 +1,21 @@
+import { type Bundle } from './pool-wire.js';
+/** The newest kept bundle that still verifies against the key pinned for its server; undefined when none was fetched or none verifies. An unreadable sign-ins file stops the command (`loadSignIns`) and is not read as no bundle. */
+export declare const lastFetchedBundle: (storeDir: string) => Promise<Bundle | undefined>;
+/** The pool lines of `books`: the four, or one plain line when there is nothing to state them from. */
+export declare const booksLines: (bundle: Bundle | undefined) => string[];
+/** The totals as flat numbers for the health batch to read; a field with no source is null and never 0, and a bundle with no books gives null. */
+export interface BooksTotals {
+    /** Lineage (section 17 rule 6): the floor the served count was held to, the day it was as of, and the day the panel was counted, which a 304 can leave days old. */
+    floor: number;
+    asOfDay: string | null;
+    panelDay: string | null;
+    servedCells: number;
+    belowFloor: number;
+    panel: number | null;
+    comparisonReadOwners: number | null;
+    followOnReads: number | null;
+    readYield: number | null;
+    costPerServedCell: number | null;
+    yieldPerServedCell: number | null;
+}
+export declare const booksTotals: (bundle: Bundle | undefined) => BooksTotals | null;

package/dist/sessions/pool-books.js

@@ -0,0 +1,75 @@
+// `oars sessions books`, the pool's side: the set of four (the pool design notes, set of four) from the last fetched bundle. The bundle is the replica a fetch kept, checked again against the key pinned at login, so a
+// file edited on disk prints nothing. A field with no source says so and is never printed as zero.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadSignIns } from './pool-command.js';
+import { isHarness, verifyBundle } from './pool-wire.js';
+import { contentHash } from './read.js';
+const names = async (folder) => readdir(folder).catch(() => []);
+const candidatesOf = async (storeDir) => {
+    const root = join(storeDir, 'pool-replica');
+    const found = [];
+    for (const server of await names(root)) {
+        for (const harness of await names(join(root, server))) {
+            for (const name of await names(join(root, server, harness))) {
+                if (!name.endsWith('.json'))
+                    continue;
+                const file = join(root, server, harness, name);
+                found.push({ file, server, harness, version: decodeURIComponent(name.slice(0, -'.json'.length)), modified: (await stat(file)).mtimeMs });
+            }
+        }
+    }
+    return found.sort((a, b) => b.modified - a.modified);
+};
+/** The newest kept bundle that still verifies against the key pinned for its server; undefined when none was fetched or none verifies. An unreadable sign-ins file stops the command (`loadSignIns`) and is not read as no bundle. */
+export const lastFetchedBundle = async (storeDir) => {
+    const keys = await loadSignIns(storeDir, 'books');
+    for (const { file, server, harness, version } of await candidatesOf(storeDir)) {
+        const key = keys.find((entry) => contentHash(entry.server) === server)?.signingKey;
+        if (key === undefined || !isHarness(harness))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const verified = await verifyBundle(parsed, key, harness, version);
+        if (verified.ok)
+            return verified.bundle;
+    }
+    return undefined;
+};
+const shown = (field, unit) => (field.state === 'value' ? `${String(field.value)}${unit}` : `no source yet (${field.reason})`);
+const linesOf = (books) => [
+    `served cells ${String(books.served.total)}, below floor ${String(books.backlog)}, as of ${books.asOf.day ?? 'no known day'}`,
+    books.panel.state === 'value' ? `panel: ${String(books.panel.value)} accounts deposited in the last four weeks${books.panelDay === null ? '' : `, as of ${books.panelDay}`}` : `panel: ${shown(books.panel, '')}`,
+    `demand: comparison-read owners ${shown(books.demand.comparisonReadOwners, '')}, follow-on reads ${shown(books.demand.followOnReads, '')}`,
+    `goal metric: read yield ${shown(books.goal.readYield, '')}, cost per served cell ${shown(books.goal.costPerServedCell, '')}, yield per served cell ${shown(books.goal.yieldPerServedCell, '')}`,
+];
+/** The pool lines of `books`: the four, or one plain line when there is nothing to state them from. */
+export const booksLines = (bundle) => {
+    if (bundle === undefined)
+        return ['no pool bundle yet'];
+    return bundle.books === undefined ? ['the last fetched bundle carries no pool books; run oars pool fetch again'] : linesOf(bundle.books);
+};
+const valueOf = (field) => (field.state === 'value' ? field.value : null);
+export const booksTotals = (bundle) => {
+    const books = bundle?.books;
+    if (books === undefined)
+        return null;
+    return {
+        floor: books.floor,
+        asOfDay: books.asOf.day,
+        panelDay: books.panelDay,
+        servedCells: books.served.total,
+        belowFloor: books.backlog,
+        panel: valueOf(books.panel),
+        comparisonReadOwners: valueOf(books.demand.comparisonReadOwners),
+        followOnReads: valueOf(books.demand.followOnReads),
+        readYield: valueOf(books.goal.readYield),
+        costPerServedCell: valueOf(books.goal.costPerServedCell),
+        yieldPerServedCell: valueOf(books.goal.yieldPerServedCell),
+    };
+};

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

@@ -0,0 +1,5 @@
+import type { FolderSend, PoolChoices } from './store.js';
+export type Sends = 'all' | FolderSend;
+export declare const sendsOf: (choices: PoolChoices, project: string) => Sends;
+/** Whether a raw copy of this folder's sessions may be built: raw consent granted, and the folder neither skeleton only nor off. */
+export declare const rawAllowed: (choices: PoolChoices, project: string) => boolean;

package/dist/sessions/pool-choices.js

@@ -0,0 +1,11 @@
+// What a folder may send to a pool, from the choices in `state.json`: everything (the default after the covenant is accepted), skeletons only, or nothing.
+// A project that more than one entry names takes the narrowest of them, so a switch that is off is never undone by a broader entry.
+import { compileAllow } from './allow.js';
+export const sendsOf = (choices, project) => {
+    const modes = Object.entries(choices.folders).filter(([entry]) => compileAllow([entry]).allows(project)).map(([, mode]) => mode);
+    if (modes.includes('off'))
+        return 'off';
+    return modes.includes('skeleton') ? 'skeleton' : 'all';
+};
+/** Whether a raw copy of this folder's sessions may be built: raw consent granted, and the folder neither skeleton only nor off. */
+export const rawAllowed = (choices, project) => choices.rawConsent === 'granted' && sendsOf(choices, project) === 'all';

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

@@ -0,0 +1,115 @@
+import type { Outcome, RunDeps } from '../cli.js';
+import { CliError } from '../errors.js';
+import { Masker, type Outgoing } from './pool-print.js';
+import { isObject, loadSignIns, textIn, type SignIn } from './pool-replica.js';
+import { type SessionsRuntime } from './store.js';
+import { type Git } from './survival.js';
+export declare const DEPOSIT = "pool-deposit";
+export declare const POOL_PROVIDERS: readonly ["github", "google"];
+export { isObject, loadSignIns, textIn };
+/** The Many Oars pool, used when neither `--server` nor `OARS_POOL_URL` names another. */
+export declare const DEFAULT_POOL_URL = "https://pool.manyoars.com";
+/** `--server`, else `OARS_POOL_URL`, else the Many Oars pool. A token and a session's shape cross this connection, so plain http goes only to this machine. */
+export declare const poolServer: (env: NodeJS.ProcessEnv, step: string, named?: string) => string;
+export declare const runtimeOf: (deps: RunDeps) => SessionsRuntime;
+export declare const signedIn: (deps: RunDeps, storeDir: string, server: string, step: string) => Promise<SignIn>;
+export interface Reply {
+    status: number;
+    body: unknown;
+    headers: Headers;
+}
+interface Call {
+    body?: unknown;
+    /** A body already serialized, sent as it is: a batch from the outbox, whose bytes were hashed and printed. */
+    bytes?: string;
+    token?: string;
+    /** One part of a batch sent in several: its position (from 1), how many there are, and the SHA-256 of the whole batch, which is what keeps the parts one deposit. */
+    part?: {
+        index: number;
+        count: number;
+        batch: string;
+    };
+    /** The ETag of the bundle already kept, so the pool can answer 304 with no bundle. */
+    ifNoneMatch?: string;
+    /** Set for a command that prints what it sends: the print comes first, with these secrets masked. */
+    show?: Masker;
+    /** A raw part is a PUT of bytes that are not JSON; every other call is a GET, or a POST when it has a body. */
+    method?: 'PUT';
+    type?: string;
+    /** Headers beyond the usual ones (the raw routes state their redaction and capture versions, and the raw consent). */
+    extra?: Array<[string, string]>;
+}
+/** How a request leaves this machine. The command line passes none, so a send goes over the network (`networkSender`); a test passes one to read what would leave. */
+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;
+/**
+ * `oars pool login` (spec Section 1.4): the device flow runs here, against the provider, and the pool sees only the provider's token, once, and answers its own credential. Every request prints before it is sent, with the device code, the provider's token,
+ * and the credential masked as `<credential: n bytes>`. A client ID, scope, grant type, and Google's `client_secret` print as they are: none is secret.
+ */
+export declare const poolLogin: (deps: RunDeps, options: {
+    server?: string | undefined;
+    provider?: string | undefined;
+}) => Promise<Outcome>;
+export declare const vocabularyExpired: (deps: RunDeps) => CliError | undefined;
+/** One batch to the pool: a batch past one request's bytes goes in parts, in order, each answered 202 until the last completes the deposit with 201. A part sent again is harmless, so the retry covers every part alike. */
+export declare const postBatch: (deps: RunDeps, options: {
+    server: string;
+    token: string;
+    bytes: string;
+    hash: string;
+    via: Sender;
+}) => Promise<void>;
+/**
+ * One redacted raw copy to the pool: its parts by PUT, then the completion, which the pool checks against the SHA-256 in the path. Every request states the redaction and capture versions and that the person said yes to the raw prompt;
+ * the caller sends only for a person who did. A part sent again replaces itself, and one for an object that stands writes nothing, so a copy that failed halfway is sent again whole.
+ */
+export declare const postRaw: (deps: RunDeps, options: {
+    server: string;
+    token: string;
+    hash: string;
+    body: string;
+    bytes: number;
+    via: Sender;
+}) => Promise<void>;
+/**
+ * `oars pool deposit`: every session in the store that passes both session gates is built into a canonical batch in the outbox, and the command stops: nothing is sent. The gates run before any projection does: the folder
+ * allowlist, then the exclusion check. A session that fails either, or has no raw to scan, is counted and never built. A session is built only once it has ended: no transcript of it, main or subagent, has gained a line (the later of its capture
+ * and its raw file's last write) for `session_idle_hours` (6 hours). One that has not is counted under `notEnded`, and any batch of it from an earlier pass is withdrawn. `--send <hash>` is the lock in `sendBatch`.
+ */
+export declare const poolDeposit: (deps: RunDeps, options: {
+    server?: string | undefined;
+    acceptCovenant?: string | undefined;
+    send?: string | undefined;
+    via?: Sender | undefined;
+    git?: Git | 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: {
+    server?: string | undefined;
+    explain?: boolean | 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: {
+    server?: string | undefined;
+    harness?: string | undefined;
+    harnessVersion: string;
+}) => Promise<Outcome>;
+/** The raw prompt, in plain words: shown by `oars pool raw` until it is answered, and what the nightly send relies on. Redaction is best effort and the text says so. */
+export declare const RAW_PROMPT: string;
+/** `oars pool raw`: shows the raw prompt and the answer so far; `--consent yes|no` records the answer; `--folder <entry> --mode all|skeleton|off` sets what one folder may send. */
+export declare const poolRaw: (deps: RunDeps, options: {
+    consent?: string | undefined;
+    folder?: string | undefined;
+    mode?: string | undefined;
+}) => Promise<Outcome>;
+/**
+ * `oars pool coverage`: the two bands only the operator can state, kept on this machine and read at deposit. They are what the pool can say about whom a deposit covers, not a filter; `unknown` states nothing.
+ * With no flag it prints what is set.
+ */
+export declare const poolCoverage: (deps: RunDeps, options: {
+    orgSize?: string | undefined;
+    repoVisibility?: string | undefined;
+}) => Promise<Outcome>;