gentle-pi 4.2.0 → 4.4.0

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/bounded-writer-admission.ts

@@ -1,6 +1,7 @@
 import { realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, parse, relative, resolve } from "node:path";
+import { contextBackstopReached, type MeasuredContext } from "./context-backstop.ts";
 import { resolveSessionWorktree, type WorktreeResolver } from "./session-worktree-registry.ts";
 
 const WRITER_NAMES = ["gentle-ai-worker", "worker", "jd-fix-agent"];
@@ -79,6 +80,56 @@ export function rejectUnscopedBoundedWriterDispatch(input: unknown): { block: tr
 	return { block: true, reason: `${WRITER_EDIT_SURFACE_REJECTION} ${parsed.problem} Resend the same task text unchanged except for that section; never shorten or re-summarize it.` };
 }
 
+// Pain-point iteration S16: prompt rules alone did not stop small-task delegation (a two-feature request still
+// started two writers for ~35-line units). A generic writer launch is admitted only for a task of an existing ODD
+// feature document, or when the parent's measured context reaches the context backstop (the same threshold as the
+// runtime notice, lib/context-backstop.ts). Judgment Day fix agents and continuations keep their own protocols.
+// A line that starts with `Spec:` (optionally as a list item), names an odd/tasks document, and names a task
+// `T<n>` later on the same line: covers the canon (`, T2, S3-S4`), the delegation card (`(read until "## Log").
+// Do T2; S3.`), and comma-free forms (`.md T1 S1;`). A mention inside prose does not start the line.
+const FEATURE_DOCUMENT_TASK = /^[ \t]*(?:[-*+][ \t]+)?Spec:[ \t]*`?(odd\/tasks\/[^\s,`()]+\.md)`?[^\n]*?\bT\d+\b/gm;
+export const WRITER_FEATURE_DOCUMENT_REJECTION =
+	"Writers run only for a task of an existing ODD feature document (`Spec: odd/tasks/<feature>.md, T<n>` in the task) or when your measured context reaches the context backstop. This unit has neither: write this unit inline yourself now; do not retry the launch, and never create a feature document only to launch writers.";
+
+function featureDocumentExists(root: string, relativePath: string): boolean {
+	// Resolve symlinks on both sides so a document linked from outside the root, or an odd/tasks directory linked
+	// elsewhere, never admits a writer; the document must be a regular file under <root>/odd/tasks.
+	try {
+		const realRoot = realpathSync(resolve(root));
+		const tasksDir = realpathSync(resolve(realRoot, "odd", "tasks"));
+		const target = realpathSync(resolve(realRoot, relativePath));
+		const inTasks = relative(tasksDir, target);
+		if (relative(realRoot, tasksDir).startsWith("..") || !inTasks || inTasks.startsWith("..") || isAbsolute(inTasks)) return false;
+		return statSync(target).isFile();
+	} catch {
+		return false;
+	}
+}
+
+// True when a string value has a `Spec:` task line naming an existing feature document under `root`. Shared by
+// writer and verifier admission so both accept exactly the same task lines.
+export function namesExistingFeatureDocumentTask(values: readonly unknown[], root: string): boolean {
+	for (const value of values) {
+		if (typeof value !== "string") continue;
+		for (const match of value.matchAll(FEATURE_DOCUMENT_TASK)) {
+			if (featureDocumentExists(root, match[1])) return true;
+		}
+	}
+	return false;
+}
+
+export function rejectUndocumentedWriterLaunch(
+	input: unknown,
+	options: { root: string; contextUsage: MeasuredContext | undefined; env?: Readonly<Record<string, string | undefined>> },
+): { block: true; reason: string } | undefined {
+	if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+	const record = input as Record<string, unknown>;
+	if (typeof record.agent !== "string" || !isGenericBoundedWriter(record.agent)) return undefined;
+	if (namesExistingFeatureDocumentTask([record.task, record.context], options.root)) return undefined;
+	if (contextBackstopReached(options.contextUsage, options.env)) return undefined;
+	return { block: true, reason: WRITER_FEATURE_DOCUMENT_REJECTION };
+}
+
 // A continuation resumes the same delegated task, so a writer follow-up that
 // carries no section of its own inherits the surfaces its original launch was
 // admitted with. A follow-up that carries the heading is validated as written,

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

@@ -30,10 +30,6 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 			{ command: "gentle:animations", label: "Animation mode" },
 			{ command: "gentle:vim", label: "Vim opt-in · Pi slash commands" },
 			{ command: "gentle:telemetry", label: "Telemetry" },
-			{ command: "gentle:banner", label: "Startup banner" },
-			{ command: "gentle:banner-color", label: "Banner color" },
-			{ command: "gentle:toggle-rose", label: "Toggle banner rose" },
-			{ command: "gentle:toggle-text-logo", label: "Toggle banner text logo" },
 			{ command: "gentle:dev-binary", label: "Gentle AI dev binary" },
 		],
 	},
@@ -46,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

@@ -0,0 +1,100 @@
+import { execFile } from "node:child_process";
+import type { ToolResultEvent, ToolResultEventResult } from "@earendil-works/pi-coding-agent";
+import { resolve } from "node:path";
+
+// Harness roadmap T4 (R1): ODD slices delivery at about 400 authored changed
+// lines, but the model had to estimate the count. After each parent commit the
+// runtime reports it from Git, so the slicing decision reads a number.
+
+export const SLICE_LINES = 400;
+
+// Generated files that do not count as authored lines.
+const GENERATED = [/(^|\/)(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock|go\.sum|poetry\.lock|composer\.lock|Gemfile\.lock)$/, /\.min\.(js|css)$/];
+
+// `git [-C dir | -c key=value]... commit` at the start of a segment, after any variable assignments.
+const COMMIT = /^\s*(\w+=\S*\s+)*git(\s+-[Cc]\s+\S+)*\s+commit(\s|$)/;
+
+/** A commit is a git invocation that starts a shell segment; text that only mentions one (echo, a message) is not. */
+export function isGitCommitCommand(command: string): boolean {
+	return command.split(/[;&|(\n]/).some((segment) => COMMIT.test(segment));
+}
+
+/** Shell segments joined by `;`, `&&`, `||`, or a newline. */
+export const SHELL_SEGMENT_SEPARATOR = /;|&&|\|\||\n/;
+
+const unquote = (value: string) => value.replace(/^["']|["']$/g, "");
+
+/** The directory after a shell segment: `cd <dir>` resolved against `base`, else `base`. */
+export function directoryAfterSegment(segment: string, base: string): string {
+	const cdDir = /^\s*cd\s+("[^"]+"|'[^']+'|\S+)\s*$/.exec(segment)?.[1];
+	return cdDir ? resolve(base, unquote(cdDir)) : base;
+}
+
+/** The directory the commit runs in: `git -C <dir>` under every `cd <dir>` segment before the commit (joined by `;`, `&&`, `||`, or a newline), else the session cwd. */
+export function commitTargetDirectory(command: string, cwd: string): string {
+	const gitDir = /\bgit\s+-C\s+("[^"]+"|'[^']+'|\S+)\s+(?:-[Cc]\s+\S+\s+)*commit\b/.exec(command)?.[1];
+	let base = cwd;
+	for (const segment of command.split(SHELL_SEGMENT_SEPARATOR)) {
+		if (COMMIT.test(segment)) break;
+		base = directoryAfterSegment(segment, base);
+	}
+	return gitDir ? resolve(base, unquote(gitDir)) : base;
+}
+
+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, windowsHide: true }, (error, stdout) => resolve(error ? undefined : stdout.trim()));
+});
+
+async function defaultBranch(cwd: string, git: Git): Promise<string | undefined> {
+	const remote = await git(["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"], cwd);
+	if (remote) return remote;
+	for (const name of ["main", "master"]) {
+		if (await git(["rev-parse", "--verify", "-q", `refs/heads/${name}`], cwd) !== undefined) return name;
+	}
+	return undefined;
+}
+
+/** One line for the parent after a commit on a feature branch, or undefined when there is no slice to report. */
+export async function commitSliceReport(cwd: string, git: Git = runGit): Promise<string | undefined> {
+	const branch = await git(["symbolic-ref", "-q", "--short", "HEAD"], cwd);
+	const target = branch === undefined ? undefined : await defaultBranch(cwd, git);
+	if (!branch || !target || branch === target || `origin/${branch}` === target) return undefined;
+	const base = await git(["merge-base", "HEAD", target], cwd);
+	const commits = base ? Number(await git(["rev-list", "--count", `${base}..HEAD`], cwd)) : 0;
+	if (!base || !(commits > 0)) return undefined;
+	// A failed or timed-out diff is not an empty one: report nothing rather than 0.
+	// `-M` counts a move by what it changed; `-z` keeps paths unquoted for the generated-file filter.
+	const numstat = await git(["diff", "--numstat", "-z", "-M", base, "HEAD"], cwd);
+	if (numstat === undefined) return undefined;
+	let lines = 0;
+	const fields = numstat.split("\0");
+	for (let i = 0; i < fields.length; i++) {
+		const [added, deleted, inline] = fields[i].split("\t");
+		// A rename leaves the inline path empty and is followed by its old and new paths.
+		const path = inline === "" ? fields[i += 2] : inline;
+		if (!path || added === "-" || GENERATED.some((pattern) => pattern.test(path))) continue;
+		lines += Number(added) + Number(deleted);
+	}
+	const head = `Commit slice: ${lines} authored changed lines in ${commits} commit${commits === 1 ? "" : "s"} on ${branch} since ${target} (lock files excluded).`;
+	return lines > SLICE_LINES
+		? `${head} Past the ~${SLICE_LINES}-line slice: apply the feature's delivery strategy before the next commit (record the slice boundary in the feature document).`
+		: `${head} ${SLICE_LINES - lines} lines left before the ~${SLICE_LINES}-line slice.`;
+}
+
+/**
+ * tool_result patch for a successful parent `git commit`: the slice line appended, structured content kept.
+ * Only foreground `bash`: a background job's result arrives before its commit exists.
+ */
+export async function commitSliceToolResult(event: Pick<ToolResultEvent, "toolName" | "input" | "isError" | "content" | "structuredContent">, cwd: string, git: Git = runGit): Promise<ToolResultEventResult | undefined> {
+	const command = (event.input as { command?: unknown } | undefined)?.command;
+	if (event.toolName !== "bash" || event.isError !== false || typeof command !== "string" || !isGitCommitCommand(command)) return undefined;
+	const report = await commitSliceReport(commitTargetDirectory(command, cwd), git);
+	if (!report) return undefined;
+	return {
+		content: [...event.content, { type: "text", text: `\n${report}` }],
+		...(event.structuredContent === undefined ? {} : { structuredContent: event.structuredContent }),
+	};
+}