gentle-pi 4.2.0 → 4.4.0

package/extensions/startup-banner.ts

@@ -1,13 +1,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, VERSION } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import * as os from "node:os";
 import { execFile } from "node:child_process";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { resolveAnimationPolicy } from "../lib/animation-policy.ts";
 import { PI_SUBCOMMANDS } from "../lib/gentle-shell-launcher.ts";
-import { bundledGentlePiConfigHome } from "../lib/gentle-shell-bundled.ts";
+import { gentlePiConfigHome } from "../lib/agent-home.ts";
 
 
 export type BannerColor = "pink" | "cyan" | "yellow" | "green";
@@ -68,7 +67,7 @@ function rgb(r: number, g: number, b: number, text: string): string {
 }
 
 function gentleAiConfigHome(): string {
-  return bundledGentlePiConfigHome(process.env) ?? process.env.GENTLE_PI_CONFIG_HOME ?? join(os.homedir(), ".pi", "gentle-ai");
+  return gentlePiConfigHome(process.env);
 }
 
 function bannerConfigPath(configHome = gentleAiConfigHome()): string {

package/lib/agent-home.ts

@@ -1,6 +1,8 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { bundledGentlePiConfigHome, runningBundledPrefix } from "./gentle-shell-bundled.ts";
+import { resolveGentlePiConfigHome, runningBundledPrefix } from "./gentle-shell-bundled.ts";
+
+export { GENTLE_SHELL_CONFIG_HOME_ENV } from "./gentle-shell-bundled.ts";
 
 // Pi Subagents resolves its global directory as `PI_CODING_AGENT_DIR || ~/.pi/agent`,
 // so an empty value must fall through here too or the two homes diverge again.
@@ -12,9 +14,12 @@ export function resolveGentlePiAgentHome(env: NodeJS.ProcessEnv = process.env):
 // commands own lives here. It is defined once because the launch-time profile pin
 // resolver reads the same profiles store the `/gentle:profiles` panel writes, and
 // two spellings of the override would silently read two different stores.
-// A bundled Gentle Shell keeps it inside its prefix (S9, bundledGentlePiConfigHome).
+// A bundled Gentle Shell keeps it inside its prefix (S9, bundledGentlePiConfigHome),
+// the standalone launcher's isolated home next to its agent dir (#2201). The rule
+// itself lives in resolveGentlePiConfigHome, a generated runtime module, so the
+// launcher and the Gentle AI process environment share it too.
 export function gentlePiConfigHome(env: NodeJS.ProcessEnv = process.env): string {
-	return bundledGentlePiConfigHome(env) ?? (env.GENTLE_PI_CONFIG_HOME || join(homedir(), ".pi", "gentle-ai"));
+	return resolveGentlePiConfigHome(env, homedir());
 }
 
 // The agent home Pi runs with, only in a bundled Gentle Shell (S9): there the

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

@@ -127,6 +127,9 @@ export interface TaskRecord {
 	startedAt: number | null;
 	endedAt: number | null;
 	model: string;
+	/** Launch-layer token recorded next to `model` (#2180): which profile layer won.
+	 * Host-computed at the launch seam; absent for requests and records that never named one. */
+	modelSource?: string;
 	thinking: string | undefined;
 	sessionPath: string | null;
 	error: string | null;
@@ -161,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). */
@@ -478,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;
@@ -489,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();
 	}
 
@@ -499,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;
 	}
@@ -530,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;
 	}
 
@@ -562,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

@@ -2,16 +2,19 @@ import { isSessionChangeEvidence, type SessionChangeEvidence } from "./session-c
 import { chmodSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { tmpdir, userInfo } from "node:os";
-import { join, resolve } from "node:path";
+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";
 import { ParentStandingReviewPermissionBroker } from "./review-session-standing-permission-ipc.ts";
 import { isFinished, normalizeRpcEvent, ToolArgumentProgress, TASK_EVENT, TASK_STATUS, taskLabel, type AskRequest, type ChildResponseObservation, type TaskRecord, type TaskStore } from "./agents-protocol.ts";
 import { WriterSurfaceRegistry, writerSurfaceConflictMessage } from "./writer-surfaces.ts";
+import { holdSubagentScratch, releaseSubagentScratch, SUBAGENT_SCRATCH_PREFIX } from "./session-scratch.ts";
 
 // Gentle Agents runner. Every subagent is its own `pi --mode rpc` process:
 // the host never runs subagent work on the TUI thread. It writes JSON
@@ -69,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 {
@@ -133,6 +138,11 @@ export interface TaskRequest {
 	// Host-provided only: the launcher's package injection signal (#1690) or
 	// the curated fallback. Never derived from tool input or agent definitions.
 	extensionPaths?: string[];
+	// Host-computed launch-layer token for the card (#2180): which profile layer
+	// supplied `model` (`binding`, `frozen:*`, `pin:*`, `declaration`, `profile`,
+	// `definition`, `default`). Same host-only provenance as `extensionPaths`:
+	// never derived from tool input or agent definitions.
+	modelSource?: string;
 	// Same host-only provenance as extensionPaths (#1690).
 	noExtensions?: boolean;
 	// Parsed `## Allowed edit surfaces` of a bounded writer. While the task is
@@ -202,6 +212,8 @@ interface LiveTask {
 	childExit: number | null | undefined;
 	childExitSignal?: string | null;
 	instructionsTransportDir?: string;
+	/** The child's own TMPDIR, removed when the child ends unless its exit is unconfirmed. */
+	scratchDir?: string;
 	cleanupDeadlineAt: number | undefined;
 	quarantined: boolean;
 	nextId: number;
@@ -236,6 +248,8 @@ const DEFAULT_TOOLS: readonly string[] = [];
 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",
@@ -407,6 +421,8 @@ export class AgentRunner {
 			startedAt: null,
 			endedAt: null,
 			model: formatModelRef(request.model),
+			// Copied, never recomputed: the layer token was resolved once at the seam (#2180).
+			...(request.modelSource === undefined ? {} : { modelSource: request.modelSource }),
 			thinking: request.thinking,
 			sessionPath: request.resumeSessionPath ?? null,
 			error: null,
@@ -541,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;
@@ -562,6 +587,22 @@ export class AgentRunner {
 				return;
 			}
 		}
+		// Harness roadmap T3: scratch the child makes with mktemp lands in its own
+		// TMPDIR, under the inherited one, so the runtime removes it at the end
+		// instead of asking the parent. Best effort: without it the child keeps
+		// the inherited TMPDIR.
+		let scratchDir: string | undefined;
+		try {
+			const inherited = request.env.TMPDIR?.trim();
+			// A relative TMPDIR would resolve against this process, not the child cwd.
+			// A short name and no real path: socket paths under TMPDIR are capped near 104 bytes.
+			scratchDir = mkdtempSync(join(inherited && isAbsolute(inherited) ? inherited : tmpdir(), SUBAGENT_SCRATCH_PREFIX));
+			// Session shutdown keeps it while it is held (extensions/session-scratch.ts).
+			holdSubagentScratch(scratchDir);
+			try { chmodSync(scratchDir, DIR_MODE); } catch { /* best effort */ }
+			env.TMPDIR = scratchDir;
+			if (this.processControl.platform === "win32") { env.TMP = scratchDir; env.TEMP = scratchDir; }
+		} catch { scratchDir = undefined; }
 		let child: ChildLike;
 		try {
 			const pi = this.deps.resolvePi?.() ?? this.deps.pi;
@@ -573,15 +614,16 @@ export class AgentRunner {
 				stdio: hasParentPermissionChannel ? ["pipe", "pipe", "pipe", permissionChannelStdio, "ipc"] : ["pipe", "pipe", "pipe", "ipc"],
 			});
 		} catch (error) {
-			if (instructionsTransportDir) {
-				try { rmSync(instructionsTransportDir, { recursive: true, force: true }); } catch { /* best effort */ }
+			for (const dir of [instructionsTransportDir, scratchDir]) {
+				if (dir) try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
 			}
+			if (scratchDir) releaseSubagentScratch(scratchDir);
 			this.store.update(id, { status: TASK_STATUS.RUNNING, startedAt: this.deps.now(), lastStep: "starting" });
 			this.finish(id, TASK_STATUS.FAILED, `could not start pi: ${error instanceof Error ? error.message : String(error)}`);
 			return;
 		}
 		const processGroup = detached && typeof child.pid === "number" && child.pid > 0 ? child.pid : undefined;
-		const live: LiveTask = { child, sawRunEvent: false, mutationStarts: new Map(), inFlightTools: new Map(), argumentProgress: new ToolArgumentProgress(), pending: new Map(), queries: new Map(), replies: new Map(), cancelStall: () => {}, cancelGrace: () => {}, processGroup, terminal: undefined, childExit: undefined, childExitSignal: undefined, instructionsTransportDir, cleanupDeadlineAt: undefined, quarantined: false, nextId: 0, ipcClosed: false, acknowledgedIpcIds: new Set(), acknowledgedIpcOrder: [], stderrTail: "" };
+		const live: LiveTask = { child, sawRunEvent: false, mutationStarts: new Map(), inFlightTools: new Map(), argumentProgress: new ToolArgumentProgress(), pending: new Map(), queries: new Map(), replies: new Map(), cancelStall: () => {}, cancelGrace: () => {}, processGroup, terminal: undefined, childExit: undefined, childExitSignal: undefined, instructionsTransportDir, scratchDir, cleanupDeadlineAt: undefined, quarantined: false, nextId: 0, ipcClosed: false, acknowledgedIpcIds: new Set(), acknowledgedIpcOrder: [], stderrTail: "" };
 		if (request.prepareResponseObservations) {
 			let ready = false;
 			live.observationPreparation = () => ready;
@@ -878,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);
@@ -921,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;
@@ -997,7 +1074,8 @@ export class AgentRunner {
 		live.cancelGrace = this.deps.schedule(() => this.confirmGroupExit(id, live), GROUP_CONFIRM_MS);
 	}
 
-	private cleanupLive(live: LiveTask): void {
+	/** `exitProven` is true only in completeExit, after the child's exit was observed or its group is gone. */
+	private cleanupLive(live: LiveTask, exitProven = false): void {
 		live.permissionBroker?.close();
 		this.closeIpc(live);
 		live.cancelStall();
@@ -1006,6 +1084,13 @@ export class AgentRunner {
 			try { rmSync(live.instructionsTransportDir, { recursive: true, force: true }); } catch { /* best effort */ }
 			live.instructionsTransportDir = undefined;
 		}
+		// A quarantined child's exit is unconfirmed: a live descendant may still
+		// hold files there, so its scratch stays until the exit is proven.
+		if (live.scratchDir && (!live.quarantined || exitProven)) {
+			try { rmSync(live.scratchDir, { recursive: true, force: true }); } catch { /* best effort */ }
+			releaseSubagentScratch(live.scratchDir);
+			live.scratchDir = undefined;
+		}
 	}
 
 	private childError(id: string, error: Error): void {
@@ -1030,13 +1115,26 @@ export class AgentRunner {
 		const exitDesc = formatChildExit(code, signal);
 		if (this.groupExists(live)) {
 			if (!live.terminal) this.requestStop(id, TASK_STATUS.FAILED, `pi exited with ${exitDesc} before agent_settled${this.stderrSuffix(live)}`);
+			else if (live.quarantined) live.cancelGrace = this.deps.schedule(() => this.awaitQuarantinedGroup(id, live), QUARANTINE_PROBE_MS);
+			return;
+		}
+		this.completeExit(id, live);
+	}
+
+	// Quarantine stopped probing, and a descendant outlives the child's observed
+	// exit: no later event reports the group's end, so keep probing until it is
+	// gone, then release the slot and scratch.
+	private awaitQuarantinedGroup(id: string, live: LiveTask): void {
+		if (this.live.get(id) !== live) return;
+		if (this.groupExists(live)) {
+			live.cancelGrace = this.deps.schedule(() => this.awaitQuarantinedGroup(id, live), QUARANTINE_PROBE_MS);
 			return;
 		}
 		this.completeExit(id, live);
 	}
 
 	private completeExit(id: string, live: LiveTask): void {
-		this.cleanupLive(live);
+		this.cleanupLive(live, true);
 		this.live.delete(id);
 		// Quarantine already notified completion, but its retained slot is now free.
 		if (live.quarantined) {

package/lib/agents-session-transport.ts

@@ -1,11 +1,17 @@
-import { chmod, constants, link, lstat, mkdir, open, opendir, realpath, unlink, writeFile } from "node:fs/promises";
+import { chmod, constants, link, lstat, mkdir, open, opendir, readdir, realpath, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { createConnection, createServer, type Server, type Socket } from "node:net";
 
 const DIR_MODE = 0o700, FILE_MODE = 0o600, MAX_RECORD_BYTES = 8192, MAX_ENTRIES = 64, MAX_SOCKET_PATH_BYTES = 100;
+// Over-cap debris collection bounds: a presence directory may hold at most
+// this many schema-matching records before sweeping is refused, and each
+// liveness probe gets a short bounded connect attempt. A genuine flood of
+// live listeners stays over the cap and keeps failing busy, unchanged.
+const SWEEP_MAX_FILES = 4096, SWEEP_PROBE_TIMEOUT_MS = 1_000, SWEEP_PROBE_CONCURRENCY = 8;
 const RUNTIME_TMP = "/tmp", RUNTIME_PREFIX = "gentle-pi-", PROFILE_HASH_HEX_LENGTH = 32, SOCKET_NAME_BYTES = 27;
 const SESSION = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/, TOKEN = /^[A-Za-z0-9_-]{22}$/;
+const PRESENCE_FILE = /^([A-Za-z0-9][A-Za-z0-9_-]{0,127})\.([A-Za-z0-9_-]{22})\.json$/;
 const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
 type Code = "invalid_session" | "not_found" | "invalid_presence" | "unsafe_path" | "io_error" | "busy";
 
@@ -131,7 +137,25 @@ export class SessionPresenceRegistry {
 		return (await this.listActivations(excludeSessionId)).map(({ sessionId }) => Object.freeze({ sessionId, reachability: "unknown" as const }));
 	}
 
-	async listActivations(excludeSessionId?: string): Promise<readonly PresenceRecord[]> {
+	// An over-cap failure is stale debris until proven otherwise: sessions that
+	// exit uncleanly never remove their record, so a long-lived profile accrues
+	// them until every scan fails busy (gentle-shell#2501: 133 records, oldest
+	// four weeks old, 126 provably dead). Sweep once — bounded, liveness-based —
+	// and retry; a flood of live listeners stays over the cap and still fails.
+	private async withStaleSweep<T>(scan: () => Promise<T>): Promise<T> {
+		try { return await scan(); }
+		catch (error) {
+			if (!(error instanceof SessionPresenceError) || error.code !== "busy") throw error;
+			if (!await this.sweepStaleRecords().catch(() => false)) throw error;
+			return scan();
+		}
+	}
+
+	listActivations(excludeSessionId?: string): Promise<readonly PresenceRecord[]> {
+		return this.withStaleSweep(() => this.scanActivations(excludeSessionId));
+	}
+
+	private async scanActivations(excludeSessionId?: string): Promise<readonly PresenceRecord[]> {
 		const excluded = excludeSessionId === undefined ? undefined : sessionId(excludeSessionId);
 		await privateDirectory(this.paths.root);
 		await privateDirectory(this.paths.presence);
@@ -142,9 +166,12 @@ export class SessionPresenceRegistry {
 		try {
 			dir = await opendir(this.paths.presence);
 			for await (const entry of dir) {
-				if (++count > MAX_ENTRIES) fail("busy", "presence registry is busy");
-				const match = /^([A-Za-z0-9][A-Za-z0-9_-]{0,127})\.([A-Za-z0-9_-]{22})\.json$/.exec(entry.name);
+				const match = PRESENCE_FILE.exec(entry.name);
+				// Foreign-schema records (orchestrator headers, activity, and discovery
+				// sidecars) share this directory without ever being activations, so
+				// only schema-matching entries count toward the spam guard.
 				if (!match) continue;
+				if (++count > MAX_ENTRIES) fail("busy", "presence registry is busy");
 				try { await this.beforeCandidateOpen?.(); } catch { fail("io_error", "transport I/O failed"); }
 				try {
 					const loaded = await this.read(join(this.paths.presence, entry.name), match[1], match[2]);
@@ -160,7 +187,11 @@ export class SessionPresenceRegistry {
 		return [...newest.values()].sort((left, right) => left.sessionId.localeCompare(right.sessionId));
 	}
 
-	async resolve(id: string): Promise<PresenceRecord> {
+	resolve(id: string): Promise<PresenceRecord> {
+		return this.withStaleSweep(() => this.scanResolve(id));
+	}
+
+	private async scanResolve(id: string): Promise<PresenceRecord> {
 		id = sessionId(id);
 		await privateDirectory(this.paths.root);
 		await privateDirectory(this.paths.presence);
@@ -170,9 +201,11 @@ export class SessionPresenceRegistry {
 		try {
 			dir = await opendir(this.paths.presence);
 			for await (const entry of dir) {
-				if (++count > MAX_ENTRIES) fail("busy", "presence registry is busy");
 				const match = new RegExp(`^${id}\\.([A-Za-z0-9_-]{22})\\.json$`).exec(entry.name);
+				// Same shared-directory rule as listActivations: foreign-schema
+				// records are skipped before counting toward the cap.
 				if (!match) continue;
+				if (++count > MAX_ENTRIES) fail("busy", "presence registry is busy");
 				try { await this.beforeCandidateOpen?.(); } catch { fail("io_error", "transport I/O failed"); }
 				try {
 					const loaded = await this.read(join(this.paths.presence, entry.name), id, match[1]);
@@ -215,6 +248,68 @@ export class SessionPresenceRegistry {
 		}
 	}
 
+	// One bounded connect attempt against a candidate's own socket endpoint.
+	// Endpoints reaching this probe were validated into this registry's sockets
+	// directory and lstat-verified as same-user sockets by advertises(), so the
+	// probe cannot reach foreign services. Only an active refusal proves the
+	// record dead: an ambiguous outcome (timeout, unexpected error) keeps it.
+	private liveness(endpoint: string): Promise<"live" | "dead" | "unclear"> {
+		return new Promise((resolveProbe) => {
+			const socket = createConnection(endpoint);
+			const settle = (verdict: "live" | "dead" | "unclear") => {
+				clearTimeout(timer);
+				socket.destroy();
+				resolveProbe(verdict);
+			};
+			const timer = setTimeout(() => settle("unclear"), SWEEP_PROBE_TIMEOUT_MS);
+			socket.once("connect", () => settle("live"));
+			socket.once("error", (error: NodeJS.ErrnoException) => settle(error.code === "ETIMEDOUT" ? "unclear" : "dead"));
+		});
+	}
+
+	// Garbage-collects provably dead records once the directory is over cap:
+	// no live endpoint (advertises false, i.e. the socket is gone) or a refused
+	// connect. Removes the record files only — socket files belong to their
+	// owning session. Returns whether anything was removed, so the caller
+	// retries the scan exactly once; nothing here runs on a healthy directory.
+	private async sweepStaleRecords(): Promise<boolean> {
+		const names = (await readdir(this.paths.presence)).filter((name) => PRESENCE_FILE.test(name));
+		if (names.length === 0 || names.length > SWEEP_MAX_FILES) return false;
+		let removed = 0;
+		const remove = async (file: string) => {
+			try { await unlink(file); removed += 1; }
+			catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") removed += 1; }
+		};
+		const live: PresenceRecord[] = [];
+		for (const name of names) {
+			const match = PRESENCE_FILE.exec(name);
+			if (!match) continue;
+			try {
+				const loaded = await this.read(join(this.paths.presence, name), match[1], match[2]);
+				const record = loaded?.record;
+				// A record that no longer validates (malformed, pruned endpoint) is
+				// debris; an unsafe_path one is left for its owner, never touched.
+				if (!record) { await remove(join(this.paths.presence, name)); continue; }
+				if (await this.advertises(record)) live.push(record);
+				else await remove(join(this.paths.presence, name));
+			} catch (error) {
+				// Malformed content is debris from an interrupted write and is
+				// collected; unsafe-path records are left for their owner, never
+				// touched by the sweep.
+				if (error instanceof SessionPresenceError && error.code === "invalid_presence") await remove(join(this.paths.presence, name));
+			}
+		}
+		let next = 0;
+		const worker = async () => {
+			while (next < live.length) {
+				const record = live[next++];
+				if (await this.liveness(record.endpoint) === "dead") await remove(this.presencePath(record));
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(SWEEP_PROBE_CONCURRENCY, live.length) }, worker));
+		return removed > 0;
+	}
+
 	private token(endpoint: unknown) {
 		if (typeof endpoint !== "string" || dirname(endpoint) !== this.paths.sockets || resolve(endpoint) !== endpoint || Buffer.byteLength(endpoint) > MAX_SOCKET_PATH_BYTES) fail("unsafe_path", "unsafe transport path");
 		const name = basename(endpoint), token = name.endsWith(".sock") ? name.slice(0, -5) : "";

package/lib/agents-view.ts

@@ -143,7 +143,9 @@ function sameItemValue(a: unknown, b: unknown): boolean {
 }
 
 export function taskHeader(task: TaskRecord, now: number): string {
-	const parts = [task.agent, task.status, task.model, task.tokens > 0 ? formatTokens(task.tokens) : "", task.cost > 0 ? formatCost(task.cost) : "", task.startedAt === null ? "" : formatElapsed((task.endedAt ?? now) - task.startedAt)];
+	// #2180: the winning profile layer is shown right after the model it supplied;
+	// records without one render exactly as before.
+	const parts = [task.agent, task.status, task.model, ...(task.modelSource === undefined ? [] : [task.modelSource]), task.tokens > 0 ? formatTokens(task.tokens) : "", task.cost > 0 ? formatCost(task.cost) : "", task.startedAt === null ? "" : formatElapsed((task.endedAt ?? now) - task.startedAt)];
 	return parts.filter((part) => part.length > 0).join(" · ");
 }