dorfl 0.1.2 → 0.2.1

package/src/env-config.ts

@@ -100,12 +100,12 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	taskingIntegration: {enum: ['propose', 'merge']},
 	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — spec
 	// `staging-pool-position-gate-and-trust-model` US #5) coerces as the
-	// `pre-backlog`/`ready` enum, so `DORFL_TASKS_LAND_IN=ready` works and a
+	// `backlog`/`ready` enum, so `DORFL_TASKS_LAND_IN=ready` works and a
 	// typo FAILS LOUDLY. Same
 	// precedence chain as `taskingIntegration` (flag > env > per-repo > global >
-	// built-in `pre-backlog`); fed into the runner-deterministic placement
+	// built-in `backlog`); fed into the runner-deterministic placement
 	// resolver (`src/placement.ts`) as the configured-default rung.
-	tasksLandIn: {enum: ['pre-backlog', 'ready']},
+	tasksLandIn: {enum: ['backlog', 'ready']},
 	// `specsLandIn` (the per-repo SPEC-PLACEMENT default — spec
 	// `staging-pool-position-gate-and-trust-model` US #2/#5) coerces as the
 	// `pre-proposed`/`ready` enum, so `DORFL_SPECS_LAND_IN=ready` works and a typo
@@ -113,7 +113,7 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// > global > built-in `pre-proposed`); fed into the shared placement resolver
 	// (`src/placement.ts`) as the configured-default rung for the spec lifecycle.
 	// The legacy `prdsLandIn` key / `DORFL_PRDS_LAND_IN` env are GONE after the
-	// `prd` → `spec` hard cutover (clean break).
+	// ''prd'' → `spec` hard cutover (clean break).
 	specsLandIn: {enum: ['pre-proposed', 'ready']},
 	// `noPR` (the PR-INTENT axis) is a BOOLEAN coercion (like `review`), so
 	// `DORFL_NO_PR=true|false` works and a typo FAILS LOUDLY. The removed
@@ -152,6 +152,14 @@ const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
 	// works and a typo FAILS LOUDLY. Default OFF; ON re-surfaces the
 	// merge-question on a merge-base change instead of auto-landing.
 	strictMergeApproval: 'boolean',
+	// The dorfl-INTERNAL agent deadline (minutes) — spec
+	// `graceful-pre-timeout-wip-checkpoint`. NUMBER coercion (like
+	// `reviewMaxRounds`); range validation is fail-loud in `validateDeadlineConfig`
+	// (not clamped here). Env is a per-machine source, so CI can override the
+	// per-repo default without a config edit: `DORFL_AGENT_DEADLINE_MINUTES=90`.
+	agentDeadlineMinutes: 'number',
+	checkpointHeadroomMinutes: 'number',
+	maxAutoCheckpoints: 'number',
 	// `promptGuidance` is a STRUCTURED (nested) namespace, so it has no scalar env
 	// var of its own — each MEMBER carries its own env var (the nested-key form
 	// `DORFL_PROMPT_GUIDANCE_<MEMBER>`), handled out-of-band in

package/src/failure-cause.ts

@@ -2,7 +2,8 @@
  * **The failure-CAUSE classifier** (task `failure-cause-classification-model-vs-
  * git-vs-agent`).
  *
- * When a claimed item routes to `work/needs-attention/`, the runner records WHY.
+ * When a claimed item is marked stuck on its per-item lock (post lock-cutover —
+ * `state: stuck`, no `work/needs-attention/` folder write), the runner records WHY.
  * Historically several DIFFERENT causes collapsed into one undifferentiated label
  * ("agent failed"), even though the CAUSE drives the RECOVERY:
  *
@@ -49,6 +50,7 @@
  */
 export type FailureCause =
 	| 'transient-infra' // a harness-surfaced model/connection outage (post-retry), or a git/provider outage — RETRY the same work
+	| 'needs-reauth' // a credential expired / was revoked (e.g. OAuth refresh token) — RETRY CANNOT help; a human must RE-AUTH
 	| 'config-error' // a thrown CORE wiring/config error (e.g. review on, no reviewGate) — fix the WIRING
 	| 'agent-failed'; // the conservative generic: the agent ran but produced bad/empty output, OR the cause is UNKNOWN
 
@@ -65,6 +67,24 @@ const CONFIG_ERROR_SIGNATURES = [
 	/no review gate is configured/i,
 ];
 
+/**
+ * Substrings that mark a CREDENTIAL-EXPIRY failure surfaced by the harness: an
+ * OAuth refresh token has expired or been revoked, or a 401 came back tagged
+ * `authentication_required`. Retry cannot help these — only a human RE-AUTH can.
+ * Kept SEPARATE from `TRANSIENT_INFRA_SIGNATURES` (see ADR
+ * `transient-infra-and-needs-reauth-routing`) so downstream routing can branch
+ * cleanly on the cause: retry-with-backoff for infra, straight to a needs-reauth
+ * surface for credentials. Conservative: unrelated 401s that don't mention auth /
+ * token stay `agent-failed`.
+ */
+const NEEDS_REAUTH_SIGNATURES = [
+	/authentication_required/i,
+	/OAuth (?:refresh )?token (?:expired|revoked|invalid)/i,
+	/refresh token (?:expired|revoked|invalid)/i,
+	/\b401\b[^\n]{0,80}(?:auth|token|credential|unauthori[sz]ed)/i,
+	/(?:auth|token|credential)[^\n]{0,40}\b401\b/i,
+];
+
 /**
  * Substrings that mark a TRANSIENT-INFRA failure: a model endpoint / connection
  * outage the harness surfaced AFTER exhausting its own retries, or a git/provider
@@ -117,6 +137,13 @@ export function classifyFailureCause(detail: string | undefined): FailureCause {
 	if (CONFIG_ERROR_SIGNATURES.some((re) => re.test(text))) {
 		return 'config-error';
 	}
+	// Credential-expiry is checked BEFORE `transient-infra` because a 401 body may
+	// also mention words like "unavailable"/network, and no amount of retry helps
+	// — a human must re-auth. Kept as its own cause per ADR
+	// `transient-infra-and-needs-reauth-routing`.
+	if (NEEDS_REAUTH_SIGNATURES.some((re) => re.test(text))) {
+		return 'needs-reauth';
+	}
 	if (TRANSIENT_INFRA_SIGNATURES.some((re) => re.test(text))) {
 		return 'transient-infra';
 	}
@@ -134,6 +161,8 @@ export function failureCauseLabel(cause: FailureCause): string {
 	switch (cause) {
 		case 'transient-infra':
 			return 'transient infra';
+		case 'needs-reauth':
+			return 'needs re-auth (credential expired)';
 		case 'config-error':
 			return 'config error';
 		case 'agent-failed':

package/src/format.ts

@@ -117,40 +117,20 @@ function cwdDivergenceLine(
  * consistency rule): the two reads have different freshness + storage models.
  */
 /**
- * Render ONE held per-item lock entry (action × state + reason/questions) as
- * indented lines, the SHARED renderer for the in-flight lock surface on BOTH the
- * registry view (`formatStatus`) and the cwd section (`formatCwdSection`), so the
- * two substrates present a held/stuck item identically (NOT a forked renderer). An
- * `active` hold reads as `in-progress`; a `stuck` hold as `needs-attention` and
- * carries its (possibly multi-line) reason + any surfaced questions.
+ * Render ONE held per-item lock entry as an indented line, the SHARED renderer
+ * for the in-flight lock surface on BOTH the registry view (`formatStatus`) and
+ * the cwd section (`formatCwdSection`). Post-`retire-stuck-lock-state` the
+ * lock state is degenerate (`active` only) — a held lock is always an
+ * in-progress hold; a parked item is a `needsAnswers:true` pool item on `main`
+ * with a sidecar, rendered by the pool categoriser (NOT here).
  */
 export function formatLockEntryLines(
 	entry: LockEntry,
 	indent: string,
 ): string[] {
-	const lines: string[] = [];
-	const view = entry.state === 'stuck' ? 'needs-attention' : 'in-progress';
-	lines.push(
-		`${indent}${entry.entry}   (${entry.action}/${entry.state} = ${view})`,
-	);
-	if (entry.state === 'stuck') {
-		const reason =
-			entry.reason && entry.reason !== ''
-				? entry.reason
-				: '(no reason recorded)';
-		const reasonLines = reason.split('\n');
-		lines.push(`${indent}  reason: ${reasonLines[0]}`);
-		for (const extra of reasonLines.slice(1)) {
-			lines.push(`${indent}    ${extra}`);
-		}
-		if (entry.questions && entry.questions.length > 0) {
-			lines.push(`${indent}  questions:`);
-			for (const q of entry.questions) {
-				lines.push(`${indent}    - ${q}`);
-			}
-		}
-	}
-	return lines;
+	return [
+		`${indent}${entry.entry}   (${entry.action}/${entry.state} = in-progress)`,
+	];
 }
 
 export function formatCwdSection(section: CwdSection): string[] {
@@ -214,7 +194,7 @@ export function formatCwdSection(section: CwdSection): string[] {
 	const lockHeld = section.repo.lockHeld ?? [];
 	if (lockHeld.length > 0) {
 		lines.push('');
-		lines.push('    In progress / stuck (lock held — refs/dorfl/lock/*):');
+		lines.push('    In progress (lock held — refs/dorfl/lock/*):');
 		for (const entry of lockHeld) {
 			lines.push(...formatLockEntryLines(entry, '      '));
 		}

package/src/frontmatter.ts

@@ -7,8 +7,8 @@
 
 /**
  * **Origin-trust PROVENANCE** (task `untrusted-origin-forces-build-propose`).
- * How a prd/task was BORN and the AUTHOR-TRUST verdict at birth, stamped so the
- * signal SURVIVES the prd/task merge boundary (a landed-on-`main` artifact would
+ * How a spec/task was BORN and the AUTHOR-TRUST verdict at birth, stamped so the
+ * signal SURVIVES the spec/task merge boundary (a landed-on-`main` artifact would
  * otherwise erase how it was created — the laundering gap).
  *
  * - `origin` — `human` (the default / unset: a human authored it locally; a local
@@ -48,8 +48,8 @@ export interface Frontmatter {
 	 * spec lives at `work/specs/ready/<spec>.md`. The `spec` vocabulary name (spec
 	 * `prd-to-spec-vocabulary-cutover-and-migration-command`). `parseFrontmatter`
 	 * populates it from the canonical `spec:` key ONLY — the HARD CUTOVER (the last
-	 * `prd` back-compat surface removed): the legacy `prd:` KEY read is GONE, so an
-	 * un-migrated `prd:` field no longer silently resolves. A downstream repo
+	 * ''prd'' back-compat surface removed): the legacy ''prd:'' KEY read is GONE, so
+	 * an un-migrated ''prd:'' field no longer silently resolves. A downstream repo
 	 * migrates its data with `dorfl prd-to-spec` (a purely TEXTUAL `prd: → spec:`
 	 * rewrite that does NOT go through this parser), after which the field reads
 	 * canonically. There is no `fm.prd` FIELD.
@@ -292,6 +292,36 @@ export function setFrontmatterMarker(
 	return lines.join('\n');
 }
 
+/**
+ * Read ONE arbitrary top-level scalar frontmatter key by name, returning its
+ * unquoted value (or `undefined` when the doc has no fence, or the key is absent).
+ *
+ * A general-purpose companion to {@link parseFrontmatter} for keys that are NOT in
+ * the modelled {@link Frontmatter} shape — e.g. the observation→task provenance
+ * back-reference `promotedFrom:` the triage-promote path stamps and the create-CAS
+ * lost-race disambiguation reads (task
+ * `observation-triage-already-triaged-benign-skip`). Only top-level `key: value`
+ * lines are matched (block-list / nested values are out of scope for a scalar read).
+ */
+export function readFrontmatterField(
+	content: string,
+	key: string,
+): string | undefined {
+	const block = extractBlock(content);
+	if (block === undefined) {
+		return undefined;
+	}
+	const pattern = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+	for (const line of block.split('\n')) {
+		const match = pattern.exec(line);
+		if (match) {
+			const value = unquote(match[1]);
+			return value === '' ? undefined : value;
+		}
+	}
+	return undefined;
+}
+
 /**
  * PROPAGATE the origin-trust PROVENANCE (`origin` + `originTrust`) from a SOURCE
  * artifact (a spec) onto a TARGET artifact's content (an emitted task), returning
@@ -374,7 +404,7 @@ export function parseFrontmatter(content: string): Frontmatter {
 		} else if (key === 'spec') {
 			// The parent-spec pointer, read from the canonical `spec:` key ONLY into the
 			// `fm.spec` field (spec `prd-to-spec-vocabulary-cutover-and-migration-command`,
-			// HARD CUTOVER). The legacy `prd:` KEY read is GONE — an un-migrated `prd:`
+			// HARD CUTOVER). The legacy ''prd:'' KEY read is GONE — an un-migrated ''prd:''
 			// field no longer resolves here; a repo converts its data via the TEXTUAL
 			// `dorfl prd-to-spec` rewrite (which does not use this parser). An empty value
 			// leaves the field undefined.

package/src/gc.ts

@@ -8,7 +8,9 @@ import {
 	removeJobRecord,
 	type JobRecord,
 } from './workspace.js';
-import {workBranchRef} from './slug-namespace.js';
+import {parseWorkBranchRef, workBranchRef} from './slug-namespace.js';
+import {terminalMainPaths} from './item-lock.js';
+import type {SidecarType} from './sidecar.js';
 
 /**
  * The **reaper** for job worktrees, governed by the **provably-safe deletion
@@ -140,8 +142,23 @@ export function evaluateDeletionSafety(
 
 	const localTip = revParse(input.dir, 'HEAD', env);
 
-	// 2a. Merged: the tip is an ancestor of <arbiter>/main.
-	if (isAncestor(input.dir, localTip, `refs/remotes/${arbiter}/main`, env)) {
+	// 2a. Merged: the tip is provably on <arbiter>/main — either a plain
+	//     ancestor (fast path) OR squash-aware-equivalent (the durable done/
+	//     dropped record is on main AND the branch carries nothing main lacks).
+	const arbiterMainRef = `refs/remotes/${arbiter}/main`;
+	const reapIdentity = reapIdentityFromBranch(input.branch);
+	if (
+		reapIdentity !== undefined
+			? isProvablyMergedForReap({
+					cwd: input.dir,
+					tip: localTip,
+					arbiterMain: arbiterMainRef,
+					namespace: reapIdentity.namespace,
+					slug: reapIdentity.slug,
+					env,
+				})
+			: isAncestor(input.dir, localTip, arbiterMainRef, env)
+	) {
 		return {safe: true, reachableVia: 'merged'};
 	}
 
@@ -432,14 +449,160 @@ function fetchTracking(
 	);
 }
 
+/**
+ * Extract the `{namespace, slug}` identity a reap decision needs from a work
+ * branch ref (`work/[<producer>-]<type>-<slug>`). Returns `undefined` for a
+ * non-namespaced branch — the caller then falls back to the ancestry-only
+ * fast-path (the squash-aware fallback has no anchor without an identity to
+ * look up on `<arbiter>/main`, so the safe direction is the strict old rule).
+ */
+function reapIdentityFromBranch(
+	branch: string,
+): {namespace: SidecarType; slug: string} | undefined {
+	const parsed = parseWorkBranchRef(branch);
+	if (parsed === undefined) {
+		return undefined;
+	}
+	// `SlugNamespace` and `SidecarType` share the same three members
+	// (`'task' | 'spec' | 'observation'`); the cast is structural.
+	return {namespace: parsed.namespace as SidecarType, slug: parsed.slug};
+}
+
+/** Input for {@link isProvablyMergedForReap}. */
+export interface ProvablyMergedForReapInput {
+	/** The local repo the git predicates run in. */
+	cwd: string;
+	/** The candidate branch tip (a 40-hex sha or a resolvable ref). */
+	tip: string;
+	/**
+	 * The arbiter's main as a ref RESOLVABLE INSIDE `cwd` — a fetched
+	 * remote-tracking ref (`refs/remotes/<arbiter>/main`) or short-form
+	 * (`<arbiter>/main`). Callers are responsible for the fetch (best-effort;
+	 * an unresolvable ref reads as not-provable ⇒ false).
+	 */
+	arbiterMain: string;
+	/**
+	 * The item's type (task/spec/observation) — used to look up the durable
+	 * terminal records on `<arbiter>/main`. Reap decisions on a
+	 * `work/<type>-<slug>` branch pass the parsed type from
+	 * {@link parseWorkBranchRef}.
+	 */
+	namespace: SidecarType;
+	/** The item's bare slug — the anchor for the squash-aware fallback. */
+	slug: string;
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The **squash-aware, provably-merged predicate** used to decide reap-safety
+ * across the workspace: `gc.ts`'s worktree reaper, `reap-branches.ts`'s remote
+ * `work/*` sweep, `integrator.ts`'s post-merge remote-head reap, and
+ * `complete.ts`'s local-branch reap. ONE decision point so the two rules can
+ * never drift apart, and NEVER `--force` — a merged-for-reap ref needs none.
+ *
+ * A remote/local `work/<slug>` branch is reapable iff EITHER:
+ *
+ *   1. **Fast path (unchanged).** `git merge-base --is-ancestor <tip>
+ *      <arbiter>/main` succeeds — the fast-forward / true-merge land case.
+ *   2. **Squash-aware fallback (new).** BOTH of the following hold:
+ *      - the item is TERMINAL on `<arbiter>/main` — i.e. the matching
+ *        {@link terminalMainPaths} (`work/tasks/done/<slug>.md` or
+ *        `work/tasks/cancelled/<slug>.md` for a task; `work/specs/tasked/…`
+ *        or `work/specs/dropped/…` for a spec) exists in the fetched main
+ *        tree; AND
+ *      - the branch carries NOTHING main lacks — either `git diff --quiet
+ *        <arbiter>/main <tip>` reads clean (content-equal / content-subset)
+ *        OR `git cherry <arbiter>/main <tip>` reports every commit as
+ *        already applied by patch-id (`-` on every line, catching
+ *        rebase-lands the tree check misses).
+ *
+ * Grounding: the durable `<arbiter>/main` record is authoritative. It is what
+ * `complete` writes FIRST, so if the terminal record is there the item's work
+ * is at rest, and a branch that carries nothing main lacks has no in-flight
+ * work to protect. The safety floor is unchanged: NEVER reap an in-flight /
+ * unmerged branch (no terminal record ⇒ retain), NEVER reap a branch carrying
+ * commits main lacks (content check fails ⇒ retain), NEVER `--force`.
+ *
+ * This is the branch-side twin of the lock-side terminal-on-main recovery
+ * (`isTerminalOnMain` in `item-lock.ts`): same anchor, different subject.
+ */
+export function isProvablyMergedForReap(
+	input: ProvablyMergedForReapInput,
+): boolean {
+	const {cwd, tip, arbiterMain, namespace, slug, env} = input;
+
+	// 1. Fast path — the fast-forward / true-merge land case. Cheap: one
+	//    `git merge-base --is-ancestor`.
+	if (isAncestor(cwd, tip, arbiterMain, env)) {
+		return true;
+	}
+
+	// 2. Squash-aware fallback. Anchor: the durable terminal record on
+	//    `<arbiter>/main`. No terminal record ⇒ the item is still in-flight (or
+	//    an observation, which has no terminal folder) ⇒ retain (never reap
+	//    in-flight work).
+	if (!terminalRecordOnMain(cwd, arbiterMain, namespace, slug, env)) {
+		return false;
+	}
+
+	// 2a. Content-subset: `git diff --quiet <arbiterMain> <tip>` clean ⇒ the
+	//     two trees are identical, so the branch carries nothing main lacks
+	//     (the incident shape: the branch is a since-lagged snapshot of a
+	//     squash-landed item, no new content on it).
+	const diff = run('git', ['diff', '--quiet', arbiterMain, tip], cwd, {env});
+	if (diff.status === 0) {
+		return true;
+	}
+
+	// 2b. Patch-id equivalence via `git cherry <upstream> <head>`: every commit
+	//     reachable from `<tip>` but not `<arbiterMain>` is reported as `-`
+	//     (already applied upstream by patch-id). This catches rebase-lands
+	//     where the tree diff is non-empty but every commit is already on main
+	//     under a different sha.
+	const cherry = run('git', ['cherry', arbiterMain, tip], cwd, {env});
+	if (cherry.status === 0) {
+		const lines = cherry.stdout
+			.split('\n')
+			.map((l) => l.trim())
+			.filter((l) => l !== '');
+		if (lines.length > 0 && lines.every((l) => l.startsWith('- '))) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/** True iff `<arbiterMain>` carries ANY of the item's durable terminal records
+ * ({@link terminalMainPaths}). Best-effort: `cat-file -e` is a cheap tree
+ * probe; an unresolvable `<arbiterMain>` reads as no-record ⇒ retain (the safe
+ * direction). Observations have no terminal folder ⇒ always false. */
+function terminalRecordOnMain(
+	cwd: string,
+	arbiterMain: string,
+	namespace: SidecarType,
+	slug: string,
+	env: NodeJS.ProcessEnv | undefined,
+): boolean {
+	for (const path of terminalMainPaths(namespace, slug)) {
+		const res = run('git', ['cat-file', '-e', `${arbiterMain}:${path}`], cwd, {
+			env,
+		});
+		if (res.status === 0) {
+			return true;
+		}
+	}
+	return false;
+}
+
 /**
  * True iff `ancestor` is an ancestor of (or equal to) `descendant`, both
- * resolved IN the local repo `dir` (`git merge-base --is-ancestor`). This is the
- * ONE provably-merged reachability predicate in the system: the worktree reaper
- * above uses it for `<tip> --is-ancestor <arbiter>/main`, and the remote
- * merged-branch sweep (`reap-branches.ts`) REUSES it (not a second predicate) to
- * decide a remote `work/<slug>` branch is provably merged before deleting it.
- * EXPORTED so that single source of truth is shared, never forked.
+ * resolved IN the local repo `dir` (`git merge-base --is-ancestor`). The
+ * low-level fast-path building block for {@link isProvablyMergedForReap} —
+ * reap-safety decisions across the workspace go through the squash-aware
+ * wrapper, never this raw predicate. EXPORTED so callers that legitimately
+ * need pure ancestry (non-reap idempotency checks, claim-reachability guards)
+ * keep the one shared implementation.
  */
 export function isAncestor(
 	dir: string,

package/src/github.ts

@@ -209,6 +209,26 @@ export class GitHubProvider implements ReviewProvider {
 			return this.parseOpened(input, first);
 		}
 
+		// PR ALREADY EXISTS (task `committed-recovery-completes-existing-pr`): a
+		// re-pushed branch whose PR is still open makes `gh pr create` fail with
+		// "a pull request for branch ... already exists". This is NOT an outage and
+		// NOT a missing/unauth `gh` — retrying is pointless (it fails identically)
+		// and degrading to push-only would DROP the refreshed body + the Gate-2
+		// review comment on a PR that genuinely exists (the committed-recovery re-run
+		// case). Instead RESOLVE the existing PR, UPDATE its title/body to match what
+		// this run would have created, and return it as `opened` so the caller's
+		// review-comment path fires normally. NEVER throws; a failed edit still
+		// returns the resolved PR (the comment is the more important audit trail).
+		if (prAlreadyExists(first)) {
+			const existing = this.updateExistingRequest(input);
+			if (existing !== undefined) {
+				return existing;
+			}
+			// Could not resolve the existing PR's url (e.g. a transient `gh pr view`
+			// failure) — fall through to the degrade path rather than crashing; the
+			// branch is already pushed, so the work is safe.
+		}
+
 		// Failed once — distinguish DETERMINISTIC (missing/unauth) from a TRANSIENT
 		// outage by an availability probe. Missing/unauth ⇒ degrade now (no retry).
 		// Thread the FAILED first attempt so the degrade surfaces the REAL `gh` cause
@@ -246,6 +266,47 @@ export class GitHubProvider implements ReviewProvider {
 		return this.parseOpened(input, attempt.value);
 	}
 
+	/**
+	 * The PR for this branch ALREADY EXISTS (task
+	 * `committed-recovery-completes-existing-pr`): resolve its url, REFRESH its
+	 * title/body via `gh pr edit` (so a committed-recovery re-run's synthesised
+	 * title + task-pointer body replace the earlier run's blank `--fill` ones),
+	 * and return it as `{opened: true, url}` so the caller's review-comment path
+	 * fires on the existing PR. Returns `undefined` when the url cannot be
+	 * resolved (the caller then falls through to the degrade path). The `gh pr
+	 * edit` is best-effort: a failed edit still returns the resolved PR (posting
+	 * the review comment matters more than refreshing the body), and it is only
+	 * attempted when this run actually has explicit title/body to set (else the
+	 * existing PR's content is left untouched).
+	 */
+	private updateExistingRequest(
+		input: OpenRequestInput,
+	): OpenRequestResult | undefined {
+		const url = this.resolvePrUrlForBranch(input.branch, input.cwd, input.env);
+		if (url === undefined) {
+			return undefined;
+		}
+		// Refresh the PR body/title only when this run supplies them (a committed-
+		// recovery re-run does; an unset run leaves the existing content alone).
+		if (input.title !== undefined || input.body !== undefined) {
+			const editArgs = ['pr', 'edit', url];
+			if (input.title !== undefined) {
+				editArgs.push('--title', input.title);
+			}
+			if (input.body !== undefined) {
+				editArgs.push('--body', input.body);
+			}
+			// Best-effort: ignore the result. A failed edit must not lose the PR (or
+			// the upcoming review comment) — NEVER throws (runGh swallows spawn errors).
+			this.runGh(editArgs, input.cwd, input.env);
+		}
+		return {
+			opened: true,
+			url,
+			instruction: `Updated the existing GitHub PR for ${input.branch}: ${url}`,
+		};
+	}
+
 	/** Map a successful `gh pr create` RunResult to an OpenRequestResult. */
 	private parseOpened(
 		input: OpenRequestInput,
@@ -457,6 +518,23 @@ export function prCreateContentArgs(input: {
 	return ['--title', input.title ?? '', '--body', input.body ?? ''];
 }
 
+/**
+ * Does a FAILED `gh pr create` result mean "a PR for this branch already
+ * exists" (task `committed-recovery-completes-existing-pr`)? `gh` exits non-zero
+ * with a message like `a pull request for branch "work/task-x" into branch
+ * "main" already exists: https://github.com/.../pull/357`. We match on the
+ * stable "already exists" phrase in `gh`'s stderr/stdout so a re-pushed branch
+ * whose PR is still open is treated as an UPDATE, not a transient outage. A
+ * missing `gh` (`undefined`) or a success is not this case.
+ */
+function prAlreadyExists(result: RunResult | undefined): boolean {
+	if (result === undefined || result.status === 0) {
+		return false;
+	}
+	const text = `${result.stderr ?? ''}\n${result.stdout ?? ''}`.toLowerCase();
+	return text.includes('already exists');
+}
+
 /**
  * Parse the PR URL `gh pr create` prints to stdout. `gh` prints the PR URL as a
  * line (often the only/last line); we pick the first GitHub PR URL we find. Any

package/src/harness.ts

@@ -61,6 +61,21 @@ export interface LaunchInput {
 	 * `undefined` ⇒ the pi adapter falls back to a generated default for its cwd.
 	 */
 	session?: string;
+	/**
+	 * **Optional agent-session DEADLINE** (absolute epoch-ms wall-clock timestamp)
+	 * for the ASYNC {@link Harness} launch (spec
+	 * `graceful-pre-timeout-wip-checkpoint`). When set AND the future arrives
+	 * before the child exits, the harness sends SIGTERM (a ~10s grace, then
+	 * SIGKILL) and resolves the {@link LaunchResult} with `timedOut: true` — so
+	 * the caller can route the run as a CHECKPOINT (save WIP + auto-continue /
+	 * surface) rather than a generic agent-failure. Ignored on the synchronous
+	 * {@link Harness.launch} path (`spawnSync` cannot be interrupted from the
+	 * same event loop; the async path is where CI's `--watch` legs run and where
+	 * the checkpoint discipline lives). Absent ⇒ no deadline (byte-for-byte the
+	 * pre-task behaviour: a run finishing before its deadline is unchanged; on
+	 * `exit` the timer is cleared).
+	 */
+	deadlineMs?: number;
 	env?: NodeJS.ProcessEnv;
 }
 
@@ -170,6 +185,16 @@ export interface LaunchResult {
 	record: HarnessRecord;
 	/** Failure detail when `ok` is false (the stderr/failure channel). */
 	detail?: string;
+	/**
+	 * **True iff the launch was stopped by the dorfl-internal DEADLINE**
+	 * ({@link LaunchInput.deadlineMs}) rather than exiting on its own (spec
+	 * `graceful-pre-timeout-wip-checkpoint`). Distinct from `ok` (a deadline
+	 * stop is neither a success nor a generic failure — it is a CHECKPOINT the
+	 * caller routes through the save+auto-continue/surface path). Absent/false
+	 * when the child exited before the deadline, so a run that finishes
+	 * normally is byte-for-byte unchanged.
+	 */
+	timedOut?: boolean;
 	/**
 	 * The agent's final ANSWER (task `harness-agent-output`): the concatenated
 	 * `text` of the LAST assistant turn the invocation produced. This is the

package/src/index.ts

@@ -26,6 +26,8 @@ export type {
 } from './repo-config.js';
 export {
 	REPO_CONFIG_FILENAME,
+	REPO_CONFIG_FILENAME_LEGACY,
+	resolveRepoConfigPath,
 	REPO_ALLOWED_KEYS,
 	REPO_REJECTED_KEYS,
 	repoConfigPath,
@@ -783,3 +785,11 @@ export type {
 	InstallCIResult,
 } from './install-ci.js';
 export {installCI, runWizard} from './install-ci.js';
+
+export type {
+	InstallSkillsOptions,
+	InstallSkillsResult,
+	InstalledAgent,
+} from './install-skills.js';
+export {installSkills, resolveSkillsSourceDir} from './install-skills.js';
+export type {Agent} from './vendor/incur/agents.js';