gentle-pi 3.2.1 → 3.3.0

package/lib/shell-usage-view.ts

@@ -1,5 +1,6 @@
-import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { renderUsagePanel, type ActiveProvider, type UsageStore, type UsageTheme } from "./shell-usage.ts";
+import { paintHoverable } from "./shell-hover.ts";
 
 // Gentle Shell subscriptions overlay: a framed panel over the usage store.
 // It reads the store on every render, so a refresh only needs to record.
@@ -33,10 +34,32 @@ function fit(text: string, width: number): string {
 	return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
 }
 
+// Column offset of the footer's hint text within the rendered line: the
+// frame draws "│ " before the fitted content starts.
+const HINT_CONTENT_OFFSET = 2;
+const HINT_GAP = "   ";
+
+type HintAction = "refresh" | "close";
+
+interface HintSpan {
+	start: number;
+	end: number;
+	action: HintAction;
+}
+
+interface PointerLayout {
+	width: number;
+	height: number;
+	row: number;
+	spans: HintSpan[];
+}
+
 export class UsageView {
 	private readonly store: UsageStore;
 	private readonly deps: UsageViewDeps;
 	private refreshing = false;
+	private pointer: PointerLayout | undefined;
+	private hoveredHint: HintAction | undefined;
 
 	constructor(store: UsageStore, deps: UsageViewDeps) {
 		this.store = store;
@@ -48,13 +71,25 @@ export class UsageView {
 			this.deps.onClose();
 			return;
 		}
-		if (data === "r" && !this.refreshing) {
-			this.refreshing = true;
+		if (data === "r") this.refresh();
+	}
+
+	// A failing usage fetch is the store's problem to report (its rows already
+	// carry the last error); the panel only clears its "refreshing" state. The
+	// rejection must never leave this method: an unhandled rejection is fatal
+	// to the whole shell on current Node.
+	private refresh(): void {
+		if (this.refreshing) return;
+		this.refreshing = true;
+		this.deps.requestRender();
+		const settle = () => {
+			this.refreshing = false;
 			this.deps.requestRender();
-			void this.deps.onRefresh().finally(() => {
-				this.refreshing = false;
-				this.deps.requestRender();
-			});
+		};
+		try {
+			this.deps.onRefresh().then(settle, settle);
+		} catch {
+			settle();
 		}
 	}
 
@@ -66,11 +101,64 @@ export class UsageView {
 		const body = renderUsagePanel(this.store.all(), theme, inner - 2, this.deps.now(), this.deps.active()).map(
 			(line) => `${theme.fg(FRAME_ROLE, "│")} ${fit(line, inner - 2)} ${theme.fg(FRAME_ROLE, "│")}`,
 		);
-		const keys = KEYS.map(([key, label]) => `${theme.fg(KEY_ROLE, key)} ${theme.fg(KEY_TEXT_ROLE, label)}`).join("   ");
+		const hints = KEYS.map(([key, label]) => ({ key, label, text: `${key} ${label}`, action: (key === "r" ? "refresh" : "close") as HintAction }));
+		// The hovered hint paints entirely in the shared hover role (key and
+		// label together, one color) instead of its ordinary two-role split --
+		// the same treatment every other clickable surface uses.
+		const keys = hints
+			.map(({ key, label, action }) =>
+				this.hoveredHint === action ? paintHoverable(theme, `${key} ${label}`, true) : `${theme.fg(KEY_ROLE, key)} ${theme.fg(KEY_TEXT_ROLE, label)}`,
+			)
+			.join(HINT_GAP);
 		const keysLine = `${theme.fg(FRAME_ROLE, "│")} ${fit(keys, inner - 2)} ${theme.fg(FRAME_ROLE, "│")}`;
 		const bottom = theme.fg(FRAME_ROLE, `╰${rule(inner)}╯`);
-		return [top, ...body, keysLine, bottom];
+		const lines = [top, ...body, keysLine, bottom];
+		this.pointer = this.hintLayout(width, lines.length, body.length + 1, hints, inner - 2);
+		return lines;
 	}
 
-	invalidate(): void {}
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (event.type === "move" && event.button === "none") {
+			const layout = this.pointer;
+			const action = layout && event.width === layout.width && event.height === layout.height && event.y === layout.row
+				? layout.spans.find((candidate) => event.x >= candidate.start && event.x < candidate.end)?.action
+				: undefined;
+			if (action === this.hoveredHint) return action ? { handled: true } : undefined;
+			this.hoveredHint = action;
+			return { handled: true, render: true };
+		}
+		if (event.type !== "click" || event.button !== "left") return undefined;
+		const layout = this.pointer;
+		if (!layout || event.width !== layout.width || event.height !== layout.height || event.y !== layout.row) return undefined;
+		const span = layout.spans.find((candidate) => event.x >= candidate.start && event.x < candidate.end);
+		if (!span) return undefined;
+		if (span.action === "close") {
+			this.deps.onClose();
+			return { handled: true, render: true };
+		}
+		this.refresh();
+		return { handled: true, render: true };
+	}
+
+	invalidate(): void {
+		this.pointer = undefined;
+		this.hoveredHint = undefined;
+	}
+
+	// Spans are only registered when the hints text fits without truncation:
+	// past that point `fit` clips it with an ellipsis and per-hint columns no
+	// longer line up with the plain "key label" text used here.
+	private hintLayout(width: number, height: number, row: number, hints: Array<{ text: string; action: HintAction }>, contentWidth: number): PointerLayout | undefined {
+		const plainWidth = hints.reduce((total, hint) => total + hint.text.length, 0) + HINT_GAP.length * Math.max(0, hints.length - 1);
+		if (plainWidth > contentWidth) return undefined;
+		const spans: HintSpan[] = [];
+		let cursor = HINT_CONTENT_OFFSET;
+		for (const hint of hints) {
+			const start = cursor;
+			const end = start + hint.text.length;
+			spans.push({ start, end, action: hint.action });
+			cursor = end + HINT_GAP.length;
+		}
+		return { width, height, row, spans };
+	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "3.2.1",
+	"version": "3.3.0",
 	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
 	"license": "MIT",
 	"type": "module",

package/runtime/native-review-cli.mjs

@@ -1005,6 +1005,20 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// remain dark because neither is proven to reach the negotiated START
 	// path Pi consumes.
 	"3.2.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v3.4.0 (gentle-pi never pinned the intervening v3.3.0 tag, so it gets no
+	// row here) added capabilities/v2.6 and status/v8-v9, and extended
+	// `review assess` with review_due/review_due_reason/next_transition
+	// (gentle-ai #4714 follow-up). Ground-truthed by diffing
+	// contracts/review-integration/v2 and contracts/review-provider-contract
+	// between the v3.2.1 and v3.4.0 tags in the gentle-ai source tree: the
+	// provider contract stays byte-identical at 1.2.0, and every
+	// review-integration/v2 change is an additive superset (new optional
+	// schema/fields) that decodeReviewStatusV3 and the capabilities
+	// negotiator already accept without touching the closed START/STATUS
+	// fields this row negotiates, so it repeats 3.2.1 exactly. riskEvidence
+	// and hint remain dark because neither is proven to reach the negotiated
+	// START path Pi consumes.
+	"3.4.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 

package/runtime/review-integration-v2.mjs

@@ -200,6 +200,22 @@ const CAPABILITIES_SCHEMA_IDENTITIES
 		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
 		optionalFeatureFloor: 14,
 	}),
+	// Ground-truthed against the published v3.4.0 binary: capabilities/v2.6
+	// advertises the same required surface as v2.5 (status/v6 is still
+	// advertised for compatibility) plus the status/v7 and status/v8 schemas,
+	// which are superset-checked additions, not requirements --
+	// decodeReviewStatusV3 already accepts v7/v8/v9 as additive extensions of
+	// v6, so the required-schema floor stays unchanged. `review assess` also
+	// gained review_due/review_due_reason/next_transition, which is unrelated
+	// to this negotiated capabilities surface. The v3.4.0 binary advertised
+	// 15 optional features, same as v2.5's binary (floor stays at 14, its
+	// established minimum).
+	"gentle-ai.review-integration.capabilities/v2.6": Object.freeze({
+		protocolMinor: 6,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON_V23, "gentle-ai.review-integration.capabilities/v2.6", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v4", "gentle-ai.review-integration.status/v6", "gentle-ai.review-intended-untracked-selection/v1"]),
+		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
+		optionalFeatureFloor: 14,
+	}),
 });
 const OPTIONAL_FEATURE_NAMES = Object.freeze([
 	"base_ref_workspace_overlay",
@@ -439,11 +455,21 @@ const REPOSITORY_CONTEXT_OUTCOMES = ["applied", "pending", "blocked_conflict", "
 
 
 
-// The two Go-owned non-lens provider role capture operations (gentle-pi#311
-// P4-roles; provider side gentle-ai#3264). Their collect inputs are
-// self-contained authority-advancing vectors: binding tokens plus
-// `--agent=pi --execute=true`, with NO submission descriptor. The known set
-// is closed — an unknown role capture operation is never executed.
+// The two non-lens provider role capture operations (gentle-pi#311 P4-roles;
+// provider side gentle-ai#3264). An older gentle-ai still renders each one as
+// a self-contained authority-advancing vector: binding tokens plus
+// `--agent=pi --execute=true`, with NO submission descriptor — executing the
+// exact rendered tokens makes Go materialize the role prompt, run its own
+// locked-down pi subprocess, and admit the verdict itself.
+//
+// gentle-ai's v9 contract makes both roles host-mediated exactly like a lens
+// materialize slot instead (gentle-pi#311 P3): the collect input carries
+// `--materialize=true` (never alongside `--execute`) plus a provider-owned
+// `submission` descriptor, and the host completes the frozen prompt
+// in-process and submits the result through that exact descriptor. The two
+// wire forms are mutually exclusive on one input; see the gating in
+// decodeCollectInput below. The known operation set is closed — an unknown
+// role capture operation is never executed either way.
 export const REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION = {
 	CAPTURE_REFUTER: "review.capture-refuter",
 	CAPTURE_VALIDATION: "review.capture-validation",
@@ -1452,11 +1478,18 @@ function decodeCaptureSubmission(value         , label        , v5         , v6
 	// one-entry values array the host relay already consumes. A payload
 	// carrying both wire forms at once matches no captured shape and falls
 	// through to the legacy decoder, which rejects the unknown `value` key.
+	//
+	// gentle-ai's v9 contract renders the same singular-value shape for the
+	// two host-mediated provider role operations (capture-refuter,
+	// capture-validation): they carry a `schema` key exactly like
+	// capture-result, since both bind one artifact-path-or-stdin value, never
+	// the correction-plan's numeric bounds (gentle-pi#311 P3).
 	if (v5 && typeof value === "object" && value !== null && "value" in value && !("values" in value)) {
 		const submission = exactRecord(value, label, ["operation_token", "argument_tokens", "value"]);
-		const operationToken = enumeration(submission.operation_token, ["capture-result", "capture-correction-plan"]         , `${label}.operation_token`);
+		const operationToken = enumeration(submission.operation_token, ["capture-result", "capture-correction-plan", "capture-refuter", "capture-validation"]         , `${label}.operation_token`);
 		const argumentTokens = stringArray(submission.argument_tokens, `${label}.argument_tokens`, { minimum: 1 });
-		const row = operationToken === "capture-result"
+		const bindsArtifactSchema = operationToken === "capture-result" || operationToken === "capture-refuter" || operationToken === "capture-validation";
+		const row = bindsArtifactSchema
 			? exactRecord(submission.value, `${label}.value`, ["slot", "domain", "schema", "substitution_location"])
 			: exactRecord(submission.value, `${label}.value`, ["slot", "domain", "minimum", "maximum", "substitution_location"]);
 		return {
@@ -1465,7 +1498,11 @@ function decodeCaptureSubmission(value         , label        , v5         , v6
 			values: [{
 				slot: operationToken === "capture-result"
 					? enumeration(row.slot, ["reviewer_result"]         , `${label}.value.slot`)
-					: enumeration(row.slot, ["correction_lines"]         , `${label}.value.slot`),
+					: operationToken === "capture-correction-plan"
+					? enumeration(row.slot, ["correction_lines"]         , `${label}.value.slot`)
+					: operationToken === "capture-refuter"
+					? enumeration(row.slot, ["provider_refuter"]         , `${label}.value.slot`)
+					: enumeration(row.slot, ["provider_targeted_validator"]         , `${label}.value.slot`),
 				domain: nonempty(row.domain, `${label}.value.domain`),
 				...(row.schema === undefined ? {} : { schema: nonempty(row.schema, `${label}.value.schema`) }),
 				...(row.minimum === undefined ? {} : { minimum: integer(row.minimum, `${label}.value.minimum`, 1, 200) }),
@@ -1606,7 +1643,7 @@ const CORRECTION_REQUEST_REASON_CODES = Object.freeze(["correction_plan_required
 // v5 capture operations that must carry a submission descriptor.
 const V5_SUBMISSION_CAPTURE_OPERATIONS = Object.freeze(["review.capture-correction-plan"]         );
 
-function decodeCollectInput(value         , label        , v5         , v6         )                       {
+function decodeCollectInput(value         , label        , v5         , v6         , v9         )                       {
 	const input = exactRecord(value, label, ["name", "schema", "capture_operation", "arguments"], ["artifact_subject", "base_tree", "candidate_tree", "changed_path_manifest", "submission", ...(v5 ? ["provider_task", "validation_request"] : [])]);
 	const name = text(input.name, `${label}.name`, { minimum: 1, pattern: /^[a-z0-9_]+$/ });
 	const schema = nonempty(input.schema, `${label}.schema`);
@@ -1657,13 +1694,18 @@ function decodeCollectInput(value         , label        , v5         , v6
 		sha256(argumentsList[5] .value, `${label}.arguments[5].value`);
 	}
 
-	// gentle-pi#311 P4-roles: the two Go-owned non-lens provider role capture
-	// operations render SELF-CONTAINED authority-advancing vectors. Executing
+	// gentle-pi#311 P4-roles / P3: the two non-lens provider role capture
+	// operations render either wire form on one input, never both at once.
+	// An older gentle-ai renders a SELF-CONTAINED authority-advancing vector
+	// (binding tokens + --agent=pi --execute=true, no submission): executing
 	// the exact rendered tokens makes Go materialize the role prompt, run its
-	// own locked-down pi subprocess, and admit the raw verdict — so a
-	// submission descriptor (the host-mediated completing form) on one of
-	// these inputs would hand the caller a way to author the verdict and is
-	// rejected as a provider contract violation.
+	// own locked-down pi subprocess, and admit the raw verdict. gentle-ai's
+	// v9 contract instead renders a HOST-MEDIATED form: the same binding
+	// tokens plus --materialize=true (never --execute) and a provider-owned
+	// submission descriptor, exactly like a lens capture-result materialize
+	// slot — the host completes the frozen prompt in-process and submits
+	// through that descriptor.
+	const isRoleCaptureOperation = (REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS                     ).includes(captureOperation);
 	if (captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_REFUTER && schema !== "https://gentle-ai.dev/schema/review/refuter/v1") {
 		throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/refuter/v1`);
 	}
@@ -1694,8 +1736,30 @@ function decodeCollectInput(value         , label        , v5         , v6
 		if (providerArgument("target") !== validationRequest.correctionTargetIdentity) throw new TypeError(`${label}.arguments target must bind validation_request.correction_target_identity`);
 		if (providerArgument("request-hash") !== validationRequest.requestHash) throw new TypeError(`${label}.arguments request-hash must bind validation_request.request_hash`);
 	}
-	if (input.submission !== undefined && (REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS                     ).includes(captureOperation)) {
-		throw new TypeError(`${label}.submission is not allowed on the self-contained ${captureOperation} vector`);
+	if (isRoleCaptureOperation && input.submission !== undefined) {
+		// A submission descriptor only ever rides the v9 host-mediated form
+		// (gentle-ai's v9 provider contract; the sibling branch ahead of the
+		// currently-released v8). A v8-or-earlier provider (status/v3..v8) never
+		// renders one, even if it happened to carry a submission-shaped payload,
+		// so this is gated on v9 specifically — not on v5, which v8 already
+		// satisfies. Within a v9 payload the discriminator is exactly the
+		// materialize slot's --materialize=true with no --execute, the same one
+		// a lens capture-result materialize slot already uses. Mixing a
+		// submission with the old self-contained --execute=true vector, or with
+		// neither flag, is a malformed vector.
+		if (!v9) {
+			throw new TypeError(`${label}.submission requires the v9 provider contract for the host-mediated ${captureOperation} form`);
+		}
+		const argumentNamed = (argumentName        )                     => {
+			const matches = argumentsList.filter((argument) => argument.name === argumentName);
+			return matches.length === 1 ? matches[0] .value : undefined;
+		};
+		if (argumentNamed("materialize") !== "true") {
+			throw new TypeError(`${label}.submission requires --materialize=true on the host-mediated ${captureOperation} form`);
+		}
+		if (argumentNamed("execute") !== undefined) {
+			throw new TypeError(`${label} must not carry --execute alongside a submission descriptor on ${captureOperation}`);
+		}
 	}
 
 	if (captureOperation === "review.capture-result") {
@@ -1712,7 +1776,12 @@ function decodeCollectInput(value         , label        , v5         , v6
 	const submissionOperations                    = v5
 		? ["review.capture-result", "review.capture-correction-plan", ...(v6 ? ["external.select_intended_untracked"] : [])]
 		: ["review.capture-result"];
-	if (input.submission !== undefined && !submissionOperations.includes(captureOperation)) {
+	// Role operations are gated above by the materialize/execute discriminator
+	// instead of this allowlist: an older gentle-ai's self-contained vector
+	// legitimately carries no submission regardless of v5/v6, so they cannot
+	// simply join the list the way every other submission-carrying operation
+	// does.
+	if (input.submission !== undefined && !isRoleCaptureOperation && !submissionOperations.includes(captureOperation)) {
 		throw new TypeError(v5 ? `${label}.submission is only valid for ${submissionOperations.join(", ")}` : `${label}.submission is only valid for review.capture-result`);
 	}
 	if (intendedUntracked && input.submission === undefined) throw new TypeError(`${label}.submission is required for external.select_intended_untracked`);
@@ -1750,8 +1819,14 @@ export function decodeReviewManagedAssetsContinuationV1(value         , label
 	return { operation, command, ...(agent === undefined ? {} : { agent }), ...(staleAssets === undefined ? {} : { staleAssets }) };
 }
 
-export function decodeReviewNextTransitionV3(value         , options                                 = {})                         {
-	const v6 = options.v6 === true;
+export function decodeReviewNextTransitionV3(value         , options                                               = {})                         {
+	// v9 (gentle-ai's next contract, ahead of the currently-released v8) is
+	// the only rung this sub-decoder distinguishes beyond v6: v7 and v8 add
+	// nothing to next_transition/collect-input decoding (v8 only extended the
+	// reviewer-result transition for OpenCode provider tasks at the top
+	// status level), so they decode on the exact v6 surface here.
+	const v9 = options.v9 === true;
+	const v6 = options.v6 === true || v9;
 	const v5 = options.v5 === true || v6;
 	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : []), "continuation", "unachievable_lens_slots"]);
 	const kind = enumeration(transition.kind, ["execute", "collect", "stop"]         , "next_transition.kind");
@@ -1813,7 +1888,7 @@ export function decodeReviewNextTransitionV3(value         , options
 	}
 	if (kind === "collect") {
 		const collect = exactRecord(transition.collect, "next_transition.collect", ["inputs"]);
-		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label, v5, v6), { minimum: 1 });
+		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label, v5, v6, v9), { minimum: 1 });
 		if (transition.execute !== undefined) throw new TypeError("next_transition.execute is incompatible with collect");
 		return { kind, reasonCode, collect: { inputs }, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
@@ -1926,16 +2001,25 @@ export function decodeReviewStatusV3(value         )                 {
 	// surfaces. status/v6 adds the intended-untracked selection; status/v7
 	// (gentle-ai v2.6.0, advertised through capabilities/v2.5 alongside v6)
 	// adds optional `eligible_untracked_inventory` and escalation metadata,
-	// so it is decoded on the v6 surface. v3 keeps rejecting every v5/v6/v7-only
-	// field.
+	// so it is decoded on the v6 surface. status/v8 (gentle-ai main, PR #4765;
+	// the current released contract) only extended the reviewer-result
+	// transition for OpenCode provider tasks -- no new top-level key -- so it
+	// decodes on the exact v7 surface too. status/v9 (the sibling gentle-ai
+	// branch's contract, ahead of the released v8) adds nothing at this top
+	// level either: its one addition is the host-mediated role `submission`
+	// on a next_transition.collect input (gentle-pi#311 P3), gated on v9 in
+	// decodeCollectInput, not here. v3 keeps rejecting every
+	// v5/v6/v7/v8/v9-only field.
 	const schema = typeof value === "object" && value !== null ? (value                           ).schema : undefined;
-	const v7 = schema === "gentle-ai.review-integration.status/v7";
+	const v9 = schema === "gentle-ai.review-integration.status/v9";
+	const v8 = v9 || schema === "gentle-ai.review-integration.status/v8";
+	const v7 = v8 || schema === "gentle-ai.review-integration.status/v7";
 	const v6 = v7 || schema === "gentle-ai.review-integration.status/v6";
 	const v5 = v6 || schema === "gentle-ai.review-integration.status/v5";
 	const body = exactRecord(value, "status", [
 		"schema", "contract", "operation", "applicability", "action", "replayability", "target_identity", "projection", "repair", "candidates",
 	], ["authority", "frozen", "action_disposition", "eligibility", "next_transition", "authority_target_identity", ...(v5 ? ["receipt", "forecast", "repository_context", "validation_request"] : []), ...(v7 ? ["eligible_untracked_inventory", "escalation"] : [])]);
-	requireIdentity(body, v7 ? "gentle-ai.review-integration.status/v7" : v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
+	requireIdentity(body, v9 ? "gentle-ai.review-integration.status/v9" : v8 ? "gentle-ai.review-integration.status/v8" : v7 ? "gentle-ai.review-integration.status/v7" : v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
 
 	const applicability = enumeration(body.applicability, ["current_target", "unrelated", "ambiguous", "corrupted"]         , "status.applicability");
 	let receipt                                   ;
@@ -1983,7 +2067,7 @@ export function decodeReviewStatusV3(value         )                 {
 	if (action === "recover" && actionDisposition === undefined) throw new TypeError("recover status requires action_disposition");
 	if (action !== "recover" && actionDisposition !== undefined) throw new TypeError("status.action_disposition is only valid for the recover action");
 	if (body.eligibility !== undefined) decodeEligibility(body.eligibility, "status.eligibility");
-	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5, v6 });
+	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5, v6, v9 });
 	const validationRequest = v5 && body.validation_request !== undefined
 		? decodeReviewTargetedValidationRequestV1(body.validation_request, "status.validation_request")
 		: undefined;

package/scripts/gentle-ai-installer.mjs

@@ -36,7 +36,7 @@ const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
 // version check below) derives from this constant instead of repeating the
 // literal, so a pin bump cannot leave a stale copy behind. See
 // scripts/install-gentle-ai.mjs for the incident that motivated this.
-export const INSTALLER_VERSION = "3.2.1";
+export const INSTALLER_VERSION = "3.4.0";
 export const RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-ai/releases/download/v${INSTALLER_VERSION}/`;
 export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 	SIGNED_RELEASE_ASSET: "signed-release-asset",
@@ -45,10 +45,10 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v3";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.2.1`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.4.0`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit e7729359, the published v3.2.1 release head.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:0QFo0ERv8/3lgTepEG0E/P7yD9qXXCx2M7ppQviVHMo=";
+// tag resolves to commit 82a6de96, the published v3.4.0 release head.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:bQOM+Xa3WN5+idTagEk15rgEEQQWVhZvq8BPF/FHtSs=";
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE = `${GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH}@${GENTLE_AI_WINDOWS_SOURCE_TAG}`;
 export const GENTLE_AI_WINDOWS_MINIMUM_GO_VERSION = "1.25.10";
 export const GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE_CODE = "GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE";
@@ -67,7 +67,7 @@ export class GentleAiInstallerError extends Error {
 // Sentinel used while a re-pinned gentle-ai release is not yet published. A
 // sentinel digest can never match a real SHA-256, so installation fails closed,
 // and verify-package-files.mjs refuses to pack/publish while any digest below
-// still holds it. The v3.2.1 digests are pinned from the published release:
+// still holds it. The v3.4.0 digests are pinned from the published release:
 // archive sha256 values verified against the minisign-signed checksums.txt and
 // freshly computed hashes; binary sha256 values computed from the extracted
 // executables.
@@ -109,15 +109,15 @@ async function downloadPinnedGentleAiAsset(asset, destination, options) {
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v3.2.1 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v3.4.0 publishes signed
 // Darwin/Linux archives only. Windows x64/arm64 uses the separately verified
 // exact-tag Go SumDB source-build path below; restore archive rows only when
 // upstream ships signed Windows assets.
 export const GENTLE_AI_RELEASE_ASSETS = Object.freeze({
-	"darwin/amd64": asset("gentle-ai_3.2.1_darwin_amd64.tar.gz", "1696a4852435920ebae351a5173adead6da17db6762359dcb12dc3971d983c3f", "ed7d18b7446c63f265a827a736ed4465ec562cc3c07c470743d3740fb4d2f4a9", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_3.2.1_darwin_arm64.tar.gz", "e3a991a03c6fb6373f6a254b808c3fabf36330634d93704c9d9ba365467fc6f8", "2ae66cfa11f8ab93ea46c20e79bd191dedde40a4898f0b312330a0790f802ca3", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_3.2.1_linux_amd64.tar.gz", "e2e3171377c040c27a93ae66b4adf824626f23cacd398b3b652af0d87ff65807", "3464525775b60cad6358a589c298a2d4098466bc0a5ae5f0d1e578ab10134659", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_3.2.1_linux_arm64.tar.gz", "342c7fc60cf062730c8f593f09269f75485b3b1fa2907b2b188eafded1a0e222", "d2c4d8ebfdc681ceece254d0d12cd04dd7af3b435c945e42623e3475981c2f8f", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_3.4.0_darwin_amd64.tar.gz", "7d13fa45489098ff9e82dee2232204f72bf1c04ef998ceadfe1ea972697f2e56", "d9096b4bb13e56aae1251dfacd2487821a15c40b7c9397555ad615ede47e658a", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_3.4.0_darwin_arm64.tar.gz", "b9052d8dc02923663d4451a4b031c4ef7328cd866c0cb6729e8ff2b9853603f0", "0aca1239cafd87ce63b194ab69da90e762801d82a96418fd6b7b12ea3806dc07", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_3.4.0_linux_amd64.tar.gz", "c287289a514420381e890991bb3fbea4a2c36d7b4b1774fcf6bc4deb83378915", "309d9aafb48de5ef90ba0a212e8a98e8fdbb82d0852e24015e36a5ce0fe04c06", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_3.4.0_linux_arm64.tar.gz", "dfd1fe70acfe577d2a36e3a658895f481467518a2923b7200403dbcca0181399", "83ba7d27d250019115690be51664bd356e09085da8858761e362e6053c6290d3", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,