@manyoars/oars 0.5.1 → 0.5.3

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/pool-wire.d.ts

@@ -313,11 +313,12 @@ export declare const SESSION_IDLE_HOURS = 6;
 /** No session leaves this machine sooner than this after it ends, whatever `session_idle_hours` is: time for `oars sessions deposit --deny` or a delete to act on it first. Today the longer idle window governs; this is the floor under it. */
 export declare const HOLD_WINDOW_MS: number;
 /**
- * Whether a session's batch may be built at `now`: no transcript of it, main or subagent, has gained a line for `SESSION_IDLE_HOURS`. A transcript gains a line when capture sees it change, which
- * stamps a new `rev` in epoch milliseconds, but a transcript can grow after the last capture, so `written` (the newest write to any raw file of the session, 0 when none is known) counts too: the
- * session was last active at the later of the two. A subagent that died without an end marker holds its session back at most that long.
+ * Whether a session's batch may be built at `now`: no transcript of it, main or subagent, has gained a line for `SESSION_IDLE_HOURS`. A transcript was last active at its own last line (`tsLast`, the
+ * session's clock, not ours), or at its capture (`rev`, epoch milliseconds) when it has none, so a store captured a minute ago from days-old transcripts holds sessions that ended days ago. A transcript can
+ * also grow after the last capture, so `written` (the newest write to any raw file of the session, 0 when none is known) counts when it is later than every capture: a write at or before the capture is the
+ * file arriving, not the session going on. A last line later than the capture is a bad clock, and the capture caps it. A person's build (`sender` false) takes the ended session at once. The sender, which builds and sends in one run, also waits `HOLD_WINDOW_MS` after the newest capture, so a session oars is seeing for the first time (a days-old transcript of a new harness) leaves no sooner than an hour later, time for `--deny` or a delete. A subagent that died without an end marker holds its session back at most that long.
  */
-export declare const hasEnded: (records: SessionRecords, now: number, written: number, idleMs?: number) => boolean;
+export declare const hasEnded: (records: SessionRecords, now: number, written: number, idleMs?: number, sender?: boolean) => boolean;
 /** Every main session of a store, with its records. */
 export declare const sessionsOf: (store: {
     sessions: readonly SessionObservation[];

package/dist/sessions/pool-wire.js

@@ -89,11 +89,21 @@ const HOUR_MS = 60 * 60 * 1000;
 /** No session leaves this machine sooner than this after it ends, whatever `session_idle_hours` is: time for `oars sessions deposit --deny` or a delete to act on it first. Today the longer idle window governs; this is the floor under it. */
 export const HOLD_WINDOW_MS = HOUR_MS;
 /**
- * Whether a session's batch may be built at `now`: no transcript of it, main or subagent, has gained a line for `SESSION_IDLE_HOURS`. A transcript gains a line when capture sees it change, which
- * stamps a new `rev` in epoch milliseconds, but a transcript can grow after the last capture, so `written` (the newest write to any raw file of the session, 0 when none is known) counts too: the
- * session was last active at the later of the two. A subagent that died without an end marker holds its session back at most that long.
+ * Whether a session's batch may be built at `now`: no transcript of it, main or subagent, has gained a line for `SESSION_IDLE_HOURS`. A transcript was last active at its own last line (`tsLast`, the
+ * session's clock, not ours), or at its capture (`rev`, epoch milliseconds) when it has none, so a store captured a minute ago from days-old transcripts holds sessions that ended days ago. A transcript can
+ * also grow after the last capture, so `written` (the newest write to any raw file of the session, 0 when none is known) counts when it is later than every capture: a write at or before the capture is the
+ * file arriving, not the session going on. A last line later than the capture is a bad clock, and the capture caps it. A person's build (`sender` false) takes the ended session at once. The sender, which builds and sends in one run, also waits `HOLD_WINDOW_MS` after the newest capture, so a session oars is seeing for the first time (a days-old transcript of a new harness) leaves no sooner than an hour later, time for `--deny` or a delete. A subagent that died without an end marker holds its session back at most that long.
  */
-export const hasEnded = (records, now, written, idleMs = SESSION_IDLE_HOURS * HOUR_MS) => now - Math.max(written, ...records.transcripts.map(({ session }) => session.rev)) >= Math.max(idleMs, HOLD_WINDOW_MS);
+export const hasEnded = (records, now, written, idleMs = SESSION_IDLE_HOURS * HOUR_MS, sender = false) => {
+    const lastLines = records.transcripts.map(({ session }) => {
+        const ts = session.tsLast === null ? Number.NaN : Date.parse(session.tsLast);
+        return Number.isNaN(ts) ? session.rev : Math.min(ts, session.rev);
+    });
+    const captured = Math.max(...records.transcripts.map(({ session }) => session.rev));
+    if (sender && now - captured < HOLD_WINDOW_MS)
+        return false;
+    return now - Math.max(written > captured ? written : 0, ...lastLines) >= Math.max(idleMs, HOLD_WINDOW_MS);
+};
 const groupBy = (items, keyOf) => {
     const groups = new Map();
     for (const item of items) {

package/dist/sessions/read-interaction.js

@@ -1,6 +1,6 @@
 // Interaction (spec Section 6, order 2): a tool fails more on one tier than another, beyond how those two tiers differ on every other tool. The difference of differences is
 // what makes it an interaction: a tier that fails more on everything has a main effect, usually the harder work it is given. The axis is the tier assigned, not a model version
-// (ruling mrd5591-08: one version per model on this store), and comparisons hold the version bucket constant. Effort is not in a cell (rule 3), so nothing here holds it. Confounders it does not remove: task assignment by
+// (ruling owner-08: one version per model on this store), and comparisons hold the version bucket constant. Effort is not in a cell (rule 3), so nothing here holds it. Confounders it does not remove: task assignment by
 // tier, which is the operator's own choice and the largest of them, effort, prompt class, and a failure not being a misfit.
 import { UNKNOWN } from './cells.js';
 import { candidateOf, differenceOf, estimateOf, screen, TRIALS_FLOOR } from './read-order.js';

package/dist/sessions/read-lead-lag.js

@@ -1,5 +1,5 @@
 // Lead-lag (spec Section 6, order 3), the labeled experiment: does a tool's failure rate moving come before its share moving? Chosen over a model release moving tool choice
-// because each model has one version here with no release date (ruling mrd5591-08), and two version boundaries are too few to cut in time, while consecutive days over many tools
+// because each model has one version here with no release date (ruling owner-08), and two version boundaries are too few to cut in time, while consecutive days over many tools
 // can be cut. A search over pairs of tools was rejected: it manufactures the false patterns Section 6 warns about, and this is one question asked once.
 //
 // A pair shares no day between its sides. A failure move ending on day d is paired with the share move from d+1 to d+2, not d to d+1: a burst of failing calls on d lifts both the

package/dist/sessions/read-readable.js

@@ -1,4 +1,4 @@
-// What this store cannot read, stated rather than forced (ruling mrd5591-08). A family that finds nothing has made no claim about why, so a reader of an empty family could take
+// What this store cannot read, stated rather than forced (ruling owner-08). A family that finds nothing has made no claim about why, so a reader of an empty family could take
 // "no reads" for "nothing moved". These rows separate the two: a question the store cannot ask from one it asked and got no answer to.
 import { interactionCandidates } from './read-interaction.js';
 import { leadLagPairs, PAIRS_FLOOR } from './read-lead-lag.js';

package/dist/sessions/redact.d.ts

@@ -8,10 +8,19 @@ export declare const makeRedactor: (domains?: readonly string[]) => Redactor;
 export declare const placeholders: (text: string) => number;
 /** The names this machine's person goes by in a transcript: the account's and the home folder's. A name under three characters would mask ordinary words, so it is left to the path rules. */
 export declare const localNames: (home?: string, account?: () => string) => string[];
+/** What only a sample pack asks of the raw-copy rules (t1111). */
+export interface PackRules {
+    /** The accounts the operator's repositories live under (a GitHub user or organization): masked as `<owner>` where one stands as a path segment or after a `:` of a remote. */
+    handles?: readonly string[];
+    /** Rewrites a tool use id (`toolu_...`, `srvtoolu_...`) to the value the pack keys it to, so a call and its result still pair; without it the entropy rule masks each as `<secret>`. */
+    toolId?: (id: string) => string;
+    /** Keeps a public host the session itself fetched or searched (the URL or `allowed_domains` of a WebFetch or WebSearch input) in the clear in that call's result. */
+    fetchedHosts?: boolean;
+}
 /** A whole transcript body redacted for upload, and how many values were masked (placeholders added, a count and nothing else). `names` are the local usernames to mask wherever they stand as a whole word. */
-export declare const redactTranscript: (body: string, domains?: readonly string[], names?: readonly string[], injectedKey?: string) => {
+export declare const redactTranscript: (body: string, domains?: readonly string[], names?: readonly string[], injectedKey?: string, pack?: PackRules) => {
     text: string;
     masked: number;
 };
 /** The version of the rules above, stated to the pool with every raw part; a change to any rule of `redactTranscript` raises it. */
-export declare const REDACTION_VERSION = "3";
+export declare const REDACTION_VERSION = "4";

package/dist/sessions/redact.js

@@ -8,25 +8,30 @@ import { injectedRule, learnInjected } from './injected.js';
 export const PATTERNS = [
     [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, '<secret>'],
     [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, '<secret>'],
-    [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, '<secret>'],
-    [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, '<secret>'],
+    // A synthetic fixture quoted in a session is masked like a real token (a secret scanner flags the prefix, not the value), so the minimums are short and the
+    // left guard is a non-alphanumeric: `FAKE_ghp_...` still starts a token where `\b` would miss it.
+    [/(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{8,}(?![A-Za-z0-9])/g, '<secret>'],
+    [/(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{8,}(?![A-Za-z0-9])/g, '<secret>'],
     [/\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}\b/g, '<secret>'],
-    [/\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{10,}\b/g, '<secret>'],
-    [/\bwhsec_[A-Za-z0-9]{10,}\b/g, '<secret>'],
-    [/\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g, '<secret>'],
+    [/(?<![A-Za-z0-9])(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{6,}(?![A-Za-z0-9])/g, '<secret>'],
+    [/(?<![A-Za-z0-9])whsec_[A-Za-z0-9]{6,}(?![A-Za-z0-9])/g, '<secret>'],
+    [/(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{6,}(?![A-Za-z0-9])/g, '<secret>'],
     [/\bAIza[0-9A-Za-z_-]{30,}\b/g, '<secret>'],
     [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, '<secret>'],
     [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{12,}/gi, '$1 <secret>'],
     // user:password@host inside a URL
     [/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/:@]+:[^\s/@]+@/gi, '$1<secret>@'],
-    // NAME=value and "name": "value" where the name says it is a secret
-    [/\b([A-Za-z0-9_-]*(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|credential)[A-Za-z0-9_-]*)(["']?\s*[=:]\s*)(["']?)[^\s"'&,;]{4,}\3/gi, '$1$2$3<secret>$3'],
+    // NAME=value and "name": "value" where the name says it is a secret. A vendor name before a colon (`1password: ...` in prose) is no key. A plural
+    // `tokens` name (`tokens`, `max_tokens`, `inputTokens`) is a count and keeps a bare number, as the JSON walk does; any other `token` name masks a number too.
+    [/\b(?!1password(?![A-Za-z0-9_-])["']?\s*:\s)([A-Za-z0-9_-]*(?:password|passwd|secret|api[_-]?key|private[_-]?key|credential)[A-Za-z0-9_-]*)(["']?\s*[=:]\s*)(["']?)[^\s"'&,;]{4,}\3/gi, '$1$2$3<secret>$3'],
+    [/\b((?![A-Za-z0-9_-]*tokens(?![A-Za-z0-9_-]))[A-Za-z0-9_-]*token[A-Za-z0-9_-]*)(["']?\s*[=:]\s*)(["']?)[^\s"'&,;]{4,}\3/gi, '$1$2$3<secret>$3'],
+    [/\b([A-Za-z0-9_-]*tokens)(["']?\s*[=:]\s*)(["']?)(?!\d+(?![^\s"'&,;]))[^\s"'&,;]{4,}\3/gi, '$1$2$3<secret>$3'],
 ];
 const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+/g;
 // A pinned alias, `foo@npm:bar@1.0.0` or `jsr:@scope/bar@1.0.0`, ends in `bar@1.0.0`, which EMAIL reads as an address. Digits and dots after
 // the `@` are a version, never a domain, so that one shape right after `npm:` or `jsr:` (and an optional scope) is kept. An all-numeric four-part tail is an
 // IP address, a real host, so it stays masked (as in `extract.ts` `VERSIONED`); any other address stays masked too.
-const ALIAS_PREFIX = /(?<![A-Za-z0-9])(?:npm|jsr):(?:@[A-Za-z0-9._~-]+\/)?$/;
+const ALIAS_PREFIX = /(?<![A-Za-z0-9])(?:npm|jsr):(?:@[A-Za-z0-9._~-]+\/)?$|(?<![A-Za-z0-9._%+-])@[A-Za-z0-9._~-]+\/$/;
 const DOTTED_VERSION = /@(?!\d+\.\d+\.\d+\.\d+$)\d+(?:\.\d+)+$/;
 const TOKEN = /[A-Za-z0-9+_=-]{24,}/g;
 const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -71,7 +76,7 @@ const PROMPT = /(?:<user>|\b[A-Za-z0-9._-]+)@[A-Za-z0-9-]+(?=:[~/.])/g;
 // Full, compressed, and loopback forms. A clock time (`10:20:30`) has no `::`, so it is never one.
 const IPV6 = /(?<![0-9A-Za-z:])(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:(?:[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,6})?|::[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,6})(?![0-9A-Za-z:])/gi;
 const MIN_NAME = 3;
-const PLACEHOLDER = /<(?:secret|email|org-domain|host|user|env)>/g;
+const PLACEHOLDER = /<(?:secret|email|org-domain|host|user|env|owner)>/g;
 // A `.env` line whose name is lower case (`mapbox=q8z7...`): only a whole line of that shape, so `--flag=value` and `?page=2` are left alone.
 const LOWER_ENVIRONMENT = /^([ \t]*(?:export[ \t]+)?[a-z][a-z0-9_]{2,}=)(?!<)(?:(["'])[^"'\n]*\2|[^\s"']+)[ \t]*$/gm;
 // Shapes `makeRedactor` does not know (t955, census S3). They run only on a raw copy, and before the shared rules, because the entropy rule would
@@ -112,7 +117,7 @@ const parseContainer = (text) => {
         return undefined;
     }
 };
-const redactDecoded = (body, redactText, injected) => {
+const redactDecoded = (body, redactText, injected, enter) => {
     // A name reaches the strings of an array under it (`"tokens": ["..."]`); an object's own keys name their values.
     const walk = (value, name) => {
         if (typeof value === 'string')
@@ -133,15 +138,27 @@ const redactDecoded = (body, redactText, injected) => {
     // The text as it was when nothing in it changed; otherwise the value written again, inside the whitespace (a `\r`, a newline) it had around it.
     // A transcript line is a top-level object: the harness's own blocks in it are marked first (their hash is of the text as written), then the rest is walked.
     const rewrite = (text, parsed, top) => {
+        if (top && !Array.isArray(parsed))
+            enter(parsed);
         const marked = top && !Array.isArray(parsed) ? injected(parsed) : parsed;
         const next = walk(marked, '');
         return next === parsed ? text : `${text.slice(0, text.length - text.trimStart().length)}${JSON.stringify(next)}${text.slice(text.trimEnd().length)}`;
     };
+    // A top-level plain-text run follows no tool result: a host a fetch named is kept in that result's line only (a string inside the line is not top level).
+    const redactPlain = (run, top) => {
+        if (top)
+            enter();
+        return redactText(run.join('\n'));
+    };
     // `text` is a whole document, or lines of which some are JSON: the JSON ones are walked, the runs between them take the plain-text path.
     const redactBlock = (text, top = false) => {
         const whole = parseContainer(text);
-        if (whole !== undefined)
+        // A top-level array line is no tool-result line: it keeps no fetched host.
+        if (whole !== undefined) {
+            if (top && Array.isArray(whole))
+                enter();
             return rewrite(text, whole, top);
+        }
         const out = [];
         let run = [];
         for (const line of text.split('\n')) {
@@ -151,12 +168,12 @@ const redactDecoded = (body, redactText, injected) => {
                 continue;
             }
             if (run.length > 0)
-                out.push(redactText(run.join('\n')));
+                out.push(redactPlain(run, top));
             run = [];
             out.push(rewrite(line, parsed, top));
         }
         if (run.length > 0)
-            out.push(redactText(run.join('\n')));
+            out.push(redactPlain(run, top));
         return out.join('\n');
     };
     return redactBlock(body, true);
@@ -183,15 +200,70 @@ const nameRule = (names) => {
     const forms = [...new Set(usable.flatMap((name) => [name, name.replace(/[^A-Za-z0-9]/g, '-')]))].sort((a, b) => b.length - a.length);
     return forms.length === 0 ? undefined : new RegExp(`(?<![A-Za-z0-9<])(?:${forms.map(escapeRegExp).join('|')})(?![A-Za-z0-9>])`, 'gi');
 };
+const TOOL_ID = /(?<![A-Za-z0-9])(?:srv)?tool(?:u|use)_(?:bdrk_|vrtx_)?[A-Za-z0-9_-]{8,}/g;
+const FETCH_TOOLS = new Set(['WebFetch', 'WebSearch']);
+const HOST_OF_URL = /^[a-z][a-z0-9+.-]*:\/\/([A-Za-z0-9.-]+)/i;
+const URLS = /\b[a-z][a-z0-9+.-]*:\/\/[^\s/@"'\\]*@?[A-Za-z0-9.-]+/gi;
+// Loopback, an IP literal, a bare name, and the internal suffixes of INTERNAL_NAME are never a public host.
+const INTERNAL_SUFFIX = /\.(?:internal|local|lan|corp|intranet|home|localdomain)$/;
+const publicHost = (host) => host.includes('.') && !/^[\d.]+$/.test(host) && !INTERNAL_SUFFIX.test(host) && host !== 'localhost';
+const hostsIn = (value, found, listed = false) => {
+    if (typeof value === 'string') {
+        for (const url of value.match(URLS) ?? [])
+            if (!url.includes('@'))
+                found.add((HOST_OF_URL.exec(url)?.[1] ?? '').toLowerCase());
+        // `allowed_domains` lists bare domains.
+        if (listed)
+            found.add(value.toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, '').replace(/[/:].*$/, ''));
+    }
+    else if (Array.isArray(value))
+        for (const item of value)
+            hostsIn(item, found, listed);
+    else if (typeof value === 'object' && value !== null)
+        for (const [key, item] of Object.entries(value))
+            hostsIn(item, found, key === 'allowed_domains');
+};
+/** The blocks of a transcript line's message content, when it has any. */
+const blocksOf = (line) => {
+    const message = line['message'];
+    const content = typeof message === 'object' && message !== null && !Array.isArray(message) ? message['content'] : undefined;
+    return Array.isArray(content) ? content.filter((block) => typeof block === 'object' && block !== null && !Array.isArray(block)) : [];
+};
+/** The public hosts each WebFetch or WebSearch call of a transcript named, by the call's tool use id. */
+const fetchedBy = (lines) => {
+    const byId = new Map();
+    for (const line of lines) {
+        for (const block of blocksOf(line)) {
+            const { type, id, name, input } = block;
+            if (type !== 'tool_use' || typeof id !== 'string' || typeof name !== 'string' || !FETCH_TOOLS.has(name) || input === undefined)
+                continue;
+            const found = new Set();
+            hostsIn(input, found);
+            byId.set(id, new Set([...found].filter(publicHost)));
+        }
+    }
+    return byId;
+};
+// A handle is a whole path segment (`/acme/app`, `\acme\app`, `git@host:acme/app.git`) or a hyphen-bounded word of an encoded project folder (`-repos-acme-app`).
+const handleRule = (handles) => {
+    const usable = [...new Set(handles.filter((handle) => handle.length >= MIN_NAME))].sort((a, b) => b.length - a.length);
+    return usable.length === 0 ? undefined : new RegExp(String.raw `(?<=[\\/:-])(?:${usable.map(escapeRegExp).join('|')})(?=[\\/.-]|["'\s]|$)`, 'gi');
+};
 /** A whole transcript body redacted for upload, and how many values were masked (placeholders added, a count and nothing else). `names` are the local usernames to mask wherever they stand as a whole word. */
-export const redactTranscript = (body, domains = [], names = [], injectedKey = randomBytes(16).toString('hex')) => {
+export const redactTranscript = (body, domains = [], names = [], injectedKey = randomBytes(16).toString('hex'), pack = {}) => {
     const named = nameRule(names);
+    const owner = handleRule(pack.handles ?? []);
     const known = makeRedactor(domains);
-    const redactText = (text) => {
+    // The hosts the line being redacted may keep: those its tool results' calls fetched.
+    let kept = new Set();
+    const keepHost = (match, scheme) => (!match.includes('@') && kept.has((HOST_OF_URL.exec(match)?.[1] ?? '').toLowerCase()) ? match : `${scheme}<host>`);
+    const redactText = (original) => {
+        const text = pack.toolId === undefined ? original : original.replace(TOOL_ID, pack.toolId);
         // The names go first: a hyphenated or spaced name must be masked whole before the path rules take its first word.
         const masked = known(rawRules(text));
-        return (named === undefined ? masked : masked.replace(named, '<user>'))
-            .replace(URL_HOST, '$1<host>')
+        const mine = named === undefined ? masked : masked.replace(named, '<user>');
+        return (owner === undefined ? mine : mine.replace(owner, '<owner>'))
+            .replace(URL_HOST, keepHost)
             .replace(INTERNAL_NAME, '<host>')
             .replace(IPV4, '<host>')
             .replace(IPV6, '<host>')
@@ -208,8 +280,12 @@ export const redactTranscript = (body, domains = [], names = [], injectedKey = r
     for (const parsed of whole !== undefined ? [whole] : body.split('\n').map(parseContainer))
         if (parsed !== undefined && !Array.isArray(parsed))
             learnInjected(parsed, repeated);
-    const redacted = redactDecoded(body, redactText, injectedRule(injectedKey, repeated));
+    const calls = pack.fetchedHosts === true ? fetchedBy([...(whole !== undefined ? [whole] : body.split('\n').map(parseContainer))].filter((parsed) => parsed !== undefined && !Array.isArray(parsed))) : new Map();
+    const enter = (line) => {
+        kept = new Set(line === undefined ? [] : blocksOf(line).flatMap((block) => (block['type'] === 'tool_result' && typeof block['tool_use_id'] === 'string' ? [...(calls.get(block['tool_use_id']) ?? [])] : [])));
+    };
+    const redacted = redactDecoded(body, redactText, injectedRule(injectedKey, repeated), enter);
     return { text: redacted, masked: Math.max(0, placeholders(redacted) - placeholders(body)) };
 };
 /** The version of the rules above, stated to the pool with every raw part; a change to any rule of `redactTranscript` raises it. */
-export const REDACTION_VERSION = '3';
+export const REDACTION_VERSION = '4';

package/dist/sessions/repo-root.d.ts

@@ -2,6 +2,13 @@
 export declare const makeRepoRoot: (exists?: (path: string) => boolean) => ((cwd: string) => string | null);
 /** `https://User:pw@GitHub.com/org/repo.git`, `git@github.com:org/repo.git`, and `ssh://git@github.com/org/repo/` all read `github.com/org/repo`. */
 export declare const normalizeRemote: (url: string) => string;
+/** The `url` of `[remote "origin"]` in a git `config`, or null. */
+export declare const originUrl: (config: string) => string | null;
+/**
+ * The git `config` text of a repository root, or null: `<root>/.git/config`, or for a linked worktree or submodule (`.git` is a file)
+ * the common directory's, reached through the file's `gitdir:` line and that directory's `commondir` file.
+ */
+export declare const configOf: (root: string, read?: (path: string) => string | null) => string | null;
 /**
  * A resolver from a repository root to its identity string: `origin:<normalized remote>` when the repository's `config` names an
  * `origin`, else `path:<root>`. The `config` is `<root>/.git/config`, or for a linked worktree (`.git` is a file) the common