@stevecastaneda/paseo-progress 0.1.7 → 0.2.0

package/dist/server/store.js

@@ -0,0 +1,205 @@
+// Where a worktree's progress files live, and the run history a repo can opt
+// in to saving. The working files never touch the repo: they live outside it,
+// one folder per worktree, so git never sees them and nothing needs hiding.
+// Only runs the user asks to save are written into the repo, one file per run.
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { appendFile, mkdir, readdir, readFile, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, normalize, resolve } from "node:path";
+import { promisify } from "node:util";
+import { LEGACY_FOLDER, PANEL_OPENED_NAME, PROGRESS_FILE_NAME } from "../shared/events.js";
+import { withLock } from "./lock.js";
+import { outside } from "./paths.js";
+const LOCK_NAME = `${PROGRESS_FILE_NAME}.lock`;
+const SAVE_RUNS_KEY = "paseo-progress.saveRuns";
+// Exactly what 0.1.x wrote into .scratch/.gitignore. Only this is ever removed.
+const LEGACY_GITIGNORE = `# Added by the progress plugin for Paseo so its files stay out of git.
+${PROGRESS_FILE_NAME}
+${LOCK_NAME}/
+${PANEL_OPENED_NAME}
+.gitignore
+`;
+export async function git(cwd, args) {
+    try {
+        const { stdout } = await promisify(execFile)("git", args, { cwd });
+        return { code: 0, stdout };
+    }
+    catch (error) {
+        const failed = error;
+        return { code: typeof failed.code === "number" ? failed.code : -1, stdout: failed.stdout ?? "" };
+    }
+}
+async function exists(path) {
+    return Boolean(await stat(path).catch(() => null));
+}
+// One folder per worktree on this computer, named so a person can tell which
+// worktree it belongs to.
+export function outsideDirectory(root, home = homedir()) {
+    let real = root;
+    try {
+        real = realpathSync(root);
+    }
+    catch { }
+    const hash = createHash("sha1").update(real).digest("hex").slice(0, 8);
+    return join(home, ".local", "state", "paseo-progress", `${basename(real)}-${hash}`);
+}
+// Whether git tracks a 0.1.x progress file, per worktree, until the file changes.
+const trackedLegacy = new Map();
+async function legacyTracked(root, mtimeMs) {
+    const cached = trackedLegacy.get(root);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.tracked;
+    const { code } = await git(root, ["ls-files", "--error-unmatch", "--", `${LEGACY_FOLDER}/${PROGRESS_FILE_NAME}`]);
+    trackedLegacy.set(root, { mtimeMs, tracked: code === 0 });
+    return code === 0;
+}
+// The worktree's working files. A run 0.1.x left in .scratch moves outside the
+// first time anything asks, unless git tracks it: then it stays and is used in
+// place, so nothing changes for a repo that commits it.
+export async function findStore(root, home = homedir()) {
+    const directory = outsideDirectory(root, home);
+    const store = { directory, shown: directory.startsWith(home) ? `~${directory.slice(home.length)}` : directory };
+    const legacy = join(root, LEGACY_FOLDER);
+    const info = await stat(join(legacy, PROGRESS_FILE_NAME)).catch(() => null);
+    if (!info)
+        return store;
+    if (await legacyTracked(root, info.mtimeMs))
+        return { directory: legacy, shown: LEGACY_FOLDER };
+    await moveLegacy(legacy, directory);
+    return store;
+}
+// Appends the old file's lines to the new one rather than replacing it, so a
+// command that wrote to the old place mid-move loses nothing: the next move
+// picks those lines up. Then tidies what 0.1.x left behind.
+async function moveLegacy(legacy, directory) {
+    await mkdir(directory, { recursive: true });
+    await withLock(join(legacy, LOCK_NAME), async () => {
+        const text = await readFile(join(legacy, PROGRESS_FILE_NAME), "utf8").catch(() => null);
+        if (text === null)
+            return;
+        await withLock(join(directory, LOCK_NAME), async () => {
+            const current = await readFile(join(directory, PROGRESS_FILE_NAME), "utf8").catch(() => "");
+            const lead = current && !current.endsWith("\n") ? "\n" : "";
+            await appendFile(join(directory, PROGRESS_FILE_NAME), `${lead}${text}`);
+        });
+        await rm(join(legacy, PROGRESS_FILE_NAME));
+        if (await exists(join(legacy, PANEL_OPENED_NAME))) {
+            await writeFile(join(directory, PANEL_OPENED_NAME), "");
+            await rm(join(legacy, PANEL_OPENED_NAME));
+        }
+    });
+    const ignore = await readFile(join(legacy, ".gitignore"), "utf8").catch(() => null);
+    if (ignore === LEGACY_GITIGNORE)
+        await rm(join(legacy, ".gitignore"));
+    // Only if nothing else is in there; the user's own files keep the folder.
+    await rmdir(legacy).catch(() => { });
+}
+// The repo's saved-history folder, kept in its local git config, which every
+// worktree of the repo shares and nothing commits. Polls cost one stat; git
+// runs again only when the config file changes.
+const configFiles = new Map();
+const savedFolders = new Map();
+async function configFile(root) {
+    if (!configFiles.has(root)) {
+        const { code, stdout } = await git(root, ["rev-parse", "--git-common-dir"]);
+        configFiles.set(root, code === 0 ? join(resolve(root, stdout.trim()), "config") : null);
+    }
+    return configFiles.get(root);
+}
+// Whether the worktree is in a git repo, which saving run history needs.
+export async function inGitRepo(root) {
+    return (await configFile(root)) !== null;
+}
+// The folder runs are saved to, relative to the worktree root, or null.
+export async function historyFolder(root) {
+    const file = await configFile(root);
+    if (file === null)
+        return null;
+    const mtimeMs = (await stat(file).catch(() => null))?.mtimeMs ?? 0;
+    const cached = savedFolders.get(file);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.folder;
+    const { stdout } = await git(root, ["config", "--get", SAVE_RUNS_KEY]);
+    const folder = stdout.trim() || null;
+    savedFolders.set(file, { mtimeMs, folder });
+    return folder;
+}
+// A folder the user picked, as a clean path inside the worktree, or why not.
+export function checkFolder(raw) {
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    if (!trimmed)
+        return { error: "Choose a folder" };
+    const folder = normalize(trimmed);
+    if (outside(folder) || folder === ".")
+        return { error: "Choose a folder inside the repo" };
+    if (folder === ".git" || folder.startsWith(".git/"))
+        return { error: "Choose a folder outside .git" };
+    return { folder };
+}
+// Starts or stops saving runs for the whole repo. Files already saved stay.
+export async function setHistoryFolder(root, raw) {
+    if (raw === null) {
+        const { code } = await git(root, ["config", "--local", "--unset-all", SAVE_RUNS_KEY]);
+        // 5: it wasn't set, which is what was asked for.
+        if (code !== 0 && code !== 5)
+            throw new Error("Could not change this repo's git settings.");
+        return null;
+    }
+    const checked = checkFolder(raw);
+    if ("error" in checked)
+        throw new Error(checked.error);
+    const { code } = await git(root, ["config", "--local", SAVE_RUNS_KEY, checked.folder]);
+    if (code !== 0)
+        throw new Error("Could not save this in the repo's git settings. Is it a git repo?");
+    return checked.folder;
+}
+// "20261001-064512-warn-when-scratch.jsonl": when the run started, then its
+// title as it was at the start, so the name never changes and two runs never
+// share one.
+export function runFileName(startedAt, title) {
+    const stamp = startedAt.replace(/\.\d+Z$/, "").replace(/[-:]/g, "").replace("T", "-");
+    const slug = title.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
+    return `${stamp}${slug ? `-${slug}` : ""}.jsonl`;
+}
+// After each change: when the repo saves runs, rewrite the current run's file
+// with every event from its start. Runs before the first start aren't saved.
+export async function saveRunCopy(root, text) {
+    const folder = await historyFolder(root);
+    if (!folder)
+        return;
+    const lines = text.split("\n").filter((line) => line.trim());
+    let start = -1;
+    let event = null;
+    for (let index = lines.length - 1; index >= 0; index--) {
+        try {
+            const parsed = JSON.parse(lines[index]);
+            if (parsed?.type === "run.start") {
+                start = index;
+                event = parsed;
+                break;
+            }
+        }
+        catch { }
+    }
+    if (start < 0 || !event?.ts || !event.title)
+        return;
+    const directory = join(root, folder);
+    await mkdir(directory, { recursive: true });
+    await writeFile(join(directory, runFileName(event.ts, event.title)), `${lines.slice(start).join("\n")}\n`);
+}
+// The folders directly inside one folder of the worktree ("" is the top), for
+// the folder picker. .git is left out; so are links, which could leave the repo.
+export async function listFolders(root, folder) {
+    const checked = folder === "" ? { folder: "" } : checkFolder(folder);
+    if ("error" in checked)
+        throw new Error(checked.error);
+    const entries = await readdir(join(root, checked.folder), { withFileTypes: true }).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const folders = entries.filter((entry) => entry.isDirectory() && !(checked.folder === "" && entry.name === ".git")).map((entry) => entry.name);
+    return { folder: checked.folder, folders: folders.sort((a, b) => a.localeCompare(b)) };
+}

package/dist/shared/events.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
-// One line of `.scratch/progress.jsonl`. The command-line tool writes these;
-// the dashboard reducer reads them. `v` lets later versions change a shape
-// without misreading old files.
-export const PROGRESS_FILE = ".scratch/progress.jsonl";
+// One line of `progress.jsonl`. The command-line tool writes these; the
+// dashboard reducer reads them. `v` lets later versions change a shape without
+// misreading old files. Which folder holds it is set up per repo.
+export const PROGRESS_FILE_NAME = "progress.jsonl";
 // Present once someone has opened the Progress panel for this worktree.
-export const PANEL_OPENED_FILE = ".scratch/progress-panel-opened";
+export const PANEL_OPENED_NAME = "progress-panel-opened";
+// Where 0.1.x kept each worktree's files. store.ts moves them out.
+export const LEGACY_FOLDER = ".scratch";
 export const EVENT_VERSION = 1;
 export const TICKET_STATUSES = ["not_started", "working", "blocked", "done", "skipped"];
 export const ticketStatusSchema = z.enum(TICKET_STATUSES);

package/index.server.ts

@@ -1,9 +1,9 @@
 import type { PluginServerContext } from "@getpaseo/plugin/server";
-import { handleGetAttention, handleGetDashboard, handleMarkPanelOpened } from "./server/dashboard";
+import { handleGetAttention, handleGetDashboard, handleListFolders, handleMarkPanelOpened, handleSetHistoryFolder } from "./server/dashboard";
 import { handleInstallLauncher, handleLauncherStatus } from "./server/launcher";
 import { handleOpenDeliverable, handlePreviewDeliverable } from "./server/open";
 import { handleInstallSkill, handleSkillStatus } from "./server/skill";
-import { getAttention, getDashboard, getLauncherStatus, getSkillStatus, installLauncher, installSkill, markPanelOpened, openDeliverable, previewDeliverable } from "./shared/rpc";
+import { getAttention, getDashboard, getLauncherStatus, getSkillStatus, installLauncher, installSkill, listFolders, markPanelOpened, openDeliverable, previewDeliverable, setHistoryFolder } from "./shared/rpc";
 
 export default function contribute(server: PluginServerContext) {
   server.handle(getDashboard, handleGetDashboard);
@@ -15,5 +15,7 @@ export default function contribute(server: PluginServerContext) {
   server.handle(previewDeliverable, handlePreviewDeliverable);
   server.handle(getSkillStatus, handleSkillStatus);
   server.handle(installSkill, handleInstallSkill);
+  server.handle(listFolders, handleListFolders);
+  server.handle(setHistoryFolder, handleSetHistoryFolder);
   return () => {};
 }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@stevecastaneda/paseo-progress",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@stevecastaneda/paseo-progress",
-      "version": "0.1.7",
+      "version": "0.2.0",
       "license": "MIT",
       "dependencies": {
         "@getpaseo/client": "^0.9.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stevecastaneda/paseo-progress",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "A live progress dashboard per worktree for Paseo, drawn from a file agents write with the paseo-progress command.",
   "license": "MIT",
   "author": "Steve Castaneda",

package/server/cli.ts

@@ -1,14 +1,15 @@
 // The command agents run to record progress. Each command appends one event
 // to the worktree's progress file and prints what it recorded.
-import { existsSync, realpathSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { realpathSync, statSync } from "node:fs";
+import { relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { isSettled, type Dashboard, type NextIds } from "../shared/dashboard.ts";
-import { DELIVERABLE_KINDS, PROGRESS_FILE, TICKET_STATUSES } from "../shared/events.ts";
+import { DELIVERABLE_KINDS, TICKET_STATUSES } from "../shared/events.ts";
 import { appendProgress, InvalidEvent, readProgress, type EventDraft } from "./progress-file.ts";
-import { outside } from "./paths.ts";
+import { findRoot, outside } from "./paths.ts";
 import { installLauncher } from "./launcher.ts";
+import { findStore, saveRunCopy } from "./store.ts";
 import { dashboardText } from "../shared/show.ts";
 import { imageMimeType } from "../shared/attachments.ts";
 import { homedir } from "node:os";
@@ -438,7 +439,7 @@ function help(): string {
   return [
     `Usage: ${USAGE_NAME} <command>`,
     "",
-    `Records progress in ${PROGRESS_FILE} at the worktree root, shown by the Progress panel in Paseo.`,
+    `Records progress for this worktree, shown by the Progress panel in Paseo. The file lives outside the repo, so git never sees it.`,
     `Add --help after any command for its options.`,
     "",
     ...Object.values(commands).flatMap((command) => [`  ${command.usage}`, `      ${command.summary}`]),
@@ -449,18 +450,6 @@ function help(): string {
   ].join("\n");
 }
 
-// The worktree root is the nearest directory with a `.git` entry (a folder in
-// a checkout, a file in a linked worktree). Outside git, use the directory.
-export function findRoot(cwd: string): string {
-  let directory = resolve(cwd);
-  while (true) {
-    if (existsSync(join(directory, ".git"))) return directory;
-    const parent = dirname(directory);
-    if (parent === directory) return resolve(cwd);
-    directory = parent;
-  }
-}
-
 export async function runCli(argv: string[], options: CliOptions): Promise<number> {
   const out = options.out ?? ((line: string) => console.log(line));
   const now = options.now ?? (() => new Date());
@@ -476,7 +465,8 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe
     }
     if (first === "show") {
       const root = findRoot(options.cwd);
-      out(`Worktree: ${root}\n\n${dashboardText((await readProgress(root, now())).dashboard, now().getTime())}`);
+      const store = await findStore(root);
+      out(`Worktree: ${root}\n\n${dashboardText((await readProgress(store.directory, now())).dashboard, now().getTime())}`);
       return 0;
     }
     const target = resolve(options.cwd, (argv[1] ?? DEFAULT_LAUNCHER).replace(/^~(?=$|\/)/, homedir()));
@@ -502,14 +492,15 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe
       throw new UsageError((error as Error).message);
     }
     const root = findRoot(options.cwd);
-    const message = await appendProgress(root, now, (state) => {
+    const store = await findStore(root);
+    const message = await appendProgress(store.directory, now, (state) => {
       const finished = state.dashboard.run?.finished;
       if (finished && command !== commands.start) {
         throw new UsageError(`The run "${state.dashboard.run!.title}" is finished. Start new work with: ${USAGE_NAME} start "<title>"`);
       }
       const { event, message } = command.run({ positionals: parsed.positionals, values: parsed.values, state, cwd: options.cwd, root });
       return { event, result: message };
-    });
+    }, (text) => saveRunCopy(root, text));
     out(message);
     return 0;
   } catch (error) {

package/server/dashboard.ts

@@ -1,16 +1,20 @@
 import type { PluginHandlerContext } from "@getpaseo/plugin/server";
 import { createHash } from "node:crypto";
+import { join } from "node:path";
 import type { Dashboard } from "../shared/dashboard.ts";
+import { PROGRESS_FILE_NAME } from "../shared/events.ts";
 import type { AttentionResult, DashboardResult } from "../shared/rpc.ts";
 import { markPanelOpened, readProgress } from "./progress-file.ts";
+import { findRoot } from "./paths.ts";
+import { findStore, historyFolder, inGitRepo, listFolders, setHistoryFolder } from "./store.ts";
 
-const versions = new WeakMap<Dashboard, { panelOpened: boolean; version: string }>();
+const versions = new WeakMap<Dashboard, { key: string; version: string }>();
 
 export async function handleMarkPanelOpened(
   input: { workspaceId: string; workspaceDirectory: string },
   _context: PluginHandlerContext,
 ) {
-  await markPanelOpened(input.workspaceDirectory);
+  await markPanelOpened((await findStore(findRoot(input.workspaceDirectory))).directory);
   return {};
 }
 
@@ -20,14 +24,20 @@ export async function handleGetDashboard(
   input: { workspaceId: string; workspaceDirectory: string; since?: string },
   _context: PluginHandlerContext,
 ): Promise<DashboardResult | { unchanged: true; version: string }> {
-  const result = await readProgress(input.workspaceDirectory);
+  const root = findRoot(input.workspaceDirectory);
+  const store = await findStore(root);
+  const result = await readProgress(store.directory);
+  const file = join(store.shown, PROGRESS_FILE_NAME);
+  const savedTo = await historyFolder(root);
+  const inRepo = await inGitRepo(root);
+  const key = JSON.stringify([result.panelOpened, file, savedTo, inRepo]);
   let cached = versions.get(result.dashboard);
-  if (!cached || cached.panelOpened !== result.panelOpened) {
-    cached = { panelOpened: result.panelOpened, version: createHash("sha1").update(JSON.stringify(result)).digest("base64url") };
+  if (!cached || cached.key !== key) {
+    cached = { key, version: createHash("sha1").update(JSON.stringify(result) + key).digest("base64url") };
     versions.set(result.dashboard, cached);
   }
   const { version } = cached;
-  return input.since === version ? { unchanged: true, version } : { ...result, version };
+  return input.since === version ? { unchanged: true, version } : { ...result, file, savedTo, inRepo, root, version };
 }
 
 // Just what a message-box pill needs, so polling every workspace stays small.
@@ -35,7 +45,7 @@ export async function handleGetAttention(
   input: { workspaceId: string; workspaceDirectory: string },
   _context: PluginHandlerContext,
 ): Promise<AttentionResult> {
-  const { configured, dashboard, panelOpened } = await readProgress(input.workspaceDirectory);
+  const { configured, dashboard, panelOpened } = await readProgress((await findStore(findRoot(input.workspaceDirectory))).directory);
   return {
     configured,
     questions: dashboard.questions.open.length,
@@ -44,3 +54,18 @@ export async function handleGetAttention(
     panelOpened,
   };
 }
+
+export async function handleListFolders(
+  input: { workspaceId: string; workspaceDirectory: string; folder: string },
+  _context: PluginHandlerContext,
+) {
+  return listFolders(findRoot(input.workspaceDirectory), input.folder);
+}
+
+// Runs only when the user picks a folder, or stops saving, in the panel.
+export async function handleSetHistoryFolder(
+  input: { workspaceId: string; workspaceDirectory: string; folder: string | null },
+  _context: PluginHandlerContext,
+) {
+  return { savedTo: await setHistoryFolder(findRoot(input.workspaceDirectory), input.folder) };
+}

package/server/open.ts

@@ -6,7 +6,8 @@ import { join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import { findAttachment, imageMimeType, previewKind } from "../shared/attachments.ts";
 import { readProgress } from "./progress-file.ts";
-import { outside } from "./paths.ts";
+import { findRoot, outside } from "./paths.ts";
+import { findStore } from "./store.ts";
 
 export type Opener = (path: string) => Promise<void>;
 
@@ -43,10 +44,11 @@ export const systemOpener: Opener = async (path) => {
 // so the panel can never reach an arbitrary path. Only files inside the
 // worktree resolve.
 async function resolveAttachment(directory: string, ref: string, verb: string): Promise<{ path: string; target: string }> {
-  const { dashboard } = await readProgress(directory);
+  const worktree = findRoot(directory);
+  const { dashboard } = await readProgress((await findStore(worktree)).directory);
   const path = findAttachment(dashboard, ref)?.path;
   if (!path) throw new Error(`No local ${ref.startsWith("Q") ? "attachment" : "deliverable"} ${ref} in this worktree.`);
-  const root = await realpath(directory);
+  const root = await realpath(worktree);
   const target = await realpath(resolve(root, path)).catch(() => null);
   if (!target) throw new Error(`${path} no longer exists.`);
   const inside = relative(root, target);

package/server/paths.ts

@@ -1,7 +1,22 @@
-import { isAbsolute, sep } from "node:path";
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 
 // Whether a path from relative(root, target) leaves the root. "..notes" is a
 // name inside it, not a step out.
 export function outside(inside: string): boolean {
   return inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside);
 }
+
+// The worktree root is the nearest directory with a `.git` entry (a folder in
+// a checkout, a file in a linked worktree). Outside git, use the directory.
+// The command and the panel both start from here, so a Paseo project set at a
+// subfolder of the repo still reads the file the agent writes.
+export function findRoot(cwd: string): string {
+  let directory = resolve(cwd);
+  while (true) {
+    if (existsSync(join(directory, ".git"))) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) return resolve(cwd);
+    directory = parent;
+  }
+}

package/server/progress-file.ts

@@ -1,24 +1,14 @@
 // Everything that reads or writes a worktree's progress files: the event log
-// the command appends to, the panel-opened marker, and the .gitignore that keeps
-// both out of git. The command and the panel's RPC handlers go through here, so
-// they always agree on where the files are and how they're read.
+// the command appends to and the panel-opened marker. Each function takes the
+// folder that holds them, which `findStore` in store.ts picks. The command and
+// the panel's RPC handlers go through here, so they agree on how they're read.
 import { access, appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { join } from "node:path";
 import { EMPTY_DASHBOARD, parseProgress, reduceProgress, type Dashboard, type NextIds } from "../shared/dashboard.ts";
-import { EVENT_VERSION, eventSchema, PANEL_OPENED_FILE, PROGRESS_FILE, type ProgressEvent } from "../shared/events.ts";
+import { EVENT_VERSION, eventSchema, PANEL_OPENED_NAME, PROGRESS_FILE_NAME, type ProgressEvent } from "../shared/events.ts";
 import { withLock } from "./lock.ts";
 
-const SCRATCH_DIR = dirname(PROGRESS_FILE);
-const LOCK_FILE = `${PROGRESS_FILE}.lock`;
-
-// Names only this plugin's files, so they stay out of git without the user
-// editing their own .gitignore. Other files in .scratch/ are left to the repo.
-export const SCRATCH_GITIGNORE = `# Added by the progress plugin for Paseo so its files stay out of git.
-${basename(PROGRESS_FILE)}
-${basename(LOCK_FILE)}/
-${basename(PANEL_OPENED_FILE)}
-.gitignore
-`;
+const LOCK_NAME = `${PROGRESS_FILE_NAME}.lock`;
 
 // An event as a command builds it; `append` stamps the version and time.
 export type EventDraft = { [K in ProgressEvent["type"]]: Omit<Extract<ProgressEvent, { type: K }>, "v" | "ts"> }[ProgressEvent["type"]];
@@ -33,7 +23,7 @@ export interface ProgressRead {
   panelOpened: boolean;
 }
 
-// The parsed file per worktree, kept until its size or change time moves. The
+// The parsed file per folder, kept until its size or change time moves. The
 // file only grows, and the panel and pills read it every few seconds.
 const parsedFiles = new Map<string, { size: number; mtimeMs: number; ctimeMs: number; parsed: ReturnType<typeof parseProgress> }>();
 // Replaced file snapshots and their derived data can be collected together.
@@ -43,9 +33,9 @@ const dashboards = new WeakMap<ReturnType<typeof parseProgress>, { dashboard: Da
 // reuse the last one until the file changes or a stale or overdue time passes.
 // Stale and overdue checks use the daemon host's clock, the same clock the
 // command stamps events with.
-export async function readProgress(root: string, now = new Date()): Promise<ProgressRead> {
-  const parsed = await readParsed(root);
-  const panelOpened = await exists(join(root, PANEL_OPENED_FILE));
+export async function readProgress(directory: string, now = new Date()): Promise<ProgressRead> {
+  const parsed = await readParsed(directory);
+  const panelOpened = await exists(join(directory, PANEL_OPENED_NAME));
   if (parsed === null) return { configured: false, dashboard: EMPTY_DASHBOARD, panelOpened };
   let cached = dashboards.get(parsed);
   // A backwards clock jump must also re-evaluate stale/overdue state.
@@ -61,13 +51,15 @@ export async function readProgress(root: string, now = new Date()): Promise<Prog
 // that run at once take turns, so each sees the others' events and no two hand
 // out the same id. `write` may throw to append nothing.
 export async function appendProgress<T>(
-  root: string,
+  directory: string,
   now: () => Date,
   write: (state: { dashboard: Dashboard; nextIds: NextIds }) => { event: EventDraft; result: T },
+  // Runs before the lock is released, with the whole file as it now is.
+  after?: (text: string) => Promise<void>,
 ): Promise<T> {
-  await prepareScratch(root);
-  return withLock(join(root, LOCK_FILE), async () => {
-    const text = (await readText(root)) ?? "";
+  await mkdir(directory, { recursive: true });
+  return withLock(join(directory, LOCK_NAME), async () => {
+    const text = (await readText(directory)) ?? "";
     const { dashboard, nextIds } = reduceProgress(parseProgress(text), now());
     const { event, result } = write({ dashboard, nextIds });
     const checked = eventSchema.safeParse({ v: EVENT_VERSION, ts: now().toISOString(), ...withoutUndefined(event) });
@@ -76,54 +68,46 @@ export async function appendProgress<T>(
     }
     // A line cut short (a killed command, a hand edit) would swallow this event, so start a new line.
     const lead = text && !text.endsWith("\n") ? "\n" : "";
-    await appendFile(join(root, PROGRESS_FILE), `${lead}${JSON.stringify(checked.data)}\n`);
+    const line = `${lead}${JSON.stringify(checked.data)}\n`;
+    await appendFile(join(directory, PROGRESS_FILE_NAME), line);
+    await after?.(text + line);
     return result;
   });
 }
 
-export async function markPanelOpened(root: string): Promise<void> {
-  await prepareScratch(root);
-  await writeFile(join(root, PANEL_OPENED_FILE), "");
-}
-
-// Creates .scratch/ in the worktree and, the first time, its .gitignore. An
-// existing .gitignore is the user's, so it is never touched.
-async function prepareScratch(root: string): Promise<void> {
-  const directory = join(root, SCRATCH_DIR);
+export async function markPanelOpened(directory: string): Promise<void> {
   await mkdir(directory, { recursive: true });
-  await writeFile(join(directory, ".gitignore"), SCRATCH_GITIGNORE, { flag: "wx" }).catch((error: NodeJS.ErrnoException) => {
-    if (error.code !== "EEXIST") throw error;
-  });
+  await writeFile(join(directory, PANEL_OPENED_NAME), "");
 }
 
-async function readText(root: string): Promise<string | null> {
+async function readText(directory: string): Promise<string | null> {
   try {
-    return await readFile(join(root, PROGRESS_FILE), "utf8");
+    return await readFile(join(directory, PROGRESS_FILE_NAME), "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
     throw error;
   }
 }
 
-async function readParsed(root: string): Promise<ReturnType<typeof parseProgress> | null> {
-  const info = await stat(join(root, PROGRESS_FILE)).catch((error: NodeJS.ErrnoException) => {
+async function readParsed(directory: string): Promise<ReturnType<typeof parseProgress> | null> {
+  const info = await stat(join(directory, PROGRESS_FILE_NAME)).catch((error: NodeJS.ErrnoException) => {
     if (error.code === "ENOENT") return null;
     throw error;
   });
   if (!info) {
-    parsedFiles.delete(root);
+    parsedFiles.delete(directory);
     return null;
   }
-  const cached = parsedFiles.get(root);
+  const cached = parsedFiles.get(directory);
   if (cached && cached.size === info.size && cached.mtimeMs === info.mtimeMs && cached.ctimeMs === info.ctimeMs) return cached.parsed;
   // Stat before reading: if the file grows in between, the next stat won't match and it's read again.
-  const text = await readText(root);
+  const text = await readText(directory);
   if (text === null) {
-    parsedFiles.delete(root);
+    parsedFiles.delete(directory);
     return null;
   }
   const parsed = parseProgress(text);
-  parsedFiles.set(root, { size: info.size, mtimeMs: info.mtimeMs, ctimeMs: info.ctimeMs, parsed });
+  parsedFiles.set(directory, { size: info.size, mtimeMs: info.mtimeMs, ctimeMs: info.ctimeMs, parsed });
   return parsed;
 }