pi-shorthand 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seb Insua
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# pi-shorthand
+
+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.
+
+## Install
+
+```sh
+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`.
+
+You also need Bun, git, and either [bubblewrap](https://github.com/containers/bubblewrap) 0.9+
+(Linux) or [AgentFS](https://github.com/tursodatabase/agentfs) (macOS:
+`curl -fsSL https://agentfs.ai/install | bash`).
+
+## What a program can use
+
+Anything in Bun or Node, plus these globals (no imports):
+
+```ts
+await $`bun test src/api.test.ts`; // 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.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.
+- `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).
+- 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`.
+
+## Developing
+
+`npm run check` type-checks (TypeScript 7), lints (oxlint) and checks formatting (oxfmt). A pre-commit
+hook runs it; `npm run format` fixes formatting.
+
+`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.
+
+`bun e2e/run.ts --repo <path or git URL> --task "…" --setup baseline|code|read-code --check "…"` runs Pi
+with a real model on a fresh copy of a repo and summarises what it did (time, turns, tool calls,
+tokens, whether the check passed).

package/display.ts

@@ -0,0 +1,205 @@
+/**
+ * How a code call looks in Pi. (The model gets a separate plain-text version: see textForModel.)
+ *
+ * A verdict line first, whose colour carries the outcome. Lines indented under it belong to it: what
+ * went wrong, or what to watch out for. A blank line starts a new section. The sections come in the
+ * order that matters for the outcome: on success the diff (the point of the tool), then the output;
+ * 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 type { FileChange, RunResult } from "./runner.ts";
+
+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"
+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 suffix = settings.filter(Boolean).join(", ");
+	return `${theme.fg("toolTitle", theme.bold("code"))} ${args.title ?? ""}${suffix ? theme.fg("muted", ` (${suffix})`) : ""}`;
+}
+
+/** Lines that belong to the verdict line above them. */
+function indent(line: string): string {
+	return `  ${line}`;
+}
+
+export function resultLines(run: RunResult, expanded: boolean, theme: Theme): string[] {
+	const applied = run.changes.filter((change) => run.applied.includes(change.path));
+	const notApplied = run.changes.filter(
+		(change) => !run.applied.includes(change.path) && !run.rolledBack.includes(change.path),
+	);
+	const outputLinesAll = run.output.split("\n");
+	const printedWarnings = outputLinesAll.filter((line) => line.startsWith("warning: ")).map((line) => line.slice(9));
+	const output = outputLinesAll
+		.filter((line) => !line.startsWith("warning: "))
+		.join("\n")
+		.trim();
+
+	// The verdict, and what belongs to it.
+	const lines = [verdict(run, applied, theme)];
+	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))));
+	// 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`)));
+	}
+	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));
+	if (output && (expanded || !error)) sections.push(outputLines(output, expanded, run.changes.length > 0, theme));
+	if (notApplied.length > 0) sections.push(notAppliedLines(notApplied, expanded, theme));
+	for (const section of sections) lines.push("", ...section);
+	return lines;
+}
+
+/** e.g. "✓ Applied 3 files · +6 −6 · 0.6s" or "✕ Failed · rolled back all changes · exit 1 · 0.2s" */
+function verdict(run: RunResult, applied: FileChange[], theme: Theme): string {
+	const muted = (text: string) => theme.fg("muted", text);
+	const took = muted(` · ${(run.durationMs / 1000).toFixed(1)}s`);
+	const failure = run.timedOut ? `Timed out after ${run.timeoutMs / 1000}s` : "Failed";
+	const exit = run.timedOut ? "" : muted(` · exit ${run.exitCode}`);
+
+	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;
+	}
+	if (applied.length > 0) {
+		const rolledBack = run.rolledBack.length > 0 ? `, rolled back ${run.rolledBack.length}` : "";
+		const kept = theme.fg("warning", `⚠ ${failure} · kept ${fileCount(applied)}${rolledBack}`);
+		return kept + ` · ${stats(applied, theme)}` + exit + took;
+	}
+	const undone =
+		run.changes.length === 0 ? "no changes" : run.rollback === "all" ? "rolled back all changes" : "nothing to keep";
+	return theme.fg("error", `✕ ${failure} · ${undone}`) + exit + took;
+}
+
+/** The error Bun printed, e.g. "expected 1 match, found 3" (or "TypeError: …"). */
+function errorMessage(output: string): string | undefined {
+	const line = output.split("\n").findLast((candidate) => /^(error|\w*Error): /.test(candidate));
+	return line?.replace(/^error: /, "");
+}
+
+/** The last few lines, like Pi's bash tool; all of it when expanded. Labelled when not alone. */
+function outputLines(output: string, expanded: boolean, labelled: boolean, theme: Theme): string[] {
+	const lines = output.split("\n").map((line) => theme.fg("toolOutput", line));
+	const label = labelled ? [theme.fg("muted", "Program output")] : [];
+	if (expanded || lines.length <= OUTPUT_PREVIEW_LINES) return [...label, ...lines];
+
+	const earlier = lines.length - OUTPUT_PREVIEW_LINES;
+	const hint =
+		theme.fg("muted", `… ${earlier} earlier lines (`) +
+		keyHint("app.tools.expand", "to expand") +
+		theme.fg("muted", ")");
+	return [...label, hint, ...lines.slice(-OUTPUT_PREVIEW_LINES)];
+}
+
+/** 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")]);
+	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")})`)];
+	}
+
+	const lines = files.flatMap((file, index) => (index === 0 ? file : ["", ...file]));
+	if (lines.length <= EXPANDED_DIFF_LINES) return lines;
+	const more = lines.length - EXPANDED_DIFF_LINES;
+	return [...lines.slice(0, EXPANDED_DIFF_LINES), theme.fg("muted", `… ${more} more lines of diff`)];
+}
+
+function notAppliedLines(changes: FileChange[], expanded: boolean, theme: Theme): string[] {
+	const heading = theme.fg("muted", `Would have changed ${fileCount(changes)} · `) + stats(changes, theme);
+	if (expanded) return [heading, "", ...diffLines(changes, true, theme)];
+	return [heading + theme.fg("muted", ` (${keyHint("app.tools.expand", "to see the diff")})`)];
+}
+
+/** The first few files, then how many more. */
+function fileList(changes: FileChange[], theme: Theme): string[] {
+	const listed = changes.slice(0, LISTED_FILES).map((change) => fileLine(change, theme));
+	const more = changes.length - LISTED_FILES;
+	return more > 0 ? [...listed, theme.fg("muted", `… and ${more} more files`)] : listed;
+}
+
+/** 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)}`;
+}
+
+/** "+6 −2", in the diff colours. */
+function stats(changes: FileChange[], theme: Theme): string {
+	const counts = changes.map((change) => countLines(change.patch));
+	const additions = counts.reduce((sum, count) => sum + count.additions, 0);
+	const deletions = counts.reduce((sum, count) => sum + count.deletions, 0);
+	return `${theme.fg("toolDiffAdded", `+${additions}`)} ${theme.fg("toolDiffRemoved", `−${deletions}`)}`;
+}
+
+/** Cut to fit on one line, since a wrapped line loses its indentation. The full text is in the output. */
+function shorten(text: string, length: number): string {
+	return text.length <= length ? text : `${text.slice(0, length - 1)}…`;
+}
+
+function fileCount(changes: FileChange[]): string {
+	return changes.length === 1 ? "1 file" : `${changes.length} files`;
+}
+
+/**
+ * Converts a git-style patch to the format Pi's renderDiff reads: "+12 added", "-12 removed",
+ * " 12 context", and "     ..." between hunks. Removed and context lines use old line numbers.
+ */
+function toPiDiff(patch: string): string {
+	if (patch.includes("\nBinary file changed")) return " binary file changed";
+	const lastLines = [...patch.matchAll(/^@@ -(\d+),(\d+) \+(\d+),(\d+) @@/gm)].flatMap((hunk) => [
+		Number(hunk[1]) + Number(hunk[2]),
+		Number(hunk[3]) + Number(hunk[4]),
+	]);
+	const width = String(Math.max(1, ...lastLines)).length;
+	const number = (n: number | string) => String(n).padStart(width, " ");
+
+	const out: string[] = [];
+	let inHunks = false; // skips the headers before the first hunk
+	let oldLine = 0;
+	let newLine = 0;
+	for (const line of patch.split("\n")) {
+		const hunk = line.match(/^@@ -(\d+),\d+ \+(\d+),\d+ @@/);
+		if (hunk) {
+			if (inHunks) out.push(` ${number("")} ...`);
+			inHunks = true;
+			oldLine = Number(hunk[1]);
+			newLine = Number(hunk[2]);
+		} else if (!inHunks) {
+			continue;
+		} else if (line.startsWith("+")) {
+			out.push(`+${number(newLine++)} ${line.slice(1)}`);
+		} else if (line.startsWith("-")) {
+			out.push(`-${number(oldLine++)} ${line.slice(1)}`);
+		} else if (line.startsWith(" ")) {
+			out.push(` ${number(oldLine++)} ${line.slice(1)}`);
+			newLine++;
+		}
+	}
+	return out.join("\n");
+}
+
+/** Added and removed lines in a patch. Only lines after the first "@@" count, not the ---/+++ headers. */
+export function countLines(patch: string) {
+	let additions = 0;
+	let deletions = 0;
+	let inHunks = false;
+	for (const line of patch.split("\n")) {
+		if (line.startsWith("@@")) inHunks = true;
+		else if (inHunks && line.startsWith("+")) additions++;
+		else if (inHunks && line.startsWith("-")) deletions++;
+	}
+	return { additions, deletions };
+}

package/index.ts

@@ -0,0 +1,261 @@
+/**
+ * The `code` tool: the model writes one Bun program that makes a multi-step change to the repository.
+ * Its writes go to a copy-on-write overlay; if it succeeds, they're applied and the diff is returned.
+ */
+
+import { spawn } from "node:child_process";
+import { closeSync, openSync, readSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import * as path from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type ExtensionAPI, truncateHead, truncateTail } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { callLine, countLines, resultLines } from "./display.ts";
+import type { FileChange, RunOptions, RunResult } from "./runner.ts";
+
+// Where runner.ts logs each step. (Not imported from runner.ts, which only runs under Bun.)
+const LOG_FILE = path.join(homedir(), ".cache", "pi-shorthand", "runs.jsonl");
+
+// Runs typically take well under a second. Programs that run tests or builds pass a longer timeout.
+const DEFAULT_TIMEOUT_SECONDS = 2;
+
+const DESCRIPTION = `Make a repository change with one TypeScript program, run by Bun as a transaction: its writes are applied only if it exits successfully, and you get the diff. Put the checks that prove the change worked (type-check, targeted tests, no leftover matches) in the same program, and throw if they fail. Work out what to change inside the program (e.g. with grep) rather than copying lists from earlier output.
+
+Use it when a change takes several deterministic steps (reads, searches, multi-file edits, structural rewrites, checks) and you already know what to do with each intermediate result. If seeing an intermediate result could change your plan, look first with a normal tool call.
+
+The program runs in the working directory, and sees the repository at its usual path. Top-level await works, and so do ordinary Bun and Node APIs. These globals are synchronous, and see the files git sees (not node_modules or ignored files):
+- glob(pattern, dir?) → string[]
+- grep(stringOrRegExp, paths?) → {file, line, text}[]. A string matches literally.
+- sg.find(pattern, files?) → {file, line, text, vars}[]. ast-grep pattern: $X is one node, $$$X is zero or more. files is a file, directory, glob or a list of them (JS/TS).
+- sg.rewrite(pattern, templateOrFunction, files?) → number rewritten. A template can use $X and $$$X; a function gets the match (its captures are on it: m.X) and returns the new text, or null to leave it.
+- sg also has ast-grep's own API (sg.parse, sg.Lang, sg.findInFiles, …), and import "@ast-grep/napi" works too.
+- grit(gritqlPattern, paths?, {lang?, dryRun?}) → {file, matches}[], e.g. grit("\`a($x)\` => \`b($x)\`", "src")
+Bun's shell $ needs await: await $\`bun test src/foo.test.ts\`. You can also run the ast-grep, grit and git CLIs with it. For how to write these programs, see the shorthand skill.
+
+Throw or exit non-zero to fail. rollback decides what a failure undoes:
+- "all" (default): nothing is applied; you get the error and the candidate diff.
+- "file": every file the program finished writing is applied; files left half-written (e.g. by a timeout) are rolled back and listed.
+The default timeout is 2 seconds; pass a longer timeout when the program runs tests or builds. Only files git sees (tracked, or untracked and not ignored) are diffed and applied; writes to .git are blocked. Print what you need to know (counts, assertions), not whole files.`;
+
+export default function (pi: ExtensionAPI) {
+	// A failed run is an error, both for the model and for how Pi shows it. (execute() returns its details
+	// 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) return { isError: true };
+	});
+
+	pi.registerTool({
+		name: "code",
+		label: "Code",
+		description: DESCRIPTION,
+		promptSnippet:
+			"Make a change with one Bun program, run as a transaction: its edits are kept only if it exits 0, so put your checks inside it",
+		promptGuidelines: [
+			"Use code when several related reads, searches, edits or checks can be done without looking at intermediate results: put that logic in one program rather than many read/edit/bash calls.",
+			"Don't use code to explore when you need to see results before deciding what to do.",
+		],
+		parameters: Type.Object({
+			title: Type.String({ description: "A few words describing the change, shown to the user" }),
+			program: Type.String({ description: "TypeScript program run with Bun (top-level await allowed)" }),
+			rollback: Type.Optional(
+				StringEnum(["all", "file"] as const, {
+					description:
+						'On failure: "all" (default) applies nothing; "file" applies finished files and rolls back half-written ones',
+				}),
+			),
+			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);
+			const startedAt = Date.now();
+			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 },
+				});
+			}, 500);
+
+			const result = await runWithBun(
+				{
+					runId,
+					cwd: ctx.cwd,
+					program: params.program,
+					timeoutMs: (params.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
+					rollback: params.rollback ?? "all",
+				},
+				signal,
+			).finally(() => clearInterval(progress));
+			return {
+				content: [{ type: "text", text: textForModel(result, toolCallId) }],
+				details: result,
+			};
+		},
+
+		renderCall(args, theme) {
+			return new Text(callLine(args, theme), 0, 0);
+		},
+
+		renderResult(result, { expanded, isPartial }, theme) {
+			if (isPartial) {
+				const progress = (result.details as { progress?: string } | undefined)?.progress;
+				return new Text(theme.fg("muted", progress ? `running… ${progress}` : "running…"), 0, 0);
+			}
+			const run = result.details as RunResult | undefined;
+			if (!run) return new Text(theme.fg("muted", "running…"), 0, 0);
+			return new Text(resultLines(run, expanded, theme).join("\n"), 0, 0);
+		},
+	});
+}
+
+/**
+ * Pi runs extensions in Node, so the work happens in a Bun process (runner.ts). On abort it's asked
+ * 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.
+ */
+function runWithBun(options: RunOptions, signal?: AbortSignal): 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 stop = () => runner.kill("SIGTERM");
+		signal?.addEventListener("abort", stop);
+
+		let stdout = "";
+		let stderr = "";
+		runner.stdout.setEncoding("utf8"); // so a multi-byte character split across chunks decodes intact
+		runner.stderr.setEncoding("utf8");
+		runner.stdout.on("data", (chunk) => (stdout += chunk));
+		runner.stderr.on("data", (chunk) => (stderr += chunk));
+		runner.on("error", reject);
+		runner.on("close", (code) => {
+			signal?.removeEventListener("abort", stop);
+			try {
+				process.kill(-runner.pid!, "SIGKILL"); // anything the program left running
+			} catch {
+				// nothing left
+			}
+			if (signal?.aborted) reject(new Error("Aborted"));
+			else if (code === 0) resolve(JSON.parse(stdout));
+			else reject(new Error(stderr.trim() || `runner exited with ${code}`));
+		});
+
+		runner.stdin.end(JSON.stringify(options));
+	});
+}
+
+/**
+ * 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(LOG_FILE).size;
+		const length = Math.min(size, 64 * 1024);
+		const buffer = Buffer.alloc(length);
+		const file = openSync(LOG_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 = [];
+	parts.push(run.timedOut ? "timed out" : `exit ${run.exitCode}`);
+	parts.push(`${run.durationMs} ms`);
+
+	if (run.changes.length === 0) {
+		parts.push("no changes");
+	} else {
+		const counts = run.changes.map((change) => countLines(change.patch));
+		const additions = counts.reduce((sum, count) => sum + count.additions, 0);
+		const deletions = counts.reduce((sum, count) => sum + count.deletions, 0);
+		const files = run.changes.length === 1 ? "1 file" : `${run.changes.length} files`;
+		parts.push(`${files} · +${additions} −${deletions}`);
+
+		if (run.applied.length === run.changes.length) parts.push("applied");
+		else if (run.applied.length === 0) parts.push("NOT applied");
+		else parts.push(`${run.applied.length} of ${run.changes.length} applied`);
+	}
+	return `${run.exitCode === 0 ? "✓" : "✕"} ${parts.join(" · ")}`;
+}
+
+/** e.g. "  M src/a.ts +3 −1" */
+function fileLine(change: FileChange): string {
+	const letter = { added: "A", modified: "M", deleted: "D" }[change.kind];
+	const { additions, deletions } = countLines(change.patch);
+	return `  ${letter} ${change.path} +${additions} −${deletions}`;
+}
+
+function textForModel(run: RunResult, toolCallId: string): string {
+	const lines = [summaryLine(run)];
+
+	if (run.applied.length === 0 && run.changes.length > 0) {
+		lines.push("The real workspace is unchanged. Below is the candidate diff.");
+	}
+	for (const change of run.changes) lines.push(fileLine(change));
+	for (const warning of run.warnings) lines.push(`warning: ${warning}`);
+	if (run.rolledBack.length > 0) {
+		lines.push(`Rolled back, because they were half-written when the program was killed: ${run.rolledBack.join(", ")}`);
+	}
+	if (run.stillRunning.length > 0) {
+		lines.push("Still running when it was killed:", ...run.stillRunning.map((command) => `  ${command}`));
+	} else if (run.lastStep) {
+		lines.push(`Its last logged step before the timeout: ${run.lastStep}`);
+	}
+
+	const output = outputForModel(run, toolCallId);
+	const diff = diffForModel(run, toolCallId);
+
+	// On failure the error goes last, where it's easiest to find; on success, the diff does.
+	if (run.exitCode === 0) lines.push(...output, ...diff);
+	else lines.push(...diff, ...output);
+	return lines.join("\n");
+}
+
+/** The program's output, within Pi's usual limits for tool output. Says so if anything was cut. */
+function outputForModel(run: RunResult, toolCallId: string): string[] {
+	const output = run.output.trim();
+	if (!output) return [];
+
+	const truncated = truncateTail(output);
+	if (!truncated.truncated) return ["", "output:", output];
+
+	const fullOutputPath = path.join(tmpdir(), `pi-shorthand-${toolCallId}.output`);
+	writeFileSync(fullOutputPath, output);
+	const notice = `[output truncated: the last ${truncated.outputLines} of ${truncated.totalLines} lines; full output: ${fullOutputPath}]`;
+	return ["", "output:", notice, truncated.content];
+}
+
+function diffForModel(run: RunResult, toolCallId: string): string[] {
+	const diff = run.changes.map((change) => change.patch).join("\n");
+	if (!diff) return [];
+
+	const truncated = truncateHead(diff);
+	const lines = ["", truncated.content];
+	if (truncated.truncated) {
+		const fullDiffPath = path.join(tmpdir(), `pi-shorthand-${toolCallId}.diff`);
+		writeFileSync(fullDiffPath, diff);
+		lines.push(
+			`[diff truncated at ${truncated.outputLines} of ${truncated.totalLines} lines; full diff: ${fullDiffPath}]`,
+		);
+	}
+	return lines;
+}

package/overlay-linux.ts

@@ -0,0 +1,80 @@
+/**
+ * Linux: bubblewrap (0.9+) mounts a kernel overlayfs over the repository in a private mount
+ * namespace, so only the program sees it. Its writes land in an upper directory in tempDir, which
+ * is also where the changes are read from. There's nothing to undo afterwards.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { $ } from "bun";
+import type { Overlay } from "./runner.ts";
+
+export async function openLinuxOverlay(repo: string, tempDir: string): Promise<Overlay> {
+	const bwrap = Bun.which("bwrap");
+	if (!bwrap) throw new Error("The code tool needs bubblewrap (0.9 or later) on Linux.");
+
+	const upper = path.join(tempDir, "upper");
+	const work = path.join(tempDir, "work");
+	await fs.mkdir(upper);
+	await fs.mkdir(work);
+
+	const wrap = (command: string[], cwd: string) => [
+		bwrap,
+		"--die-with-parent", // so killing bwrap also kills the program
+		"--dev-bind",
+		"/",
+		"/",
+		"--overlay-src",
+		repo,
+		"--overlay",
+		upper,
+		work,
+		repo,
+		"--chdir",
+		cwd, // resolve the working directory again, inside the overlay
+		"--",
+		...command,
+	];
+
+	return {
+		originalDir: repo,
+		writableDir: upper,
+		gitExcludes: [],
+		wrap,
+		changes: async () => [...(await writtenFiles(upper)), ...(await deletedFiles(repo, wrap))],
+		close: async () => {},
+	};
+}
+
+/** Regular files in the upper directory, except git's own writes to .git (e.g. refreshing its index). */
+async function writtenFiles(upper: string) {
+	const written: { file: string; contents: Uint8Array | null }[] = [];
+	for (const entry of await fs.readdir(upper, { recursive: true, withFileTypes: true })) {
+		const fullPath = path.join(entry.parentPath, entry.name);
+		const file = path.relative(upper, fullPath);
+		if (!entry.isFile() || file.startsWith(".git/")) continue;
+		written.push({ file, contents: await Bun.file(fullPath).bytes() });
+	}
+	return written;
+}
+
+/**
+ * Files git saw before that are gone in the overlay, found by asking git inside it. (overlayfs's own
+ * records aren't enough: deleting a directory leaves one "whiteout" for all of it, and recreating a
+ * directory hides everything that was in it.)
+ */
+async function deletedFiles(repo: string, wrap: (command: string[], cwd: string) => string[]) {
+	const untracked = ["git", "ls-files", "-z", "--others", "--exclude-standard"];
+	const inOverlay = (command: string[]) =>
+		$`${wrap(command, repo)}`.env({ ...process.env, GIT_OPTIONAL_LOCKS: "0" }).text();
+
+	const before = $`${untracked}`.cwd(repo).text(); // outside the overlay, so it can run alongside
+	// Inside the overlay, one mount at a time: overlayfs won't let two mounts share a work directory.
+	const trackedGone = await inOverlay(["git", "ls-files", "-z", "--deleted"]);
+	const untrackedAfter = await inOverlay(untracked);
+	const untrackedBefore = await before;
+
+	const stillThere = new Set(untrackedAfter.split("\0"));
+	const deleted = [...trackedGone.split("\0"), ...untrackedBefore.split("\0").filter((file) => !stillThere.has(file))];
+	return deleted.filter(Boolean).map((file) => ({ file, contents: null }));
+}