pi-shorthand 0.1.0 → 0.2.0

package/README.md

@@ -1,11 +1,13 @@
 # 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 [Pi](https://github.com/earendil-works/pi) tool for token-efficient writes. The model writes a whole
 change as one small Bun program, in shorthand, instead of calling `read`, `edit` and `bash` over
 and over: fewer tokens, and fewer round trips.
 
-The program sees your repo as normal, but its writes are held back. If it succeeds, they're applied
-and the model gets the diff. If it fails, nothing changes.
+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.
 
 ## Install
 
@@ -15,8 +17,10 @@ pi install npm:pi-shorthand
 
 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) (macOS:
+(Linux) or [AgentFS](https://github.com/tursodatabase/agentfs) and `clang` (macOS:
 `curl -fsSL https://agentfs.ai/install | bash`).
 
 ## What a program can use
@@ -29,23 +33,37 @@ 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");
 ```
 
 ## Options
 
-- `rollback`: `"all"` (default) applies nothing if the program fails. `"file"` keeps the files it
-  finished writing.
+- `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.
-- On macOS your repo is briefly swapped for the overlay while a program runs (about 150 ms), so your
-  editor may notice. On Linux nothing outside the program sees it (about 15 ms).
+- 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.
+- 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`.
-- To watch runs as they happen, including each command a program starts: `tail -f ~/.cache/pi-shorthand/runs.jsonl`.
+- 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
 

package/display.ts

@@ -7,9 +7,14 @@
  * on failure the output, then what would have changed; for an exploration, just the output.
  */
 
-import { keyHint, renderDiff, type Theme } from "@earendil-works/pi-coding-agent";
+import { getLanguageFromPath, highlightCode, keyHint, renderDiff, type Theme } from "@earendil-works/pi-coding-agent";
 import type { FileChange, RunResult } from "./runner.ts";
 
+type ToolBackground = "toolSuccessBg" | "toolErrorBg";
+
+const ANSI_CUBE_VALUES = [0, 95, 135, 175, 215, 255];
+const ANSI_GRAY_VALUES = Array.from({ length: 24 }, (_, index) => 8 + index * 10);
+
 const OUTPUT_PREVIEW_LINES = 5; // like Pi's bash tool
 const INLINE_DIFF_LINES = 40; // a longer diff collapses to a list of its files…
 const LISTED_FILES = 8; // …showing this many, then "and N more files"
@@ -21,6 +26,19 @@ export function callLine(args: { title?: string; timeout?: number; rollback?: st
 	return `${theme.fg("toolTitle", theme.bold("code"))} ${args.title ?? ""}${suffix ? theme.fg("muted", ` (${suffix})`) : ""}`;
 }
 
+/** Text to show when a completed tool result has no structured RunResult details. */
+export function unstructuredResultText(content: readonly unknown[]): string {
+	const text = content
+		.flatMap((block) =>
+			typeof block === "object" && block !== null && "type" in block && block.type === "text" && "text" in block
+				? [String(block.text)]
+				: [],
+		)
+		.join("\n")
+		.trim();
+	return text || "Code failed without result details";
+}
+
 /** Lines that belong to the verdict line above them. */
 function indent(line: string): string {
 	return `  ${line}`;
@@ -43,21 +61,28 @@ export function resultLines(run: RunResult, expanded: boolean, theme: Theme): st
 	const error = run.exitCode !== 0 && !run.timedOut ? errorMessage(run.output) : undefined;
 	if (error) lines.push(indent(theme.fg("error", error)));
 	if (error && run.errorLine) lines.push(indent(theme.fg("muted", shorten(run.errorLine, 88))));
+	for (const file of run.conflicts) lines.push(indent(theme.fg("error", `changed while running: ${file}`)));
 	// A command still running is what it was stuck on; otherwise the last step it logged is a clue.
 	for (const command of run.stillRunning) lines.push(indent(theme.fg("warning", `stuck on $ ${command}`)));
 	if (run.timedOut && run.stillRunning.length === 0 && run.lastStep) {
 		lines.push(indent(theme.fg("warning", `last step: ${run.lastStep}`)));
 	}
 	for (const file of run.rolledBack) {
-		lines.push(indent(theme.fg("warning", `rolled back ${file}: half-written when the program was killed`)));
+		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";
+		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[][] = [];
-	if (applied.length > 0) sections.push(diffLines(applied, expanded, theme));
+	const background: ToolBackground = run.exitCode === 0 && run.conflicts.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));
+	if (notApplied.length > 0) sections.push(notAppliedLines(notApplied, expanded, theme, background));
 	for (const section of sections) lines.push("", ...section);
 	return lines;
 }
@@ -69,6 +94,15 @@ function verdict(run: RunResult, applied: FileChange[], theme: Theme): string {
 	const failure = run.timedOut ? `Timed out after ${run.timeoutMs / 1000}s` : "Failed";
 	const exit = run.timedOut ? "" : muted(` · exit ${run.exitCode}`);
 
+	if (run.conflicts.length > 0) {
+		const program = run.timedOut
+			? ` · timed out after ${run.timeoutMs / 1000}s`
+			: run.exitCode
+				? ` · exit ${run.exitCode}`
+				: "";
+		const application = applied.length === 0 ? "nothing applied" : `${fileCount(applied)} applied`;
+		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) {
 		return theme.fg("success", `✓ Applied ${fileCount(applied)}`) + ` · ${stats(applied, theme)}` + took;
@@ -104,8 +138,8 @@ function outputLines(output: string, expanded: boolean, labelled: boolean, theme
 }
 
 /** Each file's diff under its name, in Pi's own diff style. A long diff collapses to a list of files. */
-function diffLines(changes: FileChange[], expanded: boolean, theme: Theme): string[] {
-	const files = changes.map((change) => [fileLine(change, theme), ...renderDiff(toPiDiff(change.patch)).split("\n")]);
+function diffLines(changes: FileChange[], expanded: boolean, theme: Theme, background: ToolBackground): string[] {
+	const files = changes.map((change) => [fileLine(change, theme), ...renderFileDiff(change, theme, background)]);
 	const total = files.reduce((sum, file) => sum + file.length, 0);
 	if (!expanded && total > INLINE_DIFF_LINES) {
 		return [...fileList(changes, theme), theme.fg("muted", `(${keyHint("app.tools.expand", "to see the diff")})`)];
@@ -117,9 +151,152 @@ function diffLines(changes: FileChange[], expanded: boolean, theme: Theme): stri
 	return [...lines.slice(0, EXPANDED_DIFF_LINES), theme.fg("muted", `… ${more} more lines of diff`)];
 }
 
-function notAppliedLines(changes: FileChange[], expanded: boolean, theme: Theme): string[] {
+function renderFileDiff(change: FileChange, theme: Theme, background: ToolBackground): string[] {
+	const diff = toPiDiff(change.patch);
+	const language = getLanguageFromPath(change.path);
+	if (!language || diff === " binary file changed") return renderDiff(diff).split("\n");
+
+	const rendered: string[] = [];
+	let hunk: string[] = [];
+	const flush = () => {
+		if (hunk.length > 0) rendered.push(...renderSyntaxHunk(hunk, language, theme, background));
+		hunk = [];
+	};
+	for (const line of diff.split("\n")) {
+		if (/^\s+\.\.\.$/.test(line)) {
+			flush();
+			rendered.push(theme.fg("toolDiffContext", line));
+		} else {
+			hunk.push(line);
+		}
+	}
+	flush();
+	return rendered;
+}
+
+function renderSyntaxHunk(lines: string[], language: string, theme: Theme, background: ToolBackground): string[] {
+	const parsed = lines.map((line) => {
+		const match = line.match(/^([+\- ])(\s*\d*) (.*)$/);
+		return match ? { prefix: match[1], number: match[2], code: match[3] } : undefined;
+	});
+	const oldLines = parsed.flatMap((line) => (line && line.prefix !== "+" ? [line.code] : []));
+	const newLines = parsed.flatMap((line) => (line && line.prefix !== "-" ? [line.code] : []));
+	const oldHighlighted = highlightCode(oldLines.join("\n"), language);
+	const newHighlighted = highlightCode(newLines.join("\n"), language);
+	let oldIndex = 0;
+	let newIndex = 0;
+
+	return parsed.map((line, index) => {
+		if (!line) return theme.fg("toolDiffContext", lines[index]);
+		if (line.prefix === "-") {
+			const content = theme.fg("toolDiffRemoved", `-${line.number} `) + oldHighlighted[oldIndex++];
+			return tintedDiffLine(content, "toolDiffRemoved", background, theme);
+		}
+		if (line.prefix === "+") {
+			const content = theme.fg("toolDiffAdded", `+${line.number} `) + newHighlighted[newIndex++];
+			return tintedDiffLine(content, "toolDiffAdded", background, theme);
+		}
+		oldIndex++;
+		return theme.fg("toolDiffContext", ` ${line.number} `) + newHighlighted[newIndex++];
+	});
+}
+
+function tintedDiffLine(
+	line: string,
+	changeColor: "toolDiffAdded" | "toolDiffRemoved",
+	baseBackground: ToolBackground,
+	theme: Theme,
+): string {
+	const base = ansiRgb(theme.getBgAnsi(baseBackground));
+	const change = ansiRgb(theme.getFgAnsi(changeColor));
+	if (!base || !change) return line;
+	const [red, green, blue] = base.map((channel, index) => Math.round(channel * 0.86 + change[index] * 0.14));
+	const background =
+		theme.getColorMode() === "truecolor"
+			? `\x1b[48;2;${red};${green};${blue}m`
+			: `\x1b[48;5;${ansi256(red, green, blue)}m`;
+	return `${background}${line}${theme.getBgAnsi(baseBackground)}`;
+}
+
+function ansiRgb(code: string): [number, number, number] | undefined {
+	const truecolor = code.match(/\[(?:38|48);2;(\d+);(\d+);(\d+)m/);
+	if (truecolor) return [Number(truecolor[1]), Number(truecolor[2]), Number(truecolor[3])];
+	const indexed = code.match(/\[(?:38|48);5;(\d+)m/);
+	return indexed ? rgbFromAnsi256(Number(indexed[1])) : undefined;
+}
+
+function rgbFromAnsi256(index: number): [number, number, number] | undefined {
+	if (index < 0 || index > 255) return undefined;
+	if (index < 16) {
+		const palette = [
+			[0, 0, 0],
+			[128, 0, 0],
+			[0, 128, 0],
+			[128, 128, 0],
+			[0, 0, 128],
+			[128, 0, 128],
+			[0, 128, 128],
+			[192, 192, 192],
+			[128, 128, 128],
+			[255, 0, 0],
+			[0, 255, 0],
+			[255, 255, 0],
+			[0, 0, 255],
+			[255, 0, 255],
+			[0, 255, 255],
+			[255, 255, 255],
+		] as const;
+		return [...palette[index]];
+	}
+	if (index >= 232) {
+		const gray = 8 + (index - 232) * 10;
+		return [gray, gray, gray];
+	}
+	const cube = index - 16;
+	return [
+		ansiCubeChannel(Math.floor(cube / 36)),
+		ansiCubeChannel(Math.floor((cube % 36) / 6)),
+		ansiCubeChannel(cube % 6),
+	];
+}
+
+function ansiCubeChannel(value: number): number {
+	return value === 0 ? 0 : 55 + value * 40;
+}
+
+function ansi256(red: number, green: number, blue: number): number {
+	const [redIndex, greenIndex, blueIndex] = [red, green, blue].map((channel) =>
+		closestIndex(channel, ANSI_CUBE_VALUES),
+	);
+	const cube = [ANSI_CUBE_VALUES[redIndex], ANSI_CUBE_VALUES[greenIndex], ANSI_CUBE_VALUES[blueIndex]];
+	const cubeIndex = 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
+	const cubeDistance = colorDistance([red, green, blue], cube);
+
+	const luminance = Math.round(0.299 * red + 0.587 * green + 0.114 * blue);
+	const grayOffset = closestIndex(luminance, ANSI_GRAY_VALUES);
+	const gray = ANSI_GRAY_VALUES[grayOffset];
+	const grayDistance = colorDistance([red, green, blue], [gray, gray, gray]);
+	const spread = Math.max(red, green, blue) - Math.min(red, green, blue);
+	return spread < 10 && grayDistance < cubeDistance ? 232 + grayOffset : cubeIndex;
+}
+
+function closestIndex(value: number, choices: number[]): number {
+	let closest = 0;
+	for (let index = 1; index < choices.length; index++) {
+		if (Math.abs(value - choices[index]) < Math.abs(value - choices[closest])) closest = index;
+	}
+	return closest;
+}
+
+function colorDistance(first: number[], second: number[]): number {
+	return (
+		(first[0] - second[0]) ** 2 * 0.299 + (first[1] - second[1]) ** 2 * 0.587 + (first[2] - second[2]) ** 2 * 0.114
+	);
+}
+
+function notAppliedLines(changes: FileChange[], expanded: boolean, theme: Theme, background: ToolBackground): string[] {
 	const heading = theme.fg("muted", `Would have changed ${fileCount(changes)} · `) + stats(changes, theme);
-	if (expanded) return [heading, "", ...diffLines(changes, true, theme)];
+	if (expanded) return [heading, "", ...diffLines(changes, true, theme, background)];
 	return [heading + theme.fg("muted", ` (${keyHint("app.tools.expand", "to see the diff")})`)];
 }
 
@@ -133,7 +310,19 @@ function fileList(changes: FileChange[], theme: Theme): string[] {
 /** e.g. "src/a.ts +3 −1", or "src/new.ts (new) +12 −0" */
 function fileLine(change: FileChange, theme: Theme): string {
 	const kind = change.kind === "modified" ? "" : theme.fg("muted", change.kind === "added" ? " (new)" : " (deleted)");
-	return `${theme.fg("accent", change.path)}${kind} ${stats([change], theme)}`;
+	const metadata = fileMetadataSummary(change);
+	return `${theme.fg("accent", change.path)}${kind}${metadata ? theme.fg("muted", ` (${metadata})`) : ""} ${stats([change], theme)}`;
+}
+
+export function fileMetadataSummary(change: FileChange): string {
+	if (change.beforeType && change.afterType && change.beforeType !== change.afterType) {
+		return `${change.beforeType} → ${change.afterType}`;
+	}
+	if (change.afterType === "symlink" && change.beforeType !== "symlink") return "symlink";
+	if (change.beforeMode !== undefined && change.afterMode !== undefined && change.beforeMode !== change.afterMode) {
+		return `${change.beforeMode.toString(8)} → ${change.afterMode.toString(8)}`;
+	}
+	return "";
 }
 
 /** "+6 −2", in the diff colours. */

package/history.ts

@@ -0,0 +1,252 @@
+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);
+	}
+}