@manyoars/oars 0.5.2 → 0.5.3

package/LICENSE

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

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

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

package/dist/sessions/pool-command.js

@@ -19,7 +19,7 @@ import { carriedDeltas, heldDeltas, keptDeltas, markDeltasSent, placedOf, sentDe
 import { Masker, printed, TRANSPORT_HEADERS, waitWords } from './pool-print.js';
 import { rawAllowed, rawStale, sendsOf } from './pool-choices.js';
 import { heldRaw, rawParts, removeRawExcept, writeRaw } from './pool-raw.js';
-import { SendLockBusy, withSendLock } from './pool-send-lock.js';
+import { SendInterrupted, SendLockBusy, watchInterrupt, withSendLock } from './pool-send-lock.js';
 import { markSent, retirePulled, sentLog } from './pool-sent.js';
 import { shellReader } from './projection.js';
 import { isVocabularyExpired, REGISTRY_MAX_AGE_DAYS, VOCAB_SNAPSHOT_DATE } from './public-vocabulary.js';
@@ -102,29 +102,92 @@ export const ask = (deps, step, server, path, init, via) => {
     const request = outgoing(deps, server, path, init);
     return via === undefined ? send(deps, step, request, init.show, init.binary === true) : via(request);
 };
-/** Prints the request when asked to, then sends exactly those headers and that body. */
-const send = async (deps, step, request, show, binary = false) => {
+/** The pool took the request and then said nothing for `Guard.stallMs`. */
+class PoolStalled extends Error {
+}
+/** A newcomer's words for the network failures a stalled or restarted pool produces; the raw reason follows the sentence in parentheses. */
+const PLAIN_REASONS = [
+    [/ECONNRESET|socket hang up|UND_ERR_SOCKET/, 'the connection was dropped before the pool answered'],
+    [/ECONNREFUSED/, 'nothing is listening there'],
+    [/ENOTFOUND|EAI_AGAIN/, 'that name did not resolve'],
+    [/ETIMEDOUT|UND_ERR_CONNECT_TIMEOUT/, 'the connection timed out'],
+    [/EPIPE/, 'the connection closed while the batch was going out'],
+];
+const NOT_MARKED = 'Nothing was marked sent.';
+const TRY_AGAIN = 'Run the same command to try again.';
+const RETRY = `${NOT_MARKED} ${TRY_AGAIN}`;
+/** Said after a stop or a stall once the request carrying the batch had gone out: the pool may hold it even though nothing here saw the answer. */
+const MAY_HAVE_RECEIVED = 'The pool may already have received it.';
+/** What `deposit` says after it writes the outbox: the covenant (the person's consent, docs/covenant 2.1) already lets the background sender send what is queued, with or without this command. A machine's batches are never sent by it. */
+const SENT_LATER = 'Nothing was sent yet. Once the covenant is accepted, oars sends what is queued automatically, in the background.';
+/**
+ * What a person reads after a send they stopped (Ctrl-C, a closed terminal, a launcher that died): the batch stays queued, and the background sender (hook-bin.js nightly, started by a later oars command
+ * or the end of a session, about once an hour at most, not on a timer) sends it once the covenant is accepted, whether or not this command ever finishes. The second line is added only when a request carrying the batch had gone out.
+ * The folder switch and the sign-out are the two real ways to stop that: the sender builds the outbox again first, which withdraws a folder that is off, and it sends nothing without a sign-in.
+ */
+export const stoppedText = (received) => [
+    'Stopped. This batch stays queued, and once the covenant is accepted oars sends it automatically in the background.',
+    ...(received ? [MAY_HAVE_RECEIVED] : []),
+    'To keep a folder out, run oars pool raw --folder <folder> --mode off.',
+    'To stop this machine sending, run oars pool logout.',
+].join('\n');
+/** Why a guarded request ended without an answer, in plain words: a stall, an interrupt, or a network failure whose raw reason is kept after the sentence. The exit code is the unreachable one, as before. */
+const guardedFailure = (step, cause, origin, guard, received) => {
+    if (cause instanceof PoolStalled)
+        return new CliError(`The pool at ${origin} did not answer within ${String(guard.stallMs / 1000)} seconds. ${received ? `${NOT_MARKED} ${MAY_HAVE_RECEIVED} ${TRY_AGAIN}` : RETRY}`, ExitCode.UNREACHABLE, step);
+    if (cause instanceof SendInterrupted)
+        return new CliError(stoppedText(received), ExitCode.UNEXPECTED, step);
+    const unreachable = unreachableError(step, cause, origin);
+    const raw = unreachable.message.slice(`Cannot reach the server at ${origin}: `.length);
+    const plain = PLAIN_REASONS.find(([pattern]) => pattern.test(raw));
+    return plain === undefined ? unreachable : new CliError(`Cannot reach the pool at ${origin}: ${plain[1]} (${raw}). ${RETRY}`, ExitCode.UNREACHABLE, step);
+};
+/** Prints the request when asked to, then sends exactly those headers and that body. A guarded request also ends when its stall time passes or its signal aborts, and fails in plain words. */
+const send = async (deps, step, request, show, binary = false, guard) => {
     if (show !== undefined)
         deps.io.stderr(`${printed(request, show)}
 `);
-    let response;
-    try {
-        response = await fetch(request.url, { method: request.method, headers: request.headers, redirect: 'error', ...(request.body === undefined ? {} : { body: request.body }) });
-    }
-    catch (error) {
-        throw unreachableError(step, error, request.url.origin);
-    }
-    let body;
+    const stop = new AbortController();
+    const relay = () => {
+        stop.abort(guard?.signal?.reason);
+    };
+    guard?.signal?.addEventListener('abort', relay, { once: true });
+    if (guard?.signal?.aborted === true)
+        relay();
+    const timer = guard === undefined ? undefined : setTimeout(() => {
+        stop.abort(new PoolStalled());
+    }, guard.stallMs);
+    // Whether the batch itself had gone out when the run ended: only the deposit request carries it, and only when it went out before the run was stopped.
+    let started = false;
+    const failure = (error) => (guard === undefined ? unreachableError(step, error, request.url.origin) : guardedFailure(step, stop.signal.aborted ? stop.signal.reason : error, request.url.origin, guard, started && request.url.pathname === POOL_DEPOSITS));
     try {
-        body = binary && response.status === 200 ? new Uint8Array(await response.arrayBuffer()) : await response.json();
+        let response;
+        try {
+            started = !stop.signal.aborted;
+            response = await fetch(request.url, { method: request.method, headers: request.headers, redirect: 'error', ...(guard === undefined ? {} : { signal: stop.signal }), ...(request.body === undefined ? {} : { body: request.body }) });
+        }
+        catch (error) {
+            throw failure(error);
+        }
+        let body;
+        try {
+            body = binary && response.status === 200 ? new Uint8Array(await response.arrayBuffer()) : await response.json();
+        }
+        catch (error) {
+            // An answer that began and then stalled is no answer; one that ended badly is read as no body, as before.
+            if (stop.signal.aborted)
+                throw failure(error);
+            body = undefined;
+        }
+        return { status: response.status, body, headers: response.headers };
     }
-    catch {
-        body = undefined;
+    finally {
+        clearTimeout(timer);
+        guard?.signal?.removeEventListener('abort', relay);
     }
-    return { status: response.status, body, headers: response.headers };
 };
-/** The sender `deposit --send` uses when none is given: the request goes out over the network as built. The loopback test passes it to read what reaches the socket. */
-export const networkSender = (deps, step) => (request) => send(deps, step, request, undefined);
+/** The sender `deposit --send` uses when none is given: the request goes out over the network as built. The loopback test passes it to read what reaches the socket. An interactive send passes a `Guard`. */
+export const networkSender = (deps, step, guard) => (request) => send(deps, step, request, undefined, false, guard);
 /** The server's named refusal, as a failure: its `error` is the problem's code in `--json`. */
 export const refusal = (step, { status, body }) => {
     const code = isObject(body) ? textIn(body, 'error') : undefined;
@@ -296,8 +359,18 @@ const regionOf = (text) => {
     const answer = text?.trim().toLowerCase();
     return answer === 'yes' || answer === 'no' ? answer : undefined;
 };
+/**
+ * The CLI's own words around the covenant screen, never inside it: the screen text and the hash of it that the pool records stay exactly what the pool served. They say what a deposit gives and what to run next, and
+ * they promise only access, as covenant 2.1 does ("What you get" and Section 4.3). The third line points at the full text because Part A is a summary and Section 16.2 makes the full covenant the whole agreement.
+ */
+export const OFFER_BEFORE = [
+    'Depositing gives your account access to the pool.',
+    'A counting deposit lifts the weekly limit on pool fetches for 90 days.',
+    'The covenant is the whole deal. Its full text is linked below. Read it before you type.',
+];
+export const OFFER_AFTER = ['Accepted. Sending your batch now.', 'Run oars pool fetch --help for your first pool download.'];
 /** A send stops here when the server is closed or wants a covenant accepted, before the batch is read for the last time. */
-const openCovenant = async (deps, server, token, accept, region, via) => {
+const openCovenant = async (deps, server, token, accept, region, via, signal) => {
     const reply = await ask(deps, DEPOSIT, server, '/v1/covenant', { token }, via);
     if (reply.status !== 200 || !isObject(reply.body))
         throw refusal(DEPOSIT, reply);
@@ -321,13 +394,17 @@ const openCovenant = async (deps, server, token, accept, region, via) => {
     if (!isTerminal(deps)) {
         throw notAccepted(`Covenant ${version} is not accepted for this account. Accepting it takes a person at a terminal who reads it and types its phrase: run this command from one. Nothing was accepted.`);
     }
+    deps.io.stderr(`${OFFER_BEFORE.join('\n')}\n`);
     deps.io.stderr(`\n${screen.text}\n\n> `);
     emitOf(deps)('covenant-shown', { version });
     // One reader for both lines: a second one opened after the first closed would lose a line the first had already taken from a pipe.
-    const lines = createInterface({ input: runtimeOf(deps).stdin, terminal: false });
+    // A stop signal (Ctrl-C, a closed terminal) closes the reader, so a read that is waiting for the person ends with the signal's reason instead of holding the process open.
+    const lines = createInterface({ input: runtimeOf(deps).stdin, terminal: false, ...(signal === undefined ? {} : { signal }) });
     const iterator = lines[Symbol.asyncIterator]();
     const nextLine = async () => {
         const next = await iterator.next();
+        if (signal?.aborted === true)
+            throw signal.reason;
         return next.done === true ? undefined : next.value;
     };
     let answered = region;
@@ -349,6 +426,7 @@ const openCovenant = async (deps, server, token, accept, region, via) => {
     const accepted = await ask(deps, DEPOSIT, server, '/v1/covenant/accept', { token, body }, via);
     if (accepted.status !== 200)
         throw refusal(DEPOSIT, accepted);
+    deps.io.stderr(`${OFFER_AFTER.join('\n')}\n`);
     // A yes to the raw prompt belongs to the covenant it was given under, and a covenant can change what that prompt covers: accepting another version asks the raw question again.
     const reset = { done: false };
     await updatePoolChoices(runtimeOf(deps).storeDir, (choices) => {
@@ -449,10 +527,12 @@ const termsHint = (file) => `No exclusion terms file at ${file}: until it holds
 /** `deposit --send <hash>`: the send lock the detached sender (hook-bin.js nightly) takes too, then a skip for a hash already in `sent.log`, then the batch lock, then the covenant (accepted here or before, or nothing is sent), then the request. The body is read and hashed again just before the request. */
 const sendBatch = async (deps, options) => {
     const { outbox, server, token, hash } = options;
-    const via = options.via ?? networkSender(deps, DEPOSIT);
     if (!/^[0-9a-f]{64}$/.test(hash))
         throw usage('--send takes the SHA-256 that oars pool outbox printed: 64 hexadecimal characters.', DEPOSIT);
     const refuse = (code, title) => new CliError(title, ExitCode.CONFLICT, DEPOSIT, { code, title, status: 409 });
+    // Ctrl-C, a kill, a closed terminal, or a launcher that died ends the wait for the lock and the request in flight, so a send the person gave up on cannot finish later.
+    const interrupt = watchInterrupt();
+    const via = options.via ?? networkSender(deps, DEPOSIT, { stallMs: SEND_STALL_MS, signal: interrupt.signal });
     try {
         return await withSendLock(outbox, async () => {
             // The rule the nightly follows: a hash `sent.log` holds is not posted again. Read under the lock, so two runs cannot both see it unsent.
@@ -470,21 +550,59 @@ const sendBatch = async (deps, options) => {
                 throw refuse(locked.code, lockMessages[locked.code]);
             if (!scan.open && (await heldAcross(outbox)).batches.some((batch) => batch.hash === hash && batch.pulled))
                 throw refuse('terms_missing', 'This batch was held by a cloud session, and your exclusion term file is missing or empty, so it cannot be checked and was not sent.');
-            await openCovenant(deps, server, token, options.acceptCovenant, options.region, via);
+            await openCovenant(deps, server, token, options.acceptCovenant, options.region, via, interrupt.signal);
             const bytes = await unchangedBytes(locked.file, hash);
             if (bytes === undefined)
                 throw refuse('batch_changed', lockMessages.batch_changed);
+            deps.io.stderr(`Sending batch ${hash.slice(0, 12)} to ${server}...\n`);
             await postBatch(deps, { server, token, bytes, hash, via });
             await markSent(outbox, hash, deps.now());
             await retirePulled(outbox, DEPOSIT);
             return { document: { ok: true, server, hash, sent: true }, text: `Sent batch ${hash} to ${server}.` };
+        }, options.lock?.times, options.lock?.fs, {
+            onWait: (waiting) => {
+                deps.io.stderr(`${waitingLine(waiting)}\n`);
+            },
+            signal: interrupt.signal,
         });
     }
     catch (error) {
         if (error instanceof SendLockBusy)
-            throw refuse('send_locked', 'Another oars run is sending from this outbox. Try again in a minute.');
+            throw refuse('send_locked', busyLine(error.detail));
+        if (error instanceof SendInterrupted)
+            throw new CliError(stoppedText(false), ExitCode.UNEXPECTED, DEPOSIT);
         throw error;
     }
+    finally {
+        interrupt.stop();
+    }
+};
+/**
+ * How long the pool gets to answer one request of a send (an interactive `--send` and the background sender) before the send ends. It is a deadline for the whole request, the upload and the answer together,
+ * not an idle timeout: a batch is one session's skeleton, whose largest fixture is 887 KB (docs/pool.md), which a link of 240 kbit/s or better uploads inside 30 seconds. A slower link fails each try with the stall
+ * sentence; resetting the timer once headers arrive would not help it, because the upload is what is slow.
+ */
+export const SEND_STALL_MS = 30_000;
+/** A span in words a person can plan around: seconds under two minutes, else whole minutes. */
+const span = (ms) => {
+    const seconds = Math.max(1, Math.round(ms / 1000));
+    return seconds < 120 ? `${String(seconds)} second${seconds === 1 ? '' : 's'}` : `${String(Math.round(seconds / 60))} minutes`;
+};
+/** What the person reads within a second of a send that has to wait: whose lock it is, how old it is, and how long this run waits. */
+export const waitingLine = ({ holder, ageMs, waitMs }) => holder === undefined
+    ? `Another oars run holds this outbox's send lock (the lock does not name its process; it was last touched ${span(ageMs)} ago). Waiting up to ${span(waitMs)} for it; Ctrl-C stops this run.`
+    : `Another oars run (pid ${String(holder.pid)}) took this outbox's send lock ${span(ageMs)} ago and is still sending. Waiting up to ${span(waitMs)} for it; Ctrl-C stops this run.`;
+/**
+ * What a send that gave up says: nothing was sent, who held the lock, and when a retry can succeed. A live holder on this host touches the lock every quarter of staleMs, even while it waits on a stalled pool, so the clock
+ * never frees its lock: the true condition is its end (a dead holder is taken over at once). Only a holder the lock does not name, or one on another host, whose liveness cannot be read, is decided by the clock: a
+ * retry is certain once the lock has gone untouched for staleMs.
+ */
+export const busyLine = ({ holder, local, ageMs, untouchedMs, waitedMs, staleMs }) => {
+    const who = holder === undefined ? 'Another oars run' : `Another oars run (pid ${String(holder.pid)})`;
+    const held = `${who} has held this outbox's send lock for ${span(ageMs)} and was still sending after the ${span(waitedMs)} this run waited, so nothing was sent.`;
+    if (holder !== undefined && local)
+        return `${held} A retry succeeds as soon as pid ${String(holder.pid)} ends.`;
+    return `${held} Run the same command again once it ends. If it has hung, oars takes the lock over about ${span(Math.max(1, staleMs - untouchedMs))} from now.`;
 };
 /** The covenant version the pool names, or `undefined` when it cannot be asked or names none. The route is public, so no credential goes with it. */
 const covenantOrUndefined = async (deps, server) => {
@@ -527,7 +645,7 @@ export const poolDeposit = async (deps, options) => {
     const outbox = outboxFolder(runtime.storeDir, server);
     await mkdirOwnerOnly(outbox);
     if (options.send !== undefined)
-        return sendBatch(deps, { outbox, server, token, hash: options.send, acceptCovenant: options.acceptCovenant, region, via: options.via });
+        return sendBatch(deps, { outbox, server, token, hash: options.send, acceptCovenant: options.acceptCovenant, region, via: options.via, lock: options.lock });
     const { terms } = exclusionPaths(runtime.projectsRoot, deps.env);
     const saved = await readState(runtime.storeDir);
     // A yes to the raw prompt counts only for the covenant it was given under, so an interactive build asks the pool which is in force; the nightly already knows and passes it. A pool that cannot be asked, or names none, leaves it unknown and the build goes on as before.
@@ -668,7 +786,7 @@ export const poolDeposit = async (deps, options) => {
     // Counts only: how many sessions each gate kept out, never a folder, a term, or a name.
     emitOf(deps)('deposit', { step: 'build', sessions: counts.sessions, batched: counts.batched, bytes: builtBytes, excludedFolder: folder, excludedTerm: term, excludedNoRaw: noRaw, excludedNoTerms: noTerms, excludedUnreadable: unreadable, notEnded: counts.notEnded, uncaptured: counts.uncaptured, refused: counts.refused, withdrawn: counts.withdrawn, discarded });
     const lines = [
-        `Wrote ${String(counts.batched)} of ${String(counts.sessions)} sessions to the outbox for ${server}. Nothing was sent.`,
+        `Wrote ${String(counts.batched)} of ${String(counts.sessions)} sessions to the outbox for ${server}. ${machine === undefined ? SENT_LATER : 'Nothing was sent.'}`,
         `Kept out by the session gates, never built: ${String(folder)} in a folder not on the allowlist, ${String(term)} for a term, ${String(noRaw)} with no raw to scan, ${String(noTerms)} with no term file, ${String(unreadable)} unreadable.`,
         `Not built: ${String(counts.uncaptured)} captured before steps and frames or with no root, ${String(counts.notEnded)} not ended (a transcript gained a line within ${String(SESSION_IDLE_HOURS)} hours), ${String(counts.refused)} refused by the vocabulary${counts.refusedFields.length === 0 ? '' : ` (${counts.refusedFields.join(', ')})`}.`,
         ...(counts.withdrawn === 0 ? [] : [`Removed ${String(counts.withdrawn)} ${counts.withdrawn === 1 ? 'batch' : 'batches'} of sessions that no longer pass the gates, have not ended, or are no longer in the store.`]),

package/dist/sessions/pool-nightly.js

@@ -5,7 +5,7 @@ import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { CliError } from '../errors.js';
 import { machineOf } from './machine.js';
-import { ask, currentTerms, DEPOSIT, isObject, networkSender, poolDeposit, poolServer, postBatch, postRaw, runtimeOf, signedIn, textIn, vocabularyExpired } from './pool-command.js';
+import { ask, currentTerms, DEPOSIT, isObject, networkSender, poolDeposit, poolServer, postBatch, postRaw, runtimeOf, SEND_STALL_MS, signedIn, textIn, vocabularyExpired } from './pool-command.js';
 import { rawStale } from './pool-choices.js';
 import { heldAcross, lockedBatch, outboxFolder, rescanPulled } from './pool-outbox.js';
 import { heldRaw } from './pool-raw.js';
@@ -119,7 +119,8 @@ export const nightlyPoolSend = async (deps, via) => {
     const tally = { outcome: 'failed', batches: 0, raw: 0 };
     let result;
     try {
-        result = await night(deps, via ?? networkSender(deps, DEPOSIT), tally);
+        // A pool that goes silent ends the night after SEND_STALL_MS, so it cannot hold the send lock (and with it every `deposit --send`) for as long as the pool stalls. The next run sends what this one did not.
+        result = await night(deps, via ?? networkSender(deps, DEPOSIT, { stallMs: SEND_STALL_MS }), tally);
     }
     catch {
         result = { ...tally, outcome: 'failed' };

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

@@ -5,6 +5,8 @@ export interface LockTimes {
     /** How long a run waits for the lock before it gives up. */
     waitMs: number;
     pollMs: number;
+    /** How long a run waits behind a live holder before it tells the person it is waiting. */
+    noticeMs: 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 {
@@ -13,8 +15,76 @@ export interface LockFs {
     }>;
     open?: (path: string, flags: 'wx') => Promise<FileHandle>;
     platform?: NodeJS.Platform;
+    /** Whether a process with this id is running on this machine. A test answers for a pid it made up. */
+    running?: (pid: number) => boolean;
+    /** This run's pid and host, recorded in the lock; a test names the holder it plays. */
+    self?: {
+        pid: number;
+        host: string;
+    };
+    /** The clock and the pause between polls; a test drives both instead of sleeping. */
+    clock?: {
+        now: () => number;
+        sleep: (ms: number) => Promise<void>;
+    };
+}
+export declare const DEFAULT_TIMES: LockTimes;
+/** Who holds the lock, as the holder wrote it into the file: its run, pid, host, and when it took the lock (epoch ms). */
+export interface Holder {
+    run: string;
+    pid: number;
+    host: string;
+    since: number;
+}
+/** What a run that waits tells its caller once, when the wait has lasted `noticeMs`: the holder when the file names one (an empty or older-format file names none), how old the lock is, and how long this run will wait. */
+export interface Waiting {
+    holder: Holder | undefined;
+    ageMs: number;
+    waitMs: number;
+}
+/** What a run that gave up knows: the holder, the lock's age now, the time already waited, and the constants the takeover rules use. */
+export interface BusyDetail {
+    holder: Holder | undefined;
+    /** Time since the holder took the lock, else since the lock file was last touched. */
+    ageMs: number;
+    /** Time since the lock file was last touched: a live holder touches it every `staleMs / 4`. */
+    untouchedMs: number;
+    waitedMs: number;
+    staleMs: number;
+    /** Whether the holder is a process on this host: its heartbeat then keeps the lock fresh while it lives, so only its end (not the clock) frees the lock. */
+    local: boolean;
+}
+export interface LockWait {
+    /** Called once if the lock is still held after `noticeMs`. */
+    onWait?: (waiting: Waiting) => void;
+    /** Ends the wait: the run throws the signal's reason. An interrupted `--send` leaves nothing waiting. */
+    signal?: AbortSignal;
 }
 export declare class SendLockBusy extends Error {
-    constructor();
+    readonly detail: BusyDetail;
+    constructor(detail?: BusyDetail);
+}
+export declare const withSendLock: <T>(outbox: string, run: () => Promise<T>, times?: Partial<LockTimes>, fs?: LockFs, wait?: LockWait) => Promise<T>;
+/** Why an interactive send ended before it finished: a signal reached it, or the process that launched it is gone. */
+export declare class SendInterrupted extends Error {
+    readonly kind: 'signal' | 'launcher';
+    constructor(kind: 'signal' | 'launcher', message: string);
+}
+/** What a test replaces: the process's signal hooks, its launcher, and how that launcher's liveness is read. */
+export interface InterruptHost {
+    on: (event: NodeJS.Signals, listener: () => void) => unknown;
+    off: (event: NodeJS.Signals, listener: () => void) => unknown;
+    /** The pid of the process that started this one; checked every `checkMs`. */
+    parent: number;
+    running: (pid: number) => boolean;
+    checkMs: number;
 }
-export declare const withSendLock: <T>(outbox: string, run: () => Promise<T>, times?: Partial<LockTimes>, fs?: LockFs) => Promise<T>;
+/**
+ * The signal an interactive `oars pool deposit --send` waits and sends under. Ctrl-C, a closed terminal, and a kill all end it. A launcher that is killed without a signal reaching its child (Windows `taskkill` of the
+ * shell or the `oars.cmd` shim, a `timeout` wrapper) leaves the child running, so the launcher's pid is read every second and a run whose launcher is gone ends too. The detached nightly sender is not watched:
+ * it is meant to outlive its starter.
+ */
+export declare const watchInterrupt: (host?: InterruptHost) => {
+    signal: AbortSignal;
+    stop: () => void;
+};

package/dist/sessions/pool-send-lock.js

@@ -1,15 +1,46 @@
 // One sender at a time per outbox: the detached sender (hook-bin.js nightly) and `deposit --send` both take this lock, so a batch is never posted twice by two runs that overlap. The lock is a file created
-// with `wx` beside `sent.log`, so it holds across processes as well as inside one. A run that finds it held waits; a lock older than `staleMs` belongs to a run that died, and is taken over by one waiter only, under a guard file. The holder touches the file while it runs, so a long send (a first night of raw parts) is never mistaken for a dead run, and it removes the file only if the file still names its own run.
+// with `wx` beside `sent.log`, so it holds across processes as well as inside one. A run that finds it held waits; a holder on this host whose pid is not running is taken over at once, and a lock untouched for `staleMs` belongs to a run that died (the rule for a holder whose liveness cannot be read: an empty or older-format file, another host's pid). Either takeover is by one waiter only, under a guard file. The holder touches the file while it runs, so a long send (a first night of raw parts) is never mistaken for a dead run, and it removes the file only if the file still names its own run.
 import { randomUUID } from 'node:crypto';
 import { mkdir, open, readFile, rm, stat, utimes } from 'node:fs/promises';
+import { hostname } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
-const DEFAULT_TIMES = { staleMs: 10 * 60 * 1000, waitMs: 2 * 60 * 1000, pollMs: 50 };
+export const DEFAULT_TIMES = { staleMs: 10 * 60 * 1000, waitMs: 2 * 60 * 1000, pollMs: 50, noticeMs: 500 };
 export class SendLockBusy extends Error {
-    constructor() {
+    detail;
+    constructor(detail = { holder: undefined, ageMs: 0, untouchedMs: 0, waitedMs: 0, staleMs: DEFAULT_TIMES.staleMs, local: false }) {
         super('Another oars run is sending from this outbox.');
+        this.detail = detail;
     }
 }
+const running = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to someone else.
+        return error instanceof Error && Reflect.get(error, 'code') === 'EPERM';
+    }
+};
+/** The holder a lock file names, or `undefined` for a file that is empty, half written, or not in this format: such a lock is judged by the clock alone. */
+const holderOf = async (file) => {
+    const text = await readFile(file, 'utf8').catch(() => '');
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const run = Reflect.get(parsed, 'run');
+    const pid = Reflect.get(parsed, 'pid');
+    const host = Reflect.get(parsed, 'host');
+    const since = Reflect.get(parsed, 'since');
+    return typeof run === 'string' && typeof pid === 'number' && Number.isInteger(pid) && pid > 0 && typeof host === 'string' && typeof since === 'number' ? { run, pid, host, since } : undefined;
+};
 // EEXIST means another run holds the file. On Windows an open of a file whose delete is still pending (the holder just released it) answers EPERM or EACCES instead: the same contention, so retry within waitMs.
 const contended = (error, platform) => {
     if (!(error instanceof Error))
@@ -18,24 +49,37 @@ const contended = (error, platform) => {
     return code === 'EEXIST' || (platform === 'win32' && (code === 'EPERM' || code === 'EACCES'));
 };
 /**
- * A stale lock is removed under a takeover guard (`send.lock.takeover`, created with `wx`), so one waiter at a time reads the lock again and removes it only if it is still stale. A live lock is never moved
- * or removed: a waiter that read a lock as stale, but meets a lock another run took over and refreshed in the meantime, finds it fresh under the guard and leaves it. A guard left by a taker that died is
+ * Whether a lock can be removed now: its holder is a process on this machine that is not running (taken over at once, whatever the clock says), or the file has not been touched for `staleMs` (the holder's heartbeat stopped).
+ * A holder whose liveness cannot be read (an empty file, another host's pid) is judged by the clock alone, which is the only reason `staleMs` stays at ten minutes. A pid the system has handed to another process since reads as
+ * running, so pid reuse can only make a waiter wait for the clock, never take a live holder's lock; the lock's age is not taken from the pid for that reason.
+ */
+const reclaimable = async (file, staleMs, fs, now) => {
+    const held = await fs.stat(file).catch(() => undefined);
+    if (held === undefined)
+        return false;
+    if (now() - held.mtimeMs > staleMs)
+        return true;
+    const holder = await holderOf(file);
+    return holder !== undefined && holder.host === (fs.self?.host ?? hostname()) && !(fs.running ?? running)(holder.pid);
+};
+/**
+ * A reclaimable lock is removed under a takeover guard (`send.lock.takeover`, created with `wx`), so one waiter at a time reads the lock again and removes it only if it is still reclaimable. A live lock is never moved
+ * or removed: a waiter that read a lock as reclaimable, but meets a lock another run took over and refreshed in the meantime, finds it live under the guard and leaves it. A guard left by a taker that died is
  * removed once it is older than `staleMs`.
  */
-const takeOver = async (file, staleMs, fs) => {
+const takeOver = async (file, staleMs, fs, now) => {
     const guard = `${file}.takeover`;
     try {
         await (await open(guard, 'wx')).close();
     }
     catch {
         const left = await stat(guard).catch(() => undefined);
-        if (left !== undefined && Date.now() - left.mtimeMs > staleMs)
+        if (left !== undefined && now() - left.mtimeMs > staleMs)
             await rm(guard, { force: true });
         return false;
     }
     try {
-        const held = await fs.stat(file).catch(() => undefined);
-        if (held === undefined || Date.now() - held.mtimeMs <= staleMs)
+        if (!(await reclaimable(file, staleMs, fs, now)))
             return false;
         await rm(file, { force: true });
         return true;
@@ -44,18 +88,25 @@ const takeOver = async (file, staleMs, fs) => {
         await rm(guard, { force: true });
     }
 };
-export const withSendLock = async (outbox, run, times = {}, fs = { stat }) => {
-    const { staleMs, waitMs, pollMs } = { ...DEFAULT_TIMES, ...times };
+export const withSendLock = async (outbox, run, times = {}, fs = { stat }, wait = {}) => {
+    const { staleMs, waitMs, pollMs, noticeMs } = { ...DEFAULT_TIMES, ...times };
     const file = join(outbox, 'send.lock');
     const runId = randomUUID();
     const create = fs.open ?? open;
     const platform = fs.platform ?? process.platform;
+    const clock = fs.clock ?? { now: () => Date.now(), sleep: (ms) => sleep(ms) };
+    const self = fs.self ?? { pid: process.pid, host: hostname() };
     await mkdir(outbox, { recursive: true });
-    const giveUp = Date.now() + waitMs;
+    const began = clock.now();
+    const giveUp = began + waitMs;
+    let noticed = false;
     for (;;) {
+        if (wait.signal?.aborted === true)
+            throw wait.signal.reason;
         try {
             const handle = await create(file, 'wx');
-            await handle.writeFile(runId);
+            const holder = { run: runId, pid: self.pid, host: self.host, since: clock.now() };
+            await handle.writeFile(JSON.stringify(holder));
             await handle.close();
             break;
         }
@@ -65,11 +116,19 @@ export const withSendLock = async (outbox, run, times = {}, fs = { stat }) => {
         }
         const held = await fs.stat(file).catch(() => undefined);
         // A takeover that cleared the lock goes straight back to taking it; any other outcome waits, and gives up once waitMs has passed.
-        if (held !== undefined && Date.now() - held.mtimeMs > staleMs && (await takeOver(file, staleMs, fs)))
+        if (held !== undefined && (await reclaimable(file, staleMs, fs, clock.now)) && (await takeOver(file, staleMs, fs, clock.now)))
             continue;
-        if (Date.now() >= giveUp)
-            throw new SendLockBusy();
-        await sleep(pollMs);
+        const at = clock.now();
+        const holder = await holderOf(file);
+        const untouchedMs = held === undefined ? 0 : Math.max(0, at - held.mtimeMs);
+        const ageMs = holder === undefined ? untouchedMs : Math.max(0, at - holder.since);
+        if (!noticed && at - began >= noticeMs) {
+            noticed = true;
+            wait.onWait?.({ holder, ageMs, waitMs });
+        }
+        if (at >= giveUp)
+            throw new SendLockBusy({ holder, ageMs, untouchedMs, waitedMs: at - began, staleMs, local: holder?.host === self.host });
+        await clock.sleep(pollMs);
     }
     const beat = setInterval(() => {
         const now = new Date();
@@ -81,7 +140,46 @@ export const withSendLock = async (outbox, run, times = {}, fs = { stat }) => {
     finally {
         clearInterval(beat);
         // The file is ours only while it still names this run; a lock another run took over is theirs.
-        if ((await readFile(file, 'utf8').catch(() => undefined)) === runId)
+        if ((await holderOf(file))?.run === runId)
             await rm(file, { force: true });
     }
 };
+/** Why an interactive send ended before it finished: a signal reached it, or the process that launched it is gone. */
+export class SendInterrupted extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'SendInterrupted';
+    }
+}
+const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * The signal an interactive `oars pool deposit --send` waits and sends under. Ctrl-C, a closed terminal, and a kill all end it. A launcher that is killed without a signal reaching its child (Windows `taskkill` of the
+ * shell or the `oars.cmd` shim, a `timeout` wrapper) leaves the child running, so the launcher's pid is read every second and a run whose launcher is gone ends too. The detached nightly sender is not watched:
+ * it is meant to outlive its starter.
+ */
+export const watchInterrupt = (host = { on: (event, listener) => process.on(event, listener), off: (event, listener) => process.off(event, listener), parent: process.ppid, running, checkMs: 1000 }) => {
+    const controller = new AbortController();
+    const listeners = SIGNALS.map((name) => [
+        name,
+        () => {
+            controller.abort(new SendInterrupted('signal', `Interrupted by ${name}.`));
+        },
+    ]);
+    for (const [name, listener] of listeners)
+        host.on(name, listener);
+    const timer = setInterval(() => {
+        if (!host.running(host.parent))
+            controller.abort(new SendInterrupted('launcher', 'The program that started this send is gone.'));
+    }, host.checkMs);
+    timer.unref();
+    return {
+        signal: controller.signal,
+        stop: () => {
+            clearInterval(timer);
+            for (const [name, listener] of listeners)
+                host.off(name, listener);
+        },
+    };
+};

package/dist/sessions/vocab-load.d.ts

@@ -17,10 +17,13 @@ export interface Vocabulary {
     models: ReadonlySet<string>;
     harnessVersions: ReadonlyMap<string, ReadonlySet<string>>;
 }
-/** packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. */
-export declare const VOCAB_DIR: import("url").URL;
+/**
+ * packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. A function, not a constant: a bundle imported from a
+ * `data:` URL (the pool's sample-pack command) has no file location, and building this URL at load time would throw before that caller could pass its own folder.
+ */
+export declare const vocabDir: () => URL;
 export declare const PACKAGE_FILES: readonly ["npm.json", "pypi.json", "crates.json", "rubygems.json", "homebrew.json", "go.json", "maven.json"];
 /** Reads and checks every snapshot under `dir` (default: the shipped folder). */
 export declare const readVocabulary: (dir?: URL) => Vocabulary;
-/** The shipped vocabulary, read once on first use: reading 6 MB of JSON is not free, and most commands never project. */
-export declare const vocabulary: () => Vocabulary;
+/** The vocabulary of a folder (the shipped one by default), read once per folder on first use: reading 6 MB of JSON is not free, and most commands never project. `dir` is for a caller that cannot locate the folder itself. */
+export declare const vocabulary: (dir?: URL) => Vocabulary;

package/dist/sessions/vocab-load.js

@@ -3,8 +3,11 @@
 // A snapshot that does not parse is an error and never an empty list: an empty list would quietly project every name as `private`.
 import { readFileSync } from 'node:fs';
 import { VOCAB_SNAPSHOT_DATE, VOCAB_VERSION } from './public-vocabulary.js';
-/** packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. */
-export const VOCAB_DIR = new URL('../../vocab/', import.meta.url);
+/**
+ * packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. A function, not a constant: a bundle imported from a
+ * `data:` URL (the pool's sample-pack command) has no file location, and building this URL at load time would throw before that caller could pass its own folder.
+ */
+export const vocabDir = () => new URL('../../vocab/', import.meta.url);
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const recordAt = (value, where) => {
     if (!isRecord(value))
@@ -35,7 +38,7 @@ const packageSnapshot = (dir, file) => {
 };
 export const PACKAGE_FILES = ['npm.json', 'pypi.json', 'crates.json', 'rubygems.json', 'homebrew.json', 'go.json', 'maven.json'];
 /** Reads and checks every snapshot under `dir` (default: the shipped folder). */
-export const readVocabulary = (dir = VOCAB_DIR) => {
+export const readVocabulary = (dir = vocabDir()) => {
     const manifest = readJson(dir, 'manifest.json');
     const snapshotDate = manifest['snapshotDate'];
     if (snapshotDate !== VOCAB_SNAPSHOT_DATE) {
@@ -56,6 +59,13 @@ export const readVocabulary = (dir = VOCAB_DIR) => {
         harnessVersions: new Map(Object.entries(harnesses).map(([harness, versions]) => [harness, new Set(stringsAt(versions, `harness.${harness}`))])),
     };
 };
-let loaded;
-/** The shipped vocabulary, read once on first use: reading 6 MB of JSON is not free, and most commands never project. */
-export const vocabulary = () => (loaded ??= readVocabulary());
+const loaded = new Map();
+/** The vocabulary of a folder (the shipped one by default), read once per folder on first use: reading 6 MB of JSON is not free, and most commands never project. `dir` is for a caller that cannot locate the folder itself. */
+export const vocabulary = (dir = vocabDir()) => {
+    const held = loaded.get(dir.href);
+    if (held !== undefined)
+        return held;
+    const read = readVocabulary(dir);
+    loaded.set(dir.href, read);
+    return read;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manyoars/oars",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "mcpName": "io.github.manyoars/oars",
   "description": "A local, searchable record of your coding agent sessions. Reads Claude Code, Cursor, Codex, Copilot CLI, Gemini CLI, and more, and keeps the record on your machine.",
   "homepage": "https://manyoars.com/",
@@ -49,7 +49,7 @@
     "test:live": "vitest run --config vitest.live.config.ts"
   },
   "dependencies": {
-    "@manyoars/oars-client": "^0.1.2",
+    "@manyoars/oars-client": "^0.1.3",
     "commander": "^15.0.0",
     "openid-client": "^6.8.8"
   },