@cat-factory/executor-harness 1.50.14 → 1.50.18

package/dist/agent-runner.js

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

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);
     });
 }
 /**
@@ -737,14 +745,12 @@ async function runCodingMode(job, opts) {
     return result;
 }
 /**
- * The ordinary single-repo coding flow: clone `branch` (or resume `newBranch`), run the agent,
- * commit + push to `pushBranch`, and open `pr` when one is set and the run produced changes. A
- * no-op is a failure for the implementer (`noChangesIsError` default) and a non-fatal no-op for
- * the in-place fixers (and for a seed-only kind like `repro-test`).
+ * Assemble the {@link runCodingAgent} spec for the ordinary single-repo coding flow. Extracted
+ * from {@link runSingleRepoCoding} so the many optional-field spreads don't inflate that
+ * function's cyclomatic complexity; the mapping is a straight field copy off `job`.
  */
-async function runSingleRepoCoding(job, opts) {
-    const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
-    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation } = await runCodingAgent({
+function buildSingleRepoCodingSpec(job, pushBranch) {
+    return {
         kind: 'agent',
         jobId: job.jobId,
         repo: job.repo,
@@ -781,10 +787,22 @@ async function runSingleRepoCoding(job, opts) {
                 },
             }
             : {}),
-    }, opts);
+    };
+}
+/**
+ * The ordinary single-repo coding flow: clone `branch` (or resume `newBranch`), run the agent,
+ * commit + push to `pushBranch`, and open `pr` when one is set and the run produced changes. A
+ * no-op is a failure for the implementer (`noChangesIsError` default) and a non-fatal no-op for
+ * the in-place fixers (and for a seed-only kind like `repro-test`).
+ */
+async function runSingleRepoCoding(job, opts) {
+    const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
+    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, effortReport } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts);
     // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
     // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
     const ralphVerdict = validation ? { ralphVerdict: validation } : {};
+    // The agent's effort self-assessment, spread onto every result path below (mirrors ralphVerdict).
+    const effort = effortReport ? { effortReport } : {};
     if (!pushed) {
         // A no-op: a failure for the implementer, a clean non-event for the fixers.
         if (job.noChangesIsError === false) {
@@ -796,6 +814,7 @@ async function runSingleRepoCoding(job, opts) {
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
                 ...ralphVerdict,
+                ...effort,
             };
         }
         return {
@@ -807,6 +826,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 +859,7 @@ async function runSingleRepoCoding(job, opts) {
                     stats,
                     ...(usage ? { usage } : {}),
                     ...(callMetrics ? { callMetrics } : {}),
+                    ...effort,
                 };
             }
             return {
@@ -850,6 +871,7 @@ async function runSingleRepoCoding(job, opts) {
                 failureCause: 'no-changes',
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
+                ...effort,
             };
         }
         return {
@@ -861,6 +883,7 @@ async function runSingleRepoCoding(job, opts) {
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
             ...ralphVerdict,
+            ...effort,
         };
     }
     return {
@@ -871,6 +894,7 @@ async function runSingleRepoCoding(job, opts) {
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
+        ...effort,
     };
 }
 /**
@@ -935,7 +959,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 +980,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 +989,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 +1079,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 +1099,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 +1121,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/job.js

@@ -555,6 +555,24 @@ function isReservedEnvName(key) {
     const lower = key.toLowerCase();
     return RESERVED_ENV_PREFIXES.some((p) => lower.startsWith(p));
 }
+/**
+ * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
+ * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
+ * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
+ * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
+ * replace it with a URL and the build would no longer find its tools. Extracted from the infra
+ * parsers to keep their cyclomatic complexity down.
+ */
+function parseInfraEnv(raw) {
+    const env = {};
+    if (typeof raw === 'object' && raw !== null) {
+        for (const [key, val] of Object.entries(raw)) {
+            if (key && !isReservedEnvName(key) && typeof val === 'string')
+                env[key] = val;
+        }
+    }
+    return env;
+}
 /** Parse the frontend UI-test infra spec (`kind: 'frontend'`), tolerating missing knobs. */
 function parseFrontendInfraSpec(o) {
     const packageManager = o.packageManager === 'pnpm' || o.packageManager === 'npm' || o.packageManager === 'yarn'
@@ -562,18 +580,7 @@ function parseFrontendInfraSpec(o) {
         : undefined;
     const serveMode = o.serveMode === 'static' || o.serveMode === 'command' ? o.serveMode : undefined;
     const envInjection = o.envInjection === 'build' || o.envInjection === 'runtime' ? o.envInjection : undefined;
-    // Only string→string entries survive; a non-string value is dropped so a malformed
-    // binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved names
-    // that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
-    // dropped too: they are spread over `process.env` at build time, so a binding named `PATH`
-    // would replace it with a URL and the build would no longer find its tools.
-    const env = {};
-    if (typeof o.env === 'object' && o.env !== null) {
-        for (const [key, val] of Object.entries(o.env)) {
-            if (key && !isReservedEnvName(key) && typeof val === 'string')
-                env[key] = val;
-        }
-    }
+    const env = parseInfraEnv(o.env);
     const servePort = port(o.servePort);
     const wiremockPort = port(o.wiremockPort);
     // The app's monorepo subdirectory becomes the install/build/serve cwd, so it goes through the
@@ -732,11 +739,7 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ghToken: str(o.ghToken, 'ghToken'),
         repo: parseRepoSpec(repo),
         branch: str(o.branch, 'branch'),
-        ...(typeof o.githubApiBase === 'string' ? { githubApiBase: o.githubApiBase } : {}),
-        ...(typeof o.webToolsGuidance === 'string' ? { webToolsGuidance: o.webToolsGuidance } : {}),
-        ...(o.webSearch === true ? { webSearch: true } : {}),
-        ...(o.full === true ? { full: true } : {}),
-        ...(typeof o.mergeBase === 'string' && o.mergeBase ? { mergeBase: o.mergeBase } : {}),
+        ...collectOptionalRequestFields(o),
         ...(bootstrap ? { bootstrap } : {}),
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
@@ -744,20 +747,35 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(skill ? { skill } : {}),
         ...(testSecrets.length ? { testSecrets } : {}),
         ...(infra ? { infra } : {}),
-        ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
-        ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),
-        ...(typeof o.commitMessage === 'string' && o.commitMessage
-            ? { commitMessage: o.commitMessage }
-            : {}),
         ...(pr ? { pr } : {}),
         ...(peerRepos.length ? { peerRepos } : {}),
         ...(referenceRepos.length ? { referenceRepos } : {}),
         ...(referenceBranches.length ? { referenceBranches } : {}),
         ...(reviewPrNumber !== undefined ? { reviewPrNumber } : {}),
+        ...(guardLimits ? { guardLimits } : {}),
+        ...(validation ? { validation } : {}),
+    };
+}
+/**
+ * The optional {@link AgentJob} fields read directly off the request `o` (booleans + trimmed
+ * strings). Extracted from {@link assembleAgentJob} to keep its cyclomatic complexity down; every
+ * key is unique so grouping the conditional spreads is behaviour-neutral (spread order is
+ * irrelevant with no colliding keys).
+ */
+function collectOptionalRequestFields(o) {
+    return {
+        ...(typeof o.githubApiBase === 'string' ? { githubApiBase: o.githubApiBase } : {}),
+        ...(typeof o.webToolsGuidance === 'string' ? { webToolsGuidance: o.webToolsGuidance } : {}),
+        ...(o.webSearch === true ? { webSearch: true } : {}),
+        ...(o.full === true ? { full: true } : {}),
+        ...(typeof o.mergeBase === 'string' && o.mergeBase ? { mergeBase: o.mergeBase } : {}),
+        ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
+        ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),
+        ...(typeof o.commitMessage === 'string' && o.commitMessage
+            ? { commitMessage: o.commitMessage }
+            : {}),
         ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
         ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
         ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
-        ...(guardLimits ? { guardLimits } : {}),
-        ...(validation ? { validation } : {}),
     };
 }

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