@vibe-commit/capture 0.9.0 → 0.11.0

package/dist/drain.d.ts

@@ -0,0 +1,68 @@
+/**
+ * THE IDLE-SESSION DRAIN, WORKER SIDE — U5c of the detached uploader (plan §3.9 "Idle drain cap", §3.3 fairness).
+ *
+ * A session whose last firing ran with bytes still behind (a multi-repo session at `SessionEnd`, a repo found late in a long one) has no
+ * next hook of its own. The hook used to finish such sessions with the leftover of its one deadline (`drainIdleSessions`, `entry.ts`); U6
+ * removes that from the hook, and this is where it lives. The worker calls `drainIdleStep` when it has no live firing to serve, so
+ * **live firings always outrank the drain** and the queue is looked at again between deltas.
+ *
+ * ## What a step is
+ * ONE delta for the first idle session that has something to send, under THAT session's writer lock (never waited for: a busy session is
+ * skipped), consent re-checked by the resolver, discovery continued (`resolveTargets` with `drain: true`: ≤8 MiB and ≤8 roots per call).
+ *
+ * ## What bounds it
+ *  - **64 MiB per worker life** (`DRAIN_CAP_BYTES`, plan §3.9, a starting value, unmeasured). Without a deadline the drain would otherwise
+ *    send every idle session's backlog on the worker's first run and flood the shared-cpu VM. U8 measures the Stop-to-`capture_turns` lag.
+ *  - Sessions are served OLDEST first and a session that cannot be acted on moves to the back of the line (`rotate`), so forty unactionable
+ *    records at the front cannot starve a live owed session behind them (C18 #7).
+ *  - Only sessions idle for 10 minutes (`DRAIN_IDLE_MS`) and with NO unconsumed firing: a session with a firing waiting is a live session.
+ *
+ * ## ⛔ Identity (plan §3.13): "a worker serves only firings of its own identity, in the idle drain as well"
+ * The target record names no credential, so the identity is read from the session's firing log: the last firing's `id` must be ours. A
+ * session with NO firing log is a LEGACY one (recorded by a hook before U6) and is served only by a worker using the saved credential
+ * (`VIBECOMMIT_TOKEN` unset), which is the credential those hooks used unless the user said otherwise. A worker running on an environment
+ * token never drains a session it cannot prove is its own.
+ *
+ * ## ⛔ A drain delivery is not a hook's: it stamps NO liveness (`byHook: false`, no `liveAtMs`). The old hook drain stamped "now" on
+ * every idle session it touched, which kept a finished session live for a window it did not earn; that was a defect and is not carried.
+ */
+import { type ReplayConfig } from "./replay.js";
+/** Bytes the drain may send in one worker's life (plan §3.9). */
+export declare const DRAIN_CAP_BYTES: number;
+export interface DrainState {
+    /** Bytes sent by the drain so far in this worker's life. */
+    bytes: number;
+}
+export type DrainStep = 
+/** Nothing idle has anything to send (or the cap is spent): the worker may go idle. */
+{
+    readonly kind: "idle";
+}
+/** One delta went. `bytes` is how much it moved the ledgers by. */
+ | {
+    readonly kind: "delivered";
+    readonly bytes: number;
+    readonly elapsedMs: number;
+}
+/** A timeout or 5xx with no recorded state: the session is retried later. */
+ | {
+    readonly kind: "later";
+    readonly session: string;
+    readonly elapsedMs: number;
+    readonly retryAfterMs?: number;
+}
+/**
+ * U6b (F2a): a request WAS made and nothing moved and nothing failed: the server HELD the session (a 403 `capture_not_approved`). Returned like `delivered`
+ * and `later`: ONE request per step, however many held sessions are in line. The worker backs the whole drain off after it.
+ */
+ | {
+    readonly kind: "held";
+    readonly session: string;
+    readonly elapsedMs: number;
+}
+/** The server rejected the credential. The worker stops. */
+ | {
+    readonly kind: "fatal";
+    readonly elapsedMs: number;
+};
+export declare function drainIdleStep(cfg: ReplayConfig, state: DrainState, nowMs?: () => number): Promise<DrainStep>;

package/dist/drain.js

@@ -0,0 +1,234 @@
+/**
+ * THE IDLE-SESSION DRAIN, WORKER SIDE — U5c of the detached uploader (plan §3.9 "Idle drain cap", §3.3 fairness).
+ *
+ * A session whose last firing ran with bytes still behind (a multi-repo session at `SessionEnd`, a repo found late in a long one) has no
+ * next hook of its own. The hook used to finish such sessions with the leftover of its one deadline (`drainIdleSessions`, `entry.ts`); U6
+ * removes that from the hook, and this is where it lives. The worker calls `drainIdleStep` when it has no live firing to serve, so
+ * **live firings always outrank the drain** and the queue is looked at again between deltas.
+ *
+ * ## What a step is
+ * ONE delta for the first idle session that has something to send, under THAT session's writer lock (never waited for: a busy session is
+ * skipped), consent re-checked by the resolver, discovery continued (`resolveTargets` with `drain: true`: ≤8 MiB and ≤8 roots per call).
+ *
+ * ## What bounds it
+ *  - **64 MiB per worker life** (`DRAIN_CAP_BYTES`, plan §3.9, a starting value, unmeasured). Without a deadline the drain would otherwise
+ *    send every idle session's backlog on the worker's first run and flood the shared-cpu VM. U8 measures the Stop-to-`capture_turns` lag.
+ *  - Sessions are served OLDEST first and a session that cannot be acted on moves to the back of the line (`rotate`), so forty unactionable
+ *    records at the front cannot starve a live owed session behind them (C18 #7).
+ *  - Only sessions idle for 10 minutes (`DRAIN_IDLE_MS`) and with NO unconsumed firing: a session with a firing waiting is a live session.
+ *
+ * ## ⛔ Identity (plan §3.13): "a worker serves only firings of its own identity, in the idle drain as well"
+ * The target record names no credential, so the identity is read from the session's firing log: the last firing's `id` must be ours. A
+ * session with NO firing log is a LEGACY one (recorded by a hook before U6) and is served only by a worker using the saved credential
+ * (`VIBECOMMIT_TOKEN` unset), which is the credential those hooks used unless the user said otherwise. A worker running on an environment
+ * token never drains a session it cannot prove is its own.
+ *
+ * ## ⛔ A drain delivery is not a hook's: it stamps NO liveness (`byHook: false`, no `liveAtMs`). The old hook drain stamped "now" on
+ * every idle session it touched, which kept a finished session live for a window it did not earn; that was a defect and is not carried.
+ */
+import { existsSync, rmSync, utimesSync } from "node:fs";
+import { admitsTranscript } from "./agents/registry.js";
+import { loadCredential } from "./credential.js";
+import { forgetFirings, readCursor, readFirings } from "./firing.js";
+import { CAPTURE_NOT_APPROVED } from "./post.js";
+import { DRAIN_EXAMINE_MAX, DRAIN_FORGET_MS, DRAIN_IDLE_MS, deliverFiring, fileSize, findSubagentFiles, wait, writeOffOwed, } from "./hooks/entry.js";
+import { claimSessionWriter } from "./hooks/fire_lock.js";
+import { sessionFileStem } from "./paths.js";
+import { REQUEST_TIMEOUT_MS, SESSION_BEAT_MS, SESSION_LOCK_STALE_MS } from "./replay.js";
+import { dialectIsolates, listTargetRecords, resolveTargets, stopKeyOf, LockLostError } from "./session_targets.js";
+import { fileState, loadSessionState, pruneDeliveredEndHold } from "./state.js";
+/** Bytes the drain may send in one worker's life (plan §3.9). */
+export const DRAIN_CAP_BYTES = 64 * 1024 * 1024;
+/** Total bytes acknowledged across a session's ledgers: the measure of what a step moved. */
+function sentBytes(cfg, targets, sessionId, subFiles) {
+    let total = 0;
+    for (const target of targets) {
+        const state = loadSessionState(cfg.home, { repoKey: target.ledgerKey, sessionId });
+        total += fileState(state, "main").sentOffset;
+        for (const file of subFiles)
+            total += fileState(state, file.fileKey).sentOffset;
+    }
+    return total;
+}
+/** Does this session owe a firing, of any identity? Then it is live work, not idle work. */
+function hasFiring(cfg, sessionId) {
+    const stem = sessionFileStem(sessionId);
+    return readFirings(cfg.home, stem, readCursor(cfg.home, stem).offset).firings.length > 0;
+}
+/** May THIS worker's credential serve this session? See the module doc. */
+function ours(cfg, sessionId) {
+    const stem = sessionFileStem(sessionId);
+    const last = readFirings(cfg.home, stem, 0).firings.at(-1)?.firing;
+    if (last !== undefined)
+        return last.id === cfg.identity;
+    const token = cfg.env.VIBECOMMIT_TOKEN?.trim() ?? "";
+    return token === "";
+}
+export async function drainIdleStep(cfg, state, nowMs = Date.now) {
+    if (state.bytes >= DRAIN_CAP_BYTES)
+        return { kind: "idle" };
+    const candidates = listTargetRecords(cfg.home)
+        .sort((a, b) => a.mtimeMs - b.mtimeMs)
+        .slice(0, DRAIN_EXAMINE_MAX);
+    for (const { path, record } of candidates) {
+        const now = nowMs();
+        if (now - record.firedAt < DRAIN_IDLE_MS)
+            continue;
+        if (hasFiring(cfg, record.sessionId))
+            continue;
+        const rotate = () => {
+            try {
+                utimesSync(path, new Date(), new Date());
+            }
+            catch {
+                // Ordering only.
+            }
+        };
+        const forgetIfOld = () => {
+            if (now - record.firedAt > DRAIN_FORGET_MS) {
+                try {
+                    rmSync(path);
+                    forgetFirings(cfg.home, record.sessionId);
+                }
+                catch {
+                    // A record we could not delete is just examined again.
+                }
+            }
+            else {
+                rotate();
+            }
+        };
+        if (record.transcriptPath === null) {
+            rotate();
+            continue;
+        }
+        const transcript = record.transcriptPath;
+        if (!ours(cfg, record.sessionId)) {
+            rotate();
+            continue;
+        }
+        // C28: a dialect that cannot isolate is never owed; it delivers only the repo each turn ends in, on that turn's own firing.
+        if (!dialectIsolates(cfg.home, cfg.env, transcript)) {
+            forgetIfOld();
+            continue;
+        }
+        // Confinement again (`/cso` finding 1): this path was read from a record, and it reaches a read whose result is uploaded.
+        if (existsSync(transcript) && !admitsTranscript(cfg.home, cfg.env, transcript)) {
+            rotate();
+            continue;
+        }
+        // `agentId` is a placeholder: the drain also serves Codex and Cursor sessions, and delivery takes the dialect and the scrubber from the
+        // transcript path, not from this field (the hook drain this replaces used whichever hook happened to be running).
+        const ctx = { env: cfg.env, home: cfg.home, nodeVersion: cfg.nodeVersion, agentId: "claude-code", readStdin: () => Promise.resolve("") };
+        const size = fileSize(transcript);
+        if (size === null) {
+            // The transcript is gone: what is owed becomes a gap now (`writeOffOwed`), a write, so under the session's lock, never waited for.
+            const writeOff = await claimSessionWriter(cfg.home, record.sessionId, { staleAfterMs: SESSION_LOCK_STALE_MS, deadlineAtMs: 0, wait });
+            if (writeOff === null) {
+                rotate();
+                continue;
+            }
+            try {
+                writeOffOwed(cfg.home, record, now);
+            }
+            finally {
+                writeOff.release();
+            }
+            forgetIfOld();
+            continue;
+        }
+        const live = record.targets.filter((target) => record.stopped[stopKeyOf(target)] === undefined);
+        const subFiles = findSubagentFiles(ctx, transcript);
+        const behind = live.some((target) => {
+            const ledger = loadSessionState(cfg.home, { repoKey: target.ledgerKey, sessionId: record.sessionId });
+            return (ledger.endHold !== null ||
+                fileState(ledger, "main").sentOffset < size ||
+                subFiles.some((file) => fileState(ledger, file.fileKey).sentOffset < file.size));
+        });
+        if (!behind && record.settled) {
+            rotate();
+            continue;
+        }
+        const claim = await claimSessionWriter(cfg.home, record.sessionId, { staleAfterMs: SESSION_LOCK_STALE_MS, deadlineAtMs: 0, wait });
+        if (claim === null) {
+            rotate();
+            continue;
+        }
+        const startedAt = nowMs();
+        // The lock goes stale in four beats, not in a request timeout: a timer keeps it alive through a long request (as `replayStep`'s does).
+        const beat = setInterval(() => claim.refresh(), SESSION_BEAT_MS);
+        beat.unref();
+        try {
+            const load = loadCredential({ env: cfg.env, home: cfg.home });
+            if (load.kind !== "ok")
+                return { kind: "fatal", elapsedMs: 0 };
+            const heartbeat = () => claim.refresh();
+            let resolution;
+            try {
+                resolution = resolveTargets({
+                    home: cfg.home,
+                    env: cfg.env,
+                    sessionId: record.sessionId,
+                    transcriptPath: transcript,
+                    turnEndCwd: null,
+                    mode: "turn",
+                    nowMs: nowMs(),
+                    drain: true,
+                    heartbeat,
+                });
+            }
+            catch (error) {
+                if (error instanceof LockLostError)
+                    continue;
+                throw error;
+            }
+            if (resolution.targets.length === 0) {
+                rotate();
+                continue;
+            }
+            const input = { sessionId: record.sessionId, transcriptPath: transcript, cwd: "", eventName: "Stop" };
+            const subs = findSubagentFiles(ctx, transcript);
+            const before = sentBytes(cfg, resolution.targets, record.sessionId, subs);
+            const results = await deliverFiring({
+                ctx,
+                input,
+                url: cfg.url,
+                credential: load.credential,
+                resolution,
+                eof: size,
+                event: null,
+                isSessionEnd: false,
+                pace: { kind: "unbounded", timeoutMs: cfg.requestTimeoutMs ?? REQUEST_TIMEOUT_MS },
+                heartbeat,
+            });
+            for (const target of resolution.targets)
+                pruneDeliveredEndHold(cfg.home, { repoKey: target.ledgerKey, sessionId: record.sessionId });
+            const moved = Math.max(0, sentBytes(cfg, resolution.targets, record.sessionId, subs) - before);
+            state.bytes += moved;
+            const deliveries = results.flatMap((r) => [r.delivery, ...r.subagents.deliveries]);
+            if (results.some((r) => r.reason.kind === "fatal") || deliveries.some((d) => d.kind === "attempted" && d.disposition === "fatal")) {
+                return { kind: "fatal", elapsedMs: nowMs() - startedAt };
+            }
+            if (results.some((r) => r.reason.kind === "later") || deliveries.some((d) => d.kind === "attempted" && d.disposition === "later" && d.detail?.code !== CAPTURE_NOT_APPROVED)) {
+                // To the back of the line: a session that keeps failing must not stand in front of the ones behind it.
+                rotate();
+                const waits = deliveries.flatMap((d) => (d.kind === "attempted" && d.disposition === "later" && d.retryAfterMs !== undefined ? [d.retryAfterMs] : []));
+                return { kind: "later", session: record.sessionId, elapsedMs: nowMs() - startedAt, ...(waits.length === 0 ? {} : { retryAfterMs: Math.max(...waits) }) };
+            }
+            if (moved > 0)
+                return { kind: "delivered", bytes: moved, elapsedMs: nowMs() - startedAt };
+            // Nothing moved and nothing failed. If a request WAS made, the server held this session (403 capture_not_approved): rotate it to the back
+            // and RETURN, so one step is one request (F2a: the old loop went on to the next held session inside the same step, up to
+            // DRAIN_EXAMINE_MAX back-to-back requests, re-sent on every worker life). If nothing was sent at all, move on without cost.
+            rotate();
+            if (deliveries.some((d) => d.kind === "attempted"))
+                return { kind: "held", session: record.sessionId, elapsedMs: nowMs() - startedAt };
+        }
+        finally {
+            clearInterval(beat);
+            claim.release();
+        }
+    }
+    return { kind: "idle" };
+}
+//# sourceMappingURL=drain.js.map

package/dist/drain.js.map

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

package/dist/firing.d.ts

@@ -0,0 +1,169 @@
+/**
+ * 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 { type SessionKey } 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 declare 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 declare const MAX_FIRING_BYTES: number;
+/** 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 declare const MAX_FIRING_THROWS = 3;
+/**
+ * Per repo key: the liveness the hook read BEFORE it stamped (plan §3.4, P2 point 4). Stamping first would flip `stale-own` to `first-turn`.
+ *  - a number: the stamp (`SessionState.liveAt`, or the `.live` file, whichever is later).
+ *  - `null`: a state file exists with NO `liveAt` (what `finalize` and `backfill` leave). Reads as `stale-own`.
+ *  - key ABSENT: no state file at all. Reads as `first-turn`.
+ * A plain number-or-omitted map would read a resumed session as `first-turn` and keep a lingering-id line.
+ */
+export type PriorLiveness = Readonly<Record<string, number | null>>;
+export interface Firing {
+    readonly v: number;
+    /** The hook's own clock, epoch ms: "the moment its hook runs". Promotion, pending mode and the commit pin are all judged as of it. */
+    readonly at: number;
+    /**
+     * The session id as the agent named it. The log's FILE NAME is `sanitise(sid)` (capped at 128 characters), which loses characters the
+     * wire id keeps, so the worker takes the id to send from here and never from a file name.
+     */
+    readonly sid: string;
+    /** `Stop`, `PreCompact`, `SessionEnd`, ... as the dialect named it. */
+    readonly event: string;
+    /** The main transcript's size when the hook ran. `SessionEnd` is settled by the worker, not here. */
+    readonly eof: number;
+    readonly transcript: string;
+    /** The turn-end folder (stdin's `cwd`). */
+    readonly cwd: string;
+    /** The turn-end repo's keys as step 3 resolved them. Re-deriving from `cwd` fails once a work tree is gone (§3.2). Absent: not in a repo. */
+    readonly keys?: {
+        readonly worktree: string;
+        readonly consent: string;
+    };
+    /** Present only when step 3's consent check got a REAL slug, never the `local:` fallback. */
+    readonly slug?: string;
+    readonly agent: string;
+    /** The identity digest (§3.13): a worker serves only firings of its own. */
+    readonly id: string;
+    readonly prior: PriorLiveness;
+    /** A sub-agent transcript the dialect announced for this firing. */
+    readonly announced?: string;
+    /**
+     * U6b (F5, C33): each sub-agent file's size when the hook ran, by file key. A replay sends no sub-agent byte past these (a file absent here
+     * sends nothing in this step), so a late replay cannot read sub-agent bytes that did not exist at the firing and a delayed worker produces what
+     * a prompt one does. ABSENT: an older firing, or one whose map would not fit the line; its sub-agents are sent to their real size, as before.
+     */
+    readonly sub?: Readonly<Record<string, number>>;
+}
+/** 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 declare const MAX_FIRING_SUB_FILES = 200;
+/** One firing as read back: where it starts and ends in the log, so a cursor can step over exactly it. */
+export interface ReadFiring {
+    readonly firing: Firing;
+    readonly start: number;
+    readonly end: number;
+}
+export interface FiringRead {
+    /** Valid firings at or after the cursor, oldest first, up to the first line of a NEWER version. */
+    readonly firings: readonly ReadFiring[];
+    /**
+     * The offset after the last COMPLETE line this read judged (a malformed one included, a partial trailing one not, a newer-version one
+     * not). Advancing the cursor here steps over torn lines that no valid firing follows.
+     */
+    readonly through: number;
+    /** True when a line of a newer `v` stopped the read. The worker leaves it unconsumed and exits (a newer build owns it). */
+    readonly blockedByNewer: boolean;
+}
+/**
+ * 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 declare function appendFiring(home: string, sessionId: string, firing: Firing): boolean;
+/**
+ * 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 declare function recordFiring(home: string, sessionId: string, firing: Firing): boolean;
+/**
+ * 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 declare function readFirings(home: string, sessionId: string, from?: number): FiringRead;
+/**
+ * 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 declare function firingSessions(home: string): string[];
+/** Forget a session's firing log and cursor (with its target record, on the existing 30-day schedule). Never throws. */
+export declare function forgetFirings(home: string, sessionId: string): void;
+export interface FiringCursor {
+    /** Byte offset of the first unconsumed firing. */
+    readonly offset: number;
+    /** Uncaught throws on the firing at `offset`. Reset whenever the cursor moves. */
+    readonly throws: number;
+}
+export declare const START_OF_LOG: FiringCursor;
+/**
+ * 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 declare function readCursor(home: string, sessionId: string): FiringCursor;
+/**
+ * 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 declare function writeCursor(home: string, sessionId: string, cursor: FiringCursor): boolean;
+/** Move the cursor to `offset`; the throw count belongs to the firing it left, so it resets. */
+export declare const advanced: (cursor: FiringCursor, offset: number) => FiringCursor;
+/** The firing at the cursor made the worker throw once more. */
+export declare const threw: (cursor: FiringCursor) => FiringCursor;
+/** Skip the firing at the cursor: it has thrown `MAX_FIRING_THROWS` times. */
+export declare const shouldSkip: (cursor: FiringCursor) => boolean;
+/**
+ * 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 declare function stampLive(home: string, key: SessionKey, atMs: number): boolean;
+/** The `.live` stamp at `path`, or null when absent, unreadable or not a positive number. Unknown fields are ignored. */
+export declare function readLiveFile(path: string): number | 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 declare function liveAtOf(stateLiveAt: number | null, livePath: string | null): number | null;
+/**
+ * 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 declare function liveStampKeys(input: {
+    readonly isolates: boolean;
+    readonly turnEnd: string | null;
+    readonly recordLedgerKeys: readonly string[];
+}): string[];