@zhivex-ai/harness 0.11.0 → 0.11.1

package/dist/zhx.js

@@ -4,7 +4,7 @@
 import { createInterface } from "node:readline/promises";
 import { randomUUID as randomUUID6 } from "node:crypto";
 import { constants as fsConstants3, realpathSync as realpathSync2 } from "node:fs";
-import { access, lstat as lstat9, readFile as readFile4, stat as stat4 } from "node:fs/promises";
+import { access, lstat as lstat9, stat as stat4 } from "node:fs/promises";
 import path12 from "node:path";
 import { fileURLToPath } from "node:url";
 import { z as z6 } from "zod";
@@ -759,13 +759,14 @@ var MAX_EDIT_FILE_BYTES = 1024 * 1024;
 var MAX_EDIT_PROPOSAL_BYTES = 4 * 1024 * 1024;
 var SHA256_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
 var fileDigestSchema = z.string().regex(SHA256_DIGEST_PATTERN, "Digest must use the format sha256:<64 lowercase hexadecimal characters>.");
+var expectedEditDigestSchema = fileDigestSchema.nullable().describe("Required. Use the inspected sha256 digest for an existing file, or explicit JSON null for a create-only target. Never omit this field.");
 var workspaceFilePathSchema = z.string().min(1).max(1024).refine((value) => !value.includes("\x00"), "Path cannot contain a NUL byte.").refine((value) => !path2.isAbsolute(value) && !/^[A-Za-z]:[\\/]/.test(value), "Path must be relative.").refine((value) => {
   const segments = value.split(/[\\/]+/);
   return segments.every((segment) => segment !== "" && segment !== "." && segment !== "..");
 }, "Path must be normalized and cannot contain empty, dot, or parent segments.");
 var editChangeSchema = z.strictObject({
   path: workspaceFilePathSchema,
-  expectedDigest: fileDigestSchema.nullable(),
+  expectedDigest: expectedEditDigestSchema,
   content: z.string()
 }).superRefine((change, context) => {
   if (Buffer.byteLength(change.content, "utf8") > MAX_EDIT_FILE_BYTES) {
@@ -806,7 +807,7 @@ var editProposalInputSchema = z.strictObject({
 });
 var editProposalChangeSchema = z.strictObject({
   path: workspaceFilePathSchema,
-  expectedDigest: fileDigestSchema.nullable(),
+  expectedDigest: expectedEditDigestSchema,
   contentDigest: fileDigestSchema,
   bytes: z.number().int().min(0).max(MAX_EDIT_FILE_BYTES)
 });
@@ -885,9 +886,97 @@ var editContractDocument = (kind, result) => ({
 
 // src/workspace.ts
 import { createHash as createHash4, randomUUID } from "node:crypto";
-import { link, lstat as lstat2, mkdir, open, readFile, readdir, realpath, rename, stat, unlink } from "node:fs/promises";
+import { link, lstat as lstat2, mkdir, open as open2, readdir, realpath, rename, stat, unlink } from "node:fs/promises";
 import path4 from "node:path";
 
+// src/file-security.ts
+import { constants as fsConstants } from "node:fs";
+import { open } from "node:fs/promises";
+var sameOpenFile = (before, after) => before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeMs === after.mtimeMs && before.ctimeMs === after.ctimeMs && before.mode === after.mode && before.nlink === after.nlink;
+
+class UnsafeFileTypeError extends Error {
+  constructor(label) {
+    super(`${label} must be a regular file and must not be a symbolic link.`);
+    this.name = "UnsafeFileTypeError";
+  }
+}
+
+class FileSizeLimitError extends Error {
+  label;
+  maxBytes;
+  constructor(label, maxBytes) {
+    super(`${label} exceeds the ${maxBytes}-byte limit.`);
+    this.label = label;
+    this.maxBytes = maxBytes;
+    this.name = "FileSizeLimitError";
+  }
+}
+
+class FileChangedWhileReadingError extends Error {
+  constructor(label) {
+    super(`${label} changed while it was being read.`);
+    this.name = "FileChangedWhileReadingError";
+  }
+}
+var invalidFileError = (label) => new UnsafeFileTypeError(label);
+var openRegularFileNoFollow = async (target, label) => {
+  try {
+    return await open(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ELOOP" || code === "EMLINK")
+      throw invalidFileError(label);
+    throw error;
+  }
+};
+var statRegularFileNoFollow = async (target, options) => {
+  const handle = await openRegularFileNoFollow(target, options.label);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || options.requireSingleLink && stat.nlink !== 1) {
+      throw invalidFileError(options.label);
+    }
+    return stat;
+  } finally {
+    await handle.close();
+  }
+};
+var readRegularFileNoFollow = async (target, options) => {
+  const handle = await openRegularFileNoFollow(target, options.label);
+  try {
+    const before = await handle.stat();
+    if (!before.isFile() || options.requireSingleLink && before.nlink !== 1) {
+      throw invalidFileError(options.label);
+    }
+    if (!Number.isSafeInteger(before.size) || before.size < 0) {
+      throw new Error(`${options.label} has an unsupported size.`);
+    }
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0) {
+      throw new Error(`${options.label} has an invalid byte limit.`);
+    }
+    if (before.size > options.maxBytes) {
+      throw new FileSizeLimitError(options.label, options.maxBytes);
+    }
+    const contents = Buffer.alloc(before.size);
+    let offset = 0;
+    while (offset < contents.byteLength) {
+      const { bytesRead } = await handle.read(contents, offset, contents.byteLength - offset, offset);
+      if (bytesRead === 0)
+        break;
+      offset += bytesRead;
+    }
+    const probe = Buffer.allocUnsafe(1);
+    const { bytesRead: extraBytes } = await handle.read(probe, 0, 1, before.size);
+    const after = await handle.stat();
+    if (offset !== before.size || extraBytes !== 0 || !sameOpenFile(before, after) || options.requireSingleLink && after.nlink !== 1) {
+      throw new FileChangedWhileReadingError(options.label);
+    }
+    return { contents, stat: after };
+  } finally {
+    await handle.close();
+  }
+};
+
 // src/package-manager.ts
 import { lstat } from "node:fs/promises";
 import path3 from "node:path";
@@ -1068,9 +1157,11 @@ var runPortableProcess = async (command, options = {}) => {
   const argv = [...command];
   const stdout = new BoundedTextCapture(maxOutputCharacters);
   const stderr = new BoundedTextCapture(maxOutputCharacters);
+  const useProcessGroup = process.platform !== "win32";
   const child = spawn(argv[0], argv.slice(1), {
     ...options.cwd ? { cwd: options.cwd } : {},
     env: processEnvironment(options.env),
+    detached: useProcessGroup,
     shell: false,
     stdio: ["ignore", "pipe", "pipe"],
     windowsHide: true
@@ -1080,13 +1171,27 @@ var runPortableProcess = async (command, options = {}) => {
   let terminationTimer;
   child.stdout.on("data", (chunk) => stdout.write(chunk));
   child.stderr?.on("data", (chunk) => stderr.write(chunk));
+  const signalProcessTree = (signal) => {
+    if (useProcessGroup && child.pid !== undefined) {
+      try {
+        process.kill(-child.pid, signal);
+        return;
+      } catch (error) {
+        if (error.code !== "ESRCH") {
+          child.kill(signal);
+          return;
+        }
+      }
+    }
+    if (child.exitCode === null && child.signalCode === null)
+      child.kill(signal);
+  };
   const terminate = () => {
-    if (child.exitCode !== null || child.signalCode !== null)
+    if (terminationTimer)
       return;
-    child.kill("SIGTERM");
+    signalProcessTree("SIGTERM");
     terminationTimer = setTimeout(() => {
-      if (child.exitCode === null && child.signalCode === null)
-        child.kill("SIGKILL");
+      signalProcessTree("SIGKILL");
     }, DEFAULT_TERMINATION_GRACE_MS);
     terminationTimer.unref?.();
   };
@@ -1297,6 +1402,9 @@ class Workspace {
     let current = this.root;
     for (let index = 0;index < segments.length; index += 1) {
       current = path4.join(current, segments[index]);
+      const leaf = index === segments.length - 1;
+      if (leaf && options.skipLeafValidation)
+        continue;
       let entry;
       try {
         entry = await lstat2(current);
@@ -1309,7 +1417,6 @@ class Workspace {
       if (entry.isSymbolicLink()) {
         throw new Error(`The path resolves outside the workspace or through a symbolic link: ${relativePath}`);
       }
-      const leaf = index === segments.length - 1;
       if (!leaf && !entry.isDirectory())
         throw new Error(`A path ancestor is not a directory: ${relativePath}`);
       if (leaf && options.requireFile && !entry.isFile())
@@ -1319,15 +1426,12 @@ class Workspace {
   }
   async readStableFile(relativePath, allowBinary = true) {
     this.indexMetrics.stableFileReads += 1;
-    const safe = await this.safePath(relativePath, { requireFile: true });
-    const before = await lstat2(safe.path);
-    if (before.size > MAX_FILE_BYTES)
-      throw new Error(`The file exceeds the ${MAX_FILE_BYTES}-byte limit.`);
-    const contents = await readFile(safe.path);
-    const after = await lstat2(safe.path);
-    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
-      throw new Error(`The file changed while it was being read: ${relativePath}`);
-    }
+    const safe = await this.safePath(relativePath, { skipLeafValidation: true });
+    const file = await readRegularFileNoFollow(safe.path, {
+      label: "The file",
+      maxBytes: MAX_FILE_BYTES
+    });
+    const { contents } = file;
     if (!allowBinary && contents.includes(0))
       throw new Error("The file appears to be binary and cannot be read as text.");
     return {
@@ -1335,7 +1439,7 @@ class Workspace {
       absolutePath: safe.path,
       contents,
       digest: digestBytes(contents),
-      mode: before.mode & 511
+      mode: file.stat.mode & 511
     };
   }
   fingerprint(relativePath, kind, entry, digest2) {
@@ -1358,23 +1462,20 @@ class Workspace {
     for (const filename of IGNORE_FILES) {
       try {
         const ignorePath = path4.join(directory, filename);
-        const before = await lstat2(ignorePath);
-        if (before.isSymbolicLink() || !before.isFile())
+        const inspected = await statRegularFileNoFollow(ignorePath, { label: "The ignore file" });
+        if (inspected.size > MAX_FILE_BYTES) {
+          ignoreFiles.push(this.fingerprint(wirePath(path4.relative(this.root, ignorePath)), "ignore-file", inspected));
           continue;
-        if (before.size <= MAX_FILE_BYTES) {
-          const contents = await readFile(ignorePath);
-          const after = await lstat2(ignorePath);
-          if (after.isSymbolicLink() || !after.isFile() || !this.sameFingerprint(after, this.fingerprint("", "ignore-file", before))) {
-            throw new Error(`The ignore file changed while the workspace was being indexed: ${wirePath(path4.relative(this.root, ignorePath))}`);
-          }
-          const digest2 = digestBytes(contents);
-          ignoreFiles.push(this.fingerprint(wirePath(path4.relative(this.root, ignorePath)), "ignore-file", after, digest2));
-          rules.push(...parseIgnoreRules(contents.toString("utf8"), base));
-        } else {
-          ignoreFiles.push(this.fingerprint(wirePath(path4.relative(this.root, ignorePath)), "ignore-file", before));
         }
+        const file = await readRegularFileNoFollow(ignorePath, {
+          label: "The ignore file",
+          maxBytes: MAX_FILE_BYTES
+        });
+        const digest2 = digestBytes(file.contents);
+        ignoreFiles.push(this.fingerprint(wirePath(path4.relative(this.root, ignorePath)), "ignore-file", file.stat, digest2));
+        rules.push(...parseIgnoreRules(file.contents.toString("utf8"), base));
       } catch (error) {
-        if (error.code !== "ENOENT")
+        if (error.code !== "ENOENT" && !(error instanceof UnsafeFileTypeError))
           throw error;
       }
     }
@@ -1417,13 +1518,17 @@ class Workspace {
       }
       for (const fingerprint of index.ignoreFiles) {
         const absolute = path4.join(this.root, fingerprint.path);
-        const before = await lstat2(absolute);
-        if (before.isSymbolicLink() || !before.isFile() || !this.sameFingerprint(before, fingerprint))
-          return false;
         if (fingerprint.digest) {
-          const contents = await readFile(absolute);
-          const after = await lstat2(absolute);
-          if (after.isSymbolicLink() || !after.isFile() || !this.sameFingerprint(after, fingerprint) || digestBytes(contents) !== fingerprint.digest)
+          const file = await readRegularFileNoFollow(absolute, {
+            label: "The ignore file",
+            maxBytes: MAX_FILE_BYTES
+          });
+          if (!this.sameFingerprint(file.stat, fingerprint) || digestBytes(file.contents) !== fingerprint.digest) {
+            return false;
+          }
+        } else {
+          const inspected = await statRegularFileNoFollow(absolute, { label: "The ignore file" });
+          if (!this.sameFingerprint(inspected, fingerprint))
             return false;
         }
       }
@@ -1808,7 +1913,7 @@ class Workspace {
   async stageFile(target, contents, mode) {
     const directory = await this.secureWorkspaceDirectory(path4.dirname(target));
     const temporary = path4.join(directory, `.${path4.basename(target)}.zhivex-${randomUUID()}.tmp`);
-    const handle = await open(temporary, "wx", mode);
+    const handle = await open2(temporary, "wx", mode);
     try {
       await handle.writeFile(contents);
       await handle.chmod(mode);
@@ -2031,17 +2136,7 @@ class Workspace {
     await rename(temporary, target);
   }
   async readInternalRegularFile(target, label, maxBytes) {
-    const before = await lstat2(target);
-    if (before.isSymbolicLink() || !before.isFile())
-      throw new Error(`${label} must be a regular non-symlink file.`);
-    if (before.size > maxBytes)
-      throw new Error(`${label} exceeds its size limit.`);
-    const contents = await readFile(target);
-    const after = await lstat2(target);
-    if (after.isSymbolicLink() || !after.isFile() || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
-      throw new Error(`${label} changed while it was being read.`);
-    }
-    return { contents, stat: before };
+    return await readRegularFileNoFollow(target, { label, maxBytes });
   }
   async quarantineFile(input) {
     const parsed = quarantineFileInputSchema.parse(input);
@@ -2054,7 +2149,7 @@ class Workspace {
     if ((await this.readStableFile(parsed.path)).digest !== parsed.expectedDigest)
       throw new Error(`Stale quarantine rejected for ${parsed.path}.`);
     await link(source.absolutePath, dataPath);
-    if (digestBytes(await readFile(dataPath)) !== source.digest) {
+    if (digestBytes((await this.readInternalRegularFile(dataPath, "Quarantine payload", MAX_FILE_BYTES)).contents) !== source.digest) {
       await unlink(dataPath).catch(() => {});
       throw new Error(`Quarantine payload changed before commit: ${parsed.path}.`);
     }
@@ -2111,8 +2206,8 @@ class Workspace {
       throw new Error("Quarantine payload changed before restore commit.");
     }
     await link(dataPath, destination.path);
-    const linkedDestination = await lstat2(destination.path);
-    if (linkedDestination.isSymbolicLink() || !linkedDestination.isFile() || linkedDestination.dev !== dataFile.stat.dev || linkedDestination.ino !== dataFile.stat.ino || digestBytes(await readFile(destination.path)) !== digest2) {
+    const linkedDestination = await this.readInternalRegularFile(destination.path, "Restore destination", MAX_FILE_BYTES);
+    if (linkedDestination.stat.dev !== dataFile.stat.dev || linkedDestination.stat.ino !== dataFile.stat.ino || digestBytes(linkedDestination.contents) !== digest2) {
       await unlink(destination.path).catch(() => {});
       throw new Error("Restore destination did not match the quarantined payload.");
     }
@@ -2175,7 +2270,7 @@ class Workspace {
 }
 
 // src/operations.ts
-import { chmod, lstat as lstat4, mkdir as mkdir2, open as open2 } from "node:fs/promises";
+import { chmod, lstat as lstat4, mkdir as mkdir2, open as open3 } from "node:fs/promises";
 import path6 from "node:path";
 import {
   cancelAgentRun,
@@ -2552,19 +2647,12 @@ var openHarnessPersistence = async (config, options = {}) => {
   const databasePath = path6.join(config.stateDirectory, HARNESS_SQLITE_FILE);
   let databaseEntry;
   try {
+    const handle = await open3(databasePath, "wx", 384);
+    await handle.close();
     databaseEntry = await lstat4(databasePath);
   } catch (error) {
-    if (error.code !== "ENOENT") {
+    if (error.code !== "EEXIST")
       throw error;
-    }
-    try {
-      const handle = await open2(databasePath, "wx", 384);
-      await handle.close();
-    } catch (creationError) {
-      if (creationError.code !== "EEXIST") {
-        throw creationError;
-      }
-    }
     databaseEntry = await lstat4(databasePath);
   }
   if (databaseEntry.isSymbolicLink() || !databaseEntry.isFile()) {
@@ -2606,7 +2694,7 @@ var openHarnessPersistence = async (config, options = {}) => {
 };
 
 // src/mcp.ts
-import { lstat as lstat5, readFile as readFile2, realpath as realpath2 } from "node:fs/promises";
+import { lstat as lstat5, readFile, realpath as realpath2 } from "node:fs/promises";
 import path7 from "node:path";
 import {
   createMcpToolSet,
@@ -2762,7 +2850,7 @@ var loadHarnessMcpConfiguration = async (workspace, configPath) => {
   }
   let value;
   try {
-    value = JSON.parse(await readFile2(canonicalConfig, "utf8"));
+    value = JSON.parse(await readFile(canonicalConfig, "utf8"));
   } catch (error) {
     throw new Error("MCP configuration is not valid JSON.", { cause: error });
   }
@@ -3176,13 +3264,12 @@ var runHarnessReviewGroup = async (runtime, input, profiles = ["explorer", "revi
 // src/execution-environment.ts
 import { createHash as createHash6, randomUUID as randomUUID3 } from "node:crypto";
 import { spawn as spawn2 } from "node:child_process";
-import { constants as fsConstants } from "node:fs";
+import { constants as fsConstants2 } from "node:fs";
 import {
   chmod as chmod2,
   copyFile,
   lstat as lstat6,
   mkdir as mkdir3,
-  readFile as readFile3,
   readdir as readdir2,
   realpath as realpath3,
   rename as rename2,
@@ -3201,6 +3288,8 @@ var TERMINAL_STATUSES = new Set([
   "cancelled",
   "timed_out"
 ]);
+var EXECUTION_ARTIFACT_DIRECTORY_PATTERN = /^[a-f0-9]{24}$/;
+var STAGED_EXECUTION_ARTIFACT_DIRECTORY_PATTERN = /^\.cleanup-([a-f0-9]{24})-[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/;
 var BUILT_IN_TOOL_NAMES = new Set([
   "list_files",
   "read_file",
@@ -3372,7 +3461,9 @@ var validateSynchronizedSnapshot = async (stagedRoot, previousRoot, maxWorkspace
   const seal = createHash6("sha256");
   const metadata = createHash6("sha256");
   const visit = async (directory, relativeDirectory = "") => {
-    for (const name of (await readdir2(directory)).sort()) {
+    const children = (await readdir2(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+    for (const child of children) {
+      const name = child.name;
       const relative = relativeDirectory ? `${relativeDirectory}/${name}` : name;
       const absolute = path8.join(directory, name);
       if (!isInside3(stagedRoot, absolute) || relative.length > 1024) {
@@ -3386,37 +3477,53 @@ var validateSynchronizedSnapshot = async (stagedRoot, previousRoot, maxWorkspace
         await rm(absolute, { recursive: true, force: true });
         continue;
       }
-      const entry = await lstat6(absolute);
-      if (entry.isSymbolicLink()) {
+      if (child.isSymbolicLink()) {
         throw new Error(`OCI workspace export contains a symbolic link: ${relative}.`);
       }
-      if (entry.isDirectory()) {
-        updateSnapshotMetadata(metadata, "directory", relative, entry);
-        seal.update(`directory\x00${relative}\x00${entry.mode & 511}\x00`);
+      if (child.isDirectory()) {
+        const directoryEntry = await lstat6(absolute);
+        if (directoryEntry.isSymbolicLink() || !directoryEntry.isDirectory()) {
+          throw new Error(`OCI workspace export directory changed while it was being validated: ${relative}.`);
+        }
+        updateSnapshotMetadata(metadata, "directory", relative, directoryEntry);
+        seal.update(`directory\x00${relative}\x00${directoryEntry.mode & 511}\x00`);
         await visit(absolute, relative);
         continue;
       }
-      if (!entry.isFile() || entry.nlink !== 1) {
+      if (!child.isFile()) {
         throw new Error(`OCI workspace export contains a special or linked file: ${relative}.`);
       }
-      const contents = await readFile3(absolute);
-      const after = await lstat6(absolute);
-      if (after.isSymbolicLink() || !after.isFile() || after.nlink !== 1 || entry.dev !== after.dev || entry.ino !== after.ino || entry.size !== after.size || entry.mtimeMs !== after.mtimeMs || entry.ctimeMs !== after.ctimeMs || (entry.mode & 511) !== (after.mode & 511)) {
-        throw new Error(`OCI workspace export changed while it was being validated: ${relative}.`);
+      let file;
+      try {
+        file = await readRegularFileNoFollow(absolute, {
+          label: `OCI workspace export file ${relative}`,
+          maxBytes: maxWorkspaceBytes - totalBytes,
+          requireSingleLink: true
+        });
+      } catch (error) {
+        if (error instanceof FileSizeLimitError) {
+          throw new Error(`OCI workspace export exceeds the ${maxWorkspaceBytes}-byte workspace limit.`);
+        }
+        throw error;
       }
+      const contents = file.contents;
+      const entry = file.stat;
       totalBytes += entry.size;
       if (totalBytes > maxWorkspaceBytes) {
         throw new Error(`OCI workspace export exceeds the ${maxWorkspaceBytes}-byte workspace limit.`);
       }
       const contentDigest = digest2(contents);
-      updateSnapshotMetadata(metadata, "file", relative, after);
+      updateSnapshotMetadata(metadata, "file", relative, entry);
       seal.update(`file\x00${relative}\x00${entry.mode & 511}\x00${entry.size}\x00${contentDigest}\x00`);
       if (entry.size > maxFileWriteBytes) {
         const previous = path8.join(previousRoot, ...relative.split("/"));
         let unchanged = false;
         try {
-          const previousEntry = await lstat6(previous);
-          unchanged = previousEntry.isFile() && !previousEntry.isSymbolicLink() && previousEntry.size === entry.size && digest2(await readFile3(previous)) === contentDigest;
+          const previousFile = await readRegularFileNoFollow(previous, {
+            label: `Previous OCI workspace file ${relative}`,
+            maxBytes: entry.size
+          });
+          unchanged = previousFile.stat.size === entry.size && digest2(previousFile.contents) === contentDigest;
         } catch (error) {
           if (error.code !== "ENOENT")
             throw error;
@@ -4081,17 +4188,14 @@ var readSnapshotFile = async (workspace, expected, metrics) => {
   if (!isInside3(workspace.root, absolute)) {
     throw new Error(`Snapshot file escaped its workspace: ${expected.path}.`);
   }
-  const before = await lstat6(absolute);
-  if (before.isSymbolicLink() || !before.isFile()) {
-    throw new Error(`Snapshot source is not a regular file: ${expected.path}.`);
-  }
-  const contents = await readFile3(absolute);
-  const after = await lstat6(absolute);
-  if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || (before.mode & 511) !== (after.mode & 511)) {
-    throw new Error(`Snapshot source changed while reading: ${expected.path}.`);
-  }
+  const file = await readRegularFileNoFollow(absolute, {
+    label: `Snapshot source ${expected.path}`,
+    maxBytes: expected.bytes
+  });
+  const { contents } = file;
+  const entry = file.stat;
   const actualDigest = digest2(contents);
-  if (actualDigest !== expected.digest || contents.byteLength !== expected.bytes || (before.mode & 511) !== expected.mode) {
+  if (actualDigest !== expected.digest || contents.byteLength !== expected.bytes || (entry.mode & 511) !== expected.mode) {
     throw new Error(`Snapshot source changed after inventory: ${expected.path}.`);
   }
   if (metrics) {
@@ -4102,7 +4206,7 @@ var readSnapshotFile = async (workspace, expected, metrics) => {
 };
 var copySnapshotFile = async (source, target, metrics) => {
   try {
-    await copyFile(source, target, fsConstants.COPYFILE_FICLONE_FORCE);
+    await copyFile(source, target, fsConstants2.COPYFILE_FICLONE_FORCE);
   } catch (error) {
     const code = error.code;
     if (!code || !COPY_ON_WRITE_UNSUPPORTED_CODES.has(code))
@@ -4382,10 +4486,11 @@ var createHarnessOciExecutionEnvironment = async (options) => {
       const snapshotRoot = path8.join(directory, "workspace");
       let metadata;
       try {
-        const entry = await lstat6(metadataPath);
-        if (entry.isSymbolicLink() || !entry.isFile())
-          throw new Error("Execution metadata must be a regular file.");
-        metadata = JSON.parse(await readFile3(metadataPath, "utf8"));
+        const metadataFile = await readRegularFileNoFollow(metadataPath, {
+          label: "Execution metadata",
+          maxBytes: 1024 * 1024
+        });
+        metadata = JSON.parse(metadataFile.contents.toString("utf8"));
         if (metadata.schemaVersion !== HARNESS_EXECUTION_ARTIFACT_SCHEMA_VERSION || metadata.runId !== request.runId || metadata.hostWorkspace !== options.workspace.root || metadata.binding.fingerprint !== binding.fingerprint || metadata.binding.workspaceId !== binding.workspaceId) {
           throw new Error(`Execution artifact binding changed for run ${request.runId}.`);
         }
@@ -4601,7 +4706,11 @@ var createHarnessOciExecutionEnvironment = async (options) => {
         async runCheck(check, expectedScript, allowedChecks, context) {
           let manifestDocument;
           try {
-            manifestDocument = JSON.parse(await readFile3(path8.join(snapshotRoot, "package.json"), "utf8"));
+            const manifestFile = await readRegularFileNoFollow(path8.join(snapshotRoot, "package.json"), {
+              label: "Snapshot package.json",
+              maxBytes: 1024 * 1024
+            });
+            manifestDocument = JSON.parse(manifestFile.contents.toString("utf8"));
           } catch (error) {
             if (error.code === "ENOENT") {
               throw new Error("The environment snapshot does not contain package.json.");
@@ -4646,30 +4755,56 @@ var cleanupHarnessExecutionArtifacts = async (stateDirectory, before) => {
     throw error;
   }
   for (const entry of entries) {
-    if (!entry.isDirectory() || entry.isSymbolicLink() || !/^[a-f0-9]{24}$/.test(entry.name)) {
+    const stagedMatch = STAGED_EXECUTION_ARTIFACT_DIRECTORY_PATTERN.exec(entry.name);
+    const artifactName = EXECUTION_ARTIFACT_DIRECTORY_PATTERN.test(entry.name) ? entry.name : stagedMatch?.[1];
+    if (!entry.isDirectory() || entry.isSymbolicLink() || !artifactName) {
       result.skipped += 1;
       continue;
     }
     result.scanned += 1;
     const directory = path8.join(root, entry.name);
-    const resolved = await realpath3(directory);
-    if (!isInside3(root, resolved)) {
-      result.skipped += 1;
-      continue;
-    }
     try {
+      const resolved = await realpath3(directory);
+      if (!isInside3(root, resolved))
+        throw new Error("unsafe execution artifact directory");
+      const directoryEntry = await lstat6(directory);
+      if (directoryEntry.isSymbolicLink() || !directoryEntry.isDirectory()) {
+        throw new Error("unsafe execution artifact directory");
+      }
       const metadataPath = path8.join(directory, "environment.json");
-      const metadataEntry = await lstat6(metadataPath);
-      if (metadataEntry.isSymbolicLink() || !metadataEntry.isFile())
-        throw new Error("unsafe metadata");
-      const metadata = JSON.parse(await readFile3(metadataPath, "utf8"));
+      const metadataFile = await readRegularFileNoFollow(metadataPath, {
+        label: "Execution cleanup metadata",
+        maxBytes: 1024 * 1024
+      });
+      const metadata = JSON.parse(metadataFile.contents.toString("utf8"));
       const releasedAt = metadata.releasedAt ? Date.parse(metadata.releasedAt) : Number.NaN;
       if (!metadata.status || !TERMINAL_STATUSES.has(metadata.status) || !Number.isFinite(releasedAt) || releasedAt >= before) {
         result.skipped += 1;
         continue;
       }
-      await rm(directory, { recursive: true, force: true });
-      result.deleted += 1;
+      const stagedDirectory = path8.join(root, `.cleanup-${artifactName}-${randomUUID3()}`);
+      let staged = false;
+      try {
+        await rename2(directory, stagedDirectory);
+        staged = true;
+        const movedEntry = await lstat6(stagedDirectory);
+        if (movedEntry.isSymbolicLink() || !movedEntry.isDirectory() || movedEntry.dev !== directoryEntry.dev || movedEntry.ino !== directoryEntry.ino) {
+          throw new Error("execution artifact directory changed before cleanup");
+        }
+        const recheckedMetadata = await readRegularFileNoFollow(path8.join(stagedDirectory, "environment.json"), { label: "Execution cleanup metadata", maxBytes: 1024 * 1024 });
+        if (!recheckedMetadata.contents.equals(metadataFile.contents)) {
+          throw new Error("execution artifact metadata changed before cleanup");
+        }
+        await rm(stagedDirectory, { recursive: true, force: true });
+        staged = false;
+        result.deleted += 1;
+      } catch (error) {
+        if (staged)
+          await rename2(stagedDirectory, directory).catch(() => {
+            return;
+          });
+        throw error;
+      }
     } catch {
       result.skipped += 1;
     }
@@ -4685,8 +4820,7 @@ var describeOciCommand = (command, args) => commandDisplay([command, ...args]);
 
 // src/context-engineering.ts
 import { createHash as createHash7 } from "node:crypto";
-import { constants as fsConstants2 } from "node:fs";
-import { lstat as lstat7, open as open3, readdir as readdir3 } from "node:fs/promises";
+import { lstat as lstat7, readdir as readdir3 } from "node:fs/promises";
 import path9 from "node:path";
 import { z as z3 } from "zod";
 var HARNESS_CONTEXT_CONFIG_SCHEMA_VERSION = 1;
@@ -4765,7 +4899,6 @@ var validateRelativePath = (value) => {
   }
   return normalized;
 };
-var stableEntry = (before, after) => before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeMs === after.mtimeMs && before.ctimeMs === after.ctimeMs;
 var resolveSafeWorkspaceEntry = async (workspace, relativePath, options = {}) => {
   const normalized = validateRelativePath(relativePath);
   const absolutePath = path9.resolve(workspace.root, normalized);
@@ -4777,6 +4910,9 @@ var resolveSafeWorkspaceEntry = async (workspace, relativePath, options = {}) =>
   const segments = normalized.split("/");
   for (let index = 0;index < segments.length; index += 1) {
     current = path9.join(current, segments[index]);
+    const leaf = index === segments.length - 1;
+    if (leaf && options.skipLeafValidation)
+      continue;
     let entry;
     try {
       entry = await lstat7(current);
@@ -4788,7 +4924,6 @@ var resolveSafeWorkspaceEntry = async (workspace, relativePath, options = {}) =>
     if (entry.isSymbolicLink()) {
       throw new Error(`The harness context path cannot contain a symbolic link: ${relativePath}`);
     }
-    const leaf = index === segments.length - 1;
     if (!leaf && !entry.isDirectory()) {
       throw new Error(`A harness context path ancestor is not a directory: ${relativePath}`);
     }
@@ -4802,42 +4937,39 @@ var resolveSafeWorkspaceEntry = async (workspace, relativePath, options = {}) =>
   return { path: absolutePath, relativePath: normalized };
 };
 var readStableWorkspaceText = async (workspace, relativePath, maxBytes, allowMissing = false) => {
-  const resolved = await resolveSafeWorkspaceEntry(workspace, relativePath, { allowMissing });
+  const resolved = await resolveSafeWorkspaceEntry(workspace, relativePath, {
+    allowMissing,
+    skipLeafValidation: true
+  });
   if (!resolved)
     return;
-  const before = await lstat7(resolved.path);
-  if (before.size > maxBytes) {
-    throw new Error(`Harness context file ${resolved.relativePath} exceeds the ${maxBytes}-byte limit.`);
+  let file;
+  try {
+    file = await readRegularFileNoFollow(resolved.path, {
+      label: `Harness context file ${resolved.relativePath}`,
+      maxBytes
+    });
+  } catch (error) {
+    if (allowMissing && error.code === "ENOENT")
+      return;
+    throw error;
+  }
+  const { contents } = file;
+  if (contents.includes(0)) {
+    throw new Error(`Harness context file must be UTF-8 text: ${resolved.relativePath}`);
   }
-  const handle = await open3(resolved.path, fsConstants2.O_RDONLY | fsConstants2.O_NOFOLLOW);
+  let content;
   try {
-    const opened = await handle.stat();
-    if (!opened.isFile() || !stableEntry(before, opened)) {
-      throw new Error(`Harness context file changed while opening: ${resolved.relativePath}`);
-    }
-    const contents = await handle.readFile();
-    const after = await handle.stat();
-    if (!stableEntry(opened, after) || contents.byteLength !== after.size) {
-      throw new Error(`Harness context file changed while reading: ${resolved.relativePath}`);
-    }
-    if (contents.includes(0)) {
-      throw new Error(`Harness context file must be UTF-8 text: ${resolved.relativePath}`);
-    }
-    let content;
-    try {
-      content = new TextDecoder("utf-8", { fatal: true }).decode(contents);
-    } catch {
-      throw new Error(`Harness context file must be valid UTF-8: ${resolved.relativePath}`);
-    }
-    return {
-      path: resolved.relativePath,
-      digest: digestBytes2(contents),
-      bytes: contents.byteLength,
-      content
-    };
-  } finally {
-    await handle.close();
+    content = new TextDecoder("utf-8", { fatal: true }).decode(contents);
+  } catch {
+    throw new Error(`Harness context file must be valid UTF-8: ${resolved.relativePath}`);
   }
+  return {
+    path: resolved.relativePath,
+    digest: digestBytes2(contents),
+    bytes: contents.byteLength,
+    content
+  };
 };
 var parseConfiguration = (file) => {
   let document;
@@ -6469,7 +6601,6 @@ var normalizeScope = (scope) => {
 var stableKey = (kind, value) => createHash9("sha256").update(kind).update("\x00").update(value).digest("hex");
 var sessionId = () => `ses_${randomUUID5()}`;
 var turnId = () => `turn_${randomUUID5()}`;
-var isMissing = (error) => error.code === "ENOENT";
 var ensurePrivateDatabase = async (workspace, stateDirectory) => {
   const requestedStateDirectory = path11.resolve(stateDirectory);
   await validateStateDirectory(workspace, requestedStateDirectory);
@@ -6483,19 +6614,12 @@ var ensurePrivateDatabase = async (workspace, stateDirectory) => {
   const databasePath = path11.join(canonicalStateDirectory2, HARNESS_SESSION_INDEX_FILE);
   let databaseEntry;
   try {
+    const handle = await open4(databasePath, "wx", 384);
+    await handle.close();
     databaseEntry = await lstat8(databasePath);
   } catch (error) {
-    if (!isMissing(error)) {
+    if (error.code !== "EEXIST")
       throw error;
-    }
-    try {
-      const handle = await open4(databasePath, "wx", 384);
-      await handle.close();
-    } catch (creationError) {
-      if (creationError.code !== "EEXIST") {
-        throw creationError;
-      }
-    }
     databaseEntry = await lstat8(databasePath);
   }
   if (databaseEntry.isSymbolicLink() || !databaseEntry.isFile()) {
@@ -9274,14 +9398,11 @@ var inspectGit = async (workspace) => {
 var inspectScripts = async (workspace, allowedChecks) => {
   const packagePath = path12.join(workspace, "package.json");
   try {
-    const packageStat = await stat4(packagePath);
-    if (!packageStat.isFile() || packageStat.size > 1024 * 1024) {
-      return diagnostic("scripts", "warn", "package.json is not a readable regular file.", {
-        packageJson: false,
-        available: []
-      });
-    }
-    const packageJson = JSON.parse(await readFile4(packagePath, "utf8"));
+    const packageFile = await readRegularFileNoFollow(packagePath, {
+      label: "package.json",
+      maxBytes: 1024 * 1024
+    });
+    const packageJson = JSON.parse(packageFile.contents.toString("utf8"));
     const scripts = packageJson.scripts && typeof packageJson.scripts === "object" ? packageJson.scripts : {};
     const available = allowedChecks.filter((name) => typeof scripts[name] === "string");
     const missing = allowedChecks.filter((name) => typeof scripts[name] !== "string");
@@ -9816,22 +9937,22 @@ var MAX_CHANGE_ARTIFACT_BYTES = 64 * 1024 * 1024;
 var readStableCliArtifact = async (filePath, maxBytes) => {
   const absolute = path12.resolve(process.cwd(), filePath);
   try {
-    const before = await lstat9(absolute);
-    if (before.isSymbolicLink() || !before.isFile()) {
+    return (await readRegularFileNoFollow(absolute, {
+      label: `Change artifact ${filePath}`,
+      maxBytes
+    })).contents;
+  } catch (error) {
+    if (error instanceof CliUsageError)
+      throw error;
+    if (error instanceof UnsafeFileTypeError) {
       throw new CliUsageError(`Change artifact must be a regular non-symlink file: ${filePath}`);
     }
-    if (before.size > maxBytes) {
+    if (error instanceof FileSizeLimitError) {
       throw new CliUsageError(`Change artifact exceeds the ${maxBytes}-byte limit: ${filePath}`);
     }
-    const contents = await readFile4(absolute);
-    const after = await lstat9(absolute);
-    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
+    if (error instanceof FileChangedWhileReadingError) {
       throw new CliUsageError(`Change artifact changed while it was being read: ${filePath}`);
     }
-    return contents;
-  } catch (error) {
-    if (error instanceof CliUsageError)
-      throw error;
     const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
     if (typeof code === "string") {
       throw new CliUsageError(`Change artifact cannot be read (${code}): ${filePath}`);