@cairnkeep/cli 2.22.3 → 2.22.5

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.5",
     "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/release-verification.mjs

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+
+function requireThat(condition, label) { if (!condition) throw new Error(`Release verification failed: ${label}.`); }
+const hash = bytes => createHash("sha256").update(bytes).digest("hex");
+const digestPattern = /^sha256:[a-f0-9]{64}$/;
+
+export function validateReleaseOptions(options) {
+  requireThat(/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(options.repo ?? ""), "repository");
+  requireThat(/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(options.version ?? ""), "stable version");
+  for (const field of ["commit", "tree"]) requireThat(/^[a-f0-9]{40}$/.test(options[field] ?? ""), `exact ${field}`);
+  for (const field of ["ciRun", "securityRun", "publishRun"]) requireThat(/^[1-9][0-9]*$/.test(options[field] ?? ""), field);
+}
+
+export function releaseAttestationArguments(image, digest, options) {
+  validateReleaseOptions(options);
+  requireThat(digestPattern.test(digest), "attestation subject digest");
+  requireThat(image === options.repo || image === `${options.repo}-workspace`, "attestation image repository");
+  // Exact certificate identity binds repository, workflow and tag. The CLI
+  // makes this mutually exclusive with its broader signer-workflow selector.
+  return ["attestation", "verify", `oci://ghcr.io/${image}@${digest}`, "--repo", options.repo,
+    "--source-ref", `refs/tags/v${options.version}`, "--source-digest", options.commit,
+    "--cert-identity", `https://github.com/${options.repo}/.github/workflows/publish.yml@refs/tags/v${options.version}`,
+    "--cert-oidc-issuer", "https://token.actions.githubusercontent.com",
+    "--predicate-type", "https://slsa.dev/provenance/v1", "--deny-self-hosted-runners", "--format", "json"];
+}
+
+function json(bytes, label) {
+  try { return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); }
+  catch { throw new Error(`Release verification failed: ${label} encoding or JSON.`); }
+}
+
+function verifyAssets(options, candidate, released) {
+  const names = [`cairnkeep-cli-${options.version}.tgz`, `cairnkeep-cli-${options.version}.cdx.json`];
+  const exactKeys = (map, expected) => map instanceof Map && JSON.stringify([...map.keys()].sort()) === JSON.stringify(expected.sort());
+  requireThat(exactKeys(candidate, [...names, "SHA256SUMS", "RELEASE-CANDIDATE.json"]), "candidate file set");
+  requireThat(exactKeys(released, [...names, "SHA256SUMS"]), "release asset set");
+  const manifest = json(candidate.get("RELEASE-CANDIDATE.json"), "candidate manifest");
+  requireThat(Object.keys(manifest).sort().join(",") === "schema_version,tree,version"
+    && manifest.schema_version === 1 && manifest.tree === options.tree && manifest.version === options.version, "candidate manifest binding");
+  const sums = new TextDecoder("utf-8", { fatal: true }).decode(candidate.get("SHA256SUMS")).trim().split("\n");
+  requireThat(sums.length === names.length, "checksum file count");
+  const seen = new Set();
+  for (const line of sums) {
+    const match = /^([a-f0-9]{64})\s+\*?(?:\.\/)?([A-Za-z0-9._-]+)$/.exec(line);
+    requireThat(match && names.includes(match[2]) && !seen.has(match[2]), "checksum paths and uniqueness");
+    seen.add(match[2]);
+    requireThat(hash(candidate.get(match[2])) === match[1], "candidate checksum");
+    requireThat(candidate.get(match[2]).equals(released.get(match[2])), "release/candidate exact bytes");
+  }
+  requireThat(candidate.get("SHA256SUMS").equals(released.get("SHA256SUMS")), "checksum asset exact bytes");
+  const sbom = json(candidate.get(names[1]), "SBOM");
+  requireThat(sbom.bomFormat === "CycloneDX" && sbom.specVersion === "1.6"
+    && sbom.metadata?.component?.version === options.version, "CycloneDX release binding");
+  return candidate.get(names[0]);
+}
+
+export async function verifyPublishedRelease(options, io) {
+  validateReleaseOptions(options);
+  const api = path => io.api(path);
+  const ci = await api(`actions/runs/${options.ciRun}`);
+  requireThat(ci.conclusion === "success" && ci.path === ".github/workflows/ci.yml", "successful maintained CI");
+  requireThat((await api(`git/commits/${ci.head_sha}`)).tree?.sha === options.tree, "tested tree");
+  requireThat((await api(`git/commits/${options.commit}`)).tree?.sha === options.tree, "release tree");
+  const security = await api(`actions/runs/${options.securityRun}`);
+  requireThat(security.conclusion === "success" && security.path === ".github/workflows/security.yml", "successful maintained security workflow");
+  requireThat((await api(`git/commits/${security.head_sha}`)).tree?.sha === options.tree, "security-tested tree");
+  let tag = (await api(`git/ref/tags/v${options.version}`)).object;
+  for (let depth = 0; tag?.type === "tag" && depth < 4; depth++) tag = (await api(`git/tags/${tag.sha}`)).object;
+  requireThat(tag?.type === "commit" && tag.sha === options.commit, "immutable tag source");
+  const publication = await api(`actions/runs/${options.publishRun}`);
+  requireThat(publication.conclusion === "success" && publication.path === ".github/workflows/publish.yml"
+    && publication.event === "release" && publication.head_sha === options.commit, "successful exact-source publication");
+  const release = await api(`releases/tags/v${options.version}`);
+  requireThat(release.tag_name === `v${options.version}` && release.draft === false && release.prerelease === false, "published stable release");
+  const artifacts = (await api(`actions/runs/${options.ciRun}/artifacts?per_page=100`)).artifacts;
+  const matches = artifacts?.filter(a => a.name === `release-candidate-${options.tree}` && a.expired === false);
+  requireThat(matches?.length === 1, "one retained exact-tree candidate");
+  const tarball = verifyAssets(options, await io.candidate(matches[0]), await io.release());
+  const registry = await io.registry();
+  let url;
+  try { url = new URL(registry.dist?.tarball); } catch { /* fail below */ }
+  requireThat(registry.version === options.version && url?.protocol === "https:" && url.hostname === "registry.npmjs.org"
+    && !url.username && !url.password && !url.port && !url.hash, "registry tarball authority");
+  const publishedTarball = await io.tarball(url.href);
+  requireThat(tarball.equals(publishedTarball), "registry/candidate exact bytes");
+  requireThat(registry.dist.integrity === `sha512-${createHash("sha512").update(tarball).digest("base64")}`, "registry integrity");
+  requireThat(await io.verifyNpm(tarball), "npm signatures and attestations");
+
+  const images = [];
+  const [owner, project] = options.repo.split("/");
+  for (const name of [project, `${project}-workspace`]) {
+    const image = `${owner}/${name}`;
+    const get = async (kind, ref) => {
+      requireThat([options.version, "latest"].includes(ref) || digestPattern.test(ref), "OCI reference");
+      const result = await io.oci(image, kind, ref);
+      requireThat(digestPattern.test(result.digest) && (!ref.startsWith("sha256:") || result.digest === ref), "OCI content digest");
+      return result;
+    };
+    const index = await get("manifests", options.version);
+    requireThat((await get("manifests", "latest")).digest === index.digest, "stable image channel");
+    const manifests = index.value.manifests;
+    requireThat(Array.isArray(manifests) && manifests.length <= 32, "bounded OCI index");
+    for (const arch of ["amd64", "arm64"]) {
+      const entries = manifests.filter(m => m.platform?.os === "linux" && m.platform?.architecture === arch);
+      requireThat(entries.length === 1, "one image per supported architecture");
+      const entry = entries[0];
+      const manifest = (await get("manifests", entry.digest)).value;
+      const config = (await get("blobs", manifest.config?.digest)).value;
+      requireThat(config.os === "linux" && config.architecture === arch
+        && config.config?.Labels?.["org.opencontainers.image.revision"] === options.commit, "image platform/source binding");
+      const attestations = manifests.filter(m => m.annotations?.["vnd.docker.reference.digest"] === entry.digest
+        && m.annotations?.["vnd.docker.reference.type"] === "attestation-manifest");
+      requireThat(attestations.length === 1, "bound build attestation");
+      const layers = (await get("manifests", attestations[0].digest)).value.layers;
+      requireThat(Array.isArray(layers) && layers.length <= 32, "bounded attestation layers");
+      let sbom = false;
+      for (const layer of layers) {
+        const statement = (await get("blobs", layer.digest)).value;
+        if (statement.predicateType === "https://spdx.dev/Document" && statement.predicate?.spdxVersion?.startsWith("SPDX-")
+          && statement.subject?.some(s => s.digest?.sha256 === entry.digest.slice(7))) sbom = true;
+      }
+      requireThat(sbom, "per-architecture bound SPDX SBOM");
+    }
+    requireThat(await io.verifyAttestation(image, index.digest, options), "verified exact-source release-workflow provenance");
+    images.push({ image: `ghcr.io/${image}`, digest: index.digest, platforms: ["linux/amd64", "linux/arm64"] });
+  }
+  return { schema_version: 1, status: "verified", ...options, candidate_artifact: matches[0].id,
+    exact_bytes: true, cyclonedx: "1.6", npm_signatures_and_attestations: true, images,
+    scope: "release-artifacts-only", anonymous_oci_metadata_verified: true,
+    full_image_layer_pull_verified: false, deployment_verified: false };
+}

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 = {};