gentle-pi 3.3.0 → 3.5.0

package/extensions/ask-user-question.ts

@@ -0,0 +1,338 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
+import { type QuestionData, type QuestionParams, QuestionParamsSchema } from "../lib/questionnaire/schema.ts";
+import {
+	QuestionnaireView,
+	type AnswerRow,
+	type QuestionnaireResult,
+} from "../lib/questionnaire/questionnaire-view.ts";
+import { validateQuestionnaire, type QuestionnaireError } from "../lib/questionnaire/validate.ts";
+import { isInteractiveRpcHost } from "../lib/rpc-host.ts";
+
+const QUESTION_TOOL_NAME = "ask_user_question";
+const ASK_USER_QUESTION_BLOCKED_EVENT = "gentle-pi:ask-user-question:blocked";
+
+/** Maximum characters kept from a renderCall question summary. */
+const CALL_SUMMARY_LIMIT = 120;
+
+/** Structured details returned by the tool for UI rendering and callers. */
+interface QuestionnaireDetails {
+	cancelled?: boolean;
+	answers?: AnswerRow[];
+	error?: QuestionnaireError;
+	errorKind?: string;
+}
+
+/** Content plus details returned by `execute`. */
+interface QuestionnaireToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: QuestionnaireDetails;
+}
+
+/**
+ * Invalid-parameter result. `AgentToolResult` has no `isError` field, so this
+ * follows the repository convention for rejected tool input: a leading error
+ * sentence in `content` plus a machine-readable payload in `details`
+ * (`extensions/gentle-todo.ts` returns `Error: ...` with `details.error`).
+ */
+function invalidQuestionnaireResult(error: QuestionnaireError): QuestionnaireToolResult {
+	return {
+		content: [{ type: "text", text: `Invalid questionnaire: ${error.message}` }],
+		details: { error, errorKind: error.code },
+	};
+}
+
+/** Non-interactive result; parity with ask_user_choice's TUI-only guard. */
+function unavailableResult(): QuestionnaireToolResult {
+	return {
+		content: [{ type: "text", text: "Error: ask_user_question is unavailable outside the interactive TUI" }],
+		details: { errorKind: "unavailable_outside_tui" },
+	};
+}
+
+/** Same cancellation shape the TUI questionnaire returns for its Escape key. */
+function cancelledResult(): QuestionnaireToolResult {
+	return {
+		content: [{ type: "text", text: "User cancelled the questionnaire" }],
+		details: { cancelled: true },
+	};
+}
+
+/** Label for the trailing "finish this question" entry in a multiSelect round. */
+const MULTI_SELECT_DONE_LABEL = "Done";
+
+/** One toggle round's select prompt: `[x] label` / `[ ] label` plus Done. */
+function multiSelectRoundOptions(question: QuestionData, toggled: readonly boolean[]): string[] {
+	return [
+		...question.options.map((choiceOption, index) => `${toggled[index] ? "[x]" : "[ ]"} ${choiceOption.label}`),
+		MULTI_SELECT_DONE_LABEL,
+	];
+}
+
+/**
+ * Floor for the toggle-round safety cap so a misbehaving or chatty host
+ * cannot spin this loop forever, and every question -- however few options
+ * it has -- still gets room to toggle, untoggle, and retoggle before Done.
+ */
+const MULTI_SELECT_ROUND_CAP_FLOOR = 32;
+
+/**
+ * Hard bound on toggle rounds for one question: every option must be
+ * toggleable at least once, plus one round for the explicit Done and one
+ * spare round for a single correction (an un-toggle), so the cap scales
+ * with the option count (`options.length + 2`), floored at
+ * `MULTI_SELECT_ROUND_CAP_FLOOR` for small questions.
+ */
+function multiSelectRoundCap(optionsLength: number): number {
+	return Math.max(MULTI_SELECT_ROUND_CAP_FLOOR, optionsLength + 2);
+}
+
+/** Committed multiSelect answer from the current toggle state (explicit Done, or every option toggled on). */
+function finishMultiSelect(question: QuestionData, toggled: readonly boolean[]): AnswerRow {
+	return {
+		questionIndex: -1, // overwritten by the caller with the question's position
+		question: question.question,
+		kind: "multi",
+		answer: null,
+		selected: question.options.filter((_choiceOption, index) => toggled[index]).map((choiceOption) => choiceOption.label),
+	};
+}
+
+/**
+ * Resolves one multiSelect question by looping `ctx.ui.select` over toggle
+ * rounds, bounded by `multiSelectRoundCap`. Returns `undefined` on
+ * cancellation, when the cap is hit without an explicit Done, and when the
+ * host returns an answer that matches none of the current round's options:
+ * a partial toggle state must never commit silently in either case.
+ */
+export async function askMultiSelect(
+	ctx: Pick<ExtensionContext, "ui">,
+	question: QuestionData,
+): Promise<AnswerRow | undefined> {
+	const toggled = question.options.map(() => false);
+	const roundCap = multiSelectRoundCap(question.options.length);
+	for (let round = 0; round < roundCap; round++) {
+		const roundOptions = multiSelectRoundOptions(question, toggled);
+		const picked = await ctx.ui.select(`${question.header}: ${question.question}`, roundOptions);
+		if (picked === undefined) return undefined;
+		const pickedIndex = roundOptions.indexOf(picked);
+		if (pickedIndex === question.options.length) return finishMultiSelect(question, toggled); // explicit Done
+		if (pickedIndex === -1) return undefined; // unrecognised answer: never commit a partial state
+		toggled[pickedIndex] = !toggled[pickedIndex];
+		if (toggled.every(Boolean)) return finishMultiSelect(question, toggled);
+	}
+	// The safety cap was spent without an explicit Done: refuse to commit a
+	// partial selection silently and cancel instead.
+	return undefined;
+}
+
+/** Resolves one single-select question through `ctx.ui.select`. Returns `undefined` on cancellation. */
+async function askSingleSelect(
+	ctx: Pick<ExtensionContext, "ui">,
+	question: QuestionData,
+): Promise<AnswerRow | undefined> {
+	const labels = question.options.map((choiceOption) => choiceOption.label);
+	const picked = await ctx.ui.select(`${question.header}: ${question.question}`, labels);
+	if (picked === undefined) return undefined;
+	const chosen = question.options.find((choiceOption) => choiceOption.label === picked);
+	return {
+		questionIndex: -1, // overwritten by the caller with the question's position
+		question: question.question,
+		kind: "option",
+		answer: picked,
+		...(chosen?.preview !== undefined ? { preview: chosen.preview } : {}),
+	};
+}
+
+/**
+ * Interactive-RPC-host fallback for the TUI questionnaire: one
+ * `ctx.ui.select` dialog per question (looped for multiSelect), keeping the
+ * exact TUI result shapes. A cancel on any question cancels the whole
+ * questionnaire, matching the TUI Escape key. There is no schema-declared
+ * free-text option (`lib/questionnaire/schema.ts` has none), so the
+ * always-available "Type something." row has no RPC-dialog equivalent here.
+ */
+async function askThroughDialogs(
+	ctx: Pick<ExtensionContext, "ui">,
+	params: QuestionParams,
+): Promise<QuestionnaireToolResult> {
+	const answers: AnswerRow[] = [];
+	for (let questionIndex = 0; questionIndex < params.questions.length; questionIndex++) {
+		const question = params.questions[questionIndex]!;
+		const answer = question.multiSelect
+			? await askMultiSelect(ctx, question)
+			: await askSingleSelect(ctx, question);
+		if (answer === undefined) return cancelledResult();
+		answers.push({ ...answer, questionIndex });
+	}
+	return { content: [{ type: "text", text: answersText(answers) }], details: { answers } };
+}
+
+/**
+ * Human-readable body for one answer. A custom answer on a multiSelect
+ * question keeps the toggled options, so the text must name them explicitly:
+ * the free-text value alone would silently drop the user's selections. Plain
+ * custom answers (no selections) stay concise.
+ */
+function answerBody(answer: AnswerRow): string {
+	if (answer.kind === "multi") return `selected: ${(answer.selected ?? []).join(", ")}`;
+	if (answer.kind === "custom") {
+		const body = `(custom) ${answer.answer ?? ""}`;
+		const selected = answer.selected ?? [];
+		return selected.length > 0 ? `${body} — selected: ${selected.join(", ")}` : body;
+	}
+	return answer.answer ?? "";
+}
+
+/**
+ * Compact LLM-facing transcript of the committed answers. Each row keeps the
+ * original one-based question index so a partially answered questionnaire
+ * (the last question committed early) still reads in order.
+ */
+function answersText(answers: AnswerRow[]): string {
+	if (answers.length === 0) return "The user answered the questionnaire.";
+	const lines: string[] = [];
+	for (const answer of answers) {
+		const prefix = `${answer.questionIndex + 1}. ${answer.question}`;
+		lines.push(`${prefix} — ${answerBody(answer)}`);
+		if (answer.preview !== undefined) lines.push(`   selected preview: ${answer.preview}`);
+	}
+	return lines.join("\n");
+}
+
+/** Single-line summary of one question for the collapsed tool call row. */
+function callSummary(question: unknown, index: number): string {
+	const source = typeof question === "object" && question !== null ? question as { header?: unknown; options?: unknown } : {};
+	const header = typeof source.header === "string" ? source.header : "";
+	const labels = Array.isArray(source.options)
+		? source.options
+			.map((option) => (typeof option === "object" && option !== null && typeof (option as { label?: unknown }).label === "string"
+				? (option as { label: string }).label
+				: ""))
+			.filter((label) => label.length > 0)
+		: [];
+	const labelsPart = labels.length > 0 ? ` (${labels.join(", ")})` : "";
+	return `${index + 1}. ${header}${labelsPart}`;
+}
+
+function truncate(text: string, limit: number): string {
+	return text.length <= limit ? text : `${text.slice(0, Math.max(0, limit - 1))}…`;
+}
+
+/**
+ * Register the first-party questionnaire tool.
+ *
+ * Name-collision semantics (live-verified against the installed Pi runtime):
+ * - Tool names are exclusive across extensions. Pi has no precedence, override,
+ *   or silent shadowing: loading two extensions that register the same tool
+ *   name fails the whole load with a hard error
+ *   (`Tool "ask_user_question" conflicts with <other extension>`; the runtime
+ *   exits non-zero). The name is either free or fatal, full stop.
+ * - `registerTool` writes into the calling extension's own tool map keyed by
+ *   name, so re-registering inside one extension overwrites that entry
+ *   (`loader.js:240`). That same-name write is the only one Pi tolerates.
+ * - This first-party tool ships as THE `ask_user_question` provider. A competing
+ *   provider such as the third-party `@juicesharp/rpiv-ask-user-question`
+ *   package fails the load by design and must be removed from the user's Pi
+ *   settings; that deletion is the documented migration path, not a runtime
+ *   precedence choice.
+ */
+export default function askUserQuestion(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: QUESTION_TOOL_NAME,
+		renderShell: "self",
+		label: "Ask User Question",
+		description: "Ask one to four structured questions in a single call, each with two to four ordered options, and read the user's answers back in one result.",
+		promptGuidelines: [
+			"Use ask_user_question to collect decisions in one batch: ask one to four questions at a time, each with two to four options.",
+			"Keep each header a short chip of at most 16 characters and each option label at most 60 characters.",
+			"Add a preview to an option when the user needs to compare rich detail side-by-side with the options.",
+			"Set multiSelect when the choices are not mutually exclusive.",
+			"The free-text \"Type something.\" row is always available and is also how the user bails out into a normal conversation; never rely on it as a hidden escape hatch.",
+			"Never use this tool for decisions that must not be delegated to the user.",
+		],
+		parameters: QuestionParamsSchema,
+		executionMode: "sequential",
+		async execute(
+			_toolCallId: string,
+			params: QuestionParams,
+			_signal: AbortSignal | undefined,
+			_onUpdate: undefined,
+			ctx,
+		): Promise<QuestionnaireToolResult> {
+			const error = validateQuestionnaire(params);
+			if (error) return invalidQuestionnaireResult(error);
+			if (ctx.mode !== "tui") {
+				if (!isInteractiveRpcHost(ctx.mode, process.env)) return unavailableResult();
+				try {
+					pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: true });
+					return await askThroughDialogs(ctx, params);
+				}
+				finally {
+					pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: false });
+				}
+			}
+
+			let selection: QuestionnaireResult | undefined;
+			try {
+				pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: true });
+				selection = await ctx.ui.custom<QuestionnaireResult>((tui, theme, keybindings, done) => {
+					const view = new QuestionnaireView({
+						questions: params.questions,
+						theme,
+						keybindings,
+						onComplete: (result) => done(result),
+					});
+					// Native dock swap, never an overlay: the transcript stays scrollable
+					// while the questionnaire owns focus. No `overlay` option is passed.
+					const container = createNativeFullscreenInteraction({
+						keyboardTarget: view,
+						requestRender: () => tui.requestRender(),
+					});
+					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+					container.addChild(view);
+					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+					return container;
+				});
+			}
+			finally {
+				pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: false });
+			}
+
+			if (selection === undefined || selection.cancelled) {
+				return {
+					content: [{ type: "text", text: "User cancelled the questionnaire" }],
+					details: { cancelled: true },
+				};
+			}
+			return {
+				content: [{ type: "text", text: answersText(selection.answers) }],
+				details: { answers: selection.answers },
+			};
+		},
+		renderCall(args: QuestionParams, theme) {
+			const questions = Array.isArray(args.questions) ? args.questions : [];
+			const summary = truncate(questions.map((question, index) => callSummary(question, index)).join(" "), CALL_SUMMARY_LIMIT);
+			return new Text(
+				theme.fg("toolTitle", theme.bold("ask_user_question ")) +
+				theme.fg("muted", summary),
+				0,
+				0,
+			);
+		},
+		renderResult(result, _options, theme) {
+			const details = result.details as QuestionnaireDetails | undefined;
+			if (details?.cancelled === true) return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			const answers = Array.isArray(details?.answers) ? details.answers : [];
+			if (answers.length === 0) return new Text(theme.fg("warning", "No answers"), 0, 0);
+			const lines = answers.map((answer) => {
+				if (answer.kind === "multi") return theme.fg("success", `✓ ${answer.question} — ${(answer.selected ?? []).join(", ")}`);
+				if (answer.kind === "custom") return theme.fg("success", `✓ ${answer.question} — ${answerBody(answer)}`);
+				return theme.fg("success", `✓ ${answer.question} — ${answer.answer ?? ""}`);
+			});
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	});
+}

package/extensions/gentle-agents.ts

@@ -17,6 +17,7 @@ import { invalidateSidebar } from "../lib/shell-sidebar-layout.ts";
 import { createCompletionQueue } from "../lib/agents-completion-delivery.ts";
 import { AGENT_MODE, discoverAgents, parseAgentDefinition, loadAgentsConfig, resolveAgentProfile, withPinnedModelProfiles, type AgentDefinition, type AgentMode } from "../lib/agents-config.ts";
 import { resolveBackgroundSubagentsPolicy } from "../lib/background-subagents-policy.ts";
+import { installBackgroundCacheWarming } from "../lib/background-cache-warming.ts";
 import { isFinished, TASK_EVENT, TASK_STATUS, TaskStore, type AskRequest, type TaskRecord } from "../lib/agents-protocol.ts";
 import { AgentRunner, piCommand, abortReasonText, plannedCommands, type RemediationPlan, type RemediationScope, REMEDIATION_PLAN_ENV, parseRemediationPlan, type AskAnswer, type RunnerDeps, type SddChangeSelection, type TaskRequest } from "../lib/agents-runner.ts";
 import { ChildMessenger, type IpcEndpoint } from "../lib/agents-messaging.ts";
@@ -27,6 +28,8 @@ import { historyDir, loadHistory, loadStoredTask, pruneHistory, saveTask } from
 import { sessionToMarkdown } from "../lib/agents-transcript.ts";
 import { AgentsView } from "../lib/agents-view.ts";
 import { PresencePublisher } from "../lib/orchestrator-presence.ts";
+import { createRpcActivityPublisher, type RpcActivityPublisher } from "../lib/agents-rpc-publisher.ts";
+import { isInteractiveRpcHost } from "../lib/rpc-host.ts";
 import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 import { AGENTS_GLYPH, renderAgentsCard, widgetExpiryMs, widgetRows } from "../lib/agents-widget.ts";
 import { CARD_TONE, renderCard } from "../lib/shell-card.ts";
@@ -475,6 +478,12 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 	let sidebarTui: TUI | undefined;
 	let sessions: ExtensionContext["sessionManager"] | undefined;
 	let presence: PresencePublisher | undefined;
+	let rpcActivityPublisher: RpcActivityPublisher | undefined;
+	// Messages already surfaced to the user this session through the RPC
+	// activity publisher's `onError`, so a recurring push failure (the
+	// coalescing window retries every burst) notifies at most once per
+	// session instead of flooding the UI. Reset on every `session_start`.
+	let notifiedRpcActivityErrors: Set<string> | undefined;
 	const overlays = new Set<AgentsView>();
 	const publishActivity = () => {
 		if (!sessions) return;
@@ -529,6 +538,12 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 	// started before /new or /resume stays in the store and comes back with
 	// its session. Before the first session_start there is nothing to scope by.
 	const activeSessionId = (): string | undefined => (sessions === undefined ? undefined : sessions.getSessionId() ?? "");
+	// Pi 0.86.1 adds this event; the package's pinned 0.85.1 types predate it.
+	installBackgroundCacheWarming(pi as unknown as Parameters<typeof installBackgroundCacheWarming>[0], () => ({
+		sessionId: activeSessionId(),
+		ownedTaskIds,
+		tasks: store.list(activeSessionId()),
+	}));
 	const visibleTasks = (): TaskRecord[] => store.list(activeSessionId());
 	type SessionTransport = { generation: number; sessionId: string; sessionManager: ExtensionContext["sessionManager"]; client: SessionTransportClient; listener: SessionTransportListener; registry: SessionTransportRegistry; close(): Promise<void> };
 	let transportGeneration = 0;
@@ -1168,7 +1183,7 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 		if (observe) metricTasks.set(task.id, metrics);
 		ownedTaskIds.add(task.id);
 		store.subscribe(task.id, () => { publishActivity(); requestRender(); });
-		if (request.mode === AGENT_MODE.BACKGROUND) return text(`Started ${task.agent} in the background as task ${task.id}. Use subagent_status or subagent_result with that id.`, taskDetails(task));
+		if (request.mode === AGENT_MODE.BACKGROUND) return text(`Started ${task.agent} in the background as task ${task.id}. Retain that id; completion is pushed automatically. Never sleep or periodically poll subagent_status/subagent_result for completion or cache maintenance. Inspect status only at a real orchestration decision boundary; never relaunch equivalent queued/running work.`, taskDetails(task));
 		// A tool call aborted by the host (a human interrupting the turn, a timeout)
 		// would otherwise leave the child running and end the call with no result and
 		// no recorded reason. Cancel through the runner so the lifecycle runs and the
@@ -1443,12 +1458,37 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 			publishActivity();
 		} catch { presence = undefined; }
 		void startSessionTransport(ctx);
+		// The desktop app's own pi process: publish live subagent state through
+		// setWidget's RPC-mode string[] path. Plain headless RPC (no variable) and
+		// TUI are untouched -- the TUI card above the editor is showWidget's own
+		// factory push, ignored by pi's RPC transport since it is not an array.
+		rpcActivityPublisher?.stop();
+		rpcActivityPublisher = undefined;
+		notifiedRpcActivityErrors = new Set();
+		if (ctx.hasUI && isInteractiveRpcHost(ctx.mode, deps.env)) {
+			rpcActivityPublisher = createRpcActivityPublisher({
+				store,
+				ui: { setWidget: (key, lines) => ctx.ui.setWidget(key, lines) },
+				now: deps.now,
+				schedule: deps.schedule,
+				parentSessionId: activeSessionId(),
+				onError: (error) => {
+					const message = `Gentle Agents activity push failed: ${error instanceof Error ? error.message : String(error)}`;
+					if (notifiedRpcActivityErrors?.has(message)) return;
+					notifiedRpcActivityErrors?.add(message);
+					ctx.ui.notify(message, "warning");
+				},
+			});
+			rpcActivityPublisher.start();
+		}
 	});
 	pi.on("session_shutdown", async () => {
 		completions.dropAll();
 		activeAgentRuns = 0;
 		presence?.dispose();
 		presence = undefined;
+		rpcActivityPublisher?.stop();
+		rpcActivityPublisher = undefined;
 		cancelClock?.();
 		for (const view of overlays) { view.handleInput("q"); view.dispose(); }
 		overlays.clear();

package/extensions/gentle-ai.ts

@@ -199,6 +199,7 @@ import {
 	nativeReviewRecoverAuthorization,
 	normalizeNativeReviewCwd,
 	NativeReviewCliError,
+	nativeUntrackedSelection,
 	NativeReviewConsentBindingError,
 	NativeReviewConsentRequiredError,
 	NativeReviewIntegrationError,
@@ -1023,18 +1024,26 @@ async function resolveReviewAssessmentPlan(
 
 	let assessment: ReviewAssessmentV1 | undefined;
 	let unassessableDetail: string | undefined;
+	let unassessableCode = "native-assess-unavailable";
 	if (nativeReviewCli?.assess === undefined) {
 		unassessableDetail = "native review assess is unavailable: the installed gentle-ai binary does not expose the assess command.";
 	} else {
 		try {
 			const request: NativeReviewAssessRequest = {
 				cwd,
+				...nativeUntrackedSelection(input),
 				...(input.baseRef === undefined ? {} : { baseRef: input.baseRef, committedOnly: true as const }),
 				...(signal === undefined ? {} : { signal }),
 			};
 			assessment = await nativeReviewCli.assess(request);
 		} catch (error) {
-			unassessableDetail = `native review assess failed: ${error instanceof Error ? error.message : String(error)}`;
+			const nativeError = asNativeReviewCliError(error);
+			unassessableCode = nativeError?.code ?? unassessableCode;
+			// Only the sanitized process surface may supply native evidence.
+			// Arbitrary thrown messages can contain argv or environment values.
+			unassessableDetail = nativeError?.diagnostics.stderr
+				? `native review assess failed: ${nativeError.diagnostics.stderr}`
+				: "native review assess failed; no sanitized stderr diagnostic is available.";
 		}
 	}
 
@@ -1050,7 +1059,7 @@ async function resolveReviewAssessmentPlan(
 	return {
 		schema: "gentle-pi.review-assessment-plan/v1",
 		risk,
-		reasons: assessment?.reasons ?? (unassessableDetail === undefined ? [] : [{ code: "native-assess-unavailable", path: "", detail: unassessableDetail }]),
+		reasons: assessment?.reasons ?? (unassessableDetail === undefined ? [] : [{ code: unassessableCode, path: "", detail: unassessableDetail }]),
 		changedPaths: assessment?.changedPaths ?? 0,
 		changedLines: assessment?.changedLines ?? 0,
 		candidate: assessment === undefined ? null : { kind: assessment.candidate.kind, baseRef: assessment.candidate.baseRef },
@@ -4826,7 +4835,7 @@ interface ReviewScopeParameters {
 // as `gentle_review` operation `assess` (not a dedicated tool), taking its
 // optional fields through the controller's existing generic `input` JSON
 // string, exactly like START's `{"mode":...,"baseRef":...}`.
-interface ReviewAssessInput {
+interface ReviewAssessInput extends Pick<NativeReviewAssessRequest, "untrackedScope" | "expectedUntrackedInventory" | "intendedUntracked"> {
 	baseRef?: string;
 	committedOnly?: boolean;
 	writerModelId?: string;
@@ -4845,7 +4854,7 @@ function isNativeReviewOutcome(value: unknown): value is NativeReviewOutcome {
 function parseReviewAssessInput(operation: ReviewControllerOperation, raw: string | undefined): ReviewAssessInput {
 	if (raw === undefined) return {};
 	const value = parseControllerJson(raw, operation);
-	const allowed = new Set(["baseRef", "committedOnly", "writerModelId", "writerEffort", "nativeReviewOutcome"]);
+	const allowed = new Set(["baseRef", "committedOnly", "writerModelId", "writerEffort", "nativeReviewOutcome", "untrackedScope", "expectedUntrackedInventory", "intendedUntracked"]);
 	const unexpected = Object.keys(value).find((key) => !allowed.has(key));
 	if (unexpected !== undefined) throw new Error(`Review controller ${operation} input does not accept ${unexpected}`);
 	const { baseRef, committedOnly, writerModelId, writerEffort, nativeReviewOutcome } = value;
@@ -4859,6 +4868,7 @@ function parseReviewAssessInput(operation: ReviewControllerOperation, raw: strin
 	return {
 		...(baseRef === undefined ? {} : { baseRef: baseRef as string }),
 		...(committedOnly === undefined ? {} : { committedOnly: committedOnly as boolean }),
+		...nativeUntrackedSelection(value),
 		...(writerModelId === undefined ? {} : { writerModelId: writerModelId as string }),
 		...(writerEffort === undefined ? {} : { writerEffort: writerEffort as string }),
 		...(nativeReviewOutcome === undefined ? {} : { nativeReviewOutcome: nativeReviewOutcome as NativeReviewOutcome }),
@@ -6754,6 +6764,11 @@ async function executeReviewHostRelayCapture(
 	route: RetainedNativeCaptureRoute | undefined,
 	signal?: AbortSignal,
 	modelRegistry?: InProcessReviewerRegistry,
+	// The caller's live session id: forwarded into the relay request so an
+	// OpenCode-routed reviewer completion carries its x-opencode-session
+	// attribution header. Appended last so every existing positional call site
+	// keeps compiling unchanged.
+	reviewerSessionId?: string,
 ): Promise<Record<string, unknown>> {
 	try {
 		if (slot.submission === undefined) {
@@ -6777,6 +6792,7 @@ async function executeReviewHostRelayCapture(
 				submission: slot.submission,
 				...launch,
 				...(modelRegistry === undefined ? {} : { reviewerRegistry: modelRegistry }),
+				...(reviewerSessionId === undefined ? {} : { reviewerSessionId }),
 				...(signal === undefined ? {} : { signal }),
 			};
 		})());
@@ -7379,6 +7395,11 @@ async function executeReviewCaptureOperation(
 	// inserted) so every existing positional call site — none of which pass an
 	// eighth argument — keeps compiling unchanged.
 	modelRegistry?: InProcessReviewerRegistry,
+	// The caller's live session id, threaded into every relay request this
+	// capture launches so an OpenCode-routed reviewer model carries its
+	// x-opencode-session attribution header. Appended last for the same
+	// positional-call-site reason as modelRegistry above.
+	reviewerSessionId?: string,
 ): Promise<Record<string, unknown>> {
 	const parameters = parseReviewCaptureParameters(parametersValue);
 	if (nativeReviewCli === null || nativeReviewCli.targetStatus === undefined) {
@@ -7438,7 +7459,7 @@ async function executeReviewCaptureOperation(
 				mutation_outcome: "none",
 			};
 		}
-		return withCorrectionTarget(await executeReviewHostRelayCapture(hostRelaySlots[0]!, nativeReviewCli, cwd, selected.binding, retainedUntrackedSelections, route, signal, modelRegistry));
+		return withCorrectionTarget(await executeReviewHostRelayCapture(hostRelaySlots[0]!, nativeReviewCli, cwd, selected.binding, retainedUntrackedSelections, route, signal, modelRegistry, reviewerSessionId));
 	}
 
 	// gentle-pi#311 P3: gentle-ai's v9 contract renders the refuter and
@@ -7464,7 +7485,7 @@ async function executeReviewCaptureOperation(
 				mutation_outcome: "none",
 			};
 		}
-		return withCorrectionTarget(await executeReviewHostRelayCapture(hostMediatedRoleSlots[0]!, nativeReviewCli, cwd, selected.binding, retainedUntrackedSelections, route, signal, modelRegistry));
+		return withCorrectionTarget(await executeReviewHostRelayCapture(hostMediatedRoleSlots[0]!, nativeReviewCli, cwd, selected.binding, retainedUntrackedSelections, route, signal, modelRegistry, reviewerSessionId));
 	}
 
 	if (selected.input.captureOperation === "review.capture-correction-plan") {
@@ -7545,6 +7566,10 @@ async function executeReviewCaptureGroupOperation(
 	requireRegisteredRoute = false,
 	// gentle-pi#311 P2: see executeReviewCaptureOperation's matching parameter.
 	modelRegistry?: InProcessReviewerRegistry,
+	// The caller's live session id, set on every grouped relay request so an
+	// OpenCode-routed reviewer model carries its x-opencode-session attribution
+	// header. Appended last for the same positional-call-site reason as above.
+	reviewerSessionId?: string,
 ): Promise<Record<string, unknown>> {
 	const parameters = parseReviewCaptureGroupParameters(parametersValue);
 	if (nativeReviewCli === null || nativeReviewCli.targetStatus === undefined) return { ...captureGroupRejected("native target STATUS is unavailable"), outcome: "native-status-unsupported" };
@@ -7587,6 +7612,7 @@ async function executeReviewCaptureGroupOperation(
 		submission: slot.submission!,
 		...reviewHostRelaySelection(slot.lens, readModelConfig(cwd)),
 		...(modelRegistry === undefined ? {} : { reviewerRegistry: modelRegistry }),
+		...(reviewerSessionId === undefined ? {} : { reviewerSessionId }),
 		...(signal === undefined ? {} : { signal }),
 	}));
 	let prepared: readonly ReviewHostRelayPreparedResult[];
@@ -8317,11 +8343,13 @@ async function executeReviewControllerOperation(
 				// native START are resolved, and re-derive the target for that range,
 				// so all three agree on one base-diff identity. Adopting the offer
 				// later left the workspace target and the base-diff candidate view
-				// disagreeing, and START failed with identity-mismatch. Both an
-				// explicit caller baseRef and any START with an untracked selection in
-				// play keep today's single-STATUS flow; only an adopted offer pays the
-				// second read-only STATUS.
-				if (canonicalBaseRef === undefined && untrackedSelection.untrackedScope === undefined && untrackedSubmission === undefined) {
+				// disagreeing, and START failed with identity-mismatch. An explicit
+				// caller baseRef still wins (it already is the adopted range), but an
+				// in-play untracked selection now also pays this second read-only
+				// STATUS: the renegotiated target is a base-diff projection, so the
+				// candidate view must be materialized WITH the offered base instead of
+				// the base-less view that tripped candidate-target-projection-drift.
+				if (canonicalBaseRef === undefined) {
 					const offeredBaseRef = offeredCommittedRangeBaseRef(target);
 					if (offeredBaseRef !== undefined) {
 						const renegotiated = await negotiatedStatusForHostTransport(nativeReviewCli, {
@@ -8329,6 +8357,8 @@ async function executeReviewControllerOperation(
 							...(parameters.lineageId === undefined ? {} : { lineageId: parameters.lineageId }),
 							baseRef: offeredBaseRef,
 							committedOnly: true,
+							...(untrackedSelection.untrackedScope === undefined ? {} : untrackedSelection),
+							...(untrackedSubmission === undefined ? {} : { intendedUntrackedSelection: untrackedSubmission }),
 							...(signal === undefined ? {} : { signal }),
 						}, retainedUntrackedSelections, defaultCwd);
 						if (renegotiated.transport !== undefined) return hostTransportUnavailable(parameters.operation, renegotiated.transport);
@@ -8375,11 +8405,7 @@ async function executeReviewControllerOperation(
 			let nativeStartAttempted = false;
 			try {
 				const candidateRequest = { contributorRoot: defaultCwd, replayKey, ...(canonicalBaseRef === undefined ? {} : { baseRef: canonicalBaseRef, committedOnly: true }) };
-				candidateView = candidateViews?.createOrReuse({ ...candidateRequest, ...(candidateIntendedUntracked.length === 0 ? {} : { intendedUntracked: candidateIntendedUntracked }) });
-				if (candidateView !== undefined && candidateIntendedUntracked.length === 0 && candidateView.candidateTree !== target.projection.currentCandidateTree) {
-					candidateView.cleanup();
-					candidateView = candidateViews?.createOrReuse({ ...candidateRequest, intendedUntracked: [] });
-				}
+				candidateView = candidateViews?.createOrReuse({ ...candidateRequest, intendedUntracked: candidateIntendedUntracked });
 				if (candidateView !== undefined) assertNativeStartCandidateBinding(candidateView, target);
 				let result: NativeStartResult;
 				try {
@@ -8860,6 +8886,10 @@ function createGentleAiExtensionForTesting(
 				((sessionKey: PendingReviewConsentSessionKey) => processRetainedNativeStatusSelections.get(sessionKey) ?? processRetainedNativeStatusSelections.set(sessionKey, new Map()).get(sessionKey)!)(pendingReviewConsentSessionKey(ctx, pendingReviewConsentFallbackKey)),
 				true,
 				ctx.modelRegistry,
+				// The live session id rides into the reviewer side-call so an
+				// OpenCode-routed completion carries its attribution headers
+				// (pi adds those inside the main agent loop; this is not that loop).
+				reviewSessionManagerAndId(ctx)?.sessionId,
 			);
 			return { content: [{ type: "text", text: JSON.stringify(details) }], details };
 		},
@@ -8899,6 +8929,10 @@ function createGentleAiExtensionForTesting(
 				((sessionKey: PendingReviewConsentSessionKey) => processRetainedNativeStatusSelections.get(sessionKey) ?? processRetainedNativeStatusSelections.set(sessionKey, new Map()).get(sessionKey)!)(pendingReviewConsentSessionKey(ctx, pendingReviewConsentFallbackKey)),
 				true,
 				ctx.modelRegistry,
+				// The live session id rides into the reviewer side-call so an
+				// OpenCode-routed completion carries its attribution headers
+				// (pi adds those inside the main agent loop; this is not that loop).
+				reviewSessionManagerAndId(ctx)?.sessionId,
 			);
 			return {
 				content: [{ type: "text", text: JSON.stringify(details) }],
@@ -9696,9 +9730,16 @@ function createGentleAiExtensionForTesting(
 	// background subagents may be launched at all, so nothing in Pi may write
 	// it. The only writer is this handler, reached only by explicit invocation.
 	pi.registerCommand("gentle:background-subagents", {
-		description: "Show or set the managed background-subagents policy (status|enable|disable). Every sub-action is user-initiated only; Pi automation never toggles it.",
+		description: "Show or set the managed background-subagents policy; no argument opens a selectable menu (status|enable|disable). Every sub-action is user-initiated only; Pi automation never toggles it.",
+		// No argument opens a selectable menu when an interactive UI is present;
+		// headless callers and fakes without ui.select keep the status fallback.
 		handler: async (args, ctx) => {
-			const subAction = args.trim().length === 0 ? "status" : args.trim();
+			let subAction = args.trim().length === 0 ? "status" : args.trim();
+			if (args.trim().length === 0 && ctx.hasUI && typeof ctx.ui.select === "function") {
+				const selected = await ctx.ui.select("Background subagents policy", ["status", "enable", "disable"]);
+				if (selected === undefined) return;
+				subAction = selected;
+			}
 			if (subAction !== "status" && subAction !== "enable" && subAction !== "disable") {
 				ctx.ui.notify(`Unknown /gentle:background-subagents sub-action "${subAction}". Use status, enable, or disable.`, "warning");
 				return;