gentle-pi 3.7.0 → 4.0.0

package/runtime/native-review-cli.mjs

@@ -68,8 +68,6 @@ export const NATIVE_REVIEW_OPERATION = {
 	CAPTURE_PROVIDER_ROLE: "review/capture-provider-role",
 	CAPTURE_UNACHIEVABLE: "review/capture-unachievable",
 	ACKNOWLEDGE_APPROVED: "review/acknowledge-approved",
-	SDD_STATUS: "sdd-status",
-	SDD_CONTINUE: "sdd-continue",
 }         ;
 
 
@@ -124,11 +122,6 @@ export const NATIVE_REVIEW_ERROR_CODE = {
 
 
 
-
-
-
-
-
 export const NATIVE_REVIEW_MODE_OPERATION = {
 	STATUS: "status",
 	ENABLE: "enable",
@@ -168,35 +161,6 @@ export const NATIVE_REVIEW_MODE_SCOPE = {
 
 
 
-
-
-
-
-/**
- * The native CLI owns this complete v2 record. The decoder validates the fields
- * Pi relies on and returns the original object without adding, omitting, or
- * reconciling local SDD state.
- */
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 
 // Read-only risk assessment request (gentle-pi#662). `baseRef` requires
 // explicit `committedOnly` acknowledgement, exactly like Native START's
@@ -748,6 +712,21 @@ function nativeUntrackedSelectionArguments(selection                          )
 	];
 }
 
+// Fail closed on malformed or duplicate provider selectors before invoking STATUS.
+function providerFlagValue(tokens                   , flag        )                     {
+	let found                    ;
+	for (let index = 0; index < tokens.length; index++) {
+		const token = tokens[index] ;
+		if (token !== `--${flag}` && !token.startsWith(`--${flag}=`)) continue;
+		if (found !== undefined) throw new TypeError(`Native intended-untracked selection repeats --${flag}`);
+		const value = token === `--${flag}` ? tokens[index + 1] : token.slice(`--${flag}=`.length);
+		if (value === undefined || value === "" || value.startsWith("--")) throw new TypeError(`Native intended-untracked selection has an invalid --${flag} value`);
+		found = value;
+		if (token === `--${flag}`) index++;
+	}
+	return found;
+}
+
 const NATIVE_RISK_LEVEL = ["low", "medium", "high"]         ;
 
 // gentle-ai's negotiated `start/v2` envelope is a closed schema
@@ -1049,6 +1028,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c
 	// at contract 1.2.0. No new negotiated capability is asserted.
 	"3.7.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 }),
+	// v4.0.0 repeats 3.7.0: the published provider-contract tar remains SHA-256
+	// 547b68e172cc87aa297309d61624e5fc2c24d407a494b53eeb5a2b053904352c
+	// at contract 1.2.0, and the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2. The Go module path moved
+	// to /v4 without a review-integration/v2 change. No new negotiated
+	// capability is asserted.
+	"4.0.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 }),
 });
 
 
@@ -1516,52 +1502,6 @@ function nativeError(code                       , operation
 
 
 
-const NATIVE_SDD_DEPENDENCIES = ["proposal", "specs", "design", "tasks", "apply", "verify", "archive"]         ;
-const NATIVE_SDD_INSTRUCTION_PHASES = ["apply", "verify", "archive"]         ;
-const NATIVE_SDD_NEXT_RECOMMENDATIONS = ["apply", "verify", "remediate", "archive", "archived", "resolve-blockers", "sdd-new", "select-change", "propose", "spec", "design", "tasks"]         ;
-const NATIVE_SDD_DEPENDENCY_STATES = ["blocked", "ready", "all_done"]         ;
-
-/** Strictly validates the native v2 contract while preserving its whole record. */
-export function decodeNativeSddStatusV2(value         , request                                                              )                    {
-	const status = object(value);
-	if (status.schemaName !== "gentle-ai.sdd-status" || status.schemaVersion !== 2) throw new Error("wrong native SDD status schema");
-	if ((request.changeName !== undefined && status.changeName !== request.changeName) || (status.changeName !== null && !isCanonicalProcessString(status.changeName))) throw new Error("native SDD status change identity mismatch");
-	const artifactStore = enumString(status.artifactStore, ["openspec", "engram", "hybrid", "none"]);
-	const planningHome = object(status.planningHome);
-	if (planningHome.mode !== "repo-local" || !isCanonicalProcessString(planningHome.path)) throw new Error("invalid native SDD planning home");
-	const expectedOpenSpecHome = join(request.workspaceRoot, "openspec");
-	if (planningHome.path !== expectedOpenSpecHome && !((artifactStore === "engram" || artifactStore === "hybrid") && planningHome.path === "engram:sdd")) throw new Error("native SDD planning home escaped its workspace");
-	if (status.changeRoot !== null && !isCanonicalProcessString(status.changeRoot)) throw new Error("invalid native SDD change root");
-	const actionContext = object(status.actionContext);
-	if (actionContext.mode !== "repo-local" || actionContext.workspaceRoot !== request.workspaceRoot || !isCanonicalProcessString(actionContext.workspaceRoot)) throw new Error("native SDD status workspace root mismatch");
-	const allowedEditRoots = stringArray(actionContext.allowedEditRoots);
-	if (!allowedEditRoots.includes(request.workspaceRoot) || allowedEditRoots.some((root) => !isAbsolute(root) || root !== join(root))) throw new Error("invalid native SDD allowed edit roots");
-	const dependencies = object(status.dependencies);
-	for (const phase of NATIVE_SDD_DEPENDENCIES) {
-		if (enumString(dependencies[phase], NATIVE_SDD_DEPENDENCY_STATES) !== dependencies[phase]) throw new Error("invalid native SDD dependency");
-	}
-	if (Object.keys(dependencies).length !== NATIVE_SDD_DEPENDENCIES.length) throw new Error("native SDD dependencies have an unsupported shape");
-	if (status.instructions !== undefined) throw new Error("native SDD status uses phaseInstructions, not instructions");
-	if (status.phaseInstructions !== undefined) {
-		const instructions = object(status.phaseInstructions);
-		for (const phase of NATIVE_SDD_INSTRUCTION_PHASES) stringArray(instructions[phase]);
-		// Classical SDD no longer emits a remediation phase. Keep the published
-		// producer's optional legacy instructions intact without inventing them
-		// for a newer producer or accepting unknown phase keys.
-		const hasRemediation = Object.hasOwn(instructions, "remediate");
-		if (hasRemediation) stringArray(instructions.remediate);
-		if (Object.keys(instructions).length !== NATIVE_SDD_INSTRUCTION_PHASES.length + Number(hasRemediation)) throw new Error("native SDD instructions have an unsupported shape");
-		if (status.nextRecommended === "remediate" && !hasRemediation) throw new Error("native SDD remediation instructions are missing");
-	}
-	if (status.nextRecommended === "remediate" || status.remediationState !== undefined) {
-		const remediation = object(status.remediationState);
-		if (typeof remediation.required !== "boolean" || typeof remediation.complete !== "boolean" || typeof remediation.failedEvidenceRevision !== "string" || (remediation.failedEvidenceRevision !== "" && !/^sha256:[0-9a-f]{64}$/.test(remediation.failedEvidenceRevision)) || (status.nextRecommended === "remediate" && (!remediation.required || remediation.complete || !remediation.failedEvidenceRevision))) throw new Error("Invalid native remediation state");
-	}
-	stringArray(status.blockedReasons);
-	enumString(status.nextRecommended, NATIVE_SDD_NEXT_RECOMMENDATIONS);
-	return status                     ;
-}
-
 class NativeReviewPlainCli {
 	                 adapter                 ;
 	                 executable                         ;
@@ -2200,30 +2140,6 @@ export class NativeReviewCliV216                            {
 		return this.invoke(operation, cwd, arguments_, mutating, signal, this.executablePath(operation, mutating), toleratedStderr);
 	}
 
-	async sddStatus(request                        )                             {
-		return this.sddProjection(request, false);
-	}
-
-	async sddContinue(request                        )                             {
-		if (!isCanonicalProcessString(request.changeName)) throw new TypeError("Native SDD continuation requires an exact selected change");
-		return this.sddProjection(request, true);
-	}
-
-	        async sddProjection(request                        , mutating         )                             {
-		if ((request.changeName !== undefined && !isCanonicalProcessString(request.changeName)) || !isCanonicalProcessString(request.workspaceRoot) || !isAbsolute(request.workspaceRoot)) {
-			throw new TypeError("Native SDD status requires a canonical change and absolute workspace root");
-		}
-		const operation = mutating ? NATIVE_REVIEW_OPERATION.SDD_CONTINUE : NATIVE_REVIEW_OPERATION.SDD_STATUS;
-		const execution = await this.negotiated(
-			operation,
-			request.workspaceRoot,
-			[operation, ...(request.changeName === undefined ? [] : [request.changeName]), "--cwd", request.workspaceRoot, "--json", "--instructions"],
-			mutating,
-			request.signal,
-		);
-		return decode(operation, mutating, () => decodeNativeSddStatusV2(execution.body, request));
-	}
-
 	async start(request                    )                             {
 		if (request.baseRef !== undefined && !isCanonicalProcessString(request.baseRef)) throw new TypeError("Native START baseRef must be a non-empty, trimmed, NUL-free string");
 		if (request.baseRef !== undefined && request.committedOnly !== true) throw new TypeError("Native START baseRef requires explicit committedOnly acknowledgement");
@@ -2346,7 +2262,32 @@ export class NativeReviewCliV216                            {
 		const selection = nativeUntrackedSelection(request);
 		const submitted = request.intendedUntrackedSelection;
 		if (submitted !== undefined && submitted.argumentTokens.reduce((count, token) => count + token.split("{{value}}").length - 1, 0) !== 1) throw new TypeError("Native intended-untracked selection requires exactly one provider-issued {{value}} token");
-		const statusArguments = submitted === undefined ? [
+		const submittedTokens = submitted === undefined ? undefined : submitted.argumentTokens.map((token) => token.replaceAll("{{value}}", submitted.value));
+		// gentle-ai 3.7.1 submission argument_tokens never carry --base-ref /
+		// --committed-only / --lineage, so a forwarded selector must be appended
+		// after them; only bail if the provider already staked out a conflicting
+		// value for the same flag. providerFlagValue also fails closed on a
+		// dangling `--flag` (last token, no value) or an empty `--flag=`.
+		const submittedBaseRefValue = submittedTokens === undefined ? undefined : providerFlagValue(submittedTokens, "base-ref");
+		if (request.baseRef !== undefined && submittedBaseRefValue !== undefined && submittedBaseRefValue !== request.baseRef) throw new TypeError("Native intended-untracked selection already carries a conflicting base-ref");
+		const submittedLineageValue = submittedTokens === undefined ? undefined : providerFlagValue(submittedTokens, "lineage");
+		if (request.lineageId !== undefined && submittedLineageValue !== undefined && submittedLineageValue !== request.lineageId) throw new TypeError("Native intended-untracked selection already carries a conflicting lineage");
+		let submittedHasCommittedOnly = false;
+		for (const token of submittedTokens ?? []) {
+			if (token !== "--committed-only" && !token.startsWith("--committed-only=")) continue;
+			if (token !== "--committed-only" && token !== "--committed-only=true") throw new TypeError("Native intended-untracked selection has an invalid --committed-only value");
+			if (submittedHasCommittedOnly) throw new TypeError("Native intended-untracked selection repeats --committed-only");
+			submittedHasCommittedOnly = true;
+		}
+		// Append only the half of the base-ref/committed-only pair the provider
+		// did not already carry (a present base-ref already equals
+		// request.baseRef; the throw above ruled out the conflicting case).
+		const forwardedBaseRef = request.baseRef === undefined ? [] : [
+			...(submittedBaseRefValue === undefined ? ["--base-ref", request.baseRef] : []),
+			...(submittedHasCommittedOnly ? [] : ["--committed-only"]),
+		];
+		const forwardedLineage = request.lineageId === undefined || submittedLineageValue !== undefined ? [] : ["--lineage", request.lineageId];
+		const statusArguments = submittedTokens === undefined ? [
 			"review", "status", "--contract", REVIEW_INTEGRATION_CONTRACT, "--cwd", request.cwd,
 			"--projection", request.projection ?? "workspace",
 			...nativeUntrackedSelectionArguments(selection),
@@ -2354,7 +2295,7 @@ export class NativeReviewCliV216                            {
 			...(request.lineageId === undefined ? [] : ["--lineage", request.lineageId]),
 			...(request.agent === undefined ? [] : ["--agent", request.agent]),
 			"--next-transition",
-		] : ["review", "status", "--cwd", request.cwd, ...submitted.argumentTokens.map((token) => token.replaceAll("{{value}}", submitted.value))];
+		] : ["review", "status", "--cwd", request.cwd, ...submittedTokens, ...forwardedBaseRef, ...forwardedLineage];
 		const execution = await this.negotiated(NATIVE_REVIEW_OPERATION.STATUS, request.cwd, statusArguments, false, request.signal);
 		assertSupportedNextTransitionOperation(execution.body);
 		return decode(NATIVE_REVIEW_OPERATION.STATUS, false, () => decodeReviewStatusV3(execution.body));

package/runtime/review-risk-assessment.mjs

@@ -11,6 +11,11 @@
 // prints `{"schema":"gentle-ai.review-assessment/v1","risk":"passive|medium|high",
 // "reasons":[{"code":"…","path":"…","detail":"…"}],"changed_paths":1,
 // "changed_lines":1,"candidate":{"kind":"current-changes|base-diff","base_ref":"…"}}`.
+// gentle-pi#1175: the native v2 `assess.schema.json` requires only `code` on a
+// reason (`path`/`detail` are optional) and adds `candidate.consumed`,
+// `review_due`, `review_due_reason`, and an opaque `next_transition`. Older
+// binaries (for example gentle-ai v3.7.0) predate those fields, so
+// they decode as optional and stay absent rather than being defaulted.
 // A non-zero exit or a failure envelope means the candidate could not be
 // assessed; hosts treat that as `high`. Older binaries without the verb (or
 // any other decode/process failure) fail closed the same way -- see
@@ -31,6 +36,41 @@ export const REVIEW_ASSESSMENT_CANDIDATE_KIND = {
 }         ;
 
 
+export const REVIEW_DUE_REASON = {
+	HIGH_RISK: "high_risk",
+	SLICE_BUDGET_REACHED: "slice_budget_reached",
+	PASSIVE: "passive",
+	UNDER_BUDGET: "under_budget",
+	ALREADY_REVIEWED: "already_reviewed",
+}         ;
+
+
+export const REVIEW_ASSESSMENT_NEXT_TRANSITION_OPERATION = "review.status"         ;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+/**
+ * The native, literally runnable `review status ... --next-transition`
+ * preflight continuation. Carried verbatim as an opaque value: hosts never
+ * rebuild, reorder, or synthesize it.
+ */
 
 
 
@@ -55,25 +95,99 @@ function isRecord(value         )                                   {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isNonEmptyString(value         )                  {
+	return typeof value === "string" && value.length > 0;
+}
+
 function decodeReason(value         )                         {
 	if (!isRecord(value)) throw new TypeError("review assessment reason must be an object");
 	const { code, path, detail } = value;
-	if (typeof code !== "string" || code.length === 0) throw new TypeError("review assessment reason.code must be a non-empty string");
-	if (typeof path !== "string") throw new TypeError("review assessment reason.path must be a string");
-	if (typeof detail !== "string") throw new TypeError("review assessment reason.detail must be a string");
-	return Object.freeze({ code, path, detail });
+	if (!isNonEmptyString(code)) throw new TypeError("review assessment reason.code must be a non-empty string");
+	if (path !== undefined && !isNonEmptyString(path)) throw new TypeError("review assessment reason.path must be a non-empty string when present");
+	if (detail !== undefined && !isNonEmptyString(detail)) throw new TypeError("review assessment reason.detail must be a non-empty string when present");
+	// Absent path/detail stay absent: never synthesized (gentle-pi#1175).
+	return Object.freeze({
+		code,
+		...(path === undefined ? {} : { path: path           }),
+		...(detail === undefined ? {} : { detail: detail           }),
+	});
 }
 
 function decodeCandidate(value         )                            {
 	if (!isRecord(value)) throw new TypeError("review assessment candidate must be an object");
-	const { kind, base_ref: baseRef } = value;
+	const { kind, base_ref: baseRef, consumed } = value;
 	if (kind !== REVIEW_ASSESSMENT_CANDIDATE_KIND.CURRENT_CHANGES && kind !== REVIEW_ASSESSMENT_CANDIDATE_KIND.BASE_DIFF) {
 		throw new TypeError("review assessment candidate.kind must be current-changes or base-diff");
 	}
-	if (baseRef !== undefined && (typeof baseRef !== "string" || baseRef.length === 0)) {
+	if (baseRef !== undefined && !isNonEmptyString(baseRef)) {
 		throw new TypeError("review assessment candidate.base_ref must be a non-empty string when present");
 	}
-	return Object.freeze({ kind, baseRef: baseRef                       });
+	if (consumed !== undefined && typeof consumed !== "boolean") {
+		throw new TypeError("review assessment candidate.consumed must be a boolean when present");
+	}
+	// An older binary omits consumed; it stays absent, never defaulted.
+	return Object.freeze({ kind, baseRef: baseRef                      , ...(consumed === undefined ? {} : { consumed: consumed            }) });
+}
+
+function isReviewDueReason(value         )                           {
+	return Object.values(REVIEW_DUE_REASON).includes(value                   );
+}
+
+// The native schema fixes review_due by reason: due for high_risk and
+// slice_budget_reached, not due for passive, under_budget, and
+// already_reviewed (gentle-pi#1175).
+const DUE_REVIEW_REASONS                             = [REVIEW_DUE_REASON.HIGH_RISK, REVIEW_DUE_REASON.SLICE_BUDGET_REACHED];
+
+/**
+ * Rejects a review_due/review_due_reason/consumed combination the native
+ * schema can never produce. `already_reviewed` takes precedence exactly when
+ * the candidate is consumed, so the two must agree in both directions. A
+ * contradictory envelope is never trusted, least of all as closure evidence.
+ * Envelopes without the pair (older binaries) are not checked here.
+ */
+function validateReviewDueConsistency(reviewDue         , reviewDueReason                 , candidate                           )       {
+	if (reviewDue !== DUE_REVIEW_REASONS.includes(reviewDueReason)) {
+		throw new TypeError(`review assessment review_due ${reviewDue} contradicts review_due_reason ${reviewDueReason}`);
+	}
+	const alreadyReviewed = reviewDueReason === REVIEW_DUE_REASON.ALREADY_REVIEWED;
+	if (alreadyReviewed !== (candidate.consumed === true)) {
+		throw new TypeError("review assessment review_due_reason already_reviewed must be reported exactly when candidate.consumed is true");
+	}
+}
+
+function hasOnlyKeys(value                         , allowed                   )          {
+	return Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function validateNextTransitionArgument(value         )       {
+	if (!isRecord(value) || !hasOnlyKeys(value, ["name", "value", "token"])) {
+		throw new TypeError("review assessment next_transition argument must be an object with only name, value, and token");
+	}
+	if (!isNonEmptyString(value.name)) throw new TypeError("review assessment next_transition argument name must be a non-empty string");
+	if (typeof value.value !== "string") throw new TypeError("review assessment next_transition argument value must be a string");
+	if (value.token !== undefined && !isNonEmptyString(value.token)) {
+		throw new TypeError("review assessment next_transition argument token must be a non-empty string when present");
+	}
+}
+
+/**
+ * Validates `next_transition` exactly as the native schema declares it and
+ * returns the native value itself, frozen -- validated, never rebuilt,
+ * reordered, or synthesized (gentle-pi#1175).
+ */
+function decodeNextTransition(value         )                                 {
+	if (!isRecord(value) || !hasOnlyKeys(value, ["operation", "command", "arguments"])) {
+		throw new TypeError("review assessment next_transition must be an object with only operation, command, and arguments");
+	}
+	if (value.operation !== REVIEW_ASSESSMENT_NEXT_TRANSITION_OPERATION) {
+		throw new TypeError(`review assessment next_transition.operation must be ${REVIEW_ASSESSMENT_NEXT_TRANSITION_OPERATION}`);
+	}
+	if (!isNonEmptyString(value.command)) throw new TypeError("review assessment next_transition.command must be a non-empty string");
+	if (!Array.isArray(value.arguments)) throw new TypeError("review assessment next_transition.arguments must be an array");
+	for (const argument of value.arguments) validateNextTransitionArgument(argument);
+	for (const argument of value.arguments) Object.freeze(argument);
+	Object.freeze(value.arguments);
+	return Object.freeze(value)                                             ;
 }
 
 /**
@@ -82,24 +196,55 @@ function decodeCandidate(value         )                            {
  * native review CLI wrapper turns a thrown error here into the same
  * schema-incompatible failure it already produces for every other decoded
  * native response.
+ *
+ * `review_due` and `review_due_reason` were added together natively: both
+ * absent (an older binary) or both present are accepted; only one of them is
+ * rejected. When present, the pair must agree with each other and with
+ * `candidate.consumed` (see `validateReviewDueConsistency`).
+ * `next_transition` is accepted only alongside `review_due: true`.
+ * Unknown extra top-level fields are ignored and never projected, so a newer
+ * binary stays decodable (gentle-pi#1175).
  */
 export function decodeReviewAssessmentV1(value         )                     {
 	if (!isRecord(value)) throw new TypeError("review assessment must be an object");
 	if (value.schema !== REVIEW_ASSESSMENT_SCHEMA) throw new TypeError(`review assessment schema must be ${REVIEW_ASSESSMENT_SCHEMA}`);
-	const { risk, reasons, changed_paths: changedPaths, changed_lines: changedLines, candidate } = value;
+	const {
+		risk,
+		reasons,
+		changed_paths: changedPaths,
+		changed_lines: changedLines,
+		candidate,
+		review_due: reviewDue,
+		review_due_reason: reviewDueReason,
+		next_transition: nextTransition,
+	} = value;
 	if (risk !== REVIEW_ASSESSMENT_RISK.PASSIVE && risk !== REVIEW_ASSESSMENT_RISK.MEDIUM && risk !== REVIEW_ASSESSMENT_RISK.HIGH) {
 		throw new TypeError("review assessment risk must be passive, medium, or high");
 	}
 	if (!Array.isArray(reasons)) throw new TypeError("review assessment reasons must be an array");
 	if (!Number.isSafeInteger(changedPaths) || (changedPaths          ) < 0) throw new TypeError("review assessment changed_paths must be a non-negative integer");
 	if (!Number.isSafeInteger(changedLines) || (changedLines          ) < 0) throw new TypeError("review assessment changed_lines must be a non-negative integer");
+	if ((reviewDue === undefined) !== (reviewDueReason === undefined)) {
+		throw new TypeError("review assessment review_due and review_due_reason must be both present or both absent");
+	}
+	if (reviewDue !== undefined && typeof reviewDue !== "boolean") throw new TypeError("review assessment review_due must be a boolean when present");
+	if (reviewDueReason !== undefined && !isReviewDueReason(reviewDueReason)) {
+		throw new TypeError(`review assessment review_due_reason must be one of ${Object.values(REVIEW_DUE_REASON).join(", ")}`);
+	}
+	if (nextTransition !== undefined && reviewDue !== true) {
+		throw new TypeError("review assessment next_transition is only valid when review_due is true");
+	}
+	const decodedCandidate = decodeCandidate(candidate);
+	if (reviewDue !== undefined) validateReviewDueConsistency(reviewDue           , reviewDueReason                   , decodedCandidate);
 	return Object.freeze({
 		schema: REVIEW_ASSESSMENT_SCHEMA,
 		risk,
 		reasons: Object.freeze(reasons.map(decodeReason)),
 		changedPaths: changedPaths          ,
 		changedLines: changedLines          ,
-		candidate: decodeCandidate(candidate),
+		candidate: decodedCandidate,
+		...(reviewDue === undefined ? {} : { reviewDue: reviewDue           , reviewDueReason: reviewDueReason                    }),
+		...(nextTransition === undefined ? {} : { nextTransition: decodeNextTransition(nextTransition) }),
 	});
 }
 

package/scripts/build-runtime-modules.mjs

@@ -14,6 +14,7 @@ const sources = [
 	"native-review-cli",
 	"telemetry-trigger",
 	"gentle-shell-launcher",
+	"gentle-shell-resume-hint",
 ];
 const header = "// Generated by scripts/build-runtime-modules.mjs. Do not edit.\n";
 

package/scripts/gentle-ai-installer.mjs

@@ -36,19 +36,20 @@ 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.7.0";
+export const INSTALLER_VERSION = "4.0.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",
 	GO_SUMDB_SOURCE_BUILD: "go-sumdb-source-build",
 });
-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_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai";
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v4";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.7.0`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v4@v4.0.0`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit 6dee8f833aec9e46015759c5065a9035795d9af1, the published v3.7.0 release head.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:MQbzHlLdPklUQn0rVE9Mz94UygHsN2OPe7xMfPn9aGw=";
+// tag resolves to commit ff77164d4f56f1665b22fb6fac51c2ccbb769400, the published v4.0.0 release head.
+// v4.0.0 moved the Go module path to the /v4 major-version suffix.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:pZ/XZ2Pk3U9lgXigOTY62zlxxFOHnc9CjQhLgaV/Hfc=";
 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 +68,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.7.0 digests are pinned from the published release:
+// still holds it. The v4.0.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 +110,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.7.0 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v4.0.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.7.0_darwin_amd64.tar.gz", "e55ff3ee06258a90e9195c0e3a593b85f6d79cc439e9e6c04b2596725120a610", "aa30a940e3b75ac218249b3f92d17afd2b972f833258e8212175a73d8e76d5bf", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_3.7.0_darwin_arm64.tar.gz", "66eb5740c4506cb2cfd1cc5207439c61cfe07678854f4ac7c83027a95a0e666a", "ca726cf3f9a523dc0112aa113beb634cda389e8b47edc5851254c32979bee89e", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_3.7.0_linux_amd64.tar.gz", "a730a61a43758f04cc9a4ac644945cc0e8652a1e33d6997a0a3d3f0044d2fff5", "002d09fd2b9628a29986a660c1f51f8a5042ff7fd54c8ab15b7b27de96c6cccc", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_3.7.0_linux_arm64.tar.gz", "a3a3d3a974f3d9b67d935fe9e306ae83c305da4ec1baed4a5319c10b044cd0eb", "e29546c51d8d65528bf565239ed3fc174da73c5fa3e861e64f20f84b16f28f26", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_4.0.0_darwin_amd64.tar.gz", "b5b74f22b38ec3339b38e8c68f797dc76ff12ed6580826a6e425d5c718da80c1", "d4a5b16ff70e65331e17a62356941bb0c75ecb9dbe3a0d98a6b54cfbd76cd6b0", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_4.0.0_darwin_arm64.tar.gz", "d2159caf6d68f367b18830ece6af71ef26963d5f5320d7df6a794773f45cc7e9", "18a9f7fae55d85c95684b6d512a4a148d0cb24a856325f72573c34caf65159eb", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_4.0.0_linux_amd64.tar.gz", "5f4417cf29c969c86da4799942fd673368840901be1bb09c779a12d7ed6096ea", "50ba217b5138c1a9c7d5bf2f79931b1bb89b89c4cf650dcd7ee037657c88158d", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_4.0.0_linux_arm64.tar.gz", "1383b040c95cfc69206660d73c21907b14ad70ab913f410917c54f43d3147e57", "6703704f0c4a5b70c36fbdc44db641e810871cab16bc28040d06aa1d10704ad3", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,
@@ -402,7 +403,7 @@ async function safeRemoveDirectory(path) {
 	try {
 		const details = await lstat(path);
 		if (!details.isDirectory() || details.isSymbolicLink()) throw new Error("not a real directory");
-		await rm(path, { recursive: true, force: true });
+		await rm(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
 	} catch (error) { if (!(error && typeof error === "object" && error.code === "ENOENT")) throw error; }
 }
 

package/scripts/mirror-odd-routing.mjs

@@ -38,8 +38,8 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/gentleman-programming/gentle-ai/v3/internal/components/agentguidance"
-	"github.com/gentleman-programming/gentle-ai/v3/internal/model"
+	"github.com/gentleman-programming/gentle-ai/v4/internal/components/agentguidance"
+	"github.com/gentleman-programming/gentle-ai/v4/internal/model"
 )
 
 func main() {

package/scripts/run-test-suite.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Sequential test-suite runner for `pnpm test` (gentle-pi#1285).
+//
+// `pnpm test` used to chain its three stages with `&&`, so any stage-1
+// failure — including a known-flaky unit test — silently suppressed the
+// provider-contract check and the runtime harness while reporting a plain
+// "test failed". This runner executes every stage unconditionally, prints a
+// per-stage header and a final summary, and exits non-zero when any stage
+// fails. Stages are plain shell commands, so behavior stays identical on
+// POSIX and Windows CI.
+
+import { spawn } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_STAGES = Object.freeze([
+	{ name: "unit-tests", command: "node --experimental-strip-types --test tests/*.test.ts" },
+	{ name: "provider-contract", command: "pnpm run check:provider-contract" },
+	{ name: "runtime-harness", command: "pnpm run test:harness" },
+]);
+
+export async function runStage(stage) {
+	return await new Promise((resolve) => {
+		const child = spawn(stage.command, { shell: true, stdio: "inherit" });
+		child.on("close", (code) => resolve({ name: stage.name, code: code ?? 1 }));
+		child.on("error", (error) => {
+			console.error(`\n[${stage.name}] spawn failed: ${error.message}`);
+			resolve({ name: stage.name, code: 1 });
+		});
+	});
+}
+
+export async function runTestSuite(stages = DEFAULT_STAGES, { runStageImpl = runStage, write = (line) => console.log(line) } = {}) {
+	const results = [];
+	for (const stage of stages) {
+		write(`\n=== [${stage.name}] ${stage.command} ===`);
+		results.push(await runStageImpl(stage));
+	}
+	write("\n=== test suite summary ===");
+	for (const result of results) write(`${result.code === 0 ? "PASS" : "FAIL"}  ${result.name}`);
+	const failures = results.filter((result) => result.code !== 0);
+	write(failures.length === 0 ? "all stages passed" : `${failures.length} stage(s) failed: ${failures.map((f) => f.name).join(", ")}`);
+	return results;
+}
+
+function readStagesFromJsonPath(jsonPath) {
+	const stages = JSON.parse(readFileSync(jsonPath, "utf8"));
+	if (!Array.isArray(stages) || stages.some((stage) => typeof stage?.name !== "string" || typeof stage?.command !== "string")) {
+		throw new Error(`stages file must be an array of { name, command } objects: ${jsonPath}`);
+	}
+	return stages;
+}
+
+// Direct-invocation detection must survive symlinks: Node real-paths
+// `import.meta.url` but keeps `process.argv[1]` logical, so a plain equality
+// check silently no-ops the whole runner (zero stages run, exit 0) when the
+// script is reached through a file symlink.
+function isDirectRun(argv1) {
+	if (!argv1) return false;
+	try {
+		return realpathSync(argv1) === realpathSync(fileURLToPath(import.meta.url));
+	} catch {
+		return false;
+	}
+}
+
+if (isDirectRun(process.argv[1])) {
+	try {
+		const stages = process.argv[2] ? readStagesFromJsonPath(process.argv[2]) : DEFAULT_STAGES;
+		const results = await runTestSuite(stages);
+		process.exitCode = results.some((result) => result.code !== 0) ? 1 : 0;
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : error);
+		process.exitCode = 1;
+	}
+}