gentle-pi 4.3.0 → 4.4.0

package/extensions/session-scratch.ts

@@ -15,9 +15,11 @@ import {
 	isProtectedPath,
 	isSessionScratchName,
 	isWithin,
+	LEDGER_ARTIFACTS_CAP,
 	LEDGER_VERSION,
 	ledgerPath,
 	listLedgers,
+	listLedgersSync,
 	liveSubagentScratch,
 	processStartToken,
 	readLedger,
@@ -32,6 +34,7 @@ import {
 	type ScratchLedger,
 	type StoredLedger,
 	writeLedger,
+	writeLedgerSync,
 } from "../lib/session-scratch.ts";
 
 // Session scratch and artifact ledger (odd/tasks/session-scratch-ledger.md):
@@ -92,10 +95,18 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 	const tempVariables = (options.platform ?? process.platform) === "win32" ? ["TMPDIR", "TMP", "TEMP"] : ["TMPDIR"];
 	const configHome = () => options.configHome ?? gentlePiConfigHome(env);
 
-	const persist = (path: string, ledger: ScratchLedger) => {
+	const persist = async (path: string, ledger: ScratchLedger) => {
 		try {
 			if (ledger.scratchDir === null && ledger.artifacts.length === 0) deleteLedger(path);
-			else writeLedger(path, ledger);
+			else await writeLedger(path, ledger);
+		} catch { /* Best effort: an unwritable config home keeps the session running. */ }
+	};
+	// The shutdown path stays synchronous: its callers (tests/agents-runner.ts, and any
+	// handler consumer that does not await) read its post-conditions right after it runs.
+	const persistSync = (path: string, ledger: ScratchLedger) => {
+		try {
+			if (ledger.scratchDir === null && ledger.artifacts.length === 0) deleteLedger(path);
+			else writeLedgerSync(path, ledger);
 		} catch { /* Best effort: an unwritable config home keeps the session running. */ }
 	};
 	// Paths the runtime never records or removes, whatever a ledger says.
@@ -121,26 +132,28 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 	const endSession = (session: ActiveSession) => {
 		const { ledger } = session;
 		// A running or quarantined subagent's TMPDIR stays; the scratch then stays in the ledger for a later sweep.
-		const removal = removeSessionScratch(ledger, heldBy(listLedgers(configHome()))(session.path, ledger), { ownRoot: ledger.tempRoot ?? undefined, liveSubagentDirs: subagentDirs() });
+		const removal = removeSessionScratch(ledger, heldBy(listLedgersSync(configHome()))(session.path, ledger), { ownRoot: ledger.tempRoot ?? undefined, liveSubagentDirs: subagentDirs() });
 		if (removal === "removed" || removal === "absent") ledger.scratchDir = null;
 		for (const [key, value] of Object.entries(ledger.inherited)) {
 			if (value === null) delete env[key];
 			else env[key] = value;
 		}
-		persist(session.path, ledger);
+		persistSync(session.path, ledger);
 		activeSessions.delete(env);
 		pending.clear();
 	};
 
 	// S5(b): scratch of ended sessions past the grace period; their artifacts stay for the command.
+	// The startup sweep stays synchronous: session_start's callers (tests/agents-runner.ts) read
+	// its post-conditions right after it runs, without awaiting the handler.
 	const sweep = (ownPath: string) => {
-		const ledgers = listLedgers(configHome());
+		const ledgers = listLedgersSync(configHome());
 		const held = heldBy(ledgers);
 		for (const { path, ledger, mtimeMs } of ledgers) {
 			if (path === ownPath || isLive(ledger) || now() - mtimeMs < graceMs) continue;
 			const artifacts = ledger.artifacts.filter((artifact) => { try { lstatSync(artifact.path); return true; } catch { return false; } });
 			const removal = ledger.scratchDir === null ? "absent" : removeSessionScratch(ledger, held(path, { ...ledger, artifacts }), { ownRoot: ownRoot(), liveSubagentDirs: subagentDirs() });
-			persist(path, { ...ledger, scratchDir: removal === "removed" || removal === "absent" ? null : ledger.scratchDir, artifacts });
+			persistSync(path, { ...ledger, scratchDir: removal === "removed" || removal === "absent" ? null : ledger.scratchDir, artifacts });
 		}
 	};
 
@@ -152,6 +165,8 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 		return !!current && [resolve(current), realTempRoot(current)].some((dir) => dir !== undefined && isWithin(dir, ledger.scratchDir!));
 	};
 
+	// The startup path stays synchronous, like the shutdown path: its callers
+	// (tests/agents-runner.ts) read its post-conditions without awaiting the handler.
 	const startSession = (ctx: ExtensionContext, reason: string) => {
 		const sessionId = ctx.sessionManager.getSessionId?.();
 		if (!sessionId) return;
@@ -162,7 +177,7 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 		const previous = readLedger(path);
 		if (previous && isLiveScratch(previous)) {
 			activeSessions.set(env, { sessionId, path, ledger: previous });
-			persist(path, previous);
+			persistSync(path, previous);
 			sweep(path);
 			return;
 		}
@@ -202,11 +217,11 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 		};
 		// A scratch of this process is never removed at startup: it may still be in use.
 		if (previous?.scratchDir && previous.scratchDir !== scratchDir && previous.pid !== process.pid && !isLive(previous)) {
-			const held = heldBy(listLedgers(configHome()))(path, ledger);
+			const held = heldBy(listLedgersSync(configHome()))(path, ledger);
 			removeSessionScratch(previous, scratchDir ? [...held, scratchDir] : held, { ownRoot: ownRoot(), liveSubagentDirs: subagentDirs() });
 		}
 		activeSessions.set(env, { sessionId, path, ledger });
-		persist(path, ledger);
+		persistSync(path, ledger);
 		sweep(path);
 	};
 
@@ -222,8 +237,10 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 		if (absent.length > 0) pending.set(toolCallId, absent);
 	};
 
-	// S4: the noted destinations that a successful command created.
-	const capture = (targets: readonly ArtifactTarget[], command: string) => {
+	// S4: the noted destinations that a successful command created. The ledger keeps
+	// only the most recent artifacts, evicting the oldest first, so a long session's
+	// ledger file stays bounded.
+	const capture = async (targets: readonly ArtifactTarget[], command: string) => {
 		const session = activeSessions.get(env);
 		if (!session) return;
 		const { ledger } = session;
@@ -238,22 +255,24 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 			ledger.artifacts.push({ kind: target.kind, path, command, recordedAt: new Date(now()).toISOString() });
 			changed = true;
 		}
-		if (changed) persist(session.path, ledger);
+		if (!changed) return;
+		if (ledger.artifacts.length > LEDGER_ARTIFACTS_CAP) ledger.artifacts = ledger.artifacts.slice(-LEDGER_ARTIFACTS_CAP);
+		await persist(session.path, ledger);
 	};
 
-	const endedLedgers = (ownPath: string | undefined) =>
-		listLedgers(configHome()).filter(({ path, ledger }) => path !== ownPath && !isLive(ledger));
+	const endedLedgers = async (ownPath: string | undefined) =>
+		(await listLedgers(configHome())).filter(({ path, ledger }) => path !== ownPath && !isLive(ledger));
 
 	const describe = (artifact: ScratchArtifact) => `${artifact.kind} ${artifact.path}`;
 
-	const list = (): string => {
+	const list = async (): Promise<string> => {
 		const session = activeSessions.get(env);
 		const lines: string[] = [];
 		const own = session?.ledger;
 		lines.push(own?.scratchDir
 			? `Session scratch: ${own.scratchDir} (${formatSize(directorySize(own.scratchDir))})`
 			: `Session scratch: none (TMPDIR ${env.TMPDIR ?? tmpdir()})`);
-		const ended = endedLedgers(session?.path);
+		const ended = await endedLedgers(session?.path);
 		for (const { ledger } of ended) if (ledger.scratchDir) lines.push(`Ended-session scratch: ${ledger.scratchDir} (session ${ledger.sessionId})`);
 		const artifacts = [
 			...(own?.artifacts ?? []).map((artifact) => `  ${describe(artifact)} (this session)`),
@@ -269,7 +288,7 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 		const session = activeSessions.get(env);
 		const groups = [
 			...(session ? [{ path: session.path, ledger: session.ledger, own: true }] : []),
-			...endedLedgers(session?.path).map(({ path, ledger }) => ({ path, ledger, own: false })),
+			...(await endedLedgers(session?.path)).map(({ path, ledger }) => ({ path, ledger, own: false })),
 		];
 		const lines: string[] = [];
 		const entries = groups.flatMap((group) => group.ledger.artifacts.map((artifact) => ({ group, artifact })));
@@ -305,7 +324,7 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 			}
 		}
 		// Scratch goes without asking; the live session keeps its TMPDIR and empties it.
-		const held = heldBy(listLedgers(configHome()));
+		const held = heldBy(await listLedgers(configHome()));
 		for (const group of groups) {
 			const { ledger } = group;
 			if (!ledger.scratchDir) continue;
@@ -316,7 +335,7 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 			else if (removal === "kept") lines.push(`${group.own ? "Emptied" : "Kept"} scratch ${dir}${group.own ? " except subagent scratch, live sessions' scratch, recorded artifacts, and entries changed in the last minute" : ": holds a recorded artifact, a live session's scratch, or a live subagent's scratch"}`);
 			else lines.push(`${group.own ? "Emptied" : "Removed"} scratch ${dir}`);
 		}
-		for (const group of groups) persist(group.path, group.ledger);
+		for (const group of groups) await persist(group.path, group.ledger);
 		return lines.length > 0 ? lines.join("\n") : "Nothing to clean.";
 	};
 
@@ -338,13 +357,13 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 			try { note(event.toolCallId, command, ctx); } catch { /* Capture never blocks a tool call. */ }
 			return undefined;
 		});
-		pi.on("tool_result", (event) => {
+		pi.on("tool_result", async (event) => {
 			const targets = pending.get(event.toolCallId);
 			if (!targets) return undefined;
 			pending.delete(event.toolCallId);
 			const command = (event.input as { command?: unknown } | undefined)?.command;
 			if (event.toolName !== "bash" || event.isError !== false || typeof command !== "string") return undefined;
-			try { capture(targets, command); } catch { /* Capture never changes a tool result. */ }
+			try { await capture(targets, command); } catch { /* Capture never changes a tool result. */ }
 			return undefined;
 		});
 		pi.registerCommand("gentle:scratch", {
@@ -352,7 +371,7 @@ export function createSessionScratchExtension(options: SessionScratchOptions = {
 			getArgumentCompletions: (prefix) => ["list", "clean"].filter((action) => action.startsWith(prefix.trim())).map((action) => ({ value: action, label: action })),
 			handler: async (args, ctx) => {
 				const action = args.trim() || "list";
-				if (action === "list") ctx.ui.notify(list(), "info");
+				if (action === "list") ctx.ui.notify(await list(), "info");
 				else if (action === "clean") ctx.ui.notify(await clean(ctx), "info");
 				else ctx.ui.notify(SCRATCH_COMMAND_USAGE, "warning");
 			},

package/extensions/skill-registry.ts

@@ -25,6 +25,11 @@ const SECTION_MARKER = "## Skills";
 const EXCLUDE_NAMES = new Set(["_shared", "skill-registry"]);
 const EXCLUDE_PREFIXES = ["sdd-"];
 const WATCH_DEBOUNCE_MS = 500;
+// inotify budgets are finite (ENOSPC/EMFILE) and recursive watches degrade
+// silently on exhausted systems -- WSL2 hits this constantly -- so a slow
+// poll is the floor that keeps regeneration working when the OS cannot
+// deliver change events. The fingerprint gate makes a redundant poll cheap.
+const WATCH_FALLBACK_POLL_MS = 2_000;
 const REGISTRY_SCHEMA_VERSION = 7;
 const NO_SKILL_REGISTRY_FLAG = "no-skill-registry";
 const NO_SKILL_REGISTRY_ENV = "GENTLE_PI_NO_SKILL_REGISTRY";
@@ -98,6 +103,11 @@ function projectSkillDirs(cwd: string): string[] {
 	];
 }
 
+function isMissingSkillFileError(error: unknown): boolean {
+	if (typeof error !== "object" || error === null || !("code" in error)) return false;
+	return error.code === "ENOENT" || error.code === "ENOTDIR";
+}
+
 async function findSkillFiles(root: string): Promise<string[]> {
 	if (!(await pathExists(root))) return [];
 	let entries;
@@ -107,7 +117,8 @@ async function findSkillFiles(root: string): Promise<string[]> {
 		return [];
 	}
 
-	const out: string[] = [];
+	const directSkills: string[] = [];
+	const nestedSkills: string[] = [];
 	for (const entry of entries) {
 		const skillDir = join(root, entry.name);
 		let dirInfo;
@@ -121,12 +132,40 @@ async function findSkillFiles(root: string): Promise<string[]> {
 		const candidate = join(skillDir, "SKILL.md");
 		try {
 			const skillInfo = await stat(candidate);
-			if (skillInfo.isFile()) out.push(candidate);
+			if (skillInfo.isFile()) directSkills.push(candidate);
+			continue;
+		} catch (error) {
+			if (!isMissingSkillFileError(error)) continue;
+		}
+		if (entry.isSymbolicLink() || isExcluded(entry.name)) continue;
+
+		let nestedEntries;
+		try {
+			nestedEntries = await readdir(skillDir, { withFileTypes: true });
 		} catch {
-			// Missing or unreadable skill files are ignored; the registry is best-effort.
+			continue;
+		}
+		for (const nestedEntry of nestedEntries) {
+			if (nestedEntry.isSymbolicLink()) continue;
+			const nestedSkillDir = join(skillDir, nestedEntry.name);
+			let nestedDirInfo;
+			try {
+				nestedDirInfo = await stat(nestedSkillDir);
+			} catch {
+				continue;
+			}
+			if (!nestedDirInfo.isDirectory()) continue;
+
+			const nestedCandidate = join(nestedSkillDir, "SKILL.md");
+			try {
+				const nestedSkillInfo = await stat(nestedCandidate);
+				if (nestedSkillInfo.isFile()) nestedSkills.push(nestedCandidate);
+			} catch {
+				// Missing or unreadable skill files are ignored; the registry is best-effort.
+			}
 		}
 	}
-	return out.sort();
+	return [...directSkills.sort(), ...nestedSkills.sort()];
 }
 
 function parseFrontmatter(source: string): { name?: string; description?: string; body: string } {
@@ -346,7 +385,7 @@ async function hasNoGitMetadata(cwd: string): Promise<boolean> {
 }
 
 // Freshness (including forced self-heal) never grants automatic write permission.
-async function automaticWriteWarning(
+export async function automaticWriteWarning(
 	cwd: string,
 	targets: string[],
 	remedy = "Run /skill-registry:refresh to deliberately regenerate runtime files.",
@@ -357,6 +396,7 @@ async function automaticWriteWarning(
 			cwd,
 			env: { ...process.env, LC_ALL: "C" },
 			timeout: gitTimeoutMs,
+			windowsHide: true,
 		});
 		tracked = stdout.split("\0").filter(Boolean);
 	} catch (error) {
@@ -496,6 +536,7 @@ async function regenerateRegistry(
 }
 
 const watchedCwds = new Set<string>();
+const watcherPolls = new Map<string, ReturnType<typeof setInterval>>();
 // Startup regeneration runs after session_start returns; watcher refreshes
 // wait for it so an older startup scan never overwrites a newer refresh.
 const pendingStartups = new Map<string, Promise<void>>();
@@ -574,6 +615,8 @@ function closeSkillRegistryWatchers(): void {
 		}
 	}
 	activeWatchers.clear();
+	for (const poll of watcherPolls.values()) clearInterval(poll);
+	watcherPolls.clear();
 	watchedCwds.clear();
 }
 
@@ -588,6 +631,9 @@ async function startSkillRegistryWatcher(
 		...userSkillDirs(),
 	]);
 	let timer: ReturnType<typeof setTimeout> | undefined;
+	// The poll re-asks a state the watchers already answered: without this,
+	// an unchanged tracked-target warning would repeat every poll interval.
+	let lastWarning: string | undefined;
 	const refresh = () => {
 		if (timer) clearTimeout(timer);
 		timer = setTimeout(() => {
@@ -595,9 +641,14 @@ async function startSkillRegistryWatcher(
 				try {
 					await pendingStartups.get(cwd);
 					const result = await regenerateRegistry(cwd, false);
-					if (result.warning) notify(result.warning, "warning");
-					if (result.regenerated) {
-						notify(`Skill registry refreshed (${result.skillCount} skills)`, "info");
+					if (result.warning) {
+						if (result.warning !== lastWarning) notify(result.warning, "warning");
+						lastWarning = result.warning;
+					} else {
+						lastWarning = undefined;
+						if (result.regenerated) {
+							notify(`Skill registry refreshed (${result.skillCount} skills)`, "info");
+						}
 					}
 				} catch (error) {
 					notify(`Skill registry refresh failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
@@ -620,12 +671,16 @@ async function startSkillRegistryWatcher(
 			// Some filesystems do not support recursive watches; session_start/manual refresh still work.
 		}
 	}
+	// Watchers may be absent (unsupported filesystem) or silently eventless
+	// (exhausted inotify budget): the poll keeps regeneration alive either way.
+	if (!watcherPolls.has(cwd)) watcherPolls.set(cwd, setInterval(refresh, WATCH_FALLBACK_POLL_MS));
 }
 
 export const __testing = {
 	projectSkillDirs,
 	userSkillDirs,
 	findSkillFiles,
+	isMissingSkillFileError,
 	uniqueExistingDirs,
 	dedupeBySkillName,
 	scopeForPath,

package/lib/agent-profiles.ts

@@ -8,6 +8,9 @@
 import { randomUUID } from "node:crypto";
 import { closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import {
+	unmatchedProfileKeys,
+} from "./agents-config.ts";
 import {
 	normalizeModelConfig,
 	type AgentModelConfig,
@@ -364,6 +367,29 @@ export function profileRoutingRows(config: AgentModelConfig): ProfileRoutingRow[
 		.sort((left, right) => left.agent.localeCompare(right.agent));
 }
 
+/**
+ * Issue #2196 (PR #2233 maintainer decision): a routing row whose key names no
+ * discovered agent was rendered as a valid-looking row while its setting was
+ * silently ignored at launch. Each unmatched row gets one note: a did-you-mean
+ * suggestion when the packaged short name maps to a discovered agent, and a
+ * plain "no matching agent" otherwise. Matched rows get no note.
+ */
+export function unmatchedRoutingNotes(
+	rows: ProfileRoutingRow[],
+	agentNames: string[],
+): Map<string, string> {
+	const unmatched = unmatchedProfileKeys(
+		Object.fromEntries(rows.map((row) => [row.agent, { model: undefined, thinking: undefined }])),
+		agentNames.map((name) => ({ name })),
+	);
+	return new Map(
+		unmatched.map(({ key, suggestion }) => [
+			key,
+			suggestion === undefined ? "no matching agent" : `did you mean ${suggestion}?`,
+		]),
+	);
+}
+
 /**
  * Column widths shared by every routing table in one panel, so the profile's
  * routing and the effective routing align column for column instead of each

package/lib/agents-config.ts

@@ -316,6 +316,41 @@ function pick<T>(candidates: Array<[T | undefined, ProfileSource]>): [T | undefi
 	return candidates.find(([value]) => value !== undefined) ?? [undefined, PROFILE_SOURCE.UNRESOLVED];
 }
 
+export interface UnmatchedProfileKey {
+	key: string;
+	suggestion: string | undefined;
+}
+
+// Issue #2196: a role key that names no discovered agent was silently ignored,
+// so the child inherited the orchestrator model with no warning anywhere. The
+// alias approach (PR #2233) was rejected because applying a bundled agent's
+// profile to a user-owned same-short-name agent is the exact silence the
+// prefix exists to prevent; reporting the unmatched key keeps resolution
+// exact-match and makes the misconfiguration visible instead.
+export function unmatchedProfileKeys(
+	modelProfiles: Record<string, ModelProfile>,
+	agents: ReadonlyArray<{ name: string }>,
+): UnmatchedProfileKey[] {
+	const names = new Set(agents.map((agent) => agent.name));
+	const lowerNames = new Set(agents.map((agent) => agent.name.toLowerCase()));
+	const suggestionFor = (key: string): string | undefined => {
+		const lowered = key.toLowerCase();
+		if (lowerNames.has(lowered)) return agents.find((agent) => agent.name.toLowerCase() === lowered)?.name;
+		const stripped = lowered.replace(/^gentle-ai-/, "");
+		for (const candidate of [lowered, stripped]) {
+			for (const name of lowerNames) {
+				if (name === candidate || name === `gentle-ai-${candidate}`) {
+					return agents.find((agent) => agent.name.toLowerCase() === name)?.name;
+				}
+			}
+		}
+		return undefined;
+	};
+	return Object.keys(modelProfiles)
+		.filter((key) => !names.has(key))
+		.map((key) => ({ key, suggestion: suggestionFor(key) }));
+}
+
 export function resolveAgentProfile(agent: AgentDefinition, config: AgentsConfig): ResolvedProfile {
 	const profile = config.modelProfiles[agent.name];
 	const [model, modelSource] = pick<ModelRef>([

package/lib/agents-protocol.ts

@@ -164,6 +164,12 @@ export interface TaskStatusChange {
 export type StatusChangeListener = (change: TaskStatusChange) => void | Promise<void>;
 
 const DEFAULT_LIMITS: ThreadLimits = { maxItems: 400, maxOutputChars: 16_000 };
+/** Finished tasks keep their thread weight only for this many most-recent
+ * records per parent session, matching the agents view's visible history cap
+ * (MAX_FINISHED_PER_SESSION in agents-view.ts, pinned by tests); older
+ * terminal tasks (record, thread, run id, listeners) leave the store
+ * entirely. Running tasks are never evicted. */
+export const TERMINAL_RETENTION = 200;
 /** Child UI requests that block on an answer; everything else (notify, setStatus, setWidget) is noise here. */
 export const DIALOG_METHODS: ReadonlySet<string> = new Set(["select", "confirm", "input", "editor"]);
 /** The one child notify that reaches the task thread: requested --tools the child does not have (#1690). */
@@ -481,6 +487,9 @@ export class TaskStore {
 	private sequence = 0;
 	private readonly runIds = new Map<string, string>();
 	private readonly statusListeners = new Set<StatusChangeListener>();
+	// Insertion-ordered recency of finished tasks, oldest first (Set keeps
+	// insertion order); prune evicts from the front.
+	private readonly terminalOrder = new Set<string>();
 
 	constructor(limits: Partial<ThreadLimits> = {}) {
 		this.limits = limits;
@@ -492,6 +501,11 @@ export class TaskStore {
 		this.tasks.set(task.id, task);
 		this.threads.set(task.id, emptyThread(this.limits));
 		this.notifyStatus(task, previous);
+		if (isFinished(task.status)) {
+			this.markTerminal(task.id);
+			this.listeners.delete(task.id);
+			this.pruneTerminal();
+		}
 		this.notifySummary();
 	}
 
@@ -502,6 +516,11 @@ export class TaskStore {
 		this.tasks.set(task.id, task);
 		this.runIds.set(task.id, randomUUID());
 		this.threads.set(task.id, { ...thread, limits: { ...DEFAULT_LIMITS, ...this.limits } });
+		if (isFinished(task.status)) {
+			this.markTerminal(task.id);
+			this.listeners.delete(task.id);
+			this.pruneTerminal();
+		}
 		this.notifySummary();
 		return true;
 	}
@@ -533,7 +552,16 @@ export class TaskStore {
 		this.tasks.set(id, next);
 		this.notifyStatus(next, current.status);
 		this.notifyTask(next);
-		if (next.status !== current.status) this.notifySummary();
+		if (next.status !== current.status) {
+			// The terminal transition itself is the final notification; after it
+			// the task never changes, so its listeners stop costing anything.
+			if (isFinished(next.status)) {
+				this.listeners.delete(next.id);
+				this.markTerminal(next.id);
+			}
+			this.pruneTerminal();
+			this.notifySummary();
+		}
 		return next;
 	}
 
@@ -565,6 +593,34 @@ export class TaskStore {
 		return () => { this.statusListeners.delete(listener); };
 	}
 
+	private markTerminal(id: string): void {
+		if (!this.terminalOrder.has(id)) this.terminalOrder.add(id);
+	}
+
+	/** Evict the oldest finished tasks beyond TERMINAL_RETENTION per parent
+	 * session, with their threads, run ids and listeners. Running tasks are
+	 * never evicted; a task that left the terminal state is skipped as stale. */
+	private pruneTerminal(): void {
+		const finished = new Map<string, number>();
+		for (const task of this.tasks.values()) {
+			if (!isFinished(task.status)) continue;
+			finished.set(task.parentSessionId, (finished.get(task.parentSessionId) ?? 0) + 1);
+		}
+		if (finished.size === 0) return;
+		for (const id of this.terminalOrder) {
+			const task = this.tasks.get(id);
+			if (!task || !isFinished(task.status)) { this.terminalOrder.delete(id); continue; }
+			const count = finished.get(task.parentSessionId) ?? 0;
+			if (count <= TERMINAL_RETENTION) continue;
+			this.tasks.delete(id);
+			this.threads.delete(id);
+			this.listeners.delete(id);
+			this.runIds.delete(id);
+			this.terminalOrder.delete(id);
+			finished.set(task.parentSessionId, count - 1);
+		}
+	}
+
 	private notifyStatus(task: TaskRecord, previousStatus?: TaskStatus): void {
 		if (task.status === previousStatus) return;
 		const change: TaskStatusChange = Object.freeze({ producerId: this.producerId,

package/lib/agents-runner.ts

@@ -6,6 +6,8 @@ import { isAbsolute, join, resolve } from "node:path";
 import { Duplex, type Readable, type Writable } from "node:stream";
 import { stripVTControlCharacters } from "node:util";
 import { withoutInteractiveHost } from "./rpc-host.ts";
+import { gentlePiConfigHome } from "./agent-home.ts";
+import { resolveBackgroundSubagentsPolicy } from "./background-subagents-policy.ts";
 import { childPackageExtensionArgs } from "./child-package-injection.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";
@@ -70,6 +72,8 @@ export interface RunnerLimits {
 	// Longer ceiling used while an announced tool call is in flight. Optional so
 	// callers that only bound silence keep the idle budget as the tool ceiling.
 	toolStallTimeoutMs?: number;
+	// Bounded asynchronous cleanup window allowed after settlement before escalating to SIGTERM/SIGKILL.
+	cleanupTimeoutMs?: number;
 }
 
 export interface AskAnswer {
@@ -245,6 +249,7 @@ const TERMINATION_GRACE_MS = 250;
 const GROUP_CONFIRM_MS = 25;
 const GROUP_CONFIRM_DEADLINE_MS = 1_000;
 const QUARANTINE_PROBE_MS = 1_000;
+export const DEFAULT_CLEANUP_TIMEOUT_MS = 5_000;
 const QUERY_REJECTION_ERRORS = new Set([
 	"invalid child IPC frame",
 	"invalid child IPC correlation",
@@ -552,6 +557,15 @@ export class AgentRunner {
 		delete env.GENTLE_PI_SDD_REMEDIATION_PLAN;
 		delete env.GENTLE_PI_RESEARCH_SELECTION;
 		const tools = requestedTools(request);
+		if (request.agent.tools.includes("bash_background")) {
+			const policy = resolveBackgroundSubagentsPolicy(request.cwd, { env: request.env, gentlePiConfigHome: gentlePiConfigHome(request.env) });
+			if (policy.policy === "off") {
+				const file = policy.source === "global_file" ? policy.globalFile : policy.projectFile;
+				this.store.update(id, { status: TASK_STATUS.RUNNING, startedAt: this.deps.now(), lastStep: "starting" });
+				this.finish(id, TASK_STATUS.FAILED, `could not start pi: explicit tool bash_background requires background-subagents policy on. Set ${file} to {"schema":"gentle-pi.background-subagents/v1","policy":"on"}; inspect or change policy with /gentle:background-subagents enable|disable|status.`);
+				return;
+			}
+		}
 		if (tools !== undefined) env[REQUESTED_TOOLS_ENV] = tools;
 		else delete env[REQUESTED_TOOLS_ENV];
 		let instructionsTransportDir: string | undefined;
@@ -906,9 +920,9 @@ export class AgentRunner {
 			if (event.type === TASK_EVENT.AGENT_SETTLED) {
 				if (live.observations) live.observations.agentSettled = true;
 				const terminal = this.store.get(id);
-				if (terminal?.error) this.requestStop(id, TASK_STATUS.FAILED, terminal.error);
-				else if (terminal?.result) this.requestStop(id, TASK_STATUS.COMPLETED, null);
-				else this.requestStop(id, TASK_STATUS.FAILED, "assistant settled without a final report");
+				if (terminal?.error) this.settleOrderly(id, TASK_STATUS.FAILED, terminal.error);
+				else if (terminal?.result) this.settleOrderly(id, TASK_STATUS.COMPLETED, null);
+				else this.settleOrderly(id, TASK_STATUS.FAILED, "assistant settled without a final report");
 			}
 		}
 		if (!live.terminal && progress) this.armStall(id, live);
@@ -949,6 +963,41 @@ export class AgentRunner {
 		}
 	}
 
+	/**
+	 * Requests orderly child shutdown via stdin upon settlement and schedules
+	 * bounded signal escalation if the child process does not exit within cleanupTimeoutMs.
+	 */
+	private settleOrderly(id: string, status: TaskRecord["status"], error: string | null): void {
+		const live = this.live.get(id);
+		if (!live || live.terminal) return;
+		live.terminal = { status, error };
+		live.mutationStarts.clear();
+		live.inFlightTools.clear();
+		live.permissionBroker?.close();
+		this.closeIpc(live);
+		live.cancelStall();
+		const current = this.store.get(id);
+		if (current && !isFinished(current.status)) {
+			this.store.update(id, { lastStep: "cleaning up" });
+		}
+		try {
+			live.child.stdin.end();
+		} catch {
+			this.signal(live, "SIGTERM");
+		}
+		const cleanupTimeoutMs = this.limits.cleanupTimeoutMs ?? DEFAULT_CLEANUP_TIMEOUT_MS;
+		live.cancelGrace = this.deps.schedule(() => {
+			if (this.live.get(id) !== live) return;
+			this.signal(live, "SIGTERM");
+			live.cancelGrace = this.deps.schedule(() => {
+				if (this.live.get(id) !== live) return;
+				live.cleanupDeadlineAt = this.deps.now() + GROUP_CONFIRM_DEADLINE_MS;
+				this.signal(live, "SIGKILL");
+				this.confirmGroupExit(id, live);
+			}, TERMINATION_GRACE_MS);
+		}, cleanupTimeoutMs);
+	}
+
 	private requestStop(id: string, status: TaskRecord["status"], error: string | null, abort = false): void {
 		const live = this.live.get(id);
 		if (!live || live.terminal) return;