dorfl 0.11.2 → 0.12.0

package/src/integration-core.ts

@@ -28,6 +28,7 @@ import {
 	reviewRoundsExhaustedReason,
 } from './review-gate.js';
 import {type IntegrateResult, type ReviewProvider} from './integrator.js';
+import {extractDecisionsBlock} from './agent-stop.js';
 import {ledgerWrite} from './ledger-write.js';
 import {selectProvider} from './github.js';
 import type {IntegrationMode} from './config.js';
@@ -1104,6 +1105,20 @@ export async function performIntegration(
 		);
 	}
 
+	// 2b. TRANSCRIBE the agent's `## Decisions` block into the DONE RECORD (the
+	//     builder's rationale channel, WORK-CONTRACT "Where a BUILDER's RATIONALE
+	//     lives"). The builder does NO git and MUST NOT edit the task body, and the
+	//     done-move is ours, so "record your rationale in the done record" is an
+	//     instruction it CANNOT obey directly. It emits a `## Decisions` block on the
+	//     one surface it owns (its final report, reaching us as `input.body`), and we
+	//     append it here: AFTER the move (so we write the record at its DONE path) and
+	//     BEFORE the `git add -A` below (so it rides the SAME atomic completion commit,
+	//     not a second one). Skipped for a TASKING transition (`lifecycle`), which
+	//     lands a spec: no done record, and no building agent.
+	if (!lifecycle) {
+		transcribeDecisionsIntoDoneRecord({cwd, slug, output: input.body, note});
+	}
+
 	// 3. Commit: git add -A (the agent's uncommitted work + the move) into ONE
 	//    atomic commit. Nothing to commit is FATAL (no-op-is-fatal, like claim.sh).
 	await gitHard(['add', '-A'], cwd, env);
@@ -2530,6 +2545,68 @@ const CAPTURE_NOTE_DIRS = [
 	workFolderPrefix('findings'),
 ] as const;
 
+/**
+ * TRANSCRIBE the build agent's `## Decisions` block into the DONE RECORD: the
+ * runner half of the builder's rationale channel (WORK-CONTRACT.md, "Where a
+ * BUILDER's RATIONALE lives").
+ *
+ * The builder MUST surface a non-obvious in-scope decision for ratification, but
+ * every home the contract used to offer it was UNREACHABLE: it does no git, it must
+ * not edit the task body (`CLAIM-PROTOCOL.md`), and the done-move, the completion
+ * commit and the PR body are all the RUNNER's. So an acceptance criterion like
+ * "rationale recorded in the done record" was structurally unsatisfiable, and the
+ * rationale scattered into a JSDoc, a changeset, or an invented
+ * `work/notes/observations/decisions-<slug>.md` note (a BACKWARD artifact in a LIVE,
+ * FORWARD bucket, so it can never be discharged). Reviewers then re-raised the
+ * identical "no Decisions block in the done record" finding on task after task.
+ *
+ * The fix is structural, not exhortative: the builder emits the block on the ONE
+ * surface it owns (its final report, which reaches us as `input.body`), and the
+ * runner, already the owner of the done-move, appends it here. Properties that
+ * matter:
+ *
+ *   - **Same commit.** The caller invokes this AFTER the `git mv` (so the record is
+ *     written at its `tasks/done/` path) and BEFORE `git add -A` (so it rides the
+ *     ONE atomic completion commit, never a second, dangling one).
+ *   - **Verbatim.** The agent's prose is appended unaltered under a `## Decisions`
+ *     heading; we add structure, never interpretation.
+ *   - **Idempotent.** A record that ALREADY carries a `## Decisions` section is left
+ *     untouched, so a `requeue` continue, or a re-run over an already-done-moved
+ *     branch (`source: 'done'`), cannot append the same block twice.
+ *   - **Best-effort.** No block, no record on disk, or an unreadable/unwritable file
+ *     is a silent no-op: a rationale note must NEVER fail an otherwise-green
+ *     completion (the same stance as {@link reportScoopedNotes}).
+ */
+function transcribeDecisionsIntoDoneRecord(params: {
+	cwd: string;
+	slug: string;
+	output: string | undefined;
+	note: (message: string) => void;
+}): void {
+	const {cwd, slug, output, note} = params;
+	const decisions = extractDecisionsBlock(output);
+	if (decisions === undefined) {
+		return; // the common case: the agent recorded no in-scope decision.
+	}
+	const path = workItemPath(cwd, 'done', slug);
+	if (!existsSync(path)) {
+		return; // no done record to annotate (a lifecycle/degenerate shape).
+	}
+	try {
+		const body = readFileSync(path, 'utf8');
+		if (/^##\s+Decisions\s*$/m.test(body)) {
+			return; // already transcribed (a continue/re-run): never duplicate.
+		}
+		const separator = body.endsWith('\n') ? '\n' : '\n\n';
+		writeFileSync(path, `${body}${separator}## Decisions\n\n${decisions}\n`);
+		note(
+			`Recorded the agent's "## Decisions" block in ${workItemRel('done', `${slug}.md`)}.`,
+		);
+	} catch {
+		// Best-effort: never fail a green completion over a rationale note.
+	}
+}
+
 /**
  * SCOOP + REPORT the agent-authored CAPTURED NOTES this run's atomic commit is
  * landing (task `runner-scoops-captured-notes`). A rung's agent writes

package/src/item-lock.ts

@@ -298,10 +298,14 @@ export async function acquireItemLock(
 	const entry = lockEntryFor(opts.item);
 	const ref = itemLockRef(entry);
 	try {
-		// Fetch the current lock refs so the lease sees the real state.
+		// Fetch the current lock refs (PRUNED) so the lease sees the real arbiter
+		// state — `--prune` keeps the local `refs/dorfl/lock/*` namespace from
+		// accumulating refs the arbiter has deleted (observation
+		// `gc-ledger-reports-mirror-stale-lock-refs-as-arbiter-state`).
 		await gitHard(
 			[
 				'fetch',
+				'--prune',
 				'--quiet',
 				arbiter,
 				`+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
@@ -393,9 +397,13 @@ async function releaseLockEntry(
 ): Promise<ReleaseResult> {
 	const ref = itemLockRef(entry);
 	try {
+		// `--prune` so a lock already released on the arbiter reads as not-held
+		// (its stale local ref is pruned) rather than as a phantom hold
+		// (observation `gc-ledger-reports-mirror-stale-lock-refs-as-arbiter-state`).
 		await gitHard(
 			[
 				'fetch',
+				'--prune',
 				'--quiet',
 				arbiter,
 				`+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
@@ -558,8 +566,18 @@ async function fetchHeldEntry(
 	arbiter: string,
 	env: NodeJS.ProcessEnv | undefined,
 ): Promise<{lock: LockEntry; sha: string} | undefined> {
+	// `--prune` so a lock RELEASED on the arbiter (its ref deleted there) is PRUNED
+	// locally — otherwise the stale local ref survives and `rev-parse`/`show` below
+	// read it as still held (observation
+	// `gc-ledger-reports-mirror-stale-lock-refs-as-arbiter-state`).
 	await gitHard(
-		['fetch', '--quiet', arbiter, `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`],
+		[
+			'fetch',
+			'--prune',
+			'--quiet',
+			arbiter,
+			`+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
+		],
 		cwd,
 		env,
 	);
@@ -903,8 +921,19 @@ export async function readItemLock(
 	const env = opts.env;
 	const cwd = opts.cwd;
 	const ref = itemLockRef(lockEntryFor(opts.item));
+	// `--prune` so a lock RELEASED on the arbiter (its ref deleted there) is PRUNED
+	// locally — otherwise the stale local `refs/dorfl/lock/<entry>` would survive
+	// and `git show <ref>:lock.md` below would read it as still held (observation
+	// `gc-ledger-reports-mirror-stale-lock-refs-as-arbiter-state`). After the prune,
+	// a released lock's ref is gone locally ⇒ `show` fails ⇒ `undefined` (not locked).
 	await gitHard(
-		['fetch', '--quiet', arbiter, `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`],
+		[
+			'fetch',
+			'--prune',
+			'--quiet',
+			arbiter,
+			`+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
+		],
 		cwd,
 		env,
 	);
@@ -1052,10 +1081,13 @@ export async function reconcileItemLockAgainstMain(
 	const ref = itemLockRef(entry);
 	try {
 		// One fetch refreshes BOTH the lock refs and `<arbiter>/main` so the lock and
-		// the durable record are read from the SAME live arbiter snapshot.
+		// the durable record are read from the SAME live arbiter snapshot. `--prune`
+		// keeps the local lock namespace from accumulating refs the arbiter deleted
+		// (observation `gc-ledger-reports-mirror-stale-lock-refs-as-arbiter-state`).
 		await gitHard(
 			[
 				'fetch',
+				'--prune',
 				'--quiet',
 				arbiter,
 				`+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
@@ -1235,9 +1267,12 @@ export async function classifyItemLockAgainstMain(
 	const entry = lockEntryFor(opts.item);
 	const ref = itemLockRef(entry);
 	try {
+		// `--prune` keeps the local lock namespace from accumulating refs the
+		// arbiter deleted (observation `gc-ledger-reports-mirror-stale-lock-refs-as-arbiter-state`).
 		await gitHard(
 			[
 				'fetch',
+				'--prune',
 				'--quiet',
 				arbiter,
 				`+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
@@ -1799,8 +1834,25 @@ export async function listItemLocks(
 	arbiter = 'origin',
 	env?: NodeJS.ProcessEnv,
 ): Promise<string[]> {
+	// `--prune` so a lock RELEASED on the arbiter (its ref deleted there) is PRUNED
+	// locally — a bare `git fetch +refs/dorfl/lock/*:refs/dorfl/lock/*` (force, NO
+	// `--prune`) leaves local refs the arbiter has since DELETED, so `for-each-ref`
+	// would list locks that no longer exist (observation
+	// `gc-ledger-reports-mirror-stale-lock-refs-as-arbiter-state`). After the pruned
+	// fetch the local `refs/dorfl/lock/*` namespace EXACTLY matches the arbiter's, so
+	// `for-each-ref` reads the arbiter's actual lock set. The refs are materialized
+	// LOCALLY (not just `ls-remote`) because callers like `migrateStuckLocks` read a
+	// lock's body via `git show <ref>:lock.md` after this. A fault THROWS (fail-closed
+	// for the SELECTION path via {@link heldTaskSlugsStrict}; the graceful
+	// {@link heldTaskSlugs}/{@link heldSpecSlugs} twins catch it).
 	await gitHard(
-		['fetch', '--quiet', arbiter, `+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`],
+		[
+			'fetch',
+			'--prune',
+			'--quiet',
+			arbiter,
+			`+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
+		],
 		cwd,
 		env,
 	);
@@ -1837,9 +1889,44 @@ export async function listItemLockEntries(
 	env?: NodeJS.ProcessEnv,
 ): Promise<LockEntry[]> {
 	try {
-		await gitHard(
+		// Read the arbiter DIRECTLY (`git ls-remote`) for the AUTHORITATIVE lock ref
+		// set — NOT the local `refs/dorfl/lock/*` refs (observation
+		// `gc-ledger-reports-mirror-stale-lock-refs-as-arbiter-state`): a bare
+		// `git fetch +refs/dorfl/lock/*:refs/dorfl/lock/*` (force, NO `--prune`)
+		// leaves local refs the arbiter has since DELETED, so `for-each-ref` would
+		// report locks that no longer exist — and `gc --ledger`'s entire purpose is
+		// to name locks a human should delete, so it MUST NOT name locks that do not
+		// exist. `ls-remote` lists ONLY the refs that ACTUALLY exist on the arbiter
+		// right now; the report is bounded by THAT set, never by accumulated local
+		// state. A fault degrades to an EMPTY report (US #12 — recoverable), exactly
+		// as an absent lock-ref namespace reads; an arbiter with no locks returns
+		// exit 0 + empty output ⇒ `[]`.
+		const ls = await gitSoft(
+			['ls-remote', arbiter, `${LOCK_REF_PREFIX}/*`],
+			cwd,
+			env,
+		);
+		if (ls.status !== 0) {
+			return [];
+		}
+		const refs = ls.stdout
+			.split('\n')
+			.map((l) => l.trim())
+			.filter((l) => l !== '')
+			.map((l) => l.split(/\s+/)[1])
+			.filter((ref) => ref.startsWith(`${LOCK_REF_PREFIX}/`))
+			.sort();
+		if (refs.length === 0) {
+			return [];
+		}
+		// Materialize the objects AND keep the local `refs/dorfl/lock/*` namespace
+		// PRUNED to match the arbiter (best-effort). The list above is already
+		// bounded by `ls-remote`, so a fetch fault here can only UNDER-report (skip
+		// content), never name a non-existent ref — the safe direction.
+		await gitSoft(
 			[
 				'fetch',
+				'--prune',
 				'--quiet',
 				arbiter,
 				`+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
@@ -1847,19 +1934,6 @@ export async function listItemLockEntries(
 			cwd,
 			env,
 		);
-		const out = await gitSoft(
-			['for-each-ref', '--format=%(refname)', `${LOCK_REF_PREFIX}/*`],
-			cwd,
-			env,
-		);
-		if (out.status !== 0) {
-			return [];
-		}
-		const refs = out.stdout
-			.split('\n')
-			.map((l) => l.trim())
-			.filter((l) => l.startsWith(`${LOCK_REF_PREFIX}/`))
-			.sort();
 		const entries: LockEntry[] = [];
 		for (const ref of refs) {
 			const show = await gitSoft(['show', `${ref}:lock.md`], cwd, env);

package/src/pi-harness.ts

@@ -12,7 +12,7 @@ import {
 	type LaunchResult,
 } from './harness.js';
 import {generateSessionPath} from './session-path.js';
-import {lastAssistantText} from './watch-session.js';
+import {lastAssistantTurn, isOutputCappedTurn} from './watch-session.js';
 import {reapProcessGroup} from './reap-agent-tree.js';
 import type {HarnessAdapter} from './config.js';
 
@@ -188,8 +188,10 @@ export class PiHarness implements Harness {
 			detail: status === 0 ? undefined : (result.stderr ?? '').trim(),
 			// The agent's ANSWER (task `harness-agent-output`): the LAST assistant
 			// turn's text read from the session `.jsonl` pi just wrote — NOT piped
-			// stdout (which is drained). Shares `watch-session.ts`'s reader.
-			output: readLastAssistantText(sessionFile),
+			// stdout (which is drained). Shares `watch-session.ts`'s reader. The
+			// same turn's stop_reason/usage feed the outputCapped cap-truncation
+			// signal (observation `tasker-review-edits-payload-caps-the-verdict-response`).
+			...readAssistantOutput(sessionFile),
 		};
 	}
 
@@ -384,9 +386,10 @@ export class PiHarness implements Harness {
 						timedOut: timedOut ? true : undefined,
 						...(reap ? {reap} : {}),
 						// Read the agent's ANSWER from the `.jsonl` at `exit` — the same
-						// last-assistant-text read `launch` does at return (task
+						// last-assistant-turn read `launch` does at return (task
 						// `harness-agent-output`); the process has exited so the log is final.
-						output: readLastAssistantText(sessionFile),
+						// The same turn's stop_reason/usage feed the outputCapped signal.
+						...readAssistantOutput(sessionFile),
 					});
 				};
 				if (!timedOut || pgid === undefined) {
@@ -523,14 +526,18 @@ export function piSessionExists(record: HarnessRecord): boolean {
 }
 
 /**
- * Read the LAST assistant message's text from the pi session `.jsonl` at
- * `sessionFile` — the agent's final ANSWER, surfaced as `LaunchResult.output`
- * (task `harness-agent-output`). Called by BOTH `launch` (at return) and
- * `launchAsync` (at `close`), AFTER pi has exited so the log is complete.
+ * Read the LAST assistant turn's output from the pi session `.jsonl` at
+ * `sessionFile` — the agent's final ANSWER (`output`) PLUS the output-cap
+ * signal (`outputCapped`, when the turn was truncated at the model's output-token
+ * cap before it finished). Surfaced through the harness seam as
+ * `LaunchResult.output` / `LaunchResult.outputCapped` (task `harness-agent-output`;
+ * observation `tasker-review-edits-payload-caps-the-verdict-response`). Called by
+ * BOTH `launch` (at return) and `launchAsync` (at `exit`), AFTER pi has exited so
+ * the log is complete.
  *
- * It REUSES `watch-session.ts`'s {@link lastAssistantText} (one `.jsonl` parser,
- * not two). An absent file (pi never wrote it) yields `undefined`, as does a log
- * with no assistant text — a read error is never thrown back into the launch.
+ * It REUSES `watch-session.ts`'s {@link lastAssistantTurn} (one `.jsonl` parser,
+ * not two). An absent file (pi never wrote it) yields `{}`, as does a log with no
+ * assistant text — a read error is never thrown back into the launch.
  *
  * Studied (task `pi-harness-polish`, finding
  * `work/notes/findings/pi-harness-channels.md`, pinned against pi 0.73.1 +
@@ -543,14 +550,21 @@ export function piSessionExists(record: HarnessRecord): boolean {
  * so a future stream/HTTP-shaped harness (opencode-style) still fits: the file
  * shape lives BEHIND this reader and is not observable through the seam.
  */
-function readLastAssistantText(sessionFile: string): string | undefined {
+function readAssistantOutput(sessionFile: string): {
+	output?: string;
+	outputCapped?: number;
+} {
 	let jsonl: string;
 	try {
 		jsonl = readFileSync(sessionFile, 'utf8');
 	} catch {
-		return undefined; // no session log on disk — no answer to surface.
+		return {}; // no session log on disk — no answer to surface.
 	}
-	return lastAssistantText(jsonl);
+	const turn = lastAssistantTurn(jsonl);
+	return {
+		output: turn.text,
+		outputCapped: isOutputCappedTurn(turn) ? turn.outputTokens : undefined,
+	};
 }
 
 // Register the pi adapter so `status`/`do`/`gc` resolve liveness for `pi` jobs

package/src/repo-mirror.ts

@@ -11,6 +11,7 @@ import {
 	type LoadedRepoConfig,
 } from './repo-config.js';
 import {encodeRepoKey} from './repo-key.js';
+import {LOCK_REF_PREFIX} from './item-lock.js';
 
 export {encodeRepoKey} from './repo-key.js';
 
@@ -132,6 +133,27 @@ export function ensureMirror(options: EnsureMirrorOptions): EnsureMirrorResult {
 		// materialisation has its base; the per-branch onboard reads still fail loudly
 		// downstream if a needed ref is genuinely absent.
 		run('git', ['fetch', 'origin', '+refs/heads/*:refs/heads/*'], path, {env});
+		// PRUNE the per-item LOCK namespace against the arbiter (observation
+		// `gc-ledger-reports-mirror-stale-lock-refs-as-arbiter-state`): the all-heads
+		// fetch above covers only `refs/heads/*`, so `refs/dorfl/lock/*` was never
+		// pruned here and released locks accumulated on the mirror indefinitely — a
+		// `gc --ledger` (or any `status`/`scan` read) that reads the mirror then
+		// reported locks that no longer exist on the arbiter. Best-effort (soft):
+		// an unreachable arbiter leaves the existing lock refs in place (the
+		// read-side `listItemLocks`/`listItemLockEntries` read the arbiter DIRECTLY
+		// via `ls-remote`, so this is the proactive keep-the-mirror-clean pass, not
+		// the load-bearing one).
+		run(
+			'git',
+			[
+				'fetch',
+				'--prune',
+				'origin',
+				`+${LOCK_REF_PREFIX}/*:${LOCK_REF_PREFIX}/*`,
+			],
+			path,
+			{env},
+		);
 		fetched = true;
 	} else {
 		// First time: a bare mirror clone (shared object store, cheap).

package/src/review-gate.ts

@@ -126,12 +126,18 @@ export function buildReviewPrompt(slug: string): string {
 		`design choice the agent made on its own while building: a CROSS-TASK`,
 		`INTERACTION (a choice affecting another command/flag/task's behaviour), a new`,
 		`ERROR/REFUSAL, or a user-visible DEFAULT. The agent SHOULD have recorded these`,
-		`in a "## Decisions" block in its PR description — START from that block (ratify`,
+		`in a "## Decisions" block in its report, which the runner transcribes into the`,
+		`done record (work/tasks/done/<slug>.md) and which also rides the PR description.`,
+		`START from that block (ratify`,
 		`each entry) AND hunt for any it MISSED. Flag EACH such decision as a finding`,
-		`for the human to RATIFY — "non-blocking" by DEFAULT (the build proceeds; the`,
+		`for the human to RATIFY: "non-blocking" by DEFAULT (the build proceeds; the`,
 		`human ratifies or reverses), escalating to "blocking" ONLY if the decision looks`,
 		`WRONG or is genuinely load-bearing-and-hard-to-reverse. An un-recorded in-scope`,
-		`decision is NOT itself a block — it is a ratification finding.`,
+		`decision is NOT itself a block, it is a ratification finding. Do NOT raise a`,
+		`finding about WHERE the rationale was written (the done record, the commit body`,
+		`and the PR body are the RUNNER's to author, never the builder's): review the`,
+		`DECISION, not the filing. If rationale is missing entirely, that is the`,
+		`ratification finding above.`,
 		``,
 		`ALSO CHECK CONCEPTUAL COHERENCE — does this diff fit the system's existing`,
 		`LANGUAGE? For each concept / flag / config key / status / verb it introduces or`,

package/src/review-verdict.ts

@@ -40,8 +40,27 @@ export interface ReviewFinding {
 export interface TaskEdit {
 	/** Repo-relative path of the candidate task file to write. */
 	path: string;
-	/** The full replacement content for that file. */
-	content: string;
+	/**
+	 * The full replacement content for that file, emitted INLINE. LEGACY / small-edit
+	 * form. UNBOUNDED: a large decomposition's worth of full-file bodies in ONE JSON
+	 * object shares the model's capped response with the verdict, so a rich spec can
+	 * cap-truncate the response before the verdict closes (observation
+	 * `tasker-review-edits-payload-caps-the-verdict-response`). The tasker improver loop
+	 * now asks the agent to WRITE each edited body to a scratch file and reference it by
+	 * `src` instead (see {@link src}) so the verdict is obtainable independent of edit
+	 * size. Kept (optional) so a small inline edit + the existing tests still work.
+	 */
+	content?: string;
+	/**
+	 * Repo-relative path to a SCRATCH file the agent WROTE the full replacement body
+	 * to (the runner reads it, applies it through the SAME scope fence, then deletes
+	 * it). The DECOUPLED form: the verdict JSON carries only PATHS, so its size is
+	 * bounded by the NUMBER of edits, not the total body size — a large decomposition
+	 * can no longer cap-truncate the verdict. The agent writes the scratch file itself
+	 * (it runs in the job worktree and has the `write` tool); the runner applies /
+	 * commits. Exactly one of {@link content} / {@link src} carries the body.
+	 */
+	src?: string;
 }
 
 /**
@@ -91,6 +110,39 @@ export interface ReviewVerdict {
 /** Raised when the review agent ran but produced no parseable verdict. */
 export class ReviewParseError extends Error {}
 
+/**
+ * Raised when the review agent's output was TRUNCATED at the model's output cap
+ * before it could emit a complete verdict — a DISTINCT, named failure class so it is
+ * never mis-reported as a generic "produced no parseable result" (which reads as a
+ * flake and invites a blind retry, burning a second full tasking run).
+ *
+ * It is a SUBCLASS of {@link ReviewParseError} so every existing
+ * `catch (ReviewParseError)` site (the tasker-review loop's bounce routing) still
+ * catches it UNIFORMLY and routes to needs-attention — NEVER a silent approve. The
+ * only thing that changes is the MESSAGE: it names the cap and the token count so
+ * an operator knows the structural cause (the edits payload is unbounded and
+ * shared the capped response with the verdict) rather than chasing a model flake.
+ *
+ * Detected at the harness seam: the adapter surfaces the last assistant turn's
+ * `stop_reason` (null / `None` / `max_tokens` — the turn did not end naturally) and
+ * its `usage.output` token count; the gate throws this when a parse fails AND that
+ * cap signal is present. When the adapter CANNOT see the signal (the null/shell
+ * adapter, or a future adapter without usage telemetry), the parse still fails as a
+ * generic {@link ReviewParseError} — still needs-attention, never a silent approve.
+ */
+export class ReviewOutputCappedError extends ReviewParseError {
+	/** The output token count the agent reached when the cap hit (the observed `usage.output`). */
+	readonly outputTokens: number;
+	constructor(outputTokens: number) {
+		super(
+			`review agent output hit the model output cap (${outputTokens} tokens) ` +
+				'and was truncated before emitting its verdict',
+		);
+		this.name = 'ReviewOutputCappedError';
+		this.outputTokens = outputTokens;
+	}
+}
+
 /**
  * Parse the unified review verdict out of the review agent's textual output.
  * The agent may wrap the JSON object in prose / a fenced block, so the first
@@ -246,9 +298,22 @@ function parseEdits(raw: unknown): TaskEdit[] {
 			continue;
 		}
 		const item = e as Record<string, unknown>;
-		if (typeof item.path === 'string' && typeof item.content === 'string') {
-			out.push({path: item.path, content: item.content});
+		if (typeof item.path !== 'string') {
+			continue;
+		}
+		// The body is either inline `content` (legacy / small edits) OR a `src` scratch
+		// path the agent wrote (the decoupled form — see TaskEdit). Carry whichever
+		// is present; the runner resolves it. An edit with NEITHER is dropped (no body
+		// to apply) — but a path-only edit is also tolerated as a no-op marker so a
+		// verdict that names a path it did not actually rewrite does not crash the loop.
+		const edit: TaskEdit = {path: item.path};
+		if (typeof item.content === 'string') {
+			edit.content = item.content;
+		}
+		if (typeof item.src === 'string') {
+			edit.src = item.src;
 		}
+		out.push(edit);
 	}
 	return out;
 }
@@ -314,7 +379,10 @@ export function verdictContractPrompt(): string {
 		'   {"severity": "blocking" | "non-blocking", "question": "\u2026", "context": "\u2026"}',
 		' ],',
 		' "review": "<the human-readable PR-comment prose, when the caller asks for it>",',
-		' "edits": [ {"path": "work/tasks/backlog/<slug>.md", "content": "<full replacement>"} ],',
+		' "edits": [ {"path": "work/tasks/backlog/<slug>.md", "src": "<scratch path you wrote the full body to>"} ],',
+		'       // (inline "content": "<full replacement>" is the legacy small-edit form —',
+		'       //  the tasker loop writes the body to a scratch file + references it by',
+		'       //  "src" so the edits payload cannot cap-truncate this verdict)',
 		' "edit": "<single in-memory replacement body, for the lone-task review>",',
 		' "questions": ["<open question for the human>"],',
 		' "uncertainTasks": [ {"path": "work/tasks/backlog/<slug>.md", "questions": ["\u2026"]} ],',