gentle-pi 2.5.0 → 2.6.0

package/lib/agents-widget.ts

@@ -6,7 +6,7 @@ import { CARD_TONE, cardInnerWidth, renderCard, type CardTheme, type CardTone }
 // Gentle Agents widget: the card above the editor. Reads task records only
 // (status, prompt, counters, timestamps), so drawing it costs nothing per
 // event. One row per task: glyph, agent, task summary, then
-// model · tokens · cost · time right-aligned.
+// model · effort · tokens · cost · time right-aligned.
 
 export const AGENTS_GLYPH = "❀";
 
@@ -29,7 +29,7 @@ interface Columns {
 	name: number;
 	task: number;
 	meta: number;
-	withModel: boolean;
+	fullMetrics: boolean;
 }
 
 const LOOK: Record<TaskStatus, StatusLook> = {
@@ -73,6 +73,7 @@ export function formatElapsed(ms: number): string {
 }
 
 function clip(text: string, width: number): string {
+	if (width <= 0) return "";
 	if (visibleWidth(text) <= width) return text;
 	let out = "";
 	for (const char of text) {
@@ -139,9 +140,20 @@ function modelLabel(task: TaskRecord): string {
 	return id === "default" ? "" : id;
 }
 
-function meta(task: TaskRecord, now: number, withModel: boolean): string {
+function executionLabel(task: TaskRecord, width = Infinity): string {
+	const model = modelLabel(task);
+	const effort = task.thinking ?? "";
+	if (!model) return clip(effort, width);
+	if (!effort) return clip(model, width);
+	const suffix = ` · ${effort}`;
+	if (width <= visibleWidth(suffix)) return clip(`${model} · ${effort}`, width);
+	return clip(model, width - visibleWidth(suffix)) + suffix;
+}
+
+function meta(task: TaskRecord, now: number, fullMetrics: boolean): string {
 	if (task.status === TASK_STATUS.QUEUED) return "queued";
-	const parts = [withModel ? modelLabel(task) : "", task.tokens > 0 ? formatTokens(task.tokens) : "", task.cost > 0 ? `$${task.cost.toFixed(2)}` : "", elapsed(task, now)];
+	if (!fullMetrics) return executionLabel(task);
+	const parts = [executionLabel(task), task.tokens > 0 ? formatTokens(task.tokens) : "", task.cost > 0 ? `$${task.cost.toFixed(2)}` : "", elapsed(task, now)];
 	return parts.filter((part) => part.length > 0).join(" · ");
 }
 
@@ -151,23 +163,30 @@ function taskText(task: TaskRecord): string {
 	return task.label;
 }
 
-// Narrow cards give up the task column first, then the model label.
+// Narrow cards give up the task and usage columns before execution metadata.
 function columns(tasks: readonly TaskRecord[], inner: number, now: number): Columns {
-	const name = Math.min(NAME_MAX, Math.max(...tasks.map((task) => visibleWidth(task.agent))));
+	const name = Math.max(0, Math.min(NAME_MAX, inner - 3, Math.max(...tasks.map((task) => visibleWidth(task.agent)))));
 	const fixed = 1 + GLYPH_GAP.length + name + COLUMN_GAP.length;
-	const metaWidth = (withModel: boolean) => Math.max(...tasks.map((task) => visibleWidth(meta(task, now, withModel))));
+	const metaWidth = (fullMetrics: boolean) => Math.max(...tasks.map((task) => visibleWidth(meta(task, now, fullMetrics))));
 	const full = metaWidth(true);
 	const task = inner - fixed - full - COLUMN_GAP.length;
-	if (task >= TASK_MIN) return { inner, name, meta: full, task, withModel: true };
-	return { inner, name, meta: metaWidth(false), task: 0, withModel: false };
+	if (task >= TASK_MIN) return { inner, name, meta: full, task, fullMetrics: true };
+	return { inner, name, meta: Math.max(0, Math.min(inner - fixed, metaWidth(false))), task: 0, fullMetrics: false };
 }
 
-function row(task: TaskRecord, theme: CardTheme, cols: Columns, now: number): string[] {
+function row(task: TaskRecord, theme: CardTheme, cols: Columns, now: number, allowMetadataRow: boolean): string[] {
 	const look = LOOK[task.status];
 	const name = clip(task.agent, cols.name);
 	const head = `${theme.fg(look.role, look.glyph)}${GLYPH_GAP}${theme.fg(NAME_ROLE, name)}${" ".repeat(cols.name - visibleWidth(name))}`;
-	const tail = theme.fg(META_ROLE, meta(task, now, cols.withModel).padStart(cols.meta));
-	if (cols.task === 0) return [`${head}${" ".repeat(Math.max(COLUMN_GAP.length, cols.inner - visibleWidth(head) - visibleWidth(tail)))}${tail}`];
+	const metadata = cols.fullMetrics ? meta(task, now, true) : task.status === TASK_STATUS.QUEUED ? clip("queued", cols.meta) : executionLabel(task, cols.meta);
+	const tail = theme.fg(META_ROLE, " ".repeat(Math.max(0, cols.meta - visibleWidth(metadata))) + metadata);
+	if (cols.inner < 3) return [theme.fg(look.role, clip(look.glyph, cols.inner))];
+	// The scrollable sidebar can preserve identity and execution metadata on
+	// separate rows. The height-capped above-editor widget keeps its row budget.
+	if (allowMetadataRow && cols.task === 0 && task.status !== TASK_STATUS.QUEUED && visibleWidth(executionLabel(task)) > cols.meta) {
+		return [head, theme.fg(META_ROLE, executionLabel(task, cols.inner))];
+	}
+	if (cols.task === 0) return [`${head}${" ".repeat(Math.max(0, cols.inner - visibleWidth(head) - visibleWidth(tail)))}${tail}`];
 	const text = clip(taskText(task), cols.task);
 	return [`${head}${COLUMN_GAP}${theme.fg(TASK_ROLE, text)}${" ".repeat(cols.task - visibleWidth(text))}${COLUMN_GAP}${tail}`];
 }
@@ -210,8 +229,8 @@ export function renderAgentsCard(tasks: readonly TaskRecord[], theme: CardTheme,
 	if (shown.length === 0) return [];
 	const cols = columns(shown, cardInnerWidth(width), now);
 	const { listed, hidden } = options.collapsed ? { listed: [shown[0]], hidden: 0 } : visibleRows(shown, options.maxRows);
-	const hint = options.collapsed && options.collapseKey ? `${options.collapseKey} expand` : batchElapsed(shown, now);
-	const body = listed.flatMap((task) => row(task, theme, cols, now));
+	const hint = options.collapsed && options.collapseKey ? `${options.collapseKey} expand` : shown.length > 1 ? batchElapsed(shown, now) : undefined;
+	const body = listed.flatMap((task) => row(task, theme, cols, now, options.maxRows === undefined));
 	if (hidden > 0) body.push(overflowRow(hidden, theme, options.viewKey));
 	return renderCard(
 		{ title: "Agents", subtitle: counts(shown), body, tone: tone(shown), glyph: AGENTS_GLYPH },

package/lib/gentle-ai-binary.ts

@@ -16,6 +16,8 @@ import {
 import { fileURLToPath } from "node:url";
 
 export const GENTLE_AI_BINARY_MISSING_CODE = "package-local-binary-missing";
+export const GENTLE_AI_INSTALL_RECOVERY_COMMAND = "node scripts/install-gentle-ai.mjs";
+export const GENTLE_AI_INSTALL_RECOVERY_INSTRUCTIONS = `If GENTLE_PI_SKIP_GENTLE_AI_INSTALL is set, remove or unset it before changing to the installed gentle-pi package directory and running \`${GENTLE_AI_INSTALL_RECOVERY_COMMAND}\`.`;
 // Derived from the one authoritative pinned version in
 // scripts/gentle-ai-installer.mjs rather than repeating the literal here, so
 // the two can never independently drift apart the way they once did.
@@ -25,7 +27,7 @@ export class PackageLocalGentleAiBinaryMissingError extends Error {
 	readonly code = GENTLE_AI_BINARY_MISSING_CODE;
 	constructor(path: string) {
 		super(
-			`${GENTLE_AI_BINARY_MISSING_CODE}: Gentle AI v${GENTLE_AI_VERSION} is not installed at ${path}. Reinstall gentle-pi, or use GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1 only for development/offline installs.`,
+			`${GENTLE_AI_BINARY_MISSING_CODE}: Gentle AI v${GENTLE_AI_VERSION} is not installed at ${path}. ${GENTLE_AI_INSTALL_RECOVERY_INSTRUCTIONS} A missing binary can result from skipped lifecycle scripts, but does not prove install lifecycle scripts were disabled.`,
 		);
 		this.name = "PackageLocalGentleAiBinaryMissingError";
 	}

package/lib/gentle-ai-renderer.ts

@@ -7,7 +7,9 @@ import { sanitizeTerminalText } from "./terminal-theme.ts";
 // gentle_review tool draws the same card as the other Gentle notices. The
 // call component owns the top rule; the result component closes the frame.
 
-export type GentleAiRenderTheme = CardTheme;
+export interface GentleAiRenderTheme extends CardTheme {
+	bg?(color: string, text: string): string;
+}
 
 export interface GentleAiRenderState {
 	lifecycleComponent?: boolean;
@@ -67,12 +69,12 @@ export function getGentleAiRenderState(state: unknown): GentleAiRenderState | un
 // result is in, the result card closes it instead.
 export class GentleAiCallCard {
 	private card: Card = { title: CARD_TITLE, body: [], tone: CARD_TONE.WARNING };
-	private theme: CardTheme = passthroughTheme;
+	private theme: GentleAiRenderTheme = passthroughTheme;
 	private detail: string | undefined;
 	private hint: string | undefined;
 	private open = true;
 
-	update(status: LifecycleStatus, operationPath: string, theme: CardTheme, detail?: string, hint?: string): void {
+	update(status: LifecycleStatus, operationPath: string, theme: GentleAiRenderTheme, detail?: string, hint?: string): void {
 		this.card = { title: CARD_TITLE, subtitle: `${status} · ${operationPath}`, body: [], tone: STATUS_TONE[status], glyph: CARD_GLYPH };
 		this.theme = theme;
 		this.detail = detail;
@@ -98,10 +100,10 @@ export class GentleAiResultCard {
 	private readonly text: string;
 	private readonly expanded: boolean;
 	private readonly tone: CardTone;
-	private readonly theme: CardTheme;
+	private readonly theme: GentleAiRenderTheme;
 	private readonly partial: boolean;
 
-	constructor(text: string, expanded: boolean, tone: CardTone, theme: CardTheme, partial = false) {
+	constructor(text: string, expanded: boolean, tone: CardTone, theme: GentleAiRenderTheme, partial = false) {
 		this.text = text;
 		this.expanded = expanded;
 		this.tone = tone;
@@ -139,7 +141,7 @@ export interface GentleAiResultRenderOptions {
 export function renderGentleAiResult(
 	result: AgentToolResult<unknown>,
 	options: GentleAiResultRenderOptions,
-	theme: CardTheme = passthroughTheme,
+	theme: GentleAiRenderTheme = passthroughTheme,
 	context?: GentleAiRenderContext,
 ): GentleAiResultCard {
 	const textItems = result.content.flatMap((content) => (content.type === "text" ? [sanitizeTerminalText(content.text)] : []));

package/lib/native-review-cli.ts

@@ -65,7 +65,11 @@ export const NATIVE_REVIEW_OPERATION = {
 	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",
 } as const;
 export type NativeReviewOperation = (typeof NATIVE_REVIEW_OPERATION)[keyof typeof NATIVE_REVIEW_OPERATION];
 
@@ -106,6 +110,8 @@ export interface NativeReviewCli {
 	captureResult?(request: NativeReviewCaptureResultRequest): Promise<NativeReviewCaptureResultOutcome>;
 	captureCorrectionPlan?(request: NativeReviewCorrectionPlanCaptureRequest): Promise<ReviewLastEventClosureV1>;
 	captureProviderRole?(request: NativeReviewProviderRoleCaptureRequest): Promise<NativeReviewProviderRoleCaptureOutcome>;
+	// gentle-pi#638: records the host relay's declaration that one bound selected lens slot cannot be completed under current conditions. Younger than every binary pinned in NATIVE_CLI_CONTRACTS, so the capability is gated invocation-adjacent (see isNativeReviewUnachievableVerbRefused) instead of by a contract row.
+	captureUnachievableLens?(request: NativeReviewUnachievableLensCaptureRequest): Promise<NativeReviewUnachievableLensCaptureArtifact>;
 	// Dark until a negotiated version reports the `mode` capability true
 	// (Design Decision #7, organic-rdd-parity). Plain versioned CLI operation,
 	// outside the negotiated review-integration protocol — same shape as
@@ -116,6 +122,44 @@ export interface NativeReviewCli {
 	// an older binary without the verb, or any other process/decode failure,
 	// rejects the returned promise -- callers fail closed to `high` risk.
 	assess?(request: NativeReviewAssessRequest): Promise<ReviewAssessmentV1>;
+	// Exact native SDD readiness authority for an explicitly selected phase.
+	// This is intentionally separate from review/RDD gates and carries no
+	// delivery or review-transaction authority.
+	sddStatus?(request: NativeSddStatusRequest): Promise<NativeSddStatusV2>;
+	sddContinue?(request: NativeSddStatusRequest): Promise<NativeSddStatusV2>;
+	sddAttemptAcquire?(request: NativeSddAcquireRequest): Promise<NativeSddAttemptResult>;
+	sddAttemptSettle?(request: NativeSddSettleRequest): Promise<NativeSddAttemptResult>;
+}
+
+export interface NativeSddAttemptRequest extends Pick<NativeUntrackedSelectionRequest, "untrackedScope" | "expectedUntrackedInventory" | "intendedUntracked"> {
+	workspaceRoot: string;
+	changeName: string;
+	requestId: string;
+	remediatesEvidenceRevision?: string;
+}
+export interface NativeSddAcquireRequest extends NativeSddAttemptRequest {
+	workUnit: string;
+	evidenceGoal: string;
+	maxAttempts?: number;
+	maxChangedLines?: number;
+	expectedRevision?: string;
+	token?: string;
+}
+export const SDD_ATTEMPT_OUTCOME = { PASSED: "passed", FAILED: "failed", INTERRUPTED: "interrupted" } as const;
+export interface NativeSddSettleRequest extends NativeSddAttemptRequest {
+	token: string;
+	outcome: (typeof SDD_ATTEMPT_OUTCOME)[keyof typeof SDD_ATTEMPT_OUTCOME];
+	evidenceRevision?: string;
+	remediationEvidence?: string;
+	diagnosis: string;
+	harnessDisposition: "reused" | "invalidated";
+	cleanupEvidence: string;
+	processEvidence: string;
+}
+export interface NativeSddAttemptResult {
+	state: "proceed" | "blocked" | "complete";
+	token?: string;
+	reason?: string;
 }
 
 export const NATIVE_REVIEW_MODE_OPERATION = {
@@ -152,6 +196,35 @@ export const NATIVE_REVIEW_MODE_SCOPE = {
 } as const;
 export type NativeReviewModeScope = (typeof NATIVE_REVIEW_MODE_SCOPE)[keyof typeof NATIVE_REVIEW_MODE_SCOPE];
 
+export interface NativeSddStatusRequest {
+	changeName?: string;
+	workspaceRoot: string;
+	signal?: AbortSignal;
+}
+
+export type NativeSddPhase = "apply" | "verify" | "archive";
+export type NativeSddDependencyState = "blocked" | "ready" | "all_done";
+
+/**
+ * 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.
+ */
+export interface NativeSddStatusV2 extends Readonly<Record<string, unknown>> {
+	schemaName: "gentle-ai.sdd-status";
+	schemaVersion: 2;
+	changeName: string | null;
+	artifactStore: "openspec" | "engram" | "hybrid" | "none";
+	planningHome: Readonly<Record<string, unknown>> & { mode: "repo-local"; path: string };
+	changeRoot: string | null;
+	actionContext: Readonly<Record<string, unknown>> & { mode: "repo-local"; workspaceRoot: string; allowedEditRoots: readonly string[] };
+	dependencies: Readonly<Record<(typeof NATIVE_SDD_DEPENDENCIES)[number], NativeSddDependencyState>>;
+	phaseInstructions?: Readonly<Record<(typeof NATIVE_SDD_INSTRUCTION_PHASES)[number], readonly string[]>>;
+	blockedReasons: readonly string[];
+	nextRecommended: string;
+	remediationState?: { required: boolean; complete: boolean; failedEvidenceRevision: string };
+}
+
 export interface NativeReviewModeRequest {
 	cwd: string;
 	operation: NativeReviewModeOperation;
@@ -431,6 +504,49 @@ export interface NativeReviewProviderRoleCaptureArtifact {
 	readonly captured: true;
 }
 
+// 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;
+
+export interface NativeReviewUnachievableLensCaptureRequest {
+	/** Exact frozen review lineage identifier of the offered slot. */
+	readonly lineageId: string;
+	/** Exact frozen target identity of the offered slot. */
+	readonly targetIdentity: string;
+	/** Exact reviewing-authority revision the collect transition offered. */
+	readonly expectedRevision: string;
+	/** The offered slot's subject-hash; Go resolves the lens from it. */
+	readonly requestHash: string;
+	/** Short machine-readable cause, e.g. relay_transport_bound_exceeded. */
+	readonly reason: string;
+	/** Optional bounded evidence; refused above the Go-side byte limit. */
+	readonly detail?: string;
+	/** Opaque provider-issued repository context the slot carried, if any. */
+	readonly repositoryContext?: string;
+	/** Process working directory only; never rendered into the invocation. */
+	readonly cwd: string;
+	readonly signal?: AbortSignal;
+}
+
+export interface NativeReviewUnachievableLensCaptureArtifact {
+	readonly schema: typeof NATIVE_REVIEW_UNACHIEVABLE_LENS_CAPTURE_SCHEMA;
+	readonly lineageId: string;
+	readonly targetIdentity: string;
+	readonly lens: string;
+	readonly selectedOrder: number;
+	readonly reason: string;
+	readonly recorded: true;
+}
+
+// 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: unknown): boolean {
+	if (typeof error !== "object" || error === null) return false;
+	const stderr = (error as { diagnostics?: { stderr?: unknown } }).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. */
 export type NativeReviewProviderRoleCaptureOutcome = NativeReviewProviderRoleCaptureArtifact | ReviewLastEventClosureV1;
 
@@ -843,6 +959,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 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 }),
 });
 
 export interface NativeReviewProcessDiagnostics {
@@ -874,7 +997,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;
 	}
@@ -1299,6 +1422,46 @@ interface NativeJsonExecution {
 	process: ExecFileResult;
 }
 
+const NATIVE_SDD_DEPENDENCIES = ["proposal", "specs", "design", "tasks", "apply", "verify", "archive"] as const;
+const NATIVE_SDD_INSTRUCTION_PHASES = ["apply", "verify", "remediate", "archive"] as const;
+const NATIVE_SDD_NEXT_RECOMMENDATIONS = ["apply", "verify", "remediate", "archive", "archived", "resolve-blockers", "sdd-new", "select-change", "propose", "spec", "design", "tasks"] as const;
+const NATIVE_SDD_DEPENDENCY_STATES = ["blocked", "ready", "all_done"] as const;
+
+/** Strictly validates the native v2 contract while preserving its whole record. */
+export function decodeNativeSddStatusV2(value: unknown, request: Pick<NativeSddStatusRequest, "changeName" | "workspaceRoot">): NativeSddStatusV2 {
+	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 as NativeSddStatusV2;
+}
+
 class NativeReviewPlainCli {
 	private readonly adapter: ExecFileAdapter;
 	private readonly executable: string | (() => string);
@@ -1829,6 +1992,23 @@ function decodeNativeProviderRoleCaptureArtifact(value: unknown): NativeReviewPr
 	});
 }
 
+// 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: unknown): NativeReviewUnachievableLensCaptureArtifact {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("native unachievable lens capture artifact must be an object");
+	const body = value as Record<string, unknown>;
+	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: string): string => {
+		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 implements NativeReviewCli {
 	private readonly plain: NativeReviewPlainCli;
 	private readonly adapter: ExecFileAdapter;
@@ -1920,6 +2100,89 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 		return this.invoke(operation, cwd, arguments_, mutating, signal, this.executablePath(operation, mutating), toleratedStderr);
 	}
 
+	async sddAttemptAcquire(request: NativeSddAcquireRequest): Promise<NativeSddAttemptResult> {
+		return this.sddAttempt("acquire", request);
+	}
+
+	async sddAttemptSettle(request: NativeSddSettleRequest): Promise<NativeSddAttemptResult> {
+		return this.sddAttempt("settle", request);
+	}
+
+	private async sddAttempt(verb: "acquire" | "settle", request: NativeSddAcquireRequest | NativeSddSettleRequest): Promise<NativeSddAttemptResult> {
+		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: string, value: string, max: number) => {
+			if (!isCanonicalProcessString(value) || /[\r\n]/.test(value) || Buffer.byteLength(value) > max) throw new TypeError(`Invalid ${flag}`);
+			args.push(flag, value);
+		};
+		const revision = (flag: string, value: string | undefined) => {
+			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 as NativeSddAcquireRequest;
+			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]] as const) {
+				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 as NativeSddSettleRequest;
+			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 as unknown as NativeSddAttemptResult;
+			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: NativeSddStatusRequest): Promise<NativeSddStatusV2> {
+		return this.sddProjection(request, false);
+	}
+
+	async sddContinue(request: NativeSddStatusRequest): Promise<NativeSddStatusV2> {
+		if (!isCanonicalProcessString(request.changeName)) throw new TypeError("Native SDD continuation requires an exact selected change");
+		return this.sddProjection(request, true);
+	}
+
+	private async sddProjection(request: NativeSddStatusRequest, mutating: boolean): Promise<NativeSddStatusV2> {
+		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: NativeStartRequest): Promise<NativeStartResult> {
 		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");
@@ -2194,6 +2457,25 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 		});
 	}
 
+	// 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: NativeReviewUnachievableLensCaptureRequest): Promise<NativeReviewUnachievableLensCaptureArtifact> {
+		for (const [field, value] of (["lineageId", "reason"] as const).map((field) => [field, request[field]] as const)) {
+			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"] as const).map((field) => [field, request[field]] as const)) {
+			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>