gentle-pi 2.4.0 → 2.6.0

package/runtime/native-review-cli.mjs

@@ -6,6 +6,7 @@ import { dirname, isAbsolute, join, posix, win32 } from "node:path";
 import { promisify } from "node:util";
 import { PackageLocalGentleAiBinaryMissingError, resolveGentleAiBinary } from "./gentle-ai-binary.mjs";
 import { GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "./review-relay-contract.mjs";
+import { decodeReviewAssessmentV1,                         } from "./review-risk-assessment.mjs";
 import {
 	REVIEW_INTEGRATION_CONTRACT,
 	decodeReviewAcknowledgedV1,
@@ -60,11 +61,16 @@ export const NATIVE_REVIEW_OPERATION = {
 	RECONCILE_AUTHORITY: "review/reconcile-authority",
 	REPAIR_LEGACY_ALIAS: "review/repair-legacy-alias",
 	MODE: "review/mode",
+	ASSESS: "review/assess",
 	REPAIR: "review/repair",
 	CAPTURE_RESULT: "review/capture-result",
 	CAPTURE_CORRECTION_PLAN: "review/capture-correction-plan",
 	CAPTURE_PROVIDER_ROLE: "review/capture-provider-role",
+	CAPTURE_UNACHIEVABLE: "review/capture-unachievable",
 	ACKNOWLEDGE_APPROVED: "review/acknowledge-approved",
+	SDD_STATUS: "sdd-status",
+	SDD_ATTEMPT: "sdd-attempt",
+	SDD_CONTINUE: "sdd-continue",
 }         ;
 
 
@@ -104,6 +110,8 @@ export const NATIVE_REVIEW_ERROR_CODE = {
 
 
 
+
+
 
 
 
@@ -112,6 +120,49 @@ export const NATIVE_REVIEW_ERROR_CODE = {
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+export const SDD_ATTEMPT_OUTCOME = { PASSED: "passed", FAILED: "failed", INTERRUPTED: "interrupted" }         ;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export const NATIVE_REVIEW_MODE_OPERATION = {
 	STATUS: "status",
 	ENABLE: "enable",
@@ -155,6 +206,46 @@ 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
+// baseRef/committedOnly pairing, because both select a committed range
+// instead of the ambient working tree.
+
+
+
+
+
+
+
+
+
+
 
 
 
@@ -305,7 +396,6 @@ export const NATIVE_REVIEW_LEGACY_ALIAS_REPAIR = {
 
 
 
-
 
 
 /** Raw audited native record; Pi relays it verbatim and never reinterprets it. */
@@ -415,6 +505,49 @@ function isNativeReviewProviderRoleCaptureOperation(operation        )
 
 
 
+// gentle-pi#638: the typed declaration that one bound selected lens slot cannot be completed under current conditions. Mirrored from Go's reviewUnachievableLensCaptureArtifact (internal/cli/review_capture_unachievable.go): same schema identity, same closed field set, and the same 512-byte detail bound Go enforces, so a declaration this client refuses locally can never reach a binary that would accept it, and vice versa.
+export const NATIVE_REVIEW_UNACHIEVABLE_LENS_CAPTURE_SCHEMA = "gentle-ai.review-capture-unachievable/v1";
+export const NATIVE_REVIEW_UNACHIEVABLE_LENS_DETAIL_LIMIT = 512;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// gentle-pi#638 fail-open capability gate: `review capture-unachievable` is younger than every released binary pinned in NATIVE_CLI_CONTRACTS, so the verb is gated invocation-adjacent instead of by a capability row. An older binary renders Go's exact `unknown review command "capture-unachievable"` refusal (internal/cli/review_facade.go) on stderr with no stdout, so the invocation rejects before any decode and the captured diagnostics are the only place that text survives. Every other failure -- a typed binding-mismatch refusal, a timeout, a decode failure -- is a real outcome the caller must surface, never a capability signal. Duck-typed on purpose: the classifier must survive a duplicated module instance exactly like the error it inspects.
+const NATIVE_REVIEW_UNKNOWN_UNACHIEVABLE_VERB_REFUSAL = /unknown review command "capture-unachievable"/;
+
+export function isNativeReviewUnachievableVerbRefused(error         )          {
+	if (typeof error !== "object" || error === null) return false;
+	const stderr = (error                                          ).diagnostics?.stderr;
+	return typeof stderr === "string" && NATIVE_REVIEW_UNKNOWN_UNACHIEVABLE_VERB_REFUSAL.test(stderr);
+}
+
 /** Refuter and validator captures close only when they are the native last event. */
 
 
@@ -499,7 +632,12 @@ export const NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION = {
 }         ;
 
 
-export const NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS = NATIVE_REVIEW_AUTHORITY_STATUS;
+export const NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS = {
+	...NATIVE_REVIEW_AUTHORITY_STATUS,
+	INCOMPLETE_STORE_ENTRY: "incomplete-store-entry",
+	HISTORICAL_PRE_RECEIPT: "historical-pre-receipt",
+	INVALIDATED: "invalidated",
+}         ;
 
 
 export const NATIVE_REVIEW_LOCK_STATUS = {
@@ -570,6 +708,11 @@ export const NATIVE_REVIEW_RECOVERY_DISPOSITION = {
 
 
 
+
+
+
+
+
 
 
 
@@ -805,6 +948,25 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// consumes did not change between 2.5.0 and 2.6.0, so the columns match
 	// the 2.5.0 row.
 	"2.6.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 }),
+	// Ground-truthed against the published v2.7.0 binary installed from its
+	// signed archive: `review capabilities` on the v2 lane still advertises
+	// capabilities/v2.5 (protocol minor 5) and answers status/v7, consent/v3,
+	// and the `start/v4` continuation, all of which the decoders already read.
+	// `review mode status --json` still answers `gentle-ai.rdd-mode-status/v1`
+	// and `review validate --gate pre-commit` still answers
+	// `gentle-ai.review-gate-result/v1` carrying `delivery`, both verified
+	// against the binary. riskEvidence and hint stay dark for the same reason
+	// they have on every row since 2.2.0: still not proven to reach the
+	// negotiated START path Pi reads. The closed fields Pi consumes did not
+	// change between 2.6.0 and 2.7.0, so the columns match the 2.6.0 row.
+	"2.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 }),
+	// Ground-truthed against the published v2.8.0 linux/amd64 binary from its
+	// signed release archive. The v2 lane still advertises capabilities/v2.5
+	// (protocol minor 5) with status/v7, consent/v3, and start/v4 schemas.
+	// The closed fields Pi consumes did not change between 2.7.0 and 2.8.0,
+	// so this row repeats 2.7.0. riskEvidence and hint remain dark because
+	// neither is proven to reach the negotiated START path Pi consumes.
+	"2.8.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 }),
 });
 
 
@@ -836,7 +998,7 @@ export class NativeReviewCliError extends Error {
 		this.launchAttempted = launchAttempted;
 		this.mutating = mutating;
 		this.mutationOutcome = launchAttempted && mutating ? "unknown" : "none";
-		this.nextAction = this.mutationOutcome === "unknown" ? "review.status" : undefined;
+		this.nextAction = this.mutationOutcome === "unknown" && operation !== NATIVE_REVIEW_OPERATION.SDD_ATTEMPT ? "review.status" : undefined;
 		this.diagnostics = diagnostics ?? { operation, error_code: code, timed_out: false, output_limit_exceeded: false };
 		this.auditRecord = auditRecord;
 	}
@@ -1047,8 +1209,15 @@ function decodeNativeReviewRecovery(value         )                       {
 		...(recovery.maintainer_authorization === undefined ? {} : { maintainerAuthorization: requiredString(recovery.maintainer_authorization) }),
 	};
 }
+function decodeNativeReviewDiscardedWorkSummary(value         )                                   {
+	const discardedWork = exactObject(value, ["captured_lens_results", "findings_present"]);
+	return {
+		capturedLensResults: stringArray(discardedWork.captured_lens_results),
+		findingsPresent: booleanValue(discardedWork.findings_present),
+	};
+}
 function decodeNativeReviewStatusEntry(value         )                             {
-	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "snapshot_identity", "chain_identity", "recovery"]);
+	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "snapshot_identity", "chain_identity", "recovery", "discarded_work"]);
 	return {
 		version: enumString(entry.version, Object.values(NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION))                                     ,
 		...(entry.lineage_id === undefined ? {} : { lineageId: requiredString(entry.lineage_id) }),
@@ -1059,6 +1228,7 @@ function decodeNativeReviewStatusEntry(value         )
 		...(entry.snapshot_identity === undefined ? {} : { snapshotIdentity: sha256Identity(entry.snapshot_identity) }),
 		...(entry.chain_identity === undefined ? {} : { chainIdentity: requiredString(entry.chain_identity) }),
 		...(entry.recovery === undefined ? {} : { recovery: decodeNativeReviewRecovery(entry.recovery) }),
+		...(entry.discarded_work === undefined ? {} : { discardedWork: decodeNativeReviewDiscardedWorkSummary(entry.discarded_work) }),
 		problems: stringArray(entry.problems),
 	};
 }
@@ -1253,6 +1423,46 @@ function nativeError(code                       , operation
 
 
 
+const NATIVE_SDD_DEPENDENCIES = ["proposal", "specs", "design", "tasks", "apply", "verify", "archive"]         ;
+const NATIVE_SDD_INSTRUCTION_PHASES = ["apply", "verify", "remediate", "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]);
+		if (Object.keys(instructions).length !== NATIVE_SDD_INSTRUCTION_PHASES.length) throw new Error("native SDD instructions have an unsupported shape");
+	}
+	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                         ;
@@ -1373,9 +1583,7 @@ class NativeReviewPlainCli {
 			if (!isCanonicalProcessString(value)) throw new TypeError(`Native ABANDON ${name} must be a non-empty, trimmed, NUL-free string`);
 		}
 		if (!Array.isArray(request.capturedLensResults) || request.capturedLensResults.some((entry) => !isCanonicalProcessString(entry))) throw new TypeError("Native ABANDON capturedLensResults must be an array of non-empty, trimmed, NUL-free strings");
-		for (const [name, value] of [["findingsPresent", request.findingsPresent], ["evidenceRecordsPresent", request.evidenceRecordsPresent]]         ) {
-			if (typeof value !== "boolean") throw new TypeError(`Native ABANDON ${name} must be a boolean`);
-		}
+		if (typeof request.findingsPresent !== "boolean") throw new TypeError("Native ABANDON findingsPresent must be a boolean");
 		if (request.maintainerAuthorization !== nativeReviewAbandonAuthorization(request)) throw new TypeError("Native ABANDON maintainerAuthorization must match the exact lineage, revision, snapshot, reason, discarded-work, and actor binding");
 		const execution = await this.execute(NATIVE_REVIEW_OPERATION.ABANDON, request.cwd, [
 			"review", "abandon", "--cwd", request.cwd,
@@ -1464,7 +1672,11 @@ class NativeReviewPlainCli {
 	}
 }
 
-export function nativeReviewAbandonAuthorization(request                                                                                                                                                                                   )         {
+export function nativeReviewAbandonAuthorization(request                                                                                                                                                        )         {
+	// gentle-ai 0ed9225f removed evidence records from the discarded-work summary,
+	// so the native v2 gate verifies an exact eight-line binding (schema, lineage,
+	// revision, snapshot_identity, reason, captured_lens_results, findings_present,
+	// actor) — there is no evidence_records_present line to derive or relay.
 	return [
 		"gentle-ai.review-abandon-authorization/v2",
 		`lineage=${request.lineage}`,
@@ -1473,7 +1685,6 @@ export function nativeReviewAbandonAuthorization(request
 		`reason=${request.reason}`,
 		`captured_lens_results=${request.capturedLensResults.join(",")}`,
 		`findings_present=${request.findingsPresent}`,
-		`evidence_records_present=${request.evidenceRecordsPresent}`,
 		`actor=${request.actor.trim()}`,
 	].join("\n");
 }
@@ -1596,14 +1807,20 @@ function splitNativeConsentInvocation(invocation        )                    {
 	let quote                       ;
 	let escaping = false;
 	let started = false;
-	for (const character of invocation.trim()) {
+	const source = invocation.trim();
+	for (let index = 0; index < source.length; index += 1) {
+		const character = source[index] ;
 		if (escaping) {
 			current += character;
 			escaping = false;
 			started = true;
 			continue;
 		}
-		if (character === "\\" && quote !== "'") {
+		// Provider invocations are not shell commands. Keep every path backslash
+		// verbatim, including quoted UNC and drive-root paths. Outside quotes,
+		// only a backslash before whitespace joins a space-containing token.
+		const next = source[index + 1];
+		if (character === "\\" && quote === undefined && next !== undefined && /\s/.test(next)) {
 			escaping = true;
 			started = true;
 			continue;
@@ -1694,7 +1911,9 @@ function consentInvocationArguments(request                                  )
 	if (words[0] !== "gentle-ai" || words[1] !== "review" || words[2] !== "start") throw new NativeReviewConsentBindingError("consent-invocation-not-start", "Native consent invocation is not a provider review START");
 	const arguments_ = words.slice(1);
 	if (exactConsentOption(arguments_, "--contract") !== REVIEW_INTEGRATION_CONTRACT) throw new NativeReviewConsentBindingError("consent-invocation-contract-changed", "Native consent invocation contract changed");
-	if (exactConsentOption(arguments_, "--cwd") !== request.cwd) throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
+	const providerCwd = exactConsentOption(arguments_, "--cwd");
+	const requestedCwd = normalizeNativeReviewCwd(request.cwd);
+	if (normalizeNativeReviewCwd(providerCwd) !== requestedCwd) throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
 	if (exactConsentOption(arguments_, "--target") !== request.consent.targetIdentity) throw new NativeReviewConsentBindingError("consent-invocation-target-changed", "Native consent invocation target binding changed");
 	if (exactConsentOption(arguments_, "--projection") !== request.consent.projection) throw new NativeReviewConsentBindingError("consent-invocation-projection-changed", "Native consent invocation projection binding changed");
 	const lineageId = optionalConsentLineageOption(arguments_);
@@ -1774,6 +1993,23 @@ function decodeNativeProviderRoleCaptureArtifact(value         )
 	});
 }
 
+// gentle-pi#638: the recorded declaration Go prints for one unachievable slot. Closed key set, exact schema identity, and the lens Go itself resolved from the request hash -- the host never asserts which lens failed, only reads back the one the provider bound.
+function decodeNativeUnachievableLensCaptureArtifact(value         )                                              {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("native unachievable lens capture artifact must be an object");
+	const body = value                           ;
+	const allowed = new Set(["schema", "lineage_id", "target_identity", "lens", "selected_order", "reason", "recorded"]);
+	for (const key of Object.keys(body)) if (!allowed.has(key)) throw new TypeError(`native unachievable lens capture artifact carries unexpected key ${key}`);
+	const text = (key        )         => {
+		const found = body[key];
+		if (typeof found !== "string" || found.trim() !== found || found.length === 0) throw new TypeError(`native unachievable lens capture artifact ${key} must be a non-empty trimmed string`);
+		return found;
+	};
+	if (text("schema") !== NATIVE_REVIEW_UNACHIEVABLE_LENS_CAPTURE_SCHEMA) throw new TypeError(`native unachievable lens capture artifact schema must be ${NATIVE_REVIEW_UNACHIEVABLE_LENS_CAPTURE_SCHEMA}`);
+	if (typeof body.selected_order !== "number" || !Number.isSafeInteger(body.selected_order) || body.selected_order < 0) throw new TypeError("native unachievable lens capture artifact selected_order must be a non-negative integer");
+	if (body.recorded !== true) throw new TypeError("native unachievable lens capture artifact must report recorded: true");
+	return Object.freeze({ schema: NATIVE_REVIEW_UNACHIEVABLE_LENS_CAPTURE_SCHEMA, lineageId: text("lineage_id"), targetIdentity: text("target_identity"), lens: text("lens"), selectedOrder: body.selected_order, reason: text("reason"), recorded: true });
+}
+
 export class NativeReviewCliV216                            {
 	                 plain                      ;
 	                 adapter                 ;
@@ -1865,6 +2101,89 @@ export class NativeReviewCliV216                            {
 		return this.invoke(operation, cwd, arguments_, mutating, signal, this.executablePath(operation, mutating), toleratedStderr);
 	}
 
+	async sddAttemptAcquire(request                         )                                  {
+		return this.sddAttempt("acquire", request);
+	}
+
+	async sddAttemptSettle(request                        )                                  {
+		return this.sddAttempt("settle", request);
+	}
+
+	        async sddAttempt(verb                      , request                                                  )                                  {
+		const args = ["sdd-attempt", verb, "--cwd", request.workspaceRoot, "--change", request.changeName, "--request-id", request.requestId];
+		if (!isAbsolute(request.workspaceRoot) || !isCanonicalProcessString(request.workspaceRoot) || !isCanonicalProcessString(request.changeName) || !/^[a-z0-9][a-z0-9._-]{0,127}$/.test(request.requestId)) throw new TypeError("Invalid SDD attempt identity");
+		const text = (flag        , value        , max        ) => {
+			if (!isCanonicalProcessString(value) || /[\r\n]/.test(value) || Buffer.byteLength(value) > max) throw new TypeError(`Invalid ${flag}`);
+			args.push(flag, value);
+		};
+		const revision = (flag        , value                    ) => {
+			if (value === undefined) return;
+			if (!/^sha256:[0-9a-f]{64}$/.test(value)) throw new TypeError(`Invalid ${flag}`);
+			args.push(flag, value);
+		};
+		if (verb === "acquire") {
+			const acquire = request                           ;
+			text("--work-unit", acquire.workUnit, 160);
+			text("--evidence-goal", acquire.evidenceGoal, 240);
+			for (const [flag, value, max] of [["--max-attempts", acquire.maxAttempts, 100], ["--max-changed-lines", acquire.maxChangedLines, 1_000_000]]         ) {
+				if (value === undefined) continue;
+				if (!Number.isInteger(value) || value < 1 || value > max) throw new TypeError(`Invalid ${flag}`);
+				args.push(flag, String(value));
+			}
+			if (acquire.expectedRevision === "") args.push("--expected-revision", "");
+			else revision("--expected-revision", acquire.expectedRevision);
+			if (acquire.token !== undefined) text("--token", acquire.token, 500);
+		} else {
+			const settle = request                          ;
+			text("--token", settle.token, 500);
+			if (!Object.values(SDD_ATTEMPT_OUTCOME).includes(settle.outcome)) throw new TypeError("Invalid outcome");
+			args.push("--outcome", settle.outcome);
+			if (settle.outcome === "interrupted" ? settle.evidenceRevision !== undefined || settle.remediationEvidence !== undefined : !settle.evidenceRevision && !(settle.outcome === "passed" && settle.remediationEvidence)) throw new TypeError("Invalid terminal evidence");
+			revision("--evidence-revision", settle.evidenceRevision);
+			text("--diagnosis", settle.diagnosis, 500);
+			if (!["reused", "invalidated"].includes(settle.harnessDisposition)) throw new TypeError("Invalid harness disposition");
+			args.push("--harness-disposition", settle.harnessDisposition);
+			text("--cleanup-evidence", settle.cleanupEvidence, 500);
+			text("--process-evidence", settle.processEvidence, 500);
+			if (settle.remediationEvidence !== undefined) args.push("--remediation-evidence", settle.remediationEvidence);
+		}
+		revision("--remediates-evidence-revision", request.remediatesEvidenceRevision);
+		args.push(...nativeUntrackedSelectionArguments(nativeUntrackedSelection(request)));
+		const operation = NATIVE_REVIEW_OPERATION.SDD_ATTEMPT;
+		const { body } = await this.negotiated(operation, request.workspaceRoot, args, true);
+		return decode(operation, true, () => {
+			const result = body                                     ;
+			if (!result || !["proceed", "blocked", "complete"].includes(result.state)) throw new TypeError("Invalid compact state");
+			if (verb === "acquire" && result.state === "proceed" && !isCanonicalProcessString(result.token)) throw new TypeError("Missing compact token");
+			if (result.reason !== undefined && typeof result.reason !== "string") throw new TypeError("Invalid compact reason");
+			return { state: result.state, ...(result.token === undefined ? {} : { token: result.token }), ...(result.reason === undefined ? {} : { reason: result.reason }) };
+		});
+	}
+
+	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");
@@ -2139,6 +2458,25 @@ export class NativeReviewCliV216                            {
 		});
 	}
 
+	// gentle-pi#638: `gentle-ai review capture-unachievable` records one bound declaration that the exact slot the collect transition offered cannot be completed under current conditions. Unlike every other capture verb the host runs, this one reports a failure instead of a result, so it never takes the provider-issued tokens verbatim: the declaration's binding values are named fields re-derived from the slot, and Go verifies them against the frozen lineage, revision, target, and subject hash before recording anything (internal/cli/review_capture_unachievable.go). A binding that no longer matches is a typed refusal the caller surfaces, never a host-side reconstruction.
+	async captureUnachievableLens(request                                            )                                                       {
+		for (const [field, value] of (["lineageId", "reason"]         ).map((field) => [field, request[field]]         )) {
+			if (!isCanonicalProcessString(value)) throw new TypeError(`Native CAPTURE_UNACHIEVABLE ${field} must be a non-empty, trimmed, NUL-free string`);
+		}
+		// The three identity fields are digests on every slot the provider offers, so a non-sha value means the declaration binding was parsed wrong; refuse it locally instead of invoking a doomed process.
+		for (const [field, value] of (["targetIdentity", "expectedRevision", "requestHash"]         ).map((field) => [field, request[field]]         )) {
+			if (!/^sha256:[0-9a-f]{64}$/.test(value)) throw new TypeError(`Native CAPTURE_UNACHIEVABLE ${field} must be a canonical SHA-256 identity`);
+		}
+		const detail = request.detail === undefined ? "" : request.detail.trim();
+		// gentle-pi#822: the native limit is 512 UTF-8 bytes, not 512 UTF-16 code units — the Go side measures the encoded payload, so a multibyte detail needs Buffer.byteLength; a .length check would let 300 two-byte characters through.
+		if (Buffer.byteLength(detail, "utf8") > NATIVE_REVIEW_UNACHIEVABLE_LENS_DETAIL_LIMIT) throw new TypeError(`Native CAPTURE_UNACHIEVABLE detail exceeds ${NATIVE_REVIEW_UNACHIEVABLE_LENS_DETAIL_LIMIT} bytes`);
+		if (request.repositoryContext !== undefined && !isCanonicalProcessString(request.repositoryContext)) throw new TypeError("Native CAPTURE_UNACHIEVABLE repositoryContext must be a non-empty, trimmed, NUL-free string");
+		const executable = this.executablePath(NATIVE_REVIEW_OPERATION.CAPTURE_UNACHIEVABLE, true);
+		// gentle-pi#822: --repository-context is authoritative and mutually exclusive with a path (the captureProviderRole discipline), so --cwd rides the invocation only when no repository context names it; the process working directory stays request.cwd either way.
+		const execution = await this.invoke(NATIVE_REVIEW_OPERATION.CAPTURE_UNACHIEVABLE, request.cwd, ["review", "capture-unachievable", "--lineage", request.lineageId, "--target", request.targetIdentity, "--expected-revision", request.expectedRevision, "--request-hash", request.requestHash, "--reason", request.reason, ...(detail === "" ? [] : ["--detail", detail]), ...(request.repositoryContext === undefined ? ["--cwd", request.cwd] : ["--repository-context", request.repositoryContext])], true, request.signal, executable);
+		return decode(NATIVE_REVIEW_OPERATION.CAPTURE_UNACHIEVABLE, true, () => decodeNativeUnachievableLensCaptureArtifact(execution.body));
+	}
+
 	// gentle-pi#311 P5: executes one provider-rendered `review.finalize`
 	// execute transition exactly as rendered. The tokens come verbatim from
 	// the negotiated next_transition (e.g. `--lineage=<id>
@@ -2194,6 +2532,26 @@ export class NativeReviewCliV216                            {
 		return decode(NATIVE_REVIEW_OPERATION.MODE, mutating, () => decodeNativeReviewMode(execution.body, request.operation));
 	}
 
+	// Read-only risk assessment (gentle-ai#4295, gentle-pi#662). Never mutates;
+	// an older binary without the verb, or any other process/decode failure,
+	// rejects -- callers (the `gentle_review` tool's `assess` operation) fail
+	// closed to `high`.
+	async assess(request                           )                              {
+		if (request.baseRef !== undefined && !isCanonicalProcessString(request.baseRef)) throw new TypeError("Native ASSESS baseRef must be a non-empty, trimmed, NUL-free string");
+		if (request.baseRef !== undefined && request.committedOnly !== true) throw new TypeError("Native ASSESS baseRef requires explicit committedOnly acknowledgement");
+		if (request.baseRef === undefined && request.committedOnly !== undefined) throw new TypeError("Native ASSESS committedOnly requires an explicit baseRef");
+		const cwd = await canonicalNativeReviewCwd(request.cwd);
+		const execution = await this.invoke(
+			NATIVE_REVIEW_OPERATION.ASSESS,
+			cwd,
+			["review", "assess", "--cwd", cwd, ...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef, "--committed-only"]), "--json"],
+			false,
+			request.signal,
+			this.executablePath(NATIVE_REVIEW_OPERATION.ASSESS, false),
+		);
+		return decode(NATIVE_REVIEW_OPERATION.ASSESS, false, () => decodeReviewAssessmentV1(execution.body));
+	}
+
 	// Recovery commands are version-gated plain CLI operations outside the
 	// negotiated integration-v1 contract, exactly like reviewStatus.
 	reclaim(request                            )                                      {