dorfl 0.11.1 → 0.11.3

package/src/reap-agent-tree.ts

@@ -0,0 +1,221 @@
+/**
+ * **Reap a stopped agent's whole PROCESS TREE, and VERIFY it is gone** (spec
+ * `graceful-pre-timeout-wip-checkpoint`, observation
+ * `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+ *
+ * ## The gap this closes
+ *
+ * The deadline checkpoint used to `child.kill('SIGTERM')` the agent process and
+ * treat the signal as if it were the outcome: the moment pi's own `exit` fired,
+ * the runner saved the WIP, RELEASED the item lock, and let the next tick
+ * dispatch a CONTINUATION agent into the SAME worktree. But `child.kill` signals
+ * exactly ONE pid, and a modern agent is a TREE (subagent processes, MCP servers,
+ * model proxies, tool subshells). Those descendants survive the parent's SIGTERM,
+ * and once pi exits they are re-parented to init — so they can no longer even be
+ * FOUND by walking `ppid`, while they keep writing into the worktree.
+ *
+ * Observed on a real run: the checkpoint saved WIP at 02:13, a continuation agent
+ * onboarded into the same worktree at ~02:15, and the predecessor's session log
+ * kept being written until 02:19:29 — four minutes INTO the successor's run,
+ * whose opening `git status` had already read the tree as clean. Nothing was lost
+ * only because the two happened to touch different files. The shape is the
+ * defect: one lock, one working tree, two live writers. A write landing after the
+ * successor's `git status` is invisible to it; a write landing during its edits
+ * can be clobbered either way; and the successor can commit the predecessor's
+ * half-finished edits as its own, under a message describing something else.
+ *
+ * ## Why the PROCESS GROUP is the handle
+ *
+ * A pid-tree walk cannot work here: the descendants we must reap are precisely
+ * the ones that OUTLIVE the parent, and an orphan's `ppid` is gone. A process
+ * GROUP id, by contrast, is inherited by every descendant and is NOT changed by
+ * re-parenting. So if the agent is spawned as a group LEADER (`detached: true`,
+ * making its pgid equal its pid), `kill(-pgid, …)` reaches the entire tree,
+ * orphans included — which is why {@link reapProcessGroup} takes a pgid and why
+ * `pi-harness.ts` spawns the deadline-capable async launch detached.
+ *
+ * ## Signal, then VERIFY — never assume
+ *
+ * The point of the whole module is that sending a signal is not evidence that
+ * anything died. So: SIGTERM the group, POLL until it is actually gone, escalate
+ * to SIGKILL after a grace, keep polling, and if it STILL will not die, say so
+ * LOUDLY and let the caller refuse to release the lock. A checkpoint that cannot
+ * prove the predecessor is dead must not hand the worktree to a successor.
+ */
+
+/** Poll interval while waiting for a signalled group to actually exit. */
+const REAP_POLL_MS = 50;
+
+/**
+ * How long to wait after SIGTERM before escalating to SIGKILL. Matches
+ * `pi-harness.ts`'s `DEADLINE_SIGKILL_GRACE_MS` intent: enough for an agent to
+ * flush its session log and exit cleanly, short enough not to stall a CI leg.
+ */
+export const REAP_SIGTERM_GRACE_MS = 10_000;
+
+/** How long to keep waiting after SIGKILL before declaring the reap FAILED. */
+export const REAP_SIGKILL_TIMEOUT_MS = 5_000;
+
+/** The outcome of a {@link reapProcessGroup} attempt. */
+export interface ReapResult {
+	/**
+	 * True iff the group is VERIFIED gone (observed non-existent, not merely
+	 * signalled). Only a `true` here licenses releasing the item lock and
+	 * dispatching a successor into the same worktree.
+	 */
+	reaped: boolean;
+	/** True iff SIGKILL was needed (the tree ignored SIGTERM) — worth reporting. */
+	escalatedToSigkill: boolean;
+	/** Total wall-clock ms spent waiting for the tree to die. */
+	waitedMs: number;
+	/** A human-readable account, always populated (the LOUD failure text). */
+	detail: string;
+}
+
+/** Sleep helper (injectable clock is not needed: callers inject `wait` in tests). */
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => {
+		const timer = setTimeout(resolve, ms);
+		timer.unref?.();
+	});
+}
+
+/**
+ * Is any process still alive in process group `pgid`?
+ *
+ * `process.kill(-pgid, 0)` is the liveness probe: signal 0 performs the
+ * permission/existence check WITHOUT delivering a signal (the same technique
+ * `harness.ts`'s {@link pidAlive} uses for a single pid, widened to the group).
+ *
+ *  - It THROWS `ESRCH` when no process in the group exists ⇒ the group is gone.
+ *  - It THROWS `EPERM` when the group exists but we may not signal it. That is
+ *    still "alive", and reporting it as dead would be the very assumption this
+ *    module exists to remove — so `EPERM` reads as ALIVE.
+ *  - It succeeds ⇒ alive.
+ */
+export function processGroupAlive(pgid: number): boolean {
+	if (!Number.isInteger(pgid) || pgid <= 1) {
+		// pgid 0/1 (or a bogus value) would mean "our own group" / init — signalling
+		// those would be catastrophic, so never claim they are ours to reap.
+		return false;
+	}
+	try {
+		process.kill(-pgid, 0);
+		return true;
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code === 'EPERM') {
+			return true; // exists, just not signallable by us.
+		}
+		return false; // ESRCH (or anything else): treat as gone.
+	}
+}
+
+/** Signal a whole process group, tolerating an already-dead group. */
+function signalGroup(pgid: number, signal: NodeJS.Signals): void {
+	try {
+		process.kill(-pgid, signal);
+	} catch {
+		// ESRCH: already gone — the wait loop below observes that and succeeds.
+	}
+}
+
+/**
+ * SIGTERM process group `pgid`, wait for it to ACTUALLY exit, escalate to
+ * SIGKILL after {@link REAP_SIGTERM_GRACE_MS}, and report whether the tree is
+ * VERIFIED gone.
+ *
+ * Bounded by construction: at worst `sigtermGraceMs + sigkillTimeoutMs` before it
+ * returns `reaped: false` with a loud `detail`. It never waits indefinitely, so
+ * it cannot reintroduce the runner-hang the async launch's resolve-on-`exit`
+ * discipline exists to avoid.
+ */
+export async function reapProcessGroup(params: {
+	/** The process GROUP id to reap (the group leader's pid). */
+	pgid: number;
+	sigtermGraceMs?: number;
+	sigkillTimeoutMs?: number;
+	/** Injectable sleep so tests need not burn real seconds. */
+	wait?: (ms: number) => Promise<void>;
+	/**
+	 * Injectable liveness probe (default {@link processGroupAlive}). Exists so the
+	 * REFUSAL path — a tree that survives SIGTERM *and* SIGKILL — can be tested
+	 * deterministically. There is no portable way to create a genuinely unkillable
+	 * process, and the alternative (a group we truly cannot signal) would risk the
+	 * test process itself, so the probe is the seam.
+	 */
+	alive?: (pgid: number) => boolean;
+}): Promise<ReapResult> {
+	const {
+		pgid,
+		sigtermGraceMs = REAP_SIGTERM_GRACE_MS,
+		sigkillTimeoutMs = REAP_SIGKILL_TIMEOUT_MS,
+		wait = sleep,
+		alive = processGroupAlive,
+	} = params;
+	const started = Date.now();
+
+	if (!alive(pgid)) {
+		return {
+			reaped: true,
+			escalatedToSigkill: false,
+			waitedMs: 0,
+			detail: `agent process group ${pgid} was already gone (nothing to reap).`,
+		};
+	}
+
+	// 1. SOFT: ask the whole tree to stop, then WAIT for it to be observably gone.
+	signalGroup(pgid, 'SIGTERM');
+	while (Date.now() - started < sigtermGraceMs) {
+		if (!alive(pgid)) {
+			const waitedMs = Date.now() - started;
+			return {
+				reaped: true,
+				escalatedToSigkill: false,
+				waitedMs,
+				detail:
+					`agent process group ${pgid} exited on SIGTERM after ${waitedMs}ms ` +
+					'(verified gone).',
+			};
+		}
+		await wait(REAP_POLL_MS);
+	}
+
+	// 2. HARD: the tree ignored SIGTERM through the grace. SIGKILL it and keep
+	//    verifying — a wedged agent still holding the worktree must not survive
+	//    into the successor's run.
+	signalGroup(pgid, 'SIGKILL');
+	const killDeadline = Date.now() + sigkillTimeoutMs;
+	while (Date.now() < killDeadline) {
+		if (!alive(pgid)) {
+			const waitedMs = Date.now() - started;
+			return {
+				reaped: true,
+				escalatedToSigkill: true,
+				waitedMs,
+				detail:
+					`agent process group ${pgid} ignored SIGTERM and was SIGKILLed; ` +
+					`exited after ${waitedMs}ms (verified gone).`,
+			};
+		}
+		await wait(REAP_POLL_MS);
+	}
+
+	// 3. LOUD FAILURE: we cannot prove the predecessor is dead. Say exactly that,
+	//    and exactly what the caller must not do as a result.
+	const waitedMs = Date.now() - started;
+	return {
+		reaped: false,
+		escalatedToSigkill: true,
+		waitedMs,
+		detail:
+			`REFUSING TO PROCEED: agent process group ${pgid} is STILL ALIVE ${waitedMs}ms ` +
+			'after SIGTERM and SIGKILL (an unkillable/uninterruptible descendant — e.g. a ' +
+			'process wedged in a kernel call, or one we lack permission to signal). It may ' +
+			'still be WRITING to the worktree, so the item lock must NOT be released and no ' +
+			'successor agent may onboard here: two live writers in one working tree can ' +
+			'silently clobber each other and let a successor commit the predecessor’s ' +
+			`half-finished edits. Inspect and kill it by hand (\`ps -g ${pgid}\`, ` +
+			`\`kill -9 -${pgid}\`) before re-running this item.`,
+	};
+}

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`,