pi-shorthand 0.3.1 → 0.3.2

package/README.md

@@ -1,100 +1,33 @@
 # pi-shorthand
 
-![A code call in Pi: the verdict, then the diff it applied, then the program's output](https://raw.githubusercontent.com/sebinsua/pi-shorthand/main/docs/screenshot.png?v=2)
+![A code call in Pi](https://raw.githubusercontent.com/sebinsua/pi-shorthand/main/docs/screenshot.png?v=2)
 
 A [Pi](https://github.com/earendil-works/pi) tool for editing repositories with Bun programs.
-The model can combine ordinary JavaScript, text edits and structural transformations in one call.
-
-The program sees your repo as normal, but its writes are held back. By default, they're applied only
-if the program succeeds and destination files are unchanged, and the model gets the diff.
-The program performs the edit; tests, type-checks and other verification run separately afterward.
 
 ## Install
 
+Install pi-shorthand and initialize Grit:
+
 ```sh
 pi install npm:pi-shorthand
+npx @getgrit/cli init --global
 ```
 
-Or from GitHub (`pi install git:github.com/sebinsua/pi-shorthand`), or a local clone: `npm install`, then `pi install /path/to/pi-shorthand`.
-
-A project install (`pi install -l`) only loads once you trust the project: Pi asks, or run `pi --approve`.
-
-You also need Bun, git, and either [bubblewrap](https://github.com/containers/bubblewrap) 0.9+
-(Linux) or [AgentFS](https://github.com/tursodatabase/agentfs) and `clang` (macOS:
-`curl -fsSL https://agentfs.ai/install | bash`).
+On macOS, install clang and AgentFS:
 
-The optional `grit()` helper needs Grit’s modules initialized before sandboxed use. Run
-`npm run setup:grit` from this package’s directory if you want to use it. This explicitly runs
-`grit init --global` and changes your user-level Grit state; package installation does not run it.
-
-## What a program can use
-
-Anything in Bun or Node, plus these globals (no imports):
-
-```ts
-await $`git ls-files`.text(); // Bun's shell (the only async one)
-glob("src/**/*.ts"); // → ["src/a.ts", …]
-grep("oldApi(", "src"); // → [{ file, line, text }, …]
-sg.find("oldApi($$$ARGS)", "src"); // ast-grep search
-sg.rewrite("oldApi($$$ARGS)", "newApi($$$ARGS)", "src");
-sg.insert("initialize();", { before: sg.one("run();", "src/app.ts") });
-sg.move(sg.one("function helper() { $$$BODY }", "src/old.ts"), { endOf: sg.file("src/new.ts") });
-sg.remove(sg.one("obsolete();", "src/app.ts"));
-sg.parse(sg.Lang.TypeScript, source); // ast-grep's own API (or import from "@ast-grep/napi")
-grit("`console.log($x)` => `logger.info($x)`", "src");
+```sh
+xcode-select --install
+curl -fsSL https://agentfs.ai/install | bash
 ```
 
-`sg.find`, `sg.one`, `sg.rewrite` and `grit` also accept `sg.file("src/app.ts")` directly, including
-in arrays mixed with paths. Search reads the file's current contents. Missing targets are valid insertion
-destinations but cannot be searched. An explicit target can select an ignored file inside the workspace;
-the tool still only applies Git-visible changes.
+On Linux, install bubblewrap 0.9 or later. For Debian and Ubuntu:
 
-[api.d.ts](api.d.ts) exposes the actual injected helper types for editor completion and external TypeScript
-checking of editing programs. Include it in the program's TypeScript project (or reference
-`pi-shorthand/api` via `compilerOptions.types` when installed as a package). This supplies types, not runtime
-globals. Bun execution does not automatically type-check programs or run application verification.
-
-## Options
-
-- `title`: a short description shown with the call (required).
-- `rollback`: `"all"` (default) applies nothing if the program fails. After a timeout, `"file"`
-  keeps changed files that were no longer open for writing if writer inspection succeeds. Other
-  failures apply nothing because open writers cannot be identified after the process exits.
-- `timeout`: seconds before the program is killed. Default 2.
-
-## Good to know
-
-- Only files git tracks, or would track, are applied.
-- Successful edits are formatted with detected installed project tools (Prettier, oxfmt, Biome, Ruff,
-  Black, gofmt or rustfmt) before the final diff. Ambiguous setups are skipped; formatter failures warn
-  without discarding completed edits. Set `PI_SHORTHAND_FORMAT=0` to disable. No project config is required.
-- Each run snapshots the checkout first; reflinks make that cheap where supported, while other
-  filesystems copy its contents and use corresponding temporary space. On macOS the program runs at
-  a private AgentFS mount, so use paths relative to its working directory for repository files.
-- Generated programs can write to the private workspace and run-specific temporary space; host files
-  outside those roots are read-only, including targets reached through repository symlinks. Run-history
-  logging has a narrow write exception. On macOS, the live checkout is also unreadable.
-- Runs against the same checkout are serialized. If another process edits a destination while a run
-  is in progress, shorthand checks it again immediately before replacing it and reports a conflict.
-  A non-cooperating writer can still race the final filesystem rename or removal itself.
-- To try it with only `read` and `code`: `pi --tools read,code`.
-- Run history is stored in `~/.cache/pi-shorthand/runs.jsonl` with directory mode `0700` and file
-  mode `0600`. It records timestamps, opaque run IDs, lifecycle events, exit status, durations,
-  counts, helper names, and shell executable names. It does not record programs, output, errors,
-  arguments, repository paths, file paths, or diffs. The log rotates at 1 MiB and expires after
-  seven days. Set `PI_SHORTHAND_HISTORY=0` to disable it. To watch enabled history:
-  `tail -f ~/.cache/pi-shorthand/runs.jsonl`.
-
-## Developing
+```sh
+sudo apt install bubblewrap
+```
 
-`npm run check` type-checks (TypeScript 7), lints (oxlint) and checks formatting (oxfmt). A pre-commit
-hook runs it; `npm run format` fixes formatting.
+## Technical choices
 
-`npm test` runs the tests against real overlays (it needs AgentFS on macOS, bubblewrap on Linux).
-`test/linux.sh` runs them on Linux in Docker.
+pi-shorthand gives Pi a programming environment instead of a patch format. This makes multi-file and structural edits possible in one call, but does not guarantee that Pi will find it easier or more reliable than its built-in edit tool. Which works better depends on the model and the task.
 
-`bun e2e/suite.ts` previews the local benchmark suite without calling a model. Add `--execute` to run it.
-The [comparison harness](e2e/README.md) supports stock, optional and replacement editing tools, controlled
-documentation/skills, independent task checks, saved final changes and session reports.
-`bun e2e/run.ts --repo <path or git URL> --task "…" --setups baseline,replace,code --check "…"` runs Pi
-with a real model on fresh copies of your own repository.
+Programs edit an isolated snapshot, with host files outside the repository kept read-only. By default, a failure keeps completed files and rolls back files involved in failed or interrupted edits; changes are applied only if their destination files have not changed. Progress is reported while a program runs, but no run history is written to disk.

package/display.ts

@@ -21,7 +21,7 @@ const LISTED_FILES = 8; // …showing this many, then "and N more files"
 const EXPANDED_DIFF_LINES = 2000; // even expanded, a diff of hundreds of files stops here
 
 export function callLine(args: { title?: string; timeout?: number; rollback?: string }, theme: Theme): string {
-	const settings = [args.rollback === "file" && "rollback per file", args.timeout && `timeout ${args.timeout}s`];
+	const settings = [args.rollback === "all" && "rollback all", args.timeout && `timeout ${args.timeout}s`];
 	const suffix = settings.filter(Boolean).join(", ");
 	return `${theme.fg("toolTitle", theme.bold("code"))} ${args.title ?? ""}${suffix ? theme.fg("muted", ` (${suffix})`) : ""}`;
 }
@@ -69,17 +69,16 @@ export function resultLines(run: RunResult, expanded: boolean, theme: Theme): st
 	}
 	for (const file of run.rolledBack) {
 		const reason = run.writerInspectionFailed
-			? "open writers could not be inspected at the timeout"
-			: run.timedOut
-				? "half-written when the program was killed"
-				: "finished writes unknown after the program exited";
+			? "open writers could not be inspected"
+			: "file edit failed or was interrupted";
 		lines.push(indent(theme.fg("warning", `rolled back ${file}: ${reason}`)));
 	}
 	for (const warning of [...run.warnings, ...printedWarnings]) lines.push(indent(theme.fg("warning", `⚠ ${warning}`)));
 
 	// The sections, each after a blank line.
 	const sections: string[][] = [];
-	const background: ToolBackground = run.exitCode === 0 && run.conflicts.length === 0 ? "toolSuccessBg" : "toolErrorBg";
+	const background: ToolBackground =
+		run.exitCode === 0 && run.conflicts.length === 0 && run.rolledBack.length === 0 ? "toolSuccessBg" : "toolErrorBg";
 	if (applied.length > 0) sections.push(diffLines(applied, expanded, theme, background));
 	if (output && (expanded || !error)) sections.push(outputLines(output, expanded, run.changes.length > 0, theme));
 	if (notApplied.length > 0) sections.push(notAppliedLines(notApplied, expanded, theme, background));
@@ -104,7 +103,7 @@ function verdict(run: RunResult, applied: FileChange[], theme: Theme): string {
 		return theme.fg("error", `✕ Conflict · ${application}${program}`) + took;
 	}
 	if (run.exitCode === 0 && run.changes.length === 0) return theme.fg("success", "✓ No changes") + took;
-	if (run.exitCode === 0) {
+	if (run.exitCode === 0 && run.rolledBack.length === 0) {
 		return theme.fg("success", `✓ Applied ${fileCount(applied)}`) + ` · ${stats(applied, theme)}` + took;
 	}
 	if (applied.length > 0) {

package/file-outcomes.ts

@@ -0,0 +1,100 @@
+/** Per-file edit outcomes sent to the runner over a private inherited descriptor. */
+import { spawnSync } from "node:child_process";
+import { realpathSync, writeSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+
+export type FileOutcomeEvent =
+	| { type: "begin"; id: number; files: string[] }
+	| { type: "end" | "fail"; id: number }
+	| { type: "error"; files: string[] }
+	| { type: "writers"; files: string[] | null };
+
+const descriptor = process.env.PI_SHORTHAND_OUTCOMES_FD;
+const root = process.env.PI_SHORTHAND_EXECUTION_ROOT;
+const forceInspectionFailure = process.env.PI_SHORTHAND_INSPECTION_FAILURE === "1";
+// Subprocesses do not inherit descriptor 3 by default, so do not advertise it to them.
+delete process.env.PI_SHORTHAND_OUTCOMES_FD;
+delete process.env.PI_SHORTHAND_EXECUTION_ROOT;
+delete process.env.PI_SHORTHAND_INSPECTION_FAILURE;
+let nextId = 0;
+
+function send(event: FileOutcomeEvent): void {
+	if (!descriptor) return;
+	const bytes = Buffer.from(JSON.stringify(event) + "\n");
+	let offset = 0;
+	while (offset < bytes.length) offset += writeSync(Number(descriptor), bytes, offset);
+}
+
+function paths(files: readonly string[]): string[] {
+	if (!root) return [];
+	return [
+		...new Set(
+			files
+				.filter((file) => typeof file === "string")
+				.flatMap((file) => {
+					const absolute = resolve(file);
+					try {
+						return [relative(root, absolute), relative(root, realpathSync(absolute))];
+					} catch {
+						return [relative(root, absolute)];
+					}
+				}),
+		),
+	].filter((file) => file !== ".." && !file.startsWith("../") && !isAbsolute(file));
+}
+
+/** An operation may touch several files (for example, moving a node between files). */
+export function editingFiles<T>(files: readonly string[], edit: () => T): T {
+	if (!descriptor) return edit();
+	const id = nextId++;
+	send({ type: "begin", id, files: paths(files) });
+	try {
+		const result = edit();
+		send({ type: "end", id });
+		return result;
+	} catch (error) {
+		send({ type: "fail", id });
+		throw error;
+	}
+}
+
+export function installFileOutcomeTracking(): void {
+	if (!descriptor) return;
+	process.on("uncaughtExceptionMonitor", (error) => {
+		// Native filesystem errors identify their paths even when no editing helper was involved.
+		const details = (typeof error === "object" && error !== null ? error : {}) as { path?: unknown; dest?: unknown };
+		const files = [details.path, details.dest].filter((file): file is string => typeof file === "string");
+		send({ type: "error", files: paths(files) });
+	});
+	process.on("exit", (code) => {
+		if (code === 0) return;
+		send({ type: "writers", files: inspectWriters() });
+	});
+}
+
+/** Exit handlers run before descriptors close, so ordinary errors can be inspected too. */
+function inspectWriters(): string[] | null {
+	if (!root || forceInspectionFailure) return null;
+	// bubblewrap replaces /dev, hiding the host's message-queue mount. Exempt that unrelated
+	// mount from stat probes; otherwise lsof reports incomplete output for every Linux run.
+	const args = ["-n", "-P", "-F", "an", ...(process.platform === "linux" ? ["-e", "/dev/mqueue"] : [])];
+	const result = spawnSync("lsof", args, {
+		encoding: "utf8",
+		timeout: 2000,
+		maxBuffer: 64 * 1024 * 1024,
+	});
+	if (result.error || result.status !== 0 || result.stderr) return null;
+	return parseOpenWriters(result.stdout, root);
+}
+
+export function parseOpenWriters(output: string, directory: string): string[] {
+	const files = new Set<string>();
+	let access = "";
+	for (const line of output.split("\n")) {
+		if (line.startsWith("f")) access = "";
+		if (line.startsWith("a")) access = line.slice(1);
+		if (line.startsWith(`n${directory}/`) && (access === "w" || access === "u"))
+			files.add(relative(directory, line.slice(1)));
+	}
+	return [...files];
+}

package/index.ts

@@ -4,15 +4,15 @@
  */
 
 import { spawn } from "node:child_process";
-import { closeSync, openSync, readSync, statSync, writeFileSync } from "node:fs";
+import { writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import * as path from "node:path";
+import type { Readable } from "node:stream";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type Theme, truncateHead, truncateTail } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { callLine, countLines, fileMetadataSummary, resultLines, unstructuredResultText } from "./display.ts";
-import { RUN_HISTORY_FILE } from "./history.ts";
 import type { FileChange, RunOptions, RunResult } from "./runner.ts";
 
 // Runs typically take well under a second. Longer transformations can request more time.
@@ -34,14 +34,19 @@ export default function (pi: ExtensionAPI) {
 	// rather than throwing, since a thrown error loses them.)
 	pi.on("tool_result", async (event) => {
 		const run = event.details as RunResult | undefined;
-		if (event.toolName === "code" && run && (run.exitCode !== 0 || run.conflicts.length > 0)) return { isError: true };
+		if (
+			event.toolName === "code" &&
+			run &&
+			(run.exitCode !== 0 || run.conflicts.length > 0 || run.rolledBack.length > 0)
+		)
+			return { isError: true };
 	});
 
 	pi.registerTool({
 		name: "code",
 		label: "Code",
 		description: DESCRIPTION,
-		promptSnippet: "Make a change with one transactional Bun editing program; run verification separately afterward",
+		promptSnippet: "Make a change with one Bun editing program; run verification separately afterward",
 
 		parameters: Type.Object({
 			title: Type.String({ description: "A few words describing the change, shown to the user" }),
@@ -49,19 +54,18 @@ export default function (pi: ExtensionAPI) {
 			rollback: Type.Optional(
 				StringEnum(["all", "file"] as const, {
 					description:
-						'On failure: "all" (default) applies nothing; "file" retains files closed before a timeout when writer inspection succeeds',
+						'On failure: "file" (default) rolls back failed or interrupted file edits and retains the others; "all" applies nothing',
 				}),
 			),
 			timeout: Type.Optional(Type.Number({ description: "Seconds before the program is killed (default 2)" })),
 		}),
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			// While it runs, show how long it's been going and the latest step from the log.
-			const runId = Math.random().toString(36).slice(2, 10);
+			// While it runs, show how long it's been going and the latest reported step.
 			const startedAt = Date.now();
+			let latest: string | undefined;
 			const progress = setInterval(() => {
 				const elapsed = `${((Date.now() - startedAt) / 1000).toFixed(1)} s`;
-				const latest = latestStep(runId);
 				onUpdate?.({
 					content: [{ type: "text", text: "running" }],
 					details: { progress: latest ? `${elapsed} · ${latest}` : elapsed },
@@ -70,13 +74,13 @@ export default function (pi: ExtensionAPI) {
 
 			const result = await runWithBun(
 				{
-					runId,
 					cwd: ctx.cwd,
 					program: params.program,
 					timeoutMs: (params.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
-					rollback: params.rollback ?? "all",
+					rollback: params.rollback ?? "file",
 				},
 				signal,
+				(step) => (latest = step),
 			).finally(() => clearInterval(progress));
 			return {
 				content: [{ type: "text", text: textForModel(result, toolCallId) }],
@@ -113,10 +117,17 @@ export function renderCodeResult(
  * to stop (it then puts the repository back and applies nothing). It has its own process group,
  * which is killed afterwards so no subprocess the program started is left behind.
  */
-export function runWithBun(options: RunOptions, signal?: AbortSignal): Promise<RunResult> {
+export function runWithBun(
+	options: RunOptions,
+	signal?: AbortSignal,
+	onProgress?: (step: string) => void,
+): Promise<RunResult> {
 	return new Promise((resolve, reject) => {
 		if (signal?.aborted) return reject(new Error("Aborted"));
-		const runner = spawn("bun", [path.join(import.meta.dirname, "runner.ts")], { detached: true });
+		const runner = spawn("bun", [path.join(import.meta.dirname, "runner.ts")], {
+			detached: true,
+			stdio: ["pipe", "pipe", "pipe", "pipe"],
+		});
 		const stop = () => runner.kill("SIGTERM");
 		signal?.addEventListener("abort", stop);
 
@@ -126,6 +137,22 @@ export function runWithBun(options: RunOptions, signal?: AbortSignal): Promise<R
 		runner.stderr.setEncoding("utf8");
 		runner.stdout.on("data", (chunk) => (stdout += chunk));
 		runner.stderr.on("data", (chunk) => (stderr += chunk));
+		let progressBuffer = "";
+		const progress = runner.stdio[3] as Readable;
+		progress.setEncoding("utf8");
+		progress.on("data", (chunk) => {
+			progressBuffer += chunk;
+			const lines = progressBuffer.split("\n");
+			progressBuffer = lines.pop() ?? "";
+			for (const line of lines) {
+				try {
+					const event = JSON.parse(line) as { step?: unknown };
+					if (typeof event.step === "string") onProgress?.(event.step);
+				} catch {
+					// Progress is advisory; malformed events do not affect the run.
+				}
+			}
+		});
 		runner.on("error", reject);
 		runner.on("close", (code) => {
 			signal?.removeEventListener("abort", stop);
@@ -145,33 +172,6 @@ export function runWithBun(options: RunOptions, signal?: AbortSignal): Promise<R
 	});
 }
 
-/**
- * The latest step logged for a run, e.g. "$ find / -name x" or "grep (18 ms)". Reads only the end of
- * the log, which is shared by every run.
- */
-function latestStep(runId: string): string | undefined {
-	let tail: string;
-	try {
-		const size = statSync(RUN_HISTORY_FILE).size;
-		const length = Math.min(size, 64 * 1024);
-		const buffer = Buffer.alloc(length);
-		const file = openSync(RUN_HISTORY_FILE, "r");
-		readSync(file, buffer, 0, length, size - length);
-		closeSync(file);
-		tail = buffer.toString("utf8");
-	} catch {
-		return undefined; // no log yet
-	}
-
-	const lines = tail.split("\n").filter((line) => line.includes(`"run":"${runId}"`));
-	const last = lines.at(-1);
-	if (!last) return undefined;
-	const event = JSON.parse(last);
-	if (event.event === "command") return `$ ${event.command}`;
-	if (event.event === "helper") return `${event.helper} (${event.ms} ms)`;
-	return event.event;
-}
-
 /** e.g. "✓ exit 0 · 326 ms · 6 files · +48 −17 · applied" */
 function summaryLine(run: RunResult): string {
 	const parts = [];

package/overlay-linux.ts

@@ -9,7 +9,6 @@ import * as fs from "node:fs/promises";
 import { homedir } from "node:os";
 import * as path from "node:path";
 import { $ } from "bun";
-import { historyEnabled, RUN_HISTORY_FILE, RUN_HISTORY_LOCK_DIR } from "./history.ts";
 import type { FilesystemEntry, Overlay } from "./runner.ts";
 
 export async function openLinuxOverlay(repo: string, tempDir: string): Promise<Overlay> {
@@ -24,8 +23,6 @@ export async function openLinuxOverlay(repo: string, tempDir: string): Promise<O
 	const cacheDir = path.join(homedir(), ".cache", "pi-shorthand");
 	const internalDir = path.join(cacheDir, "sandbox");
 	const sandboxExcludesFile = path.join(internalDir, `${path.basename(tempDir)}.exclude`);
-	const logFile = RUN_HISTORY_FILE;
-	const keepHistory = historyEnabled();
 	await copyStableTree(repo, lower);
 	const filesAtStart = await gitVisibleFiles(lower);
 	await fs.mkdir(upper);
@@ -41,8 +38,6 @@ export async function openLinuxOverlay(repo: string, tempDir: string): Promise<O
 	}
 	if ((internalStats.mode & 0o077) !== 0) await fs.chmod(internalDir, 0o700);
 	await fs.writeFile(sandboxExcludesFile, "", { flag: "wx", mode: 0o600 });
-	if (keepHistory) await fs.appendFile(logFile, "", { mode: 0o600 });
-	if (keepHistory) await fs.mkdir(RUN_HISTORY_LOCK_DIR, { recursive: true, mode: 0o700 });
 
 	const wrap = (command: string[], cwd: string) => [
 		bwrap,
@@ -61,8 +56,6 @@ export async function openLinuxOverlay(repo: string, tempDir: string): Promise<O
 		upper,
 		work,
 		repo,
-		...(keepHistory ? ["--bind", logFile, logFile] : []),
-		...(keepHistory ? ["--bind", RUN_HISTORY_LOCK_DIR, RUN_HISTORY_LOCK_DIR] : []),
 		"--tmpfs",
 		"/dev/shm",
 		"--chdir",

package/overlay-macos.ts

@@ -11,7 +11,6 @@ import { homedir, tmpdir } from "node:os";
 import * as path from "node:path";
 import { $ } from "bun";
 import { Database } from "bun:sqlite";
-import { historyEnabled, RUN_HISTORY_FILE, RUN_HISTORY_LOCK_DIR } from "./history.ts";
 import { copyStableTree } from "./overlay-linux.ts";
 import type { FilesystemEntry, Overlay } from "./runner.ts";
 
@@ -203,7 +202,9 @@ async function serveAndMount(
 	try {
 		await onSpawn(server.pid);
 		await waitForPort(port);
-		const options = `locallocks,vers=3,tcp,port=${port},mountport=${port},soft,timeo=100,retrans=5`;
+		// AgentFS copy-up can change directory attributes. Stale NFS directory caches can make
+		// getcwd() fail in nested directories; keep file caching but revalidate directories immediately.
+		const options = `locallocks,vers=3,tcp,port=${port},mountport=${port},soft,timeo=100,retrans=5,acdirmin=0,acdirmax=0`;
 		await $`/sbin/mount_nfs -o ${options} 127.0.0.1:/ ${mount}`.quiet();
 		return server;
 	} catch (error) {
@@ -213,7 +214,7 @@ async function serveAndMount(
 	}
 }
 
-/** Restrict writes to the workspace, private scratch space, devices and optional run history. */
+/** Restrict writes to the workspace, private scratch space and devices. */
 export function sandboxProfile(
 	repo: string,
 	tempDir: string,
@@ -231,12 +232,6 @@ export function sandboxProfile(
 		`(allow file-write* (require-all (subpath ${JSON.stringify(mount)}) (require-not (subpath ${JSON.stringify(path.join(mount, ".git"))}))))`,
 		`(allow file-write* (subpath ${JSON.stringify(scratch)}))`,
 		'(allow file-write-data (literal "/dev/null") (literal "/dev/tty"))',
-		...(historyEnabled()
-			? [
-					`(allow file-write-data (literal ${JSON.stringify(RUN_HISTORY_FILE)}))`,
-					`(allow file-write* (subpath ${JSON.stringify(RUN_HISTORY_LOCK_DIR)}))`,
-				]
-			: []),
 		`(deny file-read* (subpath ${JSON.stringify(repo)}))`,
 		`(deny file-write* (subpath ${JSON.stringify(repo)}))`,
 		`(deny file-write* (subpath ${JSON.stringify(tempDir)}))`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-shorthand",
-	"version": "0.3.1",
+	"version": "0.3.2",
 	"description": "Pi tool for editing repositories with Bun programs, text edits and structural transformations.",
 	"keywords": [
 		"ast-grep",

package/placement.ts

@@ -2,6 +2,7 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { Lang, parse, type SgNode } from "@ast-grep/napi";
+import { editingFiles } from "./file-outcomes.ts";
 
 export interface Match {
 	file: string;
@@ -291,11 +292,23 @@ function apply(plans: { saved: Snapshot; edits: Edit[] }[]) {
 }
 
 export function insert(text: string, destination: Destination): void {
+	return editingFiles(destinationFiles(destination), () => insertNodes(text, destination));
+}
+
+function destinationFiles(destination: Destination): string[] {
+	return Object.values(destination).flatMap((match) => (typeof match?.file === "string" ? [match.file] : []));
+}
+
+function insertNodes(text: string, destination: Destination): void {
 	const { saved, edit } = placement(text, destination);
 	apply([{ saved, edits: [edit] }]);
 }
 
 export function move(match: Match, destination: Destination, transform?: (text: string) => string): void {
+	return editingFiles([match.file, ...destinationFiles(destination)], () => moveNodes(match, destination, transform));
+}
+
+function moveNodes(match: Match, destination: Destination, transform?: (text: string) => string): void {
 	const source = snapshot(match);
 	const deletion = removal(source);
 	const text = transform ? transform(source.node.text()) : source.node.text();
@@ -322,6 +335,14 @@ export function move(match: Match, destination: Destination, transform?: (text:
 }
 
 export function remove(matches: Match | readonly Match[]): void {
+	const selected = Array.isArray(matches) ? matches : [matches as Match];
+	return editingFiles(
+		selected.map((match) => match.file),
+		() => removeNodes(matches),
+	);
+}
+
+function removeNodes(matches: Match | readonly Match[]): void {
 	const plans = new Map<string, { saved: Snapshot; edits: Edit[] }>();
 	for (const match of Array.isArray(matches) ? matches : [matches as Match]) {
 		const saved = snapshot(match);

package/prelude.ts

@@ -9,16 +9,15 @@
  * File lists come from git (tracked, plus untracked files that aren't ignored), so node_modules
  * and build output are left out on every platform.
  *
- * Each $ command and helper call is logged to the runner's log (~/.cache/pi-shorthand/runs.jsonl) as it
- * happens, so `tail -f` shows what a program is doing, including which command it's stuck on.
+ * Each $ command and helper call is reported to the runner while the program is active.
  */
 
-import { lstatSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { lstatSync, readFileSync, realpathSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import * as astGrep from "@ast-grep/napi";
 import { type Edit, Lang, type NapiConfig, parse, type SgNode } from "@ast-grep/napi";
 import { $ as bunShell, Glob } from "bun";
-import { appendRunHistory } from "./history.ts";
+import { editingFiles, installFileOutcomeTracking } from "./file-outcomes.ts";
 import {
 	file as selectFile,
 	getMatchSnapshot,
@@ -30,10 +29,19 @@ import {
 	type FileTarget,
 } from "./placement.ts";
 
-function log(event: string, details: Record<string, unknown>) {
-	const { PI_SHORTHAND_LOG, PI_SHORTHAND_RUN } = process.env;
-	if (!PI_SHORTHAND_LOG) return;
-	appendRunHistory(event, { run: PI_SHORTHAND_RUN, ...details }, PI_SHORTHAND_LOG);
+installFileOutcomeTracking();
+
+const progressDescriptor = process.env.PI_SHORTHAND_PROGRESS_FD;
+// Subprocesses do not inherit this descriptor by default, so do not advertise it to them.
+delete process.env.PI_SHORTHAND_PROGRESS_FD;
+
+function report(event: Record<string, unknown>) {
+	if (!progressDescriptor) return;
+	try {
+		writeSync(Number(progressDescriptor), JSON.stringify(event) + "\n");
+	} catch {
+		// Progress is advisory and must never change the program's result.
+	}
 }
 
 /** Runs a helper, logging how long it took and how many results it returned. */
@@ -41,7 +49,8 @@ function logged<T>(helper: string, _args: unknown[], run: () => T): T {
 	const startedAt = performance.now();
 	const result = run();
 	const results = Array.isArray(result) ? result.length : typeof result === "number" ? result : undefined;
-	log("helper", {
+	report({
+		type: "helper",
 		helper,
 		ms: Math.round(performance.now() - startedAt),
 		results,
@@ -54,7 +63,7 @@ const $ = new Proxy(bunShell, {
 	apply(target, thisArg, args: Parameters<typeof bunShell>) {
 		const [strings] = args;
 		const words = strings.raw[0].trim().split(/\s+/);
-		log("command", { command: words.find((word) => !word.includes("=")) ?? "" });
+		report({ type: "command", command: words.find((word) => !word.includes("=")) ?? "" });
 		return Reflect.apply(target, thisArg, args);
 	},
 });
@@ -354,7 +363,7 @@ function rewrite(...[target, replacement, files]: RewriteArgs): number {
 		const groups = new Map<string, SgMatch[]>();
 		const sources = new Map<string, string | null>();
 		for (const match of (Array.isArray(target) ? target : [target]) as SgMatch[]) {
-			const saved = getMatchSnapshot(match, sources, rewriteStaleAdvice);
+			const saved = editingFiles([match.file], () => getMatchSnapshot(match, sources, rewriteStaleAdvice));
 			if (!match.vars || typeof match.line !== "number")
 				throw new Error("sg.rewrite expects matches from sg.one or sg.find");
 			const file = explicitPath(match.file);
@@ -365,9 +374,11 @@ function rewrite(...[target, replacement, files]: RewriteArgs): number {
 		}
 		let count = 0;
 		for (const [file, matches] of groups) {
-			const currentSources = new Map<string, string | null>();
-			for (const match of matches) getMatchSnapshot(match, currentSources, rewriteStaleAdvice);
-			count += applyRewrites(matches, replacement, file);
+			count += editingFiles([file], () => {
+				const currentSources = new Map<string, string | null>();
+				for (const match of matches) getMatchSnapshot(match, currentSources, rewriteStaleAdvice);
+				return applyRewrites(matches, replacement, file);
+			});
 		}
 		return count;
 	}
@@ -376,13 +387,15 @@ function rewrite(...[target, replacement, files]: RewriteArgs): number {
 	let count = 0,
 		matched = 0;
 	for (const file of sourceFiles("sg.rewrite", scope)) {
-		const parsed = parseFile(file);
-		if (!parsed) continue;
-		const matches = findNodes("sg.rewrite", parsed.root, pattern).map((node) =>
-			toMatch(file, node, parsed.source, pattern),
-		);
-		matched += matches.length;
-		count += applyRewrites(matches, replacement, file);
+		count += editingFiles([file], () => {
+			const parsed = parseFile(file);
+			if (!parsed) return 0;
+			const matches = findNodes("sg.rewrite", parsed.root, pattern).map((node) =>
+				toMatch(file, node, parsed.source, pattern),
+			);
+			matched += matches.length;
+			return applyRewrites(matches, replacement, file);
+		});
 	}
 	if (matched === 0) {
 		const paths = (Array.isArray(scope) ? scope : [scope]).map((entry) =>
@@ -438,6 +451,15 @@ function grit(pattern: string, paths: FileScope = ".", options: { lang?: string;
 	if (options.lang) flags.push("--language", options.lang);
 
 	const targets = selected.map((file) => resolve(repositoryRoot, file));
+
+	if (options.dryRun) return applyGrit(pattern, flags, targets);
+	const affected = targets.flatMap((file) =>
+		statSync(file).isDirectory() ? selectFiles(file).map((entry) => resolve(repositoryRoot, entry)) : [file],
+	);
+	return editingFiles(affected, () => applyGrit(pattern, flags, targets));
+}
+
+function applyGrit(pattern: string, flags: string[], targets: string[]) {
 	const result = Bun.spawnSync(["grit", "apply", ...flags, pattern, ...targets], { env: process.env });
 	if (result.exitCode !== 0) {
 		const diagnostic = result.stderr.toString().trim() || result.stdout.toString().trim();
@@ -504,7 +526,10 @@ function editText({ path, oldText, newText }: { path: string; oldText: string; n
 
 const globals = {
 	$,
-	edit: (...args: Parameters<typeof editText>) => logged("edit", args, () => editText(...args)),
+	edit: (...args: Parameters<typeof editText>) =>
+		logged("edit", args, () =>
+			editingFiles(typeof args[0]?.path === "string" ? [args[0].path] : [], () => editText(...args)),
+		),
 	glob: (...args: Parameters<typeof glob>) => logged("glob", args, () => glob(...args)),
 	grep: (...args: Parameters<typeof grep>) => logged("grep", args, () => grep(...args)),
 	sg: {

package/runner.ts

@@ -4,31 +4,29 @@
  *
  * Usage: echo '<RunOptions as JSON>' | bun runner.ts   → prints a RunResult as JSON
  * SIGTERM aborts: the program is killed, the overlay is closed and nothing is applied.
- * Each step is logged to ~/.cache/pi-shorthand/runs.jsonl, so `tail -f` shows what a run is doing.
+ * Command and helper progress is streamed to the parent process while the run is active.
  *
  * If the program fails:
  * - rollback "all": nothing is applied;
- * - rollback "file": on timeout, files that weren't open for writing are applied. On any other
- *   failure, nothing is applied because the process has exited and its open files can't be inspected.
+ * - rollback "file": failed or interrupted file edits are discarded; other files are applied.
  */
 
 import { type ChildProcess, spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { constants, type Stats } from "node:fs";
+import { constants, type Stats, writeSync } from "node:fs";
 import * as fs from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import * as path from "node:path";
 import { Lang, parse } from "@ast-grep/napi";
 import { $ } from "bun";
 import { structuredPatch } from "diff";
-import { appendRunHistory, historyEnabled, RUN_HISTORY_FILE } from "./history.ts";
 import { openLinuxOverlay } from "./overlay-linux.ts";
 import { openMacOverlay } from "./overlay-macos.ts";
 import { discardedEdits } from "./program-lint.ts";
 import { preserveTextFormat } from "./text-format.ts";
+import { type FileOutcomeEvent, parseOpenWriters } from "./file-outcomes.ts";
 
 export interface RunOptions {
-	runId: string; // identifies this run's events in the log
 	cwd: string;
 	program: string;
 	timeoutMs: number;
@@ -64,7 +62,7 @@ export interface RunResult {
 	applied: string[]; // the changed files that were applied
 	conflicts: string[]; // destinations changed after the run's baseline was captured
 	rolledBack: string[]; // rollback "file": changed files not retained because completion was not established
-	writerInspectionFailed: boolean; // timeout: inspection failed, so no changed file was retained
+	writerInspectionFailed: boolean; // inspection unavailable: no changed file was retained on failure
 	stillRunning: string[]; // on timeout: commands the program was still running, e.g. "find / -name x (for 58s)"
 	lastStep?: string; // on timeout: the last step the program logged, e.g. "$ find / -name x" or "grep (18 ms)"
 	errorLine?: string; // on failure: the program's line the error came from, e.g. "line 3: throw new Error(…)"
@@ -113,12 +111,6 @@ const PRELUDE = path.join(import.meta.dir, "prelude.ts");
 // (e.g. Pi's project installs), one further up. Like `npm run`, look in every one from here up.
 const NODE_MODULES = ancestors(import.meta.dir).map((dir) => path.join(dir, "node_modules"));
 const MAX_OUTPUT_CHARS = 1024 * 1024; // a safety cap; index.ts decides how much the model sees
-let RUN_ID = ""; // set from RunOptions when the runner starts
-
-/** Appends one event to the log, e.g. log("program exited", { exitCode: 0 }). */
-function log(event: string, details: Record<string, unknown> = {}) {
-	appendRunHistory(event, { run: RUN_ID, ...details });
-}
 
 async function run(options: RunOptions, abort: AbortSignal): Promise<RunResult> {
 	const startedAt = performance.now();
@@ -133,10 +125,8 @@ async function run(options: RunOptions, abort: AbortSignal): Promise<RunResult>
 
 	try {
 		tempDir = await fs.mkdtemp(path.join(await fs.realpath(tmpdir()), "pi-shorthand-"));
-		log("started", { timeoutMs: options.timeoutMs, rollback: options.rollback });
 		const open = process.platform === "darwin" ? openMacOverlay : openLinuxOverlay;
 		const overlay = await open(repo, tempDir);
-		log("overlay opened");
 		let program: ProgramRun;
 		let changes: Change[];
 		let executionError: unknown;
@@ -155,7 +145,13 @@ async function run(options: RunOptions, abort: AbortSignal): Promise<RunResult>
 				changes = changes.filter((change) => !entriesEqual(change.before, change.after));
 			}
 			const files = changes.filter((change) => change.after?.type === "file").map((change) => change.file);
-			if (program.exitCode === 0 && !abort.aborted && files.length && process.env.PI_SHORTHAND_FORMAT !== "0") {
+			if (
+				program.exitCode === 0 &&
+				program.failedFiles.length === 0 &&
+				!abort.aborted &&
+				files.length &&
+				process.env.PI_SHORTHAND_FORMAT !== "0"
+			) {
 				try {
 					const module = executionPath(path.join(import.meta.dir, "format.ts"), repo, overlay);
 					const formatting = await runProgram(
@@ -218,12 +214,6 @@ console.log(JSON.stringify(await formatChanged(${JSON.stringify(files)}, process
 				warnings: applicationWarnings,
 			} = await applyChanges(repo, requested, { abort, testHooks: options.testHooks?.apply }));
 		}
-		log("finished", {
-			changed: changes.length,
-			applied: applied.length,
-			conflicts: conflicts.length,
-		});
-
 		result = {
 			exitCode: program.exitCode,
 			timedOut: program.timedOut,
@@ -237,7 +227,7 @@ console.log(JSON.stringify(await formatChanged(${JSON.stringify(files)}, process
 			rolledBack: rolledBack.map((change) => shown(change.file)),
 			writerInspectionFailed: program.openForWriting === null,
 			stillRunning: program.stillRunning,
-			lastStep: program.timedOut ? await lastLoggedStep() : undefined,
+			lastStep: program.timedOut ? program.lastStep : undefined,
 			errorLine: program.exitCode !== 0 ? failingLine(options.program, program.output) : undefined,
 			timeoutMs: options.timeoutMs,
 			rollback: options.rollback,
@@ -276,7 +266,6 @@ async function closeOverlay(overlay: Overlay, injectFailure = false) {
 function cleanupWarning(resource: string, error: unknown): string {
 	const detail = error instanceof Error ? error.message : String(error);
 	const warning = `The run reached its reported outcome, but cleanup of its ${resource} failed: ${detail}`;
-	log("cleanup warning", { warning });
 	return warning;
 }
 
@@ -390,17 +379,17 @@ async function safeParentChain(repo: string, target: string, allowMissing = fals
 	return true;
 }
 
-/** Preserve provably closed files only when a timeout lets us inspect the still-running process. */
+/** Retain independent file edits, excluding failed operations and interrupted writers. */
 function whatToApply(changes: Change[], program: ProgramRun, rollback: RunOptions["rollback"], aborted: boolean) {
 	if (aborted) return { applied: [], rolledBack: [] };
-	if (program.exitCode === 0) return { applied: changes, rolledBack: [] };
-	if (rollback === "all") return { applied: [], rolledBack: [] };
-	if (!program.timedOut) return { applied: [], rolledBack: changes };
+	if (rollback === "all") return { applied: program.exitCode === 0 ? changes : [], rolledBack: [] };
 	if (program.openForWriting === null) return { applied: [], rolledBack: changes };
 
-	const openForWriting = program.openForWriting;
-	const halfWritten = (change: Change) => openForWriting.includes(change.file);
-	return { applied: changes.filter((change) => !halfWritten(change)), rolledBack: changes.filter(halfWritten) };
+	const failed = new Set([...program.failedFiles, ...program.openForWriting]);
+	return {
+		applied: changes.filter((change) => !failed.has(change.file)),
+		rolledBack: changes.filter((change) => failed.has(change.file)),
+	};
 }
 
 /** A `$` command that isn't awaited never runs: Bun's shell starts a command when it's awaited. */
@@ -441,8 +430,10 @@ interface ProgramRun {
 	exitCode: number | null;
 	timedOut: boolean;
 	output: string;
-	openForWriting: string[] | null; // on timeout: open writers, or null when inspection failed
+	openForWriting: string[] | null; // on failure/timeout: open writers, or null when inspection was unavailable
+	failedFiles: string[];
 	stillRunning: string[]; // on timeout: the commands it was still running
+	lastStep?: string;
 }
 
 async function runProgram(
@@ -468,22 +459,29 @@ async function runProgram(
 	// detached: the program gets its own process group, so killing the group kills anything it started too.
 	const outputFile = path.join(tempDir, "output");
 	const output = await fs.open(outputFile, "w");
+	const trackFiles = options.rollback === "file";
+	const outcomePath = path.join(tempDir, "file-outcomes");
+	const outcomeFile = await fs.open(outcomePath, "w");
 	const [command, ...args] = overlay.wrap(
 		[process.execPath, "--preload", executionPrelude, executionProgramPath],
 		executionCwd,
 	);
-	log("program started", { timeoutMs: options.timeoutMs });
 	if (options.testHooks?.programStartMarker) await Bun.write(options.testHooks.programStartMarker, "started");
 	const child = spawn(command, args, {
 		cwd: executionCwd,
 		detached: true,
-		stdio: ["ignore", output.fd, output.fd],
+		stdio: ["ignore", output.fd, output.fd, trackFiles ? outcomeFile.fd : "ignore", "pipe"],
 		env: {
 			...process.env,
 			...overlay.environment,
 			...programEnvironment(excludesFile, repo, overlay),
+			PI_SHORTHAND_OUTCOMES_FD: trackFiles ? "3" : "",
+			PI_SHORTHAND_PROGRESS_FD: "4",
+			PI_SHORTHAND_EXECUTION_ROOT: overlay.executionDir,
+			PI_SHORTHAND_INSPECTION_FAILURE: options.testHooks?.writerInspectionFailure ? "1" : "",
 		},
 	});
+	const progress = trackProgress(child);
 	const killAll = () => killGroup(child);
 	abort.addEventListener("abort", killAll);
 	if (abort.aborted) killAll();
@@ -494,15 +492,16 @@ async function runProgram(
 		overlay.executionDir,
 		options.testHooks?.writerInspectionFailure,
 	);
-	log("program exited", { exitCode, timedOut, aborted: abort.aborted, stillRunning: stillRunning.length });
 	killAll(); // anything it left running
 	abort.removeEventListener("abort", killAll);
 	try {
 		await overlay.terminateProcesses?.();
 	} finally {
-		await output.close();
+		await Promise.all([output.close(), outcomeFile.close()]);
+		await progress.closed;
 		await fs.rm(programFile, { force: true });
 	}
+	const outcomes = fileOutcomes(await Bun.file(outcomePath).text());
 
 	// Keep the tail, where errors are. Show stack traces as "program.ts:3:11", and drop Bun's version footer.
 	let text = await Bun.file(outputFile).text();
@@ -511,7 +510,69 @@ async function runProgram(
 	}
 	text = text.replaceAll(executionProgramPath, "program.ts").replace(/\nBun v[\d.]+ \([^)]*\)\n?$/, "\n");
 
-	return { exitCode, timedOut, output: text, openForWriting, stillRunning };
+	return {
+		exitCode,
+		timedOut,
+		output: text,
+		openForWriting: trackFiles && exitCode !== 0 && !timedOut ? outcomes.writers : openForWriting,
+		stillRunning,
+		failedFiles: outcomes.failedFiles,
+		lastStep: progress.latest(),
+	};
+}
+
+/** Keep the latest command/helper in memory and relay it to index.ts over the runner's descriptor 3. */
+function trackProgress(child: ChildProcess) {
+	const stream = child.stdio[4];
+	let buffer = "";
+	let lastStep: string | undefined;
+	const closed = new Promise<void>((resolve) => {
+		if (!stream || !("setEncoding" in stream)) return resolve();
+		stream.setEncoding("utf8");
+		stream.on("data", (chunk) => {
+			buffer += chunk;
+			const lines = buffer.split("\n");
+			buffer = lines.pop() ?? "";
+			for (const line of lines) {
+				try {
+					const event = JSON.parse(line) as { type?: unknown; command?: unknown; helper?: unknown; ms?: unknown };
+					if (event.type === "command" && typeof event.command === "string") lastStep = `$ ${event.command}`;
+					else if (event.type === "helper" && typeof event.helper === "string" && typeof event.ms === "number")
+						lastStep = `${event.helper} (${event.ms} ms)`;
+					else continue;
+					try {
+						writeSync(3, JSON.stringify({ step: lastStep }) + "\n");
+					} catch {
+						// Direct runner callers do not provide a progress descriptor.
+					}
+				} catch {
+					// Progress is advisory; malformed events do not affect the run.
+				}
+			}
+		});
+		stream.once("end", resolve);
+		stream.once("error", resolve);
+	});
+	return { closed, latest: () => lastStep };
+}
+
+/** Replay helper outcomes after all program processes have stopped. */
+function fileOutcomes(text: string) {
+	const active = new Map<number, string[]>();
+	const failed = new Set<string>();
+	let writers: string[] | null = null;
+	for (const line of text.split("\n").slice(0, -1).filter(Boolean)) {
+		const event = JSON.parse(line) as FileOutcomeEvent;
+		if (event.type === "begin") active.set(event.id, event.files);
+		else if (event.type === "end") active.delete(event.id);
+		else if (event.type === "fail") {
+			for (const file of active.get(event.id) ?? []) failed.add(file);
+			active.delete(event.id);
+		} else if (event.type === "error") {
+			for (const file of event.files) failed.add(file);
+		} else if (event.type === "writers") writers = event.files;
+	}
+	return { writers, failedFiles: [...new Set([...failed, ...[...active.values()].flat()])] };
 }
 
 /**
@@ -535,7 +596,12 @@ async function waitWithTimeout(child: ChildProcess, timeoutMs: number, repo: str
 	]);
 	killGroup(child);
 	await exited;
-	return { exitCode: null, timedOut: true, openForWriting, stillRunning };
+	return {
+		exitCode: null,
+		timedOut: true,
+		openForWriting,
+		stillRunning,
+	};
 }
 
 /**
@@ -577,28 +643,6 @@ function seconds(elapsed: string): number {
 	return Number(days) * 86400 + hours * 3600 + minutes * 60 + secs;
 }
 
-/** The last command or helper call this run's program logged, e.g. "$ find / -name x". */
-async function lastLoggedStep(): Promise<string | undefined> {
-	let lines: string[];
-	try {
-		lines = (await Bun.file(RUN_HISTORY_FILE).text()).trimEnd().split("\n").slice(-500);
-	} catch {
-		return undefined;
-	}
-	for (const line of lines.toReversed()) {
-		let event: Record<string, unknown>;
-		try {
-			event = JSON.parse(line);
-		} catch {
-			continue;
-		}
-		if (event.run !== RUN_ID) continue;
-		if (event.event === "command") return `$ ${event.command}`;
-		if (event.event === "helper") return `${event.helper} (${event.ms} ms)`;
-	}
-	return undefined;
-}
-
 function killGroup(child: ChildProcess) {
 	try {
 		process.kill(-child.pid!, "SIGKILL");
@@ -620,8 +664,6 @@ function programEnvironment(excludesFile: string, repo: string, overlay: Overlay
 		// So programs can import the extension's own packages, e.g. "@ast-grep/napi". A repository's own
 		// node_modules still wins: NODE_PATH is only a fallback.
 		NODE_PATH: [...nodeModules, process.env.NODE_PATH].filter(Boolean).join(path.delimiter),
-		...(historyEnabled() ? { PI_SHORTHAND_LOG: RUN_HISTORY_FILE, PI_SHORTHAND_HISTORY_SANDBOX: "1" } : {}),
-		PI_SHORTHAND_RUN: RUN_ID,
 		GIT_OPTIONAL_LOCKS: "0", // read-only git commands should not dirty copied or mounted metadata
 		GIT_CONFIG_COUNT: String(count + 1),
 		[`GIT_CONFIG_KEY_${count}`]: "core.excludesFile",
@@ -651,18 +693,7 @@ async function filesOpenForWriting(dir: string, forceFailure: boolean): Promise<
 	// detached or were reparented; unlike lsof +D, it doesn't walk every file in a large repository.
 	const result = await $`lsof -n -P -F an`.nothrow().quiet();
 	if (result.exitCode !== 0 || result.stderr.length > 0) return null;
-	const output = result.stdout.toString();
-
-	const files = new Set<string>();
-	let access = "";
-	for (const line of output.split("\n")) {
-		if (line.startsWith("f")) access = "";
-		if (line.startsWith("a")) access = line.slice(1);
-		if (line.startsWith(`n${dir}/`) && (access === "w" || access === "u")) {
-			files.add(path.relative(dir, line.slice(1)));
-		}
-	}
-	return [...files];
+	return parseOpenWriters(result.stdout.toString(), dir);
 }
 
 // ── Finding, describing and applying changes ──────────────────────────────────────
@@ -957,7 +988,6 @@ async function cleanupWarnings(items: PreparedChange[], failCleanup = false): Pr
 	} catch (error) {
 		const detail = error instanceof Error ? error.message : String(error);
 		const warning = `Changes reached their reported state, but transaction backup cleanup failed: ${detail}`;
-		log("cleanup warning", { warning });
 		return [warning];
 	}
 }
@@ -1079,11 +1109,5 @@ if (import.meta.main) {
 	const abort = new AbortController();
 	process.on("SIGTERM", () => abort.abort());
 	const options: RunOptions = await Bun.stdin.json();
-	RUN_ID = options.runId;
-	try {
-		console.log(JSON.stringify(await run(options, abort.signal)));
-	} catch (error) {
-		log("failed", { error: String(error) });
-		throw error;
-	}
+	console.log(JSON.stringify(await run(options, abort.signal)));
 }

package/skills/shorthand/advanced-refactors.md

@@ -159,10 +159,15 @@ belong to `code`, not necessarily ordinary shell calls. `node:fs` and ordinary B
 
 Programs run in an isolated repository workspace. Use relative paths: the live checkout's absolute
 path is inaccessible on macOS. On both platforms, host paths outside the workspace are read-only
-(including external symlink targets), apart from run-history logging. `$TMPDIR` is private to the run.
+(including external symlink targets). `$TMPDIR` is private to the run.
 Writes to `.git` are blocked.
 
 The default timeout is two seconds; request more for longer transformations.
-By default a failed program applies nothing. `rollback: "file"` can retain closed files after a
-timeout if writer inspection succeeds; exceptions, crashes or inspection failures apply nothing.
-Use that mode only when each retained file stands on its own.
+By default, rollback happens per file: files involved in failed or interrupted edits are discarded,
+while the others are retained, including after exceptions. Unattributed failures
+(such as failed checks) preserve completed edits and report the failure. A failed file loses all
+its edits from this run, even if the error is caught. Multi-file operations such as moves and a
+single Grit invocation share one outcome. Arbitrary shell failures cannot identify failed closed
+files. Open writers are inspected before failure exits and timeout termination; inspection failures
+or crashes that bypass exit handling retain nothing. Cancellation still discards everything.
+Use `rollback: "all"` when the whole change must be atomic.

package/history.ts

@@ -1,252 +0,0 @@
-import {
-	chmodSync,
-	closeSync,
-	constants,
-	fchmodSync,
-	fstatSync,
-	lstatSync,
-	mkdirSync,
-	openSync,
-	readSync,
-	renameSync,
-	rmSync,
-	type Stats,
-	writeSync,
-} from "node:fs";
-import { homedir } from "node:os";
-import * as path from "node:path";
-
-export const RUN_HISTORY_FILE = path.join(homedir(), ".cache", "pi-shorthand", "runs.jsonl");
-export const RUN_HISTORY_LOCK_DIR = `${RUN_HISTORY_FILE}.locks`;
-export const RUN_HISTORY_MAX_BYTES = 1024 * 1024;
-export const RUN_HISTORY_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
-const HISTORY_EVENTS = new Set([
-	"started",
-	"overlay opened",
-	"program started",
-	"program exited",
-	"finished",
-	"command",
-	"helper",
-	"cleanup warning",
-	"failed",
-]);
-
-interface HistoryOptions {
-	maxBytes?: number;
-	maxAgeMs?: number;
-	now?: number;
-	env?: NodeJS.ProcessEnv;
-}
-
-export function historyEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
-	return !["0", "false", "off"].includes((env.PI_SHORTHAND_HISTORY ?? "").toLowerCase());
-}
-
-/** Persist a bounded event containing only the allowlisted, non-source fields used for diagnostics. */
-export function appendRunHistory(
-	event: string,
-	details: Record<string, unknown> = {},
-	file = RUN_HISTORY_FILE,
-	options: HistoryOptions = {},
-) {
-	if (!historyEnabled(options.env)) return;
-	if (!HISTORY_EVENTS.has(event)) return;
-	const record = JSON.stringify({
-		time: new Date(options.now ?? Date.now()).toISOString(),
-		event,
-		...safeDetails(event, details),
-	});
-	const env = options.env ?? process.env;
-	const sandboxed = env.PI_SHORTHAND_HISTORY_SANDBOX === "1";
-	withHistoryLock(file, sandboxed, () => appendBounded(file, `${record}\n`, options, sandboxed));
-}
-
-const lockWait = new Int32Array(new SharedArrayBuffer(4));
-
-function withHistoryLock(file: string, sandboxed: boolean, run: () => void) {
-	const directory = `${file}.locks`;
-	if (!sandboxed) mkdirSync(directory, { recursive: true, mode: 0o700 });
-	const directoryStats = lstatSync(directory);
-	if (
-		!directoryStats.isDirectory() ||
-		directoryStats.isSymbolicLink() ||
-		(process.getuid && directoryStats.uid !== process.getuid())
-	) {
-		throw new Error(`Unsafe run history lock directory: ${directory}`);
-	}
-	if (!sandboxed) chmodSync(directory, 0o700);
-
-	const lock = path.join(directory, "append");
-	let acquired = false;
-	for (let attempt = 0; attempt < 200; attempt++) {
-		try {
-			mkdirSync(lock, { mode: 0o700 });
-			acquired = true;
-			break;
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-			const stats = lstatSync(lock, { throwIfNoEntry: false });
-			if (stats && Date.now() - stats.mtimeMs > 10_000) {
-				rmSync(lock, { recursive: true, force: true });
-				continue;
-			}
-			Atomics.wait(lockWait, 0, 0, 5);
-		}
-	}
-	if (!acquired) return; // history must never hold up the transaction itself
-	try {
-		run();
-	} finally {
-		rmSync(lock, { recursive: true, force: true });
-	}
-}
-
-function safeDetails(event: string, details: Record<string, unknown>): Record<string, unknown> {
-	const number = (key: string) => (typeof details[key] === "number" ? details[key] : undefined);
-	const boolean = (key: string) => (typeof details[key] === "boolean" ? details[key] : undefined);
-	const text = (key: string, allowed: readonly string[]) =>
-		typeof details[key] === "string" && allowed.includes(details[key]) ? details[key] : undefined;
-
-	switch (event) {
-		case "started":
-			return compact({
-				run: safeIdentifier(details.run),
-				timeoutMs: number("timeoutMs"),
-				rollback: text("rollback", ["all", "file"]),
-			});
-		case "program started":
-			return compact({ run: safeIdentifier(details.run), timeoutMs: number("timeoutMs") });
-		case "program exited":
-			return compact({
-				run: safeIdentifier(details.run),
-				exitCode: details.exitCode === null ? null : number("exitCode"),
-				timedOut: boolean("timedOut"),
-				aborted: boolean("aborted"),
-				stillRunning: number("stillRunning"),
-			});
-		case "finished":
-			return compact({
-				run: safeIdentifier(details.run),
-				changed: number("changed"),
-				applied: number("applied"),
-				conflicts: number("conflicts"),
-			});
-		case "command":
-			return compact({ run: safeIdentifier(details.run), command: safeCommand(details.command) });
-		case "helper":
-			return compact({
-				run: safeIdentifier(details.run),
-				helper: text("helper", [
-					"glob",
-					"grep",
-					"sg.find",
-					"sg.one",
-					"sg.file",
-					"sg.insert",
-					"sg.move",
-					"sg.remove",
-					"sg.rewrite",
-					"grit",
-				]),
-				ms: number("ms"),
-				results: number("results"),
-			});
-		default:
-			return compact({ run: safeIdentifier(details.run) });
-	}
-}
-
-function compact(value: Record<string, unknown>): Record<string, unknown> {
-	return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
-}
-
-function safeIdentifier(value: unknown): string | undefined {
-	return typeof value === "string" && /^[a-zA-Z0-9_-]{1,64}$/.test(value) ? value : undefined;
-}
-
-function safeCommand(value: unknown): string | undefined {
-	if (typeof value !== "string") return undefined;
-	const command = path.basename(value);
-	return /^[a-zA-Z0-9_.-]{1,64}$/.test(command) ? command : undefined;
-}
-
-function appendBounded(file: string, line: string, options: HistoryOptions, sandboxed: boolean) {
-	const maxBytes = options.maxBytes ?? RUN_HISTORY_MAX_BYTES;
-	const maxAgeMs = options.maxAgeMs ?? RUN_HISTORY_MAX_AGE_MS;
-	const now = options.now ?? Date.now();
-	const directory = path.dirname(file);
-	const rotated = `${file}.1`;
-	if (!sandboxed) {
-		mkdirSync(directory, { recursive: true, mode: 0o700 });
-		const directoryStats = lstatSync(directory);
-		if (
-			!directoryStats.isDirectory() ||
-			directoryStats.isSymbolicLink() ||
-			(process.getuid && directoryStats.uid !== process.getuid())
-		) {
-			throw new Error(`Unsafe run history directory: ${directory}`);
-		}
-		chmodSync(directory, 0o700);
-	}
-
-	let existing: Stats | undefined;
-	try {
-		existing = lstatSync(file) as Stats;
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-	}
-	if (existing?.isSymbolicLink() || (existing && !existing.isFile()))
-		throw new Error(`Unsafe run history file: ${file}`);
-	if (!sandboxed) {
-		const rotatedStats = lstatSync(rotated, { throwIfNoEntry: false });
-		if (rotatedStats?.isSymbolicLink() || (rotatedStats && !rotatedStats.isFile())) {
-			rmSync(rotated, { recursive: true, force: true });
-		} else if (rotatedStats && now - cohortStartedAt(rotated, rotatedStats) > maxAgeMs) {
-			rmSync(rotated, { force: true });
-		}
-	}
-	if (!sandboxed && existing && now - cohortStartedAt(file, existing) > maxAgeMs) {
-		rmSync(file, { force: true });
-		existing = undefined;
-	} else if (!sandboxed && existing && existing.size + Buffer.byteLength(line) > maxBytes) {
-		rmSync(rotated, { force: true });
-		renameSync(file, rotated);
-		existing = undefined;
-	}
-
-	const descriptor = openSync(
-		file,
-		constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW,
-		0o600,
-	);
-	try {
-		const stats = fstatSync(descriptor);
-		if (!stats.isFile() || (process.getuid && stats.uid !== process.getuid()))
-			throw new Error(`Unsafe run history file: ${file}`);
-		if (sandboxed) {
-			if ((stats.mode & 0o077) !== 0) throw new Error(`Unsafe run history permissions: ${file}`);
-		} else {
-			fchmodSync(descriptor, 0o600);
-		}
-		if (stats.size + Buffer.byteLength(line) <= maxBytes) writeSync(descriptor, line);
-	} finally {
-		closeSync(descriptor);
-	}
-}
-
-/** The first record starts a cohort; later appends cannot extend that cohort's retention deadline. */
-function cohortStartedAt(file: string, stats: Stats): number {
-	const descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
-	try {
-		const buffer = Buffer.alloc(2048);
-		const length = readSync(descriptor, buffer, 0, buffer.length, 0);
-		const firstLine = buffer.subarray(0, length).toString("utf8").split("\n", 1)[0];
-		const time = Date.parse(JSON.parse(firstLine).time);
-		return Number.isFinite(time) ? time : stats.birthtimeMs;
-	} catch {
-		return stats.birthtimeMs;
-	} finally {
-		closeSync(descriptor);
-	}
-}