@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/pool-command.js

@@ -0,0 +1,542 @@
+// `oars pool`: the only part of the sessions code that talks to a remote. The server is always named, by flag or environment, so nothing leaves on a default. Sign-in runs the provider's device flow here and reads no harness token; a session leaves only as a closed-vocabulary skeleton, and only after the exclusion check found it clean. Local capture, recall,
+// and reads never come through here.
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { CliError, exitCodeForProblem, ExitCode, unreachableError } from '../errors.js';
+import { compileAllow } from './allow.js';
+import { checkSession, exclusionPaths, lastWritten } from './exclusion.js';
+import { discardStale, FIELD_ROWS, fieldsOf, heldBatches, isMissing, lockedBatch, markShown, outboxFolder, removeBatchesExcept, removeBatchOf, staleBatches, unchangedBytes, writeBatch } from './pool-outbox.js';
+import { HARNESSES, hasEnded, SESSION_IDLE_HOURS, isBundleVersion, isHarness, parseSkeleton, sessionsOf, skeletonOf, VOCAB_VERSION, verifyBundle } from './pool-wire.js';
+import { carriedDeltas, markDeltasSent, placedOf, sentDeltas } from './pool-delta.js';
+import { Masker, printed, TRANSPORT_HEADERS, waitWords } from './pool-print.js';
+import { shellReader } from './projection.js';
+import { isVocabularyExpired, REGISTRY_MAX_AGE_DAYS, VOCAB_SNAPSHOT_DATE } from './public-vocabulary.js';
+import { contentHash } from './read.js';
+import { harnessOf as sessionHarness } from './schema.js';
+import { loadStore, readSaved, readSkeletons } from './store.js';
+import { vocabulary } from './vocab-load.js';
+const LOGIN = 'pool-login';
+const DEPOSIT = 'pool-deposit';
+const OUTBOX = 'pool-outbox';
+const POOL_DEPOSITS = '/v1/deposits';
+const FETCH = 'pool-fetch';
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+export const POOL_PROVIDERS = ['github', 'google'];
+const DEFAULT_INTERVAL_SEC = 5;
+const DEFAULT_EXPIRY_SEC = 900;
+/** RFC 8628: a `slow_down` adds five seconds to every poll after it. */
+const SLOW_DOWN_MS = 5000;
+const usage = (message, step) => new CliError(message, ExitCode.USAGE, step);
+/** `--server`, else `OARS_POOL_URL`; never a default. A token and a session's shape cross this connection, so plain http goes only to this machine. */
+export const poolServer = (env, step, named) => {
+    const given = named ?? env.OARS_POOL_URL;
+    if (given === undefined || given === '')
+        throw usage('Name the pool server with --server or OARS_POOL_URL; there is no default.', step);
+    let url;
+    try {
+        url = new URL(given);
+    }
+    catch {
+        throw usage(`The pool server ${given} is not a URL.`, step);
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname)))
+        throw usage(`Refusing the pool server ${given}: it takes https, or plain http only to localhost.`, step);
+    if (url.username !== '' || url.password !== '' || url.pathname !== '/' || url.search !== '' || url.hash !== '')
+        throw usage(`The pool server ${given} is an origin only: no credentials, path, or query.`, step);
+    return url.origin;
+};
+const runtimeOf = (deps) => {
+    if (deps.sessions === undefined)
+        throw new CliError('The session store is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
+    return deps.sessions;
+};
+const textIn = (value, key) => {
+    const found = Reflect.get(value, key);
+    return typeof found === 'string' && found !== '' ? found : undefined;
+};
+const numberIn = (value, key) => {
+    const found = Reflect.get(value, key);
+    return typeof found === 'number' && Number.isFinite(found) ? found : undefined;
+};
+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;
+};
+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 };
+};
+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. */
+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;
+    });
+};
+const signedIn = async (deps, storeDir, server, step) => {
+    const found = (await loadSignIns(storeDir, step)).find((entry) => entry.server === server);
+    if (found === undefined || found.expiresAt <= deps.now())
+        throw new CliError(`Not signed in to ${server}. Run oars pool login first.`, ExitCode.AUTH, step);
+    return found;
+};
+/** The request exactly as it will be sent: `outbox` prints it, and `ask` hands the same value to `fetch`. */
+const outgoing = (deps, server, path, init) => {
+    const headers = [['user-agent', `oars/${deps.version}`], ['accept', 'application/json']];
+    if (init.token !== undefined)
+        headers.push(['authorization', `Bearer ${init.token}`]);
+    // Node's `fetch` writes `cache-control` and `pragma` itself whenever `if-none-match` is set, so they are named here to be printed.
+    if (init.ifNoneMatch !== undefined)
+        headers.push(['if-none-match', init.ifNoneMatch], ['cache-control', 'no-cache'], ['pragma', 'no-cache']);
+    const body = init.bytes ?? (init.body === undefined ? undefined : JSON.stringify(init.body));
+    if (body !== undefined)
+        headers.push(['content-type', 'application/json']);
+    headers.push(...TRANSPORT_HEADERS);
+    return { method: body === undefined ? 'GET' : 'POST', url: new URL(path, server), headers, ...(body === undefined ? {} : { body }) };
+};
+/** 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. */
+const ask = (deps, step, server, path, init, via) => {
+    const request = outgoing(deps, server, path, init);
+    return via === undefined ? send(deps, step, request, init.show) : via(request);
+};
+/** Prints the request when asked to, then sends exactly those headers and that body. */
+const send = async (deps, step, request, show) => {
+    if (show !== undefined)
+        deps.io.stderr(`${printed(request, show)}
+`);
+    let response;
+    try {
+        response = await fetch(request.url, { method: request.method, headers: request.headers, redirect: 'error', ...(request.body === undefined ? {} : { body: request.body }) });
+    }
+    catch (error) {
+        throw unreachableError(step, error, request.url.origin);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = undefined;
+    }
+    return { status: response.status, body, headers: response.headers };
+};
+/** The sender a real send would use: the request goes out over the network as built. The command line does not pass it (sending waits on the covenant); the loopback test does, to read what reaches the socket. */
+export const networkSender = (deps, step) => (request) => send(deps, step, request, undefined);
+/** The server's named refusal, as a failure: its `error` is the problem's code in `--json`. */
+const refusal = (step, { status, body }) => {
+    const code = isObject(body) ? textIn(body, 'error') : undefined;
+    const message = (isObject(body) ? textIn(body, 'message') : undefined) ?? `The pool answered HTTP ${String(status)}.`;
+    return new CliError(message, exitCodeForProblem(status, code === undefined ? undefined : { code }), step, { title: message, status, ...(code === undefined ? {} : { code }) });
+};
+const PROVIDER_FLOWS = new Map([
+    ['github', { deviceUrl: 'https://github.com/login/device/code', tokenUrl: 'https://github.com/login/oauth/access_token', scope: '', clientIdVar: 'OARS_GITHUB_CLIENT_ID' }],
+    ['google', { deviceUrl: 'https://oauth2.googleapis.com/device/code', tokenUrl: 'https://oauth2.googleapis.com/token', scope: 'openid', clientIdVar: 'OARS_GOOGLE_CLIENT_ID', secretVar: 'OARS_GOOGLE_CLIENT_SECRET' }],
+]);
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+/** The provider's side of the flow, read from the environment. An unset value stops the command before anything is sent, and names what is missing. */
+const configOf = (env, provider) => {
+    const set = (name) => (env[name] === undefined || env[name] === '' ? undefined : env[name]);
+    const clientId = set(provider.clientIdVar);
+    if (clientId === undefined)
+        throw usage(`Set ${provider.clientIdVar} to the client ID of the Many Oars OAuth app; it is not set.`, LOGIN);
+    const clientSecret = provider.secretVar === undefined ? undefined : set(provider.secretVar);
+    if (provider.secretVar !== undefined && clientSecret === undefined)
+        throw usage(`Set ${provider.secretVar} to the client secret of the Many Oars OAuth app; it is not set.`, LOGIN);
+    return { clientId, clientSecret };
+};
+/** One form POST to a provider, printed before it is sent. The provider answers JSON on whatever status it chooses (Google's pending poll is a 428), so the caller reads the body and not the status. */
+const askProvider = (deps, url, form, masker) => {
+    const headers = [['user-agent', `oars/${deps.version}`], ['accept', 'application/json'], ['content-type', 'application/x-www-form-urlencoded'], ...TRANSPORT_HEADERS];
+    return send(deps, LOGIN, { method: 'POST', url: new URL(url), headers, body: new URLSearchParams(form).toString() }, masker);
+};
+const deviceOf = ({ body }) => {
+    // Google names the link `verification_url`, against the RFC's `verification_uri`.
+    const [deviceCode, userCode, verificationUri] = isObject(body) ? [textIn(body, 'device_code'), textIn(body, 'user_code'), textIn(body, 'verification_uri') ?? textIn(body, 'verification_url')] : [];
+    // A provider that refuses here (GitHub's `device_flow_disabled`, Google's `invalid_client`) is how an unfinished OAuth app shows, so its word goes to the operator.
+    const refusal = isObject(body) ? textIn(body, 'error') : undefined;
+    if (refusal !== undefined) {
+        const title = `The provider refused the sign-in: ${refusal}.`;
+        throw new CliError(title, ExitCode.AUTH, LOGIN, { code: 'login_refused', title });
+    }
+    // `openBrowser` parses the link before it returns its promise, so one that cannot parse has to stop here or it throws past the login's catch.
+    if (!isObject(body) || deviceCode === undefined || userCode === undefined || verificationUri === undefined || !URL.canParse(verificationUri))
+        throw new CliError('The provider did not start a sign-in.', ExitCode.UNEXPECTED, LOGIN);
+    // An interval of 0 or below would poll with no wait and never run out the clock, so it takes the default like a missing one.
+    const interval = numberIn(body, 'interval');
+    return { deviceCode, userCode, verificationUri, intervalMs: (interval === undefined || interval <= 0 ? DEFAULT_INTERVAL_SEC : interval) * 1000, expiresMs: (numberIn(body, 'expires_in') ?? DEFAULT_EXPIRY_SEC) * 1000 };
+};
+/** Polls the provider's token route until the operator approves, and returns the provider's token. Time is counted in the waits asked for, so a machine that slept through the code still gets one poll that says it expired. */
+const awaitToken = async (deps, provider, config, device, masker) => {
+    let { intervalMs } = device;
+    const form = [['client_id', config.clientId], ['device_code', device.deviceCode], ['grant_type', DEVICE_GRANT]];
+    if (config.clientSecret !== undefined)
+        form.push(['client_secret', config.clientSecret]);
+    for (let waited = 0; waited < device.expiresMs; waited += intervalMs) {
+        await deps.sleep(intervalMs);
+        const { body } = await askProvider(deps, provider.tokenUrl, form, masker);
+        if (!isObject(body))
+            throw new CliError('The provider answered a sign-in poll with no body.', ExitCode.UNEXPECTED, LOGIN);
+        const accessToken = textIn(body, 'access_token');
+        if (accessToken !== undefined)
+            return accessToken;
+        const error = textIn(body, 'error') ?? 'no_token';
+        if (error === 'slow_down')
+            intervalMs += SLOW_DOWN_MS;
+        else if (error === 'expired_token')
+            break;
+        else if (error !== 'authorization_pending') {
+            const title = `The provider refused the sign-in: ${error}.`;
+            throw new CliError(title, ExitCode.AUTH, LOGIN, { code: 'login_refused', title });
+        }
+    }
+    const title = 'The sign-in code expired. Run oars pool login again.';
+    throw new CliError(title, ExitCode.AUTH, LOGIN, { code: 'EXPIRED_TOKEN', title });
+};
+/**
+ * `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 const poolLogin = async (deps, options) => {
+    const { storeDir } = runtimeOf(deps);
+    const server = poolServer(deps.env, LOGIN, options.server);
+    const { provider } = options;
+    const flow = PROVIDER_FLOWS.get(provider ?? '');
+    if (provider === undefined || flow === undefined)
+        throw usage(`The provider is one of ${POOL_PROVIDERS.join(', ')}.`, LOGIN);
+    const config = configOf(deps.env, flow);
+    const saved = await loadSignIns(storeDir, LOGIN);
+    const masker = new Masker();
+    const device = deviceOf(await askProvider(deps, flow.deviceUrl, [['client_id', config.clientId], ['scope', flow.scope]], masker));
+    masker.add(device.deviceCode);
+    deps.io.stderr(`To sign in, open ${device.verificationUri}\nand confirm the code ${device.userCode}\n`);
+    await deps.openBrowser(device.verificationUri).catch(() => {
+        deps.io.stderr('Could not open a browser; open the link above yourself.\n');
+    });
+    const accessToken = await awaitToken(deps, flow, config, device, masker);
+    masker.add(accessToken);
+    const reply = await ask(deps, LOGIN, server, '/v1/login', { body: { provider, token: accessToken }, show: masker });
+    if (reply.status !== 200)
+        throw refusal(LOGIN, reply);
+    const signIn = signInOf(isObject(reply.body) ? { ...reply.body, server } : undefined);
+    if (signIn === undefined)
+        throw new CliError('The pool answered a sign-in with no account, token, or signing key.', ExitCode.UNEXPECTED, LOGIN);
+    const known = saved.find((entry) => entry.server === server);
+    // The key is trusted once, here, and never replaced by a later login: a server that swaps it could otherwise sign anything it likes.
+    if (known !== undefined && known.signingKey.x !== signIn.signingKey.x)
+        throw new CliError(`${server} now signs with a different key than the one pinned at your first login. Nothing was saved. If the pool really did change its key, remove ${server} from ${signInsFile(storeDir)} and sign in again.`, ExitCode.AUTH, LOGIN, { code: 'signing_key_changed', title: 'The pool signing key changed.' });
+    await mkdir(storeDir, { recursive: true });
+    await writeFile(signInsFile(storeDir), `${JSON.stringify([...saved.filter((entry) => entry !== known), signIn])}\n`, { mode: 0o600 });
+    return { document: { ok: true, server, account: signIn.account, expiresAt: signIn.expiresAt }, text: `Signed in to ${server} as ${signIn.account}.` };
+};
+/** A send stops here when the server is closed or wants a covenant accepted, before the batch is read for the last time. */
+const openCovenant = async (deps, server, token, accept, via) => {
+    const reply = await ask(deps, DEPOSIT, server, '/v1/covenant', { token }, via);
+    if (reply.status !== 200 || !isObject(reply.body))
+        throw refusal(DEPOSIT, reply);
+    const version = textIn(reply.body, 'version');
+    if (version === undefined) {
+        const title = 'This pool is not taking deposits: its covenant is not published.';
+        throw new CliError(title, ExitCode.AUTH, DEPOSIT, { code: 'deposits_closed', title, status: 403 });
+    }
+    if (accept !== undefined) {
+        const accepted = await ask(deps, DEPOSIT, server, '/v1/covenant/accept', { token, body: { version: accept } }, via);
+        if (accepted.status !== 200)
+            throw refusal(DEPOSIT, accepted);
+        return;
+    }
+    if (Reflect.get(reply.body, 'accepted') !== true) {
+        const title = `Read covenant ${version} of this pool, then rerun with --accept-covenant ${version}.`;
+        throw new CliError(title, ExitCode.AUTH, DEPOSIT, { code: 'covenant_not_accepted', title, status: 403 });
+    }
+};
+const excludedKey = (reason) => (reason === 'no-raw' ? 'noRaw' : reason === 'no-terms' ? 'noTerms' : reason);
+/** A deposit answered with this code is sent again: another deposit of the same session landed between the pool's read and its write, and the next one nets against the winner. */
+const DEPOSIT_CONFLICT = 'deposit_conflict';
+const SEND_ATTEMPTS = 3;
+const vocabularyExpired = (deps) => {
+    if (!isVocabularyExpired(new Date(deps.now())))
+        return undefined;
+    const title = `This oars is out of date: its vocabulary ${VOCAB_VERSION} was taken on ${VOCAB_SNAPSHOT_DATE}, over ${String(REGISTRY_MAX_AGE_DAYS)} days ago. Upgrade with npm install -g @manyoars/oars, then run oars pool deposit again. Your sessions stay on this machine.`;
+    return new CliError(title, ExitCode.CONFLICT, DEPOSIT, { code: 'vocabulary_expired', title, status: 409 });
+};
+const lockMessages = {
+    batch_unknown: 'No batch with that hash is in the outbox. Run oars pool outbox to list them.',
+    batch_not_shown: 'That batch was never printed. Run oars pool outbox, read it, then send it.',
+    batch_changed: 'That batch changed on disk after it was printed, or since it was written, so it was not sent. Run oars pool deposit to build it again, then oars pool outbox to print it.',
+};
+/** `deposit --send <hash>`: the lock, then (only when a sender is given) the covenant and the request. The body is read and hashed again just before the request. */
+const sendBatch = async (deps, options) => {
+    const { outbox, server, token, hash, via } = options;
+    if (!/^[0-9a-f]{64}$/.test(hash))
+        throw usage('--send takes the SHA-256 that oars pool outbox printed: 64 hexadecimal characters.', DEPOSIT);
+    const locked = await lockedBatch(outbox, hash);
+    if (!locked.ok) {
+        const title = lockMessages[locked.code];
+        throw new CliError(title, ExitCode.CONFLICT, DEPOSIT, { code: locked.code, title, status: 409 });
+    }
+    if (via === undefined) {
+        const title = 'Sending a batch waits on the pool covenant: this oars does not send one yet. Nothing was sent.';
+        throw new CliError(title, ExitCode.CONFLICT, DEPOSIT, { code: 'sending_disabled', title, status: 409 });
+    }
+    await openCovenant(deps, server, token, options.acceptCovenant, via);
+    const bytes = await unchangedBytes(locked.file, hash);
+    if (bytes === undefined) {
+        const title = lockMessages.batch_changed;
+        throw new CliError(title, ExitCode.CONFLICT, DEPOSIT, { code: 'batch_changed', title, status: 409 });
+    }
+    let reply = await ask(deps, DEPOSIT, server, POOL_DEPOSITS, { token, bytes }, via);
+    for (let attempt = 1; attempt < SEND_ATTEMPTS && reply.status === 409 && isObject(reply.body) && textIn(reply.body, 'error') === DEPOSIT_CONFLICT; attempt += 1) {
+        reply = await ask(deps, DEPOSIT, server, POOL_DEPOSITS, { token, bytes }, via);
+    }
+    if (reply.status !== 201)
+        throw refusal(DEPOSIT, reply);
+    return { document: { ok: true, server, hash, sent: true }, text: `Sent batch ${hash} to ${server}.` };
+};
+/**
+ * `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 const poolDeposit = async (deps, options) => {
+    const runtime = runtimeOf(deps);
+    const server = poolServer(deps.env, DEPOSIT, options.server);
+    const { account, token } = await signedIn(deps, runtime.storeDir, server, DEPOSIT);
+    // A client past `registry_max_age` builds no batch (spec Section 1.3): its sessions wait in `A` and nothing is lost. This comes before anything is written or sent.
+    const expired = vocabularyExpired(deps);
+    if (expired !== undefined)
+        throw expired;
+    // Accepting the covenant is a step of sending, which is disabled in this release: say so rather than exit 0 as though it was accepted.
+    if (options.send === undefined && options.acceptCovenant !== undefined)
+        throw usage('--accept-covenant belongs to --send, and sending is disabled in this release. Nothing was accepted.', DEPOSIT);
+    const outbox = outboxFolder(runtime.storeDir, server);
+    if (options.send !== undefined)
+        return sendBatch(deps, { outbox, server, token, hash: options.send, acceptCovenant: options.acceptCovenant, via: options.via });
+    const { terms } = exclusionPaths(runtime.projectsRoot, deps.env);
+    const allow = compileAllow((await readSaved(runtime.storeDir)).allow);
+    const discarded = await discardStale(outbox);
+    const counts = { sessions: 0, batched: 0, excluded: { folder: 0, term: 0, noRaw: 0, noTerms: 0, unreadable: 0 }, uncaptured: 0, notEnded: 0, refused: 0, refusedFields: [], discarded, withdrawn: 0 };
+    const built = new Set();
+    const refusedFields = new Set();
+    const roots = new Map((await readSkeletons(runtime.storeDir, undefined, true)).skeletons.map(({ session, merkleRoot, leaves }) => [session, { merkleRoot, leaves }]));
+    // The sessions that pass both gates and have ended, in the order the store holds them: the windows of a delta are counted over these alone, and the batch of each is built after, once its deltas are known.
+    const ready = [];
+    // A session that fails a gate loses its earlier batch at once, so a later throw in this pass cannot leave one in the outbox.
+    const withdraw = async (key) => {
+        counts.withdrawn += await removeBatchOf(outbox, key);
+    };
+    for (const records of sessionsOf(await loadStore(runtime.storeDir), roots)) {
+        counts.sessions += 1;
+        // Hashed with the account, so a redeposit replaces its own batch and two accounts' copies of one session cannot be joined.
+        const key = contentHash([account, records.main.session]);
+        if (!allow.allows(records.main.project)) {
+            counts.excluded.folder += 1;
+            await withdraw(key);
+            continue;
+        }
+        const verdict = await checkSession(runtime, terms, records.main.project, records.main.session);
+        if (verdict.reason !== 'clean') {
+            counts.excluded[excludedKey(verdict.reason)] += 1;
+            await withdraw(key);
+            continue;
+        }
+        // The batch of a session is built once the session and its subagents have ended; a session still in progress waits, and an earlier batch of it is withdrawn.
+        if (!hasEnded(records, deps.now(), await lastWritten(runtime, records.main.project, records.main.session))) {
+            counts.notEnded += 1;
+            await withdraw(key);
+            continue;
+        }
+        ready.push({ records, key });
+    }
+    // A delta is built from the sessions that passed, carried by the batch of the session that filled its after window, and marked sent only once that batch is written: a deposit that stops first builds it again.
+    const placed = ready.flatMap(({ records }) => placedOf(records) ?? []);
+    const carried = carriedDeltas(account, placed, await sentDeltas(outbox));
+    for (const { records, key } of ready) {
+        const delta = carried.get(records.main.session);
+        const skeleton = skeletonOf(records, key, shellReader(vocabulary()), contentHash, delta?.entries);
+        if (skeleton === null) {
+            counts.uncaptured += 1;
+            await withdraw(key);
+            continue;
+        }
+        const parsed = parseSkeleton(skeleton);
+        if (!parsed.ok) {
+            counts.refused += 1;
+            refusedFields.add(parsed.field);
+            await withdraw(key);
+            continue;
+        }
+        await writeBatch(outbox, key, parsed.skeleton);
+        await markDeltasSent(outbox, delta?.marks ?? []);
+        built.add(key);
+        counts.batched += 1;
+    }
+    // The batch of a session or account this store no longer holds goes too.
+    counts.withdrawn += await removeBatchesExcept(outbox, built);
+    counts.refusedFields = [...refusedFields].sort();
+    const { folder, term, noRaw, noTerms, unreadable } = counts.excluded;
+    const lines = [
+        `Wrote ${String(counts.batched)} of ${String(counts.sessions)} sessions to the outbox for ${server}. Nothing was sent.`,
+        `Kept out by the session gates, never built: ${String(folder)} in a folder not on the allowlist, ${String(term)} for a term, ${String(noRaw)} with no raw to scan, ${String(noTerms)} with no term file, ${String(unreadable)} unreadable.`,
+        `Not built: ${String(counts.uncaptured)} captured before steps and frames or with no root, ${String(counts.notEnded)} not ended (a transcript gained a line within ${String(SESSION_IDLE_HOURS)} hours), ${String(counts.refused)} refused by the vocabulary${counts.refusedFields.length === 0 ? '' : ` (${counts.refusedFields.join(', ')})`}.`,
+        ...(counts.withdrawn === 0 ? [] : [`Removed ${String(counts.withdrawn)} ${counts.withdrawn === 1 ? 'batch' : 'batches'} of sessions that no longer pass the gates, have not ended, or are no longer in the store.`]),
+        ...(discarded === 0 ? [] : [`Discarded ${String(discarded)} ${discarded === 1 ? 'batch' : 'batches'} built under an older vocabulary, field list, or skeleton format.`]),
+        'Run oars pool outbox to print exactly what would be sent.',
+    ];
+    return { document: { ok: true, server, ...counts }, text: lines.join('\n') };
+};
+/** Each field of a batch, at any depth, with its row. A field with no row fails the command rather than printing blank. */
+const explained = (bytes) => {
+    const rows = {};
+    for (const field of fieldsOf(bytes)) {
+        const row = Object.hasOwn(FIELD_ROWS, field) ? FIELD_ROWS[field] : undefined;
+        if (row === undefined) {
+            const title = `The batch holds a field, ${field}, with no row to explain it. Nothing was printed for it.`;
+            throw new CliError(title, ExitCode.INVALID, OUTBOX, { code: 'field_without_row', title });
+        }
+        rows[field] = row;
+    }
+    return rows;
+};
+/** `oars pool outbox`: prints each batch as it would be sent, 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 const poolOutbox = async (deps, options) => {
+    const runtime = runtimeOf(deps);
+    const server = poolServer(deps.env, OUTBOX, options.server);
+    const { token } = await signedIn(deps, runtime.storeDir, server, OUTBOX);
+    const outbox = outboxFolder(runtime.storeDir, server);
+    const { batches, edited } = await heldBatches(outbox);
+    const masker = new Masker();
+    masker.add(token);
+    const shown = [];
+    for (const batch of batches) {
+        const fields = options.explain === true ? explained(batch.bytes) : undefined;
+        shown.push({ hash: batch.hash, request: printed(outgoing(deps, server, POOL_DEPOSITS, { token, bytes: batch.bytes }), masker), ...(fields === undefined ? {} : { fields }) });
+    }
+    for (const { hash } of shown)
+        await markShown(outbox, hash, deps.now());
+    const stale = await staleBatches(outbox);
+    const blocks = shown.map(({ hash, request, fields }) => [request, `sha256: ${hash}`, ...Object.entries(fields ?? {}).map(([field, row]) => `  ${field}: ${row}`)].join('\n'));
+    const notes = [
+        ...(edited === 0 ? [] : [`${String(edited)} ${edited === 1 ? 'batch was' : 'batches were'} edited on disk since ${edited === 1 ? 'it was' : 'they were'} written and ${edited === 1 ? 'is' : 'are'} not printed or sent. Run oars pool deposit to build ${edited === 1 ? 'it' : 'them'} again.`]),
+        ...(stale === 0 ? [] : [`${String(stale)} ${stale === 1 ? 'batch was' : 'batches were'} built under an older vocabulary, field list, or skeleton format and will never be sent.`]),
+    ];
+    const text = shown.length === 0 ? ['The outbox is empty. Run oars pool deposit first.', ...notes].join('\n') : [...blocks, ...notes].join('\n\n');
+    return { document: { ok: true, server, batches: shown, edited, stale }, text };
+};
+/** One folder per harness under the server's, so a fetch for one harness never overwrites another's bundle of the same version. */
+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. */
+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 weekly cap, as a failure of its own code: the bundle on disk is untouched, and the words say when the pool will answer again. */
+const cappedError = (deps, reply, kept) => {
+    const retryAfter = reply.headers.get('retry-after');
+    const wait = retryAfter === null ? undefined : waitWords(retryAfter, deps.now());
+    const when = wait === undefined ? 'The pool did not say when; it counts fetches per ISO week, so try again next week.' : `Try again ${wait}.`;
+    const title = `The pool's weekly fetch cap is used up. ${when} ${kept ? 'The bundle already on disk is untouched.' : 'No verified bundle is kept.'}`;
+    return new CliError(title, ExitCode.CAPPED, FETCH, { code: 'fetch_cap', title, status: 429 }, { retryAfter });
+};
+/** What a fetch asks for when no `--harness` is given, and what it falls back to when no one harness leads the local store. */
+const DEFAULT_HARNESS = 'claude-code';
+/**
+ * The harness a fetch asks for. `--harness` names it, and nothing is printed. Without the flag it is the harness the local store holds the most sessions of, and the choice and the way to
+ * change it go to stderr before the request: a fetch never picks silently. An empty store or a tie asks for Claude Code's and says so. It reads counts only, and none of them leaves the machine.
+ */
+const fetchHarness = async (deps, storeDir, named) => {
+    if (named !== undefined) {
+        if (!isHarness(named))
+            throw usage(`${named} is not a harness the pool serves. Choose one of ${HARNESSES.join(', ')}.`, FETCH);
+        return named;
+    }
+    const counts = new Map();
+    for (const session of (await loadStore(storeDir)).sessions)
+        counts.set(sessionHarness(session), (counts.get(sessionHarness(session)) ?? 0) + 1);
+    const [top, runnerUp] = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+    const lead = top !== undefined && (runnerUp === undefined || top[1] > runnerUp[1]) ? top : undefined;
+    const harness = lead === undefined ? DEFAULT_HARNESS : lead[0];
+    const total = [...counts.values()].reduce((sum, count) => sum + count, 0);
+    const why = lead === undefined ? `${total === 0 ? 'your local store is empty' : 'no one harness leads your local store'}, so Claude Code is the default` : `the harness your local store holds the most sessions of (${String(lead[1])} of ${String(total)})`;
+    deps.io.stderr(`No --harness given: fetching ${harness}, ${why}. Pass --harness <name> to fetch another (${HARNESSES.join(', ')}).
+`);
+    return harness;
+};
+/** `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 const poolFetch = async (deps, options) => {
+    const { storeDir } = runtimeOf(deps);
+    const server = poolServer(deps.env, FETCH, options.server);
+    const { harnessVersion } = options;
+    if (!isBundleVersion(harnessVersion))
+        throw usage(`${harnessVersion} is not a public harness version.`, FETCH);
+    const { token, signingKey } = await signedIn(deps, storeDir, server, FETCH);
+    const harness = await fetchHarness(deps, storeDir, options.harness);
+    const file = replicaFile(storeDir, server, harness, harnessVersion);
+    const kept = await keptReplica(file, signingKey, harness, harnessVersion);
+    const credential = new Masker();
+    credential.add(token);
+    const reply = await ask(deps, FETCH, server, `/bundle/${harness}/${encodeURIComponent(harnessVersion)}/${encodeURIComponent(VOCAB_VERSION)}`, { token, show: credential, ...(kept?.etag === undefined ? {} : { ifNoneMatch: kept.etag }) });
+    if (reply.status === 429)
+        throw cappedError(deps, reply, kept !== undefined);
+    if (reply.status === 304) {
+        // A 304 answers an If-None-Match, so one to a fetch that sent none is a pool that has lost track of what it was asked.
+        if (kept?.etag === undefined)
+            throw new CliError('The pool answered 304 to a fetch that named no kept bundle.', ExitCode.UNEXPECTED, FETCH);
+        const { cells, motifs, reads, asOf } = kept.bundle;
+        return {
+            document: { ok: true, server, harness, harnessVersion, file, unchanged: true, cells: cells.length, motifs: motifs.length, reads: reads.length, asOf },
+            text: `${harness} ${harnessVersion} is unchanged: the bundle at ${file} is still current (${String(reads.length)} reads, ${String(cells.length)} cells, and ${String(motifs.length)} motifs).`,
+        };
+    }
+    if (reply.status !== 200)
+        throw refusal(FETCH, reply);
+    const verified = await verifyBundle(reply.body, signingKey, harness, harnessVersion);
+    if (!verified.ok) {
+        const title = `Refused the bundle: ${verified.reason}.`;
+        throw new CliError(title, ExitCode.INVALID, FETCH, { code: 'bundle_unverified', title });
+    }
+    const etag = reply.headers.get('etag');
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify({ ...(isObject(reply.body) ? reply.body : {}), ...(etag === null ? {} : { etag }) })}
+`);
+    const { cells, motifs, reads, asOf } = verified.bundle;
+    return {
+        document: { ok: true, server, harness, harnessVersion, file, unchanged: false, cells: cells.length, motifs: motifs.length, reads: reads.length, asOf },
+        text: `Fetched ${harness} ${harnessVersion}: ${String(reads.length)} reads, ${String(cells.length)} cells, and ${String(motifs.length)} motifs, verified against the pinned key and kept at ${file}.`,
+    };
+};

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

@@ -0,0 +1,54 @@
+import { type DeltaEntry, type SessionRecords } from './pool-wire.js';
+/** `delta_days` and `delta_min_sessions` (spec Section 7): a week on each side spans a work cycle, and five sessions keep one session from being the delta. */
+export declare const DELTA_DAYS = 7;
+export declare const DELTA_MIN_SESSIONS = 5;
+/** A session as a window sees it: when it began (epoch milliseconds) and an id that orders two sessions of one instant. */
+export interface Placed {
+    id: string;
+    at: number;
+}
+/** A before and an after window, each of `DELTA_DAYS`, the after window's place on the grid (its index), and the session that brought the after window to its minimum. */
+export interface Windows<T> {
+    index: number;
+    before: T[];
+    after: T[];
+    filler: T;
+}
+/**
+ * The pairs of windows a set of sessions holds. Windows are consecutive spans of `days` on a grid counted from the epoch, not from any session, so a session belongs to exactly one window and the grid does
+ * not move when a session is added, lost to a gate, or not yet ended: the `index` of a window is the same whenever the deposit runs. A pair is two windows next to each other that each hold at least
+ * `min` sessions; a gap of an empty window, or of one with too few, compares nothing across it. The `filler` is the `min`th session of the after window in time order. It chooses which batch carries
+ * the delta and can change from one deposit to the next, so nothing that must hold still is keyed on it.
+ */
+export declare const windowsOf: <T extends Placed>(sessions: readonly T[], days?: number, min?: number) => Windows<T>[];
+/**
+ * The entries a pair of windows holds, each window in time order (the caller sorts). A plugin is added or removed, a `permissionMode` or `effort` changed by name alone (the most common value of each
+ * window differs, a value outside its list read as one word), and a `package` removed. Each entry carries the move of one metric in its field's own buckets: calls per session for a plugin, a permission
+ * mode, and a package, thinking per prompt for an effort. A name outside its list is `private`, and everything that is `private` in one field is one entry.
+ */
+export declare const deltasOf: (before: readonly SessionRecords[], after: readonly SessionRecords[]) => DeltaEntry[];
+/**
+ * The once-only mark of a delta: a hash of the account, the entry without the size of its move, and the index of its after window on the grid. The move is left out so a recount of the same windows is
+ * the same delta, and the index is in so a later pair that shows the same change is a new one. The filler is not in it: which session fills a window moves with the sessions ready, a window's index does not.
+ */
+export declare const deltaMark: (account: string, { deltaKind, field, name, registry, metric }: DeltaEntry, index: number) => string;
+/** The marks of the deltas this outbox has already carried in a written batch. A folder with no log holds none; a log that cannot be read is an error, not an empty one, so a delta is never built twice by mistake. */
+export declare const sentDeltas: (outbox: string) => Promise<Set<string>>;
+/** Marks deltas as sent, one line each. The caller writes this only after the batch that carries them is written, so a deposit that stopped before it builds them again. */
+export declare const markDeltasSent: (outbox: string, marks: readonly string[]) => Promise<void>;
+/** A session that passed the session gates, placed for the windows: its records, when it began, and its id. */
+export interface Gated extends Placed {
+    records: SessionRecords;
+}
+/** The session placed by when it began (epoch milliseconds) and its own id; none when it has no start that reads as a time, since no window can hold it. */
+export declare const placedOf: (records: SessionRecords) => Gated | undefined;
+/** What one batch carries: its delta entries and the marks to write once the batch is written. */
+export interface Carried {
+    entries: DeltaEntry[];
+    marks: string[];
+}
+/**
+ * The deltas not yet sent, by the id of the session that filled their after window: that session's batch carries them, and the mark is the window's index, so it holds whichever session fills. A delta whose mark is held is dropped, so a rebuilt session, or a batch written
+ * again under the same key, builds none it already carried. Nothing is marked here: the caller marks them once the batch is written.
+ */
+export declare const carriedDeltas: (account: string, sessions: readonly Gated[], sent: ReadonlySet<string>) => Map<string, Carried>;