dorfl 0.14.2 → 0.15.0

package/src/crashed-run-save.ts

@@ -0,0 +1,162 @@
+import {existsSync} from 'node:fs';
+import {run} from './git.js';
+import {evaluateDeletionSafety, RETAIN_REASON_TEXT} from './gc.js';
+import {resolveHarness} from './harness.js';
+// Import for the registration side-effect: ensures the `pi` adapter is in the
+// harness registry so a pi job's liveness is answered by the pi adapter (the
+// same reason `status.ts` imports it).
+import './pi-harness.js';
+import {jobWorktreePath, readJobRecord} from './workspace.js';
+import {workBranchRef} from './slug-namespace.js';
+import {refWrite} from './ref-write.js';
+import type {BackoffOptions, Sleep} from './retry-backoff.js';
+
+/**
+ * **Save a CRASHED run's local-only work before its lock is released** (task
+ * `a-crashed-runs-local-work-is-saved-before-its-lock-is-released`).
+ *
+ * A `do --isolated` run that is killed mid-agent (a host restart, an OOM kill)
+ * leaves its per-item lock `active` and its job worktree RETAINED under
+ * `<workspacesDir>/work/<work-id>/`. The runner's own abort handler may already
+ * have made the usual wip commit there, but the process died before pushing it,
+ * so the work exists ONLY in that worktree. A plain `requeue` then released the
+ * lock without saving it, and the next claim (or `gc --force`) cut the worktree
+ * away: the work was lost.
+ *
+ * This is the SAVE step `requeue` runs before it releases a held lock. It
+ * locates the slug's retained job worktree by the SAME arbiter-URL + slug naming
+ * `do --isolated` created it with (`jobWorktreePath`, as `complete --isolated`
+ * locates it), and:
+ *
+ *   - no retained worktree (or one that belongs to a same-slug SPEC run)
+ *     ⇒ `no-worktree`: nothing to do, requeue behaves as before;
+ *   - the run is still ALIVE per its harness (PID/session, never mtime, ADR §5)
+ *     ⇒ `alive`: we never write into a live agent's tree;
+ *   - the gc deletion-safety predicate already holds (clean tree AND tip on the
+ *     arbiter) ⇒ `nothing-unsaved`: requeue behaves as before;
+ *   - otherwise commit any uncommitted residue as the usual wip commit and push
+ *     the work branch through `refWrite.saveWorkBranch` (the SAME save half
+ *     `routeToNeedsAttention` and the deadline checkpoint use: plain push, never
+ *     `--force`, bounded backoff), then RE-CHECK the predicate: holds ⇒ `saved`,
+ *     else `not-saved` with why (the caller keeps the lock and the worktree).
+ *
+ * A worktree whose HEAD is not on its work branch (e.g. a run killed mid-rebase,
+ * detached HEAD) is `not-saved` WITHOUT touching it: committing onto a detached
+ * HEAD would strand the commit, so the human resolves it by hand.
+ */
+export type CrashedRunSaveOutcome =
+	| {kind: 'no-worktree'}
+	| {kind: 'alive'; dir: string; branch: string}
+	| {kind: 'nothing-unsaved'; dir: string; branch: string}
+	| {kind: 'saved'; dir: string; branch: string; committedResidue: boolean}
+	| {kind: 'not-saved'; dir: string; branch: string; detail: string};
+
+export interface SaveCrashedRunWorkOptions {
+	/** The operator's checkout; its `arbiter` remote names the repo. */
+	cwd: string;
+	/** The arbiter remote NAME in {@link cwd}. */
+	arbiter: string;
+	/** The task slug (the branch is `work/task-<slug>`). */
+	slug: string;
+	/** The execution working area (config `workspacesDir`). */
+	workspacesDir: string;
+	env?: NodeJS.ProcessEnv;
+	note?: (message: string) => void;
+	/** Backoff bounds for the save push (tests pass a no-wait `sleep`). */
+	backoff?: BackoffOptions;
+	sleep?: Sleep;
+}
+
+/** The arbiter remote name valid INSIDE a job worktree (cut from the bare hub mirror). */
+const WORKTREE_ARBITER_REMOTE = 'origin';
+
+export async function saveCrashedRunWork(
+	options: SaveCrashedRunWorkOptions,
+): Promise<CrashedRunSaveOutcome> {
+	const note = options.note ?? (() => {});
+	const {cwd, arbiter, slug, workspacesDir, env} = options;
+
+	const url = run('git', ['remote', 'get-url', arbiter], cwd, {env});
+	if (url.status !== 0 || url.stdout.trim() === '') {
+		return {kind: 'no-worktree'};
+	}
+	const dir = jobWorktreePath(workspacesDir, url.stdout.trim(), slug);
+	if (!existsSync(dir)) {
+		return {kind: 'no-worktree'};
+	}
+	const branch = workBranchRef('task', slug);
+	const record = readJobRecord(dir);
+	if (record !== undefined && record.branch !== branch) {
+		// A same-slug SPEC (tasking) run shares the work-id; it is not this task's.
+		return {kind: 'no-worktree'};
+	}
+
+	if (
+		record !== undefined &&
+		record.state === 'running' &&
+		resolveHarness(record.harness).isAlive(record.harness)
+	) {
+		note(
+			`'${slug}': its run in ${dir} is still ALIVE (per its harness), so ` +
+				'requeue does not touch its worktree.',
+		);
+		return {kind: 'alive', dir, branch};
+	}
+
+	const before = evaluateDeletionSafety({dir, branch, env});
+	if (before.safe) {
+		return {kind: 'nothing-unsaved', dir, branch};
+	}
+
+	const head = run('git', ['symbolic-ref', '-q', '--short', 'HEAD'], dir, {
+		env,
+	});
+	if (head.status !== 0 || head.stdout.trim() !== branch) {
+		return {
+			kind: 'not-saved',
+			dir,
+			branch,
+			detail:
+				`its worktree is not on ${branch} (HEAD: ` +
+				`${head.status === 0 ? head.stdout.trim() : 'detached, e.g. killed mid-rebase'}), ` +
+				'so it cannot be saved automatically',
+		};
+	}
+
+	note(
+		`'${slug}': its crashed run left unsaved work in ${dir} ` +
+			`(${RETAIN_REASON_TEXT[before.reason ?? 'unmerged-commits']}); saving it ` +
+			`to ${branch} on the arbiter before releasing the lock.`,
+	);
+	const saved = await refWrite.saveWorkBranch({
+		cwd: dir,
+		slug,
+		reason: `save a crashed run's local work before requeue`,
+		arbiter: WORKTREE_ARBITER_REMOTE,
+		branch,
+		env,
+		// The save half's own notes speak of a bounce; this is a requeue, so we
+		// report from the outcome instead.
+		note: () => {},
+		...(options.backoff !== undefined ? {backoff: options.backoff} : {}),
+		...(options.sleep !== undefined ? {sleep: options.sleep} : {}),
+	});
+	const committedResidue = saved.moveCommit !== undefined;
+
+	const after = evaluateDeletionSafety({dir, branch, env});
+	if (after.safe) {
+		note(
+			`Saved the crashed run's work: pushed ${branch}` +
+				(committedResidue
+					? ' (with a wip commit of its uncommitted files)'
+					: '') +
+				'.',
+		);
+		return {kind: 'saved', dir, branch, committedResidue};
+	}
+	const detail =
+		saved.branchPush === 'failed'
+			? `the push of ${branch} failed (${saved.pushError ?? 'unknown error'})`
+			: `it is still ${RETAIN_REASON_TEXT[after.reason ?? 'unmerged-commits']}`;
+	return {kind: 'not-saved', dir, branch, detail};
+}

package/src/cwd-section.ts

@@ -6,6 +6,7 @@ import {listMirrors} from './registry.js';
 import {encodeRepoKey, mirrorPath} from './repo-mirror.js';
 import {
 	heldTaskSlugsStrict,
+	proposeKeptTaskSlugs,
 	heldSpecSlugsStrict,
 	listItemLockEntries,
 	classifyTerminalItemLocks,
@@ -421,12 +422,21 @@ export async function resolveCwdSection(
 	//    with the arbiter-read held set SUBTRACTED so in-flight (lock-held) items are
 	//    not reported eligible. Thread the per-machine override so the cwd section's
 	//    eligibility matches what `do`/`advance` autopick will actually select.
+	// The held tasks whose lock a finished propose build keeps (the `propose-pr`
+	// marker): an answered `merge` on one of them is still enumerated, because
+	// its apply takes that lock over (task
+	// `wire-merge-questions-into-the-advance-tick`, decision 6). GRACEFUL: a read
+	// fault yields an empty set, so every held lock keeps excluding its item.
+	const proposeKeptSlugs = hasLockRemote
+		? await proposeKeptTaskSlugs(cwd, lockRemote, env)
+		: new Set<string>();
 	const localReport = scanRepoPaths(
 		[cwd],
 		config,
 		heldSlugs,
 		options.override,
 		heldSpecSlugs,
+		proposeKeptSlugs,
 	);
 	const repo = localReport.repos[0];
 

package/src/decision-engine.ts

@@ -138,6 +138,16 @@ export interface DecisionVerdict {
 	 * append/re-pause loop).
 	 */
 	question?: string;
+	/**
+	 * The follow-up questions as SEPARATE questions (`ask` outcome); when
+	 * non-empty it takes precedence over {@link question}, and each becomes its
+	 * own sidecar entry. The decision agent's contract emits the single
+	 * `question` ({@link parseDecisionVerdict} does not read this field); the CI
+	 * apply phase sets it when it replays a handed-over `ask`, so a handoff's
+	 * questions are never joined into one (task
+	 * `ci-surface-questions-keep-their-context-and-default`).
+	 */
+	questions?: string[];
 }
 
 /**

package/src/do-config.ts

@@ -1,7 +1,6 @@
 import type {
 	Config,
 	IntegrationMode,
-	MergeQuestions,
 	ObservationTriage,
 	PartialConfig,
 } from './config.js';
@@ -79,7 +78,6 @@ export function doFlagOverrides(
 		SelectionOrderFlags &
 		ObservationTriageFlags &
 		SurfaceBlockersFlags &
-		MergeQuestionsFlags &
 		StrictMergeApprovalFlags &
 		NoPRFlags &
 		MergeRetriesFlags,
@@ -94,17 +92,10 @@ export function doFlagOverrides(
 		// boolean gate over DECLARED blocked work (the orthogonal peer of
 		// `--observation-triage`).
 		...surfaceBlockersFlagOverrides(flags),
-		// `--merge-questions <off|ask|auto>` rides the SAME flag-override chain
-		// (flag > env > per-repo > global > default `ask`): the 3-state gate over
-		// the merge-question SURFACER (spec `land-time-reverify-and-parallel-
-		// merge-ceiling` Story 17 / task `merge-questions-gate-axis`). SEPARATE
-		// axis from `--observation-triage` with a HIGHER default — NEVER rides
-		// `--observation-triage`.
-		...mergeQuestionsFlagOverrides(flags),
 		// `--strict-merge-approval`/`--no-strict-merge-approval` rides the SAME
 		// flag-override chain (flag > env > per-repo > global > default `false`):
 		// the OPT-IN strictness layered on the OQ6 stale-approval default. SEPARATE
-		// axis from `--merge-questions` — the re-surface vs. land branch is
+		// axis from `mergeQuestions`: the re-surface vs. land branch is
 		// `apply-rung-merge-disposition`'s consumer; this only resolves the boolean.
 		...strictMergeApprovalFlagOverrides(flags),
 		// `--selection-order <order>` rides the SAME flag-override chain (flag > env >
@@ -450,51 +441,6 @@ export function mergeRetriesFlagOverrides(
 	return overrides;
 }
 
-/**
- * The merge-questions CLI flag (`advance`): `--merge-questions <off|ask|auto>`,
- * the 3-state gate over the MERGE-QUESTION SURFACER (spec
- * `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
- * `merge-questions-gate-axis`). MIRRORS `--observation-triage`'s SHAPE but is a
- * SEPARATE axis with a HIGHER default (`ask`, never `off` — a dropped merge-
- * question means pushed work never lands). Resolved through the SAME
- * `flag > env > per-repo > global > default` chain as the other gate flags.
- */
-export interface MergeQuestionsFlags {
-	/** `--merge-questions <off|ask|auto>` — the merge-question surfacer gate. */
-	mergeQuestions?: string;
-}
-
-/** The valid `--merge-questions` values (mirrors the env enum coercion). */
-const MERGE_QUESTIONS_VALUES: readonly MergeQuestions[] = [
-	'off',
-	'ask',
-	'auto',
-];
-
-/**
- * Map the `--merge-questions` flag into a {@link PartialConfig} override. Only a
- * present flag contributes (absent ⇒ absent key). An INVALID value FAILS LOUDLY
- * (the same loud-failure contract `--observation-triage` enforces) rather than
- * silently falling through — a typo on a question-surfacing gate must never be
- * quietly ignored.
- */
-export function mergeQuestionsFlagOverrides(
-	flags: MergeQuestionsFlags,
-): PartialConfig {
-	const overrides: PartialConfig = {};
-	if (flags.mergeQuestions !== undefined) {
-		const raw = flags.mergeQuestions;
-		if (!MERGE_QUESTIONS_VALUES.includes(raw as MergeQuestions)) {
-			throw new Error(
-				`Invalid value for --merge-questions: '${raw}'. ` +
-					`Expected one of: ${MERGE_QUESTIONS_VALUES.join(', ')}.`,
-			);
-		}
-		overrides.mergeQuestions = raw as MergeQuestions;
-	}
-	return overrides;
-}
-
 /**
  * **The strict-merge-approval CLI flag** (`--strict-merge-approval` /
  * `--no-strict-merge-approval`) — spec
@@ -504,8 +450,7 @@ export function mergeQuestionsFlagOverrides(
  * change instead of auto-landing on a green re-verify (the host-agnostic
  * analogue of GitHub's "dismiss stale approvals when the base changes"); OFF
  * (default) honours the prior answer + lands when the rebased tip re-verifies
- * GREEN. Offered alongside `--merge-questions` on `advance` (the apply rung is
- * the consumer). Resolved through the SAME `flag > env > per-repo > global >
+ * GREEN. Offered on `advance` (the apply rung is the consumer). Resolved through the SAME `flag > env > per-repo > global >
  * default` chain as the other gate-family members. A negatable boolean
  * (mirrors `--fresh-worktree-gate`).
  */