dorfl 0.14.2 → 0.15.0

package/src/close-job-template.ts

@@ -14,6 +14,15 @@
  *     a normal (non-fork-restricted) `GITHUB_TOKEN` that can actually close issues
  *     — whereas a `pull_request` event from a FORK gets a read-only token and
  *     cannot close. (See the `## Decisions` block in the task.)
+ *   - PLUS an hourly `schedule:` (the same `'0 * * * *'` cron the generated
+ *     `advance-lifecycle` uses) and `workflow_dispatch:` (task
+ *     `close-job-also-runs-on-a-schedule`): GitHub starts NO workflow for a push
+ *     made with a job's `GITHUB_TOKEN`, so a land the CI apply job pushes itself
+ *     (merge mode, an answered `merge` question, a tree-less publish) never fires
+ *     the `push` trigger. `close-merged-issues` keeps no state (every run
+ *     re-derives from `main` what is complete) and skips an issue that is already
+ *     closed, so the timed run is safe and quiet; it catches those lands within
+ *     the hour. The `push` trigger stays so a human-merged PR closes at once.
  *   - The job INVOKES the close machinery via `dorfl close-merged-issues`,
  *     which CONSUMES the UNCHANGED engine pieces: the resolution
  *     (`resolveClosingIssue`), the "spec complete?" query (`prd-complete-query`,
@@ -33,15 +42,19 @@
  * the test generates this artifact under `--fake` and asserts every invariant.
  */
 
+import {ACTION_PINS, pinnedUses} from './install-ci-action-pins.js';
 import type {ResolvedCIConfig} from './install-ci-core.js';
-import {shouldDropCheckoutCredentials} from './install-ci-core.js';
+import {
+	WRITER_SETUP_ACTION_USES,
+	shouldDropCheckoutCredentials,
+} from './install-ci-core.js';
 
 /** The capability id (the registry key + the emitted workflow file stem). */
 export const CLOSE_JOB_CAPABILITY_ID = 'close-job';
 
 /** The wizard-facing label for the close-job capability. */
 export const CLOSE_JOB_CAPABILITY_LABEL =
-	'Close issues when their work lands (the close-job: on a merge to main)';
+	'Close issues when their work lands (the close-job: on a merge to main, and hourly)';
 
 /** The repo-relative path (under the output base) of the emitted workflow. */
 export const CLOSE_JOB_WORKFLOW_PATH = 'workflows/close-job.yml';
@@ -62,8 +75,7 @@ export function generateCloseJobWorkflow(config: ResolvedCIConfig): string {
 		? `
           # Public repository: every git read works without a token, and this
           # job cannot push, so do not leave the token in .git/config for later
-          # steps (the setup action, including any project-setup hook, and
-          # close-merged-issues) to read.
+          # steps (the setup action and close-merged-issues) to read.
           persist-credentials: false`
 		: '';
 	return `\
@@ -78,6 +90,13 @@ export function generateCloseJobWorkflow(config: ResolvedCIConfig): string {
 #     actually CLOSE issues — a \`pull_request\` event from a FORK gets a read-only
 #     token and could not close (a real limitation we deliberately avoid).
 #
+# PLUS an HOURLY schedule (and workflow_dispatch for a manual catch-up). GitHub
+# starts NO workflow for a push made with a job's GITHUB_TOKEN, so a land the CI
+# pushes itself (merge mode, an answered \`merge\` question, a tree-less publish)
+# never fires the push trigger above. The schedule closes those issues within the
+# hour. It is safe to repeat: \`close-merged-issues\` keeps no state (every run
+# re-derives from main what is complete) and skips an issue already closed.
+#
 # WHAT IT DOES — \`dorfl close-merged-issues\` resolves which source issue(s)
 # the landed work closes and closes them. CI owns ONLY this job + the trigger; the
 # command CONSUMES the engine's UNCHANGED pieces and re-implements none of them:
@@ -106,6 +125,12 @@ on:
   push:
     branches:
       - main
+  # Hourly (the same cadence as advance-lifecycle): a land the CI pushes with its
+  # GITHUB_TOKEN starts no workflow, so this catches the issues those lands close.
+  schedule:
+    - cron: '0 * * * *'
+  # Manual catch-up.
+  workflow_dispatch:
 
 # Serialise overlapping close ticks on main; the close-job mutates only the ISSUE
 # (not the main-CAS), so this just avoids redundant concurrent passes.
@@ -113,20 +138,25 @@ concurrency:
   group: close-job-\${{ github.ref }}
   cancel-in-progress: false
 
-# NO \`workflows\` permission: the running job can NEVER edit the workflows tree
-# under .github (US #9). It needs only to READ the work/ tree and CLOSE issues.
-permissions:
-  contents: read
-  issues: write
+# Nothing at workflow level: the job grants its own scopes. NO \`workflows\`
+# permission: the running job can NEVER edit the workflows tree under .github
+# (US #9).
+permissions: {}
 
 jobs:
   close-merged-issues:
     runs-on: ubuntu-latest
+    # It needs only to READ the work/ tree and CLOSE issues.
+    permissions:
+      contents: read
+      issues: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: ${pinnedUses(ACTION_PINS.checkout)}
         with:
           fetch-depth: 0${checkoutCredentials}
-      - uses: ./.github/actions/dorfl-setup
+      # The writer role (Node and dorfl only): this job runs no agent, so it
+      # installs no harness, no provider key and no project-setup hook.
+      - uses: ${WRITER_SETUP_ACTION_USES}
       - name: close issues whose work has landed on main
         # In-place in this checkout (no --isolated/--remote): the CI container IS
         # the isolation. Resolves the closing issue(s) from the work/ tree, runs
@@ -188,11 +218,18 @@ export function validateCloseJobWorkflow(text: string): CloseJobValidation {
 		operative,
 	), 'must NOT use the `pull_request` trigger (a fork PR gets a read-only token ' +
 		'that cannot close; `push: [main]` is the chosen trigger).');
-	// And it must NOT be the build/task tick's cron/dispatch shape — the close-job
-	// is event-driven on a merge, not a scheduled drain.
-	require('no-cron-trigger', !/\bschedule:\s*[\s\S]*?-\s*cron:/.test(
+	// AND an hourly schedule + workflow_dispatch: GitHub starts no workflow for a
+	// push made with a job's GITHUB_TOKEN, so a land the CI pushes itself never
+	// fires the push trigger; the timed run closes those issues. Operative lines
+	// only: the header comment mentions the schedule.
+	require('trigger-cron', /\bschedule:\s*[\s\S]*?-\s*cron:/.test(
+		operative,
+	), 'must ALSO trigger on a cron schedule (`on.schedule[].cron`): a land the ' +
+		'CI pushes with its GITHUB_TOKEN starts no workflow, so only the timed run ' +
+		'closes its issue.');
+	require('trigger-workflow-dispatch', /\bworkflow_dispatch:/.test(
 		operative,
-	), 'the close-job is merge-triggered, NOT a cron drain (no `on.schedule.cron`).');
+	), 'must trigger on `workflow_dispatch` (manual catch-up).');
 	require('no-answer-loop-push-trigger', !/work\/questions\//.test(
 		text,
 	), 'the close-job must NOT carry the `push work/questions/**` (answer-loop) ' +

package/src/close-job.ts

@@ -10,8 +10,9 @@
  *     fanned task reaches the number via `task.spec: → work/specs/<spec>.md spec
  *     issue:`, and `spec:` WINS on a (hand-edited) conflict;
  *   - the QUERY — {@link isSpecComplete} (`spec-complete.ts`, task
- *     `prd-complete-query`, done): a spec is COMPLETE iff ≥1 `spec:<slug>` task AND
- *     all such tasks are in `work/done/`;
+ *     `prd-complete-query`, done): a spec is COMPLETE iff ≥1 `spec:<slug>` task is
+ *     in `work/tasks/done/` AND every other one is in `work/tasks/cancelled/` (a
+ *     task staged in backlog, ready or in progress keeps it open);
  *   - the CLOSE — {@link IssueProvider.closeIssue} (`issue-provider.ts`, the atomic
  *     comment+close seam intake already uses): NO direct `gh` in this core; any
  *     informational comment rides the SAME close call (never the PR seam
@@ -25,13 +26,27 @@
  *     `spec:<slug>` tasks are in `work/done/` (reason `completed`).
  *
  * A spec whose query is NOT yet complete is left OPEN (the final fanned task's
- * merge tick closes it). A lone task still outside `work/done/` is skipped. The
+ * merge tick closes it). A lone task still outside `work/done/` is skipped.
+ *
+ * CANCELLED work never closes an issue (task
+ * `spec-complete-counts-staged-and-cancelled-tasks`): a spec whose tasks are ALL
+ * cancelled, and a lone task that was cancelled, are left OPEN with decision
+ * `cancelled`, not closed as `completed` (nothing was delivered) and not closed
+ * as `not planned` either: abandoning an issue is a human's call (drop the spec,
+ * close the issue by hand), not something a merge-to-main job infers. The
  * close DEGRADES (never throws) on a missing/unauthenticated provider, exactly
  * like intake's bounce close — the run reports the real cause and stays exit-0.
  *
+ * An issue the provider already reports CLOSED is skipped with decision
+ * `already-closed` (no close call, no comment, not counted in `closed`): the
+ * workflow also runs HOURLY, so without this every pass would re-close and
+ * re-report issues closed long ago.
+ *
  * This is the JOB the close-job WORKFLOW (capability E) invokes via
  * `dorfl close-merged-issues`; the workflow is triggered on a merge to
- * `main` (`push: {branches: [main]}`). The driver itself is provider-pluggable
+ * `main` (`push: {branches: [main]}`) AND on an hourly `schedule:`, because a
+ * land the CI pushes with its `GITHUB_TOKEN` starts no workflow. Every pass
+ * re-derives everything from the `work/` tree (no state), so repeating is safe. The driver itself is provider-pluggable
  * (it takes an {@link IssueProvider}) and reads only the `work/` tree.
  */
 
@@ -64,6 +79,8 @@ export type CloseDecision =
 	| 'closed' // the issue was closed via the provider seam
 	| 'not-complete' // a spec whose query says it is not yet complete → left open
 	| 'not-landed' // a lone task not yet in work/done/ → left open
+	| 'cancelled' // a spec whose tasks are ALL cancelled, or a cancelled lone task → left open
+	| 'already-closed' // closure condition held but the issue is already closed → no close call
 	| 'close-failed'; // closure condition held but the provider close degraded
 
 /** One candidate the close-job considered, with the decision it reached. */
@@ -199,11 +216,15 @@ function resolveCandidates(repoPath: string): {
 	return [...specCandidates, ...taskCandidates];
 }
 
-/** True iff the lone task with this slug resides in `work/done/`. */
-function loneTaskLanded(repoPath: string, taskSlug: string): boolean {
-	for (const file of listMarkdown(repoPath, 'done')) {
+/** True iff the lone task with this slug resides in `work/<folder>/`. */
+function loneTaskIn(
+	repoPath: string,
+	taskSlug: string,
+	folder: 'done' | 'cancelled',
+): boolean {
+	for (const file of listMarkdown(repoPath, folder)) {
 		const fm = parseFrontmatter(
-			readFileSync(join(repoPath, workItemRel('done', file)), 'utf8'),
+			readFileSync(join(repoPath, workItemRel(folder, file)), 'utf8'),
 		);
 		const slug = fm.slug ?? basename(file, '.md');
 		if (slug === taskSlug) {
@@ -220,6 +241,32 @@ function closeComment(via: 'issue' | 'spec', slug: string): string {
 		: `Closed by dorfl: the task \`${slug}\` has landed in \`work/done/\`.`;
 }
 
+/**
+ * True iff the provider reports the issue as already `closed` (via the existing
+ * {@link IssueProvider.getIssue} read, whose `state` is lower-cased). A read that
+ * FAILS (the GitHub adapter throws on a `gh` failure) or reports no state answers
+ * `false`, so the pass falls through to the close attempt exactly as before: the
+ * close then either succeeds or reports `close-failed` with the real cause. A
+ * state read must never be the reason an issue stays open.
+ */
+async function isAlreadyClosed(
+	issueProvider: IssueProvider,
+	repoPath: string,
+	issueNumber: number,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<boolean> {
+	try {
+		const issue = await issueProvider.getIssue({
+			cwd: repoPath,
+			issueNumber,
+			env,
+		});
+		return issue.state === 'closed';
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Run the close-job over a repo's `work/` tree: resolve the closure candidates,
  * apply the per-kind closure condition (a landed lone task; a spec whose
@@ -243,11 +290,14 @@ export async function runCloseJob(
 		let shouldClose: boolean;
 		let notReady: CloseDecision;
 		if (cand.via === 'spec') {
-			shouldClose = isSpecComplete({repoPath, slug: cand.slug}).complete;
-			notReady = 'not-complete';
+			const query = isSpecComplete({repoPath, slug: cand.slug});
+			shouldClose = query.complete;
+			notReady = query.allCancelled ? 'cancelled' : 'not-complete';
 		} else {
-			shouldClose = loneTaskLanded(repoPath, cand.slug);
-			notReady = 'not-landed';
+			shouldClose = loneTaskIn(repoPath, cand.slug, 'done');
+			notReady = loneTaskIn(repoPath, cand.slug, 'cancelled')
+				? 'cancelled'
+				: 'not-landed';
 		}
 
 		if (!shouldClose) {
@@ -260,6 +310,21 @@ export async function runCloseJob(
 			continue;
 		}
 
+		// ALREADY CLOSED? The close-job also runs hourly (task
+		// `close-job-also-runs-on-a-schedule`), so most passes meet issues an
+		// earlier pass (or a human) already closed. Read the state through the
+		// provider seam (NO direct `gh`) and skip those: no second close, no second
+		// comment, not counted in `closed`.
+		if (await isAlreadyClosed(issueProvider, repoPath, cand.issueNumber, env)) {
+			candidates.push({
+				issueNumber: cand.issueNumber,
+				via: cand.via,
+				slug: cand.slug,
+				decision: 'already-closed',
+			});
+			continue;
+		}
+
 		// CLOSE via the provider seam (NO direct `gh`): comment + reason + close in
 		// ONE atomic call, exactly the seam intake's bounce uses.
 		const result = await issueProvider.closeIssue({

package/src/complete.ts

@@ -11,7 +11,7 @@ import {
 	PR_TITLE_MAX,
 } from './integration-core.js';
 import {ledgerWrite} from './ledger-write.js';
-import {releaseItemLock} from './item-lock.js';
+import {markLockKeptForProposePr, releaseItemLock} from './item-lock.js';
 import {workBranchRef, parseWorkBranchRef} from './slug-namespace.js';
 import {isProvablyMergedForReap} from './gc.js';
 import type {SidecarType} from './sidecar.js';
@@ -1272,6 +1272,24 @@ async function releaseClaimLockAfterDurableMove(
 				'the lock is released by the next claim (or now, with `dorfl status ' +
 				'--reconcile-locks`).',
 		);
+		// Say so ON the lock (task `wire-merge-questions-into-the-advance-tick`,
+		// decision 4): the kept lock no longer covers a live build, so the
+		// merge-question surfacer may ask about the branch (when no PR is open) and
+		// an answered `merge` may take the lock over. Best-effort: an unmarked kept
+		// lock only means the branch is treated as a live build (never surfaced).
+		try {
+			const marked = await markLockKeptForProposePr({
+				item: `task:${slug}`,
+				cwd,
+				arbiter,
+				env,
+			});
+			if (marked.outcome === 'lost' || marked.outcome === 'error') {
+				note(marked.message);
+			}
+		} catch {
+			// Never fail a completed propose on the marker.
+		}
 		return;
 	}
 	try {

package/src/config.ts

@@ -81,31 +81,28 @@ export type SpecsLandIn = 'proposed' | 'ready';
 export type ObservationTriage = 'off' | 'ask' | 'auto';
 
 /**
- * **The `mergeQuestions` gate axis** — the 3-state member of the question-
+ * **The `mergeQuestions` gate axis**: the 2-state member of the question-
  * surfacing gate family that governs the MERGE-QUESTION surfacer (spec
  * `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
- * `merge-questions-gate-axis`). MIRRORS `observationTriage`'s shape
- * (`off | ask | auto`) but is a SEPARATE axis — "should this built work merge?"
- * is materially more consequential than "is this observation worth promoting?",
- * so a merge-question must NEVER ride `observationTriage` and must NOT default
- * `off` (a silently-dropped merge-question means finished, pushed work never
- * lands). The states:
+ * `merge-questions-gate-axis`). A SEPARATE axis from `observationTriage`:
+ * "should this built work merge?" is materially more consequential than "is
+ * this observation worth promoting?", so a merge-question must NEVER ride
+ * `observationTriage` and must NOT default `off` (a silently-dropped
+ * merge-question means finished, pushed work never lands). The states:
  *   - `off` ⇒ the merge-question surfacer is not invoked (only correct for a
  *     repo that lands by some other means);
- *   - `ask` (DEFAULT) ⇒ the surfacer enumerates unmerged `work/*` branches +
- *     emits a merge-question sidecar; a human's plain `merge | hold | drop`
- *     answer is required before the land. The conservative default that honours
- *     propose semantics and never silently drops pushed work;
- *   - `auto` ⇒ the runner self-supplies the `merge` answer without surfacing
- *     and lands through the SAME deterministic answer-driven runner-action
- *     dispatch + apply-time re-verify (the merge-mode-like fast path). Does NOT
- *     invoke the agentic decider — a merge-land is never an agent decision.
- * Resolved through the SAME precedence chain as the other gates (flag > env >
- * per-repo > global > default `ask`). The exact name + default + shape were
- * answered in this task's Applied answers 2026-06-26 (q1/q2/q3) + SPEC sidecar
- * Q3.
+ *   - `ask` (DEFAULT) ⇒ the surfacer enumerates unmerged `work/*` branches with
+ *     no open PR + emits a merge-question sidecar; a human's plain
+ *     `merge | hold | drop` answer is required before the land. The
+ *     conservative default that honours propose semantics and never silently
+ *     drops pushed work.
+ * There is NO `auto` (task `wire-merge-questions-into-the-advance-tick`,
+ * decision 3): unattended landing is what merge mode (`integration: merge`) is
+ * for. Resolved through the precedence chain env > per-repo > global > default
+ * `ask` (there is no CLI flag). The surfacer runs in the laptop bare `advance`
+ * tick and in the CI `surface-merge-questions` job (`merge-question-tick.ts`).
  */
-export type MergeQuestions = 'off' | 'ask' | 'auto';
+export type MergeQuestions = 'off' | 'ask';
 
 /**
  * Which harness adapter (ADR §5) launches a job's agent and reports its
@@ -229,23 +226,20 @@ export interface Config {
 	 */
 	observationTriage: ObservationTriage;
 	/**
-	 * Per-repo policy governing the MERGE-QUESTION SURFACER — the 3-state member
+	 * Per-repo policy governing the MERGE-QUESTION SURFACER, the 2-state member
 	 * of the question-surfacing gate family (spec
 	 * `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
-	 * `merge-questions-gate-axis`). MIRRORS `observationTriage`'s SHAPE
-	 * (`off | ask | auto`) but is a SEPARATE axis with a DIFFERENT default —
-	 * `observationTriage` defaults `off` (a dropped observation is safely
-	 * ignorable), `mergeQuestions` defaults `ask` (a dropped merge-question means
-	 * pushed work never lands). `off` ⇒ the surfacer is NOT invoked (only for a
-	 * repo that lands by some other means); `ask` (default) ⇒ the surfacer
-	 * enumerates unmerged `work/*` branches and emits a merge-question sidecar a
-	 * human answers; `auto` ⇒ the runner self-supplies the `merge` answer without
-	 * surfacing and lands via the SAME deterministic answer-driven runner-action
-	 * dispatch + apply-time re-verify (the merge-mode-like fast path; NOT the
-	 * agentic decider). Resolved like `observationTriage`/`integration`: flag
-	 * (`--merge-questions`) > `DORFL_MERGE_QUESTIONS` env > per-repo > global >
-	 * default `ask`. Gates the SURFACE phase of the merge-question loop only;
-	 * APPLY (consume a committed merge-answer) stays ALWAYS allowed (the
+	 * `merge-questions-gate-axis`). A SEPARATE axis from `observationTriage` with
+	 * a DIFFERENT default: `observationTriage` defaults `off` (a dropped
+	 * observation is safely ignorable), `mergeQuestions` defaults `ask` (a
+	 * dropped merge-question means pushed work never lands). `off` ⇒ the
+	 * surfacer is NOT invoked (only for a repo that lands by some other means);
+	 * `ask` (default) ⇒ the surfacer enumerates unmerged `work/*` branches with no
+	 * open PR and emits a merge-question sidecar a human answers. No `auto` (task
+	 * `wire-merge-questions-into-the-advance-tick`, decision 3: unattended landing
+	 * is merge mode's job). Resolved `DORFL_MERGE_QUESTIONS` env > per-repo >
+	 * global > default `ask`. Gates the SURFACE phase of the merge-question loop
+	 * only; APPLY (consume a committed merge-answer) stays ALWAYS allowed (the
 	 * create-vs-consume invariant the gate family obeys, ADR
 	 * `ci-config-policy-and-gate-family` §4).
 	 */
@@ -746,8 +740,10 @@ export interface Config {
 	 * INTEGRATES in ONE process; across separate CI jobs the CAS loop IS the queue,
 	 * and this cap is what determines how wide a matrix burst converges before any
 	 * spurious bounce. A wide-matrix CI raises it; the default stays modest. Race-1
-	 * safety is unchanged (a lost CAS costs only a re-rebase + re-gate retry, never a
-	 * `--force`, never a both-land-broken) — scaling the cap only changes WHEN a
+	 * safety is unchanged (a lost CAS costs only a re-rebase and a retried push, never
+	 * a `--force`, never a both-land-broken; it does NOT re-run the gate, and the CI
+	 * apply phase reports a land whose tree differs from the gated tree, ADR
+	 * `ci-agent-job-holds-no-write-token` decision 2) — scaling the cap only changes WHEN a
 	 * genuinely-stuck loser gives up. Resolved per-repo like `freshWorktreeGate`:
 	 * flag (`--merge-retries`) > env (`DORFL_MERGE_RETRIES`) > per-repo > global >
 	 * default. The default matches `integration-core.ts`'s built-in fallback (1000 —
@@ -762,13 +758,14 @@ export interface Config {
 	 * **Per-repo OPT-IN strictness layered on the OQ6 stale-approval default**
 	 * (spec `land-time-reverify-and-parallel-merge-ceiling`, sidecar OQ6 / task
 	 * `strict-merge-approval-gate`). Controls how the apply rung treats a prior
-	 * merge-answer when the merge-base CHANGED between the human's answer and
-	 * the apply step. The default (`false`) honours the prior answer and lands
-	 * when the rebased tip re-verifies GREEN — a green re-verify is trusted as
-	 * sufficient (the cheap fast-path). `true` re-surfaces the merge-question
-	 * (clears the answer back to no-answer and re-authors the question on
-	 * `main`/runner under the `advancing` lock — no branch-side mutation)
-	 * instead of auto-landing on a merge-base change, even on a green re-verify
+	 * merge-answer when `main`'s code (outside `work/`) moved since the question
+	 * was asked (the `askedAtMain` the question records). The default (`false`)
+	 * honours the prior answer and lands when the rebased tip re-verifies GREEN
+	 * (a green re-verify is trusted as sufficient: the cheap fast-path). `true`
+	 * re-surfaces the merge-question (appends a follow-up asked against the
+	 * current `main`, under the `advancing` lock, before any checkout or
+	 * rebase: no branch-side mutation) instead of auto-landing when `main`
+	 * moved, even on a green re-verify
 	 * — the host-agnostic analogue of GitHub's "dismiss stale approvals when
 	 * the base changes". Story #16's RED-re-verify refusal is UNCHANGED and
 	 * independent of this flag.
@@ -905,10 +902,8 @@ export const DEFAULT_CONFIG: Config = {
 	// a silently-dropped merge-question means finished, pushed work never lands —
 	// strictly more consequential than a dropped observation-promote prompt, so
 	// this gate axis is DELIBERATELY HIGHER than `observationTriage`'s `off`. A
-	// trusted-repo fast path opts into `auto` (runner self-supplies the `merge`
-	// answer + lands via the SAME deterministic apply-time re-verify); a repo that
-	// lands by some other means opts into `off`. Resolved per-repo through the
-	// SAME precedence chain (flag > env > per-repo > global > default).
+	// repo that lands by some other means opts into `off`. Resolved per-repo
+	// through the SAME precedence chain (env > per-repo > global > default).
 	mergeQuestions: 'ask',
 	// DECLARED blocked work is calm by default (`false`): the `needsAnswers`-blocked
 	// pool is dropped from the auto-pick selection, so `advance` does NOT proactively

package/src/continue-branch.ts

@@ -165,11 +165,91 @@ export function branchAheadOfArbiter(options: {
 	return branchAheadOf(cwd, branchRef, mainRef, env);
 }
 
+/**
+ * Why a continue rebase did not apply (task
+ * `a-failed-rebase-reports-its-real-cause`). Either way the rebase was
+ * `--abort`ed (NEVER auto-resolved) and the kept branch is back on its
+ * un-rebased tip; the two kinds differ only in what the report says:
+ *
+ *  - `conflict`: git stopped on conflicting paths (`paths`, the unmerged index
+ *    entries; empty only when git printed a `CONFLICT (...)` line but left no
+ *    unmerged entry). A genuine content conflict for a human to resolve.
+ *  - `failed`: the rebase exited non-zero WITHOUT a conflict (a missing
+ *    committer identity, an unresolvable `main`, a dirty tree, a hook, ...).
+ *    Calling it "conflicted" hid the real cause (observation
+ *    `ci-answered-merge-reports-a-conflict-a-plain-rebase-does-not-have`).
+ *
+ * `onto` is the sha `mainRef` resolved to when the rebase ran (`''` when it did
+ * not resolve), and `output` is git's own report (stderr, then stdout),
+ * condensed to one line by {@link condenseGitOutput}.
+ */
+export type ContinueRebaseFailure =
+	| {kind: 'conflict'; onto: string; paths: string[]; output: string}
+	| {kind: 'failed'; onto: string; output: string};
+
 /** The result of rebasing a continued branch onto the freshly-fetched main. */
-export interface ContinueRebaseResult {
-	/** `clean` — the rebase replayed onto main with no conflict. */
-	/** `conflict` — the rebase conflicted; it was `--abort`ed (never auto-resolved). */
-	kind: 'clean' | 'conflict';
+export type ContinueRebaseResult = {kind: 'clean'} | ContinueRebaseFailure;
+
+/** The longest git report a {@link ContinueRebaseFailure} carries. */
+const MAX_GIT_OUTPUT = 600;
+
+/**
+ * Condense git's multi-line report into one line for a reason / note: split
+ * on newlines and on the carriage returns of git's progress lines, drop blank
+ * and `hint:` lines, join the rest with ` / `, and cap the length.
+ */
+export function condenseGitOutput(text: string): string {
+	const lines = text
+		.split(/[\r\n]+/)
+		.map((l) => l.trim())
+		.filter((l) => l !== '' && !l.startsWith('hint:'));
+	const joined = lines.join(' / ');
+	return joined.length > MAX_GIT_OUTPUT
+		? `${joined.slice(0, MAX_GIT_OUTPUT)}...`
+		: joined;
+}
+
+/**
+ * What happened to a continue rebase, as the tail of a sentence that starts
+ * "rebasing `<branch>` onto current main ...". A conflict names its paths and
+ * the `main` sha; any other failure says so and quotes git. Both say the rebase
+ * was aborted, so the kept work is intact.
+ */
+export function describeContinueRebaseFailure(
+	failure: ContinueRebaseFailure,
+): string {
+	const onto = failure.onto === '' ? 'an unresolved main' : failure.onto;
+	if (failure.kind === 'conflict') {
+		const on =
+			failure.paths.length > 0 ? ` on ${failure.paths.join(', ')}` : '';
+		return (
+			`(${onto}) conflicted${on} (aborted, never auto-resolved)` +
+			(failure.paths.length > 0 || failure.output === ''
+				? ''
+				: `; git: ${failure.output}`)
+		);
+	}
+	return (
+		`(${onto}) failed without a conflict (aborted); git: ` +
+		(failure.output === '' ? '(no output)' : failure.output)
+	);
+}
+
+/**
+ * The whole sentence for a continue rebase that did not apply: "rebasing
+ * `<branch>` onto current main (<sha>) conflicted on <paths> ..." or "... failed
+ * without a conflict (aborted); git: <report>". `failure` is optional only so a
+ * caller holding just the legacy boolean still gets a sentence.
+ */
+export function continueRebaseSentence(
+	branch: string,
+	failure: ContinueRebaseFailure | undefined,
+): string {
+	const tail =
+		failure === undefined
+			? 'did not apply (aborted, never auto-resolved)'
+			: describeContinueRebaseFailure(failure);
+	return `rebasing \`${branch}\` onto current main ${tail}`;
 }
 
 /**
@@ -188,10 +268,13 @@ export interface ContinueRebaseResult {
  * rename/rename ledger conflict that inheritance caused) is deleted. The ONLY
  * commits replayed are the agent's own wip / `→done` commits.
  *
- * A CLEAN rebase returns `{kind: 'clean'}`; a CONFLICTING rebase (a GENUINE code
- * conflict) is `--abort`ed (NEVER auto-resolved) and returns `{kind: 'conflict'}`
- * so the caller can route the item to needs-attention via the §10 path. Must be
- * called while HEAD is the continued branch.
+ * A CLEAN rebase returns `{kind: 'clean'}`. Any other outcome is `--abort`ed
+ * (NEVER auto-resolved) and returns a {@link ContinueRebaseFailure} carrying the
+ * `main` sha rebased onto and git's report: `conflict` (with the conflicting
+ * paths) when git stopped on a GENUINE conflict, `failed` for every other
+ * non-zero exit. The caller routes either to needs-attention via the §10 path,
+ * naming the real cause ({@link describeContinueRebaseFailure}). Must be called
+ * while HEAD is the continued branch.
  *
  * RENAME-DETECTION-OFF (task `disable-rename-detection-on-continue-rebase`): the
  * rebase is invoked with `-c merge.directoryRenames=false` SCOPED to the
@@ -210,6 +293,11 @@ export function rebaseContinuedBranchOntoMain(
 	mainRef: string,
 	env: NodeJS.ProcessEnv | undefined,
 ): ContinueRebaseResult {
+	const onto = gitSoft(
+		['rev-parse', '--verify', '--quiet', `${mainRef}^{commit}`],
+		cwd,
+		env,
+	).stdout.trim();
 	const rebase = gitSoft(
 		['-c', 'merge.directoryRenames=false', 'rebase', mainRef],
 		cwd,
@@ -218,9 +306,20 @@ export function rebaseContinuedBranchOntoMain(
 	if (rebase.status === 0) {
 		return {kind: 'clean'};
 	}
-	// NEVER auto-resolve: abort back to a clean continued-branch tip.
+	// Read the conflicting paths (the unmerged index entries) BEFORE the abort
+	// clears them. git prints its `CONFLICT (...)` lines on stdout.
+	const paths = gitSoft(['diff', '--name-only', '--diff-filter=U'], cwd, env)
+		.stdout.split('\n')
+		.map((p) => p.trim())
+		.filter((p) => p !== '');
+	const output = condenseGitOutput([rebase.stderr, rebase.stdout].join('\n'));
+	// NEVER auto-resolve: abort back to a clean continued-branch tip. A failure
+	// that never started a rebase leaves nothing to abort; that exit is harmless.
 	gitSoft(['rebase', '--abort'], cwd, env);
-	return {kind: 'conflict'};
+	if (paths.length > 0 || /^CONFLICT \(/m.test(rebase.stdout)) {
+		return {kind: 'conflict', onto, paths, output};
+	}
+	return {kind: 'failed', onto, output};
 }
 
 /**
@@ -376,6 +475,9 @@ export function pushProposeBranchWithStaleLeaseRetry(options: {
 		// shape is the same create-only `--force-with-lease=<ref>:` form
 		// `item-lock.ts` uses for the CAS create.
 		const lease = observed === '' ? `${branch}:` : `${branch}:${observed}`;
+		// Write-seam implementation: reached only from the integrator, behind
+		// `ledgerWrite.applyCompleteTransition` (guard:
+		// `write-sites-through-seams.test.ts`).
 		const push = gitSoft(
 			['push', arbiter, `${branch}:${branch}`, `--force-with-lease=${lease}`],
 			cwd,
@@ -423,11 +525,12 @@ export type ContinuedPushResult =
 	/** The work branch landed on the arbiter (first try or after a clean re-rebase). */
 	| {kind: 'pushed'}
 	/**
-	 * A re-rebase onto the freshly-fetched main CONFLICTED on a retry; it was
-	 * `--abort`ed (NEVER auto-resolved). The caller routes the item to
-	 * needs-attention via the §10 path — the green work stays intact on the branch.
+	 * A re-rebase onto the freshly-fetched main did not apply on a retry (a
+	 * `conflict`, or a non-conflict `failed`); it was `--abort`ed (NEVER
+	 * auto-resolved). The caller routes the item to needs-attention via the §10
+	 * path, naming the cause; the green work stays intact on the branch.
 	 */
-	| {kind: 'conflict'};
+	| ContinueRebaseFailure;
 
 /**
  * Push the CONTINUED `work/<slug>` branch to the arbiter with
@@ -493,6 +596,8 @@ export function pushContinuedBranchWithStaleLeaseRetry(options: {
 	let attempt = 0;
 	// eslint-disable-next-line no-constant-condition
 	while (true) {
+		// Write-seam implementation: callers reach this through
+		// `refWrite.pushContinuedBranch` (guard: `write-sites-through-seams.test.ts`).
 		const push = gitSoft(
 			[
 				'push',
@@ -556,8 +661,8 @@ export function pushContinuedBranchWithStaleLeaseRetry(options: {
 		// merge). A CONFLICT is the EXISTING abort → needs-attention path — the retry
 		// handles ONLY the clean-rebase stale-lease case (never auto-resolves).
 		const rebase = rebaseContinuedBranchOntoMain(cwd, mainRef, env);
-		if (rebase.kind === 'conflict') {
-			return {kind: 'conflict'};
+		if (rebase.kind !== 'clean') {
+			return rebase;
 		}
 		// Loop: retry the push, now re-leased against the freshly-fetched remote tip.
 	}