dorfl 0.0.0 → 0.1.0

package/src/failure-cause.ts

@@ -0,0 +1,142 @@
+/**
+ * **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.
+ * Historically several DIFFERENT causes collapsed into one undifferentiated label
+ * ("agent failed"), even though the CAUSE drives the RECOVERY:
+ *
+ *   - **transient-infra** → retry the SAME work (the work is fine: a model
+ *     endpoint outage the harness surfaced AFTER its own retries, or a git/
+ *     provider outage).
+ *   - **config-error** → fix the WIRING, not the task (a thrown CORE wiring/
+ *     config error, e.g. `review` on with no `reviewGate` configured).
+ *   - **agent-failed** (the conservative generic) → a human/agent must FIX
+ *     something the agent did (ran but produced bad/empty output), OR the cause is
+ *     simply UNKNOWN — the safe default that never forces a wrong specific label.
+ *
+ * This module classifies ONLY the axis that was previously lumped under
+ * "agent-failed". The OTHER existing terminal causes already have precise names
+ * and are NOT re-classified here — a red acceptance gate stays `gate-failed`, a
+ * rebase abort stays `rebase-conflict`, a deliberate STOP stays `agent-stopped`,
+ * a Gate-2 block stays `review-blocked`. This is the CAUSE axis ON TOP of those
+ * (see CONTEXT.md's *failure cause* glossary entry — the single source of truth).
+ *
+ * The classification is BEST-EFFORT + CONSERVATIVE: an unrecognised cause stays
+ * the generic `agent-failed`. The new precision is ADDED only where the cause is
+ * knowable from the surfaced error/detail; it never forces a wrong label.
+ *
+ * **`do` and `run` classify the SAME error the SAME way** by both routing their
+ * thrown-core-error / failed-agent detail through THIS one function — closing the
+ * cross-path divergence recorded in
+ * `work/notes/observations/run-thrown-core-error-labeled-agent-failed.md` (the SAME
+ * thrown core error used to read as `usage-error` in `do` but `agent-failed` in
+ * `run`).
+ *
+ * SCOPE FENCE: model-endpoint RETRIES are the HARNESS's job (pi retries its own
+ * API ~3–4×). This module does NOT add retries — it only CLASSIFIES what the
+ * harness SURFACES once its retries are exhausted (so a post-retry model outage
+ * reads as `transient-infra`, distinct from the agent producing bad output).
+ */
+
+/**
+ * The CAUSE of a stuck item, the axis ON TOP of the existing terminal outcomes.
+ * Only the values this module decides between are listed — the genuinely-NEW
+ * `transient-infra` / `config-error` plus the conservative generic `agent-failed`
+ * (the existing name, reused as the safe default). The other terminal causes
+ * (`gate-failed`, `rebase-conflict`, `agent-stopped`, `review-blocked`) are NOT
+ * produced here; they keep their own precise outcome names at their own sites.
+ */
+export type FailureCause =
+	| 'transient-infra' // a harness-surfaced model/connection outage (post-retry), or a git/provider outage — RETRY the same work
+	| '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
+
+/**
+ * The signature of a thrown CORE wiring/config error this module recognises. The
+ * core throws a plain `Error` for `review` on with no `reviewGate` wired (the
+ * canonical config-error; see `integration-core.ts`), whose message contains
+ * "wiring bug". We match on that stable phrase rather than the error CLASS so the
+ * classification survives the message crossing the plain-`Error` boundary the
+ * catch sites hand us (they only have `err.message`).
+ */
+const CONFIG_ERROR_SIGNATURES = [
+	/wiring bug/i,
+	/no review gate is configured/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
+ * outage. Best-effort lexical signals (the harness/git only hand us a message
+ * string) — deliberately conservative: anything not matched stays `agent-failed`.
+ */
+const TRANSIENT_INFRA_SIGNATURES = [
+	// A Gate-2 review verdict the runner could not PARSE (malformed JSON from the
+	// review agent, common on large diffs + weaker models). This is `transient-infra`,
+	// NOT `agent-failed`/`config-error`: the WORK is fine and the wiring is fine; the
+	// STOCHASTIC gate output misbehaved, so re-running the SAME work is the natural
+	// recovery (and the parser's repair pass + the tightened contract make a re-run far
+	// more likely to parse). Matches both `parseReviewVerdict` throw phrasings ("review
+	// verdict was not valid JSON" and "produced no parseable {verdict, findings}") and
+	// the core's "verdict could not be parsed" wrapper.
+	/review verdict was not valid JSON/i,
+	/verdict could not be parsed/i,
+	/no parseable \{verdict/i,
+	/\bECONN(?:REFUSED|RESET|ABORTED)\b/i,
+	/\bETIMEDOUT\b/i,
+	/\bENOTFOUND\b/i,
+	/\bEAI_AGAIN\b/i,
+	/connection (?:error|refused|reset|timed out|failed)/i,
+	/network (?:error|is unreachable|timeout)/i,
+	/\b(?:could not|unable to) (?:connect|reach)\b/i,
+	/\btimed? ?out\b/i,
+	/\b(?:overloaded|service unavailable|temporarily unavailable)\b/i,
+	/\b(?:429|500|502|503|504)\b/,
+	/model (?:endpoint )?(?:offline|unavailable|overloaded)/i,
+	/(?:after|exhausted) .{0,40}retr(?:y|ies)/i,
+	/rate.?limit/i,
+];
+
+/**
+ * Classify a failure CAUSE from the surfaced error/detail text, best-effort +
+ * conservative (an unrecognised cause stays `agent-failed`).
+ *
+ * Order matters: a thrown CORE config/wiring error is checked FIRST (it is the
+ * most specific + the cross-path divergence this task closes), then the
+ * transient-infra signals, else the generic default.
+ *
+ * Used by BOTH `do` and `run` at their failure-routing sites so the SAME error
+ * yields the SAME cause regardless of path.
+ */
+export function classifyFailureCause(detail: string | undefined): FailureCause {
+	const text = (detail ?? '').trim();
+	if (text === '') {
+		return 'agent-failed';
+	}
+	if (CONFIG_ERROR_SIGNATURES.some((re) => re.test(text))) {
+		return 'config-error';
+	}
+	if (TRANSIENT_INFRA_SIGNATURES.some((re) => re.test(text))) {
+		return 'transient-infra';
+	}
+	return 'agent-failed';
+}
+
+/**
+ * A short, human-readable label for a cause, used to PREFIX the recorded
+ * needs-attention reason so an operator (or an autonomous triage loop) reads the
+ * cause WITHOUT a second naming scheme. The generic `agent-failed` gets the
+ * historical "agent failed:" prefix so existing reason prose / tests are
+ * unchanged; only the NEW causes carry a distinct, legible prefix.
+ */
+export function failureCauseLabel(cause: FailureCause): string {
+	switch (cause) {
+		case 'transient-infra':
+			return 'transient infra';
+		case 'config-error':
+			return 'config error';
+		case 'agent-failed':
+			return 'agent failed';
+	}
+}

package/src/format.ts

@@ -0,0 +1,313 @@
+import type {ScanReport, ScannedItem} from './scan.js';
+import type {CwdSection} from './cwd-section.js';
+import type {LockEntry} from './item-lock.js';
+import {formatDuplicateWarnings} from './ledger-lint.js';
+import {
+	categoriseItems,
+	summariseGroups,
+	CATEGORY_ORDER,
+	CATEGORY_LABELS,
+	type CategorisedItem,
+	type CategorisedGroups,
+} from './categorise.js';
+
+/**
+ * Human label for the two autonomy axes. `humanOnly` is reported first when both
+ * are set, so the REASON an agent is gated is always visible and distinct from
+ * `needsAnswers`.
+ */
+export function gateLabel(
+	humanOnly: boolean | undefined,
+	needsAnswers?: boolean | undefined,
+): string {
+	if (humanOnly === true) {
+		return 'human-only';
+	}
+	if (needsAnswers === true) {
+		return 'needs-answers';
+	}
+	return 'undeclared';
+}
+
+/** A short description of the `blockedBy` readiness for one item. */
+function readinessLabel(item: ScannedItem): string {
+	if (item.blockedBy.length === 0) {
+		return 'deps: satisfied (none)';
+	}
+	if (item.eligibility.blockedBy.satisfied) {
+		return `deps: satisfied (${item.blockedBy.join(', ')})`;
+	}
+	return `deps: waiting on ${item.eligibility.blockedBy.missing.join(', ')}`;
+}
+
+/** Ready items get a filled marker, blocked ones an open one. */
+function readinessMarker(entry: CategorisedItem): string {
+	return entry.ready ? '*' : 'o';
+}
+
+function formatItem(entry: CategorisedItem): string {
+	return `      ${readinessMarker(entry)} ${entry.item.slug}   ${readinessLabel(entry.item)}`;
+}
+
+/** Render one repo's three labelled groups; empty groups show `(none)`. */
+function formatRepo(path: string, groups: CategorisedGroups): string[] {
+	const lines: string[] = [];
+	lines.push(`  ${path}`);
+	lines.push('');
+	for (const category of CATEGORY_ORDER) {
+		lines.push(`    ${CATEGORY_LABELS[category]}:`);
+		const entries = groups[category];
+		if (entries.length === 0) {
+			lines.push('      (none)');
+		} else {
+			for (const entry of entries) {
+				lines.push(formatItem(entry));
+			}
+		}
+	}
+	lines.push('');
+	return lines;
+}
+
+function pluralRepos(n: number): string {
+	return n === 1 ? 'repo' : 'repos';
+}
+
+function pluralItems(n: number): string {
+	return n === 1 ? 'item' : 'items';
+}
+
+/**
+ * The divergence-vs-arbiter line for the cwd-local section, using the
+ * `main-divergence-guard` framing: local `main` AHEAD of `<arbiter>/main` means
+ * UNPUSHED commits (the local working tree is more authoritative than the
+ * arbiter for those); BEHIND means the arbiter has commits the local tree lacks.
+ * When the fetch failed it says so (the divergence reflects last-known).
+ */
+function cwdDivergenceLine(
+	arbiter: NonNullable<CwdSection['arbiter']>,
+): string {
+	const freshness = arbiter.fetched
+		? 'fetched just now'
+		: 'FETCH FAILED — last-known (offline)';
+	const {ahead, behind, remote} = arbiter;
+	if (ahead === 0 && behind === 0) {
+		return `      in sync with ${remote}/main (${freshness}).`;
+	}
+	const parts: string[] = [];
+	if (ahead > 0) {
+		parts.push(`${ahead} commit${ahead === 1 ? '' : 's'} ahead (unpushed)`);
+	}
+	if (behind > 0) {
+		parts.push(`${behind} commit${behind === 1 ? '' : 's'} behind`);
+	}
+	return `      local main is ${parts.join(', ')} vs ${remote}/main (${freshness}).`;
+}
+
+/**
+ * Render the CWD-LOCAL section of `scan`/`status` (the `scan-status-read-cwd-repo`
+ * task): a DISTINCT, separately-counted block for the CURRENT repo, read from
+ * the LOCAL WORKING TREE (NOT the registry's bare mirror ref). Returns `[]` when
+ * the cwd does NOT participate (no local section). The section LABELS its source
+ * + freshness, shows the divergence-vs-arbiter (`main-divergence-guard` framing),
+ * and — when the cwd participates but is NOT registered — teaches
+ * self-registration instead of the dead-end "No participating repos found".
+ *
+ * The counts here are the cwd's OWN (never merged into the registry total — the
+ * 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.
+ */
+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;
+}
+
+export function formatCwdSection(section: CwdSection): string[] {
+	if (!section.participating || section.repo === undefined) {
+		return [];
+	}
+	const lines: string[] = [];
+	const dedup = section.alsoRegistered === true ? ' (also registered)' : '';
+	lines.push('This repo (local working tree):');
+	lines.push(`  ${section.path}${dedup}`);
+	lines.push(
+		'  source: local working tree (may be ahead of / behind the arbiter) — ' +
+			'distinct from the registry view below (arbiter main, fetched).',
+	);
+
+	// Fetch-first divergence-vs-arbiter (or a no-arbiter note).
+	if (section.arbiter !== undefined) {
+		lines.push(cwdDivergenceLine(section.arbiter));
+	} else {
+		lines.push(
+			'      no arbiter remote configured — divergence vs arbiter unknown.',
+		);
+	}
+
+	const total = section.totalItems ?? 0;
+	// Self-registration hint when the cwd participates but is NOT registered.
+	if (section.alsoRegistered !== true) {
+		lines.push('');
+		lines.push(
+			`  This repo participates (${total} backlog ${pluralItems(total)}) but is ` +
+				'NOT registered — `run`/`scan` across machines won’t see it until ' +
+				'`dorfl remote add . --local` (or `remote add <its-url>`).',
+		);
+	}
+
+	// The cwd's grouped backlog — the SAME who-can-take-it grouping the registry
+	// view uses, but read from the working tree and counted SEPARATELY.
+	const groups = categoriseItems(section.repo.items);
+	lines.push('');
+	for (const category of CATEGORY_ORDER) {
+		lines.push(`    ${CATEGORY_LABELS[category]}:`);
+		const entries = groups[category];
+		if (entries.length === 0) {
+			lines.push('      (none)');
+		} else {
+			for (const entry of entries) {
+				lines.push(formatItem(entry));
+			}
+		}
+	}
+
+	// The PER-ITEM LOCK in-flight SURFACE for the cwd (prd
+	// `ledger-status-per-item-lock-refs` US #8): held (`active` = in-progress) and
+	// `stuck` (= needs-attention) lock entries + their reasons. This is what keeps a
+	// held/stuck cwd item from vanishing: the held-slug subtraction removes it from
+	// the buckets above, so without THIS block it would be invisible (the regression
+	// this fixes). Symmetric with the registry view's `In-flight locks` block (same
+	// `refs/dorfl/lock/*` source, same primitive); rendered HERE inside the cwd
+	// section so it stays the cwd's OWN, separately-counted surface. Empty ⇒ no
+	// block (a calm repo adds no lines).
+	const lockHeld = section.repo.lockHeld ?? [];
+	if (lockHeld.length > 0) {
+		lines.push('');
+		lines.push('    In progress / stuck (lock held — refs/dorfl/lock/*):');
+		for (const entry of lockHeld) {
+			lines.push(...formatLockEntryLines(entry, '      '));
+		}
+	}
+	lines.push('');
+	lines.push(
+		`  Local total: ${total} ${pluralItems(total)} ` +
+			`(${section.totalEligible ?? 0} eligible) — this repo only, NOT merged with ` +
+			'the registry total below.',
+	);
+	return lines;
+}
+
+/**
+ * Render the cross-repo queue as a human decision dashboard: under each repo,
+ * every backlog item is grouped by who-can-take-it (Agent-claimable now /
+ * Human-only / Blocked), with empty groups shown as `(none)`. Within a group,
+ * ready (deps-satisfied) items sort above blocked ones.
+ *
+ * The set of groups shown is INDEPENDENT of `autoBuild`; only the eligibility
+ * *verdict* line reflects the policy (`report.totalEligible` counts an
+ * agent-claimable item only when `autoBuild` is on).
+ */
+export function formatReport(report: ScanReport, cwd?: CwdSection): string {
+	const lines: string[] = [];
+
+	// The cwd-local section (the `scan-status-read-cwd-repo` task): a DISTINCT,
+	// separately-counted block for the CURRENT repo, ABOVE the registry view.
+	const cwdLines = cwd !== undefined ? formatCwdSection(cwd) : [];
+	if (cwdLines.length > 0) {
+		lines.push(...cwdLines);
+		lines.push('');
+	}
+
+	// De-dup: when the cwd is ALSO registered, drop its registry row (shown once,
+	// above, marked "(also registered)") so the same repo never appears twice.
+	const registryRepos =
+		cwd?.alsoRegistered === true && cwd.registeredMirrorPath !== undefined
+			? report.repos.filter((r) => r.path !== cwd.registeredMirrorPath)
+			: report.repos;
+
+	if (registryRepos.length === 0) {
+		// If the cwd participates we already rendered its local section above (no
+		// dead-end). Otherwise keep the existing empty-state.
+		if (cwdLines.length === 0) {
+			lines.push('No participating repos found.');
+			lines.push(
+				'(A repo participates iff its work/ tree has lifecycle content in any ' +
+					'pool: tasks/ready, tasks/backlog, prds/proposed, prds/ready, ' +
+					'notes/observations, or questions.)',
+			);
+		} else {
+			lines.push(
+				'Registered repos: (none) — nothing registered in the registry yet.',
+			);
+		}
+		return lines.join('\n').replace(/\n+$/, '');
+	}
+
+	lines.push('Registered repos (registry — arbiter main, fetched):');
+	lines.push('');
+	const allGroups: CategorisedGroups[] = [];
+	for (const repo of registryRepos) {
+		const groups = categoriseItems(repo.items);
+		allGroups.push(groups);
+		lines.push(...formatRepo(repo.path, groups));
+		// The one-slug-one-folder LINT (prd `ledger-integrity` story 3): WARN LOUDLY
+		// when any slug in this repo's ledger resides in >1 status folder (a corrupt
+		// ledger — never a silent pass). Clean ledgers add no lines.
+		const warnings = formatDuplicateWarnings(repo.ledgerDuplicates ?? []);
+		if (warnings.length > 0) {
+			lines.push(...warnings.map((w) => `  ${w}`));
+			lines.push('');
+		}
+	}
+
+	const s = summariseGroups(allGroups);
+	const repoCount = registryRepos.length;
+	const registryItems = registryRepos.reduce((n, r) => n + r.items.length, 0);
+	const registryEligible = registryRepos.reduce(
+		(n, r) => n + r.items.filter((i) => i.eligibility.eligible).length,
+		0,
+	);
+	lines.push(
+		`Registry summary: ${registryItems} item(s) across ${repoCount} ${pluralRepos(repoCount)} — ` +
+			`${s.agentClaimable} agent-claimable, ${s.humanOnly} human-only, ` +
+			`${s.needsAnswers} needs-answers, ${s.blocked} blocked ` +
+			`(${s.ready} ready).`,
+	);
+	lines.push(
+		`Runner verdict: ${registryEligible}/${registryItems} item(s) eligible now ` +
+			`(under the current --auto-build policy).`,
+	);
+
+	return lines.join('\n');
+}