@cat-factory/executor-harness 1.114.0 → 1.118.0

package/dist/git.js

@@ -91,6 +91,48 @@ export function isGitTimeoutKill(err, aborted) {
 function gitSubcommand(args) {
     return args.find((a) => a !== '' && !a.startsWith('-')) ?? 'command';
 }
+/**
+ * Whether `stderr` is a REFUSED push, and which shape. Ordered: the lease/fetch-first shapes are
+ * checked first, because a `(stale info)` refusal also prints the generic "failed to push some
+ * refs" line the non-fast-forward shape shares. Pure, so both branches are unit-tested against
+ * real git output rather than inferred.
+ */
+export function classifyPushRejection(stderr) {
+    // A HOST-side refusal is not contention, and re-dispatching cannot help: branch protection, a
+    // pre-receive hook or a token policy is declining the write itself, and GitHub's protected-branch
+    // message says "refusing to allow a non-fast-forward push", which would otherwise read as a
+    // rewrite. Git's own labels separate the two cleanly (`! [remote rejected]` is the server
+    // declining, `! [rejected]` is git's own fast-forward/lease check), so such a failure stays a
+    // plain `git` fault with the write-access remedy below.
+    if (/remote rejected|protected branch|hook declined|refusing to allow/i.test(stderr)) {
+        return undefined;
+    }
+    if (/\(stale info\)|\(fetch first\)|remote contains work that you do not/i.test(stderr)) {
+        return 'remote-writer';
+    }
+    if (/\(non-fast-forward\)|tip of your current branch is behind|branch tip is behind/i.test(stderr)) {
+        return 'local-rewrite';
+    }
+    return undefined;
+}
+/**
+ * The remedy each {@link PushRejection} earns. A `Record`, so a new rejection shape cannot be
+ * classified without saying what a human should do about it. Neither is "run `git pull`", which is
+ * what git's own hint advises and is advice for a person at a terminal, not for an autonomous run.
+ */
+const PUSH_REJECTION_REMEDIES = {
+    'local-rewrite': 'The push was refused because the commit it publishes is not descended from the one the work ' +
+        'branch already holds: this checkout rewrote history that had already been pushed (an amend, ' +
+        "reset or rebase of an existing commit). The platform checkpoint-pushes the agent's commits " +
+        'while it works and lets a run force over its OWN published checkpoint, so what stays refused ' +
+        'is a rewrite it cannot attribute to this pass: commits an earlier run published, or a rewrite ' +
+        'that dropped the branch tip this pass started from. The engine re-dispatches the step to ' +
+        'resume from the branch as it stands; work already on the branch is never dropped.',
+    'remote-writer': 'The push was refused because another writer advanced this work branch while the run was ' +
+        'working (a second dispatch for the same block, or a person pushing to it). Nothing is lost: ' +
+        "the other writer's commits stay on the branch and the engine re-dispatches the step so the " +
+        'agent resumes on top of them. If it recurs, check whether two runs are active for the same block.',
+};
 /**
  * Classify the common shapes of git's own stderr into an actionable remedy, else undefined
  * (an unrecognized failure keeps just its raw stderr). This is the FIRST-WRAP-POINT for
@@ -102,6 +144,11 @@ function gitSubcommand(args) {
  */
 export function describeGitFailure(stderr) {
     const s = stderr.toLowerCase();
+    // A refused push first: its stderr carries neither an auth nor an access shape, so a miss here
+    // would leave the operator git's own "use 'git pull' before pushing again" hint and nothing else.
+    const rejection = classifyPushRejection(stderr);
+    if (rejection)
+        return PUSH_REJECTION_REMEDIES[rejection];
     // Rate-limit / abuse-detection first: the host returns these as a 403, which would
     // otherwise fall into the write-access shape below and be mislabeled as a permission
     // problem — but the fix is to wait, not to grant access.
@@ -154,13 +201,21 @@ function gitFailure(err, args, aborted) {
     }
     const stderr = typeof e?.stderr === 'string' ? e.stderr : (e?.stderr?.toString() ?? '');
     const base = e instanceof Error ? e.message : String(err);
-    const combined = stderr.trim() ? `${base}\n${stderr.trim()}` : base;
-    // Append a cause + fix for the recognized auth/access shapes, keeping the raw (scrubbed)
-    // stderr above it as the detail. The remedy is static text with no secrets, so it is added
-    // after redaction.
+    // `execFile` builds its rejection message as `Command failed: <cmd>\n<stderr>`, so for the
+    // ordinary non-zero exit the stderr is ALREADY in `base`, and appending it again printed every
+    // git failure's output twice, which reads as two attempts. Append only what `base` lacks
+    // (a killed/other rejection whose message carries no output).
+    const tail = stderr.trim();
+    const combined = tail && !base.includes(tail) ? `${base}\n${tail}` : base;
+    // Append a cause + fix for the recognized auth/access/push-rejection shapes, keeping the raw
+    // (scrubbed) stderr above it as the detail. The remedy is static text with no secrets, so it is
+    // added after redaction.
     const remedy = describeGitFailure(combined);
     const message = remedy ? `${redactSecrets(combined)}\n${remedy}` : redactSecrets(combined);
-    const failure = new HarnessFailure('git', message);
+    // A REFUSED push is not a generic `git` fault: the branch moved under this run, which the engine
+    // recovers from by re-dispatching the step onto the branch as it now stands. It gets its own
+    // structured cause so that recovery keys off a classification rather than this message.
+    const failure = new HarnessFailure(classifyPushRejection(combined) ? 'branch-contended' : 'git', message);
     if (e?.stack)
         failure.stack = redactSecrets(e.stack);
     return failure;
@@ -851,15 +906,113 @@ export async function fetchPullRequestHead(opts) {
     }
 }
 /**
- * Push the work branch to origin. The remote URL carries only the username, so
- * the token is supplied here via the askpass env (never in argv).
+ * Push the work branch to origin and return the sha it PUBLISHED. The remote URL carries only the
+ * username, so the token is supplied here via the askpass env (never in argv).
+ *
+ * The push names an explicit SOURCE COMMIT (`<sha>:refs/heads/<branch>`) rather than the branch,
+ * which is what makes the return value exact rather than a guess. The agent commits while this
+ * runs, so `git push origin <branch>` publishes whatever the branch ref holds at the moment git
+ * reads it, and a caller that leases against a sha it read either side of that has leased against
+ * the wrong commit. Reading it back from `refs/remotes/origin/<branch>` afterwards is worse than
+ * inexact, it is EMPTY on the production checkout: a fresh coding run clones one branch
+ * (`cloneRepo`), so the remote's fetch refspec covers the base alone and `git push` creates no
+ * tracking ref for the work branch at all. Naming the sha needs no ref and no round trip.
+ *
+ * `-u` goes with it: with a non-branch source git sets no upstream config (verified), nothing in
+ * the harness reads that config, and the agent is told never to push or pull.
+ *
+ * `expectRemoteSha` turns the push into a LEASED force (`--force-with-lease=<branch>:<sha>`), which
+ * is how a run whose own checkpoint push it has since rewritten still lands. It is deliberately NOT
+ * a plain `--force`: the lease succeeds only while the remote still holds the sha THIS run
+ * published, so a second writer's commits refuse the push (`(stale info)`) instead of being
+ * clobbered. Callers therefore pass only a sha this same pass published; leasing against a tip we
+ * merely CLONED would force over an earlier run's work.
  */
-export async function pushBranch(dir, branch, ghToken, signal) {
-    await git(['push', '-u', 'origin', branch], {
+export async function pushBranch(dir, branch, ghToken, signal, opts = {}) {
+    const sha = (await git(['rev-parse', '--verify', `refs/heads/${branch}`], { cwd: dir, signal })).trim();
+    const lease = opts.expectRemoteSha ? [`--force-with-lease=${branch}:${opts.expectRemoteSha}`] : [];
+    await git(['push', ...lease, 'origin', `${sha}:refs/heads/${branch}`], {
         cwd: dir,
         signal,
         env: await authEnv(ghToken),
     });
+    return sha;
+}
+/**
+ * Whether `sha` is still reachable from `branch`'s tip, i.e. the branch CONTAINS it:
+ * `git rev-list --count --max-count=1 <sha> --not refs/heads/<branch>` is 0 when everything
+ * reachable from `sha` is reachable from the branch too (the tip itself counts as contained).
+ *
+ * Phrased as a rev-list rather than `merge-base --is-ancestor` on purpose: the latter answers "no"
+ * by EXITING 1, which is indistinguishable here from a broken checkout, and this probe's whole job
+ * is to be trusted only when it is a definite answer. Tri-state for the same reason (as
+ * {@link branchAheadOfBase} is):
+ *
+ *  - `true`: confirmed contained.
+ *  - `false`: confirmed dropped, so the branch was rewritten below `sha`.
+ *  - `undefined`: could not determine (an unknown object, a rev-list error). A caller must not read
+ *    a failed probe as either answer.
+ *
+ * The work-branch lease is gated on this: see {@link workBranchLease}.
+ */
+export async function branchContainsCommit(dir, branch, sha, signal) {
+    try {
+        const out = await git(['rev-list', '--count', '--max-count=1', sha, '--not', `refs/heads/${branch}`], { cwd: dir, signal });
+        const count = Number(out.trim());
+        return Number.isNaN(count) ? undefined : count === 0;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The work branch's tip when it holds something UNPUBLISHED, else undefined: the answer to whether a
+ * checkpoint tick has anything to do. Two ways of having nothing:
+ *
+ *  - the tip is still `baseSha`, so this pass has committed nothing. Pushing here would create the
+ *    work branch at the base commit, and a later retry would see that zero-diff branch via
+ *    `remoteBranchExists`, resume it as work, and fail to open a PR ("no commits between base and
+ *    head"). A pass that never commits must leave NO branch behind.
+ *  - the tip is `publishedSha`, so the last push already published it. Without this the checkpoint
+ *    re-pushed an unchanged branch on every tick: an hour-long run committing eight times issued
+ *    ~60 pushes, ~52 of them a full authenticated round trip answering "Everything up-to-date",
+ *    each one counting against the host's push rate limits.
+ *
+ * That second condition is also what keeps the INTERVAL the right knob. It expresses the acceptable
+ * loss window when a container dies (a property of the deployment's infra churn), not a rate: gated
+ * this way, the tick publishes at most one push per commit the agent makes, whatever the model or
+ * the run's length, so nothing here needs to be tuned per model.
+ */
+export async function unpublishedWorkBranchTip(args) {
+    const head = await headCommit(args.dir, args.signal);
+    if (head === args.baseSha || head === args.publishedSha)
+        return undefined;
+    return head;
+}
+/**
+ * The lease a work-branch push is entitled to (the `opts` {@link pushBranch} takes): the sha this
+ * pass last published, and nothing at all before it has published one.
+ *
+ * The extra condition is what bounds the force to THIS pass's own commits, which the lease alone
+ * does not do and the design promises. Once one checkpoint has landed, a rewrite that drops
+ * `baseSha` (the tip the pass started from, which on a RESUMED branch is an earlier run's published
+ * work) would still lease successfully against our own checkpoint and carry those earlier commits
+ * away with it. So the lease is withheld unless the branch still CONTAINS `baseSha`: the push then
+ * goes out plain, git refuses it as a non-fast-forward, and the engine re-dispatches onto the
+ * branch as it stands.
+ *
+ * A probe that could not answer withholds it too (`onWithheld('unreadable')`), because the two
+ * mistakes are not symmetric: withholding costs a refused rewrite and one re-dispatch, trusting an
+ * unreadable probe costs commits.
+ */
+export async function workBranchLease(args) {
+    if (!args.publishedSha)
+        return {};
+    const contains = await branchContainsCommit(args.dir, args.branch, args.baseSha, args.signal);
+    if (contains === true)
+        return { expectRemoteSha: args.publishedSha };
+    args.onWithheld?.(contains === undefined ? 'unreadable' : 'dropped');
+    return {};
 }
 /**
  * Reset the working tree's git history to a single bootstrap commit and push it

package/dist/inline.js

@@ -13,14 +13,27 @@ import { runSubscriptionHarness } from './agent-runner.js';
 // `auth.json`), so the container and coding paths can never disagree on how a credential
 // is injected.
 /**
- * Map the harness CLI's terminal stop reason (lifted onto the last call metric) to the
- * inline `finishReason` the reviewer keys off. Only Claude Code reports it (`max_tokens` on
- * a `--output-format stream-json` result); Codex's thinner stream exposes none, so it reads
- * as `stop` — the same one-shot limitation the host-CLI runner has.
+ * Map the harness CLI's terminal stop reason (lifted onto the last call metric) to the inline
+ * `finishReason` the reviewer keys off, or `undefined` when the CLI reported NONE.
+ *
+ * Undefined rather than `stop`, which is what this returned for years on the strength of a
+ * comment claiming Claude Code reports the reason. It does not: its `stream-json` `assistant`
+ * envelopes carry the message-START snapshot, whose `stop_reason` is null, so every call metric
+ * a claude-code or codex run produces has a null reason and this answered `stop` for all of them.
+ * `stop` is a positive claim that the model finished of its own accord, and it is the exact claim
+ * a truncation check is trying to disprove — so the one caller keyed off it
+ * (`finishReason === 'length'`) could never fire, and every store that kept the row recorded a
+ * clean stop nobody observed.
+ *
+ * Kept as a MAPPING rather than deleted because the field remains reachable: a subagent turn is
+ * read from a completed JSONL transcript, which does carry `stop_reason`, and a future CLI build
+ * (or `--include-partial-messages`) would restore it on the parent stream too.
  */
 function deriveFinishReason(calls) {
     const last = calls?.[calls.length - 1];
-    const reason = last?.finishReason?.toLowerCase() ?? '';
+    const reason = last?.finishReason?.toLowerCase();
+    if (!reason)
+        return undefined;
     return reason === 'max_tokens' || reason === 'length' ? 'length' : 'stop';
 }
 /**
@@ -51,9 +64,10 @@ export async function handleInline(job, opts) {
             ...(opts.signal ? { signal: opts.signal } : {}),
             ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
         });
+        const finishReason = deriveFinishReason(outcome.callMetrics);
         return {
             text: outcome.summary,
-            finishReason: deriveFinishReason(outcome.callMetrics),
+            ...(finishReason ? { finishReason } : {}),
             ...(outcome.usage ? { usage: inlineUsage(outcome.usage, outcome.callMetrics) } : {}),
             ...(outcome.callMetrics ? { callMetrics: outcome.callMetrics } : {}),
         };

package/dist/job.d.ts

@@ -673,7 +673,14 @@ export interface InlineJob extends HarnessAuthFields {
 /** The inline completion result: the reply text plus lifted token usage / per-call telemetry. */
 export interface InlineResult {
     text: string;
-    /** `length` when the model hit its output cap (the reviewer rejects a truncated doc). */
+    /**
+     * `length` when the model hit its output cap (the reviewer rejects a truncated doc), `stop`
+     * when it finished of its own accord, ABSENT when the CLI reported no stop reason at all.
+     *
+     * Absent is the normal case today: neither subscription CLI exposes a per-call stop reason on
+     * its parent stream, and the three states must stay distinct because a reader that takes
+     * absent for `stop` is asserting the one thing a truncation check exists to disprove.
+     */
     finishReason?: 'stop' | 'length';
     /**
      * The job's token usage with the input side split into its three ORTHOGONAL classes:

package/dist/pi.d.ts

@@ -304,6 +304,16 @@ export interface HarnessCallMetric {
      * never disagree about which phase billed a call.
      */
     phase?: string;
+    /**
+     * This row is not a TURN: it stands for the job as a whole, carrying the spend the CLI reported
+     * in its terminal cumulative total and did not attribute to any turn it narrated (see
+     * {@link unaccountedUsageCall}). It has no bodies, because there was no request to capture.
+     *
+     * The backend files it with a NULL turn index for that reason, while still deriving its row id
+     * from {@link seq} so a replayed poll re-records instead of duplicating. Absent on every real
+     * turn. `CliInlineLanguageModel`'s step-level row is the same idea on the inline path.
+     */
+    standsForJob?: boolean;
 }
 /**
  * Publish one captured model call: append it to the run's list (which becomes the terminal
@@ -318,32 +328,15 @@ export interface HarnessCallMetric {
  * A published call must be FINAL. The backend records it the moment the drain reaches it and
  * IGNORES the terminal repeat (first write wins, so its stored prompt delta stays valid against
  * the chain tip it was written against), which means a field mutated after publishing never
- * reaches the store. A producer whose calls can still change (the cumulative-usage fallback,
- * whose totals arrive with the CLI's terminal `result` event) publishes through
- * {@link createCallMetricPublisher} instead, which withholds exactly those.
- */
-export declare function publishCallMetric(calls: HarnessCallMetric[], call: HarnessCallMetric, onCallMetric?: (call: HarnessCallMetric) => void): void;
-/** Appends captured calls to a run's list, streaming each one as soon as it is final. */
-export interface CallMetricPublisher {
-    /** Append a captured call, streaming it now unless its tokens can still be rewritten. */
-    publish(call: HarnessCallMetric): void;
-    /** Stream whatever is still withheld. Call once the run's totals are attributed. */
-    flush(): void;
-}
-/**
- * A {@link publishCallMetric} wrapper for a producer whose per-call tokens may be filled in at
- * the END of the run: a CLI that reports only a cumulative total leaves every turn at zero, and
- * `attributeCumulativeUsage` pins the total onto the last call once the terminal `result` event
- * arrives.
+ * reaches the store.
  *
- * Since a published call must be final (the backend stores it on the drain and ignores the
- * terminal repeat), a call the CLI did NOT cost is appended to the list but WITHHELD from the
- * live stream — otherwise it records as a zero-token row and the attributed numbers never land.
- * The withholding window closes the moment any call IS costed: attribution can no longer fire, so
- * everything held is final and released at once, in capture order, and every later call streams
- * immediately whatever its tokens. {@link flush} covers the run that was never costed at all.
+ * That is a rule about every producer, and it is why the cumulative-usage reconciliation files its
+ * shortfall as a NEW row here at the end of the run (`unaccountedUsageCall`) rather than growing the
+ * last captured turn. This used to be wrapped by a publisher that withheld the turn attribution
+ * could still rewrite, trading a turn of streaming lag for that mutability; with nothing mutated,
+ * the wrapper had no reason left to exist.
  */
-export declare function createCallMetricPublisher(calls: HarnessCallMetric[], onCallMetric?: (call: HarnessCallMetric) => void): CallMetricPublisher;
+export declare function publishCallMetric(calls: HarnessCallMetric[], call: HarnessCallMetric, onCallMetric?: (call: HarnessCallMetric) => void): void;
 /** Pi's assistant summary plus {@link PiRunStats} describing what it did. */
 export interface PiRunOutcome {
     summary: string;

package/dist/pi.js

@@ -436,52 +436,18 @@ export async function writeWebToolsConfig(config) {
  * A published call must be FINAL. The backend records it the moment the drain reaches it and
  * IGNORES the terminal repeat (first write wins, so its stored prompt delta stays valid against
  * the chain tip it was written against), which means a field mutated after publishing never
- * reaches the store. A producer whose calls can still change (the cumulative-usage fallback,
- * whose totals arrive with the CLI's terminal `result` event) publishes through
- * {@link createCallMetricPublisher} instead, which withholds exactly those.
+ * reaches the store.
+ *
+ * That is a rule about every producer, and it is why the cumulative-usage reconciliation files its
+ * shortfall as a NEW row here at the end of the run (`unaccountedUsageCall`) rather than growing the
+ * last captured turn. This used to be wrapped by a publisher that withheld the turn attribution
+ * could still rewrite, trading a turn of streaming lag for that mutability; with nothing mutated,
+ * the wrapper had no reason left to exist.
  */
 export function publishCallMetric(calls, call, onCallMetric) {
     calls.push(call);
     onCallMetric?.(call);
 }
-/**
- * A {@link publishCallMetric} wrapper for a producer whose per-call tokens may be filled in at
- * the END of the run: a CLI that reports only a cumulative total leaves every turn at zero, and
- * `attributeCumulativeUsage` pins the total onto the last call once the terminal `result` event
- * arrives.
- *
- * Since a published call must be final (the backend stores it on the drain and ignores the
- * terminal repeat), a call the CLI did NOT cost is appended to the list but WITHHELD from the
- * live stream — otherwise it records as a zero-token row and the attributed numbers never land.
- * The withholding window closes the moment any call IS costed: attribution can no longer fire, so
- * everything held is final and released at once, in capture order, and every later call streams
- * immediately whatever its tokens. {@link flush} covers the run that was never costed at all.
- */
-export function createCallMetricPublisher(calls, onCallMetric) {
-    const withheld = [];
-    let anyCosted = false;
-    const flush = () => {
-        for (const call of withheld)
-            onCallMetric?.(call);
-        withheld.length = 0;
-    };
-    return {
-        publish(call) {
-            const costed = call.inputTokens > 0 || call.outputTokens > 0;
-            if (!costed && !anyCosted) {
-                publishCallMetric(calls, call);
-                withheld.push(call);
-                return;
-            }
-            if (costed)
-                anyCosted = true;
-            // Released BEFORE this call so the live sequence stays in capture order.
-            flush();
-            publishCallMetric(calls, call, onCallMetric);
-        },
-        flush,
-    };
-}
 /**
  * Pull the `todo` tool's result `details` out of a Pi `--mode json` event, or
  * undefined if the event isn't a successful `todo` tool result.

package/dist/usage-attribution.d.ts

@@ -0,0 +1,56 @@
+import type { HarnessCallMetric } from './pi.js';
+/**
+ * Read Claude Code's terminal cumulative usage.
+ *
+ * Counts every input bucket Anthropic bills: fresh input plus BOTH cache reads and cache writes
+ * (`cache_creation_input_tokens`), which are real consumed tokens and are the dominant share on a
+ * long agent run. Omitting them under-weights a token's true load in the usage-aware rotation
+ * window. `undefined` when the event carried no usage at all, so a caller can tell that from a
+ * genuine zero.
+ */
+export declare function claudeUsage(raw: unknown): {
+    inputTokens: number;
+    outputTokens: number;
+} | undefined;
+/**
+ * The row standing for whatever the per-turn channel did NOT account for: the terminal cumulative
+ * usage minus the sum of the turns already costed, computed PER SIDE. `undefined` when the turns
+ * add up, so nothing is double counted.
+ *
+ * The per-side part is why this exists at all, and it replaced an all-or-nothing guard
+ * (`calls.some(c => c.inputTokens > 0 || c.outputTokens > 0)` ⇒ return) that only ever fired for a
+ * CLI reporting no per-turn usage at all. Claude Code reports plenty: its `assistant` envelopes
+ * carry the message-START usage snapshot, whose INPUT and cache counts are final and whose
+ * `output_tokens` is the 1-5 tokens produced when the message opened. So the guard saw costed
+ * turns, returned, and the run's whole output side stayed at that snapshot. Measured on a real
+ * board: a `coder` step recorded 198 output tokens across 34 calls against the 14,033 the terminal
+ * `result` event reported, an `initiative-analyst` 531 against 30,471. Input matched the terminal
+ * figure exactly, which is what made the shortfall invisible to a check that asked whether ANY
+ * tokens had been reported.
+ *
+ * **It is its OWN row rather than tokens added to the last captured call.** Growing a real turn by
+ * thousands of output tokens it did not produce makes a fabricated number indistinguishable from a
+ * measured one everywhere a per-call figure is read (`/api/v1/debug/*`, the observability panel, a
+ * step's per-call breakdown), and there is nothing on the row to mark it. The sibling rule on the
+ * inline path (`CliInlineLanguageModel.fileUnaccounted`) reached that conclusion first and files a
+ * step-level row; this is the same answer for the channel that has a call list. {@link
+ * HarnessCallMetric.standsForJob} is what keeps it from reading as a turn.
+ *
+ * **`calls` must be the PARENT loop's alone.** The terminal `result` event's cumulative covers the
+ * parent conversation only — a subagent's tokens live in its own transcript — so subtracting a
+ * subagent turn's tokens from it understates the shortfall, and pinning the remainder near one
+ * would bill a conversation for spend it never saw. Both were live in `ambientAuth` mode, where the
+ * CLI streams subagent turns onto the parent's stdout and no transcript watcher runs, so those
+ * turns are captured through the same publisher as the parent's.
+ *
+ * {@link claudeUsage} sums every billed input bucket, so the already-accounted input is the sum of
+ * all THREE per-call input classes, not `inputTokens` (fresh) alone. A residual input shortfall
+ * lands on `inputTokens` because nothing in the terminal event says which class it belonged to.
+ *
+ * Clamped at 0 per side: a CLI whose terminal figure is LOWER than its own per-turn sum has
+ * reported the two inconsistently, and negative spend is not a thing to record.
+ */
+export declare function unaccountedUsageCall(parentCalls: readonly HarnessCallMetric[], usage: {
+    inputTokens: number;
+    outputTokens: number;
+} | undefined): HarnessCallMetric | undefined;

package/dist/usage-attribution.js

@@ -0,0 +1,96 @@
+import { isObject, numberOf } from './claude-stream.js';
+// How a subscription CLI's TWO token channels are reconciled into the per-call rows the backend
+// stores: the per-turn usage the stream narrates, and the cumulative total the terminal `result`
+// event reports. They disagree routinely and in a specific direction, so the reconciliation is a
+// concern of its own rather than a helper beside the stream reader that happens to need it.
+//
+// Split out of `agent-runner.ts` when it hit its size budget.
+/**
+ * Read Claude Code's terminal cumulative usage.
+ *
+ * Counts every input bucket Anthropic bills: fresh input plus BOTH cache reads and cache writes
+ * (`cache_creation_input_tokens`), which are real consumed tokens and are the dominant share on a
+ * long agent run. Omitting them under-weights a token's true load in the usage-aware rotation
+ * window. `undefined` when the event carried no usage at all, so a caller can tell that from a
+ * genuine zero.
+ */
+export function claudeUsage(raw) {
+    if (!isObject(raw))
+        return undefined;
+    const input = numberOf(raw.input_tokens) +
+        numberOf(raw.cache_read_input_tokens) +
+        numberOf(raw.cache_creation_input_tokens);
+    const output = numberOf(raw.output_tokens);
+    if (input === 0 && output === 0)
+        return undefined;
+    return { inputTokens: input, outputTokens: output };
+}
+/**
+ * The row standing for whatever the per-turn channel did NOT account for: the terminal cumulative
+ * usage minus the sum of the turns already costed, computed PER SIDE. `undefined` when the turns
+ * add up, so nothing is double counted.
+ *
+ * The per-side part is why this exists at all, and it replaced an all-or-nothing guard
+ * (`calls.some(c => c.inputTokens > 0 || c.outputTokens > 0)` ⇒ return) that only ever fired for a
+ * CLI reporting no per-turn usage at all. Claude Code reports plenty: its `assistant` envelopes
+ * carry the message-START usage snapshot, whose INPUT and cache counts are final and whose
+ * `output_tokens` is the 1-5 tokens produced when the message opened. So the guard saw costed
+ * turns, returned, and the run's whole output side stayed at that snapshot. Measured on a real
+ * board: a `coder` step recorded 198 output tokens across 34 calls against the 14,033 the terminal
+ * `result` event reported, an `initiative-analyst` 531 against 30,471. Input matched the terminal
+ * figure exactly, which is what made the shortfall invisible to a check that asked whether ANY
+ * tokens had been reported.
+ *
+ * **It is its OWN row rather than tokens added to the last captured call.** Growing a real turn by
+ * thousands of output tokens it did not produce makes a fabricated number indistinguishable from a
+ * measured one everywhere a per-call figure is read (`/api/v1/debug/*`, the observability panel, a
+ * step's per-call breakdown), and there is nothing on the row to mark it. The sibling rule on the
+ * inline path (`CliInlineLanguageModel.fileUnaccounted`) reached that conclusion first and files a
+ * step-level row; this is the same answer for the channel that has a call list. {@link
+ * HarnessCallMetric.standsForJob} is what keeps it from reading as a turn.
+ *
+ * **`calls` must be the PARENT loop's alone.** The terminal `result` event's cumulative covers the
+ * parent conversation only — a subagent's tokens live in its own transcript — so subtracting a
+ * subagent turn's tokens from it understates the shortfall, and pinning the remainder near one
+ * would bill a conversation for spend it never saw. Both were live in `ambientAuth` mode, where the
+ * CLI streams subagent turns onto the parent's stdout and no transcript watcher runs, so those
+ * turns are captured through the same publisher as the parent's.
+ *
+ * {@link claudeUsage} sums every billed input bucket, so the already-accounted input is the sum of
+ * all THREE per-call input classes, not `inputTokens` (fresh) alone. A residual input shortfall
+ * lands on `inputTokens` because nothing in the terminal event says which class it belonged to.
+ *
+ * Clamped at 0 per side: a CLI whose terminal figure is LOWER than its own per-turn sum has
+ * reported the two inconsistently, and negative spend is not a thing to record.
+ */
+export function unaccountedUsageCall(parentCalls, usage) {
+    if (!usage)
+        return undefined;
+    let accountedInput = 0;
+    let accountedOutput = 0;
+    for (const call of parentCalls) {
+        accountedInput += call.inputTokens + call.cacheReadTokens + call.cacheWriteTokens;
+        accountedOutput += call.outputTokens;
+    }
+    const inputTokens = Math.max(0, usage.inputTokens - accountedInput);
+    const outputTokens = Math.max(0, usage.outputTokens - accountedOutput);
+    if (!inputTokens && !outputTokens)
+        return undefined;
+    return {
+        // No `model`: the terminal event names none, and the recorder then files the row under the
+        // model the step DISPATCHED, which is the same answer without this claiming to have observed
+        // it. (Claude Code serves some turns with a different model, so a guess here misprices.)
+        promptText: '',
+        messageCount: 0,
+        responseText: '',
+        reasoningText: '',
+        inputTokens,
+        // Both 0 rather than a split of `inputTokens`: the terminal figure is one number and says
+        // nothing about which input class the remainder belonged to.
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        outputTokens,
+        finishReason: null,
+        standsForJob: true,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.114.0",
+  "version": "1.118.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -30,9 +30,9 @@
     "hono": "^4.13.1",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.296.1",
-    "@cat-factory/server": "0.283.1",
-    "@cat-factory/spend": "0.15.87"
+    "@cat-factory/kernel": "0.298.1",
+    "@cat-factory/server": "0.284.1",
+    "@cat-factory/spend": "0.15.90"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",