gentle-pi 4.3.0 → 4.4.0

package/lib/session-profile-disk-reader.ts

@@ -0,0 +1,182 @@
+// Observable selected-record authority only, not conversation durability.
+import { readFileSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
+import {
+	isSessionProfileFamilyEntry,
+	readSessionProfileEntry,
+	type SessionProfileReadResult,
+} from "./session-profile-persistence.ts";
+
+export interface SessionProfileSource {
+	getSessionId(): string;
+	getSessionFile(): string | undefined;
+	getBranch(): readonly unknown[];
+}
+export type DiskProfileIndeterminateReason =
+	| "missing-source"
+	| "invalid-candidate-metadata"
+	| "unreadable-file"
+	| "source-changed"
+	| "invalid-record"
+	| "session-header-mismatch"
+	| "duplicate-id"
+	| "missing-header"
+	| "selected-record-missing"
+	| "selected-record-mismatch"
+	| "unserializable-source";
+export type DiskProfileResult =
+	| {
+			status: "indeterminate";
+			reason: DiskProfileIndeterminateReason;
+			entryIndex?: never;
+			lineNumber?: number;
+	  }
+	| (SessionProfileReadResult & { entryIndex?: number; lineNumber?: number });
+
+export interface DiskProfileOptions {
+	readFile?: (path: string) => string;
+	/** Trusted caller evidence ONLY: exclude known failed appends, never arbitrary
+	 * invalid/future entries. This reader owns no quarantine or append controller.
+	 * Failed IDs remain excluded even if they subsequently appear on disk. */
+	knownFailedEntryIds?: ReadonlySet<string>;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Own required metadata of a profile-family candidate, before serialization. */
+export function hasSessionProfileCandidateMetadata(value: unknown): boolean {
+	return (
+		record(value) && metadata(value) && Object.hasOwn(value, "customType")
+	);
+}
+function metadata(value: Record<string, unknown>): boolean {
+	return (
+		["type", "id", "parentId", "timestamp"].every((key) =>
+			Object.hasOwn(value, key),
+		) &&
+		typeString(value.type) &&
+		typeString(value.id) &&
+		typeString(value.timestamp) &&
+		(value.parentId === null || typeString(value.parentId))
+	);
+}
+function typeString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+function snapshot(value: unknown): unknown {
+	// Same undefined omission/toJSON behavior as Pi's JSONL serialization. Throws
+	// on cycles/BigInt; decoded copies cannot retain mutable memory references.
+	try {
+		return JSON.parse(JSON.stringify(value));
+	} catch {
+		throw new TypeError("Unserializable source snapshot");
+	}
+}
+function unavailable(
+	reason: DiskProfileIndeterminateReason,
+	lineNumber?: number): DiskProfileResult {
+	return lineNumber === undefined
+		? { status: "indeterminate", reason }
+		: { status: "indeterminate", reason, lineNumber };
+}
+
+/**
+ * Stateless synchronous read of the captured public active branch and file.
+ * No writes, SDK imports, UI, fallback policy, cache, ancestry repair or fsync.
+ * An orphan selected record can be corroborated: complete disk ancestry is NOT
+ * required. No external-writer/TOCTOU guarantee is implied by source checks.
+ * Missing disk is conservative and does not decide future memory-only activation.
+ */
+export function readSessionProfileDisk(
+	source: SessionProfileSource,
+	options: DiskProfileOptions = {},
+): DiskProfileResult {
+	try {
+		const sessionId = source.getSessionId();
+		const path = source.getSessionFile();
+		const rawBranch = source.getBranch();
+		if (!typeString(sessionId) || !typeString(path) || !Array.isArray(rawBranch))
+			return unavailable("missing-source");
+		// Validate own required candidate metadata before serialization can hide
+		// missing/inherited fields. Ordinary branch entries have no profile meaning.
+		for (const raw of rawBranch) {
+			if (
+				isSessionProfileFamilyEntry(raw) &&
+				!hasSessionProfileCandidateMetadata(raw)
+			)
+				return unavailable("invalid-candidate-metadata");
+		}
+		const branch = snapshot(rawBranch) as unknown[];
+		const failed = new Set(options.knownFailedEntryIds);
+		let entryIndex = -1;
+		for (let index = branch.length - 1; index >= 0; index--) {
+			const candidate = branch[index];
+			if (
+				isSessionProfileFamilyEntry(candidate) &&
+				!failed.has((candidate as { id?: unknown }).id as string)
+			) {
+				entryIndex = index;
+				break;
+			}
+		}
+		let text: string;
+		try {
+			text = (options.readFile ?? ((file) => readFileSync(file, "utf8")))(path);
+		} catch {
+			return unavailable("unreadable-file");
+		}
+		if (
+			source.getSessionId() !== sessionId ||
+			source.getSessionFile() !== path ||
+			!isDeepStrictEqual(snapshot(source.getBranch()), branch)
+		)
+			return unavailable("source-changed");
+		const disk = new Map<
+			string,
+			{ value: Record<string, unknown>; lineNumber: number }
+		>();
+		let foundHeader = false;
+		const lines = text.split("\n");
+		for (let index = 0; index < lines.length; index++) {
+			if (!lines[index].trim()) continue;
+			const lineNumber = index + 1;
+			let value: unknown;
+			try {
+				value = JSON.parse(lines[index]);
+			} catch {
+				// Pi's session parser skips malformed lines, so a file Pi opens must
+				// not become permanently indeterminate here.
+				continue;
+			}
+			if (!record(value)) return unavailable("invalid-record", lineNumber);
+			if (!foundHeader) {
+				if (value.type !== "session" || value.id !== sessionId)
+					return unavailable("session-header-mismatch", lineNumber);
+				foundHeader = true;
+				continue;
+			}
+			if (!metadata(value) || value.type === "session")
+				return unavailable("invalid-record", lineNumber);
+			if (disk.has(value.id as string) || value.id === sessionId)
+				return unavailable("duplicate-id", lineNumber);
+			disk.set(value.id as string, { value, lineNumber });
+		}
+		if (!foundHeader) return unavailable("missing-header");
+		if (entryIndex < 0) return { status: "absent" };
+		const selected = branch[entryIndex] as Record<string, unknown>;
+		const saved = disk.get(selected.id as string);
+		if (!saved) return unavailable("selected-record-missing");
+		if (!isDeepStrictEqual(selected, saved.value))
+			return unavailable("selected-record-mismatch", saved.lineNumber);
+		const semantic = readSessionProfileEntry({
+			type: selected.type as string,
+			customType: selected.customType as string,
+			data: selected.data,
+		});
+		return { ...semantic, entryIndex, lineNumber: saved.lineNumber };
+	} catch {
+		// Never expose exception messages or record contents (including getters).
+		return unavailable("unserializable-source");
+	}
+}

package/lib/session-profile-persistence.ts

@@ -11,7 +11,20 @@ import {
 } from "./model-routing-authority.ts";
 
 export const SESSION_PROFILE_CUSTOM_TYPE = "gentle-pi.session-profile/v1";
-const SESSION_PROFILE_FAMILY = "gentle-pi.session-profile/";
+export const SESSION_PROFILE_FAMILY = "gentle-pi.session-profile/";
+
+/** True for any custom entry in the session-profile family, known version or not. */
+export function isSessionProfileFamilyEntry(entry: unknown): boolean {
+	return (
+		typeof entry === "object" &&
+		entry !== null &&
+		(entry as { type?: unknown }).type === "custom" &&
+		typeof (entry as { customType?: unknown }).customType === "string" &&
+		(entry as { customType: string }).customType.startsWith(
+			SESSION_PROFILE_FAMILY,
+		)
+	);
+}
 
 export type SessionProfileOrigin = "user" | "local" | "repo" | "global";
 
@@ -148,12 +161,7 @@ export function createSessionProfileClear(): SessionProfileClearPayload {
 export function readSessionProfileEntry(
 	entry: SessionProfileEntry,
 ): SessionProfileReadResult {
-	if (
-		entry.type !== "custom" ||
-		typeof entry.customType !== "string" ||
-		!entry.customType.startsWith(SESSION_PROFILE_FAMILY)
-	)
-		return { status: "absent" };
+	if (!isSessionProfileFamilyEntry(entry)) return { status: "absent" };
 	if (entry.customType !== SESSION_PROFILE_CUSTOM_TYPE)
 		return { status: "unsupported" };
 	const data = entry.data;

package/lib/session-scratch.ts

@@ -1,6 +1,7 @@
 import { execFile, execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
 import { directoryAfterSegment, SHELL_SEGMENT_SEPARATOR } from "./commit-slice-signal.ts";
@@ -12,6 +13,8 @@ import { directoryAfterSegment, SHELL_SEGMENT_SEPARATOR } from "./commit-slice-s
 // and every check refuses rather than guesses.
 
 export const LEDGER_VERSION = 1;
+/** The ledger keeps the most recent artifacts, evicting the oldest first, so a long session's ledger file stays bounded. */
+export const LEDGER_ARTIFACTS_CAP = 64;
 // Short on purpose (S9): TMPDIR points at `gpXXXXXX` and a subagent's TMPDIR at
 // `gaXXXXXX` under it, and Unix socket paths below them are capped near 104 bytes.
 export const SCRATCH_PREFIX = "gp";
@@ -105,8 +108,36 @@ export function readLedger(path: string): ScratchLedger | undefined {
 	}
 }
 
+// The fs functions the ledger file I/O uses. Tests spy on this object to pin the
+// ledger I/O to the async fs API; the sync fs functions stay for the single-ledger
+// read and the scratch-directory checks, which were already synchronous.
+export const ledgerFs = { mkdir, readFile, readdir, rename, stat, unlink, writeFile };
+
+/** A valid ledger read from `path`, or undefined for a missing, unreadable, or foreign file. */
+async function readLedgerFile(path: string): Promise<ScratchLedger | undefined> {
+	try {
+		const parsed: unknown = JSON.parse(await ledgerFs.readFile(path, "utf8"));
+		return isLedger(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /** Atomic and private: a temp file in the same directory, then a rename. */
-export function writeLedger(path: string, ledger: ScratchLedger): void {
+export async function writeLedger(path: string, ledger: ScratchLedger): Promise<void> {
+	await ledgerFs.mkdir(dirname(path), { recursive: true, mode: 0o700 });
+	const temp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+	try {
+		await ledgerFs.writeFile(temp, `${JSON.stringify(ledger, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+		await ledgerFs.rename(temp, path);
+	} catch (error) {
+		try { await ledgerFs.unlink(temp); } catch { /* already renamed or never created */ }
+		throw error;
+	}
+}
+
+/** Synchronous `writeLedger`, for the one caller that cannot await it (the shutdown path, whose callers do not await the handler). */
+export function writeLedgerSync(path: string, ledger: ScratchLedger): void {
 	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
 	const temp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
 	try {
@@ -123,7 +154,25 @@ export function deleteLedger(path: string): void {
 }
 
 /** Every valid ledger in the config home; other files are left alone. */
-export function listLedgers(configHome: string): StoredLedger[] {
+export async function listLedgers(configHome: string): Promise<StoredLedger[]> {
+	const dir = ledgerDirectory(configHome);
+	let names: string[];
+	try { names = await ledgerFs.readdir(dir); } catch { return []; }
+	const result: StoredLedger[] = [];
+	for (const name of names) {
+		if (!name.endsWith(".json")) continue;
+		const path = join(dir, name);
+		try {
+			const ledger = await readLedgerFile(path);
+			if (!ledger) continue;
+			result.push({ path, ledger, mtimeMs: (await ledgerFs.stat(path)).mtimeMs });
+		} catch { /* removed meanwhile */ }
+	}
+	return result;
+}
+
+/** Synchronous `listLedgers`, for the one caller that cannot await it (the shutdown path, whose callers do not await the handler). */
+export function listLedgersSync(configHome: string): StoredLedger[] {
 	const dir = ledgerDirectory(configHome);
 	let names: string[];
 	try { names = readdirSync(dir); } catch { return []; }
@@ -388,7 +437,7 @@ const GIT_ENV_OVERRIDES = ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_CO
 const runGit: Git = (args, cwd) => new Promise((resolveResult) => {
 	const env = { ...process.env };
 	for (const key of GIT_ENV_OVERRIDES) delete env[key];
-	execFile("git", args, { cwd, env, encoding: "utf8", timeout: 10_000 }, (error, stdout) => resolveResult(error ? undefined : stdout.trim()));
+	execFile("git", args, { cwd, env, encoding: "utf8", timeout: 10_000, windowsHide: true }, (error, stdout) => resolveResult(error ? undefined : stdout.trim()));
 });
 
 export type ArtifactCheck =

package/lib/session-worktree-registry.ts

@@ -30,6 +30,13 @@ function canonicalDirectory(path: string, cwd: string): string {
 	return statSync(canonical).isDirectory() ? canonical : dirname(canonical);
 }
 
+// Windows accepts `/` as its separator and Git prints roots that way, while
+// realpath answers with `\`. Only the separator is translated, so any other
+// non-canonical spelling (dot segments, trailing separators) still differs.
+export function nativeRootSpelling(path: string, platform: NodeJS.Platform = process.platform): string {
+	return platform === "win32" ? path.replaceAll("/", "\\") : path;
+}
+
 export function resolveSessionWorktreeWithGit(path: string, cwd: string, run: typeof execFileSync = execFileSync): WorktreeIdentity | undefined {
 	try {
 		const directory = canonicalDirectory(path, cwd);

package/lib/shell-bar.ts

@@ -22,7 +22,7 @@ export interface ShellBarModel {
 	review?: ReviewSidebarSnapshot;
 	jobs?: RunningJobDisplay[];
 	profile?: string;
-	changes?: { files: number; added: number; deleted: number; notice?: string };
+	changes?: { files: number; added: number; deleted: number };
 	cwd: string;
 	branch: string | null;
 	dirty: number | undefined;
@@ -240,7 +240,6 @@ export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme
 				changes?.files
 					? `${changes.files} ${changes.files === 1 ? "file" : "files"} · ${theme.fg("success", `+${changes.added}`)} ${theme.fg("error", `−${changes.deleted}`)}`
 					: label("No captured changes"),
-				...(changes?.notice ? [theme.fg("warning", sanitizeStatus(changes.notice))] : []),
 				label("/gentle:changes"),
 			],
 		}]),
@@ -427,7 +426,9 @@ export function renderShellBelowInputFloat(model: ShellBarModel, theme: ShellBar
 	const targetWidth = Math.max(0, Math.floor(width));
 	if (floatHeaderPaint(theme, targetWidth, () => "") === undefined) return undefined;
 	const chrome = renderShellHeaderChrome(buildShellHeaderModel(model, presentation.statusPlacement === "hidden"), theme, targetWidth, usageHint, presentation, paint);
-	const changesRow = changes?.files.length && presentation.visibility.changes !== false
+	// The row exists only while files are actually tracked; an unborn-only root
+	// is silence here (/gentle:changes explains the state on demand).
+	const changesRow = Boolean(changes && changes.files.length > 0) && presentation.visibility.changes !== false
 		? floatHeaderRow(theme, targetWidth, (inner) => renderChangesWidget(changes, theme, inner)[0] ?? "")
 		: undefined;
 	const statuses = presentation.statusPlacement === "hidden" ? [] : [

package/lib/shell-changes.ts

@@ -27,6 +27,8 @@ export interface ChangesModel {
 	files: ChangedFile[];
 	added: number;
 	deleted: number;
+	/** Stored once per model build; the footer memo reads it every keystroke. */
+	digest?: string;
 }
 
 export interface ChangesSnapshot {
@@ -63,7 +65,7 @@ const HAS_RENAME_BRACES = /\{[^{}]* => [^{}]*\}/;
 const RENAME_ARROW = " => ";
 
 export function emptyChanges(): ChangesModel {
-	return { files: [], added: 0, deleted: 0 };
+	return { files: [], added: 0, deleted: 0, digest: EMPTY_CHANGES_DIGEST };
 }
 
 function renamedPath(path: string): string {
@@ -124,9 +126,42 @@ export function changesModel(changed: ChangedFile[]): ChangesModel {
 		files,
 		added: files.reduce((total, file) => total + file.added, 0),
 		deleted: files.reduce((total, file) => total + file.deleted, 0),
+		digest: changesDigest({ files, added: 0, deleted: 0 }),
 	};
 }
 
+// The footer Status memo asks "did any change move?" on every keystroke, so
+// the answer must be O(1) to read: the model stores this digest once per
+// build (changesModel/emptyChanges) and consumers read the stored field.
+// It is a 64-bit FNV-1a roll over every per-file tuple the renderer consumes
+// (path, status, counts, diffRevision, countsUnavailable), so counts alone
+// cannot miss a same-count edit. A hash collision could only skip one
+// refresh until the next change moves the digest again -- it never renders a
+// wrong picture -- but it is a probabilistic signal, not an exact one.
+function fnv1a(hash: number, text: string): number {
+	for (let index = 0; index < text.length; index += 1) {
+		hash ^= text.charCodeAt(index);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return hash >>> 0;
+}
+
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+const SECOND_SEED = 0x811c9dc5 ^ 0x9e3779b9;
+
+export function changesDigest(model: ChangesModel): string {
+	let first = FNV_OFFSET_BASIS;
+	let second = SECOND_SEED;
+	for (const file of model.files) {
+		const tuple = `\u0000${file.path}\u0000${file.status}\u0000${file.added}\u0000${file.deleted}\u0000${file.diffRevision ?? ""}\u0000${file.countsUnavailable ?? ""}`;
+		first = fnv1a(first, tuple);
+		second = fnv1a(second, tuple);
+	}
+	return `${first.toString(16).padStart(8, "0")}${second.toString(16).padStart(8, "0")}`;
+}
+
+const EMPTY_CHANGES_DIGEST = changesDigest({ files: [], added: 0, deleted: 0 });
+
 export function changesSummary(model: ChangesModel): string {
 	const noun = model.files.length === 1 ? "file" : "files";
 	return `${model.files.length} ${noun} · +${model.added} −${model.deleted}${model.files.some(file => file.countsUnavailable) ? " · partial counts" : ""}`;
@@ -134,19 +169,39 @@ export function changesSummary(model: ChangesModel): string {
 
 // One line: summary, the files joined by dots, and the command pushed to
 // the right edge. The file list goes first when the terminal is narrow.
+// The idle widget exists only while files are tracked. An unborn root (no
+// commits yet) is silence here: /gentle:changes explains the state on demand,
+// where the message has room and context.
+//
+// Both surfaces that paint it (the sidebar part and the below-input header
+// row) re-render every frame, so the paint is memoized per digest, width and
+// theme identity -- one stored frame, like CodemodeCard's cachedFrame. The
+// digest already rolls up every per-file detail the paint consumes (path,
+// status, counts, diffRevision, countsUnavailable), so a digest hit skips the
+// per-file join entirely; a digest-less (hand-built) model never caches, and
+// a new theme object repaints.
+type WidgetFrame = { digest: string; width: number; theme: ChangesTheme; lines: string[] };
+let widgetFrame: WidgetFrame | undefined;
+
 export function renderChangesWidget(model: ChangesModel, theme: ChangesTheme, width: number): string[] {
 	if (model.files.length === 0) return [];
+	if (model.digest !== undefined && widgetFrame?.digest === model.digest && widgetFrame.width === width && widgetFrame.theme === theme) return widgetFrame.lines;
 	const noun = model.files.length === 1 ? "file" : "files";
 	const dot = theme.fg("muted", "·");
 	const head = `${theme.fg("accent", WIDGET_GLYPH)} ${theme.fg("text", `${model.files.length} ${noun}`)} ${dot} ${theme.fg("success", `+${model.added}`)} ${theme.fg("error", `−${model.deleted}`)}${model.files.some(file => file.countsUnavailable) ? " · partial counts" : ""}`;
 	const hint = theme.fg("dim", CHANGES_COMMAND);
 	const list = model.files.map((file) => theme.fg("muted", file.path)).join(` ${dot} `);
 	const left = `${head} ${dot} ${list}`;
+	let lines: string[];
 	const gap = width - visibleWidth(left) - visibleWidth(hint);
-	if (gap >= 2) return [`${left}${" ".repeat(gap)}${hint}`];
-	const headGap = width - visibleWidth(head) - visibleWidth(hint);
-	if (headGap >= 2) return [`${head}${" ".repeat(headGap)}${hint}`];
-	return [truncateToWidth(head, width, "…")];
+	if (gap >= 2) lines = [`${left}${" ".repeat(gap)}${hint}`];
+	else {
+		const headGap = width - visibleWidth(head) - visibleWidth(hint);
+		lines = headGap >= 2 ? [`${head}${" ".repeat(headGap)}${hint}`] : [truncateToWidth(head, width, "…")];
+	}
+	if (model.digest === undefined) return lines;
+	widgetFrame = { digest: model.digest, width, theme, lines };
+	return lines;
 }
 
 export interface GitResult {
@@ -199,12 +254,24 @@ export async function foreignRootBranch(git: GitRunner): Promise<string | undefi
 	return verified.code === 0 ? branch : "no commits yet";
 }
 
+// A root whose HEAD is unborn (no commits yet) has no baseline: `git diff
+// HEAD` is meaningless and `git status` reports every file as untracked.
+// Worktree-holder folders -- repositories that exist only to parent linked
+// worktrees -- look exactly like this, and scanning them floods Changes with
+// thousands of phantom untracked files (the whole holder's contents). One
+// cheap verify answers "is there anything to diff against" before a scan.
+const HEAD_EXISTS_ARGS = ["rev-parse", "--verify", "-q", "HEAD"];
+
 // /gentle:changes: one group per registered root holding its working tree
 // against HEAD. A root whose Git fails (timed out, rejected) has no group but
 // is listed in failedRoots: a failed scan is never reported as a clean root.
+// A root with no commits has no group either, listed in unbornRoots: there is
+// nothing to track yet, and the bar says so instead of scanning the holder.
 export class WorktreeChangesTracker {
 	worktrees: WorktreeChanges[] = [];
 	failedRoots: string[] = [];
+	/** Registered roots whose HEAD is unborn: skipped, never scanned. */
+	unbornRoots: string[] = [];
 	scannedRootCount = 0;
 	private inFlight: Promise<ChangesModel> | undefined;
 	private readonly discover: GitRunner;
@@ -266,9 +333,17 @@ export class WorktreeChangesTracker {
 		const metadata = new Map((result.code === 0 ? parseWorktrees(result.stdout) : []).map((tree) => [tree.root, tree]));
 		// Roots scan in parallel so one slow root does not delay the others.
 		const failed: string[] = [];
+		const unborn: string[] = [];
 		const scanned = await Promise.all([...roots].map(async (root): Promise<WorktreeChanges | undefined> => {
 			const known = metadata.get(root);
 			try {
+				// Only an answered "no" means unborn: a rejected verify cannot tell
+				// unborn from broken Git, so the scan below still decides.
+				const head = await this.gitForRoot(root)(HEAD_EXISTS_ARGS).catch(() => undefined);
+				if (head && head.code !== 0) {
+					unborn.push(root);
+					return undefined;
+				}
 				const tracker = new ChangesTracker(this.gitForRoot(root), this.linesForRoot(root), this.revisionForRoot(root));
 				await tracker.start();
 				if (!tracker.statusRead) {
@@ -301,6 +376,7 @@ export class WorktreeChangesTracker {
 		if (latest.size !== roots.size || [...latest].some((root) => !roots.has(root))) return this.capture();
 		this.worktrees = trees;
 		this.failedRoots = failed;
+		this.unbornRoots = unborn;
 		this.scannedRootCount = roots.size;
 		return this.model;
 	}

package/lib/shell-prompt.ts

@@ -23,10 +23,10 @@ const PETAL_TONE = {
 
 export type PetalTone = (typeof PETAL_TONE)[keyof typeof PETAL_TONE];
 
-// Keep Pi's original loader cadence while carrying the banner's reflected-light
-// language into the compact working labels. The highlight enters before the
-// word, crosses it as a soft symmetric wave, then exits before wrapping.
-export const SHELL_PULSE_MS = 80;
+// Render-driven animation (gentle-shell#994): the petal advances inside the
+// prompt's own frames while streaming, so the only timer left is a watchdog
+// that repaints silent working phases (long tool runs with no output).
+export const SHELL_PULSE_WATCHDOG_MS = 1000;
 export const SHELL_SCANNER_STEPS = 15;
 const SCANNER_ENTRY_OFFSET = 3;
 

package/lib/shell-sidebar-layout.ts

@@ -25,7 +25,7 @@ type LayoutRoot = Component & { [NODE]?: () => LayoutNode };
 type Host = TUI & { mode?: string; layoutRoot?: LayoutRoot };
 type SidebarCache = { revision: number };
 type RailHit = { key: string; component: Component; startY: number; height: number; width: number };
-type SectionCacheEntry = { component: Component; digest: string | undefined; revision: number; contentWidth: number; theme: ShellBarTheme; lines: string[] };
+type SectionCacheEntry = { component: Component; digest: string | undefined; revision: number; contentWidth: number; theme: ShellBarTheme; themeSignature: string; lines: string[] };
 type SidebarPresentation = { scrollTop: number; output: LayoutNode };
 type PreparedRail = {
 	revision: number;
@@ -35,6 +35,7 @@ type PreparedRail = {
 	cardStyle: CardStyle;
 	root: LayoutRoot;
 	theme: ShellBarTheme;
+	themeSignature: string;
 	parts: Array<[string, SidebarRail]>;
 	digests: Array<string | undefined>;
 	contentWidth: number;
@@ -74,6 +75,20 @@ function railDigest(rail: SidebarRail): string | undefined {
 	}
 }
 
+// Pi passes extensions one live theme proxy, so identity never changes on a
+// theme switch, and the switch only calls ui.invalidate(), which does not reach
+// the rail inside the layout tree. How the current theme paints a few roles is
+// what changes, so the memo keys on that: a digest-only section (Status,
+// Agents, Todos) would otherwise keep the previous theme's colors.
+const THEME_SIGNATURE_ROLES = ["accent", "border", "borderAccent", "muted", "dim", "text", "success", "warning", "error"];
+function themeSignature(theme: ShellBarTheme): string {
+	try {
+		return THEME_SIGNATURE_ROLES.map((role) => theme.fg(role, "·")).join("") + theme.bold("·");
+	} catch {
+		return "";
+	}
+}
+
 export const STATUS_OWNER = { HEADER: "header", BOTTOM: "bottom" } as const;
 export type StatusOwner = (typeof STATUS_OWNER)[keyof typeof STATUS_OWNER];
 export interface StatusOwnerInput {
@@ -217,9 +232,13 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () =>
 		}
 		const style = cardStyle();
 		const parts = [...state.parts.entries()];
+		// Digest closures read live session state, so they must be evaluated once
+		// per frame and stored for the next comparison (issue #1681): the sections
+		// loop below reuses this pass instead of calling each digest a second time.
 		const digests = parts.map(([, rail]) => railDigest(rail));
+		const signature = themeSignature(theme);
 		const unchanged = prepared?.revision === cache.revision &&
-			prepared.width === width && prepared.mode === host.mode && prepared.headerPlacement === headerPlacement() && prepared.cardStyle === style && prepared.root === root && prepared.theme === theme &&
+			prepared.width === width && prepared.mode === host.mode && prepared.headerPlacement === headerPlacement() && prepared.cardStyle === style && prepared.root === root && prepared.theme === theme && prepared.themeSignature === signature &&
 			prepared.parts.length === parts.length && prepared.parts.every(([key, part], index) => parts[index]?.[0] === key && parts[index]?.[1] === part) &&
 			prepared.digests.length === digests.length && prepared.digests.every((digest, index) => digest === digests[index]);
 		if (unchanged) {
@@ -228,6 +247,7 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () =>
 			return prepared.active;
 		}
 		try {
+			const digestByPart = new Map(parts.map(([key], index) => [key, digests[index]]));
 			// The header is a full-width sibling row, not a rail section: it reads
 			// the terminal width (minus the rail's right inset), never the
 			// 50-column rail's content width.
@@ -241,16 +261,16 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () =>
 					sectionCache.delete(key);
 					return { key, component, lines: [] as string[] };
 				}
-				const digest = railDigest(component);
+				const digest = digestByPart.get(key);
 				const existing = sectionCache.get(key);
-				const reusable = existing?.component === component && existing.contentWidth === contentWidth && existing.theme === theme &&
+				const reusable = existing?.component === component && existing.contentWidth === contentWidth && existing.theme === theme && existing.themeSignature === signature &&
 					(digest !== undefined ? existing.digest === digest : existing.digest === undefined && existing.revision === cache.revision);
 				const lines = reusable ? existing.lines : (() => {
 					const rendered = [...(component.render(contentWidth - RAIL_PADDING * 2) ?? [])];
 					while (rendered.length && rendered[rendered.length - 1]?.trim() === "") rendered.pop();
 					return rendered;
 				})();
-				sectionCache.set(key, { component, digest, revision: cache.revision, contentWidth, theme, lines });
+				sectionCache.set(key, { component, digest, revision: cache.revision, contentWidth, theme, themeSignature: signature, lines });
 				return { key, component, lines };
 			}).filter((section) => section.component !== undefined && section.lines.length > 0) as Array<{ key: string; component: Component; lines: string[] }>;
 			// The header carries the brand once it is active; the banner is the
@@ -276,7 +296,7 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () =>
 			// Height is owned by the native ScrollView, never by the transcript.
 			const active = railLines.length > 0 && railLines.every((line) => visibleWidth(line) <= contentWidth);
 			headerLines = headerActive && headerPlacement() === "top" ? preparedHeaderLines : [];
-			prepared = { revision: cache.revision, width, mode: host.mode, headerPlacement: headerPlacement(), cardStyle: style, root, theme, parts, digests, contentWidth, active, lines: railLines, hits, headerLines, headerActive: headerLines.length > 0 };
+			prepared = { revision: cache.revision, width, mode: host.mode, headerPlacement: headerPlacement(), cardStyle: style, root, theme, themeSignature: signature, parts, digests, contentWidth, active, lines: railLines, hits, headerLines, headerActive: headerLines.length > 0 };
 			state.active = active;
 			return active;
 		} catch {

package/lib/shell-todo.ts

@@ -281,7 +281,7 @@ export function replayTodo(entries: readonly unknown[]): TodoState {
 // the tail of the conversation, never the prefix.
 const TODO_PROMPT_BLOCK = [
 	"## Todo list",
-	"Keep it current with the `todo` tool: mark a task in_progress before starting it, done right after finishing it, and rewrite the whole list with `write` whenever the plan changes. Update it before you end the turn.",
+	"A small task (Task Size) uses no todo list: do it and report. For tracked or multi-step work, keep it current with the `todo` tool: mark a task in_progress before starting it, done right after finishing it, and rewrite the whole list with `write` whenever the plan changes. Update it before you end the turn.",
 	"A blocked task waits on something outside the list: do not work on it until its condition holds. When the plan changes, mark the tasks it made obsolete dropped instead of leaving them pending or marking them done.",
 	"While tasks stay open, the current list arrives as a hidden conversation message whenever it changes; the latest one is current, and it is not repeated here.",
 ].join("\n");

package/lib/verifier-admission.ts

@@ -7,10 +7,11 @@ import { contextBackstopReached, type MeasuredContext } from "./context-backstop
 // existing feature document (the same lines writer admission accepts), or the parent's measured context reaches the
 // context backstop. The agent catalog has no generic verifier alias, so only `gentle-ai-verify` is gated.
 const VERIFIER_NAMES = ["gentle-ai-verify"];
-// A line that starts with `Risk:` (optionally as a list item) whose first entry is `item N` with N in 1-6, for
-// example `Risk: item 3 (shared parser)` or `- Risk: item 2, item 3 (reason)`. `Risk: none` and prose mentions
-// do not start such a line.
-const HIGH_RISK_ITEM_LINE = /^[ \t]*(?:[-*+][ \t]+)?Risk:[ \t]*item[ \t]+[1-6](?!\d)/m;
+// A declaration that starts a line (optionally as a list item) or a sentence (after `.`, `!` or `?` and a space) with
+// `Risk:` whose first entry is `item N` with N in 1-6, for example `Risk: item 3 (shared parser)`, `- Risk: item 2,
+// item 3 (reason)` or `... on top of ebf3f35. Risk: item 1 (migration)`. `Risk: none` and a mention inside a
+// sentence ("Do not write Risk: item 3") do not start one.
+const HIGH_RISK_ITEM_LINE = /(?:^[ \t]*(?:[-*+][ \t]+)?|[.!?][ \t]+)Risk:[ \t]*item[ \t]+[1-6](?!\d)/m;
 export const VERIFIER_RISK_REJECTION =
 	"An independent verifier runs only for a change that declares a named high-risk item (`Risk: item N` from the Task Size list in the task). This change declares none: run its focused test and suite inline yourself now; do not retry the launch, and never add a Risk line or create a feature document only to get a verifier admitted.";