gentle-pi 2.6.2 → 2.6.4

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

@@ -980,6 +980,19 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 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.2",
+	"version": "2.6.4",
 	"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",

package/runtime/native-review-cli.mjs

@@ -981,6 +981,19 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 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 }),
 });
 
 

package/scripts/gentle-ai-installer.mjs

@@ -36,7 +36,7 @@ const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
 // version check below) derives from this constant instead of repeating the
 // literal, so a pin bump cannot leave a stale copy behind. See
 // scripts/install-gentle-ai.mjs for the incident that motivated this.
-export const INSTALLER_VERSION = "2.8.2";
+export const INSTALLER_VERSION = "2.9.0";
 export const RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-ai/releases/download/v${INSTALLER_VERSION}/`;
 export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 	SIGNED_RELEASE_ASSET: "signed-release-asset",
@@ -45,10 +45,10 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v2";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v2@v2.8.2`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v2@v2.9.0`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit e3f53de6, the published v2.8.2 release head.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:54VJ0ruRiPc6MbNw4iFmlcBkQFOyF5D8iHY0A54Ivug=";
+// tag resolves to commit be495547, the published v2.9.0 release head.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:WqmYw1UfVYCbtOxU1uTuiYq9+ROCUIDrmKIOjyYggQI=";
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE = `${GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH}@${GENTLE_AI_WINDOWS_SOURCE_TAG}`;
 export const GENTLE_AI_WINDOWS_MINIMUM_GO_VERSION = "1.25.10";
 export const GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE_CODE = "GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE";
@@ -67,7 +67,7 @@ export class GentleAiInstallerError extends Error {
 // Sentinel used while a re-pinned gentle-ai release is not yet published. A
 // sentinel digest can never match a real SHA-256, so installation fails closed,
 // and verify-package-files.mjs refuses to pack/publish while any digest below
-// still holds it. The v2.8.2 digests are pinned from the published release:
+// still holds it. The v2.9.0 digests are pinned from the published release:
 // archive sha256 values verified against the minisign-signed checksums.txt and
 // freshly computed hashes; binary sha256 values computed from the extracted
 // executables.
@@ -109,15 +109,15 @@ async function downloadPinnedGentleAiAsset(asset, destination, options) {
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v2.8.2 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v2.9.0 publishes signed
 // Darwin/Linux archives only. Windows x64/arm64 uses the separately verified
 // exact-tag Go SumDB source-build path below; restore archive rows only when
 // upstream ships signed Windows assets.
 export const GENTLE_AI_RELEASE_ASSETS = Object.freeze({
-	"darwin/amd64": asset("gentle-ai_2.8.2_darwin_amd64.tar.gz", "0daa28897e6e54ce584f12ccefebf0d0df84e4ea8fbbd3a07e596ca82b079fa2", "17069156869ceda8e23eaa4fe5d7565cd57c1d78528f121dabba7301b82a0c14", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_2.8.2_darwin_arm64.tar.gz", "12265017e0fb6d5dd1ddb1751f188fa8c47d95a95d7c7515ae174394da5f6e97", "491542e4b60e432048d4074f21c1b04417b980cf77eb34cd0a2e7447ca57dd77", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_2.8.2_linux_amd64.tar.gz", "5b95b184606168685a4ff576c103b051ceb23346a7f81ba557e047fa4d744146", "a55f4d2e114128866810c25195e5efecdded4502660e9a9c35c0b7a41c909dd8", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_2.8.2_linux_arm64.tar.gz", "a33c91ca0f5c5c85a4fd69f5169138089eb53e0a92c6ab80de5094d0688debb7", "e2759aca09ffe97638e984491319e43c9477d1ae117726ecbdf20d29d44c8950", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_2.9.0_darwin_amd64.tar.gz", "0e1ce0b117e6f15b56e05defecb33a33825c2e25eb8306df09401d41e0a176fb", "0dc22de552e0403f318770067adccd82783b1f654ed4d0410d7d969e28e39602", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_2.9.0_darwin_arm64.tar.gz", "0a58d81cd7d76315e1d11ecf6b38abb27ee8e7e709a04c9a786e89636fb559bb", "5e72f1f34667a858fc179504e794847a1407142240361f99effd252d6ad49ee9", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_2.9.0_linux_amd64.tar.gz", "7d414cd8cba8ddc0ab9fa4bc309932638c533217b2f999b2a52e7a4fc0bf6f14", "5c47029fb6520f99b7df1b6841766b09d7184efed2e18694d83795bf4d4a5ad4", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_2.9.0_linux_arm64.tar.gz", "2bdab4684b5d415df9c9423c2022b017c7c1c1d9056f56acc08633fa0d821cfc", "56501a4d91f4e3255726b63c59b96a6d42c6952af2d265f54c8e99b361cda0c9", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,

package/scripts/verify-package-files.mjs

@@ -340,7 +340,7 @@ async function main() {
   });
 
   if (driftedContracts.length > 0) {
-    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v2.8.2 runtime's vendored Gentle AI contract artifacts:");
+    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v2.9.0 runtime's vendored Gentle AI contract artifacts:");
     for (const drift of driftedContracts) console.error(`- ${drift.relativePath}: expected ${drift.expected}, got ${drift.actual}`);
     process.exit(1);
   }
@@ -385,7 +385,7 @@ async function main() {
     process.exit(1);
   }
 
-  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v2.8.2 runtime).`);
+  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v2.9.0 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;

package/tests/agents-history.test.ts

@@ -1,9 +1,10 @@
 import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
 import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test, { after } from "node:test";
-import { historyDir, loadHistory, loadStoredTask, pruneHistory, saveTask } from "../lib/agents-history.ts";
+import { acquireTaskLock, historyDir, loadHistory, loadStoredTask, pruneHistory, saveTask } from "../lib/agents-history.ts";
 import { applyTaskEvent, emptyThread, TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
 
 // Gentle Agents history: JSON per task, async, lazy, pruned by count.
@@ -12,6 +13,13 @@ const root = mkdtempSync(join(tmpdir(), "gentle-agents-history-"));
 after(() => rmSync(root, { recursive: true, force: true }));
 const dir = join(root, "tasks");
 
+function orphanLock(lockDir: string, id: string): void {
+	const moduleUrl = new URL("../lib/agents-history.ts", import.meta.url).href;
+	const source = `import { acquireTaskLock } from ${JSON.stringify(moduleUrl)}; const [dir, id] = process.argv.slice(-2); acquireTaskLock(dir, id);`;
+	const child = spawnSync(process.execPath, ["--experimental-strip-types", "--input-type=module", "-e", source, lockDir, id], { encoding: "utf8" });
+	assert.equal(child.status, 0, child.stderr || child.stdout);
+}
+
 function task(id: string, createdAt: number): TaskRecord {
 	return { id, agent: "explore", mode: "task", prompt: "p", label: "p", cwd: "/r", parentSessionId: "s", status: TASK_STATUS.COMPLETED, createdAt, startedAt: createdAt, endedAt: createdAt + 5, model: "m", thinking: undefined, sessionPath: null, error: null, result: "ok", lastStep: "done", lastActivityAt: createdAt, turns: 1, toolCalls: 0, tokens: 10, cost: 0.01 };
 }
@@ -33,6 +41,20 @@ test("saveTask writes a task with its thread and loadStoredTask reads it back",
 	assert.deepEqual(readdirSync(dir), ["a1.json"], "no temp file is left behind");
 });
 
+test("task reconciliation elections bypass dead candidates and fail closed for active or ambiguous candidates", () => {
+	const lockDir = join(root, "task-locks"), token = "11111111-1111-4111-8111-111111111111";
+	const held = acquireTaskLock(lockDir, "busy");
+	assert.match(held.path, /busy\.reconcile\.[0-9a-f-]+$/);
+	assert.throws(() => acquireTaskLock(lockDir, "busy"), /busy|active|ambiguous/i); held.release();
+	orphanLock(lockDir, "dead");
+	const deadName = readdirSync(lockDir).find(name => name.startsWith("dead.reconcile."))!;
+	const bypassed = acquireTaskLock(lockDir, "dead");
+	assert.notEqual(bypassed.path, join(lockDir, deadName)); assert.ok(!readdirSync(lockDir).includes(deadName)); bypassed.release();
+	const malformed = join(lockDir, `malformed.reconcile.${token}`); writeFileSync(malformed, "not-json");
+	assert.throws(() => acquireTaskLock(lockDir, "malformed"), /busy|active|ambiguous|malformed/i);
+	const foreign = join(lockDir, `foreign.reconcile.${token}`); writeFileSync(foreign, JSON.stringify({ schema: "gentle-pi.task-reconciliation-lock/v1", taskId: "foreign", token, pid: process.pid, host: "foreign-host" }));
+	assert.throws(() => acquireTaskLock(lockDir, "foreign"), /busy|active|ambiguous|foreign/i);
+});
 test("loadHistory skips broken files, sorts newest first, and pruneHistory keeps the newest N", async () => {
 	await saveTask(dir, task("b2", 3000), emptyThread());
 	await saveTask(dir, task("c3", 2000), emptyThread());

package/tests/agents-runner.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { PassThrough } from "node:stream";
 import { AGENT_MODE, parseAgentsConfig, resolveAgentProfile, type AgentDefinition } from "../lib/agents-config.ts";
 import { TASK_STATUS, TaskStore, type RemediationTaskState, type TaskRecord } from "../lib/agents-protocol.ts";
 import { AgentRunner, childArguments, JsonLines, piCommand, abortReasonText, type RemediationPlan, type RemediationTerminalFacts, type RunnerDeps, type RunnerHooks, type TaskRequest } from "../lib/agents-runner.ts";
@@ -25,7 +26,7 @@ interface Harness {
 	spawnOptions: Array<{ env: NodeJS.ProcessEnv; stdio?: string[] }>;
 }
 
-function harness(options: { pid?: number; maxConcurrency?: number; answer?: Record<string, unknown>; exitOnKill?: boolean; state?: Record<string, unknown>; stateSuccess?: boolean; onNotification?: RunnerHooks["onNotification"]; onSuccessfulMutation?: RunnerHooks["onSuccessfulMutation"]; onFinish?: RunnerHooks["onFinish"] } = {}): Harness {
+function harness(options: { pid?: number; maxConcurrency?: number; stallTimeoutMs?: number; answer?: Record<string, unknown>; exitOnKill?: boolean; state?: Record<string, unknown>; stateSuccess?: boolean; onNotification?: RunnerHooks["onNotification"]; onSuccessfulMutation?: RunnerHooks["onSuccessfulMutation"]; onFinish?: RunnerHooks["onFinish"] } = {}): Harness {
 	const children: FakeChild[] = [];
 	const timers: Harness["timers"] = [];
 	const asks: Harness["asks"] = [];
@@ -59,7 +60,7 @@ function harness(options: { pid?: number; maxConcurrency?: number; answer?: Reco
 		pi: { command: "pi", args: [] },
 	};
 	const store = new TaskStore();
-	const runner = new AgentRunner(store, { maxConcurrency: options.maxConcurrency ?? 2, stallTimeoutMs: 10_000 }, deps, {
+	const runner = new AgentRunner(store, { maxConcurrency: options.maxConcurrency ?? 2, stallTimeoutMs: options.stallTimeoutMs ?? 10_000 }, deps, {
 		askUser: async (taskId, ask) => {
 			asks.push({ taskId, method: ask.method });
 			return options.answer ?? { value: "yes" };
@@ -73,6 +74,157 @@ function harness(options: { pid?: number; maxConcurrency?: number; answer?: Reco
 
 const tick = () => new Promise((resolve) => setImmediate(resolve));
 
+const FOUR_MIN_MS = 4 * 60_000;
+
+// A child that never answers the launch RPC commands (get_state, prompt), so
+// the task's lastStep never leaves its initial "starting" stage. Used to
+// exercise the stall watchdog before any child response arrives.
+function silentHarness(stallTimeoutMs: number): { store: TaskStore; runner: AgentRunner; timers: Array<{ fn: () => void; ms: number; cancelled: boolean }>; child: () => FakeChild } {
+	const timers: Array<{ fn: () => void; ms: number; cancelled: boolean }> = [];
+	let clock = 1000;
+	let created: FakeChild | undefined;
+	const store = new TaskStore();
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs }, {
+		spawn: () => {
+			created = fakeChild();
+			created.child.stdin.removeAllListeners("data");
+			return created.child;
+		},
+		now: () => (clock += 1),
+		schedule: (fn, ms) => {
+			const timer = { fn, ms, cancelled: false };
+			timers.push(timer);
+			return () => {
+				timer.cancelled = true;
+			};
+		},
+		pi: { command: "pi", args: [] },
+	}, { askUser: async () => ({ cancelled: true }) });
+	return { store, runner, timers, child: () => created! };
+}
+
+test("stall before any child response records the last completed stage as starting, with the stderr tail", async () => {
+	const h = silentHarness(FOUR_MIN_MS);
+	const task = h.runner.run(request());
+	await tick();
+	(h.child().child.stderr as unknown as PassThrough).write("Error:   cannot bind\nprovider socket\n");
+	await tick();
+	const stall = h.timers.filter((timer) => timer.ms === FOUR_MIN_MS && !timer.cancelled).at(-1);
+	assert.ok(stall);
+	stall!.fn();
+	await tick();
+	assert.equal(h.store.get(task.id)?.status, TASK_STATUS.TIMED_OUT);
+	assert.equal(h.store.get(task.id)?.error, "stalled for 4 min after: starting; stderr: Error: cannot bind provider socket");
+});
+
+test("stall after get_state and prompt responses records the prompt accepted stage", async () => {
+	const h = harness({ stallTimeoutMs: FOUR_MIN_MS });
+	const task = h.runner.run(request());
+	await tick();
+	assert.deepEqual(h.children[0].written.map((command) => command.type), ["get_state", "prompt"]);
+	assert.equal(h.store.get(task.id)?.lastStep, "prompt accepted");
+	const stall = h.timers.filter((timer) => timer.ms === FOUR_MIN_MS && !timer.cancelled).at(-1);
+	assert.ok(stall);
+	stall!.fn();
+	await tick();
+	assert.equal(h.store.get(task.id)?.error, "stalled for 4 min after: prompt accepted");
+});
+
+test("stderr tail bounds the child's raw output to 512 characters before stripping ANSI escapes", async () => {
+	const h = silentHarness(FOUR_MIN_MS);
+	const task = h.runner.run(request());
+	await tick();
+	const filler = "x".repeat(508);
+	(h.child().child.stderr as unknown as PassThrough).write(`${filler}OK`);
+	await tick();
+	const stall = h.timers.filter((timer) => timer.ms === FOUR_MIN_MS && !timer.cancelled).at(-1)!;
+	stall.fn();
+	await tick();
+	const expectedTail = `${"x".repeat(501)}OK`;
+	assert.equal(h.store.get(task.id)?.error, `stalled for 4 min after: starting; stderr: ${expectedTail}`);
+});
+
+test("child exit before agent_settled includes the stderr tail; a completed task never carries stderr", async () => {
+	const h = harness({ maxConcurrency: 2 });
+	const crashing = h.runner.run(request());
+	const completing = h.runner.run(request({ prompt: "finish clean" }));
+	await tick();
+	const crashChild = h.children[0];
+	const doneChild = h.children[1];
+	(crashChild.child.stderr as unknown as PassThrough).write("panic: provider unavailable");
+	await tick();
+	crashChild.exit(1);
+	await tick();
+	assert.equal(h.store.get(crashing.id)?.status, TASK_STATUS.FAILED);
+	assert.equal(h.store.get(crashing.id)?.error, "pi exited with code 1 before agent_settled; stderr: panic: provider unavailable");
+
+	(doneChild.child.stderr as unknown as PassThrough).write("noisy but irrelevant");
+	await tick();
+	doneChild.emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "final report" }], stopReason: "stop" }] });
+	doneChild.emit({ type: "agent_settled" });
+	await h.runner.waitFor(completing.id);
+	assert.equal(h.store.get(completing.id)?.status, TASK_STATUS.COMPLETED);
+	assert.equal(h.store.get(completing.id)?.error, null);
+});
+
+test("cancel(id, reason) records the given reason for a live and a queued task; cancelAll(reason) threads it", async () => {
+	const h = harness({ maxConcurrency: 1 });
+	const running = h.runner.run(request());
+	const queued = h.runner.run(request({ prompt: "queued work" }));
+	await tick();
+	assert.equal(h.store.get(queued.id)?.status, TASK_STATUS.QUEUED);
+	assert.equal(h.runner.cancel(queued.id, "stopped from the agents panel"), true);
+	assert.equal(h.store.get(queued.id)?.status, TASK_STATUS.CANCELLED);
+	assert.equal(h.store.get(queued.id)?.error, "stopped from the agents panel before start");
+	assert.equal(h.runner.cancel(running.id, "stopped from the agents panel"), true);
+	await tick();
+	assert.equal(h.store.get(running.id)?.status, TASK_STATUS.CANCELLED);
+	assert.equal(h.store.get(running.id)?.error, "stopped from the agents panel");
+
+	const h2 = harness({ maxConcurrency: 1 });
+	const runningTwo = h2.runner.run(request());
+	const queuedTwo = h2.runner.run(request({ prompt: "queued work" }));
+	await tick();
+	assert.equal(h2.runner.cancelAll("cancelled: parent session shut down"), 2);
+	await tick();
+	assert.equal(h2.store.get(runningTwo.id)?.error, "cancelled: parent session shut down");
+	assert.equal(h2.store.get(queuedTwo.id)?.error, "cancelled: parent session shut down before start");
+});
+
+test("earlier get_state and prompt responses cannot regress lastStep past a later child event", async () => {
+	const store = new TaskStore();
+	const timers: Array<{ fn: () => void; ms: number; cancelled: boolean }> = [];
+	let clock = 1000;
+	const fake = fakeChild();
+	fake.child.stdin.removeAllListeners("data"); // respond to get_state/prompt manually, out of order
+	const written: Array<Record<string, unknown>> = [];
+	fake.child.stdin.on("data", (chunk: Buffer) => written.push(JSON.parse(chunk.toString())));
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: FOUR_MIN_MS }, {
+		spawn: () => fake.child,
+		now: () => (clock += 1),
+		schedule: (fn, ms) => {
+			const timer = { fn, ms, cancelled: false };
+			timers.push(timer);
+			return () => {
+				timer.cancelled = true;
+			};
+		},
+		pi: { command: "pi", args: [] },
+	}, { askUser: async () => ({ cancelled: true }) });
+	const task = runner.run(request());
+	await tick();
+	assert.deepEqual(written.map((command) => command.type), ["get_state", "prompt"]);
+	// A later child event (a tool call) advances lastStep before either launch reply arrives.
+	fake.emit({ type: "tool_execution_start", toolCallId: "c1", toolName: "bash", args: {} });
+	await tick();
+	assert.equal(store.get(task.id)?.lastStep, "bash");
+	// The get_state and prompt responses arrive late; they must not regress the stage.
+	fake.emit({ type: "response", id: written[0]?.id, command: "get_state", success: true, data: { sessionFile: "/sessions/child.jsonl" } });
+	fake.emit({ type: "response", id: written[1]?.id, command: "prompt", success: true });
+	await tick();
+	assert.equal(store.get(task.id)?.lastStep, "bash", "a late get_state/prompt reply must not regress lastStep");
+});
+
 test("synchronous cancellation before dequeue never invokes the policy callback", async () => {
 	const h = harness(); let checks = 0;
 	const task = h.runner.run(request({ prepareResponseObservations: async () => { checks++; return true; } }));

package/tests/gentle-agents.test.ts

@@ -11,7 +11,7 @@ import { visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import gentleAgents, { agentRuntimePaths, agentsCollapseKey, agentsEnabled, agentsStopKey, agentsViewKey, answerThroughUi, completionText, legacySubagentsInstalled, type AgentsDeps } from "../extensions/gentle-agents.ts";
 import { historyDir, loadHistory, saveTask } from "../lib/agents-history.ts";
 import { STALE_COMPLETION_MS } from "../lib/agents-completion-delivery.ts";
-import { emptyThread, TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
+import { applyTaskEvent, emptyThread, TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
 import { NativePointerScope } from "../lib/native-pointer-region.ts";
 import { PresenceCursor, PresencePublisher, listPresence, readActivity } from "../lib/orchestrator-presence.ts";
 import { stripAnsi } from "../lib/terminal-theme.ts";
@@ -179,10 +179,11 @@ function deps(): { deps: Partial<AgentsDeps>; children: FakeChild[]; spawned: st
 	};
 }
 
-test("all nine subagent registrations own their transcript shell", () => {
+test("all ten subagent registrations own their transcript shell", () => {
 	const { pi, tools } = fakePi();
 	gentleAgents(pi, {}, deps().deps);
-	assert.equal(tools.size, 9);
+	assert.equal(tools.size, 10);
+	assert.deepEqual(tools.get("subagent_reconcile")?.parameters, { type: "object", additionalProperties: false, required: ["task_id"], properties: { task_id: { type: "string" } } });
 	for (const tool of tools.values()) assert.equal(tool.renderShell, "self", tool.name);
 });
 
@@ -1261,7 +1262,7 @@ test("subagent_list_agents and subagent_run in task mode launch a child with the
 	gentleAgents(pi, {}, harness.deps);
 	const { ctx, widget } = fakeContext();
 	await fire("session_start", ctx);
-	assert.deepEqual([...tools.keys()].sort(), ["subagent_cancel", "subagent_continue", "subagent_list_agents", "subagent_list_tasks", "subagent_reply", "subagent_result", "subagent_run", "subagent_send_message", "subagent_status"]);
+	assert.deepEqual([...tools.keys()].sort(), ["subagent_cancel", "subagent_continue", "subagent_list_agents", "subagent_list_tasks", "subagent_reconcile", "subagent_reply", "subagent_result", "subagent_run", "subagent_send_message", "subagent_status"]);
 	const listed = await tools.get("subagent_list_agents")!.execute("c0", {}, undefined, undefined, ctx);
 	assert.match(listed.content[0].text, /- explore \(global\): maps things/);
 
@@ -2141,6 +2142,81 @@ test("R1 malformed child grant denies tools even before/after failed session ini
 });
 
 
+test("public reconciliation replays retained authority, persists closure, and never exposes or starts the actor", async () => {
+	const fixtureHome = join(root, "remediation-reconcile");
+	const acquire = { workspaceRoot: cwd, changeName: "alpha", requestId: "retained-acquire", workUnit: "correct", evidenceGoal: "Observed correction", remediatesEvidenceRevision: `sha256:${"a".repeat(64)}` };
+	await saveTask(historyDir(fixtureHome), { id: "retained", agent: "sdd-remediate", cwd, status: "failed", createdAt: 1, sddRemediation: { acquire, acquireUncertain: true } } as never, emptyThread());
+	const h = fakePi(), runtime = deps(), calls = [];
+	gentleAgents(h.pi, {}, { ...runtime.deps, home: fixtureHome, nativeSdd: {
+		sddAttemptAcquire: async input => { calls.push(["acquire", structuredClone(input)]); return { state: "proceed", token: "private-token" }; },
+		sddAttemptSettle: async input => { calls.push(["settle", structuredClone(input)]); return { state: "complete" }; },
+	} as unknown as NativeReviewCli });
+	const { ctx } = fakeContext(); await h.fire("session_start", ctx);
+	const output = await h.tools.get("subagent_reconcile").execute("reconcile", { task_id: "retained" }, undefined, undefined, ctx);
+	assert.match(output.content[0].text, /reconciled/i);
+	assert.equal(JSON.stringify(output).includes("private-token"), false);
+	assert.deepEqual(calls[0], ["acquire", acquire]); assert.equal(calls[1][0], "settle");
+	assert.equal(runtime.spawned.length, 0);
+	const retained = (await loadHistory(historyDir(fixtureHome)))[0].task;
+	assert.equal(retained.sddRemediation.acquireUncertain, undefined);
+	assert.deepEqual(retained.sddRemediation.settlement, { state: "complete" });
+});
+
+test("durable reconciliation locks serialize independent extension instances sharing one tasksDir", async () => {
+	const fixtureHome = join(root, "remediation-reconcile-independent");
+	const id = "retained-independent";
+	const acquire = { workspaceRoot: cwd, changeName: "alpha", requestId: id, workUnit: "correct", evidenceGoal: "Observed correction" };
+	await saveTask(historyDir(fixtureHome), { id, agent: "sdd-remediate", cwd, status: "failed", createdAt: 1, sddRemediation: { acquire, acquireUncertain: true } } as never, emptyThread());
+	const first = fakePi(), second = fakePi(), runtime = deps();
+	let calls = 0, release!: (result: { state: "blocked" }) => void;
+	const pending = new Promise<{ state: "blocked" }>(resolve => { release = resolve; });
+	const native = { sddAttemptAcquire: async () => { calls++; return calls === 1 ? pending : { state: "blocked" }; } } as unknown as NativeReviewCli;
+	gentleAgents(first.pi, {}, { ...runtime.deps, home: fixtureHome, nativeSdd: native });
+	gentleAgents(second.pi, {}, { ...runtime.deps, home: fixtureHome, nativeSdd: native });
+	const firstContext = fakeContext(), secondContext = fakeContext();
+	await first.fire("session_start", firstContext.ctx); await second.fire("session_start", secondContext.ctx);
+	const running = first.tools.get("subagent_reconcile")!.execute("first", { task_id: id }, undefined, undefined, firstContext.ctx);
+	await eventually(() => calls === 1, "the first instance must reach native acquire while holding the lock");
+	await assert.rejects(second.tools.get("subagent_reconcile")!.execute("second", { task_id: id }, undefined, undefined, secondContext.ctx), /busy|active|already being reconciled/i);
+	assert.equal(calls, 1, "a busy filesystem lock fails before native acquire");
+	release({ state: "blocked" }); await running;
+	await first.fire("session_shutdown", firstContext.ctx); await second.fire("session_shutdown", secondContext.ctx);
+});
+
+test("reconciliation reloads a stale local task and preserves the retained disk thread", async () => {
+	const fixtureHome = join(root, "remediation-reconcile-reload");
+	const id = "retained-reload";
+	const oldAcquire = { workspaceRoot: cwd, changeName: "alpha", requestId: "old", workUnit: "old", evidenceGoal: "old" };
+	const freshAcquire = { workspaceRoot: cwd, changeName: "alpha", requestId: "fresh", workUnit: "fresh", evidenceGoal: "fresh" };
+	await saveTask(historyDir(fixtureHome), { id, agent: "sdd-remediate", cwd, status: "failed", createdAt: 1, sddRemediation: { acquire: oldAcquire, acquireUncertain: true } } as never, applyTaskEvent(emptyThread(), { type: TASK_EVENT.NOTE, text: "old thread" }));
+	const h = fakePi(), runtime = deps(), seen: unknown[] = [];
+	gentleAgents(h.pi, {}, { ...runtime.deps, home: fixtureHome, nativeSdd: { sddAttemptAcquire: async input => { seen.push(structuredClone(input)); return { state: "blocked" }; } } as unknown as NativeReviewCli });
+	const { ctx } = fakeContext(); await h.fire("session_start", ctx);
+	await h.tools.get("subagent_status")!.execute("status", { task_id: id }, undefined, undefined, ctx);
+	const freshThread = applyTaskEvent(emptyThread(), { type: TASK_EVENT.NOTE, text: "fresh thread" });
+	await saveTask(historyDir(fixtureHome), { id, agent: "sdd-remediate", cwd, status: "failed", createdAt: 1, sddRemediation: { acquire: freshAcquire, acquireUncertain: true } } as never, freshThread);
+	await h.tools.get("subagent_reconcile")!.execute("reconcile", { task_id: id }, undefined, undefined, ctx);
+	assert.deepEqual(seen, [freshAcquire], "native receives the force-reloaded retained request");
+	const stored = (await loadHistory(historyDir(fixtureHome))).find(entry => entry.task.id === id)!;
+	assert.deepEqual(stored.thread.items, freshThread.items, "persistence retains the exact disk thread, not the stale store thread");
+	await h.fire("session_shutdown", ctx);
+});
+
+test("reconciliation releases the durable lock after native failure", async () => {
+	const fixtureHome = join(root, "remediation-reconcile-failure");
+	const id = "retained-failure";
+	const acquire = { workspaceRoot: cwd, changeName: "alpha", requestId: id, workUnit: "correct", evidenceGoal: "Observed correction" };
+	await saveTask(historyDir(fixtureHome), { id, agent: "sdd-remediate", cwd, status: "failed", createdAt: 1, sddRemediation: { acquire, acquireUncertain: true } } as never, emptyThread());
+	const h = fakePi(), runtime = deps(); let calls = 0;
+	gentleAgents(h.pi, {}, { ...runtime.deps, home: fixtureHome, nativeSdd: { sddAttemptAcquire: async () => { calls++; if (calls === 1) throw new TypeError("native failure"); return { state: "blocked" }; } } as unknown as NativeReviewCli });
+	const { ctx } = fakeContext(); await h.fire("session_start", ctx);
+	await assert.rejects(h.tools.get("subagent_reconcile")!.execute("failed", { task_id: id }, undefined, undefined, ctx), /native failure/);
+	const recovered = await h.tools.get("subagent_reconcile")!.execute("retry", { task_id: id }, undefined, undefined, ctx);
+	assert.match(recovered.content[0].text, /reconciled/i);
+	assert.equal(calls, 2, "the second attempt acquires after finally released the first lock");
+	await h.fire("session_shutdown", ctx);
+});
+
 test("R3/R4 host reload refuses retained acquire/actor uncertainty without another launch", async () => {
 	for (const actorClaimed of [false, true, "blocked", "complete"]) {
 		const normal = typeof actorClaimed === "string";

package/tests/gentle-ai-binary.test.ts

@@ -97,7 +97,7 @@ async function writeWindowsSourceBinary(packageRoot: string): Promise<{ binaryPa
 		method: "go-sumdb-source-build",
 		package: "github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai",
 		module: "github.com/gentleman-programming/gentle-ai/v2",
-		tag: "v2.8.2",
+		tag: "v2.9.0",
 		architecture: process.arch === "x64" ? "x64" : "arm64",
 		binarySha256: createHash("sha256").update(binary).digest("hex"),
 		moduleChecksum: GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,