@vibe-commit/capture 0.9.0 → 0.11.0

package/dist/firing.js

@@ -0,0 +1,334 @@
+/**
+ * THE FIRING LOG AND THE HOOK'S LIVENESS STAMP — U3 of the detached uploader.
+ *
+ * A *firing* is one hook that ended a turn: today's hook body, deferred. The hook appends one line saying "this turn ended here, at this
+ * size, in this folder, with these repos" and returns; the upload worker (U5) replays the lines in order, each ALONE, with the values
+ * recorded at the moment the hook fired (plan §3.2-§3.4, D15). This module is the storage half and nothing in the hook calls it yet:
+ * it is inert until the hook is flipped (U6).
+ *
+ * ## What it owns
+ *  - `<sid>.firings.jsonl` — append-only, one `O_APPEND` write per line, no lock (hooks never wait).
+ *  - `<sid>.firings.cursor` — the worker's progress: a byte offset, and how many times the firing at that offset made the worker THROW.
+ *    Written atomically, and only by a holder of the session's writer lock.
+ *  - `<repo digest>/<sid>.live` — the hook-only liveness stamp, and the ONE function that reads liveness (`liveAtOf`).
+ *
+ * ## What a firing holds: paths and numbers only
+ * No credential, no transcript content. The worker re-confines `transcript` and `announced` with `admitsTranscript` before every read.
+ *
+ * ## ⛔ A LEAF MODULE. It imports `paths` and `atomic_write` and nothing else of this package's, because `spool.ts` and `state.ts` both
+ * read liveness through it and neither may import the other.
+ */
+import { appendFileSync, chmodSync, closeSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { writeFileAtomic } from "./atomic_write.js";
+import { sessionFileStem, sessionFiringsCursorPath, sessionFiringsPath, sessionLivePath, targetsDir } from "./paths.js";
+/** The line format this build writes and reads. A reader sees a NEWER `v` as a stop sign, never as garbage (§3.14). */
+export const FIRING_VERSION = 1;
+/** A line longer than this is not written: a firing is ~300 bytes, and one `O_APPEND` write of a small buffer is what keeps hooks lock-free. */
+export const MAX_FIRING_BYTES = 32 * 1024;
+/** After this many uncaught throws on one firing, the worker skips it. A firing only sets an EOF, so the next one still covers its bytes. */
+export const MAX_FIRING_THROWS = 3;
+/** More sub-agent files than this in one firing: the map is left out (uncapped) rather than growing the line past `MAX_FIRING_BYTES`. */
+export const MAX_FIRING_SUB_FILES = 200;
+// --- the log -------------------------------------------------------------------------------------------------------------------
+/**
+ * Append one firing. Returns false on any failure — a hook must never throw, and a missed firing self-heals: the NEXT firing's `eof`
+ * covers the same bytes.
+ *
+ * ⛔ ONE `O_APPEND` WRITE. Two hooks (Cursor double-fires) interleave whole lines, never halves, so no lock is needed. A line over
+ * `MAX_FIRING_BYTES` is refused rather than split.
+ */
+export function appendFiring(home, sessionId, firing) {
+    try {
+        const line = `${JSON.stringify(firing)}\n`;
+        if (Buffer.byteLength(line) > MAX_FIRING_BYTES)
+            return false;
+        const path = sessionFiringsPath(home, sessionId);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        appendFileSync(path, line, { mode: 0o600 });
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * What the hook calls: `appendFiring`, and if the line is refused while it carries a `sub` map, once more WITHOUT it (uncapped, the behaviour before
+ * the cap existed). The map is the one part of a line that grows with the session; the cap must never cost a firing. Never throws.
+ */
+export function recordFiring(home, sessionId, firing) {
+    if (appendFiring(home, sessionId, firing))
+        return true;
+    if (firing.sub === undefined)
+        return false;
+    const { sub: _dropped, ...withoutSub } = firing;
+    return appendFiring(home, sessionId, withoutSub);
+}
+/**
+ * The firings from `from` (a cursor offset) on. Never throws: an unreadable log reads as empty.
+ *
+ * A malformed COMPLETE line is skipped and counted in `through`. A trailing line with no newline is a hook mid-append and is left alone.
+ * A line of a newer `v` stops the read and is not consumed (`blockedByNewer`).
+ */
+export function readFirings(home, sessionId, from = 0) {
+    const empty = { firings: [], through: from, blockedByNewer: false };
+    let fd = null;
+    try {
+        fd = openSync(sessionFiringsPath(home, sessionId), "r");
+        const size = fstatSync(fd).size;
+        if (!Number.isSafeInteger(from) || from < 0 || from >= size)
+            return { ...empty, through: Math.min(Math.max(from, 0), size) };
+        const buf = Buffer.alloc(size - from);
+        let got = 0;
+        while (got < buf.length) {
+            const n = readSync(fd, buf, got, buf.length - got, from + got);
+            if (n <= 0)
+                break;
+            got += n;
+        }
+        const firings = [];
+        let through = from;
+        let start = 0;
+        for (let nl = buf.indexOf(0x0a, 0); nl !== -1 && nl < got; nl = buf.indexOf(0x0a, start)) {
+            const parsed = parseFiring(buf.subarray(start, nl).toString("utf8"), sessionFileStem(sessionId));
+            const lineStart = from + start;
+            const lineEnd = from + nl + 1;
+            if (parsed === "newer")
+                return { firings, through, blockedByNewer: true };
+            if (parsed !== null)
+                firings.push({ firing: parsed, start: lineStart, end: lineEnd });
+            through = lineEnd;
+            start = nl + 1;
+        }
+        return { firings, through, blockedByNewer: false };
+    }
+    catch {
+        return empty;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* nothing to do */
+            }
+        }
+    }
+}
+/** A valid firing, `"newer"` for a line of a version this build does not know, or null for anything else. */
+function parseFiring(text, stem) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const o = raw;
+    if (typeof o.v !== "number" || !Number.isInteger(o.v) || o.v < 1)
+        return null;
+    if (o.v > FIRING_VERSION)
+        return "newer";
+    const str = (x) => typeof x === "string" && x !== "";
+    if (typeof o.at !== "number" || !Number.isFinite(o.at) || o.at <= 0)
+        return null;
+    if (typeof o.eof !== "number" || !Number.isSafeInteger(o.eof) || o.eof < 0)
+        return null;
+    // `sid` must be THIS log's session: a line whose id sanitises to another file name could otherwise be replayed under another session's cursor,
+    // lock and ledger. It is deliberately NOT required to be header-safe HERE: `sid` goes on the wire as `x-session-id` and delivery refuses an id the
+    // wire cannot carry (`sessionIdSafe`, post.ts) as a LOUD write-off (`never`, a gap `status` counts). Dropping such a line at the parse would be a
+    // new, differently-silent no-op (the 182 ruling); the id never reaches a header, a file name or a lock path except through `sanitise`.
+    if (!str(o.sid) || o.sid.length > 512 || sessionFileStem(o.sid) !== stem)
+        return null;
+    if (!str(o.event) || !str(o.transcript) || !str(o.agent) || !str(o.id) || typeof o.cwd !== "string")
+        return null;
+    const prior = {};
+    if (o.prior !== undefined) {
+        if (o.prior === null || typeof o.prior !== "object" || Array.isArray(o.prior))
+            return null;
+        for (const [key, value] of Object.entries(o.prior)) {
+            if (value === null)
+                prior[key] = null;
+            else if (typeof value === "number" && Number.isFinite(value) && value > 0)
+                prior[key] = value;
+            else
+                return null;
+        }
+    }
+    let keys;
+    if (o.keys !== undefined) {
+        const k = o.keys;
+        if (k === null || typeof k !== "object" || !str(k.worktree) || !str(k.consent))
+            return null;
+        keys = { worktree: k.worktree, consent: k.consent };
+    }
+    if (o.slug !== undefined && !str(o.slug))
+        return null;
+    if (o.announced !== undefined && !str(o.announced))
+        return null;
+    // A `sub` map that is not exactly {key: non-negative integer} is IGNORED (the firing is uncapped, today's behaviour), never a reason to drop the firing.
+    let sub;
+    if (o.sub !== null && typeof o.sub === "object" && !Array.isArray(o.sub)) {
+        const entries = Object.entries(o.sub);
+        if (entries.length <= MAX_FIRING_SUB_FILES && entries.every(([, size]) => typeof size === "number" && Number.isSafeInteger(size) && size >= 0)) {
+            sub = Object.fromEntries(entries);
+        }
+    }
+    return {
+        v: o.v,
+        at: o.at,
+        sid: o.sid,
+        event: o.event,
+        eof: o.eof,
+        transcript: o.transcript,
+        cwd: o.cwd,
+        ...(keys === undefined ? {} : { keys }),
+        ...(o.slug === undefined ? {} : { slug: o.slug }),
+        agent: o.agent,
+        id: o.id,
+        prior,
+        ...(o.announced === undefined ? {} : { announced: o.announced }),
+        ...(sub === undefined ? {} : { sub }),
+    };
+}
+const LOG_SUFFIX = ".firings.jsonl";
+/**
+ * Every session that has a firing log: the file stems, oldest-modified first (so a session that has waited longest is served first). A
+ * stem is `sanitise(sid)`; it names the log and cursor files and nothing else, because the id to SEND is `Firing.sid`. Never throws.
+ */
+export function firingSessions(home) {
+    try {
+        const dir = targetsDir(home);
+        return readdirSync(dir)
+            .filter((name) => name.endsWith(LOG_SUFFIX) && name.length > LOG_SUFFIX.length)
+            .map((name) => ({ stem: name.slice(0, -LOG_SUFFIX.length), at: modifiedAt(`${dir}/${name}`) }))
+            .sort((a, b) => a.at - b.at || (a.stem < b.stem ? -1 : 1))
+            .map((entry) => entry.stem);
+    }
+    catch {
+        return [];
+    }
+}
+function modifiedAt(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Forget a session's firing log and cursor (with its target record, on the existing 30-day schedule). Never throws. */
+export function forgetFirings(home, sessionId) {
+    for (const path of [sessionFiringsPath(home, sessionId), sessionFiringsCursorPath(home, sessionId)]) {
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+            /* an undeletable file is retried next schedule */
+        }
+    }
+}
+export const START_OF_LOG = { offset: 0, throws: 0 };
+/**
+ * The cursor, or the start of the log when it is missing or unreadable. Starting over is SAFE: replaying a consumed firing is a no-op
+ * (`firing.eof <= sentOffset`, trap 1), just slower.
+ */
+export function readCursor(home, sessionId) {
+    try {
+        const raw = JSON.parse(readFileSync(sessionFiringsCursorPath(home, sessionId), "utf8"));
+        const offset = raw.offset;
+        const throws = raw.throws;
+        if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0)
+            return START_OF_LOG;
+        return { offset, throws: typeof throws === "number" && Number.isSafeInteger(throws) && throws > 0 ? throws : 0 };
+    }
+    catch {
+        return START_OF_LOG;
+    }
+}
+/**
+ * Persist the cursor atomically. ⛔ ONLY A HOLDER OF THE SESSION'S WRITER LOCK may call this, and only after a heartbeat that said the
+ * lock is still its own (§3.3: "every cursor write beats first"); a worker that lost its lock writes nothing. Returns false on failure.
+ */
+export function writeCursor(home, sessionId, cursor) {
+    try {
+        const path = sessionFiringsCursorPath(home, sessionId);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileAtomic(path, `${JSON.stringify({ v: 1, offset: cursor.offset, throws: cursor.throws })}\n`, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Move the cursor to `offset`; the throw count belongs to the firing it left, so it resets. */
+export const advanced = (cursor, offset) => ({ offset: Math.max(cursor.offset, offset), throws: 0 });
+/** The firing at the cursor made the worker throw once more. */
+export const threw = (cursor) => ({ offset: cursor.offset, throws: cursor.throws + 1 });
+/** Skip the firing at the cursor: it has thrown `MAX_FIRING_THROWS` times. */
+export const shouldSkip = (cursor) => cursor.throws >= MAX_FIRING_THROWS;
+// --- liveness ------------------------------------------------------------------------------------------------------------------
+/**
+ * Stamp "this session's hook ran at `atMs`" for one repo key. HOOK-ONLY: the worker runs `deliver` with `byHook: false` and never calls
+ * this. A JSON object (`{at}`) rather than a bare number so P2's T7 can add `transcript` without a format change; the reader ignores
+ * unknown fields. Atomic replace. Never throws; false on failure (the commit then falls to the cold rung or goes unrecorded, as today
+ * before a first hook).
+ */
+export function stampLive(home, key, atMs) {
+    const path = sessionLivePath(home, key);
+    if (path === null || !Number.isFinite(atMs) || atMs <= 0)
+        return false;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileAtomic(path, `${JSON.stringify({ at: atMs })}\n`, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The `.live` stamp at `path`, or null when absent, unreadable or not a positive number. Unknown fields are ignored. */
+export function readLiveFile(path) {
+    try {
+        const at = JSON.parse(readFileSync(path, "utf8")).at;
+        return typeof at === "number" && Number.isFinite(at) && at > 0 ? at : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ⛔ THE ONE LIVENESS READER (§3.5). A session is live as of the LATER of its state file's `liveAt` (stamped by `deliver()` for a hook
+ * delivery) and its `.live` file (stamped by the hook itself, before the worker has delivered anything). All three readers go through
+ * this: `liveSessions` and `pendingModeFor` (`spool.ts`) and the two `status` classifiers (`state.ts`). Read straight from the files,
+ * never from the mtime: a `finalize` that rewrites a dead session's state must not make it live (VG review 2, D2).
+ */
+export function liveAtOf(stateLiveAt, livePath) {
+    const stamped = livePath === null ? null : readLiveFile(livePath);
+    if (stamped === null)
+        return stateLiveAt;
+    return stateLiveAt === null ? stamped : Math.max(stateLiveAt, stamped);
+}
+/**
+ * Which repo keys a hook stamps `.live` for (§3.5).
+ *  - the turn-end repo, when allowed;
+ *  - for a dialect that ISOLATES its content records (Claude Code, Codex): also every ledger key in the session's target record;
+ *  - for one that does not (Cursor): the turn-end repo ONLY. Sticky targets stay in Cursor's record but are not delivered, and only
+ *    delivered targets stamp today. Stamping them would keep a repo Cursor has left live for 30 minutes past every turn, a human's commit
+ *    there would become `sole_live_session`, and the row is permanent.
+ */
+export function liveStampKeys(input) {
+    const keys = new Set();
+    if (input.turnEnd !== null && input.turnEnd !== "")
+        keys.add(input.turnEnd);
+    if (input.isolates)
+        for (const key of input.recordLedgerKeys)
+            if (key !== "")
+                keys.add(key);
+    return [...keys];
+}
+//# sourceMappingURL=firing.js.map

package/dist/firing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firing.js","sourceRoot":"","sources":["../src/firing.ts"],"names":[],"mappings":"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"}

package/dist/hooks/entry.d.ts

@@ -36,11 +36,12 @@
 import { type IngestCredential } from "../credential.js";
 import { type Delivery, type FileKey } from "../post.js";
 import { type RecordCutter } from "../policy.js";
-import { type Isolation } from "../session_targets.js";
+import { type Isolation, type Resolution, type Target } from "../session_targets.js";
 import type { HookEventName } from "../agents/types.js";
+import { type PriorLiveness } from "../firing.js";
 import { type SessionKey } from "../paths.js";
 export { confinementRoots } from "../project.js";
-import { turnStart, type TurnStart } from "../pending_bound.js";
+import { turnStart, type PendingMode, type TurnStart } from "../pending_bound.js";
 /**
  * Default wall-clock budget. `CR-028` sets the real per-event `timeout` in
  * `claude-plugin/hooks/hooks.json`; this is the client-side backstop, which must
@@ -62,30 +63,6 @@ export declare const DEFAULT_HOOK_BUDGET_MS = 5000;
 export declare function sendTimeoutMs(budgetMs: number, consumedMs: number): number;
 /** A promise that resolves after `ms`. The one clock the settle path needs. */
 export declare function wait(ms: number): Promise<void>;
-/**
- * The budget the SENDS may spend — the whole budget, less the stamp's share.
- *
- * A function, and exported, for the reason `sendTimeoutMs` is: the carve-out is
- * the thing this task changes, and a wall-clock test cannot pin it. Every
- * discriminator that distinguishes reserve from no-reserve through a real
- * process turned out to slide with per-send overhead — a 149 ms window that
- * moves by 25 ms for every 10 ms of connect-and-compress cost — so pinning it
- * there would be tuning a constant to one machine. Here it is arithmetic.
- *
- * ⛔ `budgetMs` itself still governs the SETTLE and the WATCHDOG. Only the sends
- * are carved.
- */
-/**
- * ⛔ **TAKES THE RESOLVED EVENT, NEVER THE RAW `hook_event_name` (`CR-195`).**
- *
- * It used to take a `string`, and that is precisely how Cursor's `sessionEnd`
- * bought a full-budget send with no reserve: the comparison was against
- * `"SessionEnd"`, so an unrecognised spelling was `false` rather than an error.
- * `HookEventName | null` makes the resolution a thing the CALLER must already
- * have done — `null` is the honest "none of the three", and an unresolved wire
- * string is no longer expressible here at all.
- */
-export declare function sendBudgetMs(budgetMs: number, event: HookEventName | null, sinceHookStartMs?: number): number;
 export interface HookInput {
     readonly sessionId: string;
     readonly transcriptPath: string;
@@ -205,6 +182,139 @@ export declare function runHook(ctx: HookEnvironment): Promise<never>;
  * `VIBECOMMIT_HOOK_TIMEOUT_MS` still wins outright, as it always has.
  */
 export declare function hookBudgetMs(env: NodeJS.ProcessEnv, agentId: string): number;
+/**
+ * U4 — HOW A DELIVERY IS PACED. A HOOK has a wall clock: one shared deadline, every request's timeout trimmed to what is left, a floor
+ * under the budget below which a further file is not started. The UPLOAD WORKER has none, and ⛔ must not be given an infinite one:
+ * `setTimeout(Infinity)` fires at 1 ms (trap 4), and any deadline at all brings back the abandonment this build removes (`withinBudget`
+ * trims the timeout near the end of a round, the client aborts, the server applies). So it passes a FIXED request timeout and no deadline.
+ */
+export type Pace = {
+    readonly kind: "hook";
+    readonly settleStart: number;
+    readonly sendBudget: number;
+    readonly consumedMs: number;
+} | {
+    readonly kind: "unbounded";
+    readonly timeoutMs: number;
+};
+/**
+ * U4 — THE INPUTS A REPLAY FIXES AT THE MOMENT THE HOOK FIRED (plan §3.4). Absent for the inline hook, `finalize`, `backfill` and the drain,
+ * which are "now" and read the whole spool.
+ */
+export interface ReplayAsOf {
+    /** `firing.at`: the clock for promotion and pending mode, and the commit pin. */
+    readonly at: number;
+    /** `firing.prior`: liveness as the hook read it BEFORE it stamped (`firing.ts`), keyed by ledger key. */
+    readonly prior: PriorLiveness;
+    /** U6b (F5): `firing.sub`, the ceiling per sub-agent file. Left out when the firing has none or is a settled `SessionEnd` (real sizes). */
+    readonly subCap?: Readonly<Record<string, number>>;
+}
+/**
+ * U4 — WHAT HAPPENED TO ONE TARGET, in the terms the worker's cursor needs. `Delivery.kind` alone cannot say: `nothing-to-send` is also a lost
+ * lock, a failed read and an unterminated record, and `ok` can be one delta of several. Derived from the delivery AND the ledger (plan §3.3).
+ */
+export type TargetReason = 
+/** `sentOffset >= eof`: this firing's main bytes are delivered (or were already). */
+{
+    readonly kind: "caught-up";
+}
+/** A RECORDED state keeps the bytes owed; they ride this target's next delivery, and it never holds back another target. */
+ | {
+    readonly kind: "held";
+    readonly why: "capture-not-approved" | "stopped" | "unterminated" | "folder-forbidden";
+}
+/** The server refused these bytes for good; they were advanced past and counted. */
+ | {
+    readonly kind: "never";
+}
+/** A `later` with NO recorded state (a timeout, a 5xx): the bytes are still owed and the worker backs off. */
+ | {
+    readonly kind: "later";
+}
+/** Credential-level: the worker stops. */
+ | {
+    readonly kind: "fatal";
+}
+/** The caller's lock heartbeat failed: nothing was written, and nothing may be called done. */
+ | {
+    readonly kind: "lock-lost";
+}
+/** The span could not be read, or the ledger could not be written: retried, and counted toward the throw limit. */
+ | {
+    readonly kind: "not-progressed";
+    readonly why: "read-failed" | "unwritable";
+}
+/** Sent, but `sentOffset < eof` still: more owed, call again. */
+ | {
+    readonly kind: "more-owed";
+};
+/** What delivering one target produced. */
+export interface TargetResult {
+    readonly target: Target;
+    readonly delivery: Delivery;
+    readonly subagents: DelegatedDeliveries;
+    /** The server refused THIS target for good (C3): nothing else about the firing changes. */
+    readonly stopped: boolean;
+    /** U4: see `TargetReason`. */
+    readonly reason: TargetReason;
+}
+/** Pure. The reason for one target from its delivery and where its main ledger stands against the `eof` it was asked to reach. */
+export declare function targetReason(delivery: Delivery, sentOffset: number, eof: number, stopped: boolean): TargetReason;
+/**
+ * U4 — DELIVER ONE FIRING TO ITS RESOLVED TARGETS. The loop `hookBody` always ran inline, callable by the upload worker with a replay's
+ * as-of inputs and no wall clock. Behaviour for the inline hook is unchanged: `pace.kind === "hook"` and no `asOf` is the old code.
+ *
+ * Order and fairness are as before: least-recently-sent target first, so a 20 MB backlog on one cannot starve the rest.
+ */
+export declare function deliverFiring(opts: {
+    ctx: HookEnvironment;
+    input: HookInput;
+    url: string;
+    credential: IngestCredential;
+    resolution: Resolution;
+    eof: number;
+    event: HookEventName | null;
+    isSessionEnd: boolean;
+    pace: Pace;
+    asOf?: ReplayAsOf;
+    /**
+     * U5: the caller's session-lock heartbeat. Called before a target is touched and before every request and write beneath it (`beforeRequest`,
+     * U1). `false` means the lock is no longer ours: nothing more is written, and that target reports `lock-lost`. The inline hook passes none.
+     */
+    heartbeat?: () => boolean;
+}): Promise<TargetResult[]>;
+/**
+ * U4 — `pendingModeFor`, answered from `firing.prior` (plan §3.4, P2 point 4). `prior` keeps `pendingModeFor`'s three outcomes:
+ *  - a NUMBER is the stamp the hook read before it stamped: live within the window of `firing.at` is `first-turn`, older is `stale-own`;
+ *  - an explicit `null` is a state file with NO `liveAt` (what `finalize` and `backfill` leave): `stale-own`;
+ *  - an ABSENT key is no state file at hook time: `first-turn`. A key the hook did not record at all (a second work tree, a parent-folder
+ *    repo on its first firing) falls back to `pendingModeFor` judged at `firing.at`, never `Date.now()`, which is safe because stamps arrive in
+ *    firing order.
+ * A plain number-or-omitted map would read a resumed session as `first-turn` and keep a lingering-id line.
+ */
+export declare function modeFromPrior(home: string, key: SessionKey, asOf: ReplayAsOf): PendingMode;
+/**
+ * U6b (F2d): THE WORKER'S PACE BETWEEN REQUESTS (D9): sleep `max(250 ms, the request's own elapsed)`, capped at 30 s. It lives here, beside the delivery loops
+ * that must honour it, because ONE worker step can put several requests on the wire (the main delta, then one per sub-agent file) and pacing only
+ * after the whole step let a fast server take thirteen of them back to back.
+ */
+export declare const UNBOUNDED_PACE_FLOOR_MS = 250;
+export declare const UNBOUNDED_PACE_CAP_MS = 30000;
+export declare function unboundedPaceMs(elapsedMs: number): number;
+/** A session with no firing of its own for this long is IDLE: another session's firing may finish its owed bytes (R19 · D22). */
+export declare const DRAIN_IDLE_MS: number;
+/** Session records one firing looks at. Examined ones move to the back of the line (their mtime moves), so none starves. */
+export declare const DRAIN_EXAMINE_MAX = 40;
+/** A record whose transcript is gone and that owes nothing is forgotten after this long. */
+export declare const DRAIN_FORGET_MS: number;
+/**
+ * An owed target whose transcript is GONE (Claude Code deletes transcripts ~30 days on) can never be sent: its hold becomes the
+ * honest gap now (R19 · D22), and the hold is cleared. Whatever was already delivered is untouched.
+ */
+export declare function writeOffOwed(home: string, record: {
+    readonly sessionId: string;
+    readonly targets: readonly Target[];
+}, nowMs: number): void;
 /** One sub-agent transcript that passed confinement and the key bound. */
 interface SubagentFile {
     readonly path: string;
@@ -276,8 +386,23 @@ export declare function deliverSubagents(opts: {
      * bytes this target was never allowed to send. Absent for a repo target: it sends to each file's end, as it always did.
      */
     sizeCap?: Readonly<Record<string, number>>;
+    /**
+     * U6b (F5): a REPLAYED firing's ceiling per sub-agent file, `Firing.sub` (what existed when the hook ran). Combined with `sizeCap` by `min`; a file
+     * with no key sends nothing. Absent for a hook, the drain, `finalize` and `backfill` (they read the real size), and for a settled `SessionEnd`.
+     */
+    firingCap?: Readonly<Record<string, number>>;
     /** A-T4: what the delegated streams may contain (R17 / R6). Default: a repo target's own `redactionRoots`. */
     isolation?: Isolation;
+    /** U4: the upload worker's stamp (`DeliveryContext.liveAtMs`); requires `byHook: false`. */
+    liveAtMs?: number;
+    /**
+     * U4 — **THE WORKER'S PACE**: a fixed request timeout and NO budget. When set, `startedAt`/`sendBudget` are ignored: no remainder arithmetic,
+     * no floor under which a further file is skipped, no `deadlineAtMs`, and no cap of `MAX_SUBAGENT_FILES` per firing (it loops until none is
+     * owed). Never `Infinity`: `setTimeout(Infinity)` fires at 1 ms (trap 4).
+     */
+    unboundedTimeoutMs?: number;
+    /** U6b (F2d): in an unbounded step, wait this long before the FIRST request (the main delta just went); each later one waits `unboundedPaceMs` of the previous request. */
+    pauseFirstMs?: number;
     /**
      * C25: the caller's session-lock heartbeat (`finalize`, `backfill`). Called before each delegated file and before every request
      * inside it; `false` means the lock is gone, and the loop stops with nothing more written. A hook passes none.
@@ -302,6 +427,26 @@ export interface DelegatedDeliveries {
      */
     readonly deliveries: readonly Delivery[];
 }
+/**
+ * Every `agent-*.jsonl` under this session's `subagents/`, oldest first.
+ *
+ * **`agent-*.jsonl`, never `agent-*`.** The directory carries an
+ * `agent-<id>.meta.json` beside every transcript — 636 of each on this machine,
+ * exactly 1:1 — so the looser glob would double every upload and send metadata
+ * as transcript content.
+ *
+ * **Every path is confined.** `isInsideAny(transcriptRoots(...))` gates each
+ * entry before it is opened, exactly as the main transcript is gated: this adds
+ * a new SET of readers to the surface `/cso` finding 1 rated HIGH, and a
+ * symlinked entry in `subagents/` must not walk out of the transcript roots.
+ *
+ * Oldest first, because it cannot starve. Ordering by pending bytes would let a
+ * small file lose every round forever; by mtime, every file reaches the front.
+ *
+ * A missing or unreadable directory is simply "no sub-agents" — silent, per the
+ * hook contract.
+ */
+export declare function findSubagentFiles(ctx: HookEnvironment, transcriptPath: string): SubagentFile[];
 /** Size in bytes, or null if it cannot be read. */
 export declare function fileSize(path: string): number | null;
 /**