@vibe-commit/capture 0.10.0 → 0.11.1

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;
 /**