dorfl 0.14.2 → 0.15.0

package/src/repo-mirror.ts

@@ -1,5 +1,6 @@
 import {existsSync, mkdirSync} from 'node:fs';
-import {dirname, join} from 'node:path';
+import {dirname, isAbsolute, join} from 'node:path';
+import {fileURLToPath} from 'node:url';
 import {git, run} from './git.js';
 import type {Config, PartialConfig} from './config.js';
 import type {ConfigOverrideMap} from './config-override.js';
@@ -35,6 +36,27 @@ export function readOriginUrl(
 	return url === '' ? undefined : url;
 }
 
+/**
+ * Is `mirrorPath` inside a `--reconcile-locks` write scope? `undefined` scope
+ * means every mirror (the explicit `--all-arbiters`); otherwise only the mirror
+ * whose `origin` URL hub-keys to `arbiterKey` (the SAME keying `gc` uses for its
+ * per-job arbiter scope). A mirror whose `origin` is unreadable is OUT of scope:
+ * the safe direction for a write. Shared by `status --reconcile-locks` (task
+ * `reconcile-locks-stays-within-the-current-arbiter`) and `scan
+ * --reconcile-locks` (task `status-no-arbiter-is-honoured`).
+ */
+export function mirrorInReconcileScope(
+	mirrorPath: string,
+	arbiterKey: string | undefined,
+	env: NodeJS.ProcessEnv | undefined,
+): boolean {
+	if (arbiterKey === undefined) {
+		return true;
+	}
+	const url = readOriginUrl(mirrorPath, env);
+	return url !== undefined && encodeRepoKey(url) === arbiterKey;
+}
+
 /**
  * The shared **hub-mirror primitive**: one bare mirror per repo under
  * `<workspacesDir>/repos/<key>.git`, re-fetched from the arbiter. Both the
@@ -409,3 +431,87 @@ export function fetchMirrorMainOrWarn(options: {
 		return false;
 	}
 }
+
+/**
+ * The mirror's `origin` URL when it names a LOCAL arbiter (a `file://` URL or an
+ * absolute path) that no longer exists on disk; `undefined` otherwise (a live
+ * local arbiter, a network remote, or an unreadable origin). Read-only.
+ */
+export function missingLocalOrigin(
+	mirrorPath: string,
+	env: NodeJS.ProcessEnv | undefined,
+): string | undefined {
+	const url = readOriginUrl(mirrorPath, env);
+	if (url === undefined) {
+		return undefined;
+	}
+	let localPath: string | undefined;
+	if (url.startsWith('file://')) {
+		try {
+			localPath = fileURLToPath(url);
+		} catch {
+			return undefined;
+		}
+	} else if (isAbsolute(url)) {
+		localPath = url;
+	}
+	return localPath !== undefined && !existsSync(localPath) ? url : undefined;
+}
+
+/** How many dead mirrors the summary line names before "and N more". */
+const DEAD_MIRROR_EXAMPLES = 3;
+
+/**
+ * The fetch-first refresh `status` and `scan` run over every registered mirror,
+ * with DEAD LOCAL ARBITERS summarised on ONE line instead of one warning each.
+ *
+ * A mirror whose origin is a local path that no longer exists (typically a
+ * throwaway `/tmp` arbiter, or a disk that is not mounted) cannot be fetched, and
+ * warning once per mirror buried the real output under hundreds of identical
+ * git errors. Such a mirror is NOT fetched and NOT removed: it is still read
+ * from its last-known state exactly like an offline mirror, because a read-only
+ * command must never delete state (an unmounted disk comes back). `flush()`
+ * then emits a single line with the count, a few examples and the removal
+ * command. Every other fetch failure keeps its own warning, as before.
+ */
+export function createMirrorRefresher(options: {
+	warn?: (message: string) => void;
+	env?: NodeJS.ProcessEnv;
+}): {refresh(mirrorPath: string): void; flush(): void} {
+	const dead: {mirrorPath: string; url: string}[] = [];
+	return {
+		refresh(mirrorPath: string): void {
+			const url = missingLocalOrigin(mirrorPath, options.env);
+			if (url !== undefined) {
+				dead.push({mirrorPath, url});
+				return;
+			}
+			fetchMirrorMainOrWarn({
+				mirrorPath,
+				warn: options.warn,
+				env: options.env,
+			});
+		},
+		flush(): void {
+			if (dead.length === 0) {
+				return;
+			}
+			const shown = dead
+				.slice(0, DEAD_MIRROR_EXAMPLES)
+				.map((d) => d.url)
+				.join(', ');
+			const more =
+				dead.length > DEAD_MIRROR_EXAMPLES
+					? ` and ${dead.length - DEAD_MIRROR_EXAMPLES} more`
+					: '';
+			const noun =
+				dead.length === 1
+					? '1 registered mirror points at a local arbiter that no longer exists'
+					: `${dead.length} registered mirrors point at a local arbiter that no longer exists`;
+			options.warn?.(
+				`${noun} (${shown}${more}); skipped the fetch and read their last-known ` +
+					'state. Remove each with `dorfl remote rm <origin-url>` if it is gone for good.',
+			);
+		},
+	};
+}

package/src/review-verdict.ts

@@ -124,7 +124,7 @@ export class ReviewParseError extends Error {}
  * shared the capped response with the verdict) rather than chasing a model flake.
  *
  * Detected at the harness seam: the adapter surfaces the last assistant turn's
- * `stop_reason` (null / `None` / `max_tokens` — the turn did not end naturally) and
+ * stop reason (pi's `length`, or a raw `max_tokens`: the turn hit the output cap) and
  * its `usage.output` token count; the gate throws this when a parse fails AND that
  * cap signal is present. When the adapter CANNOT see the signal (the null/shell
  * adapter, or a future adapter without usage telemetry), the parse still fails as a

package/src/run.ts

@@ -1,3 +1,4 @@
+import {continueRebaseSentence} from './continue-branch.js';
 import {type Config, resolvePromptGuidance} from './config.js';
 import {resolveRepoConfig} from './repo-config.js';
 import type {ConfigOverrideMap} from './config-override.js';
@@ -16,7 +17,7 @@ import {
 	type IsolationStrategy,
 } from './isolation.js';
 import {runConcurrent, createKeyedLock} from './concurrency.js';
-import type {Harness} from './harness.js';
+import type {CutOffTurn, Harness} from './harness.js';
 import {createHarness} from './pi-harness.js';
 import {generateSessionPath} from './session-path.js';
 import {
@@ -32,6 +33,7 @@ import {
 	isWorkBranchDiffEmpty,
 	emptyDiffStopReason,
 	emptyDiffDisposeEnvelope,
+	resolveCutOffTurnFailure,
 	type AgentStopKind,
 } from './agent-stop.js';
 import {surfaceStuckToNeedsAttention} from './needs-attention.js';
@@ -233,6 +235,12 @@ export type Dorfl = (input: {
 	 * provider degrades to `--fill` (no regression).
 	 */
 	output?: string;
+	/**
+	 * The agent's final model turn was CUT OFF (`length` / `error` stop; the
+	 * harness seam's `LaunchResult.cutOffTurn`, mirrors `DoDorfl.cutOffTurn`). An
+	 * empty diff with this set routes `agent-failed`, never the empty-diff STOP.
+	 */
+	cutOffTurn?: CutOffTurn;
 };
 
 export interface RunOnceOptions {
@@ -725,8 +733,9 @@ async function runOneItem(
 		//     predicate still HOLDS and this worktree is reaped — more §14-aligned.
 		if (tree.continueRebaseConflict) {
 			const reason =
-				`continuing the kept ${tree.branch}: rebase onto the latest main ` +
-				'conflicted (aborted, never auto-resolved) — run `requeue --reconcile` ' +
+				`continuing the kept ${tree.branch}: ` +
+				`${continueRebaseSentence(tree.branch, tree.continueRebaseFailure)} — ` +
+				'run `requeue --reconcile` ' +
 				'to non-destructively re-sync the mirror and retry the rebase (keeps ' +
 				'the work). Last resort: `requeue --reset` DESTRUCTIVELY discards the ' +
 				'branch and starts fresh.';
@@ -824,6 +833,7 @@ async function runOneItem(
 				cwd: tree.dir,
 				continueContext,
 				promptGuidance: itemGuidance,
+				taskFolder: task.folder,
 			});
 		} catch (err) {
 			if (err instanceof PromptError) {
@@ -837,7 +847,12 @@ async function runOneItem(
 		//    resolved per-repo `buildModel` (ADR §13, which inherits the general
 		//    `model` when unset) flows through the seam to the adapter; a
 		//    `{model}`-in-agentCmd misconfiguration surfaces as agent-failed.
-		let agent: {ok: boolean; detail?: string; output?: string};
+		let agent: {
+			ok: boolean;
+			detail?: string;
+			output?: string;
+			cutOffTurn?: CutOffTurn;
+		};
 		try {
 			agent = runAgent(
 				ctx,
@@ -874,6 +889,21 @@ async function runOneItem(
 		//     catches a stop without one. Either routes to needs-attention (surfaced on
 		//     the arbiter) and SKIPS the gate + Gate-2 (the whole `performIntegration`
 		//     band) — a clean STOP is NOT "a build that changed nothing".
+		//     A CUT-OFF final turn (`length`/`error`) with an empty diff is a harness
+		//     failure, not a STOP: route it `agent-failed` before the empty-diff
+		//     backstop (task `a-truncated-agent-turn-routes-as-agent-failed`, the
+		//     same guard `do` runs).
+		const cutOffDetail = await resolveCutOffTurnFailure({
+			cutOffTurn: agent.cutOffTurn,
+			output: agent.output,
+			slug,
+			cwd: tree.dir,
+			arbiter: tree.arbiterRemote,
+			env: gitEnv,
+		});
+		if (cutOffDetail !== undefined) {
+			return await saveAgentFailure(base, tree, slug, cutOffDetail, ctx);
+		}
 		const sentinel = parseStopSentinel(agent.output);
 		const stopReason: {kind: AgentStopKind; reason: string} | undefined =
 			sentinel !== undefined
@@ -1119,7 +1149,12 @@ function runAgent(
 	agentCmd: string,
 	model: string | undefined,
 	sessionsDir: string | undefined,
-): {ok: boolean; detail?: string; output?: string} {
+): {
+	ok: boolean;
+	detail?: string;
+	output?: string;
+	cutOffTurn?: CutOffTurn;
+} {
 	if (ctx.dorfl) {
 		return ctx.dorfl({cwd: tree.dir, prompt, slug, env: ctx.env});
 	}
@@ -1148,7 +1183,13 @@ function runAgent(
 	// Surface the agent's FINAL SUMMARY (`LaunchResult.output`) — the source channel
 	// for the propose-mode PR body — instead of dropping it (mirrors `do`'s
 	// `runDoAgent`). Absent (no parseable assistant text) ⇒ undefined ⇒ `--fill`.
-	return {ok: launched.ok, detail: launched.detail, output: launched.output};
+	return {
+		ok: launched.ok,
+		detail: launched.detail,
+		output: launched.output,
+		// How the final model turn ended (the cut-off guard before the STOP route).
+		cutOffTurn: launched.cutOffTurn,
+	};
 }
 
 /**

package/src/scan.ts

@@ -9,7 +9,8 @@ import {
 } from './ledger-read.js';
 import {listMirrors} from './registry.js';
 import {
-	fetchMirrorMainOrWarn,
+	createMirrorRefresher,
+	mirrorInReconcileScope,
 	resolveRepoConfigFromMirror,
 } from './repo-mirror.js';
 import {resolveRepoConfig} from './repo-config.js';
@@ -425,6 +426,16 @@ export async function scan(
 		 * claim path sweeps on every unit of work.
 		 */
 		reconcileLocks?: boolean;
+		/**
+		 * ARBITER SCOPE of the {@link reconcileLocks} write (task
+		 * `status-no-arbiter-is-honoured`, the same scoping `status --reconcile-locks`
+		 * has). When set, ONLY the registered mirror whose `origin` hub-keys to this
+		 * key has its stale locks RELEASED; every other mirror is merely classified,
+		 * exactly as without `reconcileLocks`. `undefined` reconciles EVERY mirror:
+		 * the CLI leaves it undefined only behind the explicit `--all-arbiters`.
+		 * Ignored when `reconcileLocks` is not `true`.
+		 */
+		reconcileArbiterKey?: string;
 		env?: NodeJS.ProcessEnv;
 		/**
 		 * The per-machine {@link ConfigOverrideMap} (from `loadConfigOverride`),
@@ -444,15 +455,17 @@ export async function scan(
 	const repos: RepoReport[] = [];
 	const counts = {totalItems: 0, totalEligible: 0};
 
+	// Dead LOCAL arbiters are summarised on one line after the loop (see
+	// `createMirrorRefresher`), not warned once per mirror.
+	const refresher = createMirrorRefresher({
+		warn: options.warn,
+		env: options.env,
+	});
 	for (const mirror of mirrors) {
 		// Fetch-first (ADR §5/§6): refresh this mirror's `main` so the read below
 		// sees the remote truth. Never fatal — a failed fetch WARNS and falls back to
 		// the mirror's last-known `main` (the read strategy is unchanged).
-		fetchMirrorMainOrWarn({
-			mirrorPath: mirror.path,
-			warn: options.warn,
-			env: options.env,
-		});
+		refresher.refresh(mirror.path);
 		// Read the full `work/` lifecycle from the mirror's bare `main` ref through
 		// the read seam (git ls-tree/show; NOT a working-tree read).
 		const state = await ledgerRead.resolveMirrorState({
@@ -494,7 +507,14 @@ export async function scan(
 		const MIRROR_MAIN = {mainRef: 'main'};
 		let staleLockEntries: string[];
 		let lockHeld: LockEntry[];
-		if (options.reconcileLocks === true) {
+		if (
+			options.reconcileLocks === true &&
+			mirrorInReconcileScope(
+				mirror.path,
+				options.reconcileArbiterKey,
+				options.env,
+			)
+		) {
 			const swept = await reconcileTerminalItemLocks(
 				mirror.path,
 				'origin',
@@ -612,6 +632,7 @@ export async function scan(
 			staleLocks: staleLockEntries,
 		});
 	}
+	refresher.flush();
 
 	return {
 		repos,
@@ -668,6 +689,14 @@ export function scanRepoPaths(
 	 * handle); DEFAULTS empty.
 	 */
 	heldSpecSlugs: Set<string> = new Set(),
+	/**
+	 * The held TASK slugs whose lock a finished propose build keeps (the
+	 * `propose-pr` marker): passed to {@link gatherLifecycleInPlace}, which lets
+	 * such a slug through the lifecycle subtraction when its merge question is
+	 * answered `merge` (task `wire-merge-questions-into-the-advance-tick`,
+	 * decision 6). The build pool is unaffected. DEFAULTS empty.
+	 */
+	proposeKeptSlugs: Set<string> = new Set(),
 ): ScanReport {
 	const repos: RepoReport[] = [];
 	const counts = {totalItems: 0, totalEligible: 0};
@@ -705,6 +734,7 @@ export function scanRepoPaths(
 				// symmetric to the `scoreItems` subtraction above, so a held task never
 				// leaks into a surface/apply leg either.
 				heldSlugs,
+				proposeKeptSlugs,
 			}),
 		);
 		// The one-slug-one-folder LINT over THIS working tree's `work/` ledger.

package/src/sidecar.ts

@@ -144,8 +144,23 @@ export interface SidecarEntry {
 	 * kind-based SUBFOLDERS.
 	 */
 	kind?: SidecarKind;
+	/**
+	 * The arbiter `main` commit this question was ASKED AGAINST (a full hex
+	 * sha), set on a `kind: merge` entry by the merge-question surfacer and by
+	 * the `strictMergeApproval` re-surface path (task
+	 * `strict-merge-approval-restale-check-runs-before-the-continue-rebase`).
+	 * With `strictMergeApproval` on, an answered merge re-surfaces when `main`'s
+	 * code moved since this commit. Absent on every other entry and on a merge
+	 * entry written before the field existed (which then never re-stales).
+	 * Carried in the per-entry HTML comment as `askedAtMain=<sha>`; a malformed
+	 * value reads as absent.
+	 */
+	askedAtMain?: string;
 }
 
+/** A full git object name: 40 hex (SHA-1) or 64 hex (SHA-256). */
+const FULL_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
 /** The parsed sidecar: identity frontmatter + ordered entries. */
 export interface SidecarModel {
 	/** The NAMESPACED identity (`spec:autotask`, `task:foo`, `observation:bar`). */
@@ -434,6 +449,7 @@ interface EntryFields {
 	id?: string;
 	answered?: boolean;
 	kind?: SidecarKind;
+	askedAtMain?: string;
 }
 
 /** Parse a per-entry `<!-- qN fields: key=val … -->` HTML comment. */
@@ -467,6 +483,11 @@ function parseEntryComment(line: string): EntryFields | undefined {
 			if (SIDECAR_KINDS.has(value as SidecarKind)) {
 				out.kind = value as SidecarKind;
 			}
+		} else if (key === 'askedAtMain') {
+			// Silent-on-malformed, as for `kind`: only a full sha is kept.
+			if (FULL_SHA.test(value)) {
+				out.askedAtMain = value;
+			}
 		}
 	}
 	return out;
@@ -481,6 +502,7 @@ function parseEntrySection(lines: string[]): SidecarEntry {
 	let defaultVal: string | undefined;
 	let answeredOverride: boolean | undefined;
 	let kind: SidecarKind | undefined;
+	let askedAtMain: string | undefined;
 	let answerStart = -1;
 
 	for (let i = 0; i < lines.length; i++) {
@@ -500,6 +522,9 @@ function parseEntrySection(lines: string[]): SidecarEntry {
 			if (entryFields.kind !== undefined) {
 				kind = entryFields.kind;
 			}
+			if (entryFields.askedAtMain !== undefined) {
+				askedAtMain = entryFields.askedAtMain;
+			}
 			inBlockquote = false;
 			continue;
 		}
@@ -568,6 +593,9 @@ function parseEntrySection(lines: string[]): SidecarEntry {
 	if (kind !== undefined) {
 		entry.kind = kind;
 	}
+	if (askedAtMain !== undefined) {
+		entry.askedAtMain = askedAtMain;
+	}
 	return entry;
 }
 
@@ -718,6 +746,9 @@ export function serialiseSidecar(
 		if (entry.kind !== undefined) {
 			fields.push(`kind=${entry.kind}`);
 		}
+		if (entry.askedAtMain !== undefined && FULL_SHA.test(entry.askedAtMain)) {
+			fields.push(`askedAtMain=${entry.askedAtMain}`);
+		}
 		out.push(`<!-- ${entry.id} fields: ${fields.join(' ')} -->`);
 		out.push('');
 		out.push(ANSWER_MARKER);
@@ -775,6 +806,8 @@ export interface NewQuestion {
 	 * agentic `decide()` path. INTERIM — removable once kind-subfolders land.
 	 */
 	kind?: SidecarKind;
+	/** The arbiter `main` sha the question is asked against (see {@link SidecarEntry.askedAtMain}). */
+	askedAtMain?: string;
 }
 
 /**
@@ -802,6 +835,9 @@ export function appendQuestions(
 		if (q.kind !== undefined) {
 			entry.kind = q.kind;
 		}
+		if (q.askedAtMain !== undefined) {
+			entry.askedAtMain = q.askedAtMain;
+		}
 		entries.push(entry);
 	}
 	return {...model, entries};

package/src/single-job-warning.ts

@@ -0,0 +1,135 @@
+/**
+ * The **old single-job workflow warning** (decision 9 of ADR
+ * `ci-agent-job-holds-no-write-token`, task `ci-split-warn-single-job-workflows`).
+ *
+ * A consumer that upgrades dorfl but keeps a workflow generated before the CI
+ * split runs an agent verb in ONE job whose checkout persisted the write token
+ * in `.git/config`. The agent can read that credential. dorfl cannot fix the
+ * workflow from inside it, so it warns loudly: in GitHub Actions, when an
+ * agent-spawning verb ({@link AGENT_SPAWNING_VERBS}) runs WITHOUT `--phase` in a
+ * checkout whose local git config holds a credential. Behaviour is otherwise
+ * unchanged; the next minor version turns this warning into a refusal (an
+ * intent recorded in the warning text and the changeset, not in code).
+ *
+ * The credential itself is NEVER printed: detection returns only a boolean.
+ */
+
+import {inGitHubActions} from './agent-env.js';
+import {run} from './git.js';
+import {AGENT_SPAWNING_VERBS, type Phase} from './phase.js';
+
+/**
+ * Agent-spawning verbs this warning deliberately skips. `verify` is in
+ * {@link AGENT_SPAWNING_VERBS} because it runs repository code, but it launches
+ * no agent, and the generated `verify.yml` persists only a `contents: read`
+ * credential. Warning there would flag every private consumer's PR check, and
+ * the planned refusal would break it. Task `ci-split-generate-workflows` (the
+ * workflow guard) must apply the same exemption.
+ */
+export const SINGLE_JOB_WARNING_EXEMPT_VERBS: ReadonlySet<string> = new Set([
+	'verify',
+]);
+
+/** An HTTP(S) URL carrying userinfo (`https://user:token@host/...`). */
+const URL_WITH_USERINFO = /https?:\/\/[^/@\s]+@/i;
+
+/** An `http.extraheader` / `http.<url>.extraheader` key. */
+const EXTRAHEADER_KEY = /^http\.(?:.*\.)?extraheader$/i;
+
+/**
+ * Does this `git config --null --list` output hold a credential: a non-empty
+ * `http.*.extraheader`, or any value that is an HTTP(S) URL with userinfo?
+ * Returns a boolean only, so no caller can print the secret by accident.
+ */
+export function gitConfigListHoldsCredential(nullList: string): boolean {
+	for (const entry of nullList.split('\0')) {
+		if (entry === '') {
+			continue;
+		}
+		const newline = entry.indexOf('\n');
+		const key = newline === -1 ? entry : entry.slice(0, newline);
+		const value = newline === -1 ? '' : entry.slice(newline + 1);
+		if (EXTRAHEADER_KEY.test(key) && value.trim() !== '') {
+			return true;
+		}
+		if (URL_WITH_USERINFO.test(value)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Does the checkout at `cwd` persist a credential in its LOCAL git config
+ * (`.git/config` and the files it includes: `actions/checkout` v6+ writes the
+ * header to a separate file pulled in by an `includeIf`)? Global, system and
+ * environment (`GIT_CONFIG_*`) config are not read: the agent phase hands its
+ * read token to dorfl's git through the environment, which is not a persisted
+ * credential. Any failure (not a repository, no git) answers `false`: the
+ * warning never breaks a run.
+ */
+export function checkoutPersistsCredential(cwd: string): boolean {
+	try {
+		const result = run(
+			'git',
+			['config', '--local', '--includes', '--null', '--list'],
+			cwd,
+		);
+		return result.status === 0 && gitConfigListHoldsCredential(result.stdout);
+	} catch {
+		return false;
+	}
+}
+
+/** The warning text (never contains the credential). */
+export function singleJobWarningText(verb: string): string {
+	return [
+		'',
+		'!! WARNING: unsafe single-job CI workflow',
+		`!! 'dorfl ${verb}' is running in GitHub Actions without --phase, in a checkout`,
+		'!! whose git config persists a credential. Any agent this run launches can read',
+		'!! and use that token. Re-run `dorfl install-ci` to upgrade to the split',
+		'!! lock / agent / apply workflow, where the agent job holds no write token.',
+		'!! The next minor version of dorfl will REFUSE to run in this shape.',
+		'',
+	].join('\n');
+}
+
+/** Inputs to {@link singleJobWarning}. */
+export interface SingleJobWarningInput {
+	/** The top-level CLI verb that is about to run. */
+	verb: string;
+	/** Its `--phase`, or `undefined` when none was given. */
+	phase: Phase | undefined;
+	env: NodeJS.ProcessEnv;
+	/** The checkout to inspect. */
+	cwd: string;
+	/** Injectable credential probe (default {@link checkoutPersistsCredential}). */
+	persistsCredential?: (cwd: string) => boolean;
+}
+
+/**
+ * The warning to print for this invocation, or `undefined` when the shape is
+ * safe (a `--phase` run, not in GitHub Actions, a verb that spawns no agent or
+ * is exempt, or no persisted credential). The git config is read last, only
+ * when every cheap condition already says "unsafe".
+ */
+export function singleJobWarning(
+	input: SingleJobWarningInput,
+): string | undefined {
+	const {verb, phase, env, cwd} = input;
+	if (phase !== undefined) {
+		return undefined;
+	}
+	if (!AGENT_SPAWNING_VERBS.has(verb)) {
+		return undefined;
+	}
+	if (SINGLE_JOB_WARNING_EXEMPT_VERBS.has(verb)) {
+		return undefined;
+	}
+	if (!inGitHubActions(env)) {
+		return undefined;
+	}
+	const probe = input.persistsCredential ?? checkoutPersistsCredential;
+	return probe(cwd) ? singleJobWarningText(verb) : undefined;
+}

package/src/spec-complete.ts

@@ -12,8 +12,13 @@ import {
 /**
  * The read-only **"is this spec complete?"** core query (spec `issue-intake`, US #8 —
  * the closure-linkage half). Given a spec slug + a `work/` tree, a spec is COMPLETE
- * iff there is **≥1 task carrying `spec:<slug>`** AND **all such tasks reside in
- * `work/done/`**. Pure `work/`-folder logic — no seam, no git, no `gh`, no mutation.
+ * iff there is **≥1 task carrying `spec:<slug>` in `work/tasks/done/`** AND **every
+ * other such task is in `work/tasks/cancelled/`**. A task that names the spec
+ * ANYWHERE else (staged in `tasks/backlog/`, in `tasks/ready/`, in progress) keeps
+ * the spec incomplete; a cancelled task does not block completion, but a spec whose
+ * tasks are ALL cancelled (none done) is NOT complete (reported as
+ * {@link SpecCompleteResult.allCancelled}, so the close-job never closes its issue
+ * as `completed`). Pure `work/`-folder logic — no seam, no git, no `gh`, no mutation.
  *
  * This is the LINKAGE the intake engine emits for CI to ACT on: a spec fans out to N
  * tasks = N PRs whose tasks carry `spec:` ONLY (no `Refs #N` keyword is emitted),
@@ -26,9 +31,11 @@ import {
  * It is a `work/`-FOLDER RESIDENCE scan keyed on the parsed `spec:` field — NOT the
  * claim ledger (`ledger-read.ts` resolves claim-STATE, a different concern). It
  * reuses {@link parseFrontmatter} (the `spec:` field) rather than hand-rolling a YAML
- * parse, and scans the task lifecycle folders directly: `work/tasks/ready/`,
- * `work/in-progress/`, and `work/done/`. A task that has NOT yet landed in
- * `work/done/` (still in backlog / in-progress) means the spec is not yet complete.
+ * parse, and scans EVERY task lifecycle folder directly ({@link TASK_LIFECYCLE_FOLDERS}:
+ * backlog, ready, in-progress, done, cancelled). Task
+ * `spec-complete-counts-staged-and-cancelled-tasks`: the scan used to skip
+ * `tasks/backlog/`, so a spec whose tasks were still staged read as complete as
+ * soon as its first task landed.
  */
 
 /** The task lifecycle folders a `spec:<slug>` task can reside in. */
@@ -62,11 +69,18 @@ export interface SpecTask {
  */
 export interface SpecCompleteResult {
 	/**
-	 * `true` iff ≥1 task carries `spec:<slug>` AND every such task resides in
-	 * `work/done/`. `false` when no task carries the slug (≥1 is REQUIRED) OR when
-	 * any matching task is still outside `work/done/`.
+	 * `true` iff ≥1 `spec:<slug>` task resides in `work/tasks/done/` AND every other
+	 * such task resides in `work/tasks/cancelled/`. `false` when no task carries the
+	 * slug, when any matching task is still open (backlog / ready / in-progress), or
+	 * when every matching task is cancelled (see {@link allCancelled}).
 	 */
 	complete: boolean;
+	/**
+	 * `true` iff ≥1 task carries `spec:<slug>` AND every one of them is in
+	 * `work/tasks/cancelled/` (none done): the spec did not complete, it was
+	 * abandoned. Never `true` together with {@link complete}.
+	 */
+	allCancelled: boolean;
 	/** Every task carrying `spec:<slug>`, across all task folders, sorted by slug. */
 	tasks: SpecTask[];
 }
@@ -84,10 +98,10 @@ function listMarkdown(repoPath: string, folder: TaskFolder): string[] {
 }
 
 /**
- * Is this spec COMPLETE? Read-only: scan the task lifecycle folders, parse each
+ * Is this spec COMPLETE? Read-only: scan every task lifecycle folder, parse each
  * task's `spec:` via {@link parseFrontmatter}, keep those whose `spec:` equals
- * `slug`, and return COMPLETE iff that set is NON-EMPTY and EVERY member resides in
- * `work/done/`. Touches no git, no network, no mutation — a pure `work/`-folder
+ * `slug`, and return COMPLETE iff ≥1 member resides in `work/tasks/done/` and EVERY
+ * member resides in `work/tasks/done/` or `work/tasks/cancelled/`. Touches no git, no network, no mutation — a pure `work/`-folder
  * residence scan keyed on the parsed `spec:` field.
  */
 export function isSpecComplete(input: SpecCompleteInput): SpecCompleteResult {
@@ -111,7 +125,15 @@ export function isSpecComplete(input: SpecCompleteInput): SpecCompleteResult {
 	}
 	tasks.sort((a, b) => a.slug.localeCompare(b.slug));
 
-	// COMPLETE iff ≥1 such task AND every one of them is in `work/done/`.
-	const complete = tasks.length > 0 && tasks.every((s) => s.folder === 'done');
-	return {complete, tasks};
+	// COMPLETE iff ≥1 such task is done AND every one of them is done or
+	// cancelled. A staged/ready/in-progress task keeps it open; an all-cancelled
+	// set is NOT complete (nothing was delivered).
+	const settled = tasks.every(
+		(s) => s.folder === 'done' || s.folder === 'cancelled',
+	);
+	const anyDone = tasks.some((s) => s.folder === 'done');
+	const complete = settled && anyDone;
+	const allCancelled =
+		tasks.length > 0 && tasks.every((s) => s.folder === 'cancelled');
+	return {complete, allCancelled, tasks};
 }