@basein/runner 0.3.25 → 0.3.27

package/dist/record/remote-recorder.d.ts

@@ -25,7 +25,17 @@
  *     too; its retry is for the recording, never for a hook.
  *   - **One probe, not a stampede.** While the breaker is half-open, one
  *     queued send finds out for all the lanes; the rest wait for its verdict
- *     and then follow it a moment apart, not all at once.
+ *     and then follow it a moment apart, not all at once. When a turn's last
+ *     send fails and none is queued, one timer for the end of the cool-down
+ *     asks with a `GET /health` instead, so the next prompt finds the service
+ *     answering again ({@link CooldownTimer}).
+ *   - **A send the service takes twice is not given up on one failure.** A
+ *     run's finish, a step's patch and an execution report with a ticket go
+ *     back to the head of their lane when a try ends without the service's
+ *     verdict (a timeout, a reset, a 5xx), {@link REPEATABLE_TRIES} tries in
+ *     all, paced by the breaker's cool-down and never given up on its wait. A
+ *     finish lost to one 502 leaves a run that never ends. Every other send is
+ *     tried once: the service does not deduplicate their ids.
  *   - **Bounded.** The lanes are the real backlog (the hook server's step queue
  *     drains instantly into them), so they carry the bound: past
  *     {@link DEFAULT_MAX_PENDING_SENDS} sends or {@link DEFAULT_MAX_PENDING_BYTES}
@@ -35,7 +45,8 @@
  *     expiry, then one retry. Sessions outlive access tokens.
  *   - **It follows credentials.json.** `bir logout` removes the file; a
  *     recorder that loaded its session from it stops sending within seconds,
- *     rather than recording for the rest of the access token's life.
+ *     rather than recording for the rest of the access token's life. A token
+ *     refresh answered after the file changed is dropped, not saved over it.
  *   - **It redacts and caps every free-text field it sends** — the prompt, the
  *     answer, reasoning, errors — as the last line of defence. Structured tool
  *     payloads are redacted by their producers; text is only ever seen here.
@@ -170,6 +181,8 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
      * or a hook-requested `GET /health` — and when it started.
      */
     private probe?;
+    /** Asks again, at the end of a cool-down, when no send is left to ({@link drain}). */
+    private readonly idleProbe;
     private matchIntentOffUntil;
     /** True once this recorder's session is known to be the one in credentials.json. */
     private follow;
@@ -316,7 +329,8 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
      * A doubled report (a retry, `Stop` racing `SessionEnd`) is safe by
      * construction: the ticket *is* the row's id, so the service books once and
      * answers `200 { duplicate: true }`. That is also why a report *with* a
-     * ticket is the one kind retried after an ambiguous failure.
+     * ticket is sent again after an ambiguous failure ({@link REPEATABLE_TRIES}),
+     * as a run's finish and a step's patch are; a report without one is not.
      */
     reportExecution(report: ExecutionReport): void;
     /**
@@ -352,7 +366,11 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
      * is actually waiting.
      */
     private waitForLanes;
-    /** Run one job: decide whether it may still go, wait out a cool-down, send. Never throws. */
+    /**
+     * Run one job: decide whether it may still go, wait out a cool-down, send.
+     * A repeatable job that got no verdict goes back to the head of `lane`, its
+     * own, to be run again. Never throws.
+     */
     private execute;
     private whyNotSend;
     /**
@@ -404,7 +422,10 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
      * - The breaker is closed: go at once.
      * - It is cooling down: sleep until it ends. A send that has waited
      *   {@link COOLDOWN_WAIT_MAX_MS} and still faces more than
-     *   {@link COOLDOWN_GRACE_MS} of it is given up (`giveUp`), unsent.
+     *   {@link COOLDOWN_GRACE_MS} of it is given up (`giveUp`), unsent — unless
+     *   `mayGiveUp` is false: a repeatable send ({@link REPEATABLE_TRIES}) is
+     *   bounded by its tries, each one paced by a cool-down, and a finish given
+     *   up after a minute's outage left a run that never ends.
      * - It is half-open: ONE lane takes the probe slot and goes (`endProbe`
      *   gives the slot back once its send settles); every other lane waits for
      *   that verdict. A success lets them go, each after its own short random

package/dist/record/remote-recorder.js

@@ -25,7 +25,17 @@
  *     too; its retry is for the recording, never for a hook.
  *   - **One probe, not a stampede.** While the breaker is half-open, one
  *     queued send finds out for all the lanes; the rest wait for its verdict
- *     and then follow it a moment apart, not all at once.
+ *     and then follow it a moment apart, not all at once. When a turn's last
+ *     send fails and none is queued, one timer for the end of the cool-down
+ *     asks with a `GET /health` instead, so the next prompt finds the service
+ *     answering again ({@link CooldownTimer}).
+ *   - **A send the service takes twice is not given up on one failure.** A
+ *     run's finish, a step's patch and an execution report with a ticket go
+ *     back to the head of their lane when a try ends without the service's
+ *     verdict (a timeout, a reset, a 5xx), {@link REPEATABLE_TRIES} tries in
+ *     all, paced by the breaker's cool-down and never given up on its wait. A
+ *     finish lost to one 502 leaves a run that never ends. Every other send is
+ *     tried once: the service does not deduplicate their ids.
  *   - **Bounded.** The lanes are the real backlog (the hook server's step queue
  *     drains instantly into them), so they carry the bound: past
  *     {@link DEFAULT_MAX_PENDING_SENDS} sends or {@link DEFAULT_MAX_PENDING_BYTES}
@@ -35,7 +45,8 @@
  *     expiry, then one retry. Sessions outlive access tokens.
  *   - **It follows credentials.json.** `bir logout` removes the file; a
  *     recorder that loaded its session from it stops sending within seconds,
- *     rather than recording for the rest of the access token's life.
+ *     rather than recording for the rest of the access token's life. A token
+ *     refresh answered after the file changed is dropped, not saved over it.
  *   - **It redacts and caps every free-text field it sends** — the prompt, the
  *     answer, reasoning, errors — as the last line of defence. Structured tool
  *     payloads are redacted by their producers; text is only ever seen here.
@@ -49,11 +60,11 @@
  * before the answer came.
  */
 import { randomUUID } from "node:crypto";
-import { statSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { credentialsPath, describeBody, isAuthResponse, issuedFor, loadCredentials, saveCredentials, } from "../auth/client.js";
 import { errText, logDetail, logEvery, logLine } from "../util/log.js";
 import { serviceHeaders } from "../util/service-headers.js";
-import { isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
+import { isUnhealthyStatus, MAX_TIMER_MS, serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
 import { redact, redactJsonText, redactText } from "./redact.js";
 import { capJsonText, capText, DEFAULT_MAX_PAYLOAD_BYTES, preCut, REPORT_PAYLOAD_MAX_BYTES, truncateString, } from "./truncate.js";
 /**
@@ -141,6 +152,18 @@ const RETRY_STATUSES = new Set([429, 503]);
  * double it. A reset mid-request is not among them.
  */
 const SAFE_RETRY_CODES = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT"]);
+/**
+ * How often, in all, a send the service takes twice without harm is tried
+ * when a try ends without the service's verdict (a timeout, a reset, a 5xx):
+ * a run's finish (an update the service expects more than once), a step's
+ * patch (it sets one field), and an execution report with a ticket (the
+ * ticket is the row's id, and a repeat is answered `200 { duplicate: true }`).
+ * Why the other sends are not repeated — the service does not deduplicate
+ * their ids — does not hold for these three, and one lost try cost a run that
+ * never ends (the service embeds a run at its finish, so its prompt never
+ * matches and it is never calculated) or a turn whose cost is never booked.
+ */
+const REPEATABLE_TRIES = 3;
 /** A refresh that failed without an answer to act on is not tried again sooner than this. */
 const REFRESH_RETRY_MS = 30_000;
 /** After a refused refresh, how long to wait for a sibling's newer session to land on disk. */
@@ -375,9 +398,10 @@ function pendError(text) {
         return undefined;
     return /^\s*[{[]/.test(text) ? pend(text, DEFAULT_MAX_PAYLOAD_BYTES, true) : pend(text, TEXT_CAPS.toolError);
 }
+/** A positive number from the environment, held to what a timer takes ({@link MAX_TIMER_MS}). */
 function positiveEnv(name, fallback) {
     const n = Number(process.env[name]);
-    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+    return Number.isFinite(n) && n > 0 ? Math.min(Math.floor(n), MAX_TIMER_MS) : fallback;
 }
 function reasonOf(err) {
     const cause = err?.cause;
@@ -388,6 +412,15 @@ function causeCode(err) {
     const cause = err?.cause;
     return cause?.code ?? cause?.errors?.[0]?.code;
 }
+/**
+ * Did a send end without the service's verdict on it? No answer at all (a
+ * timeout, a reset, no connection), or a status that is the service being
+ * unwell rather than answering (a 5xx, 408, 429). Any other status is its
+ * answer, and final.
+ */
+function noVerdict(err) {
+    return err instanceof ServiceError && (err.status === undefined || isUnhealthyStatus(err.status));
+}
 /**
  * An answer that is a web page rather than the API: a captive portal, a
  * website, a CDN challenge. Judged by the body — an empty or plain-text 2xx
@@ -462,6 +495,51 @@ function retryDelayMs(res) {
     }
     return jitterMs();
 }
+/**
+ * The one timer that asks a failing service again when no send is left to.
+ *
+ * A failure stays on record until the service next answers, and after a
+ * turn's last send the next request is the next prompt's create — whose hook
+ * does not wait for its match while a failure is on record. So one 502 at the
+ * end of a turn left the next prompt unreplayed, twenty minutes later,
+ * although the service had answered everybody else all along: nothing asked
+ * it between turns.
+ *
+ * One timer, for the end of the cool-down, so the service is asked at most
+ * once per cool-down; unref'd, so a recorder with nothing to send is never
+ * what keeps a process alive; and nothing while no failure is on record.
+ */
+class CooldownTimer {
+    health;
+    ask;
+    timer;
+    constructor(health, 
+    /** Called once the cool-down is over. */
+    ask) {
+        this.health = health;
+        this.ask = ask;
+    }
+    arm() {
+        if (this.timer || this.health.snapshot().consecutiveFailures === 0)
+            return;
+        const left = (this.health.snapshot().openUntil ?? 0) - Date.now();
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            // A send that was already out has failed since, and made the cool-down
+            // longer (a turn's finish and its report, one 502 after the other):
+            // asking now would be asking into it. Wait that out too.
+            if (this.health.canWait())
+                this.ask();
+            else
+                this.arm();
+        }, Math.max(left, 25));
+        this.timer.unref?.();
+    }
+    clear() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+}
 const PAUSE_WHY = {
     signed_out: "credentials.json was removed (bir logout) — nothing more is sent and replay stops until you sign in again",
     auth_rejected: "the service refused this session and no newer one was on disk — run `bir login`; recording resumes on its own (the session is also retried every 10 minutes)",
@@ -509,6 +587,8 @@ export class RemoteRecorder {
      * or a hook-requested `GET /health` — and when it started.
      */
     probe;
+    /** Asks again, at the end of a cool-down, when no send is left to ({@link drain}). */
+    idleProbe;
     matchIntentOffUntil = 0;
     /** True once this recorder's session is known to be the one in credentials.json. */
     follow = false;
@@ -527,6 +607,7 @@ export class RemoteRecorder {
         this.authRecheckMs = opts.authRecheckMs ?? AUTH_RECHECK_MS;
         this.authRetryMs = opts.authRetryMs ?? AUTH_REJECTED_RETRY_MS;
         this.cooldownWaitMaxMs = opts.cooldownWaitMaxMs ?? COOLDOWN_WAIT_MAX_MS;
+        this.idleProbe = new CooldownTimer(this.health, () => this.probeIfFailing());
         // Follow the file only when this session came from it. A synthetic session
         // (BIR_AUTH_DISABLE, tests) has no file, and must not read "no file" as
         // "signed out".
@@ -979,7 +1060,8 @@ export class RemoteRecorder {
      * A doubled report (a retry, `Stop` racing `SessionEnd`) is safe by
      * construction: the ticket *is* the row's id, so the service books once and
      * answers `200 { duplicate: true }`. That is also why a report *with* a
-     * ticket is the one kind retried after an ambiguous failure.
+     * ticket is sent again after an ambiguous failure ({@link REPEATABLE_TRIES}),
+     * as a run's finish and a step's patch are; a report without one is not.
      */
     reportExecution(report) {
         const costUsd = report.deriveCostUsd + report.sessionCostUsd + report.fallbackCostUsd;
@@ -999,6 +1081,8 @@ export class RemoteRecorder {
             bytes: sizeOf(prompt, error, answer, ...(steps ?? []).flatMap((s) => [s.toolInput, s.toolOutput])) +
                 Math.min(callBytes, ANSWER_CALLS_MAX_BYTES + 64 * 1024) +
                 1024,
+            // Without a ticket nothing tells the service a repeat from a second report.
+            repeatable: Boolean(report.ticket),
             send: async () => {
                 // Shaped here, off the hook's path: the cuts serialize the calls a few times.
                 const answerCalls = calls ? answerCallsBody(calls) : undefined;
@@ -1189,6 +1273,7 @@ export class RemoteRecorder {
             send: async () => {
                 await send();
             },
+            repeatable: kind === "finish" || kind === "patch",
         });
     }
     /** Append to a lane. Synchronous and never throws; the lane drains after the caller returns. */
@@ -1225,7 +1310,7 @@ export class RemoteRecorder {
                 this.pendingSends -= 1;
                 this.pendingBytes -= job.bytes;
                 this.noteBacklogRecovered();
-                await this.execute(job);
+                await this.execute(job, lane);
             }
         }
         catch {
@@ -1241,6 +1326,10 @@ export class RemoteRecorder {
                     this.lanes.delete(key);
                 for (const resolve of lane.waiters.splice(0))
                     resolve();
+                // Its last send may have left a failure on record, and no send is
+                // queued here to find out when the service answers again.
+                if (this.state === "recording")
+                    this.idleProbe.arm();
             }
         }
     }
@@ -1275,7 +1364,7 @@ export class RemoteRecorder {
             };
             // Not unref'd: a caller awaiting this must get its answer even when the
             // only other thing left is a lane asleep in an unref'd cool-down.
-            const deadline = setTimeout(() => finish("timeout"), Math.max(0, timeoutMs));
+            const deadline = setTimeout(() => finish("timeout"), Math.min(Math.max(0, timeoutMs), MAX_TIMER_MS));
             const poll = setInterval(() => {
                 if (!this.health.canWait())
                     finish("cooling");
@@ -1303,8 +1392,12 @@ export class RemoteRecorder {
                 finish("idle");
         });
     }
-    /** Run one job: decide whether it may still go, wait out a cool-down, send. Never throws. */
-    async execute(job) {
+    /**
+     * Run one job: decide whether it may still go, wait out a cool-down, send.
+     * A repeatable job that got no verdict goes back to the head of `lane`, its
+     * own, to be run again. Never throws.
+     */
+    async execute(job, lane) {
         const run = job.runId ? this.runs.get(job.runId) : undefined;
         let endProbe;
         try {
@@ -1312,8 +1405,9 @@ export class RemoteRecorder {
             if (why)
                 return this.retire(job, run, why);
             // Don't hammer a service that just failed: wait out its cool-down, and
-            // then let one send (maybe this one) find out whether it came back.
-            const wait = await this.waitForService();
+            // then let one send (maybe this one) find out whether it came back. A
+            // repeatable job waits however long that takes: its tries are its bound.
+            const wait = await this.waitForService(!job.repeatable);
             endProbe = wait.endProbe;
             if (wait.giveUp) {
                 this.retire(job, run, "service_down");
@@ -1322,7 +1416,11 @@ export class RemoteRecorder {
                     this.markDead(job.runId, run, "service_down");
                 return;
             }
-            await this.refreshAhead();
+            // Not once paused: the wait above ends at once then (`bir logout` while
+            // this send slept out a cool-down), and a refresh here would spend the
+            // token of the session that was just signed out.
+            if (this.state === "recording")
+                await this.refreshAhead();
             // Both can take a while (a minute of cool-down, a refresh), and a hook
             // may have signed another account in meanwhile: ask again, or a run
             // opened under one account would go out under the next one's token.
@@ -1338,6 +1436,26 @@ export class RemoteRecorder {
                 this.retire(job, run, this.accountChanged(job, run));
                 return;
             }
+            if (job.repeatable && noVerdict(err)) {
+                job.tries = (job.tries ?? 0) + 1;
+                if (job.tries < REPEATABLE_TRIES) {
+                    // Not lost yet, so not counted as failed. At the head, so nothing
+                    // queued behind it goes first; and when it goes is the breaker's
+                    // business — the failure just reported opened it, and this job
+                    // sleeps out the cool-down like any other (it is then the probe).
+                    lane.jobs.unshift(job);
+                    this.pendingSends += 1;
+                    this.pendingBytes += job.bytes;
+                    logDetail("recorder.send_again", {
+                        run: job.lane,
+                        kind: job.kind,
+                        tries: job.tries,
+                        error: errText(err),
+                        why: "the service did not say whether it took this one, and takes it twice without harm",
+                    });
+                    return;
+                }
+            }
             this.onSendFailed(job, run, err);
             if (job.kind === "finish" && run && job.runId)
                 this.summarize(job.runId, run);
@@ -1589,7 +1707,11 @@ export class RemoteRecorder {
             return;
         const end = this.beginProbe();
         this.request("GET", "/health", undefined, { timeoutMs: PROBE_TIMEOUT_MS, anonymous: true })
-            .catch(() => undefined)
+            // Still down: ask again at the end of the cool-down this failure started.
+            .catch(() => {
+            if (this.state === "recording")
+                this.idleProbe.arm();
+        })
             .finally(end);
     }
     /** Take the half-open slot. The returned function gives it back, once. */
@@ -1628,7 +1750,10 @@ export class RemoteRecorder {
      * - The breaker is closed: go at once.
      * - It is cooling down: sleep until it ends. A send that has waited
      *   {@link COOLDOWN_WAIT_MAX_MS} and still faces more than
-     *   {@link COOLDOWN_GRACE_MS} of it is given up (`giveUp`), unsent.
+     *   {@link COOLDOWN_GRACE_MS} of it is given up (`giveUp`), unsent — unless
+     *   `mayGiveUp` is false: a repeatable send ({@link REPEATABLE_TRIES}) is
+     *   bounded by its tries, each one paced by a cool-down, and a finish given
+     *   up after a minute's outage left a run that never ends.
      * - It is half-open: ONE lane takes the probe slot and goes (`endProbe`
      *   gives the slot back once its send settles); every other lane waits for
      *   that verdict. A success lets them go, each after its own short random
@@ -1637,7 +1762,7 @@ export class RemoteRecorder {
      * Before this, every lane with a queued send woke at the same moment and
      * sent into the dead service together, once per cool-down.
      */
-    async waitForService() {
+    async waitForService(mayGiveUp = true) {
         const started = Date.now();
         let waited = false;
         for (;;) {
@@ -1661,7 +1786,7 @@ export class RemoteRecorder {
             }
             const left = this.cooldownWaitMaxMs - (Date.now() - started);
             const cooling = (this.health.snapshot().openUntil ?? 0) - Date.now();
-            if (left <= 0 && cooling > Math.min(COOLDOWN_GRACE_MS, this.cooldownWaitMaxMs / 12))
+            if (mayGiveUp && left <= 0 && cooling > Math.min(COOLDOWN_GRACE_MS, this.cooldownWaitMaxMs / 12))
                 return { giveUp: true };
             // Past the bound, only a cool-down about to end is still waited out.
             await sleep(Math.min(Math.max(cooling, 25), left > 0 ? left : Number.POSITIVE_INFINITY, 5_000), true);
@@ -1962,12 +2087,15 @@ export class RemoteRecorder {
         const timeoutMs = serviceTimeoutMs();
         const signal = timeoutSignal(timeoutMs);
         const started = this.health.stamp();
+        // The session this spends: the answer is for it alone, and by the time it
+        // comes credentials.json may hold another, or none.
+        const spent = this.session;
         let res;
         try {
             res = await fetch(`${this.baseUrl}/auth/refresh`, {
                 method: "POST",
                 headers: { "content-type": "application/json", ...serviceHeaders() },
-                body: JSON.stringify({ refreshToken: this.session.refreshToken }),
+                body: JSON.stringify({ refreshToken: spent.refreshToken }),
                 signal,
             });
         }
@@ -2009,6 +2137,33 @@ export class RemoteRecorder {
             throw new ServiceError(`refresh failed: the answer was not a session${page ? " (a web page)" : ""} — nothing saved`);
         }
         this.health.ok(started);
+        // THE FILE MAY HAVE MOVED ON while the request was out: `bir logout`
+        // removed it, or somebody signed in. Adopting and saving the answer then
+        // signed the machine back in after the logout, or wrote over the new
+        // sign-in. So the file is read once more, and when it no longer holds the
+        // session this refresh spent, the file decides and the answer is dropped —
+        // the keeper's rule for its own refresh (control/recorder-keeper.ts,
+        // `not_ours`). A file that is there but cannot be read is no sign-in to
+        // protect: it is written over, as before.
+        if (this.follow) {
+            const onDisk = loadCredentials();
+            if (!onDisk && !existsSync(credentialsPath())) {
+                this.credMtime = -1;
+                this.pause("signed_out");
+                return;
+            }
+            if (onDisk && (onDisk.refreshToken !== spent.refreshToken || onDisk.user.id !== spent.user.id)) {
+                logDetail("auth.refresh_superseded", {
+                    why: "the sign-in in credentials.json changed while a refresh was out; what is there now decides",
+                });
+                // The credentials check takes it from here — now, whatever the file's
+                // timestamp says and however lately it was looked at.
+                this.credMtime = -1;
+                this.credCheckedAt = 0;
+                this.checkCredentials();
+                return;
+            }
+        }
         this.session = {
             accessToken: body.accessToken,
             refreshToken: body.refreshToken,
@@ -2112,6 +2267,7 @@ export class RemoteRecorder {
         if (this.state === state)
             return;
         this.state = state;
+        this.idleProbe.clear();
         let dropped = 0;
         for (const lane of this.lanes.values()) {
             const jobs = lane.jobs;

package/dist/record/truncate.js

@@ -159,7 +159,9 @@ export function truncateStrings(value, max, depth = 0) {
     if (value && typeof value === "object") {
         const out = {};
         for (const [k, v] of Object.entries(value)) {
-            out[k] = truncateStrings(v, max, depth + 1);
+            // Defined, not assigned: `out.__proto__ = …` sets the copy's prototype,
+            // and a tool's `__proto__` key was missing from the recorded step.
+            Object.defineProperty(out, k, { value: truncateStrings(v, max, depth + 1), enumerable: true, writable: true, configurable: true });
         }
         return out;
     }

package/dist/replay/bash-channel.d.ts

@@ -19,7 +19,13 @@
  */
 /** Up to this many characters the text rides inside the command, as a heredoc. */
 export declare const HEREDOC_MAX = 6000;
-/** Where delivered texts wait to be read. Under `BIR_HOME`, mode 0700. */
+/**
+ * Where delivered texts wait to be read. Under `BIR_HOME`, mode 0700.
+ *
+ * Absolute whatever `BIR_HOME` says: the path is handed to a Bash that runs in
+ * the session's folder, not this process's, and a relative one was not found
+ * there.
+ */
 export declare function deliveryDir(): string;
 /**
  * The command that prints `text`, or undefined when it could not be prepared —

package/dist/replay/bash-channel.js

@@ -19,15 +19,21 @@
  */
 import { randomUUID } from "node:crypto";
 import { readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { configDir, ensureDir } from "../control/paths.js";
 /** Up to this many characters the text rides inside the command, as a heredoc. */
 export const HEREDOC_MAX = 6_000;
 /** A delivered file is read once, at once; an hour is a generous margin. */
 const MAX_AGE_MS = 60 * 60_000;
-/** Where delivered texts wait to be read. Under `BIR_HOME`, mode 0700. */
+/**
+ * Where delivered texts wait to be read. Under `BIR_HOME`, mode 0700.
+ *
+ * Absolute whatever `BIR_HOME` says: the path is handed to a Bash that runs in
+ * the session's folder, not this process's, and a relative one was not found
+ * there.
+ */
 export function deliveryDir() {
-    return join(configDir(), "tmp");
+    return resolve(configDir(), "tmp");
 }
 /**
  * The command that prints `text`, or undefined when it could not be prepared —

package/dist/replay/builtins.d.ts

@@ -163,6 +163,20 @@ export declare function runBuiltin(toolName: string, input: Record<string, unkno
  * even be the WSL stub (a different filesystem view entirely). Resolved once.
  */
 export declare function bashExecutable(): string;
+/**
+ * The one short line bash is started with: read the script's file and `eval`
+ * it — as the host evals the command it is given. Run that way `$0`, the line
+ * numbers and the shell's own error text stay what they were when the script
+ * was the `-c` argument (`/usr/bin/bash: line 3: jq: command not found`); run
+ * as `bash <file>` every one of them would carry this file's name instead. A
+ * file that cannot be read is exit 126: evaluated without the check it is an
+ * empty script, which succeeds. And `unread`, a marker unique to the call, goes
+ * to stderr first: a command's own 126 (a file that is not executable) is a
+ * command that ran, and only the marker tells the two apart ({@link runBash}).
+ *
+ * Exported for the tests.
+ */
+export declare function readsScript(file: string, unread: string): string;
 /**
  * A glob pattern as a RegExp over `/`-separated relative paths: `**` crosses
  * directories, `*` and `?` stay inside one, `{a,b}` alternates, `[…]` passes