@cat-factory/executor-harness 1.50.12 → 1.50.16

package/src/agent-runner.ts

@@ -13,7 +13,7 @@ import type { Logger } from './logger.js'
 import type { HarnessCallMetric, PiRunOutcome, PiRunStats, TodoProgress } from './pi.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
-import { createSliceTracker, startSubagentWatcher } from './subagents.js'
+import { createSliceTracker, pickProgress, startSubagentWatcher } from './subagents.js'
 import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js'
 import { retainSessionTranscripts } from './transcript-retention.js'
 
@@ -325,16 +325,18 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       ]
   const calls: HarnessCallMetric[] = []
 
-  // ADR 0026 D2.1: derive slice progress from the parent stream's `Task` dispatches +
-  // their terminal tool_results (both DO appear here — only a subagent's intermediate
-  // turns don't). A real parent TodoWrite plan, when the agent writes one, wins; the
-  // slice-derived progress is the fallback for the parallel-subagent shape that writes no
-  // parent plan (the pr-reviewer failure this fixes).
+  // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from TWO reconciled
+  // sources. The parent's `Task` dispatches + their terminal tool_results DO appear on this
+  // stream (only a subagent's intermediate turns don't), so `sliceTracker` derives per-slice
+  // progress for the parallel-subagent shape; a parent `TodoWrite` plan (the sequential
+  // shape) is tracked in `lastTodo`. `pickProgress` picks whichever is further along on each
+  // update, so neither masks the other — the pr-reviewer prompt writes its todo plan ONCE
+  // and never marks it done, which used to gate the slice signal off and pin progress at 0%.
   const sliceTracker = createSliceTracker()
-  let sawTodoPlan = false
-  const emitSliceProgress = (): void => {
-    if (sawTodoPlan || !opts.onProgress) return
-    const progress = sliceTracker.progress()
+  let lastTodo: TodoProgress | undefined
+  const emitProgress = (): void => {
+    if (!opts.onProgress) return
+    const progress = pickProgress(lastTodo, sliceTracker.progress())
     if (progress) opts.onProgress(progress)
   }
 
@@ -347,21 +349,13 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       stats.assistantChars += text.length
       stats.toolCalls += toolUses
       for (const block of content) {
-        if (
-          isObject(block) &&
-          block.type === 'tool_use' &&
-          block.name === 'TodoWrite' &&
-          opts.onProgress
-        ) {
+        if (isObject(block) && block.type === 'tool_use' && block.name === 'TodoWrite') {
           const progress = todosToProgress((block.input as Record<string, unknown>)?.todos)
-          if (progress) {
-            sawTodoPlan = true
-            opts.onProgress(progress)
-          }
+          if (progress) lastTodo = progress
         }
       }
       sliceTracker.onAssistant(content)
-      emitSliceProgress()
+      emitProgress()
       // Record this call BEFORE appending its turn: the prompt is the history that
       // produced this response. The append-only array keeps each call's prompt a strict
       // prefix of the next, so the backend's telemetry chain delta-compresses cleanly.
@@ -383,7 +377,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       const content = (event.message as Record<string, unknown>).content
       if (Array.isArray(content)) {
         sliceTracker.onUser(content)
-        emitSliceProgress()
+        emitProgress()
         messages.push({ role: 'tool', content })
       }
     } else if (type === 'result') {
@@ -446,13 +440,16 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
           : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken! }),
       }
 
-  // ADR 0026 D2.1/D3: while the run is live, tail the CLI's `subagents/*.jsonl`
-  // transcripts (under the isolated config home) so a parallel-subagent review keeps the
-  // inactivity heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible
-  // token spend is lifted into the run's telemetry. Ambient mode has no isolated home to
-  // watch. Best-effort — a missing/renamed transcript layout just yields no extra signal.
+  // 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
+  // heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible token spend is
+  // lifted into the run's telemetry. The CLI writes them per-session under
+  // `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/*.jsonl`, so we watch the
+  // `projects` tree and let the watcher discover the `subagents/` dir (the session uuid isn't
+  // known up front). Ambient mode has no isolated home to watch. Best-effort — a
+  // missing/renamed transcript layout just yields no extra signal.
   const subagents = configHome
-    ? startSubagentWatcher(join(configHome, 'subagents'), {
+    ? startSubagentWatcher(join(configHome, 'projects'), {
         ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
         secrets,
         model: opts.model,
@@ -502,9 +499,10 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     // 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 `subagents/*.jsonl` transcripts (a
-    // directory distinct from the parent's `projects/` session transcript), which the watcher
-    // reads and nothing else does — so neither `calls` nor `usage` can already contain them.
+    // 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
         ? {

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,
     )
   })
 }
@@ -894,7 +911,7 @@ 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 } =
+  const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, effortReport } =
     await runCodingAgent(
       {
         kind: 'agent',
@@ -939,6 +956,8 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
   // 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 +970,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
+        ...effort,
       }
     }
     return {
@@ -962,6 +982,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       failureCause: 'no-changes',
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
+      ...effort,
     }
   }
 
@@ -995,6 +1016,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
           stats,
           ...(usage ? { usage } : {}),
           ...(callMetrics ? { callMetrics } : {}),
+          ...effort,
         }
       }
       return {
@@ -1010,6 +1032,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         failureCause: 'no-changes',
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
+        ...effort,
       }
     }
     return {
@@ -1021,6 +1044,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
       ...ralphVerdict,
+      ...effort,
     }
   }
   return {
@@ -1031,6 +1055,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     ...(usage ? { usage } : {}),
     ...(callMetrics ? { callMetrics } : {}),
     ...ralphVerdict,
+    ...effort,
   }
 }
 
@@ -1100,23 +1125,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 +1151,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 +1271,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 +1296,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 +1322,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,
+    )
   })
 }
 

package/src/coding-agent.ts

@@ -31,6 +31,7 @@ import {
 } from './git.js'
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js'
 import type { HarnessCallMetric, PiRunStats } from './pi.js'
+import { EFFORT_REPORT_FILE, type EffortReport } from './effort.js'
 import {
   acquireRepoCheckout,
   agentNeverActed,
@@ -123,6 +124,8 @@ export interface CodingAgentOutcome {
   usage?: { inputTokens: number; outputTokens: number }
   /** Per-model-call telemetry from a subscription harness's CLI stream (absent for Pi). */
   callMetrics?: HarnessCallMetric[]
+  /** The agent's effort self-assessment, lifted from its sentinel file (absent when it wrote none). */
+  effortReport?: EffortReport
   /**
    * Ralph loop: the verdict of the post-commit validation command (whether it exited 0, the
    * exit code, and a bounded/redacted output tail). Present only when {@link CodingAgentSpec.validation}
@@ -242,6 +245,14 @@ export async function runCodingAgent(
       const workDir = serviceDirectory ? join(dir, serviceDirectory) : dir
       if (serviceDirectory) await mkdir(workDir, { recursive: true })
 
+      // Every container agent is asked to write its effort self-assessment to `.cat-effort.json`
+      // in its cwd (the backend appends EFFORT_REPORT_GUIDANCE to every container prompt). Locally
+      // exclude it from git — exactly like the follow-ups sentinel below — so the agent's own
+      // `git add` can never stage it into the PR. `readEffortReport` also removes it after the run,
+      // but that cannot un-stage a mid-run commit; the per-clone exclude is what prevents it. A bare
+      // filename pattern matches the file in any subdirectory, so it covers a monorepo `workDir` too.
+      await excludeFromGit(dir, EFFORT_REPORT_FILE, signal)
+
       // Follow-up companion: tail the Coder's sentinel file and stream new items out on the
       // job view. Locally exclude it from git first so the agent's own `git add` can never
       // stage it and it never surfaces as an untracked leftover or in the PR. The sentinel
@@ -462,7 +473,7 @@ async function finalizeCodingRun(args: {
     agentRun,
   } = args
   const { signal } = opts
-  const { summary, stats, stderrTail, usage, callMetrics } = agentRun
+  const { summary, stats, stderrTail, usage, callMetrics, effortReport } = agentRun
   let outcome: CodingAgentOutcome
 
   // Stop tailing the follow-up sentinel and flush any items written after the last
@@ -521,6 +532,7 @@ async function finalizeCodingRun(args: {
       ...(stderrTail ? { stderrTail } : {}),
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
+      ...(effortReport ? { effortReport } : {}),
     }
   } else {
     opts.onPhase?.('push')
@@ -534,6 +546,7 @@ async function finalizeCodingRun(args: {
       ...(stderrTail ? { stderrTail } : {}),
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
+      ...(effortReport ? { effortReport } : {}),
     }
   }
 
@@ -765,26 +778,27 @@ export async function runMultiRepoCoding(
     // note + the backend system-prompt section explain the layout.
     opts.onPhase?.('agent')
     logger.info('multi-repo: running agent', { repos: legs.map((l) => l.dirName) })
-    const { summary, stats, stderrTail, usage, callMetrics } = await runAgentInWorkspace(
-      {
-        dir: root,
-        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,
-        webToolsGuidance: job.webToolsGuidance,
-        webSearchProxy: job.webSearch,
-        guardLimits: job.guardLimits,
-        ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
-        multiRepo: true,
-      },
-      opts,
-    )
+    const { summary, stats, stderrTail, usage, callMetrics, effortReport } =
+      await runAgentInWorkspace(
+        {
+          dir: root,
+          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,
+          webToolsGuidance: job.webToolsGuidance,
+          webSearchProxy: job.webSearch,
+          guardLimits: job.guardLimits,
+          ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
+          multiRepo: true,
+        },
+        opts,
+      )
 
     // Commit forgotten tracked edits, then push + open a PR for each repo the run actually changed.
     const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(
@@ -807,6 +821,7 @@ export async function runMultiRepoCoding(
           stats,
           ...(usage ? { usage } : {}),
           ...(callMetrics ? { callMetrics } : {}),
+          ...(effortReport ? { effortReport } : {}),
         }
       }
       return {
@@ -822,6 +837,7 @@ export async function runMultiRepoCoding(
         failureCause: 'no-changes',
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
+        ...(effortReport ? { effortReport } : {}),
       }
     }
     logger.info('multi-repo: complete', {
@@ -838,6 +854,7 @@ export async function runMultiRepoCoding(
       stats,
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
+      ...(effortReport ? { effortReport } : {}),
     }
   })
 }

package/src/effort.ts

@@ -0,0 +1,99 @@
+import { readFile, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+
+// ---------------------------------------------------------------------------
+// The agent effort self-assessment side channel. Every container agent is asked
+// (via the backend-composed system prompt) to end its run by writing a short JSON
+// self-assessment — how hard the work was, what reduced its effectiveness, the key
+// obstacles — to a sentinel file in its working directory. The harness reads it after
+// the agent finishes, removes it (so it never lands in a commit), and forwards it on
+// the job result; the backend records it on the step and surfaces it in run details.
+//
+// The filename is kept in sync with `EFFORT_REPORT_FILE` in `@cat-factory/agents`
+// (the executor-harness has no dependency on that package), exactly like CONTEXT_DIR
+// and the follow-ups sentinel. The shape mirrors the contracts `AgentEffortReport`.
+// ---------------------------------------------------------------------------
+
+/** The sentinel file the agent writes its effort self-assessment to (relative to its cwd). */
+export const EFFORT_REPORT_FILE = '.cat-effort.json'
+
+/** A container agent's self-assessment of the work it just did. */
+export interface EffortReport {
+  /** How hard the work was: 1 (trivial) .. 10 (extremely hard). */
+  difficulty: number
+  /** One or two sentences on how hard/easy the work was and why. */
+  summary?: string
+  /** What reduced the agent's effectiveness. */
+  reducedEffectiveness?: string
+  /** The key obstacles the agent hit. */
+  obstacles?: string[]
+}
+
+/**
+ * Read + parse + REMOVE the agent's effort sentinel file from `cwd`. Lenient: returns undefined
+ * when the file is absent (the agent wrote none), unreadable, not JSON, or carries nothing
+ * meaningful. Never throws — a malformed self-report must never fail an otherwise-good run.
+ */
+export async function readEffortReport(cwd: string): Promise<EffortReport | undefined> {
+  const path = join(cwd, EFFORT_REPORT_FILE)
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return undefined // no report written — the common case
+  }
+  // Remove it so it never lands in a commit (defence in depth; the backend also excludes it).
+  await rm(path, { force: true }).catch(() => {})
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+  return coerceEffort(parsed)
+}
+
+/** Coerce arbitrary parsed JSON into a clean {@link EffortReport}, or undefined when it carries nothing. */
+function coerceEffort(value: unknown): EffortReport | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const o = value as Record<string, unknown>
+  const report: EffortReport = { difficulty: clampDifficulty(o.difficulty) }
+  if (typeof o.summary === 'string' && o.summary.trim()) {
+    report.summary = o.summary.trim().slice(0, 2000)
+  }
+  if (typeof o.reducedEffectiveness === 'string' && o.reducedEffectiveness.trim()) {
+    report.reducedEffectiveness = o.reducedEffectiveness.trim().slice(0, 2000)
+  }
+  if (Array.isArray(o.obstacles)) {
+    const obstacles = o.obstacles
+      .filter((x): x is string => typeof x === 'string' && x.trim().length > 0)
+      .map((x) => x.trim().slice(0, 500))
+      .slice(0, 20)
+    if (obstacles.length) report.obstacles = obstacles
+  }
+  // Nothing beyond a defaulted difficulty ⇒ the agent didn't really report anything; drop it so
+  // run details don't show an empty "5/10, no detail" card for a stray/blank file.
+  if (
+    report.summary === undefined &&
+    report.reducedEffectiveness === undefined &&
+    report.obstacles === undefined &&
+    !isFiniteNumber(o.difficulty)
+  ) {
+    return undefined
+  }
+  return report
+}
+
+function clampDifficulty(v: unknown): number {
+  const n = isFiniteNumber(v)
+    ? v
+    : typeof v === 'string' && v.trim() !== ''
+      ? Number(v)
+      : Number.NaN
+  if (!Number.isFinite(n)) return 5
+  return Math.min(10, Math.max(1, Math.round(n)))
+}
+
+function isFiniteNumber(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v)
+}