@cat-factory/executor-harness 1.50.14 → 1.50.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.50.14",
+  "version": "1.50.18",
   "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,8 +26,8 @@
     "hono": "^4.12.30",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.141.3",
-    "@cat-factory/spend": "0.12.73"
+    "@cat-factory/server": "0.143.1",
+    "@cat-factory/spend": "0.12.75"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -424,21 +424,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     await writeNativeSkill(skillsRoot, opts.skill).catch(() => {})
   }
 
-  // Anthropic itself authenticates with the subscription OAuth token; a
-  // non-Anthropic Claude-Code vendor (GLM via Z.ai, Kimi via Moonshot, DeepSeek)
-  // points Claude Code at its Anthropic-compatible endpoint with an auth-token key.
-  // Ambient mode injects neither — the CLI uses the developer's logged-in `~/.claude`.
-  const env: Record<string, string> = opts.ambientAuth
-    ? {}
-    : {
-        CLAUDE_CONFIG_DIR: configHome!,
-        ...(opts.subscriptionBaseUrl
-          ? {
-              ANTHROPIC_BASE_URL: opts.subscriptionBaseUrl,
-              ANTHROPIC_AUTH_TOKEN: opts.subscriptionToken!,
-            }
-          : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken! }),
-      }
+  const env = buildClaudeEnv(opts, configHome)
 
   // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
   // subagent `*.jsonl` transcripts so a parallel-subagent review keeps the inactivity
@@ -484,39 +470,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       onEvent,
     )
 
-    // The parent's cumulative-usage fallback applies to the PARENT calls only (before the
-    // subagent calls, which carry their own per-turn tokens, are concatenated).
-    attributeCumulativeUsage(calls, usage)
-    // Final drain of any subagent transcript writes that landed after the last poll, then
-    // fold the subagents' usage + per-call telemetry into the run's outcome — their tokens
-    // never appear on the parent stream, so this is the only place they are accounted.
-    await subagents?.stop()
-    const subUsage = subagents?.usage() ?? { inputTokens: 0, outputTokens: 0 }
-    const subCalls = subagents?.calls() ?? []
-    const mergedCalls = [...calls, ...subCalls]
-    // INVARIANT (do not "fix" this into a double count): the run total is the parent usage
-    // PLUS the subagent usage because the two are disjoint sources. The parent `usage` here
-    // is the terminal `result` event's cumulative, which covers ONLY the parent loop — the
-    // ADR 0026 incident is itself the proof: a heavily subagent-parallelised review reported
-    // ~0 tokens, i.e. the parent stream (and its `result` total) never included the subagent
-    // spend. The subagent tokens live exclusively in the per-session `subagents/*.jsonl`
-    // transcripts, which the watcher reads and nothing else does; it deliberately EXCLUDES the
-    // sibling parent session transcript (whose usage `result` already totals), so neither
-    // `calls` nor `usage` can already contain the subagent spend.
-    const mergedUsage =
-      usage || subUsage.inputTokens || subUsage.outputTokens
-        ? {
-            inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,
-            outputTokens: (usage?.outputTokens ?? 0) + subUsage.outputTokens,
-          }
-        : undefined
-    return {
-      summary,
-      stats,
-      stderrTail,
-      ...(mergedUsage ? { usage: mergedUsage } : {}),
-      ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
-    }
+    return await assembleClaudeOutcome({ summary, stats, stderrTail, calls, usage, subagents })
   } finally {
     await subagents?.stop()
     if (configHome) {
@@ -533,6 +487,71 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   }
 }
 
+/**
+ * Build the child-process env for the `claude` CLI: an isolated config home plus subscription
+ * auth (Anthropic OAuth token, or an Anthropic-compatible base URL + auth token for a
+ * non-Anthropic Claude-Code vendor like GLM/Kimi/DeepSeek), or an empty env in ambient mode
+ * (the developer's own logged-in `~/.claude` is used). Extracted from {@link runClaudeCode} to
+ * keep its cyclomatic complexity down; behaviour is a straight move of the original expression.
+ */
+function buildClaudeEnv(
+  opts: SubscriptionRunOptions,
+  configHome: string | undefined,
+): Record<string, string> {
+  if (opts.ambientAuth) return {}
+  return {
+    CLAUDE_CONFIG_DIR: configHome!,
+    ...(opts.subscriptionBaseUrl
+      ? {
+          ANTHROPIC_BASE_URL: opts.subscriptionBaseUrl,
+          ANTHROPIC_AUTH_TOKEN: opts.subscriptionToken!,
+        }
+      : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken! }),
+  }
+}
+
+/**
+ * Merge the parent-loop telemetry with the subagents' out-of-band usage + per-call metrics into
+ * the run outcome. INVARIANT (do not "fix" this into a double count): the run total is the parent
+ * usage PLUS the subagent usage because the two are disjoint sources — the parent `usage` (the
+ * terminal `result` event's cumulative) covers ONLY the parent loop, and the subagent tokens live
+ * exclusively in the per-session `subagents/*.jsonl` transcripts the watcher reads. Extracted from
+ * {@link runClaudeCode} verbatim to keep its cyclomatic complexity down.
+ */
+async function assembleClaudeOutcome(args: {
+  summary: string
+  stats: PiRunStats
+  stderrTail: string
+  calls: HarnessCallMetric[]
+  usage: { inputTokens: number; outputTokens: number } | undefined
+  subagents: ReturnType<typeof startSubagentWatcher> | undefined
+}): Promise<PiRunOutcome> {
+  const { summary, stats, stderrTail, calls, usage, subagents } = args
+  // The parent's cumulative-usage fallback applies to the PARENT calls only (before the
+  // subagent calls, which carry their own per-turn tokens, are concatenated).
+  attributeCumulativeUsage(calls, usage)
+  // Final drain of any subagent transcript writes that landed after the last poll, then
+  // fold the subagents' usage + per-call telemetry into the run's outcome.
+  await subagents?.stop()
+  const subUsage = subagents?.usage() ?? { inputTokens: 0, outputTokens: 0 }
+  const subCalls = subagents?.calls() ?? []
+  const mergedCalls = [...calls, ...subCalls]
+  const mergedUsage =
+    usage || subUsage.inputTokens || subUsage.outputTokens
+      ? {
+          inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,
+          outputTokens: (usage?.outputTokens ?? 0) + subUsage.outputTokens,
+        }
+      : undefined
+  return {
+    summary,
+    stats,
+    stderrTail,
+    ...(mergedUsage ? { usage: mergedUsage } : {}),
+    ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
+  }
+}
+
 /** Map Claude Code's `TodoWrite` todos array onto subtask counts. */
 function todosToProgress(todos: unknown): TodoProgress | undefined {
   if (!Array.isArray(todos)) return undefined

package/src/agent.ts

@@ -31,6 +31,7 @@ import {
   unmergedPaths,
 } from './git.js'
 import type { PiRunStats, RunDiagnostics } from './pi.js'
+import type { EffortReport } from './effort.js'
 import {
   makeDirClaimer,
   noChangesReason,
@@ -312,6 +313,15 @@ async function cloneServiceCheckout(
   return deriveWorkDir(dir, job.repo.serviceDirectory)
 }
 
+/**
+ * Fold an agent's effort self-assessment (lifted from its sentinel file by `runAgentInWorkspace`)
+ * onto its final result. Every container mode routes its result through this so the report reaches
+ * the backend uniformly. A run that wrote no report passes through unchanged.
+ */
+function mergeEffort(result: AgentResult, effortReport: EffortReport | undefined): AgentResult {
+  return effortReport ? { ...result, effortReport } : result
+}
+
 /** Run one generic agent job end to end, dispatching on `mode`. */
 export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise<AgentResult> {
   // Private-registry auth first, before any mode runs: every mode with a checkout may
@@ -558,6 +568,7 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
           usage,
           callMetrics,
           diagnostics: runDiag,
+          effortReport,
         } = await runAgentInWorkspace(
           {
             dir: workDir,
@@ -582,10 +593,13 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
           opts,
         )
 
-        return await finalizeExploreResult(
-          job,
-          { summary, stats, stderrTail, usage, callMetrics, runDiag },
-          { infra, infraSetupFields, logger, signal: opts.signal },
+        return mergeEffort(
+          await finalizeExploreResult(
+            job,
+            { summary, stats, stderrTail, usage, callMetrics, runDiag },
+            { infra, infraSetupFields, logger, signal: opts.signal },
+          ),
+          effortReport,
         )
       } finally {
         restoreSecrets()
@@ -808,17 +822,20 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
       },
       opts,
     )
-    return finalizeExploreResult(
-      job,
-      {
-        summary: run.summary,
-        stats: run.stats,
-        stderrTail: run.stderrTail,
-        usage: run.usage,
-        callMetrics: run.callMetrics,
-        runDiag: run.diagnostics,
-      },
-      { infraSetupFields: {}, logger, signal: opts.signal },
+    return mergeEffort(
+      await finalizeExploreResult(
+        job,
+        {
+          summary: run.summary,
+          stats: run.stats,
+          stderrTail: run.stderrTail,
+          usage: run.usage,
+          callMetrics: run.callMetrics,
+          runDiag: run.diagnostics,
+        },
+        { infraSetupFields: {}, logger, signal: opts.signal },
+      ),
+      run.effortReport,
     )
   })
 }
@@ -886,6 +903,55 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
   return result
 }
 
+/**
+ * Assemble the {@link runCodingAgent} spec for the ordinary single-repo coding flow. Extracted
+ * from {@link runSingleRepoCoding} so the many optional-field spreads don't inflate that
+ * function's cyclomatic complexity; the mapping is a straight field copy off `job`.
+ */
+function buildSingleRepoCodingSpec(
+  job: AgentJob,
+  pushBranch: string,
+): Parameters<typeof runCodingAgent>[0] {
+  return {
+    kind: 'agent',
+    jobId: job.jobId,
+    repo: job.repo,
+    cloneBranch: job.branch,
+    ...(job.newBranch ? { newBranch: job.newBranch } : {}),
+    pushBranch,
+    ghToken: job.ghToken,
+    systemPrompt: job.systemPrompt,
+    userPrompt: job.userPrompt,
+    model: job.model,
+    harness: job.harness,
+    subscriptionToken: job.subscriptionToken,
+    subscriptionBaseUrl: job.subscriptionBaseUrl,
+    ambientAuth: job.ambientAuth,
+    proxyBaseUrl: job.proxyBaseUrl,
+    sessionToken: job.sessionToken,
+    commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
+    webToolsGuidance: job.webToolsGuidance,
+    webSearchProxy: job.webSearch,
+    guardLimits: job.guardLimits,
+    ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
+    ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
+    ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
+    // Repo-sourced skill (slice 2): installed harness-aware by runAgentInWorkspace.
+    ...(job.skill ? { skill: job.skill } : {}),
+    // Ralph loop: run the completion command after the agent commits and report its verdict.
+    ...(job.validation
+      ? {
+          validation: {
+            command: job.validation.command,
+            ...(job.validation.iteration !== undefined
+              ? { iteration: job.validation.iteration }
+              : {}),
+          },
+        }
+      : {}),
+  }
+}
+
 /**
  * The ordinary single-repo coding flow: clone `branch` (or resume `newBranch`), run the agent,
  * commit + push to `pushBranch`, and open `pr` when one is set and the run produced changes. A
@@ -894,51 +960,13 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
  */
 async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<AgentResult> {
   const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch
-  const { summary, stats, stderrTail, pushed, usage, callMetrics, validation } =
-    await runCodingAgent(
-      {
-        kind: 'agent',
-        jobId: job.jobId,
-        repo: job.repo,
-        cloneBranch: job.branch,
-        ...(job.newBranch ? { newBranch: job.newBranch } : {}),
-        pushBranch,
-        ghToken: job.ghToken,
-        systemPrompt: job.systemPrompt,
-        userPrompt: job.userPrompt,
-        model: job.model,
-        harness: job.harness,
-        subscriptionToken: job.subscriptionToken,
-        subscriptionBaseUrl: job.subscriptionBaseUrl,
-        ambientAuth: job.ambientAuth,
-        proxyBaseUrl: job.proxyBaseUrl,
-        sessionToken: job.sessionToken,
-        commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
-        webToolsGuidance: job.webToolsGuidance,
-        webSearchProxy: job.webSearch,
-        guardLimits: job.guardLimits,
-        ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
-        ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
-        ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
-        // Repo-sourced skill (slice 2): installed harness-aware by runAgentInWorkspace.
-        ...(job.skill ? { skill: job.skill } : {}),
-        // Ralph loop: run the completion command after the agent commits and report its verdict.
-        ...(job.validation
-          ? {
-              validation: {
-                command: job.validation.command,
-                ...(job.validation.iteration !== undefined
-                  ? { iteration: job.validation.iteration }
-                  : {}),
-              },
-            }
-          : {}),
-      },
-      opts,
-    )
+  const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, effortReport } =
+    await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts)
   // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
   // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
   const ralphVerdict = validation ? { ralphVerdict: validation } : {}
+  // The agent's effort self-assessment, spread onto every result path below (mirrors ralphVerdict).
+  const effort = effortReport ? { effortReport } : {}
 
   if (!pushed) {
     // A no-op: a failure for the implementer, a clean non-event for the fixers.
@@ -951,6 +979,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
+        ...effort,
       }
     }
     return {
@@ -962,6 +991,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       failureCause: 'no-changes',
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
+      ...effort,
     }
   }
 
@@ -995,6 +1025,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
           stats,
           ...(usage ? { usage } : {}),
           ...(callMetrics ? { callMetrics } : {}),
+          ...effort,
         }
       }
       return {
@@ -1010,6 +1041,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         failureCause: 'no-changes',
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
+        ...effort,
       }
     }
     return {
@@ -1021,6 +1053,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
       ...ralphVerdict,
+      ...effort,
     }
   }
   return {
@@ -1031,6 +1064,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     ...(usage ? { usage } : {}),
     ...(callMetrics ? { callMetrics } : {}),
     ...ralphVerdict,
+    ...effort,
   }
 }
 
@@ -1100,23 +1134,24 @@ async function runConflictResolution(job: AgentJob, opts: RunOptions): Promise<A
     const diff = await conflictDiff(dir, conflicted, signal)
     const userPrompt = buildConflictPrompt(mergeBase, job.branch, conflicted, diff, job.userPrompt)
 
-    const { summary, stats, stderrTail, usage, callMetrics } = await runAgentInWorkspace(
-      {
-        dir,
-        systemPrompt: job.systemPrompt,
-        userPrompt,
-        model: job.model,
-        harness: job.harness,
-        subscriptionToken: job.subscriptionToken,
-        subscriptionBaseUrl: job.subscriptionBaseUrl,
-        ambientAuth: job.ambientAuth,
-        proxyBaseUrl: job.proxyBaseUrl,
-        sessionToken: job.sessionToken,
-        contextFiles: job.contextFiles,
-        guardLimits: job.guardLimits,
-      },
-      opts,
-    )
+    const { summary, stats, stderrTail, usage, callMetrics, effortReport } =
+      await runAgentInWorkspace(
+        {
+          dir,
+          systemPrompt: job.systemPrompt,
+          userPrompt,
+          model: job.model,
+          harness: job.harness,
+          subscriptionToken: job.subscriptionToken,
+          subscriptionBaseUrl: job.subscriptionBaseUrl,
+          ambientAuth: job.ambientAuth,
+          proxyBaseUrl: job.proxyBaseUrl,
+          sessionToken: job.sessionToken,
+          contextFiles: job.contextFiles,
+          guardLimits: job.guardLimits,
+        },
+        opts,
+      )
 
     // Never push a half-resolved tree: if any conflict markers / unmerged paths remain,
     // the PR would still be broken. Fail so the engine can retry / notify.
@@ -1125,30 +1160,36 @@ async function runConflictResolution(job: AgentJob, opts: RunOptions): Promise<A
       logger.error('agent(conflict): unresolved conflicts remain, refusing to push', {
         unresolved: unresolved.length,
       })
-      return {
-        pushed: false,
-        branch: job.branch,
-        summary,
-        stats,
-        error: unresolvedReason(unresolved, stats, stderrTail),
-        failureCause: 'agent',
-        ...(usage ? { usage } : {}),
-        ...(callMetrics ? { callMetrics } : {}),
-      }
+      return mergeEffort(
+        {
+          pushed: false,
+          branch: job.branch,
+          summary,
+          stats,
+          error: unresolvedReason(unresolved, stats, stderrTail),
+          failureCause: 'agent',
+          ...(usage ? { usage } : {}),
+          ...(callMetrics ? { callMetrics } : {}),
+        },
+        effortReport,
+      )
     }
     // Complete the merge commit with the agent's resolution staged, then push.
     await commitAll(dir, `Merge ${mergeBase} into ${job.branch}`, signal)
     opts.onPhase?.('push')
     logger.info('agent(conflict): pushing resolved branch', { ...stats })
     await pushBranch(dir, job.branch, job.ghToken, signal)
-    return {
-      pushed: true,
-      branch: job.branch,
-      summary,
-      stats,
-      ...(usage ? { usage } : {}),
-      ...(callMetrics ? { callMetrics } : {}),
-    }
+    return mergeEffort(
+      {
+        pushed: true,
+        branch: job.branch,
+        summary,
+        stats,
+        ...(usage ? { usage } : {}),
+        ...(callMetrics ? { callMetrics } : {}),
+      },
+      effortReport,
+    )
   })
 }
 
@@ -1239,22 +1280,23 @@ async function runBootstrap(job: AgentJob, opts: RunOptions): Promise<AgentResul
 
     opts.onPhase?.('agent')
     logger.info('agent(bootstrap): running agent')
-    const { summary, stats, stderrTail, usage, callMetrics } = await runAgentInWorkspace(
-      {
-        dir,
-        systemPrompt: job.systemPrompt,
-        userPrompt: job.userPrompt,
-        model: job.model,
-        harness: job.harness,
-        subscriptionToken: job.subscriptionToken,
-        subscriptionBaseUrl: job.subscriptionBaseUrl,
-        ambientAuth: job.ambientAuth,
-        proxyBaseUrl: job.proxyBaseUrl,
-        sessionToken: job.sessionToken,
-        guardLimits: job.guardLimits,
-      },
-      opts,
-    )
+    const { summary, stats, stderrTail, usage, callMetrics, effortReport } =
+      await runAgentInWorkspace(
+        {
+          dir,
+          systemPrompt: job.systemPrompt,
+          userPrompt: job.userPrompt,
+          model: job.model,
+          harness: job.harness,
+          subscriptionToken: job.subscriptionToken,
+          subscriptionBaseUrl: job.subscriptionBaseUrl,
+          ambientAuth: job.ambientAuth,
+          proxyBaseUrl: job.proxyBaseUrl,
+          sessionToken: job.sessionToken,
+          guardLimits: job.guardLimits,
+        },
+        opts,
+      )
 
     // Guard against a no-op run: Pi can exit cleanly having done nothing (e.g. it never
     // reached the model), and a force-push would then publish an empty tree — leaving the
@@ -1263,14 +1305,17 @@ async function runBootstrap(job: AgentJob, opts: RunOptions): Promise<AgentResul
     if (!(await producedRepoContent(dir, !fromScratch, signal))) {
       const error = bootstrapNoOpReason(!fromScratch, stats, summary, stderrTail)
       logger.error('agent(bootstrap): agent produced no content, refusing to push', { ...stats })
-      return {
-        summary,
-        stats,
-        error,
-        failureCause: 'agent',
-        ...(usage ? { usage } : {}),
-        ...(callMetrics ? { callMetrics } : {}),
-      }
+      return mergeEffort(
+        {
+          summary,
+          stats,
+          error,
+          failureCause: 'agent',
+          ...(usage ? { usage } : {}),
+          ...(callMetrics ? { callMetrics } : {}),
+        },
+        effortReport,
+      )
     }
 
     opts.onPhase?.('push')
@@ -1286,13 +1331,16 @@ async function runBootstrap(job: AgentJob, opts: RunOptions): Promise<AgentResul
         : `Bootstrap from ${job.repo.owner}/${job.repo.name}`,
     })
     logger.info('agent(bootstrap): complete', { defaultBranch: boot.target.defaultBranch })
-    return {
-      defaultBranch: boot.target.defaultBranch,
-      summary,
-      stats,
-      ...(usage ? { usage } : {}),
-      ...(callMetrics ? { callMetrics } : {}),
-    }
+    return mergeEffort(
+      {
+        defaultBranch: boot.target.defaultBranch,
+        summary,
+        stats,
+        ...(usage ? { usage } : {}),
+        ...(callMetrics ? { callMetrics } : {}),
+      },
+      effortReport,
+    )
   })
 }