dorfl 0.14.2 → 0.15.0

package/src/cli.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import {Command, Option} from 'commander';
+import {Command, InvalidArgumentError, Option} from 'commander';
 import type {Command as Commander} from 'commander';
 import {createInterface} from 'node:readline';
 import {fileURLToPath} from 'node:url';
@@ -66,7 +66,11 @@ import {
 	type IsolatedAdvanceContext,
 } from './advance-isolated.js';
 import {advanceRegistrySetRunTick} from './advance-loop-driver.js';
-import {performIntake, resolveIntakeIntegrationModes} from './intake.js';
+import {
+	performIntake,
+	resolveIntakeIntegrationModes,
+	type PerformIntakeOptions,
+} from './intake.js';
 import {workFolderPrefix} from './work-layout.js';
 import {
 	performDoAuto,
@@ -90,6 +94,7 @@ import {
 	encodeRepoKey,
 } from './repo-mirror.js';
 import {identityEnv, type Identity} from './identity.js';
+import {runMergeQuestionTick} from './merge-question-tick.js';
 import {
 	harnessFlagOverrides,
 	doFlagOverrides,
@@ -121,7 +126,10 @@ import {
 	type DataLeak,
 } from './prd-to-spec.js';
 import {resyncProtocol, type ResyncResult} from './resync-protocol.js';
-import {sweepRemoteMergedBranches} from './reap-branches.js';
+import {
+	sweepRemoteMergedBranches,
+	sweepTerminalItemLocks,
+} from './reap-branches.js';
 import {sweepOrphanSidecars} from './orphan-sidecar.js';
 import {sweepLedgerDuplicates, formatLedgerSweep} from './ledger-lint.js';
 import {status, formatStatus} from './status.js';
@@ -161,6 +169,19 @@ import {GitHubCIContext} from './install-ci-github.js';
 import {loadCapabilityRegistry} from './install-ci-core.js';
 import {performCloseMergedIssues} from './close-job.js';
 import {installSkills, type InstallSkillsResult} from './install-skills.js';
+import {parsePhase, PhaseUsageError, type Phase} from './phase.js';
+import {activateProcessPhase} from './phase-recorder.js';
+import {performBuildPhase, type BuildPhaseVerb} from './ci-phase-build.js';
+import {performIntakePhase} from './ci-phase-intake.js';
+import {performTaskingPhase} from './ci-phase-tasking.js';
+import {advancePhasePath, performTreelessPhase} from './ci-phase-treeless.js';
+import {
+	AgentResultUsageError,
+	parseAgentJobResult,
+	parseAgentTimeoutMinutes,
+	type AgentJobResult,
+} from './ci-agent-result.js';
+import {singleJobWarning} from './single-job-warning.js';
 
 interface ScanFlags {
 	config?: string;
@@ -168,10 +189,61 @@ interface ScanFlags {
 	json?: boolean;
 	here?: boolean;
 	reconcileLocks?: boolean;
+	allArbiters?: boolean;
 	arbiterRemote?: string;
 	arbiter?: string;
 }
 
+/**
+ * Resolve the ARBITER SCOPE of a `--reconcile-locks` write for `status` or `scan`
+ * (tasks `reconcile-locks-stays-within-the-current-arbiter` and
+ * `status-no-arbiter-is-honoured`). Like `gc`, the drain is arbiter-scoped by
+ * DEFAULT: the hub key of the arbiter resolved from the cwd (its `--arbiter`
+ * remote, else the configured `defaultArbiter`), so a drain run in repo A never
+ * releases repo B's locks. `--all-arbiters` is the explicit, loud global opt-in
+ * and returns `undefined` (= every mirror). With neither a resolvable cwd arbiter
+ * nor the flag this REFUSES (exit 1) rather than silently widening the write.
+ * Returns `undefined` too when `--reconcile-locks` is absent (the key is then
+ * ignored by the report builders).
+ */
+function resolveReconcileArbiterKey(
+	verb: 'status' | 'scan',
+	flags: {
+		reconcileLocks?: boolean;
+		allArbiters?: boolean;
+		arbiter?: string | false;
+	},
+	defaultArbiter: string,
+): string | undefined {
+	if (flags.reconcileLocks !== true) {
+		return undefined;
+	}
+	if (flags.allArbiters === true) {
+		console.error(
+			'>> --all-arbiters: releasing stale per-item locks GLOBALLY across ' +
+				'ALL registered arbiters (NOT scoped to the current repo).',
+		);
+		return undefined;
+	}
+	// `typeof` guard: on `status`, `--no-arbiter` is commander's negation of
+	// `--arbiter`, so it arrives as `arbiter: false`, not a remote name.
+	const remote =
+		typeof flags.arbiter === 'string' ? flags.arbiter : defaultArbiter;
+	const key = resolveArbiterKeyFromCwd(process.cwd(), remote, process.env);
+	if (key === undefined) {
+		console.error(
+			`refusing: \`${verb} --reconcile-locks\` is ARBITER-SCOPED and could ` +
+				`not resolve an arbiter from the current directory (no '${remote}' ` +
+				'git remote, or not inside a repo). It will NOT fall back to ' +
+				'releasing locks on every arbiter. Run it from a repo with an ' +
+				'arbiter remote, pass --arbiter <remote>, or --all-arbiters to ' +
+				'reconcile every registered arbiter.',
+		);
+		process.exit(1);
+	}
+	return key;
+}
+
 /**
  * Whether `--auto-build` / `--no-auto-build` was explicitly passed on the command
  * line. Commander gives a negatable boolean option a default of `true`, so we
@@ -750,6 +822,16 @@ function explicitSpecsLandInFromFlag(
 
 interface DoFlags {
 	config?: string;
+	/** Hidden, CI-only `--phase lock|agent|apply` (see {@link phaseOption}). */
+	phase?: Phase;
+	/** Hidden, CI-only: the directory the agent phase writes the handoff to. */
+	handoffOut?: string;
+	/** Hidden, CI-only: the directory the apply phase reads the handoff from. */
+	handoffIn?: string;
+	/** Hidden, CI-only: `needs.agent.result`, for the apply phase. */
+	agentResult?: AgentJobResult;
+	/** Hidden, CI-only: the lock job's `agentTimeoutMinutes`, for the apply phase. */
+	agentTimeoutMinutes?: number;
 	arbiter?: string;
 	remote?: string;
 	/** `--isolated`: build in a job worktree off THIS repo's arbiter (no checkout takeover). Since `make-isolated-default-build-mode` this is the DEFAULT; the flag remains accepted as a redundant explicit opt-IN alias (D3). */
@@ -764,8 +846,6 @@ interface DoFlags {
 	observationTriage?: string;
 	/** `--surface-blockers` / `--no-surface-blockers`: the declared-blocked-work gate (`advance`). */
 	surfaceBlockers?: boolean;
-	/** `--merge-questions <off|ask|auto>`: the merge-question SURFACER gate (`advance`). SEPARATE from `--observation-triage` with a HIGHER default. */
-	mergeQuestions?: string;
 	/** `--strict-merge-approval` / `--no-strict-merge-approval`: the OPT-IN strictness layered on the OQ6 stale-approval default (`advance`). Default OFF — ON re-surfaces the merge-question on a merge-base change instead of auto-landing on a green re-verify. */
 	strictMergeApproval?: boolean;
 	merge?: boolean;
@@ -804,6 +884,16 @@ interface DoFlags {
 
 interface IntakeFlags {
 	config?: string;
+	/** Hidden, CI-only `--phase lock|agent|apply` (see {@link phaseOption}). */
+	phase?: Phase;
+	/** Hidden, CI-only: the directory the agent phase writes the handoff to. */
+	handoffOut?: string;
+	/** Hidden, CI-only: the directory the apply phase reads the handoff from. */
+	handoffIn?: string;
+	/** Hidden, CI-only: `needs.agent.result`, for the apply phase. */
+	agentResult?: AgentJobResult;
+	/** Hidden, CI-only: accepted for parity with `do`/`advance`; intake does not use it. */
+	agentTimeoutMinutes?: number;
 	arbiter?: string;
 	merge?: boolean;
 	propose?: boolean;
@@ -1027,10 +1117,15 @@ interface StatusFlags {
 	config?: string;
 	workspace?: string;
 	arbiterRemote?: string;
-	arbiter?: string;
-	noArbiter?: boolean;
+	/**
+	 * `--arbiter <remote>` gives the remote name; `--no-arbiter` is commander's
+	 * NEGATION of the same option and arrives as `false` (there is no separate
+	 * `noArbiter` key). `undefined` when neither is passed.
+	 */
+	arbiter?: string | false;
 	here?: boolean;
 	reconcileLocks?: boolean;
+	allArbiters?: boolean;
 	json?: boolean;
 }
 
@@ -1307,6 +1402,254 @@ function resolvePackageVersion(): string {
 	}
 }
 
+/**
+ * The hidden, CI-only `--phase lock|agent|apply` option shared by `intake`,
+ * `advance` and `do` (spec `ci-agent-job-without-write-token`, see `phase.ts`).
+ * Validated at PARSE time ({@link parsePhase}): an unknown value, or any value
+ * outside GitHub Actions, is a commander usage error before the action runs.
+ * Absent ⇒ today's single process.
+ */
+function phaseOption(): Option {
+	return new Option(
+		'--phase <phase>',
+		'(CI-only) run as one job of the split CI item workflow: lock, agent or apply. Requires GITHUB_ACTIONS=true.',
+	)
+		.hideHelp()
+		.argParser((raw: string): Phase => {
+			try {
+				return parsePhase(raw);
+			} catch (err) {
+				if (err instanceof PhaseUsageError) {
+					throw new InvalidArgumentError(err.message);
+				}
+				throw err;
+			}
+		});
+}
+
+/**
+ * Enter the `--phase` for this one-shot process (a no-op without one): the phase
+ * guards fire from here on, and the agent phase records its write seams.
+ */
+function enterCliPhase(phase: Phase | undefined): void {
+	if (phase !== undefined) {
+		activateProcessPhase(phase);
+	}
+}
+
+/**
+ * The hidden, CI-only handoff-directory options of the phase mode: the agent
+ * phase writes the handoff to `--handoff-out`, the apply phase reads it from
+ * `--handoff-in` (task `ci-split-build-path`).
+ */
+function handoffDirOptions(): Option[] {
+	return [
+		new Option(
+			'--handoff-out <dir>',
+			'(CI-only, --phase agent) write the handoff artifact to this directory',
+		).hideHelp(),
+		new Option(
+			'--handoff-in <dir>',
+			'(CI-only, --phase apply) read the handoff artifact from this directory (under $RUNNER_TEMP)',
+		).hideHelp(),
+	];
+}
+
+/**
+ * The hidden, CI-only agent-result options of the apply phase (task
+ * `ci-split-agent-result-and-reruns`, decision 5): `--agent-result` is
+ * `needs.agent.result` (only `success` reads the handoff), and
+ * `--agent-timeout-minutes` is the lock job's trusted `agentTimeoutMinutes`,
+ * which tells a timed-out agent job from a cancelled one.
+ */
+function agentResultOptions(): Option[] {
+	const parse =
+		<T>(fn: (raw: string) => T) =>
+		(raw: string): T => {
+			try {
+				return fn(raw);
+			} catch (err) {
+				if (err instanceof AgentResultUsageError) {
+					throw new InvalidArgumentError(err.message);
+				}
+				throw err;
+			}
+		};
+	return [
+		new Option(
+			'--agent-result <result>',
+			'(CI-only, --phase apply) the agent job result (needs.agent.result): success, failure, cancelled or skipped',
+		)
+			.hideHelp()
+			.argParser(parse(parseAgentJobResult)),
+		new Option(
+			'--agent-timeout-minutes <n>',
+			"(CI-only, --phase apply) the agent job's timeout, the lock job's agentTimeoutMinutes output",
+		)
+			.hideHelp()
+			.argParser(parse(parseAgentTimeoutMinutes)),
+	];
+}
+
+/**
+ * Run ONE phase of the split build path (`do <slug>` / `advance task:<slug>`)
+ * or tasking path (`do spec:<slug>` / `advance spec:<slug>`, task
+ * `ci-split-tasking`) for a single named item with `--phase`, and exit with its
+ * code. The lock phase
+ * reads its trusted facts back from nowhere (it produces them); the agent and
+ * apply phases read them from `DORFL_LOCK_OUTPUTS` (see `ci-lock-outputs.ts`).
+ */
+async function runBuildPhaseAndExit(
+	verb: BuildPhaseVerb,
+	args: string[],
+	flags: DoFlags,
+	options: Omit<DoOptions, 'arg'>,
+): Promise<never> {
+	const phase = flags.phase!;
+	if (args.length !== 1) {
+		console.error(
+			`error: --phase runs ONE CI item; name exactly one item (got ${args.length}).`,
+		);
+		process.exit(1);
+	}
+	const handoffDir = phase === 'agent' ? flags.handoffOut : flags.handoffIn;
+	if (phase !== 'lock' && handoffDir === undefined) {
+		console.error(
+			`error: --phase ${phase} needs ${phase === 'agent' ? '--handoff-out' : '--handoff-in'} <dir>.`,
+		);
+		process.exit(1);
+	}
+	if (phase === 'apply' && flags.agentResult === undefined) {
+		console.error(
+			'error: --phase apply needs --agent-result <result> (needs.agent.result).',
+		);
+		process.exit(1);
+	}
+	// A `spec:<slug>` item is the TASKING path (task `ci-split-tasking`); every
+	// other item is the build path, which refuses a non-task itself.
+	const result =
+		parseSlugArg(args[0]).explicit === 'spec'
+			? await performTaskingPhase({
+					...options,
+					arg: args[0],
+					phase,
+					verb,
+					handoffDir,
+					agentResult: flags.agentResult,
+					agentTimeoutMinutes: flags.agentTimeoutMinutes,
+				})
+			: await performBuildPhase({
+					...options,
+					arg: args[0],
+					phase,
+					verb,
+					handoffDir,
+					allowBacklog: flags.allowBacklog === true,
+					agentResult: flags.agentResult,
+					agentTimeoutMinutes: flags.agentTimeoutMinutes,
+				});
+	if (result.exitCode !== 0) {
+		console.error(`error: ${result.message}`);
+	} else {
+		console.error(`>> ${result.message}`);
+	}
+	process.exit(result.exitCode);
+}
+
+/**
+ * Run ONE phase of `advance <item> --phase` and exit with its code. The item's
+ * rung picks the split path ({@link advancePhasePath}): the build and tasking
+ * paths as before ({@link runBuildPhaseAndExit}), and the tree-less rungs
+ * (surface, triage, apply; task `ci-split-treeless-rungs`) through
+ * {@link performTreelessPhase} with the same advance context the laptop tick
+ * gets.
+ */
+async function runAdvancePhaseAndExit(
+	args: string[],
+	flags: DoFlags,
+	doOptions: Omit<DoOptions, 'arg'>,
+	advanceContext: AdvanceContext,
+): Promise<never> {
+	const phase = flags.phase!;
+	if (args.length === 1) {
+		const path = await advancePhasePath({
+			phase,
+			arg: args[0],
+			cwd: advanceContext.cwd,
+			arbiter: advanceContext.arbiter,
+			env: identityEnv(doOptions.identity, process.env),
+		});
+		if (path === 'treeless') {
+			const handoffDir = phase === 'agent' ? flags.handoffOut : flags.handoffIn;
+			if (phase !== 'lock' && handoffDir === undefined) {
+				console.error(
+					`error: --phase ${phase} needs ${phase === 'agent' ? '--handoff-out' : '--handoff-in'} <dir>.`,
+				);
+				process.exit(1);
+			}
+			if (phase === 'apply' && flags.agentResult === undefined) {
+				console.error(
+					'error: --phase apply needs --agent-result <result> (needs.agent.result).',
+				);
+				process.exit(1);
+			}
+			const result = await performTreelessPhase({
+				...advanceContext,
+				arg: args[0],
+				phase,
+				identity: doOptions.identity,
+				handoffDir,
+				agentResult: flags.agentResult,
+				agentTimeoutMinutes: flags.agentTimeoutMinutes,
+			});
+			if (result.exitCode !== 0) {
+				console.error(`error: ${result.message}`);
+			} else {
+				console.error(`>> ${result.message}`);
+			}
+			process.exit(result.exitCode);
+		}
+	}
+	return runBuildPhaseAndExit('advance', args, flags, doOptions);
+}
+
+/**
+ * Run ONE phase of the split intake path (`intake <N> --phase`) and exit with
+ * its code (task `ci-split-intake`). The agent and apply phases read the lock
+ * job's facts from `DORFL_LOCK_OUTPUTS`.
+ */
+async function runIntakePhaseAndExit(
+	flags: IntakeFlags,
+	options: PerformIntakeOptions,
+): Promise<never> {
+	const phase = flags.phase!;
+	const handoffDir = phase === 'agent' ? flags.handoffOut : flags.handoffIn;
+	if (phase !== 'lock' && handoffDir === undefined) {
+		console.error(
+			`error: --phase ${phase} needs ${phase === 'agent' ? '--handoff-out' : '--handoff-in'} <dir>.`,
+		);
+		process.exit(1);
+	}
+	if (phase === 'apply' && flags.agentResult === undefined) {
+		console.error(
+			'error: --phase apply needs --agent-result <result> (needs.agent.result).',
+		);
+		process.exit(1);
+	}
+	const result = await performIntakePhase({
+		...options,
+		phase,
+		handoffDir,
+		agentResult: flags.agentResult,
+	});
+	if (result.exitCode !== 0) {
+		console.error(`error: ${result.message}`);
+	} else {
+		console.error(`>> ${result.message}`);
+	}
+	process.exit(result.exitCode);
+}
+
 export function buildProgram(): Command {
 	const program = new Command();
 
@@ -1389,7 +1732,11 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--reconcile-locks',
-			'WRITE: release the per-item locks whose item is already at rest in a terminal folder on the arbiter’s main (e.g. a merged propose PR left its lock behind). Without this flag `scan` is strictly read-only. Not normally needed, the claim path releases them automatically on every unit of work. An item that is NOT terminal on main (a live build, an open PR, a stuck item) is NEVER released, with or without the flag.',
+			'WRITE: release the per-item locks whose item is already at rest in a terminal folder on the arbiter’s main (e.g. a merged propose PR left its lock behind). Without this flag `scan` is strictly read-only. SCOPE: by DEFAULT this is ARBITER-SCOPED, like gc and `status --reconcile-locks`: it releases locks ONLY on the arbiter resolved from the current directory (its --arbiter remote, default: the configured defaultArbiter), so a drain run in repo A never touches repo B’s locks (other repos’ stale locks are still classified). Pass --all-arbiters to release across EVERY registered arbiter. Refuses when no arbiter resolves from the cwd and --all-arbiters is not given. Not normally needed, the claim path releases them automatically on every unit of work. An item that is NOT terminal on main (a live build, an open PR, a stuck item) is NEVER released, with or without the flag.',
+		)
+		.option(
+			'--all-arbiters',
+			'with --reconcile-locks: release stale locks across EVERY registered arbiter (loud + global), not just the current repo’s. No effect on the read-only report, which always covers every registered repo.',
 		)
 		.option('--json', 'output the raw report as JSON')
 		.action(async (flags: ScanFlags, command: Commander) => {
@@ -1432,10 +1779,19 @@ export function buildProgram(): Command {
 				}
 				return;
 			}
+			// SCOPE of the registry-loop `--reconcile-locks` WRITE: arbiter-scoped by
+			// default, `--all-arbiters` for the global drain, refusal when neither
+			// resolves (the SAME rule `status --reconcile-locks` applies).
+			const reconcileArbiterKey = resolveReconcileArbiterKey(
+				'scan',
+				flags,
+				config.defaultArbiter,
+			);
 			const report = await scan(config, {
 				warn,
 				override,
 				reconcileLocks: flags.reconcileLocks === true,
+				reconcileArbiterKey,
 			});
 			// The cwd-local section: resolve it ONLY when a participating cwd is NOT
 			// already covered by a registered mirror. A FETCH-FREE pre-check
@@ -2425,7 +2781,13 @@ export function buildProgram(): Command {
 			'--merge-retries <n>',
 			'cross-job merge-serialiser CAS-retry cap (see `run --help`); resolved flag > env > per-repo > global > default 1000.',
 		)
+		.addOption(phaseOption())
+		.addOption(handoffDirOptions()[0])
+		.addOption(handoffDirOptions()[1])
+		.addOption(agentResultOptions()[0])
+		.addOption(agentResultOptions()[1])
 		.action(async (rawSlugs: string[], flags: DoFlags) => {
+			enterCliPhase(flags.phase);
 			// Variadic grammar (`do-autopick`): zero args = AUTO-PICK; one = the single
 			// named item; many = those, IN SEQUENCE. `-n <x>` is the auto-pick count.
 			const args = rawSlugs ?? [];
@@ -2798,6 +3160,7 @@ export function buildProgram(): Command {
 			// sequential `performDo` (do-autopick runs the EXISTING pipeline per item).
 			const baseDoOptions: Omit<DoOptions, 'arg'> = {
 				cwd,
+				phase: flags.phase,
 				arbiter: flags.arbiter ?? config.defaultArbiter,
 				// The host-only runner IDENTITY (a bot): scopes the runner's git/provider
 				// ops (claim, push, integrate, `gh`) — NEVER the agent launch. Absent ⇒
@@ -2910,6 +3273,12 @@ export function buildProgram(): Command {
 				process.exit(1);
 			}
 
+			// CI PHASE MODE (task `ci-split-build-path`): `--phase` runs ONE job of the
+			// split item workflow for a single named task or spec, on the SAME pipeline.
+			if (flags.phase !== undefined) {
+				await runBuildPhaseAndExit('do', args, flags, baseDoOptions);
+			}
+
 			// DISPATCH the variadic grammar (in-place forms):
 			//   zero args         -> AUTO-PICK `count` (default 1) across the two pools
 			//                        (ordered by selectionOrder; default drain = tasks-first)
@@ -2964,7 +3333,7 @@ export function buildProgram(): Command {
 		.command('advance')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'Advance work/ item(s) one lifecycle rung toward ready/built (SPEC advance-loop), the SEQUENTIAL one-shot driver over the advance tick. advance <slug> (bare = the task) | advance spec:<slug> (the spec tasking rung) | advance obs:<slug> (triage an observation) | advance (auto-pick one eligible) | advance <a> <b> (those, in sequence) | advance -n <x> (x eligible, in sequence). Each item: classify (read-only, no model, no lock) → take the `advancing` CAS lock → dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do spec:`, surface/apply always run, triage respects observationTriage (off|ask|auto). The bare/`-n` selection respects the per-action gates (build→autoBuild, task→autoTask, triage→observationTriage); `-n` is ALWAYS sequential (parallelism is `run` / the CI matrix).',
+			'Advance work/ item(s) one lifecycle rung toward ready/built (SPEC advance-loop), the SEQUENTIAL one-shot driver over the advance tick. advance <slug> (bare = the task) | advance spec:<slug> (the spec tasking rung) | advance obs:<slug> (triage an observation) | advance (auto-pick one eligible) | advance <a> <b> (those, in sequence) | advance -n <x> (x eligible, in sequence). Each item: classify (read-only, no model, no lock) → take the `advancing` CAS lock → dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do spec:`, surface/apply always run, triage respects observationTriage (off|ask|auto). The bare/`-n` selection respects the per-action gates (build→autoBuild, task→autoTask, triage→observationTriage); `-n` is ALWAYS sequential (parallelism is `run` / the CI matrix). Before it selects, the bare/`-n` form also asks a merge question for each unmerged work/task-<slug> branch with no open PR and no live build (the `surface-merge-questions` pass; gated by mergeQuestions off|ask).',
 		)
 		.argument(
 			'[slugs...]',
@@ -3001,15 +3370,11 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--strict-merge-approval',
-			'opt in to the host-agnostic "dismiss stale approvals on base change" discipline (spec `land-time-reverify-and-parallel-merge-ceiling` sidecar OQ6): when the merge-base CHANGED between the human’s merge-answer and the apply step, RE-SURFACE the merge-question (clear the answer back to no-answer; re-author the question on main/runner under the advancing lock) instead of auto-landing on a green re-verify. Default OFF (a green re-verify is trusted as sufficient; honour the prior answer). Story #16’s RED-re-verify refusal is UNCHANGED and independent of this flag. Resolved flag > env > per-repo > global > default off.',
+			'opt in to the host-agnostic "dismiss stale approvals on base change" discipline (spec `land-time-reverify-and-parallel-merge-ceiling` sidecar OQ6): when `main`’s code (anything outside `work/`) moved since the merge-question was asked (the `askedAtMain` it records), RE-SURFACE the merge-question (append a follow-up asked against the current `main`, under the advancing lock) instead of auto-landing on a green re-verify. A question written before `askedAtMain` existed never re-stales. Default OFF (a green re-verify is trusted as sufficient; honour the prior answer). Story #16’s RED-re-verify refusal is UNCHANGED and independent of this flag. Resolved flag > env > per-repo > global > default off.',
 		)
 		.option(
 			'--no-strict-merge-approval',
-			'honour the prior merge-answer and land when the rebased tip re-verifies GREEN even if the merge-base changed (default; the cheap green-re-verify-is-enough path)',
-		)
-		.option(
-			'--merge-questions <mode>',
-			'the merge-question SURFACER gate (off|ask|auto): off drops the surfacer (only for a repo that lands by some other means); ask (default) enumerates unmerged `work/*` branches and surfaces a merge-question sidecar a human answers; auto self-supplies the `merge` answer and lands via the SAME deterministic apply-time re-verify (the merge-mode-like fast path). SEPARATE axis from --observation-triage with a HIGHER default (a dropped merge-question means pushed work never lands). Resolved flag > env > per-repo > global > default ask.',
+			'honour the prior merge-answer and land when the rebased tip re-verifies GREEN even if `main` moved since the question was asked (default; the cheap green-re-verify-is-enough path)',
 		)
 		.option(
 			'--merge',
@@ -3027,7 +3392,13 @@ export function buildProgram(): Command {
 			'--watch',
 			"stream the build agent's high-signal events live by tailing the pi session log (requires harness: pi; READ-ONLY observer — does not change outcome/gate/git). The same view `do --watch` gives, threaded through the build rung; CI uses it so the job log shows the agent working instead of freezing.",
 		)
+		.addOption(phaseOption())
+		.addOption(handoffDirOptions()[0])
+		.addOption(handoffDirOptions()[1])
+		.addOption(agentResultOptions()[0])
+		.addOption(agentResultOptions()[1])
 		.action(async (rawSlugs: string[], flags: DoFlags) => {
+			enterCliPhase(flags.phase);
 			// Variadic grammar (mirrors `do`): zero args = AUTO-PICK; one = the single
 			// named item; many = those, IN SEQUENCE. `-n <x>` is the auto-pick count
 			// (ALWAYS sequential, US #25).
@@ -3289,6 +3660,7 @@ export function buildProgram(): Command {
 			// hands the resolved arg to `performDo`, never re-implementing it.
 			const doOptions: Omit<DoOptions, 'arg'> = {
 				cwd,
+				phase: flags.phase,
 				// `--watch`: stream the build agent's session live (pi harness only;
 				// validated in `performDo`). Threaded through the orchestrated build rung
 				// so `advance --watch` (and CI) shows the agent working, not a frozen log.
@@ -3351,6 +3723,7 @@ export function buildProgram(): Command {
 			// Surface + apply stay ALWAYS allowed regardless of the gate family.
 			const advanceContext: AdvanceContext = {
 				cwd,
+				phase: flags.phase,
 				arbiter: flags.arbiter ?? config.defaultArbiter,
 				doOptions,
 				surfaceGate: harnessSurfaceGate({harness, agentCmd: config.agentCmd}),
@@ -3360,6 +3733,14 @@ export function buildProgram(): Command {
 				observationTriage: config.observationTriage,
 				triageGate: harnessTriageGate({harness, agentCmd: config.agentCmd}),
 				triageModel: config.triageModel,
+				// The answered-merge land (the apply rung's `kind: merge` action) cuts
+				// its job worktree under `workspacesDir` and gates the rebased tip with
+				// `prepare` / `verify`; without them an answered `merge` is refused
+				// as a usage error (task `wire-merge-questions-into-the-advance-tick`).
+				workspacesDir: config.workspacesDir,
+				prepare: config.prepare,
+				verify: config.verify,
+				strictMergeApproval: config.strictMergeApproval,
 				note: (message) => console.error(`>> ${message}`),
 			};
 
@@ -3368,6 +3749,24 @@ export function buildProgram(): Command {
 			// ticks in sequence and would tail several logs; reject rather than silently
 			// stream only one. The CI propose matrix names a single item per leg, so it
 			// satisfies this; the `-n` merge job must NOT pass `--watch`.
+			// CI PHASE MODE (task `ci-split-build-path`): `--phase` runs ONE job of the
+			// split item workflow: the build, tasking and tree-less (surface, triage,
+			// apply) paths are split (task `ci-split-treeless-rungs`), and the apply
+			// rung's answered merge action with them (task
+			// `ci-split-answered-merge-action`), whose agent job checks the branch
+			// out through `createJob` under `workspacesDir` and gates the rebased tip
+			// with the repo's `prepare` / `verify`. Threaded for the phase mode ONLY:
+			// the in-place laptop tick below keeps today's context.
+			if (flags.phase !== undefined) {
+				await runAdvancePhaseAndExit(args, flags, doOptions, {
+					...advanceContext,
+					workspacesDir: config.workspacesDir,
+					prepare: config.prepare,
+					verify: config.verify,
+					strictMergeApproval: config.strictMergeApproval,
+				});
+			}
+
 			const advanceMulti =
 				args.length === 0 || count !== undefined || args.length > 1;
 			if (advanceMulti && flags.watch === true) {
@@ -3461,7 +3860,7 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--remote-branches',
-			'SWEEP the arbiter’s remote work/* BRANCHES instead of job worktrees: delete (via git push --delete, NEVER --force) exactly those PROVABLY MERGED into <arbiter>/main (git merge-base --is-ancestor, the SAME predicate the worktree reaper uses), and RETAIN the rest with a reason. An in-flight/un-merged branch (the recovery point) is NEVER touched. Provider-agnostic plain git — works on a --bare arbiter. The merged-only complement of `requeue --reset`.',
+			'SWEEP the arbiter’s remote work/* BRANCHES instead of job worktrees: delete (via git push --delete, NEVER --force) exactly those PROVABLY MERGED into <arbiter>/main (git merge-base --is-ancestor, the SAME predicate the worktree reaper uses), and RETAIN the rest with a reason. An in-flight/un-merged branch (the recovery point) is NEVER touched. Provider-agnostic plain git — works on a --bare arbiter. The merged-only complement of `requeue --reset`. The same run ALSO releases every per-item lock whose item is TERMINAL on <arbiter>/main (the `status --reconcile-locks` reconcile: leased on the sha it read, never forced; a lock whose item is not terminal is never touched), so the locks merged propose PRs leave behind do not accumulate.',
 		)
 		.option(
 			'--arbiter <remote-or-url>',
@@ -3477,7 +3876,7 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--dry-run',
-			'(with --remote-branches) REPORT which merged branches WOULD be reaped without deleting anything (a read-only preview)',
+			'(with --remote-branches) REPORT which merged branches WOULD be reaped (and which terminal-item locks WOULD be released) without deleting anything (a read-only preview)',
 		)
 		.option('--json', 'output the raw result as JSON')
 		.action(async (flags: GcFlags) => {
@@ -3631,9 +4030,27 @@ export function buildProgram(): Command {
 					dryRun: flags.dryRun === true,
 					note: (message) => console.error(`>> ${message}`),
 				});
+				// The TERMINAL-LOCK release (task `ci-releases-locks-of-terminal-items`)
+				// rides this SAME invocation for the same reason the orphan sweep does: the
+				// scheduled `reap-merged-branches` CI job runs exactly this command, and a
+				// merged propose item is never claimed again, so without it the lock a
+				// merged PR leaves behind accumulates on the arbiter for ever. It is the
+				// `status --reconcile-locks` reconcile (terminal-on-main only, leased on
+				// the sha it read, never forced), scoped to the one `--arbiter` swept
+				// here. Honours `--dry-run` (report-only preview).
+				const locks = await sweepTerminalItemLocks({
+					cwd: sweepCwd,
+					arbiter: flags.arbiter ?? 'origin',
+					dryRun: flags.dryRun === true,
+					note: (message) => console.error(`>> ${message}`),
+				});
 				if (flags.json) {
 					console.log(
-						JSON.stringify({...sweep, orphanSidecars: orphans}, null, 2),
+						JSON.stringify(
+							{...sweep, orphanSidecars: orphans, terminalLocks: locks},
+							null,
+							2,
+						),
 					);
 					return;
 				}
@@ -3644,6 +4061,11 @@ export function buildProgram(): Command {
 					for (const w of orphans.wouldReap) {
 						console.log(`  [would-reap] ${w.path} \u2014 orphan sidecar`);
 					}
+					for (const entry of locks.wouldRelease) {
+						console.log(
+							`  [would-release] lock ${entry} \u2014 item terminal on main`,
+						);
+					}
 				} else {
 					for (const r of sweep.reaped) {
 						console.log(`  [reaped]   ${r.branch} \u2014 merged`);
@@ -3651,6 +4073,14 @@ export function buildProgram(): Command {
 					for (const r of orphans.reaped) {
 						console.log(`  [reaped]   ${r.path} \u2014 orphan sidecar`);
 					}
+					for (const entry of locks.released) {
+						console.log(
+							`  [released] lock ${entry} \u2014 item terminal on main`,
+						);
+					}
+				}
+				for (const e of locks.errors) {
+					console.log(`  [kept]     lock ${e.entry} \u2014 ${e.message}`);
 				}
 				for (const ret of sweep.retained) {
 					console.log(`  [retained] ${ret.branch} \u2014 ${ret.reasonText}`);
@@ -3660,8 +4090,19 @@ export function buildProgram(): Command {
 						? sweep.wouldReap.length + orphans.wouldReap.length
 						: sweep.reaped.length + orphans.reaped.length;
 				const verb = flags.dryRun === true ? 'would reap' : 'reaped';
+				const releasedLocks =
+					flags.dryRun === true
+						? locks.wouldRelease.length
+						: locks.released.length;
+				const releaseVerb =
+					flags.dryRun === true ? 'would release' : 'released';
 				console.log(
-					`Summary: ${reapedCount} ${verb}, ${sweep.retained.length} retained.`,
+					`Summary: ${reapedCount} ${verb}, ${sweep.retained.length} retained; ` +
+						`${releasedLocks} terminal-item lock(s) ${releaseVerb}` +
+						(locks.errors.length > 0
+							? `, ${locks.errors.length} kept on error`
+							: '') +
+						'.',
 				);
 				return;
 			}
@@ -3773,7 +4214,8 @@ export function buildProgram(): Command {
 			}
 			for (const retained of result.retained) {
 				console.log(
-					`  [retained] ${retained.slug} \u2014 ${RETAIN_REASON_TEXT[retained.reason]}`,
+					`  [retained] ${retained.slug} \u2014 ${RETAIN_REASON_TEXT[retained.reason]}` +
+						(retained.hint ? ` (${retained.hint})` : ''),
 				);
 			}
 			for (const orphan of result.sweptOrphans) {
@@ -3921,7 +4363,11 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--reconcile-locks',
-			'WRITE: release the per-item locks reported as "Completed, lock not yet released" (item already at rest in a terminal folder on the arbiter’s main, e.g. a merged propose PR). Without this flag `status` is strictly read-only and only REPORTS them. Not normally needed, the claim path releases them automatically on every unit of work; this is the manual “drain them now” lever. An item that is NOT terminal on main (a live build, an open PR, a stuck item) is NEVER released, with or without the flag.',
+			'WRITE: release the per-item locks reported as "Completed, lock not yet released" (item already at rest in a terminal folder on the arbiter’s main, e.g. a merged propose PR). Without this flag `status` is strictly read-only and only REPORTS them. SCOPE: by DEFAULT this is ARBITER-SCOPED, like gc: it releases locks ONLY on the arbiter resolved from the current directory (its --arbiter remote, default: the configured defaultArbiter), so a drain run in repo A never touches repo B’s locks (other repos’ stale locks are still REPORTED). Pass --all-arbiters to release across EVERY registered arbiter. Refuses when no arbiter resolves from the cwd and --all-arbiters is not given. Not normally needed, the claim path releases them automatically on every unit of work; this is the manual “drain them now” lever. An item that is NOT terminal on main (a live build, an open PR, a stuck item) is NEVER released, with or without the flag.',
+		)
+		.option(
+			'--all-arbiters',
+			'with --reconcile-locks: release stale locks across EVERY registered arbiter (loud + global), not just the current repo’s. No effect on the read-only report, which always covers every registered repo.',
 		)
 		.option('--json', 'output the raw report as JSON')
 		.action(async (flags: StatusFlags) => {
@@ -3937,7 +4383,10 @@ export function buildProgram(): Command {
 					config,
 					override,
 					arbiterRemote: flags.arbiterRemote ?? DEFAULT_ARBITER_REMOTE,
-					lockArbiterRemote: flags.arbiter ?? 'origin',
+					// `--no-arbiter` arrives as `arbiter: false` (commander negation):
+					// never pass `false` on as a remote name.
+					lockArbiterRemote:
+						typeof flags.arbiter === 'string' ? flags.arbiter : 'origin',
 					reconcileLocks: flags.reconcileLocks === true,
 					warn,
 				});
@@ -3964,10 +4413,23 @@ export function buildProgram(): Command {
 			// REGISTERED HUB MIRROR (the registry), read from its bare `main` ref
 			// through the read seam (mirrors have no working tree).
 			const mirrorPaths = listMirrors({workspacesDir}).map((m) => m.path);
+			// SCOPE of the `--reconcile-locks` WRITE (task
+			// `reconcile-locks-stays-within-the-current-arbiter`): ARBITER-SCOPED by
+			// default, resolved from the cwd exactly like `gc`, so a drain in repo A
+			// never releases repo B's locks. `--all-arbiters` is the explicit, loud
+			// global opt-in. With neither a resolvable cwd arbiter nor the flag we
+			// REFUSE rather than silently widening the write to every arbiter.
+			const reconcileArbiterKey = resolveReconcileArbiterKey(
+				'status',
+				flags,
+				config.defaultArbiter,
+			);
 			// Fold in the current repo's arbiter state (the old `arbiter status`, ADR
 			// §1/§7) unless --no-arbiter. Read-only; tolerates not being in a repo.
+			// Commander treats `--no-arbiter` as the NEGATION of `--arbiter <remote>`
+			// (one `arbiter` key): it sets `arbiter: false`, never a `noArbiter` key.
 			const arbiter =
-				flags.noArbiter === true
+				flags.arbiter === false
 					? undefined
 					: arbiterStatus({
 							cwd: process.cwd(),
@@ -3993,6 +4455,7 @@ export function buildProgram(): Command {
 				arbiter,
 				cwd: cwdSection,
 				reconcileLocks: flags.reconcileLocks === true,
+				reconcileArbiterKey,
 				warn,
 			});
 			if (flags.json) {
@@ -4006,7 +4469,7 @@ export function buildProgram(): Command {
 		.command('requeue <slug>')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'Requeue a STUCK task to the backlog for re-claiming (ADR §12/§14). Recovers a task whose per-item lock is held — stuck (the resolved-recovery path: a previously-routed needs-attention item, now lock `state: stuck`) OR active (a claim that never surfaced — an un-surfaced abort, a killed run, or an in-place requeue note). The body rests in work/tasks/backlog/<slug>.md (claim never moves it under the per-item-lock model); requeue releases the lock so the item is claimable again. The release is published as a TREE-LESS compare-and-swap to the arbiter ref, EXACTLY like claim — it NEVER stages or commits in the cwd working tree, so a requeue in a shared checkout can never sweep up a concurrent writer’s uncommitted files. Escalation ladder (least to most destructive): (1) DEFAULT = keep + continue: leave the work/<slug> branch UNTOUCHED so the next claim CONTINUES from its tip (rebased onto fresh main at onboard-time); if the work/<slug> branch is not on the arbiter (never pushed, or a prior --reset already deleted it), default requeue succeeds anyway with a fresh-claim note. (2) --reconcile (alias --rebase) = NON-DESTRUCTIVE recovery: re-sync the mirror to the arbiter (prune-fetch) and RETRY the rebase of the kept branch onto latest arbiter/main in a scratch worktree; on a clean rebase, push the reconciled tip back (--force-with-lease, work branch only) and release the lock; on a genuine content conflict AFTER the clean re-sync, leave the item stuck and the branch UNTOUCHED (nothing deleted) so the human can retry when the churn settles. NEVER deletes the remote branch. (3) --reset = DESTRUCTIVE last resort: delete the remote work/<slug> branch FIRST (then release the lock) so the next claim starts fresh (guarded; never the default). -m/--message appends a dated handoff note to the item body (all modes; append-only).',
+			'Requeue a STUCK task to the backlog for re-claiming (ADR §12/§14). Recovers a task whose per-item lock is held — stuck (the resolved-recovery path: a previously-routed needs-attention item, now lock `state: stuck`) OR active (a claim that never surfaced — an un-surfaced abort, a killed run, or an in-place requeue note). The body rests in work/tasks/backlog/<slug>.md (claim never moves it under the per-item-lock model); requeue releases the lock so the item is claimable again. The release is published as a TREE-LESS compare-and-swap to the arbiter ref, EXACTLY like claim — it NEVER stages or commits in the cwd working tree, so a requeue in a shared checkout can never sweep up a concurrent writer’s uncommitted files. Escalation ladder (least to most destructive): (1) DEFAULT = keep + continue: leave the work/<slug> branch UNTOUCHED so the next claim CONTINUES from its tip (rebased onto fresh main at onboard-time); if the work/<slug> branch is not on the arbiter (never pushed, or a prior --reset already deleted it), default requeue succeeds anyway with a fresh-claim note. (2) --reconcile (alias --rebase) = NON-DESTRUCTIVE recovery: re-sync the mirror to the arbiter (prune-fetch) and RETRY the rebase of the kept branch onto latest arbiter/main in a scratch worktree; on a clean rebase, push the reconciled tip back (--force-with-lease, work branch only) and release the lock; on a genuine content conflict AFTER the clean re-sync, leave the item stuck and the branch UNTOUCHED (nothing deleted) so the human can retry when the churn settles. NEVER deletes the remote branch. (3) --reset = DESTRUCTIVE last resort: delete the remote work/<slug> branch FIRST (then release the lock) so the next claim starts fresh (guarded; never the default). RELEASED LOCK: a surfaced item (question sidecar on main) has its lock already released by the surface; if its body rests in the pool and its work/<slug> branch is on the arbiter, --reconcile and --reset still act on it, taking a short per-item lock for the operation and releasing it on every outcome; plain requeue on such an item is a no-op (the next claim already continues from the kept branch). -m/--message adds a dated handoff note to the item body, just before its `## Acceptance criteria` so it cannot collide with a kept branch’s done-move tail on the continue rebase (all modes; additive). CRASHED RUN: when the lock is held and a DEAD run left its retained job worktree (workspacesDir/work/*) with commits or uncommitted files the arbiter’s work/<slug> lacks, requeue first commits the residue as a wip commit and pushes the branch (plain push, never --force), so the next claim continues from it; if that save fails, the lock and the worktree are KEPT and requeue says why (not on --reset, which discards the work by design).',
 		)
 		.option('-c, --config <path>', 'config file path', defaultConfigPath())
 		.option(
@@ -4054,6 +4517,11 @@ export function buildProgram(): Command {
 				);
 				process.exit(1);
 			}
+			// Where `do --isolated` retains job worktrees: a CRASHED run's retained
+			// worktree may hold local-only commits, which requeue saves (pushes to the
+			// work branch) before it releases the lock (task
+			// `a-crashed-runs-local-work-is-saved-before-its-lock-is-released`).
+			const {workspacesDir} = resolveGlobalConfig(loadConfig(flags.config), {});
 			const result = await ledgerWrite.applyReturnToBacklogTransition({
 				cwd,
 				slug,
@@ -4061,6 +4529,7 @@ export function buildProgram(): Command {
 				// arbiter to `origin` so the common case Just Works; `--arbiter` overrides.
 				// `--cwd` is purely the ORIGIN SOURCE the remote is resolved from.
 				arbiter: flags.arbiter ?? 'origin',
+				workspacesDir,
 				reset: flags.reset,
 				reconcile,
 				message: flags.message,
@@ -4076,7 +4545,13 @@ export function buildProgram(): Command {
 				: result.reconciled
 					? ` (--reconcile: re-synced mirror + rebased ${workBranchRef('task', slug)} onto latest main and pushed the reconciled tip back; next claim continues from it)`
 					: ' (kept the work branch; next claim continues from its tip)';
-			console.log(`Requeued '${slug}' to backlog for re-claiming.${how}`);
+			const saved =
+				result.crashedRunSave?.kind === 'saved'
+					? ` Saved the crashed run's local work from ${result.crashedRunSave.dir} to ${result.crashedRunSave.branch} first.`
+					: '';
+			console.log(
+				`Requeued '${slug}' to backlog for re-claiming.${how}${saved}`,
+			);
 		});
 
 	// `promote [item]` (spec `staging-pool-position-gate-and-trust-model`, tasks
@@ -4450,7 +4925,13 @@ export function buildProgram(): Command {
 			'--sessions-dir <dir>',
 			'HOST-ONLY root folder under which the pi session file is generated',
 		)
+		.addOption(phaseOption())
+		.addOption(handoffDirOptions()[0])
+		.addOption(handoffDirOptions()[1])
+		.addOption(agentResultOptions()[0])
+		.addOption(agentResultOptions()[1])
 		.action(async (rawNumber: string, flags: IntakeFlags) => {
+			enterCliPhase(flags.phase);
 			const issueNumber = Number(rawNumber);
 			if (
 				rawNumber.trim() === '' ||
@@ -4555,9 +5036,10 @@ export function buildProgram(): Command {
 				);
 				process.exit(1);
 			}
-			const result = await performIntake({
+			const intakeOptions: PerformIntakeOptions = {
 				issueNumber,
 				cwd,
+				phase: flags.phase,
 				arbiter: flags.arbiter ?? config.defaultArbiter,
 				integration: modes,
 				// The resolved cross-job CAS-retry cap (config `mergeRetries`). `intake`
@@ -4597,7 +5079,13 @@ export function buildProgram(): Command {
 				// decision/review AGENT launches); absent ⇒ ambient.
 				identity: config.identity,
 				note: (message) => console.error(`>> ${message}`),
-			});
+			};
+			// CI PHASE MODE (task `ci-split-intake`): `--phase` runs ONE job of the
+			// split item workflow for `issue:<N>`, on the SAME intake pipeline.
+			if (flags.phase !== undefined) {
+				await runIntakePhaseAndExit(flags, intakeOptions);
+			}
+			const result = await performIntake(intakeOptions);
 			if (result.exitCode !== 0) {
 				console.error(`error: ${result.message}`);
 			} else {
@@ -4617,7 +5105,7 @@ export function buildProgram(): Command {
 		.command('close-merged-issues')
 		.helpGroup(ADVANCED_GROUP)
 		.description(
-			'Close source issues whose work has landed on main (CI capability E, spec runner-in-ci). Resolves each closing issue from the work/ tree (resolveClosingIssue: a lone task closes its own `issue:`; a fanned task reaches the number via `task.spec: → spec issue:`), runs the existing "spec complete?" query for the spec case (closes ONLY when ALL its spec:<slug> tasks are in work/done/), and closes via the IssueProvider seam (atomic comment+close; NO direct gh). Re-implements NONE of the resolution/query/close — it WIRES them. Invoked by the emitted close-job workflow on a merge to main; DEGRADES (never crashes) on a missing/unauthenticated gh.',
+			'Close source issues whose work has landed on main (CI capability E, spec runner-in-ci). Resolves each closing issue from the work/ tree (resolveClosingIssue: a lone task closes its own `issue:`; a fanned task reaches the number via `task.spec: → spec issue:`), runs the existing "spec complete?" query for the spec case (closes ONLY when ALL its spec:<slug> tasks are in work/done/), and closes via the IssueProvider seam (atomic comment+close; NO direct gh). Re-implements NONE of the resolution/query/close — it WIRES them. Invoked by the emitted close-job workflow on a merge to main and hourly (a land the CI pushes itself triggers no workflow); an issue that is already closed is skipped (`already-closed`), not closed again. DEGRADES (never crashes) on a missing/unauthenticated gh.',
 		)
 		.option(
 			'--cwd <dir>',
@@ -4640,6 +5128,10 @@ export function buildProgram(): Command {
 						console.error(
 							`>> closed issue #${c.issueNumber} (${c.via} ${c.slug}).`,
 						);
+					} else if (c.decision === 'already-closed') {
+						console.error(
+							`>> issue #${c.issueNumber} (${c.via} ${c.slug}) already closed.`,
+						);
 					} else if (c.decision === 'close-failed') {
 						console.error(
 							`>> issue #${c.issueNumber} (${c.via} ${c.slug}) NOT closed: ${c.reason}`,
@@ -4659,6 +5151,56 @@ export function buildProgram(): Command {
 			process.exit(0);
 		});
 
+	// `surface-merge-questions` (task `wire-merge-questions-into-the-advance-tick`,
+	// decision 5): the no-agent entry point the generated `advance-lifecycle`
+	// workflow's `surface-merge-questions` job runs. It asks, in the current
+	// checkout of `main`, a merge question for every unmerged `work/task-<slug>`
+	// branch with no open PR and no live build, and publishes the questions to
+	// `<arbiter>/main`. Gated by `mergeQuestions` (`off` does nothing). The laptop
+	// bare `advance` runs the SAME pass before it selects.
+	program
+		.command('surface-merge-questions')
+		.helpGroup(ADVANCED_GROUP)
+		.description(
+			'Ask a merge question (a `kind: merge` sidecar entry, answered `merge | hold | drop`) for every unmerged `work/task-<slug>` branch on the arbiter that has no open PR (GitHub), whose task rests in tasks/ready/ or tasks/backlog/, whose lock is free or kept by its finished propose build, and whose tip carries the done-move; then publish the questions to <arbiter>/main (never --force). Fetches the arbiter first. Runs no agent. Gated by `mergeQuestions` (off|ask, default ask; DORFL_MERGE_QUESTIONS > dorfl.json > global): `off` surfaces nothing. The CI `advance-lifecycle` workflow runs it as its `surface-merge-questions` job; the bare laptop `advance` runs the same pass before it selects.',
+		)
+		.option(
+			'--arbiter <name>',
+			'the arbiter remote whose work branches to ask about (default: the configured defaultArbiter)',
+		)
+		.option('--gh-bin <bin>', 'the gh CLI binary (default: gh on PATH)')
+		.option('-c, --config <path>', 'config file path', defaultConfigPath())
+		.action(
+			async (flags: {arbiter?: string; ghBin?: string; config: string}) => {
+				const cwd = process.cwd();
+				const {global, override} = loadGlobalAndOverride(flags.config);
+				let config;
+				try {
+					config = resolveRepoConfig({repoPath: cwd, global, override}).config;
+				} catch (err) {
+					console.error(
+						`error: ${err instanceof Error ? err.message : String(err)}`,
+					);
+					process.exit(1);
+				}
+				const pass = await runMergeQuestionTick({
+					cwd,
+					arbiter: flags.arbiter ?? config.defaultArbiter,
+					mergeQuestions: config.mergeQuestions,
+					ghBin: flags.ghBin,
+					env: identityEnv(config.identity, process.env),
+					note: (message) => console.error(`>> ${message}`),
+				});
+				// A failed pass (fetch, lock read, or the GitHub open-PR listing) is
+				// an `error:` line and a non-zero exit, so a CI job cannot go green
+				// while asking about no branch.
+				console.error(
+					pass.failed ? `error: ${pass.message}` : `>> ${pass.message}`,
+				);
+				process.exit(pass.failed ? 1 : 0);
+			},
+		);
+
 	// The REGISTRY command group (ADR §1): the registered set of targets IS the
 	// hub-mirror set on disk. `remote add --local` absorbs the old `arbiter init`;
 	// `arbiter status` is folded into `status`. There is no standalone `arbiter`
@@ -4819,7 +5361,7 @@ export function buildProgram(): Command {
 		.command('install-ci')
 		.helpGroup(ADVANCED_GROUP)
 		.description(
-			'Scaffold the CI auth/setup foundation (a one-time, human-run SCAFFOLDER): write the shared composite setup action (`dorfl-setup`) + provider auth (models.json default, or auth.json + GH_PAT + OAuth refresh) and set the provider secrets via the GitHub seam. Interactive wizard, or `--config <file>` for a non-interactive reproduction; `--export-config` round-trips the config; `--fake` writes to `.fake/` (never `.github/`) and sets NO real secret (a snapshot dry-run).',
+			'Scaffold the CI auth/setup foundation (a one-time, human-run SCAFFOLDER): write the shared composite setup action (`dorfl-setup`) + provider auth (a generated models.json; put rotating credentials such as OAuth behind a proxy provider `baseUrl`) and set the provider secrets via the GitHub seam. Interactive wizard, or `--config <file>` for a non-interactive reproduction; `--export-config` round-trips the config; `--fake` writes to `.fake/` (never `.github/`) and sets NO real secret (a snapshot dry-run).',
 		)
 		.option(
 			'--config <file>',
@@ -4938,6 +5480,26 @@ export function buildProgram(): Command {
 			console.log(formatSkillsAddReport(result, flags.local === true));
 		});
 
+	// Decision 9 (task `ci-split-warn-single-job-workflows`): warn before an
+	// agent-spawning verb runs in an old single-job CI workflow (GitHub Actions,
+	// no `--phase`, a credential persisted in the checkout's git config).
+	// Warn-only: the action still runs.
+	program.hook('preAction', (_program, actionCommand) => {
+		if (actionCommand.parent !== program) {
+			return;
+		}
+		const phase = (actionCommand.opts() as {phase?: Phase}).phase;
+		const warning = singleJobWarning({
+			verb: actionCommand.name(),
+			phase,
+			env: process.env,
+			cwd: process.cwd(),
+		});
+		if (warning !== undefined) {
+			console.error(warning);
+		}
+	});
+
 	return program;
 }