@andares/pi-toolkits 0.9.6 → 0.9.8

package/src/features/ask/scratch.ts

@@ -0,0 +1,324 @@
+/**
+ * ask feature — scratch directory for planning notes.
+ *
+ * Ask mode used to confiscate every write tool, including writes to a temp
+ * file. That is stricter than the promise it makes ("do not change the
+ * project"): a model that wants to hold an outline, a checklist or a draft
+ * analysis had to either dump it into the reply or work around the sandbox. So
+ * the mode now hands out exactly one place to write — a per-session directory
+ * under the OS temp dir, outside the project:
+ *
+ *  - the root is `<os.tmpdir()>/pi-ask/<session>`, so nothing here can touch the
+ *    repository and no path arrives from the model (names are relative);
+ *  - names are validated against a narrow allowlist (letters, digits, dot,
+ *    dash, underscore; at most two levels; no `..`, no absolute path, no
+ *    backslash), and the joined path is re-checked for containment as defence
+ *    in depth;
+ *  - existing symlinked components are refused, so a pre-existing link in the
+ *    temp dir cannot turn a note into a write somewhere else;
+ *  - files are capped at {@link SCRATCH_MAX_BYTES}: "notes" are not a dump of
+ *    the repository, and the cap also keeps a tool result from flooding the
+ *    context when the model reads its own note back;
+ *  - `createScratchStore` throws when the temp dir cannot be created or written.
+ *    The caller then degrades to the old fully read-only mode instead of
+ *    running half-open.
+ *
+ * Nothing written here is ever executed: ask mode's bash sandbox stays
+ * read-only, so a script dropped into the scratch directory is just text.
+ */
+import { createHash } from "node:crypto";
+// Creation and sweeping are synchronous on purpose: ask mode can be entered from
+// `session_start` (the autostart path), and the first run starts before an async
+// directory creation would resolve. Those are a handful of syscalls; the actual
+// note operations stay async because they run inside tool calls.
+import {
+	mkdirSync,
+	realpathSync,
+	readdirSync,
+	rmSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import {
+	appendFile,
+	lstat,
+	mkdir,
+	readFile,
+	readdir,
+	stat,
+	unlink,
+	writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+
+/** Directory under the OS temp dir that holds every session's scratch space. */
+export const SCRATCH_DIR_NAME = "pi-ask";
+/** Largest single note. Notes are planning aids, not a copy of the repository. */
+export const SCRATCH_MAX_BYTES = 256 * 1024;
+/** Scratch directories older than this are removed when a session enters ask mode. */
+export const SCRATCH_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** A note name segment: no leading dot, no separators, no shell metacharacters. */
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A session id that is safe as a directory name (pi uses UUIDs; be defensive). */
+const SESSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Deepest allowed note name, e.g. `notes/api.md`. */
+const MAX_SEGMENTS = 2;
+
+/** One note as reported by `list`. */
+export interface ScratchFile {
+	readonly name: string;
+	readonly bytes: number;
+}
+
+/** Result of writing or appending one note. */
+export interface ScratchWrite {
+	readonly name: string;
+	readonly path: string;
+	readonly bytes: number;
+	readonly lines: number;
+}
+
+/** The scratch space of one session. Every operation takes a relative note name. */
+export interface ScratchStore {
+	readonly root: string;
+	write(name: string, content: string): Promise<ScratchWrite>;
+	append(name: string, content: string): Promise<ScratchWrite>;
+	read(name: string): Promise<string>;
+	list(): Promise<ScratchFile[]>;
+	remove(name: string): Promise<void>;
+}
+
+/** Why `name` is not a valid note name, or undefined when it is. */
+export function nameError(name: string): string | undefined {
+	const trimmed = name.trim();
+	if (trimmed === "") {
+		return 'The note name is empty. Use a relative name such as "plan.md".';
+	}
+	if (isAbsolute(name) || /^[A-Za-z]:/.test(name) || name.includes("\\")) {
+		return `"${name}" is not a relative name. Scratch names are relative to the scratch directory (for example "plan.md"); absolute paths and backslashes are rejected.`;
+	}
+	const segments = name.split("/");
+	if (segments.length > MAX_SEGMENTS) {
+		return `"${name}" is nested too deeply. At most ${MAX_SEGMENTS} levels are allowed ("notes/api.md").`;
+	}
+	const invalid = segments.find((segment) => !SEGMENT.test(segment));
+	if (invalid !== undefined) {
+		return `"${name}" has an invalid segment "${invalid}". A segment is 1-64 characters of letters, digits, dot, dash or underscore and may not start with a dot.`;
+	}
+	return undefined;
+}
+
+/** Case-folded containment check (Windows paths are case-insensitive). */
+function inside(root: string, target: string): boolean {
+	const fold = (value: string): string =>
+		process.platform === "win32" ? value.toLowerCase() : value;
+	const base = fold(root);
+	const candidate = fold(target);
+	return (
+		candidate === base ||
+		candidate.startsWith(base.endsWith(sep) ? base : `${base}${sep}`)
+	);
+}
+
+/** Absolute path of a validated note name, re-checked for containment. */
+function targetFor(root: string, name: string): string {
+	const problem = nameError(name);
+	if (problem !== undefined) throw new Error(problem);
+	const target = resolve(root, name);
+	if (!inside(root, target)) {
+		throw new Error(`"${name}" resolves outside the scratch directory.`);
+	}
+	return target;
+}
+
+/**
+ * Refuse a target whose existing components go through a symlink.
+ *
+ * The store never creates links itself, so this only matters when something
+ * else (the operator, another process) put one in the temp directory first.
+ * Missing components are fine: they are about to be created inside the root.
+ */
+async function assertNoSymlink(root: string, target: string): Promise<void> {
+	const parts = target.slice(root.length).split(sep).filter(Boolean);
+	let current = root;
+	for (const part of parts) {
+		current = join(current, part);
+		try {
+			const info = await lstat(current);
+			if (info.isSymbolicLink()) {
+				throw new Error(
+					`${part} in the scratch directory is a symbolic link; scratch notes must be regular files.`,
+				);
+			}
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw error;
+		}
+	}
+}
+
+function tooBig(bytes: number): string {
+	const kib = Math.ceil(SCRATCH_MAX_BYTES / 1024);
+	return `Scratch notes are capped at ${kib} KiB; this note would be ${Math.ceil(bytes / 1024)} KiB. Keep it to the planning essentials — the reply, not the note, is the deliverable.`;
+}
+
+function lineCount(text: string): number {
+	if (text === "") return 0;
+	const breaks = text.split("\n").length;
+	return text.endsWith("\n") ? breaks - 1 : breaks;
+}
+
+async function sizeOf(path: string): Promise<number | undefined> {
+	try {
+		const info = await stat(path);
+		return info.size;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Create a {@link ScratchStore} rooted in `options.baseDir` (default: OS temp). */
+export function createScratchStore(options: {
+	readonly sessionId: string;
+	readonly baseDir?: string;
+	readonly now?: number;
+}): ScratchStore {
+	const base = join(resolve(options.baseDir ?? tmpdir()), SCRATCH_DIR_NAME);
+	const leaf = SESSION.test(options.sessionId)
+		? options.sessionId
+		: createHash("sha256").update(options.sessionId).digest("hex").slice(0, 16);
+	const created = join(base, leaf);
+	mkdirSync(created, { recursive: true });
+	// macOS resolves /var (and therefore the default tmpdir) through a symlink.
+	const root = realpathSync(created);
+	// Prove the directory is writable: on a read-only TMPDIR `mkdir -p` on an
+	// existing directory succeeds without proving anything. Ask mode degrades
+	// when this throws.
+	const probe = join(root, `.probe-${process.pid}-${Date.now()}`);
+	writeFileSync(probe, "");
+	unlinkSync(probe);
+	sweepScratchDirs(base, SCRATCH_MAX_AGE_MS, options.now);
+
+	const store: ScratchStore = {
+		root,
+
+		async write(name, content) {
+			const target = targetFor(root, name);
+			const bytes = Buffer.byteLength(content, "utf8");
+			if (bytes > SCRATCH_MAX_BYTES) throw new Error(tooBig(bytes));
+			await assertNoSymlink(root, target);
+			await mkdir(resolve(target, ".."), { recursive: true });
+			await writeFile(target, content, "utf8");
+			return { name, path: target, bytes, lines: lineCount(content) };
+		},
+
+		async append(name, content) {
+			const target = targetFor(root, name);
+			const existing = (await sizeOf(target)) ?? 0;
+			const bytes = Buffer.byteLength(content, "utf8");
+			if (existing + bytes > SCRATCH_MAX_BYTES) {
+				throw new Error(tooBig(existing + bytes));
+			}
+			await assertNoSymlink(root, target);
+			await mkdir(resolve(target, ".."), { recursive: true });
+			await appendFile(target, content, "utf8");
+			const total = existing + bytes;
+			return {
+				name,
+				path: target,
+				bytes: total,
+				// The appended text is what the caller just wrote; the file's own
+				// line count is not needed by the model.
+				lines: lineCount(content),
+			};
+		},
+
+		async read(name) {
+			const target = targetFor(root, name);
+			await assertNoSymlink(root, target);
+			let data: Buffer;
+			try {
+				data = await readFile(target);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+					throw new Error(
+						`There is no scratch note named "${name}". Use op "list" to see the notes that exist.`,
+					);
+				}
+				throw error;
+			}
+			if (data.length > SCRATCH_MAX_BYTES) {
+				return `${data.subarray(0, SCRATCH_MAX_BYTES).toString("utf8")}\n…(truncated at ${Math.floor(SCRATCH_MAX_BYTES / 1024)} KiB)`;
+			}
+			return data.toString("utf8");
+		},
+
+		async list() {
+			const files: ScratchFile[] = [];
+			const walk = async (dir: string, prefix: string): Promise<void> => {
+				const entries = await readdir(dir, { withFileTypes: true });
+				for (const entry of entries) {
+					if (entry.name.startsWith(".")) continue;
+					const name = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+					if (entry.isDirectory()) {
+						// One level only: names cannot nest deeper than MAX_SEGMENTS.
+						if (prefix === "") await walk(join(dir, entry.name), name);
+						continue;
+					}
+					// Symlinks and other non-files are deliberately not listed.
+					if (!entry.isFile()) continue;
+					const size = await sizeOf(join(dir, entry.name));
+					files.push({ name, bytes: size ?? 0 });
+				}
+			};
+			await walk(root, "");
+			return files.sort((a, b) => a.name.localeCompare(b.name));
+		},
+
+		async remove(name) {
+			const target = targetFor(root, name);
+			try {
+				await unlink(target);
+			} catch (error) {
+				// Deleting a note that is already gone is not an error: the model
+				// asked for the note to be gone and it is.
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			}
+		},
+	};
+	return store;
+}
+
+/**
+ * Remove scratch directories older than `maxAgeMs`. Never throws: cleanup is
+ * housekeeping, and a stale directory must not keep ask mode from starting.
+ */
+export function sweepScratchDirs(
+	base: string,
+	maxAgeMs: number,
+	now = Date.now(),
+): string[] {
+	const removed: string[] = [];
+	let entries;
+	try {
+		entries = readdirSync(base, { withFileTypes: true });
+	} catch {
+		return removed;
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const dir = join(base, entry.name);
+		try {
+			const info = statSync(dir);
+			if (now - info.mtimeMs <= maxAgeMs) continue;
+			rmSync(dir, { recursive: true, force: true });
+			removed.push(entry.name);
+		} catch {
+			// Best effort; a directory in use elsewhere stays.
+		}
+	}
+	return removed;
+}

package/src/features/autostart/autostart.ts

@@ -48,7 +48,7 @@ export const RUNNABLE_REASONS: ReadonlySet<string> = new Set([
  * `-r` (`--resume`), `--session <path>` and `--fork <path>` all open an
  * existing session *before* the first runtime exists, and that runtime is
  * created without an explicit session_start event, so extensions see pi's
- * default reason — `startup` — not `resume` (verified on pi 1.0.0–1.3.0:
+ * default reason — `startup` — not `resume` (verified on pi 1.1.0–1.4.0:
  * `main.js` builds the initial session manager from those flags and calls
  * `createAgentSessionRuntime` with no `sessionStartEvent`;
  * `agent-session.js` defaults it to `{ reason: "startup" }`). `resume` is only

package/src/features/autostart/index.ts

@@ -27,7 +27,7 @@
  * that flag is what routes "/cmd args" through _tryExecuteExtensionCommand
  * instead of the model prompt path. The wrapper defaults it to false in this
  * package (each byte-identical across every published version of the supported
- * window, 1.0.0 → 1.3.0; see AGENTS.md host-compat discipline for the version
+ * window, 1.1.0 → 1.4.0; see AGENTS.md host-compat discipline for the version
  * matrix).
  *
  * Only extension commands can run this way. Built-in commands (/compact,

package/src/features/compact/compact.test.ts

@@ -418,27 +418,25 @@ describe("session_before_compact handler", () => {
 			.calls[0] as [
 			AvailableModel,
 			unknown,
-			{ maxTokens: number; signal: AbortSignal },
+			{ maxTokens?: number; signal: AbortSignal },
 		];
 		expect(modelKey(model)).toBe("google/gemini-2.5-flash");
-		// 0.8 × reserveTokens(16000) = 12800, under the model cap (8192).
-		expect(options.maxTokens).toBe(8192);
+		// pi 1.4.0 (#9512): no fixed output cap — the request omits maxTokens
+		// so the provider uses the model's own output limit.
+		expect(options).not.toHaveProperty("maxTokens");
 		expect(options.signal).toBe(event.signal);
 	});
 
-	it("clamps the budget by reserveTokens when the model cap is larger", async () => {
+	it("does not derive an output budget from reserveTokens", async () => {
 		getCompactStore().setModel("google/gemini-2.5-flash");
 		const { handler } = registeredHandler();
 		const bigCapModel = { ...MODELS[0], maxTokens: 65536 };
 		const { ctx, complete } = fakeCtx({ models: [bigCapModel] });
 		await handler(fakeEvent() as never, ctx);
 		const [, , options] = (complete as ReturnType<typeof vi.fn>).mock
-			.calls[0] as [
-			AvailableModel,
-			unknown,
-			{ maxTokens: number },
-		];
-		expect(options.maxTokens).toBe(12800);
+			.calls[0] as [AvailableModel, unknown, { maxTokens?: number }];
+		// reserveTokens (16000) used to cap this at 12800; the cap is gone.
+		expect(options).not.toHaveProperty("maxTokens");
 	});
 
 	it("falls back with a warning on an empty summary", async () => {
@@ -568,6 +566,31 @@ describe("session_before_compact handler", () => {
 		expect(prompts[0]).toContain("Additional focus: 保留命令输出细节");
 	});
 
+	it("passes customInstructions to the split-turn prefix summary too", async () => {
+		getCompactStore().setModel("google/gemini-2.5-flash");
+		const { handler } = registeredHandler();
+		const prompts: string[] = [];
+		const { ctx } = fakeCtx({
+			complete: vi.fn(async (_model, context) => {
+				prompts.push(
+					(context.messages[0]?.content as Array<{ text?: string }>)[0]?.text ??
+						"",
+				);
+				return fakeResponse("## Goal\n- x");
+			}),
+		});
+		const event = fakeEvent({
+			messagesToSummarize: [],
+			turnPrefixMessages: [userMessage("prefix msg")],
+			isSplitTurn: true,
+		});
+		Object.assign(event, { customInstructions: "保留命令输出细节" });
+		await handler(event as never, ctx);
+		expect(prompts).toHaveLength(1);
+		expect(prompts[0]).toContain("# Instructions");
+		expect(prompts[0]).toContain("Additional focus: 保留命令输出细节");
+	});
+
 	it("switches to the update prompt when a previous summary exists", async () => {
 		getCompactStore().setModel("google/gemini-2.5-flash");
 		const { handler } = registeredHandler();

package/src/features/compact/index.ts

@@ -9,13 +9,15 @@
  *  - takeover point: the `session_before_compact` extension event, which pi
  *    emits for ALL three trigger reasons (manual / threshold / overflow)
  *    before running its own compaction
- *  - prompts, message assembly, split-turn handling, output budgets, and the
- *    summary file-list tail are verbatim pi built-in behavior (copied from
- *    0.87.1, byte-identical across every published version of the supported
- *    window, 1.0.0 → 1.3.0) — only the executing model differs. The one
- *    exception is `serializeConversation`, which is imported from the host
- *    instead of mirrored, so it tracks whatever the running host does
- *    (1.2.0 stopped feeding assistant thinking into the request).
+ *  - prompts, message assembly, split-turn handling, summary budgets, and
+ *    the summary file-list tail are verbatim pi built-in behavior (copied
+ *    from 0.87.1; `core/compaction/compaction.js` stayed byte-identical
+ *    1.0.0 → 1.3.0, and 1.4.0 changed only the summary output budget and
+ *    the split-turn focus handling mirrored below) — only the executing
+ *    model differs. The one exception is `serializeConversation`, which is
+ *    imported from the host instead of mirrored, so it tracks whatever the
+ *    running host does (1.2.0 stopped feeding assistant thinking into the
+ *    request).
  *  - lossless fallback: unset config, unavailable model, empty/failed
  *    summary, or user abort → return undefined and pi's default compaction
  *    (session model) runs untouched. The extension can never make
@@ -75,7 +77,6 @@ async function completeSummary(
 	ctx: ExtensionContext,
 	model: AvailableModel,
 	promptText: string,
-	maxTokens: number,
 	signal: AbortSignal,
 ): Promise<{ text: string; usage: CompleteUsage }> {
 	const response = await ctx.modelRegistry.complete(
@@ -91,7 +92,10 @@ async function completeSummary(
 			],
 		},
 		{
-			maxTokens,
+			// No `maxTokens`: since pi 1.4.0 (#9512) the built-in compaction asks
+			// for the model's own output limit instead of a fixed fraction of
+			// reserveTokens, so a long reasoning block can no longer eat the cap
+			// and fail the summary with "generation hit the token cap".
 			signal,
 			cacheRetention: "none",
 			sessionId: uuidv7(),
@@ -118,30 +122,26 @@ async function completeSummary(
 	return { text, usage: response.usage };
 }
 
-/**
- * pi's output-budget formula (compaction.js, 0.87.1 → 1.3.0 unchanged): a
- * fraction of reserveTokens clamped by the model's own output cap.
- */
-function summarizationBudget(
-	fraction: number,
-	reserveTokens: number,
-	modelMaxTokens: number,
-): number {
-	return Math.min(
-		Math.floor(fraction * reserveTokens),
-		modelMaxTokens > 0 ? modelMaxTokens : Number.POSITIVE_INFINITY,
-	);
-}
-
 /**
  * Run the full compaction summarization with the configured model,
- * replicating pi's compact() (0.87.1, byte-identical across the supported
- * 1.0.0 → 1.3.0 window):
+ * replicating pi's compact() as of 1.4.0 (byte-identical to 0.87.1's shape
+ * apart from the two 1.4.0 fixes adopted for the whole window, see below):
  * history summary (first-connection or iterative-update prompt, custom
  * focus appended), plus a separate turn-prefix checkpoint when the cut point
  * splits a turn, merged into one summary with the file-list tail. Returns
  * undefined on any failure after notifying (pi default compaction then takes
  * over).
+ *
+ * 1.4.0 changed two things this mirror covers, and we follow 1.4.0 for every
+ * host in the supported window (1.1.0 → 1.4.0) because both are bug fixes
+ * rather than behavior we could sensibly keep per version:
+ *  - summaries no longer cap maxTokens at 0.8/0.5 × reserveTokens; the
+ *    request omits maxTokens so the provider uses the model's output limit
+ *    (#9512 — long reasoning made summaries fail with "generation hit the
+ *    token cap"). `reserveTokens` now only decides when compaction starts.
+ *  - `/compact <instructions>` also reaches the split-turn prefix summary
+ *    (#11058; before 1.4.0 the focus was dropped when the split turn was the
+ *    only new content).
  */
 async function runCompactModelCompaction(
 	ctx: ExtensionContext,
@@ -157,7 +157,6 @@ async function runCompactModelCompaction(
 		firstKeptEntryId,
 		previousSummary,
 		fileOps,
-		settings,
 	} = preparation;
 
 	try {
@@ -177,11 +176,6 @@ async function runCompactModelCompaction(
 						previousSummary,
 						customInstructions,
 					),
-					summarizationBudget(
-						0.8,
-						settings.reserveTokens,
-						model.maxTokens,
-					),
 					signal,
 				);
 				historyText = history.text;
@@ -192,8 +186,8 @@ async function runCompactModelCompaction(
 				model,
 				buildTurnPrefixPromptText(
 					serializeConversation(convertToLlm(turnPrefixMessages)),
+					customInstructions,
 				),
-				summarizationBudget(0.5, settings.reserveTokens, model.maxTokens),
 				signal,
 			);
 			summaryText = `${historyText}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefix.text}`;
@@ -212,7 +206,6 @@ async function runCompactModelCompaction(
 					previousSummary,
 					customInstructions,
 				),
-				summarizationBudget(0.8, settings.reserveTokens, model.maxTokens),
 				signal,
 			);
 			summaryText = history.text;

package/src/features/compact/prompt.ts

@@ -6,14 +6,15 @@
  * summaries produced by the configured compact model are formatted exactly
  * like pi's own compaction output. Only the executing model differs.
  * Verified byte-identical against every published version of the supported
- * window (1.0.0 → 1.3.0): dist/core/compaction/compaction.js and
- * core/usage-totals.js are unchanged files across that span, and the only
- * utils.js change (1.2.0 dropping assistant thinking from
+ * window (1.1.0 → 1.4.0): core/usage-totals.js is unchanged across that
+ * span, the only utils.js change (1.2.0 dropping assistant thinking from
  * serializeConversation) does not touch the strings mirrored here — that
- * serializer is imported from the host, not mirrored. 0.87.0 shipped a
- * different split-turn prefix prompt; the text mirrored here is 0.87.1's
- * fix, and the mirror is the only variant any supported host gets —
- * intentional.
+ * serializer is imported from the host, not mirrored — and compaction.js
+ * changed once, in 1.4.0, in the output budget and the split-turn focus
+ * handling (both adopted here, see buildTurnPrefixPromptText). 0.87.0
+ * shipped a different split-turn prefix prompt; the text mirrored here is
+ * 0.87.1's fix, and the mirror is the only variant any supported host gets
+ * — intentional.
  *
  * Update these strings whenever pi changes its built-in prompts (diff
  * dist/core/compaction/compaction.js between versions).
@@ -146,11 +147,21 @@ export function buildHistoryPromptText(
 
 /**
  * Build the split-turn prefix prompt text (pi 0.87.1
- * generateTurnPrefixSummary): `# Conversation` block followed by
- * `# Instructions`.
+ * generateTurnPrefixSummary, extended in 1.4.0): `# Conversation` block
+ * followed by `# Instructions`, with the `/compact <instructions>` focus
+ * appended as `Additional focus: ...`. 1.4.0 added that last line (#11058:
+ * the focus used to be dropped when the split turn was the only new
+ * content since the last compaction); we use the fixed form on every host.
  */
-export function buildTurnPrefixPromptText(conversationText: string): string {
-	return `# Conversation\n${conversationText}\n\n# Instructions\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
+export function buildTurnPrefixPromptText(
+	conversationText: string,
+	customInstructions?: string,
+): string {
+	let promptText = `# Conversation\n${conversationText}\n\n# Instructions\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
+	if (customInstructions) {
+		promptText = `${promptText}\n\nAdditional focus: ${customInstructions}`;
+	}
+	return promptText;
 }
 
 /** File-operation sets extracted by pi's prepareCompaction. */
@@ -203,7 +214,7 @@ export function formatFileOperations(
 /**
  * Combine two provider usage records field-wise (pi 0.87.1 compaction.js
  * combineUsage, moved verbatim to core/usage-totals.js in 0.99.0 and
- * unchanged through 1.3.0): used when
+ * unchanged through 1.4.0): used when
  * a split turn produces two summarization calls.
  */
 export function combineUsage<T extends UsageLike>(first: T, second: T): T {

package/src/features/favorites/constants.ts

@@ -8,8 +8,8 @@
  * bindings — only the cycle semantics change (patch-cycle.ts), so no
  * keybinding conflicts arise.
  *
- * Verified against every published version of the supported window
- * (1.0.0 → 1.3.0) keybinding
+ * Verified against every published version of the supported range
+ * (0.99.0 → 1.4.0) keybinding
  * tables + pi-tui input dispatch on WSL2 + Windows Terminal; re-run
  * `pnpm check:keybindings` after every host upgrade before trusting this.
  */
@@ -30,11 +30,12 @@ export const FAVORITES_FILE = "pi-toolkits-favorites.json";
  * Windows/WSL `tui.altScreen.search` resolves to ctrl+f, and
  * `TuiAltScreen.handleViewportInput()` checks it before
  * `shouldDeferViewportInputToOverlay()`, so the keystroke opens transcript
- * search and the selector never sees it (verified in pi-tui 1.3.0
+ * search and the selector never sees it (verified in pi-tui 1.4.0
  * `dist/tui-alt-screen.js`: the search check is the first key branch and
- * returns `{ consume: true }` unconditionally).
+ * returns `{ consume: true }` unconditionally; the 1.4.0 changes to that
+ * file are exit/teardown only).
  *
- * Why ctrl+alt+f was discarded: clean at the pi layer across 1.0–1.3 (only
+ * Why ctrl+alt+f was discarded: clean at the pi layer across 1.1–1.4 (only
  * ctrl+alt+] is taken from that family) and byte-distinguishable without
  * kitty — but grabbed at the OS/app layer on the author's machine by a
  * Windows screenshot tool, so it never reached the terminal. Lesson: a key

package/src/features/favorites/patch-cycle.ts

@@ -15,7 +15,8 @@
  *    model available" feedback); otherwise jump to it
  *  - the apply logic mirrors pi's _cycleScopedModel/_cycleAvailableModel
  *    (byte-identical across every published version in the supported window
- *    1.0.0 → 1.3.0:
+ *    1.1.0 → 1.4.0 — `cycleModel` itself is untouched by 1.4.0's recovery and
+ *    tool-restore rewrites:
  *    state swap, session persistence, default-model persistence only when
  *    `options.persist` is set, thinking-level re-clamp, model_select emit
  *    with source "cycle")
@@ -31,9 +32,9 @@ import { getFavoritesStore, modelKey } from "./store.js";
 
 /**
  * pi's `Model<any>` — the exact type of `ModelCycleResult.model`
- * (pi-coding-agent 1.0–1.3; the field is unchanged across that span).
+ * (pi-coding-agent 1.1–1.4; the field is unchanged across that span).
  * Derived here instead of importing `Model` from @earendil-works/pi-ai,
- * whose index.d.ts (1.0 through 1.3.0 alike) re-exports it via an
+ * whose index.d.ts (1.1 through 1.4.0 alike) re-exports it via an
  * extensioned `"./types.ts"` specifier that not every TS resolver substitutes
  * to `types.d.ts` (tsc 5.9 bundler does; other tsserver builds don't).
  */

package/src/features/favorites/patch-selector.ts

@@ -21,8 +21,8 @@
  * upgraded internals), patches are skipped with a warning — the extension
  * keeps loading and ctrl+p falls back to stock behavior. The prototype
  * shape touched here (handleInput/updateList/filterModels and the instance
- * fields below) is byte-identical across every published version in
- * pi 1.0.0 → 1.3.0 (and 0.99.0 → 1.2.0 before the floor moved).
+ * fields below) is byte-identical across the mandatory window
+ * pi 1.1.0 → 1.4.0 (and exercised by the 0.99.0 → 1.0.4 backward probes).
  */
 import {
 	ModelSelectorComponent,