Keep another process's downloads when opening a library (closes #105)

The download writer's temp files are now named .quak-<pid>-<random>.tmp.
removeLeftoverTempFiles moves from the backup into the download module and
deletes a .quak-*.tmp file only when the process ID in its name is no
longer running; the content cache calls it at open() instead of deleting
every temp file, so a download in progress in another process sharing the
cache survives. The README backup layout and TODO.md are updated.

Model: opus-5-5

src/download/index.ts

@@ -1,4 +1,5 @@
-import { randomUUID } from "node:crypto";
+import { randomBytes } from "node:crypto";
+import { readdirSync, rmSync } from "node:fs";
 import { open, rename, rm } from "node:fs/promises";
 import type { FileHandle } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -180,6 +181,38 @@ export const fsyncPath = async (path: string): Promise<void> => {
     }
 };
 
+// A process-ID check: signal 0 delivers nothing and only reports whether the
+// process exists. EPERM means it exists but belongs to another user.
+const isRunning = (pid: number): boolean => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (err) {
+        return (err as NodeJS.ErrnoException).code === "EPERM";
+    }
+};
+
+// Delete the temp files a killed process left in `dir`: the writer's
+// `.quak-<pid>-<random>.tmp` and the backup copy's
+// `.quak-backup-<name>-<pid>-<random>.tmp`. Only files whose process is no
+// longer running are removed, so another process writing into the same
+// directory keeps its own. A reused process ID can only keep a leftover a while
+// longer, never remove a live one.
+export const removeLeftoverTempFiles = (dir: string): void => {
+    let names: string[];
+    try {
+        names = readdirSync(dir);
+    } catch {
+        return;
+    }
+    for (const name of names) {
+        const match = /^\.quak-(?:.*-)?(\d+)-[0-9a-z]*\.tmp$/.exec(name);
+        if (match && !isRunning(Number(match[1]))) {
+            rmSync(join(dir, name), { force: true });
+        }
+    }
+};
+
 // Stage a write to `destination` atomically and durably, then rename it into
 // place. `fill` writes the contents into the open temp file handle — either the
 // whole buffer at once (`writeAtomic`) or chunk by chunk as they decrypt
@@ -205,8 +238,12 @@ const stageAtomic = async (
 ): Promise<void> => {
     const dir = dirname(destination);
     // The random suffix keeps concurrent downloads of the same destination
-    // from stepping on each other's temporary file.
-    const tmpPath = join(dir, `.quak-${randomUUID()}.tmp`);
+    // from stepping on each other's temporary file; the process ID lets
+    // `removeLeftoverTempFiles` tell a leftover from a write in progress.
+    const tmpPath = join(
+        dir,
+        `.quak-${process.pid}-${randomBytes(16).toString("hex")}.tmp`,
+    );
     try {
         const handle = await open(tmpPath, "w");
         try {