ccdeck 3.22.15 → 3.23.1

package/src/server/browser-react.mjs

@@ -21,8 +21,11 @@
 // tab. Only quitting takes anything back.
 import { run } from "./exec.mjs";
 // The one table of process names, shared with the presence probe so the reaction
-// and the "is it running" answer can never disagree about what to look for.
-import { processName } from "./browser-presence.mjs";
+// and the "is it running" answer can never disagree about what to look for —
+// and, with it, the two questions that table cannot answer on its own: which
+// browsers this platform cannot tell apart by name, and where each of those is
+// installed.
+import { installMarker, processName, sharesProcessName } from "./browser-presence.mjs";
 
 /** Reactions this platform can actually carry out, in the order the panel
  *  should offer them. Never a list the caller has to filter again. */
@@ -231,14 +234,156 @@ export async function quitBrowser(browserKey, platform = process.platform, deps
   // the other probe reads them from, so the two cannot drift apart.
   const proc = processName(browserKey, platform);
   if (!proc) return { ok: false, reason: "unknown_browser" };
-  if (platform === "win32") {
-    const r = await exec("taskkill", ["/IM", `${proc}.exe`, "/F"]).catch(() => null);
-    return { ok: r?.ok === true, reason: r?.ok ? "quit" : "taskkill_failed" };
-  }
+  if (platform === "win32") return await quitWindows(browserKey, proc, exec);
   const r = await exec("pkill", ["-x", proc]).catch(() => null);
   return { ok: r?.ok === true, reason: r?.ok ? "quit" : "pkill_failed" };
 }
 
+/**
+ * The windowed processes of one image name, and where each was run from.
+ *
+ * `MainWindowHandle -ne 0` is the filter that makes the whole thing safe to
+ * send a close to. Every renderer, GPU process and utility process a Chromium
+ * browser starts carries the SAME image name as the browser itself, has no
+ * window, and cannot be asked to close — only forced. Selecting on the window
+ * handle leaves exactly the processes a WM_CLOSE means something to, which is
+ * the set the user is thinking of when they arm this reaction.
+ *
+ * `Path` rides along because it is what tells the four Chrome-family channels
+ * apart; see installMarker.
+ *
+ * `-ErrorAction SilentlyContinue` because "no process of that name" is the
+ * ordinary answer — the browser may have been closed by hand between the visit
+ * and the poll — and it is not a reason to print a stack.
+ *
+ * SINGLE QUOTES THROUGHOUT AND NOT ONE DOUBLE QUOTE, deliberately. This is a
+ * `-Command` string and the whole of it has to survive being one argv entry on
+ * a Windows command line; the repo has already paid for the other spelling once
+ * (see notify, above: PowerShell documents that a string `-Command` must be the
+ * LAST parameter, and everything after it is appended to the command TEXT). A
+ * script with no embedded double quote has nothing in it for Node's
+ * command-line construction to have to escape.
+ *
+ * `proc` is interpolated, and it comes from the fixed APP_NAME table in
+ * browser-presence.mjs and from nowhere else — the same rule closeTabScript
+ * keeps for the application name it interpolates. No value a user or a web page
+ * chose reaches this string.
+ */
+export const windowedProcessesPs = proc =>
+  `Get-Process -Name ${proc} -ErrorAction SilentlyContinue | Where-Object { $_.MainWindowHandle -ne 0 } | Select-Object Id,Path | ConvertTo-Json -Compress`;
+
+/**
+ * The process ids from that listing which belong to this install.
+ *
+ * `marker` null means the image name IS the install — `msedge`, `brave`,
+ * `vivaldi` — so every windowed process of that name is wanted. A marker means
+ * the name is shared and only the ones whose executable sits under it are.
+ *
+ * A row with NO readable path is dropped rather than kept. `Get-Process` cannot
+ * read `.Path` for a process this session may not open, and a row the deck
+ * cannot attribute is one it must not claim: keeping it would put the
+ * unattributable processes back into a set whose entire purpose is to exclude
+ * the ones that are not this browser. Erring towards closing nothing is the
+ * only direction that cannot take somebody's tabs with it.
+ *
+ * `ConvertTo-Json` emits a bare object rather than an array when the listing
+ * has exactly one row — one browser window is the common case — so a single
+ * object is read as readily as a list.
+ */
+export function pickInstallPids(json, marker) {
+  let rows;
+  try { rows = typeof json === "string" ? JSON.parse(json) : json; }
+  catch { return []; }
+  if (!rows) return [];
+  if (!Array.isArray(rows)) rows = [rows];
+  const want = marker ? marker.toLowerCase() : null;
+  const out = [];
+  for (const r of rows) {
+    const pid = Number(r?.Id);
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    if (want) {
+      const path = typeof r?.Path === "string" ? r.Path : "";
+      if (!path.toLowerCase().includes(want)) continue;
+    }
+    if (!out.includes(pid)) out.push(pid);
+  }
+  return out;
+}
+
+/**
+ * Quit a browser on Windows — by asking it to close, and asking only the one
+ * the finding came from.
+ *
+ * WHAT THIS USED TO BE, because it is the reason the function exists (#1028):
+ *
+ *     exec("taskkill", ["/IM", `${proc}.exe`, "/F"])
+ *
+ * Two separate faults, and both of them cost the user work.
+ *
+ * `/F` is TerminateProcess. It is not a request and nothing gets to refuse it:
+ * no beforeunload, no session write, no "restore pages?" on the next launch.
+ * The other two legs of this same function are graceful — macOS sends the
+ * AppleScript `quit`, Linux sends SIGTERM through `pkill -x` — so Windows was
+ * the one platform where arming this reaction meant losing whatever was typed
+ * into every open form. Without `/F`, taskkill posts WM_CLOSE, which is the
+ * Windows spelling of the same polite request the other two legs make, and
+ * which Chrome honours by saving its session first.
+ *
+ * `/IM chrome.exe` is every Chrome-family process on the machine. Four browser
+ * keys share that image name (see sharesProcessName), so a user who armed this
+ * for a finding in Canary lost stable Chrome, Beta, Canary and Chromium at
+ * once — while the very same reaction on the very same finding quits Canary
+ * alone on macOS, where the table distinguishes "Google Chrome" from "Google
+ * Chrome Canary". Selecting the pids first and passing them with `/PID` is what
+ * makes the Windows reaction as narrow as the macOS one.
+ *
+ * THE FALLBACK NEVER WIDENS THE DAMAGE, only the reach. If PowerShell cannot be
+ * reached at all, this asks the image name to close — the same set the old code
+ * touched, and still without `/F`, so the worst case here is strictly gentler
+ * than the best case was before. It says which of the two it did, because a
+ * reaction that quietly closed three more browsers than it was asked to is
+ * something the reader has to be able to see in the log.
+ *
+ * And a browser with no window open is reported, not worked around. That is the
+ * case where the old code would have closed somebody else's browser instead of
+ * this one, and "could not" is the honest answer — the same rule react() keeps
+ * for every other failure it prints.
+ */
+async function quitWindows(browserKey, proc, exec) {
+  // The filter is applied only where the name is ambiguous. Narrowing an image
+  // name that already names one browser would mean a Brave installed somewhere
+  // this table did not predict is a Brave the reaction refuses to close.
+  const shared = sharesProcessName(browserKey, "win32").length > 0;
+  const marker = shared ? installMarker(browserKey, "win32") : null;
+
+  // Ambiguous AND unknown to the install table: there is no way to tell this
+  // browser's processes from three others', so the only honest answers are the
+  // broad graceful close or nothing. Broad-and-graceful, said out loud.
+  if (shared && !marker) return await closeByImage(proc, exec, "quit_family");
+
+  const listed = await exec("powershell.exe", [
+    "-NoProfile", "-NonInteractive", "-Command", windowedProcessesPs(proc),
+  ]).catch(() => null);
+
+  if (!listed?.ok) return await closeByImage(proc, exec, "quit_family");
+
+  const pids = pickInstallPids(String(listed.stdout ?? "").trim(), marker);
+  if (!pids.length) return { ok: false, reason: "no_window" };
+
+  // One taskkill with every pid on it rather than one per pid: a browser with
+  // four windows open is four processes only on the rarest Chromium build, but
+  // a profile the user runs twice is two, and closing one of them and reporting
+  // success would leave the session this reaction exists to take back.
+  const r = await exec("taskkill", pids.flatMap(pid => ["/PID", String(pid)])).catch(() => null);
+  return { ok: r?.ok === true, reason: r?.ok ? "quit" : "taskkill_failed" };
+}
+
+/** Ask every window of an image name to close. Graceful — never `/F`. */
+async function closeByImage(proc, exec, reason) {
+  const r = await exec("taskkill", ["/IM", `${proc}.exe`]).catch(() => null);
+  return { ok: r?.ok === true, reason: r?.ok ? reason : "taskkill_failed" };
+}
+
 /**
  * Carry out the armed reaction for one episode.
  *
@@ -279,6 +424,14 @@ export async function react(reaction, episode, { platform = process.platform, de
   }
 
   const out = await quitBrowser(episode.browser, platform, deps);
-  done.push(out.ok ? "quit the browser" : `could not quit the browser — ${out.reason}`);
+  // `quit_family` is the Windows fallback that could not tell four browsers
+  // sharing one image name apart and asked all of them to close. It succeeded,
+  // so it is not a `could not` line — but a reaction that closed three more
+  // browsers than the reader armed it for is not "quit the browser" either, and
+  // the log is the only place they would ever find out.
+  done.push(
+    out.reason === "quit_family"
+      ? "asked every window of that browser's family to close — this platform cannot tell its channels apart by process name"
+      : out.ok ? "quit the browser" : `could not quit the browser — ${out.reason}`);
   return done;
 }

package/src/server/browser-watch-store.mjs

@@ -17,12 +17,25 @@
 // `~/.claude/agent-dag`: readLiveDecks() reads every `.json` in that directory
 // and would have to keep skipping this one forever. A subdirectory is not a
 // name it can collide with.
-import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+//
+// AND THE READ IS THE OTHER HALF OF THAT SENTENCE, which took #1003 to notice.
+// An archive whose whole premise is that the browser's own copy can be erased
+// has to survive its own file being damaged, and what this module did when it
+// met one was read it as an empty archive — same answer as "no file yet" — and
+// then let the next ten-second poll write that emptiness over it. A file that
+// cannot be parsed is now moved aside and said out loud; only a genuinely
+// ABSENT file starts clean. See loadStore.
+import { appendFile, mkdir, open, readFile, stat, unlink } from "node:fs/promises";
 // The rename, with the Windows retry ladder installer.mjs wrote for exactly
-// this call. See the note over `writeNow` (#786).
-import { renameWithRetry } from "./installer.mjs";
+// this call. See the note over `writeNow` (#786). `stripBom` comes from the same
+// module for the reason its export block gives: a rule spelled twice is a rule
+// that drifts, and "a BOM is not damage" has to mean the same thing here as it
+// does on settings.json, or a state.json somebody opened in Notepad gets
+// quarantined for a mark the settings reader has ignored since it was written.
+import { renameWithRetry, stripBom } from "./installer.mjs";
 import { join } from "node:path";
 import { claudeConfigDir } from "./claude-dir.mjs";
+import { PRODUCT } from "./brand.mjs";
 
 /** Reactions the panel can arm. `close-tab` is macOS-only and the server is the
  *  one that says so — a client cannot be trusted to know what the OS can do,
@@ -54,14 +67,70 @@ const STORE_VERSION = 2;
  *  person could open and read. Trimmed oldest-first. */
 const KEEP = 500;
 
-const storeDir = (home = claudeConfigDir()) => join(home, "agent-dag", "browser-watch");
+/** Exported so the boot-time temp sweep can be handed this directory by name
+ *  rather than by a second spelling of the path. `sweepTempFiles` does not
+ *  recurse — deck-home.mjs:229 walks the directories it is given and nothing
+ *  under them — so the archive's own `.tmp` files, about 2.5 MB each with a
+ *  full 500-episode store, were outside every sweep the deck has ever run. */
+export const storeDir = (home = claudeConfigDir()) => join(home, "agent-dag", "browser-watch");
 export const storePath = (home = claudeConfigDir()) => join(storeDir(home), "state.json");
 
+/** Where the bytes of a state.json nothing could parse are put.
+ *
+ *  `Date.now()` rather than an ISO timestamp because a colon is not a legal
+ *  filename character on Windows, and a quarantine that cannot be created on
+ *  the platform it is protecting is not a quarantine. Beside the file it came
+ *  from, so nobody has to be told where to look — and it does not end in `.tmp`,
+ *  so the sweep that now reaches this directory will not carry it off. */
+export const quarantinePath = (home = claudeConfigDir(), at = Date.now()) =>
+  `${storePath(home)}.corrupt-${at}`;
+
 /** The plain-text log, which is the one file here a person opens themselves.
  *  state.json is the deck's own record and is JSON because the deck reads it
  *  back; this is the same events in the shape `tail -f` wants. */
 export const logPath = (home = claudeConfigDir()) => join(storeDir(home), "watch.log");
 
+/** The one generation kept behind it. `.1` rather than a datestamp because this
+ *  is `tail -f`'s file and `logrotate`'s convention is the one a person reading
+ *  it already knows — and because a name that changes is a name nothing can
+ *  overwrite, which is how a rotation that bounds nothing gets written. */
+export const rolledLogPath = (home = claudeConfigDir()) => `${logPath(home)}.1`;
+
+/**
+ * How large watch.log may grow before it is rolled over (#989).
+ *
+ * EVERY OTHER STORE IN THIS MODULE HAS A CAP. `KEEP` holds the archive to 500
+ * episodes, `DISMISS_KEEP` holds dismissals to 2000, and the panel's feed is
+ * held to 200 lines — while this file, the one that writes out EVERY ADDRESS in
+ * full, grew for the life of the install and nothing ever trimmed it. With the
+ * watch on by default, a machine where something drives a browser in a loop
+ * builds a plaintext list of every address it touched, without end.
+ *
+ * TWO MEBIBYTES. An episode of twenty addresses with query strings is about
+ * 2 KB of this file, so the cap is on the order of a thousand episodes: twice
+ * the archive beside it, which `KEEP` sizes at about two years of the measured
+ * rate. It is only reached where something drives a browser far more often than
+ * that, and that machine must not fill its disk reporting it.
+ *
+ * ONE GENERATION, `watch.log.1`, so the most this costs on disk is a number a
+ * reader can state: twice the cap, plus one append that was larger on its own.
+ */
+const LOG_MAX_BYTES = 2 * 1024 * 1024;
+
+/**
+ * What the log holds on disk right now, both generations, in bytes — for the
+ * panel, which names the file and now its size. Never throws: 0 is the answer
+ * for a log never written, and a coverage field is not where a stat error goes.
+ */
+export async function logSize(home = claudeConfigDir(), deps = {}) {
+  const st = deps.stat ?? stat;
+  let total = 0;
+  for (const file of [logPath(home), rolledLogPath(home)]) {
+    try { total += (await st(file)).size; } catch { /* not there, or not readable */ }
+  }
+  return total;
+}
+
 /**
  * Append one episode, and EVERY ADDRESS IN IT, oldest first.
  *
@@ -84,6 +153,11 @@ export const logPath = (home = claudeConfigDir()) => join(storeDir(home), "watch
  * the only part of this feature that outlives the process by design — the panel
  * shows what this deck has seen, this file is what somebody reads three days
  * later without opening the panel at all.
+ *
+ * ROLLED OVER, NOT EDITED, at LOG_MAX_BYTES (#989), which keeps that rule: the
+ * whole file moves to `watch.log.1` and the next append starts a new one. No
+ * line this function wrote is ever changed. Trimming the oldest lines out in
+ * place was the other way to bound it, and it is the edit the rule forbids.
  */
 export async function appendLog(episodes, home = claudeConfigDir(), deps = {}) {
   if (!episodes.length) return;
@@ -108,7 +182,42 @@ export async function appendLog(episodes, home = claudeConfigDir(), deps = {}) {
     return [head, ...rows].join("\n");
   };
   await mk(storeDir(home), { recursive: true });
-  await add(logPath(home), episodes.map(block).join("\n") + "\n", "utf8");
+  const text = episodes.map(block).join("\n") + "\n";
+  await rollIfFull(home, Buffer.byteLength(text, "utf8"), deps);
+  await add(logPath(home), text, "utf8");
+}
+
+/**
+ * Move the log aside when this append would carry it past the cap.
+ *
+ * MEASURED BEFORE THE WRITE, so the cap is a ceiling rather than a line the file
+ * sits above until the next append. The one overshoot left is a single append
+ * larger than the whole cap, written whole on purpose: an episode split across
+ * two files would leave addresses under no summary line, and that line and its
+ * indented addresses are what `grep -v '^ '` and `grep '^  '` separate.
+ *
+ * A ROTATION THAT FAILS MUST NOT COST THE APPEND. This is the record of what a
+ * program did in somebody's browser. A full disk, a Windows handle still open on
+ * `watch.log.1`, a permission on the directory: each is a reason to write a
+ * larger file than intended, and none is a reason to write nothing. The next
+ * append tries again.
+ *
+ * `renameWithRetry` for the reason #786 gives over `writeNow`: on Windows a
+ * rename loses to anything still holding a handle, and this is a file people
+ * open to read.
+ */
+async function rollIfFull(home, adding, deps) {
+  const st = deps.stat ?? stat;
+  const mv = deps.rename ?? renameWithRetry;
+  try {
+    const { size } = await st(logPath(home));
+    if (size === 0 || size + adding <= LOG_MAX_BYTES) return;
+    await mv(logPath(home), rolledLogPath(home));
+  } catch {
+    // No log yet (the ordinary first call), or the filesystem refused. Either
+    // way the append is the thing that matters and it is not this function's to
+    // cancel.
+  }
 }
 
 /**
@@ -179,10 +288,132 @@ export const episodeKey = (host, startMs) => `${host}\u0000${startMs}`;
  *  it cannot be. */
 const DISMISS_KEEP = 2000;
 
-export async function readStore(home = claudeConfigDir(), deps = {}) {
+/** The refusal `updateStore` throws rather than merge onto a base it knows is
+ *  not what is on disk. Shaped like installer.mjs's SETTINGS_UNREADABLE and
+ *  deck-prefs' PREFS_UNREADABLE, which is this same policy on the other two
+ *  files the deck rewrites in place: a file we cannot reproduce is never
+ *  treated as an empty one. */
+function unreadableStore(path, why) {
+  const err = new Error(
+    `${path} could not be read (${why}). Refusing to overwrite it — the episodes ` +
+    `in there are this deck's own record of what a program did in the browser, and ` +
+    `nothing can re-derive them. Fix the file or move it aside, then restart ${PRODUCT}.`,
+  );
+  err.code = "WATCH_STORE_UNREADABLE";
+  err.storePath = path;
+  err.why = why;
+  return err;
+}
+
+/**
+ * Complaints already made, so a poll does not repeat one six times a minute.
+ *
+ * THE DIVERGENCE FROM deck-prefs, and the reason for it. prefs.json is read at
+ * boot and when somebody presses something; this file is read by the panel's
+ * ten-second poll and by the badge's background one, for as long as the deck is
+ * up. A quarantine that succeeded says its piece once by construction — the
+ * damaged file is gone from that name afterwards — but the two failures that
+ * CANNOT clear themselves, an unreadable file and a quarantine the filesystem
+ * refused, would otherwise put the same line on stderr every ten seconds
+ * forever, which is how a warning becomes something people filter out.
+ *
+ * Keyed on the path and the reason, not on a bare flag: two different things
+ * going wrong with two different files are two things somebody needs told.
+ */
+const _said = new Set();
+function sayOnce(warn, key, line) {
+  if (_said.has(key)) return;
+  _said.add(key);
+  warn(line);
+}
+
+/**
+ * Read the store, and say WHICH of four things happened — because three of them
+ * hand back the same empty archive and only one of them means it.
+ *
+ * WHY THE SOURCE IS PART OF THE ANSWER (#1003). The old read caught every
+ * failure the same way — one bare `catch` marked "absent or corrupt" — which is
+ * a defensible answer to a question about VALUES and a catastrophic one as the
+ * merge base of a write, because `updateStore` asked it that question on every
+ * single write. Measured end to end against a state.json truncated to half its
+ * length, the way a machine that died between the write and the rename leaves
+ * one: the archive read as empty, and the next poll wrote an archive holding
+ * only what Chrome itself still remembered — which is precisely the copy this
+ * feature exists because an intruder can erase. The dismissals went with it and
+ * the settings went back to defaults in the same write, and nothing anywhere
+ * said a word.
+ *
+ *   "file"       parsed. This is the deck's own record.
+ *   "missing"    ENOENT, and only ENOENT. Nothing has been written yet;
+ *                an empty archive, silently, which is what a first run is.
+ *   "corrupt"    bytes that are not JSON. Moved aside to `quarantined` BEFORE
+ *                this returns, so nothing can write over them.
+ *   "unreadable" the read itself failed for some reason other than absence — a
+ *                permission, a directory in the way. The file is still there
+ *                and still unread, which is exactly when a write must not land.
+ */
+export async function loadStore(home = claudeConfigDir(), deps = {}) {
   const read = deps.readFile ?? readFile;
-  let parsed = null;
-  try { parsed = JSON.parse(await read(storePath(home), "utf8")); } catch { /* absent or corrupt */ }
+  const warn = deps.warn ?? console.error;
+  const path = storePath(home);
+  const empty = () => ({ settings: normalise(null), episodes: [], dismissed: [], migrated: false });
+
+  let raw;
+  try {
+    raw = await read(path, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return { store: empty(), source: "missing", quarantined: "" };
+    sayOnce(warn, `${path} read`,
+      `${PRODUCT}: could not read ${path}: ${err?.message ?? err}. Leaving it alone — ` +
+      `the episode archive will not be written until it can be read.`);
+    return { store: empty(), source: "unreadable", quarantined: "" };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stripBom(raw));
+  } catch (err) {
+    const why = err?.message ?? String(err);
+    const mv = deps.rename ?? renameWithRetry;
+    const to = quarantinePath(home);
+    try {
+      await mv(path, to);
+    } catch (moveErr) {
+      // ENOENT means somebody else moved it between the read and the rename —
+      // a second deck on the same home, or this deck's own poll racing its own
+      // write queue. The bytes are safe, just not under a name this read chose,
+      // and what is at `path` now is nothing.
+      if (moveErr?.code === "ENOENT") return { store: empty(), source: "missing", quarantined: "" };
+      // Anything else and the damaged file is STILL THERE, unread and
+      // unprotected. Saying so is the whole point: `updateStore` refuses on it.
+      sayOnce(warn, `${path} quarantine`,
+        `${PRODUCT}: ${path} could not be read as JSON (${why}), and could not be moved ` +
+        `aside either: ${moveErr?.message ?? moveErr}. The episode archive will not be ` +
+        `written until it is fixed or moved.`);
+      return { store: empty(), source: "corrupt", quarantined: "" };
+    }
+    warn(
+      `${PRODUCT}: ${path} could not be read as JSON (${why}). It has been kept as ${to} ` +
+      `and Browser Watch is starting a fresh archive — the episodes this deck recorded ` +
+      `are in that file, so do not delete it if you want them back.`,
+    );
+    return { store: empty(), source: "corrupt", quarantined: to };
+  }
+  return { store: shapeStore(parsed), source: "file", quarantined: "" };
+}
+
+/** What is on disk, or an empty archive — the VALUES alone, for the callers
+ *  that want nothing else. `loadStore` is the same read with the answer to "and
+ *  was that really the deck's own file?" still attached; anything about to
+ *  write must ask that question, and does. */
+export async function readStore(home = claudeConfigDir(), deps = {}) {
+  return (await loadStore(home, deps)).store;
+}
+
+/** The parsed document as the rest of the deck reads it. Unchanged from what
+ *  `readStore` always did; it is a function of its own now only because the
+ *  read above has three other answers to give. */
+function shapeStore(parsed) {
   const settings = normalise(parsed?.settings);
 
   // A VERSION BUMP DROPS THE EPISODES AND KEEPS THE SETTINGS, because the two
@@ -207,8 +438,24 @@ export async function readStore(home = claudeConfigDir(), deps = {}) {
   // caller — so it says so and the snapshot does it.
   if (parsed && parsed.v !== STORE_VERSION) return { settings, episodes: [], dismissed: [], migrated: true };
 
+  // FILTERED BEFORE `archivable`, NOT AFTER. archivable opens with
+  // `String(e.host ?? "")`, which is a property access — so a `null` element
+  // threw before the `.filter` below could refuse it, and the throw escaped
+  // readStore (the try up there wraps only JSON.parse) through
+  // browserWatchSnapshot and fetchBrowserWatch into guard(): a 500 on
+  // GET /api/browser-watch, and on the settings and dismiss POSTs through
+  // updateStore. The panel stayed dead until the file was edited by hand.
+  //
+  // `{"v":2,"episodes":[null]}` is all it took. A string element was already
+  // handled correctly — it is specifically a non-object that reached the
+  // property access — and normalise a few lines up is defensive for exactly
+  // this reason: "a hand edit, a half-written save and an older version all
+  // arrive from" here.
   const episodes = Array.isArray(parsed?.episodes)
-    ? parsed.episodes.map(archivable).filter(e => Number.isFinite(e.startMs))
+    ? parsed.episodes
+        .filter(e => e && typeof e === "object")
+        .map(archivable)
+        .filter(e => Number.isFinite(e.startMs))
     : [];
   // WHAT THE READER HAS ALREADY LOOKED AT. It has to be its own list rather
   // than a deletion from `episodes`, because the panel reads the browser's
@@ -260,10 +507,37 @@ export async function writeStore(state, home = claudeConfigDir(), deps = {}) {
   return serialized(() => writeNow(state, home, deps));
 }
 
+/**
+ * The temp file, on disk and FLUSHED, before anything renames it.
+ *
+ * A rename orders the DIRECTORY ENTRY; it does not order the bytes. A machine
+ * that loses power just after one can come up with the new entry pointing at
+ * blocks that were never written — the classic file of zero bytes, and the
+ * ordinary outcome of a crash for a writer that does not sync. installer.mjs's
+ * writeFileAtomic has fsync'd for exactly this reason since it was written, and
+ * this is the file where the argument is strongest: a truncated state.json is a
+ * lost archive, and the archive exists because the browser's own copy can be
+ * erased by whoever is driving it.
+ *
+ * Signature-compatible with `writeFile` on purpose. `deps.writeFile` is the seam
+ * the suite drives a fake filesystem through, and a staging step that changed
+ * its shape would be a second thing for every caller of that seam to know.
+ */
+async function writeAndSync(path, body, encoding) {
+  const fh = await open(path, "w");
+  try {
+    await fh.writeFile(body, encoding);
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+}
+
 /** The write itself, already inside the queue. */
 async function writeNow(state, home, deps) {
   const mk = deps.mkdir ?? mkdir;
-  const write = deps.writeFile ?? writeFile;
+  const write = deps.writeFile ?? writeAndSync;
+  const drop = deps.unlink ?? unlink;
   // `renameWithRetry`, not `rename` (#786). Same Windows rule as deck-prefs,
   // and the stakes are higher here: none of the three writers catches the
   // throw, so a refused rename 500s `GET /api/browser-watch` and the panel goes
@@ -281,14 +555,29 @@ async function writeNow(state, home, deps) {
   // the calls inside one, and there are three writers in this process — the
   // poll's snapshot, the settings route and the dismiss route — with nothing
   // between them. Measured with a full 500-episode archive (~2.5 MB, past the
-  // 512 KiB writeFile chunk): eight concurrent runs left state.json unparseable
+  // 512 KiB write chunk): eight concurrent runs left state.json unparseable
   // in six of them and failed one call with ENOENT, renaming a temp file the
-  // other writer had already renamed away. readStore swallows a corrupt file,
-  // so the next poll reported an empty archive and no dismissals at all — total
-  // loss of the one file this feature exists to keep.
+  // other writer had already renamed away. readStore swallowed a corrupt file
+  // then, so the next poll reported an empty archive and no dismissals at all —
+  // total loss of the one file this feature exists to keep. That second half is
+  // no longer true of any cause, which is #1003 and `loadStore` above; this
+  // counter is what stops this particular cause from arising at all.
   const tmp = `${storePath(home)}.${process.pid}.${++_writeSeq}.tmp`;
-  await write(tmp, body, "utf8");
-  await mv(tmp, storePath(home));
+  let landed = false;
+  try {
+    await write(tmp, body, "utf8");
+    await mv(tmp, storePath(home));
+    landed = true;
+  } finally {
+    // A REFUSED WRITE MUST NOT LEAVE ITS STAGING FILE. Each of these is about
+    // 2.5 MB with a full archive, and nothing ever unlinked one: a rename the
+    // Windows ladder could not outlast, a full disk, a permission — every one
+    // of them left a copy of the whole archive lying beside it. That is only
+    // half the litter, because a deck KILLED between the two never reaches this
+    // line at all; the other half is the boot sweep, which now gets handed this
+    // directory (see `storeDir`, and bin/deck.js's sweepTempFiles call).
+    if (!landed) await drop(tmp).catch(() => {});
+  }
 }
 
 /**
@@ -305,10 +594,23 @@ async function writeNow(state, home, deps) {
  * So a caller that owns one field passes a function instead: it runs inside the
  * same queue the write does, against the state on disk at that moment, and no
  * other writer can slip between the read and the write.
+ *
+ * AND IT REFUSES RATHER THAN MUTATE A BASE THAT IS NOT WHAT IS ON DISK (#1003).
+ * `current` exists to PRESERVE what the caller does not own; handed an empty
+ * archive because `loadStore` could not read the file, it preserves nothing and
+ * this becomes the call that destroys the episodes. So the two failures that
+ * read as empty are separated: a file already moved aside is safe to start
+ * clean over, and one still sitting there unread is not. installer.mjs's
+ * readSettingsForWrite is the same policy on settings.json and deck-prefs'
+ * writePrefs is the same policy on prefs.json.
  */
 export async function updateStore(mutate, home = claudeConfigDir(), deps = {}) {
   return serialized(async () => {
-    const current = await readStore(home, deps);
+    const { store: current, source, quarantined } = await loadStore(home, deps);
+    if (source === "unreadable") throw unreadableStore(storePath(home), "the read failed");
+    if (source === "corrupt" && !quarantined) {
+      throw unreadableStore(storePath(home), "it is not JSON and could not be moved aside");
+    }
     const next = (await mutate(current)) ?? current;
     await writeNow(next, home, deps);
     return next;