diff --git a/CACHE_PROTOCOL.md b/CACHE_PROTOCOL.md
new file mode 100644
index 0000000..c7f00b5
--- /dev/null
+++ b/CACHE_PROTOCOL.md
@@ -0,0 +1,77 @@
+# Relevance cache write coordination
+
+The committed cache remains UTF-8 JSON in the existing shape:
+
+```json
+{"version": 1, "entries": {"cache-key": {"decision": "yes"}}}
+```
+
+No cache-key, prompt-version, or record-format migration is required. Each
+instance tracks the records it has changed. A flush rereads the latest file,
+merges **only those dirty records**, and atomically replaces the JSON file.
+For conflicting keys, the last serialized flush wins. An old clean snapshot
+never overwrites a newer record or resurrects records after the file is cleared.
+A failed flush retains unsaved records so the same instance can retry.
+
+## Shared Node/Python protocol
+
+Updated Node and Python writers coordinate through `<absolute-cache-path>.lock/`
+on a local filesystem. It is a persistent directory, usually empty when idle.
+It must not be deleted while writers are active. Memory-only/browser caches do
+not access the filesystem or acquire claims.
+
+Each contender uses a new random 32-character lowercase hexadecimal token and
+atomically publishes `<token>.json` with these fields:
+
+```json
+{"version": 1, "hostname": "host", "pid_scope": "linux:pid:[123]", "pid": 1234, "token": "0123456789abcdef0123456789abcdef", "ticket": 0}
+```
+
+`ticket: 0` announces that the contender is choosing. It then publishes one more
+than the greatest visible ticket and waits until no contender is still choosing
+and no `(ticket, token)` pair sorts before its own. This is the bakery-lock
+algorithm; tokens break ties identically in both languages. JSON is published
+through `.<token>.tmp` followed by atomic rename, so readers never observe a
+half-written claim. Ticket/PID values must be positive safe integers (ticket 0
+is the sole choosing exception), tokens must match filenames, and every owner
+field must be well formed.
+
+A writer removes only its own unique claim on completion or error. It never
+removes the shared directory. A claim left by a crashed process can be removed
+only on POSIX, when its hostname and PID scope match the current process and a
+process probe proves its PID no longer exists. Windows and other unsupported
+platforms never signal an owner or automatically reclaim its claim; an
+abandoned claim there requires manual inspection/removal after owners stop. Linux scope identifies `/proc/self/ns/pid`
+so another container's live PID cannot be mistaken for a dead local process.
+Other platforms use their platform identifier. Missing namespace information,
+permission-denied probes, foreign owners and malformed records are not evidence
+of death and are never automatically stolen. Unique filenames avoid the race
+where two stale-lock reapers accidentally remove a replacement owner's lock.
+
+Lock acquisition waits at most two seconds (apart from filesystem call latency).
+Contention or an unidentifiable abandoned claim then fails the cache flush:
+Node rejects `flush()`; Python logs a warning, retaining its existing API contract.
+`filterRelevant`/`filter_relevant` already log cache failures and continue the
+classification result. Unknown/foreign abandoned records require an operator to
+inspect them; remove them only after establishing that their owners have stopped.
+Temporary files left by a killed process do not block later claims.
+
+## Compatibility limits
+
+This coordination protocol requires all concurrent writers to be upgraded.
+Older clients can still read the version-1 file, but an older writer ignores the
+claims and can still overwrite newer entries. Network/distributed filesystems,
+cache-path aliases, and external deletion or modification of active claims are
+outside this local-filesystem coordination contract. A loaded instance is an
+in-memory snapshot; reopen it (or successfully flush local changes) to see other
+writers' new records.
+
+Node also serializes flush calls on the same instance. A `put` during async I/O
+stays dirty until a subsequent flush, so an older pending flush cannot erase it.
+Python keeps its existing per-instance thread lock around each flush.
+
+The Node regression suite can run an actual mixed-language process test with
+`PATCHLING_PY_SOURCE` pointing to a Python source checkout and
+`PATCHLING_PYTHON` selecting its Python interpreter. Without that optional
+checkout, independent-process coverage still runs and the mixed-language check
+is explicitly skipped; tests never fetch a repository or call an inference API.
diff --git a/README.md b/README.md
index 287fb8b..60de1a6 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,22 @@ on 2026-10-13 (re-checked 2026-10-21, when the default `deepseek/deepseek-v4.1-f
 The decision demo requests MiMo's supported `none` reasoning effort.
 Library environment defaults below are independent of the demo choices.
 
+The homepage snapshots its mode and models for each run; changes made while it
+is working apply to the next run. Model catalogs retry after temporary failures
+and reload when the saved credential changes.
+
+OpenAI-compatible streaming completions must include `[DONE]` or a successful terminal finish
+reason. A truncated stream, `finish_reason: length`, or `content_filter` rejects
+with an `IncompleteCompletionError`; length/filter failures also reject on the
+non-streaming path. Tokens may already have reached `onToken`, so publish file
+changes only after the completion promise resolves. Partial streams are not
+automatically retried, avoiding replay of a possibly billed request.
+
+Disk-backed relevance caches retain version-1 JSON and coordinate updated
+Node/Python writers. See [cache coordination and compatibility](CACHE_PROTOCOL.md)
+for lock recovery, timeout behavior, and the requirement to upgrade concurrent
+writers together. Browser and memory-only caches keep their existing behavior.
+
 ## Configuration
 
 Configuration comes from environment variables (Node) or `setEnv(...)` overrides (browser). OAuth sign-in sets the API key override for you.
diff --git a/landing/index.html b/landing/index.html
index 704b979..e54a34d 100644
--- a/landing/index.html
+++ b/landing/index.html
@@ -728,11 +728,12 @@ <h3>Python</h3>
 </div>
 
 <script type="module">
-import { buildEnvironment, generateDiff, smartapply, parseDiffPerFile }
+import { buildEnvironment, generateDiff, smartapply, parseDiffPerFile, callLlmForApply }
   from "https://esm.sh/patchling";
 import { registerClient, beginSignIn, completeSignIn }
   from "https://esm.sh/patchling/oauth";
 import { filterRelevant, DEFAULT_FILTER_MODEL } from "./relevance.js";
+import { callLlm } from "./lib/llm.js";
 
 const $ = (id) => document.getElementById(id);
 const DEFAULT_MODEL = "xiaomi/mimo-v2.6-flash";
@@ -981,7 +982,10 @@ <h1>${esc(title)}</h1>${cards}`;
 
 /* ---------- key + model storage ---------- */
 const getKey = () => localStorage.getItem("pl_key");
-const setKey = (k) => (k ? localStorage.setItem("pl_key", k) : localStorage.removeItem("pl_key"));
+const setKey = (k) => {
+  k ? localStorage.setItem("pl_key", k) : localStorage.removeItem("pl_key");
+  invalidateModels();
+};
 // Replace previous factory picks; preserve visitors' custom model choices.
 const savedModel = localStorage.getItem("pl_model");
 let MODEL = savedModel && !["zai-org/glm-5.2:thinking", "xiaomi/mimo-v2.5-pro-ultraspeed"].includes(savedModel)
@@ -989,6 +993,7 @@ <h1>${esc(title)}</h1>${cards}`;
 
 /* ---------- model picker (same pattern as the live examples) ---------- */
 let allModels = null, topOrder = new Map();
+let modelsLoaded = false, modelsKey = null, modelsRequest = null;
 const LABS = [
   ["OpenAI", /^openai\/(gpt-[0-9]|o[1-9])/i],
   ["Anthropic", /claude-(opus|sonnet)/i],
@@ -1028,19 +1033,55 @@ <h1>${esc(title)}</h1>${cards}`;
   $("modelprice").textContent = m.prompt != null ? `(${px(m.prompt)} / ${px(m.completion)} per 1M)` : "";
 }
 async function loadModels() {
-  if (allModels) return allModels;
-  let arr = [];
-  try {
-    const headers = {}; const k = getKey(); if (k) headers.Authorization = `Bearer ${k}`;
-    arr = (await (await fetch("https://nano-gpt.com/api/v1/models?detailed=true", { headers })).json()).data || [];
-  } catch { /* offline / blocked — the exact-id path still works */ }
-  allModels = arr.map((m) => ({ id: m.id, prompt: m.pricing?.prompt, completion: m.pricing?.completion, created: m.created })).filter((m) => m.id);
-  if (!allModels.length) allModels = [{ id: DEFAULT_MODEL }];
-  computeTop();
-  allModels.sort((a, b) => (rank(a.id) - rank(b.id)) || a.id.localeCompare(b.id));
+  const key = getKey() || "";
+  if (modelsLoaded && modelsKey === key) return allModels;
+  if (modelsRequest && modelsRequest.key === key) return modelsRequest.promise;
+  const request = { key, promise: null };
+  modelsRequest = request;
+  request.promise = (async () => {
+    let next, loaded = false;
+    try {
+      const headers = {}; if (key) headers.Authorization = `Bearer ${key}`;
+      const response = await fetch("https://nano-gpt.com/api/v1/models?detailed=true", { headers });
+      if (!response.ok) throw new Error("Model catalog request failed");
+      const data = (await response.json()).data;
+      if (!Array.isArray(data)) throw new Error("Invalid model catalog");
+      next = data.filter((m) => m && typeof m.id === "string" && m.id.trim()).map((m) => ({
+        id: m.id, prompt: m.pricing?.prompt, completion: m.pricing?.completion, created: m.created,
+      }));
+      if (!next.length) throw new Error("Empty model catalog");
+      loaded = true;
+    } catch { next = [{ id: DEFAULT_MODEL }]; } // exact-id entry remains available; the next open retries
+    try {
+      // A sign-in/out or newer request must not inherit an older account's catalog/prices.
+      if (modelsRequest !== request || (getKey() || "") !== key) return allModels || [{ id: DEFAULT_MODEL }];
+      allModels = next;
+      modelsLoaded = loaded;
+      modelsKey = key;
+      computeTop();
+      allModels.sort((a, b) => (rank(a.id) - rank(b.id)) || a.id.localeCompare(b.id));
+      renderModelRow();
+      renderFilterModelRow();
+      return allModels;
+    } finally {
+      if (modelsRequest === request) modelsRequest = null;
+    }
+  })();
+  return request.promise;
+}
+function invalidateModels() {
+  allModels = null;
+  modelsLoaded = false;
+  modelsKey = null;
+  modelsRequest = null;
+  topOrder = new Map();
+  for (const prefix of ["model", "filtermodel"]) {
+    $(prefix + "picker").style.display = "none";
+    $(prefix + "list").innerHTML = "";
+    $(prefix + "count").textContent = "";
+  }
   renderModelRow();
   renderFilterModelRow();
-  return allModels;
 }
 function modelButton(m) {
   const b = document.createElement("button");
@@ -1430,7 +1471,7 @@ <h1>${esc(title)}</h1>${cards}`;
 // The punchline, told only after it happened: which files git apply would
 // have bounced, and what smartapply did about it. Built from the actual run
 // outcome, so it's just as true in real mode as in the canned demo.
-function renderVerdict(perFile, inputFiles, updated, llmResolved, decisions, price) {
+function renderVerdict(perFile, inputFiles, updated, llmResolved, decisions, price, runMode = mode, scenario = SCENARIOS[scenarioKey]) {
   const v = $("verdict");
   v.innerHTML = "";
   const repaired = [...llmResolved].filter((p) => p in updated);
@@ -1462,10 +1503,10 @@ <h1>${esc(title)}</h1>${cards}`;
 
   if (decisions) line("ok", formatClassifierCost(decisions, price));
 
-  if (mode === "demo" && SCENARIOS[scenarioKey].reveal) {
+  if (runMode === "demo" && scenario.reveal) {
     const why = document.createElement("p");
     why.className = "vwhy";
-    why.textContent = SCENARIOS[scenarioKey].reveal;
+    why.textContent = scenario.reveal;
     v.appendChild(why);
   }
   v.style.display = "block";
@@ -1481,11 +1522,15 @@ <h1>${esc(title)}</h1>${cards}`;
 /* ---------- the run ---------- */
 async function run() {
   const scn = SCENARIOS[scenarioKey];
+  // Settings changed during a run apply to the next run, never halfway through this one.
+  const runMode = mode;
+  const runDiffModel = MODEL;
+  const runApplyModel = APPLY_MODEL;
 
   // Demo mode replays a canned response, so it must run against the canned
   // files and goal. If the visitor edited either, reset (and say so) rather
   // than lie about what produced the output.
-  if (mode === "demo") {
+  if (runMode === "demo") {
     const pristine = JSON.stringify(files) === JSON.stringify(scn.files)
       && $("goal").value.trim() === scn.goal;
     files = { ...scn.files };
@@ -1528,18 +1573,18 @@ <h1>${esc(title)}</h1>${cards}`;
     let decisions = null;
     if (filtering) {
       $("decisionwrap").style.display = "block";
-      $("filtersrc").textContent = mode === "demo" ? "· pre-recorded decisions" : "· live, cheap model";
+      $("filtersrc").textContent = runMode === "demo" ? "· pre-recorded decisions" : "· live, cheap model";
       decisions = await collectDecisions(inputFiles, goal, runId, runModel);
       if (!isCurrentRun(runId)) return;
     }
 
     if (!isCurrentRun(runId)) return;
     $("phase").textContent = "generating diff…";
-    $("diffsrc").textContent = mode === "demo" ? "· pre-recorded reply, real engine" : "· live from NanoGPT";
+    $("diffsrc").textContent = runMode === "demo" ? "· pre-recorded reply, real engine" : "· live from NanoGPT";
     $("diffwrap").style.display = "block";
-    const genOpts = mode === "demo"
+    const genOpts = runMode === "demo"
       ? { callLlm: makeFakeCallLlm(scn), onToken: onDiffToken }
-      : { apiKey: key, model: MODEL, onToken: onDiffToken };
+      : { apiKey: key, model: runDiffModel, callLlm, onToken: onDiffToken };
 
     const diff = await generateDiff(buildEnvironment(filesForDiff(inputFiles, decisions)), goal, genOpts);
     if (!isCurrentRun(runId)) return;
@@ -1579,9 +1624,13 @@ <h1>${esc(title)}</h1>${cards}`;
       pre.scrollTop = pre.scrollHeight;
     };
 
-    const applyOpts = mode === "demo"
+    const applyOpts = runMode === "demo"
       ? { callLlmForApply: makeFakeApply(scn), onToken: onApplyToken }
-      : { apiKey: key, model: APPLY_MODEL, onToken: onApplyToken };
+      : {
+        apiKey: key, model: runApplyModel, onToken: onApplyToken,
+        callLlmForApply: (path, original, patch, model, opts) =>
+          callLlmForApply(path, original, patch, model, { ...opts, callLlm }),
+      };
 
     const updated = await smartapply(diff, inputFiles, applyOpts);
     if (!isCurrentRun(runId)) return;
@@ -1611,14 +1660,14 @@ <h1>${esc(title)}</h1>${cards}`;
     renderEditors();
     renderPreview();
 
-    renderVerdict(perFile, inputFiles, updated, llmResolved, decisions, runPrice);
+    renderVerdict(perFile, inputFiles, updated, llmResolved, decisions, runPrice, runMode, scn);
 
     const cost = decisions ? formatClassifierCost(decisions, runPrice) : "";
     $("phase").textContent = cost
       ? "done ✓ — " + cost + " — the preview and files above are the new map"
       : "done ✓ — the preview and files above are the new map";
     document.querySelector("#status .spin").style.display = "none";
-    if (mode === "demo") $("upsell").style.display = "block";
+    if (runMode === "demo") $("upsell").style.display = "block";
   } catch (e) {
     if (!isCurrentRun(runId)) return;
     $("phase").textContent = "error";
diff --git a/landing/lib/filter.js b/landing/lib/filter.js
index e289f36..db62af4 100644
--- a/landing/lib/filter.js
+++ b/landing/lib/filter.js
@@ -151,6 +151,130 @@ const SYSTEM_PROMPT = (
  * @property {string} [cache_key]
  */
 
+/** @typedef {{ version: number, hostname: string, pid_scope: string | null, pid: number, token: string, ticket: number }} CacheClaim */
+
+const CACHE_LOCK_WAIT_MS = 2000;
+const CACHE_LOCK_POLL_MS = 10;
+
+/** @param {unknown} value @param {string} name @returns {value is CacheClaim} */
+function validCacheClaim(value, name) {
+  if (!value || typeof value !== 'object') return false;
+  const v = /** @type {CacheClaim} */ (value);
+  return v.version === 1 && typeof v.hostname === 'string' && v.hostname.length > 0
+    && (v.pid_scope === null || (typeof v.pid_scope === 'string' && v.pid_scope.length > 0))
+    && Number.isSafeInteger(v.pid) && v.pid > 0
+    && Number.isSafeInteger(v.ticket) && v.ticket >= 0
+    && typeof v.token === 'string' && /^[a-f0-9]{32}$/.test(v.token)
+    && name === `${v.token}.json`;
+}
+
+/** True only when this process can prove the local owner no longer exists. */
+function deadCacheOwner(claim, owner) {
+  // Restrict automatic recovery to POSIX process probes. In particular, the
+  // shared protocol must never treat a Windows signal call as a harmless probe.
+  if (!['aix', 'android', 'darwin', 'freebsd', 'linux', 'openbsd', 'sunos'].includes(process.platform)) return false;
+  if (claim.hostname !== owner.hostname || !owner.pid_scope || claim.pid_scope !== owner.pid_scope) return false;
+  try {
+    process.kill(claim.pid, 0);
+    return false;
+  } catch (err) {
+    return err && err.code === 'ESRCH'; // EPERM/unknown is not evidence of death.
+  }
+}
+
+/** Read atomically published contenders; remove only uniquely named, dead owners. */
+async function cacheClaims(fs, lockDir, owner) {
+  const claims = [];
+  let unknown = false;
+  for (const name of await fs.readdir(lockDir)) {
+    if (/^\.[a-f0-9]{32}\.tmp$/.test(name)) continue;
+    const path = `${lockDir}/${name}`;
+    let claim;
+    try {
+      claim = JSON.parse(await fs.readFile(path, 'utf8'));
+    } catch (err) {
+      if (!err || err.code !== 'ENOENT') unknown = true;
+      continue;
+    }
+    if (!validCacheClaim(claim, name)) { unknown = true; continue; }
+    if (claim.token !== owner.token && deadCacheOwner(claim, owner)) {
+      // A token is never reused. Concurrent reapers can remove this exact name
+      // without unlinking a replacement owner's lock (the stale-lock ABA race).
+      await fs.unlink(path).catch((err) => { if (err.code !== 'ENOENT') throw err; });
+      continue;
+    }
+    claims.push(claim);
+  }
+  return { claims, unknown };
+}
+
+/**
+ * Shared JS/Python local-filesystem bakery lock. Claims first announce choosing
+ * (ticket 0), then take max(ticket)+1 and wait for earlier (ticket, token) pairs.
+ * The directory stays in place; no writer ever deletes another live claim.
+ */
+async function withCacheWriteLock(fs, pathMod, target, write) {
+  const os = await import('node:os');
+  const crypto = await import('node:crypto');
+  const lockDir = `${target}.lock`;
+  await fs.mkdir(lockDir, { recursive: true });
+  /** @type {string | null} */
+  let scope = process.platform;
+  if (process.platform === 'linux') {
+    scope = await fs.readlink('/proc/self/ns/pid').then((v) => `linux:${v}`, () => null);
+  }
+  /** @type {CacheClaim} */
+  const owner = { version: 1, hostname: os.hostname(), pid_scope: scope,
+    pid: process.pid, token: crypto.randomBytes(16).toString('hex'), ticket: 0 };
+  const claimPath = pathMod.join(lockDir, `${owner.token}.json`);
+  const tmp = pathMod.join(lockDir, `.${owner.token}.tmp`);
+  const publish = async () => {
+    try {
+      await fs.writeFile(tmp, JSON.stringify(owner), { encoding: 'utf8', flag: 'wx' });
+      await fs.rename(tmp, claimPath);
+    } finally { await fs.unlink(tmp).catch(() => {}); }
+  };
+  const deadline = performance.now() + CACHE_LOCK_WAIT_MS;
+  const wait = async () => {
+    if (performance.now() >= deadline) throw new Error(`Timed out waiting for relevance cache lock: ${target}`);
+    await new Promise((resolve) => setTimeout(resolve, CACHE_LOCK_POLL_MS));
+  };
+  try {
+    await publish();
+    for (;;) {
+      const state = await cacheClaims(fs, lockDir, owner);
+      if (state.unknown) { await wait(); continue; }
+      const max = state.claims.reduce((n, c) => Math.max(n, c.ticket), 0);
+      if (max >= Number.MAX_SAFE_INTEGER) throw new Error('Relevance cache lock ticket exhausted');
+      owner.ticket = max + 1;
+      await publish();
+      break;
+    }
+    for (;;) {
+      const state = await cacheClaims(fs, lockDir, owner);
+      if (!state.claims.some((c) => c.token === owner.token && c.ticket === owner.ticket)) {
+        throw new Error('Relevance cache lock claim was removed');
+      }
+      const earlier = state.claims.some((c) => c.token !== owner.token
+        && (c.ticket === 0 || c.ticket < owner.ticket || (c.ticket === owner.ticket && c.token < owner.token)));
+      if (!state.unknown && !earlier) return await write();
+      await wait();
+    }
+  } finally { await fs.unlink(claimPath).catch(() => {}); }
+}
+
+/** Read the latest committed entries; corrupt/missing JSON remains a cache miss. */
+async function cacheEntriesOnDisk(fs, path) {
+  let text;
+  try { text = await fs.readFile(path, 'utf8'); }
+  catch (err) { if (err.code === 'ENOENT') return Object.create(null); throw err; }
+  let payload;
+  try { payload = JSON.parse(text); } catch { return Object.create(null); }
+  const entries = payload && typeof payload === 'object' ? payload.entries : null;
+  return entries && typeof entries === 'object' && !Array.isArray(entries)
+    ? Object.assign(Object.create(null), entries) : Object.create(null);
+}
+
 /**
  * In-memory relevance cache with an optional on-disk JSON file.
  *
@@ -172,6 +296,10 @@ export class RelevanceCache {
     this._entries = Object.create(null);
     /** @type {Promise<void> | null} */
     this._loadPromise = null;
+    /** @type {Map<string, RelevanceCacheRecord>} */
+    this._dirty = new Map();
+    /** @type {Promise<void>} */
+    this._flushPromise = Promise.resolve();
   }
 
   /**
@@ -232,7 +360,9 @@ export class RelevanceCache {
    */
   async put(key, record) {
     await this.load();
-    this._entries[key] = { ...record };
+    const value = { ...record };
+    this._entries[key] = value;
+    this._dirty.set(String(key), value);
   }
 
   /**
@@ -245,26 +375,41 @@ export class RelevanceCache {
     await this.put(key, record);
   }
 
-  /** Write `{ version: 1, entries }` atomically. No-op without a path. */
+  /** Merge this writer's dirty entries into the latest version-1 JSON atomically. */
   async flush() {
     if (!this.path) return;
+    // Serialize this instance too: an older snapshot must never follow a newer one.
+    const pending = this._flushPromise.catch(() => {}).then(() => this._flush());
+    this._flushPromise = pending;
+    return pending;
+  }
+
+  /** @returns {Promise<void>} */
+  async _flush() {
     await this.load();
+    if (!this._dirty.size) return;
+    const dirty = new Map(this._dirty);
     const fs = await import('node:fs/promises');
     const pathMod = await import('node:path');
-    const dir = pathMod.dirname(pathMod.resolve(this.path));
+    const target = pathMod.resolve(this.path);
+    const dir = pathMod.dirname(target);
     await fs.mkdir(dir, { recursive: true });
-    const tmp = pathMod.join(
-      dir,
-      `.relevance-cache-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`,
-    );
-    const payload = JSON.stringify({ version: 1, entries: this._entries });
-    try {
-      await fs.writeFile(tmp, payload, 'utf8');
-      await fs.rename(tmp, this.path);
-    } catch (err) {
-      await fs.unlink(tmp).catch(() => {});
-      throw err;
-    }
+    await withCacheWriteLock(fs, pathMod, target, async () => {
+      const entries = await cacheEntriesOnDisk(fs, target);
+      for (const [key, record] of dirty) entries[key] = record;
+      const tmp = pathMod.join(dir,
+        `.relevance-cache-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`);
+      try {
+        await fs.writeFile(tmp, JSON.stringify({ version: 1, entries }), { encoding: 'utf8', flag: 'wx' });
+        await fs.rename(tmp, target);
+      } finally { await fs.unlink(tmp).catch(() => {}); }
+      for (const [key, record] of dirty) {
+        if (this._dirty.get(key) === record) this._dirty.delete(key);
+      }
+      this._entries = entries;
+      // A put during asynchronous I/O remains dirty and visible for the next flush.
+      for (const [key, record] of this._dirty) this._entries[key] = record;
+    });
   }
 
   /** @returns {Promise<void>} */
diff --git a/landing/lib/llm.js b/landing/lib/llm.js
index 9631544..418074d 100644
--- a/landing/lib/llm.js
+++ b/landing/lib/llm.js
@@ -80,6 +80,7 @@ async function consumeSseStream(resp, onToken) {
   let content = '';
   let usage = null;
   let dataLines = [];
+  let finishReason = null;
 
   // Dispatch one SSE event; returns true when the [DONE] sentinel is seen.
   const dispatch = () => {
@@ -96,6 +97,11 @@ async function consumeSseStream(resp, onToken) {
     if (json.error) {
       throw new Error(`LLM API error (stream): ${JSON.stringify(json.error)}`);
     }
+    const reason = json.choices?.[0]?.finish_reason;
+    if (reason != null) {
+      rejectIncompleteReason(reason);
+      finishReason = reason;
+    }
     const text = json.choices?.[0]?.delta?.content;
     if (typeof text === 'string' && text.length) {
       content += text;
@@ -117,26 +123,48 @@ async function consumeSseStream(resp, onToken) {
   };
 
   let finished = false;
-  while (!finished) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-    let idx;
-    while ((idx = buffer.indexOf('\n')) !== -1) {
-      const line = buffer.slice(0, idx);
-      buffer = buffer.slice(idx + 1);
-      if (handleLine(line)) {
-        finished = true;
-        break;
+  try {
+    while (!finished) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 1);
+        if (handleLine(line)) {
+          finished = true;
+          break;
+        }
       }
     }
+    // A final event need not have a trailing blank line. EOF by itself is
+    // not successful completion: a proxy can close after a usable diff prefix.
+    buffer += decoder.decode();
+    if (!finished && buffer) finished = handleLine(buffer);
+    if (!finished) finished = dispatch();
+    if (!finished && !['stop', 'tool_calls', 'function_call'].includes(finishReason)) {
+      throw incompleteCompletion('LLM stream ended before a terminal completion event.');
+    }
+    return { choices: [{ message: { content } }], usage };
+  } finally {
+    // Also clean up after [DONE], a provider error, an abort, or a throwing
+    // onToken callback. Transport cancellation must not delay the result/error.
+    try { if (typeof reader.cancel === 'function') Promise.resolve(reader.cancel()).catch(() => {}); } catch { /* preserve the original result/error */ }
+    try { if (typeof reader.releaseLock === 'function') reader.releaseLock(); } catch { /* already released */ }
   }
-  // Flush any trailing bytes / final event lacking a terminating blank line.
-  buffer += decoder.decode();
-  if (!finished && buffer) handleLine(buffer);
-  if (!finished) dispatch();
+}
 
-  return { choices: [{ message: { content } }], usage };
+function incompleteCompletion(message) {
+  const error = new Error(message);
+  error.name = 'IncompleteCompletionError';
+  return error;
+}
+
+function rejectIncompleteReason(reason) {
+  if (reason === 'length' || reason === 'content_filter') {
+    throw incompleteCompletion(`LLM completion was incomplete (finish_reason: ${reason}).`);
+  }
 }
 
 /**
@@ -274,6 +302,7 @@ export async function callLlm({
   if (json.error) {
     throw new Error(`LLM API error from ${domainForUrl(url)}: ${JSON.stringify(json.error)}`);
   }
+  rejectIncompleteReason(json.choices?.[0]?.finish_reason);
   return json;
 }
 
diff --git a/src/filter.d.ts b/src/filter.d.ts
index aa1a26b..c9f6cd4 100644
--- a/src/filter.d.ts
+++ b/src/filter.d.ts
@@ -169,53 +169,6 @@ export const FILTER_PROMPT_VERSION: 3;
  * Patterns are case-insensitive globs (`**` crosses directories, `*` does not).
  */
 export const DEFAULT_IGNORE_PATTERNS: string[];
-/**
- * @typedef {object} RelevanceDecision
- * @property {string} path
- * @property {'yes' | 'no'} decision `yes` files go on to generateDiff.
- *   Ambiguous answers and errors are `yes`.
- * @property {string} reason short explanation; the cleaned model text when a call was made
- * @property {string | null} raw model text before parsing, or null when no call was made
- * @property {number} tokens total tokens for the call; 0 when no call was made
- * @property {number} promptTokens
- * @property {number} completionTokens
- * @property {boolean} cached true when this judgment was reused (a cache hit, or a later path in a shared request)
- * @property {'binary' | 'oversize' | 'truncated' | 'ignored' | null} skippedReason
- *   set when the file was not sent in full. `ignored` is a lockfile or generated path.
- * @property {string | null} error set when the call threw or the answer was empty;
- *   the file is still included
- * @property {boolean} failedOpen true when the file was included without a
- *   definitive yes/no (empty, malformed, thrown, or a cache failure that
- *   blocked a decision)
- */
-/**
- * @typedef {object} FilterRelevantResult
- * @property {Record<string, string | Uint8Array>} files `yes` files in input order.
- *   Valid UTF-8 bytes are decoded to text, keeping a leading BOM. A binary
- *   file kept by policy is the original value, bytes untouched.
- * @property {RelevanceDecision[]} decisions one per input file, in input order
- * @property {string} model
- * @property {RelevanceDecision[]} errors decisions whose call threw
- * @property {number} billedTokens sum of `tokens` on decisions that were not cache hits
- * @property {number} billedPromptTokens
- * @property {number} billedCompletionTokens
- * @property {number} failedOpen files included because the call failed, the answer
- *   was empty, or the answer was ambiguous
- */
-/**
- * Record stored in a cache. Snake_case so a JSON file matches the Python cache.
- * @typedef {object} RelevanceCacheRecord
- * @property {'yes' | 'no'} decision
- * @property {string} [reason]
- * @property {string | null} [raw]
- * @property {number} [tokens]
- * @property {number} [prompt_tokens]
- * @property {number} [completion_tokens]
- * @property {'binary' | 'oversize' | 'truncated' | null} [skipped_reason]
- * @property {string | null} [error]
- * @property {boolean} [failed_open]
- * @property {string} [cache_key]
- */
 /**
  * In-memory relevance cache with an optional on-disk JSON file.
  *
@@ -269,6 +222,10 @@ export class RelevanceCache {
     _entries: Record<string, RelevanceCacheRecord>;
     /** @type {Promise<void> | null} */
     _loadPromise: Promise<void> | null;
+    /** @type {Map<string, RelevanceCacheRecord>} */
+    _dirty: Map<string, RelevanceCacheRecord>;
+    /** @type {Promise<void>} */
+    _flushPromise: Promise<void>;
     /**
      * @param {string} key
      * @returns {Promise<RelevanceCacheRecord | undefined>}
@@ -287,9 +244,11 @@ export class RelevanceCache {
      * @returns {Promise<void>}
      */
     set(key: string, record: RelevanceCacheRecord): Promise<void>;
-    /** Write `{ version: 1, entries }` atomically. No-op without a path. */
+    /** Merge this writer's dirty entries into the latest version-1 JSON atomically. */
     flush(): Promise<void>;
     /** @returns {Promise<void>} */
+    _flush(): Promise<void>;
+    /** @returns {Promise<void>} */
     load(): Promise<void>;
     /** @returns {Promise<void>} */
     _load(): Promise<void>;
@@ -401,3 +360,11 @@ export type RelevanceCacheRecord = {
     failed_open?: boolean;
     cache_key?: string;
 };
+export type CacheClaim = {
+    version: number;
+    hostname: string;
+    pid_scope: string | null;
+    pid: number;
+    token: string;
+    ticket: number;
+};
diff --git a/src/filter.js b/src/filter.js
index e289f36..db62af4 100644
--- a/src/filter.js
+++ b/src/filter.js
@@ -151,6 +151,130 @@ const SYSTEM_PROMPT = (
  * @property {string} [cache_key]
  */
 
+/** @typedef {{ version: number, hostname: string, pid_scope: string | null, pid: number, token: string, ticket: number }} CacheClaim */
+
+const CACHE_LOCK_WAIT_MS = 2000;
+const CACHE_LOCK_POLL_MS = 10;
+
+/** @param {unknown} value @param {string} name @returns {value is CacheClaim} */
+function validCacheClaim(value, name) {
+  if (!value || typeof value !== 'object') return false;
+  const v = /** @type {CacheClaim} */ (value);
+  return v.version === 1 && typeof v.hostname === 'string' && v.hostname.length > 0
+    && (v.pid_scope === null || (typeof v.pid_scope === 'string' && v.pid_scope.length > 0))
+    && Number.isSafeInteger(v.pid) && v.pid > 0
+    && Number.isSafeInteger(v.ticket) && v.ticket >= 0
+    && typeof v.token === 'string' && /^[a-f0-9]{32}$/.test(v.token)
+    && name === `${v.token}.json`;
+}
+
+/** True only when this process can prove the local owner no longer exists. */
+function deadCacheOwner(claim, owner) {
+  // Restrict automatic recovery to POSIX process probes. In particular, the
+  // shared protocol must never treat a Windows signal call as a harmless probe.
+  if (!['aix', 'android', 'darwin', 'freebsd', 'linux', 'openbsd', 'sunos'].includes(process.platform)) return false;
+  if (claim.hostname !== owner.hostname || !owner.pid_scope || claim.pid_scope !== owner.pid_scope) return false;
+  try {
+    process.kill(claim.pid, 0);
+    return false;
+  } catch (err) {
+    return err && err.code === 'ESRCH'; // EPERM/unknown is not evidence of death.
+  }
+}
+
+/** Read atomically published contenders; remove only uniquely named, dead owners. */
+async function cacheClaims(fs, lockDir, owner) {
+  const claims = [];
+  let unknown = false;
+  for (const name of await fs.readdir(lockDir)) {
+    if (/^\.[a-f0-9]{32}\.tmp$/.test(name)) continue;
+    const path = `${lockDir}/${name}`;
+    let claim;
+    try {
+      claim = JSON.parse(await fs.readFile(path, 'utf8'));
+    } catch (err) {
+      if (!err || err.code !== 'ENOENT') unknown = true;
+      continue;
+    }
+    if (!validCacheClaim(claim, name)) { unknown = true; continue; }
+    if (claim.token !== owner.token && deadCacheOwner(claim, owner)) {
+      // A token is never reused. Concurrent reapers can remove this exact name
+      // without unlinking a replacement owner's lock (the stale-lock ABA race).
+      await fs.unlink(path).catch((err) => { if (err.code !== 'ENOENT') throw err; });
+      continue;
+    }
+    claims.push(claim);
+  }
+  return { claims, unknown };
+}
+
+/**
+ * Shared JS/Python local-filesystem bakery lock. Claims first announce choosing
+ * (ticket 0), then take max(ticket)+1 and wait for earlier (ticket, token) pairs.
+ * The directory stays in place; no writer ever deletes another live claim.
+ */
+async function withCacheWriteLock(fs, pathMod, target, write) {
+  const os = await import('node:os');
+  const crypto = await import('node:crypto');
+  const lockDir = `${target}.lock`;
+  await fs.mkdir(lockDir, { recursive: true });
+  /** @type {string | null} */
+  let scope = process.platform;
+  if (process.platform === 'linux') {
+    scope = await fs.readlink('/proc/self/ns/pid').then((v) => `linux:${v}`, () => null);
+  }
+  /** @type {CacheClaim} */
+  const owner = { version: 1, hostname: os.hostname(), pid_scope: scope,
+    pid: process.pid, token: crypto.randomBytes(16).toString('hex'), ticket: 0 };
+  const claimPath = pathMod.join(lockDir, `${owner.token}.json`);
+  const tmp = pathMod.join(lockDir, `.${owner.token}.tmp`);
+  const publish = async () => {
+    try {
+      await fs.writeFile(tmp, JSON.stringify(owner), { encoding: 'utf8', flag: 'wx' });
+      await fs.rename(tmp, claimPath);
+    } finally { await fs.unlink(tmp).catch(() => {}); }
+  };
+  const deadline = performance.now() + CACHE_LOCK_WAIT_MS;
+  const wait = async () => {
+    if (performance.now() >= deadline) throw new Error(`Timed out waiting for relevance cache lock: ${target}`);
+    await new Promise((resolve) => setTimeout(resolve, CACHE_LOCK_POLL_MS));
+  };
+  try {
+    await publish();
+    for (;;) {
+      const state = await cacheClaims(fs, lockDir, owner);
+      if (state.unknown) { await wait(); continue; }
+      const max = state.claims.reduce((n, c) => Math.max(n, c.ticket), 0);
+      if (max >= Number.MAX_SAFE_INTEGER) throw new Error('Relevance cache lock ticket exhausted');
+      owner.ticket = max + 1;
+      await publish();
+      break;
+    }
+    for (;;) {
+      const state = await cacheClaims(fs, lockDir, owner);
+      if (!state.claims.some((c) => c.token === owner.token && c.ticket === owner.ticket)) {
+        throw new Error('Relevance cache lock claim was removed');
+      }
+      const earlier = state.claims.some((c) => c.token !== owner.token
+        && (c.ticket === 0 || c.ticket < owner.ticket || (c.ticket === owner.ticket && c.token < owner.token)));
+      if (!state.unknown && !earlier) return await write();
+      await wait();
+    }
+  } finally { await fs.unlink(claimPath).catch(() => {}); }
+}
+
+/** Read the latest committed entries; corrupt/missing JSON remains a cache miss. */
+async function cacheEntriesOnDisk(fs, path) {
+  let text;
+  try { text = await fs.readFile(path, 'utf8'); }
+  catch (err) { if (err.code === 'ENOENT') return Object.create(null); throw err; }
+  let payload;
+  try { payload = JSON.parse(text); } catch { return Object.create(null); }
+  const entries = payload && typeof payload === 'object' ? payload.entries : null;
+  return entries && typeof entries === 'object' && !Array.isArray(entries)
+    ? Object.assign(Object.create(null), entries) : Object.create(null);
+}
+
 /**
  * In-memory relevance cache with an optional on-disk JSON file.
  *
@@ -172,6 +296,10 @@ export class RelevanceCache {
     this._entries = Object.create(null);
     /** @type {Promise<void> | null} */
     this._loadPromise = null;
+    /** @type {Map<string, RelevanceCacheRecord>} */
+    this._dirty = new Map();
+    /** @type {Promise<void>} */
+    this._flushPromise = Promise.resolve();
   }
 
   /**
@@ -232,7 +360,9 @@ export class RelevanceCache {
    */
   async put(key, record) {
     await this.load();
-    this._entries[key] = { ...record };
+    const value = { ...record };
+    this._entries[key] = value;
+    this._dirty.set(String(key), value);
   }
 
   /**
@@ -245,26 +375,41 @@ export class RelevanceCache {
     await this.put(key, record);
   }
 
-  /** Write `{ version: 1, entries }` atomically. No-op without a path. */
+  /** Merge this writer's dirty entries into the latest version-1 JSON atomically. */
   async flush() {
     if (!this.path) return;
+    // Serialize this instance too: an older snapshot must never follow a newer one.
+    const pending = this._flushPromise.catch(() => {}).then(() => this._flush());
+    this._flushPromise = pending;
+    return pending;
+  }
+
+  /** @returns {Promise<void>} */
+  async _flush() {
     await this.load();
+    if (!this._dirty.size) return;
+    const dirty = new Map(this._dirty);
     const fs = await import('node:fs/promises');
     const pathMod = await import('node:path');
-    const dir = pathMod.dirname(pathMod.resolve(this.path));
+    const target = pathMod.resolve(this.path);
+    const dir = pathMod.dirname(target);
     await fs.mkdir(dir, { recursive: true });
-    const tmp = pathMod.join(
-      dir,
-      `.relevance-cache-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`,
-    );
-    const payload = JSON.stringify({ version: 1, entries: this._entries });
-    try {
-      await fs.writeFile(tmp, payload, 'utf8');
-      await fs.rename(tmp, this.path);
-    } catch (err) {
-      await fs.unlink(tmp).catch(() => {});
-      throw err;
-    }
+    await withCacheWriteLock(fs, pathMod, target, async () => {
+      const entries = await cacheEntriesOnDisk(fs, target);
+      for (const [key, record] of dirty) entries[key] = record;
+      const tmp = pathMod.join(dir,
+        `.relevance-cache-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`);
+      try {
+        await fs.writeFile(tmp, JSON.stringify({ version: 1, entries }), { encoding: 'utf8', flag: 'wx' });
+        await fs.rename(tmp, target);
+      } finally { await fs.unlink(tmp).catch(() => {}); }
+      for (const [key, record] of dirty) {
+        if (this._dirty.get(key) === record) this._dirty.delete(key);
+      }
+      this._entries = entries;
+      // A put during asynchronous I/O remains dirty and visible for the next flush.
+      for (const [key, record] of this._dirty) this._entries[key] = record;
+    });
   }
 
   /** @returns {Promise<void>} */
diff --git a/src/llm.js b/src/llm.js
index 9631544..418074d 100644
--- a/src/llm.js
+++ b/src/llm.js
@@ -80,6 +80,7 @@ async function consumeSseStream(resp, onToken) {
   let content = '';
   let usage = null;
   let dataLines = [];
+  let finishReason = null;
 
   // Dispatch one SSE event; returns true when the [DONE] sentinel is seen.
   const dispatch = () => {
@@ -96,6 +97,11 @@ async function consumeSseStream(resp, onToken) {
     if (json.error) {
       throw new Error(`LLM API error (stream): ${JSON.stringify(json.error)}`);
     }
+    const reason = json.choices?.[0]?.finish_reason;
+    if (reason != null) {
+      rejectIncompleteReason(reason);
+      finishReason = reason;
+    }
     const text = json.choices?.[0]?.delta?.content;
     if (typeof text === 'string' && text.length) {
       content += text;
@@ -117,26 +123,48 @@ async function consumeSseStream(resp, onToken) {
   };
 
   let finished = false;
-  while (!finished) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-    let idx;
-    while ((idx = buffer.indexOf('\n')) !== -1) {
-      const line = buffer.slice(0, idx);
-      buffer = buffer.slice(idx + 1);
-      if (handleLine(line)) {
-        finished = true;
-        break;
+  try {
+    while (!finished) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 1);
+        if (handleLine(line)) {
+          finished = true;
+          break;
+        }
       }
     }
+    // A final event need not have a trailing blank line. EOF by itself is
+    // not successful completion: a proxy can close after a usable diff prefix.
+    buffer += decoder.decode();
+    if (!finished && buffer) finished = handleLine(buffer);
+    if (!finished) finished = dispatch();
+    if (!finished && !['stop', 'tool_calls', 'function_call'].includes(finishReason)) {
+      throw incompleteCompletion('LLM stream ended before a terminal completion event.');
+    }
+    return { choices: [{ message: { content } }], usage };
+  } finally {
+    // Also clean up after [DONE], a provider error, an abort, or a throwing
+    // onToken callback. Transport cancellation must not delay the result/error.
+    try { if (typeof reader.cancel === 'function') Promise.resolve(reader.cancel()).catch(() => {}); } catch { /* preserve the original result/error */ }
+    try { if (typeof reader.releaseLock === 'function') reader.releaseLock(); } catch { /* already released */ }
   }
-  // Flush any trailing bytes / final event lacking a terminating blank line.
-  buffer += decoder.decode();
-  if (!finished && buffer) handleLine(buffer);
-  if (!finished) dispatch();
+}
 
-  return { choices: [{ message: { content } }], usage };
+function incompleteCompletion(message) {
+  const error = new Error(message);
+  error.name = 'IncompleteCompletionError';
+  return error;
+}
+
+function rejectIncompleteReason(reason) {
+  if (reason === 'length' || reason === 'content_filter') {
+    throw incompleteCompletion(`LLM completion was incomplete (finish_reason: ${reason}).`);
+  }
 }
 
 /**
@@ -274,6 +302,7 @@ export async function callLlm({
   if (json.error) {
     throw new Error(`LLM API error from ${domainForUrl(url)}: ${JSON.stringify(json.error)}`);
   }
+  rejectIncompleteReason(json.choices?.[0]?.finish_reason);
   return json;
 }
 
diff --git a/test/cache-concurrency.test.js b/test/cache-concurrency.test.js
new file mode 100644
index 0000000..35ea3bb
--- /dev/null
+++ b/test/cache-concurrency.test.js
@@ -0,0 +1,224 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import { tmpdir, hostname } from 'node:os';
+import { join, resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { runInNewContext } from 'node:vm';
+import { execFile, spawnSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { syncBuiltinESMExports } from 'node:module';
+import { RelevanceCache } from '../src/filter.js';
+
+const exec = promisify(execFile);
+const moduleUrl = new URL('../src/filter.js', import.meta.url).href;
+const record = (raw) => ({ decision: 'yes', raw });
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+test('claim records reject ambiguous PID, ticket, scope and token values', () => {
+  const source = readFileSync(new URL('../src/filter.js', import.meta.url), 'utf8');
+  const body = source.match(/function validCacheClaim\(value, name\) \{[^]*?\n\}/)[0];
+  const valid = runInNewContext(`${body}\nvalidCacheClaim`);
+  const owner = { version: 1, hostname: 'host', pid_scope: 'linux:pid:[1]', pid: 1,
+    ticket: 1, token: 'a'.repeat(32) };
+  const name = `${owner.token}.json`;
+  assert.equal(valid(owner, name), true);
+  for (const bad of [{ pid: true }, { pid: 0 }, { pid: 1.5 }, { ticket: -1 },
+    { ticket: Number.MAX_SAFE_INTEGER + 1 }, { hostname: '' }, { pid_scope: '' },
+    { token: 'b'.repeat(32) }, { version: true }]) {
+    assert.equal(valid({ ...owner, ...bad }, name), false, JSON.stringify(bad));
+  }
+});
+
+test('Windows/unknown platforms never signal another cache owner for recovery', () => {
+  const source = readFileSync(new URL('../src/filter.js', import.meta.url), 'utf8');
+  const body = source.match(/function deadCacheOwner\(claim, owner\) \{[^]*?\n\}/)[0];
+  for (const platform of ['win32', 'unknown']) {
+    let probes = 0;
+    const dead = runInNewContext(`${body}\ndeadCacheOwner`, {
+      process: { platform, kill() { probes += 1; throw new Error('must not signal'); } },
+    });
+    const owner = { hostname: 'host', pid_scope: platform };
+    assert.equal(dead({ ...owner, pid: 1234 }, owner), false);
+    assert.equal(probes, 0);
+  }
+});
+
+async function fixture(t) {
+  const dir = await fs.mkdtemp(join(tmpdir(), 'patchling-cache-'));
+  t.after(() => fs.rm(dir, { recursive: true, force: true }));
+  return { dir, path: join(dir, 'cache.json') };
+}
+
+async function scope() {
+  return process.platform === 'linux'
+    ? fs.readlink('/proc/self/ns/pid').then((v) => `linux:${v}`, () => null)
+    : process.platform;
+}
+
+async function claim(path, values = {}) {
+  const owner = { version: 1, hostname: hostname(), pid_scope: await scope(),
+    pid: process.pid, token: 'a'.repeat(32), ticket: 1, ...values };
+  await fs.mkdir(`${path}.lock`, { recursive: true });
+  const file = join(`${path}.lock`, `${owner.token}.json`);
+  await fs.writeFile(file, JSON.stringify(owner));
+  return file;
+}
+
+test('independent stale instances merge only dirty entries and retain the newer conflict', async (t) => {
+  const { path } = await fixture(t);
+  const a = new RelevanceCache(path), b = new RelevanceCache(path);
+  await Promise.all([a.load(), b.load()]);
+  await a.put('shared', record('old')); await a.flush();
+  await b.put('shared', record('new')); await b.put('b', record('b')); await b.flush();
+  await a.put('a', record('a')); await a.flush();
+  const restored = new RelevanceCache(path);
+  assert.equal((await restored.get('shared')).raw, 'new');
+  assert.equal((await restored.get('a')).raw, 'a');
+  assert.equal((await restored.get('b')).raw, 'b');
+  assert.deepEqual(await fs.readdir(`${path}.lock`), []);
+});
+
+test('simultaneous instances preserve all disjoint records', async (t) => {
+  const { path } = await fixture(t);
+  const caches = Array.from({ length: 6 }, () => new RelevanceCache(path));
+  await Promise.all(caches.map((cache) => cache.load()));
+  await Promise.all(caches.map((cache, i) => cache.put(String(i), record(String(i)))));
+  await Promise.all(caches.map((cache) => cache.flush()));
+  const payload = JSON.parse(await fs.readFile(path, 'utf8'));
+  assert.equal(payload.version, 1);
+  assert.equal(Object.keys(payload.entries).length, caches.length);
+});
+
+test('a deleted cache is not repopulated from a stale clean snapshot; corrupt JSON recovers', async (t) => {
+  const { path } = await fixture(t);
+  const cache = new RelevanceCache(path);
+  await cache.put('old', record('old')); await cache.flush();
+  await fs.unlink(path);
+  await cache.put('fresh', record('fresh')); await cache.flush();
+  assert.equal((await new RelevanceCache(path).get('old')), undefined);
+  await fs.writeFile(path, '{corrupt');
+  await cache.put('after-corruption', record('ok')); await cache.flush();
+  assert.equal((await new RelevanceCache(path).get('after-corruption')).raw, 'ok');
+});
+
+test('write failure keeps dirty entries retryable and releases the claim', async (t) => {
+  const { path } = await fixture(t);
+  const cache = new RelevanceCache(path);
+  await cache.put('pending', record('pending'));
+  const rename = fs.rename;
+  fs.rename = async (from, to) => {
+    if (to === path) throw new Error('injected cache replacement failure');
+    return rename(from, to);
+  };
+  syncBuiltinESMExports();
+  try { await assert.rejects(cache.flush(), /injected cache replacement failure/); }
+  finally { fs.rename = rename; syncBuiltinESMExports(); }
+  assert.deepEqual(await fs.readdir(`${path}.lock`), []);
+  await cache.flush();
+  assert.equal((await new RelevanceCache(path).get('pending')).raw, 'pending');
+});
+
+test('a put and queued flush during I/O cannot be overwritten by the older flush', async (t) => {
+  const { path } = await fixture(t);
+  const cache = new RelevanceCache(path);
+  await cache.put('key', record('old'));
+  let entered, release;
+  const writing = new Promise((r) => { entered = r; });
+  const gate = new Promise((r) => { release = r; });
+  const rename = fs.rename;
+  let first = true;
+  fs.rename = async (from, to) => {
+    if (to === path && first) { first = false; entered(); await gate; }
+    return rename(from, to);
+  };
+  syncBuiltinESMExports();
+  try {
+    const old = cache.flush(); await writing;
+    await cache.put('key', record('new'));
+    const newer = cache.flush(); release();
+    await Promise.all([old, newer]);
+  } finally { release(); fs.rename = rename; syncBuiltinESMExports(); }
+  assert.equal((await new RelevanceCache(path).get('key')).raw, 'new');
+});
+
+test('an abandoned same-host claim is recovered without deleting its directory', {
+  skip: !['aix', 'android', 'darwin', 'freebsd', 'linux', 'openbsd', 'sunos'].includes(process.platform),
+}, async (t) => {
+  const { path } = await fixture(t);
+  const exited = spawnSync(process.execPath, ['-e', '']);
+  assert.equal(exited.status, 0);
+  const old = await claim(path, { pid: exited.pid });
+  const cache = new RelevanceCache(path); await cache.put('a', record('a')); await cache.flush();
+  await assert.rejects(fs.stat(old), { code: 'ENOENT' });
+  assert.equal((await new RelevanceCache(path).get('a')).raw, 'a');
+  assert.equal((await fs.stat(`${path}.lock`)).isDirectory(), true);
+});
+
+for (const kind of ['live', 'foreign', 'unknown']) {
+  test(`${kind} owner is never stolen; contention fails in bounded time and remains retryable`, async (t) => {
+    const { path } = await fixture(t);
+    const file = await claim(path, kind === 'foreign' ? { hostname: `${hostname()}-other` } : {});
+    if (kind === 'unknown') await fs.writeFile(file, '{malformed');
+    const cache = new RelevanceCache(path); await cache.put('a', record('a'));
+    const began = performance.now();
+    await assert.rejects(cache.flush(), /Timed out waiting/);
+    assert.ok(performance.now() - began < 5000);
+    assert.equal((await fs.stat(file)).isFile(), true);
+    await fs.unlink(file); await cache.flush();
+    assert.equal((await new RelevanceCache(path).get('a')).raw, 'a');
+  });
+}
+
+const jsWriter = `
+import fs from 'node:fs/promises';
+import { RelevanceCache } from ${JSON.stringify(moduleUrl)};
+const [path,key,barrier] = process.argv.slice(1);
+const cache = new RelevanceCache(path); await cache.load();
+await cache.put(key,{decision:'yes',raw:key});
+await fs.writeFile(barrier+'/'+key,'ready');
+while (!(await fs.stat(barrier+'/go').catch(()=>null))) await new Promise(r=>setTimeout(r,5));
+await cache.flush();
+`;
+
+async function waitForReady(dir, keys) {
+  const deadline = performance.now() + 10000;
+  while (!(await Promise.all(keys.map((key) => fs.stat(join(dir, key)).catch(() => null)))).every(Boolean)) {
+    if (performance.now() > deadline) throw new Error('writer process did not become ready');
+    await sleep(10);
+  }
+}
+
+test('independent Node processes overlap writes without losing records', async (t) => {
+  const { path, dir } = await fixture(t);
+  const keys = ['n1', 'n2', 'n3', 'n4'];
+  const writers = keys.map((key) => exec(process.execPath, ['--input-type=module', '-e', jsWriter, path, key, dir]));
+  await waitForReady(dir, keys); await fs.writeFile(join(dir, 'go'), 'go');
+  await Promise.all(writers);
+  const restored = new RelevanceCache(path);
+  for (const key of keys) assert.equal((await restored.get(key)).raw, key);
+});
+
+test('actual Python and Node writers use the same coordination protocol', {
+  skip: !process.env.PATCHLING_PY_SOURCE,
+}, async (t) => {
+  const { path, dir } = await fixture(t);
+  const python = `
+import os,sys,time
+from patchling.relevance import RelevanceCache
+path,key,barrier=sys.argv[1:]
+cache=RelevanceCache(path);cache.put(key,{'decision':'yes','raw':key})
+open(os.path.join(barrier,key),'w').close()
+while not os.path.exists(os.path.join(barrier,'go')):time.sleep(.005)
+cache.flush()
+`;
+  const pythonSource = resolve(process.env.PATCHLING_PY_SOURCE);
+  const writers = ['n1', 'n2'].map((key) => exec(process.execPath, ['--input-type=module', '-e', jsWriter, path, key, dir]));
+  writers.push(...['p1', 'p2'].map((key) => exec(process.env.PATCHLING_PYTHON || 'python3', ['-c', python, path, key, dir], {
+    cwd: pythonSource, env: { ...process.env, PYTHONPATH: pythonSource },
+  })));
+  await waitForReady(dir, ['n1', 'n2', 'p1', 'p2']); await fs.writeFile(join(dir, 'go'), 'go');
+  await Promise.all(writers);
+  const restored = new RelevanceCache(path);
+  for (const key of ['n1', 'n2', 'p1', 'p2']) assert.equal((await restored.get(key)).raw, key);
+});
diff --git a/test/completion-terminal.test.js b/test/completion-terminal.test.js
new file mode 100644
index 0000000..eb231d3
--- /dev/null
+++ b/test/completion-terminal.test.js
@@ -0,0 +1,89 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { callLlm, generateDiff } from '../src/index.js';
+
+const frame = (data) => `data: ${JSON.stringify(data)}\n\n`;
+function response(chunks, failure, cancel) {
+  let index = 0;
+  const state = { cancelled: 0, released: 0 };
+  const reader = {
+    async read() {
+      if (index < chunks.length) return { value: new TextEncoder().encode(chunks[index++]), done: false };
+      if (failure) throw failure;
+      return { done: true };
+    },
+    async cancel() { state.cancelled += 1; return cancel?.(); },
+    releaseLock() { state.released += 1; },
+  };
+  return { state, value: { ok: true, status: 200, headers: new Headers(), body: { getReader: () => reader } } };
+}
+const options = { apiKey: 'test-key', model: 'test-model', messages: [{ role: 'user', content: 'edit' }] };
+
+test('EOF before a terminal event rejects a usable diff prefix without replaying the request', async () => {
+  const partial = '```diff\n--- a/a.txt\n+++ b/a.txt\n@@ -1 +1 @@\n-old\n+new\n```';
+  const stream = response([frame({ choices: [{ delta: { content: partial } }] })]);
+  let requests = 0;
+  await assert.rejects(generateDiff('two files', 'change both files', {
+    ...options, onToken() {},
+    callLlm: (req) => callLlm({ ...req, fetchImpl: async () => { requests += 1; return stream.value; } }),
+  }), { name: 'IncompleteCompletionError' });
+  assert.equal(requests, 1);
+  assert.deepEqual(stream.state, { cancelled: 1, released: 1 });
+});
+
+test('a terminal stop reason permits EOF-only providers and keeps the final usage', async () => {
+  const stream = response([
+    frame({ choices: [{ delta: { content: 'complete' } }] }),
+    // Deliberately no final blank line or [DONE].
+    'data: ' + JSON.stringify({ choices: [{ delta: {}, finish_reason: 'stop' }], usage: { total_tokens: 7 } }),
+  ]);
+  const result = await callLlm({ ...options, onToken() {}, fetchImpl: async () => stream.value });
+  assert.equal(result.choices[0].message.content, 'complete');
+  assert.equal(result.usage.total_tokens, 7);
+  assert.deepEqual(stream.state, { cancelled: 1, released: 1 });
+});
+
+test('[DONE] completes legacy compatible streams without reading another chunk', async () => {
+  const stream = response([frame({ choices: [{ delta: { content: 'complete' } }] }) + 'data: [DONE]\n\n'], new Error('must not read past DONE'));
+  const result = await callLlm({ ...options, onToken() {}, fetchImpl: async () => stream.value });
+  assert.equal(result.choices[0].message.content, 'complete');
+  assert.deepEqual(stream.state, { cancelled: 1, released: 1 });
+});
+
+for (const reason of ['length', 'content_filter']) {
+  test(`explicit ${reason} is incomplete even when followed by DONE`, async () => {
+    const stream = response([frame({ choices: [{ delta: { content: 'prefix' }, finish_reason: reason }] }) + 'data: [DONE]\n\n']);
+    await assert.rejects(callLlm({ ...options, onToken() {}, fetchImpl: async () => stream.value }), { name: 'IncompleteCompletionError' });
+    assert.deepEqual(stream.state, { cancelled: 1, released: 1 });
+  });
+  test(`non-streaming ${reason} is not passed off as a complete answer`, async () => {
+    await assert.rejects(callLlm({ ...options, fetchImpl: async () => Response.json({
+      choices: [{ message: { content: 'prefix' }, finish_reason: reason }],
+    }) }), { name: 'IncompleteCompletionError' });
+  });
+}
+
+test('reader interruption propagates without retry and releases the response', async () => {
+  const aborted = new DOMException('cancelled', 'AbortError');
+  const stream = response([frame({ choices: [{ delta: { content: 'prefix' } }] })], aborted);
+  let requests = 0;
+  await assert.rejects(callLlm({ ...options, onToken() {}, fetchImpl: async () => { requests += 1; return stream.value; } }), (error) => error === aborted);
+  assert.equal(requests, 1);
+  assert.deepEqual(stream.state, { cancelled: 1, released: 1 });
+});
+
+test('a throwing token consumer still cancels and releases the response', async () => {
+  const stream = response([frame({ choices: [{ delta: { content: 'prefix' } }] })]);
+  await assert.rejects(callLlm({ ...options, onToken() { throw new Error('consumer failed'); }, fetchImpl: async () => stream.value }), /consumer failed/);
+  assert.deepEqual(stream.state, { cancelled: 1, released: 1 });
+});
+
+for (const complete of [true, false]) {
+  test(`stalled transport cancellation does not delay ${complete ? 'completion' : 'incomplete-stream rejection'}`, { timeout: 1000 }, async () => {
+    const stream = response([frame({ choices: [{ delta: { content: 'prefix' } }] }) + (complete ? 'data: [DONE]\n\n' : '')], null, () => new Promise(() => {}));
+    const pending = callLlm({ ...options, onToken() {}, fetchImpl: async () => stream.value });
+    if (complete) assert.equal((await pending).choices[0].message.content, 'prefix');
+    else await assert.rejects(pending, { name: 'IncompleteCompletionError' });
+    assert.deepEqual(stream.state, { cancelled: 1, released: 1 });
+  });
+}
diff --git a/test/demo-models.test.js b/test/demo-models.test.js
index bfd565b..31f01ab 100644
--- a/test/demo-models.test.js
+++ b/test/demo-models.test.js
@@ -44,7 +44,7 @@ test('landing picker retains creation dates and ranks the newer flagship first',
     DEFAULT_MODEL: defaults.DEFAULT_MODEL, MODEL: defaults.DEFAULT_MODEL,
     localStorage: { setItem() {} }, $: () => ({}), getKey: () => null,
     renderFilterModelRow() {},
-    fetch: async () => ({ json: async () => ({ data: [
+    fetch: async () => ({ ok: true, json: async () => ({ data: [
       { id: 'google/gemini-3-pro', created: 20 },
       { id: 'google/gemini-2-pro', created: 10 },
     ] }) }),
diff --git a/test/landing-state.test.js b/test/landing-state.test.js
new file mode 100644
index 0000000..aaecef7
--- /dev/null
+++ b/test/landing-state.test.js
@@ -0,0 +1,114 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { runInNewContext } from 'node:vm';
+
+const html = readFileSync(new URL('../landing/index.html', import.meta.url), 'utf8');
+const deferred = () => { let resolve; const promise = new Promise((done) => { resolve = done; }); return { promise, resolve }; };
+function ui() {
+  const elements = new Map();
+  const $ = (id) => {
+    if (!elements.has(id)) elements.set(id, { value: '', textContent: '', checked: false, style: {}, classList: { add() {} }, appendChild() {} });
+    return elements.get(id);
+  };
+  return { $, document: { querySelector: $ } };
+}
+function runHarness(mode) {
+  const elements = ui(), filtering = deferred(), generation = deferred(), genEntered = deferred();
+  const requests = [];
+  const context = {
+    ...elements, mode, scenarioKey: 'sample', SCENARIOS: { sample: { files: { a: 'original' }, goal: 'recorded goal', reveal: 'recorded explanation' } },
+    files: { a: 'original' }, FILTER_MODEL: 'classifier', MODEL: 'initial-diff', APPLY_MODEL: 'initial-apply',
+    beginRun: () => 1, isCurrentRun: () => true, priceOf: () => null, renderRun() {},
+    renderEditors() {}, renderPreview() {}, getKey: () => 'test-key',
+    collectDecisions: async () => { await filtering.promise; return []; },
+    makeFakeCallLlm: () => async () => {}, makeFakeApply: () => async () => {},
+    callLlm: async () => {},
+    callLlmForApply: (_path, _original, _patch, _model, opts) => { requests.push(['strict-apply', opts.callLlm]); },
+    generateDiff: async (_env, _goal, opts) => { requests.push(['generate', opts]); genEntered.resolve(); await generation.promise; return 'diff'; },
+    smartapply: async (_diff, _files, opts) => { requests.push(['apply', opts]); return { a: 'updated' }; },
+    buildEnvironment: (files) => files, filesForDiff: (files) => files,
+    renderDiff() {}, parseDiffPerFile: () => [['a', 'diff']],
+    fileCard: () => ({ ...elements.$('card'), querySelector: elements.$ }),
+    renderVerdict: (...args) => { requests.push(['verdict', args[6]]); },
+    formatClassifierCost: () => '', setBadge() {}, resultMsg(message) { throw new Error(message); },
+  };
+  elements.$('goal').value = 'custom goal'; elements.$('filteron').checked = true;
+  const runBody = html.match(/async function run\(\) \{[^]*?\n\}/)[0];
+  const setMode = html.match(/function setMode\(m\) \{[^]*?\n\}/)[0];
+  const api = runInNewContext(`${setMode}\n${runBody}\n({ run, setMode })`, context);
+  return { context, elements, api, filtering, generation, genEntered, requests };
+}
+
+for (const mode of ['real', 'demo']) {
+  test(`${mode} run keeps its original mode and models across filtering/generation`, async () => {
+    const h = runHarness(mode), pending = h.api.run();
+    h.api.setMode(mode === 'real' ? 'demo' : 'real');
+    h.context.MODEL = 'later-diff'; h.context.APPLY_MODEL = 'later-apply';
+    h.filtering.resolve(); await h.genEntered.promise;
+    h.api.setMode(mode); h.generation.resolve(); await pending;
+    const gen = h.requests.find(([kind]) => kind === 'generate')[1];
+    const apply = h.requests.find(([kind]) => kind === 'apply')[1];
+    if (mode === 'real') {
+      assert.equal(gen.apiKey, 'test-key'); assert.equal(gen.model, 'initial-diff');
+      assert.equal(apply.apiKey, 'test-key'); assert.equal(apply.model, 'initial-apply');
+      assert.equal(gen.callLlm, h.context.callLlm);
+      apply.callLlmForApply('a', 'original', 'diff', 'initial-apply', {});
+      assert.equal(h.requests.find(([kind]) => kind === 'strict-apply')[1], h.context.callLlm);
+    } else {
+      assert.equal(typeof gen.callLlm, 'function'); assert.equal(typeof apply.callLlmForApply, 'function');
+      assert.equal(gen.apiKey, undefined); assert.equal(apply.apiKey, undefined);
+    }
+    assert.equal(h.requests.find(([kind]) => kind === 'verdict')[1], mode);
+    assert.equal(h.context.files.a, 'updated');
+  });
+}
+
+function picker(fetch) {
+  const elements = ui(); let key = '';
+  const block = html.slice(html.indexOf('let allModels ='), html.indexOf('function modelButton'));
+  const api = runInNewContext(`${block}\n({ loadModels, invalidateModels })`, {
+    ...elements, DEFAULT_MODEL: 'fallback', MODEL: 'fallback',
+    localStorage: { setItem() {} }, getKey: () => key, renderFilterModelRow() {}, fetch,
+  });
+  return { ...api, ...elements, setKey: (value) => { key = value; api.invalidateModels(); } };
+}
+const catalog = (id) => ({ ok: true, json: async () => ({ data: [{ id }] }) });
+
+for (const failure of ['offline', 'http', 'empty']) {
+  test(`catalog recovers on the next request after ${failure}`, async () => {
+    let requests = 0;
+    const api = picker(async () => {
+      requests += 1;
+      if (requests > 1) return catalog('recovered');
+      if (failure === 'offline') throw new Error('offline');
+      if (failure === 'http') return { ok: false };
+      return { ok: true, json: async () => ({ data: [] }) };
+    });
+    assert.equal((await api.loadModels())[0].id, 'fallback');
+    assert.equal((await api.loadModels())[0].id, 'recovered');
+    await api.loadModels(); assert.equal(requests, 2);
+  });
+}
+
+test('concurrent opens share a request, and a late old-account result cannot replace a new one', async () => {
+  const first = deferred(); let requests = 0;
+  const api = picker(async () => { requests += 1; return requests === 1 ? first.promise : catalog('new-account'); });
+  const old = api.loadModels(), duplicate = api.loadModels();
+  assert.equal(requests, 1);
+  for (const prefix of ['model', 'filtermodel']) {
+    api.$(prefix + 'picker').style.display = 'block';
+    api.$(prefix + 'list').innerHTML = 'old-account buttons';
+    api.$(prefix + 'count').textContent = 'old count';
+  }
+  api.setKey('new-key');
+  for (const prefix of ['model', 'filtermodel']) {
+    assert.equal(api.$(prefix + 'picker').style.display, 'none');
+    assert.equal(api.$(prefix + 'list').innerHTML, '');
+    assert.equal(api.$(prefix + 'count').textContent, '');
+  }
+  assert.equal((await api.loadModels())[0].id, 'new-account');
+  first.resolve(catalog('old-account')); await Promise.all([old, duplicate]);
+  assert.equal((await api.loadModels())[0].id, 'new-account');
+  assert.equal(requests, 2);
+});