gentle-pi 4.3.0 → 4.4.0

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-widget.ts

@@ -1,6 +1,7 @@
 import { visibleWidth } from "@earendil-works/pi-tui";
 import { isFinished, TASK_STATUS, type TaskRecord, type TaskStatus } from "./agents-protocol.ts";
 import { formatCost, formatTokens } from "./shell-bar.ts";
+import { paintHoverable } from "./shell-hover.ts";
 import { CARD_TONE, panelExtraRows, panelInnerWidth, renderCard, type CardTheme, type CardTone } from "./shell-card.ts";
 
 // Gentle Agents widget: the card above the editor. Reads task records only
@@ -17,6 +18,10 @@ export interface AgentsWidgetOptions {
 	// "… N more" line so the card never pushes the editor off the screen.
 	maxRows?: number;
 	viewKey?: string;
+	// Paint the clickable "▾ Collapse" / "▸ Expand" control in the header, the
+	// same control the Todos card carries; hovered paints its hover role.
+	collapseControl?: boolean;
+	hovered?: boolean;
 }
 
 interface StatusLook {
@@ -297,6 +302,11 @@ function batchElapsed(tasks: readonly TaskRecord[], now: number): string | undef
 	return formatElapsed(end - Math.min(...starts));
 }
 
+/** The tone the card paints for these tasks, so a host can locate its header row. */
+export function agentsCardTone(tasks: readonly TaskRecord[], now: number): CardTone {
+	return tone(widgetTasks(tasks, now));
+}
+
 export function renderAgentsCard(tasks: readonly TaskRecord[], theme: CardTheme, width: number, now: number, options: AgentsWidgetOptions): string[] {
 	const shown = widgetTasks(tasks, now);
 	if (shown.length === 0) return [];
@@ -310,8 +320,11 @@ export function renderAgentsCard(tasks: readonly TaskRecord[], theme: CardTheme,
 	const hint = options.collapsed && options.collapseKey ? `${options.collapseKey} expand` : shown.length > 1 ? batchElapsed(shown, now) : undefined;
 	const body = listed.flatMap((task) => row(task, theme, cols, now, options.maxRows === undefined));
 	if (hidden > 0) body.push(overflowRow(hidden, theme, options.viewKey));
+	const icon = options.collapsed ? "▸" : "▾";
+	const control = `${icon} ${width >= 28 ? (options.collapsed ? "Expand" : "Collapse") : ""}`.trimEnd();
+	const title = options.collapseControl ? `Agents ${paintHoverable(theme, control, options.hovered ?? false, "accent")}` : "Agents";
 	return renderCard(
-		{ title: "Agents", subtitle: counts(shown), body, tone: tone(shown), glyph: AGENTS_GLYPH },
+		{ title, subtitle: counts(shown), body, tone: tone(shown), glyph: AGENTS_GLYPH },
 		theme,
 		width,
 		{ expanded: true, hint, panel: true },

package/lib/auto-permission-memory.ts

@@ -6,23 +6,41 @@ export interface AutoPermissionMemoryContext {
  project: string;
  cwd: string;
 }
+/** First failed provenance predicate, in evaluation order. */
+export type AutoPermissionMemorySourceRejection = "tool-missing" | "tool-ambiguous" | "metadata-missing" | "origin" | "source-format" | "path";
+/** Closed, content-free observation of the latest binder decision; never an authorization input. */
+export type AutoPermissionMemoryDiagnostic =
+ | {stage:"admission" | "write"; reason:"untrusted-source"; sourceRejection:AutoPermissionMemorySourceRejection}
+ | ({sourceRejection?:undefined} & (
+  | {stage:"admission"; reason:"admitted" | "invalid-request" | "unexpected-error"}
+  | {stage:"resolution"; reason:"bound" | "provider-error" | "stale-identity" | "invalid-request" | "invalid-result" | "unexpected-error"}
+  | {stage:"write"; reason:"attached" | "stale-binding" | "source-mismatch" | "destination-mismatch" | "invalid-arguments" | "unexpected-error"}
+  | {stage:"clear"; reason:"binding-cleared"}));
 type Call = Pick<ToolCallEvent,"toolName"|"input"|"toolCallId">;
 type Identity = {manager: ExtensionContext["sessionManager"]; id:string; cwd:string; epoch:number; anchor:string; source:string};
+type Source = {source:string; rejection?:undefined} | {source?:undefined; rejection:AutoPermissionMemorySourceRejection};
 /** Live native-provider evidence only: never restore bindings from transcript text. */
 export class AutoPermissionMemory {
  private readonly tools: () => ToolInfo[];
  constructor(tools: () => ToolInfo[]) { this.tools=tools; }
  private pending?: Identity & {callId:string};
  private binding?: Identity & {project:string};
- clear(): void { this.pending=undefined;this.binding=undefined; }
- private source(name:string):string|undefined {
+ private last?: AutoPermissionMemoryDiagnostic;
+ /** Snapshot of the latest decision; mutating it never affects the binder. */
+ diagnostic(): AutoPermissionMemoryDiagnostic | undefined { return this.last && {...this.last}; }
+ clear(): void { this.reset();this.last={stage:"clear",reason:"binding-cleared"}; }
+ private reset(): void { this.pending=undefined;this.binding=undefined; }
+ private inspect(name:string):Source {
   const matches=this.tools().filter(tool=>tool.name===name);
-  if(matches.length!==1)return undefined;
+  if(matches.length!==1)return {rejection:matches.length ? "tool-ambiguous" : "tool-missing"};
   const s=matches[0].sourceInfo;
-  if(!s || s.origin!=="package" || !/^npm:gentle-engram(?:@[^\s/]+)?$/.test(s.source) ||
-   typeof s.path!=="string" || !s.path || s.path.startsWith("builtin:") || s.path.startsWith("<"))return undefined;
-  return JSON.stringify([s.path,s.source,s.scope,s.origin,s.baseDir ?? null]);
+  if(!s)return {rejection:"metadata-missing"};
+  if(s.origin!=="package")return {rejection:"origin"};
+  if(!/^npm:gentle-engram(?:@[^\s/]+)?$/.test(s.source))return {rejection:"source-format"};
+  if(typeof s.path!=="string" || !s.path || s.path.startsWith("builtin:") || s.path.startsWith("<"))return {rejection:"path"};
+  return {source:JSON.stringify([s.path,s.source,s.scope,s.origin,s.baseDir ?? null])};
  }
+ private source(name:string):string|undefined { return this.inspect(name).source; }
  private valid(value:Identity,ctx:ExtensionContext,epoch:number):boolean {
   return value.manager===ctx.sessionManager && value.id===ctx.sessionManager.getSessionId() && value.cwd===ctx.cwd &&
    value.epoch===epoch && this.source("mem_current_project")===value.source &&
@@ -30,40 +48,52 @@ export class AutoPermissionMemory {
  }
  admitted(event:Call,ctx:ExtensionContext,epoch:number):void {
   if(event.toolName!=="mem_current_project")return;
-  this.clear();
+  this.reset();
   try {
-   const source=this.source(event.toolName),id=ctx.sessionManager.getSessionId();
+   const {source,rejection}=this.inspect(event.toolName),id=ctx.sessionManager.getSessionId();
    const args=event.input as Record<string,unknown>;
    const anchor=ctx.sessionManager.getBranch().at(-1)?.id;
+   if(rejection){this.last={stage:"admission",reason:"untrusted-source",sourceRejection:rejection};return;}
    if(!source || !id || !anchor || !args || args.cwd!==ctx.cwd ||
-    Object.keys(args).some(key=>key!=="cwd"))return;
+    Object.keys(args).some(key=>key!=="cwd")){this.last={stage:"admission",reason:"invalid-request"};return;}
    this.pending={manager:ctx.sessionManager,id,cwd:ctx.cwd,epoch,anchor,source,callId:event.toolCallId};
-  } catch { this.clear(); }
+   this.last={stage:"admission",reason:"admitted"};
+  } catch { this.reset();this.last={stage:"admission",reason:"unexpected-error"}; }
  }
  result(event:ToolResultEvent,ctx:ExtensionContext,epoch:number):void {
   if(event.toolName!=="mem_current_project")return;
   const pending=this.pending;
   if(!pending || event.toolCallId!==pending.callId)return;
-  this.clear();
+  this.reset();
   try {
-   if(event.isError || !this.valid(pending,ctx,epoch) || (event.input as Record<string,unknown>)?.cwd!==ctx.cwd)return;
+   if(event.isError){this.last={stage:"resolution",reason:"provider-error"};return;}
+   if(!this.valid(pending,ctx,epoch)){this.last={stage:"resolution",reason:"stale-identity"};return;}
+   if((event.input as Record<string,unknown>)?.cwd!==ctx.cwd){this.last={stage:"resolution",reason:"invalid-request"};return;}
    const data=(event.details as {data?:Record<string,unknown>} | undefined)?.data;
    if(!data || data.cwd!==ctx.cwd || typeof data.project!=="string" || !data.project.trim() || data.project.length>256 ||
     /[\p{Cc}\p{Cf}\p{Cs}]/u.test(data.project) || typeof data.project_source!=="string" || !["git_remote","dir_basename"].includes(data.project_source) ||
     (data.available_projects!=null && (!Array.isArray(data.available_projects) || data.available_projects.length>0)) ||
-    Object.keys(data).some(key=>/error|warning|fallback/i.test(key)))return;
+    Object.keys(data).some(key=>/error|warning|fallback/i.test(key))){this.last={stage:"resolution",reason:"invalid-result"};return;}
    this.binding={...pending,project:data.project};
-  } catch { this.clear(); }
+   this.last={stage:"resolution",reason:"bound"};
+  } catch { this.reset();this.last={stage:"resolution",reason:"unexpected-error"}; }
  }
+ /** Without a binding the diagnostic keeps the cause that prevented one. */
  context(event:Pick<Call,"toolName"|"input">,ctx:ExtensionContext,epoch:number):AutoPermissionMemoryContext|undefined {
   try {
    if(event.toolName!=="mem_save" && event.toolName!=="mem_session_summary")return undefined;
    const binding=this.binding,args=event.input as Record<string,unknown>;
-   if(!binding || !this.valid(binding,ctx,epoch) || this.source(event.toolName)!==binding.source ||
-    !args || args.cwd!==ctx.cwd || args.project!==binding.project || (args.scope!==undefined && args.scope!=="project"))return undefined;
+   if(!binding)return undefined;
+   if(!this.valid(binding,ctx,epoch)){this.last={stage:"write",reason:"stale-binding"};return undefined;}
+   const {source,rejection}=this.inspect(event.toolName);
+   if(rejection){this.last={stage:"write",reason:"untrusted-source",sourceRejection:rejection};return undefined;}
+   if(source!==binding.source){this.last={stage:"write",reason:"source-mismatch"};return undefined;}
+   if(!args || args.cwd!==ctx.cwd || args.project!==binding.project || (args.scope!==undefined && args.scope!=="project")){
+    this.last={stage:"write",reason:"destination-mismatch"};return undefined;}
    const allowed=event.toolName==="mem_save" ? ["cwd","project","title","content","type","scope","topic_key","capture_prompt"] : ["cwd","project","content"];
-   if(Object.keys(args).some(key=>!allowed.includes(key)))return undefined;
+   if(Object.keys(args).some(key=>!allowed.includes(key))){this.last={stage:"write",reason:"invalid-arguments"};return undefined;}
+   this.last={stage:"write",reason:"attached"};
    return {provider:"gentle-engram",operation:event.toolName,project:binding.project,cwd:binding.cwd};
-  } catch { return undefined; }
+  } catch { this.last={stage:"write",reason:"unexpected-error"};return undefined; }
  }
 }

package/lib/auto-permission-runtime.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { lstatSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import type { ExtensionAPI, ExtensionContext, InputEvent, ToolCallEvent, ToolCallEventResult, ToolResultEvent } from "@earendil-works/pi-coding-agent";
 import { gentlePiConfigHome } from "./agent-home.ts";
@@ -18,7 +18,7 @@ export function updateAutoPrompt(options: AppendableSystemPromptOptions | undefi
  if (active) appendSystemPromptOnce(options, AUTO_DIRECTIVE);
 }
 
-type ModeController = {mode(ctx: ExtensionContext): Promise<string>; epoch(): number};
+type ModeController = {mode(ctx: ExtensionContext, admission?: { toolCallId: string }): Promise<string>; epoch(): number};
 type Verdict = {status: string; decision?: string; reason?: string; code?: string; usage?: unknown; usageKnown?: boolean; actualModel?: unknown; requestedModel?: unknown; diagnostic?: unknown};
 /** Project a closed metadata schema; injected classifiers cannot add payloads to diagnostics. */
 function safeDiagnostic(value: unknown): AutoPermissionDiagnostic | undefined {
@@ -96,7 +96,8 @@ function within(path: string, root: string): boolean {
 function canonical(path: string): string {
  const absolute = resolve(path);
  let ancestor = absolute;
- while (!existsSync(ancestor)) { const parent = dirname(ancestor); if (parent === ancestor) break; ancestor = parent; }
+ // A dangling symlink exists as a directory entry: let realpath fail closed.
+ while (!lstatSync(ancestor,{throwIfNoEntry:false})) { const parent = dirname(ancestor); if (parent === ancestor) break; ancestor = parent; }
  return resolve(realpathSync(ancestor), relative(ancestor, absolute));
 }
 /** True only for an existing symlink-free in-project regular file larger than the reader accepts.
@@ -368,8 +369,22 @@ export class AutoPermissionRuntime {
  private protectedMutation(event: Pick<ToolCallEvent,"toolName"|"input">, ctx: ExtensionContext): boolean {
   const args=event.input as Record<string,unknown>;
   if (!args || typeof args!=="object") return false;
+  const projectHome=resolve(ctx.cwd,".pi","gentle-ai");
   if ((event.toolName==="write" || event.toolName==="edit") && typeof args.path==="string") {
-   try { return within(canonical(resolve(ctx.cwd,args.path)),canonical(this.configHome)); } catch { return true; }
+   try {
+    const target=canonical(resolve(ctx.cwd,args.path)),home=canonical(this.configHome);
+    // Keep policy aliases and containing directories protected, including project restrictions.
+    if([resolve(this.configHome,"permission-mode.json"),resolve(this.configHome,"runtime-guardrails.json"),
+     resolve(projectHome,"runtime-guardrails.json")].some(path=>within(canonical(path),target)))return true;
+    if(!within(target,home))return false;
+    // A shared inode can alias policy without changing the canonical path.
+    if((lstatSync(target,{throwIfNoEntry:false})?.nlink ?? 0)>1)return true;
+    // Only updater-owned data returns to ordinary permission checks. Compare the
+    // resolved target to literal destinations under home: canonicalizing exemptions
+    // would let a dev-binary.json symlink exempt the authority file it points at.
+    return !["dev-binary.json","channel.json"].some(path=>target===resolve(home,path)) &&
+     !["main","tools/go"].some(path=>within(target,resolve(home,path)));
+   } catch { return true; }
   }
   if (["bash","bash_background","monitor"].includes(event.toolName) && typeof args.command==="string") {
    // Best-effort shell recognition supplements classification, not OS containment.
@@ -395,7 +410,7 @@ export class AutoPermissionRuntime {
   if(this.protectedMutation(event,ctx))return block("Permission configuration is human-controlled. Use the mode settings UI; model tools cannot change it.");
   // Revocation while identity lookup is pending must not become a fresh grant.
   const generation=this.generation, epoch=this.modes.epoch(), owner=this.owner;
-  const mode=await this.modes.mode(ctx);
+  const mode=await this.modes.mode(ctx,{toolCallId:event.toolCallId});
   if(generation!==this.generation || epoch!==this.modes.epoch() || owner!==this.owner || ctx.signal?.aborted)
    return block("Auto decision expired during mode lookup. The action was not run.");
   if(mode!=="auto") { this.memory.admitted(event,ctx,epoch);return undefined; }
@@ -452,7 +467,7 @@ export class AutoPermissionRuntime {
     if(result.status==="available" || result.code!=="provider-error" || controller.signal.aborted)break;
    }
   }finally{ctx.signal?.removeEventListener("abort",onAbort);this.active.delete(controller);}
-  const stillAuto=await this.modes.mode(ctx)==="auto";
+  const stillAuto=await this.modes.mode(ctx,{toolCallId:event.toolCallId})==="auto";
   if(!current() || controller.signal.aborted || !stillAuto)return block("Auto decision expired because the action, mode, request or session changed. The action was not run.");
   if(result.status!=="available" || !["allow","deny"].includes(result.decision ?? "")){
    // Contention and revocation are not failed safety judgements or provider outages.

package/lib/clipboard-image.ts

@@ -0,0 +1,147 @@
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { getNativeClipboard, type NativeClipboard } from "@earendil-works/pi-tui";
+
+// Clipboard image reader for the prompt's attachment chips (gentle-shell#2464).
+// Pi reads the same backends but does not export its reader, and its handler
+// writes the image to a temp file and inserts the path. This reader keeps the
+// bytes in memory and returns null whenever Pi's own handler should decide
+// instead: no image, an unsupported format, or files copied in a file manager.
+
+export interface ClipboardImage {
+	bytes: Uint8Array;
+	mimeType: string;
+}
+
+/** Resolves to stdout, or undefined when the command is missing, fails, or times out. */
+export type ClipboardCommandRunner = (command: string, args: readonly string[], options?: { timeoutMs?: number }) => Promise<Buffer | undefined>;
+
+export interface ClipboardImageOptions {
+	env?: NodeJS.ProcessEnv;
+	platform?: NodeJS.Platform;
+	run?: ClipboardCommandRunner;
+	native?: () => NativeClipboard | undefined;
+	procVersion?: () => string | undefined;
+}
+
+export const SUPPORTED_IMAGE_MIME_TYPES = ["image/png", "image/jpeg", "image/webp", "image/gif"] as const;
+
+const LIST_TIMEOUT_MS = 1000;
+const READ_TIMEOUT_MS = 5000;
+const POWERSHELL_TIMEOUT_MS = 10_000;
+const MAX_CLIPBOARD_BYTES = 64 * 1024 * 1024;
+
+// Encodes the Windows clipboard image as PNG on stdout, so nothing touches disk.
+const POWERSHELL_SCRIPT = [
+	"Add-Type -AssemblyName System.Windows.Forms",
+	"Add-Type -AssemblyName System.Drawing",
+	"$img = [System.Windows.Forms.Clipboard]::GetImage()",
+	"if (-not $img) { exit 0 }",
+	"$ms = New-Object System.IO.MemoryStream",
+	"$img.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)",
+	"[Convert]::ToBase64String($ms.ToArray())",
+].join("; ");
+
+export const runClipboardCommand: ClipboardCommandRunner = (command, args, options) => new Promise((resolve) => {
+	execFile(command, [...args], { encoding: "buffer", timeout: options?.timeoutMs ?? READ_TIMEOUT_MS, maxBuffer: MAX_CLIPBOARD_BYTES, windowsHide: true }, (error, stdout) => {
+		resolve(error ? undefined : stdout);
+	});
+});
+
+/** Identify a supported image by its signature, never by a clipboard-declared type. */
+export function sniffImageMimeType(bytes: Uint8Array): string | undefined {
+	const starts = (...signature: number[]) => signature.every((byte, index) => bytes[index] === byte);
+	if (starts(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)) return "image/png";
+	if (starts(0xff, 0xd8, 0xff)) return "image/jpeg";
+	if (starts(0x47, 0x49, 0x46, 0x38)) return "image/gif";
+	if (starts(0x52, 0x49, 0x46, 0x46) && bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50) return "image/webp";
+	return undefined;
+}
+
+export function isWsl(env: NodeJS.ProcessEnv, procVersion: () => string | undefined = readProcVersion): boolean {
+	if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) return true;
+	return /microsoft|wsl/i.test(procVersion() ?? "");
+}
+
+function readProcVersion(): string | undefined {
+	try { return readFileSync("/proc/version", "utf8"); } catch { return undefined; }
+}
+
+function supported(bytes: Uint8Array | null): ClipboardImage | null {
+	if (!bytes || bytes.length === 0) return null;
+	const mimeType = sniffImageMimeType(bytes);
+	return mimeType ? { bytes, mimeType } : null;
+}
+
+// A failed read is "backend unavailable", exactly as Pi treats it, so the next backend still runs.
+function supportedRead(bytes: Buffer | undefined): ClipboardImage | null | undefined {
+	return bytes === undefined ? undefined : supported(bytes);
+}
+
+function preferredImageType(listing: Buffer): string | undefined {
+	const types = listing.toString("utf8").split(/\r?\n/).map((type) => type.trim()).filter(Boolean);
+	return SUPPORTED_IMAGE_MIME_TYPES.find((wanted) => types.some((type) => type.split(";")[0]?.trim().toLowerCase() === wanted));
+}
+
+// undefined: backend unavailable, try the next one. null: backend answered, no usable image.
+async function viaWlPaste(run: ClipboardCommandRunner): Promise<ClipboardImage | null | undefined> {
+	const listing = await run("wl-paste", ["--list-types"], { timeoutMs: LIST_TIMEOUT_MS });
+	if (listing === undefined) return undefined;
+	const type = preferredImageType(listing);
+	if (!type) return null;
+	return supportedRead(await run("wl-paste", ["--type", type, "--no-newline"]));
+}
+
+async function viaXclip(run: ClipboardCommandRunner): Promise<ClipboardImage | null | undefined> {
+	const listing = await run("xclip", ["-selection", "clipboard", "-t", "TARGETS", "-o"], { timeoutMs: LIST_TIMEOUT_MS });
+	if (listing === undefined) return undefined;
+	const type = preferredImageType(listing);
+	if (!type) return null;
+	return supportedRead(await run("xclip", ["-selection", "clipboard", "-t", type, "-o"]));
+}
+
+async function viaPowerShell(run: ClipboardCommandRunner): Promise<ClipboardImage | null> {
+	const output = await run("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-STA", "-Command", POWERSHELL_SCRIPT], { timeoutMs: POWERSHELL_TIMEOUT_MS });
+	const base64 = output?.toString("utf8").trim();
+	if (!base64) return null;
+	return supported(new Uint8Array(Buffer.from(base64, "base64")));
+}
+
+// Files copied in a file manager stay Pi's: it pastes their paths.
+async function hasCopiedFiles(native: NativeClipboard | undefined): Promise<boolean> {
+	const files = await native?.getFilePaths?.().catch(() => undefined);
+	return Boolean(files && files.length > 0);
+}
+
+async function viaNative(native: NativeClipboard | undefined): Promise<ClipboardImage | null> {
+	if (!native) return null;
+	return supported((await native.getImage().catch(() => undefined)) ?? null);
+}
+
+/**
+ * Read a supported image from the clipboard, mirroring Pi's backend order:
+ * Wayland, then X11, then the Windows clipboard on WSL, then the native
+ * clipboard. Returns null when Pi's own paste handler should run instead.
+ */
+export async function readClipboardImage(options: ClipboardImageOptions = {}): Promise<ClipboardImage | null> {
+	const env = options.env ?? process.env;
+	const platform = options.platform ?? process.platform;
+	const run = options.run ?? runClipboardCommand;
+	const native = options.native ?? getNativeClipboard;
+	if (env.TERMUX_VERSION) return null;
+	try {
+		const nativeClipboard = native();
+		if (await hasCopiedFiles(nativeClipboard)) return null;
+		if (platform !== "linux") return await viaNative(nativeClipboard);
+		const wsl = isWsl(env, options.procVersion);
+		let image: ClipboardImage | null | undefined;
+		if (env.WAYLAND_DISPLAY || env.XDG_SESSION_TYPE === "wayland" || wsl) image = await viaWlPaste(run);
+		if (image === undefined) image = await viaXclip(run);
+		// The Linux clipboard never receives Windows screenshots (Win+Shift+S).
+		if (!image && wsl) image = (await viaPowerShell(run)) ?? image;
+		if (image === undefined) image = await viaNative(nativeClipboard);
+		return image ?? null;
+	} catch {
+		return null;
+	}
+}

package/lib/command-palette-catalog.ts

@@ -42,6 +42,8 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 			{ command: "gentle:jobs", label: "Background jobs" },
 			{ command: "gentle:usage", label: "Subscription usage" },
 			{ command: "gentle:review-session-permission", label: "Review session permission" },
+			{ command: "gentle:voice", label: "Voice dictation · local Parakeet" },
+			{ command: "gentle:design", label: "Design · HTML artboards" },
 		],
 	},
 	{

package/lib/commit-slice-signal.ts

@@ -45,7 +45,7 @@ type Git = (args: string[], cwd: string) => Promise<string | undefined>;
 
 // Asynchronous, so the parent stays responsive while git answers.
 const runGit: Git = (args, cwd) => new Promise((resolve) => {
-	execFile("git", args, { cwd, encoding: "utf8", timeout: 2_000 }, (error, stdout) => resolve(error ? undefined : stdout.trim()));
+	execFile("git", args, { cwd, encoding: "utf8", timeout: 2_000, windowsHide: true }, (error, stdout) => resolve(error ? undefined : stdout.trim()));
 });
 
 async function defaultBranch(cwd: string, git: Git): Promise<string | undefined> {

package/lib/context-backstop.ts

@@ -12,6 +12,9 @@ export const CONTEXT_BACKSTOP_TOKENS = 150_000;
 export const CONTEXT_BACKSTOP_FRACTION = 0.15;
 export const CONTEXT_BACKSTOP_TOKENS_ENV = "GENTLE_PI_CONTEXT_BACKSTOP_TOKENS";
 export const CONTEXT_BACKSTOP_FRACTION_ENV = "GENTLE_PI_CONTEXT_BACKSTOP_FRACTION";
+// Sampling window for the measured context (see createThrottledContextMeasure).
+export const CONTEXT_BACKSTOP_MEASURE_MS_ENV = "GENTLE_PI_CONTEXT_BACKSTOP_MEASURE_MS";
+export const CONTEXT_BACKSTOP_MEASURE_MS_DEFAULT = 5_000;
 
 /** The part of Pi's `ctx.getContextUsage()` the backstop reads; null tokens are unknown (e.g. right after compaction). */
 export interface MeasuredContext {
@@ -69,6 +72,39 @@ export function createContextBackstopSignal(env: Env = process.env): (session: u
 	};
 }
 
+export interface ThrottledContextMeasureOptions {
+	now?: () => number;
+	/** Injected window in ms; 0 samples on every call (tests). Omitted resolves the env, then the 5 s default. */
+	minIntervalMs?: number;
+	env?: Env;
+}
+
+/**
+ * One measured context per session per window. `ctx.getContextUsage()` rebuilds the whole session projection
+ * (O(session) per call), so the backstop samples it instead of paying that on every tool result. The first
+ * sample of a session is immediate — a resumed session already past the backstop must not wait a window — and
+ * every call inside the window skips the measurement entirely, so the backstop sees `undefined` (unknown
+ * tokens change nothing). A throwing measure returns `undefined`; the failed attempt still consumed its
+ * window, so a persistently failing host cannot turn every tool result into a retry.
+ */
+export function createThrottledContextMeasure(options: ThrottledContextMeasureOptions = {}): (session: unknown, measure: () => MeasuredContext | undefined) => MeasuredContext | undefined {
+	const now = options.now ?? (() => Date.now());
+	const env = options.env ?? process.env;
+	const minIntervalMs = options.minIntervalMs ?? envNumber(env, CONTEXT_BACKSTOP_MEASURE_MS_ENV, positive, CONTEXT_BACKSTOP_MEASURE_MS_DEFAULT);
+	const lastMeasuredAt = new Map<unknown, number>();
+	return (session, measure) => {
+		const previous = lastMeasuredAt.get(session);
+		const at = now();
+		if (previous !== undefined && at - previous < minIntervalMs) return undefined;
+		lastMeasuredAt.set(session, at);
+		try {
+			return measure();
+		} catch {
+			return undefined;
+		}
+	};
+}
+
 /** Appends the notice after the (possibly already patched) tool output, keeping structured content and the error flag. */
 export function appendContextBackstopNotice(
 	event: Pick<ToolResultEvent, "content" | "structuredContent">,