claude-teammate 0.1.304 → 0.1.306

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-teammate",
-  "version": "0.1.304",
+  "version": "0.1.306",
   "description": "CLI bootstrapper for Claude Teammate.",
   "license": "MIT",
   "type": "module",

package/src/claude/process.js

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
 
 const CHILD_CLEANUP_WAIT_MS = 1_000;
-const CLAUDE_MAX_ATTEMPTS = 1;
+const CLAUDE_MAX_ATTEMPTS = 3;
+const CLAUDE_RETRY_BASE_DELAY_MS = 2_000;
 const DEFAULT_CLAUDE_PERMISSION_MODE = "bypassPermissions";
 
 export class ClaudeCliError extends Error {
@@ -53,8 +54,44 @@ export function formatClaudeInvocationError(error, timeoutMs) {
   return `Claude CLI invocation failed${timeout ? ` after ${timeoutMs}ms` : ""}${signal ? ` (${signal})` : ""}${codeFragment}${details ? `: ${details}` : "."}`;
 }
 
-export function shouldRetryClaudeCommand(options = {}, attempt) {
-  return !options.noRetry && attempt < CLAUDE_MAX_ATTEMPTS;
+// Resource/transport failures that a fresh attempt can plausibly clear:
+// fork failures under VM load (EAGAIN/ENOMEM/ENFILE/EMFILE), OOM-kills
+// (SIGKILL), and timeouts. Deterministic failures must NOT retry: a usage
+// limit, an over-long prompt, or a clean non-zero exit (a logic/permission
+// error from a CLI that actually ran) will fail again identically and just
+// burn quota.
+const TRANSIENT_SPAWN_ERRNOS = new Set(["EAGAIN", "ENOMEM", "ENFILE", "EMFILE", "ECONNRESET", "ETIMEDOUT"]);
+
+export function isTransientClaudeError(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  if (error.hitUsageLimit || error.promptTooLong) {
+    return false;
+  }
+  if (error.killed) {
+    return true;
+  }
+  if (typeof error.code === "string" && TRANSIENT_SPAWN_ERRNOS.has(error.code)) {
+    return true;
+  }
+  // External SIGKILL with no captured output is the classic OOM-killer
+  // signature; SIGTERM here is our own maxBuffer/limit kill and is handled
+  // by the flags above, so only treat SIGKILL as transient.
+  if (error.signal === "SIGKILL") {
+    return true;
+  }
+  return false;
+}
+
+export function shouldRetryClaudeCommand(options = {}, attempt, error) {
+  return !options.noRetry && attempt < CLAUDE_MAX_ATTEMPTS && isTransientClaudeError(error);
+}
+
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
 }
 
 export async function runClaudeCommand(command, args, options) {
@@ -62,9 +99,13 @@ export async function runClaudeCommand(command, args, options) {
     try {
       return await runClaudeCommandOnce(command, args, options);
     } catch (error) {
-      if (!shouldRetryClaudeCommand(options, attempt)) {
+      if (!shouldRetryClaudeCommand(options, attempt, error)) {
         throw error;
       }
+      options.onRetry?.({ attempt, error });
+      // Exponential backoff so a transient spike (fork storm, OOM) gets a
+      // moment to subside before the next attempt.
+      await delay(CLAUDE_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1));
     }
   }
 }

package/src/claude/prompts.js

@@ -1,5 +1,28 @@
 import { formatAdditionalRepoPaths } from "./paths.js";
 
+// Re-ground a re-invoked implementation run on what an earlier run already did.
+// Both fields are optional; when neither is present this contributes nothing so
+// first runs are unchanged. The diff is truncated by the caller to stay within
+// the prompt budget.
+function formatPriorWorkContext(input) {
+  const sections = [];
+  const priorSummary = String(input.priorSummary || "").trim();
+  if (priorSummary) {
+    sections.push(`\nPrior run summary (what you reported last time):\n${priorSummary}`);
+  }
+  const branchDiff = String(input.branchDiff || "").trim();
+  if (branchDiff) {
+    sections.push(`\nWork already done on this branch (diff vs base):\n${branchDiff}`);
+  }
+  if (sections.length === 0) {
+    return "";
+  }
+  sections.push(
+    "\nBuild on the work above; do not redo or revert changes that already satisfy the plan unless the latest comment asks for it."
+  );
+  return `${sections.join("\n")}\n`;
+}
+
 const INCLUDE_RESOURCE_LINKS_RULE =
   "When your response is posted as a comment on a Jira issue, GitHub issue, or GitHub PR, include the URL of every resource you created (e.g. Jira task, spreadsheet, test design, test cases, document, Confluence page) so the reader can navigate directly to it.";
 
@@ -353,7 +376,7 @@ ${input.latestComment?.body || "(none)"}
 
 Recent PR comments:
 ${recentComments || "(none)"}
-
+${formatPriorWorkContext(input)}
 Instructions:
 - Checkout the branch above in this repository.
 - Implement the plan described in the pull request body.
@@ -469,7 +492,7 @@ ${JSON.stringify(input.memory?.epic || {}, null, 2)}
 
 Step to implement:
 ${input.step}
-
+${formatPriorWorkContext(input)}
 Instructions:
 - Checkout the branch above in this repository.
 - Implement only the step described above. Do not implement other parts of the plan.

package/src/claude/stream.js

@@ -26,6 +26,24 @@ export function formatStreamEvent(event) {
   }
 }
 
+// Pull the Claude session id out of stream-json events so the caller can
+// persist it and resume the same conversation on a later run (e.g. when a
+// developer comments on the PR). Both `system` (init) and `result` events
+// carry session_id; the last one wins.
+export function extractSessionId(lines) {
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    try {
+      const event = JSON.parse(lines[i]);
+      if (event && typeof event.session_id === "string" && event.session_id) {
+        return event.session_id;
+      }
+    } catch {
+      // skip non-JSON lines
+    }
+  }
+  return "";
+}
+
 export function extractResultFromStreamJson(lines) {
   for (let i = lines.length - 1; i >= 0; i--) {
     try {
@@ -40,13 +58,79 @@ export function extractResultFromStreamJson(lines) {
   throw new Error("No result event found in stream-json output.");
 }
 
+function tryParseJson(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+// Recover a JSON object/array embedded in prose or markdown fences. Claude
+// frequently wraps the requested JSON in ```json fences or surrounds it with a
+// sentence or two; previously any such non-strict output threw a raw
+// SyntaxError that crashed the whole task. We try a fenced block first, then
+// fall back to the first balanced {...} / [...] span.
+function extractEmbeddedJson(text) {
+  if (typeof text !== "string") {
+    return { ok: false };
+  }
+
+  const fence = text.match(/```(?:json)?\s*([[{][\s\S]*?[\]}])\s*```/iu);
+  if (fence) {
+    const parsed = tryParseJson(fence[1].trim());
+    if (parsed.ok) {
+      return parsed;
+    }
+  }
+
+  const start = text.search(/[[{]/u);
+  if (start !== -1) {
+    const open = text[start];
+    const close = open === "{" ? "}" : "]";
+    let depth = 0;
+    for (let i = start; i < text.length; i += 1) {
+      const ch = text[i];
+      if (ch === open) {
+        depth += 1;
+      } else if (ch === close) {
+        depth -= 1;
+        if (depth === 0) {
+          const parsed = tryParseJson(text.slice(start, i + 1));
+          if (parsed.ok) {
+            return parsed;
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  return { ok: false };
+}
+
+// Parse a string that is expected to be JSON, falling back to embedded-JSON
+// recovery. Throws a clear, catchable Error (never a raw SyntaxError) so the
+// caller can treat "model returned prose" as a normal task failure.
+function parseJsonOrRecover(text, label) {
+  const parsed = tryParseJson(text);
+  if (parsed.ok) {
+    return parsed.value;
+  }
+  const embedded = extractEmbeddedJson(text);
+  if (embedded.ok) {
+    return embedded.value;
+  }
+  throw new Error(`Claude CLI ${label} was not valid JSON: ${String(text).slice(0, 200)}`);
+}
+
 export function parseClaudeOutput(output) {
   const trimmed = output.trim();
   if (!trimmed) {
     throw new Error("Claude CLI returned empty output.");
   }
 
-  const direct = JSON.parse(trimmed);
+  const direct = parseJsonOrRecover(trimmed, "output");
   if (direct && typeof direct === "object") {
     if ("structured_output" in direct && direct.structured_output && typeof direct.structured_output === "object") {
       return direct.structured_output;
@@ -83,11 +167,11 @@ export function parseClaudeOutput(output) {
     }
 
     if ("result" in direct && typeof direct.result === "string") {
-      return JSON.parse(direct.result);
+      return parseJsonOrRecover(direct.result, "result");
     }
 
     if ("content" in direct && typeof direct.content === "string") {
-      return JSON.parse(direct.content);
+      return parseJsonOrRecover(direct.content, "content");
     }
   }
 

package/src/claude.js

@@ -13,6 +13,7 @@ import {
   cleanupClaudeProcesses,
   formatClaudeInvocationError,
   isClaudeCliError,
+  isTransientClaudeError,
   resolveClaudePermissionMode,
   runClaudeCommand,
   shouldRetryClaudeCommand
@@ -45,7 +46,12 @@ import {
   buildSuggestionRevisionSystemPrompt,
   buildSuggestionRevisionUserPrompt
 } from "./claude/prompts.js";
-import { extractResultFromStreamJson, formatStreamEvent, parseClaudeOutput } from "./claude/stream.js";
+import {
+  extractResultFromStreamJson,
+  extractSessionId,
+  formatStreamEvent,
+  parseClaudeOutput
+} from "./claude/stream.js";
 import {
   validateClaudeResult,
   validateEpicMemoryCleanupResult,
@@ -76,6 +82,7 @@ export {
   hasPlaywrightMcpConfigured,
   isClaudeCliError,
   isHeadlessPlaywrightMcpConfig,
+  isTransientClaudeError,
   parseClaudeOutput,
   shouldRetryClaudeCommand
 };
@@ -380,10 +387,39 @@ const REPO_EXTRACTION_SCHEMA = {
   required: ["repos", "pr_repo_url"]
 };
 
+// A `--resume <id>` invocation failed specifically because the session could
+// not be loaded (worker moved hosts, local session store cleared, id stale).
+// Distinct from a real task failure so we only fall back to a fresh run for
+// the recoverable case.
+export function isResumeSessionError(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const text = `${error.stderr || ""}\n${error.stdout || ""}\n${error.message || ""}`.toLowerCase();
+  return (
+    text.includes("no conversation found") ||
+    text.includes("session not found") ||
+    text.includes("could not find session") ||
+    text.includes("no session") ||
+    (text.includes("resume") && text.includes("not found"))
+  );
+}
+
+function wrapClaudeCliError(error, timeoutMs) {
+  const cliError = new ClaudeCliError(formatClaudeInvocationError(error, timeoutMs));
+  if (error?.hitUsageLimit) {
+    cliError.hitUsageLimit = true;
+  }
+  if (error?.promptTooLong) {
+    cliError.promptTooLong = true;
+  }
+  return cliError;
+}
+
 async function invokeClaudeTask(schema, systemPrompt, userPrompt, opts = {}) {
   const { model, permissionMode, effort, extraArgs = [], validate, runOpts = {} } = opts;
 
-  const args = [
+  const baseArgs = [
     "--print",
     "--model",
     model || DEFAULT_MODEL,
@@ -400,14 +436,21 @@ async function invokeClaudeTask(schema, systemPrompt, userPrompt, opts = {}) {
     userPrompt
   ];
 
-  const { issueKey, logger, phase, epicContext, ...restRunOpts } = runOpts;
+  const { issueKey, logger, phase, epicContext, resumeSessionId, onSessionId, ...restRunOpts } = runOpts;
 
   // Always use stream-json so we have full event data for skill failure detection.
   const loggingEnabled = Boolean(issueKey && logger && typeof logger.issueLog === "function");
-  const effectiveArgs = buildStreamArgs(args);
+
+  // Resume the prior conversation when a session id is supplied so the model
+  // keeps its earlier context (e.g. responding to a PR comment). `--resume`
+  // is prepended; if it fails because the session is gone we fall back to a
+  // fresh run below so a stale id never permanently blocks the task.
+  const resumeId = String(resumeSessionId || "").trim();
+  const buildArgs = (withResume) =>
+    buildStreamArgs(withResume && resumeId ? ["--resume", resumeId, ...baseArgs] : baseArgs);
 
   const collectedLines = [];
-  const onData = (chunk) => {
+  const makeOnData = () => (chunk) => {
     const lines = String(chunk)
       .split("\n")
       .filter((l) => l.trim());
@@ -427,21 +470,40 @@ async function invokeClaudeTask(schema, systemPrompt, userPrompt, opts = {}) {
     }
   };
 
-  try {
-    await runClaudeCommand("claude", effectiveArgs, {
+  const runOnce = (withResume) => {
+    collectedLines.length = 0;
+    return runClaudeCommand("claude", buildArgs(withResume), {
       maxBuffer: 10 * 1024 * 1024,
       ...restRunOpts,
-      onData
+      onData: makeOnData()
     });
+  };
+
+  try {
+    await runOnce(Boolean(resumeId));
   } catch (error) {
-    const cliError = new ClaudeCliError(formatClaudeInvocationError(error, runOpts.timeout));
-    if (error?.hitUsageLimit) {
-      cliError.hitUsageLimit = true;
+    // A stale/missing session is recoverable: retry once from a clean slate.
+    if (resumeId && isResumeSessionError(error)) {
+      void logger?.info?.("Claude session resume failed; retrying without resume", { issueKey, phase });
+      try {
+        await runOnce(false);
+      } catch (retryError) {
+        throw wrapClaudeCliError(retryError, runOpts.timeout);
+      }
+    } else {
+      throw wrapClaudeCliError(error, runOpts.timeout);
     }
-    if (error?.promptTooLong) {
-      cliError.promptTooLong = true;
+  }
+
+  if (typeof onSessionId === "function") {
+    const sessionId = extractSessionId(collectedLines);
+    if (sessionId) {
+      try {
+        onSessionId(sessionId);
+      } catch {
+        // Persisting the session id is best-effort; never fail the task on it.
+      }
     }
-    throw cliError;
   }
 
   const outputToParse = extractResultFromStreamJson(collectedLines);
@@ -787,7 +849,9 @@ export async function runClaudeImplementation(input) {
         issueKey: input.issueKey,
         logger: input.logger,
         phase: "implementation",
-        epicContext: input.epicContext
+        epicContext: input.epicContext,
+        resumeSessionId: input.resumeSessionId,
+        onSessionId: input.onSessionId
       }
     }
   );
@@ -870,7 +934,9 @@ export async function runClaudeImplementationStep(input) {
         issueKey: input.issueKey,
         logger: input.logger,
         phase: "implementation-step",
-        epicContext: input.epicContext
+        epicContext: input.epicContext,
+        resumeSessionId: input.resumeSessionId,
+        onSessionId: input.onSessionId
       }
     }
   );

package/src/forge/gitlab.js

@@ -150,17 +150,17 @@ export function createGitLabClient(config) {
 
     async createIssueReaction(repoUrl, issueNumber, content = "eyes") {
       const repo = parseGitLabRepoUrl(repoUrl);
-      return requestGitLabProject(config, repo, `${issueNotePath(issueNumber)}/award_emoji`, {
-        method: "POST",
-        body: {
-          name: mapReaction(content)
-        }
-      });
+      return awardEmojiOnce(
+        config,
+        projectPath(repo, `${issueNotePath(issueNumber)}/award_emoji`),
+        `${repo.origin}/`,
+        mapReaction(content)
+      );
     },
 
     async createIssueCommentReaction(repoUrl, commentId, content = "eyes", issueNumber = "") {
       const repo = parseGitLabRepoUrl(repoUrl);
-      const body = { name: mapReaction(content) };
+      const name = mapReaction(content);
       const candidates = [
         projectPath(repo, `${mergeRequestNotePath(issueNumber)}/${commentId}/award_emoji`),
         projectPath(repo, `/issues/${issueNumber}/notes/${commentId}/award_emoji`)
@@ -169,15 +169,9 @@ export function createGitLabClient(config) {
       let lastError = null;
       for (const candidate of candidates) {
         try {
-          return await requestGitLab(config, candidate, {
-            baseUrl: `${repo.origin}/`,
-            method: "POST",
-            body
-          });
+          // Don't swallow 404 here: a wrong-kind path must fall through to the next candidate.
+          return await awardEmojiOnce(config, candidate, `${repo.origin}/`, name, { ignoreMissing: false });
         } catch (error) {
-          if (String(error?.message || "").includes("Award Emoji Name has already been taken")) {
-            return;
-          }
           lastError = error;
         }
       }
@@ -187,13 +181,12 @@ export function createGitLabClient(config) {
 
     async createPullRequestCommentReaction(repoUrl, commentId, content = "eyes", pullNumber = "") {
       const repo = parseGitLabRepoUrl(repoUrl);
-      return requestGitLab(config, projectPath(repo, `${mergeRequestNotePath(pullNumber)}/${commentId}/award_emoji`), {
-        baseUrl: `${repo.origin}/`,
-        method: "POST",
-        body: {
-          name: mapReaction(content)
-        }
-      });
+      return awardEmojiOnce(
+        config,
+        projectPath(repo, `${mergeRequestNotePath(pullNumber)}/${commentId}/award_emoji`),
+        `${repo.origin}/`,
+        mapReaction(content)
+      );
     },
 
     async isRepoCollaborator(repoUrl, username) {
@@ -544,11 +537,12 @@ export function createGitLabClient(config) {
 
     async addReactionToNote(repoUrl, prNumber, noteId, reaction = "eyes") {
       const repo = parseGitLabRepoUrl(repoUrl);
-      return requestGitLab(config, projectPath(repo, `/merge_requests/${prNumber}/notes/${noteId}/award_emoji`), {
-        baseUrl: `${repo.origin}/`,
-        method: "POST",
-        body: { name: mapReaction(reaction) }
-      });
+      return awardEmojiOnce(
+        config,
+        projectPath(repo, `/merge_requests/${prNumber}/notes/${noteId}/award_emoji`),
+        `${repo.origin}/`,
+        mapReaction(reaction)
+      );
     },
 
     async listAiReviewedPrs(repoUrl) {
@@ -1014,6 +1008,47 @@ function mapReaction(content) {
   }
 }
 
+async function findExistingAward(config, awardEmojiPath, baseUrl, name) {
+  // GitLab returns every award on the resource; reuse ours instead of re-POSTing each poll.
+  try {
+    const existing = await requestGitLab(config, awardEmojiPath, { baseUrl });
+    if (Array.isArray(existing)) {
+      return existing.find((emoji) => emoji?.name === name) || null;
+    }
+  } catch {
+    // List failed — fall through to POST, which still tolerates a duplicate.
+  }
+  return null;
+}
+
+function isAwardEmojiDuplicate(error) {
+  return String(error?.message || "").includes("has already been taken");
+}
+
+function isMissingResource(error) {
+  return error?.statusCode === 404 || /failed with 404\b/u.test(String(error?.message || ""));
+}
+
+// Idempotent award: skip when ours already exists, swallow the duplicate race,
+// and (for single-path callers) treat a deleted resource as a no-op success.
+async function awardEmojiOnce(config, awardEmojiPath, baseUrl, name, { ignoreMissing = true } = {}) {
+  const found = await findExistingAward(config, awardEmojiPath, baseUrl, name);
+  if (found) {
+    return found;
+  }
+  try {
+    return await requestGitLab(config, awardEmojiPath, { baseUrl, method: "POST", body: { name } });
+  } catch (error) {
+    if (isAwardEmojiDuplicate(error)) {
+      return {};
+    }
+    if (ignoreMissing && isMissingResource(error)) {
+      return {};
+    }
+    throw error;
+  }
+}
+
 async function requestGitLab(config, pathOrUrl, init = {}) {
   const url = pathOrUrl.startsWith("http")
     ? new URL(pathOrUrl)
@@ -1050,7 +1085,9 @@ async function requestGitLab(config, pathOrUrl, init = {}) {
       authError.statusCode = response.status;
       throw authError;
     }
-    throw new Error(buildGitLabRequestError(response.status, url, body));
+    const requestError = new Error(buildGitLabRequestError(response.status, url, body));
+    requestError.statusCode = response.status;
+    throw requestError;
   }
 
   if (response.status === 204) {

package/src/forge/repo-host.js

@@ -2,6 +2,22 @@ import process from "node:process";
 
 const GITHUB_HOST = "github.com";
 
+// Path segments that mark a URL as something other than a repo root: forge
+// sub-pages (blob/tree/pull/merge_requests/…) and auth/account endpoints
+// (sign_in/users/…). Matched as a whole path component (slash-delimited).
+const NON_REPO_PATHS =
+  /\/(?:blob|tree|raw|actions|issues|pull|commit|releases|compare|discussions|wiki|tags|branches|security|pulse|graphs|settings|merge_requests|pipelines|environments|packages|network|activity|sign_in|sign_up|users|sessions|oauth|-)\//u;
+// GitLab uses /-/ as a separator before sub-paths (e.g. /-/merge_requests/12).
+const GITLAB_SUBPATH = /\/-\//u;
+
+// True when a URL path is NOT a plain `owner/repo` root. Used both to filter
+// discovered URLs and (authoritatively) inside parseRepoParts so a junk URL
+// can never be turned into a clone target.
+export function isNonRepoPath(pathOrUrl) {
+  const probe = `/${String(pathOrUrl || "").replace(/^\/+/u, "")}/`;
+  return NON_REPO_PATHS.test(probe) || GITLAB_SUBPATH.test(probe);
+}
+
 export function parseRepoUrl(repoUrl) {
   const value = String(repoUrl || "").trim();
   if (!value) {
@@ -101,12 +117,8 @@ export function extractRepoUrls(text) {
     return [];
   }
 
-  // Filter out URLs that are not repo roots (e.g. blob, tree, actions, issues, pull, commit paths)
-  const NON_REPO_PATHS =
-    /\/(?:blob|tree|raw|actions|issues|pull|commit|releases|compare|discussions|wiki|tags|branches|security|pulse|graphs|settings|merge_requests|pipelines|environments|packages|network|activity)\//u;
-  // GitLab uses /-/ as a separator before sub-paths (e.g. /-/merge_requests/12, /-/issues/5)
-  const GITLAB_SUBPATH = /\/-\//u;
-  const repoUrls = matches.filter((url) => !NON_REPO_PATHS.test(url) && !GITLAB_SUBPATH.test(url));
+  // Filter out URLs that are not repo roots (blob/tree/issues/merge_requests/…)
+  const repoUrls = matches.filter((url) => !isNonRepoPath(url));
 
   return [...new Set(repoUrls)];
 }
@@ -116,6 +128,14 @@ function parseRepoParts(host, rawPath) {
   const cleanPath = String(rawPath || "")
     .replace(/\.git$/u, "")
     .replace(/\/+$/u, "");
+
+  // Single source of truth: reject MR/issue/auth/redirect paths here so a junk
+  // URL reaching parseRepoUrl by any route can never be built into a bogus
+  // clone target (e.g. `.../-/merge_requests/15.git`, `.../users/sign_in.git`).
+  if (isNonRepoPath(cleanPath)) {
+    throw new Error(`Not a ${getProviderLabel(provider)} repo URL (sub-page or auth path): ${rawPath}`);
+  }
+
   const segments = cleanPath.split("/").filter(Boolean);
 
   if (segments.length < 2) {

package/src/fs-atomic.js

@@ -0,0 +1,23 @@
+import { rename, writeFile } from "node:fs/promises";
+
+// Monotonic per-process counter so two writes from the same process never
+// share a temp path, even within the same millisecond.
+let tempCounter = 0;
+
+// Build a temp path that is unique per process + call. Concurrent writers
+// (same process or two worker processes) each rename their own temp file onto
+// the target, so the rename can never hit ENOENT from another writer having
+// already consumed a shared `<file>.tmp`.
+export function buildTempPath(filePath) {
+  tempCounter = (tempCounter + 1) % Number.MAX_SAFE_INTEGER;
+  return `${filePath}.${process.pid}.${tempCounter}.tmp`;
+}
+
+// Atomically write `content` to `filePath`: write to a unique temp file then
+// rename onto the target. The rename is atomic on POSIX, so readers always see
+// either the old or the new complete file, never a partial write.
+export async function atomicWriteFile(filePath, content) {
+  const tempFile = buildTempPath(filePath);
+  await writeFile(tempFile, content, "utf8");
+  await rename(tempFile, filePath);
+}