dorfl 0.12.0 → 0.13.1

package/src/advance.ts

@@ -32,10 +32,13 @@ import type {ObservationTriage} from './config.js';
 import {
 	autoDispositionObservation,
 	promoteObservation,
+	stampTriagedMarker,
 	type AutoDispositionOptions,
 	type AutoDispositionResult,
 	type PromoteObservationOptions,
 	type PromoteObservationResult,
+	type StampTriagedMarkerOptions,
+	type StampTriagedMarkerResult,
 } from './triage-persist.js';
 import {mintAdr, type MintAdrOptions, type MintAdrResult} from './mint-adr.js';
 import {LIFECYCLE_CAS_CONTENTION} from './advancing-lock.js';
@@ -57,6 +60,8 @@ import {
 } from './surface-persist.js';
 import {
 	applyAnsweredQuestions,
+	hasAppliedAnswersRecord,
+	TRIAGED_RESOLVE,
 	type ApplyAnsweredQuestionsOptions,
 	type ApplyAnsweredQuestionsResult,
 } from './apply-persist.js';
@@ -324,6 +329,15 @@ export interface AdvanceContext {
 	 * commit). Tests inject a spy; production uses {@link autoDispositionObservation}.
 	 */
 	autoDisposition?: (options: AutoDispositionOptions) => AutoDispositionResult;
+	/**
+	 * Back-stamp the `triaged:` settled marker on a note that was ALREADY
+	 * resolved-and-kept before the apply rung learned to stamp it (the legacy arm of
+	 * the triage rung's settled guard). Tests inject a spy; production uses
+	 * {@link stampTriagedMarker}.
+	 */
+	stampTriaged?: (
+		options: StampTriagedMarkerOptions,
+	) => StampTriagedMarkerResult;
 	/**
 	 * Promote an answered observation: CAS-create a new backlog stub keyed on the
 	 * NEW item's identity, then record + resolve the observation. Tests inject a
@@ -910,10 +924,20 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
 	// note. (Replaces the old `detectObservationLimbo` special-case: there is no
 	// limbo any more — an UNtriaged observation always surfaces the deterministic
 	// question below; a SETTLED one is a calm no-op here.)
+	//
+	// SECOND ARM — the LEGACY back-fill (ADR
+	// `resolve-settles-the-question-loop-not-the-note`): a note the apply rung
+	// resolved-and-KEPT before it learned to stamp the marker carries the
+	// ENGINE-WRITTEN `## Applied answers` record but NO marker, which is the exact
+	// shape this rung would re-ask forever. That record is PROOF the engine already
+	// applied a human's answers to this note, so we stamp what the apply rung would
+	// have written and no-op. Self-healing and one-shot: the stamped note drops out
+	// of the pool, so this arm can never fire twice for the same note.
 	{
 		const itemRel = findItemPath(cwd, input.namespace, input.slug);
 		if (itemRel !== undefined) {
-			const fm = parseFrontmatter(readFileSync(join(cwd, itemRel), 'utf8'));
+			const body = readFileSync(join(cwd, itemRel), 'utf8');
+			const fm = parseFrontmatter(body);
 			if (fm.triaged !== undefined && fm.triaged !== '') {
 				return {
 					exitCode: 0,
@@ -921,6 +945,21 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
 					message: `triage ${item}: already triaged (triaged:${fm.triaged}) — nothing to do.`,
 				};
 			}
+			if (hasAppliedAnswersRecord(body)) {
+				const stamp = context.stampTriaged ?? stampTriagedMarker;
+				const result = stamp({
+					cwd,
+					item,
+					itemPath: itemRel,
+					value: TRIAGED_RESOLVE,
+					reason:
+						'Back-filled: the note carries an engine-written applied-answers ' +
+						'record, so its triage question-loop was already settled by a human ' +
+						'answer before the apply rung stamped the marker.',
+					note,
+				});
+				return {exitCode: 0, outcome: 'no-op', message: result.message};
+			}
 		}
 	}
 
@@ -951,9 +990,10 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
 		if (decision.auto === true) {
 			// A no-question case (duplicate / map) — auto-disposition WITHOUT a
 			// question. BOTH discharge the redundant note BY DELETION (a duplicate is a
-			// redundant copy; a map is already covered by the item it maps onto). There
-			// is no resting `triaged:keep` state any more. NEVER auto-deletes a
-			// NON-redundant signal; NEVER auto-promotes.
+			// redundant copy; a map is already covered by the item it maps onto), so an
+			// AUTO disposition never RESTS a note — resting a KEPT note is the
+			// human-answered `resolve` verdict's job on the apply rung. NEVER auto-deletes
+			// a NON-redundant signal; NEVER auto-promotes.
 			const dispose = context.autoDisposition ?? autoDispositionObservation;
 			const result = dispose({
 				cwd,
@@ -1654,6 +1694,14 @@ async function applyAgenticDecision(
 		// the sibling of `dispose`, which git-rm's it or moves it to a terminal). `resolveReason` is advisory
 		// context only; the durable disposition record is the harvested `## Applied
 		// answers` block the resolve-fully path writes (NOT a separate convention).
+		//
+		// Because the note is KEPT, that same commit also stamps `triaged: resolve` on
+		// it (ADR `resolve-settles-the-question-loop-not-the-note`): a kept note stays
+		// in the inbox the triage rung scans, and without the marker its two
+		// classifier signals (`needsAnswers:false`, no sidecar) are IDENTICAL to a note
+		// that was never triaged — so the next tick re-surfaced the same engine-built
+		// triage question forever. The stamp is done by the persist, not here, so no
+		// caller of the resolve-fully path can forget it.
 		const apply = context.applyPersist ?? applyAnsweredQuestions;
 		try {
 			const result = apply({cwd, item, itemPath, note});

package/src/apply-decide.ts

@@ -40,7 +40,13 @@ import {
  * by the task `apply-decide-resolve-verdict-mint-nothing` so the decider can
  * honestly handle "the human answered, keep the note on record, mint nothing"
  * (previously it had no valid verdict for that case and looped on `ask`,
- * re-surfacing an already-answered question every tick). `adr` was DEFERRED at the
+ * re-surfacing an already-answered question every tick). Its MEANING was SHARPENED
+ * by ADR `resolve-settles-the-question-loop-not-the-note`: `resolve` settles the
+ * QUESTION-LOOP on a note that REMAINS a live signal (and the persist stamps
+ * `triaged:` so the triage rung stops re-asking it, closing a second re-ask loop
+ * the first fix left open); a note whose SIGNAL is finished is `dispose`, not
+ * `resolve` — a dead note kept and stamped "resolved" is exactly the
+ * backward-artifact-in-a-forward-bucket the work contract forbids. `adr` was DEFERRED at the
  * keystone launch (no
  * ADR-mint path existed yet) and is now WIRED by the follow-on task
  * `agentic-apply-mint-adr-route`, which added the {@link
@@ -201,15 +207,22 @@ export function buildApplyDecisionPrompt(input: ApplyDecisionInput): string {
 		`    \`reason:\` frontmatter); a SPEC is git-mv-ed to \`specs/dropped/\` (RETAINED).`,
 		`    A task can NEVER be hard-deleted by the apply rung \u2014 dispose is the`,
 		`    only path off the board.`,
-		`  - "resolve": the answer SETTLES this item and there is NOTHING to mint (no`,
-		`    task/spec/adr) \u2014 the correct move is to CLOSE the question-loop while`,
-		`    KEEPING the note on record (e.g. an evidence/watch-item observation whose`,
-		`    answer is "acknowledged, keep this on record, no artifact"). The answers are`,
-		`    harvested into the item body and the loop is cleared; the note is RETAINED`,
-		`    (this is the sibling of "dispose", which DROPS the observation-note or`,
-		`    moves a task/spec to its terminal \u2014 pick "resolve" when the observation`,
-		`    should SURVIVE in place, "dispose" when it should not). Emit`,
-		`    {"outcome":"resolve","resolveReason":"\u2026"}.`,
+		`  - "resolve": the answer SETTLES the QUESTION-LOOP and there is NOTHING to`,
+		`    mint (no task/spec/adr), AND the note is STILL A LIVE SIGNAL worth keeping`,
+		`    in the inbox \u2014 e.g. a standing map of a known gap, or accepted residue the`,
+		`    answer explicitly says to keep on record until it is acted on. The answers`,
+		`    are harvested into the item body, the loop is cleared, and the note is`,
+		`    RETAINED and STAMPED as triaged, so it is never re-asked this question.`,
+		`    Emit {"outcome":"resolve","resolveReason":"\u2026"}.`,
+		`    PICK BETWEEN "resolve" AND "dispose" ON LIVENESS, NOT ON POLITENESS: both`,
+		`    close the loop and mint nothing, and the ONLY question is whether the note`,
+		`    is still a live signal AFTER this answer. If the answer means the signal is`,
+		`    FINISHED (the thing was fixed, it was already covered elsewhere, it is`,
+		`    obsolete, or its whole content is now carried by a task/spec/ADR/commit),`,
+		`    that note stops being live \u2014 emit "dispose", NOT "resolve". "resolve" is`,
+		`    only correct when the note still carries a signal nothing else records.`,
+		`    Do NOT use "resolve" as a soft "dispose": a note kept only to show it was`,
+		`    handled is a backward artifact in a forward bucket.`,
 		`  - "ask": you need more from the human before acting. Emit`,
 		`    {"outcome":"ask","question":"\u2026"} \u2014 ask everything you still need as ONE`,
 		`    batch (never a drip); the engine appends it and re-pauses.`,

package/src/apply-persist.ts

@@ -42,17 +42,26 @@ import {workItemRel} from './work-layout.js';
  *     hard-deleted from here — dispose is the only path off the board; OR
  *   - **resolve fully** (the default) — clear `needsAnswers` + DELETE the sidecar
  *     in the SAME atomic commit (the invariant `needsAnswers:false ⟺ no active
- *     sidecar`); the item advances toward build by its normal lifecycle.
+ *     sidecar`); the item advances toward build by its normal lifecycle. For an
+ *     OBSERVATION this ALSO stamps the `triaged:` settled marker (see
+ *     {@link TRIAGED_RESOLVE}) in that same commit — the note is KEPT, so it needs
+ *     a durable record that its triage question-loop is CLOSED or the triage rung
+ *     re-asks it forever (ADR `resolve-settles-the-question-loop-not-the-note`).
  *
  * **The disposition vocabulary is GONE** (task
  * `agentic-apply-retire-disposition-vocabulary`): the apply rung no longer reads a
- * per-entry `disposition=` token, no longer runs a most-decisive picker, and has
- * no `keep`/`triaged:keep` resting state. A sidecar entry is BINARY (no-answer |
- * answered); what to DO with a fully-answered OBSERVATION is decided by the
- * AGENTIC apply decision in the advance tick (`advance.ts` `applyRung` over the
- * shared `decide` engine), which then routes here (re-pause / dispose / via
- * `promoteObservation` for a mint). A signal is still-open, acted-on, or deleted
- * — there is no \"retain as resolved\" state.
+ * per-entry `disposition=` token and no longer runs a most-decisive picker. A
+ * sidecar entry is BINARY (no-answer | answered); what to DO with a fully-answered
+ * OBSERVATION is decided by the AGENTIC apply decision in the advance tick
+ * (`advance.ts` `applyRung` over the shared `decide` engine), which then routes
+ * here (re-pause / dispose / resolve / via `promoteObservation` for a mint).
+ *
+ * What the retirement removed was the human-stamped `disposition=`/`promote-*`
+ * TOKEN vocabulary, NOT the settled AXIS: a note that the `resolve` verdict KEEPS
+ * still rests as `triaged: resolve` + `needsAnswers:false` + no sidecar. That is
+ * the one resting state a note has, and it says "the question-loop is settled",
+ * NOT "the signal is finished" (a finished signal is `dispose`d — it leaves the
+ * inbox by deletion).
  *
  * The work-item (task/spec) terminal MOVES (`tasks/cancelled`, `specs/dropped`) and
  * the stuck (lock `state: stuck`) LIFECYCLE state are a SEPARATE lifecycle concern (a
@@ -87,6 +96,32 @@ export {APPLY_LIFECYCLE_FOLDERS, resolveItemPathByIdentity};
 /** Marker that opens the applied-answers record in an item body. */
 const APPLIED_HEADING = '## Applied answers';
 
+/**
+ * The `triaged:` settled-marker VALUE the resolve-fully path stamps on a KEPT
+ * OBSERVATION (ADR `resolve-settles-the-question-loop-not-the-note`).
+ *
+ * The `resolve` verdict is the ONE apply terminal that RETAINS an observation in
+ * the inbox. Every other terminal removes it from the triage pool by MOVING or
+ * DELETING the file (mint → `git rm` + the new artifact; dispose → `git rm` /
+ * terminal folder), so only this one needs an in-file record that the note has
+ * been through triage. Without it the resolved note is byte-indistinguishable, to
+ * the classifier's two signals (`needsAnswers` + sidecar), from a note that was
+ * NEVER triaged: `needsAnswers:false` + no sidecar ⇒ ANALYSE ⇒ `triage-observation`
+ * ⇒ the engine-built triage question is surfaced AGAIN, and the human is asked
+ * something they already answered (observed live in the `rocketh` consumer repo:
+ * surface → answer → resolve → the byte-identical question re-surfaced).
+ *
+ * The marker is the axis the READ side already models end-to-end — `frontmatter.ts`
+ * parses it, `ledger-read.ts` carries it, `lifecycle-pools.ts` drops a marked
+ * observation out of the CREATE-side triage pool, and `advance.ts`'s triage rung
+ * no-ops on it for an explicit `obs:<slug>`. Only the WRITER was missing.
+ *
+ * It does NOT strand a later answer: an ANSWERED sidecar dominates the marker (ADR
+ * `answered-observation-sidecar-dominates-triaged-marker`), so a genuinely NEW
+ * question about a settled note still routes to apply and is still answerable.
+ */
+export const TRIAGED_RESOLVE = 'resolve';
+
 /**
  * The STRUCTURAL fence the templates wrap the transient open-questions block in
  * — an HTML-comment marker pair, mirroring the existing `<!-- dorfl-…
@@ -108,6 +143,21 @@ const APPLIED_HEADING = '## Applied answers';
 export const OPEN_QUESTIONS_MARKER_OPEN = '<!-- open-questions -->';
 export const OPEN_QUESTIONS_MARKER_CLOSE = '<!-- /open-questions -->';
 
+/**
+ * Does this item body carry the ENGINE-WRITTEN applied-answers record?
+ *
+ * Only {@link applyAnsweredQuestions} writes this heading, and only after a human
+ * answered EVERY open question on the item, so its presence is PROOF the engine
+ * has applied a human's answers here — not a prose heuristic. The triage rung uses
+ * it as the legacy back-fill trigger for notes resolved-and-kept before the
+ * `triaged:` stamp existed (ADR `resolve-settles-the-question-loop-not-the-note`).
+ */
+export function hasAppliedAnswersRecord(body: string): boolean {
+	return new RegExp(`^${APPLIED_HEADING}\\b`, 'm').test(
+		body.replace(/\r\n/g, '\n'),
+	);
+}
+
 export interface ApplyAnsweredQuestionsOptions {
 	/** Working clone/worktree the apply commits in. */
 	cwd: string;
@@ -490,7 +540,10 @@ export function applyAnsweredQuestions(
 	// compatible — no marker ⇒ identical bytes. The re-pause path above is
 	// deliberately untouched (D3): its open-questions block is still open.
 	const reconciledBody = stripOpenQuestionsBlocks(baseBody);
-	const resolvedBody = withAppliedAnswers(reconciledBody, model.entries);
+	const resolvedBody = withTriagedMarkerIfKeptNote(
+		withAppliedAnswers(reconciledBody, model.entries),
+		item,
+	);
 	const result = applyAtomic({
 		cwd,
 		itemPath,
@@ -512,6 +565,30 @@ export function applyAnsweredQuestions(
 	};
 }
 
+/**
+ * Stamp the `triaged:` settled marker on a resolve-fully body — but ONLY for an
+ * OBSERVATION (the one item type this path KEEPS in a re-scanned inbox).
+ *
+ * Structural, not caller-supplied, so it cannot be forgotten by a future caller:
+ * every route that reaches the resolve-fully branch with an observation identity
+ * has, by definition, just closed that note's question-loop while retaining the
+ * file. A TASK/SPEC is deliberately EXCLUDED — it rests in a lifecycle FOLDER (its
+ * status), is not enumerated from the observation inbox, and has no triage rung to
+ * re-ask it; stamping a triage marker on one would invent a second status axis for
+ * an item whose status is already the folder.
+ *
+ * Idempotent ({@link setFrontmatterMarker} replaces an existing key) and
+ * fence-creating (observations are routinely born fence-less), so re-resolving a
+ * note after a genuinely new question re-stamps rather than duplicating.
+ */
+function withTriagedMarkerIfKeptNote(body: string, item: string): string {
+	const {type} = resolveSidecarIdentity(item);
+	if (type !== 'observation') {
+		return body;
+	}
+	return setFrontmatterMarker(body, 'triaged', TRIAGED_RESOLVE);
+}
+
 interface DisposeInput {
 	cwd: string;
 	item: string;

package/src/do.ts

@@ -17,7 +17,12 @@ import {
 	resolvePromptGuidanceForItem,
 	PromptError,
 } from './prompt.js';
-import {NullHarness, type AgentTreeReap, type Harness} from './harness.js';
+import {
+	NullHarness,
+	type AgentTreeReap,
+	type Harness,
+	type HarnessRecord,
+} from './harness.js';
 import {acquireWorktreeWriterLock} from './worktree-writer-lock.js';
 import {PiHarness} from './pi-harness.js';
 import {launchWithOptionalWatch} from './agent-launch.js';
@@ -33,7 +38,7 @@ import {
 	type IsolatedTree,
 } from './isolation.js';
 import {ensureMirror, encodeRepoKey, mirrorPath} from './repo-mirror.js';
-import {jobWorktreePath} from './workspace.js';
+import {jobWorktreePath, updateJobRecord} from './workspace.js';
 import {reapJob} from './gc.js';
 import {isGitHubArbiterUrl, GitHubProvider} from './github.js';
 import type {ReviewProvider} from './integrator.js';
@@ -1983,6 +1988,15 @@ async function runDoAgent(
 	output?: string;
 	timedOut?: boolean;
 	reap?: AgentTreeReap;
+	/**
+	 * The launch's real harness record (adapter + liveness anchor), when the run
+	 * went through a harness. The caller threads it into the job record so the
+	 * record says what ACTUALLY ran, not `createJob`'s placeholder
+	 * (`{adapter: 'null'}`) — the placeholder is what stranded a field
+	 * investigation into reading a healthy pi run as a null-harness misfire
+	 * (observation `deadline-reap-lets-node-exit-0-before-the-checkpoint-runs`).
+	 */
+	record?: HarnessRecord;
 }> {
 	if (options.dorfl) {
 		return options.dorfl({cwd, prompt, slug, env: options.env});
@@ -2032,6 +2046,7 @@ async function launchAgentUnderWriterLock(params: {
 	output?: string;
 	timedOut?: boolean;
 	reap?: AgentTreeReap;
+	record?: HarnessRecord;
 }> {
 	const {options, cwd, prompt, slug, harness} = params;
 	// Convert the dorfl-internal deadline (minutes) into a wall-clock epoch-ms so
@@ -2068,6 +2083,10 @@ async function launchAgentUnderWriterLock(params: {
 		detail: launched.detail,
 		output: launched.output,
 		timedOut: launched.timedOut,
+		// The launch's REAL record (adapter + pid/session anchor) — the caller
+		// finalises the job record with it (mirroring `run.ts`), so a `do` job's
+		// record stops reading `{adapter: 'null'}` forever.
+		record: launched.record,
 		// The harness's PROOF that a deadline-stopped agent's process tree is gone.
 		// Threaded to {@link routeDeadlineCheckpoint}, which refuses to release the
 		// item lock without it.
@@ -2610,6 +2629,12 @@ export async function performDoRemote(
 				throw err;
 			}
 			result = await runRemotePipeline(options, tree, slug, note, env);
+			// Finalise the job record to MATCH the terminal outcome (mirroring `run`'s
+			// tail): a retained worktree whose record still says `state: running`
+			// reads as a crashed job to `status`/`gc` FOREVER, when the run in fact
+			// reached a decision (observation
+			// `deadline-reap-lets-node-exit-0-before-the-checkpoint-runs`).
+			finaliseDoJobRecord(tree.dir, result);
 			return result;
 		} finally {
 			// 7. Teardown via the strategy handle. On a CLEAN completion: reap iff clean
@@ -2632,6 +2657,53 @@ export async function performDoRemote(
 	}
 }
 
+/**
+ * Bring a `do --remote`/`--isolated` job record in line with the terminal outcome
+ * the pipeline is returning — the SAME tail discipline `run` applies
+ * (`updateJobRecord(tree.dir, …)` on every routed outcome), which the `do` path
+ * never had (
+ * `deadline-reap-lets-node-exit-0-before-the-checkpoint-runs`): until now
+ * `createJob`'s initial `state: 'running'` record stood FOREVER on a retained
+ * worktree, so `status`/`gc` could not tell a decided-but-retained job from a
+ * runner that died mid-flight.
+ *
+ * The mapping is by outcome family, mirroring `run`'s tail:
+ *
+ *  - `completed`: state `done` (usually moot — the §4 teardown reaps the
+ *    worktree and its record immediately; kept for parity and for the retained
+ *    edge).
+ *  - `deadline-auto-continued`: deliberately UNTOUCHED. Nothing needs
+ *    attention — the checkpoint saved the WIP, pushed the branch, and released
+ *    the lock so the next claim continues the job. The record's `running` here
+ *    means "the job is not over", which is true.
+ *  - everything else that reached a terminal decision (needs-attention family,
+ *    the failure-cause axis, agent-stopped, refusals/usage errors): state
+ *    `needs-attention` with the pipeline's own message as the reason, so
+ *    `status` surfaces WHY without re-deriving it.
+ *
+ * Outcomes that never claimed the item (`lost`/`contended`) return before a
+ * worktree exists, so they never reach this helper. A pipeline that THREW
+ * likewise skips it — the failure is loud (the CLI crashes non-zero), and the
+ * retained record now carries the real harness anchor (finalised at launch),
+ * so `status` reads it as crashed-running-but-dead, which is honest.
+ */
+function finaliseDoJobRecord(dir: string, result: DoResult): void {
+	switch (result.outcome) {
+		case 'completed':
+			updateJobRecord(dir, {state: 'done'});
+			return;
+		case 'deadline-auto-continued':
+		case 'lost':
+		case 'contended':
+			return;
+		default:
+			updateJobRecord(dir, {
+				state: 'needs-attention',
+				reason: result.message,
+			});
+	}
+}
+
 /**
  * Best-effort reap of a worktree that {@link IsolationStrategy.prepare}/`createJob`
  * may have created at the deterministic per-job path BEFORE it threw (so the
@@ -2882,6 +2954,7 @@ async function runRemotePipeline(
 		output?: string;
 		timedOut?: boolean;
 		reap?: AgentTreeReap;
+		record?: HarnessRecord;
 	};
 	try {
 		agent = await runDoAgent(options, cwd, prompt, slug);
@@ -2897,6 +2970,19 @@ async function runRemotePipeline(
 			note,
 		});
 	}
+	// FINALISE the job record's harness block with the REAL launch record the
+	// agent ran under (mirroring `run.ts`'s `updateJobRecord(tree.dir,
+	// {harness: launched.record})`): `createJob` wrote the placeholder
+	// `{adapter: 'null'}`, and nothing on the `do` path ever overwrote it, so
+	// every `do` job's record read as adapter-null forever — on BOTH healthy and
+	// failed runs (observation
+	// `deadline-reap-lets-node-exit-0-before-the-checkpoint-runs`; a field
+	// investigation read it as "no agent was attached" and chased the wrong
+	// defect). The pid/session anchor is also what `status`/`gc` need to answer
+	// liveness for a do-path job AT ALL.
+	if (agent.record !== undefined) {
+		updateJobRecord(cwd, {harness: agent.record});
+	}
 	// Deadline checkpoint on the no-checkout `do --remote` path — same routing
 	// as the in-place path (see performDo).
 	if (agent.timedOut) {

package/src/frontmatter.ts

@@ -94,13 +94,20 @@ export interface Frontmatter {
 	 */
 	needsAnswers: boolean | undefined;
 	/**
-	 * The triage SETTLED marker (US #30). A non-empty `triaged:` value (e.g.
-	 * `keep` / `duplicate`) means a human (or the conservative auto-disposition)
-	 * has SETTLED this observation, so it DROPS OUT of the triage candidate pool
-	 * and is never re-asked. `undefined` when omitted (an UNTRIAGED observation,
-	 * still in the pool). Carried so the lifecycle-pool enumeration
-	 * (`advance-autopick-lifecycle-pools`) can exclude settled observations from
-	 * the triage selection.
+	 * The triage SETTLED marker (US #30). A non-empty `triaged:` value means this
+	 * observation's triage QUESTION-LOOP has been settled by a human's answer, so it
+	 * DROPS OUT of the triage candidate pool and is never re-asked. `undefined` when
+	 * omitted (an UNTRIAGED observation, still in the pool). Carried so the
+	 * lifecycle-pool enumeration (`advance-autopick-lifecycle-pools`) can exclude
+	 * settled observations from the triage selection.
+	 *
+	 * The one WRITER today is the apply rung's `resolve` verdict, which stamps
+	 * `triaged: resolve` on a note it settles and KEEPS (ADR
+	 * `resolve-settles-the-question-loop-not-the-note`). It says the question-loop is
+	 * settled, NOT that the signal is finished — a finished signal has no resting
+	 * state at all (it is deleted), and an ANSWERED sidecar still dominates this
+	 * marker (ADR `answered-observation-sidecar-dominates-triaged-marker`), so a
+	 * genuinely new question about a settled note is still asked and answered.
 	 */
 	triaged: string | undefined;
 	/** Slugs this item is blocked by; `[]` when omitted or empty. */
@@ -241,9 +248,9 @@ export function setNeedsAnswersMarker(content: string, value: boolean): string {
 /**
  * Set (or replace) a top-level scalar `<key>: <value>` frontmatter marker on a
  * `work/` markdown document, returning the new content. The generalised form of
- * {@link setNeedsAnswersMarker} the advance APPLY rung uses to stamp a
- * `triaged: keep` marker (US #30) on an item a human answered "keep" — so a
- * settled observation drops out of the candidate pool and is never re-asked. If a
+ * {@link setNeedsAnswersMarker} the advance APPLY rung uses to stamp the
+ * `triaged: resolve` marker (US #30) on a note a human's answer settles but KEEPS
+ * — so a settled observation drops out of the candidate pool and is never re-asked. If a
  * `<key>:` line already exists it is REPLACED (idempotent); otherwise it is
  * appended as the last line inside the frontmatter fence.
  *

package/src/pi-harness.ts

@@ -1,5 +1,5 @@
 import {spawn, spawnSync} from 'node:child_process';
-import {existsSync, readFileSync} from 'node:fs';
+import {existsSync, readFileSync, writeSync} from 'node:fs';
 import {
 	NullHarness,
 	pidAlive,
@@ -66,6 +66,97 @@ import type {HarnessAdapter} from './config.js';
 /** The default pi CLI binary name (resolved on `PATH`). */
 export const DEFAULT_PI_BIN = 'pi';
 
+/**
+ * **A runner MUST NOT exit while an async launch is unsettled** (observation
+ * `deadline-reap-lets-node-exit-0-before-the-checkpoint-runs`).
+ *
+ * An `await` is not a handle: node keeps a process alive for referenced HANDLES
+ * (timers, sockets, child processes), and a suspended promise is none of those.
+ * {@link PiHarness.launchAsync} deliberately drops every handle it owns the
+ * moment pi exits (it destroys the stdio pipes and `unref`s the child so a
+ * leaked grandchild's inherited FDs cannot pin the loop), and on the deadline
+ * path it then keeps the promise pending across the process-group reap. In the
+ * field that combination let the event loop go EMPTY mid-reap: node exited
+ * normally with code 0, the suspended pipeline (checkpoint save, branch push,
+ * lock release, writer-sentinel release, job-record update) simply never ran,
+ * and the run reported SUCCESS while leaving the item locked and 90 minutes of
+ * agent work uncommitted.
+ *
+ * So the launch holds an explicit REFERENCED keep-alive for exactly as long as
+ * it is in flight, and an exit guard turns any remaining way of exiting mid-
+ * launch into a LOUD, non-zero failure instead of a silent success. The two are
+ * deliberately independent: the keep-alive prevents the known mechanism, the
+ * guard refuses to let any future variant of it be mistaken for a clean run.
+ */
+let inFlightLaunches = 0;
+/** The referenced handle that keeps the loop alive while launches are in flight. */
+let inFlightKeepAlive: NodeJS.Timeout | undefined;
+let inFlightExitGuardInstalled = false;
+
+/**
+ * The keep-alive tick. Long, because it exists ONLY to be a referenced handle:
+ * it never does work, and it is cleared the moment the last launch settles.
+ */
+const KEEPALIVE_TICK_MS = 60_000;
+
+/** Report an exit that happened with a launch still in flight, LOUDLY. */
+function installInFlightExitGuard(): void {
+	if (inFlightExitGuardInstalled) {
+		return;
+	}
+	inFlightExitGuardInstalled = true;
+	process.on('exit', (code) => {
+		if (inFlightLaunches === 0) {
+			return;
+		}
+		// `writeSync` on fd 2, NOT console.error: stderr to a pipe is asynchronous,
+		// and an `exit` listener is the last synchronous moment there is, so a
+		// buffered write would be dropped exactly when it matters most.
+		writeSync(
+			2,
+			`>> INTERNAL ERROR: dorfl is exiting while ${inFlightLaunches} agent ` +
+				'launch(es) are still in flight, so the run STOPPED between the agent ' +
+				'and its outcome: nothing was committed, pushed, surfaced or released, ' +
+				'and any item lock is still held. This is a dorfl defect, not a task ' +
+				'failure. Recover with `dorfl requeue <slug>` (the work branch/worktree ' +
+				'is kept) and please report it.\n',
+		);
+		if (code === 0) {
+			// NEVER report this as success: a caller (CI leg, driving loop, `run`
+			// tick) that only checks the status must see a failure here.
+			process.exitCode = 1;
+		}
+	});
+}
+
+/** Mark one async launch as started (holds the loop open + arms the guard). */
+function launchStarted(): void {
+	inFlightLaunches += 1;
+	installInFlightExitGuard();
+	if (inFlightKeepAlive === undefined) {
+		// REFERENCED on purpose: this is the handle that keeps the runner alive
+		// across the window where it owns no other one.
+		inFlightKeepAlive = setInterval(() => {}, KEEPALIVE_TICK_MS);
+	}
+}
+
+/** Mark one async launch as settled (releases the keep-alive when the last one lands). */
+function launchSettled(): void {
+	inFlightLaunches = Math.max(0, inFlightLaunches - 1);
+	if (inFlightLaunches === 0 && inFlightKeepAlive !== undefined) {
+		clearInterval(inFlightKeepAlive);
+		inFlightKeepAlive = undefined;
+	}
+}
+
+/**
+ * How many async launches are currently unsettled. Exposed for the regression
+ * test that pins the keep-alive/guard invariant; not part of the harness seam.
+ */
+export function inFlightLaunchCount(): number {
+	return inFlightLaunches;
+}
+
 /**
  * The grace period between a deadline SIGTERM and the follow-up SIGKILL in
  * {@link PiHarness.launchAsync} (spec `graceful-pre-timeout-wip-checkpoint`).
@@ -233,7 +324,11 @@ export class PiHarness implements Harness {
 			command: [this.piBin, ...args].join(' '),
 			session: sessionFile,
 		};
-		return new Promise<LaunchResult>((resolve, reject) => {
+		// IN FLIGHT from here until the promise settles: hold the loop open and arm
+		// the exit guard, so the runner can never quietly disappear between the
+		// agent and its outcome (see the keep-alive block above).
+		launchStarted();
+		const launch = new Promise<LaunchResult>((resolve, reject) => {
 			const child = spawn(this.piBin, args, {
 				// Same as `launch`: spawn in the repo/worktree dir so the session
 				// header `cwd` groups the dashboard correctly (invariant #3).
@@ -436,6 +531,11 @@ export class PiHarness implements Harness {
 			}
 			child.stdin?.end();
 		});
+		// Release the keep-alive on BOTH outcomes (resolve AND reject) — a failed
+		// spawn must not pin the loop open for the rest of the process's life.
+		return launch.finally(() => {
+			launchSettled();
+		});
 	}
 
 	/**

package/src/reap-agent-tree.ts

@@ -72,11 +72,27 @@ export interface ReapResult {
 	detail: string;
 }
 
-/** Sleep helper (injectable clock is not needed: callers inject `wait` in tests). */
+/**
+ * Sleep helper (injectable clock is not needed: callers inject `wait` in tests).
+ *
+ * **The timer is deliberately REFERENCED — do not `unref()` it.** This sleep is
+ * the ONLY pending handle the runner holds while it waits for a signalled group
+ * to die: by the time {@link reapProcessGroup} runs, the harness has already
+ * destroyed the child's stdio and `unref`'d the child handle, and a pending
+ * promise is not a handle. An `unref`'d timer here therefore left the event loop
+ * with NOTHING referenced, so node did the correct thing with an empty loop and
+ * EXITED 0 mid-reap — abandoning the suspended `await` and with it the whole
+ * deadline checkpoint (no WIP commit, no branch push, no lock release, no
+ * sentinel release), while reporting success (observation
+ * `deadline-reap-lets-node-exit-0-before-the-checkpoint-runs`).
+ *
+ * Referencing it cannot hang a runner: this loop is bounded by construction
+ * (`sigtermGraceMs + sigkillTimeoutMs`), which is the same property that lets
+ * the launch resolve-on-`exit` discipline stay safe.
+ */
 function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => {
-		const timer = setTimeout(resolve, ms);
-		timer.unref?.();
+		setTimeout(resolve, ms);
 	});
 }
 

package/src/triage-gate.ts

@@ -26,8 +26,10 @@ import {extractJsonObjectSpan} from './verdict-json.js';
  *   - `map` — an UNAMBIGUOUS map onto an existing item → DISCHARGE the redundant
  *     note BY DELETION too (it is already covered by the item it maps onto, so it
  *     carries no unique signal; the mapping is recorded in the commit message).
- *     There is no resting `triaged:keep` state any more (task
- *     `agentic-apply-retire-disposition-vocabulary`).
+ *     An AUTO disposition never RESTS a note (task
+ *     `agentic-apply-retire-disposition-vocabulary`); the one path that KEEPS a
+ *     note is the human-answered `resolve` verdict on the apply rung (ADR
+ *     `resolve-settles-the-question-loop-not-the-note`).
  *
  * It is the DIRECT mirror of `surface-gate.ts`'s spawn→emit→parse seam, with a
  * narrower emitted payload (`{auto, …}` rather than `{questions}`). Production