gentle-pi 4.0.0 → 4.2.0

package/extensions/skill-registry.ts

@@ -1,7 +1,9 @@
+import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, type FSWatcher, watch } from "node:fs";
 import {
 	access,
+	lstat,
 	mkdir,
 	readFile,
 	readdir,
@@ -10,9 +12,12 @@ import {
 	writeFile,
 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, join, normalize, relative, sep } from "node:path";
+import { basename, delimiter, dirname, join, normalize, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isHomeOrBroadUserDirectory } from "../lib/bounded-writer-admission.ts";
+import { resolveSessionWorktree } from "../lib/session-worktree-registry.ts";
 
 const REGISTRY_REL_PATH = ".atl/skill-registry.md";
 const CACHE_REL_PATH = ".atl/.skill-registry.cache.json";
@@ -311,11 +316,65 @@ interface RegenResult {
 	regenerated: boolean;
 	skillCount: number;
 	reason: string;
+	warning?: string;
+}
+
+const execFileAsync = promisify(execFile);
+// A tracking check that cannot answer (for example a repository rooted at HOME)
+// fails closed through the ordinary detection-failure path instead of hanging.
+let gitTimeoutMs = 5000;
+
+// A failed Git lookup is genuinely non-Git only when no ancestor has metadata.
+// lstat also detects dangling redirects; permission failures remain fail-closed.
+async function hasNoGitMetadata(cwd: string): Promise<boolean> {
+	if (process.env.GIT_DIR || process.env.GIT_WORK_TREE) return false;
+	const ceilings = (process.env.GIT_CEILING_DIRECTORIES ?? "").split(delimiter).filter(Boolean).map((path) => resolve(path));
+	let directory = resolve(cwd);
+	for (;;) {
+		// Git does not inspect ancestors at or above its discovery ceiling.
+		if (directory !== resolve(cwd) && ceilings.includes(directory)) return true;
+		try {
+			await lstat(join(directory, ".git"));
+			return false;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") return false;
+		}
+		const parent = dirname(directory);
+		if (parent === directory) return true;
+		directory = parent;
+	}
+}
+
+// Freshness (including forced self-heal) never grants automatic write permission.
+async function automaticWriteWarning(
+	cwd: string,
+	targets: string[],
+	remedy = "Run /skill-registry:refresh to deliberately regenerate runtime files.",
+): Promise<string | undefined> {
+	let tracked: string[];
+	try {
+		const { stdout } = await execFileAsync("git", ["ls-files", "--cached", "-z", "--", ...targets], {
+			cwd,
+			env: { ...process.env, LC_ALL: "C" },
+			timeout: gitTimeoutMs,
+		});
+		tracked = stdout.split("\0").filter(Boolean);
+	} catch (error) {
+		const failure = error as { code?: number; stderr?: string };
+		if (failure.code === 128 && failure.stderr?.startsWith("fatal: not a git repository") && await hasNoGitMetadata(cwd)) return undefined;
+		throw new Error(`Cannot verify Git tracking for ${targets.join(", ")}; automatic writes skipped. Resolve Git detection, or deliberately run /skill-registry:refresh.`);
+	}
+	if (tracked.length === 0) return undefined;
+	return `Skill registry automatic writes skipped for tracked targets: ${tracked.join(", ")}. ${remedy}`;
 }
 
-async function ensureAtlIgnored(cwd: string): Promise<void> {
+async function ensureAtlIgnored(cwd: string, intentional = false): Promise<string | undefined> {
 	const atlDir = join(cwd, ".atl");
 	const gitignorePath = join(atlDir, ".gitignore");
+	if (!intentional) {
+		const warning = await automaticWriteWarning(cwd, [".atl/.gitignore"]);
+		if (warning) return warning;
+	}
 	if (await pathExists(gitignorePath)) {
 		const existing = await readFile(gitignorePath, "utf8");
 		const ignoreRules = existing
@@ -355,7 +414,7 @@ async function nextLegacyDisabledPath(cwd: string): Promise<string> {
 	return `${base}.${Date.now()}`;
 }
 
-async function quarantineLegacyProjectRegistry(cwd: string): Promise<boolean> {
+async function quarantineLegacyProjectRegistry(cwd: string, notifyWarning: (message: string) => void): Promise<boolean> {
 	const legacyPath = join(cwd, LEGACY_PROJECT_REGISTRY_REL_PATH);
 	if (!(await pathExists(legacyPath))) return false;
 	let source = "";
@@ -366,6 +425,15 @@ async function quarantineLegacyProjectRegistry(cwd: string): Promise<boolean> {
 	}
 	if (!isGeneratedLegacyProjectRegistry(source)) return false;
 	const disabledPath = await nextLegacyDisabledPath(cwd);
+	const warning = await automaticWriteWarning(
+		cwd,
+		[LEGACY_PROJECT_REGISTRY_REL_PATH, relative(cwd, disabledPath).split(sep).join("/")],
+		"Review and manually handle the tracked legacy extension (and any tracked quarantine destination) before retrying startup; refresh only regenerates registry runtime files.",
+	);
+	if (warning) {
+		notifyWarning(warning);
+		return false;
+	}
 	try {
 		await rename(legacyPath, disabledPath);
 		return true;
@@ -377,6 +445,7 @@ async function quarantineLegacyProjectRegistry(cwd: string): Promise<boolean> {
 async function regenerateRegistry(
 	cwd: string,
 	force: boolean,
+	intentional = false,
 ): Promise<RegenResult> {
 	const existingDirs = await uniqueExistingDirs([
 		...projectSkillDirs(cwd),
@@ -401,6 +470,10 @@ async function regenerateRegistry(
 	if (!force && cached === fp && (await pathExists(registryPath))) {
 		return { regenerated: false, skillCount: 0, reason: "cache-hit" };
 	}
+	if (!intentional) {
+		const warning = await automaticWriteWarning(cwd, [REGISTRY_REL_PATH, CACHE_REL_PATH]);
+		if (warning) return { regenerated: false, skillCount: 0, reason: "tracked-target", warning };
+	}
 	const entries: SkillEntry[] = [];
 	for (const file of files) {
 		const entry = await loadSkill(file);
@@ -423,6 +496,17 @@ async function regenerateRegistry(
 }
 
 const watchedCwds = new Set<string>();
+// 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>>();
+let startupGeneration = 0;
+
+// A repository rooted at HOME (or a broad user folder) makes every Git call
+// scan the user's whole tree. gentle-ai owns the single user-facing warning.
+function repositoryRootedAtHome(cwd: string): boolean {
+	const root = resolveSessionWorktree(cwd, cwd)?.root;
+	return root !== undefined && isHomeOrBroadUserDirectory(root);
+}
 
 function isTruthyEnv(value: string | undefined): boolean {
 	return value === "1" || value === "true" || value === "yes" || value === "on";
@@ -438,6 +522,9 @@ function shouldSkipSkillRegistryStartup(
 	env = process.env,
 ): boolean {
 	return (
+		// gentle-shell#1690: delegated children share the parent's cwd; the
+		// parent owns .atl/ writes, the legacy rename and the watcher.
+		env.GENTLE_PI_AGENTS_CHILD === "1" ||
 		pi.getFlag(NO_SKILL_REGISTRY_FLAG) === true ||
 		isTruthyEnv(env[NO_SKILL_REGISTRY_ENV]) ||
 		hasCliArg(argv, "--no-skills", "-ns")
@@ -461,7 +548,7 @@ function extensionSourcePath(source: string): string | undefined {
 function shouldSkipDuplicateExtensionLoad(
 	source = import.meta.url,
 	cwd = process.cwd(),
-	state = globalThis as typeof globalThis & SkillRegistryExtensionGlobal,
+	state: SkillRegistryExtensionGlobal = globalThis as typeof globalThis & SkillRegistryExtensionGlobal,
 ): boolean {
 	const currentPath = extensionSourcePath(source);
 	const projectLocalPath = comparablePath(join(cwd, "extensions", "skill-registry.ts"));
@@ -492,7 +579,7 @@ function closeSkillRegistryWatchers(): void {
 
 async function startSkillRegistryWatcher(
 	cwd: string,
-	notify: (message: string) => void,
+	notify: (message: string, level?: "info" | "warning") => void,
 ): Promise<void> {
 	if (watchedCwds.has(cwd)) return;
 	watchedCwds.add(cwd);
@@ -506,12 +593,14 @@ async function startSkillRegistryWatcher(
 		timer = setTimeout(() => {
 			void (async () => {
 				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)`);
+						notify(`Skill registry refreshed (${result.skillCount} skills)`, "info");
 					}
-				} catch {
-					// Keep the watcher best-effort; session_start/manual refresh surfaces detailed failures.
+				} catch (error) {
+					notify(`Skill registry refresh failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
 				}
 			})();
 		}, WATCH_DEBOUNCE_MS);
@@ -519,6 +608,13 @@ async function startSkillRegistryWatcher(
 	for (const dir of dirs) {
 		try {
 			const watcher = watch(dir, { recursive: true }, refresh);
+			watcher.on("error", (error) => {
+				// Recursive rescans can fail after watch() returns (e.g. a removed
+				// assets directory). Without this listener Node terminates Pi.
+				watcher.close();
+				activeWatchers.delete(watcher);
+				notify(`Skill registry watcher stopped: ${error.message}. Run /skill-registry:refresh to update manually.`, "warning");
+			});
 			activeWatchers.add(watcher);
 		} catch {
 			// Some filesystems do not support recursive watches; session_start/manual refresh still work.
@@ -545,12 +641,21 @@ export const __testing = {
 	activeWatcherCount() {
 		return activeWatchers.size;
 	},
+	async startupSettled(): Promise<void> {
+		await Promise.all(pendingStartups.values());
+	},
+	setGitTimeoutMs(ms: number): number {
+		const previous = gitTimeoutMs;
+		gitTimeoutMs = ms;
+		return previous;
+	},
 };
 
 export default function (pi: ExtensionAPI) {
 	if (shouldSkipDuplicateExtensionLoad()) return;
 
 	pi.on("session_shutdown", () => {
+		startupGeneration += 1;
 		closeSkillRegistryWatchers();
 	});
 
@@ -562,47 +667,71 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		if (shouldSkipSkillRegistryStartup(pi)) return;
-		try {
-			await ensureAtlIgnored(ctx.cwd);
-			const quarantinedLegacy = await quarantineLegacyProjectRegistry(ctx.cwd);
-			const result = await regenerateRegistry(ctx.cwd, quarantinedLegacy);
-			if (result.regenerated && ctx.hasUI) {
-				ctx.ui.notify(
-					`Skill registry refreshed (${result.skillCount} skills)`,
-					"info",
-				);
-			}
-			if (quarantinedLegacy && ctx.hasUI) {
-				ctx.ui.notify(
-					"Disabled stale project-local skill registry extension; using package registry with project skills first.",
-					"warning",
-				);
+		if (repositoryRootedAtHome(ctx.cwd)) return;
+		const cwd = ctx.cwd;
+		const generation = startupGeneration;
+		const notifyWarning = (message: string) => {
+			if (ctx.hasUI) ctx.ui.notify(message, "warning");
+		};
+		const regenerate = async () => {
+			if (generation !== startupGeneration) return;
+			try {
+				const ignoreWarning = await ensureAtlIgnored(cwd);
+				if (ignoreWarning) notifyWarning(ignoreWarning);
+				const quarantinedLegacy = await quarantineLegacyProjectRegistry(cwd, notifyWarning);
+				const result = await regenerateRegistry(cwd, quarantinedLegacy);
+				if (result.warning) notifyWarning(result.warning);
+				if (result.regenerated && ctx.hasUI) {
+					ctx.ui.notify(
+						`Skill registry refreshed (${result.skillCount} skills)`,
+						"info",
+					);
+				}
+				if (quarantinedLegacy && ctx.hasUI) {
+					ctx.ui.notify(
+						"Disabled stale project-local skill registry extension; using package registry with project skills first.",
+						"warning",
+					);
+				}
+				if (quarantinedLegacy) {
+					setTimeout(() => {
+						if (generation !== startupGeneration) return;
+						void (async () => {
+							try {
+								const result = await regenerateRegistry(cwd, true);
+								if (result.warning) notifyWarning(result.warning);
+							} catch (error) {
+								notifyWarning(`Skill registry refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+							}
+						})();
+					}, WATCH_DEBOUNCE_MS);
+				}
+			} catch (error) {
+				if (ctx.hasUI) {
+					const message =
+						error instanceof Error ? error.message : String(error);
+					ctx.ui.notify(
+						`Skill registry refresh failed: ${message}`,
+						"warning",
+					);
+				}
 			}
+		};
+		// Pi awaits session_start handlers one after another, so the Git tracking
+		// checks and the skill scan run after startup instead of inside it.
+		const startup = new Promise<void>((resolve) => setImmediate(resolve))
+			.then(regenerate)
+			.catch(() => { /* A replaced session's stale UI must not surface here. */ })
+			.finally(() => { if (pendingStartups.get(cwd) === startup) pendingStartups.delete(cwd); });
+		pendingStartups.set(cwd, startup);
+		try {
 			if (ctx.hasUI) {
-				await startSkillRegistryWatcher(ctx.cwd, (message) => {
-					ctx.ui.notify(message, "info");
+				await startSkillRegistryWatcher(cwd, (message, level = "info") => {
+					ctx.ui.notify(message, level);
 				});
 			}
-			if (quarantinedLegacy) {
-				setTimeout(() => {
-					void (async () => {
-						try {
-							await regenerateRegistry(ctx.cwd, true);
-						} catch {
-							// Best-effort same-session self-heal in case the stale extension already ran.
-						}
-					})();
-				}, WATCH_DEBOUNCE_MS);
-			}
 		} catch (error) {
-			if (ctx.hasUI) {
-				const message =
-					error instanceof Error ? error.message : String(error);
-				ctx.ui.notify(
-					`Skill registry refresh failed: ${message}`,
-					"warning",
-				);
-			}
+			notifyWarning(`Skill registry refresh failed: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	});
 
@@ -610,8 +739,8 @@ export default function (pi: ExtensionAPI) {
 		description: "Regenerate .atl/skill-registry.md from local skill sources.",
 		handler: async (_args, ctx) => {
 			try {
-				await ensureAtlIgnored(ctx.cwd);
-				const result = await regenerateRegistry(ctx.cwd, true);
+				await ensureAtlIgnored(ctx.cwd, true);
+				const result = await regenerateRegistry(ctx.cwd, true, true);
 				ctx.ui.notify(
 					`Skill registry: ${result.skillCount} skill(s) written to ${REGISTRY_REL_PATH}`,
 					"info",

package/extensions/startup-banner.ts

@@ -7,6 +7,7 @@ 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";
 
 
 export type BannerColor = "pink" | "cyan" | "yellow" | "green";
@@ -67,7 +68,7 @@ function rgb(r: number, g: number, b: number, text: string): string {
 }
 
 function gentleAiConfigHome(): string {
-  return process.env.GENTLE_PI_CONFIG_HOME ?? join(os.homedir(), ".pi", "gentle-ai");
+  return bundledGentlePiConfigHome(process.env) ?? process.env.GENTLE_PI_CONFIG_HOME ?? join(os.homedir(), ".pi", "gentle-ai");
 }
 
 function bannerConfigPath(configHome = gentleAiConfigHome()): string {
@@ -548,12 +549,17 @@ async function countPackageExtensions(packages: unknown[]): Promise<number> {
   return count;
 }
 
-export function readGitBranch(cwd: string, run: typeof execFile = execFile): Promise<string> {
+// A repository rooted at HOME can make even this lookup crawl; a timeout reads
+// as the ordinary failure instead of holding the banner stats.
+const GIT_BRANCH_TIMEOUT_MS = 3000;
+
+export function readGitBranch(cwd: string, run: typeof execFile = execFile, timeoutMs = GIT_BRANCH_TIMEOUT_MS): Promise<string> {
   return new Promise((resolve) => {
     run("git", ["-C", cwd, "branch", "--show-current"], {
       encoding: "utf8",
       shell: false,
       windowsHide: true,
+      timeout: timeoutMs,
     }, (error, stdout) => {
       if (error) {
         resolve("Not a git repo");
@@ -647,6 +653,9 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     disposeHeader();
     if (!ctx.hasUI) return;
+    // Delegated rpc children report hasUI=true but have no terminal to paint
+    // (gentle-shell#1690); do not rely on a piped stdout lacking rows/columns.
+    if (process.env.GENTLE_PI_AGENTS_CHILD === "1") return;
 
     // CLI subcommands such as `pi update` or `pi install` skip the animated intro.
     if (isPiCliSubcommandInvocation(process.argv)) return;

package/lib/agent-home.ts

@@ -1,5 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { bundledGentlePiConfigHome, runningBundledPrefix } 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.
@@ -11,6 +12,14 @@ 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).
 export function gentlePiConfigHome(env: NodeJS.ProcessEnv = process.env): string {
-	return env.GENTLE_PI_CONFIG_HOME || join(homedir(), ".pi", "gentle-ai");
+	return bundledGentlePiConfigHome(env) ?? (env.GENTLE_PI_CONFIG_HOME || join(homedir(), ".pi", "gentle-ai"));
+}
+
+// The agent home Pi runs with, only in a bundled Gentle Shell (S9): there the
+// extensions that otherwise write under ~/.pi/agent keep their files in it.
+// Undefined elsewhere, where they keep their existing locations.
+export function bundledGentlePiAgentHome(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	return runningBundledPrefix(env) === undefined ? undefined : resolveGentlePiAgentHome(env);
 }

package/lib/agent-model-resolution.ts

@@ -0,0 +1,80 @@
+import { join, resolve } from "node:path";
+import { resolveGentlePiAgentHome } from "./agent-home.ts";
+import { resolveProfilePin } from "./agent-profile-pin.ts";
+import {
+	discoverAgents,
+	loadAgentsConfig,
+	resolveAgentProfile,
+	withPinnedModelProfiles,
+	type AgentDefinition,
+	type DiscoveryRoots,
+	type ModelRef,
+	type ResolvedProfile,
+} from "./agents-config.ts";
+import type { WorktreeResolver } from "./session-worktree-registry.ts";
+
+// gentle-shell#1731: subagent launches and the harness model-routing fact share
+// one resolution of the effective subagent model, so the fact the orchestrator
+// reads can never disagree with the model a launch would actually use.
+
+export interface AgentHomeSelection {
+	env: NodeJS.ProcessEnv;
+	home: string;
+	/** An explicit agent home, kept literal. */
+	agentHome?: string;
+	/** An explicit home selects `<home>/.pi/agent` and ignores the environment. */
+	homeOverridden?: boolean;
+}
+
+/** The agent home Gentle Agents discovers definitions and `subagents.json` from. */
+export function resolveAgentHomeDirectory(selection: AgentHomeSelection): string {
+	const selectedHome = selection.agentHome ?? (selection.homeOverridden ? join(selection.home, ".pi", "agent") : resolveGentlePiAgentHome(selection.env));
+	// Expand environment tildes like Pi, but leave explicit path APIs literal.
+	const environmentHome = selection.agentHome === undefined && !selection.homeOverridden;
+	const expandedHome = environmentHome && selectedHome === "~" ? selection.home
+		: environmentHome && (selectedHome.startsWith("~/") || (process.platform === "win32" && selectedHome.startsWith("~\\"))) ? join(selection.home, selectedHome.slice(2)) : selectedHome;
+	return resolve(expandedHome);
+}
+
+export interface AgentProfileScope {
+	roots: DiscoveryRoots;
+	/** The directory whose repository profile pin applies to the launch. */
+	pinCwd: string;
+	configHome: string;
+	resolveWorktree?: WorktreeResolver;
+}
+
+/**
+ * The launch profile for an agent: global and project `subagents.json`, with a
+ * repository profile pin replacing `modelProfiles` wholesale when one applies.
+ */
+export function resolvePinnedAgentProfile(agent: AgentDefinition, scope: AgentProfileScope): ResolvedProfile {
+	const config = withPinnedModelProfiles(
+		loadAgentsConfig(scope.roots),
+		resolveProfilePin({ cwd: scope.pinCwd, configHome: scope.configHome, resolveWorktree: scope.resolveWorktree })?.modelProfiles,
+	);
+	return resolveAgentProfile(agent, config);
+}
+
+export interface EffectiveAgentModel {
+	agent: string;
+	model: ModelRef | undefined;
+	/** No profile, definition, or default routes the agent: it inherits the session model. */
+	inherited: boolean;
+}
+
+/**
+ * The model a launch of `agentName` would use, falling back to the session model
+ * when nothing routes it; `undefined` when the agent is not discovered.
+ */
+export function resolveEffectiveAgentModel(
+	agentName: string,
+	scope: AgentProfileScope & { fallback?: ModelRef },
+): EffectiveAgentModel | undefined {
+	const agent = discoverAgents(scope.roots).agents.find((candidate) => candidate.name === agentName);
+	if (!agent) return undefined;
+	const profile = resolvePinnedAgentProfile(agent, scope);
+	return profile.model === undefined
+		? { agent: agentName, model: scope.fallback, inherited: true }
+		: { agent: agentName, model: profile.model, inherited: false };
+}

package/lib/agent-profiles.ts

@@ -406,18 +406,28 @@ export interface ProfileListItem {
 	description: string;
 }
 
+/** One list item per saved profile, named with the markers that explain what a launch would use: the global `(active)` claim, plus `(pinned)` for the pin winner or `(session)` for this session's binding when either applies. */
 export function buildProfileListItems(
 	file: AgentProfilesFile,
 	pinned?: string,
+	sessionBound?: string,
 ): ProfileListItem[] {
 	return Object.entries(file.profiles).map(([name, config]) => {
 		const roles = profileRoleEntries(config).length;
 		const active = 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. A session
+		// binding outranks the pin in this list (slice 1 stores it; slice 2,
+		// gentle-shell#1558, makes launches resolve it), so its marker wins on the
+		// same profile.
+		const label = name === sessionBound
+			? `${active} (session)`
+			: name === pinned
+				? `${active} (pinned)`
+				: active;
 		return {
 			id: 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,
+			label,
 			description: `${roles} ${roles === 1 ? "role" : "roles"}`,
 		};
 	});

package/lib/agents-completion-delivery.ts

@@ -11,9 +11,10 @@
 // behavior is unit-testable against a fake clock.
 
 /**
- * A completion older than this at flush time is stale: the parent had many
- * turns to pull the result with subagent_result, so replaying it into the
- * model context would re-enter state the conversation may already have used.
+ * A completion older than this at flush time is stale: replaying its full
+ * report into the model context could re-enter state the conversation may
+ * already have used, so the parent gets a compact notice instead. The parent
+ * is told never to poll, so a stale completion must still announce itself.
  * Ninety seconds comfortably covers one slow orchestrator turn (model latency
  * plus a few tool calls) while staying orders of magnitude below the 50-58
  * minute followUp delays measured in issue #867.
@@ -36,6 +37,8 @@ export interface CompletionQueue<T extends { id: string }> {
 	consume(taskId: string): void;
 	/** Remove and return the still-pending completions in settle order, each with its staleness decision at `now`. Consumed entries are dropped and never returned. */
 	takeDeliverable(now: number): Array<DeliverableCompletion<T>>;
+	/** Return a taken completion whose forwarding failed to the pending queue, so a later flush retries it. A consumed id stays dropped. */
+	requeue(entry: DeliverableCompletion<T>): void;
 	/** Discard everything: pending completions and consumed/delivered bookkeeping. Used on session start and shutdown so nothing replays after a resume. */
 	dropAll(): void;
 }
@@ -63,6 +66,11 @@ export function createCompletionQueue<T extends { id: string }>(): CompletionQue
 			}
 			return deliverable;
 		},
+		requeue(entry) {
+			delivered.delete(entry.task.id);
+			if (consumed.has(entry.task.id) || pending.some((pendingEntry) => pendingEntry.task.id === entry.task.id)) return;
+			pending.push({ task: entry.task, settledAt: entry.settledAt });
+		},
 		dropAll() {
 			pending = [];
 			consumed.clear();

package/lib/agents-messaging.ts

@@ -95,7 +95,7 @@ function parseAck(value: unknown): AckFrame | undefined {
 	if (!record(value) || !exact(value, ["id", "kind", "accepted", "error"]) || !validChildId(value.id) || value.kind !== "ack" || typeof value.accepted !== "boolean") return undefined;
 	if (value.accepted && value.error !== undefined) return undefined;
 	if (value.error !== undefined && !boundedText(value.error, CHILD_ACK_ERROR_MAX_BYTES)) return undefined;
-	return { id: value.id, accepted: value.accepted, ...(value.error === undefined ? {} : { error: value.error }) };
+	return { id: value.id, accepted: value.accepted, ...(typeof value.error === "string" ? { error: value.error } : {}) };
 }
 
 function parseReply(value: unknown): ReplyFrame | undefined {

package/lib/agents-protocol.ts

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { sanitizeTerminalText } from "./terminal-theme.ts";
 
 // Gentle Agents protocol. A child pi process streams RPC events; the host
@@ -148,10 +148,23 @@ export interface TaskSummary {
 
 export type TaskListener = (task: TaskRecord, thread: TaskThread) => void;
 export type SummaryListener = (summary: TaskSummary) => void;
+export interface TaskStatusChange {
+	readonly producerId: string;
+	readonly sessionId: string;
+	readonly parentSessionId: string;
+	readonly taskId: string;
+	readonly runId: string;
+	readonly status: TaskStatus;
+	readonly previousStatus?: TaskStatus;
+	readonly sequence: number;
+}
+export type StatusChangeListener = (change: TaskStatusChange) => void | Promise<void>;
 
 const DEFAULT_LIMITS: ThreadLimits = { maxItems: 400, maxOutputChars: 16_000 };
 /** 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). */
+export const MISSING_TOOLS_NOTE_PREFIX = "gentle-agents: requested tools missing in child:";
 const LABEL_MAX = 72;
 const TEXT_CAP = 20_000;
 const ELLIPSIS = "…";
@@ -330,6 +343,7 @@ export function normalizeRpcEvent(raw: unknown, options: { observeResponses?: bo
 		case "agent_settled":
 			return [{ type: TASK_EVENT.AGENT_SETTLED }];
 		case "extension_ui_request":
+			if (event.method === "notify" && typeof event.message === "string" && event.message.startsWith(MISSING_TOOLS_NOTE_PREFIX)) return [{ type: TASK_EVENT.NOTE, text: clean(event.message) }];
 			return DIALOG_METHODS.has(String(event.method)) ? [{ type: TASK_EVENT.ASK, request: askRequest(event) }] : [];
 		case "auto_retry_start":
 			return [{ type: TASK_EVENT.NOTE, text: `retrying (${String(event.attempt ?? "?")}/${String(event.maxAttempts ?? "?")})` }];
@@ -460,14 +474,21 @@ export class TaskStore {
 	private readonly listeners = new Map<string, Set<TaskListener>>();
 	private readonly summaryListeners = new Set<SummaryListener>();
 	private readonly limits: Partial<ThreadLimits>;
+	private readonly producerId = randomUUID();
+	private sequence = 0;
+	private readonly runIds = new Map<string, string>();
+	private readonly statusListeners = new Set<StatusChangeListener>();
 
 	constructor(limits: Partial<ThreadLimits> = {}) {
 		this.limits = limits;
 	}
 
 	add(task: TaskRecord): void {
+		const previous = this.tasks.get(task.id)?.status;
+		if (!this.tasks.has(task.id)) this.runIds.set(task.id, randomUUID());
 		this.tasks.set(task.id, task);
 		this.threads.set(task.id, emptyThread(this.limits));
+		this.notifyStatus(task, previous);
 		this.notifySummary();
 	}
 
@@ -476,6 +497,7 @@ export class TaskStore {
 	restore(task: TaskRecord, thread: TaskThread): boolean {
 		if (this.tasks.has(task.id)) return false;
 		this.tasks.set(task.id, task);
+		this.runIds.set(task.id, randomUUID());
 		this.threads.set(task.id, { ...thread, limits: { ...DEFAULT_LIMITS, ...this.limits } });
 		this.notifySummary();
 		return true;
@@ -506,6 +528,7 @@ export class TaskStore {
 		if (!current) return undefined;
 		const next = { ...current, ...patch };
 		this.tasks.set(id, next);
+		this.notifyStatus(next, current.status);
 		this.notifyTask(next);
 		if (next.status !== current.status) this.notifySummary();
 		return next;
@@ -533,6 +556,22 @@ export class TaskStore {
 		return () => this.summaryListeners.delete(listener);
 	}
 
+	/** Optional, content-free observer. Restores and unchanged snapshots are silent. */
+	subscribeStatusChanges(listener: StatusChangeListener): () => void {
+		this.statusListeners.add(listener);
+		return () => { this.statusListeners.delete(listener); };
+	}
+
+	private notifyStatus(task: TaskRecord, previousStatus?: TaskStatus): void {
+		if (task.status === previousStatus) return;
+		const change: TaskStatusChange = Object.freeze({ producerId: this.producerId,
+			sessionId: task.parentSessionId, parentSessionId: task.parentSessionId, taskId: task.id,
+			runId: this.runIds.get(task.id)!, status: task.status, previousStatus, sequence: ++this.sequence });
+		for (const listener of [...this.statusListeners]) {
+			try { void Promise.resolve(listener(change)).catch(() => {}); } catch { /* Observability cannot fail a mutation. */ }
+		}
+	}
+
 	private notifyTask(task: TaskRecord): void {
 		const set = this.listeners.get(task.id);
 		if (!set) return;