pi-shorthand 0.5.0 → 0.7.0

package/README.md

@@ -20,9 +20,10 @@ xcode-select --install
 curl -fsSL https://agentfs.ai/install | bash
 ```
 
-On Linux, install bubblewrap 0.9 or later, a C compiler, and `lsof`. For Debian and Ubuntu:
+On Linux, install bubblewrap 0.11 or later, a C compiler, and `lsof`. For Debian and Ubuntu, check the available bubblewrap version before installing:
 
 ```sh
+apt-cache policy bubblewrap
 sudo apt install bubblewrap build-essential lsof
 ```
 
@@ -31,3 +32,5 @@ sudo apt install bubblewrap build-essential lsof
 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.
 
 Programs edit a private workspace, with host files outside the repository kept read-only. By default, a failure keeps completed files and rolls back failed or interrupted edits. Concurrent edits can cause a run to be rejected; conflict detection is best-effort, not an atomic commit.
+
+The `code` tool uses Pi's working directory by default. Pass `cwd` to target another checkout; relative paths are resolved from Pi's working directory. For example, when Pi starts in a bare worktree container, `cwd: "child"` targets its `child` worktree. The chosen directory must be inside a Git worktree.

package/api.d.ts

@@ -8,7 +8,7 @@ declare global {
 	const grep: ShorthandGlobals["grep"];
 	const sg: ShorthandGlobals["sg"];
 	const grit: ShorthandGlobals["grit"];
-	const ts: ShorthandGlobals["ts"];
+	const refactor: ShorthandGlobals["refactor"];
 }
 
 export type { RewriteResult } from "./prelude.ts";

package/display.ts

@@ -21,8 +21,15 @@ 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 === "all" && "rollback all", args.timeout && `program timeout ${args.timeout}s`];
+export function callLine(
+	args: { title?: string; cwd?: string; timeout?: number; rollback?: string },
+	theme: Theme,
+): string {
+	const settings = [
+		args.cwd && `cwd ${args.cwd}`,
+		args.rollback === "all" && "rollback all",
+		args.timeout && `program timeout ${args.timeout}s`,
+	];
 	const suffix = settings.filter(Boolean).join(", ");
 	return `${theme.fg("toolTitle", theme.bold("code"))} ${args.title ?? ""}${suffix ? theme.fg("muted", ` (${suffix})`) : ""}`;
 }
@@ -86,7 +93,7 @@ export function resultLines(run: RunResult, expanded: boolean, theme: Theme): st
 	for (const section of sections) lines.push("", ...section);
 	const timing = timingBreakdown(run);
 	if (timing) lines.push("", theme.fg("muted", `timing: ${timing}`));
-	if (run.diagnostics && ((run.diagnostics.wallMs ?? run.durationMs) >= run.timeoutMs || run.exitCode !== 0)) {
+	if (run.diagnostics && ((run.diagnostics.wallMs ?? run.durationMs) >= timeoutBudgetMs(run) || run.exitCode !== 0)) {
 		lines.push(...diagnosticLines(run.diagnostics).map((line) => theme.fg("muted", line)));
 	}
 	return lines;
@@ -108,7 +115,7 @@ const TIMING_LABELS: Record<keyof RunTimings, string> = {
 
 /** Explain calls exceeding the configured program budget, even when no individual phase does. */
 export function timingBreakdown(run: RunResult): string | undefined {
-	if (!run.timings || (run.diagnostics?.wallMs ?? run.durationMs) < run.timeoutMs) return undefined;
+	if (!run.timings || (run.diagnostics?.wallMs ?? run.durationMs) < timeoutBudgetMs(run)) return undefined;
 	const significant = Object.entries(run.timings)
 		.map(([phase, milliseconds]) => ({
 			label: TIMING_LABELS[phase as keyof RunTimings],
@@ -124,16 +131,27 @@ function formatDuration(milliseconds: number): string {
 	return milliseconds < 1_000 ? `${milliseconds}ms` : `${(milliseconds / 1_000).toFixed(1)}s`;
 }
 
+/** e.g. "2s" or "2s plus 60.0s in helpers": helper time does not count toward the timeout. */
+function timeoutText(run: RunResult): string {
+	const helpers = run.helperMs ? ` plus ${formatDuration(run.helperMs)} in helpers` : "";
+	return `${run.timeoutMs / 1000}s${helpers}`;
+}
+
+/** The longest a run can take before its timeout, including excluded helper time. */
+export function timeoutBudgetMs(run: RunResult): number {
+	return run.timeoutMs + (run.helperMs ?? 0);
+}
+
 /** 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 ? `Program timed out after ${run.timeoutMs / 1000}s` : "Failed";
+	const failure = run.timedOut ? `Program timed out after ${timeoutText(run)}` : "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`
+			? ` · timed out after ${timeoutText(run)}`
 			: run.exitCode
 				? ` · exit ${run.exitCode}`
 				: "";

package/format.ts

@@ -117,14 +117,26 @@ export function formatterFor(file: string, root: string): Command | null {
 	return null;
 }
 
+/** Files of one kind share a formatter decision: JS-family files, Python, Go or Rust. */
+function formatterKind(file: string): string {
+	const extension = extname(file);
+	if (/\.(?:[cm]?[jt]sx?|jsonc?|css|scss|less|html|vue|svelte|mdx?|ya?ml|graphql)$/i.test(extension)) return "js";
+	return extension === ".pyi" ? ".py" : extension;
+}
+
 export async function formatChanged(
 	files: string[],
 	root: string,
 ): Promise<{ messages: string[]; warnings: string[] }> {
 	const groups = new Map<string, { command: Command; files: string[] }>();
 	const result = { messages: [] as string[], warnings: [] as string[] };
+	// The choice depends only on a file's directory and kind of source, and each lookup checks several
+	// config files per ancestor directory, so decide once for files that share both.
+	const decided = new Map<string, Command | null>();
 	for (const file of files) {
-		const command = formatterFor(file, root);
+		const place = `${dirname(resolve(root, file))}\0${formatterKind(file)}`;
+		if (!decided.has(place)) decided.set(place, formatterFor(file, root));
+		const command = decided.get(place)!;
 		if (!command) continue;
 		const key = JSON.stringify(command);
 		const group = groups.get(key) ?? { command, files: [] };

package/index.ts

@@ -17,11 +17,13 @@ import {
 	countLines,
 	fileMetadataSummary,
 	resultLines,
+	timeoutBudgetMs,
 	timingBreakdown,
 	unstructuredResultText,
 } from "./display.ts";
 import type { FileChange, RunOptions, RunResult } from "./runner.ts";
 import { type Diagnostics, completeDiagnostics, diagnosticLines } from "./diagnostics.ts";
+import { modelDiff } from "./model-diff.ts";
 
 class RunnerError extends Error {
 	constructor(
@@ -35,7 +37,7 @@ class RunnerError extends Error {
 // Runs typically take well under a second. Longer transformations can request more time.
 const DEFAULT_TIMEOUT_SECONDS = 2;
 
-const DESCRIPTION = `Edit repository files with a TypeScript program run by Bun. Top-level await and ordinary Bun/Node APIs work. Use repository-relative paths. The program runs in an isolated workspace; changes apply on successful exit by default and the tool reports the diff. Run tests, type-checks and builds separately afterward with the shell tool.
+const DESCRIPTION = `Edit repository files with a TypeScript program run by Bun. Best for changes across many files, repeated edits and semantic TypeScript renames or moves; a small change to one file is quicker as a direct edit. Top-level await and ordinary Bun/Node APIs work. Use repository-relative paths. Set cwd to a checkout path when Pi's working directory is outside the repository, such as a child worktree in a bare worktree container. The program runs in an isolated workspace; changes apply on successful exit by default and the tool reports the diff. Run tests, type-checks and builds separately afterward with the shell tool.
 
 Common operations:
 - edit({ path, oldText, newText }) replaces exactly one literal occurrence; missing or ambiguous text is an error. Use text edits for known source, structural matching when it saves enumerating occurrences or preserves varying syntax.
@@ -43,10 +45,11 @@ Common operations:
 - sg.rewrite(pattern, replacement, files?) discovers and rewrites matching code; omit files for the working directory. $X captures one node; $$$X captures a sequence.
 - sg.one(pattern, files?) selects exactly one match; sg.find returns an array. sg.rewrite also accepts a selected match or array without a file scope.
 - A rewrite callback receives a match and returns text, a native node.replace(text) edit, or null to skip. Return native edits to apply them. Pass selected arrays together for independent edits; select again after changing their file.
-- await ts.rename({ file, symbol, to }) renames one resolved TypeScript symbol across the project without changing unrelated names.
-- await ts.renameFile({ from, to }) moves a TypeScript file and updates module paths that resolve to it.
+- await refactor.rename({ file, symbol, to }) renames one resolved TypeScript symbol across the project without changing unrelated names.
+- await refactor.renameFile({ from, to }) moves a TypeScript file and updates module paths that resolve to it.
+- await refactor.move({ file, symbol, to }) moves a top-level declaration to another file and updates the imports that follow it.
 
-See the shorthand skill for common writes. For extraction, complex rewrites or other languages, read its advanced-refactors.md guide. The default timeout is two seconds; request more for longer programs.`;
+See the shorthand skill for renames, moves and call-site migrations. Read its advanced-refactors.md guide only to extract code, move syntax, use GritQL or edit other languages. The default timeout is two seconds; request more for longer programs. Time spent inside the helpers above does not count toward it, up to 60 extra seconds.`;
 
 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
@@ -65,18 +68,29 @@ export default function (pi: ExtensionAPI) {
 		name: "code",
 		label: "Code",
 		description: DESCRIPTION,
-		promptSnippet: "Make a change with one Bun editing program; run verification separately afterward",
+		promptSnippet:
+			"Make multi-file, repetitive or rename/move changes with one Bun program; a small change to one file is quicker as a direct edit. Run verification separately afterward",
 
 		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)" }),
+			cwd: Type.Optional(
+				Type.String({
+					description:
+						"Working directory for the program; relative to Pi's working directory, or an absolute path. Defaults to Pi's working directory. Must be inside a git worktree.",
+				}),
+			),
 			rollback: Type.Optional(
 				StringEnum(["all", "file"] as const, {
 					description:
 						'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)" })),
+			timeout: Type.Optional(
+				Type.Number({
+					description: "Seconds of program time before it is killed (default 2); time inside helpers is excluded",
+				}),
+			),
 		}),
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -95,7 +109,7 @@ export default function (pi: ExtensionAPI) {
 			try {
 				result = await runWithBun(
 					{
-						cwd: ctx.cwd,
+						cwd: path.resolve(ctx.cwd, params.cwd ?? "."),
 						program: params.program,
 						timeoutMs: (params.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
 						rollback: params.rollback ?? "file",
@@ -307,7 +321,7 @@ function textForModel(run: RunResult, toolCallId: string): string {
 	// On failure the error goes last, where it's easiest to find; on success, the diff does.
 	if (run.exitCode === 0 && run.conflicts.length === 0) lines.push(...output, ...diff);
 	else lines.push(...diff, ...output);
-	if (run.diagnostics && ((run.diagnostics.wallMs ?? run.durationMs) >= run.timeoutMs || run.exitCode !== 0))
+	if (run.diagnostics && ((run.diagnostics.wallMs ?? run.durationMs) >= timeoutBudgetMs(run) || run.exitCode !== 0))
 		lines.push("", ...diagnosticLines(run.diagnostics));
 	return lines.join("\n");
 }
@@ -330,13 +344,17 @@ function diffForModel(run: RunResult, toolCallId: string): string[] {
 	const diff = run.changes.map((change) => change.patch).join("\n");
 	if (!diff) return [];
 
-	const truncated = truncateHead(diff);
+	// A large diff is shown as one example of each distinct change, then cut to Pi's usual limits.
+	const shown = modelDiff(run.changes);
+	const truncated = truncateHead(shown.text);
 	const lines = ["", truncated.content];
-	if (truncated.truncated) {
+	if (shown.summarized || 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}]`,
+			truncated.truncated
+				? `[diff truncated at ${truncated.outputLines} of ${truncated.totalLines} lines; full diff: ${fullDiffPath}]`
+				: `[full diff: ${fullDiffPath}]`,
 		);
 	}
 	return lines;

package/linux-observer.c

@@ -37,6 +37,7 @@ static const char *repository;
 static size_t repository_length;
 static pid_t initial;
 static volatile sig_atomic_t stopping;
+static int unresolved_external_permission;
 
 enum observation_kind {
     OBSERVE_CONTENTS = 'C',
@@ -121,6 +122,61 @@ static void descriptor(pid_t pid, int fd, char result[PATH_MAX]) {
     result[length] = 0;
     if (within(result) && strstr(result, " (deleted)")) die("unresolved deleted repository descriptor");
 }
+/* A missing getprocattr hook reports EINVAL. Other errors, including a label
+ * larger than our buffer, leave the access context unknown. */
+static int security_label(const char *path, char label[4096], size_t *length) {
+    int fd = open(path, O_RDONLY|O_CLOEXEC);
+    if (fd < 0) return -1;
+    size_t used = 0;
+    for (;;) {
+        char extra;
+        char *destination = used < 4096 ? label + used : &extra;
+        size_t available = used < 4096 ? 4096 - used : 1;
+        ssize_t count = read(fd, destination, available);
+        if (count < 0 && errno == EINTR) continue;
+        if (count < 0) {
+            int error = errno;
+            close(fd);
+            return used == 0 && error == EINVAL ? 0 : -1;
+        }
+        if (!count) { close(fd); *length = used; return 1; }
+        if (used == 4096) { close(fd); return -1; }
+        used += count;
+    }
+}
+static int same_access_context(pid_t pid) {
+    char tracee_path[96], tracee[4096], self[4096];
+    snprintf(tracee_path, sizeof(tracee_path), "/proc/%d/status", pid);
+    FILE *a = fopen(tracee_path, "r"), *b = fopen("/proc/self/status", "r");
+    if (!a || !b) { if (a) fclose(a); if (b) fclose(b); return 0; }
+    const char *fields[] = { "Uid:", "Gid:", "Groups:", "CapEff:" };
+    unsigned matched = 0;
+    while (fgets(tracee, sizeof(tracee), a)) {
+        for (size_t j = 0; j < sizeof(fields)/sizeof(*fields); j++) {
+            if (strncmp(tracee, fields[j], strlen(fields[j]))) continue;
+            if (!strchr(tracee, '\n')) { fclose(a); fclose(b); return 0; }
+            rewind(b);
+            int found = 0;
+            while (fgets(self, sizeof(self), b)) {
+                if (!strncmp(self, fields[j], strlen(fields[j]))) {
+                    if (!strchr(self, '\n') || strcmp(tracee, self)) { fclose(a); fclose(b); return 0; }
+                    found = 1;
+                    break;
+                }
+            }
+            matched += found;
+        }
+    }
+    fclose(a); fclose(b);
+    if (matched != sizeof(fields)/sizeof(*fields)) return 0;
+    snprintf(tracee_path, sizeof(tracee_path), "/proc/%d/attr/current", pid);
+    size_t tracee_length = 0, self_length = 0;
+    int tracee_label = security_label(tracee_path, tracee, &tracee_length);
+    int self_label = security_label("/proc/self/attr/current", self, &self_length);
+    return (tracee_label == 0 && self_label == 0) ||
+        (tracee_label == 1 && self_label == 1 && tracee_length == self_length &&
+         !memcmp(tracee, self, tracee_length));
+}
 /* Walk symlinks in the tracee's mount view, recording each repository link.
  * Never use realpath(/proc/PID/root/...): that can resolve against the host mount.
  */
@@ -182,7 +238,17 @@ static void resolve_name(pid_t pid, int fd, const char *input, int follow, char
         snprintf(visible, sizeof(visible), "/proc/%d/root%s", pid, result);
         struct stat info;
         int exists = lstat(visible, &info);
-        if (exists < 0 && errno != ENOENT && errno != ENOTDIR) die("cannot inspect tracee path");
+        if (exists < 0 && errno != ENOENT && errno != ENOTDIR) {
+            if ((errno == EACCES || errno == EPERM) && !within(result) && same_access_context(pid)) {
+                /* Matching filesystem credentials, capabilities and security
+                 * label make this external denial apply to the tracee too.
+                 * Confirm the syscall is denied before resuming it. */
+                unresolved_external_permission = 1;
+                result[0] = 0;
+                return;
+            }
+            die("cannot inspect tracee path");
+        }
         if ((!*rest && !follow) || exists < 0 || !S_ISLNK(info.st_mode)) {
             snprintf(pending, sizeof(pending), "%s", rest);
             continue;
@@ -353,6 +419,7 @@ struct task {
     int initial_stop;
     int registered;
     int waiting;
+    int checking_permission;
     struct task *next;
 };
 static struct task *tasks;
@@ -372,7 +439,8 @@ static struct task *task(pid_t pid) {
  * is not completion: retain the live record until wait reports its death or
  * an exec event explicitly identifies the replaced thread ID. */
 static void resume_task(pid_t pid, int signal) {
-    if (ptrace(PTRACE_CONT, pid, 0, signal) && errno != ESRCH) die("trace resume failed");
+    int request = task(pid)->checking_permission ? PTRACE_SYSCALL : PTRACE_CONT;
+    if (ptrace(request, pid, 0, signal) && errno != ESRCH) die("trace resume failed");
 }
 static void syscall_entry(pid_t pid, struct ptrace_syscall_info *info) {
     __u64 *a = info->seccomp.args; long nr = info->seccomp.nr;
@@ -514,6 +582,8 @@ static void exec_event(pid_t pid) {
     unsigned long former;
     if (ptrace(PTRACE_GETEVENTMSG, pid, 0, &former)) die("missing exec thread identity");
     struct task *current = task(pid);
+    if (current->checking_permission || (former != (unsigned long)pid && task(former)->checking_permission))
+        die("unresolved external path was executed");
     if (former != (unsigned long)pid) {
         current->bootstrap = task(former)->bootstrap;
         task(former)->alive = 0;
@@ -559,7 +629,7 @@ int main(int argc, char **argv) {
     int status, exit_code = 125;
     if (waitpid(initial, &status, 0) != initial || !WIFSTOPPED(status)) die("initial trace stop");
     long flags = PTRACE_O_TRACEFORK|PTRACE_O_TRACEVFORK|PTRACE_O_TRACECLONE|PTRACE_O_TRACEEXEC|
-        PTRACE_O_TRACESECCOMP|PTRACE_O_EXITKILL;
+        PTRACE_O_TRACESECCOMP|PTRACE_O_TRACESYSGOOD|PTRACE_O_EXITKILL;
     if (ptrace(PTRACE_SETOPTIONS, initial, 0, flags)) die("ptrace options");
     task(initial)->bootstrap = BEFORE_BWRAP_EXEC;
     task(initial)->registered = 1;
@@ -593,7 +663,22 @@ int main(int argc, char **argv) {
             struct ptrace_syscall_info info;
             if (ptrace(PTRACE_GET_SYSCALL_INFO, pid, sizeof(info), &info) < 0 || info.op != PTRACE_SYSCALL_INFO_SECCOMP)
                 die("syscall information unavailable");
-            syscall_entry(pid, &info); signal = 0;
+            unresolved_external_permission = 0;
+            syscall_entry(pid, &info);
+            if (unresolved_external_permission) task(pid)->checking_permission = 1;
+            signal = 0;
+        } else if (signal == (SIGTRAP|0x80) && task(pid)->checking_permission) {
+            struct ptrace_syscall_info info;
+            if (ptrace(PTRACE_GET_SYSCALL_INFO, pid, sizeof(info), &info) < 0)
+                die("unresolved external path result unavailable");
+            if (info.op == PTRACE_SYSCALL_INFO_EXIT) {
+                if (info.exit.rval != -EACCES && info.exit.rval != -EPERM)
+                    die("unresolved external path was accessed");
+                task(pid)->checking_permission = 0;
+            } else if (info.op != PTRACE_SYSCALL_INFO_ENTRY) {
+                die("unresolved external path result unavailable");
+            }
+            signal = 0;
         } else if (event == PTRACE_EVENT_FORK || event == PTRACE_EVENT_VFORK || event == PTRACE_EVENT_CLONE) {
             descendant_event(pid);
             signal = 0;

package/lsp-client.ts

@@ -87,6 +87,9 @@ async function startTypeScriptServer(root: string): Promise<TypeScriptServer> {
 		await connection.sendRequest("initialize", {
 			processId: process.pid,
 			rootUri: pathToFileURL(root).href,
+			// Rename without aliases: by default a renamed declaration is re-exported as `new as old`, so importers
+			// through a barrel keep the old name. typescript-refactors.ts keeps object literal keys unchanged instead.
+			initializationOptions: { userPreferences: { providePrefixAndSuffixTextForRename: false } },
 			capabilities: {
 				workspace: {
 					workspaceEdit: { documentChanges: true },

package/model-diff.ts

@@ -0,0 +1,60 @@
+/**
+ * The diff the model reads after a run. Small diffs are shown whole. A large diff is usually one kind of
+ * change repeated across many files, so it is shown as one example of each kind, with how many files share
+ * it; the per-file list and a path to the whole diff come with it. What people see in Pi is rendered from
+ * the result's details, not from this text.
+ */
+import type { FileChange } from "./runner.ts";
+
+/** Diffs up to this size are shown whole: about 4,000 tokens. */
+export const WHOLE_DIFF_CHARS = 16_000;
+
+/** Changed lines, ignoring numbers and string contents, which usually differ between repeated edits. */
+export function changeKind(patch: string): string {
+	return patch
+		.split("\n")
+		.filter((line) => /^[+-]/.test(line) && !/^(?:\+\+\+|---) /.test(line))
+		.map((line) =>
+			line
+				.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`/g, '""')
+				.replace(/\d+/g, "0")
+				.trim(),
+		)
+		.join("\n");
+}
+
+export interface ModelDiff {
+	text: string;
+	/** True when some files are represented by an example rather than shown. */
+	summarized: boolean;
+}
+
+export function modelDiff(changes: FileChange[], budget = WHOLE_DIFF_CHARS): ModelDiff {
+	const whole = changes.map((change) => change.patch).join("\n");
+	if (whole.length <= budget) return { text: whole, summarized: false };
+
+	const kinds = new Map<string, FileChange[]>();
+	for (const change of changes) {
+		const kind = `${change.kind}\0${changeKind(change.patch)}`;
+		kinds.set(kind, [...(kinds.get(kind) ?? []), change]);
+	}
+	// Rarer kinds first: an unusual edit is more likely to be the mistake worth seeing.
+	const groups = [...kinds.values()].toSorted((a, b) => a.length - b.length);
+	const sections: string[] = [];
+	let used = 0;
+	let omitted = 0;
+	for (const [example, ...same] of groups) {
+		const section = [
+			example!.patch,
+			...(same.length ? [`(and ${same.length} more file${same.length === 1 ? "" : "s"} with the same change)`] : []),
+		].join("\n");
+		if (sections.length > 0 && used + section.length > budget) {
+			omitted += 1 + same.length;
+			continue;
+		}
+		sections.push(section);
+		used += section.length;
+	}
+	const header = `[${changes.length} files changed in ${groups.length} distinct way${groups.length === 1 ? "" : "s"}; one example of each is shown${omitted ? `, except ${omitted} file${omitted === 1 ? "" : "s"} over the size limit` : ""}]`;
+	return { text: [header, ...sections].join("\n"), summarized: true };
+}