dorfl 0.14.2 → 0.15.0

package/src/advance-loop-driver.ts

@@ -12,10 +12,8 @@ import {runConcurrent} from './concurrency.js';
 import {scan, type ScanReport} from './scan.js';
 import {run as runProcess} from './git.js';
 import {jobWorktreeDoDriver} from './do.js';
-import {
-	pushTreelessResult,
-	TREELESS_RUNGS,
-} from './advance-treeless-publish.js';
+import {TREELESS_RUNGS} from './advance-treeless-publish.js';
+import {refWrite} from './ref-write.js';
 import type {Config} from './config.js';
 import type {
 	RunTick,
@@ -206,7 +204,7 @@ export async function advanceOnce(
 				TREELESS_RUNGS.has(result.rung) &&
 				options.context.cwd !== undefined
 			) {
-				await pushTreelessResult({
+				await refWrite.publishTreelessResult({
 					cwd: options.context.cwd,
 					arbiter: options.context.arbiter ?? 'origin',
 					// Large liveness ceiling (C2, task `c2-rebase-until-real-on-durable-main-

package/src/advance-treeless-publish.ts

@@ -134,6 +134,8 @@ export async function pushTreelessResult(
 	const {cwd, arbiter, retries, env, note} = params;
 	const jitterMs = params.jitterMs ?? DEFAULT_TREELESS_JITTER_MS;
 	for (let i = 0; i <= retries; i++) {
+		// Write-seam implementation: callers reach this through
+		// `refWrite.publishTreelessResult` (guard: `write-sites-through-seams.test.ts`).
 		const push = await runAsync(
 			'git',
 			['push', '--quiet', arbiter, 'HEAD:main'],
@@ -207,6 +209,65 @@ export async function pushTreelessResult(
 	}
 }
 
+/** The result of {@link checkTreelessPublishScope}. */
+export type TreelessPublishScope =
+	/** `HEAD` is `base`: the rung committed nothing, so there is nothing to push. */
+	| {kind: 'nothing'}
+	/** `HEAD` is exactly one commit whose parent is `base`: the rung's own. */
+	| {kind: 'rung-commit'; commit: string}
+	/** Anything else: publishing `HEAD:main` would carry commits that are not the rung's. */
+	| {kind: 'refused'; message: string};
+
+/**
+ * Check, BEFORE a tree-less publish, that `HEAD:main` would publish exactly the
+ * rung's own commit (task `ci-split-treeless-rungs`; observation
+ * `advance-lifecycle-push-trigger-lands-an-unreviewed-work-branch-on-main`).
+ * {@link pushTreelessResult} pushes `HEAD:main` from whatever is checked out, so
+ * a checkout not based on the fetched `<arbiter>/main` tip (`base`) would
+ * publish every commit between the two. The CI apply phase runs the rung on a
+ * fresh checkout of `base` and calls this first: the new commit's parent must be
+ * `base` (the publish's own retry may then rebase only that commit). Read-only.
+ */
+export async function checkTreelessPublishScope(params: {
+	cwd: string;
+	base: string;
+	env: NodeJS.ProcessEnv | undefined;
+}): Promise<TreelessPublishScope> {
+	const {cwd, base, env} = params;
+	const head = await runAsync('git', ['rev-parse', 'HEAD'], cwd, {env});
+	if (head.status !== 0) {
+		return {kind: 'refused', message: 'the checkout has no HEAD commit'};
+	}
+	const tip = head.stdout.trim();
+	if (tip === base) return {kind: 'nothing'};
+	const list = await runAsync('git', ['rev-list', `${base}..${tip}`], cwd, {
+		env,
+	});
+	const commits = list.stdout.split('\n').filter((l) => l.trim() !== '');
+	const parents = await runAsync(
+		'git',
+		['rev-list', '--parents', '-n', '1', tip],
+		cwd,
+		{env},
+	);
+	const parentList = parents.stdout.trim().split(/\s+/).slice(1);
+	if (
+		list.status !== 0 ||
+		commits.length !== 1 ||
+		parentList.length !== 1 ||
+		parentList[0] !== base
+	) {
+		return {
+			kind: 'refused',
+			message:
+				`HEAD (${tip}) is not one commit on top of the fetched main (${base}): ` +
+				`${commits.length} commit(s) would be published, so the tree-less publish ` +
+				'is refused (it would land commits that are not the rung result)',
+		};
+	}
+	return {kind: 'rung-commit', commit: tip};
+}
+
 /**
  * The rung kinds that commit a tree-less result LOCALLY (sidecar / `needsAnswers`
  * / `triaged:` marker) and therefore need {@link pushTreelessResult} to reach the

package/src/advance.ts

@@ -1,3 +1,4 @@
+import type {Phase} from './phase.js';
 import {existsSync, readFileSync} from 'node:fs';
 import {join} from 'node:path';
 import {type WorkFolderKey, workItemPath, workItemRel} from './work-layout.js';
@@ -401,9 +402,10 @@ export interface AdvanceContext {
 	 * Resolved `strictMergeApproval` boolean (sibling task
 	 * `strict-merge-approval-gate`). Default OFF ⇒ honour the prior approval +
 	 * land on a green re-verify (cheap, the SPEC-applied OQ6 default). ON ⇒
-	 * re-surface the merge-question when the merge-base moved between the
-	 * surfacer's question and this apply (the host-agnostic analogue of
-	 * GitHub's "dismiss stale approvals when the base changes").
+	 * re-surface the merge-question when `main`'s code (outside `work/`) moved
+	 * since the question was asked, i.e. since its recorded `askedAtMain` (the
+	 * host-agnostic analogue of GitHub's "dismiss stale approvals when the base
+	 * changes").
 	 */
 	strictMergeApproval?: boolean;
 	/**
@@ -433,6 +435,13 @@ export interface AdvanceContext {
 	stuckAction?: StuckActionHandler;
 	/** Sink for human-readable progress notes. */
 	note?: (message: string) => void;
+	/**
+	 * The CI phase this run executes as (`--phase lock|agent|apply`, CI-only;
+	 * see `phase.ts`). `undefined` ⇒ today's single process. Threaded next to
+	 * `env` and `note` so the per-path phase splits can branch on it; the phase
+	 * guards read the process-wide active phase.
+	 */
+	phase?: Phase;
 }
 
 /** The options one `advance` tick consumes. */
@@ -494,7 +503,7 @@ export interface ReadSignalsInput {
  * to the `spec` sidecar type, so `advance spec:<slug>` resolves its
  * signals/folders (`FOLDERS_FOR_TYPE['spec']`) and orchestrates `do spec:<slug>`.
  */
-function sidecarTypeFor(namespace: SlugNamespace): SidecarType {
+export function sidecarTypeFor(namespace: SlugNamespace): SidecarType {
 	return namespace === 'observation'
 		? 'observation'
 		: namespace === 'spec'
@@ -1186,8 +1195,8 @@ async function applyRung(input: RungExecInput): Promise<RungExecResult> {
  *     the item to needs-attention through its own shared seam, so `main` never
  *     received a failing tree. The apply rung SHORT-CIRCUITS — the sidecar is
  *     LEFT IN PLACE so the open answer stays surfaced for a human follow-up.
- *   - `restale` ⇒ `strictMergeApproval` was ON and the merge-base moved
- *     between the surfacer's question and this apply; the apply rung appends
+ *   - `restale` ⇒ `strictMergeApproval` was ON and `main`'s code moved
+ *     since the question was asked; the apply rung appends
  *     a follow-up question + re-pauses (the human re-confirms against the new
  *     base).
  *   - `hold` / `drop` ⇒ no land; fall through to the normal apply path so the
@@ -1263,7 +1272,9 @@ async function maybeRunMergeAction(
 	if (result.outcome === 'restale') {
 		// `strictMergeApproval` re-surface: append a follow-up question and
 		// re-pause. The previous answer stays recorded in the entry; the human
-		// re-confirms against the new merge-base in the appended question.
+		// re-confirms against the new `main` in the appended question, which
+		// records that `main` as its `askedAtMain` (so a re-answer while `main`
+		// stays put lands instead of re-staling forever).
 		const apply = context.applyPersist ?? applyAnsweredQuestions;
 		try {
 			const applied = apply({
@@ -1273,11 +1284,12 @@ async function maybeRunMergeAction(
 				appendQuestions: [
 					{
 						question:
-							`Merge-base for \`work/${input.slug}\` moved since your last ` +
-							`answer (strictMergeApproval is ON). Re-confirm: still land?`,
+							`\`main\` moved since the merge question for \`work/${input.slug}\` ` +
+							`was asked (strictMergeApproval is ON). Re-confirm: still land?`,
 						context: result.message,
 						default: 'merge | hold | drop',
 						kind: 'merge',
+						...(result.main === undefined ? {} : {askedAtMain: result.main}),
 					},
 				],
 				note,
@@ -1432,6 +1444,87 @@ async function maybeRunStuckAction(
 	}
 }
 
+/**
+ * What a TREE-LESS rung needs to run on this item, read off the same state the
+ * rung body reads (spec `ci-agent-job-without-write-token` decision 11, task
+ * `ci-split-treeless-rungs`): the CI lock phase publishes it as `needsAgent`, and
+ * the apply phase recomputes it on its fresh checkout. It mirrors the rung
+ * bodies above branch for branch, so it lives next to them:
+ *
+ *  - `triage-observation`: a note already carrying `triaged:`, or the legacy
+ *    back-fill (an engine-written `## Applied answers` record without the
+ *    marker), is deterministic; under `observationTriage: auto` the triage gate
+ *    agent runs; otherwise the surface path runs the `surface-questions` agent
+ *    unless the observation provably has nothing to ask (the surface
+ *    short-circuit, which then surfaces only the engine-built triage question);
+ *  - `surface`: the `surface-questions` agent, or the same short-circuit;
+ *  - `apply`: an answered `kind: merge` entry answered `merge` runs the agent
+ *    job (task `ci-split-answered-merge-action`: no model, but `prepare` and
+ *    `verify` run the branch's code on the rebased tip), and `hold` / `drop`
+ *    run none; the CI phases refine the `merge` case against the arbiter (a
+ *    work branch that is absent or already on `main` needs none, see
+ *    `ci-phase-treeless.ts`), which this tree-only read cannot see. An
+ *    answered `kind: stuck` entry and a task/spec content answer run no agent;
+ *    an answered observation runs the agentic decision.
+ *
+ * A missing item file needs no agent (the rung is a benign `vanished` skip).
+ */
+export type TreelessAgentNeed =
+	| {needsAgent: boolean}
+	| {unsplit: string; needsAgent?: undefined};
+
+/** See {@link TreelessAgentNeed}. */
+export function treelessAgentNeed(input: RungExecInput): TreelessAgentNeed {
+	const {item, context} = input;
+	const cwd = context.cwd;
+	const itemPath = findItemPath(cwd, input.namespace, input.slug);
+	if (itemPath === undefined) return {needsAgent: false};
+	const sidecarExists = existsSync(join(cwd, sidecarPathFor(item)));
+	switch (input.classification.kind) {
+		case 'triage-observation': {
+			const body = readFileSync(join(cwd, itemPath), 'utf8');
+			const fm = parseFrontmatter(body);
+			if (fm.triaged !== undefined && fm.triaged !== '') {
+				return {needsAgent: false};
+			}
+			if (hasAppliedAnswersRecord(body)) return {needsAgent: false};
+			if (context.observationTriage === 'auto') return {needsAgent: true};
+			return {
+				needsAgent: !isNothingToSurfaceObservation(
+					cwd,
+					input,
+					itemPath,
+					sidecarExists,
+				),
+			};
+		}
+		case 'surface':
+			return {
+				needsAgent: !isNothingToSurfaceObservation(
+					cwd,
+					input,
+					itemPath,
+					sidecarExists,
+				),
+			};
+		case 'apply':
+			const merge = detectAnsweredMergeAction(cwd, item);
+			if (merge !== undefined) {
+				return {needsAgent: merge.verb === 'merge'};
+			}
+			if (detectAnsweredStuckAction(cwd, item) !== undefined) {
+				return {needsAgent: false};
+			}
+			return {
+				needsAgent:
+					input.namespace === 'observation' &&
+					!(context.applyFollowups && context.applyFollowups.length > 0),
+			};
+		default:
+			return {unsplit: `the ${input.classification.kind} rung`};
+	}
+}
+
 /**
  * The cross-tick-window BENIGN SKIP shared by all three rungs that need to
  * resolve an item file (surface / triage / apply). The lifecycle pool enumerated
@@ -1462,7 +1555,7 @@ function vanishedSkip(input: {
  * folders it may rest in (the SAME folder set {@link readNeedsAnswers} searches).
  * Returns the path RELATIVE to `cwd`, or `undefined` when no file exists.
  */
-function findItemPath(
+export function findItemPath(
 	cwd: string,
 	namespace: SlugNamespace,
 	slug: string,
@@ -1547,8 +1640,14 @@ async function applyAgenticDecision(
 	if (verdict.outcome === 'ask') {
 		// ask-follow-up → the EXISTING append/re-pause loop. One BATCH of follow-ups.
 		const apply = context.applyPersist ?? applyAnsweredQuestions;
-		const question = (verdict.question ?? '').trim();
-		if (question === '') {
+		const questions = (
+			verdict.questions !== undefined && verdict.questions.length > 0
+				? verdict.questions
+				: [verdict.question ?? '']
+		)
+			.map((q) => q.trim())
+			.filter((q) => q !== '');
+		if (questions.length === 0) {
 			return {
 				exitCode: 1,
 				outcome: 'usage-error',
@@ -1560,7 +1659,7 @@ async function applyAgenticDecision(
 				cwd,
 				item,
 				itemPath,
-				appendQuestions: [{question}],
+				appendQuestions: questions.map((question) => ({question})),
 				note,
 			});
 			return {
@@ -1857,9 +1956,21 @@ export async function performAdvance(
 	//    ITSELF acquires the SAME `task-<slug>`/`prd-<slug>` ref (the create-only CAS
 	//    with NO re-entrancy/auto-steal, per the ADR), so taking it here too would
 	//    DEADLOCK the tick against itself. The inner `do`'s claim/task lock IS the
-	//    single exclusion point for those rungs. The `work/advancing/<entry>.md` marker
-	//    CAS is KEPT for ALL rungs (its removal is the capstone task #9).
+	//    single exclusion point for those rungs. The legacy `work/advancing/<entry>.md`
+	//    marker is GONE (removed by the capstone cut-over, task
+	//    `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`): there is no
+	//    marker CAS for any rung, only the per-item lock ref (see `advancing-lock.ts`).
 	const unifiedForRung = isTreeLessRung(classification.kind);
+	// An answered `merge` may take over the lock a finished propose build of the
+	// SAME item keeps held (the `propose-pr` marker; task
+	// `wire-merge-questions-into-the-advance-tick`, decisions 2 and 4). Any other
+	// held lock still makes this tick back off.
+	const takeOverProposeKept = answersMerge(
+		repoPath,
+		item,
+		resolved.namespace,
+		classification,
+	);
 	const acquire =
 		options.acquireLock ??
 		((lockItem: string) =>
@@ -1868,6 +1979,7 @@ export async function performAdvance(
 				cwd,
 				arbiter,
 				acquireUnified: unifiedForRung,
+				takeOverProposeKept,
 				note,
 			}));
 	const lock = await acquire(item);
@@ -1965,6 +2077,24 @@ function isTreeLessRung(kind: TickClassification['kind']): boolean {
 	);
 }
 
+/**
+ * Is this tick the apply of a task whose merge question is answered `merge`
+ * (the case that may take over a propose-kept lock)? Read off the same tree the
+ * classification read.
+ */
+export function answersMerge(
+	repoPath: string,
+	item: string,
+	namespace: SlugNamespace,
+	classification: TickClassification,
+): boolean {
+	return (
+		classification.kind === 'apply' &&
+		namespace === 'task' &&
+		detectAnsweredMergeAction(repoPath, item)?.verb === 'merge'
+	);
+}
+
 /** Dispatch the classified rung to the executor seam (winner-only). */
 function dispatchRung(
 	executor: RungExecutor,

package/src/advancing-lock.ts

@@ -4,7 +4,11 @@ import {runAsync, type RunResult} from './git.js';
 import {ledgerWrite} from './ledger-write.js';
 import {resolveSidecarIdentity} from './sidecar.js';
 import {readFrontmatterField} from './frontmatter.js';
-import {acquireItemLock, releaseItemLock} from './item-lock.js';
+import {
+	acquireItemLock,
+	releaseItemLock,
+	takeOverProposeKeptLock,
+} from './item-lock.js';
 import {realSleep, type Sleep} from './retry-backoff.js';
 
 /**
@@ -110,6 +114,15 @@ export interface AcquireAdvancingLockOptions {
 	 * nothing). This module stays rung-agnostic — it only knows "unified or not".
 	 */
 	acquireUnified?: boolean;
+	/**
+	 * When the unified acquire finds the item locked, TAKE OVER the lock if (and
+	 * only if) a finished propose build of the same item keeps it held (its entry
+	 * carries the `propose-pr` marker, see `takeOverProposeKeptLock`). The advance
+	 * tick sets it for an answered `merge` (task
+	 * `wire-merge-questions-into-the-advance-tick`, decisions 2 and 4); any other
+	 * held lock is still `lost`. Ignored unless `acquireUnified`.
+	 */
+	takeOverProposeKept?: boolean;
 	/** Environment for child git processes. */
 	env?: NodeJS.ProcessEnv;
 	/** Sink for human-readable progress notes. */
@@ -215,6 +228,28 @@ async function runAcquire(
 			`failed to acquire the item lock for '${entry}': ${lock.message}`,
 		);
 	}
+	if (lock.outcome === 'lost' && options.takeOverProposeKept === true) {
+		const taken = await takeOverProposeKeptLock({
+			item: options.item,
+			action: 'advance',
+			cwd,
+			arbiter,
+			holder: by,
+			env,
+		});
+		if (taken.outcome === 'error') {
+			throw new AdvancingLockUsageError(
+				`failed to take over the item lock for '${entry}': ${taken.message}`,
+			);
+		}
+		if (taken.outcome === 'acquired') {
+			const message = `LOCKED '${entry}' for advancing on ${arbiter}: ${taken.message}.`;
+			note(message);
+			return {exitCode: 0, outcome: 'acquired', message, entry};
+		}
+		note(taken.message);
+		return {exitCode: 2, outcome: 'lost', message: taken.message, entry};
+	}
 	if (lock.outcome === 'lost') {
 		note(lock.message);
 		return {exitCode: 2, outcome: 'lost', message: lock.message, entry};

package/src/agent-env.ts

@@ -0,0 +1,174 @@
+/**
+ * **No GitHub token in a CI agent's environment.**
+ *
+ * In CI, dorfl runs an agent (with shell) over text any GitHub user can write:
+ * an issue body, a comment. Whatever the agent's environment holds, a prompt
+ * injection in that text can ask it to print. So every autonomous agent launch
+ * in GitHub Actions gets its environment with the GitHub credentials removed
+ * ({@link scrubAgentEnv}), whatever the workflow put in the step environment.
+ *
+ * This is only the cheap layer. It does not stop an agent from reading the
+ * token another way while it shares a job with one (its parent processes'
+ * environment, `.git/config` when the checkout persists a credential, `sudo` on
+ * a hosted runner). The real boundary is running the agent in a job whose
+ * token cannot write, see spec `ci-agent-job-without-write-token` (under
+ * `work/specs/`).
+ *
+ * On a laptop nothing is removed: it is the human's own machine, and a local
+ * tool the agent uses (an MCP server, a `gh` call) may legitimately need the
+ * human's token.
+ */
+
+/**
+ * Names that carry a GitHub credential by convention (case-insensitive):
+ * `GH_TOKEN`, `GITHUB_TOKEN`, any `GH_*_TOKEN` / `GITHUB_*_TOKEN` (e.g.
+ * `GH_ENTERPRISE_TOKEN`), and the dorfl-specific `DORFL_GH_TOKEN`,
+ * `DORFL_GIT_TOKEN`, `DORFL_GITHUB_TOKEN` with any infix
+ * (`DORFL_*_GH_TOKEN` / `DORFL_*_GIT_TOKEN` / `DORFL_*_GITHUB_TOKEN`).
+ */
+const GITHUB_TOKEN_NAME =
+	/^(?:(?:GH|GITHUB)_(?:\w+_)?TOKEN|DORFL_(?:\w+_)?(?:GH|GIT|GITHUB)_TOKEN)$/i;
+
+/**
+ * The GitHub Actions runtime credentials a step can see: the OIDC request pair
+ * (it mints an ID token, which a cloud role may trust for writes) and the
+ * runtime token (artifact/cache service).
+ */
+const ACTIONS_RUNTIME_NAME =
+	/^ACTIONS_(?:ID_TOKEN_REQUEST_(?:TOKEN|URL)|RUNTIME_TOKEN)$/i;
+
+/**
+ * The runner's workflow-command FILES. Not credentials, but writing to them
+ * injects environment variables, PATH entries or outputs into LATER steps of
+ * the job, which may hold a token. The agent has no use for them.
+ */
+const RUNNER_COMMAND_FILES = new Set([
+	'GITHUB_ENV',
+	'GITHUB_PATH',
+	'GITHUB_OUTPUT',
+	'GITHUB_STATE',
+	'GITHUB_STEP_SUMMARY',
+]);
+
+/**
+ * GitHub token VALUE shapes, anywhere in a value (a token inside a URL counts):
+ * personal (`ghp_`), OAuth (`gho_`), user-to-server (`ghu_`), server-to-server
+ * incl. the Actions `GITHUB_TOKEN` (`ghs_`), refresh (`ghr_`) and fine-grained
+ * PATs (`github_pat_`). Matching on the value catches a token the workflow
+ * exported under ANY name, which a name list alone would miss.
+ */
+const GITHUB_TOKEN_VALUE =
+	/(?:^|[^A-Za-z0-9_])(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/;
+
+/** `GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_<n>` / `GIT_CONFIG_VALUE_<n>`. */
+const GIT_CONFIG_ENV_ENTRY = /^GIT_CONFIG_(?:COUNT|KEY_\d+|VALUE_\d+)$/;
+
+/**
+ * Git config text that carries or fetches a credential: an HTTP auth header, a
+ * credential helper or askpass command, or an HTTP(S) URL with userinfo
+ * (`https://user:token@host`). A plain `insteadOf` rewrite is NOT matched,
+ * including an SSH one (`ssh://git@github.com/`, whose userinfo is no secret).
+ */
+const CREDENTIAL_CONFIG_TEXT =
+	/extraheader|authorization|credential\.|askpass|https?:\/\/[^/@\s]+@/i;
+
+/** The result of {@link scrubAgentEnv}. */
+export interface ScrubbedEnv {
+	/** The environment to launch the child with (a COPY; the input is untouched). */
+	env: NodeJS.ProcessEnv;
+	/** The NAMES that were removed (never the values), sorted, for diagnostics. */
+	removed: string[];
+}
+
+/**
+ * Should this single variable be withheld from an agent? True for the GitHub
+ * token names, the Actions runtime credentials, the runner command files, and
+ * any variable whose VALUE contains a GitHub token.
+ */
+export function isWriteCredentialVar(
+	name: string,
+	value: string | undefined,
+): boolean {
+	if (GITHUB_TOKEN_NAME.test(name) || ACTIONS_RUNTIME_NAME.test(name)) {
+		return true;
+	}
+	if (RUNNER_COMMAND_FILES.has(name.toUpperCase())) {
+		return true;
+	}
+	return value !== undefined && GITHUB_TOKEN_VALUE.test(value);
+}
+
+/**
+ * Return a copy of `env` with every GitHub credential removed: the variables
+ * {@link isWriteCredentialVar} flags, any OTHER variable holding the SAME value
+ * as one of those (an alias such as `TOKEN=$GH_TOKEN` of a token whose shape is
+ * not recognised, e.g. a GitHub Enterprise Server token), and git's environment
+ * config (`GIT_CONFIG_PARAMETERS`, `GIT_CONFIG_COUNT/KEY_n/VALUE_n`) when it
+ * carries a credential. The `GIT_CONFIG_COUNT/KEY_n/VALUE_n` block is removed
+ * WHOLE whenever any part of it is: removing one entry would leave a `COUNT`
+ * pointing at a missing key, which makes every git command fail.
+ *
+ * A denylist on purpose: the agent needs an open-ended set of variables (PATH,
+ * HOME, the provider key whose name the consumer chooses, node/pnpm/proxy
+ * settings), and an allowlist would break a consumer's harness.
+ */
+export function scrubAgentEnv(env: NodeJS.ProcessEnv): ScrubbedEnv {
+	const out: NodeJS.ProcessEnv = {...env};
+	const removed = new Set<string>();
+	const secretValues = new Set<string>();
+	for (const [name, value] of Object.entries(env)) {
+		if (isWriteCredentialVar(name, value)) {
+			delete out[name];
+			removed.add(name);
+			// Only a value long enough to be a secret is used for alias matching, so
+			// an empty or trivially short value cannot knock out unrelated variables.
+			if (value !== undefined && value.length >= 16) {
+				secretValues.add(value);
+			}
+		}
+	}
+	for (const [name, value] of Object.entries(out)) {
+		if (value !== undefined && secretValues.has(value)) {
+			delete out[name];
+			removed.add(name);
+		}
+	}
+	// Judge the block on the ORIGINAL env: an entry already removed above still
+	// condemns the whole block.
+	const gitConfigEntries = Object.keys(env).filter((k) =>
+		GIT_CONFIG_ENV_ENTRY.test(k),
+	);
+	if (
+		gitConfigEntries.some(
+			(k) => removed.has(k) || CREDENTIAL_CONFIG_TEXT.test(env[k] ?? ''),
+		)
+	) {
+		for (const k of gitConfigEntries) {
+			delete out[k];
+			removed.add(k);
+		}
+	}
+	if (CREDENTIAL_CONFIG_TEXT.test(out.GIT_CONFIG_PARAMETERS ?? '')) {
+		delete out.GIT_CONFIG_PARAMETERS;
+		removed.add('GIT_CONFIG_PARAMETERS');
+	}
+	return {env: out, removed: [...removed].sort()};
+}
+
+/**
+ * Is dorfl running in GitHub Actions (where agents lose the GitHub tokens)?
+ * Checks the process env too, so a caller that builds a child env from scratch
+ * (without `GITHUB_ACTIONS`) cannot switch the filter off by accident.
+ */
+export function inGitHubActions(env: NodeJS.ProcessEnv): boolean {
+	return env.GITHUB_ACTIONS === 'true' || process.env.GITHUB_ACTIONS === 'true';
+}
+
+/**
+ * The environment an autonomous agent is launched with: in GitHub Actions, the
+ * caller's env with every GitHub credential removed ({@link scrubAgentEnv}); on
+ * a laptop, the caller's env unchanged.
+ */
+export function agentEnvFor(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	return inGitHubActions(env) ? scrubAgentEnv(env).env : env;
+}

package/src/agent-stop.ts

@@ -1,6 +1,7 @@
 import {runAsync} from './git.js';
 import {JOB_RECORD_FILENAME} from './workspace.js';
 import type {NewQuestion} from './sidecar.js';
+import type {CutOffTurn} from './harness.js';
 
 /**
  * **The build-agent → runner REPORTING CHANNEL** (task `agent-stop-signal`).
@@ -363,6 +364,86 @@ export function emptyDiffStopReason(slug: string): string {
 	);
 }
 
+/**
+ * The provider error text is capped at this many characters in the failure
+ * detail: pi records the raw provider body (often a JSON blob), and the detail
+ * becomes the needs-attention reason on the lock, which must stay one readable
+ * line rather than a pasted payload.
+ */
+const MAX_CUT_OFF_ERROR_LENGTH = 300;
+
+/**
+ * The `agent-failed` detail for a run whose FINAL model turn was CUT OFF
+ * ({@link CutOffTurn}) and which left no source change (task
+ * `a-truncated-agent-turn-routes-as-agent-failed`). Names the stop cause so the
+ * operator reads a harness failure, never "the agent found nothing to build".
+ * The provider's `errorMessage` (an `error` stop) is appended VERBATIM (bounded)
+ * so the shared failure-cause classifier can still recognise an infra signature
+ * in it (an overloaded provider reads `transient-infra`).
+ */
+export function cutOffTurnFailureDetail(
+	slug: string,
+	cutOff: CutOffTurn,
+): string {
+	const cause =
+		cutOff.cause === 'length'
+			? "stopReason 'length': the turn hit the model's per-turn output-token cap"
+			: "stopReason 'error': the provider ended the turn with an error";
+	const error =
+		cutOff.errorMessage === undefined
+			? ''
+			: ` (${boundErrorMessage(cutOff.errorMessage)})`;
+	return (
+		`the agent's final model turn was cut off (${cause}${error}) before it ` +
+		`produced any source change building '${slug}'; this is a harness failure, ` +
+		'not a judgement that there is nothing to build. Requeue to retry.'
+	);
+}
+
+function boundErrorMessage(text: string): string {
+	const oneLine = text.replace(/\s+/g, ' ').trim();
+	return oneLine.length <= MAX_CUT_OFF_ERROR_LENGTH
+		? oneLine
+		: `${oneLine.slice(0, MAX_CUT_OFF_ERROR_LENGTH)}…`;
+}
+
+/**
+ * The CUT-OFF-TURN guard in front of the empty-diff STOP backstop (task
+ * `a-truncated-agent-turn-routes-as-agent-failed`): returns the `agent-failed`
+ * detail when the run's final model turn was cut off ({@link CutOffTurn}), the
+ * agent raised NO in-band STOP sentinel, AND the work branch is empty; else
+ * `undefined` (the caller proceeds to its usual STOP resolution / gate).
+ *
+ * Only a NORMAL end of turn may reach the empty-diff backstop: that route reads
+ * an empty diff as the agent's deliberate "nothing to build" and surfaces a
+ * DISPOSE-defaulted question, which for a truncated turn puts a real, unbuilt
+ * task one default answer away from `tasks/cancelled/`. A sentinel still wins
+ * (the agent DID report a deliberate STOP), and a non-empty diff still goes to
+ * the gate (the gate, not the stop reason, judges built work). Shared by `do`
+ * (in-place and remote, hence the CI agent phase) and `run` so every path with
+ * the empty-diff backstop applies the same rule.
+ */
+export async function resolveCutOffTurnFailure(params: {
+	cutOffTurn: CutOffTurn | undefined;
+	output: string | undefined;
+	slug: string;
+	cwd: string;
+	arbiter: string;
+	env?: NodeJS.ProcessEnv;
+}): Promise<string | undefined> {
+	const {cutOffTurn, output, slug, cwd, arbiter, env} = params;
+	if (cutOffTurn === undefined) {
+		return undefined;
+	}
+	if (parseStopSentinel(output) !== undefined) {
+		return undefined;
+	}
+	if (!(await isWorkBranchDiffEmpty({cwd, arbiter, env}))) {
+		return undefined;
+	}
+	return cutOffTurnFailureDetail(slug, cutOffTurn);
+}
+
 /**
  * The DISCRIMINATED classification of a `saveAgentStop` reason (spec
  * `surface-stuck-as-questions-and-retire-stuck-lock-state` resolved decision #2,