gentle-pi 3.2.1 → 3.4.0

package/lib/double-esc-cancel-policy.ts

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gentlePiConfigHome } from "./agent-home.ts";
+
+// ---------------------------------------------------------------------------
+// Double-esc-cancel policy — global file > env > default off (issue #1163)
+//
+// Deliberately global-only (no project-file layer, unlike
+// background-subagents): this preference changes what a keypress does while
+// the agent is working, and a per-project override for a personal habit like
+// this would make the same key do two different things depending on which
+// repo happens to be open. Otherwise mirrors the resolution shape of
+// lib/background-subagents-policy.ts, minus that project-file layer.
+// ---------------------------------------------------------------------------
+
+export type DoubleEscCancelPolicy = "on" | "off";
+
+/** Which of the three sources decided the effective policy. */
+export type DoubleEscCancelSource = "global_file" | "environment" | "default";
+
+export interface DoubleEscCancelResolution {
+	policy: DoubleEscCancelPolicy;
+	source: DoubleEscCancelSource;
+	/** The deciding file was present but failed the strict decode. */
+	malformed: boolean;
+	globalFile: string;
+	globalFileExists: boolean;
+	/** The raw env value, reported even when it is unrecognized and inert. */
+	envValue: string | undefined;
+}
+
+export interface LoadDoubleEscCancelOptions {
+	/** Override the config home directory (used in tests to avoid touching ~/.pi). */
+	gentlePiConfigHome?: string;
+	/** Override the environment lookup (used in tests). */
+	env?: Record<string, string | undefined>;
+}
+
+export const DOUBLE_ESC_CANCEL_SCHEMA = "gentle-pi.double-esc-cancel/v1";
+export const DOUBLE_ESC_CANCEL_FILE = "double-esc-cancel.json";
+
+// Pi's own idle double-Esc (empty editor -> /tree or /fork, interactive-mode.js
+// `lastEscapeTime`) uses a 500ms window. Canceling a running turn throws away
+// in-flight work and is harder to undo than switching prompts, so this
+// confirmation deliberately gets double that time to land the second press.
+export const DOUBLE_ESC_CANCEL_WINDOW_MS = 1000;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Strict decode of {"schema":"gentle-pi.double-esc-cancel/v1","policy":"on"|"off"}.
+ * Any malformed shape (bad JSON, wrong schema, unknown keys, invalid policy)
+ * returns undefined so the caller fails closed to "off".
+ */
+export function parseDoubleEscCancelPolicyFile(raw: string): DoubleEscCancelPolicy | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (!isRecord(parsed)) return undefined;
+	if (parsed.schema !== DOUBLE_ESC_CANCEL_SCHEMA) return undefined;
+	if (parsed.policy !== "on" && parsed.policy !== "off") return undefined;
+	if (Object.keys(parsed).length !== 2) return undefined;
+	return parsed.policy;
+}
+
+/**
+ * Resolve the double-esc-cancel policy AND the source that decided it.
+ *
+ * Resolution order (first hit wins):
+ *   1. Global file `${configHome}/double-esc-cancel.json`
+ *      (configHome honors GENTLE_PI_CONFIG_HOME, default ~/.pi/gentle-ai)
+ *   2. Env var GENTLE_PI_DOUBLE_ESC_CANCEL ("on" | "off")
+ *   3. Default "off"
+ *
+ * A present-but-malformed file fails closed to "off" instead of falling
+ * through to the env var, and stays attributed to that file: "off decided
+ * by a broken global file" and "off by default" are different situations,
+ * and only the first one is a mistake to fix.
+ */
+export function resolveDoubleEscCancelPolicy(
+	options: LoadDoubleEscCancelOptions = {},
+): DoubleEscCancelResolution {
+	const env = options.env ?? process.env;
+	const envValue = env.GENTLE_PI_DOUBLE_ESC_CANCEL;
+	let globalFile = "";
+	try {
+		const configHome = options.gentlePiConfigHome ?? gentlePiConfigHome(env);
+		globalFile = join(configHome, DOUBLE_ESC_CANCEL_FILE);
+		const globalFileExists = existsSync(globalFile);
+		if (globalFileExists) {
+			let decoded: DoubleEscCancelPolicy | undefined;
+			try {
+				decoded = parseDoubleEscCancelPolicyFile(readFileSync(globalFile, "utf8"));
+			} catch {
+				// Unreadable is indistinguishable from unusable at this layer, and
+				// both must fail closed on the file that claimed the decision.
+				decoded = undefined;
+			}
+			return decoded === undefined
+				? { policy: "off", source: "global_file", malformed: true, globalFile, globalFileExists, envValue }
+				: { policy: decoded, source: "global_file", malformed: false, globalFile, globalFileExists, envValue };
+		}
+		if (envValue === "on" || envValue === "off") {
+			return { policy: envValue, source: "environment", malformed: false, globalFile, globalFileExists, envValue };
+		}
+		return { policy: "off", source: "default", malformed: false, globalFile, globalFileExists, envValue };
+	} catch {
+		return { policy: "off", source: "default", malformed: false, globalFile, globalFileExists: false, envValue };
+	}
+}
+
+/**
+ * The effective policy alone, for callers that do not report a source.
+ * It delegates so the loader and the resolver can never disagree.
+ */
+export function loadDoubleEscCancelPolicy(options: LoadDoubleEscCancelOptions = {}): DoubleEscCancelPolicy {
+	return resolveDoubleEscCancelPolicy(options).policy;
+}
+
+/**
+ * Write the global policy file, creating the config home when needed.
+ * Used by both `/gentle:double-esc-cancel enable` and `... disable`.
+ */
+export function writeDoubleEscCancelPolicy(
+	policy: DoubleEscCancelPolicy,
+	options: { gentlePiConfigHome?: string } = {},
+): string {
+	const configHome = options.gentlePiConfigHome ?? gentlePiConfigHome();
+	const path = join(configHome, DOUBLE_ESC_CANCEL_FILE);
+	mkdirSync(configHome, { recursive: true });
+	writeFileSync(path, `${JSON.stringify({ schema: DOUBLE_ESC_CANCEL_SCHEMA, policy }, null, 2)}\n`);
+	return path;
+}

package/lib/inprocess-reviewer.ts

@@ -0,0 +1,297 @@
+// In-process reviewer completion (gentle-ai#4611; gentle-pi#311 P1).
+//
+// The relay child this module replaced ran a locked-down `pi --print` process
+// with extension discovery disabled, which dropped extension-registered
+// providers ("Model not found") and stripped env-provided API keys; its env
+// allowlist required per-provider manual configuration and Go roles had no
+// parity with it. This module is that transport's replacement for a single
+// reviewer completion: it resolves
+// the caller's "provider/id" selection through pi's live model registry,
+// authenticates through the registry's own resolver, and completes exactly
+// one frozen prompt as a single user message — no systemPrompt, no tools, no
+// session, no extension hooks.
+//
+// Every I/O seam is injected (`registry`, `complete`, `now`), so this module
+// runs under tests with no network and no pi process. gentle-pi#311 P2 wires
+// this into the lens relay (lib/review-host-relay.ts); P3 wires the provider
+// role vectors. This file stays a pure completion, never invoked from here.
+
+import type { Api, AssistantMessage, Context, Model, ProviderHeaders, SimpleStreamOptions, TextContent, ThinkingLevel } from "@earendil-works/pi-ai";
+import type { completeSimple } from "@earendil-works/pi-ai/compat";
+import { SAFE_MODEL_ID_PATTERN } from "./model-routing-authority.ts";
+
+// ---------------------------------------------------------------------------
+// Registry seam — a structural subset of pi's live ModelRegistry
+// (@earendil-works/pi-coding-agent core/model-registry.ts). Only `find` and
+// `getApiKeyAndHeaders` are needed here; the real registry's resolved auth
+// carries extra optional fields (`baseUrl`, `env`) that this narrower shape
+// simply ignores.
+// ---------------------------------------------------------------------------
+
+export interface InProcessReviewerRegistry {
+	find(provider: string, modelId: string): Model<Api> | undefined;
+	getApiKeyAndHeaders(model: Model<Api>): Promise<
+		| { readonly ok: true; readonly apiKey?: string; readonly headers?: ProviderHeaders }
+		| { readonly ok: false; readonly error: string }
+	>;
+}
+
+export const INPROCESS_REVIEWER_FAILURE = {
+	SELECTION_INVALID: "selection-invalid",
+	MODEL_NOT_FOUND: "model-not-found",
+	AUTH_UNAVAILABLE: "auth-unavailable",
+	THINKING_INVALID: "thinking-invalid",
+	TOOL_CALL_ATTEMPTED: "tool-call-attempted",
+	EMPTY_OUTPUT: "empty-output",
+	OUTPUT_TOO_LARGE: "output-too-large",
+	TIMED_OUT: "timed-out",
+	ABORTED: "aborted",
+	PROVIDER_FAILED: "provider-failed",
+} as const;
+export type InProcessReviewerFailureCode = (typeof INPROCESS_REVIEWER_FAILURE)[keyof typeof INPROCESS_REVIEWER_FAILURE];
+
+export interface InProcessReviewerRequest {
+	/** "provider/id" from models.json routing; already validated by SAFE_MODEL_ID_PATTERN upstream, re-validated here. */
+	readonly selection: string;
+	/** Routing thinking label: off | minimal | low | medium | high | xhigh | max. Omitted is treated as "off". */
+	readonly thinking?: string;
+	/** Frozen Go-materialized prompt bytes, submitted verbatim as the one user message. */
+	readonly prompt: Buffer;
+	readonly timeoutMs: number;
+	readonly signal?: AbortSignal;
+	/**
+	 * The live pi session id, threaded from the extension context. Pi's main
+	 * agent loop adds OpenCode attribution headers itself; this side-call must
+	 * carry them itself instead. Absent (or empty) means no attribution header,
+	 * never an invented one and never an error.
+	 */
+	readonly sessionId?: string;
+	/** e.g. "review-risk" — only used to name the routing config key in refusal messages. */
+	readonly routingKey: string;
+}
+
+export type InProcessReviewerOutcome =
+	| { readonly kind: "text"; readonly text: string; readonly reviewerModel: string }
+	| { readonly kind: "refused"; readonly code: InProcessReviewerFailureCode; readonly message: string; readonly evidence?: Record<string, unknown> };
+
+export interface InProcessReviewerDeps {
+	readonly registry: InProcessReviewerRegistry;
+	readonly complete: typeof completeSimple;
+	/** Test seam for the single user message's timestamp; defaults to Date.now. */
+	readonly now?: () => number;
+}
+
+// No existing bound covers the reviewer's completion text: the child this
+// module replaced returned its extracted text unbounded. 4 MiB matches this
+// repo's established convention for this class of bound (lib/session-changes.ts
+// MAX_SESSION_BYTES, lib/provider-contract-bundle.ts MAX_FILE_BYTES).
+export const INPROCESS_REVIEWER_OUTPUT_MAX_BYTES = 4 * 1024 * 1024;
+
+// pi-ai's `SimpleStreamOptions.reasoning` accepts every routing label except
+// "off" (`ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh" |
+// "max"`), and pi-ai itself clamps a level to what the selected model
+// supports through its `thinkingLevelMap`. The label is therefore forwarded
+// verbatim: the routing config owns the choice and the library owns the
+// per-provider mapping, so this module never second-guesses either.
+const THINKING_LABELS = new Set<ThinkingLevel>(["minimal", "low", "medium", "high", "xhigh", "max"]);
+const ERROR_EXCERPT_MAX_CHARS = 512;
+
+function parseSelection(selection: string): { provider: string; modelId: string } | undefined {
+	if (typeof selection !== "string" || selection.length === 0 || !SAFE_MODEL_ID_PATTERN.test(selection)) return undefined;
+	const separatorIndex = selection.indexOf("/");
+	if (separatorIndex <= 0 || separatorIndex === selection.length - 1) return undefined;
+	return { provider: selection.slice(0, separatorIndex), modelId: selection.slice(separatorIndex + 1) };
+}
+
+type ReasoningResolution = { readonly ok: true; readonly reasoning?: ThinkingLevel } | { readonly ok: false };
+
+/**
+ * "off" (or an omitted label) omits `reasoning` entirely; every other pi-ai
+ * level is forwarded verbatim; an unrecognized label is a typed refusal. A model with
+ * `reasoning === false` never receives the field, regardless of the label —
+ * checked last so an unknown label is still refused even for a non-reasoning
+ * model, instead of silently passing validation because it would be dropped
+ * anyway.
+ */
+function resolveReasoning(thinking: string | undefined, model: Model<Api>): ReasoningResolution {
+	if (thinking === undefined || thinking === "off") return { ok: true };
+	if (!THINKING_LABELS.has(thinking as ThinkingLevel)) return { ok: false };
+	return model.reasoning === false ? { ok: true } : { ok: true, reasoning: thinking as ThinkingLevel };
+}
+
+function sanitizeErrorExcerpt(error: unknown): string {
+	const raw = error instanceof Error ? error.message : String(error);
+	const collapsed = raw.replace(/\s+/g, " ").trim();
+	return collapsed.length <= ERROR_EXCERPT_MAX_CHARS ? collapsed : `${collapsed.slice(0, ERROR_EXCERPT_MAX_CHARS - 1)}…`;
+}
+
+function refuse(code: InProcessReviewerFailureCode, message: string, evidence?: Record<string, unknown>): InProcessReviewerOutcome {
+	return { kind: "refused", code, message, ...(evidence === undefined ? {} : { evidence }) };
+}
+
+function isTextContent(part: { type?: unknown }): part is TextContent {
+	return part.type === "text";
+}
+
+/**
+ * Mirrors pi's main-loop OpenCode attribution condition exactly
+ * (core/provider-attribution.js#getSessionHeaders): the model's provider is
+ * `opencode` or `opencode-go`, or its baseUrl host is `opencode.ai`. Returns
+ * the `{ x-opencode-session, x-opencode-client }` attribution pair, or
+ * undefined when the model is not OpenCode-routed or there is no live session
+ * id — a missing session id is never an error and never invents a header.
+ * The URL parse is guarded: an unparseable baseUrl follows the provider
+ * condition alone.
+ */
+export function openCodeSessionAttributionHeaders(model: Model<Api>, sessionId: string | undefined): ProviderHeaders | undefined {
+	const isOpenCode = model.provider === "opencode"
+		|| model.provider === "opencode-go"
+		|| (() => {
+			try {
+				return new URL(String(model.baseUrl ?? "")).hostname === "opencode.ai";
+			} catch {
+				return false;
+			}
+		})();
+	if (!isOpenCode || typeof sessionId !== "string" || sessionId.length === 0) return undefined;
+	return { "x-opencode-session": sessionId, "x-opencode-client": "pi" };
+}
+
+/**
+ * Runs one reviewer completion in-process: resolve the model, authenticate,
+ * map the routing thinking label, and complete exactly one frozen prompt as
+ * a single user message. Never retries, never falls back to another model,
+ * never reads process.env — every seam is injected through `deps`.
+ */
+export async function runInProcessReviewer(request: InProcessReviewerRequest, deps: InProcessReviewerDeps): Promise<InProcessReviewerOutcome> {
+	const parsed = parseSelection(request.selection);
+	if (parsed === undefined) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.SELECTION_INVALID,
+			`Invalid model selection ${JSON.stringify(request.selection)} for ${request.routingKey}; expected the "provider/id" shape.`,
+		);
+	}
+
+	const model = deps.registry.find(parsed.provider, parsed.modelId);
+	if (model === undefined) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.MODEL_NOT_FOUND,
+			`No model matches selection ${JSON.stringify(request.selection)} configured for ${request.routingKey}; assign ${request.routingKey} a model that the interactive pi's model list actually shows.`,
+		);
+	}
+
+	const auth = await deps.registry.getApiKeyAndHeaders(model);
+	// Negation narrowing (`!auth.ok`) does not eliminate the `ok: true` arm of
+	// this discriminated union under this project's `strict: false` tsconfig;
+	// an explicit `=== false` comparison narrows correctly in both directions.
+	if (auth.ok === false) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.AUTH_UNAVAILABLE,
+			`No credentials available for provider ${JSON.stringify(parsed.provider)} (used by ${request.routingKey}): ${auth.error}`,
+		);
+	}
+
+	const reasoning = resolveReasoning(request.thinking, model);
+	if (reasoning.ok === false) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.THINKING_INVALID,
+			`Unknown thinking level ${JSON.stringify(request.thinking)} for ${request.routingKey}; use one of off, minimal, low, medium, high, xhigh, max.`,
+		);
+	}
+
+	// Extension side-calls bypass pi's main agent loop, which is where OpenCode
+	// attribution headers are otherwise added, so this completion carries them
+	// itself — as a default beneath the registry's own auth headers, the same
+	// merge order pi's core uses for explicit header sources.
+	const attributionHeaders = openCodeSessionAttributionHeaders(model, request.sessionId);
+
+	// The caller's own signal (if any) and a floor timeout race together:
+	// whichever fires first aborts the completion. The catch branch below
+	// tells them apart by which underlying signal actually fired, never by
+	// inspecting the thrown error's shape, which providers are free to vary.
+	const timeoutSignal = AbortSignal.timeout(request.timeoutMs);
+	const combinedSignal = request.signal === undefined ? timeoutSignal : AbortSignal.any([request.signal, timeoutSignal]);
+
+	const context: Context = {
+		messages: [
+			{
+				role: "user",
+				content: [{ type: "text", text: request.prompt.toString("utf8") }],
+				timestamp: (deps.now ?? Date.now)(),
+			},
+		],
+	};
+	const options: SimpleStreamOptions = {
+		signal: combinedSignal,
+		timeoutMs: request.timeoutMs,
+		...(auth.apiKey === undefined ? {} : { apiKey: auth.apiKey }),
+		...(auth.headers === undefined && attributionHeaders === undefined ? {} : { headers: attributionHeaders === undefined ? auth.headers : { ...attributionHeaders, ...auth.headers } }),
+		...(reasoning.reasoning === undefined ? {} : { reasoning: reasoning.reasoning }),
+	};
+
+	// An abort is classified by which signal actually fired, never by the
+	// error's shape or the message's text, and the same classification serves
+	// both settlement paths: a provider may reject on abort, or — the pi-ai
+	// provider convention — resolve an AssistantMessage with `stopReason:
+	// "aborted"` carrying whatever text streamed before the cut. Either way a
+	// fired signal is a timeout or a caller abort, never empty or usable output.
+	const abortRefusal = (): InProcessReviewerOutcome | undefined => {
+		if (timeoutSignal.aborted) {
+			return refuse(INPROCESS_REVIEWER_FAILURE.TIMED_OUT, `Reviewer completion for ${request.routingKey} exceeded its ${request.timeoutMs}ms bound.`);
+		}
+		if (request.signal?.aborted === true) {
+			return refuse(INPROCESS_REVIEWER_FAILURE.ABORTED, `Reviewer completion for ${request.routingKey} was aborted by the caller.`);
+		}
+		return undefined;
+	};
+
+	let assistant: AssistantMessage;
+	try {
+		assistant = await deps.complete(model, context, options);
+	} catch (error) {
+		return abortRefusal() ?? refuse(INPROCESS_REVIEWER_FAILURE.PROVIDER_FAILED, `Reviewer completion failed for ${request.routingKey}: ${sanitizeErrorExcerpt(error)}`);
+	}
+
+	const resolvedAbort = abortRefusal();
+	if (resolvedAbort !== undefined) return resolvedAbort;
+	if (assistant.stopReason === "aborted") {
+		// No signal of ours fired, so the provider cut the completion on its
+		// own: that is a provider failure, and its partial text is not a review.
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.PROVIDER_FAILED,
+			`Reviewer completion failed for ${request.routingKey}: the provider reported an aborted completion (${assistant.errorMessage ?? "no provider message"}).`,
+		);
+	}
+
+	if (assistant.stopReason === "error") {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.PROVIDER_FAILED,
+			`Reviewer completion failed for ${request.routingKey}: ${assistant.errorMessage ?? "unknown provider error"}`,
+		);
+	}
+	if (assistant.content.some((part) => part.type === "toolCall")) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.TOOL_CALL_ATTEMPTED,
+			`Reviewer attempted a tool call for ${request.routingKey}; the in-process reviewer completion must answer in text only.`,
+		);
+	}
+
+	const text = assistant.content.filter(isTextContent).map((part) => part.text).join("");
+	if (text.length === 0) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.EMPTY_OUTPUT,
+			`Reviewer produced no text for ${request.routingKey} (stopReason: ${assistant.stopReason}).`,
+			{ stopReason: assistant.stopReason, ...(assistant.errorMessage === undefined ? {} : { errorMessage: assistant.errorMessage }) },
+		);
+	}
+
+	const textBytes = Buffer.byteLength(text, "utf8");
+	if (textBytes > INPROCESS_REVIEWER_OUTPUT_MAX_BYTES) {
+		return refuse(
+			INPROCESS_REVIEWER_FAILURE.OUTPUT_TOO_LARGE,
+			`Reviewer output for ${request.routingKey} exceeds the ${INPROCESS_REVIEWER_OUTPUT_MAX_BYTES}-byte bound (received ${textBytes} bytes).`,
+		);
+	}
+
+	return { kind: "text", text, reviewerModel: `${model.provider}/${model.id}` };
+}

package/lib/native-review-cli.ts

@@ -201,7 +201,7 @@ export interface NativeReviewModeRequest {
 // explicit `committedOnly` acknowledgement, exactly like Native START's
 // baseRef/committedOnly pairing, because both select a committed range
 // instead of the ambient working tree.
-export interface NativeReviewAssessRequest {
+export interface NativeReviewAssessRequest extends NativeUntrackedSelection {
 	cwd: string;
 	baseRef?: string;
 	committedOnly?: boolean;
@@ -705,7 +705,11 @@ function isNativeUntrackedPath(value: unknown): value is string {
 		&& value.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 
-function nativeUntrackedSelection(request: NativeUntrackedSelectionRequest): NativeUntrackedSelection {
+export function nativeUntrackedSelection(request: {
+	untrackedScope?: unknown;
+	expectedUntrackedInventory?: unknown;
+	intendedUntracked?: unknown;
+}): NativeUntrackedSelection {
 	const { untrackedScope, expectedUntrackedInventory, intendedUntracked } = request;
 	const declared = untrackedScope !== undefined || expectedUntrackedInventory !== undefined || intendedUntracked !== undefined;
 	if (!declared) return {};
@@ -716,16 +720,19 @@ function nativeUntrackedSelection(request: NativeUntrackedSelectionRequest): Nat
 	) {
 		throw new TypeError("Native untracked selection must declare one scope, one inventory digest, and unique repository-relative paths");
 	}
-	if (untrackedScope === NATIVE_UNTRACKED_SCOPE.EXCLUDE && (intendedUntracked?.length ?? 0) > 0) {
+	// The guard above establishes the array and element types for both typed
+	// native requests and untyped facade input.
+	const paths = intendedUntracked as readonly string[] | undefined;
+	if (untrackedScope === NATIVE_UNTRACKED_SCOPE.EXCLUDE && (paths?.length ?? 0) > 0) {
 		throw new TypeError("Native exclude untracked selection cannot include paths");
 	}
-	if (untrackedScope === NATIVE_UNTRACKED_SCOPE.SELECT && (intendedUntracked?.length ?? 0) === 0) {
+	if (untrackedScope === NATIVE_UNTRACKED_SCOPE.SELECT && (paths?.length ?? 0) === 0) {
 		throw new TypeError("Native select untracked selection requires at least one path");
 	}
 	return {
 		untrackedScope,
 		expectedUntrackedInventory,
-		intendedUntracked: intendedUntracked === undefined ? undefined : [...intendedUntracked],
+		intendedUntracked: paths === undefined ? undefined : [...paths],
 	};
 }
 
@@ -1004,6 +1011,27 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// remain dark because neither is proven to reach the negotiated START
 	// path Pi consumes.
 	"3.2.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v3.4.0 (gentle-pi never pinned the intervening v3.3.0 tag, so it gets no
+	// row here) added capabilities/v2.6 and status/v8-v9, and extended
+	// `review assess` with review_due/review_due_reason/next_transition
+	// (gentle-ai #4714 follow-up). Ground-truthed by diffing
+	// contracts/review-integration/v2 and contracts/review-provider-contract
+	// between the v3.2.1 and v3.4.0 tags in the gentle-ai source tree: the
+	// provider contract stays byte-identical at 1.2.0, and every
+	// review-integration/v2 change is an additive superset (new optional
+	// schema/fields) that decodeReviewStatusV3 and the capabilities
+	// negotiator already accept without touching the closed START/STATUS
+	// fields this row negotiates, so it repeats 3.2.1 exactly. riskEvidence
+	// and hint remain dark because neither is proven to reach the negotiated
+	// START path Pi consumes.
+	"3.4.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v3.5.0 repeats 3.4.0: the published provider contract bundle is
+	// byte-identical at 1.2.0, both binaries advertise capabilities/v2.6
+	// with only build-identity differences, and no review-integration schema
+	// changed. The v2 preflight failure identity fix does not change the
+	// closed START/STATUS fields this row negotiates. riskEvidence and hint
+	// remain dark; neither is proven to reach Pi's negotiated START path.
+	"3.5.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 {
@@ -1088,8 +1116,19 @@ function decodeSelectedLenses(value: unknown, riskLevel: string, lensesRequired:
 function enumString(value: unknown, allowed: readonly string[]): string { const parsed = stringValue(value); if (!allowed.includes(parsed)) throw new Error("unsupported enum"); return parsed; }
 const NATIVE_DIAGNOSTIC_TEXT_LIMIT = 4_096;
 
-function sanitizeNativeDiagnosticText(value: string, limit = NATIVE_DIAGNOSTIC_TEXT_LIMIT): string {
-	const normalized = value
+function sanitizeNativeDiagnosticText(value: string, limit = NATIVE_DIAGNOSTIC_TEXT_LIMIT, operation?: NativeReviewOperation): string {
+	// ASSESS diagnostics are projected into a public verification plan. Retain
+	// native guidance, not local paths or environment assignment values.
+	const input = operation === NATIVE_REVIEW_OPERATION.ASSESS
+		? value
+			.replace(/(?<![\w-])[a-z_][a-z0-9_]*=(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s]+)/gi, "[REDACTED ENV]")
+			.replace(/--(?:password|token|secret|authorization|cookie|private[_-]key|access[_-]token|[a-z0-9_-]+[_-]token|api[_-]?key)[ \t]+(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s]+)/gi, "[REDACTED CREDENTIAL]")
+			// Quoted paths have a clear boundary. For an unquoted path, the
+			// remaining line is ambiguous (spaces may belong to the filename).
+			// Redact that suffix rather than leak trailing path components.
+			.replace(/"(?:[A-Za-z]:[\\/]|\/)[^"\r\n]*"|'(?:[A-Za-z]:[\\/]|\/)[^'\r\n]*'|(?:[A-Za-z]:[\\/]|\/)[^\r\n]*/g, "[REDACTED PATH]")
+		: value;
+	const normalized = input
 		.replace(/\x1b](?:[^\x07\x1b]|\x1b(?!\\))*?(?:\x07|\x1b\\)/g, "[REDACTED CONTROL]")
 		.replace(/\x1b[PX^_][\s\S]*?\x1b\\/g, "[REDACTED CONTROL]")
 		.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "[REDACTED CONTROL]")
@@ -1123,7 +1162,7 @@ export function sanitizeForeignNativeReviewDiagnostics(value: unknown): NativeRe
 			timed_out: booleanValue(raw.timed_out),
 			output_limit_exceeded: booleanValue(raw.output_limit_exceeded),
 			...(maxBufferBytes === undefined ? {} : { max_buffer_bytes: maxBufferBytes, configuration_hint: configurationHint! }),
-			...(raw.stderr === undefined ? {} : { stderr: sanitizeNativeDiagnosticText(stringValue(raw.stderr)) }),
+			...(raw.stderr === undefined ? {} : { stderr: sanitizeNativeDiagnosticText(stringValue(raw.stderr), NATIVE_DIAGNOSTIC_TEXT_LIMIT, operation) }),
 		};
 	} catch { return undefined; }
 }
@@ -1140,7 +1179,7 @@ function nativeProcessDiagnostics(operation: NativeReviewOperation, code: Native
 		...(code === NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT && maxBufferBytes !== undefined
 			? { max_buffer_bytes: maxBufferBytes, configuration_hint: NATIVE_REVIEW_MAX_BUFFER_CONFIGURATION_HINT }
 			: {}),
-		...(result?.stderr.trim() ? { stderr: sanitizeNativeDiagnosticText(result.stderr) } : {}),
+		...(result?.stderr.trim() ? { stderr: sanitizeNativeDiagnosticText(result.stderr, NATIVE_DIAGNOSTIC_TEXT_LIMIT, operation) } : {}),
 	};
 }
 
@@ -2521,6 +2560,7 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 	// rejects -- callers (the `gentle_review` tool's `assess` operation) fail
 	// closed to `high`.
 	async assess(request: NativeReviewAssessRequest): Promise<ReviewAssessmentV1> {
+		const selection = nativeUntrackedSelection(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");
@@ -2528,7 +2568,7 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 		const execution = await this.invoke(
 			NATIVE_REVIEW_OPERATION.ASSESS,
 			cwd,
-			["review", "assess", "--cwd", cwd, ...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef, "--committed-only"]), "--json"],
+			["review", "assess", "--cwd", cwd, ...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef, "--committed-only"]), ...nativeUntrackedSelectionArguments(selection), "--json"],
 			false,
 			request.signal,
 			this.executablePath(NATIVE_REVIEW_OPERATION.ASSESS, false),

package/lib/odd-runtime-delegation-gate.ts

@@ -0,0 +1,88 @@
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { resolveSessionWorktree } from "./session-worktree-registry.ts";
+
+export interface OddDelegationRefusal {
+	block: true;
+	reason: string;
+}
+
+interface SessionState {
+	primary: boolean;
+	childDepth: number;
+	firstSuccessfulPath?: string;
+}
+
+function canonicalTarget(path: string): string {
+	let candidate = path;
+	const missing: string[] = [];
+	while (true) {
+		try { return resolve(realpathSync(candidate), ...missing); }
+		catch {
+			const parent = dirname(candidate);
+			if (parent === candidate) return path;
+			missing.unshift(basename(candidate));
+			candidate = parent;
+		}
+	}
+}
+
+function sessionPath(toolName: string, input: unknown, cwd: string): string | undefined {
+	if ((toolName !== "edit" && toolName !== "write") || !input || typeof input !== "object") return undefined;
+	const path = (input as { path?: unknown }).path;
+	if (typeof path !== "string" || path.trim().length === 0) return undefined;
+	const root = resolveSessionWorktree(cwd, cwd)?.root;
+	if (!root) return undefined;
+	const spelling = path.replace(/^@/, "");
+	const canonicalCwd = realpathSync(cwd);
+	const lexicalTarget = isAbsolute(spelling)
+		? resolve(spelling)
+		: resolve(canonicalCwd, spelling);
+	const target = canonicalTarget(lexicalTarget);
+	const repositoryPath = relative(root, target);
+	if (repositoryPath === "" || repositoryPath === ".." || repositoryPath.startsWith(`..${sep}`) || isAbsolute(repositoryPath)) return undefined;
+	const canonical = repositoryPath.split(sep).join("/");
+	return canonical === "odd/tasks" || canonical.startsWith("odd/tasks/") ? undefined : canonical;
+}
+
+export class OddRuntimeDelegationGate {
+	private readonly sessions = new Map<string, SessionState>();
+
+	start(sessionId: string, primary: boolean): void {
+		const state = this.sessions.get(sessionId);
+		if (primary) this.sessions.set(sessionId, { primary: true, childDepth: 0 });
+		else if (state?.primary) state.childDepth += 1;
+		else this.sessions.set(sessionId, { primary: false, childDepth: 1 });
+	}
+
+	endChild(sessionId: string): void {
+		const state = this.sessions.get(sessionId);
+		if (state && state.childDepth > 0) state.childDepth -= 1;
+	}
+
+	beforeTool(
+		sessionId: string,
+		toolName: string,
+		input: unknown,
+		cwd: string,
+		availableTools: readonly string[],
+	): OddDelegationRefusal | undefined {
+		const state = this.sessions.get(sessionId);
+		if (!state?.primary || state.childDepth > 0) return undefined;
+		const path = sessionPath(toolName, input, cwd);
+		if (!path || !state.firstSuccessfulPath || path === state.firstSuccessfulPath) return undefined;
+		return {
+			block: true,
+			reason: availableTools.includes("subagent_run")
+				? `ODD multi-file write refused before mutation: direct edits already changed ${state.firstSuccessfulPath}. Delegate this additional file through subagent_run, preferring gentle-ai-worker and then worker.`
+				: "ODD multi-file write refused before mutation: direct edits already changed another file, but subagent_run is not callable. Stop and report that no delegation mechanism is callable.",
+		};
+	}
+
+	recordSuccess(sessionId: string, toolName: string, input: unknown, cwd: string): void {
+		const state = this.sessions.get(sessionId);
+		if (!state?.primary || state.childDepth > 0 || state.firstSuccessfulPath) return;
+		const path = sessionPath(toolName, input, cwd);
+		if (path) state.firstSuccessfulPath = path;
+	}
+}