dorfl 0.1.2 → 0.2.0

package/src/advancing-lock.ts

@@ -3,6 +3,7 @@ import {dirname, join} from 'node:path';
 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 {realSleep, type Sleep} from './retry-backoff.js';
 
@@ -545,11 +546,25 @@ export function nextCasContentionDelayMs(input: {
 	return Math.max(base, Math.min(cap, Math.floor(base + r * (upper - base))));
 }
 
-/** A semantic label for the new-item creation outcome. */
+/**
+ * A semantic label for the new-item creation outcome.
+ *
+ * `already-exists-from-source` (task
+ * `observation-triage-already-triaged-benign-skip`): the target path already
+ * exists on `<arbiter>/main` AND that existing item is PROVABLY the one this same
+ * `sourceItem` already minted (its `promotedFrom:` back-reference equals
+ * `sourceItem`). This is a TERMINAL idempotency fact — the source was already
+ * triaged in a prior run and a retry can NEVER succeed — so it is a BENIGN SKIP
+ * (`exitCode: 0`), NOT the loud `lost` (exit 2) a genuine concurrent-create race
+ * gets. Distinguishable from `created`/`lost` so a caller (and CI) can grep it out.
+ * Only ever produced when the caller passes `sourceItem`; without it the
+ * path-exists case stays `lost` exactly as before (zero behaviour change).
+ */
 export type CreateItemOutcome =
 	| 'created'
 	| 'usage-error'
 	| 'lost'
+	| 'already-exists-from-source'
 	| 'contended';
 
 /** Maps onto the claim-CAS exit codes (identical semantics). */
@@ -574,6 +589,21 @@ export interface CreateItemThroughCasOptions {
 	 * A listed path that is absent on the create branch is skipped (best-effort rm).
 	 */
 	deletePaths?: string[];
+	/**
+	 * OPTIONAL provenance disambiguator for the LOST-race case (task
+	 * `observation-triage-already-triaged-benign-skip`). When set, this is the
+	 * namespaced identity of the SOURCE item this create was minted FROM (e.g.
+	 * `observation:<slug>`). If the target `path` already exists on `<arbiter>/main`
+	 * AND that existing file's `promotedFrom:` back-reference equals THIS `sourceItem`,
+	 * the create is TERMINAL-by-existence (the source was already triaged in a prior
+	 * run) — a BENIGN SKIP (`already-exists-from-source`, exit 0), NOT the loud `lost`
+	 * (exit 2) a genuine concurrent-create race with an UNRELATED same-path item gets.
+	 * The match is on the explicit back-reference, NOT the slug, so an unrelated task
+	 * that merely shares the slug does NOT false-positive into a benign skip. Absent
+	 * (or the existing file carries no matching `promotedFrom:`) ⇒ the path-exists case
+	 * stays `lost` exactly as before (zero behaviour change for non-provenance callers).
+	 */
+	sourceItem?: string;
 	/** Working clone/worktree the creation runs in. */
 	cwd: string;
 	/** Name of the arbiter remote (`--arbiter`). Defaults to `origin`. */
@@ -688,6 +718,36 @@ async function runCreate(
 		);
 	}
 
+	// TERMINAL 'already triaged' PRE-CHECK (case A; task
+	// `observation-triage-already-triaged-benign-skip`). When the caller passes
+	// `sourceItem`, check ONCE UP FRONT whether the target already exists on the
+	// arbiter AND was PROVABLY minted from THIS same source in a PRIOR run (its
+	// `promotedFrom:` back-reference matches). If so this is an idempotency fact, not
+	// a race: a BENIGN SKIP (exit 0), never a retry. Doing this BEFORE the contention
+	// loop is what keeps it distinct from case B (a LIVE concurrent-create race): a
+	// race winner's file appears DURING the loop (the target is absent at this
+	// pre-check), so the loser still funnels through the loop to the loud `lost`
+	// (exit 2) the existing same-NEW-task race semantics require. Only a task that
+	// ALREADY existed before this leg began resolves here.
+	if (options.sourceItem !== undefined && options.sourceItem !== '') {
+		await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+		const skip = await alreadyMintedFromSource(
+			options.sourceItem,
+			path,
+			arbiter,
+			cwd,
+			env,
+		);
+		if (skip !== undefined) {
+			note(skip);
+			return {
+				exitCode: 0,
+				outcome: 'already-exists-from-source',
+				message: skip,
+			};
+		}
+	}
+
 	// A throwaway create branch, slugified off the new item's path (so concurrent
 	// creators of DIFFERENT paths don't collide on the branch name either).
 	const createBranch = `create/${path.replace(/[^A-Za-z0-9._-]+/g, '-')}`;
@@ -911,6 +971,41 @@ async function catFileExists(
 	return (await gitSoft(['cat-file', '-e', object], cwd, env)).status === 0;
 }
 
+/**
+ * The LOST-race case-A disambiguator (task
+ * `observation-triage-already-triaged-benign-skip`): is the item ALREADY at `path`
+ * on `<arbiter>/main` PROVABLY the one `sourceItem` already minted? Reads that
+ * file's `promotedFrom:` back-reference and returns a benign-skip MESSAGE iff it
+ * equals `sourceItem`, else `undefined` (⇒ the caller keeps the loud `lost`).
+ *
+ * The match is on the EXPLICIT `promotedFrom:` back-reference, NOT the slug, so an
+ * unrelated task that merely shares the slug (or a slug PREFIX) never
+ * false-positives — only an item this exact source stamped resolves to the skip. A
+ * plumbing failure reading the existing file degrades to `undefined` (stay loud),
+ * never a false benign skip.
+ */
+async function alreadyMintedFromSource(
+	sourceItem: string,
+	path: string,
+	arbiter: string,
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): Promise<string | undefined> {
+	const show = await gitSoft(['show', `${arbiter}/main:${path}`], cwd, env);
+	if (show.status !== 0) {
+		return undefined;
+	}
+	const promotedFrom = readFrontmatterField(show.stdout, 'promotedFrom');
+	if (promotedFrom !== sourceItem) {
+		return undefined;
+	}
+	return (
+		`'${path}' already exists on ${arbiter}/main and was PROVABLY minted from ` +
+		`${sourceItem} (its promotedFrom: back-reference matches) — already triaged in ` +
+		`a prior run. Terminal by existence; a retry can never succeed. Benign skip.`
+	);
+}
+
 /** Run git, returning the raw result (no throw) — for soft checks. */
 function gitSoft(
 	args: string[],

package/src/agent-launch.ts

@@ -66,6 +66,18 @@ export interface LaunchWithOptionalWatchInput {
 	sessionsDir?: string;
 	/** Tail the session `.jsonl` live (pi harness only). */
 	watch?: boolean;
+	/**
+	 * **Optional agent-session DEADLINE** (absolute epoch-ms wall-clock timestamp,
+	 * spec `graceful-pre-timeout-wip-checkpoint`) threaded through to
+	 * {@link LaunchInput.deadlineMs}. Forces the ASYNC {@link
+	 * PiHarness.launchAsync} path (even without `watch`), because the deadline
+	 * race only works there — `spawnSync` cannot be interrupted from the same
+	 * event loop. A non-pi harness with a deadline set silently degrades to a
+	 * plain `harness.launch` (no race is possible), the same safe fall-through
+	 * used for `watch` on a non-pi harness. Absent ⇒ no deadline; a run that
+	 * finishes normally is byte-for-byte unchanged.
+	 */
+	deadlineMs?: number;
 	/** Where the tailed high-signal lines are written (defaults to stderr). */
 	watchSink?: (line: string) => void;
 	/** Emit ANSI colour in the tailed lines (the caller's TTY/`NO_COLOR` decision). */
@@ -97,17 +109,27 @@ export async function launchWithOptionalWatch(
 		id: input.sessionId,
 	});
 
-	// `--watch` (pi only): launch async + tail the KNOWN session .jsonl path
-	// concurrently. The caller is responsible for rejecting `--watch` on a non-pi
-	// harness up-front (as `do` does); a non-pi harness here falls through to the
-	// sync launch below rather than tailing a log that will never exist.
-	if (input.watch === true && harness instanceof PiHarness) {
-		const tailer = new SessionTailer({
-			sessionFile: session,
-			color: input.color ?? false,
-			sink: input.watchSink,
-		});
-		tailer.start();
+	const wantsAsync =
+		(input.watch === true || input.deadlineMs !== undefined) &&
+		harness instanceof PiHarness;
+
+	// `--watch` OR a threaded deadline (spec
+	// `graceful-pre-timeout-wip-checkpoint`) forces the ASYNC path: the deadline
+	// race is only expressible against `launchAsync` (a spawnSync child cannot be
+	// SIGTERMed from the same event loop), and `--watch` needs it to tail the
+	// session log concurrently. Both are pi-only — a non-pi harness here falls
+	// through to the sync launch below (safe: watch would have no log to tail,
+	// and the deadline was already opt-in).
+	if (wantsAsync) {
+		const tailer =
+			input.watch === true
+				? new SessionTailer({
+						sessionFile: session,
+						color: input.color ?? false,
+						sink: input.watchSink,
+					})
+				: undefined;
+		tailer?.start();
 		try {
 			return await harness.launchAsync({
 				dir: input.dir,
@@ -116,12 +138,15 @@ export async function launchWithOptionalWatch(
 				prompt: input.prompt,
 				model: input.model,
 				session,
+				deadlineMs: input.deadlineMs,
 				env: input.env,
 			});
 		} finally {
 			// Always release the tailer (one final drain) — even on a launch error —
 			// so the observer never outlives the run or leaks a handle.
-			await tailer.stop();
+			if (tailer) {
+				await tailer.stop();
+			}
 		}
 	}
 

package/src/agent-stop.ts

@@ -1,5 +1,6 @@
 import {runAsync} from './git.js';
 import {JOB_RECORD_FILENAME} from './workspace.js';
+import type {NewQuestion} from './sidecar.js';
 
 /**
  * **The build-agent → runner REPORTING CHANNEL** (task `agent-stop-signal`).
@@ -11,8 +12,10 @@ import {JOB_RECORD_FILENAME} from './workspace.js';
  *
  *   1. A HARD **STOP** sentinel ({@link STOP_SENTINEL_OPEN} … {@link
  *      STOP_SENTINEL_CLOSE}): the task DRIFTED / is ambiguous / rests on a stale
- *      premise, so the agent could not build it. The runner routes the item to
- *      `work/needs-attention/` (the agent's reason VERBATIM) and SKIPS the
+ *      premise, so the agent could not build it. The runner marks the item stuck
+ *      on its per-item lock (post lock-cutover — `state: stuck` with the agent's
+ *      reason VERBATIM on the lock entry, no `work/needs-attention/` folder
+ *      write) and SKIPS the
  *      acceptance gate + the Gate-2 review (a clean STOP is not a build that
  *      changed nothing). See {@link parseStopSentinel}.
  *   2. A SOFT **`## Decisions`** block ({@link extractDecisionsBlock}): the agent
@@ -359,3 +362,58 @@ export function emptyDiffStopReason(slug: string): string {
 		'arbiter main); treating as a no-op/stop — re-scope or re-claim.'
 	);
 }
+
+/**
+ * The DISCRIMINATED classification of a `saveAgentStop` reason (spec
+ * `surface-stuck-as-questions-and-retire-stuck-lock-state` resolved decision #2,
+ * task `empty-diff-bounce-surfaces-dispose-defaulted-question`). The two kinds
+ * route DIFFERENTLY at the bounce seam:
+ *
+ *   - `'sentinel'` — the agent raised a hard STOP with a specific drift report
+ *     (the principled case). The runner surfaces the reason VERBATIM through the
+ *     existing lock-stuck bounce path.
+ *   - `'empty-diff'` — the agent produced no source change (the deterministic
+ *     backstop). Because "nothing to do" is a NON-DETERMINISTIC LLM judgement, a
+ *     blind requeue would infinite-loop; instead the runner surfaces a sidecar
+ *     with an engine-authored DISPOSE-DEFAULTED disposition question. The engine
+ *     owns the envelope + the safe default; the LLM owns the prose.
+ */
+export type AgentStopKind = 'sentinel' | 'empty-diff';
+
+/** A classified STOP verdict + the needs-attention reason prose. */
+export interface AgentStopClass {
+	kind: AgentStopKind;
+	reason: string;
+}
+
+/**
+ * The DISPOSE-DEFAULTED disposition question the empty-diff bounce path surfaces
+ * as its engine-authored envelope entry (spec resolved decision #2). The engine
+ * GUARANTEES this envelope exists on every empty-diff bounce even when the
+ * agent surfaced no questions of its own; the LLM/human owns the prose that
+ * follows. The `default: 'dispose'` hint routes an answered "cancel" to the
+ * regime-polymorphic `dispose` outcome (task → `git mv → tasks/cancelled/`,
+ * RETAINED; NOT a `git rm`, NOT a requeue) via the shared apply decider
+ * (`apply-decide.ts`).
+ */
+export function emptyDiffDisposeEnvelope(params: {
+	item: string;
+	reason: string;
+}): NewQuestion {
+	const {item, reason} = params;
+	return {
+		question:
+			`'${item}': the agent produced no change (${reason}). ` +
+			'Cancel this item? [default: yes]',
+		context:
+			'"Nothing to do" is a non-deterministic LLM judgement, so this bounce is ' +
+			'SURFACED (not blindly requeued) to break any infinite "re-run → re-judge ' +
+			'nothing-to-do → re-bounce" loop. Answering "cancel" (or accepting the ' +
+			'default) disposes this task to its terminal (`git mv → ' +
+			'`work/tasks/cancelled/`, retained) via the regime-polymorphic `dispose` ' +
+			'outcome — the task is NOT hard-deleted. Answer with a REQUEUE / RESET ' +
+			'directive if you disagree with the agent and want the loop to try again.',
+		default: 'dispose (cancel this task → work/tasks/cancelled/, retained)',
+		kind: 'stuck',
+	};
+}

package/src/apply-decide.ts

@@ -29,8 +29,19 @@ import {
  * from the agent's VERDICT, NOT a human `promote-*` field.
  *
  * **The allowed set** (the SUBSET the apply rung passes to `decide`):
- * `{task | spec | adr | delete | ask}` \u2014 i.e. `{mint-task | mint-spec | mint-adr |
- * delete-source | ask-follow-up}`. `adr` was DEFERRED at the keystone launch (no
+ * `{task | spec | adr | dispose | resolve | ask}` \u2014 i.e. `{mint-task | mint-spec |
+ * mint-adr | dispose-source | resolve-no-mint | ask-follow-up}`. The `dispose`
+ * verdict replaced the older `delete` token (task
+ * `apply-disposition-delete-to-dispose-regime-polymorphic`, spec
+ * `surface-stuck-as-questions-and-retire-stuck-lock-state` decision #5): the
+ * disposal is now REGIME-POLYMORPHIC (observation \u2192 `git rm`, task \u2192
+ * `git mv` to `tasks/cancelled/`, spec \u2192 `git mv` to `specs/dropped/`), so a
+ * task can no longer be hard-deleted by the apply rung. `resolve` was added
+ * 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
+ * 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
  * import('./mint-adr.js').mintAdr} route and widened this set. Intake's set is
@@ -54,7 +65,8 @@ export const APPLY_ALLOWED_OUTCOMES: readonly DecisionOutcome[] = [
 	'task',
 	'spec',
 	'adr',
-	'delete',
+	'dispose',
+	'resolve',
 	'ask',
 ];
 
@@ -136,7 +148,10 @@ export function buildApplyDecisionInput(opts: {
  * the human's recorded ANSWER(S) + the SOURCE item and emit a single
  * `{outcome, \u2026}` verdict ({@link parseDecisionVerdict} reads it). The agent decides
  * what to DO with the answered signal \u2014 mint a self-contained task, mint a SPEC,
- * mint an ADR, delete the source, or ask one BATCH of follow-up questions \u2014
+ * mint an ADR, DISPOSE the source (regime-polymorphic: an observation is
+ * git-rm-ed, a task is `git mv`-ed to `tasks/cancelled/`, a spec to
+ * `specs/dropped/`), resolve it (settle the loop, mint nothing, KEEP the note),
+ * or ask one BATCH of follow-up questions \u2014
  * grounded in the source's full context. It writes NOTHING (the engine acts on
  * the verdict).
  *
@@ -178,9 +193,23 @@ export function buildApplyDecisionPrompt(input: ApplyDecisionInput): string {
 		`    a self-contained ADR (docs/adr/, the context/decision/why shape) carrying`,
 		`    the WHY from the answer(s). Emit {"outcome":"adr","adrSlug":"\u2026",`,
 		`    "adrTitle":"\u2026","adrBody":"\u2026 (markdown AFTER the frontmatter)"}.`,
-		`  - "delete": the answer means this signal should be DROPPED. Emit`,
-		`    {"outcome":"delete","deleteReason":"\u2026"} (a single revertible deletion;`,
-		`    the reason rides the commit message, git history is the archive).`,
+		`  - "dispose": the answer means this signal should be DISPOSED. Emit`,
+		`    {"outcome":"dispose","disposeReason":"\u2026"}. REGIME-POLYMORPHIC on the`,
+		`    SOURCE type: an OBSERVATION is git-rm-ed in a single revertible commit`,
+		`    (reason rides the message, git history is the archive); a TASK is git-mv-ed`,
+		`    to \`tasks/cancelled/\` (RETAINED, reason recorded in the moved body's`,
+		`    \`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"}.`,
 		`  - "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-merge-action.ts

@@ -1,9 +1,9 @@
 import {existsSync, readFileSync} from 'node:fs';
 import {join} from 'node:path';
 import {
-	allAnswered,
 	isEntryAnswered,
 	parseSidecar,
+	resolveSidecarIdentity,
 	sidecarPathFor,
 	type SidecarEntry,
 	type SidecarModel,
@@ -116,11 +116,23 @@ export function parseMergeAnswer(text: string): MergeActionVerb | undefined {
 }
 
 /**
- * Detect the FIRST answered `kind: merge` entry's deterministic action verb in
- * a fully-answered sidecar (the apply rung's pre-decider kind-check). Returns
- * `undefined` when the sidecar carries no answered `kind: merge` entry (the
- * apply rung then proceeds to the existing path — agentic for observations,
- * normal apply for task/spec content questions).
+ * Detect the `kind: merge` action verb that should drive the next apply run.
+ * The apply rung's pre-decider kind-check; returns `undefined` when there is
+ * nothing for the dispatcher to act on.
+ *
+ * ORDERING (task `merge-action-nits-followup` nit 1). The re-stale re-surface
+ * path (`advance.ts` `maybeRunMergeAction` restale branch) APPENDS a new
+ * `kind: merge` follow-up via `appendQuestions` rather than clearing the prior
+ * `answer=merge` on the original entry — that append-and-keep-history shape is
+ * canonical, but a naive FIRST-match lookup would re-fire against the STALE
+ * prior answer instead of the human's fresh follow-up. So:
+ *
+ *   1. If ANY `kind: merge` entry is UNANSWERED, return `undefined` — that is
+ *      the re-paused state (a freshly-appended follow-up awaiting an answer),
+ *      and the apply MUST NOT fire against a stale prior sibling.
+ *   2. Otherwise return the LATEST answered `kind: merge` entry — a fresh
+ *      follow-up answer wins over the stale one, and a plain single-entry
+ *      merge-question sidecar behaves as before.
  *
  * The sidecar is read OFF DISK keyed off the namespaced item identity; the
  * model is parsed via the SAME `parseSidecar` the rest of the engine uses.
@@ -139,8 +151,13 @@ export function detectAnsweredMergeAction(
 	} catch {
 		return undefined;
 	}
-	if (!allAnswered(model)) return undefined;
+	// (1) Unanswered `kind: merge` follow-up ⇒ re-paused; the apply must NOT fire.
 	for (const entry of model.entries) {
+		if (entry.kind === 'merge' && !isEntryAnswered(entry)) return undefined;
+	}
+	// (2) LATEST answered `kind: merge` entry — a fresh follow-up beats a stale one.
+	for (let i = model.entries.length - 1; i >= 0; i--) {
+		const entry = model.entries[i];
 		if (entry.kind !== 'merge') continue;
 		if (!isEntryAnswered(entry)) continue;
 		const verb = parseMergeAnswer(entry.answer);
@@ -336,6 +353,27 @@ export async function performMergeAction(
 	const note = input.note ?? (() => {});
 	const {verb} = input.action;
 
+	// INVARIANT (task `merge-action-nits-followup` nit 4). The merge-question
+	// surfacer only emits `kind: merge` sidecars for TASKS, so the hard-coded
+	// `type: 'task'` on the `createJob` call below is correct in practice — but
+	// if a future surfacer change ever stamps a `kind: merge` sidecar on a
+	// non-task item (e.g. a spec-level unmerged branch), the branch name
+	// `work/task-<slug>` would silently mis-target. Fail LOUDLY here so the
+	// invariant is asserted at the dispatcher's entry rather than manifesting
+	// as a mysterious rebase/push mis-target downstream.
+	const identity = resolveSidecarIdentity(input.item);
+	if (identity.type !== 'task') {
+		throw new Error(
+			`performMergeAction: sidecar source item \`${input.item}\` has type ` +
+				`\`${identity.type}\`, but the answered-merge dispatcher only supports ` +
+				`\`task\` items (the surfacer only stamps \`kind: merge\` on tasks; the ` +
+				`branch name \`work/task-<slug>\` would silently mis-target otherwise). ` +
+				`This is the entry-invariant asserted by nit 4 of task ` +
+				`\`merge-action-nits-followup\` — reconcile the surfacer or extend the ` +
+				`dispatcher before landing a non-task source item.`,
+		);
+	}
+
 	if (verb === 'hold') {
 		return {
 			outcome: 'hold',