@cat-factory/executor-harness 1.50.14 → 1.50.16

package/dist/agent.js

@@ -228,6 +228,14 @@ async function cloneServiceCheckout(dir, job, signal) {
     });
     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, effortReport) {
+    return effortReport ? { ...result, effortReport } : result;
+}
 /** Run one generic agent job end to end, dispatching on `mode`. */
 export async function handleAgent(job, opts = {}) {
     // Private-registry auth first, before any mode runs: every mode with a checkout may
@@ -457,7 +465,7 @@ async function runExploreMode(job, opts) {
         try {
             opts.onPhase?.('agent');
             logger.info('agent(explore): running agent', { serviceDirectory });
-            const { summary, stats, stderrTail, usage, callMetrics, diagnostics: runDiag, } = await runAgentInWorkspace({
+            const { summary, stats, stderrTail, usage, callMetrics, diagnostics: runDiag, effortReport, } = await runAgentInWorkspace({
                 dir: workDir,
                 systemPrompt: job.systemPrompt,
                 userPrompt,
@@ -477,7 +485,7 @@ async function runExploreMode(job, opts) {
                 contextFiles: job.contextFiles,
                 guardLimits: job.guardLimits,
             }, 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();
@@ -666,14 +674,14 @@ async function runMultiRepoExplore(job, opts) {
             guardLimits: job.guardLimits,
             multiRepo: true,
         }, opts);
-        return finalizeExploreResult(job, {
+        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 });
+        }, { infraSetupFields: {}, logger, signal: opts.signal }), run.effortReport);
     });
 }
 /**
@@ -744,7 +752,7 @@ async function runCodingMode(job, opts) {
  */
 async function runSingleRepoCoding(job, opts) {
     const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
-    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation } = await runCodingAgent({
+    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, effortReport } = await runCodingAgent({
         kind: 'agent',
         jobId: job.jobId,
         repo: job.repo,
@@ -785,6 +793,8 @@ async function runSingleRepoCoding(job, 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.
         if (job.noChangesIsError === false) {
@@ -796,6 +806,7 @@ async function runSingleRepoCoding(job, opts) {
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
                 ...ralphVerdict,
+                ...effort,
             };
         }
         return {
@@ -807,6 +818,7 @@ async function runSingleRepoCoding(job, opts) {
             failureCause: 'no-changes',
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
+            ...effort,
         };
     }
     // Changes are on the branch. Open a PR only when the job asked for one.
@@ -839,6 +851,7 @@ async function runSingleRepoCoding(job, opts) {
                     stats,
                     ...(usage ? { usage } : {}),
                     ...(callMetrics ? { callMetrics } : {}),
+                    ...effort,
                 };
             }
             return {
@@ -850,6 +863,7 @@ async function runSingleRepoCoding(job, opts) {
                 failureCause: 'no-changes',
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
+                ...effort,
             };
         }
         return {
@@ -861,6 +875,7 @@ async function runSingleRepoCoding(job, opts) {
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
             ...ralphVerdict,
+            ...effort,
         };
     }
     return {
@@ -871,6 +886,7 @@ async function runSingleRepoCoding(job, opts) {
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
+        ...effort,
     };
 }
 /**
@@ -935,7 +951,7 @@ async function runConflictResolution(job, opts) {
         logger.info('agent(conflict): resolving conflicts with agent', { conflicted });
         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({
+        const { summary, stats, stderrTail, usage, callMetrics, effortReport } = await runAgentInWorkspace({
             dir,
             systemPrompt: job.systemPrompt,
             userPrompt,
@@ -956,7 +972,7 @@ async function runConflictResolution(job, opts) {
             logger.error('agent(conflict): unresolved conflicts remain, refusing to push', {
                 unresolved: unresolved.length,
             });
-            return {
+            return mergeEffort({
                 pushed: false,
                 branch: job.branch,
                 summary,
@@ -965,21 +981,21 @@ async function runConflictResolution(job, opts) {
                 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 {
+        return mergeEffort({
             pushed: true,
             branch: job.branch,
             summary,
             stats,
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
-        };
+        }, effortReport);
     });
 }
 /**
@@ -1055,7 +1071,7 @@ async function runBootstrap(job, opts) {
         }
         opts.onPhase?.('agent');
         logger.info('agent(bootstrap): running agent');
-        const { summary, stats, stderrTail, usage, callMetrics } = await runAgentInWorkspace({
+        const { summary, stats, stderrTail, usage, callMetrics, effortReport } = await runAgentInWorkspace({
             dir,
             systemPrompt: job.systemPrompt,
             userPrompt: job.userPrompt,
@@ -1075,14 +1091,14 @@ async function runBootstrap(job, opts) {
         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 {
+            return mergeEffort({
                 summary,
                 stats,
                 error,
                 failureCause: 'agent',
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
-            };
+            }, effortReport);
         }
         opts.onPhase?.('push');
         logger.info('agent(bootstrap): pushing bootstrapped contents', { ...stats });
@@ -1097,13 +1113,13 @@ async function runBootstrap(job, opts) {
                 : `Bootstrap from ${job.repo.owner}/${job.repo.name}`,
         });
         logger.info('agent(bootstrap): complete', { defaultBranch: boot.target.defaultBranch });
-        return {
+        return mergeEffort({
             defaultBranch: boot.target.defaultBranch,
             summary,
             stats,
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
-        };
+        }, effortReport);
     });
 }
 /**

package/dist/coding-agent.js

@@ -5,6 +5,7 @@ import { killChildProcess, spawnDetached } from './process.js';
 import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
 import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, openPullRequest, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
+import { EFFORT_REPORT_FILE } from './effort.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
 import { log } from './logger.js';
 /**
@@ -105,6 +106,13 @@ export async function runCodingAgent(spec, opts = {}) {
         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
@@ -278,7 +286,7 @@ async function prepareCodingCheckout(dir, spec, logger, opts) {
 async function finalizeCodingRun(args) {
     const { dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, } = args;
     const { signal } = opts;
-    const { summary, stats, stderrTail, usage, callMetrics } = agentRun;
+    const { summary, stats, stderrTail, usage, callMetrics, effortReport } = agentRun;
     let outcome;
     // Stop tailing the follow-up sentinel and flush any items written after the last
     // tick, so a fast final burst still reaches the job view before the run is recorded.
@@ -335,6 +343,7 @@ async function finalizeCodingRun(args) {
             ...(stderrTail ? { stderrTail } : {}),
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
+            ...(effortReport ? { effortReport } : {}),
         };
     }
     else {
@@ -349,6 +358,7 @@ async function finalizeCodingRun(args) {
             ...(stderrTail ? { stderrTail } : {}),
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
+            ...(effortReport ? { effortReport } : {}),
         };
     }
     // Ralph loop: run the programmatic completion command against the pushed/committed
@@ -528,7 +538,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
         // 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({
+        const { summary, stats, stderrTail, usage, callMetrics, effortReport } = await runAgentInWorkspace({
             dir: root,
             systemPrompt: job.systemPrompt,
             userPrompt: job.userPrompt,
@@ -560,6 +570,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
                     stats,
                     ...(usage ? { usage } : {}),
                     ...(callMetrics ? { callMetrics } : {}),
+                    ...(effortReport ? { effortReport } : {}),
                 };
             }
             return {
@@ -571,6 +582,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
                 failureCause: 'no-changes',
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
+                ...(effortReport ? { effortReport } : {}),
             };
         }
         logger.info('multi-repo: complete', {
@@ -587,6 +599,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
             stats,
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
+            ...(effortReport ? { effortReport } : {}),
         };
     });
 }

package/dist/effort.js

@@ -0,0 +1,84 @@
+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';
+/**
+ * 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) {
+    const path = join(cwd, EFFORT_REPORT_FILE);
+    let raw;
+    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;
+    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) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    const report = { 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) => 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) {
+    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) {
+    return typeof v === 'number' && Number.isFinite(v);
+}

package/dist/pi-workspace.js

@@ -1,6 +1,7 @@
 import { mkdir, mkdtemp, rm } from 'node:fs/promises';
 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, mergeGuardLimits, progressGuardLimitsFromEnv, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
 import { runSubscriptionHarness } from './agent-runner.js';
@@ -134,7 +135,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         if (!spec.ambientAuth && !spec.subscriptionToken) {
             throw new Error(`The ${spec.harness} harness requires a subscription token`);
         }
-        return runSubscriptionHarness(spec.harness, {
+        const subOutcome = await runSubscriptionHarness(spec.harness, {
             cwd: spec.dir,
             model: spec.model,
             systemPrompt: subscriptionSystemPrompt(spec.systemPrompt, contextFiles),
@@ -148,6 +149,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             onProgress: opts.onProgress,
             ...(opts.log ? { log: opts.log } : {}),
         });
+        return withEffortReport(spec.dir, subOutcome);
     }
     if (!spec.proxyBaseUrl || !spec.sessionToken) {
         throw new Error('The Pi harness requires proxyBaseUrl and sessionToken');
@@ -178,7 +180,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     });
     await writePiModelsConfig({ model: spec.model, proxyBaseUrl });
     const { signal, onActivity, onProgress, onSpan } = opts;
-    return runPi({
+    const piOutcome = await runPi({
         cwd: spec.dir,
         model: spec.model,
         userPrompt: spec.userPrompt,
@@ -193,6 +195,16 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
         extraEnv,
     });
+    return withEffortReport(spec.dir, piOutcome);
+}
+/**
+ * Lift the agent's effort self-assessment off its sentinel file in `dir` and fold it onto the
+ * run outcome. Shared by both harness paths so EVERY container agent's effort report is captured
+ * in one place. Never throws (a bad/absent report just yields no `effortReport`).
+ */
+async function withEffortReport(dir, outcome) {
+    const effortReport = await readEffortReport(dir);
+    return effortReport ? { ...outcome, effortReport } : outcome;
 }
 /**
  * Append a pointer to the materialised linked context onto a subscription harness's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.50.14",
+  "version": "1.50.16",
   "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.142.0",
+    "@cat-factory/spend": "0.12.74"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

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)
+}

package/src/job.ts

@@ -1,6 +1,7 @@
 import type { HarnessCallMetric, PiRunStats } from './pi.js'
 import type { HarnessKind } from './pi-workspace.js'
 import type { FailureCause } from './failure.js'
+import type { EffortReport } from './effort.js'
 
 // The job the Worker's ContainerAgentExecutor POSTs to /run. Kept as plain
 // types with a hand-rolled validator so the image needs no schema dependency.
@@ -921,6 +922,12 @@ export interface AgentResult {
    * {@link HarnessCallMetric}.
    */
   callMetrics?: HarnessCallMetric[]
+  /**
+   * The agent's effort self-assessment (how hard the work was, what reduced its effectiveness,
+   * the key obstacles), lifted from its sentinel file after the run. The backend forwards it onto
+   * the job result and records it on the step for run details. Absent when the agent wrote none.
+   */
+  effortReport?: EffortReport
 }
 
 /** Parse the coding-mode bootstrap spec, or undefined when absent. Validates the target. */

package/src/pi-workspace.ts

@@ -2,6 +2,7 @@ import { mkdir, mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import type { RepoSpec, SkillSpec } from './job.js'
+import { readEffortReport } from './effort.js'
 import { log } from './logger.js'
 import {
   type ContextFileInfo,
@@ -258,7 +259,7 @@ export async function runAgentInWorkspace(
     if (!spec.ambientAuth && !spec.subscriptionToken) {
       throw new Error(`The ${spec.harness} harness requires a subscription token`)
     }
-    return runSubscriptionHarness(spec.harness, {
+    const subOutcome = await runSubscriptionHarness(spec.harness, {
       cwd: spec.dir,
       model: spec.model,
       systemPrompt: subscriptionSystemPrompt(spec.systemPrompt, contextFiles),
@@ -272,6 +273,7 @@ export async function runAgentInWorkspace(
       onProgress: opts.onProgress,
       ...(opts.log ? { log: opts.log } : {}),
     })
+    return withEffortReport(spec.dir, subOutcome)
   }
   if (!spec.proxyBaseUrl || !spec.sessionToken) {
     throw new Error('The Pi harness requires proxyBaseUrl and sessionToken')
@@ -301,7 +303,7 @@ export async function runAgentInWorkspace(
   })
   await writePiModelsConfig({ model: spec.model, proxyBaseUrl })
   const { signal, onActivity, onProgress, onSpan } = opts
-  return runPi({
+  const piOutcome = await runPi({
     cwd: spec.dir,
     model: spec.model,
     userPrompt: spec.userPrompt,
@@ -316,6 +318,17 @@ export async function runAgentInWorkspace(
     guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
     extraEnv,
   })
+  return withEffortReport(spec.dir, piOutcome)
+}
+
+/**
+ * Lift the agent's effort self-assessment off its sentinel file in `dir` and fold it onto the
+ * run outcome. Shared by both harness paths so EVERY container agent's effort report is captured
+ * in one place. Never throws (a bad/absent report just yields no `effortReport`).
+ */
+async function withEffortReport(dir: string, outcome: PiRunOutcome): Promise<PiRunOutcome> {
+  const effortReport = await readEffortReport(dir)
+  return effortReport ? { ...outcome, effortReport } : outcome
 }
 
 /**

package/src/pi.ts

@@ -7,6 +7,7 @@ import { pathExists } from './fs-utils.js'
 import { redactSecrets } from './redact.js'
 import { HarnessFailure } from './failure.js'
 import { log } from './logger.js'
+import type { EffortReport } from './effort.js'
 
 // Drives the Pi coding-agent CLI. Pi is pointed at the Worker's OpenAI-compatible
 // proxy via a custom provider in ~/.pi/agent/models.json, authenticated with the
@@ -534,6 +535,12 @@ export interface PiRunOutcome {
   callMetrics?: HarnessCallMetric[]
   /** Output-quality signals (truncation / empty final answer); see {@link RunDiagnostics}. */
   diagnostics?: RunDiagnostics
+  /**
+   * The agent's effort self-assessment, lifted from its sentinel file after the run (how hard the
+   * work was, what reduced its effectiveness, the key obstacles). Absent when the agent wrote none.
+   * See {@link EffortReport}.
+   */
+  effortReport?: EffortReport
 }
 
 /**