@cat-factory/executor-harness 1.50.12 → 1.50.16

package/dist/agent-runner.js

@@ -5,7 +5,7 @@ import { dirname, join } from 'node:path';
 import { claudeAssistantContent, claudeCallUsage, isObject, numberOf, redactBody, } from './claude-stream.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';
 /**
@@ -219,17 +219,19 @@ export async function runClaudeCode(opts) {
             { role: 'user', content: opts.userPrompt },
         ];
     const calls = [];
-    // 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 = () => {
-        if (sawTodoPlan || !opts.onProgress)
+    let lastTodo;
+    const emitProgress = () => {
+        if (!opts.onProgress)
             return;
-        const progress = sliceTracker.progress();
+        const progress = pickProgress(lastTodo, sliceTracker.progress());
         if (progress)
             opts.onProgress(progress);
     };
@@ -242,19 +244,14 @@ export async function runClaudeCode(opts) {
             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?.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.
@@ -277,7 +274,7 @@ export async function runClaudeCode(opts) {
             const content = event.message.content;
             if (Array.isArray(content)) {
                 sliceTracker.onUser(content);
-                emitSliceProgress();
+                emitProgress();
                 messages.push({ role: 'tool', content });
             }
         }
@@ -337,13 +334,16 @@ export async function runClaudeCode(opts) {
                 }
                 : { 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,
@@ -384,9 +384,10 @@ export async function runClaudeCode(opts) {
         // 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
             ? {
                 inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,

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/dist/subagents.js

@@ -1,6 +1,6 @@
 import { readdir, stat } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { claudeAssistantContent, claudeCallUsage, isObject, redactBody } from './claude-stream.js';
 export function createSliceTracker() {
     // Insertion-ordered so the progress `items` render in dispatch order.
@@ -54,21 +54,84 @@ export function createSliceTracker() {
         },
     };
 }
+/**
+ * Reconcile the two redundant views of the same slice work into the one to surface
+ * (ADR 0027 Defect B). A pr-reviewer run has BOTH a parent `TodoWrite` plan (the slices,
+ * written once at grouping time) and the {@link SliceTracker}'s `Task`-dispatch view. The
+ * sequential shape advances the todo plan; the parallel-subagent shape advances ONLY the
+ * slice tracker (the CLI writes the plan once and never marks it done, while the parallel
+ * `Task`s report in-flight/complete). Neither alone covers both shapes, and gating the
+ * slice tracker OFF whenever a todo plan exists (the old behaviour) pinned parallel runs
+ * at 0%. So prefer whichever view is further along: more `completed`, then more
+ * `inProgress` (an all-pending todo plan must not beat live in-flight slices), then more
+ * `total` (the richer view — the todo plan can carry an extra "aggregate" entry), else the
+ * todo plan. Pure + total; returns whichever single input is present when only one is.
+ */
+export function pickProgress(todo, slice) {
+    if (!todo)
+        return slice;
+    if (!slice)
+        return todo;
+    if (slice.completed !== todo.completed)
+        return slice.completed > todo.completed ? slice : todo;
+    if (slice.inProgress !== todo.inProgress)
+        return slice.inProgress > todo.inProgress ? slice : todo;
+    if (slice.total !== todo.total)
+        return slice.total > todo.total ? slice : todo;
+    return todo;
+}
 // ---------------------------------------------------------------------------
 // Subagent transcript watcher (heartbeat + usage) (D3)
 // ---------------------------------------------------------------------------
 /** Default poll cadence for the transcript directory; well under the git timeout margin. */
 const DEFAULT_POLL_MS = 3_000;
 /**
- * Start watching `dir` (the CLI's `<configHome>/subagents`) for `*.jsonl` transcripts,
- * tailing each file by byte offset. New content feeds `onActivity` (heartbeat) and each
- * assistant turn carrying usage is lifted into a {@link HarnessCallMetric} + summed into
- * the cumulative usage. Best-effort throughout: the directory may not exist yet (created
- * lazily by the CLI), a file may be mid-write, and the line/usage shape may change across
- * CLI versions — every such case is swallowed so the watcher can only ever ADD signal,
- * never break the run.
+ * Recursively collect every `*.jsonl` file that lives inside a `subagents/` directory
+ * anywhere under `root` (the CLI's `<configHome>/projects` tree). The Claude CLI writes
+ * each parallel `Task` subagent's transcript to
+ * `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/agent-*.jsonl`; the
+ * session-uuid dir isn't known before the CLI mints it, so we DISCOVER the `subagents/`
+ * dir by walking rather than guessing its path (ADR 0027 Defect A). Files NOT under a
+ * `subagents/` dir — critically the parent's own `<session-uuid>.jsonl` session transcript,
+ * whose per-turn usage the terminal `result` event already totals — are deliberately
+ * excluded: reading them would double-count the parent. `root` itself counts as inside a
+ * `subagents/` dir when its own basename is `subagents` (so passing the leaf dir works too).
+ * Best-effort: an unreadable directory is skipped, never thrown.
+ */
+async function findSubagentTranscripts(root) {
+    const out = [];
+    const walk = async (dir, inSubagents) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // dir not created yet (or vanished) — try again next tick
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full, inSubagents || entry.name === 'subagents');
+            }
+            else if (inSubagents && entry.isFile() && entry.name.endsWith('.jsonl')) {
+                out.push(full);
+            }
+        }
+    };
+    await walk(root, basename(root) === 'subagents');
+    return out;
+}
+/**
+ * Start watching `root` (the CLI's `<configHome>/projects` tree) for subagent `*.jsonl`
+ * transcripts — any file under a `subagents/` directory beneath it (see
+ * {@link findSubagentTranscripts}) — tailing each file by byte offset. New content feeds
+ * `onActivity` (heartbeat) and each assistant turn carrying usage is lifted into a
+ * {@link HarnessCallMetric} + summed into the cumulative usage. Best-effort throughout: the
+ * tree may not exist yet (created lazily by the CLI), a file may be mid-write, and the
+ * line/usage shape may change across CLI versions — every such case is swallowed so the
+ * watcher can only ever ADD signal, never break the run.
  */
-export function startSubagentWatcher(dir, opts) {
+export function startSubagentWatcher(root, opts) {
     const secrets = opts.secrets ?? [];
     const offsets = new Map();
     const calls = [];
@@ -151,16 +214,8 @@ export function startSubagentWatcher(dir, opts) {
             return;
         polling = true;
         try {
-            let entries;
-            try {
-                entries = (await readdir(dir)).filter((n) => n.endsWith('.jsonl'));
-            }
-            catch {
-                return; // dir not created yet (or vanished) — try again next tick
-            }
             let grew = false;
-            for (const name of entries) {
-                const path = join(dir, name);
+            for (const path of await findSubagentTranscripts(root)) {
                 let size;
                 try {
                     size = (await stat(path)).size;

package/package.json

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