one-code-extension 0.4.1 → 0.5.0

package/extensions/file-tracker/index.ts

@@ -7,20 +7,42 @@
  *   cannot overwrite someone else's change.
  * - Files that change out of band are reported in a `<system-reminder>` with the
  *   new content around the change, line-numbered.
+ * - pi's read, write and edit results read as Claude Code's (`results.ts`).
+ * - After a compaction, the files read or written most recently come back as
+ *   Claude Code brings them back: the contents of a small one, a note to read
+ *   a large one again (`restore.ts`), and the read state is cleared.
  *
  * Tracking is by content, not by tool call, which is what makes it catch writes
  * that went through bash and never touched an intercepted tool.
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CHILD_WROTE_CHANNEL, type ChildWrote } from "../lib/child-writes.ts";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createReadToolDefinition, type ExtensionAPI, type ExtensionContext, type SessionCompactEvent } from "@earendil-works/pi-coding-agent";
 import { pathArgument } from "../auto-mode/paths.ts";
-import { REMINDER_CHANNEL } from "../lib/reminders.ts";
-import { pathsReadOnBranch } from "./replay.ts";
+import { bashParserReady } from "../lib/bash-parser.ts";
+import { discoverContextFiles, instructionRule } from "../lib/claude-context.ts";
+import { readExternalIncludesApproval } from "../lib/claude-external-includes.ts";
+import { inContextEntries, latestCompaction } from "../lib/compaction-boundary.ts";
+import { autoMemoryEnabled } from "../lib/auto-memory.ts";
+import { projectMemoryDir } from "../lib/memory.ts";
+import { claudeConfigDir, comparablePath, isPathAtOrUnder, tryRealpath } from "../lib/paths.ts";
+import { estimateTextTokens } from "../lib/pi-ai-estimate.ts";
+import { planFileOnBranch } from "../lib/plan-mode-channels.ts";
+import { REMINDER_CHANNEL, type ReminderPayload } from "../lib/reminders.ts";
+import { resolveToolPath } from "../lib/tool-path.ts";
+import { parseRules, ruleMatches } from "../permissions/matcher.ts";
+import { loadPermissionSettings } from "../permissions/settings.ts";
+import { keptReadPaths, keptShellReadPaths, lastTouchesOnBranch, pathsReadOnBranch, shellCallsOnBranch } from "./replay.ts";
+import { type RestoredRead, restoreBlocks, restoreCandidates } from "./restore.ts";
+import { fileToolResultContent } from "./results.ts";
+import { shellReadPaths, shownInFull } from "./shell-reads.ts";
+import { sessionWorkCwd, WORKTREE_CHANNEL, type WorktreeLocation } from "../lib/worktree-channel.ts";
 import {
 	describeChanges,
-	EXTERNAL_CHANGE_REMINDER,
+	CHILD_CHANGE_REMINDER, EXTERNAL_CHANGE_REMINDER,
 	type FileStamp,
 	FileTracker,
 	STALE_REASON,
@@ -46,6 +68,15 @@ function readIfPresent(path: string): string | undefined {
 	}
 }
 
+/** Whether `path` is a regular file (symlinks followed): never a device, FIFO or directory. */
+function isRegularFile(path: string): boolean {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
 /** The file's disk stamp, or undefined when it is gone (or not a plain file we could stat). */
 function statIfPresent(path: string): FileStamp | undefined {
 	try {
@@ -56,12 +87,84 @@ function statIfPresent(path: string): FileStamp | undefined {
 	}
 }
 
-/** Observe a file's current content together with the stamp it was read at. */
-function observeFromDisk(tracker: FileTracker, path: string): void {
+function commandOf(input: unknown): string {
+	const command = (input as { command?: unknown } | undefined)?.command;
+	return typeof command === "string" ? command : "";
+}
+
+function textOf(content: unknown): string {
+	if (!Array.isArray(content)) return "";
+	return content.map((block) => (block as { type?: string; text?: string })?.type === "text" ? ((block as { text?: string }).text ?? "") : "").join("\n");
+}
+
+/**
+ * A file's identity and version, from metadata only: `ctimeMs` changes on any
+ * write, rename or metadata change, and cannot be set back by the writer.
+ */
+function versionOf(path: string): string | undefined {
+	try {
+		const stat = statSync(path);
+		return stat.isFile() ? `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The files a shell command may print, with each one's version as the command
+ * starts (`shell-reads.ts` paths, resolved as the shell resolves them, from
+ * the directory a literal `cd` earlier in the command moved to). Taken before
+ * the command runs, so a file the command itself rewrites (`cat x; cp y x`)
+ * is not certified with its new content (found by a GPT-6 Sol review,
+ * 2026-10-04). Metadata only: this runs before the permission gate decides
+ * the call, so a file the user then denies is never opened.
+ */
+function shellReadSnapshot(command: string, cwd: string): Map<string, string> {
+	const snapshot = new Map<string, string>();
+	if (!command) return snapshot;
+	for (const path of shellReadPaths(command, cwd, homedir(), (dir) => readdirSync(dir))) {
+		// Regular files only: a device or FIFO (`head -c 1 /dev/zero`) reports size 0
+		// and a read of it never ends (found by a GPT-6 Astra review).
+		if (!isRegularFile(path)) continue;
+		const stamp = statIfPresent(path);
+		if (!stamp || stamp.size > MAX_SHELL_READ_BYTES) continue;
+		const version = versionOf(path);
+		if (version !== undefined) snapshot.set(path, version);
+	}
+	return snapshot;
+}
+
+/**
+ * Count as read each file the command printed in full and did not change:
+ * its version before and after the command is the same, and the output holds
+ * all of it. Observed, not touched: the post-compaction restore follows the
+ * file tools, as Claude Code's does. Returns the files it observed.
+ */
+function observeShellReads(tracker: FileTracker, before: Map<string, string>, output: string): string[] {
+	const observed: string[] = [];
+	if (!output) return observed;
+	for (const [path, version] of before) {
+		const stamp = statIfPresent(path);
+		if (!stamp || !isRegularFile(path) || versionOf(path) !== version) continue;
+		const content = readIfPresent(path);
+		if (content === undefined || versionOf(path) !== version) continue;
+		if (!shownInFull(output, content)) continue;
+		tracker.observe(path, content, Date.now(), stamp);
+		observed.push(path);
+	}
+	return observed;
+}
+
+/** Above this a shell read's output is persisted, not shown, so the file cannot have been seen whole. */
+const MAX_SHELL_READ_BYTES = 256 * 1024;
+
+/** Observe a file's current content together with the stamp it was read at, and return that stamp. */
+function observeFromDisk(tracker: FileTracker, path: string): FileStamp | undefined {
 	const stamp = statIfPresent(path);
 	const current = readIfPresent(path);
 	if (current === undefined) tracker.forget(path);
 	else tracker.observe(path, current, Date.now(), stamp);
+	return stamp;
 }
 
 function pathOf(input: unknown, cwd: string): string | undefined {
@@ -71,40 +174,165 @@ function pathOf(input: unknown, cwd: string): string | undefined {
 	// read-before-write guard (code-review).
 	const raw = pathArgument(input as Record<string, unknown> | undefined);
 	if (typeof raw !== "string" || !raw.trim()) return undefined;
-	return isAbsolute(raw) ? raw : resolve(cwd, raw);
+	// pi's own resolution (`~`, `@`, `file://`, …): the guard must check the
+	// file the tool will actually touch (lib/tool-path.ts).
+	return resolveToolPath(raw, cwd);
+}
+
+/**
+ * The files the context still shows after a compaction, as comparable paths:
+ * the context stack (the CLAUDE.md family as claude-context discovers it, what
+ * they `@`-import, and the auto-memory index), the plan file, the files a
+ * `read` in the kept turns returned (`kept`, as written) and the files a kept
+ * bash call showed in full (`keptShell`, absolute). Claude Code's restore
+ * skips them; they stay read.
+ */
+function inContextFiles(ctx: ExtensionContext, branch: readonly { type: string; customType?: string; data?: unknown }[], kept: string[], keptShell: string[]): Set<string> {
+	const home = homedir();
+	// Use the context loader's import confinement and approval: a literal
+	// unapproved @import is not evidence that its file is still in context.
+	const stack = discoverContextFiles({ cwd: ctx.cwd, home, homeClaudeDir: claudeConfigDir(), rule: instructionRule(home),
+		includeExternal: readExternalIncludesApproval(ctx.cwd, home).approved,
+	}).flatMap((file) => [file.path, ...(file.imported ?? [])]);
+	return new Set(
+		[...stack, autoMemoryEnabled(ctx.cwd) ? join(projectMemoryDir(ctx.cwd, home), "MEMORY.md") : undefined, planFileOnBranch(branch), ...kept.map((path) => resolveToolPath(path, ctx.cwd)), ...keptShell]
+			.filter((path): path is string => typeof path === "string")
+			.map(comparablePath),
+	);
+}
+
+/**
+ * Whether a file's contents may come back without the permission gate that a
+ * `read` call passes: only a file that resolves (symlinks followed) inside the
+ * working directory and that no read deny or ask rule covers now. Any other
+ * file, one read outside the project after a question, say, is not restored;
+ * the model reads it again through the gate if it needs it. Nothing passes
+ * when the settings cannot be read (the gate reports them).
+ */
+function restoreAllowed(ctx: ExtensionContext): (path: string) => boolean {
+	try {
+		const settings = loadPermissionSettings(ctx.cwd, homedir());
+		const rules = parseRules([...settings.deny, ...settings.ask]);
+		const root = tryRealpath(ctx.cwd) ?? ctx.cwd;
+		return (path) => {
+			const real = tryRealpath(path);
+			if (!real || !isPathAtOrUnder(real, root)) return false;
+			return !rules.some((rule) => ruleMatches(rule, "read", path, ctx.cwd) || ruleMatches(rule, "read", real, ctx.cwd));
+		};
+	} catch {
+		return () => false;
+	}
+}
+
+/** A file read again through pi's own read tool, as the model would see it; undefined when gone, unreadable or an image. */
+async function readAgain(read: ReturnType<typeof createReadToolDefinition>, path: string, ctx: ExtensionContext): Promise<string | undefined> {
+	try {
+		const result = await read.execute("restore", { path }, undefined, undefined, ctx as never);
+		if (result.content.some((block) => block.type !== "text")) return undefined;
+		return result.content.map((block) => (block as { text: string }).text).join("\n");
+	} catch {
+		return undefined;
+	}
 }
 
 export default function fileTrackerExtension(pi: ExtensionAPI) {
 	let tracker = new FileTracker();
+	/**
+	 * The files each bash call showed in full, by call id, decided where the
+	 * call ran: a compaction keeps the reads of the calls it keeps from this,
+	 * since re-parsing a command later resolves it from today's directory.
+	 */
+	const shellReadsByCall = new Map<string, string[]>();
+	const recordShellReads = (callId: string, paths: string[]) => {
+		if (paths.length > 0) shellReadsByCall.set(callId, paths);
+	};
+	/** The entered worktree, where the shell runs while one is active (lib/worktree-channel.ts). */
+	let entered: WorktreeLocation | undefined;
+	pi.events.on(WORKTREE_CHANNEL, (data) => {
+		const location = data as WorktreeLocation | null | undefined;
+		entered = location?.path ? location : undefined;
+	});
 	let sessionId: string | undefined;
+	/**
+	 * Every file a read or write touched on this branch, with its modification
+	 * time as stat'ed then (the transcript time for one replayed after a resume):
+	 * the post-compaction restore's order.
+	 */
+	let touched = new Map<string, number>();
+	/**
+	 * Files this session's own child agents changed since the parent last saw
+	 * them (lib/child-writes.ts). Every way the parent sees a file clears its
+	 * entry: a file tool, a shell read, a rebuild from disk, the change scan.
+	 */
+	const childWrites = new Map<string, string | undefined>();
+	pi.events.on(CHILD_WROTE_CHANNEL, (data) => {
+		const wrote = data as ChildWrote | undefined;
+		if (wrote?.path) childWrites.set(wrote.path, wrote.agent);
+	});
+	/** Observe a file the model read or wrote, and record it as touched at its current modification time. */
+	const touch = (path: string) => {
+		childWrites.delete(path);
+		const stamp = observeFromDisk(tracker, path);
+		if (stamp) touched.set(path, stamp.mtimeMs);
+	};
 
 	// A resumed session (or a session_tree switch) carries reads the model did
-	// earlier in the transcript; rebuild the tracker from the branch so post-
-	// resume edits are not refused as "never read" (replay.ts). A new session id
-	// starts from an empty tracker.
-	const reconstruct = (ctx: ExtensionContext) => {
+	// earlier in the transcript; rebuild the tracker from the part of the branch
+	// still in context (since the latest compaction's kept tail) so post-resume
+	// edits are not refused as "never read" (replay.ts). A new session id starts
+	// from an empty tracker.
+	const reconstruct = (ctx: ExtensionContext, fresh = false) => {
 		const id = ctx.sessionManager.getSessionId?.() ?? undefined;
-		if (id !== sessionId) {
+		if (fresh || id !== sessionId) {
 			sessionId = id;
 			tracker = new FileTracker();
 		}
+		// Tracked files are re-read from disk below: what a child wrote is now the baseline.
+		childWrites.clear();
 		let entries: unknown[] = [];
 		try {
-			entries = ctx.sessionManager.getBranch() as unknown[];
+			entries = inContextEntries(ctx.sessionManager.getBranch() as unknown[]);
 		} catch {
 			return;
 		}
 		for (const raw of pathsReadOnBranch(entries)) {
-			observeFromDisk(tracker, isAbsolute(raw) ? raw : resolve(ctx.cwd, raw));
+			observeFromDisk(tracker, resolveToolPath(raw, ctx.cwd));
 		}
+		// Shell reads need the bash grammar, which may still be loading this early.
+		const target = tracker;
+		shellReadsByCall.clear();
+		const shellCalls = [...shellCallsOnBranch(entries)];
+		if (shellCalls.length > 0) {
+			void bashParserReady().then(() => {
+				if (target !== tracker) return;
+				// A replayed result has no before-state: the files as they are now stand in for it.
+				for (const call of shellCalls) recordShellReads(call.id, observeShellReads(target, shellReadSnapshot(call.command, sessionWorkCwd(entered, ctx.cwd)), call.output));
+			});
+		}
+		touched = new Map([...lastTouchesOnBranch(entries)].map(([raw, at]) => [resolveToolPath(raw, ctx.cwd), at]));
 	};
 	pi.on("session_start", (_event, ctx) => reconstruct(ctx));
-	pi.on("session_tree", (_event, ctx) => reconstruct(ctx));
+	// A branch switch keeps the session id, but the reads of the branch left
+	// behind are not in context any more: start from an empty tracker, as for a
+	// new session (found by an adversarial GPT-6 Astra run, 2026-10-04).
+	pi.on("session_tree", (_event, ctx) => reconstruct(ctx, true));
+
+	/** Whether a write's file existed when the call was made, by call id: its result says "created" or "updated". */
+	const writeTargetExisted = new Map<string, boolean>();
 
-	pi.on("tool_call", (event, ctx) => {
+	/** Each running bash call's candidate files as they were when it started (`shellReadSnapshot`). */
+	const shellSnapshots = new Map<string, Map<string, string>>();
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName === "bash") {
+			await bashParserReady();
+			// Relative paths in the command resolve where the shell runs: the entered worktree, if any.
+			shellSnapshots.set(event.toolCallId, shellReadSnapshot(commandOf(event.input), sessionWorkCwd(entered, ctx.cwd)));
+			return undefined;
+		}
 		if (!GUARDED_TOOLS.has(event.toolName)) return undefined;
 		const path = pathOf(event.input, ctx.cwd);
 		if (!path) return undefined;
+		if (event.toolName === "write") writeTargetExisted.set(event.toolCallId, existsSync(path));
 
 		const current = readIfPresent(path);
 		const status = tracker.status(path, current);
@@ -115,8 +343,19 @@ export default function fileTrackerExtension(pi: ExtensionAPI) {
 		return { block: true, reason: STALE_REASON(path) };
 	});
 
-	pi.on("tool_result", (event, ctx) => {
-		if (event.isError) return undefined;
+	pi.on("tool_result", async (event, ctx) => {
+		const existedBefore = writeTargetExisted.get(event.toolCallId);
+		writeTargetExisted.delete(event.toolCallId);
+		if (event.toolName === "bash") {
+			const before = shellSnapshots.get(event.toolCallId);
+			shellSnapshots.delete(event.toolCallId);
+			if (before) {
+				const observed = observeShellReads(tracker, before, textOf(event.content));
+				recordShellReads(event.toolCallId, observed);
+				for (const path of observed) childWrites.delete(path);
+			}
+			return undefined;
+		}
 		if (!READ_TOOLS.has(event.toolName) && !GUARDED_TOOLS.has(event.toolName)) return undefined;
 
 		const path = pathOf(event.input, ctx.cwd);
@@ -124,8 +363,69 @@ export default function fileTrackerExtension(pi: ExtensionAPI) {
 
 		// After a read we know the file; after our own write we know it again, so a
 		// successful edit does not make the file look stale to the next edit.
-		observeFromDisk(tracker, path);
-		return undefined;
+		if (!event.isError) touch(path);
+		const content = fileToolResultContent({
+			toolName: event.toolName,
+			isError: event.isError,
+			content: event.content,
+			path,
+			cwd: ctx.cwd,
+			existedBefore,
+			isEmptyFile: () => statIfPresent(path)?.size === 0,
+		});
+		return content ? { content } : undefined;
+	});
+
+	/**
+	 * Claude Code's post-compaction file restore (`restore.ts`). The
+	 * blocks open the next user message (`user-prepend`); an overflow compaction
+	 * that retries the turn has no such message, so they ride the request's tail
+	 * instead.
+	 *
+	 * Like Claude Code, the compaction also clears what the session has read:
+	 * the summary no longer holds those files, so an edit needs a fresh read.
+	 * A file the context still shows stays read (a kept turn's read or whole-file
+	 * shell read, the context stack, the plan file), and a restored file counts
+	 * as read and as touched for the next compaction's restore; a note never
+	 * marks its file read. Contents come back only for a file the gate would
+	 * let through without a question (`restoreAllowed`).
+	 */
+	pi.on("session_compact", async (event: SessionCompactEvent, ctx) => {
+		const before = touched;
+		try {
+			const branch = ctx.sessionManager.getBranch();
+			const compaction = latestCompaction(branch);
+			const keptTurns = compaction ? branch.slice(compaction.keptStart, compaction.index) : [];
+			// The kept shell reads: what each kept bash call certified as it ran.
+			const keptShell = keptShellReadPaths(keptTurns, (id) => shellReadsByCall.get(id), (path) => tracker.lastSeen(path));
+			// A call the summary took never comes back: only the kept ones need their record.
+			const keptCalls = new Set([...shellCallsOnBranch(keptTurns)].map((call) => call.id));
+			for (const id of shellReadsByCall.keys()) if (!keptCalls.has(id)) shellReadsByCall.delete(id);
+			const inContext = inContextFiles(ctx, branch, keptReadPaths(keptTurns), keptShell);
+			// The loader lists imports by real path; a tracked path may be spelled through a symlink.
+			const shown = (path: string) => inContext.has(comparablePath(path)) || inContext.has(comparablePath(tryRealpath(path) ?? path));
+			// A file the context still shows keeps its read state (what the model
+			// saw, not what is on disk now, so the stale-edit guard still holds)
+			// and its touch time, for the next compaction's restore.
+			for (const path of tracker.tracked) if (!shown(path)) tracker.forget(path);
+			touched = new Map([...before].filter(([path]) => shown(path)));
+			// Opting out of One Code's restore does not disable pi's compaction:
+			// reads discarded by either summarizer still need a fresh read.
+			if (process.env.CC_COMPACTION === "0" || before.size === 0) return;
+			const allowed = restoreAllowed(ctx);
+			const candidates = restoreCandidates(before, (path) => shown(path) || !allowed(path));
+			const read = createReadToolDefinition(ctx.cwd);
+			const reads: RestoredRead[] = await Promise.all(candidates.map(async (path) => ({ path, text: await readAgain(read, path, ctx) })));
+			const { blocks, restored } = restoreBlocks(reads, estimateTextTokens);
+			const placement = event.willRetry ? "last-append" : "user-prepend";
+			for (const text of blocks) pi.events.emit(REMINDER_CHANNEL, { text, placement } satisfies ReminderPayload);
+			for (const path of restored) touch(path);
+		} catch {
+			// The restore is best effort: nothing comes back, and an edit needs a fresh read.
+			tracker = new FileTracker();
+			touched = new Map();
+			shellReadsByCall.clear();
+		}
 	});
 
 	/**
@@ -166,14 +466,22 @@ export default function fileTrackerExtension(pi: ExtensionAPI) {
 		const detailed: string[] = [];
 		const overflow: string[] = [];
 		for (const path of tracker.tracked) {
+			// Undefined for a file tracked without content (oversized); an empty
+			// file is compared like any other.
 			const previous = tracker.lastSeen(path);
-			if (previous === undefined || previous === "") continue;
+			if (previous === undefined) continue;
 			const stamp = statIfPresent(path);
 			if (stamp && tracker.unchangedOnDisk(path, stamp)) continue;
+			// This scan accounts for the child's write whatever it finds (same
+			// content, already notified, overflow), so a later change by someone
+			// else is never credited to that agent.
+			const byChild = childWrites.has(path);
+			const childAgent = childWrites.get(path);
+			childWrites.delete(path);
 			const current = stamp ? readIfPresent(path) : undefined;
 			if (stamp === undefined || current === undefined) {
 				tracker.forget(path);
-				detailed.push(`${path} no longer exists; it was deleted or moved after you read it.`);
+				detailed.push(`${path} no longer exists; it was deleted or moved after you last read or wrote it.`);
 				continue;
 			}
 			tracker.recordStamp(path, stamp);
@@ -183,7 +491,7 @@ export default function fileTrackerExtension(pi: ExtensionAPI) {
 
 			if (detailed.length < DETAILED_CHANGE_REMINDERS_PER_TURN) {
 				const excerpt = describeChanges(previous, current);
-				if (excerpt) detailed.push(EXTERNAL_CHANGE_REMINDER(path, excerpt));
+				if (excerpt) detailed.push(byChild ? CHILD_CHANGE_REMINDER(path, childAgent, excerpt) : EXTERNAL_CHANGE_REMINDER(path, excerpt));
 			} else {
 				overflow.push(path);
 			}
@@ -212,8 +520,11 @@ export default function fileTrackerExtension(pi: ExtensionAPI) {
 	pi.on("agent_start", () => {
 		// A turn aborted mid-batch can leave ids behind; each turn starts from a
 		// clean set so the mid-turn scan cannot be wedged off for the rest of the
-		// session.
+		// session. A write blocked before it ran left its existence entry behind,
+		// and a blocked or aborted bash call its snapshot of file versions.
 		executing.clear();
+		writeTargetExisted.clear();
+		shellSnapshots.clear();
 		reportExternalChanges();
 		return undefined;
 	});

package/extensions/file-tracker/replay.ts

@@ -11,6 +11,9 @@
  * guard still catches anything that changes from this point on.
  */
 
+import { pathArgument } from "../auto-mode/paths.ts";
+import { shownInFull } from "./shell-reads.ts";
+
 const READ_TOOLS = new Set(["read", "notebook_edit"]);
 const WRITE_TOOLS = new Set(["edit", "write", "notebook_edit"]);
 
@@ -21,26 +24,109 @@ interface ToolCallBlock {
 	arguments?: Record<string, unknown>;
 }
 
-/** Paths (as written in the tool input) of every successful read/edit/write on the branch, in order, deduplicated. */
-export function pathsReadOnBranch(entries: unknown[]): string[] {
+type BranchMessage = { role?: string; content?: unknown; toolCallId?: string; isError?: boolean; timestamp?: number };
+
+/**
+ * Every tool call on the branch that names a path (`path`, `file_path` or
+ * `notebook_path`, as the gates read it) and got a successful result, in
+ * result order, with the result message's time.
+ */
+export function* successfulPathCalls(entries: readonly unknown[]): Generator<{ name: string; path: string; timestamp: number | undefined }> {
 	const calls = new Map<string, { name: string; path: string }>();
-	const seen: string[] = [];
 	for (const entry of entries) {
-		const e = entry as { type?: string; message?: { role?: string; content?: unknown; toolCallId?: string; toolName?: string; isError?: boolean } };
+		const e = entry as { type?: string; message?: BranchMessage };
 		if (e?.type !== "message" || !e.message) continue;
 		const m = e.message;
 		if (m.role === "assistant" && Array.isArray(m.content)) {
 			for (const block of m.content as ToolCallBlock[]) {
 				if (block?.type !== "toolCall" || !block.id) continue;
-				const path = block.arguments?.path;
-				if (typeof path === "string" && path.trim()) calls.set(block.id, { name: block.name, path });
+				const path = pathArgument(block.arguments);
+				if (path?.trim()) calls.set(block.id, { name: block.name, path });
 			}
 		} else if (m.role === "toolResult" && m.toolCallId && !m.isError) {
 			const call = calls.get(m.toolCallId);
-			if (!call) continue;
-			if (!READ_TOOLS.has(call.name) && !WRITE_TOOLS.has(call.name)) continue;
-			if (!seen.includes(call.path)) seen.push(call.path);
+			if (call) yield { ...call, timestamp: m.timestamp };
+		}
+	}
+}
+
+const touchesFile = (name: string) => READ_TOOLS.has(name) || WRITE_TOOLS.has(name);
+
+/** Paths (as written in the tool input) of every successful read/edit/write on the branch, in order, deduplicated. */
+export function pathsReadOnBranch(entries: readonly unknown[]): string[] {
+	const seen = new Set<string>();
+	for (const call of successfulPathCalls(entries)) if (touchesFile(call.name)) seen.add(call.path);
+	return [...seen];
+}
+
+/**
+ * Each path (as written in the tool input) a successful read/edit/write on the
+ * branch touched, with the time of its last such result message: the order
+ * the post-compaction file restore uses after a resume, when the modification
+ * times stat'ed at those reads are gone (Claude Code uses the transcript time
+ * the same way).
+ */
+export function lastTouchesOnBranch(entries: readonly unknown[]): Map<string, number> {
+	const touches = new Map<string, number>();
+	for (const call of successfulPathCalls(entries)) {
+		if (touchesFile(call.name) && call.timestamp !== undefined) touches.set(call.path, call.timestamp);
+	}
+	return touches;
+}
+
+/**
+ * The paths (as written in the tool input) that a successful `read` in the
+ * kept turns returned: those files are in context already, so the
+ * post-compaction restore skips them.
+ */
+export function keptReadPaths(kept: readonly unknown[]): string[] {
+	return [...successfulPathCalls(kept)].filter((call) => call.name === "read").map((call) => call.path);
+}
+
+/**
+ * The tracked files that a bash call in the kept turns showed in full: those
+ * the call certified when it ran (`readsOf`, by call id: the directory it ran
+ * in decided, never today's) whose content as the tracker last saw it (`seen`)
+ * is still all in its kept output. Like a kept `read`, they are in context
+ * still, so they stay read; a file changed since is then stale, not unread. A
+ * call needs its result in the kept turns too, and one with no record
+ * certifies nothing (a miss costs one re-read).
+ */
+export function keptShellReadPaths(kept: readonly unknown[], readsOf: (callId: string) => readonly string[] | undefined, seen: (path: string) => string | undefined): string[] {
+	const shown = new Set<string>();
+	for (const { id, output } of shellCallsOnBranch(kept)) {
+		for (const path of readsOf(id) ?? []) {
+			if (shown.has(path)) continue;
+			const content = seen(path);
+			if (content !== undefined && shownInFull(output, content)) shown.add(path);
+		}
+	}
+	return [...shown];
+}
+
+/**
+ * Every bash call on the branch with its command and the text of its result,
+ * in result order: a resumed session re-checks which files those outputs
+ * showed in full (`shell-reads.ts`), against the files' current content.
+ */
+export function* shellCallsOnBranch(entries: readonly unknown[]): Generator<{ id: string; command: string; output: string }> {
+	const commands = new Map<string, string>();
+	for (const entry of entries) {
+		const e = entry as { type?: string; message?: BranchMessage };
+		if (e?.type !== "message" || !e.message) continue;
+		const m = e.message;
+		if (m.role === "assistant" && Array.isArray(m.content)) {
+			for (const block of m.content as ToolCallBlock[]) {
+				const command = block?.type === "toolCall" && block.name === "bash" ? block.arguments?.command : undefined;
+				if (typeof command === "string" && block.id) commands.set(block.id, command);
+			}
+		} else if (m.role === "toolResult" && m.toolCallId) {
+			const command = commands.get(m.toolCallId);
+			if (command === undefined || !Array.isArray(m.content)) continue;
+			const output = (m.content as { type?: string; text?: string }[])
+				.map((block) => (block?.type === "text" ? (block.text ?? "") : ""))
+				.join("\n");
+			yield { id: m.toolCallId, command, output };
 		}
 	}
-	return seen;
 }

package/extensions/file-tracker/restore.ts

@@ -0,0 +1,63 @@
+/**
+ * The files that come back after a compaction, and how. Pure: no pi imports,
+ * no I/O.
+ *
+ * As in Claude Code: the five files the session read, edited or wrote with
+ * the newest modification time (as stat'ed at that read or write), minus the
+ * files the context still shows, are read again. A file within 5,000 tokens
+ * comes back as a read call and its result, a larger one as a note to read it
+ * again, while the total stays within 50,000 tokens (findings §47). Each is
+ * its own `<system-reminder>` block at the start of the next user message,
+ * worded as Claude Code words them with One Code's tool name and argument
+ * (`read`, `path`).
+ */
+
+export const RESTORE_MAX_FILES = 5;
+export const RESTORE_FILE_MAX_TOKENS = 5_000;
+export const RESTORE_TOTAL_MAX_TOKENS = 50_000;
+
+/**
+ * The files to restore, newest first: the touched files (path to modification
+ * time) minus `skip`, at most five. A file that cannot be read again is
+ * dropped afterwards, not replaced, as in Claude Code.
+ */
+export function restoreCandidates(touched: ReadonlyMap<string, number>, skip: (path: string) => boolean): string[] {
+	const candidates: string[] = [];
+	for (const [path] of [...touched].sort((a, b) => b[1] - a[1])) {
+		if (candidates.length === RESTORE_MAX_FILES) break;
+		if (!skip(path)) candidates.push(path);
+	}
+	return candidates;
+}
+
+/** What reading a candidate again gave: its text as the read tool returns it, or nothing (gone, unreadable, an image). */
+export type RestoredRead = { path: string; text: string | undefined };
+
+/**
+ * The reminder texts (one per `<system-reminder>` block) for the reads, in
+ * order: two blocks for a file within the per-file cap, one note for a larger
+ * one, nothing for a file that could not be read. A file's blocks are kept only
+ * while the running total stays within the overall cap. `restored` lists the
+ * files whose contents went back into context.
+ */
+export function restoreBlocks(reads: RestoredRead[], estimateTokens: (text: string) => number): { blocks: string[]; restored: string[] } {
+	const blocks: string[] = [];
+	const restored: string[] = [];
+	let total = 0;
+	for (const { path, text } of reads) {
+		if (text === undefined) continue;
+		const fits = estimateTokens(text) <= RESTORE_FILE_MAX_TOKENS;
+		const fileBlocks = fits ? [readCallBlock(path), readResultBlock(text)] : [tooLargeNote(path)];
+		const tokens = fileBlocks.reduce((sum, block) => sum + estimateTokens(block), 0);
+		if (total + tokens > RESTORE_TOTAL_MAX_TOKENS) continue;
+		total += tokens;
+		blocks.push(...fileBlocks);
+		if (fits) restored.push(path);
+	}
+	return { blocks, restored };
+}
+
+export const readCallBlock = (path: string) => `Called the read tool with the following input: ${JSON.stringify({ path })}`;
+export const readResultBlock = (text: string) => `Result of calling the read tool:\n${text}`;
+export const tooLargeNote = (path: string) =>
+	`Note: ${path} was read before the last conversation was summarized, but the contents are too large to include. Use read tool if you need to access it.`;