dorfl 0.14.2 → 0.15.0

package/src/frontmatter.ts

@@ -157,19 +157,172 @@ function extractBlock(content: string): string | undefined {
 	return lines.slice(1, closing).join('\n');
 }
 
-/** Strip surrounding single or double quotes from a scalar token. */
+/**
+ * Strip surrounding single or double quotes from a scalar token. A
+ * SINGLE-quoted scalar also has its one YAML escape decoded (`''` is a literal
+ * `'`), so a value written by {@link quoteYamlScalar} reads back verbatim.
+ * Double-quoted scalars keep their inner text as-is (no backslash decoding).
+ */
 function unquote(value: string): string {
 	const trimmed = value.trim();
 	if (trimmed.length >= 2) {
 		const first = trimmed[0];
 		const last = trimmed[trimmed.length - 1];
 		if ((first === '"' || first === "'") && last === first) {
-			return trimmed.slice(1, -1);
+			const inner = trimmed.slice(1, -1);
+			return first === "'" ? inner.replace(/''/g, "'") : inner;
 		}
 	}
 	return trimmed;
 }
 
+/**
+ * The read half of {@link quoteYamlScalar}, for the frontmatter readers that
+ * live outside this module (the `title:` readers in `tasking.ts` and
+ * `integration-core.ts`), so a quoted title reads back the same everywhere.
+ */
+export function unquoteYamlScalar(value: string): string {
+	return unquote(value);
+}
+
+/**
+ * Raised when a runner-side renderer is handed a value it cannot write safely
+ * into frontmatter, or when the rendered document does not read back the keys
+ * the runner meant to write (task
+ * `intake-frontmatter-title-injection-strips-origin-stamp`).
+ */
+export class FrontmatterRenderError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'FrontmatterRenderError';
+	}
+}
+
+/**
+ * Any character that can end or fold a YAML line, or any other control
+ * character: C0 controls (incl. tab, LF, CR), DEL, the C1 range (incl. NEL
+ * U+0085, a YAML 1.1 line break), and the Unicode line/paragraph separators.
+ */
+// eslint-disable-next-line no-control-regex
+const SCALAR_CONTROL_RE = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+
+/**
+ * Why `value` cannot be a one-line frontmatter scalar, or `undefined` when it
+ * can. The verdict boundaries (intake, ADR mint) use it to refuse an
+ * agent-drafted title before anything is rendered.
+ */
+export function singleLineScalarProblem(value: string): string | undefined {
+	return SCALAR_CONTROL_RE.test(value)
+		? 'must be a single line with no control characters'
+		: undefined;
+}
+
+/**
+ * THE shared quoter for agent-supplied text a runner writes into frontmatter
+ * (task `intake-frontmatter-title-injection-strips-origin-stamp`). Returns a
+ * YAML single-quoted scalar (`'...'`, an embedded `'` doubled), which is valid
+ * YAML for every one-line string and reads back verbatim through
+ * {@link unquote} (and so {@link readFrontmatterField}). A single-quoted scalar
+ * has no escape for a line break, so a value that is not one line, or holds any
+ * control character, THROWS {@link FrontmatterRenderError}: callers must reject
+ * such a value at their verdict boundary, and this throw is the backstop.
+ */
+export function quoteYamlScalar(value: string): string {
+	const problem = singleLineScalarProblem(value);
+	if (problem !== undefined) {
+		throw new FrontmatterRenderError(
+			`frontmatter value ${JSON.stringify(value)} ${problem}`,
+		);
+	}
+	return `'${value.replace(/'/g, "''")}'`;
+}
+
+/** A top-level `key: value` frontmatter line (the key grammar {@link parseFrontmatter} uses). */
+const TOP_LEVEL_KEY_RE = /^([A-Za-z0-9_.]+)\s*:\s*(.*)$/;
+
+/**
+ * The post-render RE-PARSE assertion (task
+ * `intake-frontmatter-title-injection-strips-origin-stamp`). A runner renders a
+ * document, then calls this with the frontmatter values it MEANT to write;
+ * any disagreement THROWS {@link FrontmatterRenderError}, so a document whose
+ * runner-owned keys were displaced (a closed-early fence demoting the
+ * `originTrust` stamp into the body, a smuggled duplicate `slug:`) is never
+ * emitted.
+ *
+ * For each `expected` entry: a string value means the key must appear EXACTLY
+ * ONCE as a top-level key and read back (via {@link unquote}) equal to it;
+ * `undefined` means the key must be ABSENT. The typed keys that
+ * {@link parseFrontmatter} models (`slug`, `issue`, `origin`, `originTrust`,
+ * `humanOnly`, `needsAnswers`) are ALSO cross-checked through that parser, the
+ * same reader the rest of dorfl uses. With `exact`, the frontmatter may hold no
+ * top-level key outside `expected` (for a document the runner renders whole).
+ */
+export function assertFrontmatterFields(
+	content: string,
+	expected: Readonly<Record<string, string | undefined>>,
+	options: {exact?: boolean} = {},
+): void {
+	const block = extractBlock(content);
+	if (block === undefined) {
+		throw new FrontmatterRenderError(
+			'rendered document has no frontmatter block',
+		);
+	}
+	const seen = new Map<string, string[]>();
+	for (const line of block.split('\n')) {
+		const match = TOP_LEVEL_KEY_RE.exec(line);
+		if (!match) continue;
+		const values = seen.get(match[1]) ?? [];
+		values.push(unquote(match[2]));
+		seen.set(match[1], values);
+	}
+	const fail = (detail: string): never => {
+		throw new FrontmatterRenderError(
+			`rendered frontmatter does not read back as written: ${detail}`,
+		);
+	};
+	for (const [key, want] of Object.entries(expected)) {
+		const got = seen.get(key) ?? [];
+		if (want === undefined) {
+			if (got.length > 0) fail(`'${key}' must be absent`);
+			continue;
+		}
+		if (got.length !== 1) {
+			fail(`'${key}' appears ${got.length} time(s), expected once`);
+		}
+		if (got[0] !== want) {
+			fail(
+				`'${key}' reads ${JSON.stringify(got[0])}, expected ${JSON.stringify(want)}`,
+			);
+		}
+	}
+	if (options.exact === true) {
+		for (const key of seen.keys()) {
+			if (!(key in expected)) fail(`unexpected key '${key}'`);
+		}
+	}
+	// Cross-check through the typed parser (last-wins, value-normalising), so a
+	// document that passes the line check but that dorfl would READ differently
+	// still fails.
+	const fm = parseFrontmatter(content);
+	const typed: Record<string, string | undefined> = {
+		slug: fm.slug,
+		issue: fm.issue === undefined ? undefined : String(fm.issue),
+		origin: fm.origin,
+		originTrust: fm.originTrust,
+		humanOnly: fm.humanOnly === undefined ? undefined : String(fm.humanOnly),
+		needsAnswers:
+			fm.needsAnswers === undefined ? undefined : String(fm.needsAnswers),
+	};
+	for (const [key, parsed] of Object.entries(typed)) {
+		if (key in expected && parsed !== expected[key]) {
+			fail(
+				`parsed '${key}' is ${JSON.stringify(parsed)}, expected ${JSON.stringify(expected[key])}`,
+			);
+		}
+	}
+}
+
 /**
  * Extract the `[...]` body of a YAML flow-style inline list, IGNORING anything
  * after the matching closing `]` (notably a trailing `# comment`, the documented

package/src/gc.ts

@@ -247,6 +247,30 @@ export interface RetainedJob extends GcJob {
 	reason: RetainReason;
 	/** Human-readable reason text (`RETAIN_REASON_TEXT[reason]`). */
 	reasonText: string;
+	/**
+	 * How to SAVE the retained work, for a task job (every retain reason means the
+	 * worktree holds work the arbiter lacks): `requeue <slug>` pushes it to the
+	 * work branch before releasing a crashed run's lock (task
+	 * `a-crashed-runs-local-work-is-saved-before-its-lock-is-released`). Absent
+	 * for a non-task branch.
+	 */
+	hint?: string;
+}
+
+/**
+ * The save hint {@link gc} attaches to a retained TASK job (see
+ * {@link RetainedJob.hint}), or `undefined` for any other branch.
+ */
+export function retainedWorkHint(job: GcJob): string | undefined {
+	const parsed = parseWorkBranchRef(job.branch);
+	if (parsed === undefined || parsed.namespace !== 'task') {
+		return undefined;
+	}
+	return (
+		`it holds work the arbiter lacks; if its run is dead and its lock still ` +
+		`held, \`dorfl requeue ${parsed.slug}\` saves it to ${job.branch} before ` +
+		`releasing the lock (else push ${job.branch} from ${job.dir})`
+	);
 }
 
 export interface GcOptions {
@@ -363,8 +387,9 @@ export function gc(options: GcOptions): GcResult {
 
 		const reason = result.verdict.reason ?? 'unmerged-commits';
 		const reasonText = RETAIN_REASON_TEXT[reason];
-		retained.push({...job, reason, reasonText});
-		note(`Retained ${job.slug}: ${reasonText}.`);
+		const hint = retainedWorkHint(job);
+		retained.push({...job, reason, reasonText, ...(hint ? {hint} : {})});
+		note(`Retained ${job.slug}: ${reasonText}${hint ? ` (${hint})` : ''}.`);
 	}
 
 	return {reaped, retained, sweptOrphans};

package/src/git.ts

@@ -1,6 +1,7 @@
 import {spawnSync, spawn} from 'node:child_process';
 import {existsSync, mkdirSync, statSync} from 'node:fs';
 import {delimiter, dirname, isAbsolute, join} from 'node:path';
+import {gitChildEnv} from './ci-read-token.js';
 
 /** Result of running a git (or any) command. */
 export interface RunResult {
@@ -28,7 +29,49 @@ const SYSTEM_PATH_DIRS = [
 ];
 
 /**
- * `PATH` with {@link SYSTEM_PATH_DIRS} APPENDED (caller entries kept FIRST, so a
+ * The NixOS system profiles. NixOS has no FHS `/usr/bin/git`: a system-wide git
+ * lives under `/run/current-system/sw/bin` (the NixOS system profile) or
+ * `/nix/var/nix/profiles/default/bin` (the multi-user Nix default profile), both
+ * symlinks into the Nix store. Without these, a spawn whose env has no usable
+ * `PATH` (a caller or test passing `env: {}`) cannot find git on NixOS at all.
+ * APPENDED after {@link SYSTEM_PATH_DIRS}, so the caller's own `PATH` and the FHS
+ * dirs still win; on a non-NixOS host these dirs simply do not exist and are
+ * skipped by the probe (and harmless on the spawn `PATH`).
+ */
+const NIXOS_PROFILE_DIRS = [
+	'/run/current-system/sw/bin',
+	'/nix/var/nix/profiles/default/bin',
+];
+
+/** The default fallback probe list: FHS dirs first, then the NixOS profiles. */
+const DEFAULT_FALLBACK_PATH_DIRS: readonly string[] = [
+	...SYSTEM_PATH_DIRS,
+	...NIXOS_PROFILE_DIRS,
+];
+
+/**
+ * The fallback dirs actually in use. Defaults to
+ * {@link DEFAULT_FALLBACK_PATH_DIRS}; replaceable ONLY via
+ * {@link setFallbackPathDirsForTest}, the probe-list seam a test uses to point
+ * the fallback at a fake bin dir.
+ */
+let fallbackPathDirs: readonly string[] = DEFAULT_FALLBACK_PATH_DIRS;
+
+/**
+ * Replace the fallback probe list (tests only); pass `undefined` to restore the
+ * default. Clears the {@link resolveGitBinary} cache so no stale resolution from
+ * the previous list survives.
+ */
+export function setFallbackPathDirsForTest(
+	dirs: readonly string[] | undefined,
+): void {
+	fallbackPathDirs = dirs ?? DEFAULT_FALLBACK_PATH_DIRS;
+	gitBinaryCache.clear();
+}
+
+/**
+ * `PATH` with the fallback dirs ({@link SYSTEM_PATH_DIRS}, then
+ * {@link NIXOS_PROFILE_DIRS}) APPENDED (caller entries kept FIRST, so a
  * pinned tool earlier on `PATH` still wins; missing system dirs are added, not
  * substituted). Deduplicated, preserving first-seen order.
  */
@@ -37,7 +80,7 @@ function pathWithSystemDirs(path: string | undefined): string {
 	const out: string[] = [];
 	for (const dir of [
 		...(path ? path.split(delimiter) : []),
-		...SYSTEM_PATH_DIRS,
+		...fallbackPathDirs,
 	]) {
 		if (dir !== '' && !seen.has(dir)) {
 			seen.add(dir);
@@ -85,7 +128,9 @@ export function resetResolvedGitBinaryForTest(): void {
  *   2. a probe of the env's OWN `PATH` FIRST (so a shim / pinned git earlier on
  *      `PATH` wins), then the standard system dirs APPENDED — so `/usr/bin/git`
  *      is still found when the caller dropped `/usr/bin`, but never AHEAD of the
- *      caller's own entries.
+ *      caller's own entries. LAST come the NixOS system profiles
+ *      ({@link NIXOS_PROFILE_DIRS}), so git resolves on NixOS even when the env
+ *      carries no `PATH` at all.
  *
  * Falls back to the bare name `'git'` when nothing resolves (git genuinely
  * absent) so the spawn still runs and produces the diagnostic path. Cached PER
@@ -145,8 +190,13 @@ function resolveSpawn(
 	env: NodeJS.ProcessEnv,
 ): {command: string; env: NodeJS.ProcessEnv} {
 	const hardenedEnv = envWithSystemPath(env);
-	const resolved = command === 'git' ? resolveGitBinary(hardenedEnv) : command;
-	return {command: resolved, env: hardenedEnv};
+	if (command !== 'git') {
+		return {command, env: hardenedEnv};
+	}
+	// In the CI `agent` phase, the job's read token rides on this ONE git child
+	// process (never `.git/config`); a no-op otherwise. See `ci-read-token.ts`.
+	const gitEnv = gitChildEnv(hardenedEnv);
+	return {command: resolveGitBinary(gitEnv), env: gitEnv};
 }
 
 /**
@@ -261,6 +311,34 @@ export function git(
 	return result.stdout;
 }
 
+/**
+ * Run `git <args>` in `cwd` and return its stdout as raw BYTES (no text
+ * decoding), for output that mixes headers with object contents (`cat-file
+ * --batch`). Throws on a non-zero exit, like {@link git}.
+ */
+export function gitBytes(
+	args: string[],
+	cwd: string,
+	options: {input?: string; env?: NodeJS.ProcessEnv} = {},
+): Buffer {
+	const {command: exe, env} = resolveSpawn('git', options.env ?? process.env);
+	const result = spawnSync(exe, args, {
+		cwd,
+		input: options.input,
+		env,
+		maxBuffer: 64 * 1024 * 1024,
+	});
+	if (result.error) {
+		throw new Error(spawnErrorMessage('git', exe, env, result.error));
+	}
+	if (result.status !== 0) {
+		throw new Error(
+			`git ${args.join(' ')} failed (exit ${result.status}): ${String(result.stderr).trim()}`,
+		);
+	}
+	return result.stdout;
+}
+
 /**
  * Move a tracked file with `git mv`, creating the destination directory first
  * (`mkdir -p`). The `work/` contract requires this: git does not track empty

package/src/harness.ts

@@ -1,4 +1,6 @@
 import {spawnSync} from 'node:child_process';
+import {agentEnvFor} from './agent-env.js';
+import {assertAgentOrRepoCodeAllowed} from './phase.js';
 
 /**
  * The **harness seam** (ADR §5): how a job's command is launched and how its
@@ -214,17 +216,32 @@ export interface LaunchResult {
 	 * **The model OUTPUT-CAP signal** (observation
 	 * `tasker-review-edits-payload-caps-the-verdict-response`): present iff the
 	 * adapter detected the agent's final assistant turn was TRUNCATED at the
-	 * model's output-token cap before it finished — i.e. its `stop_reason` is not a
-	 * natural turn-end (`null`/`None`/`max_tokens`) AND it produced a positive
-	 * `usage.output` token count. The value is that token count (the observed cap).
+	 * model's output-token cap before it finished — i.e. its stop reason is the
+	 * cap signal (pi's `stopReason: 'length'`, or a raw `max_tokens`) AND it
+	 * produced a positive `usage.output` token count. A normal end, an error, or no
+	 * recorded stop reason is NOT a cap. The value is that token count (the observed cap).
 	 * A gate that fails to parse a verdict AND sees this signal names the failure
 	 * a cap-truncation (NOT a generic parse error) so an operator does not mis-read
 	 * it as a model flake and retry blindly. `undefined` when the adapter has no
-	 * usage/stop_reason telemetry (the null/shell adapter) or the turn ended
-	 * naturally — in which case a parse failure stays the generic `ReviewParseError`
+	 * usage/stop-reason telemetry (the null/shell adapter) or the turn did not
+	 * hit the cap — in which case a parse failure stays the generic `ReviewParseError`
 	 * (still needs-attention, NEVER a silent approve).
 	 */
 	outputCapped?: number;
+	/**
+	 * **The agent's FINAL model turn was CUT OFF** (task
+	 * `a-truncated-agent-turn-routes-as-agent-failed`, observation
+	 * `a-truncated-model-turn-is-read-as-nothing-to-do-and-defaults-to-cancel`):
+	 * present iff the LAST assistant message of the run (whatever it carried: text,
+	 * a tool call, or only a thinking block) ended with a `length` (the per-turn
+	 * output-token cap) or `error` (a provider error) stop rather than a normal end
+	 * of turn. The run ending there is a HARNESS failure, not the agent's judgement
+	 * that there was nothing to build, so the build pipelines route an empty diff
+	 * with this signal as `agent-failed` instead of the empty-diff STOP backstop.
+	 * `undefined` when the final turn ended normally or the adapter has no
+	 * stop-reason telemetry (the null/shell adapter).
+	 */
+	cutOffTurn?: CutOffTurn;
 	/**
 	 * **The verified outcome of reaping the agent's process TREE** after a deadline
 	 * stop (observation
@@ -242,6 +259,17 @@ export interface LaunchResult {
 	reap?: AgentTreeReap;
 }
 
+/**
+ * Why the agent's final model turn ended abnormally (see
+ * {@link LaunchResult.cutOffTurn}): `length` = the turn hit the model's per-turn
+ * output-token cap; `error` = the provider ended the turn with an error.
+ * `errorMessage` is the provider's error text when the session recorded one.
+ */
+export interface CutOffTurn {
+	cause: 'length' | 'error';
+	errorMessage?: string;
+}
+
 /**
  * The harness-reported result of reaping a stopped agent's process tree — the
  * adapter-agnostic projection of `reap-agent-tree.ts`'s `ReapResult`.
@@ -296,6 +324,26 @@ export function isBenignPromptWriteError(error: Error): boolean {
 	return (error as NodeJS.ErrnoException).code === 'EPIPE';
 }
 
+/**
+ * The environment an autonomous AGENT is launched with. In GitHub Actions every
+ * GitHub credential is removed (`GH_TOKEN`, `GITHUB_TOKEN`, `DORFL_GH_TOKEN`,
+ * any value containing a GitHub token, the Actions OIDC/runtime tokens, the
+ * runner command files, and git env config carrying a credential; see
+ * `agent-env.ts`). Applied INSIDE every adapter's autonomous launch, so no
+ * caller and no workflow can hand a CI agent the token by accident. On a laptop
+ * the caller's env passes through unchanged.
+ *
+ * PHASE GUARD: throws a `PhaseGuardError` in the CI `lock` and `apply` phases
+ * (their jobs hold the write token, so no agent may launch there; see
+ * `phase.ts`).
+ */
+export function agentLaunchEnv(
+	env: NodeJS.ProcessEnv | undefined,
+): NodeJS.ProcessEnv {
+	assertAgentOrRepoCodeAllowed('agent-launch-env');
+	return agentEnvFor(env ?? process.env);
+}
+
 /**
  * The **null adapter**: runs the configured command synchronously to completion
  * in the job dir, recording the PID. Liveness is `process.kill(pid, 0)` against
@@ -307,6 +355,8 @@ export class NullHarness implements Harness {
 	readonly adapter = 'null';
 
 	launch(input: LaunchInput): LaunchResult {
+		// PHASE GUARD first: no launch at all in the CI lock/apply phases.
+		assertAgentOrRepoCodeAllowed('harness-launch');
 		// BACKSTOP (config error, NOT a spawn failure): an empty/whitespace command
 		// resolves the null adapter to `bash -c ''`, which exits 0 with no output — a
 		// "successful" build that ran NOTHING. The `do`/`run`/`--remote` CLI sites
@@ -328,7 +378,8 @@ export class NullHarness implements Harness {
 			cwd: input.dir,
 			encoding: 'utf8',
 			input: input.prompt,
-			env: input.env ?? process.env,
+			// No GitHub token reaches a CI agent (see agentLaunchEnv).
+			env: agentLaunchEnv(input.env),
 			maxBuffer: 64 * 1024 * 1024,
 		});
 		if (result.error && !isBenignPromptWriteError(result.error)) {
@@ -366,6 +417,7 @@ export class NullHarness implements Harness {
 	 * shelling out the wrong way.
 	 */
 	launchInteractive(_input: InteractiveLaunchInput): InteractiveLaunchResult {
+		assertAgentOrRepoCodeAllowed('harness-launch');
 		throw new Error(
 			'interactive launch requires the pi harness; configure `harness: pi` ' +
 				'(the null/shell adapter only supports the captured autonomous launch).',

package/src/index.ts

@@ -200,6 +200,50 @@ export type {
 	LedgerWriteStrategy,
 } from './ledger-write.js';
 export {currentLedgerWrite, ledgerWrite} from './ledger-write.js';
+export type {
+	RefWriteStrategy,
+	LockRefCreateInput,
+	LockRefDeleteInput,
+	ContinuedBranchPushInput,
+	TaskingCandidatesPushInput,
+} from './ref-write.js';
+export {currentRefWrite, refWrite} from './ref-write.js';
+
+export type {Phase, GuardedOperation} from './phase.js';
+export {
+	PHASES,
+	AGENT_SPAWNING_VERBS,
+	NON_AGENT_VERBS,
+	PhaseGuardError,
+	PhaseUsageError,
+	parsePhase,
+	activePhase,
+	enterPhase,
+	assertAgentOrRepoCodeAllowed,
+} from './phase.js';
+export type {
+	WriteSeamName,
+	WriteSeamCall,
+	RecordedWriteIntent,
+	PhaseRecorder,
+	AgentPhaseOutcome,
+} from './phase-recorder.js';
+export {
+	PhaseHaltSentinel,
+	UnrecordedWriteError,
+	createPhaseRecorder,
+	installRecordingSeams,
+	recordingReviewProvider,
+	recordingIssueProvider,
+	runAgentPhase,
+	activateProcessPhase,
+} from './phase-recorder.js';
+export {
+	resolveReadToken,
+	readTokenHeaderKey,
+	withReadTokenGitConfig,
+	gitChildEnv,
+} from './ci-read-token.js';
 
 export type {ReadyItem, ScannedItem, RepoReport, ScanReport} from './scan.js';
 export {scan, scanRepoPaths, readReadyItems, readDoneSlugs} from './scan.js';
@@ -331,6 +375,7 @@ export type {
 	ReleaseHeldResult,
 	LockReportEntry,
 	ItemLockReport,
+	LockKeptFor,
 } from './item-lock.js';
 export {
 	LOCK_REF_PREFIX,
@@ -352,6 +397,9 @@ export {
 	listItemLocks,
 	listItemLockEntries,
 	heldTaskSlugs,
+	proposeKeptTaskSlugs,
+	markLockKeptForProposePr,
+	takeOverProposeKeptLock,
 	resolveLockHolder,
 	serialiseLockEntry,
 	parseLockEntry,
@@ -501,6 +549,7 @@ export {
 	encodeWorkId,
 	jobWorktreePath,
 	createJob,
+	RetainedWorktreeUnsavedWorkError,
 	writeJobRecord,
 	readJobRecord,
 	updateJobRecord,
@@ -797,7 +846,7 @@ export {
 	resolveCIConfig,
 	exportCIConfig,
 	generateSetupAction,
-	REFRESH_OAUTH_SCRIPT,
+	AUTH_JSON_REMOVED_MESSAGE,
 	buildSetupArtifacts,
 	outputBaseName,
 	writeArtifacts,