dorfl 0.14.2 → 0.15.0

package/src/apply-merge-action.ts

@@ -1,19 +1,28 @@
-import {existsSync, readFileSync} from 'node:fs';
+import {existsSync, readFileSync, statSync} from 'node:fs';
 import {join} from 'node:path';
 import {
-	isEntryAnswered,
 	parseSidecar,
 	resolveSidecarIdentity,
 	sidecarPathFor,
-	type SidecarEntry,
 	type SidecarModel,
 } from './sidecar.js';
 import {run as runProc} from './git.js';
-import {createJob, type Job} from './workspace.js';
+import {createJob, withCheckoutCommitIdentity, type Job} from './workspace.js';
+import {continueRebaseSentence} from './continue-branch.js';
+import {ensureMirrorMain, type EnsureMirrorResult} from './repo-mirror.js';
 import {
 	performIntegration,
+	type IntegrationCoreInput,
 	type IntegrationCoreResult,
 } from './integration-core.js';
+import {
+	changedFileBlobs,
+	lfsObjectPath,
+	localLfsObjectsDir,
+	scanLfsPointers,
+} from './ci-handoff-lfs.js';
+import {commitAbortedWork} from './needs-attention.js';
+import {createPhaseRecorder, runAgentPhase} from './phase-recorder.js';
 import type {VerifyConfig} from './verify.js';
 
 /**
@@ -58,9 +67,9 @@ import type {VerifyConfig} from './verify.js';
  * "HONOUR the prior approval + land on a green re-verify" path; opt-in
  * `strictMergeApproval` (resolved per-repo via the gate-family precedence chain
  * by the sibling task `strict-merge-approval-gate`, default OFF) RE-SURFACES
- * the merge-question instead of landing when the merge-base moved between the
- * surfacer's question and this apply. The RED-re-verify refusal is unchanged
- * in both modes.
+ * the merge-question instead of landing when `main`'s code moved since the
+ * question was asked (its recorded `askedAtMain`; see `approvedBaseMoved`).
+ * The RED-re-verify refusal is unchanged in both modes.
  *
  * House-style boundary: this module is the DETERMINISTIC DISPATCH LAYER. It
  * does NOT re-implement rebase / verify / integrate (it drives the EXISTING
@@ -72,48 +81,16 @@ import type {VerifyConfig} from './verify.js';
  * needs-attention, that `verify` ran on the rebased tip).
  */
 
-/** The three deterministic actions a merge-question answer encodes. */
-export type MergeActionVerb = 'merge' | 'hold' | 'drop';
-
-/** A detected, answer-driven merge-action keyed off ONE answered `kind: merge` entry. */
-export interface DetectedMergeAction {
-	/** The deterministic verb parsed from the entry's answer text. */
-	verb: MergeActionVerb;
-	/** The answered `kind: merge` entry the verb came from. */
-	entry: SidecarEntry;
-}
-
-/**
- * Parse the human's plain free-text answer into the deterministic
- * {@link MergeActionVerb}. The merge-question surfacer renders
- * `merge | hold | drop` in the entry's `default` as a human-readable hint, so
- * the human typically types one of those words verbatim. We accept any text
- * whose first whole word (case-insensitive) is one of `merge` / `hold` / `drop`
- * — this is the same machine-parseable choice shape the surfacer's applied
- * answer q1 documents ("a DETERMINISTIC CHOICE shape … the human picks and the
- * system parses unambiguously").
- *
- * Returns `undefined` on ANYTHING else (an empty answer, a typo, a long
- * narrative without one of the three words at the start) so the caller can
- * route the ambiguity HONESTLY — never default-to-merge on a malformed answer,
- * which would invent a land the human did not authorise.
- */
-export function parseMergeAnswer(text: string): MergeActionVerb | undefined {
-	const trimmed = text.trim().toLowerCase();
-	if (trimmed === '') return undefined;
-	// The first whole alphabetic word; trailing punctuation (a comma, em-dash,
-	// period) and any following commentary are tolerated. We deliberately do
-	// NOT consume hyphens / apostrophes — the three verbs are plain ASCII
-	// words, and over-tolerating typo-shapes would silently invent a verb the
-	// human did not pick.
-	const match = /^([a-z]+)/.exec(trimmed);
-	if (match === null) return undefined;
-	const word = match[1];
-	if (word === 'merge' || word === 'hold' || word === 'drop') {
-		return word;
-	}
-	return undefined;
-}
+export {
+	answeredMergeActionIn,
+	parseMergeAnswer,
+	type DetectedMergeAction,
+	type MergeActionVerb,
+} from './merge-answer.js';
+import {
+	answeredMergeActionIn,
+	type DetectedMergeAction,
+} from './merge-answer.js';
 
 /**
  * Detect the `kind: merge` action verb that should drive the next apply run.
@@ -151,21 +128,7 @@ export function detectAnsweredMergeAction(
 	} catch {
 		return undefined;
 	}
-	// (1) Unanswered `kind: merge` follow-up ⇒ re-paused; the apply must NOT fire.
-	for (const entry of model.entries) {
-		if (entry.kind === 'merge' && !isEntryAnswered(entry)) return undefined;
-	}
-	// (2) LATEST answered `kind: merge` entry — a fresh follow-up beats a stale one.
-	for (let i = model.entries.length - 1; i >= 0; i--) {
-		const entry = model.entries[i];
-		if (entry.kind !== 'merge') continue;
-		if (!isEntryAnswered(entry)) continue;
-		const verb = parseMergeAnswer(entry.answer);
-		if (verb !== undefined) {
-			return {verb, entry};
-		}
-	}
-	return undefined;
+	return answeredMergeActionIn(model);
 }
 
 /** Input the production merge-action handler consumes. */
@@ -197,8 +160,8 @@ export interface MergeActionInput {
 	 * `strictMergeApproval` (resolved per-repo by the sibling task
 	 * `strict-merge-approval-gate`; default OFF). OFF ⇒ honour the prior answer
 	 * + land on a green re-verify (the cheap default). ON ⇒ re-surface the
-	 * merge-question when the merge-base moved between the surfacer's question
-	 * and this apply (don't land; the apply rung folds this into a re-pause).
+	 * merge-question when `main`'s code moved since the question was asked
+	 * (don't land; the apply rung folds this into a re-pause).
 	 */
 	strictMergeApproval?: boolean;
 	/** Bounded recovery-rebase retry knob (mirrors the build path). */
@@ -228,9 +191,9 @@ export type MergeActionOutcome =
 	 */
 	| 'refused'
 	/**
-	 * `answer=merge` + `strictMergeApproval` ON + the merge-base moved between
-	 * the surfacer's question and this apply: the dispatcher RE-SURFACES the
-	 * merge-question (the apply rung appends a fresh follow-up + re-pauses).
+	 * `answer=merge` + `strictMergeApproval` ON + `main`'s code moved since the
+	 * question was asked: the dispatcher RE-SURFACES the merge-question (the
+	 * apply rung appends a fresh follow-up asked at the new `main` + re-pauses).
 	 */
 	| 'restale'
 	/** `answer=hold` ⇒ no land; the apply rung records the answer in body as usual. */
@@ -250,6 +213,12 @@ export interface MergeActionResult {
 	 * `already-integrated`, …), so callers can branch on it.
 	 */
 	integration?: IntegrationCoreResult;
+	/**
+	 * On `restale`: the arbiter `main` the approval was found stale against. The
+	 * apply rung records it as the re-surfaced question's `askedAtMain`, so a
+	 * re-answer while `main` stays put lands (no re-stale livelock).
+	 */
+	main?: string;
 }
 
 /**
@@ -282,50 +251,77 @@ function resolveArbiterUrl(input: MergeActionInput): string | undefined {
 	return url === '' ? undefined : url;
 }
 
+/** The verdict of {@link approvedBaseMoved}. */
+interface ApprovedBaseCheck {
+	/** `main`'s code moved since the answered question was asked ⇒ re-surface. */
+	stale: boolean;
+	/** The arbiter `main` the check compared against (when it was read). */
+	main?: string;
+}
+
 /**
- * The `strictMergeApproval` re-stale check (SPEC OQ6 opt-in): did `<arbiter>/
- * main` move past the merge-base of the work branch since the surfacer
- * authored the question? The git-alone analogue of GitHub's "dismiss stale
- * approvals when the base changes" — host-agnostic by reachability.
+ * The `strictMergeApproval` re-stale check (SPEC OQ6 opt-in; task
+ * `strict-merge-approval-restale-check-runs-before-the-continue-rebase`): did
+ * `main` move since the answered merge question was ASKED? The git-alone
+ * analogue of GitHub's "dismiss stale approvals when the base changes".
+ *
+ * ONE implementation for the laptop dispatcher ({@link performMergeAction}) and
+ * the CI agent half ({@link prepareMergeLand}), and both call it BEFORE
+ * {@link createJob}, whose continue rebase would otherwise make the kept branch
+ * a descendant of the current `main` and hide the move (the bug this replaced).
+ *
+ * The approved base is the `askedAtMain` the answered entry carries (stamped by
+ * the merge-question surfacer, and by the re-surface path with the `main` the
+ * follow-up is asked against, so a re-answer while `main` stays put lands and
+ * the CI split cannot livelock). It is compared with the arbiter's current
+ * `main`, freshly fetched into the hub mirror {@link createJob} then reuses.
  *
- * We fetch the latest `<arbiter>/main` from the JOB worktree's hub mirror (the
- * worktree's `origin`), compute `merge-base(<branch>, <origin/main>)`, and
- * compare against `<origin/main>` itself: if the merge-base IS `<origin/main>`,
- * the branch is a strict descendant — the merge-base did NOT move — and the
- * cheap default applies (HONOUR + land on green re-verify). If the merge-base
- * is NOT `<origin/main>`, `main` advanced past the branch's divergence point
- * since the branch was last rebased — the merge-base MOVED — and the strict
- * mode re-surfaces.
+ * "Moved" means the tree OUTSIDE `work/` differs: the question, its answer and
+ * every other ledger write are commits on `main` under `work/`, so a plain sha
+ * compare would re-stale every answer (the answer commit itself moves `main`).
  *
- * Returns `true` when the merge-base moved (⇒ re-surface), `false` otherwise.
- * On any plumbing failure returns `false` (do NOT spuriously re-surface — the
- * red re-verify is still the load-bearing safety; a transient git failure must
- * not block a clean answer-then-land).
+ * Never stale (the cheap default applies) when the entry carries no
+ * `askedAtMain` (a sidecar written before it existed) or on any plumbing
+ * failure: the red re-verify on the rebased tip stays the load-bearing safety,
+ * and a transient git failure must not block a clean answer-then-land.
  */
-function mergeBaseMoved(job: Job, env: NodeJS.ProcessEnv | undefined): boolean {
-	const fetch = runProc(
+function approvedBaseMoved(
+	url: string,
+	input: MergeActionInput,
+): ApprovedBaseCheck {
+	const asked = input.action.entry.askedAtMain;
+	if (asked === undefined) return {stale: false};
+	let mirror: EnsureMirrorResult;
+	try {
+		mirror = ensureMirrorMain({
+			url,
+			workspacesDir: input.workspacesDir,
+			env: input.env,
+		});
+	} catch {
+		return {stale: false};
+	}
+	const main = mirror.mainSha;
+	if (main === asked) return {stale: false, main};
+	const diff = runProc(
 		'git',
-		[
-			'fetch',
-			'--quiet',
-			job.arbiterRemote,
-			`+refs/heads/main:refs/remotes/${job.arbiterRemote}/main`,
-		],
-		job.dir,
-		{env},
+		['diff-tree', '--quiet', '-r', asked, main, '--', ':(exclude)work'],
+		mirror.path,
+		{env: input.env},
 	);
-	if (fetch.status !== 0) return false;
-	const mainRef = `${job.arbiterRemote}/main`;
-	const mainSha = runProc(
-		'git',
-		['rev-parse', '--verify', '--quiet', mainRef],
-		job.dir,
-		{env},
+	// 0: no change outside `work/`; 1: changed; anything else: plumbing failure.
+	return {stale: diff.status === 1, main};
+}
+
+/** The re-stale message both halves report. */
+function restaleMessage(input: MergeActionInput, main: string): string {
+	const asked = input.action.entry.askedAtMain ?? '(unknown)';
+	return (
+		`merge-question for ${input.item} answered MERGE, but ` +
+		`strictMergeApproval is ON and \`main\` moved since the question was ` +
+		`asked (asked at ${asked}, now ${main}): RE-SURFACING the ` +
+		`merge-question (no land; the human re-confirms against the new base).`
 	);
-	if (mainSha.status !== 0) return false;
-	const base = runProc('git', ['merge-base', 'HEAD', mainRef], job.dir, {env});
-	if (base.status !== 0) return false;
-	return base.stdout.trim() !== mainSha.stdout.trim();
 }
 
 /**
@@ -405,6 +401,22 @@ export async function performMergeAction(
 		};
 	}
 
+	// STRICT re-stale check (OQ6 opt-in), BEFORE the checkout's continue rebase
+	// (which would push the rebased branch, and hide the move): when ON and
+	// `main` moved since the question was asked, RE-SURFACE the merge-question
+	// (the apply rung folds this into a re-pause) instead of landing. Default
+	// OFF ⇒ skipped; the cheap "green re-verify is enough" path runs.
+	if (input.strictMergeApproval === true) {
+		const check = approvedBaseMoved(url, input);
+		if (check.stale && check.main !== undefined) {
+			return {
+				outcome: 'restale',
+				message: restaleMessage(input, check.main),
+				main: check.main,
+			};
+		}
+	}
+
 	// Check out the unmerged `work/<type>-<slug>` via the EXISTING per-job
 	// worktree seam — the SAME seam build/recovery callers use, NOT a bespoke
 	// worktree or clone. The job dir is the worktree `performIntegration` works
@@ -431,17 +443,17 @@ export async function performMergeAction(
 	}
 
 	try {
-		// CONTINUE-rebase-conflict: createJob's CONTINUE-rebase aborted on a
-		// genuine code conflict. The kept work stays on the branch (recoverable);
-		// we refuse the land and route via the standard refusal shape.
+		// CONTINUE-rebase-conflict: createJob's CONTINUE-rebase aborted (a
+		// genuine code conflict, or any other rebase failure, named as such). The
+		// kept work stays on the branch (recoverable); we refuse the land and
+		// route via the standard refusal shape.
 		if (job.continueRebaseConflict) {
-			return {
-				outcome: 'refused',
-				message:
-					`merge-question for ${input.item} answered MERGE — but rebasing ` +
-					`\`work/${input.slug}\` onto current main conflicted (the kept work is ` +
-					`intact on the branch; resolve and re-answer). NOT landing.`,
-			};
+			const message =
+				`merge-question for ${input.item} answered MERGE — but ` +
+				`${continueRebaseSentence(job.branch, job.continueRebaseFailure)} (the kept work is intact on the ` +
+				`branch; resolve and re-answer). NOT landing.`;
+			note(message);
+			return {outcome: 'refused', message};
 		}
 		if (job.continuePushFailure !== undefined) {
 			return {
@@ -453,50 +465,15 @@ export async function performMergeAction(
 			};
 		}
 
-		// STRICT re-stale check (OQ6 opt-in): when ON and the merge-base moved
-		// between the surfacer's question and this apply, RE-SURFACE the
-		// merge-question (the apply rung folds this into a re-pause) instead of
-		// landing. Default OFF ⇒ this block is skipped; the cheap "green
-		// re-verify is enough" path runs.
-		if (input.strictMergeApproval === true && mergeBaseMoved(job, input.env)) {
-			return {
-				outcome: 'restale',
-				message:
-					`merge-question for ${input.item} answered MERGE — but ` +
-					`strictMergeApproval is ON and the merge-base of \`work/${input.slug}\` ` +
-					`moved between answer and apply: RE-SURFACING the merge-question ` +
-					`(no land; the human re-confirms against the new base).`,
-			};
-		}
-
 		// LAND through the EXISTING `performIntegration`. The branch's tip
 		// already carries its done-move commit (surfacer enumerates `work/*`
 		// unreachable from main, so it is a previously-built strand), so we
 		// drive the committed-recovery tail — but with `freshWorktreeGate: true`
 		// so the REBASED TIP is re-verified BEFORE the integrate (the
 		// `committed-recovery-honours-fresh-worktree-gate` task's contract).
-		const integration = await performIntegration({
-			cwd: job.dir,
-			arbiter: job.arbiterRemote,
-			slug: input.slug,
-			source: 'tasks-ready',
-			recovering: false,
-			committedRecovery: true,
-			freshWorktreeGate: true,
-			prepare: input.prepare,
-			verify: input.verify,
-			mode: 'merge',
-			// surfaceArbiter is set so a RED rebased-tip gate (or a rebase
-			// conflict surfaced during the retry loop) routes to needs-attention
-			// observably on the arbiter (not local-only). The build path uses
-			// this shape; we mirror it here for the answered-merge land.
-			surfaceArbiter: job.arbiterRemote,
-			recoveryRebaseRetries: input.recoveryRebaseRetries,
-			recoveryRebaseJitterMs: input.recoveryRebaseJitterMs,
-			mergeRetries: input.mergeRetries,
-			env: input.env,
-			note,
-		});
+		const integration = await performIntegration(
+			mergeLandIntegrationInput(job, input, note),
+		);
 
 		if (integration.outcome === 'completed') {
 			return {
@@ -538,3 +515,273 @@ export async function performMergeAction(
 		}
 	}
 }
+
+/**
+ * The `performIntegration` input of the answered-merge land: the committed-
+ * recovery tail (the branch already carries its done-move) with the fresh-
+ * worktree gate on the rebased tip, in merge mode. Shared by the laptop
+ * dispatcher ({@link performMergeAction}) and the CI agent half
+ * ({@link prepareMergeLand}), so both run the SAME rebase and gate.
+ */
+function mergeLandIntegrationInput(
+	job: Job,
+	input: MergeActionInput,
+	note: (message: string) => void,
+): IntegrationCoreInput {
+	return {
+		cwd: job.dir,
+		arbiter: job.arbiterRemote,
+		slug: input.slug,
+		source: 'tasks-ready',
+		recovering: false,
+		committedRecovery: true,
+		freshWorktreeGate: true,
+		prepare: input.prepare,
+		verify: input.verify,
+		mode: 'merge',
+		// surfaceArbiter is set so a RED rebased-tip gate (or a rebase
+		// conflict surfaced during the retry loop) routes to needs-attention
+		// observably on the arbiter (not local-only). The build path uses
+		// this shape; we mirror it here for the answered-merge land.
+		surfaceArbiter: job.arbiterRemote,
+		recoveryRebaseRetries: input.recoveryRebaseRetries,
+		recoveryRebaseJitterMs: input.recoveryRebaseJitterMs,
+		mergeRetries: input.mergeRetries,
+		env: input.env,
+		note,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// The CI agent half (task `ci-split-answered-merge-action`)
+// ---------------------------------------------------------------------------
+
+/**
+ * What the CI agent job found for an answered `merge` (spec
+ * `ci-agent-job-without-write-token` §3, the `apply, kind: merge` row). Each
+ * maps to one handoff intent of the `apply` rung:
+ *
+ *  - `integrate`: the rebased tip passed the fresh-worktree gate; the apply job
+ *    pushes it leased and lands it (`integrate`, the rebased tip bundled);
+ *  - `restale`: `strictMergeApproval` is on and `main`'s code moved since the
+ *    question was asked (`merge-restale`; checked before any checkout);
+ *  - `needs-attention`: a red gate on the rebased tip (the rebased tip bundled)
+ *    or a rebase conflict (nothing bundled: the kept branch is untouched);
+ *  - `already-integrated`: the kept tip is already on `main`; nothing to land
+ *    (the lock job's `needsAgent: false` covers this case, so here it means the
+ *    branch landed between the lock job and this one).
+ */
+export type MergeLandPreparation =
+	| {kind: 'integrate'; repo: string; workBranch: string; tip: string}
+	| {kind: 'restale'; message: string; main: string}
+	| {
+			kind: 'needs-attention';
+			reason: string;
+			questions?: string[];
+			/** The rebased (red) tip to publish, when there is one. */
+			bundle?: {repo: string; workBranch: string};
+	  }
+	| {kind: 'already-integrated'; message: string};
+
+/** A {@link MergeLandPreparation} and the job worktree it lives in. */
+export interface PreparedMergeLand {
+	preparation: MergeLandPreparation;
+	/** Remove the job worktree; call it once the handoff (and its bundle) is written. */
+	dispose(): void;
+}
+
+/**
+ * The AGENT half of the answered-merge land, for the CI agent job, which holds a
+ * read-only token: the SAME optional `strictMergeApproval` re-stale check
+ * (before the checkout), checkout ({@link createJob}), rebase and
+ * fresh-worktree gate (`prepare` +
+ * `verify` run the branch's code) as {@link performMergeAction}, but nothing is
+ * written to the arbiter. The continue rebase stays local (decision 7,
+ * `localContinue`), and `performIntegration` runs under the phase recorder, so
+ * its first write (the land, or the needs-attention route of a red gate) halts
+ * it and names what the apply job performs. Only an answered `merge` gets here
+ * (`hold` / `drop` need no agent job).
+ *
+ * The caller writes the handoff from the returned preparation (a bundle reads
+ * the job worktree) and then calls `dispose`. Throws when the checkout itself
+ * fails (the agent job then fails, and the apply job surfaces the item).
+ */
+export async function prepareMergeLand(
+	answered: MergeActionInput,
+): Promise<PreparedMergeLand> {
+	// The job worktree lives in the hub mirror, which does not see the
+	// checkout's local git config, where the CI workflow sets the identity: the
+	// continue rebase (and the wip commit of a red gate) need it
+	// (`withCheckoutCommitIdentity`).
+	const input: MergeActionInput = {
+		...answered,
+		env: withCheckoutCommitIdentity(answered.cwd, answered.env),
+	};
+	const note = input.note ?? (() => {});
+	const identity = resolveSidecarIdentity(input.item);
+	if (identity.type !== 'task' || input.action.verb !== 'merge') {
+		throw new Error(
+			`prepareMergeLand: only an answered merge of a task is prepared ` +
+				`(got ${input.item}, answer ${input.action.verb})`,
+		);
+	}
+	const url = resolveArbiterUrl(input);
+	if (url === undefined) {
+		throw new Error(
+			`the arbiter URL of ${input.item} could not be resolved (\`git remote ` +
+				`get-url ${input.arbiter}\` failed in ${input.cwd})`,
+		);
+	}
+	// The re-stale check runs BEFORE the (local) continue rebase, exactly as on
+	// the laptop: the same `approvedBaseMoved`.
+	if (input.strictMergeApproval === true) {
+		const check = approvedBaseMoved(url, input);
+		if (check.stale && check.main !== undefined) {
+			const main = check.main;
+			return {
+				preparation: {
+					kind: 'restale',
+					message: restaleMessage(input, main),
+					main,
+				},
+				dispose: () => {},
+			};
+		}
+	}
+	const job = createJob({
+		url,
+		slug: input.slug,
+		type: 'task',
+		workspacesDir: input.workspacesDir,
+		localContinue: true,
+		env: input.env,
+	});
+	const dispose = (): void => {
+		try {
+			job.dispose();
+		} catch {
+			// Best-effort, as in performMergeAction: `gc` reaps a leftover.
+		}
+	};
+	const prepared = (preparation: MergeLandPreparation): PreparedMergeLand => ({
+		preparation,
+		dispose,
+	});
+	try {
+		if (job.continueRebaseConflict) {
+			const reason =
+				`${continueRebaseSentence(job.branch, job.continueRebaseFailure)}; the kept work is intact on the ` +
+				'branch. Resolve it, then answer the merge question again.';
+			note(reason);
+			return prepared({kind: 'needs-attention', reason});
+		}
+		const outcome = await runAgentPhase(
+			createPhaseRecorder({
+				record: [
+					'ledgerWrite.applyCompleteTransition',
+					'ledgerWrite.applyNeedsAttentionTransition',
+				],
+			}),
+			() => performIntegration(mergeLandIntegrationInput(job, input, note)),
+		);
+		if (outcome.halted) {
+			const call = `${outcome.intent.seam}.${outcome.intent.method}`;
+			if (call === 'ledgerWrite.applyCompleteTransition') {
+				fetchKeptLfsObjects(job, input.env, note);
+				const tip = runProc('git', ['rev-parse', 'HEAD'], job.dir, {
+					env: input.env,
+				}).stdout.trim();
+				return prepared({
+					kind: 'integrate',
+					repo: job.dir,
+					workBranch: job.branch,
+					tip,
+				});
+			}
+			// A red gate (or prepare) on the rebased tip: the route's local half
+			// (the wip commit) runs here, so the rebased tip travels in the bundle.
+			const routed = outcome.intent.input as {
+				reason: string;
+				questions?: string[];
+			};
+			commitAbortedWork({cwd: job.dir, slug: input.slug, env: input.env});
+			fetchKeptLfsObjects(job, input.env, note);
+			return prepared({
+				kind: 'needs-attention',
+				reason: routed.reason,
+				...(routed.questions === undefined
+					? {}
+					: {questions: routed.questions}),
+				bundle: {repo: job.dir, workBranch: job.branch},
+			});
+		}
+		const result = outcome.result;
+		if (result.outcome === 'already-integrated') {
+			return prepared({
+				kind: 'already-integrated',
+				message: result.reason ?? `work/task-${input.slug} is already on main`,
+			});
+		}
+		// A rebase conflict on every attempt (or an invariant violation): nothing
+		// was written and the kept branch is untouched on the arbiter.
+		return prepared({
+			kind: 'needs-attention',
+			reason:
+				result.reason ??
+				`the answered merge of ${input.item} ended as ${result.outcome}`,
+		});
+	} catch (err) {
+		dispose();
+		throw err;
+	}
+}
+
+/**
+ * Bring into the job's local LFS store the objects of every LFS pointer the
+ * kept commits (`HEAD ^<origin>/main`) add or change, so the handoff carries
+ * them (`writeLfsObjects` copies from that store) and the apply job pushes them
+ * before the branch (decision 6). The kept branch was built elsewhere, so its
+ * objects live on the arbiter's LFS store, not in this fresh job: a read-only
+ * `git lfs fetch` of those commits. Best-effort: an object still missing is
+ * reported by the handoff writer, and the apply job then rejects the handoff
+ * and surfaces the item.
+ */
+function fetchKeptLfsObjects(
+	job: Job,
+	env: NodeJS.ProcessEnv | undefined,
+	note: (message: string) => void,
+): void {
+	const commits = runProc(
+		'git',
+		['rev-list', 'HEAD', `^refs/remotes/${job.arbiterRemote}/main`],
+		job.dir,
+		{env},
+	)
+		.stdout.split('\n')
+		.filter((l) => l !== '');
+	if (commits.length === 0) return;
+	const {pointers} = scanLfsPointers({
+		cwd: job.dir,
+		blobs: changedFileBlobs(job.dir, commits, env),
+		env,
+	});
+	if (pointers.length === 0) return;
+	const store = localLfsObjectsDir(job.dir, env);
+	const missing = pointers.some((p) => {
+		const path = lfsObjectPath(store, p.oid);
+		return !existsSync(path) || !statSync(path).isFile();
+	});
+	if (!missing) return;
+	const fetched = runProc(
+		'git',
+		['lfs', 'fetch', job.arbiterRemote, ...commits],
+		job.dir,
+		{env},
+	);
+	if (fetched.status !== 0) {
+		note(
+			`git lfs fetch of the kept commits failed (${fetched.stderr.trim().slice(0, 300)}); ` +
+				'the handoff will lack their LFS objects',
+		);
+	}
+}

package/src/apply-stuck-action.ts

@@ -7,7 +7,7 @@ import {
 	type SidecarEntry,
 	type SidecarModel,
 } from './sidecar.js';
-import {deleteRemoteWorkBranchIfPresent} from './needs-attention.js';
+import {refWrite} from './ref-write.js';
 
 /**
  * The **answered STUCK-QUESTION ACTION DISPATCH** (spec
@@ -229,7 +229,7 @@ export async function performStuckAction(
 	}
 
 	// verb === 'reset'
-	const dropped = await deleteRemoteWorkBranchIfPresent({
+	const dropped = await refWrite.deleteRemoteWorkBranch({
 		cwd: input.cwd,
 		arbiter: input.arbiter,
 		slug: input.slug,