dorfl 0.14.2 → 0.15.0

package/src/do.ts

@@ -1,8 +1,10 @@
+import type {Phase} from './phase.js';
+import {continueRebaseSentence} from './continue-branch.js';
 import {existsSync, mkdirSync, readFileSync, rmSync} from 'node:fs';
 import {dirname, join} from 'node:path';
 import {performStart} from './start.js';
 import {performComplete} from './complete.js';
-import {performClaim} from './claim-cas.js';
+import {performClaim, type ClaimCasResult} from './claim-cas.js';
 import {
 	resolveSlug,
 	SlugResolutionError,
@@ -20,6 +22,7 @@ import {
 import {
 	NullHarness,
 	type AgentTreeReap,
+	type CutOffTurn,
 	type Harness,
 	type HarnessRecord,
 } from './harness.js';
@@ -38,7 +41,11 @@ import {
 	type IsolatedTree,
 } from './isolation.js';
 import {ensureMirror, encodeRepoKey, mirrorPath} from './repo-mirror.js';
-import {jobWorktreePath, updateJobRecord} from './workspace.js';
+import {
+	jobWorktreePath,
+	RetainedWorktreeUnsavedWorkError,
+	updateJobRecord,
+} from './workspace.js';
 import {reapJob} from './gc.js';
 import {isGitHubArbiterUrl, GitHubProvider} from './github.js';
 import type {ReviewProvider} from './integrator.js';
@@ -66,12 +73,12 @@ import {
 	isWorkBranchDiffEmpty,
 	emptyDiffStopReason,
 	emptyDiffDisposeEnvelope,
+	resolveCutOffTurnFailure,
 	type AgentStopClass,
 } from './agent-stop.js';
-import {
-	surfaceStuckToNeedsAttention,
-	routeToNeedsAttention,
-} from './needs-attention.js';
+import {surfaceStuckToNeedsAttention} from './needs-attention.js';
+import {refWrite} from './ref-write.js';
+import {annotatePhaseBoundary} from './phase-recorder.js';
 import {resolveItemPathByIdentity} from './item-path.js';
 import {
 	classifyFailureCause,
@@ -159,7 +166,7 @@ function deadlineAutoContinueReason(params: {
 		`tick continues from the branch tip.`
 	);
 }
-function deadlineSurfaceReason(params: {
+export function deadlineSurfaceReason(params: {
 	slug: string;
 	kind: 'no-progress' | 'ceiling' | 'unreaped';
 	count?: number;
@@ -278,8 +285,10 @@ async function saveDeadlineCheckpoint(params: {
 	// Push the branch to the arbiter (best-effort). Reuse routeToNeedsAttention's
 	// save-half exact contract: it commits any residue + pushes the branch with
 	// bounded backoff. We already committed above; the wip commit inside
-	// routeToNeedsAttention will be a no-op (clean tree) and the push runs.
-	return routeToNeedsAttention({
+	// routeToNeedsAttention will be a no-op (clean tree) and the push runs. It
+	// is reached through the ref-write seam (`refWrite.saveWorkBranch`) so the
+	// branch push is visible to the CI phase mode.
+	return refWrite.saveWorkBranch({
 		cwd,
 		slug,
 		reason: `deadline-checkpoint save for '${slug}' (see branch)`,
@@ -290,6 +299,26 @@ async function saveDeadlineCheckpoint(params: {
 	});
 }
 
+/**
+ * What a build's FIRST WRITE is, when the write seam call alone does not say
+ * (CI phase mode, task `ci-split-build-path-non-integrate-intents`): an agent
+ * failure, a deliberate STOP and a red gate all bounce through
+ * `ledgerWrite.applyNeedsAttentionTransition`, and the deadline checkpoint's
+ * first write is a plain branch save. The pipeline names it with
+ * `annotatePhaseBoundary` right before the write; the build phase driver
+ * (`ci-phase-build.ts`) maps it to a handoff intent. Without a phase it is
+ * never read.
+ */
+export type BuildBoundary =
+	| {kind: 'agent-failed'; failureDetail: string}
+	| {kind: 'stop'; reason: string; stopKind: 'sentinel' | 'empty-diff'}
+	| {
+			kind: 'deadline-checkpoint';
+			/** Whether the checkpointed agent's process tree was verified gone. */
+			predecessorGone: boolean;
+			reapDetail?: string;
+	  };
+
 /** The terminal status of one in-place `do` run. */
 export type DoOutcome =
 	| 'completed' // claimed/onboarded → agent → gate green → integrated → exited
@@ -362,6 +391,14 @@ export type DoDorfl = (input: {
 	 * Absent ⇒ nothing was left running (the pre-existing behaviour).
 	 */
 	reap?: AgentTreeReap;
+	/**
+	 * **The agent's final model turn was CUT OFF** (`length` / `error` stop; the
+	 * harness seam's `LaunchResult.cutOffTurn`, task
+	 * `a-truncated-agent-turn-routes-as-agent-failed`). An empty diff with this
+	 * set routes `agent-failed`, never the empty-diff STOP. Lets an injected agent
+	 * drive that routing; production reads it off the pi session log.
+	 */
+	cutOffTurn?: CutOffTurn;
 };
 
 export interface DoOptions {
@@ -602,6 +639,13 @@ export interface DoOptions {
 	env?: NodeJS.ProcessEnv;
 	/** Sink for human-readable progress notes. */
 	note?: (message: string) => void;
+	/**
+	 * The CI phase this run executes as (`--phase lock|agent|apply`, CI-only;
+	 * see `phase.ts`). `undefined` ⇒ today's single process. Threaded next to
+	 * `env` and `note` so the per-path phase splits can branch on it; the phase
+	 * guards read the process-wide active phase.
+	 */
+	phase?: Phase;
 	/**
 	 * Sink for a pre-formatted block printed VERBATIM (forwarded to `complete`'s
 	 * propose-mode next-step block). Defaults to `note`.
@@ -1146,17 +1190,25 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 	//         fresh-main `work/<slug>` switch, incl. the §14 continue/rebase path)
 	//         WITHOUT re-claiming — the split the seam mandates (claim → driver,
 	//         onboarding → strategy).
-	const claim = await performClaim({
-		slug,
-		cwd,
-		arbiter,
-		// `--allow-backlog`: widen the claimable predicate to ALSO accept a
-		// `tasks/backlog/`-resident body. Claim stays a pure lock (writes nothing to
-		// `main`, moves nothing); default off ⇒ pool-only, exactly as today.
-		allowBacklog: options.allowBacklog === true,
-		env,
-		note,
-	});
+	//    CI AGENT PHASE (task `ci-split-build-path`): the lock phase already took
+	//    the claim in the job that holds the write token, and the build phase
+	//    driver (`ci-phase-build.ts`) checked the lock ref still equals its
+	//    `lockSha` before calling here. The agent job cannot write, so it skips
+	//    the claim and onboards directly; everything after is unchanged.
+	const claim: ClaimCasResult =
+		options.phase === 'agent'
+			? {exitCode: 0, outcome: 'claimed', message: 'claimed by the lock phase'}
+			: await performClaim({
+					slug,
+					cwd,
+					arbiter,
+					// `--allow-backlog`: widen the claimable predicate to ALSO accept a
+					// `tasks/backlog/`-resident body. Claim stays a pure lock (writes nothing to
+					// `main`, moves nothing); default off ⇒ pool-only, exactly as today.
+					allowBacklog: options.allowBacklog === true,
+					env,
+					note,
+				});
 	if (claim.outcome === 'lost') {
 		return {exitCode: 2, outcome: 'lost', slug, message: claim.message};
 	}
@@ -1204,8 +1256,9 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 	//     did NOT onboard; the runner owns the bounce.
 	if (tree.continueRebaseConflict) {
 		const reason =
-			`continuing the kept ${tree.branch}: rebase onto the latest main ` +
-			'conflicted (aborted, never auto-resolved) — run `requeue --reconcile` ' +
+			`continuing the kept ${tree.branch}: ` +
+			`${continueRebaseSentence(tree.branch, tree.continueRebaseFailure)} — ` +
+			'run `requeue --reconcile` ' +
 			'to non-destructively re-sync the mirror and retry the rebase (keeps ' +
 			'the work). Last resort: `requeue --reset` DESTRUCTIVELY discards the ' +
 			'branch and starts fresh.';
@@ -1318,6 +1371,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			cwd: tree.dir,
 			continueContext,
 			promptGuidance: itemGuidance,
+			taskFolder: task.folder,
 		});
 	} catch (err) {
 		if (err instanceof PromptError) {
@@ -1340,6 +1394,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 		output?: string;
 		timedOut?: boolean;
 		reap?: AgentTreeReap;
+		cutOffTurn?: CutOffTurn;
 	};
 	try {
 		agent = await runDoAgent(options, tree.dir, prompt, slug);
@@ -1394,6 +1449,29 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 	//     deterministic empty-diff backstop. Either routes to needs-attention and
 	//     SKIPS the acceptance gate AND Gate-2 — a clean STOP is NOT "a build that
 	//     changed nothing".
+	//     A CUT-OFF final turn (`length`/`error`) with an empty diff is NOT a STOP:
+	//     it is a harness failure, routed `agent-failed` (WIP save, requeue-able)
+	//     BEFORE the empty-diff backstop can read it as "nothing to build" (task
+	//     `a-truncated-agent-turn-routes-as-agent-failed`).
+	const cutOffDetail = await resolveCutOffTurnFailure({
+		cutOffTurn: agent.cutOffTurn,
+		output: agent.output,
+		slug,
+		cwd: tree.dir,
+		arbiter: tree.arbiterRemote,
+		env,
+	});
+	if (cutOffDetail !== undefined) {
+		return await saveAgentFailure({
+			slug,
+			branch,
+			cwd: tree.dir,
+			arbiter: tree.arbiterRemote,
+			detail: cutOffDetail,
+			env,
+			note,
+		});
+	}
 	const stopReason = await resolveStopReason({
 		output: agent.output,
 		slug,
@@ -1726,16 +1804,27 @@ function routeReport(
  * `requeue` (continue) / `requeue --reconcile` (non-destructive retry) vs
  * `requeue --reset` (destructive last resort).
  */
-async function saveAgentFailure(params: {
+export async function saveAgentFailure(params: {
 	slug: string;
 	branch: string | undefined;
 	cwd: string;
 	arbiter: string;
 	detail: string;
+	/**
+	 * `false`: surface only, push no work branch (the CI apply phase when the
+	 * handoff carried no bundle). Default: push, exactly as before.
+	 */
+	pushBranch?: boolean;
 	env: NodeJS.ProcessEnv | undefined;
 	note: (message: string) => void;
 }): Promise<DoResult> {
 	const {slug, cwd, arbiter, detail, env, note} = params;
+	// CI agent phase: this bounce is the build's first write; name it so the
+	// phase driver hands it over as `agent-failed` (a no-op without a phase).
+	annotatePhaseBoundary({
+		kind: 'agent-failed',
+		failureDetail: detail,
+	} satisfies BuildBoundary);
 	// The work branch is the namespaced build branch (`work/task-<slug>`; the
 	// onboarding switched the checkout to it before the agent ran); derive it from
 	// the slug so the push target is always defined even when the caller's `branch`
@@ -1761,6 +1850,7 @@ async function saveAgentFailure(params: {
 		slug,
 		reason,
 		arbiter,
+		...(params.pushBranch === false ? {pushBranch: false} : {}),
 		env,
 		note,
 	});
@@ -1863,18 +1953,27 @@ async function resolveStopReason(params: {
  * rebase conflict). The agent's STOP reason is recorded VERBATIM as the
  * needs-attention reason. The acceptance gate AND Gate-2 are NEVER reached.
  */
-async function saveAgentStop(params: {
+export async function saveAgentStop(params: {
 	slug: string;
 	branch: string | undefined;
 	cwd: string;
 	arbiter: string;
 	reason: string;
 	kind: 'sentinel' | 'empty-diff';
+	/** As {@link saveAgentFailure}'s `pushBranch` (the sentinel branch only). */
+	pushBranch?: boolean;
 	env: NodeJS.ProcessEnv | undefined;
 	note: (message: string) => void;
 }): Promise<DoResult> {
 	const {slug, cwd, arbiter, reason, kind, env, note} = params;
 	const branch = params.branch ?? workBranchRef('task', slug);
+	// CI agent phase: name this first write so the phase driver hands it over as
+	// `stop` (a no-op without a phase).
+	annotatePhaseBoundary({
+		kind: 'stop',
+		reason,
+		stopKind: kind,
+	} satisfies BuildBoundary);
 
 	// EMPTY-DIFF branch (spec resolved decision #2, task
 	// `empty-diff-bounce-surfaces-dispose-defaulted-question`): surface a sidecar
@@ -1934,6 +2033,7 @@ async function saveAgentStop(params: {
 		slug,
 		reason,
 		arbiter,
+		...(params.pushBranch === false ? {pushBranch: false} : {}),
 		env,
 		note,
 	});
@@ -1997,6 +2097,8 @@ async function runDoAgent(
 	 * (observation `deadline-reap-lets-node-exit-0-before-the-checkpoint-runs`).
 	 */
 	record?: HarnessRecord;
+	/** The harness's cut-off-final-turn signal (`LaunchResult.cutOffTurn`). */
+	cutOffTurn?: CutOffTurn;
 }> {
 	if (options.dorfl) {
 		return options.dorfl({cwd, prompt, slug, env: options.env});
@@ -2047,6 +2149,7 @@ async function launchAgentUnderWriterLock(params: {
 	timedOut?: boolean;
 	reap?: AgentTreeReap;
 	record?: HarnessRecord;
+	cutOffTurn?: CutOffTurn;
 }> {
 	const {options, cwd, prompt, slug, harness} = params;
 	// Convert the dorfl-internal deadline (minutes) into a wall-clock epoch-ms so
@@ -2091,6 +2194,9 @@ async function launchAgentUnderWriterLock(params: {
 		// Threaded to {@link routeDeadlineCheckpoint}, which refuses to release the
 		// item lock without it.
 		reap: launched.reap,
+		// How the final model turn ended: a `length`/`error` cut-off turns an
+		// empty diff into an agent failure (see `resolveCutOffTurnFailure`).
+		cutOffTurn: launched.cutOffTurn,
 	};
 }
 
@@ -2102,7 +2208,7 @@ async function launchAgentUnderWriterLock(params: {
  * Shared by {@link performDo} and {@link runRemotePipeline} so the in-place
  * and remote forms route a deadline stop identically.
  */
-async function routeDeadlineCheckpoint(params: {
+export async function routeDeadlineCheckpoint(params: {
 	slug: string;
 	branch: string;
 	cwd: string;
@@ -2141,6 +2247,13 @@ async function routeDeadlineCheckpoint(params: {
 	if (reap !== undefined && reap.escalatedToSigkill && reap.reaped) {
 		note(`Deadline checkpoint for '${slug}': ${reap.detail}`);
 	}
+	// CI agent phase: the save below is the first write; name it so the phase
+	// driver hands it over as `deadline-checkpoint` (a no-op without a phase).
+	annotatePhaseBoundary({
+		kind: 'deadline-checkpoint',
+		predecessorGone,
+		...(reap?.detail === undefined ? {} : {reapDetail: reap.detail}),
+	} satisfies BuildBoundary);
 
 	// 1. ALWAYS save the WIP first: commit any residue + push the work branch.
 	const savedReason = `deadline checkpoint save for '${slug}'`;
@@ -2625,7 +2738,12 @@ export async function performDoRemote(
 				// build's fetch. Best-effort reap the deterministic worktree path for this
 				// slug (it is reaped ONLY if its branch is reachable on the arbiter —
 				// never lose work), then re-throw so the failure is still reported.
-				reapPreparedWorktreeLeak(mirror.url, slug, workspacesDir, env, note);
+				// EXCEPT when `createJob` REFUSED over a retained worktree holding
+				// unsaved work: that tree is the work being protected, not a leak, and
+				// the reachable-only reap would discard its uncommitted changes.
+				if (!(err instanceof RetainedWorktreeUnsavedWorkError)) {
+					reapPreparedWorktreeLeak(mirror.url, slug, workspacesDir, env, note);
+				}
 				throw err;
 			}
 			result = await runRemotePipeline(options, tree, slug, note, env);
@@ -2772,8 +2890,9 @@ async function runRemotePipeline(
 	//     agent — the §10 path `run` uses.
 	if (tree.continueRebaseConflict) {
 		const reason =
-			`continuing the kept ${tree.branch}: rebase onto the latest main ` +
-			'conflicted (aborted, never auto-resolved) — run `requeue --reconcile` ' +
+			`continuing the kept ${tree.branch}: ` +
+			`${continueRebaseSentence(tree.branch, tree.continueRebaseFailure)} — ` +
+			'run `requeue --reconcile` ' +
 			'to non-destructively re-sync the mirror and retry the rebase (keeps ' +
 			'the work). Last resort: `requeue --reset` DESTRUCTIVELY discards the ' +
 			'branch and starts fresh.';
@@ -2932,6 +3051,7 @@ async function runRemotePipeline(
 			cwd,
 			continueContext,
 			promptGuidance: itemGuidance,
+			taskFolder: task.folder,
 		});
 	} catch (err) {
 		if (err instanceof PromptError) {
@@ -2955,6 +3075,7 @@ async function runRemotePipeline(
 		timedOut?: boolean;
 		reap?: AgentTreeReap;
 		record?: HarnessRecord;
+		cutOffTurn?: CutOffTurn;
 	};
 	try {
 		agent = await runDoAgent(options, cwd, prompt, slug);
@@ -3015,6 +3136,27 @@ async function runRemotePipeline(
 	//     sentinel STOP (verbatim reason) or an empty work-branch diff routes to
 	//     needs-attention (surfaced on the arbiter) and SKIPS the gate + Gate-2. The
 	//     diff base is the worktree's `origin` (arbiterRemote).
+	//     A cut-off final turn with an empty diff is an agent failure, not a STOP
+	//     (same guard as in-place `do`).
+	const cutOffDetail = await resolveCutOffTurnFailure({
+		cutOffTurn: agent.cutOffTurn,
+		output: agent.output,
+		slug,
+		cwd,
+		arbiter: arbiterRemote,
+		env,
+	});
+	if (cutOffDetail !== undefined) {
+		return await saveRemoteAgentFailure({
+			slug,
+			branch,
+			cwd,
+			arbiterRemote,
+			detail: cutOffDetail,
+			env,
+			note,
+		});
+	}
 	const stopReason = await resolveStopReason({
 		output: agent.output,
 		slug,