@50arms/session-telemetry 0.0.0-stage → 0.1.66

package/dist/dispatch-usage.js

@@ -0,0 +1,657 @@
+/**
+ * DX-2963 — a running dispatch's usage, worker side.
+ *
+ * The worker no longer sums anything. It feeds every transcript line into
+ * the ONE shared counter (`UsageLedgerCounter`, per-field maximum per reply)
+ * and ships the entries that are new or changed since the last acknowledged
+ * write to the server (`applyStats`), which derives every total from the
+ * ledger and hands them back. The worker's own view of the totals is what the
+ * server last returned — plus, for the token ceiling only, a local estimate of
+ * what it has read but the server has not acknowledged yet.
+ *
+ * Totals are taken from the server ONLY at process start (the first write,
+ * sent with no entries if there are none) and from each write's response —
+ * never seeded by hand (the reattach hand seeds this replaces).
+ *
+ * DB-free: runs in the DB-less worker. The sink decides the transport
+ * (HTTP on a registered worker, getPool-direct on the dashboard).
+ */
+import { UsageLedgerCounter, ledgerLineFromRaw, reportCompactionsOf, excessUsage, } from "./usage-ledger.js";
+import { ClaimTracker, emptyClaimState } from "./claim-tracker.js";
+import { ACTIVITY_BATCH_CAP, ACTIVITY_MESSAGE_BATCH_CAP, ACTIVITY_PROBLEM_BATCH_CAP, COMPACTION_BATCH_CAP, DispatchUsageTerminalError, chunkEntries, collapseActivityChanges, } from "./stats-wire.js";
+import { createUsageWriteQueue } from "./write-queue.js";
+import { createLogger } from "./internal-logger.js";
+const log = createLogger("dispatch-usage");
+export function zeroUsageTotals() {
+    return {
+        tokensIn: 0,
+        tokensOut: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        tokensTotal: 0,
+        costUsd: 0,
+        turnCount: 0,
+        toolCallCount: 0,
+    };
+}
+/** DX-4922 - the compactions as wire-sized chunks. */
+function chunkCompactions(compactions) {
+    const out = [];
+    for (let i = 0; i < compactions.length; i += COMPACTION_BATCH_CAP)
+        out.push(compactions.slice(i, i + COMPACTION_BATCH_CAP));
+    return out;
+}
+/** DX-5333 — the key a queued message is held under (one per activity and transcript line, so a re-read replaces rather than repeats). */
+const messageQueueKey = (m) => `${m.activityId}\u0000${m.messageKey}`;
+/** DX-5333 — the key a queued problem link is held under (one per activity and problem). */
+const problemLinkQueueKey = (l) => `${l.activityId}\u0000${l.problemRefNum}`;
+/** DX-5333 - a queue as wire-sized chunks. */
+function chunksOf(items, cap) {
+    const out = [];
+    for (let i = 0; i < items.length; i += cap)
+        out.push(items.slice(i, i + cap));
+    return out;
+}
+export class DispatchUsage {
+    counter = new UsageLedgerCounter();
+    /** DX-3962 - `null` in `"worker"` mode: the worker can never create a claim, so it can never send an `issueId`. */
+    claims;
+    /**
+     * DX-3962 - per source, the claim state as of its `acked` offset: what the next
+     * write reports with `acked`, promoted together with it. The state the tracker
+     * holds NOW belongs to `delivered`, which runs ahead.
+     */
+    ackedClaims = new Map();
+    serverTotals = zeroUsageTotals();
+    acked = new Map();
+    healthy = true;
+    refused = false;
+    started = false;
+    queue = createUsageWriteQueue();
+    constructor(mode) {
+        this.claims = mode === "operator-bridge" ? new ClaimTracker() : null;
+    }
+    // ── DX-2954: the cursor half ──────────────────────────────────────────────
+    /** How to read the watcher's live per-source cursor state. */
+    readCursorState = null;
+    /**
+     * Per source, the `delivered` offset as of the last ACKNOWLEDGED write — which
+     * is precisely what `acked` means. Seeded from the cursors this process
+     * resumed from, so a restart that writes before reading anything re-reports
+     * its own resume point instead of regressing it.
+     */
+    ackedCursor = new Map();
+    /**
+     * DX-3972 - per source, the `acked` the server holds for this dispatch: the `acked` of the last ACKNOWLEDGED
+     * report that carried the source. It is NOT {@link DispatchUsage.ackedCursor}: that is what the NEXT report
+     * claims (one write behind `delivered`), this is what the LAST one claimed. The terminal catch-up
+     * ({@link DispatchUsage.flushFinal}) is needed exactly while this lags the watcher's `delivered`.
+     */
+    storedAcked = new Map();
+    /**
+     * DX-2954 (AC 34324) — the cursors this process STARTED from, reported
+     * verbatim for every source the watcher has not opened yet until one write
+     * carrying them has landed. See {@link DispatchUsage.buildCursorReports}.
+     */
+    startCursors = {};
+    startCursorsPersisted = false;
+    /**
+     * DX-2954 — set the moment the first flush begins. `attachCursors` after that
+     * point would set the starting cursors AFTER a write that carried none, and
+     * `startCursorsPersisted` (set by any landed write) would then keep them from
+     * ever being carried — the exact AC 34324 loss, silently. So it fails loud.
+     */
+    flushBegan = false;
+    /** Past-EOF resets to report once, then forget. */
+    pastEof = [];
+    /**
+     * DX-2954 — replies this process read as REPLAYS. The server already counted
+     * them for THIS dispatch (they are below its stored `acked`), so they must not
+     * enter the unacknowledged excess the token-ceiling estimate adds on top of the
+     * server totals.
+     */
+    replayedMessageIds = new Set();
+    /** Running-set changes to report on the next write. */
+    pendingActivities = [];
+    /** DX-5333 - sub-agent messages to report on the next write, one per `(activityId, messageKey)`. */
+    pendingMessages = new Map();
+    /** DX-5333 - card problems sub-agents created, to report on the next write, one per `(activityId, problemRefNum)`. */
+    pendingProblemLinks = new Map();
+    /** The session transcript path — the ONE path field the wire carries. */
+    transcriptPath = null;
+    transcriptPathSent = false;
+    /**
+     * DX-2954 — wire the cursor half up at attach.
+     *
+     * `startCursors` are the cursors this process RESUMED from
+     * (`resolveStartCursors`); their `acked` values seed this collector's own
+     * acknowledged floor. `readCursorState` reads the watcher's live offsets at
+     * each write.
+     */
+    attachCursors(readCursorState, startCursors) {
+        // DX-2954 (AC 34324): the starting cursors ride the process-start write, so
+        // they must be attached BEFORE any write is attempted.
+        if (this.flushBegan) {
+            throw new Error("DispatchUsage.attachCursors: called after the first stats write began — the starting cursors would never be persisted");
+        }
+        this.readCursorState = readCursorState;
+        this.startCursors = startCursors;
+        for (const [source, cursor] of Object.entries(startCursors)) {
+            this.ackedCursor.set(source, cursor.acked);
+            // DX-3962 - the watcher reads each source from its stored `acked`, so the tracker starts from the claims
+            // stored with that offset: a pickup before it is never read again.
+            this.ackedClaims.set(source, cursor.claims);
+            this.claims?.seed(source, cursor.claims);
+        }
+    }
+    /**
+     * DX-2954 — a stored cursor was past its file's end; report the reset on the
+     * next write so the server records a `transcript_cursor_past_eof` event and
+     * permits the one sanctioned backwards move of `acked`.
+     */
+    recordPastEof(info) {
+        this.pastEof.push(info);
+        // The acknowledged floor MUST drop with the file. Leaving it at the old
+        // offset would make the next write report `acked` above its own `delivered`
+        // — which `parseStatsPayload` refuses outright ("delivered is behind
+        // acked"), and which the getPool-direct sink would store as a cursor pair
+        // that can never be satisfied. The bytes we believed acknowledged do not
+        // exist any more, so claiming them is simply false.
+        this.ackedCursor.set(info.source, 0);
+        // DX-3964 - the source is read again from 0: its timing reducer starts fresh, first-line-anchored.
+        this.counter.resetSource(info.source);
+        // DX-3962 - the claims recorded against the old file name a transcript that is gone; the source re-earns them
+        // from the lines it re-reads from 0 (the server clears the stored claims in the same statement as the cursor).
+        this.ackedClaims.set(info.source, emptyClaimState());
+        this.claims?.seed(info.source, emptyClaimState());
+    }
+    /**
+     * DX-2954 — queue running-set changes for the next write.
+     *
+     * Kept COLLAPSED (one entry per `(kind, activityId)`) rather than appended
+     * raw, so the queue is bounded by how many activities the dispatch has, not by
+     * how much they moved since the last write. A producer reports an activity's
+     * full current state every time anything about it changes, and a chatty
+     * sub-agent advances its `lastActivityAt` continuously — appending those would
+     * grow without bound, eventually exceed `ACTIVITY_BATCH_CAP` and take the
+     * WHOLE stats write down (not just its activity part) to describe a handful of
+     * activities.
+     *
+     * `collapseActivityChanges` applies the server's own merge rule, so collapsing
+     * here reaches the identical stored row; it is not a lossy summarisation.
+     */
+    recordActivities(changes) {
+        this.pendingActivities = collapseActivityChanges([
+            ...this.pendingActivities,
+            ...changes,
+        ]);
+    }
+    /**
+     * DX-5333 - queue sub-agent messages for the next write. One entry per `(activityId, messageKey)`: the server's insert is
+     * idempotent on that key, so a message read twice (a collector that re-reads a file) is sent once.
+     */
+    recordMessages(messages) {
+        for (const m of messages)
+            this.pendingMessages.set(messageQueueKey(m), m);
+    }
+    /** DX-5333 - queue the card problems a sub-agent created for the next write (idempotent on the pair, like {@link DispatchUsage.recordMessages}). */
+    recordProblemLinks(links) {
+        for (const l of links)
+            this.pendingProblemLinks.set(problemLinkQueueKey(l), l);
+    }
+    /**
+     * DX-2954 — the session's own transcript path, recorded on the dispatch's
+     * `jsonl_path`. Sent once, with the first stats write that carries it; the
+     * server also keeps only the first path it is given, so a repeat is harmless.
+     */
+    setTranscriptPath(path) {
+        this.transcriptPath = path;
+    }
+    /**
+     * DX-2954 — this write's cursor reports, plus the `delivered` value to promote
+     * to `acked` per source once the write is acknowledged.
+     *
+     * **`acked` deliberately LAGS `delivered` by one write.** A write reports the
+     * position it has read to (`delivered`) and the position whose entries a
+     * PREVIOUS write already had acknowledged (`acked`); only when THIS write
+     * succeeds does its own `delivered` become the next write's `acked`.
+     *
+     * The lag is not slack — it is what makes the pair safe. A reply's ledger entry
+     * can be RAISED after it was first reported (its usage grows as the reply
+     * streams), and a delivered line need not produce an entry at all (a
+     * `tool_result`), so "the server committed my last write" is NOT the same as
+     * "every line I have read is finally accounted for". Reporting `acked` one
+     * write behind is the conservative claim that is always true.
+     *
+     * What it costs: a restart re-reads the last write's window. That is exactly
+     * the window `EntryMeta.replay` covers — the ledger re-credits nothing (its
+     * excess rule) and every side-effecting subscriber skips it — so the cost is
+     * one window of re-read, never a double count or a duplicate side effect.
+     *
+     * ## The terminal write closes the lag (DX-3972)
+     *
+     * A restart is a crash, and a crash's window is the cost above. A dispatch that
+     * ENDS is not one: its watcher is drained and stopped, so every line it read has been
+     * fed to this collector and nothing will raise a reply any more. The terminal
+     * {@link DispatchUsage.flushFinal} therefore reports `acked` equal to `delivered` for
+     * every source it has opened (see {@link DispatchUsage.catchUpReports}), and a
+     * `--resume` of the session starts at the end of what this dispatch read instead of
+     * replaying the whole file. Without it a dispatch with ONE line-bearing write ended at
+     * `{acked: 0, delivered: EOF}`, and every resume of the session re-read the whole
+     * transcript and re-shipped it into its own `dispatch_logs`.
+     *
+     * ## The process-start write carries the STARTING cursors (AC 34324)
+     *
+     * `attachMonitoringStack` deliberately does NOT await `watcher.start()` —
+     * file discovery polls for up to 180 s and must not block the spawn — and the
+     * process-start stats write fires immediately after it. At that moment the
+     * watcher has opened no file, so its live `cursorState()` is empty.
+     *
+     * So every source in the cursors this process STARTED from that the watcher
+     * has not opened yet is reported VERBATIM — the exact `{acked, delivered}`
+     * pair it resumed from — until a write that carries them has landed. That is
+     * what makes "every attach persists its starting cursors" true on the FIRST
+     * write rather than one stats tick (15-30 s) later: a reattach of this row
+     * inside its first interval reads them back (start-order rule 1) and starts
+     * exactly where this process did, instead of finding no cursor, resolving
+     * rule 4 and skipping every line written since spawn. A fresh session's
+     * starting cursor is explicit too (`resolveStartCursors` rule 3 returns the
+     * main source at 0), and a `--resume`'s is its predecessor's (rule 2).
+     *
+     * Verbatim is the only honest claim for a source this process has not read:
+     * a higher `acked` would let a restart skip the replay window it has not
+     * re-credited, a lower one is refused as a regression. For the same reason
+     * the start write does not PROMOTE such a source's acknowledged floor — it
+     * delivered nothing there — so it stays out of `deliveredAtSend`.
+     *
+     * The one case with nothing to carry is rule 4 (a continuing dispatch with no
+     * cursor for ANY source): its start is "each existing file's end at
+     * discovery", which does not exist until discovery runs. Its cursors reach
+     * the server on the first write after discovery. Rule 4 is the pre-card
+     * deploy transition only — every dispatch since this card stores cursors on
+     * its first write — so that bounded window is the one the card accepts.
+     */
+    buildCursorReports() {
+        const reports = {};
+        const deliveredAtSend = new Map();
+        const claimsAtSend = new Map();
+        if (!this.readCursorState) {
+            return { reports, deliveredAtSend, claimsAtSend, reportedResets: [], carriesStartCursors: false };
+        }
+        const resetBySource = new Map(this.pastEof.map((p) => [p.source, p]));
+        const reportedResets = [];
+        const live = this.readCursorState();
+        let carriesStartCursors = false;
+        if (!this.startCursorsPersisted) {
+            for (const [source, start] of Object.entries(this.startCursors)) {
+                if (source in live)
+                    continue; // the live state supersedes it once opened
+                reports[source] = { acked: start.acked, delivered: start.delivered, claims: start.claims };
+                carriesStartCursors = true;
+            }
+        }
+        for (const [source, state] of Object.entries(live)) {
+            // `acked` floors at the source's START offset: a source opened at EOF
+            // under rule 4 must never claim byte 0 as acknowledged, or the next
+            // restart would read the whole file and re-sum the history rule 4 skipped.
+            const acked = Math.max(this.ackedCursor.get(source) ?? 0, state.startOffset);
+            // The claims reported with `acked` are the state AS OF `acked`, never the tracker's current state (which
+            // belongs to `delivered`): a restart resumes at `acked`, so that is the position the claims must describe.
+            const report = {
+                acked,
+                delivered: state.delivered,
+                claims: this.ackedClaims.get(source) ?? emptyClaimState(),
+            };
+            const reset = resetBySource.get(source);
+            if (reset) {
+                report.pastEof = { storedOffset: reset.storedOffset, fileSize: reset.fileSize };
+                reportedResets.push(reset);
+            }
+            reports[source] = report;
+            deliveredAtSend.set(source, state.delivered);
+            claimsAtSend.set(source, this.claims?.snapshot(source) ?? emptyClaimState());
+        }
+        // Only the resets that actually reached a report are consumed. A reset for a
+        // source that has left `cursorState()` (its tail dropped on ENOENT) would
+        // otherwise be taken and forgotten, leaving the stored `acked` at a value the
+        // file can never satisfy.
+        return { reports, deliveredAtSend, claimsAtSend, reportedResets, carriesStartCursors };
+    }
+    /**
+     * DX-2954 — whether the cursor half has anything new to say. An IDLE dispatch
+     * (no new lines, no hook events) must still cost zero writes per tick, which
+     * is why a write is not forced merely because cursors EXIST.
+     */
+    cursorsMoved(reports) {
+        for (const [source, report] of Object.entries(reports)) {
+            if (report.pastEof !== undefined)
+                return true;
+            // A source whose `delivered` has not moved past its last acknowledged
+            // point has nothing to report. A source seen for the FIRST time has no
+            // entry in `ackedCursor` yet, so it always counts as moved — that is how a
+            // newly discovered sub-agent file gets its starting cursor persisted.
+            if (report.delivered !== this.ackedCursor.get(source))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * DX-3972 - the TERMINAL write's reports: the tick's reports with every source this process has read claiming its
+     * whole `delivered` as `acked`, and the claim state AS OF that offset (the tracker's current state belongs to
+     * `delivered`, so it describes the new `acked` exactly, never a later position). Sources the watcher has not
+     * opened (a start cursor reported verbatim) are untouched: this process read nothing there to claim.
+     */
+    catchUpReports(reports, deliveredAtSend, claimsAtSend) {
+        const caughtUp = { ...reports };
+        for (const [source, delivered] of deliveredAtSend) {
+            caughtUp[source] = { ...reports[source], acked: delivered, claims: claimsAtSend.get(source) };
+        }
+        return caughtUp;
+    }
+    /**
+     * DX-3972 - whether the terminal write has anything to say: the server's `acked` still lags what the catch-up now
+     * claims. `ackedCursor` (the NEXT tick's claim) cannot tell, because a dispatch whose last write reported
+     * `delivered` with an older `acked` has `ackedCursor === delivered` and still lags; {@link DispatchUsage.storedAcked}
+     * is what the server holds. A source never reported at all has no entry, so it counts as lagging.
+     */
+    storedAckedLags(reports) {
+        for (const [source, report] of Object.entries(reports)) {
+            if (report.pastEof !== undefined || report.acked !== this.storedAcked.get(source))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Feed one raw transcript line of the usage feed set (assistant, user, attachment, system), in file order.
+     * DX-3964 - the usage collector is fed from the watcher's collector-only `onUsageLine` subscription, never from
+     * `onEntry`: `convertJsonlEntry` drops human prompts, attachments and system lines, and widening it would hand
+     * every other `onEntry` subscriber a new volume of entries.
+     *
+     * `meta.replay` (DX-2954) marks a line re-read after a restart. The line STILL goes to the counter - the
+     * ledger is idempotent and dropping it would lose usage a restart is meant to recover - but a replayed
+     * assistant reply's id is remembered so the local ceiling estimate does not count it twice (see
+     * {@link DispatchUsage.unacknowledged}).
+     */
+    observeRawLine(raw, meta) {
+        // DX-4922: a compaction boundary is judged against the session the file belongs to.
+        const line = ledgerLineFromRaw(raw, meta.source, meta.byteOffset, reportCompactionsOf(meta.sessionId));
+        if (!line)
+            return;
+        const message = raw.message;
+        const content = Array.isArray(message?.content) ? message.content : [];
+        // DX-3962 - a `tool_result` settles a pickup / release the source asked for earlier.
+        if (line.kind === "user")
+            this.claims?.observeResultBlocks(meta.source, content);
+        if (line.kind === "assistant") {
+            line.line.issueId = this.claims?.issueFor(meta.source) ?? null;
+            // The counter's OWN key, not `line.messageId`: a usage line with no `message.id` is keyed by
+            // `syntheticMessageKey(source, byteOffset)`, and recording a different key here would leave that reply's
+            // replay unrecognised - the exact double-count this set prevents.
+            if (meta.replay)
+                this.replayedMessageIds.add(line.replyKey);
+        }
+        this.counter.observeLine(line);
+        // AFTER the reply is counted: a reply is credited to the card held at its FIRST line, so the pickup this line
+        // itself asks for takes effect only on its result, and never on the reply that issued it.
+        if (line.kind === "assistant")
+            this.claims?.observeAssistantBlocks(meta.source, content);
+    }
+    /**
+     * Ship every changed entry in capped batches, one after another. The first
+     * call always writes (even with nothing to send) so the process takes the
+     * server totals at start. A failed batch re-queues itself and every later
+     * batch; a refusal (the dispatch went terminal) stops all later writes.
+     *
+     * DX-2954 — the write also carries the cursor half. A write happens when there
+     * are entries, OR the cursors moved, OR there are activity changes, OR it is
+     * the process-start write; an idle dispatch still writes nothing. Cursors,
+     * activity changes and the transcript path ride the LAST batch only, so a
+     * multi-batch backlog does not repeat them and the cursor can never be
+     * acknowledged ahead of the entries it covers.
+     */
+    flush(sink, dispatchId) {
+        return this.write(sink, dispatchId, false);
+    }
+    /**
+     * DX-3972 - the TERMINAL write: {@link DispatchUsage.flush} that also catches the stored `acked` up to
+     * `delivered` for every source (see {@link DispatchUsage.catchUpReports}). Call it once, when the dispatch ends,
+     * after the watcher is drained and stopped (that is the whole precondition: every line it read has reached this
+     * collector, so `delivered` is covered by the entries this very write carries), and BEFORE the row goes terminal
+     * (the server refuses a terminal dispatch's stats, which would drop the catch-up silently). A write that does not
+     * land promotes nothing, exactly as in a tick; a dispatch already caught up sends no write.
+     *
+     * It does NOT wait for the dispatch's log shipper: the spawn path flushes it before this call, the reattach path
+     * after (`reattach.ts` `_cleanup`), so on a reattach `acked` can claim a line whose `dispatch_logs` row is still in
+     * the shipper's buffer. The shipper is best-effort today and a resume's shipper skips replays either way, so
+     * nothing is lost that was not already; acking only after the log line is acknowledged is DX-2956's change.
+     */
+    flushFinal(sink, dispatchId) {
+        return this.write(sink, dispatchId, true);
+    }
+    write(sink, dispatchId, catchUp) {
+        return this.queue(async () => {
+            if (this.refused)
+                return "refused";
+            this.flushBegan = true;
+            const changed = this.counter.takeChanged();
+            const batches = chunkEntries(changed);
+            const built = this.buildCursorReports();
+            const { deliveredAtSend, claimsAtSend, reportedResets, carriesStartCursors } = built;
+            const reports = catchUp
+                ? this.catchUpReports(built.reports, deliveredAtSend, claimsAtSend)
+                : built.reports;
+            // TAKE the queued side data, exactly as `counter.takeChanged()` does, so a
+            // hook that fires during the await lands in the NEXT write rather than
+            // being silently dropped by a post-write reset of the live array.
+            // Take at most one batch's worth and LEAVE the rest queued. The cap is
+            // enforced server-side by the strict parser, and an over-cap payload comes
+            // back as a 400 — which is not a `DispatchUsageTerminalError`, so `flush`
+            // re-queues it and retries the identical over-cap payload forever. That
+            // wedges the dispatch's stats writes PERMANENTLY, entries and cursors
+            // included, not just its activity rows. The collapse in `recordActivities`
+            // makes crossing the cap unlikely (one entry per distinct activity, not per
+            // change), but nothing bounds how many distinct activities a dispatch
+            // starts, so the cap is respected here rather than merely made improbable.
+            // Splitting across writes is lossless: each row is a full-state idempotent
+            // upsert.
+            // DX-4922 - every queued compaction, in chunks of the wire's cap: chunk i rides payload i, so a backlog is
+            // drained by this one write (the terminal one included) and never waits for a later tick; a failed payload puts
+            // its chunk and every later one back on the counter's queue.
+            const compactions = this.counter.takeChangedCompactions();
+            const compactionChunks = chunkCompactions(compactions);
+            const activities = this.pendingActivities.slice(0, ACTIVITY_BATCH_CAP);
+            this.pendingActivities = this.pendingActivities.slice(ACTIVITY_BATCH_CAP);
+            // DX-5333 - like the compactions, every queued sub-agent message and problem link rides this write in wire-sized chunks
+            // (chunk i on payload i), so the terminal write drains a backlog instead of leaving it for a dispatch that no longer
+            // accepts writes. A failed payload puts its chunk and every later one back.
+            const messageChunks = chunksOf([...this.pendingMessages.values()], ACTIVITY_MESSAGE_BATCH_CAP);
+            const problemChunks = chunksOf([...this.pendingProblemLinks.values()], ACTIVITY_PROBLEM_BATCH_CAP);
+            this.pendingMessages = new Map();
+            this.pendingProblemLinks = new Map();
+            // Consume only the resets that reached a report (see `buildCursorReports`).
+            const pastEofSent = reportedResets;
+            const sentResets = new Set(reportedResets);
+            this.pastEof = this.pastEof.filter((p) => !sentResets.has(p));
+            // `carriesStartCursors` forces the write on its own: a starting pair like
+            // `{acked: 0, delivered: 0}` never looks "moved", and a process-start write
+            // whose last batch failed must still deliver it on a later, otherwise idle
+            // tick.
+            const haveSideData = carriesStartCursors ||
+                (catchUp ? this.storedAckedLags(reports) : this.cursorsMoved(reports)) ||
+                activities.length > 0 ||
+                messageChunks.length > 0 ||
+                problemChunks.length > 0 ||
+                compactions.length > 0 ||
+                (this.transcriptPath !== null && !this.transcriptPathSent);
+            if (batches.length === 0 && (!this.started || haveSideData))
+                batches.push([]);
+            while (batches.length < Math.max(compactionChunks.length, messageChunks.length, problemChunks.length))
+                batches.push([]);
+            for (let i = 0; i < batches.length; i++) {
+                const payload = { entries: batches[i] };
+                if (i < compactionChunks.length)
+                    payload.compactions = compactionChunks[i];
+                if (i < messageChunks.length)
+                    payload.activityMessages = messageChunks[i];
+                if (i < problemChunks.length)
+                    payload.activityProblems = problemChunks[i];
+                const isLast = i === batches.length - 1;
+                if (isLast) {
+                    if (Object.keys(reports).length > 0)
+                        payload.sourceCursors = reports;
+                    if (activities.length > 0)
+                        payload.activities = activities;
+                    if (this.transcriptPath !== null && !this.transcriptPathSent) {
+                        payload.transcriptPath = this.transcriptPath;
+                    }
+                }
+                try {
+                    const res = await sink.applyStats(dispatchId, payload);
+                    this.started = true;
+                    this.serverTotals = res.totals;
+                    for (const [id, u] of Object.entries(res.perMessage))
+                        this.acked.set(id, u);
+                    if (isLast) {
+                        // The write landed, so every line up to the `delivered` we SENT is
+                        // now acknowledged — that is what makes the next restart resume
+                        // there. A source the server REFUSED as a regression keeps its own
+                        // stored value, so we must not promote ours past it.
+                        const refused = new Set(res.cursorRegressions);
+                        // DX-3972 - what the server now holds as each reported source's `acked` (a refused source kept its own).
+                        for (const [source, report] of Object.entries(reports)) {
+                            if (!refused.has(source))
+                                this.storedAcked.set(source, report.acked);
+                        }
+                        // A source whose file was found truncated WHILE this write was in
+                        // flight must NOT have its floor promoted. `recordPastEof` dropped
+                        // that floor to 0 on purpose; re-raising it here would make the next
+                        // report claim `acked` above its own `delivered`, which
+                        // `parseStatsPayload` refuses outright — wedging every later write
+                        // for this dispatch, since nothing lowers `acked` again.
+                        const resetMidFlight = new Set(this.pastEof.map((p) => p.source));
+                        for (const [source, delivered] of deliveredAtSend) {
+                            if (refused.has(source) || resetMidFlight.has(source))
+                                continue;
+                            this.ackedCursor.set(source, delivered);
+                            // DX-3962 - the claims advance with the offset they describe, never ahead of it.
+                            this.ackedClaims.set(source, claimsAtSend.get(source));
+                        }
+                        if (payload.transcriptPath !== undefined)
+                            this.transcriptPathSent = true;
+                        // Safe on ANY landed write: `attachCursors` refuses to run after the
+                        // first flush began, so every starting cursor was either carried by
+                        // this write or is superseded by a live one that this write reported.
+                        this.startCursorsPersisted = true;
+                    }
+                }
+                catch (err) {
+                    if (err instanceof DispatchUsageTerminalError) {
+                        this.refused = true;
+                        return "refused";
+                    }
+                    this.healthy = false;
+                    this.counter.requeue(batches.slice(i).flat().map((e) => e.messageId));
+                    this.counter.requeueCompactions(compactionChunks.slice(i).flat().map((c) => c.id));
+                    // DX-5333 - back ahead of anything recorded during the failed write; a re-recorded message is the same entry.
+                    this.pendingMessages = new Map([
+                        ...messageChunks.slice(i).flat().map((m) => [messageQueueKey(m), m]),
+                        ...this.pendingMessages,
+                    ]);
+                    this.pendingProblemLinks = new Map([
+                        ...problemChunks.slice(i).flat().map((l) => [problemLinkQueueKey(l), l]),
+                        ...this.pendingProblemLinks,
+                    ]);
+                    // Re-queue the side data at the FRONT, and leave `ackedCursor` where it
+                    // was: the next write re-reports all three. Advancing an
+                    // unacknowledged cursor would skip those lines permanently, and
+                    // dropping a past-EOF reset would leave the server refusing the
+                    // eventual lower `acked` as a regression forever.
+                    // Collapsed on the way back in, so the re-queue keeps the invariant
+                    // `recordActivities` maintains — and so a failed write followed by
+                    // fresh changes for the same activity does not double the queue.
+                    this.pendingActivities = collapseActivityChanges([
+                        ...activities,
+                        ...this.pendingActivities,
+                    ]);
+                    this.pastEof = [...pastEofSent, ...this.pastEof];
+                    log.error(`[Dispatch ${dispatchId}] stats write failed — entries re-queued for the next write`, err);
+                    return "failed";
+                }
+            }
+            this.healthy = true;
+            return "ok";
+        });
+    }
+    /** The dispatch's totals as the server last returned them. */
+    totals() {
+        return this.serverTotals;
+    }
+    /** Window tokens (input + output + cache writes) of the server totals. */
+    serverWindowTokens() {
+        const t = this.serverTotals;
+        return t.tokensIn + t.tokensOut + t.cacheWrite;
+    }
+    /** Whether the most recent stats write succeeded. */
+    statsHealthy() {
+        return this.healthy;
+    }
+    /**
+     * The per-field excess of each local reply's maximum over what the server
+     * last acknowledged for it.
+     *
+     * DX-2954 — REPLAYED replies are excluded. The pre-DX-2954 comment here
+     * asserted that "every id this process observed was read at or after its
+     * starting cursor … so lines re-read on a restart never enter the estimate",
+     * which stopped being true the moment replays became a deliberate input: a
+     * replayed reply has no entry in `this.acked` at process start, so its FULL
+     * usage would be added on top of `serverTotals` that already contain it. That
+     * feeds a fabricated total to the token ceiling (`agent-status.ts` uses this
+     * estimate precisely when a write did NOT land) and to the context-overflow
+     * decision — either can stop a healthy dispatch.
+     */
+    unacknowledged() {
+        return this.counter
+            .all()
+            .filter((e) => !this.replayedMessageIds.has(e.messageId))
+            .map((e) => excessUsage(e.usage, this.acked.get(e.messageId) ?? {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite5m: 0,
+            cacheWrite1h: 0,
+        }));
+    }
+    /**
+     * The dispatch's usage as far as this process knows it: the server totals
+     * plus the per-field excess this process has read but the server has not
+     * acknowledged. A replay block adds nothing (its excess over the
+     * acknowledged total is zero). For a job with no dispatch row (nothing is
+     * ever acknowledged) this is exactly the local counter's total.
+     */
+    estimate() {
+        const t = this.serverTotals;
+        const out = {
+            tokensIn: t.tokensIn,
+            tokensOut: t.tokensOut,
+            cacheRead: t.cacheRead,
+            cacheWrite: t.cacheWrite,
+        };
+        for (const u of this.unacknowledged()) {
+            out.tokensIn += u.input;
+            out.tokensOut += u.output;
+            out.cacheRead += u.cacheRead;
+            out.cacheWrite += u.cacheWrite5m + u.cacheWrite1h;
+        }
+        return out;
+    }
+    /** Token-ceiling input: window tokens (input + output + cache writes) of {@link estimate}. */
+    windowTokensEstimate() {
+        const e = this.estimate();
+        return e.tokensIn + e.tokensOut + e.cacheWrite;
+    }
+    /** All-field total of {@link estimate}. */
+    totalTokensEstimate() {
+        const e = this.estimate();
+        return e.tokensIn + e.tokensOut + e.cacheRead + e.cacheWrite;
+    }
+}

package/dist/git-head.d.ts

@@ -0,0 +1 @@
+export declare function readGitHead(cwd: string): Promise<string | null>;