@cairnkeep/cli 2.22.3 → 2.22.4

package/omp/extensions/cairnkeep-capture.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
 import { join } from "node:path";
 
 // omp port of the claude/hooks memory-capture + memory-wakeup pair (D-03/D-04,
@@ -25,6 +26,7 @@ import { join } from "node:path";
 // Fail-open everywhere: every guard is a cheap check and every path is
 // try/caught so a throw can never reach the extension runner.
 const CAIRN_ROOT = "@@INFRA_ROOT@@";
+const { readStableText } = createRequire(import.meta.url)(join(CAIRN_ROOT, "scripts", "lib", "stable-file.mjs"));
 const SERVER_ENTRY = join(CAIRN_ROOT, "mcp-memory-server", "dist", "index.js");
 const STAGE_ENTRY = join(CAIRN_ROOT, "scripts", "lib", "omp-capture-stage.mjs");
 
@@ -87,21 +89,36 @@ type StagedCandidate = {
 
 // Bounded staged-candidate scan: the STAGED_MAX_FILES most recent *.json
 // files, each read capped, malformed JSON skipped (fail-open).
-function stagedCandidates(repo: string): StagedCandidate[] {
+function stagedFiles(repo: string): string[] {
+    const planning = join(repo, ".planning");
     const stagingDir = join(repo, ".planning", "memory-staging");
-    if (!existsSync(stagingDir)) return [];
-    const files = readdirSync(stagingDir)
-        .filter((name) => name.endsWith(".json"))
-        .map((name) => ({ name, mtime: statSync(join(stagingDir, name)).mtimeMs }))
-        .sort((a, b) => b.mtime - a.mtime)
+    try {
+        for (const path of [planning, stagingDir]) {
+            const info = lstatSync(path);
+            if (!info.isDirectory() || info.isSymbolicLink()) return [];
+        }
+    } catch { return []; }
+    return readdirSync(stagingDir)
+        .filter((name) => /^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/.test(name))
+        .flatMap((name) => {
+            try {
+                const info = lstatSync(join(stagingDir, name));
+                return info.isFile() && !info.isSymbolicLink() && info.size <= STAGED_FILE_READ_CAP
+                    ? [{ name, mtime: info.mtimeMs }] : [];
+            } catch { return []; }
+        })
+        .sort((a, b) => b.mtime - a.mtime || a.name.localeCompare(b.name, "en"))
         .slice(0, STAGED_MAX_FILES)
         .map(({ name }) => name);
+}
+
+function stagedCandidates(repo: string): StagedCandidate[] {
+    const stagingDir = join(repo, ".planning", "memory-staging");
     const staged: StagedCandidate[] = [];
-    for (const file of files) {
+    for (const file of stagedFiles(repo)) {
         try {
             const path = join(stagingDir, file);
-            if (statSync(path).size > STAGED_FILE_READ_CAP) continue;
-            const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+            const parsed: unknown = JSON.parse(readStableText(path, { label: "Staged candidate", maxBytes: STAGED_FILE_READ_CAP }).text);
             const count = Array.isArray((parsed as { candidates?: unknown })?.candidates)
                 ? ((parsed as { candidates: unknown[] }).candidates.length)
                 : 0;
@@ -197,12 +214,7 @@ export default function cairnCaptureExtension(pi: ExtensionAPI): void {
                     if (ctx.hasUI) ctx.ui.notify("No staged memory candidates (.planning/memory-staging is absent).", "info");
                     return;
                 }
-                const files = readdirSync(stagingDir)
-                    .filter((name) => name.endsWith(".json"))
-                    .map((name) => ({ name, mtime: statSync(join(stagingDir, name)).mtimeMs }))
-                    .sort((a, b) => b.mtime - a.mtime)
-                    .slice(0, STAGED_MAX_FILES)
-                    .map(({ name }) => name);
+                const files = stagedFiles(ctx.cwd);
                 if (files.length === 0) {
                     if (ctx.hasUI) ctx.ui.notify("No staged memory candidates.", "info");
                     return;
@@ -210,7 +222,7 @@ export default function cairnCaptureExtension(pi: ExtensionAPI): void {
                 const sections = files.map((file) => {
                     let body: string;
                     try {
-                        body = readFileSync(join(stagingDir, file), "utf8").slice(0, STAGED_FILE_READ_CAP);
+                        body = readStableText(join(stagingDir, file), { label: "Staged candidate", maxBytes: STAGED_FILE_READ_CAP }).text;
                     } catch {
                         body = "(unreadable)";
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cairnkeep/cli",
-    "version": "2.22.3",
+    "version": "2.22.4",
     "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
     "license": "Apache-2.0",
     "type": "module",

package/scripts/lib/opencode-v2-plugin-harness.mjs

@@ -76,6 +76,9 @@ await beforeHook({ ...editEvent, tool: "read", input: { filePath: join(repo, "ot
 
 const now = Date.now();
 let subscribed = false;
+let streamFinished = false;
+let finishStream;
+const streamCompletion = new Promise((resolve) => { finishStream = resolve; });
 const captureContext = {
   location: { directory: repo },
   event: {
@@ -84,6 +87,11 @@ const captureContext = {
       assert.equal(signal instanceof AbortSignal, true);
       yield { type: "session.compacted", data: { sessionID: "v2-session" } };
       yield { type: "session.idle", data: { sessionID: "v2-session" } };
+      // File creation is not capture completion. Keep that distinction
+      // deterministic even when the child writer is unusually fast.
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      streamFinished = true;
+      finishStream();
     },
   },
   session: {
@@ -125,10 +133,19 @@ const captureContext = {
 const cleanup = await capture.default.setup(captureContext);
 assert.equal(typeof cleanup, "function");
 const db = join(repo, ".agentfs", "trajectory.db");
-for (let attempt = 0; attempt < 100 && !existsSync(db); attempt += 1) {
-  await new Promise((resolve) => setTimeout(resolve, 25));
+let completionTimer;
+try {
+  await Promise.race([
+    streamCompletion,
+    new Promise((_resolve, reject) => {
+      completionTimer = setTimeout(() => reject(new Error("V2 fixture capture did not complete within eight seconds")), 8000);
+    }),
+  ]);
+} finally {
+  clearTimeout(completionTimer);
+  cleanup();
 }
-cleanup();
+assert.equal(streamFinished, true, "fixture readers must wait for completed capture, not database creation");
 assert.equal(subscribed, true, "V2 capture must subscribe to the public event stream");
 assert.equal(existsSync(db), true, "V2 idle event must create a trajectory record");
 

package/scripts/lib/stable-file.mjs

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import { dirname } from "node:path";
+
+function sameFile(left, right) {
+  return right.isFile() && !right.isSymbolicLink()
+    && left.dev === right.dev && left.ino === right.ino && left.size === right.size
+    && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs
+    && left.uid === right.uid && left.gid === right.gid && left.mode === right.mode;
+}
+
+// Recheck an already descriptor-inspected mutation target. This is a
+// point-in-time guard, not an operating-system compare-and-swap primitive.
+export function assertFileUnchanged(path, expected, label) {
+  try {
+    const named = fs.lstatSync(path);
+    if (expected && sameFile(expected, named)) return;
+  } catch (error) {
+    if (!expected && error?.code === "ENOENT") return;
+  }
+  throw new Error(`${label} changed or is unsafe before publication.`);
+}
+
+// Bootstrap utilities must work before the TypeScript server has been built.
+// Keep the descriptor-first contract aligned with src/stable-file.ts.
+export function readStableFile(path, { label, maxBytes, privateMode, nonExecutable = false }) {
+  let descriptor;
+  try {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error();
+    descriptor = fs.openSync(path, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)
+      | (fs.constants.O_NOCTTY ?? 0) | (process.platform === "win32" ? 0 : fs.constants.O_NONBLOCK ?? 0));
+    const opened = fs.fstatSync(descriptor);
+    if (!opened.isFile() || opened.size > maxBytes) throw new Error();
+    if (process.platform !== "win32") {
+      if (nonExecutable && (opened.mode & 0o111) !== 0) throw new Error(`${label} has an unsafe executable mode.`);
+      if (privateMode !== undefined && ((opened.mode & 0o777) !== privateMode
+          || (typeof process.getuid === "function" && opened.uid !== process.getuid() && opened.uid !== 0))) throw new Error();
+    }
+    const parent = fs.lstatSync(dirname(path));
+    const named = fs.lstatSync(path);
+    if (named.isSymbolicLink() || parent.isSymbolicLink()) throw new Error(`${label} crosses a symlink.`);
+    if (!parent.isDirectory() || !sameFile(opened, named)) throw new Error();
+    const buffer = Buffer.allocUnsafe(opened.size + 1);
+    let offset = 0;
+    while (offset < buffer.byteLength) {
+      const count = fs.readSync(descriptor, buffer, offset, buffer.byteLength - offset, null);
+      if (count === 0) break;
+      offset += count;
+    }
+    const after = fs.fstatSync(descriptor);
+    const parentAfter = fs.lstatSync(dirname(path));
+    if (!sameFile(opened, after) || offset !== opened.size
+        || !parentAfter.isDirectory() || parentAfter.isSymbolicLink()
+        || parent.dev !== parentAfter.dev || parent.ino !== parentAfter.ino
+        || !sameFile(opened, fs.lstatSync(path))) throw new Error();
+    return { bytes: buffer.subarray(0, offset), stat: opened };
+  } catch (error) {
+    if (error instanceof Error && [`${label} crosses a symlink.`, `${label} has an unsafe executable mode.`].includes(error.message)) throw error;
+    if (error?.code === "ELOOP") throw new Error(`${label} crosses a symlink.`);
+    throw new Error(`${label} is unsafe, changed or unreadable.`);
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+export function readStableText(path, options) {
+  const { bytes, stat } = readStableFile(path, options);
+  try { return { text: new TextDecoder("utf-8", { fatal: true }).decode(bytes), stat }; }
+  catch { throw new Error(`${options.label} contains invalid UTF-8.`); }
+}
+
+export function readStableJson(path, options) {
+  const { text } = readStableText(path, options);
+  try { return JSON.parse(text); }
+  catch { throw new Error(`${options.label} contains invalid JSON.`); }
+}

package/scripts/playbook-instructions.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { randomBytes } from "node:crypto";
-import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, fchmodSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, constants } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { readStableText, assertFileUnchanged } from "./lib/stable-file.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATE = join(ROOT, "templates", "playbook-agent-instructions.md.template");
@@ -11,17 +12,21 @@ const END = "<!-- cairnkeep:playbook:v1:end -->";
 const MAX_BYTES = 1024 * 1024;
 
 function safeRead(path) {
-  const info = lstatSync(path);
-  if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_BYTES) throw new Error("AGENTS.md is not a safe bounded regular file.");
-  let descriptor;
-  try {
-    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-    const opened = fstatSync(descriptor);
-    if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.size > MAX_BYTES) throw new Error("AGENTS.md changed during validation.");
-    return { text: readFileSync(descriptor, "utf8"), mode: info.mode & 0o777 };
-  } finally {
-    if (descriptor !== undefined) closeSync(descriptor);
+  const { text, stat } = readStableText(path, { label: "AGENTS.md", maxBytes: MAX_BYTES });
+  return { text, mode: stat.mode & 0o777, stat };
+}
+
+function safeRoot(projectRoot, allowMissing = false) {
+  const root = resolve(projectRoot);
+  let info;
+  try { info = lstatSync(root); }
+  catch (error) {
+    // Planning a new project must remain read-only before setup creates it.
+    if (allowMissing && error?.code === "ENOENT") return root;
+    throw error;
   }
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Playbook project directory is unsafe.");
+  return root;
 }
 
 function count(text, marker) {
@@ -50,38 +55,55 @@ function removeBlock(current) {
   return `${current.slice(0, start)}${current.slice(end + END.length)}`.replace(/\n{3,}/g, "\n\n").trimEnd();
 }
 
-function atomicWrite(path, text, mode) {
+function atomicWrite(path, text, mode, expected = null) {
+  const parent = lstatSync(dirname(path));
+  if (!parent.isDirectory() || parent.isSymbolicLink()) throw new Error("Instruction publication parent is unsafe.");
   const temporary = join(dirname(path), `.AGENTS.md.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+  let descriptor;
+  let ownsTemporary = false;
   try {
-    writeFileSync(temporary, text, { encoding: "utf8", mode, flag: "wx" });
-    renameSync(temporary, path);
+    descriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), mode);
+    ownsTemporary = true;
+    writeFileSync(descriptor, text, { encoding: "utf8" });
+    fchmodSync(descriptor, mode);
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = undefined;
+    const currentParent = lstatSync(dirname(path));
+    if (!currentParent.isDirectory() || currentParent.isSymbolicLink()
+        || parent.dev !== currentParent.dev || parent.ino !== currentParent.ino) throw new Error("Instruction publication parent changed.");
+    if (readStableText(temporary, { label: "Instruction publication", maxBytes: MAX_BYTES }).text !== text) throw new Error("Instruction publication changed.");
+    assertFileUnchanged(path, expected, "AGENTS.md");
+    if (expected) renameSync(temporary, path);
+    else linkSync(temporary, path);
   } finally {
-    rmSync(temporary, { force: true });
+    if (descriptor !== undefined) closeSync(descriptor);
+    if (ownsTemporary) rmSync(temporary, { force: true });
   }
 }
 
 export function reconcilePlaybookInstructions(projectRoot = process.cwd(), options = {}) {
-  const root = resolve(projectRoot);
+  const root = safeRoot(projectRoot, Boolean(options.check));
   const path = join(root, "AGENTS.md");
   if (dirname(path) !== root) throw new Error("AGENTS.md path escapes the project root.");
   const block = readFileSync(TEMPLATE, "utf8");
   const existing = existsSync(path) ? safeRead(path) : { text: "", mode: 0o644 };
   const desired = render(existing.text, block);
   const status = !existsSync(path) ? "created" : desired === existing.text ? "unchanged" : "updated";
-  if (!options.check && status !== "unchanged") atomicWrite(path, desired, existing.mode || 0o644);
+  if (!options.check && status !== "unchanged") atomicWrite(path, desired, existing.mode || 0o644, existing.stat ?? null);
   return Object.freeze({ schema_version: 1, path, status: options.check && status !== "unchanged" ? `would-${status}` : status });
 }
 
 export function removePlaybookInstructions(projectRoot = process.cwd(), options = {}) {
-  const root = resolve(projectRoot);
+  const root = safeRoot(projectRoot);
   const path = join(root, "AGENTS.md");
   if (!existsSync(path)) return Object.freeze({ schema_version: 1, path, status: "unchanged" });
   const existing = safeRead(path);
   const desired = removeBlock(existing.text);
   const status = desired === existing.text ? "unchanged" : "removed";
   if (!options.check && status === "removed") {
-    if (desired.trim()) atomicWrite(path, `${desired}\n`, existing.mode || 0o644);
-    else rmSync(path);
+    if (desired.trim()) atomicWrite(path, `${desired}\n`, existing.mode || 0o644, existing.stat);
+    else { assertFileUnchanged(path, existing.stat, "AGENTS.md"); rmSync(path); }
   }
   return Object.freeze({ schema_version: 1, path, status: options.check && status === "removed" ? "would-remove" : status });
 }

package/scripts/setup-core.mjs

@@ -1,9 +1,10 @@
-import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { constants, existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { accessSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join, parse, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HARNESS_IDS, harnessProjectAssets } from "./harness-registry.mjs";
+import { readStableJson } from "./lib/stable-file.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATE_ROOT = join(ROOT, "templates");
@@ -111,45 +112,13 @@ function parsePolicy(value) {
   return deepFreeze(policy);
 }
 
-export function readSetupPolicy(path, options = {}) {
-  const lstat = options.lstat ?? lstatSync;
-  const read = options.readFile ?? readFileSync;
-  let info;
-  try {
-    info = lstat(path);
-  } catch (error) {
-    throw operational("unsafe-policy", `Setup policy could not be read: ${error instanceof Error ? error.message : String(error)}.`);
-  }
-  if (!info.isFile() || info.isSymbolicLink()) throw operational("unsafe-policy", "Setup policy must be a regular file, not a symbolic link or device.");
-  if (info.size > POLICY_LIMIT_BYTES) throw operational("unsafe-policy", "Setup policy exceeds the size limit.");
-  if (process.platform !== "win32" && (info.mode & 0o111) !== 0) throw operational("unsafe-policy", "Setup policy must not be executable.");
-  let descriptor;
-  let bytes;
+export function readSetupPolicy(path) {
   try {
-    if (options.readFile) bytes = read(path);
-    else {
-      descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-      const opened = fstatSync(descriptor);
-      if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino) throw operational("unsafe-policy", "Setup policy changed during validation.");
-      if (opened.size > POLICY_LIMIT_BYTES || (process.platform !== "win32" && (opened.mode & 0o111) !== 0)) {
-        throw operational("unsafe-policy", "Setup policy type, size, or executable mode is unsafe.");
-      }
-      bytes = read(descriptor);
-    }
+    return parsePolicy(readStableJson(path, { label: "Setup policy", maxBytes: POLICY_LIMIT_BYTES, nonExecutable: true }));
   } catch (error) {
     if (error instanceof SetupInputError) throw error;
-    throw operational("unsafe-policy", `Setup policy could not be opened safely: ${error instanceof Error ? error.message : String(error)}.`);
-  } finally {
-    if (descriptor !== undefined) closeSync(descriptor);
-  }
-  if (bytes.byteLength > POLICY_LIMIT_BYTES) throw operational("unsafe-policy", "Setup policy exceeds the size limit.");
-  let parsed;
-  try {
-    parsed = JSON.parse(bytes.toString("utf8"));
-  } catch {
-    throw operational("unsafe-policy", "Invalid setup policy JSON syntax.");
+    throw operational("unsafe-policy", error instanceof Error ? error.message : "Setup policy is unsafe or unreadable.");
   }
-  return parsePolicy(parsed);
 }
 
 function parseHarnesses(raw) {

package/scripts/setup-reconcile.mjs

@@ -1,22 +1,19 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import {
   chmodSync,
-  closeSync,
-  constants,
   existsSync,
-  fstatSync,
   lstatSync,
   mkdirSync,
-  openSync,
-  readFileSync,
   rmSync,
-  statSync,
   writeFileSync,
 } from "node:fs";
 import { open, rename } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { HARNESS_IDS } from "./harness-registry.mjs";
+import { readStableFile, readStableJson, assertFileUnchanged } from "./lib/stable-file.mjs";
+
+const MAX_SETUP_BYTES = 1024 * 1024;
 
 export const SETUP_STATE_SCHEMA_VERSION = 1;
 
@@ -218,41 +215,37 @@ function hardenPrivatePath(path) {
   if (result.status !== 0) throw new Error("Unable to restrict private setup state.");
 }
 
-async function atomicWrite(path, bytes, mode, atomicReplace = defaultAtomicReplace, privateState = false) {
+async function atomicWrite(path, bytes, mode, atomicReplace = defaultAtomicReplace, privateState = false, expected = null) {
+  const parent = lstatSync(dirname(path));
+  if (!parent.isDirectory() || parent.isSymbolicLink()) throw new Error("Setup publication parent is unsafe.");
   const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
   let handle;
+  let ownsTemporary = false;
   try {
     handle = await open(temporary, "wx", mode);
+    ownsTemporary = true;
     await handle.writeFile(bytes);
+    await handle.chmod(mode);
     await handle.sync();
     await handle.close();
     handle = undefined;
-    chmodSync(temporary, mode);
     if (privateState) hardenPrivatePath(temporary);
+    const currentParent = lstatSync(dirname(path));
+    if (!currentParent.isDirectory() || currentParent.isSymbolicLink()
+        || parent.dev !== currentParent.dev || parent.ino !== currentParent.ino) throw new Error("Setup publication parent changed.");
+    if (!readStableFile(temporary, { label: "Setup publication", maxBytes: MAX_SETUP_BYTES }).bytes.equals(bytes)) throw new Error("Setup publication changed.");
+    assertFileUnchanged(path, expected, "Setup target");
     await atomicReplace(temporary, path);
-    chmodSync(path, mode);
     if (privateState) hardenPrivatePath(path);
   } finally {
     if (handle) await handle.close().catch(() => undefined);
-    rmSync(temporary, { force: true });
+    if (ownsTemporary) rmSync(temporary, { force: true });
   }
 }
 
 function readPriorState(statePath) {
   if (!existsSync(statePath)) return null;
-  const info = lstatSync(statePath);
-  if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) throw new Error("Existing setup state is unsafe.");
-  let descriptor;
-  try {
-    descriptor = openSync(statePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-    const opened = fstatSync(descriptor);
-    if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.size > 1024 * 1024) {
-      throw new Error("Existing setup state changed during validation.");
-    }
-    return normalizeState(JSON.parse(readFileSync(descriptor, "utf8")));
-  } finally {
-    if (descriptor !== undefined) closeSync(descriptor);
-  }
+  return normalizeState(readStableJson(statePath, { label: "Existing setup state", maxBytes: MAX_SETUP_BYTES }));
 }
 
 export async function writeSetupStateAtomic(path, state, options = {}) {
@@ -265,8 +258,13 @@ export async function writeSetupStateAtomic(path, state, options = {}) {
   safeMkdirChain(target, directory);
   hardenPrivatePath(directory);
   const bytes = Buffer.from(`${JSON.stringify(normalized, null, 2)}\n`, "utf8");
-  if (existsSync(path) && readFileSync(path).equals(bytes) && (statSync(path).mode & 0o777) === 0o600) return normalized;
-  await atomicWrite(path, bytes, 0o600, options.atomicReplace ?? defaultAtomicReplace, true);
+  let expected = null;
+  if (existsSync(path)) {
+    const current = readStableFile(path, { label: "Existing setup state", maxBytes: MAX_SETUP_BYTES });
+    if (current.bytes.equals(bytes) && (current.stat.mode & 0o777) === 0o600) return normalized;
+    expected = current.stat;
+  }
+  await atomicWrite(path, bytes, 0o600, options.atomicReplace ?? defaultAtomicReplace, true, expected);
   return normalized;
 }
 
@@ -292,20 +290,22 @@ export async function reconcileSetupPlan(plan, options = {}) {
 
   const decisions = selected.map((asset) => {
     if (!existsSync(asset.destination)) return { ...asset, status: "created" };
-    const currentInfo = lstatSync(asset.destination);
-    if (!currentInfo.isFile() || currentInfo.isSymbolicLink()) throw new Error(`Unsafe setup asset destination: ${asset.path}.`);
-    const currentDigest = hashSetupAsset(readFileSync(asset.destination));
-    const currentMode = currentInfo.mode & 0o777;
-    if (currentDigest === asset.digest && currentMode === asset.mode) return { ...asset, status: "unchanged" };
+    const current = readStableFile(asset.destination, { label: "Setup asset", maxBytes: MAX_SETUP_BYTES });
+    const currentDigest = hashSetupAsset(current.bytes);
+    const currentMode = current.stat.mode & 0o777;
+    // Windows mode bits do not represent POSIX executability. Match diagnosis:
+    // retain digest ownership there, while writers enforce private state ACLs.
+    const modeMatches = (mode) => process.platform === "win32" || currentMode === mode;
+    if (currentDigest === asset.digest && modeMatches(asset.mode)) return { ...asset, status: "unchanged" };
     const prior = previousState?.assets?.[asset.path];
-    if (prior && prior.digest === currentDigest && prior.mode === currentMode) return { ...asset, status: "updated" };
+    if (prior && prior.digest === currentDigest && modeMatches(prior.mode)) return { ...asset, status: "updated", expected: current.stat };
     return { ...asset, status: "skipped" };
   });
 
   for (const decision of decisions) {
     if (decision.status !== "created" && decision.status !== "updated") continue;
     safeMkdirChain(target, dirname(decision.destination));
-    await atomicWrite(decision.destination, decision.bytes, decision.mode, options.atomicReplace ?? defaultAtomicReplace, decision.mode === 0o600);
+    await atomicWrite(decision.destination, decision.bytes, decision.mode, options.atomicReplace ?? defaultAtomicReplace, decision.mode === 0o600, decision.expected ?? null);
   }
 
   const assets = {};

package/scripts/setup.mjs

@@ -1,13 +1,8 @@
 import { spawnSync } from "node:child_process";
 import {
-  closeSync,
-  constants,
   existsSync,
-  fstatSync,
   lstatSync,
   mkdirSync,
-  openSync,
-  readFileSync,
 } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
@@ -25,6 +20,7 @@ import { reconcileSetupPlan } from "./setup-reconcile.mjs";
 import { HARNESS_IDS, HARNESS_REGISTRY, machineSyncCommand, machineSyncCommands, requiredHarnessAssetPaths } from "./harness-registry.mjs";
 import { reconcilePlaybookInstructions } from "./playbook-instructions.mjs";
 import { selectManyPrompt, selectOnePrompt, supportsTerminalPrompts } from "./terminal-prompts.mjs";
+import { readStableFile, readStableJson, readStableText } from "./lib/stable-file.mjs";
 
 const HARNESSES = HARNESS_IDS;
 const GIT_MODES = Object.freeze(["init", "existing", "none"]);
@@ -360,33 +356,14 @@ function safeRequiredAsset(project, path, launcher) {
 }
 
 function readPrivateState(path) {
-  const info = lstatSync(path);
-  if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) throw new Error("unsafe");
-  if (process.platform !== "win32" && (info.mode & 0o777) !== 0o600) throw new Error("unsafe");
-  let descriptor;
-  try {
-    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-    const opened = fstatSync(descriptor);
-    if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.size > 1024 * 1024) throw new Error("unsafe");
-    return JSON.parse(readFileSync(descriptor, "utf8"));
-  } finally {
-    if (descriptor !== undefined) closeSync(descriptor);
-  }
+  return readStableJson(path, { label: "Setup state", maxBytes: 1024 * 1024, privateMode: 0o600 });
 }
 
 function readTomlConfig(path) {
   if (!existsSync(path)) return null;
-  const info = lstatSync(path);
-  if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) return null;
-  let descriptor;
   try {
-    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-    const opened = fstatSync(descriptor);
-    if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.size > 1024 * 1024) return null;
-    return readFileSync(descriptor, "utf8");
-  } finally {
-    if (descriptor !== undefined) closeSync(descriptor);
-  }
+    return readStableText(path, { label: "Harness configuration", maxBytes: 1024 * 1024 }).text;
+  } catch { return null; }
 }
 
 function codexMemorySection(text, id) {
@@ -457,10 +434,9 @@ export function diagnoseSetup(target = ".") {
       if (!safeStateAsset(path, record)) return incompleteDiagnosis(recovery);
       const destination = join(project, ...path.split("/"));
       if (!existsSync(destination)) return incompleteDiagnosis(recovery);
-      const info = lstatSync(destination);
-      if (!info.isFile() || info.isSymbolicLink()) return incompleteDiagnosis(recovery);
-      const digest = createHash("sha256").update(readFileSync(destination)).digest("hex");
-      if (digest !== record.digest || (process.platform !== "win32" && (info.mode & 0o777) !== record.mode)) return incompleteDiagnosis(recovery);
+      const current = readStableFile(destination, { label: "Setup asset", maxBytes: 1024 * 1024 });
+      const digest = createHash("sha256").update(current.bytes).digest("hex");
+      if (digest !== record.digest || (process.platform !== "win32" && (current.stat.mode & 0o777) !== record.mode)) return incompleteDiagnosis(recovery);
     }
     const requiredAssets = [...COMMON_SETUP_ASSETS, ...requiredHarnessAssetPaths(state.harnesses, state.memory)];
     const launchers = new Set(state.harnesses.map((id) => HARNESS_REGISTRY.find((harness) => harness.id === id).launcher.path));

package/scripts/test-ci-sharding.sh

@@ -29,5 +29,10 @@ for (const shard of ["1/3", "2/3", "3/3"]) assert.ok(workflow.includes(`shard: "
 assert.match(workflow, /run-smoke-suite\.mjs --shard \$\{\{ matrix\.shard \}\}/);
 assert.doesNotMatch(workflow.match(/  native-windows:[\s\S]*?\n  repository:/)?.[0] ?? "",
   /npm --prefix mcp-memory-server test/);
+const native = workflow.match(/  native-windows:[\s\S]*?\n  repository:/)?.[0] ?? "";
+const focused = native.indexOf("run: node mcp-memory-server/scripts/smoke-bounded-input-reads.mjs");
+assert.ok(focused > native.indexOf("npm --prefix mcp-memory-server run build"));
+assert.ok(focused < native.indexOf("- name: Native Windows CLI contracts"));
+assert.ok(focused < native.indexOf("- name: Sharded memory-server contracts"));
 console.log(`PASS: ${smokeChecks.length} memory-server contracts split once across balanced Windows shards (${weights.join(", ")})`);
 NODE