gentle-pi 2.6.1 → 2.6.3

package/extensions/gentle-agents.ts

@@ -1,6 +1,6 @@
 import { fileURLToPath } from "node:url";
 import { extractParentConfirmedSddPreflightContext, getPackageAssetOwner, isParentConfirmedSddPreflightContext, SHIPPED_SDD_AGENT_NAMES } from "../lib/sdd-preflight.ts";
-import { NativeReviewCliV216, NativeReviewCliError, createNodeExecFileAdapter, decodeNativeSddStatusV2, type NativeReviewCli, type NativeSddAcquireRequest, type NativeSddSettleRequest } from "../lib/native-review-cli.ts";
+import { NativeReviewCliV216, NativeReviewCliError, createNodeExecFileAdapter, decodeNativeSddStatusV2, type NativeReviewCli, type NativeSddAcquireRequest, type NativeSddAttemptResult, type NativeSddSettleRequest } from "../lib/native-review-cli.ts";
 import { spawn } from "node:child_process";
 import { recordReviewMutation } from "../lib/review-reminder-receipt.ts";
 import { SessionWorktreeRegistry, resolveSessionWorktree, type WorktreeResolver } from "../lib/session-worktree-registry.ts";
@@ -19,7 +19,7 @@ import { isFinished, TASK_STATUS, TaskStore, type AskRequest, type TaskRecord }
 import { AgentRunner, piCommand, abortReasonText, plannedCommands, type RemediationPlan, type RemediationScope, REMEDIATION_PLAN_ENV, parseRemediationPlan, remediationEvidence, type AskAnswer, type RunnerDeps, type SddChangeSelection, type TaskRequest, type RemediationTerminalFacts } from "../lib/agents-runner.ts";
 import { ChildMessenger, type IpcEndpoint } from "../lib/agents-messaging.ts";
 import { hasReviewSessionPermission, resolveCanonicalGitRepositoryIdentitySync, type ReviewSessionManager } from "../lib/review-session-standing-permission.ts";
-import { historyDir, remediationUnresolved, loadHistory, loadStoredTask, pruneHistory, saveTask } from "../lib/agents-history.ts";
+import { acquireTaskLock, historyDir, remediationUnresolved, loadHistory, loadStoredTask, pruneHistory, saveTask } from "../lib/agents-history.ts";
 import { sessionToMarkdown } from "../lib/agents-transcript.ts";
 import { AgentsView } from "../lib/agents-view.ts";
 import { PresencePublisher } from "../lib/orchestrator-presence.ts";
@@ -129,6 +129,97 @@ export function remediationToolAllowed(scope: RemediationScope | undefined, cwd:
 	} catch { return false; }
 }
 
+export interface RemediationReconciliationResult {
+	acquireState?: NativeSddAttemptResult["state"];
+	settlementState?: NativeSddAttemptResult["state"];
+}
+
+async function replayUncertainNativeMutation<T>(label: "acquire" | "settlement", invoke: () => Promise<T>): Promise<T> {
+	try { return await invoke(); }
+	catch (error) {
+		if (error instanceof TypeError || error instanceof NativeReviewCliError && error.mutationOutcome === "none") throw error;
+		try { return await invoke(); }
+		catch { throw new Error(`Native remediation ${label} remains unresolved; retry only this exact retained task`); }
+	}
+}
+
+function finishReconciledTask(task: TaskRecord, message: string): void {
+	task.status = TASK_STATUS.FAILED;
+	task.error = message;
+	task.lastStep = "reconciled";
+	task.endedAt ??= Date.now();
+	task.lastActivityAt = Date.now();
+}
+
+export async function reconcileManagedRemediation(task: TaskRecord, native: NativeReviewCli, persist: (task: TaskRecord) => Promise<void>): Promise<RemediationReconciliationResult> {
+	const state = task.sddRemediation;
+	if (task.agent !== "sdd-remediate" || !state?.acquire || state.acquire.workspaceRoot !== task.cwd) throw new Error("Task is not an exact managed remediation record");
+	if (state.settlement) throw new Error("Managed remediation task already has a terminal settlement");
+
+	const settleExact = async (settle: NativeSddSettleRequest, acquireState?: NativeSddAttemptResult["state"]): Promise<RemediationReconciliationResult> => {
+		if (!native.sddAttemptSettle) throw new Error("Native remediation settlement reconciliation is unavailable");
+		let settlement: NativeSddAttemptResult;
+		try { settlement = await replayUncertainNativeMutation("settlement", () => native.sddAttemptSettle!(structuredClone(settle))); }
+		catch (error) {
+			state.settlementUncertain = true;
+			await persist(task);
+			throw error;
+		}
+		state.settlement = structuredClone(settlement);
+		delete state.settlementUncertain;
+		finishReconciledTask(task, `Managed remediation settlement reconciled as ${settlement.state}${settlement.reason ? `(${settlement.reason})` : ""}; no actor started`);
+		await persist(task);
+		return { ...(acquireState === undefined ? {} : { acquireState }), settlementState: settlement.state };
+	};
+
+	if (state.settle) {
+		const settle = state.settle, acquire = state.acquire;
+		const sameUntracked = JSON.stringify({ scope: settle.untrackedScope, inventory: settle.expectedUntrackedInventory, intended: settle.intendedUntracked }) === JSON.stringify({ scope: acquire.untrackedScope, inventory: acquire.expectedUntrackedInventory, intended: acquire.intendedUntracked });
+		if (state.acquireResult?.state !== "proceed" || !state.token || state.acquireResult.token !== state.token || settle.token !== state.token || settle.workspaceRoot !== acquire.workspaceRoot || settle.changeName !== acquire.changeName || settle.remediatesEvidenceRevision !== acquire.remediatesEvidenceRevision || !sameUntracked) throw new Error("Retained remediation settlement does not match its exact acquired authority");
+		return settleExact(structuredClone(settle), state.acquireResult.state);
+	}
+	if (!state.acquireUncertain) throw new Error("Managed remediation task has no uncertain acquire or settlement to reconcile");
+	if (state.actorClaimed) throw new Error("Managed remediation actor effects are uncertain; exact settlement or maintainer intervention is required");
+	if (state.acquireResult || state.token || state.settlementUncertain) throw new Error("Managed remediation acquire history is inconsistent; maintainer intervention is required");
+	if (!native.sddAttemptAcquire) throw new Error("Native remediation acquire reconciliation is unavailable");
+
+	let acquired: NativeSddAttemptResult;
+	try { acquired = await replayUncertainNativeMutation("acquire", () => native.sddAttemptAcquire!(structuredClone(state.acquire))); }
+	catch (error) {
+		state.acquireUncertain = true;
+		await persist(task);
+		throw error;
+	}
+	if (acquired.state === "proceed" && !acquired.token) throw new Error("Native remediation acquire reconciliation returned no token");
+	state.acquireResult = structuredClone(acquired);
+	delete state.acquireUncertain;
+	if (acquired.state !== "proceed") {
+		delete state.token;
+		finishReconciledTask(task, `Managed remediation acquire reconciled as ${acquired.state}${acquired.reason ? `(${acquired.reason})` : ""}; no actor started`);
+		await persist(task);
+		return { acquireState: acquired.state };
+	}
+
+	state.token = acquired.token;
+	const acquire = state.acquire;
+	const settle: NativeSddSettleRequest = {
+		workspaceRoot: acquire.workspaceRoot,
+		changeName: acquire.changeName,
+		token: acquired.token!,
+		requestId: `reconcile-${createHash("sha256").update(JSON.stringify(acquire)).digest("hex").slice(0, 32)}`,
+		outcome: "interrupted",
+		diagnosis: "Acquire outcome was recovered after the actor launch boundary was refused; no managed actor was launched",
+		harnessDisposition: "invalidated",
+		cleanupEvidence: "No managed actor was spawned; no child cleanup was required",
+		processEvidence: "spawned=false; actor_claimed=false; reconciliation=acquire",
+		remediatesEvidenceRevision: acquire.remediatesEvidenceRevision,
+		...(acquire.untrackedScope === undefined ? {} : { untrackedScope: acquire.untrackedScope, expectedUntrackedInventory: acquire.expectedUntrackedInventory, intendedUntracked: acquire.intendedUntracked }),
+	};
+	state.settle = structuredClone(settle);
+	await persist(task); // Recovered token and exact settlement replay input become durable atomically before native mutation.
+	return settleExact(settle, acquired.state);
+}
+
 export async function admitManagedRemediation(request: TaskRequest, input: unknown, native: NativeReviewCli, persist: (task: TaskRecord) => Promise<void>, context?: Pick<ExtensionContext, "hasUI" | "ui">, preparedTask?: TaskRecord): Promise<Partial<TaskRequest>> {
 	const selected = request.sddChange;
 	const asset = fileURLToPath(new URL("../assets/agents/sdd-remediate.md", import.meta.url));
@@ -197,9 +288,12 @@ export async function admitManagedRemediation(request: TaskRequest, input: unkno
 				task.error = "Managed remediation lacks complete passing planned-command evidence";
 			}
 			if (payload.outcome === "passed" && state.settlement && state.settlement.state !== "blocked") task.status = TASK_STATUS.COMPLETED;
-			if (!state.settlement || state.settlement.state === "blocked") {
+			if (!state.settlement) {
 				task.status = TASK_STATUS.FAILED;
 				task.error = "Native remediation settlement unresolved; retain exact history for reconciliation";
+			} else if (state.settlement.state === "blocked") {
+				task.status = TASK_STATUS.FAILED;
+				task.error = `Native remediation settlement blocked(${state.settlement.reason ?? "unspecified"}); current native admission decides any later attempt`;
 			}
 			await persist(task);
 		},
@@ -868,7 +962,7 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 		const selected = store.get(task.id);
 		if (!isOwnedActive(selected)) return;
 		if (selected.status === TASK_STATUS.QUEUED) {
-			if (runner.cancel(selected.id)) ctx.ui.notify(`Stopped ${selected.agent}.`);
+			if (runner.cancel(selected.id, "stopped from the agents panel")) ctx.ui.notify(`Stopped ${selected.agent}.`);
 			else ctx.ui.notify(`Task ${selected.agent} already finished.`, "warning");
 			return;
 		}
@@ -882,7 +976,7 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 				ctx.ui.notify(`Task ${selected.agent} already finished.`, "warning");
 				return;
 			}
-			if (runner.cancel(current.id)) ctx.ui.notify(`Stopped ${current.agent}.`);
+			if (runner.cancel(current.id, "stopped from the agents panel")) ctx.ui.notify(`Stopped ${current.agent}.`);
 			else ctx.ui.notify(`Task ${current.agent} already finished.`, "warning");
 		} finally {
 			stoppingTaskIds.delete(selected.id);
@@ -901,7 +995,7 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 		const confirmation = (async () => {
 			try {
 				if (!await ctx.ui.confirm(`Stop ${count} active ${noun}?`, `Only these ${count} ${noun} will stop. Current work may be incomplete.`)) return;
-				const cancelled = active.filter((task) => runner.cancel(task.id)).length;
+				const cancelled = active.filter((task) => runner.cancel(task.id, "stopped from the agents panel (stop all)")).length;
 				ctx.ui.notify(`Stopped ${cancelled} ${cancelled === 1 ? "subagent" : "subagents"}.`);
 			} finally {
 				stopAllConfirmation = undefined;
@@ -1133,7 +1227,7 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 		// no recorded reason. Cancel through the runner so the lifecycle runs and the
 		// record is persisted, and tell the user why.
 		const onAbort = (): void => {
-			if (runner.cancel(task.id)) {
+			if (runner.cancel(task.id, `cancelled: the tool call was aborted${abortReasonText(signal?.reason)}`)) {
 				ctx.ui.notify(
 					`Subagent ${task.agent} cancelled: the tool call was aborted${abortReasonText(signal?.reason)}. The run is recorded as cancelled.`,
 					"warning",
@@ -1217,6 +1311,25 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 		return task ? text(describeTask(task), taskDetails(task)) : text(`Error: no task ${String(params.task_id)}`, { error: "unknown task" });
 	});
 
+	tool("reconcile", "Reconcile one retained managed remediation mutation without launching an actor.", { required: ["task_id"], properties: { task_id: { type: "string" } } }, async (params, ctx) => {
+		const id = String(params.task_id);
+		const lock = acquireTaskLock(tasksDir, id);
+		try {
+			const stored = await loadStoredTask(tasksDir, id);
+			if (!stored) return text(`Error: no task ${id}`, { error: "unknown task" });
+			const task = stored.task, retainedThread = stored.thread;
+			const target = registryFor(ctx).validate(task.cwd);
+			if (target !== resolve(task.cwd) || task.sddRemediation?.acquire.workspaceRoot !== target) throw new Error("Retained remediation task must resolve to its exact worktree in the same Git clone as this session");
+			const native = deps.nativeSdd ?? new NativeReviewCliV216(createNodeExecFileAdapter());
+			const persist = async (current: TaskRecord) => {
+				await saveTask(tasksDir, current, retainedThread);
+				store.update(current.id, { status: current.status, error: current.error, lastStep: current.lastStep, endedAt: current.endedAt, lastActivityAt: current.lastActivityAt, sddRemediation: current.sddRemediation });
+			};
+			const result = await reconcileManagedRemediation(task, native, persist);
+			return text(`Managed remediation task ${task.id} reconciled; no actor started. Use fresh native status and admission for later work.`, { gentleAgents: { taskId: task.id, agent: task.agent, status: task.status, mode: task.mode }, reconciliation: { ...result, actorStarted: false } });
+		} finally { lock.release(); }
+	});
+
 	tool("result", "Return the final answer of a finished subagent task, or its current state if it is still running.", { required: ["task_id"], properties: { task_id: { type: "string" } } }, async (params) => {
 		const task = await resolveTask(String(params.task_id));
 		if (!task) return text(`Error: no task ${String(params.task_id)}`, { error: "unknown task" });
@@ -1238,7 +1351,7 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 
 	tool("cancel",  "Cancel a queued or running subagent task.", { required: ["task_id"], properties: { task_id: { type: "string" } } }, async (params) => {
 		const id = String(params.task_id);
-		return runner.cancel(id) ? text(`Cancelled task ${id}.`) : text(`Error: task ${id} is not running.`, { error: "not running" });
+		return runner.cancel(id, "cancelled by the cancel tool") ? text(`Cancelled task ${id}.`) : text(`Error: task ${id} is not running.`, { error: "not running" });
 	});
 
 	tool("send_message", "Steer a running subagent with a message delivered before its next model call.", { required: ["task_id", "message"], properties: { task_id: { type: "string" }, message: { type: "string" } } }, async (params) => {
@@ -1328,6 +1441,6 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 		sidebarTui = undefined;
 		worktrees?.close();
 		worktrees = undefined;
-		runner.cancelAll();
+		runner.cancelAll("cancelled: parent session shut down");
 	});
 }

package/extensions/gentle-ai.ts

@@ -1839,7 +1839,15 @@ async function resolveSelectedNativeSddChangeStartup(
 	}
 	if (selection.phase === "remediate") {
 		if (status.nextRecommended !== "remediate" || status.remediationState?.failedEvidenceRevision !== selection.failedEvidenceRevision) throw new Error("Stale remediation selection");
-	} else if (status.nextRecommended !== selection.phase || status.dependencies[selection.phase] !== "ready" || status.blockedReasons.length > 0) {
+	} else if (status.nextRecommended !== selection.phase || status.dependencies[selection.phase] !== "ready" || (status.blockedReasons.length > 0 && selection.phase !== "verify")) {
+		// Native's contract gates terminal, archive, and apply work on a
+		// non-empty `blockedReasons`, and it deliberately keeps the `verify`
+		// route runnable, because the blocker can name the evidence refresh
+		// that is its own remedy ("failed verification evidence is incomplete;
+		// rerun SDD verification", gentle-ai#3538). Vetoing that route made the
+		// native-recommended phase unreachable (gentle-pi#972). The other
+		// phases still fail closed, and every blocker stays in the injected
+		// status for reporting.
 		throw new Error(`SDD selection native status blocks phase ${selection.phase}; it cannot execute.`);
 	}
 	return { selection, status };
@@ -5601,6 +5609,33 @@ function completeNativeStart(
 	};
 }
 
+// gentle-ai#4003: every Pi-side teardown step that fails after the native
+// burn is deferred cleanup, not a failed acknowledgement. Only the
+// already-sanitized CandidateViewError surface is relayed; anything else is
+// reduced to the step's fixed code so no path or command text reaches the
+// caller. The candidate-view hint is out-of-band on purpose: no controller
+// operation exposes a cleanup-only retry, and replaying acknowledge-approved
+// would hit the already-burned lineage.
+const POST_BURN_CLEANUP = {
+	candidateView: { code: "candidate-view-cleanup-failed", nextAction: "retry-candidate-view-cleanup-or-remove-the-view-out-of-band" },
+	retainedSelection: { code: "retained-selection-cleanup-failed", nextAction: "retained-selection-clears-on-the-next-terminal-status" },
+} as const;
+
+function deferredPostBurnCleanup(step: (typeof POST_BURN_CLEANUP)[keyof typeof POST_BURN_CLEANUP], cleanup: () => void): Record<string, unknown> | undefined {
+	try {
+		cleanup();
+		return undefined;
+	} catch (error) {
+		return {
+			status: "deferred",
+			diagnostics: error instanceof CandidateViewError
+				? { code: error.reason, message: error.message }
+				: { code: step.code },
+			next_action: step.nextAction,
+		};
+	}
+}
+
 function nativeOperationFailure(operation: ReviewControllerOperation | "gentle_review_capture", error: unknown): Record<string, unknown> {
 	const value = error as { mutationOutcome?: unknown; nextAction?: unknown; diagnostics?: unknown; auditRecord?: unknown; launchAttempted?: unknown; candidateViewPreNative?: unknown; failureEnvelope?: { raw?: unknown; mutationOutcome?: unknown; replayability?: unknown; nextAction?: unknown; code?: unknown; continuation?: { command?: unknown } } };
 	if (isRecord(value.failureEnvelope) && isRecord(value.failureEnvelope.raw)) {
@@ -7335,42 +7370,50 @@ async function executeReviewControllerOperation(
 		} catch (error) {
 			return nativeOperationFailure(parameters.operation, error);
 		}
+		let acknowledged: NativeReviewAcknowledgeApprovedOutcome | void;
 		try {
 			// gentle-ai #3947: the burn answers with one review-acknowledged/v1
 			// envelope bound to exactly this lineage, target, and revision, and
 			// the burn is reported from that envelope, never from a later
 			// STATUS. Every published release up to v2.5.0-rc.3 still burns in
 			// silence, and that result stays byte-identical.
-			const acknowledged = await acknowledgementCli.acknowledgeApproved({
+			acknowledged = await acknowledgementCli.acknowledgeApproved({
 				argumentTokens,
 				cwd: defaultCwd,
 				binding: { lineageId: parameters.lineageId, targetIdentity: status.targetIdentity, revision: status.authority.revision },
 				...(signal === undefined ? {} : { signal }),
 			});
-			clearRetainedNativeUntrackedSelection(retainedUntrackedSelections, defaultCwd, parameters.lineageId);
-			// The registry owns restoring writability of its 0555 views before
-			// removal; a terminal approved cleanup keeps the lineage projection.
-			candidateViews?.cleanupTerminal(parameters.lineageId, "approved", defaultCwd);
-			// gentle-pi#668: `closed` is never auto-derived or recorded here --
-			// a parent that wants the on-path passes nativeReviewOutcome:
-			// "closed" explicitly on its next assess call for this candidate.
-			return {
-				operation: parameters.operation,
-				status: "closed",
-				outcome: "native-approved-acknowledgement-completed",
-				lineage_id: parameters.lineageId,
-				target_identity: status.targetIdentity,
-				...(acknowledged === undefined ? {} : { consumed_revision: acknowledged.consumedRevision }),
-				authority: "burned",
-				...(acknowledged === undefined ? {} : { burn_evidence: acknowledged.schema }),
-				delivery: "ordinary-repository-policy",
-				mutation_performed: true,
-				mutation_outcome: "committed",
-			};
 		} catch (error) {
 			if (!nativeMutationRequiresStatus(error)) return nativeOperationFailure(parameters.operation, error);
 			return await reconcileNativeMutationFailure(parameters.operation, error, acknowledgementCli, target, retainedUntrackedSelections);
 		}
+		// gentle-ai#4003: from here the native burn is the committed authority
+		// outcome. Both Pi-side teardown steps run outside the mutation-result
+		// try/catch and each one is guarded on its own, so a cleanup failure is
+		// reported as deferred cleanup and never as a failed acknowledgement
+		// that would invite a replay of a burned operation.
+		const retainedSelectionCleanup = deferredPostBurnCleanup(POST_BURN_CLEANUP.retainedSelection, () => clearRetainedNativeUntrackedSelection(retainedUntrackedSelections, defaultCwd, parameters.lineageId));
+		// The registry owns restoring writability of its 0555 views before
+		// removal; a terminal approved cleanup keeps the lineage projection.
+		const candidateViewCleanup = deferredPostBurnCleanup(POST_BURN_CLEANUP.candidateView, () => candidateViews?.cleanupTerminal(parameters.lineageId, "approved", defaultCwd));
+		// gentle-pi#668: `closed` is never auto-derived or recorded here --
+		// a parent that wants the on-path passes nativeReviewOutcome:
+		// "closed" explicitly on its next assess call for this candidate.
+		return {
+			operation: parameters.operation,
+			status: "closed",
+			outcome: "native-approved-acknowledgement-completed",
+			lineage_id: parameters.lineageId,
+			target_identity: status.targetIdentity,
+			...(acknowledged === undefined ? {} : { consumed_revision: acknowledged.consumedRevision }),
+			authority: "burned",
+			...(acknowledged === undefined ? {} : { burn_evidence: acknowledged.schema }),
+			delivery: "ordinary-repository-policy",
+			mutation_performed: true,
+			mutation_outcome: "committed",
+			...(retainedSelectionCleanup === undefined ? {} : { retained_selection_cleanup: retainedSelectionCleanup }),
+			...(candidateViewCleanup === undefined ? {} : { candidate_view_cleanup: candidateViewCleanup }),
+		};
 	}
 	if (parameters.operation === REVIEW_CONTROLLER_OPERATION.ANSWER_CONSENT) {
 		const input = parseControllerJson(requiredControllerString(parameters, "input"), parameters.operation);

package/lib/agents-history.ts

@@ -1,5 +1,9 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import os from "node:os";
+import { dirname, join } from "node:path";
 import { emptyThread, type TaskRecord, type TaskThread } from "./agents-protocol.ts";
 
 // Gentle Agents history: one JSON file per finished task, written by the
@@ -16,7 +20,13 @@ export function remediationUnresolved(task: TaskRecord): boolean {
 	const state = task.sddRemediation;
 	if (!state) return false;
 	if (state.acquireUncertain || state.settlementUncertain) return true;
-	if (state.settlement) return state.settlement.state === "blocked";
+	// A received settlement is a definite native outcome, whatever its state
+	// (including "blocked"): it is terminal task history, never local
+	// ambiguity. Native admission is the sole authority over any later
+	// attempt for the same cwd/change; only genuinely uncertain outcomes, or
+	// no settlement at all with a still-retained token/claimed actor, are
+	// unresolved.
+	if (state.settlement) return false;
 	return !!state.token || !!state.actorClaimed || !["blocked", "complete"].includes(state.acquireResult?.state ?? "");
 }
 
@@ -32,6 +42,83 @@ function fileFor(dir: string, id: string): string {
 	return join(dir, `${id}${FILE_SUFFIX}`);
 }
 
+const TASK_LOCK_SCHEMA = "gentle-pi.task-reconciliation-lock/v1" as const;
+const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+type TaskLockOwner = { schema: typeof TASK_LOCK_SCHEMA; taskId: string; token: string; pid: number; host: string | null };
+export interface TaskLock { readonly path: string; readonly taskId: string; readonly token: string; release(): void; }
+function taskLockHost(): string | null {
+	try {
+		const hostname = os.hostname().trim();
+		if (process.platform === "linux") { const boot = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim(), namespace = readlinkSync("/proc/self/ns/pid"); return UUID.test(boot) && /^pid:\[\d+\]$/.test(namespace) ? `linux:${hostname}:${boot}:${namespace}` : null; }
+		if (process.platform === "darwin") { const boot = execFileSync("/usr/sbin/sysctl", ["-n", "kern.bootsessionuuid"], { encoding: "utf8", timeout: 1000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"] }).trim(); return UUID.test(boot) ? `darwin:${hostname}:${boot.toLowerCase()}` : null; }
+		return hostname ? `${process.platform}:${hostname}` : null;
+	} catch { return null; }
+}
+function errorCode(error: unknown): string | undefined {
+	return typeof error === "object" && error !== null && "code" in error && typeof (error as { code?: unknown }).code === "string" ? (error as { code: string }).code : undefined;
+}
+function lockBusy(path: string, reason: string): Error { return new Error(`Task reconciliation lock is busy or ambiguous at ${path}: ${reason}`); }
+function validTaskLockOwner(value: unknown, taskId: string): value is TaskLockOwner {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const owner = value as Partial<TaskLockOwner>;
+	return Object.keys(value).sort().join(",") === "host,pid,schema,taskId,token" && owner.schema === TASK_LOCK_SCHEMA && owner.taskId === taskId && typeof owner.token === "string" && UUID.test(owner.token) && Number.isSafeInteger(owner.pid) && owner.pid > 0 && (owner.host === null || typeof owner.host === "string" && owner.host.length > 0 && !owner.host.includes("\0"));
+}
+function ownerAt(path: string, taskId: string, token: string): TaskLockOwner {
+	if (!path.endsWith(`${taskId}.reconcile.${token}`)) throw lockBusy(path, "candidate filename is malformed");
+	const stat = lstatSync(path);
+	if (!stat.isFile() || stat.isSymbolicLink()) throw lockBusy(path, "candidate is not an expected regular file");
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!validTaskLockOwner(parsed, taskId) || parsed.token !== token) throw new Error("filename and owner metadata disagree");
+		return parsed;
+	} catch (error) { throw lockBusy(path, `candidate owner metadata is malformed${error instanceof Error ? `: ${error.message}` : ""}`); }
+}
+function ownerDead(owner: TaskLockOwner): boolean {
+	const host = taskLockHost();
+	if (!owner.host || !host || owner.host !== host || owner.pid === process.pid) return false;
+	try { process.kill(owner.pid, 0); return false; } catch (error) { return errorCode(error) === "ESRCH"; }
+}
+function syncTaskLock(path: string, directory = false): void {
+	if (directory && process.platform === "win32") return;
+	const descriptor = openSync(path, directory ? "r" : "r+");
+	try { fsyncSync(descriptor); } finally { closeSync(descriptor); }
+}
+function publishExclusive(path: string, owner: TaskLockOwner): void {
+	const temporary = `${path}.tmp`;
+	try { writeFileSync(temporary, JSON.stringify(owner), { encoding: "utf8", flag: "wx", mode: 0o600 }); syncTaskLock(temporary); linkSync(temporary, path); syncTaskLock(dirname(path), true); }
+	finally { try { unlinkSync(temporary); } catch {} }
+}
+function scanTaskCandidates(dir: string, id: string, ownPath: string): void {
+	const prefix = `${id}.reconcile.`;
+	for (const name of readdirSync(dir)) {
+		if (!name.startsWith(prefix) || name.endsWith(".tmp")) continue;
+		const path = join(dir, name), token = name.slice(prefix.length);
+		if (!UUID.test(token)) throw lockBusy(path, "candidate filename is malformed");
+		let owner: TaskLockOwner;
+		try { owner = ownerAt(path, id, token); } catch (error) { if (errorCode(error) === "ENOENT") throw lockBusy(path, "candidate disappeared during election"); throw error; }
+		if (path === ownPath) continue;
+		if (ownerDead(owner)) { try { unlinkSync(path); } catch (error) { if (errorCode(error) !== "ENOENT") throw error; } continue; }
+		throw lockBusy(path, "owner is live, foreign, or its death is inconclusive");
+	}
+}
+function releaseTaskLock(path: string, owner: TaskLockOwner): void {
+	let current: TaskLockOwner;
+	try { current = ownerAt(path, owner.taskId, owner.token); } catch (error) { if (errorCode(error) === "ENOENT") return; throw error; }
+	if (current.pid !== owner.pid || current.host !== owner.host) throw new Error("Task reconciliation lock owner token does not match");
+	unlinkSync(path); syncTaskLock(dirname(path), true);
+}
+export function acquireTaskLock(dir: string, id: string): TaskLock {
+	if (!SAFE_ID.test(id)) throw new Error(`invalid task id: ${id}`);
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
+	const owner: TaskLockOwner = { schema: TASK_LOCK_SCHEMA, taskId: id, token: randomUUID(), pid: process.pid, host: taskLockHost() };
+	const path = join(dir, `${id}.reconcile.${owner.token}`);
+	publishExclusive(path, owner);
+	try { scanTaskCandidates(dir, id, path); }
+	catch (error) { try { releaseTaskLock(path, owner); } catch {} throw error; }
+	let released = false;
+	return { path, taskId: id, token: owner.token, release() { if (!released) { releaseTaskLock(path, owner); released = true; } } };
+}
+
 function isRecord(value: unknown): value is TaskRecord {
 	const task = value as Partial<TaskRecord> | undefined;
 	return typeof task?.id === "string" && typeof task.agent === "string" && typeof task.status === "string" && typeof task.createdAt === "number";

package/lib/agents-runner.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import type { Duplex, Readable, Writable } from "node:stream";
+import { stripVTControlCharacters } from "node:util";
 import { RESEARCH_SELECTION_ENV, RESEARCH_ARTIFACT_ENV, type ResearchArtifactIntent } from "./sdd-research-capabilities.ts";
 import { AGENT_MODE, formatModelRef, type AgentDefinition, type AgentMode, type ModelRef } from "./agents-config.ts";
 import { CHILD_QUERY_MAX_INFLIGHT, CHILD_QUERY_TIMEOUT_MS, parseChildFrame, validChildMessage, validChildQueryId } from "./agents-messaging.ts";
@@ -275,8 +276,13 @@ interface LiveTask {
 	acknowledgedIpcIds: Set<string>;
 	acknowledgedIpcOrder: string[];
 	mutationStarts: Map<string, { toolName: "write" | "edit"; toolCallId: string; path: string }>;
+	// Bounded ring buffer of the child's raw stderr output, capped to the last
+	// STDERR_TAIL_MAX characters. Only surfaced on the stall and pre-settle exit
+	// terminal paths, never on completed, cancelled, or other failure reasons.
+	stderrTail: string;
 }
 
+const STDERR_TAIL_MAX = 512;
 const CHILD_MARKER = "GENTLE_PI_AGENTS_CHILD";
 const IPC_MARKER = "GENTLE_PI_AGENTS_OWNED_IPC";
 const PARENT_NOTIFICATION_TOOL = "subagent_parent_message";
@@ -487,15 +493,15 @@ export class AgentRunner {
 		return accepted;
 	}
 
-	cancel(id: string): boolean {
+	cancel(id: string, reason = "cancelled"): boolean {
 		const queued = this.queue.findIndex((entry) => entry.task.id === id);
 		if (queued >= 0) {
 			this.queue.splice(queued, 1);
-			this.finish(id, TASK_STATUS.CANCELLED, "cancelled before start");
+			this.finish(id, TASK_STATUS.CANCELLED, `${reason} before start`);
 			return true;
 		}
 		if (!this.live.has(id)) return false;
-		this.requestStop(id, TASK_STATUS.CANCELLED, "cancelled", true);
+		this.requestStop(id, TASK_STATUS.CANCELLED, reason, true);
 		return true;
 	}
 
@@ -506,9 +512,9 @@ export class AgentRunner {
 		if (live) { live.observations = undefined; live.observationGuard = undefined; }
 	}
 
-	cancelAll(): number {
+	cancelAll(reason = "cancelled"): number {
 		const ids = [...this.queue.map((entry) => entry.task.id), ...this.live.keys()];
-		return ids.filter((id) => this.cancel(id)).length;
+		return ids.filter((id) => this.cancel(id, reason)).length;
 	}
 
 	steer(id: string, message: string): boolean {
@@ -555,7 +561,7 @@ export class AgentRunner {
 			return;
 		}
 		const processGroup = detached && typeof child.pid === "number" && child.pid > 0 ? child.pid : undefined;
-		const live: LiveTask = { child, mutationStarts: new Map(), pending: new Map(), queries: new Map(), replies: new Map(), cancelStall: () => {}, cancelGrace: () => {}, processGroup, terminal: undefined, childExit: undefined, cleanupDeadlineAt: undefined, quarantined: false, nextId: 0, ipcClosed: false, acknowledgedIpcIds: new Set(), acknowledgedIpcOrder: [] };
+		const live: LiveTask = { child, mutationStarts: new Map(), pending: new Map(), queries: new Map(), replies: new Map(), cancelStall: () => {}, cancelGrace: () => {}, processGroup, terminal: undefined, childExit: undefined, cleanupDeadlineAt: undefined, quarantined: false, nextId: 0, ipcClosed: false, acknowledgedIpcIds: new Set(), acknowledgedIpcOrder: [], stderrTail: "" };
 		if (request.prepareResponseObservations) {
 			let ready = false;
 			live.observationPreparation = () => ready;
@@ -592,7 +598,11 @@ export class AgentRunner {
 		const lines = new JsonLines((value) => this.receive(id, request, value));
 		child.stdout.setEncoding("utf8");
 		child.stdout.on("data", (chunk: string) => lines.push(chunk));
-		child.stderr?.on("data", () => {});
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (chunk: string) => {
+			const tail = live.stderrTail + chunk;
+			live.stderrTail = tail.length > STDERR_TAIL_MAX ? tail.slice(-STDERR_TAIL_MAX) : tail;
+		});
 		child.on("exit", (code) => this.exited(id, code));
 		if (request.sddRemediation && child.pid === undefined) {
 			this.childError(id, new Error("remediation child has no process ID"));
@@ -602,6 +612,7 @@ export class AgentRunner {
 			const data = response.data as { sessionFile?: unknown; model?: { provider?: unknown; id?: unknown } | null; thinkingLevel?: unknown } | undefined;
 			if (response.success !== true || live.terminal || this.live.get(id) !== live || !data) return;
 			const resolved: Partial<TaskRecord> = {};
+			if (this.canAdvanceLastStep(id, ["starting"])) resolved.lastStep = "pi ready";
 			if (typeof data.sessionFile === "string" && data.sessionFile) resolved.sessionPath = data.sessionFile;
 			if (data.model === null) resolved.model = "default";
 			else if (typeof data.model?.provider === "string" && data.model.provider && typeof data.model.id === "string" && data.model.id) {
@@ -611,13 +622,35 @@ export class AgentRunner {
 			this.store.update(id, resolved);
 		});
 		void this.send(id, { type: "prompt", message: promptText(request) }).then((response) => {
-			if (response.success === false) this.requestStop(id, TASK_STATUS.FAILED, String(response.error ?? "prompt rejected"));
+			if (response.success === false) {
+				this.requestStop(id, TASK_STATUS.FAILED, String(response.error ?? "prompt rejected"));
+				return;
+			}
+			if (!live.terminal && this.live.get(id) === live && this.canAdvanceLastStep(id, ["starting", "pi ready"])) this.store.update(id, { lastStep: "prompt accepted" });
 		});
 	}
 
+	// A late get_state/prompt reply must never overwrite a stage that a child
+	// event (or the other reply) has already advanced lastStep past.
+	private canAdvanceLastStep(id: string, from: readonly string[]): boolean {
+		const current = this.store.get(id)?.lastStep;
+		return current !== undefined && from.includes(current);
+	}
+
+	// Cleaned for display only: raw bytes stay in live.stderrTail so later
+	// appends keep working from the unstripped ring buffer.
+	private stderrSuffix(live: LiveTask): string {
+		const cleaned = stripVTControlCharacters(live.stderrTail).replace(/\s+/g, " ").trim();
+		return cleaned ? `; stderr: ${cleaned}` : "";
+	}
+
 	private armStall(id: string, live: LiveTask): void {
 		live.cancelStall();
-		live.cancelStall = this.deps.schedule(() => this.requestStop(id, TASK_STATUS.TIMED_OUT, `stalled for ${Math.round(this.limits.stallTimeoutMs / 60_000)} min`), this.limits.stallTimeoutMs);
+		live.cancelStall = this.deps.schedule(() => {
+			const lastStep = this.store.get(id)?.lastStep ?? "starting";
+			const minutes = Math.round(this.limits.stallTimeoutMs / 60_000);
+			this.requestStop(id, TASK_STATUS.TIMED_OUT, `stalled for ${minutes} min after: ${lastStep}${this.stderrSuffix(live)}`);
+		}, this.limits.stallTimeoutMs);
 	}
 
 	private send(id: string, command: Record<string, unknown>): Promise<Record<string, unknown>> {
@@ -933,7 +966,7 @@ export class AgentRunner {
 		if (!live) return;
 		live.childExit = code;
 		if (this.groupExists(live)) {
-			if (!live.terminal) this.requestStop(id, TASK_STATUS.FAILED, `pi exited with code ${code ?? "unknown"} before agent_settled`);
+			if (!live.terminal) this.requestStop(id, TASK_STATUS.FAILED, `pi exited with code ${code ?? "unknown"} before agent_settled${this.stderrSuffix(live)}`);
 			return;
 		}
 		this.completeExit(id, live);
@@ -951,7 +984,7 @@ export class AgentRunner {
 			return;
 		}
 		const terminal = live.terminal;
-		this.finish(id, terminal ? terminal.status : TASK_STATUS.FAILED, terminal ? terminal.error : `pi exited with code ${live.childExit ?? "unknown"} before agent_settled`, live);
+		this.finish(id, terminal ? terminal.status : TASK_STATUS.FAILED, terminal ? terminal.error : `pi exited with code ${live.childExit ?? "unknown"} before agent_settled${this.stderrSuffix(live)}`, live);
 	}
 
 	private finish(id: string, status: TaskRecord["status"], error: string | null, live?: LiveTask): void {

package/lib/native-review-cli.ts

@@ -971,6 +971,28 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// this row repeats 2.8.0 exactly. riskEvidence and hint remain dark
 	// because neither is proven to reach the negotiated START path Pi consumes.
 	"2.8.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 }),
+	// v2.8.2 shipped OpenCode SDD preflight plugin fixes, community-tools RTK
+	// acquisition, and Claude Code Stop telemetry. The provider contract semver
+	// stays 1.2.0; the same pin re-mirrors bundle bytes that had drifted under
+	// that semver (lens inspection.status "unavailable", targeted-validator
+	// regressions/inspection members, seven Pi stop reason codes). None of
+	// those touch the closed START/STATUS fields this row negotiates, so it
+	// repeats 2.8.1 exactly. riskEvidence and hint remain dark because neither
+	// is proven to reach the negotiated START path Pi consumes.
+	"2.8.2": 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 }),
+	// v2.9.0 shipped RTK opt-in Community Tool integration (#4560, installer/
+	// sync/TUI only), SDD attempt-ledger fixes (#4564, #4567, #4569 — the
+	// remediation pointer is now decided by chain equality before shape, and
+	// the refusal wording changed), sync telemetry-runtime symlinked root
+	// (#4565), OpenCode reviewer Task wrapper decoding (#4545), and Engram
+	// protocol asset wording (#4179). Ground-truthed by diffing
+	// contracts/review-integration/v2 and contracts/review-provider-contract
+	// between the v2.8.2 and v2.9.0 tags in the gentle-ai source tree: zero
+	// bytes changed. None of the above touch the closed START/STATUS fields
+	// this row negotiates, so it repeats 2.8.2 exactly. riskEvidence and hint
+	// remain dark because neither is proven to reach the negotiated START
+	// path Pi consumes.
+	"2.9.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 {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "2.6.1",
+	"version": "2.6.3",
 	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
 	"license": "MIT",
 	"type": "module",