@cat-factory/executor-harness 1.68.0 → 1.70.0

package/README.md

@@ -57,7 +57,12 @@ The implementation job (`POST /run`) is the canonical sequence:
    to Pi's **global** context file `~/.pi/agent/AGENTS.md` (outside the checkout,
    so it never lands in a commit and never clobbers a repo's own `AGENTS.md` —
    Pi reads and concatenates both), and point Pi at the Worker's LLM proxy via
-   `~/.pi/agent/models.json` (provider `proxy`, `api: openai-completions`),
+   `~/.pi/agent/models.json` (provider `proxy`, `api: openai-completions`) — at the
+   phase-tagged completions path for the pass about to run (`.../phase/<phase>`) when the job
+   body's `proxyPhasePath` says the backend serves it, which is how a repair round's model spend
+   stays distinguishable from the first pass's in telemetry; without that flag the plain path is
+   used and the calls are recorded as unattributed
+   (see [token-burn instrumentation](../../../docs/initiatives/token-burn-instrumentation.md)),
 3. **run Pi** non-interactively (`pi -p --mode json --model proxy/<model> --approve`),
 4. **validate** the checkout, when the job body carries `validationChecks` — the service's
    configured check commands (install/lint/test/build) run with `sh -c` in the checkout, and

package/dist/agent.js

@@ -183,6 +183,7 @@ async function resolveReplyCustom(job, summary, signal) {
         subscriptionToken: job.subscriptionToken,
         subscriptionBaseUrl: job.subscriptionBaseUrl,
         proxyBaseUrl: job.proxyBaseUrl,
+        proxyPhasePath: job.proxyPhasePath,
         sessionToken: job.sessionToken,
         model: job.model,
         jobId: job.jobId,
@@ -488,6 +489,7 @@ async function runExploreMode(job, opts) {
                 subscriptionBaseUrl: job.subscriptionBaseUrl,
                 ambientAuth: job.ambientAuth,
                 proxyBaseUrl: job.proxyBaseUrl,
+                proxyPhasePath: job.proxyPhasePath,
                 sessionToken: job.sessionToken,
                 serviceDirectory,
                 // Read-only: it inspects and reports, making no edits — so the no-progress
@@ -678,6 +680,7 @@ async function runMultiRepoExplore(job, opts) {
             subscriptionBaseUrl: job.subscriptionBaseUrl,
             ambientAuth: job.ambientAuth,
             proxyBaseUrl: job.proxyBaseUrl,
+            proxyPhasePath: job.proxyPhasePath,
             sessionToken: job.sessionToken,
             // Read-only: no edits expected, so the no-progress guard's no-edit bound must not fire.
             expectsEdits: false,
@@ -780,6 +783,7 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
         subscriptionBaseUrl: job.subscriptionBaseUrl,
         ambientAuth: job.ambientAuth,
         proxyBaseUrl: job.proxyBaseUrl,
+        proxyPhasePath: job.proxyPhasePath,
         sessionToken: job.sessionToken,
         commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
         webToolsGuidance: job.webToolsGuidance,
@@ -1032,6 +1036,7 @@ async function runConflictResolution(job, opts) {
             subscriptionBaseUrl: job.subscriptionBaseUrl,
             ambientAuth: job.ambientAuth,
             proxyBaseUrl: job.proxyBaseUrl,
+            proxyPhasePath: job.proxyPhasePath,
             sessionToken: job.sessionToken,
             contextFiles: job.contextFiles,
             guardLimits: job.guardLimits,

package/dist/bootstrap-mode.js

@@ -52,6 +52,7 @@ export async function runBootstrap(job, opts) {
             subscriptionBaseUrl: job.subscriptionBaseUrl,
             ambientAuth: job.ambientAuth,
             proxyBaseUrl: job.proxyBaseUrl,
+            proxyPhasePath: job.proxyPhasePath,
             sessionToken: job.sessionToken,
             guardLimits: job.guardLimits,
             ...agentCapabilities(job),

package/dist/coding-agent.js

@@ -146,6 +146,7 @@ export async function runCodingAgent(spec, opts = {}) {
             subscriptionBaseUrl: spec.subscriptionBaseUrl,
             ambientAuth: spec.ambientAuth,
             proxyBaseUrl: spec.proxyBaseUrl,
+            proxyPhasePath: spec.proxyPhasePath,
             sessionToken: spec.sessionToken,
             serviceDirectory,
             webToolsGuidance: spec.webToolsGuidance,
@@ -716,6 +717,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
             subscriptionBaseUrl: job.subscriptionBaseUrl,
             ambientAuth: job.ambientAuth,
             proxyBaseUrl: job.proxyBaseUrl,
+            proxyPhasePath: job.proxyPhasePath,
             sessionToken: job.sessionToken,
             webToolsGuidance: job.webToolsGuidance,
             webSearchProxy: job.webSearch,

package/dist/job.js

@@ -96,6 +96,8 @@ function parseHarnessAuth(o) {
         harness,
         proxyBaseUrl: str(o.proxyBaseUrl, 'proxyBaseUrl'),
         sessionToken: str(o.sessionToken, 'sessionToken'),
+        // Opt-IN, so a backend that doesn't serve the phase route (or predates it) is the default.
+        ...(o.proxyPhasePath === true ? { proxyPhasePath: true } : {}),
     };
 }
 /**

package/dist/pi-workspace.js

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { readEffortReport } from './effort.js';
 import { log } from './logger.js';
-import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
+import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, phasedProxyBaseUrl, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
 import { mergeGuardLimits, progressGuardLimitsFromEnv, } from './progress-guard.js';
 import { runSubscriptionHarness } from './agent-runner.js';
 // The thin base every container agent shares: an ephemeral working directory, and
@@ -221,7 +221,15 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         hasBlueprints,
         ...(spec.multiRepo ? { multiRepo: true } : {}),
     });
-    await writePiModelsConfig({ model: spec.model, proxyBaseUrl });
+    // Pi's calls are metered server-side by the LLM proxy, which sees only an HTTP request — so
+    // the phase this pass runs under is carried on the URL it is pointed at. Resolved per pass
+    // (this whole function re-runs for every repair round), which is what makes a repair round's
+    // spend distinguishable from the first pass's. Only when the BACKEND said it serves that
+    // route, since a runner pool or `LOCAL_HARNESS_IMAGE` can pair this image with an older one.
+    await writePiModelsConfig({
+        model: spec.model,
+        proxyBaseUrl: phasedProxyBaseUrl(proxyBaseUrl, opts.currentPhase?.(), spec.proxyPhasePath),
+    });
     const { signal, onActivity, onProgress, onSpan } = opts;
     const piOutcome = await runPi({
         cwd: spec.dir,

package/dist/pi.js

@@ -24,6 +24,63 @@ import { ProgressGuard, progressGuardLimitsFromEnv, toolCallSignal, } from './pr
  * {@link runDiagnostics} flagging the rare case where even 32k is not enough.
  */
 export const PI_MAX_OUTPUT_TOKENS = 32_768;
+/**
+ * Longest phase label the backend keeps. Mirrors kernel's `MAX_PHASE_CHARS`; see
+ * {@link normalizeProxyPhase} for why this is a copy rather than an import.
+ */
+const MAX_PHASE_CHARS = 32;
+/**
+ * Normalise a phase label to what the backend will actually store: trimmed, lowercased,
+ * `[a-z0-9-]` only, bounded. `''` when the label is not a phase at all.
+ *
+ * A deliberate COPY of kernel's `normalizeCallPhase` — the container image is built from `src/`
+ * plus typescript alone, so the harness can carry no runtime dependency on a workspace package
+ * (the same constraint that forced `src/host-markdown.ts`). A copy that can drift is worse than
+ * no copy: if the harness rejected a label the backend would have accepted, the call would take
+ * the plain path and land unattributed, and if it accepted one the backend rejects it would
+ * spend a request on a segment destined for `''`. `test/llm-phase.conformity.test.ts` pins the
+ * two to identical verdicts over a corpus, so the alphabet can only be changed in both.
+ */
+export function normalizeProxyPhase(phase) {
+    if (typeof phase !== 'string')
+        return '';
+    const trimmed = phase.trim().toLowerCase();
+    if (!trimmed || trimmed.length > MAX_PHASE_CHARS)
+        return '';
+    return /^[a-z0-9-]+$/.test(trimmed) ? trimmed : '';
+}
+/**
+ * Point Pi's provider at the phase-tagged completions path for the pass about to run, so the
+ * backend can stamp WHICH slice of the run spent each call (the agent's own loop vs a pre-PR
+ * validation repair round vs a reproduction-proof repair round) — see
+ * `docs/initiatives/token-burn-instrumentation.md`. The harness drives those loops, so it is
+ * the only component that knows; reconstructing the boundary downstream from wall-clock
+ * timestamps is exactly the brittle inference this avoids.
+ *
+ * A URL segment because the harness does not make these requests: Pi does, from a config whose
+ * only per-run knobs are the base URL and the token — there is no per-request header to set.
+ *
+ * `supported` is the BACKEND's declaration that it serves the phase-tagged route, carried on the
+ * job body exactly as `webSearch` carries "point the search tool at my `/web-search`". Without it
+ * this function would encode a routing shape the receiving backend may not have: a runner pool
+ * pins its OWN harness image (`RunnerPoolManifest`), and `LOCAL_HARNESS_IMAGE` overrides the
+ * recommended pin outright, so "the image and the backend are a matched set" holds for the
+ * Cloudflare deployment and nowhere else. An image ahead of its backend would 404 EVERY model
+ * call — a dead run, not degraded telemetry. Absent/false ⇒ the plain path, and the calls land
+ * in the backend's unattributed slice.
+ *
+ * Pure so the join is unit-testable without spawning anything.
+ */
+export function phasedProxyBaseUrl(proxyBaseUrl, phase, supported) {
+    if (!supported)
+        return proxyBaseUrl;
+    // A label the backend would discard would be sent only to be thrown away, so send the plain
+    // path instead — the call is then honestly unattributed rather than attributed to nothing.
+    const normalized = normalizeProxyPhase(phase);
+    if (!normalized)
+        return proxyBaseUrl;
+    return `${proxyBaseUrl.replace(/\/+$/, '')}/phase/${normalized}`;
+}
 /** Write the Pi provider config that routes all model calls through the proxy. */
 export async function writePiModelsConfig(opts) {
     const dir = join(homedir(), '.pi', 'agent');

package/dist/runner.js

@@ -224,9 +224,17 @@ export class JobRegistry {
                     // instance for its terminal result, so both channels carry the same `seq` and the
                     // backend mints one stable row id per call.
                     call.seq = entry.callMetricSeq++;
+                    // …and the phase the job is in RIGHT NOW, which is what spent the call: the handlers
+                    // mark `validation-repair` / `reproduction-repair` around each repair pass, so a
+                    // looped run's telemetry says which loop the tokens went to instead of filing every
+                    // turn under one undifferentiated "agent"
+                    // (`docs/initiatives/token-burn-instrumentation.md`). Stamped at EMIT time, not at
+                    // drain time: a poll can land long after the phase moved on.
+                    call.phase = phase;
                     entry.callMetricBuffer.push(call);
                 },
                 onPhase: (next) => markPhase(next),
+                currentPhase: () => phase,
                 log: jobLog,
             });
             markPhase('done');

package/dist/structured-output.js

@@ -1,6 +1,6 @@
 import { redact, redactSecrets, secretsToRedact } from './redact.js';
 import { log } from './logger.js';
-import { PI_MAX_OUTPUT_TOKENS } from './pi.js';
+import { PI_MAX_OUTPUT_TOKENS, phasedProxyBaseUrl } from './pi.js';
 // A reusable abstraction for the "agent returns a structured JSON document as its
 // final assistant message" pattern (requirements, blueprint, merger — and any future
 // kind). An agent of this kind emits its result as text, not a tool call, and the
@@ -31,6 +31,12 @@ const REPAIR_SYSTEM = 'You repair malformed JSON. You are given text that was me
     'JSON object but does not parse. Return ONLY the corrected JSON object: no prose, ' +
     'no markdown code fences, no commentary, and never repeat or duplicate any tokens. ' +
     'Preserve the original content faithfully; only fix the JSON structure.';
+/**
+ * The run phase a structured-output repair call is billed to. A constant, not a `currentPhase`
+ * read: this call is made by the harness itself (the agent has already finished and left text
+ * that won't parse), so it belongs to no pass the registry marks.
+ */
+const STRUCTURED_REPAIR_PHASE = 'structured-repair';
 /**
  * Largest immediately-repeated run length we look for. The corruption duplicates
  * whole model tokens, which carry whitespace/punctuation context and run to ~10-15
@@ -195,7 +201,12 @@ async function callRepair(badText, spec, access) {
     if (!access.proxyBaseUrl || !access.sessionToken) {
         throw new Error('structured-output repair requires the LLM proxy (Pi harness)');
     }
-    const url = `${access.proxyBaseUrl.replace(/\/+$/, '')}/chat/completions`;
+    // A repair round is its own slice of the run's burn, not part of the agent's loop that
+    // produced the unparseable text — and unlike the phases the registry marks, this call is made
+    // by the HARNESS itself, so its phase is a constant rather than a read of `currentPhase`
+    // (docs/initiatives/token-burn-instrumentation.md).
+    const repairBaseUrl = phasedProxyBaseUrl(access.proxyBaseUrl, STRUCTURED_REPAIR_PHASE, access.proxyPhasePath);
+    const url = `${repairBaseUrl.replace(/\/+$/, '')}/chat/completions`;
     const messages = [
         { role: 'system', content: REPAIR_SYSTEM },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.68.0",
+  "version": "1.70.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",
@@ -26,9 +26,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.176.0",
-    "@cat-factory/server": "0.166.0",
-    "@cat-factory/spend": "0.12.105"
+    "@cat-factory/kernel": "0.179.0",
+    "@cat-factory/server": "0.167.0",
+    "@cat-factory/spend": "0.12.108"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -255,6 +255,7 @@ async function resolveReplyCustom(
       subscriptionToken: job.subscriptionToken,
       subscriptionBaseUrl: job.subscriptionBaseUrl,
       proxyBaseUrl: job.proxyBaseUrl,
+      proxyPhasePath: job.proxyPhasePath,
       sessionToken: job.sessionToken,
       model: job.model,
       jobId: job.jobId,
@@ -589,6 +590,7 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
             subscriptionBaseUrl: job.subscriptionBaseUrl,
             ambientAuth: job.ambientAuth,
             proxyBaseUrl: job.proxyBaseUrl,
+            proxyPhasePath: job.proxyPhasePath,
             sessionToken: job.sessionToken,
             serviceDirectory,
             // Read-only: it inspects and reports, making no edits — so the no-progress
@@ -820,6 +822,7 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
         subscriptionBaseUrl: job.subscriptionBaseUrl,
         ambientAuth: job.ambientAuth,
         proxyBaseUrl: job.proxyBaseUrl,
+        proxyPhasePath: job.proxyPhasePath,
         sessionToken: job.sessionToken,
         // Read-only: no edits expected, so the no-progress guard's no-edit bound must not fire.
         expectsEdits: false,
@@ -938,6 +941,7 @@ function buildSingleRepoCodingSpec(
     subscriptionBaseUrl: job.subscriptionBaseUrl,
     ambientAuth: job.ambientAuth,
     proxyBaseUrl: job.proxyBaseUrl,
+    proxyPhasePath: job.proxyPhasePath,
     sessionToken: job.sessionToken,
     commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
     webToolsGuidance: job.webToolsGuidance,
@@ -1217,6 +1221,7 @@ async function runConflictResolution(job: AgentJob, opts: RunOptions): Promise<A
           subscriptionBaseUrl: job.subscriptionBaseUrl,
           ambientAuth: job.ambientAuth,
           proxyBaseUrl: job.proxyBaseUrl,
+          proxyPhasePath: job.proxyPhasePath,
           sessionToken: job.sessionToken,
           contextFiles: job.contextFiles,
           guardLimits: job.guardLimits,

package/src/bootstrap-mode.ts

@@ -65,6 +65,7 @@ export async function runBootstrap(job: AgentJob, opts: RunOptions): Promise<Age
           subscriptionBaseUrl: job.subscriptionBaseUrl,
           ambientAuth: job.ambientAuth,
           proxyBaseUrl: job.proxyBaseUrl,
+          proxyPhasePath: job.proxyPhasePath,
           sessionToken: job.sessionToken,
           guardLimits: job.guardLimits,
           ...agentCapabilities(job),

package/src/coding-agent.ts

@@ -93,6 +93,8 @@ export interface CodingAgentSpec extends HarnessAuthFields {
   webToolsGuidance?: string
   /** Enable proxy-backed web search for this run (see {@link AgentRunSpec.webSearchProxy}). */
   webSearchProxy?: boolean
+  /** Backend serves the phase-tagged completions route (see {@link AgentRunSpec.proxyPhasePath}). */
+  proxyPhasePath?: boolean
   /** Per-knob progress-guard overrides (loosen-only), set per agent kind by the backend. */
   guardLimits?: Partial<ProgressGuardLimits>
   /**
@@ -352,6 +354,7 @@ export async function runCodingAgent(
             subscriptionBaseUrl: spec.subscriptionBaseUrl,
             ambientAuth: spec.ambientAuth,
             proxyBaseUrl: spec.proxyBaseUrl,
+            proxyPhasePath: spec.proxyPhasePath,
             sessionToken: spec.sessionToken,
             serviceDirectory,
             webToolsGuidance: spec.webToolsGuidance,
@@ -1052,6 +1055,7 @@ export async function runMultiRepoCoding(
           subscriptionBaseUrl: job.subscriptionBaseUrl,
           ambientAuth: job.ambientAuth,
           proxyBaseUrl: job.proxyBaseUrl,
+          proxyPhasePath: job.proxyPhasePath,
           sessionToken: job.sessionToken,
           webToolsGuidance: job.webToolsGuidance,
           webSearchProxy: job.webSearch,

package/src/job.ts

@@ -38,6 +38,20 @@ export interface HarnessAuthFields {
   harness?: HarnessKind
   /** Worker LLM proxy base URL, including /v1 (Pi harness only). */
   proxyBaseUrl?: string
+  /**
+   * The backend declaring that it serves the phase-tagged completions route
+   * (`${proxyBaseUrl}/phase/<phase>/chat/completions`), so this run may attribute each model
+   * call to the phase that spent it (`docs/initiatives/token-burn-instrumentation.md`). The
+   * same shape as {@link AgentJob.webSearch}: the backend states what IT serves, and the
+   * harness points Pi accordingly.
+   *
+   * Not a capability handshake — the harness never asks and never adapts to an answer. It
+   * exists because the harness image and the backend are only a matched set on the Cloudflare
+   * deployment: a runner pool pins its own image and `LOCAL_HARNESS_IMAGE` overrides the
+   * recommended pin, so an image ahead of its backend would otherwise 404 every model call.
+   * Absent ⇒ the plain path, and the run's calls are recorded as unattributed.
+   */
+  proxyPhasePath?: boolean
   /** Signed, model-locked proxy session token (Pi harness only). */
   sessionToken?: string
   /** Leased subscription credential (Claude Code OAuth token / Codex auth.json). */
@@ -222,6 +236,8 @@ function parseHarnessAuth(o: Record<string, unknown>): HarnessAuthFields {
     harness,
     proxyBaseUrl: str(o.proxyBaseUrl, 'proxyBaseUrl'),
     sessionToken: str(o.sessionToken, 'sessionToken'),
+    // Opt-IN, so a backend that doesn't serve the phase route (or predates it) is the default.
+    ...(o.proxyPhasePath === true ? { proxyPhasePath: true } : {}),
   }
 }
 

package/src/pi-workspace.ts

@@ -13,6 +13,7 @@ import {
   CONTEXT_DIR,
   materializeContextFiles,
   materializeSkillResources,
+  phasedProxyBaseUrl,
   runPi,
   webSearchConfigFromEnv,
   webSearchProxyEnv,
@@ -173,6 +174,12 @@ export interface AgentRunSpec {
   ambientAuth?: boolean
   /** Pi proxy base URL (Pi harness only). */
   proxyBaseUrl?: string
+  /**
+   * The backend serves the phase-tagged completions route, so this pass may tag the URL it
+   * points Pi at with the phase it is running under (see {@link HarnessAuthFields.proxyPhasePath}
+   * and `phasedProxyBaseUrl`). Absent ⇒ the plain path.
+   */
+  proxyPhasePath?: boolean
   /** Pi proxy session token (Pi harness only). */
   sessionToken?: string
   /**
@@ -356,7 +363,15 @@ export async function runAgentInWorkspace(
     hasBlueprints,
     ...(spec.multiRepo ? { multiRepo: true } : {}),
   })
-  await writePiModelsConfig({ model: spec.model, proxyBaseUrl })
+  // Pi's calls are metered server-side by the LLM proxy, which sees only an HTTP request — so
+  // the phase this pass runs under is carried on the URL it is pointed at. Resolved per pass
+  // (this whole function re-runs for every repair round), which is what makes a repair round's
+  // spend distinguishable from the first pass's. Only when the BACKEND said it serves that
+  // route, since a runner pool or `LOCAL_HARNESS_IMAGE` can pair this image with an older one.
+  await writePiModelsConfig({
+    model: spec.model,
+    proxyBaseUrl: phasedProxyBaseUrl(proxyBaseUrl, opts.currentPhase?.(), spec.proxyPhasePath),
+  })
   const { signal, onActivity, onProgress, onSpan } = opts
   const piOutcome = await runPi({
     cwd: spec.dir,

package/src/pi.ts

@@ -33,6 +33,66 @@ import {
  */
 export const PI_MAX_OUTPUT_TOKENS = 32_768
 
+/**
+ * Longest phase label the backend keeps. Mirrors kernel's `MAX_PHASE_CHARS`; see
+ * {@link normalizeProxyPhase} for why this is a copy rather than an import.
+ */
+const MAX_PHASE_CHARS = 32
+
+/**
+ * Normalise a phase label to what the backend will actually store: trimmed, lowercased,
+ * `[a-z0-9-]` only, bounded. `''` when the label is not a phase at all.
+ *
+ * A deliberate COPY of kernel's `normalizeCallPhase` — the container image is built from `src/`
+ * plus typescript alone, so the harness can carry no runtime dependency on a workspace package
+ * (the same constraint that forced `src/host-markdown.ts`). A copy that can drift is worse than
+ * no copy: if the harness rejected a label the backend would have accepted, the call would take
+ * the plain path and land unattributed, and if it accepted one the backend rejects it would
+ * spend a request on a segment destined for `''`. `test/llm-phase.conformity.test.ts` pins the
+ * two to identical verdicts over a corpus, so the alphabet can only be changed in both.
+ */
+export function normalizeProxyPhase(phase: string | undefined): string {
+  if (typeof phase !== 'string') return ''
+  const trimmed = phase.trim().toLowerCase()
+  if (!trimmed || trimmed.length > MAX_PHASE_CHARS) return ''
+  return /^[a-z0-9-]+$/.test(trimmed) ? trimmed : ''
+}
+
+/**
+ * Point Pi's provider at the phase-tagged completions path for the pass about to run, so the
+ * backend can stamp WHICH slice of the run spent each call (the agent's own loop vs a pre-PR
+ * validation repair round vs a reproduction-proof repair round) — see
+ * `docs/initiatives/token-burn-instrumentation.md`. The harness drives those loops, so it is
+ * the only component that knows; reconstructing the boundary downstream from wall-clock
+ * timestamps is exactly the brittle inference this avoids.
+ *
+ * A URL segment because the harness does not make these requests: Pi does, from a config whose
+ * only per-run knobs are the base URL and the token — there is no per-request header to set.
+ *
+ * `supported` is the BACKEND's declaration that it serves the phase-tagged route, carried on the
+ * job body exactly as `webSearch` carries "point the search tool at my `/web-search`". Without it
+ * this function would encode a routing shape the receiving backend may not have: a runner pool
+ * pins its OWN harness image (`RunnerPoolManifest`), and `LOCAL_HARNESS_IMAGE` overrides the
+ * recommended pin outright, so "the image and the backend are a matched set" holds for the
+ * Cloudflare deployment and nowhere else. An image ahead of its backend would 404 EVERY model
+ * call — a dead run, not degraded telemetry. Absent/false ⇒ the plain path, and the calls land
+ * in the backend's unattributed slice.
+ *
+ * Pure so the join is unit-testable without spawning anything.
+ */
+export function phasedProxyBaseUrl(
+  proxyBaseUrl: string,
+  phase: string | undefined,
+  supported: boolean | undefined,
+): string {
+  if (!supported) return proxyBaseUrl
+  // A label the backend would discard would be sent only to be thrown away, so send the plain
+  // path instead — the call is then honestly unattributed rather than attributed to nothing.
+  const normalized = normalizeProxyPhase(phase)
+  if (!normalized) return proxyBaseUrl
+  return `${proxyBaseUrl.replace(/\/+$/, '')}/phase/${normalized}`
+}
+
 /** Write the Pi provider config that routes all model calls through the proxy. */
 export async function writePiModelsConfig(opts: {
   model: string
@@ -548,6 +608,17 @@ export interface HarnessCallMetric {
    * falls back to the array index, which is what it always used before streaming existed.
    */
   seq?: number
+  /**
+   * The run PHASE that spent this call (`agent` / `validation-repair` / `reproduction-repair` /
+   * …), stamped by the job registry from the same marker the handlers set as they enter each
+   * phase — so the phase axis on `llm_call_metrics` comes from the component that owns the
+   * boundary rather than from a downstream guess
+   * (`docs/initiatives/token-burn-instrumentation.md`).
+   *
+   * Stamped on the SAME object as {@link seq}, so the live drain and the terminal result can
+   * never disagree about which phase billed a call.
+   */
+  phase?: string
 }
 
 /**

package/src/runner.ts

@@ -66,6 +66,15 @@ export interface RunOptions {
    * per-phase wall-clock is logged on completion. Free-form; unknown phases just show verbatim.
    */
   onPhase?: (phase: string) => void
+  /**
+   * The phase most recently marked via {@link onPhase} — the read side of the same marker, for
+   * work that has to TELL the backend which phase it is in rather than merely record it. Today
+   * that is the Pi path, whose calls are metered server-side by the LLM proxy: the harness tags
+   * the proxy URL with this so a repair round's spend is attributable
+   * (`docs/initiatives/token-burn-instrumentation.md`). Absent ⇒ no phase is carried and those
+   * calls land in the backend's unattributed slice.
+   */
+  currentPhase?: () => string
   /** A per-job child logger carrying the run's correlation fields (jobId, repo, branch, …). */
   log?: Logger
   /**
@@ -468,9 +477,17 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
           // instance for its terminal result, so both channels carry the same `seq` and the
           // backend mints one stable row id per call.
           call.seq = entry.callMetricSeq++
+          // …and the phase the job is in RIGHT NOW, which is what spent the call: the handlers
+          // mark `validation-repair` / `reproduction-repair` around each repair pass, so a
+          // looped run's telemetry says which loop the tokens went to instead of filing every
+          // turn under one undifferentiated "agent"
+          // (`docs/initiatives/token-burn-instrumentation.md`). Stamped at EMIT time, not at
+          // drain time: a poll can land long after the phase moved on.
+          call.phase = phase
           entry.callMetricBuffer.push(call)
         },
         onPhase: (next) => markPhase(next),
+        currentPhase: () => phase,
         log: jobLog,
       })
       markPhase('done')

package/src/structured-output.ts

@@ -1,6 +1,6 @@
 import { redact, redactSecrets, secretsToRedact } from './redact.js'
 import { log } from './logger.js'
-import { PI_MAX_OUTPUT_TOKENS } from './pi.js'
+import { PI_MAX_OUTPUT_TOKENS, phasedProxyBaseUrl } from './pi.js'
 
 // A reusable abstraction for the "agent returns a structured JSON document as its
 // final assistant message" pattern (requirements, blueprint, merger — and any future
@@ -52,10 +52,23 @@ export interface StructuredOutputSpec<T> {
   parse: (text: string) => T | null
 }
 
+/**
+ * The run phase a structured-output repair call is billed to. A constant, not a `currentPhase`
+ * read: this call is made by the harness itself (the agent has already finished and left text
+ * that won't parse), so it belongs to no pass the registry marks.
+ */
+const STRUCTURED_REPAIR_PHASE = 'structured-repair'
+
 /** Runtime wiring to reach the LLM proxy for the repair call. */
 export interface ProxyAccess {
   /** Pi-harness proxy base URL; absent for subscription harnesses (no proxy repair). */
   proxyBaseUrl?: string
+  /**
+   * The backend serves the phase-tagged completions route, so the repair call can be attributed
+   * to {@link STRUCTURED_REPAIR_PHASE} rather than piling into the unattributed slice
+   * (see {@link HarnessAuthFields.proxyPhasePath}).
+   */
+  proxyPhasePath?: boolean
   /** Pi-harness proxy session token; absent for subscription harnesses. */
   sessionToken?: string
   model: string
@@ -266,7 +279,16 @@ async function callRepair<T>(
   if (!access.proxyBaseUrl || !access.sessionToken) {
     throw new Error('structured-output repair requires the LLM proxy (Pi harness)')
   }
-  const url = `${access.proxyBaseUrl.replace(/\/+$/, '')}/chat/completions`
+  // A repair round is its own slice of the run's burn, not part of the agent's loop that
+  // produced the unparseable text — and unlike the phases the registry marks, this call is made
+  // by the HARNESS itself, so its phase is a constant rather than a read of `currentPhase`
+  // (docs/initiatives/token-burn-instrumentation.md).
+  const repairBaseUrl = phasedProxyBaseUrl(
+    access.proxyBaseUrl,
+    STRUCTURED_REPAIR_PHASE,
+    access.proxyPhasePath,
+  )
+  const url = `${repairBaseUrl.replace(/\/+$/, '')}/chat/completions`
   const messages = [
     { role: 'system', content: REPAIR_SYSTEM },
     {