pi-crew 0.11.11 → 0.11.13

package/src/runtime/child-pi/postmortem-registry.ts

@@ -0,0 +1,134 @@
+/**
+ * postmortem-registry.ts — U15: postmortem cleanup registry (pi-crew port).
+ *
+ * Ported from gajae-code `packages/utils/src/postmortem.ts` (fork pi-mono
+ * v0.8.2, spec U15 of pi-crew-upgrade-spec-2026-10-09.md), reduced to the
+ * ~80-line core pi-crew needs: reap still-live owned process groups on fatal
+ * or normal shutdown. Owners deregister from this registry only AFTER their
+ * teardown completed (owned-process.ts owns that discipline).
+ *
+ * Divergence from the gajae-code original (deliberate, reviewed against the
+ * spec's "guest in host process" constraint):
+ *   - The original OWNS its process: after cleanup it calls
+ *     `process.exit(128+sig)` / `process.exit(1)`. pi-crew runs as an EXTENSION
+ *     inside the pi host process (and standalone inside background-runner),
+ *     where other pi-crew modules already register SIGINT/SIGTERM/SIGHUP/
+ *     uncaught/unhandled listeners (event-log.ts, atomic-write.ts,
+ *     crew-cleanup.ts, background-runner.ts) without forcing exit. Forcing
+ *     exit here would race the host's own shutdown path, so this port NEVER
+ *     calls process.exit — hooks reap best-effort while the real exit path
+ *     drains, and the 'exit' listener fires a last sync-effort kick.
+ *   - "run once per process" is relaxed to "concurrent runs share one
+ *     in-flight promise" because a host can survive a SIGTERM-like signal and
+ *     must stay re-armable; per-process once-only semantics are the caller's
+ *     (owned groups deregister themselves after teardown, so a second run has
+ *     nothing left to reap).
+ *
+ * Listener model (installed lazily on first registration):
+ *   - exit                  → fire-and-forget async run (cannot await; hooks
+ *                             whose sync prefix sends SIGTERM still deliver).
+ *   - SIGINT/SIGTERM/SIGHUP → setImmediate kick (house pattern from
+ *                             event-log.ts) so sync flush handlers run first.
+ *   - uncaughtException/unhandledRejection → setImmediate kick, never swallow:
+ *                             we add no output and no exit; existing pi-crew
+ *                             fatal handlers already own crash reporting (and
+ *                             already suppress Node's default, see event-log).
+ */
+
+import { logInternalError } from "../../utils/internal-error.ts";
+
+export type PostmortemReason = "exit" | "SIGINT" | "SIGTERM" | "SIGHUP" | "uncaughtException" | "unhandledRejection" | "manual";
+
+export type PostmortemHook = (reason: PostmortemReason) => void | Promise<void>;
+
+// Registered hooks, keyed by owner name. Last-wins on re-registration (same
+// discipline as gajae-code's resource-owner map): a re-adopt with the same name
+// replaces the prior hook instead of accumulating duplicates.
+const postmortemHooks = new Map<string, PostmortemHook>();
+
+let listenersInstalled = false;
+let inFlightRun: Promise<void> | undefined;
+
+/**
+ * Run every registered postmortem hook for `reason`. Concurrent invocations
+ * share the single in-flight run (recursion/reentry guard); failures are
+ * isolated per hook and logged, never propagated — one bad owner must not
+ * block the others from reaping.
+ */
+export function runPostmortemCleanup(reason: PostmortemReason): Promise<void> {
+	if (inFlightRun) return inFlightRun;
+	inFlightRun = (async () => {
+		try {
+			await Promise.allSettled(
+				[...postmortemHooks.entries()].map(async ([name, hook]) => {
+					try {
+						await hook(reason);
+					} catch (err) {
+						logInternalError(
+							"child-pi.postmortem-hook",
+							err instanceof Error ? err : new Error(String(err)),
+							`name=${name} reason=${reason}`,
+						);
+					}
+				}),
+			);
+		} finally {
+			inFlightRun = undefined;
+		}
+	})();
+	return inFlightRun;
+}
+
+/**
+ * Register a postmortem cleanup hook. Idempotent by `name`: re-registering
+ * replaces the prior hook (last wins). Returns an unregister function that
+ * removes the owner only while it is still the active registration for that
+ * name — a stale unregister cannot remove a newer registration.
+ */
+export function registerPostmortemCleanup(name: string, hook: PostmortemHook): () => void {
+	postmortemHooks.set(name, hook);
+	ensurePostmortemListeners();
+	let unregistered = false;
+	return () => {
+		if (unregistered) return;
+		unregistered = true;
+		// Only remove when this exact hook is still the active registration —
+		// guards the "late unregister must not evict a newer adopter" case.
+		if (postmortemHooks.get(name) === hook) postmortemHooks.delete(name);
+	};
+}
+
+/** Number of registered postmortem hooks. Exposed for leak assertions/tests. */
+export function postmortemHookCount(): number {
+	return postmortemHooks.size;
+}
+
+/** Install the process-level listeners exactly once, on first registration. */
+function ensurePostmortemListeners(): void {
+	if (listenersInstalled) return;
+	listenersInstalled = true;
+	// 'exit' is synchronous: an async hook can only run its sync prefix here
+	// (e.g. signalTree("SIGTERM") inside dispose()) before the process dies.
+	// The remaining escalation is covered owner-side while alive + child-side
+	// by the PI_CREW_PARENT_PID guard (complementary per spec U15).
+	process.on("exit", () => {
+		void runPostmortemCleanup("exit");
+	});
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+		process.on(signal, () => {
+			setImmediate(() => {
+				void runPostmortemCleanup(signal);
+			});
+		});
+	}
+	process.on("uncaughtException", () => {
+		setImmediate(() => {
+			void runPostmortemCleanup("uncaughtException");
+		});
+	});
+	process.on("unhandledRejection", () => {
+		setImmediate(() => {
+			void runPostmortemCleanup("unhandledRejection");
+		});
+	});
+}

package/src/runtime/classifier/ambient-noise-gate.ts

@@ -0,0 +1,126 @@
+/**
+ * U6A (upgrade spec 2026-10-09, §U6 Phase A): generalized "ambient-noise vs
+ * real-failure" classifier gate for the DISPATCH-BATCH retry loop —
+ * the sibling of child-executor's model-fallback `triageRetryWithClassifier`
+ * (retry-triage). Same never-rejects contract, same dormant default
+ * (`runtime.classifierEnabled`, default FALSE — resolveClassifierEnabled),
+ * one shared flag/model for both consumers.
+ *
+ * Semantics: after a failed task attempt and BEFORE the next (expensive)
+ * worker re-spawn is queued, ask the host classifier ONE bool question — is
+ * the failure AMBIENT NOISE (transient/environmental: rate limit, provider
+ * hiccup, timeout, network blip — a fresh attempt has a realistic chance)
+ * rather than a REAL FAILURE (deterministic: auth/permission denied, invalid
+ * request, missing resource — the retry will fail the same way)?
+ *
+ * SOFT-BRANCH CONTRACT (spec caveat, mandatory):
+ *   - opencode/provider unconfigured (`getAvailableOfType("classifier")` →
+ *     [], classify stopReason "error") → caller fallback;
+ *   - classify throws / registry absent → caller fallback;
+ *   - fallback on EVERY failure mode is `proceedWithRetry: true` — the
+ *     pre-existing retry behavior. A wrong classifier verdict can only SKIP
+ *     one queued retry (the task surfaces its original error — the same
+ *     outcome as retry exhaustion); it can NEVER fail a task with a new
+ *     error or block the loop.
+ *
+ * Diagnostics (confidence monitoring, spec Phase A):
+ *   - `crew.classifier.calls_total{consumer="ambient_noise_gate",outcome}`
+ *     + `crew.classifier.confidence` histogram via classifyBool;
+ *   - `crew.classifier.decisions_total{consumer,decision}` and a
+ *     `task.noise_gate` event ONLY when a real classifier answer informed
+ *     the decision (fallback paths are already counted by the service's
+ *     calls_total and must not double-report a decision they did not make).
+ */
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
+import { appendEventAsync } from "../../state/event-log/event-log.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { classifyBool } from "./classifier-service.ts";
+
+export interface AmbientNoiseGateArgs {
+	/** Pre-resolved gate (resolveClassifierEnabled) — false short-circuits before ANY registry touch. */
+	enabled: boolean;
+	/** Host-process model registry (ctx.modelRegistry, threaded unknown). */
+	modelRegistry: unknown;
+	/** Pre-resolved classifier model id (resolveClassifierModel). */
+	classifierModel: string;
+	/** Failure summary the retry loop computed (the thrown attempt error message). */
+	failureSummary: string;
+	/** 1-based index of the attempt that just failed. */
+	attempt: number;
+	/** Retry policy maxAttempts (context for the classifier, not enforced here). */
+	maxAttempts: number;
+	/** Event-log identity for the task.noise_gate diagnostic event. */
+	eventsPath: string;
+	runId: string;
+	taskId: string;
+	/** Optional host metric registry (crew.classifier.* counters/histograms). */
+	metricRegistry?: MetricRegistry;
+}
+
+export interface AmbientNoiseGateResult {
+	/** false → skip the queued retry attempt (classifier judged the failure real/deterministic). */
+	proceedWithRetry: boolean;
+	/** true ONLY when a real classifier answer informed the decision (event + decision metric emitted). */
+	consulted: boolean;
+}
+
+/**
+ * Ask the ambient-noise gate. NEVER REJECTS and never throws up to the
+ * caller — the disabled path returns without touching the registry (zero
+ * behavior change), every classifier failure mode falls back to
+ * `proceedWithRetry: true`.
+ */
+export async function classifyAmbientNoiseGate(args: AmbientNoiseGateArgs): Promise<AmbientNoiseGateResult> {
+	if (!args.enabled) return { proceedWithRetry: true, consulted: false };
+	const result = await classifyBool({
+		modelRegistry: args.modelRegistry,
+		classifierModel: args.classifierModel,
+		questionKey: "ambient",
+		question: {
+			type: "bool",
+			instructions:
+				"A dispatched worker task attempt failed and an automatic retry is queued (the worker will be re-spawned from scratch). Read the failure state. Is the failure AMBIENT NOISE (transient or environmental — rate limit, provider hiccup, timeout, network error, stale lock — a fresh attempt has a realistic chance of success) rather than a REAL FAILURE (deterministic — auth or permission denied, invalid request, missing resource, code or prompt defect — the retry will fail the same way)?",
+			criteria: {
+				true: "Ambient noise — the queued retry may succeed",
+				false: "Real failure — the queued retry will fail the same way",
+			},
+		},
+		state: {
+			// Cap the summary: classifiers reason over small JSON state — the raw
+			// error can carry multi-KB stderr tails (same cap as retry-triage).
+			failureSummary: args.failureSummary.slice(0, 2000),
+			attempt: args.attempt,
+			maxAttempts: args.maxAttempts,
+		},
+		fallback: true,
+		metricRegistry: args.metricRegistry,
+		metricLabels: { consumer: "ambient_noise_gate" },
+	});
+	if (!result.fromClassifier) return { proceedWithRetry: true, consulted: false };
+	const decision = result.decision ? "noise_retry" : "real_giveup";
+	try {
+		args.metricRegistry?.counter("crew.classifier.decisions_total", "Classifier-informed decisions by consumer and verdict").inc({
+			consumer: "ambient_noise_gate",
+			decision,
+		});
+	} catch (metricError) {
+		logInternalError("ambient-noise-gate.metric", metricError, `decision=${decision}`, "warn");
+	}
+	void appendEventAsync(args.eventsPath, {
+		type: "task.noise_gate",
+		runId: args.runId,
+		taskId: args.taskId,
+		message: `Ambient-noise gate classified the attempt-${args.attempt} failure as ${decision} (classifier ${result.usedModel ?? args.classifierModel})`,
+		data: {
+			decision,
+			attempt: args.attempt,
+			classifierModel: result.usedModel,
+			configuredModel: args.classifierModel,
+			stopReason: result.stopReason,
+			...(result.confidence !== undefined ? { confidence: result.confidence } : {}),
+		},
+	}).catch(() => {
+		/* no-op: best-effort diagnostic append, ignore delivery errors */
+	});
+	return { proceedWithRetry: result.decision, consulted: true };
+}

package/src/runtime/classifier/classifier-service.ts

@@ -39,18 +39,36 @@ export interface ClassifierBoolQuestion {
 	criteria?: { true: string; false: string };
 }
 
+/** U6B (upgrade spec 2026-10-09 §U6 Phase B): one typed SCORE question — the
+ *  graded sibling of {@link ClassifierBoolQuestion}, used by the verifier
+ *  pre-gate. Mirrors pi-ai's ClassifierScoreQuestion (pi-ai dist/types.d.ts:
+ *  {type:"score", instructions, criteria: string[]}); answers arrive as the
+ *  ClassifierScoreAnswer shape {type:"score", score, confidence} — score is
+ *  the graded 0..1 reading, confidence the provider-reported certainty. */
+export interface ClassifierScoreQuestion {
+	type: "score";
+	instructions: string;
+	/** Rubric anchors for the 0..1 scale, ordered decisive (1.0) → useless (0.0). */
+	criteria: string[];
+}
+
 /** Request body for modelRegistry.classify(model, request). */
 export interface ClassifyRequest {
 	state: Record<string, unknown>;
-	questions: Record<string, ClassifierBoolQuestion>;
+	questions: Record<string, ClassifierBoolQuestion | ClassifierScoreQuestion>;
 }
 
 /** Structured result shape returned by modelRegistry.classify (never throws
- *  per model-registry.d.ts — but we still guard a throwing implementation). */
+ *  per model-registry.d.ts — but we still guard a throwing implementation).
+ *  U6A (spec 2026-10-09 §U6 Phase A): `confidence` is a passthrough — the
+ *  classify API documents answers "kèm confidence" (research §8.2); when a
+ *  provider reports it (top-level or per-answer `{value, confidence}`), we
+ *  surface it on the result + `crew.classifier.confidence` histogram. */
 export interface ClassifyCallResult {
 	answers?: Record<string, unknown>;
 	stopReason?: string;
 	errorMessage?: string;
+	confidence?: number;
 }
 
 /** Duck-typed host registry handle (mirrors ModelRegistryLike in
@@ -101,6 +119,47 @@ export interface ClassifyBoolResult {
 	/** Raw stopReason / errorMessage from the classify call, when one ran. */
 	stopReason: string | undefined;
 	errorMessage: string | undefined;
+	/** U6A: provider-reported answer confidence, when the registry supplied
+	 *  one (top-level `confidence` or per-answer `{value, confidence}`).
+	 *  Undefined on every fallback path and for bare-boolean answers. */
+	confidence: number | undefined;
+}
+
+export interface ClassifyScoreInput {
+	/** Host-process model registry handle (ctx.modelRegistry, threaded unknown). */
+	modelRegistry: unknown;
+	/** Configured classifier model id ("provider/id"). */
+	classifierModel: string;
+	/** Key under `questions` carrying the score question. */
+	questionKey: string;
+	question: ClassifierScoreQuestion;
+	/** JSON state the classifier reasons about (keep small + low-cardinality). */
+	state: Record<string, unknown>;
+	/** Caller-provided fallback score — returned on EVERY failure mode. */
+	fallback: number;
+	/** Optional metric registry (counter created on demand, dispatch-batch style). */
+	metricRegistry?: MetricRegistry;
+	/** Extra low-cardinality labels for the calls_total counter. */
+	metricLabels?: Record<string, string>;
+}
+
+export interface ClassifyScoreResult {
+	/** Effective graded reading: the classifier score, or the caller fallback. */
+	score: number;
+	/** True ONLY when a real classifier answer informed the score. */
+	fromClassifier: boolean;
+	/** Which branch produced the outcome (diagnostics + metric label). */
+	reason: ClassifierOutcomeReason;
+	/** Classifier model id actually used (undefined on every fallback path). */
+	usedModel: string | undefined;
+	/** Raw stopReason / errorMessage from the classify call, when one ran. */
+	stopReason: string | undefined;
+	errorMessage: string | undefined;
+	/** Provider-reported answer confidence (answer-level or top-level), when
+	 *  supplied. The pi-ai ClassifierScoreAnswer shape marks confidence
+	 *  REQUIRED, but a defensive read tolerates its absence. Undefined on
+	 *  every fallback path. */
+	confidence: number | undefined;
 }
 
 /**
@@ -144,6 +203,24 @@ function outcomeMetric(
 	}
 }
 
+/** U6A: observe the provider-reported confidence when one was supplied.
+ *  Mirrors outcomeMetric's never-break contract. */
+function confidenceMetric(
+	metricRegistry: MetricRegistry | undefined,
+	confidence: number | undefined,
+	labels: Record<string, string> | undefined,
+): void {
+	if (confidence === undefined) return;
+	try {
+		metricRegistry
+			?.histogram("crew.classifier.confidence", "Classifier answer confidence when reported", [0.25, 0.5, 0.75, 0.9, 0.99])
+			.observe({ ...labels }, confidence);
+	} catch (error) {
+		// Metric plumbing must never break the never-rejects contract.
+		logInternalError("classifier-service.metric", error, `confidence=${confidence}`, "warn");
+	}
+}
+
 /** Normalize a registry handle into the duck-typed classifier surface. */
 function asClassifierRegistry(modelRegistry: unknown): ClassifierModelRegistryLike | undefined {
 	if (!modelRegistry || typeof modelRegistry !== "object" || Array.isArray(modelRegistry)) return undefined;
@@ -173,25 +250,56 @@ export function resolveClassifierModel(explicit?: string): string {
 }
 
 /**
- * Ask ONE bool question of a host-process classifier. NEVER REJECTS — every
- * failure mode (no registry, no credentialed classifier, thrown error,
- * stopReason !== "stop", missing/non-boolean answer) returns the
- * caller-provided fallback with {@link ClassifyBoolResult.fromClassifier}
- * false, after a log-once note + metric counter increment.
+ * Internal shared pipeline for the typed classify wrappers (U6B): resolves a
+ * usable classifier and runs ONE classify call, returning either the raw
+ * answer for the question key or a fallback marker with the outcome reason.
+ * Every registry-level failure mode (missing registry, zero credentialed
+ * classifiers, thrown call, non-"stop" stopReason) logs once + counts its
+ * metric here; answer interpretation (classified / answer_missing) stays
+ * with the typed wrappers so each keeps its own acceptance shape. The
+ * observable behavior of classifyBool is unchanged by the extraction (its
+ * landed tests are the equivalence guard).
  */
-export async function classifyBool(input: ClassifyBoolInput): Promise<ClassifyBoolResult> {
+interface ClassifyPipelineInput {
+	/** Host-process model registry handle (ctx.modelRegistry, threaded unknown). */
+	modelRegistry: unknown;
+	/** Configured classifier model id ("provider/id"). */
+	classifierModel: string;
+	/** Key under `questions` carrying the typed question. */
+	questionKey: string;
+	question: ClassifierBoolQuestion | ClassifierScoreQuestion;
+	/** JSON state the classifier reasons about (keep small + low-cardinality). */
+	state: Record<string, unknown>;
+	/** Optional metric registry (counter created on demand, dispatch-batch style). */
+	metricRegistry?: MetricRegistry;
+	/** Extra low-cardinality labels for the calls_total counter. */
+	metricLabels?: Record<string, string>;
+}
+
+interface ClassifyPipelineOk {
+	status: "ok";
+	/** Raw answers[questionKey] value — the wrapper decides the acceptance shape. */
+	rawAnswer: unknown;
+	/** Top-level result.confidence passthrough, when finite. */
+	topLevelConfidence: number | undefined;
+	stopReason: string | undefined;
+	errorMessage: string | undefined;
+	usedModel: string;
+}
+
+interface ClassifyPipelineFallback {
+	status: "fallback";
+	reason: ClassifierOutcomeReason;
+	stopReason: string | undefined;
+	errorMessage: string | undefined;
+}
+
+async function runClassifyQuestion(input: ClassifyPipelineInput): Promise<ClassifyPipelineOk | ClassifyPipelineFallback> {
 	const registry = asClassifierRegistry(input.modelRegistry);
 	if (!registry || typeof registry.getAvailableOfType !== "function" || typeof registry.classify !== "function") {
 		noteFailureMode("registry_missing", input.classifierModel, "model registry absent or lacks the classifier surface");
 		outcomeMetric(input.metricRegistry, "registry_missing", input.metricLabels);
-		return {
-			decision: input.fallback,
-			fromClassifier: false,
-			reason: "registry_missing",
-			usedModel: undefined,
-			stopReason: undefined,
-			errorMessage: undefined,
-		};
+		return { status: "fallback", reason: "registry_missing", stopReason: undefined, errorMessage: undefined };
 	}
 	// Credentialed classifiers only — the catalog (getModelsOfType) can list
 	// models whose provider has no key on this host (R2.3: 6 catalog entries,
@@ -203,14 +311,7 @@ export async function classifyBool(input: ClassifyBoolInput): Promise<ClassifyBo
 	} catch (error) {
 		noteFailureMode("classify_threw", input.classifierModel, `getAvailableOfType threw: ${String(error)}`);
 		outcomeMetric(input.metricRegistry, "classify_threw", input.metricLabels);
-		return {
-			decision: input.fallback,
-			fromClassifier: false,
-			reason: "classify_threw",
-			usedModel: undefined,
-			stopReason: undefined,
-			errorMessage: undefined,
-		};
+		return { status: "fallback", reason: "classify_threw", stopReason: undefined, errorMessage: undefined };
 	}
 	if (!Array.isArray(available) || available.length === 0) {
 		noteFailureMode(
@@ -219,14 +320,7 @@ export async function classifyBool(input: ClassifyBoolInput): Promise<ClassifyBo
 			"getAvailableOfType('classifier') is empty — no credentialed classifier",
 		);
 		outcomeMetric(input.metricRegistry, "no_classifier_available", input.metricLabels);
-		return {
-			decision: input.fallback,
-			fromClassifier: false,
-			reason: "no_classifier_available",
-			usedModel: undefined,
-			stopReason: undefined,
-			errorMessage: undefined,
-		};
+		return { status: "fallback", reason: "no_classifier_available", stopReason: undefined, errorMessage: undefined };
 	}
 	// Prefer the configured model id; fall back to the first available
 	// candidate so a renamed catalog id still gets a usable classifier.
@@ -250,49 +344,171 @@ export async function classifyBool(input: ClassifyBoolInput): Promise<ClassifyBo
 				`classify stopReason=${stopReason ?? "undefined"}${errorMessage ? ` errorMessage=${errorMessage}` : ""}`,
 			);
 			outcomeMetric(input.metricRegistry, "stop_reason_error", input.metricLabels);
-			return {
-				decision: input.fallback,
-				fromClassifier: false,
-				reason: "stop_reason_error",
-				usedModel: undefined,
-				stopReason,
-				errorMessage,
-			};
+			return { status: "fallback", reason: "stop_reason_error", stopReason, errorMessage };
 		}
-		const answer = result?.answers?.[input.questionKey];
-		if (typeof answer !== "boolean") {
-			noteFailureMode("answer_missing", input.classifierModel, `answers[${input.questionKey}] is ${typeof answer}, expected boolean`);
-			outcomeMetric(input.metricRegistry, "answer_missing", input.metricLabels);
-			return {
-				decision: input.fallback,
-				fromClassifier: false,
-				reason: "answer_missing",
-				usedModel: undefined,
-				stopReason,
-				errorMessage,
-			};
-		}
-		outcomeMetric(input.metricRegistry, "classified", input.metricLabels);
+		const topLevelConfidence =
+			typeof result?.confidence === "number" && Number.isFinite(result.confidence) ? result.confidence : undefined;
 		return {
-			decision: answer,
-			fromClassifier: true,
-			reason: "classified",
-			usedModel,
+			status: "ok",
+			rawAnswer: result?.answers?.[input.questionKey],
+			topLevelConfidence,
 			stopReason,
 			errorMessage,
+			usedModel,
 		};
 	} catch (error) {
 		// The registry contract says classify never rejects, but a misbehaving
 		// implementation must still not take the orchestrator down with it.
 		noteFailureMode("classify_threw", input.classifierModel, `classify threw: ${String(error)}`);
 		outcomeMetric(input.metricRegistry, "classify_threw", input.metricLabels);
+		return { status: "fallback", reason: "classify_threw", stopReason: undefined, errorMessage: undefined };
+	}
+}
+
+/**
+ * Ask ONE bool question of a host-process classifier. NEVER REJECTS — every
+ * failure mode (no registry, no credentialed classifier, thrown error,
+ * stopReason !== "stop", missing/non-boolean answer) returns the
+ * caller-provided fallback with {@link ClassifyBoolResult.fromClassifier}
+ * false, after a log-once note + metric counter increment.
+ */
+export async function classifyBool(input: ClassifyBoolInput): Promise<ClassifyBoolResult> {
+	const outcome = await runClassifyQuestion(input);
+	if (outcome.status === "fallback") {
 		return {
 			decision: input.fallback,
 			fromClassifier: false,
-			reason: "classify_threw",
+			reason: outcome.reason,
+			usedModel: undefined,
+			stopReason: outcome.stopReason,
+			errorMessage: outcome.errorMessage,
+			confidence: undefined,
+		};
+	}
+	const rawAnswer = outcome.rawAnswer;
+	// U6A: bool answers arrive either as a bare boolean or wrapped with a
+	// confidence reading (`{value: boolean, confidence: number}` — research
+	// §8.2 "typed choice/score/bool ... answers carry confidence"). Accept
+	// both shapes; everything else stays the answer_missing fallback.
+	let answer: boolean | undefined;
+	let confidence: number | undefined;
+	if (typeof rawAnswer === "boolean") {
+		answer = rawAnswer;
+	} else if (rawAnswer && typeof rawAnswer === "object" && !Array.isArray(rawAnswer)) {
+		const wrapped = rawAnswer as { value?: unknown; confidence?: unknown };
+		if (typeof wrapped.value === "boolean") {
+			answer = wrapped.value;
+			if (typeof wrapped.confidence === "number" && Number.isFinite(wrapped.confidence)) {
+				confidence = wrapped.confidence;
+			}
+		}
+	}
+	if (outcome.topLevelConfidence !== undefined && confidence === undefined) {
+		confidence = outcome.topLevelConfidence;
+	}
+	if (answer === undefined) {
+		noteFailureMode("answer_missing", input.classifierModel, `answers[${input.questionKey}] is ${typeof rawAnswer}, expected boolean`);
+		outcomeMetric(input.metricRegistry, "answer_missing", input.metricLabels);
+		return {
+			decision: input.fallback,
+			fromClassifier: false,
+			reason: "answer_missing",
+			usedModel: undefined,
+			stopReason: outcome.stopReason,
+			errorMessage: outcome.errorMessage,
+			confidence: undefined,
+		};
+	}
+	outcomeMetric(input.metricRegistry, "classified", input.metricLabels);
+	confidenceMetric(input.metricRegistry, confidence, input.metricLabels);
+	return {
+		decision: answer,
+		fromClassifier: true,
+		reason: "classified",
+		usedModel: outcome.usedModel,
+		stopReason: outcome.stopReason,
+		errorMessage: outcome.errorMessage,
+		confidence,
+	};
+}
+
+/**
+ * Ask ONE score question of a host-process classifier (U6B — the graded
+ * sibling of {@link classifyBool}, consumer: verifier pre-gate). NEVER
+ * REJECTS — every failure mode (no registry, no credentialed classifier,
+ * thrown error, stopReason !== "stop", missing/non-numeric answer) returns
+ * the caller-provided fallback score with
+ * {@link ClassifyScoreResult.fromClassifier} false, after a log-once note +
+ * metric counter increment. A malformed or unconfigured classifier can only
+ * degrade to the caller fallback — it can never fail a task.
+ */
+export async function classifyScore(input: ClassifyScoreInput): Promise<ClassifyScoreResult> {
+	const outcome = await runClassifyQuestion(input);
+	if (outcome.status === "fallback") {
+		return {
+			score: input.fallback,
+			fromClassifier: false,
+			reason: outcome.reason,
+			usedModel: undefined,
+			stopReason: outcome.stopReason,
+			errorMessage: outcome.errorMessage,
+			confidence: undefined,
+		};
+	}
+	const rawAnswer = outcome.rawAnswer;
+	// Real pi-ai shape (ClassifierScoreAnswer): {type:"score", score: number,
+	// confidence: number} — the type marks confidence REQUIRED, but a
+	// defensive read tolerates its absence. A bare-number answer and the U6A
+	// wrapped {value, confidence} shape are accepted for symmetry with
+	// classifyBool; everything else stays the answer_missing fallback.
+	let score: number | undefined;
+	let confidence: number | undefined;
+	if (typeof rawAnswer === "number" && Number.isFinite(rawAnswer)) {
+		score = rawAnswer;
+	} else if (rawAnswer && typeof rawAnswer === "object" && !Array.isArray(rawAnswer)) {
+		const wrapped = rawAnswer as { score?: unknown; value?: unknown; confidence?: unknown };
+		const candidate =
+			typeof wrapped.score === "number" && Number.isFinite(wrapped.score)
+				? wrapped.score
+				: typeof wrapped.value === "number" && Number.isFinite(wrapped.value)
+					? wrapped.value
+					: undefined;
+		if (candidate !== undefined) {
+			score = candidate;
+			if (typeof wrapped.confidence === "number" && Number.isFinite(wrapped.confidence)) {
+				confidence = wrapped.confidence;
+			}
+		}
+	}
+	if (outcome.topLevelConfidence !== undefined && confidence === undefined) {
+		confidence = outcome.topLevelConfidence;
+	}
+	if (score === undefined) {
+		noteFailureMode(
+			"answer_missing",
+			input.classifierModel,
+			`answers[${input.questionKey}] is ${typeof rawAnswer}, expected score number`,
+		);
+		outcomeMetric(input.metricRegistry, "answer_missing", input.metricLabels);
+		return {
+			score: input.fallback,
+			fromClassifier: false,
+			reason: "answer_missing",
 			usedModel: undefined,
-			stopReason: undefined,
-			errorMessage: undefined,
+			stopReason: outcome.stopReason,
+			errorMessage: outcome.errorMessage,
+			confidence: undefined,
 		};
 	}
+	outcomeMetric(input.metricRegistry, "classified", input.metricLabels);
+	confidenceMetric(input.metricRegistry, confidence, input.metricLabels);
+	return {
+		score,
+		fromClassifier: true,
+		reason: "classified",
+		usedModel: outcome.usedModel,
+		stopReason: outcome.stopReason,
+		errorMessage: outcome.errorMessage,
+		confidence,
+	};
 }