gentle-pi 2.7.0 → 3.0.0

package/lib/agent-profile-pin.ts

@@ -0,0 +1,336 @@
+// Per-repository agent-model profile pins.
+//
+// `/gentle:profiles` applies a profile globally: it rewrites `models.json`, the
+// agent frontmatter, `subagents.json`, and the orchestrator in `settings.json`.
+// Two repositories worked in parallel therefore fight over one global routing.
+// A pin re-anchors only the subagent routing of one repository to a named profile
+// from the global store, at launch time, without materialising anything:
+//
+//   local pin         <git-common-dir>/gentle-ai/profile-pin.json
+//   repo declaration  <worktree-root>/.pi/gentle-ai/profile.json
+//
+// The local pin sits inside the Git common directory, so it is invisible to Git
+// and shared by every worktree of the clone; the repo declaration is an ordinary
+// tracked file, so a team can commit the routing a repository expects. Precedence
+// is local, then repo, then no pin — and "no pin" is exactly today's behaviour, so
+// an unreadable, invalid, or stale layer is skipped instead of aborting a launch.
+//
+// The orchestrator is deliberately out of scope: `profileRoleEntries` drops the
+// reserved orchestrator key, so a pin never moves the orchestrator model.
+//
+// `evaluateProfilePin` is the single precedence rule. The launch resolver below and
+// the `/gentle:profiles` panel both go through it, so the layer a launch uses and the
+// layer the panel reports can never disagree.
+
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { isValidProfileName, profileRoleEntries, profilesFilePath, readProfilesFileResult, writeJsonFileAtomicallySync } from "./agent-profiles.ts";
+import type { AgentModelConfig } from "./model-routing-authority.ts";
+import { resolveSessionWorktreeWithGit, type WorktreeIdentity, type WorktreeResolver } from "./session-worktree-registry.ts";
+
+export const PROFILE_PIN_KIND = "gentle-pi.agent_model_profile_pin";
+export const PROFILE_PIN_VERSION = 1;
+// Ordered root .gitignore rules that expose only the committable declaration.
+// Git cannot re-include a file while an excluded parent directory remains hidden,
+// so each parent is reopened and its unrelated children are ignored again.
+export const REPO_PROFILE_DECLARATION_GITIGNORE_RULES = [
+	"!.pi/",
+	".pi/*",
+	"!.pi/gentle-ai/",
+	".pi/gentle-ai/*",
+	"!.pi/gentle-ai/profile.json",
+] as const;
+
+export interface AgentProfilePinFile {
+	kind: typeof PROFILE_PIN_KIND;
+	version: typeof PROFILE_PIN_VERSION;
+	profile: string;
+}
+
+export type ProfilePinSource = "local" | "repo";
+
+/**
+ * What one pin file holds. `missing` is an absent file; `invalid` is a file that
+ * exists but does not hold a pin this version understands. Collapsing the two hides
+ * a broken pin behind "no pin", so the reader reports which one it found and the
+ * panel can say so instead of silently changing nothing.
+ */
+export type ProfilePinReadResult =
+	| { status: "missing" }
+	| { status: "invalid" }
+	| { status: "valid"; profile: string };
+
+/** Which pin files exist for a directory, and what each of them holds. */
+export interface ProfilePinStatus {
+	root: string;
+	commonDir: string;
+	localPath: string;
+	repoPath: string;
+	local: ProfilePinReadResult;
+	repo: ProfilePinReadResult;
+}
+
+/** One pin layer, named by its path, without the name it stores. */
+export interface ProfilePinLayerIssue {
+	source: ProfilePinSource;
+	path: string;
+}
+
+/** One pin layer whose stored name the profiles store no longer defines. */
+export interface ProfilePinStaleIssue extends ProfilePinLayerIssue {
+	profile: string;
+}
+
+/** The layer the launch resolves, when one does. */
+export interface ProfilePinSelection {
+	source: ProfilePinSource;
+	profile: string;
+	path: string;
+}
+
+/**
+ * What both layers amount to: the layer that wins (if any), every layer that is not
+ * a pin file, and every layer that names a profile the store dropped.
+ */
+export interface ProfilePinEvaluation {
+	winner?: ProfilePinSelection;
+	invalid: ProfilePinLayerIssue[];
+	stale: ProfilePinStaleIssue[];
+}
+
+/** A pin that resolved to routing the launch will actually use. */
+export interface ProfilePinResolution extends ProfilePinSelection {
+	modelProfiles: AgentModelConfig;
+	/** Both layers as they were read, so a caller can report what was skipped and why. */
+	status: ProfilePinStatus;
+	invalidLayers: ProfilePinLayerIssue[];
+	staleLayers: ProfilePinStaleIssue[];
+}
+
+export function localProfilePinPath(commonDir: string): string {
+	return join(commonDir, "gentle-ai", "profile-pin.json");
+}
+
+export function repoProfileDeclarationPath(worktreeRoot: string): string {
+	return join(worktreeRoot, ".pi", "gentle-ai", "profile.json");
+}
+
+// Fixed key order plus a trailing newline keeps the artifact byte-identical for the
+// same profile, so a committed declaration does not churn on every write.
+export function serializeProfilePin(profile: string): string {
+	const file: AgentProfilePinFile = {
+		kind: PROFILE_PIN_KIND,
+		version: PROFILE_PIN_VERSION,
+		profile,
+	};
+	return `${JSON.stringify(file, null, 2)}\n`;
+}
+
+/**
+ * Value-level normalizer: the profile name a parsed pin file holds, or `undefined`
+ * when the value is not a pin this version understands. The text parser below reuses
+ * it, so a value and its serialized text can never disagree about what is a pin.
+ */
+export function normalizeProfilePin(value: unknown): string | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	if (record.kind !== PROFILE_PIN_KIND || record.version !== PROFILE_PIN_VERSION) {
+		return undefined;
+	}
+	// Only a store-legal profile name can ever resolve, so an unparseable name is
+	// rejected here rather than reaching the store lookup.
+	if (!isValidProfileName(record.profile)) return undefined;
+	return record.profile;
+}
+
+export type ProfilePinParseResult =
+	| { status: "valid"; profile: string }
+	| { status: "invalid" };
+
+export function parseProfilePinText(text: string): ProfilePinParseResult {
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return { status: "invalid" };
+	}
+	const profile = normalizeProfilePin(value);
+	return profile === undefined ? { status: "invalid" } : { status: "valid", profile };
+}
+
+export function readProfilePinResult(path: string): ProfilePinReadResult {
+	if (!existsSync(path)) return { status: "missing" };
+	try {
+		return parseProfilePinText(readFileSync(path, "utf8"));
+	} catch {
+		// A file that exists but cannot be read is not "no pin": it is a broken pin.
+		return { status: "invalid" };
+	}
+}
+
+/**
+ * The stored name, or `undefined` for both "missing" and "invalid". Prefer
+ * `readProfilePinResult` where the difference matters; this stays for callers that
+ * only want the name.
+ */
+export function readProfilePin(path: string): string | undefined {
+	const result = readProfilePinResult(path);
+	return result.status === "valid" ? result.profile : undefined;
+}
+
+let profilePinWorktreeResolver: WorktreeResolver = resolveSessionWorktreeWithGit;
+
+/**
+ * Test seam, mirroring the other injectable seams in `lib/`: the `/gentle:profiles`
+ * panel resolves the pin through the ambient resolver, and a test must not depend
+ * on where the test runner's working directory happens to sit. The launch path
+ * passes its own resolver instead, so it needs no seam.
+ */
+export function setProfilePinWorktreeResolverForTesting(resolver?: WorktreeResolver): void {
+	profilePinWorktreeResolver = resolver ?? resolveSessionWorktreeWithGit;
+}
+
+function gentlePiWorktreeIdentity(
+	cwd: string,
+	resolveWorktree: WorktreeResolver,
+): WorktreeIdentity | undefined {
+	let identity: WorktreeIdentity | undefined;
+	try {
+		identity = resolveWorktree(cwd, cwd);
+	} catch {
+		identity = undefined;
+	}
+	return identity;
+}
+
+/**
+ * Read both pin layers for a directory. This never throws and never writes: an
+ * absent, unreadable, or invalid pin file is reported as such, so a broken pin
+ * cannot block the panel or a launch.
+ */
+export function readProfilePinStatus(
+	cwd: string,
+	resolveWorktree: WorktreeResolver = profilePinWorktreeResolver,
+): ProfilePinStatus | undefined {
+	const identity = gentlePiWorktreeIdentity(cwd, resolveWorktree);
+	if (!identity) return undefined;
+	const localPath = localProfilePinPath(identity.commonDir);
+	const repoPath = repoProfileDeclarationPath(identity.root);
+	return {
+		root: identity.root,
+		commonDir: identity.commonDir,
+		localPath,
+		repoPath,
+		local: readProfilePinResult(localPath),
+		repo: readProfilePinResult(repoPath),
+	};
+}
+
+export function writeProfilePinSync(path: string, profile: string): void {
+	if (!isValidProfileName(profile)) {
+		throw new Error(`Invalid profile name: ${JSON.stringify(profile)}.`);
+	}
+	writeJsonFileAtomicallySync(path, serializeProfilePin(profile));
+}
+
+/**
+ * Remove one pin layer. Pinning is a toggle: the key that sets a layer clears the
+ * same layer, and a missing file is already the desired state.
+ */
+export function clearProfilePinSync(path: string): void {
+	try {
+		unlinkSync(path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+}
+
+function hasProfile(profiles: Record<string, unknown>, name: string): boolean {
+	return Object.prototype.hasOwnProperty.call(profiles, name);
+}
+
+function profilePinLayers(
+	status: ProfilePinStatus,
+): Array<{ source: ProfilePinSource; path: string; read: ProfilePinReadResult }> {
+	return [
+		{ source: "local", path: status.localPath, read: status.local },
+		{ source: "repo", path: status.repoPath, read: status.repo },
+	];
+}
+
+/**
+ * The single precedence rule, shared by the launch resolver and the panel: the first
+ * layer, in local-then-repo order, whose file holds a legal name the store still
+ * defines wins. Everything else is reported instead of hidden, so the panel can name
+ * a file that is not a pin (`invalid`) separately from a name the store dropped
+ * (`stale`), and neither masks a lower layer that does resolve.
+ */
+export function evaluateProfilePin(
+	status: ProfilePinStatus | undefined,
+	profiles: Record<string, unknown>,
+): ProfilePinEvaluation {
+	const evaluation: ProfilePinEvaluation = { invalid: [], stale: [] };
+	if (!status) return evaluation;
+	for (const layer of profilePinLayers(status)) {
+		if (layer.read.status === "missing") continue;
+		if (layer.read.status === "invalid") {
+			evaluation.invalid.push({ source: layer.source, path: layer.path });
+			continue;
+		}
+		if (evaluation.winner !== undefined) {
+			// Precedence is already decided; the lower layer is only reported.
+			if (!hasProfile(profiles, layer.read.profile)) {
+				evaluation.stale.push({ source: layer.source, path: layer.path, profile: layer.read.profile });
+			}
+			continue;
+		}
+		if (hasProfile(profiles, layer.read.profile)) {
+			evaluation.winner = { source: layer.source, profile: layer.read.profile, path: layer.path };
+		} else {
+			evaluation.stale.push({ source: layer.source, path: layer.path, profile: layer.read.profile });
+		}
+	}
+	return evaluation;
+}
+
+export interface ProfilePinResolveOptions {
+	cwd: string;
+	configHome: string;
+	resolveWorktree?: WorktreeResolver;
+}
+
+/**
+ * The routing a launch should use, or `undefined` when no pin applies.
+ *
+ * Layers are tried in precedence order by `evaluateProfilePin`, and the first usable
+ * one wins: the pin file holds a legal name AND the global store still defines that
+ * profile. Everything else — no pin file, invalid JSON, a name the store no longer
+ * defines — is skipped, so a stale local pin cannot mask a valid repository
+ * declaration and a stale chain degrades to today's global routing. The resolution
+ * also carries both layers as read, so a caller can report what was skipped.
+ */
+export function resolveProfilePin(
+	options: ProfilePinResolveOptions,
+): ProfilePinResolution | undefined {
+	const status = readProfilePinStatus(options.cwd, options.resolveWorktree);
+	if (!status) return undefined;
+	if (status.local.status === "missing" && status.repo.status === "missing") return undefined;
+	const store = readProfilesFileResult(profilesFilePath(options.configHome));
+	const profiles: Record<string, AgentModelConfig> = store.status === "valid" ? store.file.profiles : {};
+	const evaluation = evaluateProfilePin(status, profiles);
+	const winner = evaluation.winner;
+	if (winner === undefined) return undefined;
+	const config = profiles[winner.profile];
+	if (config === undefined) return undefined;
+	return {
+		source: winner.source,
+		profile: winner.profile,
+		path: winner.path,
+		modelProfiles: Object.fromEntries(
+			profileRoleEntries(config).map(([agent, entry]) => [agent, { ...entry }]),
+		),
+		status,
+		invalidLayers: evaluation.invalid,
+		staleLayers: evaluation.stale,
+	};
+}

package/lib/agent-profiles.ts

@@ -406,12 +406,18 @@ export interface ProfileListItem {
 	description: string;
 }
 
-export function buildProfileListItems(file: AgentProfilesFile): ProfileListItem[] {
+export function buildProfileListItems(
+	file: AgentProfilesFile,
+	pinned?: string,
+): ProfileListItem[] {
 	return Object.entries(file.profiles).map(([name, config]) => {
 		const roles = profileRoleEntries(config).length;
+		const active = name === file.active ? `${name} (active)` : name;
 		return {
 			id: name,
-			label: name === file.active ? `${name} (active)` : name,
+			// A pinned profile is the one this repository launches with, which is not the
+			// same thing as the globally active profile, so both are named.
+			label: name === pinned ? `${active} (pinned)` : active,
 			description: `${roles} ${roles === 1 ? "role" : "roles"}`,
 		};
 	});
@@ -506,12 +512,22 @@ export function readProfilesFileResult(path: string): ProfilesFileReadResult {
 }
 
 /**
- * Replace the store through a sibling temp file and a rename. A direct write that
- * is interrupted leaves truncated JSON, which `readProfilesFileResult` must then
- * reject as unreadable, so the destination is only ever swapped for a complete
- * file and the temp file is removed on every failure path.
+ * Replace a JSON store through a sibling temp file and a rename. A direct write
+ * that is interrupted leaves truncated JSON, which the readers must then reject as
+ * unreadable, so the destination is only ever swapped for a complete file and the
+ * temp file is removed on every failure path. Shared by the profiles store and the
+ * per-repository profile pin so both stores keep the same atomicity guarantee.
  */
-export function writeProfilesFileSync(path: string, file: AgentProfilesFile): void {
+export function writeJsonFileAtomicallySync(path: string, text: string): void {
+	// Replacing a file with identical bytes is not a change, so it is skipped instead
+	// of churning the mtime. Pin writes are the reason this matters: re-applying the
+	// profile a repository already pins must not touch the pin file. An unreadable or
+	// missing destination simply falls through to the atomic write below.
+	try {
+		if (readFileSync(path, "utf8") === text) return;
+	} catch {
+		// Fall through: the file is absent or not readable as text.
+	}
 	mkdirSync(dirname(path), { recursive: true });
 	const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
 	const descriptor = openSync(
@@ -525,7 +541,7 @@ export function writeProfilesFileSync(path: string, file: AgentProfilesFile): vo
 	// path.
 	const failures: unknown[] = [];
 	try {
-		writeFileSync(descriptor, serializeProfilesFile(file));
+		writeFileSync(descriptor, text);
 	} catch (error) {
 		failures.push(error);
 	}
@@ -548,3 +564,7 @@ export function writeProfilesFileSync(path: string, file: AgentProfilesFile): vo
 	}
 	if (failures.length > 0) throw failures[0];
 }
+
+export function writeProfilesFileSync(path: string, file: AgentProfilesFile): void {
+	writeJsonFileAtomicallySync(path, serializeProfilesFile(file));
+}

package/lib/agents-config.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { THINKING_LEVELS as ROUTING_THINKING_LEVELS, type ThinkingLevel as RoutingThinkingLevel } from "./model-routing-authority.ts";
+import { THINKING_LEVELS as ROUTING_THINKING_LEVELS, type AgentModelConfig, type ThinkingLevel as RoutingThinkingLevel } from "./model-routing-authority.ts";
 
 // Gentle Agents configuration. Agent definitions are markdown files with YAML
 // frontmatter (the format gentle-ai installs) and runtime settings come from
@@ -70,6 +70,7 @@ export interface AgentsConfig {
 	defaultMode: AgentMode;
 	modelProfiles: Record<string, ModelProfile>;
 	stallTimeoutMs: number;
+	toolStallTimeoutMs: number;
 	maxConcurrency: number;
 	historyMaxTasks: number;
 }
@@ -104,6 +105,7 @@ export interface Frontmatter {
 }
 
 const DEFAULT_STALL_TIMEOUT_MS = 4 * 60_000;
+const DEFAULT_TOOL_STALL_TIMEOUT_MS = 30 * 60_000;
 const DEFAULT_MAX_CONCURRENCY = 5;
 const DEFAULT_HISTORY_MAX_TASKS = 200;
 const THINKING_LEVELS: readonly string[] = ROUTING_THINKING_LEVELS;
@@ -263,6 +265,7 @@ export function parseAgentsConfig(global: RawConfig, project: RawConfig): Agents
 	const merged: Record<string, unknown> = { ...(global ?? {}), ...(project ?? {}) };
 	const thinking = parseThinking(merged.default_effort ?? merged.default_thinking_level ?? merged.default_thinking);
 	const mode = parseMode(merged.default_mode);
+	const stallTimeoutMs = positiveInteger(merged.stall_timeout_ms, DEFAULT_STALL_TIMEOUT_MS);
 	return {
 		defaultModel: parseModelRef(merged.default_model),
 		defaultThinking: thinking !== undefined && THINKING_LEVELS.includes(thinking) ? (thinking as ThinkingLevel) : undefined,
@@ -270,7 +273,11 @@ export function parseAgentsConfig(global: RawConfig, project: RawConfig): Agents
 		modelProfiles: mergeProfiles(parseProfiles(global?.model_profiles), parseProfiles(project?.model_profiles)),
 		// `timeout_ms` remains accepted as an inert legacy key so existing JSON
 		// files load normally; only silence is bounded by `stall_timeout_ms`.
-		stallTimeoutMs: positiveInteger(merged.stall_timeout_ms, DEFAULT_STALL_TIMEOUT_MS),
+		stallTimeoutMs,
+		// An announced tool call in flight is live work, not silence, so it gets a
+		// longer ceiling; the idle budget still bounds a genuinely quiet child and
+		// remains the hard floor for this one.
+		toolStallTimeoutMs: Math.max(positiveInteger(merged.tool_stall_timeout_ms, DEFAULT_TOOL_STALL_TIMEOUT_MS), stallTimeoutMs),
 		maxConcurrency: positiveInteger(merged.max_concurrency, DEFAULT_MAX_CONCURRENCY),
 		historyMaxTasks: positiveInteger(merged.history_max_tasks, DEFAULT_HISTORY_MAX_TASKS),
 	};
@@ -290,6 +297,21 @@ export function loadAgentsConfig(roots: DiscoveryRoots): AgentsConfig {
 	return parseAgentsConfig(readJson(join(profileRoot(roots), "subagents.json")), readJson(join(roots.cwd, ".pi", "subagents.json")));
 }
 
+export function withPinnedModelProfiles(
+	config: AgentsConfig,
+	pinned: AgentModelConfig | undefined,
+): AgentsConfig {
+	// No pin, and no pin-shaped input, both mean today's routing: a repository that
+	// never opted in must not observe any difference.
+	if (pinned === undefined) return config;
+	// The profile replaces subagent routing wholesale. Merging would let routing
+	// materialised in `subagents.json` by a previous global profile leak into a
+	// repository that pinned a different one, which is the exact conflict a pin
+	// exists to remove. Only `modelProfiles` moves: the orchestrator routing and
+	// every operational default stay global.
+	return { ...config, modelProfiles: parseProfiles(pinned) };
+}
+
 function pick<T>(candidates: Array<[T | undefined, ProfileSource]>): [T | undefined, ProfileSource] {
 	return candidates.find(([value]) => value !== undefined) ?? [undefined, PROFILE_SOURCE.UNRESOLVED];
 }

package/lib/agents-history.ts

@@ -1,9 +1,5 @@
-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 os from "node:os";
-import { dirname, join } from "node:path";
+import { 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,20 +12,6 @@ export interface StoredTask {
 	thread: TaskThread;
 }
 
-export function remediationUnresolved(task: TaskRecord): boolean {
-	const state = task.sddRemediation;
-	if (!state) return false;
-	if (state.acquireUncertain || state.settlementUncertain) return true;
-	// 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 ?? "");
-}
-
 const FILE_SUFFIX = ".json";
 const SAFE_ID = /^[a-z0-9-]+$/i;
 
@@ -42,83 +24,6 @@ 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";
@@ -169,7 +74,8 @@ export async function loadHistory(dir: string): Promise<StoredTask[]> {
 // Keep the newest `maxTasks` files; the rest go. Returns how many were removed.
 export async function pruneHistory(dir: string, maxTasks: number): Promise<number> {
 	const stored = await loadHistory(dir);
-	const extra = stored.filter(({ task }) => !remediationUnresolved(task)).slice(Math.max(0, maxTasks));
+	// Preserve historical remediation payloads without interpreting or replaying their retired ledger.
+	const extra = stored.filter(({ task }) => task.sddRemediation === undefined).slice(Math.max(0, maxTasks));
 	await Promise.all(extra.map((entry) => rm(fileFor(dir, entry.task.id), { force: true })));
 	return extra.length;
 }

package/lib/agents-keys.ts

@@ -0,0 +1,27 @@
+// Shortcut helpers for the Gentle Agents view. Pure (no Pi API), so both
+// extensions/gentle-agents.ts (which owns the view) and other extensions
+// that only need the key mapping (extensions/gentle-shell.ts, for the
+// command palette's shortcut hints) can depend on it without importing one
+// another.
+
+const COLLAPSE_KEY_DEFAULT = "ctrl+shift+a";
+const VIEW_KEY_DEFAULT = "alt+a";
+const STOP_KEY_DEFAULT = "alt+s";
+
+export function agentsViewKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const value = env.GENTLE_PI_AGENTS_VIEW_KEY?.trim();
+	if (value === undefined) return VIEW_KEY_DEFAULT;
+	return value === "" || value.toLowerCase() === "off" ? undefined : value;
+}
+
+export function agentsCollapseKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const value = env.GENTLE_PI_AGENTS_KEY?.trim();
+	if (value === undefined) return COLLAPSE_KEY_DEFAULT;
+	return value === "" || value.toLowerCase() === "off" ? undefined : value;
+}
+
+export function agentsStopKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const value = env.GENTLE_PI_AGENTS_STOP_KEY?.trim();
+	if (value === undefined) return STOP_KEY_DEFAULT;
+	return value === "" || value.toLowerCase() === "off" ? undefined : value;
+}

package/lib/agents-protocol.ts

@@ -1,5 +1,3 @@
-import type { RemediationObservations, RemediationScope } from "./agents-runner.ts";
-import type { NativeSddAcquireRequest, NativeSddSettleRequest, NativeSddAttemptResult } from "./native-review-cli.ts";
 import { sanitizeTerminalText } from "./terminal-theme.ts";
 
 // Gentle Agents protocol. A child pi process streams RPC events; the host
@@ -110,20 +108,9 @@ export interface TaskThread {
 	limits: ThreadLimits;
 }
 
-export interface RemediationTaskState extends RemediationObservations {
-	scope?: RemediationScope;
-	acquire: NativeSddAcquireRequest;
-	token?: string;
-	acquireResult?: NativeSddAttemptResult;
-	acquireUncertain?: boolean;
-	actorClaimed?: boolean;
-	settle?: NativeSddSettleRequest;
-	settlement?: NativeSddAttemptResult;
-	settlementUncertain?: boolean;
-}
-
 export interface TaskRecord {
-	sddRemediation?: RemediationTaskState;
+	/** Retained legacy payload, never interpreted or replayed as launch authority. */
+	sddRemediation?: unknown;
 	/** Exact runtime-generated SDD preflight block retained only for continuation transport. */
 	sddPreflightContext?: string;
 	id: string;