@zhivex-ai/harness 0.8.0 → 0.9.0

package/dist/cli.js

@@ -4,9 +4,10 @@
 // src/cli.ts
 import { createInterface } from "readline/promises";
 import { randomUUID as randomUUID5 } from "crypto";
-import { constants as fsConstants } from "fs";
+import { constants as fsConstants2 } from "fs";
 import { access, lstat as lstat7, readFile as readFile4, stat as stat4 } from "fs/promises";
 import path9 from "path";
+import { z as z5 } from "zod";
 import {
   getAgentBudgetStatus as getAgentBudgetStatus3
 } from "@zhivex-ai/agents";
@@ -371,7 +372,7 @@ var HARNESS_CONFIG_SCHEMA_VERSION = 4;
 var HARNESS_STORE_BACKENDS = ["sqlite", "file"];
 var HARNESS_EXECUTION_BACKENDS = ["none", "oci"];
 var HARNESS_OCI_RUNTIMES = ["docker", "podman"];
-var HARNESS_EXECUTION_POLICY_VERSION = "2026-08-17-v1";
+var HARNESS_EXECUTION_POLICY_VERSION = "2026-08-20-v2";
 var DEFAULT_OCI_EXECUTION = {
   runtime: "docker",
   image: "oven/bun:1.3.7-slim",
@@ -869,6 +870,10 @@ var IGNORE_FILES = [".gitignore", ".zhivex-harnessignore"];
 var DEFAULT_CHECKS = ["test", "typecheck", "lint", "build"];
 var MAX_FILE_BYTES = 1024 * 1024;
 var MAX_TOOL_OUTPUT = 20000;
+var MAX_READ_BATCH_FILES = 20;
+var MAX_READ_BATCH_BYTES = 2 * MAX_FILE_BYTES;
+var MAX_SEARCH_MANY_QUERIES = 10;
+var MAX_SEARCH_MANY_MATCHES = 500;
 var isSensitiveName = (name) => {
   const normalized = name.toLocaleLowerCase();
   return normalized === ".env" || normalized.startsWith(".env.") && normalized !== ".env.example" || normalized === ".npmrc" || normalized === "id_rsa" || normalized === "id_ed25519" || normalized.endsWith(".key") || normalized.endsWith(".pem") || normalized.endsWith(".p12") || normalized.endsWith(".pfx");
@@ -890,6 +895,30 @@ var cursorDecode = (value) => {
     throw new Error("The pagination cursor is invalid.");
   }
 };
+var firstPathAtLeast = (files, target) => {
+  let low = 0;
+  let high = files.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    if ((files[middle]?.path ?? "") < target)
+      low = middle + 1;
+    else
+      high = middle;
+  }
+  return low;
+};
+var firstPathAfter = (files, target) => {
+  let low = 0;
+  let high = files.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    if ((files[middle]?.path ?? "") <= target)
+      low = middle + 1;
+    else
+      high = middle;
+  }
+  return low;
+};
 var escapeRegex = (value) => value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
 var globRegex = (pattern) => {
   let source = "";
@@ -981,6 +1010,11 @@ var spawnBounded = async (command, cwd, timeoutMs = 120000) => {
 class Workspace {
   root;
   auditEntries = [];
+  indexIdentity = randomUUID();
+  indexRevision = 0;
+  workspaceIndex;
+  indexBuild;
+  indexMetrics = { builds: 0, reuses: 0, stableFileReads: 0 };
   constructor(root) {
     this.root = root;
   }
@@ -1032,6 +1066,7 @@ class Workspace {
     return { path: candidate, exists: true };
   }
   async readStableFile(relativePath, allowBinary = true) {
+    this.indexMetrics.stableFileReads += 1;
     const safe = await this.safePath(relativePath, { requireFile: true });
     const before = await lstat(safe.path);
     if (before.size > MAX_FILE_BYTES)
@@ -1051,14 +1086,40 @@ class Workspace {
       mode: before.mode & 511
     };
   }
-  async rulesForDirectory(directory, base, inherited) {
+  fingerprint(relativePath, kind, entry, digest2) {
+    return {
+      path: relativePath || ".",
+      kind,
+      dev: entry.dev,
+      ino: entry.ino,
+      size: entry.size,
+      mtimeMs: entry.mtimeMs,
+      ctimeMs: entry.ctimeMs,
+      ...digest2 ? { digest: digest2 } : {}
+    };
+  }
+  sameFingerprint(entry, fingerprint) {
+    return entry.dev === fingerprint.dev && entry.ino === fingerprint.ino && entry.size === fingerprint.size && entry.mtimeMs === fingerprint.mtimeMs && entry.ctimeMs === fingerprint.ctimeMs;
+  }
+  async rulesForDirectory(directory, base, inherited, ignoreFiles) {
     const rules = [...inherited];
     for (const filename of IGNORE_FILES) {
       try {
         const ignorePath = path3.join(directory, filename);
-        const entry = await lstat(ignorePath);
-        if (entry.isFile() && entry.size <= MAX_FILE_BYTES) {
-          rules.push(...parseIgnoreRules(await readFile(ignorePath, "utf8"), base));
+        const before = await lstat(ignorePath);
+        if (before.isSymbolicLink() || !before.isFile())
+          continue;
+        if (before.size <= MAX_FILE_BYTES) {
+          const contents = await readFile(ignorePath);
+          const after = await lstat(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(path3.relative(this.root, ignorePath))}`);
+          }
+          const digest2 = digestBytes(contents);
+          ignoreFiles.push(this.fingerprint(wirePath(path3.relative(this.root, ignorePath)), "ignore-file", after, digest2));
+          rules.push(...parseIgnoreRules(contents.toString("utf8"), base));
+        } else {
+          ignoreFiles.push(this.fingerprint(wirePath(path3.relative(this.root, ignorePath)), "ignore-file", before));
         }
       } catch (error) {
         if (error.code !== "ENOENT")
@@ -1067,10 +1128,17 @@ class Workspace {
     }
     return rules;
   }
-  async collectFiles() {
+  async collectFiles(version) {
     const files = [];
+    const directories = [];
+    const ignoreFiles = [];
     const walk = async (directory, base, inherited) => {
-      const rules = await this.rulesForDirectory(directory, base, inherited);
+      const directoryEntry = await lstat(directory);
+      if (directoryEntry.isSymbolicLink() || !directoryEntry.isDirectory()) {
+        throw new Error(`A workspace directory changed while it was being indexed: ${base || "."}`);
+      }
+      directories.push(this.fingerprint(base, "directory", directoryEntry));
+      const rules = await this.rulesForDirectory(directory, base, inherited, ignoreFiles);
       const entries = (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
       for (const entry of entries) {
         const relative = base ? `${base}/${entry.name}` : entry.name;
@@ -1080,11 +1148,99 @@ class Workspace {
         if (entry.isDirectory())
           await walk(absolute, relative, rules);
         else if (entry.isFile())
-          files.push({ path: relative, size: (await lstat(absolute)).size });
+          files.push({ path: relative });
       }
     };
     await walk(this.root, "", []);
-    return files;
+    files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    return { version, files, directories, ignoreFiles };
+  }
+  async isWorkspaceIndexFresh(index) {
+    try {
+      for (const fingerprint of index.directories) {
+        const absolute = fingerprint.path === "." ? this.root : path3.join(this.root, fingerprint.path);
+        const entry = await lstat(absolute);
+        if (entry.isSymbolicLink() || !entry.isDirectory() || !this.sameFingerprint(entry, fingerprint))
+          return false;
+      }
+      for (const fingerprint of index.ignoreFiles) {
+        const absolute = path3.join(this.root, fingerprint.path);
+        const before = await lstat(absolute);
+        if (before.isSymbolicLink() || !before.isFile() || !this.sameFingerprint(before, fingerprint))
+          return false;
+        if (fingerprint.digest) {
+          const contents = await readFile(absolute);
+          const after = await lstat(absolute);
+          if (after.isSymbolicLink() || !after.isFile() || !this.sameFingerprint(after, fingerprint) || digestBytes(contents) !== fingerprint.digest)
+            return false;
+        }
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  invalidateWorkspaceIndex() {
+    this.indexRevision += 1;
+    this.workspaceIndex = undefined;
+  }
+  async buildWorkspaceIndex(revision) {
+    const version = `${this.indexIdentity}:${revision}`;
+    for (let attempt = 0;attempt < 3; attempt += 1) {
+      try {
+        const index = await this.collectFiles(version);
+        if (await this.isWorkspaceIndexFresh(index))
+          return index;
+      } catch (error) {
+        const code = error.code;
+        const changedDuringIndexing = error instanceof Error && error.message.includes("while the workspace was being indexed");
+        if (attempt === 2 || code !== "ENOENT" && !changedDuringIndexing)
+          throw error;
+      }
+    }
+    throw new Error("The workspace kept changing while its file index was being built.");
+  }
+  async getWorkspaceIndex() {
+    const cached = this.workspaceIndex;
+    if (cached) {
+      if (await this.isWorkspaceIndexFresh(cached)) {
+        this.indexMetrics.reuses += 1;
+        return cached;
+      }
+      this.invalidateWorkspaceIndex();
+    }
+    const revision = this.indexRevision;
+    if (!this.indexBuild || this.indexBuild.revision !== revision) {
+      const promise = this.buildWorkspaceIndex(revision);
+      this.indexBuild = { revision, promise };
+    }
+    const build = this.indexBuild;
+    let index;
+    try {
+      index = await build.promise;
+    } catch (error) {
+      if (this.indexBuild === build)
+        this.indexBuild = undefined;
+      throw error;
+    }
+    if (revision !== this.indexRevision)
+      return this.getWorkspaceIndex();
+    if (this.indexBuild === build)
+      this.indexBuild = undefined;
+    if (this.workspaceIndex?.version !== index.version) {
+      this.workspaceIndex = index;
+      this.indexMetrics.builds += 1;
+    }
+    return this.workspaceIndex;
+  }
+  workspaceIndexDiagnostics() {
+    const index = this.workspaceIndex;
+    return {
+      ...this.indexMetrics,
+      ...index ? { version: index.version } : {},
+      files: index?.files.length ?? 0,
+      directories: index?.directories.length ?? 0
+    };
   }
   async listFiles(relativePath = ".", options = {}) {
     const start = await this.safePath(relativePath);
@@ -1096,36 +1252,52 @@ class Workspace {
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > 5000)
       throw new Error("limit must be between 1 and 5000.");
     let after = "";
+    let cursorIndexVersion;
     if (input.cursor) {
       const parsed = cursorDecode(input.cursor);
-      if (parsed.v !== 1 || parsed.kind !== "list" || parsed.path !== requestPath || parsed.limit !== limit || typeof parsed.after !== "string") {
+      if (parsed.v !== 2 || parsed.kind !== "list" || parsed.path !== requestPath || parsed.limit !== limit || typeof parsed.indexVersion !== "string" || typeof parsed.after !== "string") {
         throw new Error("The pagination cursor does not match this list request.");
       }
       after = parsed.after;
+      cursorIndexVersion = parsed.indexVersion;
+    }
+    const index = await this.getWorkspaceIndex();
+    if (cursorIndexVersion && cursorIndexVersion !== index.version) {
+      throw new Error("The pagination cursor is stale because the workspace changed.");
     }
     const prefix = requestPath === "." ? "" : `${requestPath}/`;
-    const candidates = (await this.collectFiles()).filter((file) => (requestPath === "." || file.path.startsWith(prefix)) && file.path > after);
-    const selected = candidates.slice(0, limit);
+    let candidateIndex = after ? firstPathAfter(index.files, after) : requestPath === "." ? 0 : firstPathAtLeast(index.files, prefix);
+    const selected = [];
+    while (candidateIndex < index.files.length && selected.length <= limit) {
+      const candidate = index.files[candidateIndex];
+      if (!candidate || requestPath !== "." && !candidate.path.startsWith(prefix))
+        break;
+      selected.push(candidate);
+      candidateIndex += 1;
+    }
+    const truncated = selected.length > limit;
+    if (truncated)
+      selected.pop();
     const files = [];
     for (const candidate of selected) {
       const file = await this.readStableFile(candidate.path);
       files.push({ path: file.path, size: file.contents.byteLength, digest: file.digest });
     }
-    const truncated = candidates.length > selected.length;
     const last = selected.at(-1);
     return {
       files,
       truncated,
-      ...truncated && last ? { nextCursor: cursorEncode({ v: 1, kind: "list", path: requestPath, limit, after: last.path }) } : {}
+      ...truncated && last ? {
+        nextCursor: cursorEncode({ v: 2, kind: "list", path: requestPath, limit, after: last.path, indexVersion: index.version })
+      } : {}
     };
   }
-  async readFile(relativePath, startLine = 1, endLine) {
+  renderReadFile(file, startLine = 1, endLine) {
     if (!Number.isSafeInteger(startLine) || startLine < 1)
       throw new Error("startLine must be a positive integer.");
     if (endLine !== undefined && (!Number.isSafeInteger(endLine) || endLine < startLine)) {
       throw new Error("endLine must be greater than or equal to startLine.");
     }
-    const file = await this.readStableFile(relativePath, false);
     const lines = file.contents.toString("utf8").split(/\r?\n/);
     const boundedEnd = Math.min(endLine ?? startLine + 399, startLine + 1999, lines.length);
     return {
@@ -1139,6 +1311,37 @@ class Workspace {
       truncated: boundedEnd < lines.length
     };
   }
+  async readFile(relativePath, startLine = 1, endLine) {
+    return this.renderReadFile(await this.readStableFile(relativePath, false), startLine, endLine);
+  }
+  async readFiles(requests) {
+    if (!Array.isArray(requests) || requests.length < 1 || requests.length > MAX_READ_BATCH_FILES) {
+      throw new Error(`readFiles requires between 1 and ${MAX_READ_BATCH_FILES} file requests.`);
+    }
+    const ordered = requests.map((request) => ({
+      ...request,
+      path: wirePath(path3.relative(this.root, this.lexicalPath(request.path)))
+    })).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0) || (a.startLine ?? 1) - (b.startLine ?? 1) || (a.endLine ?? 0) - (b.endLine ?? 0));
+    const stableFiles = new Map;
+    let totalBytes = 0;
+    for (const request of ordered) {
+      if (!Number.isSafeInteger(request.startLine ?? 1) || (request.startLine ?? 1) < 1 || request.endLine !== undefined && (!Number.isSafeInteger(request.endLine) || request.endLine < (request.startLine ?? 1))) {
+        throw new Error(`Invalid line range for ${request.path}.`);
+      }
+      if (stableFiles.has(request.path))
+        continue;
+      const file = await this.readStableFile(request.path, false);
+      totalBytes += file.contents.byteLength;
+      if (totalBytes > MAX_READ_BATCH_BYTES) {
+        throw new Error(`readFiles exceeds the aggregate ${MAX_READ_BATCH_BYTES}-byte source limit.`);
+      }
+      stableFiles.set(request.path, file);
+    }
+    return {
+      files: ordered.map((request) => this.renderReadFile(stableFiles.get(request.path), request.startLine ?? 1, request.endLine)),
+      sourceBytes: totalBytes
+    };
+  }
   async inspectFile(relativePath) {
     const file = await this.readStableFile(relativePath);
     return {
@@ -1161,21 +1364,29 @@ class Workspace {
     const caseSensitive = options.caseSensitive ?? false;
     let afterPath = "";
     let afterLine = 0;
+    let cursorIndexVersion;
     if (options.cursor) {
       const parsed = cursorDecode(options.cursor);
-      if (parsed.v !== 1 || parsed.kind !== "search" || parsed.path !== requestPath || parsed.query !== query || parsed.caseSensitive !== caseSensitive || parsed.limit !== limit || typeof parsed.afterPath !== "string" || !Number.isSafeInteger(parsed.afterLine)) {
+      if (parsed.v !== 2 || parsed.kind !== "search" || parsed.path !== requestPath || parsed.query !== query || parsed.caseSensitive !== caseSensitive || parsed.limit !== limit || typeof parsed.afterPath !== "string" || !Number.isSafeInteger(parsed.afterLine) || typeof parsed.indexVersion !== "string") {
         throw new Error("The pagination cursor does not match this search request.");
       }
       afterPath = parsed.afterPath;
       afterLine = parsed.afterLine;
+      cursorIndexVersion = parsed.indexVersion;
+    }
+    const index = await this.getWorkspaceIndex();
+    if (cursorIndexVersion && cursorIndexVersion !== index.version) {
+      throw new Error("The pagination cursor is stale because the workspace changed.");
     }
     const prefix = requestPath === "." ? "" : `${requestPath}/`;
     const needle = caseSensitive ? query : query.toLocaleLowerCase();
     const matches = [];
     let hasMore = false;
-    for (const candidate of await this.collectFiles()) {
-      if (requestPath !== "." && !candidate.path.startsWith(prefix) || candidate.size > MAX_FILE_BYTES || candidate.path < afterPath)
-        continue;
+    let candidateIndex = afterPath ? firstPathAtLeast(index.files, afterPath) : requestPath === "." ? 0 : firstPathAtLeast(index.files, prefix);
+    for (;candidateIndex < index.files.length; candidateIndex += 1) {
+      const candidate = index.files[candidateIndex];
+      if (!candidate || requestPath !== "." && !candidate.path.startsWith(prefix))
+        break;
       let file;
       try {
         file = await this.readStableFile(candidate.path, false);
@@ -1183,11 +1394,11 @@ class Workspace {
         continue;
       }
       const lines = file.contents.toString("utf8").split(/\r?\n/);
-      for (let index = 0;index < lines.length; index += 1) {
-        const lineNumber = index + 1;
+      for (let index2 = 0;index2 < lines.length; index2 += 1) {
+        const lineNumber = index2 + 1;
         if (candidate.path === afterPath && lineNumber <= afterLine)
           continue;
-        const line = lines[index] ?? "";
+        const line = lines[index2] ?? "";
         if (!(caseSensitive ? line : line.toLocaleLowerCase()).includes(needle))
           continue;
         if (matches.length >= limit) {
@@ -1204,10 +1415,88 @@ class Workspace {
       matches,
       truncated: hasMore,
       ...hasMore && last ? {
-        nextCursor: cursorEncode({ v: 1, kind: "search", path: requestPath, query, caseSensitive, limit, afterPath: last.path, afterLine: last.line })
+        nextCursor: cursorEncode({
+          v: 2,
+          kind: "search",
+          path: requestPath,
+          query,
+          caseSensitive,
+          limit,
+          afterPath: last.path,
+          afterLine: last.line,
+          indexVersion: index.version
+        })
       } : {}
     };
   }
+  async searchMany(queries, relativePath = ".", options = {}) {
+    if (!Array.isArray(queries) || queries.length < 1 || queries.length > MAX_SEARCH_MANY_QUERIES) {
+      throw new Error(`searchMany requires between 1 and ${MAX_SEARCH_MANY_QUERIES} queries.`);
+    }
+    const limitPerQuery = options.limitPerQuery ?? 50;
+    if (!Number.isSafeInteger(limitPerQuery) || limitPerQuery < 1 || limitPerQuery > MAX_SEARCH_MANY_MATCHES || limitPerQuery * queries.length > MAX_SEARCH_MANY_MATCHES) {
+      throw new Error(`searchMany allows at most ${MAX_SEARCH_MANY_MATCHES} aggregate matches.`);
+    }
+    const seen = new Set;
+    const states = queries.map((input) => {
+      if (!input.query || input.query.length > 200)
+        throw new Error("Each search query must be between 1 and 200 characters.");
+      const caseSensitive = input.caseSensitive ?? false;
+      const key = `${caseSensitive ? "1" : "0"}\x00${input.query}`;
+      if (seen.has(key))
+        throw new Error("searchMany queries must be unique.");
+      seen.add(key);
+      return {
+        query: input.query,
+        caseSensitive,
+        needle: caseSensitive ? input.query : input.query.toLocaleLowerCase(),
+        matches: [],
+        truncated: false
+      };
+    });
+    const start = await this.safePath(relativePath);
+    if (!(await lstat(start.path)).isDirectory())
+      throw new Error("searchMany requires a directory.");
+    const requestPath = wirePath(path3.relative(this.root, start.path)) || ".";
+    const prefix = requestPath === "." ? "" : `${requestPath}/`;
+    const index = await this.getWorkspaceIndex();
+    let candidateIndex = requestPath === "." ? 0 : firstPathAtLeast(index.files, prefix);
+    for (;candidateIndex < index.files.length; candidateIndex += 1) {
+      const candidate = index.files[candidateIndex];
+      if (!candidate || requestPath !== "." && !candidate.path.startsWith(prefix))
+        break;
+      let file;
+      try {
+        file = await this.readStableFile(candidate.path, false);
+      } catch {
+        continue;
+      }
+      const lines = file.contents.toString("utf8").split(/\r?\n/);
+      for (let lineIndex = 0;lineIndex < lines.length; lineIndex += 1) {
+        const line = lines[lineIndex] ?? "";
+        const foldedLine = line.toLocaleLowerCase();
+        for (const state of states) {
+          if (state.truncated || !(state.caseSensitive ? line : foldedLine).includes(state.needle))
+            continue;
+          if (state.matches.length >= limitPerQuery) {
+            state.truncated = true;
+            continue;
+          }
+          state.matches.push({
+            path: candidate.path,
+            line: lineIndex + 1,
+            text: truncate(line, 500),
+            digest: file.digest
+          });
+        }
+      }
+      if (states.every((state) => state.truncated))
+        break;
+    }
+    return {
+      results: states.map(({ needle: _needle, ...state }) => state)
+    };
+  }
   audit(entry) {
     const record = { id: randomUUID(), timestamp: new Date().toISOString(), ...entry };
     this.auditEntries.push(record);
@@ -1371,6 +1660,7 @@ class Workspace {
         throw new AggregateError([error, ...rollbackErrors], "Patch failed and rollback was incomplete.");
       throw error;
     }
+    this.invalidateWorkspaceIndex();
     const changes = prepared.map((item) => this.audit({
       operation: item.before ? "update" : "create",
       path: item.change.path,
@@ -1431,6 +1721,7 @@ class Workspace {
         await unlink(destination.path).catch(() => {});
       throw error;
     }
+    this.invalidateWorkspaceIndex();
     const audit = this.audit({ operation: "move", path: parsed.source, destination: parsed.destination, beforeDigest: source.digest, afterDigest: source.digest });
     return { source: parsed.source, destination: parsed.destination, digest: source.digest, audit };
   }
@@ -1519,6 +1810,7 @@ class Workspace {
       await unlink(path3.join(directory, `${quarantineId}.json`)).catch(() => {});
       throw error;
     }
+    this.invalidateWorkspaceIndex();
     const audit = this.audit({ operation: "quarantine", path: parsed.path, beforeDigest: source.digest, quarantineId });
     return { quarantineId, path: parsed.path, digest: source.digest, audit };
   }
@@ -1587,6 +1879,7 @@ class Workspace {
       }
       throw rollbackErrors.length ? new AggregateError([error, ...rollbackErrors], "Restore failed and rollback was incomplete.") : error;
     }
+    this.invalidateWorkspaceIndex();
     const audit = this.audit({ operation: "restore", path: destinationPath, afterDigest: digest2, quarantineId: parsed.quarantineId });
     return { quarantineId: parsed.quarantineId, path: destinationPath, digest: digest2, audit };
   }
@@ -1607,7 +1900,11 @@ class Workspace {
       throw new Error(`package.json does not define the "${check}" script.`);
     if (scripts[check] !== expectedScript)
       throw new Error(`The "${check}" script changed or does not match expectedScript.`);
-    return spawnBounded(["bun", "--no-env-file", "run", check], this.root);
+    try {
+      return await spawnBounded(["bun", "--no-env-file", "run", check], this.root);
+    } finally {
+      this.invalidateWorkspaceIndex();
+    }
   }
   async gitDiff() {
     const [statusResult, diffResult, stagedResult] = await Promise.all([
@@ -2389,7 +2686,7 @@ var HARNESS_SUBAGENT_PROFILE_DESCRIPTORS = [
     toolName: "delegate_explorer",
     description: "Delegate bounded repository discovery to a read-only explorer.",
     instructions: "Inspect the repository with read-only tools. Return evidence with paths and concrete findings. Never propose or perform mutations.",
-    toolNames: ["list_files", "read_file", "search_files", "git_diff"]
+    toolNames: ["list_files", "read_file", "read_files", "search_files", "search_many", "git_diff"]
   },
   {
     id: "implementer",
@@ -2403,14 +2700,14 @@ var HARNESS_SUBAGENT_PROFILE_DESCRIPTORS = [
     toolName: "delegate_tester",
     description: "Delegate focused verification to a tester with read-only inspection and approved Bun checks.",
     instructions: "Verify the delegated behavior with repository evidence and declared Bun checks. Do not edit files. Report exact failures and limits.",
-    toolNames: ["list_files", "read_file", "search_files", "run_check", "git_diff"]
+    toolNames: ["list_files", "read_file", "read_files", "search_files", "search_many", "run_check", "git_diff"]
   },
   {
     id: "reviewer",
     toolName: "delegate_reviewer",
     description: "Delegate an independent read-only review of correctness, safety, and regressions.",
     instructions: "Review the requested scope independently. Inspect concrete code and diffs, prioritize actionable defects, and do not mutate the workspace.",
-    toolNames: ["list_files", "read_file", "search_files", "mutation_audit", "git_diff"]
+    toolNames: ["list_files", "read_file", "read_files", "search_files", "search_many", "mutation_audit", "git_diff"]
   }
 ];
 var pickTools = (tools, names) => {
@@ -2548,8 +2845,10 @@ var runHarnessReviewGroup = async (runtime, input, profiles = ["explorer", "revi
 
 // src/execution-environment.ts
 import { createHash as createHash6, randomUUID as randomUUID3 } from "crypto";
+import { constants as fsConstants } from "fs";
 import {
   chmod as chmod2,
+  copyFile,
   lstat as lstat5,
   mkdir as mkdir3,
   readFile as readFile3,
@@ -2573,7 +2872,9 @@ var TERMINAL_STATUSES = new Set([
 var BUILT_IN_TOOL_NAMES = new Set([
   "list_files",
   "read_file",
+  "read_files",
   "search_files",
+  "search_many",
   "propose_edits",
   "apply_patch",
   "move_file",
@@ -2698,11 +2999,26 @@ var parseRuntimeVersion = (stdout, runtime) => {
 var validContainerIds = (stdout) => stdout.split(/\r?\n/).map((value) => value.trim()).filter((value) => /^[a-f0-9]{12,64}$/.test(value));
 var validVolumeNames = (stdout) => stdout.split(/\r?\n/).map((value) => value.trim()).filter((value) => /^zhivex-harness-[A-Za-z0-9_.-]+$/.test(value));
 var MAX_SYNC_ENTRIES = 1e4;
+var updateSnapshotMetadata = (target, kind, relative, entry) => {
+  target.update([
+    kind,
+    relative,
+    entry.dev,
+    entry.ino,
+    entry.size,
+    entry.mtimeMs,
+    entry.ctimeMs,
+    entry.mode & 511
+  ].join("\x00"));
+  target.update("\x00");
+};
 var validateSynchronizedSnapshot = async (stagedRoot, previousRoot, maxWorkspaceBytes, maxFileWriteBytes) => {
   let entries = 0;
   let totalBytes = 0;
+  const seal = createHash6("sha256");
+  const metadata = createHash6("sha256");
   const visit = async (directory, relativeDirectory = "") => {
-    for (const name of await readdir2(directory)) {
+    for (const name of (await readdir2(directory)).sort()) {
       const relative = relativeDirectory ? `${relativeDirectory}/${name}` : name;
       const absolute = path7.join(directory, name);
       if (!isInside3(stagedRoot, absolute) || relative.length > 1024) {
@@ -2721,22 +3037,32 @@ var validateSynchronizedSnapshot = async (stagedRoot, previousRoot, maxWorkspace
         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`);
         await visit(absolute, relative);
         continue;
       }
       if (!entry.isFile() || entry.nlink !== 1) {
         throw new Error(`OCI workspace export contains a special or linked file: ${relative}.`);
       }
+      const contents = await readFile3(absolute);
+      const after = await lstat5(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}.`);
+      }
       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);
+      seal.update(`file\x00${relative}\x00${entry.mode & 511}\x00${entry.size}\x00${contentDigest}\x00`);
       if (entry.size > maxFileWriteBytes) {
         const previous = path7.join(previousRoot, ...relative.split("/"));
         let unchanged = false;
         try {
           const previousEntry = await lstat5(previous);
-          unchanged = previousEntry.isFile() && !previousEntry.isSymbolicLink() && previousEntry.size === entry.size && digest2(await readFile3(previous)) === digest2(await readFile3(absolute));
+          unchanged = previousEntry.isFile() && !previousEntry.isSymbolicLink() && previousEntry.size === entry.size && digest2(await readFile3(previous)) === contentDigest;
         } catch (error) {
           if (error.code !== "ENOENT")
             throw error;
@@ -2748,6 +3074,51 @@ var validateSynchronizedSnapshot = async (stagedRoot, previousRoot, maxWorkspace
     }
   };
   await visit(stagedRoot);
+  return {
+    entries,
+    totalBytes,
+    seal: `sha256:${seal.digest("hex")}`,
+    metadataFingerprint: `sha256:${metadata.digest("hex")}`
+  };
+};
+var snapshotMetadataFingerprint = async (root, maxWorkspaceBytes) => {
+  let entries = 0;
+  let totalBytes = 0;
+  const metadata = createHash6("sha256");
+  const visit = async (directory, relativeDirectory = "") => {
+    for (const name of (await readdir2(directory)).sort()) {
+      const relative = relativeDirectory ? `${relativeDirectory}/${name}` : name;
+      if (relative === "node_modules")
+        continue;
+      const absolute = path7.join(directory, name);
+      if (!isInside3(root, absolute) || relative.length > 1024) {
+        throw new Error(`OCI workspace snapshot contains an invalid path: ${relative}.`);
+      }
+      entries += 1;
+      if (entries > MAX_SYNC_ENTRIES) {
+        throw new Error(`OCI workspace snapshot exceeds the ${MAX_SYNC_ENTRIES}-entry limit.`);
+      }
+      const entry = await lstat5(absolute);
+      if (entry.isSymbolicLink()) {
+        throw new Error(`OCI workspace snapshot contains a symbolic link: ${relative}.`);
+      }
+      if (entry.isDirectory()) {
+        updateSnapshotMetadata(metadata, "directory", relative, entry);
+        await visit(absolute, relative);
+        continue;
+      }
+      if (!entry.isFile() || entry.nlink !== 1) {
+        throw new Error(`OCI workspace snapshot contains a special or linked file: ${relative}.`);
+      }
+      totalBytes += entry.size;
+      if (totalBytes > maxWorkspaceBytes) {
+        throw new Error(`OCI workspace snapshot exceeds the ${maxWorkspaceBytes}-byte workspace limit.`);
+      }
+      updateSnapshotMetadata(metadata, "file", relative, entry);
+    }
+  };
+  await visit(root);
+  return `sha256:${metadata.digest("hex")}`;
 };
 var replaceSnapshot = async (snapshotRoot, stagedRoot) => {
   const backupRoot = `${snapshotRoot}.${randomUUID3()}.previous`;
@@ -2762,10 +3133,42 @@ var replaceSnapshot = async (snapshotRoot, stagedRoot) => {
   }
   await rm(backupRoot, { recursive: true, force: true });
 };
+var OCI_WORKSPACE_SEAL_SCRIPT = [
+  "import { createHash } from 'node:crypto';",
+  "import { lstat, readFile, readdir, readlink, rm } from 'node:fs/promises';",
+  "import path from 'node:path';",
+  "const root='/workspace';",
+  "const seal=createHash('sha256');",
+  "const modules=path.join(root,'node_modules');",
+  "if(process.env.ZHIVEX_HARNESS_HAS_DEPENDENCIES==='1'){const entry=await lstat(modules);if(!entry.isSymbolicLink()||(await readlink(modules))!=='/dependencies')throw new Error('read-only dependency mount was replaced');}else{await rm(modules,{recursive:true,force:true});}",
+  "const digest=(value)=>`sha256:${createHash('sha256').update(value).digest('hex')}`;",
+  "const same=(before,after)=>before.dev===after.dev&&before.ino===after.ino&&before.size===after.size&&before.mtimeMs===after.mtimeMs&&before.ctimeMs===after.ctimeMs&&(before.mode&0o777)===(after.mode&0o777);",
+  "const visit=async(directory,base='')=>{",
+  "for(const name of (await readdir(directory)).sort()){",
+  "const relative=base?`${base}/${name}`:name;",
+  "if(relative==='node_modules')continue;",
+  "const absolute=path.join(directory,name);",
+  "const entry=await lstat(absolute);",
+  "if(entry.isSymbolicLink())throw new Error(`symbolic link: ${relative}`);",
+  "if(entry.isDirectory()){seal.update(`directory\\0${relative}\\0${entry.mode&0o777}\\0`);await visit(absolute,relative);continue;}",
+  "if(!entry.isFile()||entry.nlink!==1)throw new Error(`special or linked file: ${relative}`);",
+  "const contents=await readFile(absolute);",
+  "const after=await lstat(absolute);",
+  "if(!same(entry,after))throw new Error(`changed while sealing: ${relative}`);",
+  "seal.update(`file\\0${relative}\\0${entry.mode&0o777}\\0${entry.size}\\0${digest(contents)}\\0`);",
+  "}",
+  "};",
+  "await visit(root);",
+  "for(const name of await readdir('/tmp'))await rm(path.join('/tmp',name),{recursive:true,force:true});",
+  "console.log(`sha256:${seal.digest('hex')}`);"
+].join("");
+var OCI_SESSION_CONTROLLER_SCRIPT = "setInterval(()=>{},2147483647);";
 
 class CliOciRuntimeAdapter {
   runtime;
   hostEnvironment;
+  sessions = new Map;
+  runQueues = new Map;
   constructor(runtime) {
     this.runtime = runtime;
     this.hostEnvironment = Object.fromEntries(["DOCKER_CONFIG", "DOCKER_CONTEXT", "DOCKER_HOST", "HOME", "PATH", "XDG_RUNTIME_DIR"].flatMap((name) => process.env[name] ? [[name, process.env[name]]] : []));
@@ -2818,10 +3221,44 @@ ${result.stdout}`)) {
       throw new Error(`${this.runtime} could not remove OCI workspace volume ${name}: ${result.stderr.trim()}`);
     }
   }
-  async run(request) {
+  requestFingerprint(request) {
+    return digest2(JSON.stringify({
+      runId: request.runId,
+      snapshotRoot: request.snapshotRoot,
+      dependencyRoot: request.dependencyRoot ?? null,
+      imageId: request.imageId,
+      limits: request.limits
+    }));
+  }
+  async withRunLock(runId, operation) {
+    const key = runHash(runId);
+    const previous = this.runQueues.get(key) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => {
+      release = resolve;
+    });
+    const tail = previous.then(() => gate, () => gate);
+    this.runQueues.set(key, tail);
+    await previous.catch(() => {
+      return;
+    });
+    try {
+      return await operation();
+    } finally {
+      release();
+      if (this.runQueues.get(key) === tail)
+        this.runQueues.delete(key);
+    }
+  }
+  async destroySession(session) {
+    if (this.sessions.get(session.key) === session)
+      this.sessions.delete(session.key);
+    await this.forceRemove(session.name);
+    await this.removeVolume(session.volumeName);
+  }
+  async createSession(request, requestFingerprint, snapshotSeal, hostFingerprint) {
     const resourceName = `zhivex-harness-${runHash(request.runId)}-${randomUUID3().slice(0, 8)}`;
     const name = `${resourceName}-job`;
-    const exportName = `${resourceName}-export`;
     const volumeName = `${resourceName}-workspace`;
     const uid = process.getuid?.() ?? 65532;
     const gid = process.getgid?.() ?? 65532;
@@ -2877,8 +3314,6 @@ ${result.stdout}`)) {
       "BUN_INSTALL_CACHE_DIR=/tmp/bun-cache",
       "--env",
       "CI=1",
-      "--volume",
-      `${request.snapshotRoot}:/seed:ro`,
       ...request.dependencyRoot ? ["--volume", `${request.dependencyRoot}:/dependencies:ro`] : [],
       "--workdir",
       "/workspace",
@@ -2886,26 +3321,19 @@ ${result.stdout}`)) {
       "bun",
       request.imageId,
       "-e",
-      `await Bun.sleep(${request.limits.maxProcessRuntimeMs + 60000})`
+      OCI_SESSION_CONTROLLER_SCRIPT
     ];
-    let forcedRemoval;
-    const forceRemove = () => {
-      forcedRemoval ??= this.forceRemove(name);
-    };
+    let volumeCreated = false;
     try {
       await this.cli(volumeArgs);
+      volumeCreated = true;
       await this.cli(args);
       await this.cli(["start", name]);
       await this.cli([
-        "exec",
-        "--workdir",
-        "/workspace",
-        "--user",
-        `${uid}:${gid}`,
-        name,
-        "bun",
-        "-e",
-        "import { cp } from 'node:fs/promises'; await cp('/seed', '/workspace', { recursive: true, force: false, errorOnExist: true })"
+        "cp",
+        "-a",
+        `${request.snapshotRoot}${path7.sep}.`,
+        `${name}:/workspace`
       ], 60000);
       if (request.dependencyRoot) {
         await this.cli([
@@ -2920,88 +3348,183 @@ ${result.stdout}`)) {
           "import { symlink } from 'node:fs/promises'; await symlink('/dependencies', '/workspace/node_modules', 'dir')"
         ]);
       }
-      const result = await spawnBounded2([
-        this.runtime,
+      await this.cli(["pause", name]);
+      const session = {
+        key: runHash(request.runId),
+        requestFingerprint,
+        name,
+        volumeName,
+        snapshotSeal,
+        hostFingerprint,
+        paused: true
+      };
+      this.sessions.set(session.key, session);
+      return session;
+    } catch (error) {
+      await this.forceRemove(name);
+      if (volumeCreated)
+        await this.removeVolume(volumeName).catch(() => {
+          return;
+        });
+      throw error;
+    }
+  }
+  async onlyControllerProcessRemains(session) {
+    const result = await this.cli(this.runtime === "podman" ? ["top", session.name, "pid"] : ["top", session.name, "-eo", "pid"]);
+    const processIds = result.stdout.split(/\r?\n/).filter((line) => /^\s*\d+\s*$/.test(line));
+    return processIds.length === 1;
+  }
+  async containerWorkspaceSeal(session, uid, gid, hasDependencies) {
+    if (session.paused) {
+      await this.cli(["unpause", session.name]);
+      session.paused = false;
+    }
+    try {
+      const result = await this.cli([
         "exec",
         "--workdir",
         "/workspace",
         "--user",
         `${uid}:${gid}`,
-        name,
-        ...request.command
-      ], {
-        env: this.hostEnvironment,
-        timeoutMs: request.limits.maxProcessRuntimeMs,
-        maxOutputBytes: request.limits.maxProcessOutputBytes,
-        ...request.abortSignal ? { abortSignal: request.abortSignal } : {},
-        onStop: forceRemove
-      });
-      if (result.timedOut || result.cancelled || result.outputLimitExceeded) {
-        forceRemove();
-        await forcedRemoval;
-      } else if (result.exitCode === 0) {
-        await this.cli(["pause", name]);
-        const stagedRoot = path7.join(path7.dirname(request.snapshotRoot), `.workspace-sync-${randomUUID3()}`);
-        try {
-          await privateDirectory(stagedRoot);
-          try {
-            await this.cli([
-              "run",
-              "--rm",
-              "--name",
-              exportName,
-              "--label",
-              `${HARNESS_OCI_LABEL}=${HARNESS_OCI_LABEL_VALUE}`,
-              "--label",
-              `com.zhivex.harness.run=${runHash(request.runId)}`,
-              "--network",
-              "none",
-              "--read-only",
-              "--cap-drop",
-              "ALL",
-              "--security-opt",
-              "no-new-privileges",
-              "--pids-limit",
-              "32",
-              "--memory",
-              "256m",
-              "--cpus",
-              "1",
-              "--tmpfs",
-              "/tmp:rw,noexec,nosuid,nodev,size=16m",
-              "--user",
-              `${uid}:${gid}`,
-              "--volume",
-              `${volumeName}:/workspace:ro`,
-              "--volume",
-              `${stagedRoot}:/export:rw`,
-              "--workdir",
-              "/workspace",
-              "--entrypoint",
-              "bun",
-              request.imageId,
-              "-e",
-              "import { cp } from 'node:fs/promises'; await cp('/workspace', '/export', { recursive: true, force: false, errorOnExist: true })"
-            ], 60000);
-          } finally {
-            await this.forceRemove(exportName);
-          }
-          await validateSynchronizedSnapshot(stagedRoot, request.snapshotRoot, request.limits.maxWorkspaceBytes, request.limits.maxFileWriteBytes);
-          await replaceSnapshot(request.snapshotRoot, stagedRoot);
-        } finally {
-          await rm(stagedRoot, { recursive: true, force: true });
-        }
+        "--env",
+        `ZHIVEX_HARNESS_HAS_DEPENDENCIES=${hasDependencies ? "1" : "0"}`,
+        session.name,
+        "bun",
+        "-e",
+        OCI_WORKSPACE_SEAL_SCRIPT
+      ], 60000, 20000);
+      const seal = result.stdout.trim();
+      if (!/^sha256:[a-f0-9]{64}$/.test(seal)) {
+        throw new Error("OCI workspace seal helper returned an invalid digest.");
       }
-      return {
-        ...result,
-        command: request.command
-      };
+      return seal;
     } finally {
+      if (!session.paused) {
+        await this.cli(["pause", session.name]);
+        session.paused = true;
+      }
+    }
+  }
+  async runInSession(request, session, sessionReused) {
+    const uid = process.getuid?.() ?? 65532;
+    const gid = process.getgid?.() ?? 65532;
+    if (session.paused) {
+      await this.cli(["unpause", session.name]);
+      session.paused = false;
+    }
+    let forcedRemoval;
+    const forceRemove = () => {
+      forcedRemoval ??= this.forceRemove(session.name);
+    };
+    const result = await spawnBounded2([
+      this.runtime,
+      "exec",
+      "--workdir",
+      "/workspace",
+      "--user",
+      `${uid}:${gid}`,
+      session.name,
+      ...request.command
+    ], {
+      env: this.hostEnvironment,
+      timeoutMs: request.limits.maxProcessRuntimeMs,
+      maxOutputBytes: request.limits.maxProcessOutputBytes,
+      ...request.abortSignal ? { abortSignal: request.abortSignal } : {},
+      onStop: forceRemove
+    });
+    if (result.exitCode !== 0 || result.timedOut || result.cancelled || result.outputLimitExceeded) {
       forceRemove();
       await forcedRemoval;
-      await this.removeVolume(volumeName);
+      await this.destroySession(session);
+      return {
+        ...result,
+        command: request.command,
+        sessionReused,
+        workspacePublished: false,
+        workspaceExported: false
+      };
+    }
+    try {
+      if (!await this.onlyControllerProcessRemains(session)) {
+        await this.destroySession(session);
+        return {
+          ...result,
+          command: request.command,
+          exitCode: 126,
+          stderr: [
+            result.stderr,
+            "OCI command left background processes running; its workspace changes were discarded."
+          ].filter(Boolean).join(`
+`),
+          sessionReused,
+          workspacePublished: false,
+          workspaceExported: false
+        };
+      }
+      const workspaceSeal = await this.containerWorkspaceSeal(session, uid, gid, Boolean(request.dependencyRoot));
+      if (workspaceSeal === session.snapshotSeal) {
+        return {
+          ...result,
+          command: request.command,
+          sessionReused,
+          workspacePublished: true,
+          workspaceExported: false
+        };
+      }
+      const stagedRoot = path7.join(path7.dirname(request.snapshotRoot), `.workspace-sync-${randomUUID3()}`);
+      try {
+        await privateDirectory(stagedRoot);
+        await this.cli(["cp", `${session.name}:/workspace/.`, stagedRoot], 60000);
+        const validated = await validateSynchronizedSnapshot(stagedRoot, request.snapshotRoot, request.limits.maxWorkspaceBytes, request.limits.maxFileWriteBytes);
+        await replaceSnapshot(request.snapshotRoot, stagedRoot);
+        session.snapshotSeal = validated.seal;
+        session.hostFingerprint = validated.metadataFingerprint;
+      } finally {
+        await rm(stagedRoot, { recursive: true, force: true });
+      }
+      return {
+        ...result,
+        command: request.command,
+        sessionReused,
+        workspacePublished: true,
+        workspaceExported: true
+      };
+    } catch (error) {
+      await this.destroySession(session);
+      throw error;
     }
   }
+  async runLocked(request) {
+    const key = runHash(request.runId);
+    const requestFingerprint = this.requestFingerprint(request);
+    let session = this.sessions.get(key);
+    let sessionReused = Boolean(session);
+    let validated;
+    if (session) {
+      const hostFingerprint = await snapshotMetadataFingerprint(request.snapshotRoot, request.limits.maxWorkspaceBytes);
+      if (session.requestFingerprint !== requestFingerprint || session.hostFingerprint !== hostFingerprint) {
+        await this.destroySession(session);
+        session = undefined;
+        sessionReused = false;
+      }
+    }
+    if (!session) {
+      validated = await validateSynchronizedSnapshot(request.snapshotRoot, request.snapshotRoot, request.limits.maxWorkspaceBytes, request.limits.maxFileWriteBytes);
+      session = await this.createSession(request, requestFingerprint, validated.seal, validated.metadataFingerprint);
+    }
+    try {
+      return await this.runInSession(request, session, sessionReused);
+    } catch (error) {
+      if (this.sessions.get(key) === session)
+        await this.destroySession(session).catch(() => {
+          return;
+        });
+      throw error;
+    }
+  }
+  async run(request) {
+    return this.withRunLock(request.runId, () => this.runLocked(request));
+  }
   async removeByFilters(filters) {
     const listed = await spawnBounded2([this.runtime, "ps", "-aq", ...filters.flatMap((filter) => ["--filter", filter])], {
       env: this.hostEnvironment,
@@ -3047,15 +3570,23 @@ ${result.stdout}`)) {
     return removed;
   }
   async removeRunContainers(runId) {
+    const key = runHash(runId);
+    const session = this.sessions.get(key);
+    let cachedResources = 0;
+    if (session) {
+      await this.destroySession(session);
+      cachedResources = 2;
+    }
     const filters = [
       `label=${HARNESS_OCI_LABEL}=${HARNESS_OCI_LABEL_VALUE}`,
-      `label=com.zhivex.harness.run=${runHash(runId)}`
+      `label=com.zhivex.harness.run=${key}`
     ];
     const containers = await this.removeByFilters(filters);
     const volumes = await this.removeVolumesByFilters(filters);
-    return containers + volumes;
+    return cachedResources + containers + volumes;
   }
   async cleanupOrphans() {
+    this.sessions.clear();
     let removed = 0;
     for (const status of ["created", "exited", "dead", "paused"]) {
       removed += await this.removeByFilters([
@@ -3069,34 +3600,81 @@ ${result.stdout}`)) {
     return removed;
   }
 }
-var collectSnapshotFiles = async (workspace) => {
+var SNAPSHOT_INVENTORY_PAGE_SIZE = 5000;
+var COPY_ON_WRITE_UNSUPPORTED_CODES = new Set(["EINVAL", "ENOSYS", "ENOTSUP", "EOPNOTSUPP"]);
+var collectSnapshotInventory = async (workspace, metrics) => {
   const files = new Map;
+  if (metrics)
+    metrics.inventoryPasses += 1;
   let cursor;
   do {
-    const page = await workspace.listFiles(".", { limit: 500, ...cursor ? { cursor } : {} });
+    const page = await workspace.listFiles(".", {
+      limit: SNAPSHOT_INVENTORY_PAGE_SIZE,
+      ...cursor ? { cursor } : {}
+    });
+    if (metrics)
+      metrics.inventoryPages += 1;
     for (const file of page.files) {
       const absolute = path7.join(workspace.root, ...file.path.split("/"));
       if (!isInside3(workspace.root, absolute))
         throw new Error(`Snapshot file escaped its workspace: ${file.path}.`);
-      const before = await lstat5(absolute);
-      if (before.isSymbolicLink() || !before.isFile())
+      const entry = await lstat5(absolute);
+      if (entry.isSymbolicLink() || !entry.isFile()) {
         throw new Error(`Snapshot source is not a regular file: ${file.path}.`);
-      const contents = await readFile3(absolute);
-      const after = await lstat5(absolute);
-      if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
-        throw new Error(`Snapshot source changed while reading: ${file.path}.`);
       }
-      if (digest2(contents) !== file.digest)
-        throw new Error(`Snapshot digest changed while reading: ${file.path}.`);
-      files.set(file.path, { path: file.path, digest: file.digest, contents, mode: before.mode & 511 });
+      if (entry.size !== file.size) {
+        throw new Error(`Snapshot source changed while inventorying: ${file.path}.`);
+      }
+      files.set(file.path, {
+        path: file.path,
+        digest: file.digest,
+        mode: entry.mode & 511,
+        bytes: file.size
+      });
     }
     cursor = page.nextCursor;
   } while (cursor);
   return files;
 };
-var copyWorkspaceSnapshot = async (source, baseRoot, snapshotRoot, maxWorkspaceBytes) => {
-  const files = await collectSnapshotFiles(source);
-  const totalBytes = [...files.values()].reduce((total, file) => total + file.contents.byteLength, 0);
+var readSnapshotFile = async (workspace, expected, metrics) => {
+  const absolute = path7.join(workspace.root, ...expected.path.split("/"));
+  if (!isInside3(workspace.root, absolute)) {
+    throw new Error(`Snapshot file escaped its workspace: ${expected.path}.`);
+  }
+  const before = await lstat5(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 lstat5(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 actualDigest = digest2(contents);
+  if (actualDigest !== expected.digest || contents.byteLength !== expected.bytes || (before.mode & 511) !== expected.mode) {
+    throw new Error(`Snapshot source changed after inventory: ${expected.path}.`);
+  }
+  if (metrics) {
+    metrics.verifiedContentReads += 1;
+    metrics.verifiedContentBytes += contents.byteLength;
+  }
+  return { ...expected, contents };
+};
+var copySnapshotFile = async (source, target, metrics) => {
+  try {
+    await copyFile(source, target, fsConstants.COPYFILE_FICLONE_FORCE);
+  } catch (error) {
+    const code = error.code;
+    if (!code || !COPY_ON_WRITE_UNSUPPORTED_CODES.has(code))
+      throw error;
+    if (metrics)
+      metrics.snapshotCloneFallbacks += 1;
+    await copyFile(source, target);
+  }
+};
+var copyWorkspaceSnapshot = async (source, baseRoot, snapshotRoot, maxWorkspaceBytes, metrics) => {
+  const files = await collectSnapshotInventory(source, metrics);
+  const totalBytes = [...files.values()].reduce((total, file) => total + file.bytes, 0);
   if (totalBytes > maxWorkspaceBytes) {
     throw new Error(`Workspace snapshot exceeds the ${maxWorkspaceBytes}-byte OCI limit.`);
   }
@@ -3104,13 +3682,22 @@ var copyWorkspaceSnapshot = async (source, baseRoot, snapshotRoot, maxWorkspaceB
     await rm(root, { recursive: true, force: true });
     await privateDirectory(root);
   }
-  for (const file of files.values()) {
-    for (const root of [baseRoot, snapshotRoot]) {
-      const target = path7.join(root, ...file.path.split("/"));
-      await mkdir3(path7.dirname(target), { recursive: true, mode: 448 });
-      await writeFile(target, file.contents, { mode: file.mode });
-      await chmod2(target, file.mode);
-    }
+  for (const expected of files.values()) {
+    const file = await readSnapshotFile(source, expected, metrics);
+    const baseTarget = path7.join(baseRoot, ...file.path.split("/"));
+    const snapshotTarget = path7.join(snapshotRoot, ...file.path.split("/"));
+    await Promise.all([
+      mkdir3(path7.dirname(baseTarget), { recursive: true, mode: 448 }),
+      mkdir3(path7.dirname(snapshotTarget), { recursive: true, mode: 448 })
+    ]);
+    await writeFile(baseTarget, file.contents, { mode: file.mode });
+    await chmod2(baseTarget, file.mode);
+    await copySnapshotFile(baseTarget, snapshotTarget, metrics);
+    await chmod2(snapshotTarget, file.mode);
+  }
+  if (metrics) {
+    metrics.snapshotFiles += files.size;
+    metrics.snapshotBytes += totalBytes;
   }
   return { files: files.size, bytes: totalBytes };
 };
@@ -3129,9 +3716,11 @@ var textContent = (file, maxFileWriteBytes) => {
   }
   return file.contents.toString("utf8");
 };
-var createEnvironmentPatch = async (runId, base, current, maxFileWriteBytes) => {
-  const before = await collectSnapshotFiles(base);
-  const after = await collectSnapshotFiles(current);
+var createEnvironmentPatch = async (runId, base, current, maxFileWriteBytes, metrics) => {
+  const [before, after] = await Promise.all([
+    collectSnapshotInventory(base, metrics),
+    collectSnapshotInventory(current, metrics)
+  ]);
   const paths = [...new Set([...before.keys(), ...after.keys()])].sort();
   const entries = [];
   let totalBytes = 0;
@@ -3141,9 +3730,9 @@ var createEnvironmentPatch = async (runId, base, current, maxFileWriteBytes) =>
     if (oldFile?.digest === newFile?.digest && oldFile?.mode === newFile?.mode)
       continue;
     const operation = !oldFile ? "create" : !newFile ? "delete" : "update";
-    const beforeContent = oldFile ? textContent(oldFile, maxFileWriteBytes) : undefined;
-    const afterContent = newFile ? textContent(newFile, maxFileWriteBytes) : undefined;
-    const bytes = newFile?.contents.byteLength ?? 0;
+    const beforeContent = oldFile ? textContent(await readSnapshotFile(base, oldFile, metrics), maxFileWriteBytes) : undefined;
+    const afterContent = newFile ? textContent(await readSnapshotFile(current, newFile, metrics), maxFileWriteBytes) : undefined;
+    const bytes = newFile?.bytes ?? 0;
     totalBytes += bytes;
     entries.push({
       path: filePath,
@@ -3183,8 +3772,8 @@ var inspectHostPrecondition = async (workspace, filePath, expectedDigest, expect
     throw error;
   }
 };
-var importPatch = async (runId, expectedPatchId, host, base, current, maxFileWriteBytes) => {
-  const patch = await createEnvironmentPatch(runId, base, current, maxFileWriteBytes);
+var importPatch = async (runId, expectedPatchId, host, base, current, maxFileWriteBytes, metrics) => {
+  const patch = await createEnvironmentPatch(runId, base, current, maxFileWriteBytes, metrics);
   if (patch.patchId !== expectedPatchId) {
     throw new Error("Environment patch changed after review; inspect it again before import.");
   }
@@ -3278,7 +3867,7 @@ var createHarnessOciExecutionEnvironment = async (options) => {
     version: `${HARNESS_EXECUTION_POLICY_VERSION}:${image.imageDigest}`,
     backend: "container",
     assurance: "enforced",
-    isolation: "per-tool-call",
+    isolation: "per-run",
     workspace: {
       id: workspaceIdentity,
       root: "/workspace",
@@ -3315,6 +3904,8 @@ var createHarnessOciExecutionEnvironment = async (options) => {
       maxPids: options.config.maxPids,
       maxCpus: options.config.maxCpus,
       tmpfsMb: options.config.tmpfsMb,
+      containerLifecycle: "warm-per-acquired-run",
+      failedCommandRecovery: "discard-and-reseed",
       patchImportApproval: true,
       hostMutationMode: "reviewed-environment-patch"
     }
@@ -3326,6 +3917,19 @@ var createHarnessOciExecutionEnvironment = async (options) => {
     image,
     runtime,
     async acquire(request) {
+      const ioMetrics = {
+        inventoryPasses: 0,
+        inventoryPages: 0,
+        verifiedContentReads: 0,
+        verifiedContentBytes: 0,
+        snapshotFiles: 0,
+        snapshotBytes: 0,
+        snapshotCloneFallbacks: 0,
+        containerStarts: 0,
+        containerReuses: 0,
+        workspacePublishes: 0,
+        workspaceExports: 0
+      };
       await privateDirectory(environmentRoot);
       const directory = path7.join(environmentRoot, runHash(request.runId));
       await privateDirectory(directory);
@@ -3344,7 +3948,7 @@ var createHarnessOciExecutionEnvironment = async (options) => {
       } catch (error) {
         if (error.code !== "ENOENT")
           throw error;
-        const snapshot = await copyWorkspaceSnapshot(options.workspace, baseRoot, snapshotRoot, options.config.maxWorkspaceBytes);
+        const snapshot = await copyWorkspaceSnapshot(options.workspace, baseRoot, snapshotRoot, options.config.maxWorkspaceBytes, ioMetrics);
         const now = new Date().toISOString();
         metadata = {
           schemaVersion: HARNESS_EXECUTION_ARTIFACT_SCHEMA_VERSION,
@@ -3401,6 +4005,14 @@ var createHarnessOciExecutionEnvironment = async (options) => {
           },
           ...context?.abortSignal ?? request.abortSignal ? { abortSignal: context?.abortSignal ?? request.abortSignal } : {}
         });
+        if (result.sessionReused === false)
+          ioMetrics.containerStarts += 1;
+        if (result.sessionReused === true)
+          ioMetrics.containerReuses += 1;
+        if (result.workspacePublished === true)
+          ioMetrics.workspacePublishes += 1;
+        if (result.workspaceExported === true)
+          ioMetrics.workspaceExports += 1;
         const forcedExitCode = result.cancelled ? 130 : result.timedOut ? 124 : result.outputLimitExceeded ? 125 : result.exitCode;
         return {
           command: result.command,
@@ -3447,7 +4059,7 @@ var createHarnessOciExecutionEnvironment = async (options) => {
           return await operation();
         },
         async status() {
-          const patch = await createEnvironmentPatch(request.runId, base, workspace, options.config.maxFileWriteBytes);
+          const patch = await createEnvironmentPatch(request.runId, base, workspace, options.config.maxFileWriteBytes, ioMetrics);
           return {
             schemaVersion: HARNESS_EXECUTION_ARTIFACT_SCHEMA_VERSION,
             kind: "environment-status",
@@ -3461,7 +4073,8 @@ var createHarnessOciExecutionEnvironment = async (options) => {
             rootFilesystem: "read-only",
             workspace: "ephemeral-snapshot",
             patchId: patch.patchId,
-            changedFiles: patch.entries.length
+            changedFiles: patch.entries.length,
+            io: { ...ioMetrics }
           };
         },
         runCommand,
@@ -3486,7 +4099,7 @@ var createHarnessOciExecutionEnvironment = async (options) => {
           return runCommand("bun", ["--no-env-file", "run", check], context);
         },
         async inspectPatch() {
-          const patch = await createEnvironmentPatch(request.runId, base, workspace, options.config.maxFileWriteBytes);
+          const patch = await createEnvironmentPatch(request.runId, base, workspace, options.config.maxFileWriteBytes, ioMetrics);
           const payload = patchPayload(request.runId, patch.entries);
           return {
             ...payload,
@@ -3495,7 +4108,7 @@ var createHarnessOciExecutionEnvironment = async (options) => {
           };
         },
         importPatch(host, patchId) {
-          return importPatch(request.runId, patchId, host, base, workspace, options.config.maxFileWriteBytes);
+          return importPatch(request.runId, patchId, host, base, workspace, options.config.maxFileWriteBytes, ioMetrics);
         },
         async release(result) {
           await runtime.removeRunContainers(request.runId);
@@ -3559,7 +4172,7 @@ var describeOciCommand = (command, args) => commandDisplay([command, ...args]);
 
 // src/harness.ts
 var APPROVAL_VERSION = "2026-08-17-v5";
-var TOOL_CONTRACT_VERSION = "enforced-execution-v1";
+var TOOL_CONTRACT_VERSION = "workspace-batch-v2";
 var createHarnessBinding = (config, mcpConfiguration, model, subagentModels, providerTransportFingerprint, executionEnvironment) => ({
   schemaVersion: 1,
   id: "zhivex-harness",
@@ -3589,7 +4202,7 @@ var HARNESS_INSTRUCTIONS = `You are Zhivex Harness, a provider-portable coding a
 
 Rules:
 - Match the user's language.
-- Inspect the repository before proposing changes. Prefer search_files and read_file over assumptions.
+- Inspect the repository before proposing changes. Prefer search_many and read_files for independent lookups, then use search_files or read_file when pagination or one focused read is clearer.
 - Use only workspace-relative paths. Never request or expose secrets.
 - Make the smallest coherent change that fully addresses the task.
 - For every file edit, first read its digest and call propose_edits. Apply exactly that reviewed proposal with apply_patch.
@@ -3661,6 +4274,23 @@ var createWorkspaceTools = (workspace, allowedChecks) => ({
     metadata: readOnlyMetadata,
     execute: async ({ path: path8, startLine, endLine }, context) => serializeJsonValue2(await (harnessExecutionSession(context)?.workspace ?? workspace).readFile(path8, startLine, endLine))
   }),
+  read_files: tool({
+    name: "read_files",
+    description: "Read up to 20 independent UTF-8 file slices in one bounded call. Duplicate paths are read once and results use deterministic path/range order.",
+    schema: z3.object({
+      files: z3.array(z3.object({
+        path: z3.string().min(1),
+        startLine: z3.number().int().min(1).default(1),
+        endLine: z3.number().int().min(1).optional()
+      })).min(1).max(20)
+    }),
+    metadata: readOnlyMetadata,
+    execute: async ({ files }, context) => serializeJsonValue2(await (harnessExecutionSession(context)?.workspace ?? workspace).readFiles(files.map(({ path: path8, startLine, endLine }) => ({
+      path: path8,
+      startLine,
+      ...endLine !== undefined ? { endLine } : {}
+    }))))
+  }),
   search_files: tool({
     name: "search_files",
     description: "Search for a literal string in text files using a stable cursor.",
@@ -3678,6 +4308,28 @@ var createWorkspaceTools = (workspace, allowedChecks) => ({
       ...cursor ? { cursor } : {}
     }))
   }),
+  search_many: tool({
+    name: "search_many",
+    description: "Search up to 10 independent literal queries in one workspace pass, with at most 500 aggregate matches.",
+    schema: z3.object({
+      queries: z3.array(z3.object({
+        query: z3.string().min(1).max(200),
+        caseSensitive: z3.boolean().default(false)
+      })).min(1).max(10),
+      path: z3.string().min(1).default("."),
+      limitPerQuery: z3.number().int().min(1).max(500).default(50)
+    }).superRefine((input, context) => {
+      if (input.queries.length * input.limitPerQuery > 500) {
+        context.addIssue({
+          code: "custom",
+          path: ["limitPerQuery"],
+          message: "search_many allows at most 500 aggregate matches."
+        });
+      }
+    }),
+    metadata: readOnlyMetadata,
+    execute: async ({ queries, path: path8, limitPerQuery }, context) => serializeJsonValue2(await (harnessExecutionSession(context)?.workspace ?? workspace).searchMany(queries, path8, { limitPerQuery }))
+  }),
   propose_edits: tool({
     name: "propose_edits",
     description: "Validate a bounded multi-file edit against current SHA-256 digests and return a deterministic proposalId for operator review. This tool does not write files.",
@@ -4901,6 +5553,512 @@ var openCliSessionStore = async (options) => {
 };
 var openSessionStore = openCliSessionStore;
 
+// src/change-envelope.ts
+import { createHash as createHash9 } from "crypto";
+import { z as z4 } from "zod";
+var CHANGE_ENVELOPE_SCHEMA_VERSION = 1;
+var CHANGE_ENVELOPE_DIGEST_ALGORITHM = "sha256";
+var MAX_CHANGE_ENVELOPE_CHECKS = 100;
+var MAX_CHANGE_ENVELOPE_APPROVALS = 100;
+var MAX_CHANGE_ENVELOPE_APPROVAL_SCOPES = 32;
+var MAX_CHANGE_ENVELOPE_ATTESTATIONS = 32;
+var timestampSchema = z4.iso.datetime({ precision: 3 });
+var boundedIdentifierSchema = z4.string().min(1).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9._:@/-]*$/, "Identifier must contain only bounded non-secret token characters.");
+var approvalScopeSchema = z4.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:/*-]*$/, "Approval scope must contain only bounded token characters.");
+var attestationFormatSchema = z4.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9.+_-]*$/);
+var mediaTypeSchema = z4.string().min(3).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$/);
+var addDuplicateIssues = (values, key, context, path9) => {
+  const seen = new Set;
+  for (let index = 0;index < values.length; index += 1) {
+    const value = values[index];
+    if (value === undefined)
+      continue;
+    const identifier2 = key(value);
+    if (seen.has(identifier2)) {
+      context.addIssue({
+        code: "custom",
+        path: [index, path9],
+        message: `Duplicate ${path9}: ${identifier2}.`
+      });
+    }
+    seen.add(identifier2);
+  }
+};
+var addCanonicalOrderIssue = (values, key, context, path9) => {
+  for (let index = 1;index < values.length; index += 1) {
+    const previous = values[index - 1];
+    const current = values[index];
+    if (previous !== undefined && current !== undefined && key(previous) >= key(current)) {
+      context.addIssue({
+        code: "custom",
+        path: [index, path9],
+        message: `${path9} entries must be unique and in canonical ascending order.`
+      });
+    }
+  }
+};
+var approvalScopesInputSchema = z4.array(approvalScopeSchema).min(1).max(MAX_CHANGE_ENVELOPE_APPROVAL_SCOPES).superRefine((scopes, context) => addDuplicateIssues(scopes, (scope) => scope, context, "scope"));
+var canonicalApprovalScopesSchema = z4.array(approvalScopeSchema).min(1).max(MAX_CHANGE_ENVELOPE_APPROVAL_SCOPES).superRefine((scopes, context) => addCanonicalOrderIssue(scopes, (scope) => scope, context, "scope"));
+var changeEnvelopeCheckSchema = z4.strictObject({
+  checkId: boundedIdentifierSchema,
+  status: z4.enum(["passed", "failed", "skipped"]),
+  redacted: z4.literal(true),
+  startedAt: timestampSchema,
+  completedAt: timestampSchema,
+  durationMs: z4.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  exitCode: z4.number().int().min(0).max(255).optional(),
+  redactedOutputDigest: fileDigestSchema.optional(),
+  runnerFingerprint: fileDigestSchema.optional()
+}).superRefine((check, context) => {
+  const startedAt = Date.parse(check.startedAt);
+  const completedAt = Date.parse(check.completedAt);
+  if (completedAt < startedAt) {
+    context.addIssue({
+      code: "custom",
+      path: ["completedAt"],
+      message: "Check completion cannot precede its start."
+    });
+  }
+  if (check.status === "passed" && check.exitCode !== undefined && check.exitCode !== 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["exitCode"],
+      message: "A passed check cannot have a non-zero exit code."
+    });
+  }
+  if (check.status === "failed" && check.exitCode === 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["exitCode"],
+      message: "A failed check cannot have a zero exit code."
+    });
+  }
+  if (check.status === "skipped" && check.exitCode !== undefined) {
+    context.addIssue({
+      code: "custom",
+      path: ["exitCode"],
+      message: "A skipped check cannot have an exit code."
+    });
+  }
+});
+var checkInputListSchema = z4.array(changeEnvelopeCheckSchema).min(1).max(MAX_CHANGE_ENVELOPE_CHECKS).superRefine((checks, context) => addDuplicateIssues(checks, (check) => check.checkId, context, "checkId"));
+var canonicalCheckListSchema = z4.array(changeEnvelopeCheckSchema).min(1).max(MAX_CHANGE_ENVELOPE_CHECKS).superRefine((checks, context) => addCanonicalOrderIssue(checks, (check) => check.checkId, context, "checkId"));
+var changeEnvelopeApprovalSchema = z4.strictObject({
+  kind: z4.literal("approval-reference"),
+  approvalId: boundedIdentifierSchema,
+  approvalDigest: fileDigestSchema,
+  approverDigest: fileDigestSchema,
+  scopes: canonicalApprovalScopesSchema,
+  approvedAt: timestampSchema,
+  expiresAt: timestampSchema.optional()
+}).superRefine((approval, context) => {
+  if (approval.expiresAt && Date.parse(approval.expiresAt) <= Date.parse(approval.approvedAt)) {
+    context.addIssue({
+      code: "custom",
+      path: ["expiresAt"],
+      message: "Approval expiry must be later than approval time."
+    });
+  }
+});
+var changeEnvelopeApprovalInputSchema = z4.strictObject({
+  kind: z4.literal("approval-reference"),
+  approvalId: boundedIdentifierSchema,
+  approvalDigest: fileDigestSchema,
+  approverDigest: fileDigestSchema,
+  scopes: approvalScopesInputSchema,
+  approvedAt: timestampSchema,
+  expiresAt: timestampSchema.optional()
+}).superRefine((approval, context) => {
+  if (approval.expiresAt && Date.parse(approval.expiresAt) <= Date.parse(approval.approvedAt)) {
+    context.addIssue({
+      code: "custom",
+      path: ["expiresAt"],
+      message: "Approval expiry must be later than approval time."
+    });
+  }
+});
+var approvalInputListSchema = z4.array(changeEnvelopeApprovalInputSchema).min(1).max(MAX_CHANGE_ENVELOPE_APPROVALS).superRefine((approvals, context) => addDuplicateIssues(approvals, (approval) => approval.approvalId, context, "approvalId"));
+var canonicalApprovalListSchema = z4.array(changeEnvelopeApprovalSchema).min(1).max(MAX_CHANGE_ENVELOPE_APPROVALS).superRefine((approvals, context) => addCanonicalOrderIssue(approvals, (approval) => approval.approvalId, context, "approvalId"));
+var externalAttestationReferenceSchema = z4.strictObject({
+  kind: z4.literal("external-attestation-reference"),
+  attestationId: boundedIdentifierSchema,
+  format: attestationFormatSchema,
+  mediaType: mediaTypeSchema,
+  bundleDigest: fileDigestSchema
+});
+var externalAttestationInputListSchema = z4.array(externalAttestationReferenceSchema).min(1).max(MAX_CHANGE_ENVELOPE_ATTESTATIONS).superRefine((attestations, context) => addDuplicateIssues(attestations, (attestation) => attestation.attestationId, context, "attestationId"));
+var canonicalExternalAttestationListSchema = z4.array(externalAttestationReferenceSchema).min(1).max(MAX_CHANGE_ENVELOPE_ATTESTATIONS).superRefine((attestations, context) => addCanonicalOrderIssue(attestations, (attestation) => attestation.attestationId, context, "attestationId"));
+var changeEnvelopeBaseSchema = z4.strictObject({
+  workspaceDigest: fileDigestSchema,
+  treeDigest: fileDigestSchema
+});
+var changeEnvelopePatchSchema = z4.strictObject({
+  patchId: boundedIdentifierSchema,
+  patchDigest: fileDigestSchema
+});
+var changeEnvelopeFingerprintsSchema = z4.strictObject({
+  harness: fileDigestSchema,
+  policy: fileDigestSchema,
+  environment: fileDigestSchema
+});
+var changeEnvelopeEvidenceSchema = z4.strictObject({
+  schemaVersion: z4.literal(CHANGE_ENVELOPE_SCHEMA_VERSION),
+  kind: z4.literal("check-evidence-summary"),
+  digestAlgorithm: z4.literal(CHANGE_ENVELOPE_DIGEST_ALGORITHM),
+  evidenceDigest: fileDigestSchema,
+  checks: canonicalCheckListSchema
+});
+var changeEnvelopeInputSchema = z4.strictObject({
+  createdAt: timestampSchema,
+  expiresAt: timestampSchema.optional(),
+  base: changeEnvelopeBaseSchema,
+  patch: changeEnvelopePatchSchema,
+  fingerprints: changeEnvelopeFingerprintsSchema,
+  checks: checkInputListSchema,
+  approvals: approvalInputListSchema.optional(),
+  externalAttestations: externalAttestationInputListSchema.optional()
+});
+var changeEnvelopeSchema = z4.strictObject({
+  schemaVersion: z4.literal(CHANGE_ENVELOPE_SCHEMA_VERSION),
+  kind: z4.literal("change-envelope"),
+  digestAlgorithm: z4.literal(CHANGE_ENVELOPE_DIGEST_ALGORITHM),
+  envelopeId: fileDigestSchema,
+  createdAt: timestampSchema,
+  expiresAt: timestampSchema.optional(),
+  base: changeEnvelopeBaseSchema,
+  patch: changeEnvelopePatchSchema,
+  fingerprints: changeEnvelopeFingerprintsSchema,
+  evidence: changeEnvelopeEvidenceSchema,
+  approvals: canonicalApprovalListSchema.optional(),
+  externalAttestations: canonicalExternalAttestationListSchema.optional()
+}).superRefine((envelope, context) => {
+  if (envelope.expiresAt && Date.parse(envelope.expiresAt) <= Date.parse(envelope.createdAt)) {
+    context.addIssue({
+      code: "custom",
+      path: ["expiresAt"],
+      message: "Envelope expiry must be later than creation time."
+    });
+  }
+  for (let index = 0;index < envelope.evidence.checks.length; index += 1) {
+    const check = envelope.evidence.checks[index];
+    if (check && Date.parse(check.completedAt) > Date.parse(envelope.createdAt)) {
+      context.addIssue({
+        code: "custom",
+        path: ["evidence", "checks", index, "completedAt"],
+        message: "Check completion cannot be later than envelope creation time."
+      });
+    }
+  }
+  for (let index = 0;index < (envelope.approvals?.length ?? 0); index += 1) {
+    const approval = envelope.approvals?.[index];
+    if (approval && Date.parse(approval.approvedAt) > Date.parse(envelope.createdAt)) {
+      context.addIssue({
+        code: "custom",
+        path: ["approvals", index, "approvedAt"],
+        message: "Approval time cannot be later than envelope creation time."
+      });
+    }
+  }
+});
+var canonicalJson = (value) => {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new TypeError("Canonical JSON cannot encode a non-finite number.");
+    return JSON.stringify(Object.is(value, -0) ? 0 : value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+  }
+  throw new TypeError(`Canonical JSON cannot encode ${typeof value}.`);
+};
+var digestCanonical = (value) => `sha256:${createHash9("sha256").update(canonicalJson(value)).digest("hex")}`;
+var digestChangeEnvelopeArtifact = (value) => `sha256:${createHash9("sha256").update(value).digest("hex")}`;
+var evidencePayload = (checks) => ({
+  schemaVersion: CHANGE_ENVELOPE_SCHEMA_VERSION,
+  kind: "check-evidence-summary",
+  digestAlgorithm: CHANGE_ENVELOPE_DIGEST_ALGORITHM,
+  checks: [...checks]
+});
+var envelopePayload = (envelope) => {
+  const { envelopeId: _envelopeId, ...payload } = envelope;
+  return payload;
+};
+var sortBy = (values, key) => [...values].sort((left, right) => {
+  const leftKey = key(left);
+  const rightKey = key(right);
+  return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+});
+var createChangeEnvelope = (input) => {
+  const parsed = changeEnvelopeInputSchema.parse(input);
+  const checks = sortBy(parsed.checks, (check) => check.checkId);
+  const evidenceWithoutDigest = evidencePayload(checks);
+  const evidence = {
+    ...evidenceWithoutDigest,
+    evidenceDigest: digestCanonical(evidenceWithoutDigest)
+  };
+  const approvals = parsed.approvals ? sortBy(parsed.approvals, (approval) => approval.approvalId).map((approval) => ({
+    ...approval,
+    scopes: [...approval.scopes].sort()
+  })) : undefined;
+  const externalAttestations = parsed.externalAttestations ? sortBy(parsed.externalAttestations, (attestation) => attestation.attestationId) : undefined;
+  const payload = {
+    schemaVersion: CHANGE_ENVELOPE_SCHEMA_VERSION,
+    kind: "change-envelope",
+    digestAlgorithm: CHANGE_ENVELOPE_DIGEST_ALGORITHM,
+    createdAt: parsed.createdAt,
+    ...parsed.expiresAt ? { expiresAt: parsed.expiresAt } : {},
+    base: parsed.base,
+    patch: parsed.patch,
+    fingerprints: parsed.fingerprints,
+    evidence,
+    ...approvals ? { approvals } : {},
+    ...externalAttestations ? { externalAttestations } : {}
+  };
+  return changeEnvelopeSchema.parse({
+    ...payload,
+    envelopeId: digestCanonical(payload)
+  });
+};
+var canonicalizeChangeEnvelope = (input) => canonicalJson(changeEnvelopeSchema.parse(input));
+var computeChangeEnvelopeDigest = (input) => {
+  const parsed = changeEnvelopeSchema.parse(input);
+  return digestCanonical(envelopePayload(parsed));
+};
+var computeChangeEnvelopeEvidenceDigest = (input) => {
+  const parsed = changeEnvelopeEvidenceSchema.parse(input);
+  return digestCanonical(evidencePayload(parsed.checks));
+};
+var changeEnvelopePreconditionsSchema = z4.strictObject({
+  envelopeId: fileDigestSchema.optional(),
+  baseWorkspaceDigest: fileDigestSchema.optional(),
+  baseTreeDigest: fileDigestSchema.optional(),
+  patchId: boundedIdentifierSchema.optional(),
+  patchDigest: fileDigestSchema.optional(),
+  harnessFingerprint: fileDigestSchema.optional(),
+  policyFingerprint: fileDigestSchema.optional(),
+  environmentFingerprint: fileDigestSchema.optional(),
+  evidenceDigest: fileDigestSchema.optional(),
+  requiredPassedChecks: z4.array(boundedIdentifierSchema).max(MAX_CHANGE_ENVELOPE_CHECKS).optional(),
+  requiredApprovalDigests: z4.array(fileDigestSchema).max(MAX_CHANGE_ENVELOPE_APPROVALS).optional(),
+  requiredApprovalScopes: z4.array(approvalScopeSchema).max(MAX_CHANGE_ENVELOPE_APPROVAL_SCOPES).optional(),
+  requiredAttestationDigests: z4.array(fileDigestSchema).max(MAX_CHANGE_ENVELOPE_ATTESTATIONS).optional()
+}).superRefine((preconditions, context) => {
+  if (preconditions.requiredPassedChecks) {
+    addDuplicateIssues(preconditions.requiredPassedChecks, (checkId) => checkId, context, "requiredPassedCheck");
+  }
+  if (preconditions.requiredApprovalDigests) {
+    addDuplicateIssues(preconditions.requiredApprovalDigests, (digest3) => digest3, context, "requiredApprovalDigest");
+  }
+  if (preconditions.requiredApprovalScopes) {
+    addDuplicateIssues(preconditions.requiredApprovalScopes, (scope) => scope, context, "requiredApprovalScope");
+  }
+  if (preconditions.requiredAttestationDigests) {
+    addDuplicateIssues(preconditions.requiredAttestationDigests, (digest3) => digest3, context, "requiredAttestationDigest");
+  }
+});
+var verificationOptionsSchema = z4.strictObject({
+  now: z4.union([z4.date(), z4.number().int(), timestampSchema]).optional(),
+  preconditions: changeEnvelopePreconditionsSchema.optional()
+});
+var verificationTime = (value) => {
+  const date = value === undefined ? new Date : value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(date.getTime()))
+    throw new TypeError("Verification time must be a valid date.");
+  return date;
+};
+var verifyChangeEnvelope = (input, options = {}) => {
+  const parsedOptions = verificationOptionsSchema.parse(options);
+  const now = verificationTime(parsedOptions.now);
+  const checkedAt = now.toISOString();
+  const parsedEnvelope = changeEnvelopeSchema.safeParse(input);
+  if (!parsedEnvelope.success) {
+    return {
+      valid: false,
+      verificationScope: "integrity-expiration-and-preconditions-only",
+      issues: parsedEnvelope.error.issues.map((issue) => ({
+        code: "invalid-schema",
+        path: issue.path.map((segment) => typeof segment === "symbol" ? segment.description ?? "symbol" : segment),
+        message: issue.message
+      })),
+      integrity: { envelopeDigestValid: false, evidenceDigestValid: false },
+      expiration: { checkedAt, envelopeNotYetValid: false, envelopeExpired: false, expiredApprovalIds: [] },
+      checks: {
+        recorded: 0,
+        passed: [],
+        failed: [],
+        skipped: [],
+        requiredPassed: [...parsedOptions.preconditions?.requiredPassedChecks ?? []].sort(),
+        missingPassed: [...parsedOptions.preconditions?.requiredPassedChecks ?? []].sort()
+      },
+      approvals: {
+        recorded: 0,
+        requiredScopes: [...parsedOptions.preconditions?.requiredApprovalScopes ?? []].sort(),
+        missingScopes: [...parsedOptions.preconditions?.requiredApprovalScopes ?? []].sort(),
+        authenticity: "not-verified"
+      },
+      externalAttestations: {
+        referenced: 0,
+        requiredDigests: [...parsedOptions.preconditions?.requiredAttestationDigests ?? []].sort(),
+        missingDigests: [...parsedOptions.preconditions?.requiredAttestationDigests ?? []].sort(),
+        authenticity: "not-verified"
+      }
+    };
+  }
+  const envelope = parsedEnvelope.data;
+  const issues = [];
+  const computedEvidenceDigest = digestCanonical(evidencePayload(envelope.evidence.checks));
+  const evidenceDigestValid = computedEvidenceDigest === envelope.evidence.evidenceDigest;
+  if (!evidenceDigestValid) {
+    issues.push({
+      code: "evidence-digest-mismatch",
+      path: ["evidence", "evidenceDigest"],
+      message: "Evidence digest does not match the canonical redacted check summary.",
+      expected: computedEvidenceDigest,
+      actual: envelope.evidence.evidenceDigest
+    });
+  }
+  const computedEnvelopeDigest = digestCanonical(envelopePayload(envelope));
+  const envelopeDigestValid = computedEnvelopeDigest === envelope.envelopeId;
+  if (!envelopeDigestValid) {
+    issues.push({
+      code: "envelope-digest-mismatch",
+      path: ["envelopeId"],
+      message: "Envelope digest does not match its canonical payload.",
+      expected: computedEnvelopeDigest,
+      actual: envelope.envelopeId
+    });
+  }
+  const envelopeNotYetValid = now.getTime() < Date.parse(envelope.createdAt);
+  if (envelopeNotYetValid) {
+    issues.push({
+      code: "envelope-not-yet-valid",
+      path: ["createdAt"],
+      message: "Change envelope creation time is in the future."
+    });
+  }
+  const envelopeExpired = envelope.expiresAt !== undefined && now.getTime() >= Date.parse(envelope.expiresAt);
+  if (envelopeExpired) {
+    issues.push({
+      code: "envelope-expired",
+      path: ["expiresAt"],
+      message: "Change envelope has expired."
+    });
+  }
+  const expiredApprovalIds = (envelope.approvals ?? []).filter((approval) => approval.expiresAt !== undefined && now.getTime() >= Date.parse(approval.expiresAt)).map((approval) => approval.approvalId);
+  for (const approvalId of expiredApprovalIds) {
+    issues.push({
+      code: "approval-expired",
+      path: ["approvals", envelope.approvals?.findIndex((approval) => approval.approvalId === approvalId) ?? 0, "expiresAt"],
+      message: `Recorded approval has expired: ${approvalId}.`
+    });
+  }
+  const preconditions = parsedOptions.preconditions;
+  const comparePrecondition = (field, expected, actual, path9) => {
+    if (expected !== undefined && expected !== actual) {
+      issues.push({
+        code: "precondition-mismatch",
+        path: path9,
+        message: `Change envelope precondition does not match: ${field}.`,
+        expected,
+        actual
+      });
+    }
+  };
+  comparePrecondition("envelopeId", preconditions?.envelopeId, envelope.envelopeId, ["envelopeId"]);
+  comparePrecondition("baseWorkspaceDigest", preconditions?.baseWorkspaceDigest, envelope.base.workspaceDigest, ["base", "workspaceDigest"]);
+  comparePrecondition("baseTreeDigest", preconditions?.baseTreeDigest, envelope.base.treeDigest, ["base", "treeDigest"]);
+  comparePrecondition("patchId", preconditions?.patchId, envelope.patch.patchId, ["patch", "patchId"]);
+  comparePrecondition("patchDigest", preconditions?.patchDigest, envelope.patch.patchDigest, ["patch", "patchDigest"]);
+  comparePrecondition("harnessFingerprint", preconditions?.harnessFingerprint, envelope.fingerprints.harness, ["fingerprints", "harness"]);
+  comparePrecondition("policyFingerprint", preconditions?.policyFingerprint, envelope.fingerprints.policy, ["fingerprints", "policy"]);
+  comparePrecondition("environmentFingerprint", preconditions?.environmentFingerprint, envelope.fingerprints.environment, ["fingerprints", "environment"]);
+  comparePrecondition("evidenceDigest", preconditions?.evidenceDigest, envelope.evidence.evidenceDigest, ["evidence", "evidenceDigest"]);
+  const passedChecks = envelope.evidence.checks.filter((check) => check.status === "passed").map((check) => check.checkId);
+  const failedChecks = envelope.evidence.checks.filter((check) => check.status === "failed").map((check) => check.checkId);
+  const skippedChecks = envelope.evidence.checks.filter((check) => check.status === "skipped").map((check) => check.checkId);
+  const passedCheckSet = new Set(passedChecks);
+  const requiredPassed = [...preconditions?.requiredPassedChecks ?? []].sort();
+  const missingPassed = requiredPassed.filter((checkId) => !passedCheckSet.has(checkId));
+  for (const checkId of missingPassed) {
+    issues.push({
+      code: "missing-passed-check",
+      path: ["evidence", "checks"],
+      message: `Required passed check is not recorded: ${checkId}.`,
+      expected: checkId
+    });
+  }
+  const expiredApprovals = new Set(expiredApprovalIds);
+  const activeApprovals = (envelope.approvals ?? []).filter((approval) => !expiredApprovals.has(approval.approvalId));
+  const approvalDigests = new Set(activeApprovals.map((approval) => approval.approvalDigest));
+  for (const requiredDigest of preconditions?.requiredApprovalDigests ?? []) {
+    if (!approvalDigests.has(requiredDigest)) {
+      issues.push({
+        code: "missing-approval-digest",
+        path: ["approvals"],
+        message: `Required active approval digest is not recorded: ${requiredDigest}.`,
+        expected: requiredDigest
+      });
+    }
+  }
+  const approvedScopes = new Set(activeApprovals.flatMap((approval) => approval.scopes));
+  const requiredScopes = [...preconditions?.requiredApprovalScopes ?? []].sort();
+  const missingScopes = requiredScopes.filter((scope) => !approvedScopes.has(scope));
+  for (const scope of missingScopes) {
+    issues.push({
+      code: "missing-approval-scope",
+      path: ["approvals"],
+      message: `Required active approval scope is not recorded: ${scope}.`,
+      expected: scope
+    });
+  }
+  const attestationDigests = new Set((envelope.externalAttestations ?? []).map((attestation) => attestation.bundleDigest));
+  const requiredAttestationDigests = [...preconditions?.requiredAttestationDigests ?? []].sort();
+  const missingAttestationDigests = requiredAttestationDigests.filter((digest3) => !attestationDigests.has(digest3));
+  for (const requiredDigest of missingAttestationDigests) {
+    issues.push({
+      code: "missing-attestation-digest",
+      path: ["externalAttestations"],
+      message: `Required external attestation digest is not referenced: ${requiredDigest}.`,
+      expected: requiredDigest
+    });
+  }
+  return {
+    valid: issues.length === 0,
+    verificationScope: "integrity-expiration-and-preconditions-only",
+    envelope,
+    issues,
+    integrity: { envelopeDigestValid, evidenceDigestValid },
+    expiration: { checkedAt, envelopeNotYetValid, envelopeExpired, expiredApprovalIds },
+    checks: {
+      recorded: envelope.evidence.checks.length,
+      passed: passedChecks,
+      failed: failedChecks,
+      skipped: skippedChecks,
+      requiredPassed,
+      missingPassed
+    },
+    approvals: {
+      recorded: envelope.approvals?.length ?? 0,
+      requiredScopes,
+      missingScopes,
+      authenticity: "not-verified"
+    },
+    externalAttestations: {
+      referenced: envelope.externalAttestations?.length ?? 0,
+      requiredDigests: requiredAttestationDigests,
+      missingDigests: missingAttestationDigests,
+      authenticity: "not-verified"
+    }
+  };
+};
+
 // src/cli.ts
 var HARNESS_RESUME_METADATA_KEY = "zhivexHarnessResume";
 var HARNESS_RESUME_METADATA_SCHEMA_VERSION = 1;
@@ -4910,9 +6068,11 @@ var CLI_EXIT_CODES = {
   usageError: 2,
   doctorFailed: 3
 };
-var COMMANDS = new Set(["run", "review", "chat", "providers", "doctor", "resume", "runs", "sessions", "help", "version"]);
+var COMMANDS = new Set(["run", "review", "chat", "providers", "doctor", "resume", "runs", "sessions", "changes", "help", "version"]);
 var RUNS_COMMANDS = new Set(["list", "inspect", "cancel", "cleanup", "export"]);
 var SESSIONS_COMMANDS = new Set(["list", "inspect", "rename", "fork", "archive"]);
+var CHANGES_COMMANDS = new Set(["create", "verify"]);
+var CLI_TIMESTAMP_SCHEMA = z5.iso.datetime({ precision: 3 });
 var RUN_STATUSES = new Set([
   "queued",
   "running",
@@ -5132,6 +6292,23 @@ var parseCliArgs = (argv) => {
         options.mcpConfigPath = optionValue(argv, index, argument);
         index += 1;
         break;
+      case "--patch":
+        options.patchPath = optionValue(argv, index, argument);
+        index += 1;
+        break;
+      case "--preconditions":
+        options.preconditionsPath = optionValue(argv, index, argument);
+        index += 1;
+        break;
+      case "--now": {
+        const value = optionValue(argv, index, argument);
+        if (!CLI_TIMESTAMP_SCHEMA.safeParse(value).success) {
+          throw new CliUsageError("--now must be a millisecond-precision ISO-8601 UTC timestamp.");
+        }
+        options.verificationTime = value;
+        index += 1;
+        break;
+      }
       case "--execution":
         options.executionBackend = optionValue(argv, index, argument);
         index += 1;
@@ -5424,6 +6601,9 @@ var parseCliArgs = (argv) => {
   if (options.jsonl && options.command !== "run" && options.command !== "resume") {
     throw new CliUsageError("--jsonl is supported by run and resume.");
   }
+  if (options.command !== "changes" && (options.patchPath || options.preconditionsPath || options.verificationTime)) {
+    throw new CliUsageError("--patch, --preconditions, and --now are supported only by changes.");
+  }
   if (options.command === "resume") {
     const runId = positional.shift();
     if (runId) {
@@ -5473,6 +6653,26 @@ var parseCliArgs = (argv) => {
     if (positional.length > 0) {
       throw new CliUsageError(`sessions ${sessionsCommand} received unexpected positional arguments.`);
     }
+  } else if (options.command === "changes") {
+    const changesCommand = positional.shift();
+    if (!changesCommand || !CHANGES_COMMANDS.has(changesCommand)) {
+      throw new CliUsageError("changes requires one of: create, verify.");
+    }
+    options.changesCommand = changesCommand;
+    const artifactPath = positional.shift();
+    if (!artifactPath) {
+      throw new CliUsageError(`changes ${changesCommand} requires an input JSON file.`);
+    }
+    options.artifactPath = artifactPath;
+    if (!options.patchPath) {
+      throw new CliUsageError(`changes ${changesCommand} requires --patch <file>.`);
+    }
+    if (changesCommand === "create" && (options.preconditionsPath || options.verificationTime)) {
+      throw new CliUsageError("--preconditions and --now are only supported by changes verify.");
+    }
+    if (positional.length > 0) {
+      throw new CliUsageError(`changes ${changesCommand} received unexpected positional arguments.`);
+    }
   } else if (options.command === "run" || options.command === "review") {
     const prompt = positional.join(" ").trim();
     if (prompt) {
@@ -5495,6 +6695,8 @@ Usage:
   zhx resume [options] <runId> --approve|--deny
   zhx runs list [--status <status>] [--limit <n>] [--json]
   zhx sessions list|inspect|rename|fork|archive
+  zhx changes create <input.json> --patch <artifact>
+  zhx changes verify <envelope.json> --patch <artifact> [--preconditions <file>]
 
 The long command zhivex-harness remains supported for compatibility.
 
@@ -5507,6 +6709,9 @@ Options:
   --workspace <path>             Target workspace (default: cwd)
   --state-dir <path>             Durable run-state directory
   --mcp-config <path>            Declarative governed MCP JSON configuration
+  --patch <path>                 Exact patch/artifact bytes bound to a change envelope
+  --preconditions <path>         Verification preconditions JSON for changes verify
+  --now <ISO-8601 UTC>           Explicit millisecond verification time (default: current time)
   --execution <none|oci>         Enforced execution backend (default: none)
   --oci-runtime <docker|podman>  Local OCI runtime (default: docker)
   --oci-image <reference>        Preloaded immutable-capable OCI image
@@ -6305,7 +7510,7 @@ var inspectWorkspace = async (workspace) => {
     if (!workspaceStat.isDirectory()) {
       return diagnostic("workspace", "fail", "Workspace is not a directory.", { path: workspace });
     }
-    await access(workspace, fsConstants.R_OK);
+    await access(workspace, fsConstants2.R_OK);
     return diagnostic("workspace", "pass", "Workspace exists and is readable.", { path: workspace });
   } catch (error) {
     const code = error.code ?? "UNKNOWN";
@@ -6439,7 +7644,7 @@ var inspectStateDirectory = async (workspace, stateDirectory) => {
         writable: false
       });
     }
-    await access(existing.path, fsConstants.R_OK | fsConstants.W_OK);
+    await access(existing.path, fsConstants2.R_OK | fsConstants2.W_OK);
     return diagnostic("state-directory", "pass", "State directory is safe and writable.", {
       path: stateDirectory,
       exists: existing.path === stateDirectory,
@@ -6841,6 +8046,90 @@ var updateIndexedSessionRun = async (config, runId, status) => {
   }
 };
 var cliExitCodeForError = (error) => error instanceof CliUsageError ? CLI_EXIT_CODES.usageError : CLI_EXIT_CODES.runtimeError;
+var MAX_CHANGE_ENVELOPE_JSON_BYTES = 4 * 1024 * 1024;
+var MAX_CHANGE_ARTIFACT_BYTES = 64 * 1024 * 1024;
+var readStableCliArtifact = async (filePath, maxBytes) => {
+  const absolute = path9.resolve(process.cwd(), filePath);
+  try {
+    const before = await lstat7(absolute);
+    if (before.isSymbolicLink() || !before.isFile()) {
+      throw new CliUsageError(`Change artifact must be a regular non-symlink file: ${filePath}`);
+    }
+    if (before.size > maxBytes) {
+      throw new CliUsageError(`Change artifact exceeds the ${maxBytes}-byte limit: ${filePath}`);
+    }
+    const contents = await readFile4(absolute);
+    const after = await lstat7(absolute);
+    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
+      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}`);
+    }
+    throw error;
+  }
+};
+var readCliJsonArtifact = async (filePath) => {
+  const contents = await readStableCliArtifact(filePath, MAX_CHANGE_ENVELOPE_JSON_BYTES);
+  try {
+    return JSON.parse(contents.toString("utf8"));
+  } catch {
+    throw new CliUsageError(`Change artifact is not valid JSON: ${filePath}`);
+  }
+};
+var objectValue = (value, label) => {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new CliUsageError(`${label} must be a JSON object.`);
+  }
+  return value;
+};
+var manageChanges = async (options) => {
+  if (!options.changesCommand || !options.artifactPath || !options.patchPath) {
+    throw new CliUsageError("Incomplete changes command.");
+  }
+  const patchBytes = await readStableCliArtifact(options.patchPath, MAX_CHANGE_ARTIFACT_BYTES);
+  const patchDigest = digestChangeEnvelopeArtifact(patchBytes);
+  if (options.changesCommand === "create") {
+    const input = objectValue(await readCliJsonArtifact(options.artifactPath), "Change envelope input");
+    const patchInput = objectValue(input.patch, "Change envelope patch");
+    if (patchInput.patchDigest !== undefined && patchInput.patchDigest !== patchDigest) {
+      throw new CliUsageError("The declared patch.patchDigest does not match the exact --patch bytes.");
+    }
+    const envelope2 = createChangeEnvelope({
+      ...input,
+      patch: { ...patchInput, patchDigest }
+    });
+    process.stdout.write(`${canonicalizeChangeEnvelope(envelope2)}
+`);
+    return;
+  }
+  const envelope = await readCliJsonArtifact(options.artifactPath);
+  const suppliedPreconditions = options.preconditionsPath ? objectValue(await readCliJsonArtifact(options.preconditionsPath), "Change envelope preconditions") : {};
+  if (suppliedPreconditions.patchDigest !== undefined && suppliedPreconditions.patchDigest !== patchDigest) {
+    throw new CliUsageError("The precondition patchDigest does not match the exact --patch bytes.");
+  }
+  const preconditions = changeEnvelopePreconditionsSchema.parse({
+    ...suppliedPreconditions,
+    patchDigest
+  });
+  const result = verifyChangeEnvelope(envelope, {
+    ...options.verificationTime ? { now: options.verificationTime } : {},
+    preconditions
+  });
+  process.stdout.write(`${JSON.stringify({
+    schemaVersion: 1,
+    kind: "change-envelope-verification",
+    ...result
+  })}
+`);
+  if (!result.valid)
+    process.exitCode = CLI_EXIT_CODES.runtimeError;
+};
 var main = async (argv = process.argv.slice(2)) => {
   const options = parseCliArgs(argv);
   switch (options.command) {
@@ -6870,6 +8159,9 @@ var main = async (argv = process.argv.slice(2)) => {
     case "sessions":
       await manageSessions(options);
       return;
+    case "changes":
+      await manageChanges(options);
+      return;
     case "run":
       if (options.implicitCommand && !options.prompt && process.stdin.isTTY && process.stdout.isTTY) {
         await chat(options);