dorfl 0.11.2 → 0.11.3

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-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"]} ],',

package/src/tasker-review-loop.ts

@@ -1,4 +1,4 @@
-import {readFileSync, readdirSync, writeFileSync} from 'node:fs';
+import {readFileSync, readdirSync, writeFileSync, rmSync} from 'node:fs';
 import {join} from 'node:path';
 import {
 	workFolderPrefix,
@@ -12,6 +12,7 @@ import {launchWithOptionalWatch} from './agent-launch.js';
 import {
 	parseReviewVerdict,
 	ReviewParseError,
+	ReviewOutputCappedError,
 	reviewDisciplinePrompt,
 	verdictContractPrompt,
 	type ReviewFinding,
@@ -26,6 +27,20 @@ import {
 // `review-protocol-doc-and-shared-machinery`).
 export type {TaskEdit, UncertainTask} from './review-verdict.js';
 export {parseReviewVerdict as parseTaskReviewVerdict} from './review-verdict.js';
+export {ReviewOutputCappedError as TaskReviewOutputCappedError} from './review-verdict.js';
+
+/**
+ * The SCRATCH directory the review agent writes full-replacement task bodies to
+ * (the DECOUPLED edits channel — see {@link TaskEdit.src}). Sibling of `backlog/`
+ * under `work/tasks/`; NOT a {@link WorkFolderKey}, so it is never scanned by
+ * {@link newOrChangedBacklog} (which reads `work/tasks/backlog/` only) and never
+ * appears as a candidate task. The runner reads each `src` file, applies it to the
+ * target `work/tasks/backlog/<name>.md` through the SAME scope fence, then DELETES
+ * it — so the integrate's `git add -A` never sweeps the scratch into the commit. A
+ * start-of-loop clean (see {@link cleanReviewEditsScratch}) reaps any stragglers a
+ * crashed prior run left behind.
+ */
+export const REVIEW_EDITS_SCRATCH_DIR = 'work/tasks/.review-edits';
 
 /**
  * **The tasker review→edit→re-review→converge LOOP** (`slicer-review-edit-loop`,
@@ -247,6 +262,10 @@ export async function runTaskReviewLoop(
 	// tasks, never pre-existing landed ones (the requeue fix). No snapshot ⇒ an
 	// empty one (the legacy whole-directory behaviour for the empty-backlog case).
 	const before = options.before ?? new Map<string, string>();
+	// Reap any review-edits SCRATCH a crashed prior run left behind, so the
+	// integrate's `git add -A` never sweeps stragglers into this run's commit. The
+	// loop deletes each `src` it applies too; this is the crash-recovery backstop.
+	cleanReviewEditsScratch(options.cwd);
 
 	let totalPasses = 0;
 	let last: SingleExecutionResult | undefined;
@@ -456,6 +475,15 @@ function applyEdits(
 			);
 			continue;
 		}
+		// Resolve the edit BODY: inline `content` (legacy / small edits) OR a `src`
+		// scratch file the agent wrote (the decoupled form — see TaskEdit.src). The
+		// `src` form keeps the verdict JSON bounded by the NUMBER of edits, not the
+		// total body size, so a large decomposition can no longer cap-truncate the
+		// verdict. A path-only edit with no resolvable body is a no-op marker.
+		const body = resolveEditBody(cwd, edit, note);
+		if (body === undefined) {
+			continue;
+		}
 		// A pre-existing task this run did NOT touch must not be overwritten: it is
 		// in `before` and the current on-disk content still equals the snapshot.
 		if (before.has(filename)) {
@@ -475,7 +503,70 @@ function applyEdits(
 			}
 		}
 		const abs = join(cwd, normalized);
-		writeFileSync(abs, edit.content);
+		writeFileSync(abs, body);
+	}
+}
+
+/**
+ * Resolve an edit's full-replacement BODY: inline `content` (legacy) takes
+ * precedence, else read the `src` scratch file the agent wrote. Returns
+ * `undefined` when there is no body to apply (neither channel present, or `src`
+ * missing / outside the scratch fence / unreadable). The `src` is fenced to
+ * {@link REVIEW_EDITS_SCRATCH_DIR} (no `..`) so the agent cannot pull an arbitrary
+ * repo file in as the edit body. A read `src` is DELETED after reading so the
+ * integrate's `git add -A` never sweeps the scratch into the commit.
+ */
+function resolveEditBody(
+	cwd: string,
+	edit: TaskEdit,
+	note: (message: string) => void,
+): string | undefined {
+	if (edit.content !== undefined) {
+		return edit.content;
+	}
+	if (edit.src === undefined) {
+		return undefined;
+	}
+	const src = edit.src.replace(/\\/g, '/');
+	if (src.includes('..') || !src.startsWith(REVIEW_EDITS_SCRATCH_DIR + '/')) {
+		note(
+			`Skipped a review edit whose src is outside ${REVIEW_EDITS_SCRATCH_DIR}/ (${edit.src}) — ` +
+				'the scratch body must live under the review-edits scratch dir.',
+		);
+		return undefined;
+	}
+	const srcAbs = join(cwd, src);
+	let body: string | undefined;
+	try {
+		body = readFileSync(srcAbs, 'utf8');
+	} catch {
+		note(
+			`Skipped a review edit whose src scratch file is missing/unreadable (${edit.src}) — ` +
+				'the agent did not write it before emitting the verdict.',
+		);
+		return undefined;
+	}
+	// Reap the scratch file now the body is in hand — never let it survive to the
+	// integrate's `git add -A` (best-effort; a missing file is already gone).
+	try {
+		rmSync(srcAbs, {force: true});
+	} catch {
+		// Best-effort: a failure to delete does not block the apply.
+	}
+	return body;
+}
+
+/**
+ * Best-effort reap of the {@link REVIEW_EDITS_SCRATCH_DIR} (a crashed prior run may
+ * have left scratch bodies behind; the integrate's `git add -A` would otherwise
+ * sweep them into the next tasking commit). Called at the START of a loop run.
+ * Never throws — a missing/unreadable dir is the normal steady state.
+ */
+function cleanReviewEditsScratch(cwd: string): void {
+	try {
+		rmSync(join(cwd, REVIEW_EDITS_SCRATCH_DIR), {recursive: true, force: true});
+	} catch {
+		// Best-effort.
 	}
 }
 
@@ -600,7 +691,28 @@ export function harnessTaskReviewGate(
 				}`,
 			);
 		}
-		return parseReviewVerdict(readOutput(launched.output));
+		// CAP-TRUNCATION NAMING (observation
+		// `tasker-review-edits-payload-caps-the-verdict-response`): attempt the parse
+		// FIRST so a verdict that DID complete (even on a capped turn — e.g. the cap
+		// hit trailing prose after the JSON closed) is HONORED, not discarded. Only
+		// when the parse FAILS AND the adapter surfaced an output-cap signal do we
+		// re-throw the NAMED {@link ReviewOutputCappedError} (a subclass of
+		// ReviewParseError, so the bounce routing still catches it — NEVER a silent
+		// approve). A parse failure with no cap signal stays the generic
+		// ReviewParseError (the adapter could not see the signal — still
+		// needs-attention, still never a silent approve).
+		try {
+			return parseReviewVerdict(readOutput(launched.output));
+		} catch (err) {
+			if (
+				launched.outputCapped !== undefined &&
+				(err instanceof ReviewParseError ||
+					err instanceof ReviewOutputCappedError)
+			) {
+				throw new ReviewOutputCappedError(launched.outputCapped);
+			}
+			throw err;
+		}
 	};
 }
 
@@ -634,16 +746,26 @@ export function buildTaskReviewPrompt(input: TaskReviewGateInput): string {
 		`loop, not a one-shot gate.`,
 		``,
 		`This is review pass ${input.pass} (fresh context ${input.execution}). You`,
-		`do NOT edit files or run git yourself — you EMIT the edits to apply as FULL`,
-		`replacement content and the runner applies them, then re-reviews. Tasks`,
+		`do NOT run git. For the EDITS, WRITE each full-replacement task body to a`,
+		`SCRATCH file under ${REVIEW_EDITS_SCRATCH_DIR}/ and reference it by path in the`,
+		`"edits" channel — do NOT inline the body in the JSON, and do NOT edit the`,
+		`candidate task files directly (the runner applies your scratch body to the`,
+		`candidate task through its scope fence + deletes the scratch; on a review`,
+		`failure the tasker's original candidates stay pristine for recovery). This`,
+		`keeps the verdict JSON bounded by the NUMBER of edits, not the total body size,`,
+		`so a large decomposition cannot cap-truncate the verdict. Tasks`,
 		`measurably keep improving when reviewed, so propose edits that fix the`,
 		`findings; converge when a pass finds NO NEW blocking issue.`,
 		``,
 		verdictContractPrompt(),
 		``,
 		`Fill the channels appropriate to THIS caller (the tasker improver loop):`,
-		`  - "edits" — full-content replacements for candidate task files when you`,
-		`    can FIX a finding by editing (the natural improver step).`,
+		`  - "edits" — for each candidate task file you want to rewrite, WRITE the full`,
+		`    replacement body to ${REVIEW_EDITS_SCRATCH_DIR}/<name>.md (the runner reads`,
+		`    it, applies it to work/tasks/backlog/<name>.md, then deletes the scratch),`,
+		`    and emit {"path": "work/tasks/backlog/<name>.md", "src": "${REVIEW_EDITS_SCRATCH_DIR}/<name>.md"}.`,
+		`    Do NOT put the body in "content" — that shares the capped response with`,
+		`    the verdict and cap-truncates it on a large set.`,
 		`  - "uncertainTasks" — specific tasks you cannot make buildable (each gets`,
 		`    \`needsAnswers: true\` with the questions in its body).`,
 		`  - "decompositionUnclear" — the WHOLE decomposition is unsound (the spec is`,