dorfl 0.14.2 → 0.15.0

package/src/phase-recorder.ts

@@ -0,0 +1,350 @@
+import {ledgerWrite} from './ledger-write.js';
+import {refWrite} from './ref-write.js';
+import {integrationLand} from './integration-core.js';
+import type {ReviewProvider} from './integrator.js';
+import type {IssueProvider} from './issue-provider.js';
+import {enterPhase, type Phase} from './phase.js';
+
+/**
+ * **Record at the seams, resume at the boundary** (spec
+ * `ci-agent-job-without-write-token` §4, task `ci-split-phase-mode-and-guards`).
+ *
+ * In the `agent` phase the job token cannot write, and dorfl must not try: every
+ * write seam is replaced by a RECORDING implementation. The first post-agent
+ * write call the recorder KNOWS captures its intent (seam, method, input) and
+ * halts the pipeline with a {@link PhaseHaltSentinel}, which the phase driver
+ * ({@link runAgentPhase}) catches. Nothing after the first write runs in the
+ * agent phase, so no agent-phase step ever depends on a write RESULT (a PR URL,
+ * `mergeNonFastForward`, `publishedHead`, a CAS rejection).
+ *
+ * A write seam call the recorder does NOT know throws
+ * {@link UnrecordedWriteError}: an unrouted write is a bug the tests catch.
+ *
+ * The write seams covered here are every seam a CI path writes through
+ * (task `ci-split-route-direct-writes-through-seams`): `ledgerWrite` (which also
+ * reaches the integrator, via `applyCompleteTransition`), `refWrite`, the review
+ * provider and the issue provider (whose READS pass through), plus the
+ * `integrationLand` seam (`integration-core.ts`): the land half of the build's
+ * rebase-to-integrate tail, whose call is the success path's boundary (task
+ * `ci-split-build-path`). Which seam calls
+ * each path records, and how the captured input maps to a handoff intent kind
+ * (`ci-handoff-format.ts`), is decided by the per-path split tasks; this module
+ * is the shared machinery.
+ *
+ * The captured `input` is the seam's in-memory argument, which may hold an env
+ * with credentials: it is NEVER serialised as-is. The per-path code builds the
+ * handoff record from it field by field.
+ */
+
+/** The write seams a CI path reaches (the recorder replaces all of them). */
+export type WriteSeamName =
+	| 'ledgerWrite'
+	| 'refWrite'
+	| 'integrationLand'
+	| 'reviewProvider'
+	| 'issueProvider';
+
+/** A seam call id: `<seam>.<method>`, e.g. `refWrite.pushContinuedBranch`. */
+export type WriteSeamCall = `${WriteSeamName}.${string}`;
+
+/** The captured intent of the first recorded write. */
+export interface RecordedWriteIntent {
+	/** The seam the write went through. */
+	seam: WriteSeamName;
+	/** The seam method called. */
+	method: string;
+	/** The call's argument, in memory only (see the module comment). */
+	input: unknown;
+	/**
+	 * What the pipeline said the boundary IS, when it said so just before the
+	 * write ({@link annotatePhaseBoundary}): several outcomes reach the same seam
+	 * call (a red gate, an agent failure and a STOP all bounce through
+	 * `ledgerWrite.applyNeedsAttentionTransition`), and the per-path code needs to
+	 * tell them apart. In memory only, like {@link input}.
+	 */
+	annotation?: unknown;
+}
+
+/**
+ * Thrown by a recording seam on the first recorded write: it halts the
+ * pipeline so nothing after the boundary runs. The phase driver catches it; it
+ * is never a failure.
+ */
+export class PhaseHaltSentinel extends Error {
+	override readonly name = 'PhaseHaltSentinel';
+	constructor(readonly intent: RecordedWriteIntent) {
+		super(
+			`agent phase halted at the first write (${intent.seam}.${intent.method}); ` +
+				'the apply phase performs it.',
+		);
+	}
+}
+
+/**
+ * A write seam call the recorder does not know, in the agent phase. Always a
+ * dorfl bug: the write is not routed through the phase split.
+ */
+export class UnrecordedWriteError extends Error {
+	override readonly name = 'UnrecordedWriteError';
+	constructor(
+		readonly seam: WriteSeamName,
+		readonly method: string,
+	) {
+		super(
+			`agent phase: unrecorded write ${seam}.${method} (the agent job holds a ` +
+				'read-only token, and this write is not routed to the apply phase). ' +
+				'This is a dorfl bug in the phase split.',
+		);
+	}
+}
+
+/** The recording state one agent-phase run shares across every seam. */
+export interface PhaseRecorder {
+	/** The seam calls this recorder captures (every other write throws). */
+	readonly recordable: ReadonlySet<WriteSeamCall>;
+	/** The first recorded write, once the pipeline has reached it. */
+	captured(): RecordedWriteIntent | undefined;
+	/** The first unrecorded write, if the pipeline made one. */
+	violation(): UnrecordedWriteError | undefined;
+	/**
+	 * Remember what the NEXT write is (see {@link annotatePhaseBoundary}); the
+	 * first recorded write captures the latest annotation. Ignored once halted.
+	 */
+	annotate(annotation: unknown): void;
+	/**
+	 * Handle one write seam call: always throws. The first recorded call
+	 * captures its intent and throws a {@link PhaseHaltSentinel}; any later write
+	 * re-throws that same sentinel (nothing after the boundary may write). An
+	 * unknown call throws (and remembers) an {@link UnrecordedWriteError}.
+	 */
+	write(seam: WriteSeamName, method: string, input: unknown): never;
+}
+
+/** Create a {@link PhaseRecorder} that captures exactly the `record` calls. */
+export function createPhaseRecorder(options: {
+	record: Iterable<WriteSeamCall>;
+}): PhaseRecorder {
+	const recordable = new Set<WriteSeamCall>(options.record);
+	let sentinel: PhaseHaltSentinel | undefined;
+	let violation: UnrecordedWriteError | undefined;
+	let annotation: unknown;
+	return {
+		recordable,
+		captured: () => sentinel?.intent,
+		violation: () => violation,
+		annotate(next): void {
+			if (sentinel === undefined) annotation = next;
+		},
+		write(seam, method, input): never {
+			if (violation !== undefined) {
+				throw violation;
+			}
+			if (sentinel !== undefined) {
+				throw sentinel;
+			}
+			if (!recordable.has(`${seam}.${method}`)) {
+				violation = new UnrecordedWriteError(seam, method);
+				throw violation;
+			}
+			sentinel = new PhaseHaltSentinel({
+				seam,
+				method,
+				input,
+				...(annotation === undefined ? {} : {annotation}),
+			});
+			throw sentinel;
+		},
+	};
+}
+
+/**
+ * Replace EVERY method of the process-wide `ledgerWrite`, `refWrite` and
+ * `integrationLand` seams with a recording one, and return a function restoring the originals. Every
+ * method is enumerated from the seam object, so a seam method added later is
+ * covered (as an unrecorded write) without touching this function.
+ */
+export function installRecordingSeams(recorder: PhaseRecorder): () => void {
+	const previousRecorder = activeRecorder;
+	activeRecorder = recorder;
+	const restores = [
+		() => {
+			activeRecorder = previousRecorder;
+		},
+		swapMethods('ledgerWrite', ledgerWrite, recorder),
+		swapMethods('refWrite', refWrite, recorder),
+		swapMethods('integrationLand', integrationLand, recorder),
+	];
+	return () => {
+		for (const restore of restores.reverse()) {
+			restore();
+		}
+	};
+}
+
+/** The recorder the process-wide seams write into now (agent phase only). */
+let activeRecorder: PhaseRecorder | undefined;
+
+/**
+ * Say what the next write IS, for the agent-phase recorder to capture with it.
+ * A no-op outside the agent phase (no recorder is installed), so a pipeline
+ * calls it unconditionally right before a write seam call whose seam and method
+ * alone do not name the outcome (task `ci-split-build-path-non-integrate-intents`:
+ * an agent failure, a STOP and a red gate all bounce through the same seam).
+ * The annotation never reaches the arbiter; the per-path code maps it to a
+ * handoff intent.
+ */
+export function annotatePhaseBoundary(annotation: unknown): void {
+	activeRecorder?.annotate(annotation);
+}
+
+function swapMethods(
+	seam: WriteSeamName,
+	target: object,
+	recorder: PhaseRecorder,
+): () => void {
+	const record = target as Record<string, unknown>;
+	const originals = new Map<string, unknown>();
+	for (const [method, value] of Object.entries(record)) {
+		if (typeof value !== 'function') {
+			continue;
+		}
+		originals.set(method, value);
+		record[method] = (input: unknown) => recorder.write(seam, method, input);
+	}
+	return () => {
+		for (const [method, value] of originals) {
+			record[method] = value;
+		}
+	};
+}
+
+/**
+ * A recording {@link ReviewProvider}: every method is a write, so every call
+ * goes to the recorder. `name` is the wrapped provider's.
+ */
+export function recordingReviewProvider(
+	inner: ReviewProvider,
+	recorder: PhaseRecorder,
+): ReviewProvider {
+	const seam: WriteSeamName = 'reviewProvider';
+	return {
+		name: inner.name,
+		openRequest: (input) => recorder.write(seam, 'openRequest', input),
+		postPRComment: (input) => recorder.write(seam, 'postPRComment', input),
+		postPRCommentOnBranch: (input) =>
+			recorder.write(seam, 'postPRCommentOnBranch', input),
+		closeRequestOnBranch: (input) =>
+			recorder.write(seam, 'closeRequestOnBranch', input),
+	};
+}
+
+/**
+ * A recording {@link IssueProvider}: the reads (`getIssue`, `listComments`,
+ * `getLabels`) pass through to `inner` (the agent job's read token serves
+ * them); every write goes to the recorder.
+ */
+export function recordingIssueProvider(
+	inner: IssueProvider,
+	recorder: PhaseRecorder,
+): IssueProvider {
+	const seam: WriteSeamName = 'issueProvider';
+	return {
+		name: inner.name,
+		getIssue: (input) => inner.getIssue(input),
+		listComments: (input) => inner.listComments(input),
+		getLabels: (input) => inner.getLabels(input),
+		postIssueComment: (input) =>
+			recorder.write(seam, 'postIssueComment', input),
+		addLabel: (input) => recorder.write(seam, 'addLabel', input),
+		removeLabel: (input) => recorder.write(seam, 'removeLabel', input),
+		closeIssue: (input) => recorder.write(seam, 'closeIssue', input),
+	};
+}
+
+/** The outcome of one {@link runAgentPhase}. */
+export type AgentPhaseOutcome<T> =
+	| {
+			/** The pipeline finished without reaching a write. */
+			halted: false;
+			result: T;
+	  }
+	| {
+			/** The pipeline reached its first write and stopped there. */
+			halted: true;
+			/** The captured first write. */
+			intent: RecordedWriteIntent;
+			/**
+			 * True when the pipeline CAUGHT the sentinel and returned normally
+			 * instead of letting it propagate. The intent still stands (the recorder
+			 * is authoritative); the flag lets the per-path tasks assert their
+			 * pipeline stops cleanly at the boundary.
+			 */
+			sentinelSwallowed: boolean;
+	  };
+
+/**
+ * The agent-phase driver: run `pipeline` in the `agent` phase with every write
+ * seam recording (the process-wide `ledgerWrite` / `refWrite`; the pipeline
+ * wraps its injected providers with {@link recordingReviewProvider} /
+ * {@link recordingIssueProvider} on the same `recorder`), catch the
+ * {@link PhaseHaltSentinel}, and restore the seams and the previous phase.
+ *
+ * The recorder, not the exception, is authoritative: a pipeline that swallows
+ * the sentinel in a broad `catch` is still reported as halted at the captured
+ * intent, and an {@link UnrecordedWriteError} is re-thrown even if the pipeline
+ * swallowed it.
+ */
+export async function runAgentPhase<T>(
+	recorder: PhaseRecorder,
+	pipeline: () => Promise<T>,
+): Promise<AgentPhaseOutcome<T>> {
+	const restorePhase = enterPhase('agent');
+	const restoreSeams = installRecordingSeams(recorder);
+	let result: T | undefined;
+	let caught: unknown;
+	let threw = false;
+	try {
+		result = await pipeline();
+	} catch (err) {
+		threw = true;
+		caught = err;
+	} finally {
+		restoreSeams();
+		restorePhase();
+	}
+	const violation = recorder.violation();
+	if (violation !== undefined) {
+		throw violation;
+	}
+	const intent = recorder.captured();
+	if (intent !== undefined) {
+		if (threw && !(caught instanceof PhaseHaltSentinel)) {
+			throw caught;
+		}
+		return {halted: true, intent, sentinelSwallowed: !threw};
+	}
+	if (threw) {
+		throw caught;
+	}
+	return {halted: false, result: result as T};
+}
+
+/**
+ * Enter `phase` for the whole (one-shot) CLI process, the `--phase` entry
+ * point: the phase guards fire from here on, and in the `agent` phase every
+ * process-wide write seam records into a recorder that knows NO write, so any
+ * write that is not inside a per-path {@link runAgentPhase} (which installs its
+ * own recorder on top) throws {@link UnrecordedWriteError}. Returns a function
+ * restoring the previous state (tests; the CLI process simply exits).
+ */
+export function activateProcessPhase(phase: Phase): () => void {
+	const restorePhase = enterPhase(phase);
+	const restoreSeams =
+		phase === 'agent'
+			? installRecordingSeams(createPhaseRecorder({record: []}))
+			: () => {};
+	return () => {
+		restoreSeams();
+		restorePhase();
+	};
+}

package/src/phase.ts

@@ -0,0 +1,177 @@
+/**
+ * The **CI phase mode** (spec `ci-agent-job-without-write-token`, ADR
+ * `ci-agent-job-holds-no-write-token`, task `ci-split-phase-mode-and-guards`).
+ *
+ * In GitHub Actions every CI item runs as three jobs, and the SAME dorfl verb
+ * (`intake`, `advance`; `do` for parity) runs once per job with a hidden
+ * `--phase`:
+ *
+ *  - **`lock`**: the write token, NO agent, NO repository code. Takes the lock
+ *    (and the other pre-agent writes) and emits trusted facts.
+ *  - **`agent`**: a read-only token (`persist-credentials: false`). Runs the
+ *    agents, the gate and every local commit, and RECORDS the first write
+ *    instead of performing it (see `phase-recorder.ts`).
+ *  - **`apply`**: the write token, NO agent, NO repository code. Performs the
+ *    recorded writes from the agent job's handoff, treated as hostile.
+ *
+ * Absent `--phase` is today's single process, byte for byte: the active phase
+ * is `undefined` and every guard below is a no-op.
+ *
+ * The active phase is PROCESS-GLOBAL on purpose: a phase run is a one-shot CI
+ * process, and the chokepoints it must guard (`agentLaunchEnv`, the harness
+ * adapters, `runVerify`, `runPrepare`, the write seams) are reached from deep
+ * inside pipelines that do not carry a context. The same value is ALSO threaded
+ * through the run context (`AdvanceContext.phase`, `DoOptions.phase`,
+ * `PerformIntakeOptions.phase`) so the pipelines can branch on it; the global
+ * is what the guards trust.
+ */
+
+/** One of the three CI jobs a dorfl verb runs as (see the module comment). */
+export type Phase = 'lock' | 'agent' | 'apply';
+
+/** Every {@link Phase}, in pipeline order. */
+export const PHASES: readonly Phase[] = ['lock', 'agent', 'apply'];
+
+/**
+ * A `--phase` value that is not allowed: an unknown phase name, or any phase
+ * outside GitHub Actions. A usage error, raised before anything runs.
+ */
+export class PhaseUsageError extends Error {
+	override readonly name = 'PhaseUsageError';
+}
+
+/**
+ * Parse and admit a `--phase` value. It must be one of {@link PHASES}, and it is
+ * only allowed when `GITHUB_ACTIONS=true` in `env`, so a phase cannot change
+ * laptop behaviour by accident. `allowOutsideActions` is the explicit TEST
+ * override (never wired to a flag, an env var or config).
+ */
+export function parsePhase(
+	raw: string,
+	options: {env?: NodeJS.ProcessEnv; allowOutsideActions?: boolean} = {},
+): Phase {
+	const value = raw.trim();
+	if (!(PHASES as readonly string[]).includes(value)) {
+		throw new PhaseUsageError(
+			`--phase must be one of ${PHASES.join(', ')} (got '${raw}').`,
+		);
+	}
+	const env = options.env ?? process.env;
+	if (env.GITHUB_ACTIONS !== 'true' && options.allowOutsideActions !== true) {
+		throw new PhaseUsageError(
+			'--phase is CI-only: it splits one item into the lock, agent and apply ' +
+				'jobs of a GitHub Actions workflow and requires GITHUB_ACTIONS=true. ' +
+				'Run the verb without --phase for the normal single-process behaviour.',
+		);
+	}
+	return value as Phase;
+}
+
+let current: Phase | undefined;
+
+/** The phase this process runs as, or `undefined` (no `--phase`: today's behaviour). */
+export function activePhase(): Phase | undefined {
+	return current;
+}
+
+/**
+ * Make `phase` the active phase and return a function restoring the previous
+ * one. The CLI enters the phase once for the whole (one-shot) process; the
+ * phase drivers and tests scope it with the returned restore.
+ */
+export function enterPhase(phase: Phase | undefined): () => void {
+	const previous = current;
+	current = phase;
+	return () => {
+		current = previous;
+	};
+}
+
+/** What a {@link PhaseGuardError} refused to do. */
+export type GuardedOperation =
+	| 'agent-launch-env'
+	| 'harness-launch'
+	| 'verify'
+	| 'prepare';
+
+/**
+ * A phase guard fired: dorfl tried to launch an agent or run repository code in
+ * the `lock` or `apply` phase, whose job holds the write token. Always a dorfl
+ * BUG (the pipeline split is wrong), never a user error; defence in depth that
+ * holds whatever the workflow shape.
+ */
+export class PhaseGuardError extends Error {
+	override readonly name = 'PhaseGuardError';
+	constructor(
+		readonly phase: Phase,
+		readonly operation: GuardedOperation,
+	) {
+		super(
+			`phase guard: '${operation}' is not allowed in the ${phase} phase ` +
+				'(the lock and apply jobs hold the write token, so they never launch ' +
+				'an agent or run repository code). This is a dorfl bug in the phase split.',
+		);
+	}
+}
+
+/**
+ * Throw a {@link PhaseGuardError} when the active phase is `lock` or `apply`.
+ * Called at every chokepoint that launches an agent or runs repository code:
+ * `agentLaunchEnv`, each harness adapter's launch, `runVerify` and
+ * `runPrepare`. A no-op without a phase and in the `agent` phase.
+ */
+export function assertAgentOrRepoCodeAllowed(
+	operation: GuardedOperation,
+): void {
+	const phase = current;
+	if (phase === 'lock' || phase === 'apply') {
+		throw new PhaseGuardError(phase, operation);
+	}
+}
+
+/**
+ * Every CLI verb that can launch an agent (autonomous or interactive) or run
+ * repository code (`prepare` / `verify`). A CI job that runs one of these must
+ * be the agent job (read-only token, no persisted credential) or pass
+ * `--phase lock|apply`. The workflow guard (task `ci-split-generate-workflows`)
+ * and the single-job warning (task `ci-split-warn-single-job-workflows`) read
+ * this set; `phase-cli.test.ts` fails when a CLI verb is in neither this set
+ * nor {@link NON_AGENT_VERBS}.
+ */
+export const AGENT_SPAWNING_VERBS: ReadonlySet<string> = new Set([
+	'run',
+	'verify',
+	'start',
+	'resume',
+	'work-on',
+	'complete',
+	'do',
+	'advance',
+	'intake',
+]);
+
+/**
+ * Every CLI verb that neither launches an agent nor runs repository code (it
+ * reads, or writes refs / the ledger / provider state only). The explicit
+ * complement of {@link AGENT_SPAWNING_VERBS}, so a new verb must be classified.
+ */
+export const NON_AGENT_VERBS: ReadonlySet<string> = new Set([
+	'config',
+	'scan',
+	'claim',
+	'prompt',
+	'gc',
+	'sync',
+	'prd-to-spec',
+	'status',
+	'requeue',
+	'promote',
+	'release-lock',
+	'migrate-stuck-locks',
+	'drop',
+	'close-merged-issues',
+	'surface-merge-questions',
+	'remote',
+	'install-ci',
+	'skills',
+]);

package/src/pi-harness.ts

@@ -1,9 +1,12 @@
 import {spawn, spawnSync} from 'node:child_process';
 import {existsSync, readFileSync, writeSync} from 'node:fs';
+import {assertAgentOrRepoCodeAllowed} from './phase.js';
 import {
 	NullHarness,
+	agentLaunchEnv,
 	pidAlive,
 	registerHarness,
+	type CutOffTurn,
 	type Harness,
 	type HarnessRecord,
 	type InteractiveLaunchInput,
@@ -12,7 +15,11 @@ import {
 	type LaunchResult,
 } from './harness.js';
 import {generateSessionPath} from './session-path.js';
-import {lastAssistantTurn, isOutputCappedTurn} from './watch-session.js';
+import {
+	lastAssistantTurn,
+	isOutputCappedTurn,
+	cutOffTurnOf,
+} from './watch-session.js';
 import {reapProcessGroup} from './reap-agent-tree.js';
 import type {HarnessAdapter} from './config.js';
 
@@ -246,6 +253,8 @@ export class PiHarness implements Harness {
 	}
 
 	launch(input: LaunchInput): LaunchResult {
+		// PHASE GUARD first: no launch at all in the CI lock/apply phases.
+		assertAgentOrRepoCodeAllowed('harness-launch');
 		const sessionFile = this.resolveSessionFile(input);
 		const args = this.buildArgs(input, sessionFile);
 		const result = spawnSync(this.piBin, args, {
@@ -255,7 +264,8 @@ export class PiHarness implements Harness {
 			cwd: input.dir,
 			encoding: 'utf8',
 			input: input.prompt,
-			env: input.env ?? process.env,
+			// No GitHub token reaches a CI agent (see agentLaunchEnv).
+			env: agentLaunchEnv(input.env),
 			maxBuffer: 64 * 1024 * 1024,
 		});
 		if (result.error) {
@@ -280,7 +290,7 @@ export class PiHarness implements Harness {
 			// 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. The
-			// same turn's stop_reason/usage feed the outputCapped cap-truncation
+			// same turn's stop reason/usage feed the outputCapped cap-truncation
 			// signal (observation `tasker-review-edits-payload-caps-the-verdict-response`).
 			...readAssistantOutput(sessionFile),
 		};
@@ -317,6 +327,8 @@ export class PiHarness implements Harness {
 	 * belt-and-suspenders backstop bounding any such residual leak.
 	 */
 	launchAsync(input: LaunchInput): Promise<LaunchResult> {
+		// PHASE GUARD first: no launch at all in the CI lock/apply phases.
+		assertAgentOrRepoCodeAllowed('harness-launch');
 		const sessionFile = this.resolveSessionFile(input);
 		const args = this.buildArgs(input, sessionFile);
 		const record: PiHarnessRecord = {
@@ -333,7 +345,8 @@ export class PiHarness implements Harness {
 				// Same as `launch`: spawn in the repo/worktree dir so the session
 				// header `cwd` groups the dashboard correctly (invariant #3).
 				cwd: input.dir,
-				env: input.env ?? process.env,
+				// No GitHub token reaches a CI agent (see agentLaunchEnv).
+				env: agentLaunchEnv(input.env),
 				stdio: ['pipe', 'pipe', 'pipe'],
 				// PROCESS-GROUP LEADER (observation
 				// `checkpoint-releases-lock-while-predecessor-agent-still-writes`): pi's
@@ -483,7 +496,7 @@ export class PiHarness implements Harness {
 						// Read the agent's ANSWER from the `.jsonl` at `exit` — the same
 						// last-assistant-turn read `launch` does at return (task
 						// `harness-agent-output`); the process has exited so the log is final.
-						// The same turn's stop_reason/usage feed the outputCapped signal.
+						// The same turn's stop reason/usage feed the outputCapped signal.
 						...readAssistantOutput(sessionFile),
 					});
 				};
@@ -558,6 +571,8 @@ export class PiHarness implements Harness {
 	 * nothing to capture, so it returns only the exit code.
 	 */
 	launchInteractive(input: InteractiveLaunchInput): InteractiveLaunchResult {
+		// PHASE GUARD first: no launch at all in the CI lock/apply phases.
+		assertAgentOrRepoCodeAllowed('harness-launch');
 		const sessionFile = this.resolveSessionFile({
 			dir: input.dir,
 			slug: input.slug,
@@ -653,6 +668,7 @@ export function piSessionExists(record: HarnessRecord): boolean {
 function readAssistantOutput(sessionFile: string): {
 	output?: string;
 	outputCapped?: number;
+	cutOffTurn?: CutOffTurn;
 } {
 	let jsonl: string;
 	try {
@@ -664,6 +680,10 @@ function readAssistantOutput(sessionFile: string): {
 	return {
 		output: turn.text,
 		outputCapped: isOutputCappedTurn(turn) ? turn.outputTokens : undefined,
+		// How the run's FINAL turn ended (task
+		// `a-truncated-agent-turn-routes-as-agent-failed`): a `length`/`error` stop
+		// makes an empty diff an agent failure, not a deliberate empty-diff STOP.
+		cutOffTurn: cutOffTurnOf(turn),
 	};
 }
 

package/src/prepare.ts

@@ -1,4 +1,5 @@
 import {spawn} from 'node:child_process';
+import {assertAgentOrRepoCodeAllowed} from './phase.js';
 import {existsSync, mkdirSync, writeFileSync} from 'node:fs';
 import {dirname, join} from 'node:path';
 import {run} from './git.js';
@@ -93,6 +94,9 @@ export interface RunPrepareResult {
 export async function runPrepare(
 	options: RunPrepareOptions,
 ): Promise<RunPrepareResult> {
+	// PHASE GUARD: the gate runs repository code, never in the CI lock/apply
+	// phases (their jobs hold the write token; see `phase.ts`).
+	assertAgentOrRepoCodeAllowed('prepare');
 	const commands = resolvePrepareCommands(options.prepare);
 	if (commands.length === 0) {
 		return {exitCode: 0, commands, passed: true, noop: true};