dorfl 0.11.0 → 0.11.2

package/src/do-config.ts

@@ -17,6 +17,8 @@ import type {
 export interface HarnessFlags {
 	agentCmd?: string;
 	model?: string;
+	/** `--build-model <id>` — the builder-specific model override (falls back to `--model`). */
+	buildModel?: string;
 	harness?: string;
 	piBin?: string;
 	/**
@@ -43,6 +45,9 @@ export function harnessFlagOverrides(flags: HarnessFlags): PartialConfig {
 	if (flags.model !== undefined) {
 		overrides.model = flags.model;
 	}
+	if (flags.buildModel !== undefined) {
+		overrides.buildModel = flags.buildModel;
+	}
 	if (flags.harness === 'null' || flags.harness === 'pi') {
 		overrides.harness = flags.harness;
 	}
@@ -69,6 +74,7 @@ export function doFlagOverrides(
 	flags: HarnessFlags &
 		ReviewFlags &
 		TaskerLoopFlags &
+		TriageModelFlags &
 		FreshWorktreeGateFlags &
 		SelectionOrderFlags &
 		ObservationTriageFlags &
@@ -115,6 +121,10 @@ export function doFlagOverrides(
 		// family from the gate's `--review*`, never sharing a flag/key/field name.
 		// The flag fields bridge onto the `taskerLoop*` config keys.
 		...taskerLoopFlagOverrides(flags),
+		// `--triage-model <id>` (the advance lifecycle gates' model — surface, apply,
+		// triage) rides the SAME chain. DISTINCT from `--review-model`/
+		// `--tasker-loop-model`; falls back to `model` when unset at all levels.
+		...triageModelFlagOverrides(flags),
 		// `--fresh-worktree-gate`/`--no-fresh-worktree-gate` (run the acceptance gate
 		// against the REBASED tip in a clean throwaway worktree, ON by default) rides
 		// the SAME chain — a DISTINCT family from `--review*`/`--tasker-loop*`.
@@ -232,6 +242,34 @@ export function taskerLoopFlagOverrides(flags: TaskerLoopFlags): PartialConfig {
 	return overrides;
 }
 
+/**
+ * The `--triage-model` flag — the model the advance lifecycle gates (surface,
+ * apply, triage) run on. A single string flag, distinct from the harness
+ * `--model`/`--build-model` family and from `--review-model`/
+ * `--tasker-loop-model`. Resolved through the SAME `flag > env > per-repo >
+ * global > default` chain; falls back to `model` when unset at all levels (via
+ * `applyModelFallbacks`).
+ */
+export interface TriageModelFlags {
+	/** `--triage-model <id>` — the advance lifecycle gates' model (routing intent). */
+	triageModel?: string;
+}
+
+/**
+ * Map the `--triage-model` flag into a {@link PartialConfig} override. Only
+ * contributes when the flag is actually present (absent flag => absent key), so
+ * the override layer never clobbers a lower-precedence source with `undefined`.
+ */
+export function triageModelFlagOverrides(
+	flags: TriageModelFlags,
+): PartialConfig {
+	const overrides: PartialConfig = {};
+	if (flags.triageModel !== undefined) {
+		overrides.triageModel = flags.triageModel;
+	}
+	return overrides;
+}
+
 /**
  * The fresh-worktree acceptance-gate CLI flag (`do`/`complete`/`run`):
  * `--fresh-worktree-gate` / `--no-fresh-worktree-gate`, the POSITIVE boolean

package/src/do.ts

@@ -17,7 +17,8 @@ import {
 	resolvePromptGuidanceForItem,
 	PromptError,
 } from './prompt.js';
-import {NullHarness, type Harness} from './harness.js';
+import {NullHarness, type AgentTreeReap, type Harness} from './harness.js';
+import {acquireWorktreeWriterLock} from './worktree-writer-lock.js';
 import {PiHarness} from './pi-harness.js';
 import {launchWithOptionalWatch} from './agent-launch.js';
 import {ledgerRead, type LedgerReadStrategy} from './ledger-read.js';
@@ -155,10 +156,27 @@ function deadlineAutoContinueReason(params: {
 }
 function deadlineSurfaceReason(params: {
 	slug: string;
-	kind: 'no-progress' | 'ceiling';
+	kind: 'no-progress' | 'ceiling' | 'unreaped';
 	count?: number;
 	max?: number;
+	/** The harness's loud reap detail (the `unreaped` kind only). */
+	detail?: string;
 }): string {
+	if (params.kind === 'unreaped') {
+		// The auto-continue path is BLOCKED, not merely skipped: releasing the lock
+		// would let a successor onboard into a worktree a live predecessor may still
+		// be writing to (observation
+		// `checkpoint-releases-lock-while-predecessor-agent-still-writes`). The work
+		// is saved and pushed; only the hand-off is withheld.
+		return (
+			`deadline checkpoint (agent NOT verifiably stopped): '${params.slug}' hit ` +
+			'the dorfl-internal deadline and its WIP was saved + pushed, but the agent ' +
+			'process tree could not be confirmed dead, so the lock was NOT released and ' +
+			'no successor was dispatched — a second agent in the same working tree can ' +
+			'clobber or silently absorb the first one\u2019s edits. ' +
+			`${params.detail ?? ''}`.trim()
+		);
+	}
 	if (params.kind === 'no-progress') {
 		return (
 			`deadline checkpoint (no progress / ceiling): '${params.slug}' hit ` +
@@ -329,6 +347,16 @@ export type DoDorfl = (input: {
 	 * injected path — the real deadline race lives in `PiHarness.launchAsync`.
 	 */
 	timedOut?: boolean;
+	/**
+	 * **The simulated process-tree REAP verdict** for a {@link timedOut} stop
+	 * (observation `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+	 * Test-only signal, the sibling of `timedOut`, so an injected agent can drive
+	 * the "predecessor could not be verified dead" routing — where the checkpoint
+	 * must NOT release the item lock, because the next tick would then onboard a
+	 * successor into a working tree the predecessor may still be writing to.
+	 * Absent ⇒ nothing was left running (the pre-existing behaviour).
+	 */
+	reap?: AgentTreeReap;
 };
 
 export interface DoOptions {
@@ -549,7 +577,9 @@ export interface DoOptions {
 	watch?: boolean;
 	/** The configured agent command the harness shells out to (null adapter). */
 	agentCmd?: string;
-	/** The model routing intent forwarded to the harness (ADR §13). */
+	/** The model routing intent forwarded to the harness (ADR §13). Sourced
+	 * from `config.buildModel` (which inherits the general `config.model` when
+	 * unset via `applyModelFallbacks`). */
 	model?: string;
 	/**
 	 * The HOST-ONLY root folder under which this run's pi session FILE is generated
@@ -1304,6 +1334,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 		detail?: string;
 		output?: string;
 		timedOut?: boolean;
+		reap?: AgentTreeReap;
 	};
 	try {
 		agent = await runDoAgent(options, tree.dir, prompt, slug);
@@ -1332,6 +1363,7 @@ export async function performDo(options: DoOptions): Promise<DoResult> {
 			cwd: tree.dir,
 			arbiter: tree.arbiterRemote,
 			maxAutoCheckpoints: options.maxAutoCheckpoints ?? 5,
+			reap: agent.reap,
 			env,
 			note,
 		});
@@ -1950,11 +1982,58 @@ async function runDoAgent(
 	detail?: string;
 	output?: string;
 	timedOut?: boolean;
+	reap?: AgentTreeReap;
 }> {
 	if (options.dorfl) {
 		return options.dorfl({cwd, prompt, slug, env: options.env});
 	}
 	const harness = options.harness ?? new NullHarness();
+
+	// WORKING-TREE SENTINEL (observation
+	// `checkpoint-releases-lock-while-predecessor-agent-still-writes`): the item
+	// lock guards the ITEM; this guards the TREE. A deadline checkpoint releases the
+	// item lock so the next tick can continue the task in the SAME worktree, so the
+	// item lock alone cannot keep a successor out while a predecessor is still
+	// alive. Refuse to launch a second agent into a tree that already has a LIVE
+	// writer, independently of the reap. A dead holder's sentinel is stale and taken
+	// over, so a crashed runner never poisons the worktree.
+	const writer = acquireWorktreeWriterLock({dir: cwd, slug, env: options.env});
+	if (!writer.acquired) {
+		return {ok: false, detail: writer.reason};
+	}
+	try {
+		return await launchAgentUnderWriterLock({
+			options,
+			cwd,
+			prompt,
+			slug,
+			harness,
+		});
+	} finally {
+		writer.release();
+	}
+}
+
+/**
+ * The actual harness launch, run while this process holds the worktree writer
+ * sentinel (see {@link runDoAgent}). Split out purely so the sentinel's
+ * acquire/release brackets the launch in a `try/finally` without indenting the
+ * whole body.
+ */
+async function launchAgentUnderWriterLock(params: {
+	options: DoAgentLaunchOptions;
+	cwd: string;
+	prompt: string;
+	slug: string;
+	harness: Harness;
+}): Promise<{
+	ok: boolean;
+	detail?: string;
+	output?: string;
+	timedOut?: boolean;
+	reap?: AgentTreeReap;
+}> {
+	const {options, cwd, prompt, slug, harness} = params;
 	// Convert the dorfl-internal deadline (minutes) into a wall-clock epoch-ms so
 	// the harness (`launchAsync`) can race the child against it (spec
 	// `graceful-pre-timeout-wip-checkpoint`). Absent ⇒ no deadline; a run that
@@ -1989,6 +2068,10 @@ async function runDoAgent(
 		detail: launched.detail,
 		output: launched.output,
 		timedOut: launched.timedOut,
+		// The harness's PROOF that a deadline-stopped agent's process tree is gone.
+		// Threaded to {@link routeDeadlineCheckpoint}, which refuses to release the
+		// item lock without it.
+		reap: launched.reap,
 	};
 }
 
@@ -2006,10 +2089,39 @@ async function routeDeadlineCheckpoint(params: {
 	cwd: string;
 	arbiter: string;
 	maxAutoCheckpoints: number;
+	/**
+	 * The harness's VERIFIED reap of the checkpointed agent's process tree. The
+	 * auto-continue branch releases the lock and lets the next tick dispatch a
+	 * SUCCESSOR into this same worktree, so it may only run once the predecessor
+	 * is proven gone (observation
+	 * `checkpoint-releases-lock-while-predecessor-agent-still-writes`). Absent ⮕
+	 * the harness spawned no killable group (test doubles, the null adapter), which
+	 * is treated as "nothing was left running".
+	 */
+	reap?: AgentTreeReap;
 	env: NodeJS.ProcessEnv | undefined;
 	note: (message: string) => void;
 }): Promise<DoResult> {
-	const {slug, branch, cwd, arbiter, maxAutoCheckpoints, env, note} = params;
+	const {slug, branch, cwd, arbiter, maxAutoCheckpoints, reap, env, note} =
+		params;
+
+	// 0. THE PREDECESSOR MUST BE DEAD BEFORE THE LOCK CAN MOVE.
+	//
+	// The item lock guards the ITEM; nothing guards the WORKING TREE. So if we
+	// released the lock while the checkpointed agent's tree were still alive, the
+	// next tick would onboard a successor into the very worktree the predecessor is
+	// still writing to — one lock, one working tree, two live writers. That was
+	// observed in the field: a predecessor kept writing for four minutes into its
+	// successor's run, and its last write landed on a file the successor had already
+	// read as clean in its opening `git status`.
+	//
+	// A reap we could not VERIFY is therefore a hard stop for the auto-continue
+	// path. We still SAVE the work below (never lose work) and still surface the
+	// item, but we do not hand the tree to anybody else.
+	const predecessorGone = reap === undefined || reap.reaped;
+	if (reap !== undefined && reap.escalatedToSigkill && reap.reaped) {
+		note(`Deadline checkpoint for '${slug}': ${reap.detail}`);
+	}
 
 	// 1. ALWAYS save the WIP first: commit any residue + push the work branch.
 	const savedReason = `deadline checkpoint save for '${slug}'`;
@@ -2038,7 +2150,11 @@ async function routeDeadlineCheckpoint(params: {
 		env,
 	});
 
-	if (madeProgressThisSession && checkpointCount <= maxAutoCheckpoints) {
+	if (
+		predecessorGone &&
+		madeProgressThisSession &&
+		checkpointCount <= maxAutoCheckpoints
+	) {
 		// AUTO-CONTINUE: release the lock via the SAME default keep+continue path
 		// `requeue` uses (no --reset, no --reconcile, no sidecar). The branch is
 		// KEPT on the arbiter so the next claim continues from its tip.
@@ -2055,10 +2171,27 @@ async function routeDeadlineCheckpoint(params: {
 			note,
 		});
 		if (returned.moved) {
+			// Derive this line from the SINGLE state `returnToBacklog` resolved, never
+			// from an independent assumption. It used to assert "the next tick continues
+			// from <branch>" unconditionally, which contradicted the requeue's own
+			// "'<slug>' has no work branch on <arbiter> — nothing to continue from" line
+			// emitted two lines earlier. Both cannot be true, and acting on the wrong one
+			// re-drives the task from scratch and discards the saved work (observation
+			// `checkpoint-path-reports-its-own-write-as-absent`). One resolved state, one
+			// story: mutually contradictory lines are worse than emitting nothing.
+			const continueFrom = returned.continueBranch;
+			const continuation =
+				continueFrom === undefined || continueFrom.aheadOfMain
+					? `lock released so the next tick continues from ${continueFrom?.branch ?? branch}`
+					: continueFrom.trustworthy
+						? 'lock released; the arbiter has no work to continue from, so the next ' +
+							'tick starts this item fresh'
+						: `lock released; the arbiter could not be read to confirm ${continueFrom.branch}, ` +
+							'so do NOT assume the work is gone — check the branch before re-driving';
 			const message =
 				`Auto-continued '${slug}' at the dorfl-internal deadline (checkpoint ` +
 				`${checkpointCount}/${maxAutoCheckpoints}): WIP saved + branch pushed, ` +
-				`lock released so the next tick continues from ${branch}. ${reason}`;
+				`${continuation}. ${reason}`;
 			note(message);
 			return {
 				exitCode: 0,
@@ -2078,14 +2211,16 @@ async function routeDeadlineCheckpoint(params: {
 	// SURFACE: mark the lock stuck via the whole applyNeedsAttentionTransition
 	// (save + push + stuck). The WIP was already saved above; a second save is
 	// idempotent (empty commit is skipped inside routeToNeedsAttention).
-	const surfaceReason = madeProgressThisSession
-		? deadlineSurfaceReason({
-				slug,
-				kind: 'ceiling',
-				count: checkpointCount,
-				max: maxAutoCheckpoints,
-			})
-		: deadlineSurfaceReason({slug, kind: 'no-progress'});
+	const surfaceReason = !predecessorGone
+		? deadlineSurfaceReason({slug, kind: 'unreaped', detail: reap?.detail})
+		: madeProgressThisSession
+			? deadlineSurfaceReason({
+					slug,
+					kind: 'ceiling',
+					count: checkpointCount,
+					max: maxAutoCheckpoints,
+				})
+			: deadlineSurfaceReason({slug, kind: 'no-progress'});
 	const routed = await ledgerWrite.applyNeedsAttentionTransition({
 		cwd,
 		slug,
@@ -2095,12 +2230,14 @@ async function routeDeadlineCheckpoint(params: {
 		note,
 	});
 	const report = routed.moved ? routeReport(routed, branch) : undefined;
+	const why = !predecessorGone
+		? 'the checkpointed agent could not be verified dead'
+		: madeProgressThisSession
+			? `ceiling ${checkpointCount}/${maxAutoCheckpoints}`
+			: 'no progress this session';
 	const message = routed.moved
-		? `Surfaced '${slug}' at the deadline checkpoint (${
-				madeProgressThisSession
-					? `ceiling ${checkpointCount}/${maxAutoCheckpoints}`
-					: 'no progress this session'
-			}); ${report!.fragment}. ${surfaceReason}`
+		? `Surfaced '${slug}' at the deadline checkpoint (${why}); ` +
+			`${report!.fragment}. ${surfaceReason}`
 		: `Could not surface '${slug}' at the deadline checkpoint ` +
 			`(${routed.reasonNotMoved ?? 'unknown'}). ${surfaceReason}`;
 	note(message);
@@ -2744,6 +2881,7 @@ async function runRemotePipeline(
 		detail?: string;
 		output?: string;
 		timedOut?: boolean;
+		reap?: AgentTreeReap;
 	};
 	try {
 		agent = await runDoAgent(options, cwd, prompt, slug);
@@ -2768,6 +2906,7 @@ async function runRemotePipeline(
 			cwd,
 			arbiter: arbiterRemote,
 			maxAutoCheckpoints: options.maxAutoCheckpoints ?? 5,
+			reap: agent.reap,
 			env,
 			note,
 		});

package/src/env-config.ts

@@ -152,6 +152,9 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// A non-string / empty value is normalised at load (`validateDorflCmdConfig`).
 	dorflCmd: 'string',
 	model: 'string',
+	buildModel: 'string',
+	triageModel: 'string',
+	intakeModel: 'string',
 	harness: {enum: ['null', 'pi']},
 	piBin: 'string',
 	sessionsDir: 'string',

package/src/harness.ts

@@ -210,6 +210,36 @@ export interface LaunchResult {
 	 * part from its `--format json` stream — the SAME `output` field.
 	 */
 	output?: string;
+	/**
+	 * **The verified outcome of reaping the agent's process TREE** after a deadline
+	 * stop (observation
+	 * `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+	 *
+	 * Only present when {@link timedOut} is set — i.e. when the harness itself
+	 * signalled the agent and therefore owes the caller PROOF that it is gone
+	 * rather than merely signalled. `reaped: false` means a descendant may still be
+	 * writing to the worktree, so the caller MUST NOT release the item lock or let
+	 * a successor agent onboard there (see `do.ts`'s deadline routing).
+	 *
+	 * Absent on a normal exit (nothing was signalled, so there is nothing to prove)
+	 * and on adapters that do not spawn a killable process group.
+	 */
+	reap?: AgentTreeReap;
+}
+
+/**
+ * The harness-reported result of reaping a stopped agent's process tree — the
+ * adapter-agnostic projection of `reap-agent-tree.ts`'s `ReapResult`.
+ */
+export interface AgentTreeReap {
+	/** True iff the tree is VERIFIED gone (observed, not merely signalled). */
+	reaped: boolean;
+	/** The process group that was reaped (the agent's group-leader pid). */
+	pgid?: number;
+	/** True iff SIGKILL was needed because the tree ignored SIGTERM. */
+	escalatedToSigkill?: boolean;
+	/** Human-readable account — the LOUD text when `reaped` is false. */
+	detail: string;
 }
 
 /**

package/src/ledger-write.ts

@@ -1,5 +1,6 @@
 import {randomUUID} from 'node:crypto';
 import {runAsync, type RunResult} from './git.js';
+import {refreshArbiterRefs, resolveArbiterBranch} from './arbiter-refs.js';
 import {
 	Integrator,
 	type IntegrateResult,
@@ -560,17 +561,52 @@ export const currentLedgerWrite: LedgerWriteStrategy = {
 			// making" no-op, which is a LOSS. The nonce makes the two naturally
 			// distinguishable: `arbiterHead === nonced` iff WE won. So an up-to-date
 			// no-op can never satisfy this and is classified REJECTED, never published.
-			await gitHard(['fetch', '--quiet', arbiter], cwd, env);
-			const arbiterHead = (
-				await gitHard(['rev-parse', `${arbiter}/main`], cwd, env)
-			).stdout.trim();
-			if (arbiterHead === nonced) {
+			//
+			// The read MUST be ARBITER-AUTHORITATIVE, and used to not be: it was a
+			// plain `git fetch <arbiter>` + `rev-parse <arbiter>/main`. In the
+			// bare-hub-mirror job worktree `--isolated` runs in, that fetch does not
+			// populate `refs/remotes/<arbiter>/main` at all (the mirror refspec maps
+			// `+refs/heads/*:refs/heads/*`) and can even fail outright, so the verify
+			// compared our fresh sha against a view PREDATING our own push and declared
+			// a landed transition "not our commit ⇒ rejected" — five times per bounce,
+			// landing five identical commits and then reporting "did not land"
+			// (observation `checkpoint-path-reports-its-own-write-as-absent`). We now
+			// prune-fetch with the EXPLICIT refspec (so the objects/refs are local for
+			// any follow-up comparison) and then ask the ARBITER for the sha via
+			// `ls-remote`, which no local refspec accident can defeat.
+			await refreshArbiterRefs({cwd, arbiter, branches: ['main'], env});
+			const resolved = await resolveArbiterBranch({
+				cwd,
+				arbiter,
+				branch: 'main',
+				env,
+			});
+			if (resolved.sha === nonced) {
 				return {
 					kind: 'published',
 					message: 'transition published',
 					publishedHead: nonced,
 				};
 			}
+			if (!resolved.trustworthy) {
+				// The arbiter could not be reached, so we CANNOT tell a lost CAS from an
+				// unreadable view — and our push exited 0, which is evidence FOR landing.
+				// Reporting "rejected" here is precisely the defect (a successful write
+				// described as absent), and it also drives a retry that would duplicate
+				// the commit. Trust the green push: report published, and say why.
+				emit(
+					`push to ${arbiter}/main succeeded but the arbiter could not be re-read ` +
+						`to confirm it (${resolved.unreachableDetail ?? 'arbiter unreachable'}) ` +
+						'— trusting the successful push rather than reporting a landed write as ' +
+						'absent.',
+				);
+				return {
+					kind: 'published',
+					message:
+						'transition published (push succeeded; arbiter re-read unavailable)',
+					publishedHead: nonced,
+				};
+			}
 			emit(
 				`push reported up-to-date / no change of our making — ${arbiter}/main is not our commit — treating as rejected.`,
 			);