@odla-ai/harness 0.10.0 → 0.10.2

package/dist/node.cjs

@@ -56,6 +56,7 @@ __export(node_exports, {
   installedDependencies: () => installedDependencies,
   integrateSubGoals: () => integrateSubGoals,
   isCheckpointEffectCompleted: () => isCheckpointEffectCompleted,
+  materializeCodeRuntimeArchive: () => materializeCodeRuntimeArchive,
   materializeCodeRuntimeSource: () => materializeCodeRuntimeSource,
   materializeCommandWorkspace: () => materializeCommandWorkspace,
   materializeGitTree: () => materializeGitTree,
@@ -155,7 +156,7 @@ function parseAgentOutput(line) {
   if (message2.type === "tool.request") {
     const input = record(message2.input);
     const tool = String(message2.tool);
-    if (!input || !["sandbox.read", "sandbox.apply_patch", "sandbox.run_recipe"].includes(tool)) {
+    if (!input || !["sandbox.read", "sandbox.apply_patch", "sandbox.edit", "sandbox.run_recipe"].includes(tool)) {
       throw new HarnessProtocolError("tool.request requires a registered tool and object input");
     }
     return {
@@ -232,7 +233,7 @@ async function selectContainerEngine(requested = "auto", options = {}) {
   throw new TypeError("no supported container engine found");
 }
 function inspectRootlessPodman() {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     (0, import_node_child_process.execFile)(
       "podman",
       ["info", "--format", "{{.Host.Security.Rootless}}"],
@@ -242,7 +243,7 @@ function inspectRootlessPodman() {
           reject(new TypeError("could not verify that the active Podman service is rootless"));
           return;
         }
-        resolve7(stdout.trim() === "true");
+        resolve8(stdout.trim() === "true");
       }
     );
   });
@@ -1140,6 +1141,34 @@ function createCodeRuntimeControlClient(options) {
     }
     return value;
   };
+  const callRaw = async (path, body) => {
+    const timeout = AbortSignal.timeout(modelRequestTimeoutMs);
+    const signals = [options.signal, timeout].filter((item) => Boolean(item));
+    const signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+    let response2;
+    try {
+      response2 = await request(`${endpoint}${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${options.token}`, "content-type": "application/json" },
+        body: JSON.stringify(body),
+        redirect: "error",
+        signal
+      });
+    } catch (cause) {
+      if (options.signal?.aborted) throw cause;
+      throw new CodeRuntimeControlError("Code source archive is unavailable", 503, "transport_unavailable");
+    }
+    if (!response2.ok) {
+      const value = await response2.json().catch(() => null);
+      const problem = record2(record2(value)?.error);
+      throw new CodeRuntimeControlError(
+        typeof problem?.message === "string" ? problem.message : `Code runtime request failed (${response2.status})`,
+        response2.status,
+        typeof problem?.code === "string" ? problem.code : void 0
+      );
+    }
+    return response2;
+  };
   return {
     heartbeat: async (version, capabilities) => {
       validateHeartbeat(version, capabilities);
@@ -1151,6 +1180,14 @@ function createCodeRuntimeControlClient(options) {
     source: async (sessionId) => parseSource(
       await call(`/registry/code/runtime/sessions/${validSessionId(sessionId)}/source`, {})
     ),
+    sourceArchive: async (sessionId, alias) => {
+      if (!/^[a-z][a-z0-9-]{0,39}$/.test(alias)) throw new TypeError("invalid Code source alias");
+      const response2 = await callRaw(
+        `/registry/code/runtime/sessions/${validSessionId(sessionId)}/source/archive`,
+        { alias }
+      );
+      return parseSourceArchiveResponse(response2, alias);
+    },
     infer: async (sessionId, inference) => {
       const value = record2(await call(
         `/registry/code/runtime/sessions/${validSessionId(sessionId)}/inference`,
@@ -1215,9 +1252,70 @@ function createCodeRuntimeControlClient(options) {
     }
   };
 }
+var ARCHIVE_LIMIT_MAXIMA = {
+  maxCompressedBytes: 64 * 1024 * 1024,
+  maxDecompressedBytes: 96 * 1024 * 1024,
+  maxEntries: 2e5,
+  maxFiles: 1e5,
+  maxFileBytes: 16 * 1024 * 1024,
+  maxTotalFileBytes: 80 * 1024 * 1024,
+  maxPathBytes: 4096,
+  maxExtendedHeaderBytes: 32 * 1024
+};
+async function parseSourceArchiveResponse(response2, expectedAlias) {
+  const alias = response2.headers.get("x-odla-source-alias") ?? "";
+  const repository = response2.headers.get("x-odla-source-repository") ?? "";
+  const commitSha = response2.headers.get("x-odla-source-commit") ?? "";
+  if (alias !== expectedAlias || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) || !/^[0-9a-f]{40}$/.test(commitSha)) {
+    await response2.body?.cancel().catch(() => void 0);
+    throw new CodeRuntimeControlError("invalid Code source archive identity", 502, "invalid_response");
+  }
+  const limits = Object.fromEntries(Object.entries(ARCHIVE_LIMIT_MAXIMA).map(([key, maximum]) => {
+    const header = `x-odla-${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+    const value = response2.headers.get(header) ?? "";
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1 || Number(value) > maximum) {
+      throw new CodeRuntimeControlError("invalid Code source archive limits", 502, "invalid_response");
+    }
+    return [key, Number(value)];
+  }));
+  const length = response2.headers.get("content-length");
+  if (length && (!/^\d+$/.test(length) || Number(length) > limits.maxCompressedBytes)) {
+    await response2.body?.cancel().catch(() => void 0);
+    throw new CodeRuntimeControlError("Code source archive exceeds its byte bound", 502, "invalid_response");
+  }
+  const compressed = await readBoundedResponse(response2.body, limits.maxCompressedBytes);
+  return { alias, repository, commitSha, compressed, limits };
+}
+async function readBoundedResponse(body, maximum) {
+  if (!body) throw new CodeRuntimeControlError("Code source archive body is missing", 502, "invalid_response");
+  const reader = body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maximum) {
+        await reader.cancel().catch(() => void 0);
+        throw new CodeRuntimeControlError("Code source archive exceeds its byte bound", 502, "invalid_response");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const result = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}
 
 // src/code-runtime.ts
-var CODE_RUNTIME_PROTOCOL_VERSION = 2;
+var CODE_RUNTIME_PROTOCOL_VERSION = 3;
 async function runCodeRuntimeHeartbeatLoop(options) {
   const heartbeatMs = options.heartbeatMs ?? 15e3;
   if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 1e3 || heartbeatMs > 3e5) {
@@ -1286,12 +1384,12 @@ function retryableControlFailure(value) {
   return failure.status === 408 || failure.status === 425 || failure.status === 429 || failure.status >= 500;
 }
 function wait(ms, signal) {
-  return new Promise((resolve7) => {
-    if (signal?.aborted) return resolve7();
-    const timer = setTimeout(resolve7, ms);
+  return new Promise((resolve8) => {
+    if (signal?.aborted) return resolve8();
+    const timer = setTimeout(resolve8, ms);
     signal?.addEventListener("abort", () => {
       clearTimeout(timer);
-      resolve7();
+      resolve8();
     }, { once: true });
   });
 }
@@ -1949,7 +2047,8 @@ function codeCommandMetadata(payload, resume) {
   const repository = trusted?.repository;
   const baseCommitSha = trusted?.commitSha;
   const sourceTreeDigest = trusted?.treeDigest;
-  if (typeof repository !== "string" || !repository.includes("/") || typeof baseCommitSha !== "string" || !/^[0-9a-f]{40}$/.test(baseCommitSha) || typeof sourceTreeDigest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(sourceTreeDigest)) {
+  const hostMaterialized = record3(payload.sourceSet) !== null && sourceTreeDigest === void 0;
+  if (typeof repository !== "string" || !repository.includes("/") || typeof baseCommitSha !== "string" || !/^[0-9a-f]{40}$/.test(baseCommitSha) || !hostMaterialized && (typeof sourceTreeDigest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(sourceTreeDigest))) {
     throw new TypeError(`invalid Code ${resume ? "resume" : "start"} trusted base`);
   }
   if (!Number.isSafeInteger(maxTokensPerInteraction) || Number(maxTokensPerInteraction) < 4e3 || Number(maxTokensPerInteraction) > 2e5) {
@@ -1965,7 +2064,7 @@ function codeCommandMetadata(payload, resume) {
     attestationDigest: typeof attestation === "string" ? attestation : "resume",
     repository,
     baseCommitSha,
-    sourceTreeDigest
+    sourceTreeDigest: typeof sourceTreeDigest === "string" ? sourceTreeDigest : null
   };
 }
 function codeLocalSource(payload) {
@@ -2030,19 +2129,320 @@ async function prepareRuntimeLocalSource(input) {
 }
 
 // src/code-runtime-source.ts
+var import_promises10 = require("fs/promises");
+var import_node_os4 = require("os");
+var import_node_path10 = require("path");
+
+// src/code-runtime-archive.ts
+var import_node_zlib = require("zlib");
 var import_promises8 = require("fs/promises");
 var import_node_os3 = require("os");
 var import_node_path8 = require("path");
 var RESERVED2 = /* @__PURE__ */ new Set([".git", ".odla", ".wrangler", "node_modules", "dist", "coverage"]);
 var SECRET2 = /^(?:\.env(?:\..+)?|\.dev\.vars|credentials(?:\..+)?\.json|dev-token(?:\..+)?\.json)$/i;
+var MAX_NUL_SHARE = 0.1;
+async function materializeCodeRuntimeArchive(archive, visiblePaths, tempRoot = (0, import_node_os3.tmpdir)()) {
+  if (!archive.compressed.byteLength || archive.compressed.byteLength > archive.limits.maxCompressedBytes) {
+    throw new TypeError("Code source archive exceeds its compressed byte bound");
+  }
+  let bytes;
+  try {
+    bytes = archive.compressed[0] === 31 && archive.compressed[1] === 139 ? (0, import_node_zlib.gunzipSync)(archive.compressed, { maxOutputLength: archive.limits.maxDecompressedBytes }) : archive.compressed;
+  } catch {
+    throw new TypeError("Code source archive is not a valid bounded gzip stream");
+  }
+  if (bytes.byteLength > archive.limits.maxDecompressedBytes) {
+    throw new TypeError("Code source archive exceeds its decompressed byte bound");
+  }
+  const entries = parseTar(bytes, archive.limits);
+  const root = await (0, import_promises8.mkdtemp)((0, import_node_path8.join)(tempRoot, "odla-code-archive-"));
+  const sourceDir = (0, import_node_path8.join)(root, "source");
+  await (0, import_promises8.mkdir)(sourceDir);
+  let visible = 0;
+  try {
+    for (const entry of entries) {
+      if (entry.directory || visiblePaths && !visiblePaths.has(entry.path)) continue;
+      if (filteredPath(entry.path)) continue;
+      let content;
+      try {
+        content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(entry.bytes);
+      } catch {
+        continue;
+      }
+      if (nulShare(content) > MAX_NUL_SHARE) continue;
+      const target = (0, import_node_path8.resolve)(sourceDir, entry.path);
+      if (!target.startsWith(`${(0, import_node_path8.resolve)(sourceDir)}${import_node_path8.sep}`)) throw new TypeError("Code source path escapes its root");
+      await (0, import_promises8.mkdir)((0, import_node_path8.dirname)(target), { recursive: true });
+      await (0, import_promises8.writeFile)(target, content, { flag: "wx", mode: 420 });
+      visible += 1;
+    }
+    if (!visible && !visiblePaths) throw new TypeError("GitHub commit has no Code-visible text source");
+    return { sourceDir, cleanup: () => (0, import_promises8.rm)(root, { recursive: true, force: true }) };
+  } catch (cause) {
+    await (0, import_promises8.rm)(root, { recursive: true, force: true });
+    throw cause;
+  }
+}
+function parseTar(bytes, limits) {
+  const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+  const entries = [];
+  const archivePaths = /* @__PURE__ */ new Set();
+  let entryCount = 0;
+  let fileCount = 0;
+  let totalFileBytes = 0;
+  let pendingPath;
+  let pendingPaxPath;
+  let offset = 0;
+  let ended = false;
+  while (offset + 512 <= bytes.byteLength) {
+    const header = bytes.subarray(offset, offset + 512);
+    offset += 512;
+    if (zeroBlock(header)) {
+      ended = true;
+      assertZeroTail(bytes, offset);
+      break;
+    }
+    entryCount += 1;
+    if (entryCount > limits.maxEntries) throw new TypeError("Code source archive has too many entries");
+    validateChecksum(header);
+    const type = header[156] ?? 0;
+    const size = tarNumber(header.subarray(124, 136));
+    if (size > limits.maxDecompressedBytes || offset + aligned(size) > bytes.byteLength) {
+      throw new TypeError("Code source archive entry is invalid or too large");
+    }
+    const payload = bytes.subarray(offset, offset + size);
+    offset += aligned(size);
+    if (type === 120 || type === 103) {
+      if (size > limits.maxExtendedHeaderBytes) throw new TypeError("Code source archive extended header is too large");
+      const pax = parsePax(payload, decoder, limits.maxPathBytes);
+      if (pax.linkpath !== void 0 || pax.size !== void 0 || Object.keys(pax).some((key) => key.toLowerCase().includes("sparse"))) {
+        throw new TypeError("Code source archive contains an unsupported entry");
+      }
+      if (type === 103 && pax.path !== void 0) throw new TypeError("Code source archive path is unsafe");
+      if (type === 120 && pax.path !== void 0) {
+        if (pendingPaxPath !== void 0 || pendingPath !== void 0) throw new TypeError("Code source archive is invalid");
+        pendingPaxPath = pax.path;
+      }
+      continue;
+    }
+    if (type === 76) {
+      if (size > limits.maxExtendedHeaderBytes || pendingPath !== void 0 || pendingPaxPath !== void 0) {
+        throw new TypeError("Code source archive long path is invalid");
+      }
+      pendingPath = validateArchivePath(decode(payload, decoder).replace(/\0+$/, "").replace(/\n$/, ""), limits.maxPathBytes);
+      continue;
+    }
+    if (type === 75) throw new TypeError("Code source archive contains an unsupported link");
+    const path = validateArchivePath(pendingPaxPath ?? pendingPath ?? tarPath(header, decoder), limits.maxPathBytes);
+    pendingPaxPath = void 0;
+    pendingPath = void 0;
+    const directory = type === 53;
+    const regular = type === 0 || type === 48;
+    if (!directory && !regular || directory && size !== 0 || archivePaths.has(path)) {
+      throw new TypeError("Code source archive contains an invalid or duplicate entry");
+    }
+    archivePaths.add(path);
+    if (regular) {
+      fileCount += 1;
+      totalFileBytes += size;
+      if (fileCount > limits.maxFiles || size > limits.maxFileBytes || totalFileBytes > limits.maxTotalFileBytes) {
+        throw new TypeError("Code source archive exceeds its file bounds");
+      }
+    }
+    entries.push({ path, directory, ...regular ? { bytes: payload } : {} });
+  }
+  if (!ended || pendingPath !== void 0 || pendingPaxPath !== void 0 || !entries.length || !fileCount) {
+    throw new TypeError("Code source archive is incomplete");
+  }
+  return unwrapRepository(entries, limits.maxPathBytes);
+}
+function unwrapRepository(entries, maxPathBytes) {
+  const root = entries[0].path.split("/")[0];
+  if (!root || entries.some((entry) => entry.path !== root && !entry.path.startsWith(`${root}/`))) {
+    throw new TypeError("Code source archive has no single repository root");
+  }
+  const output = [];
+  const kinds = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (entry.path === root) {
+      if (!entry.directory) throw new TypeError("Code source archive root is not a directory");
+      continue;
+    }
+    const path = entry.path.slice(root.length + 1);
+    validateRepositoryPath(path, maxPathBytes);
+    const parts = path.split("/");
+    for (let index = 1; index < parts.length; index += 1) {
+      if (kinds.get(parts.slice(0, index).join("/")) === "file") throw new TypeError("Code source archive path conflicts");
+    }
+    if (!entry.directory) {
+      for (const existing of kinds.keys()) {
+        if (existing.startsWith(`${path}/`)) throw new TypeError("Code source archive path conflicts");
+      }
+    }
+    if (kinds.has(path)) throw new TypeError("Code source archive repeats a path");
+    kinds.set(path, entry.directory ? "directory" : "file");
+    output.push({ ...entry, path });
+  }
+  return output.sort((left, right) => left.path.localeCompare(right.path));
+}
+function parsePax(bytes, decoder, maxPathBytes) {
+  const result = {};
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const space = bytes.indexOf(32, offset);
+    if (space < 0) throw new TypeError("Code source archive PAX header is invalid");
+    const lengthText = ascii(bytes.subarray(offset, space));
+    if (!/^[1-9][0-9]{0,8}$/.test(lengthText)) throw new TypeError("Code source archive PAX length is invalid");
+    const length = Number(lengthText);
+    const end = offset + length;
+    if (!Number.isSafeInteger(length) || end > bytes.byteLength || bytes[end - 1] !== 10) {
+      throw new TypeError("Code source archive PAX record is invalid");
+    }
+    const record5 = decode(bytes.subarray(space + 1, end - 1), decoder);
+    const equals = record5.indexOf("=");
+    if (equals < 1) throw new TypeError("Code source archive PAX field is invalid");
+    const key = record5.slice(0, equals);
+    if (Object.hasOwn(result, key)) throw new TypeError("Code source archive PAX field repeats");
+    result[key] = record5.slice(equals + 1);
+    offset = end;
+  }
+  if (result.path !== void 0) result.path = validateArchivePath(result.path, maxPathBytes);
+  return result;
+}
+var aligned = (size) => Math.ceil(size / 512) * 512;
+var zeroBlock = (block) => block.every((value) => value === 0);
+function validateChecksum(header) {
+  const expected = tarNumber(header.subarray(148, 156));
+  let actual = 0;
+  for (let index = 0; index < header.length; index += 1) actual += index >= 148 && index < 156 ? 32 : header[index];
+  if (actual !== expected) throw new TypeError("Code source archive checksum is invalid");
+}
+function tarNumber(field) {
+  if ((field[0] ?? 0) & 128) throw new TypeError("Code source archive numeric format is unsupported");
+  const value = ascii(field).replaceAll("\0", "").trim();
+  if (!value) return 0;
+  if (!/^[0-7]+$/.test(value)) throw new TypeError("Code source archive number is invalid");
+  const parsed = Number.parseInt(value, 8);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) throw new TypeError("Code source archive number is too large");
+  return parsed;
+}
+function tarPath(header, decoder) {
+  const name = decodeNul(header.subarray(0, 100), decoder);
+  const prefix = decodeNul(header.subarray(345, 500), decoder);
+  return prefix ? `${prefix}/${name}` : name;
+}
+function decodeNul(value, decoder) {
+  const end = value.indexOf(0);
+  return decode(end < 0 ? value : value.subarray(0, end), decoder);
+}
+function decode(value, decoder) {
+  try {
+    return decoder.decode(value);
+  } catch {
+    throw new TypeError("Code source archive text is invalid UTF-8");
+  }
+}
+function ascii(value) {
+  let output = "";
+  for (const byte of value) output += String.fromCharCode(byte);
+  return output;
+}
+function validateArchivePath(input, maximum) {
+  const path = input.endsWith("/") ? input.slice(0, -1) : input;
+  validateRepositoryPath(path, maximum);
+  return path;
+}
+function validateRepositoryPath(path, maximum) {
+  if (!path || path.startsWith("/") || path.includes("\\") || /[\u0000-\u001f\u007f]/.test(path) || new TextEncoder().encode(path).byteLength > maximum || path.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new TypeError("Code source archive path is unsafe");
+  }
+}
+function assertZeroTail(bytes, offset) {
+  for (let index = offset; index < bytes.byteLength; index += 1) {
+    if (bytes[index] !== 0) throw new TypeError("Code source archive has data after its end marker");
+  }
+}
+function filteredPath(path) {
+  const parts = path.split("/");
+  return parts.some((part) => RESERVED2.has(part) || SECRET2.test(part));
+}
+function nulShare(content) {
+  if (!content.length) return 0;
+  let count = 0;
+  for (let index = 0; index < content.length; index += 1) if (content.charCodeAt(index) === 0) count += 1;
+  return count / content.length;
+}
+
+// src/code-runtime-selected-source.ts
+var import_promises9 = require("fs/promises");
+var import_node_path9 = require("path");
+function selectedSourceSet(payload) {
+  if (!payload.sourceSet) return null;
+  const set = payload.sourceSet && typeof payload.sourceSet === "object" && !Array.isArray(payload.sourceSet) ? payload.sourceSet : null;
+  if (!set) throw new TypeError("Code selected source set is invalid");
+  const parse = (value, primary2) => {
+    const item = value && typeof value === "object" && !Array.isArray(value) ? value : null;
+    const alias = item?.alias;
+    const repository = item?.repository;
+    const commitSha = item?.commitSha;
+    const materialization = item?.materialization ?? "registry_snapshot";
+    if (typeof alias !== "string" || alias !== (primary2 ? "primary" : alias) || !/^[a-z][a-z0-9-]{0,39}$/.test(alias) || typeof repository !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) || typeof commitSha !== "string" || !/^[0-9a-f]{40}$/.test(commitSha) || !["registry_snapshot", "local_checkout", "host_archive"].includes(String(materialization))) {
+      throw new TypeError("Code selected source identity is invalid");
+    }
+    const visiblePaths = item?.visiblePaths;
+    if (visiblePaths !== void 0 && (!Array.isArray(visiblePaths) || visiblePaths.length > 2e3 || visiblePaths.some((path) => typeof path !== "string" || path.length > 4096))) {
+      throw new TypeError("Code selected source visibility slice is invalid");
+    }
+    return {
+      alias,
+      repository,
+      commitSha,
+      materialization,
+      ...visiblePaths ? { visiblePaths } : {}
+    };
+  };
+  if (!Array.isArray(set.references)) throw new TypeError("Code selected source references are invalid");
+  const primary = parse(set.primary, true);
+  const references = set.references.map((item) => parse(item, false));
+  const aliases = /* @__PURE__ */ new Set([primary.alias, ...references.map((item) => item.alias)]);
+  if (aliases.size !== references.length + 1) throw new TypeError("Code selected source aliases repeat");
+  return { primary, references };
+}
+async function attachReferenceDirectories(workspace, references) {
+  for (const reference of references) {
+    validateAlias(reference.alias);
+    for (const root of [workspace.baselineDir, workspace.workspaceDir]) {
+      const target = (0, import_node_path9.join)(root, ".odla-references", reference.alias);
+      await (0, import_promises9.mkdir)((0, import_node_path9.dirname)(target), { recursive: true });
+      await (0, import_promises9.cp)(reference.sourceDir, target, { recursive: true, errorOnExist: true, force: false });
+      await makeTreeReadOnly(target);
+    }
+  }
+}
+function validateAlias(alias) {
+  if (!/^[a-z][a-z0-9-]{0,39}$/.test(alias) || alias === "primary") {
+    throw new TypeError("Code reference alias is invalid");
+  }
+}
+async function makeTreeReadOnly(root) {
+  for (const entry of await (0, import_promises9.readdir)(root, { withFileTypes: true })) {
+    const target = (0, import_node_path9.join)(root, entry.name);
+    if (entry.isDirectory()) await makeTreeReadOnly(target);
+    else if (entry.isFile()) await (0, import_promises9.chmod)(target, 292);
+  }
+}
+
+// src/code-runtime-source.ts
+var RESERVED3 = /* @__PURE__ */ new Set([".git", ".odla", ".wrangler", "node_modules", "dist", "coverage"]);
+var SECRET3 = /^(?:\.env(?:\..+)?|\.dev\.vars|credentials(?:\..+)?\.json|dev-token(?:\..+)?\.json)$/i;
 var SOURCE_MAX_FILES = 1e5;
 var SOURCE_MAX_BYTES = 80 * 1024 * 1024;
 var SOURCE_SET_MAX_BYTES = 480 * 1024 * 1024;
-async function materializeCodeRuntimeSource(snapshot, tempRoot = (0, import_node_os3.tmpdir)()) {
+async function materializeCodeRuntimeSource(snapshot, tempRoot = (0, import_node_os4.tmpdir)()) {
   if (!snapshot.files.length || snapshot.files.length > SOURCE_MAX_FILES) throw new TypeError("Code source file count is invalid");
-  const root = await (0, import_promises8.mkdtemp)((0, import_node_path8.join)(tempRoot, "odla-code-source-"));
-  const sourceDir = (0, import_node_path8.join)(root, "source");
-  await (0, import_promises8.mkdir)(sourceDir);
+  const root = await (0, import_promises10.mkdtemp)((0, import_node_path10.join)(tempRoot, "odla-code-source-"));
+  const sourceDir = (0, import_node_path10.join)(root, "source");
+  await (0, import_promises10.mkdir)(sourceDir);
   const seen = /* @__PURE__ */ new Set();
   let bytes = 0;
   try {
@@ -2052,13 +2452,13 @@ async function materializeCodeRuntimeSource(snapshot, tempRoot = (0, import_node
       seen.add(file.path);
       bytes += Buffer.byteLength(file.path) + Buffer.byteLength(file.content);
       if (bytes > SOURCE_MAX_BYTES) throw new TypeError("Code source exceeds its byte bound");
-      const target = (0, import_node_path8.resolve)(sourceDir, file.path);
-      if (!target.startsWith(`${(0, import_node_path8.resolve)(sourceDir)}${import_node_path8.sep}`)) throw new TypeError("Code source path escapes its root");
-      await (0, import_promises8.mkdir)((0, import_node_path8.dirname)(target), { recursive: true });
-      await (0, import_promises8.writeFile)(target, file.content, { flag: "wx", mode: 420 });
+      const target = (0, import_node_path10.resolve)(sourceDir, file.path);
+      if (!target.startsWith(`${(0, import_node_path10.resolve)(sourceDir)}${import_node_path10.sep}`)) throw new TypeError("Code source path escapes its root");
+      await (0, import_promises10.mkdir)((0, import_node_path10.dirname)(target), { recursive: true });
+      await (0, import_promises10.writeFile)(target, file.content, { flag: "wx", mode: 420 });
     }
     for (const reference of snapshot.references ?? []) {
-      validateAlias(reference.alias);
+      validateAlias2(reference.alias);
       if (!reference.files.length || reference.files.length > SOURCE_MAX_FILES) throw new TypeError("Code reference file count is invalid");
       for (const file of reference.files) {
         validatePath(file.path);
@@ -2067,19 +2467,19 @@ async function materializeCodeRuntimeSource(snapshot, tempRoot = (0, import_node
         seen.add(path);
         bytes += Buffer.byteLength(path) + Buffer.byteLength(file.content);
         if (bytes > SOURCE_SET_MAX_BYTES) throw new TypeError("Code source set exceeds its byte bound");
-        const target = (0, import_node_path8.resolve)(sourceDir, path);
-        if (!target.startsWith(`${(0, import_node_path8.resolve)(sourceDir)}${import_node_path8.sep}`)) throw new TypeError("Code reference path escapes its root");
-        await (0, import_promises8.mkdir)((0, import_node_path8.dirname)(target), { recursive: true });
-        await (0, import_promises8.writeFile)(target, file.content, { flag: "wx", mode: 292 });
+        const target = (0, import_node_path10.resolve)(sourceDir, path);
+        if (!target.startsWith(`${(0, import_node_path10.resolve)(sourceDir)}${import_node_path10.sep}`)) throw new TypeError("Code reference path escapes its root");
+        await (0, import_promises10.mkdir)((0, import_node_path10.dirname)(target), { recursive: true });
+        await (0, import_promises10.writeFile)(target, file.content, { flag: "wx", mode: 292 });
       }
     }
-    return { sourceDir, cleanup: () => (0, import_promises8.rm)(root, { recursive: true, force: true }) };
+    return { sourceDir, cleanup: () => (0, import_promises10.rm)(root, { recursive: true, force: true }) };
   } catch (cause) {
-    await (0, import_promises8.rm)(root, { recursive: true, force: true });
+    await (0, import_promises10.rm)(root, { recursive: true, force: true });
     throw cause;
   }
 }
-function validateAlias(alias) {
+function validateAlias2(alias) {
   if (!/^[a-z][a-z0-9-]{0,39}$/.test(alias) || alias === "primary") {
     throw new TypeError("Code reference alias is invalid");
   }
@@ -2087,24 +2487,24 @@ function validateAlias(alias) {
 async function attachCodeRuntimeReferences(workspace, references) {
   let bytes = 0;
   for (const reference of references) {
-    validateAlias(reference.alias);
+    validateAlias2(reference.alias);
     for (const file of reference.files) {
       validatePath(file.path);
       const path = `.odla-references/${reference.alias}/${file.path}`;
       bytes += Buffer.byteLength(path) + Buffer.byteLength(file.content);
       if (bytes > SOURCE_SET_MAX_BYTES - SOURCE_MAX_BYTES) throw new TypeError("Code reference set exceeds its byte bound");
       for (const root of [workspace.baselineDir, workspace.workspaceDir]) {
-        const target = (0, import_node_path8.resolve)(root, path);
-        if (!target.startsWith(`${(0, import_node_path8.resolve)(root)}${import_node_path8.sep}`)) throw new TypeError("Code reference path escapes its root");
-        await (0, import_promises8.mkdir)((0, import_node_path8.dirname)(target), { recursive: true });
-        await (0, import_promises8.writeFile)(target, file.content, { flag: "wx", mode: 292 });
+        const target = (0, import_node_path10.resolve)(root, path);
+        if (!target.startsWith(`${(0, import_node_path10.resolve)(root)}${import_node_path10.sep}`)) throw new TypeError("Code reference path escapes its root");
+        await (0, import_promises10.mkdir)((0, import_node_path10.dirname)(target), { recursive: true });
+        await (0, import_promises10.writeFile)(target, file.content, { flag: "wx", mode: 292 });
       }
     }
   }
 }
 function validatePath(path) {
   const parts = path.split("/");
-  if (!path || path.startsWith("/") || path.includes("\\") || path.includes("\0") || parts.some((part) => !part || part === "." || part === ".." || RESERVED2.has(part) || SECRET2.test(part))) {
+  if (!path || path.startsWith("/") || path.includes("\\") || path.includes("\0") || parts.some((part) => !part || part === "." || part === ".." || RESERVED3.has(part) || SECRET3.test(part))) {
     throw new TypeError("Code source contains an unsafe path");
   }
 }
@@ -2132,12 +2532,12 @@ async function materializeCommandWorkspace(input) {
         throw new TypeError("Code selected source set is invalid");
       }
       if (references.length) {
-        const selected = await input.control.source(command.sessionId);
-        if (selected.repository !== metadata.repository || selected.commitSha !== metadata.baseCommitSha || selected.treeDigest !== metadata.sourceTreeDigest) {
+        const selected2 = await input.control.source(command.sessionId);
+        if (selected2.repository !== metadata.repository || selected2.commitSha !== metadata.baseCommitSha || selected2.treeDigest !== metadata.sourceTreeDigest) {
           await prepared.workspace.cleanup();
           throw new TypeError("Code local source does not match the selected GitHub primary source");
         }
-        await attachCodeRuntimeReferences(prepared.workspace, selected.references ?? []);
+        await attachCodeRuntimeReferences(prepared.workspace, selected2.references ?? []);
       }
     }
     return {
@@ -2147,6 +2547,63 @@ async function materializeCommandWorkspace(input) {
       requestedLocal
     };
   }
+  const selected = selectedSourceSet(command.payload);
+  if (selected?.primary.materialization === "host_archive") {
+    if (!input.control.sourceArchive) {
+      throw new TypeError("Code runtime protocol does not support host source materialization");
+    }
+    const sources = [selected.primary, ...selected.references];
+    const materialized2 = [];
+    try {
+      for (const descriptor2 of sources) {
+        if (descriptor2.materialization !== "host_archive") {
+          throw new TypeError("Code selected source set mixes incompatible materialization modes");
+        }
+        const archive = await input.control.sourceArchive(command.sessionId, descriptor2.alias);
+        if (archive.repository !== descriptor2.repository || archive.commitSha !== descriptor2.commitSha) {
+          throw new TypeError("Code source archive does not match its selected repository and commit");
+        }
+        const source2 = await materializeCodeRuntimeArchive(
+          archive,
+          descriptor2.visiblePaths ? new Set(descriptor2.visiblePaths) : void 0
+        );
+        const treeDigest = await digestStagedWorkspace(source2.sourceDir, {
+          maxFiles: archive.limits.maxFiles,
+          maxBytes: archive.limits.maxTotalFileBytes
+        });
+        materialized2.push({ descriptor: descriptor2, source: source2, treeDigest });
+      }
+      const primary = materialized2[0];
+      const workspace = resume ? (await restoreCodeWorkspaceCheckpoint({
+        trustedBaseDir: primary.source.sourceDir,
+        trustedBaseCommitSha: primary.descriptor.commitSha,
+        checkpoint: codeCheckpointPayload(command.payload)
+      })).workspace : await stageWorkspace(primary.source.sourceDir, {
+        maxFiles: SOURCE_MAX_FILES,
+        maxBytes: SOURCE_SET_MAX_BYTES
+      });
+      try {
+        await attachReferenceDirectories(workspace, materialized2.slice(1).map((item) => ({
+          alias: item.descriptor.alias,
+          sourceDir: item.source.sourceDir
+        })));
+      } catch (cause) {
+        await workspace.cleanup();
+        throw cause;
+      }
+      return {
+        workspace,
+        sourceDigest: primary.treeDigest,
+        requestedLocal: null,
+        sourceDigests: materialized2.map((item) => ({
+          alias: item.descriptor.alias,
+          treeDigest: item.treeDigest
+        }))
+      };
+    } finally {
+      await Promise.allSettled(materialized2.map((item) => item.source.cleanup()));
+    }
+  }
   const source = await input.control.source(command.sessionId);
   const materialized = await materializeCodeRuntimeSource(source);
   try {
@@ -2201,10 +2658,12 @@ Prefer these over listing the tree \u2014 a full listing of a real repository is
 of thousands of tokens and you will carry it for the rest of the session.
 
 Then odla_search for a literal string, odla_read for a bounded range, and
-odla_apply_git_diff to change something. A patch must start with
-"diff --git a/<path> b/<path>", include matching "---" and "+++" headers and
-numbered "@@" hunks with at least one line of surrounding context, and must never
-use "*** Begin Patch" wrappers.
+odla_edit_file to change an existing file: give it the exact current text
+(copied verbatim from odla_read) and the text that replaces it; it must match
+once. Use odla_apply_git_diff only to create or delete whole files. A patch must
+start with "diff --git a/<path> b/<path>", include matching "---" and "+++"
+headers and numbered "@@" hunks with at least one line of surrounding context,
+and must never use "*** Begin Patch" wrappers.
 
 The workspace, model, and tool effects are controlled by the host broker.
 Never claim a build or test passed unless odla_run_recipe returned that result.`;
@@ -2264,6 +2723,21 @@ function codeSkill(opts) {
     },
     handler: (input, ctx) => call("sandbox.apply_patch", input, ctx.signal)
   };
+  const editFile = {
+    name: "odla_edit_file",
+    description: "Change an existing file by replacing one exact stretch of its current text with new text. oldText must match the file exactly once (copy it verbatim from odla_read, including indentation and blank lines; widen it if it would match more than once). Prefer this over odla_apply_git_diff for every change to an existing file; use odla_apply_git_diff only to create or delete whole files.",
+    inputSchema: {
+      type: "object",
+      required: ["path", "oldText", "newText"],
+      properties: {
+        path: { type: "string", minLength: 1, maxLength: 1024 },
+        oldText: { type: "string", minLength: 1, maxLength: 262144 },
+        newText: { type: "string", maxLength: 262144 }
+      },
+      additionalProperties: false
+    },
+    handler: (input, ctx) => call("sandbox.edit", input, ctx.signal)
+  };
   const runRecipe = {
     name: "odla_run_recipe",
     description: `Run one app-registered build or test recipe through CaMeL policy.${opts.recipeIds?.length ? ` Available recipes: ${opts.recipeIds.join(", ")}.` : ""}`,
@@ -2351,7 +2825,7 @@ function codeSkill(opts) {
     )
   ];
   const effects = opts.readOnly ? [] : [applyPatch, runRecipe];
-  const tools = opts.surface === "v3" ? [...orientation, searchFiles, read2, ...effects] : opts.surface === "v2" ? [listFiles, searchFiles, read2, ...effects] : [read2, ...effects];
+  const tools = opts.surface === "v3" ? [...orientation, searchFiles, read2, ...opts.readOnly ? [] : [editFile], ...effects] : opts.surface === "v2" ? [listFiles, searchFiles, read2, ...effects] : [read2, ...effects];
   return { name: "code", tools };
 }
 
@@ -2484,14 +2958,40 @@ async function sessionSkillsFor(options, command) {
 }
 
 // src/code-runtime-inference.ts
+var OVERLOAD_RETRY_DELAYS_MS = [2e3, 4e3, 8e3, 16e3];
+var RETRYABLE_CODES = /* @__PURE__ */ new Set(["control_plane_overloaded", "registry_overloaded", "transport_unavailable"]);
+function overloadedControlFailure(cause) {
+  return cause instanceof CodeRuntimeControlError && cause.status === 503 && RETRYABLE_CODES.has(cause.code);
+}
+async function inferWithBackoff(infer, wait2, onRetry) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await infer();
+    } catch (cause) {
+      const delayMs = OVERLOAD_RETRY_DELAYS_MS[attempt];
+      if (delayMs === void 0 || !overloadedControlFailure(cause)) throw cause;
+      await onRetry(cause, delayMs);
+      await wait2(delayMs);
+    }
+  }
+}
 async function handleCodeRuntimeInference(input) {
   const { command, request, state } = input;
   const startedAt = Date.now();
-  const response2 = await input.control.infer(command.sessionId, {
-    requestId: request.requestId,
-    interactionId: command.commandId,
-    call: request.call
-  });
+  const wait2 = input.wait ?? ((ms) => new Promise((resolve8) => setTimeout(resolve8, ms)));
+  const response2 = await inferWithBackoff(
+    () => input.control.infer(command.sessionId, {
+      requestId: request.requestId,
+      interactionId: command.commandId,
+      call: request.call
+    }),
+    wait2,
+    (cause, delayMs) => input.event({
+      type: "diagnostic",
+      level: "error",
+      message: `Code control plane overloaded (${cause.code}); retrying the model call in ${delayMs / 1e3}s`
+    }).catch(() => void 0)
+  );
   state.tokens += response2.receipt.inputTokens + response2.receipt.outputTokens;
   const { costUsd } = response2.receipt;
   if (costUsd === void 0) state.costKnown = false;
@@ -2615,6 +3115,10 @@ function codeToolRequestPresentation(request) {
   if (request.tool === "sandbox.apply_patch") {
     return { kind: "patch", ...patchStats(input.patch) };
   }
+  if (request.tool === "sandbox.edit") {
+    const lines = (value) => typeof value === "string" ? value.slice(0, 262144).split("\n").length : 0;
+    return { kind: "patch", additions: lines(input.newText), deletions: lines(input.oldText) };
+  }
   const recipeId = text(input.recipeId, 120);
   return recipeId ? { kind: "recipe", recipeId } : void 0;
 }
@@ -2742,6 +3246,11 @@ var PATCH = descriptor("sandbox.apply_patch", "reversible_mutation", {
   authority: "authority",
   patch: "payload"
 });
+var EDIT = descriptor("sandbox.edit", "reversible_mutation", {
+  workspace: "destination",
+  authority: "authority",
+  patch: "payload"
+});
 var RECIPE = descriptor("sandbox.run_recipe", "code_execution", {
   workspace: "destination",
   authority: "authority",
@@ -2809,6 +3318,14 @@ function createCodePolicyGate(options) {
         patch: { role: "payload", value: patch2 }
       }, []);
     },
+    edit: async (input) => {
+      const base = await environment(input, options, "sandbox.edit");
+      const patch2 = unsafe(base, input.patch, "patch");
+      return authorize(input, options, base, EDIT, {
+        ...base.fixedArgs,
+        patch: { role: "payload", value: patch2 }
+      }, []);
+    },
     recipe: async (input) => {
       const base = await environment(input, options, "sandbox.run_recipe");
       const conversions = await conversionRegistry([
@@ -2953,13 +3470,134 @@ function response(request, ok, content, details) {
   return { requestId: request.requestId, ok, content, details: { ...details, failureReason } };
 }
 
-// src/code-tool-reads.ts
+// src/code-tool-edit.ts
+var import_promises12 = require("fs/promises");
+
+// src/code-tool-graph.ts
 var import_promises11 = require("fs/promises");
+var import_node_path11 = require("path");
+var import_graph = require("@odla-ai/graph");
+var import_code4 = require("@odla-ai/graph/code");
+var cache = /* @__PURE__ */ new Map();
+function workspaceGraphs(workspaceDir, paths2) {
+  const existing = cache.get(workspaceDir);
+  if (existing) return existing;
+  const read2 = (path) => (0, import_promises11.readFile)((0, import_node_path11.join)(workspaceDir, path), "utf8");
+  const built = (async () => ({
+    // No knownTables: a staged workspace may not carry migrations, and a filter
+    // that silently drops every table is worse than an unfiltered one. Callers
+    // with ground truth should build the graph themselves.
+    graph: await (0, import_code4.buildCodeGraph)({ paths: paths2, read: read2, data: { ignore: (path) => path.includes(".generated.") } })
+  }))();
+  cache.set(workspaceDir, built);
+  return built;
+}
+function forgetWorkspaceGraphs(workspaceDir) {
+  cache.delete(workspaceDir);
+}
+var shortId = (id) => id.slice(id.indexOf(":") + 1);
+function renderOverview(graphs, prefix) {
+  const rows = (0, import_graph.rollup)(graphs.graph, import_code4.FILE, prefix === void 0 ? {} : { prefix });
+  if (rows.length === 0) return prefix ? `No source under "${prefix}".` : "No source files.";
+  const lines = rows.slice(0, 60).map((row) => `${row.prefix}  (${row.count})  e.g. ${row.examples[0] ?? ""}`);
+  const total = (0, import_graph.nodesOfKind)(graphs.graph, import_code4.FILE).length;
+  return [`${total} source files. Directories, largest first \u2014 read one with sandbox.list --prefix.`, ...lines].join("\n");
+}
+function renderWhereIs(graphs, symbol) {
+  const sites = (0, import_graph.neighbors)(graphs.graph, (0, import_graph.nodeId)(import_code4.SYMBOL, symbol), { direction: "in", kinds: ["exports"] }).map((id) => ({
+    path: shortId(id),
+    pkg: (0, import_graph.neighbors)(graphs.graph, id, { direction: "in", kinds: ["contains"] })[0],
+    dependents: (0, import_graph.incident)(graphs.graph, id, { direction: "in", kinds: [import_code4.IMPORTS] }).length
+  })).sort((left, right) => right.dependents - left.dependents || left.path.localeCompare(right.path));
+  if (sites.length === 0) return `No exported symbol named "${symbol}". Try sandbox.search for a textual match.`;
+  return sites.slice(0, 20).map((site) => `${site.path}${site.pkg ? `  [${shortId(site.pkg)}]` : ""}  ${site.dependents} dependents`).join("\n");
+}
+function renderWhoImports(graphs, path) {
+  const id = (0, import_graph.nodeId)(import_code4.FILE, path);
+  const importers = (0, import_graph.neighbors)(graphs.graph, id, { direction: "in", kinds: [import_code4.IMPORTS] });
+  if (importers.length === 0) {
+    return graphs.graph.nodes.has(id) ? `Nothing imports ${path}. It is a leaf.` : `${path} is not a source file in this workspace.`;
+  }
+  return importers.slice(0, 40).map(shortId).sort().join("\n");
+}
+function renderWhoTouches(graphs, query) {
+  const needle = query.toLowerCase();
+  const hits = [...graphs.graph.nodes.values()].filter((node) => (node.kind === "table" || node.kind === "namespace") && node.name.toLowerCase().includes(needle)).slice(0, 10);
+  if (hits.length === 0) return `No table or namespace matching "${query}".`;
+  return hits.map((hit) => {
+    const side = (kind) => (0, import_graph.neighbors)(graphs.graph, hit.id, { direction: "in", kinds: [kind] }).map(shortId).sort().slice(0, 8);
+    return [
+      `${hit.name}  (${hit.kind})`,
+      `  writes: ${side(import_code4.WRITES).join(", ") || "(none)"}`,
+      `  reads:  ${side(import_code4.READS).join(", ") || "(none)"}`
+    ].join("\n");
+  }).join("\n\n");
+}
+
+// src/code-tool-edit.ts
+var MAX_TEXT_BYTES = 256 * 1024;
+function editAsDiff(path, oldText, newText) {
+  const removed = oldText.split("\n").map((line) => `-${line}`);
+  const added = newText.split("\n").map((line) => `+${line}`);
+  return `diff --git a/${path} b/${path}
+--- a/${path}
++++ b/${path}
+@@ -1,${removed.length} +1,${added.length} @@
+${[...removed, ...added].join("\n")}
+`;
+}
+function occurrences(haystack, needle) {
+  let count = 0;
+  for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + needle.length)) count += 1;
+  return count;
+}
+async function editCodeFile(workspaceDir, path, oldText, newText) {
+  if (!oldText) throw new TypeError("oldText must not be empty; to create a file use sandbox.apply_patch with a new-file diff");
+  if (Buffer.byteLength(oldText) > MAX_TEXT_BYTES || Buffer.byteLength(newText) > MAX_TEXT_BYTES) {
+    throw new TypeError(`oldText and newText must each stay under ${MAX_TEXT_BYTES} bytes; split the change`);
+  }
+  if (oldText.includes("\0") || newText.includes("\0")) throw new TypeError("edit text contains NUL bytes; use plain text");
+  const target = resolveCodePath(workspaceDir, path);
+  const current = await (0, import_promises12.readFile)(target, "utf8");
+  const found = occurrences(current, oldText);
+  if (found === 0) {
+    throw new TypeError(`oldText was not found in "${path}"; sandbox.read the current lines and copy them exactly, including indentation and blank lines`);
+  }
+  if (found > 1) {
+    throw new TypeError(`oldText occurs ${found} times in "${path}"; include more of the surrounding lines so it matches exactly once`);
+  }
+  const at = current.indexOf(oldText);
+  await (0, import_promises12.writeFile)(target, `${current.slice(0, at)}${newText}${current.slice(at + oldText.length)}`, "utf8");
+  return { deletions: oldText.split("\n").length, additions: newText.split("\n").length };
+}
+async function edit(context, request, options, policy, registry) {
+  exactKeys(request.input, ["path", "oldText", "newText"]);
+  const path = stringField(request.input, "path");
+  const oldText = stringField(request.input, "oldText");
+  const newText = typeof request.input.newText === "string" ? request.input.newText : stringField(request.input, "newText");
+  const paths2 = await registry.files(context.workspaceDir);
+  if (!paths2.includes(path)) {
+    throw new TypeError(`no such file in the staged workspace: "${path}". Use sandbox.overview, sandbox.where_is or sandbox.search to find the correct path.`);
+  }
+  if (options.readOnlyPrefixes?.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))) {
+    throw new TypeError("edit targets a read-only reference source");
+  }
+  const patch2 = editAsDiff(path, oldText, newText);
+  const allowed = await policy.edit(policyContext(context, request, options, { patch: patch2 }));
+  if (!allowed) return response(request, false, "tool denied by CaMeL policy");
+  const changed = await editCodeFile(context.workspaceDir, path, oldText, newText);
+  registry.invalidate(context.workspaceDir);
+  forgetWorkspaceGraphs(context.workspaceDir);
+  return response(request, true, `Edited ${path}: -${changed.deletions} +${changed.additions} line(s).`, { paths: [path], ...changed });
+}
+
+// src/code-tool-reads.ts
+var import_promises14 = require("fs/promises");
 
 // src/code-tool-discovery.ts
 var import_node_child_process6 = require("child_process");
-var import_promises9 = require("fs/promises");
-var import_node_path9 = require("path");
+var import_promises13 = require("fs/promises");
+var import_node_path12 = require("path");
 var DEFAULT_MAX_FILES = 2e4;
 var DEFAULT_MAX_RESULTS = 100;
 var DEFAULT_MAX_FILE_BYTES = 512 * 1024;
@@ -2984,13 +3622,13 @@ function createWorkspaceFileRegistry(limit = DEFAULT_MAX_FILES, enumerate = regi
 async function registeredFiles(root, limit = DEFAULT_MAX_FILES) {
   const paths2 = [];
   const walk = async (directory) => {
-    for (const entry of await (0, import_promises9.readdir)(directory, { withFileTypes: true })) {
+    for (const entry of await (0, import_promises13.readdir)(directory, { withFileTypes: true })) {
       if (SKIP_WORKSPACE_DIRS.has(entry.name)) continue;
       if (entry.isSymbolicLink()) throw new TypeError("workspace contains a symbolic link");
-      const target = (0, import_node_path9.resolve)(directory, entry.name);
+      const target = (0, import_node_path12.resolve)(directory, entry.name);
       if (entry.isDirectory()) await walk(target);
       else if (entry.isFile()) {
-        const path = (0, import_node_path9.relative)(root, target).split("\\").join("/");
+        const path = (0, import_node_path12.relative)(root, target).split("\\").join("/");
         try {
           validateRelativePath(path);
         } catch {
@@ -3001,7 +3639,7 @@ async function registeredFiles(root, limit = DEFAULT_MAX_FILES) {
       }
     }
   };
-  await walk((0, import_node_path9.resolve)(root));
+  await walk((0, import_node_path12.resolve)(root));
   return paths2.sort();
 }
 function listWorkspace(paths2, options = {}) {
@@ -3115,7 +3753,7 @@ async function fallbackSearch(root, scoped, options) {
     if (matches.length >= options.maxResults) break;
     let source;
     try {
-      source = await (0, import_promises9.readFile)((0, import_node_path9.resolve)(root, path));
+      source = await (0, import_promises13.readFile)((0, import_node_path12.resolve)(root, path));
     } catch {
       continue;
     }
@@ -3132,67 +3770,6 @@ async function fallbackSearch(root, scoped, options) {
   return matches;
 }
 
-// src/code-tool-graph.ts
-var import_promises10 = require("fs/promises");
-var import_node_path10 = require("path");
-var import_graph = require("@odla-ai/graph");
-var import_code4 = require("@odla-ai/graph/code");
-var cache = /* @__PURE__ */ new Map();
-function workspaceGraphs(workspaceDir, paths2) {
-  const existing = cache.get(workspaceDir);
-  if (existing) return existing;
-  const read2 = (path) => (0, import_promises10.readFile)((0, import_node_path10.join)(workspaceDir, path), "utf8");
-  const built = (async () => ({
-    // No knownTables: a staged workspace may not carry migrations, and a filter
-    // that silently drops every table is worse than an unfiltered one. Callers
-    // with ground truth should build the graph themselves.
-    graph: await (0, import_code4.buildCodeGraph)({ paths: paths2, read: read2, data: { ignore: (path) => path.includes(".generated.") } })
-  }))();
-  cache.set(workspaceDir, built);
-  return built;
-}
-function forgetWorkspaceGraphs(workspaceDir) {
-  cache.delete(workspaceDir);
-}
-var shortId = (id) => id.slice(id.indexOf(":") + 1);
-function renderOverview(graphs, prefix) {
-  const rows = (0, import_graph.rollup)(graphs.graph, import_code4.FILE, prefix === void 0 ? {} : { prefix });
-  if (rows.length === 0) return prefix ? `No source under "${prefix}".` : "No source files.";
-  const lines = rows.slice(0, 60).map((row) => `${row.prefix}  (${row.count})  e.g. ${row.examples[0] ?? ""}`);
-  const total = (0, import_graph.nodesOfKind)(graphs.graph, import_code4.FILE).length;
-  return [`${total} source files. Directories, largest first \u2014 read one with sandbox.list --prefix.`, ...lines].join("\n");
-}
-function renderWhereIs(graphs, symbol) {
-  const sites = (0, import_graph.neighbors)(graphs.graph, (0, import_graph.nodeId)(import_code4.SYMBOL, symbol), { direction: "in", kinds: ["exports"] }).map((id) => ({
-    path: shortId(id),
-    pkg: (0, import_graph.neighbors)(graphs.graph, id, { direction: "in", kinds: ["contains"] })[0],
-    dependents: (0, import_graph.incident)(graphs.graph, id, { direction: "in", kinds: [import_code4.IMPORTS] }).length
-  })).sort((left, right) => right.dependents - left.dependents || left.path.localeCompare(right.path));
-  if (sites.length === 0) return `No exported symbol named "${symbol}". Try sandbox.search for a textual match.`;
-  return sites.slice(0, 20).map((site) => `${site.path}${site.pkg ? `  [${shortId(site.pkg)}]` : ""}  ${site.dependents} dependents`).join("\n");
-}
-function renderWhoImports(graphs, path) {
-  const id = (0, import_graph.nodeId)(import_code4.FILE, path);
-  const importers = (0, import_graph.neighbors)(graphs.graph, id, { direction: "in", kinds: [import_code4.IMPORTS] });
-  if (importers.length === 0) {
-    return graphs.graph.nodes.has(id) ? `Nothing imports ${path}. It is a leaf.` : `${path} is not a source file in this workspace.`;
-  }
-  return importers.slice(0, 40).map(shortId).sort().join("\n");
-}
-function renderWhoTouches(graphs, query) {
-  const needle = query.toLowerCase();
-  const hits = [...graphs.graph.nodes.values()].filter((node) => (node.kind === "table" || node.kind === "namespace") && node.name.toLowerCase().includes(needle)).slice(0, 10);
-  if (hits.length === 0) return `No table or namespace matching "${query}".`;
-  return hits.map((hit) => {
-    const side = (kind) => (0, import_graph.neighbors)(graphs.graph, hit.id, { direction: "in", kinds: [kind] }).map(shortId).sort().slice(0, 8);
-    return [
-      `${hit.name}  (${hit.kind})`,
-      `  writes: ${side(import_code4.WRITES).join(", ") || "(none)"}`,
-      `  reads:  ${side(import_code4.READS).join(", ") || "(none)"}`
-    ].join("\n");
-  }).join("\n\n");
-}
-
 // src/code-tool-reads.ts
 var GRAPH_TOOLS = /* @__PURE__ */ new Set([
   "sandbox.overview",
@@ -3215,11 +3792,11 @@ async function read(context, request, options, policy, registry) {
   const allowed = await policy.read(policyContext(context, request, options, { paths: paths2, path, startLine, endLine }));
   if (!allowed) return response(request, false, "tool denied by CaMeL policy");
   const target = resolveCodePath(context.workspaceDir, path);
-  const info = await (0, import_promises11.stat)(target);
+  const info = await (0, import_promises14.stat)(target);
   if (!info.isFile() || info.size > Math.max(options.maxReadBytes ?? 128 * 1024, 2 * 1024 * 1024)) {
     throw new TypeError("file is not a bounded regular source file");
   }
-  const source = await (0, import_promises11.readFile)(target);
+  const source = await (0, import_promises14.readFile)(target);
   if (source.includes(0)) throw new TypeError("binary files are not readable through this tool");
   const lines = source.toString("utf8").split("\n");
   const content = lines.slice(startLine - 1, endLine).join("\n");
@@ -3334,6 +3911,7 @@ async function route(context, request, options, recipes, policy, registry) {
     if (request.tool === "sandbox.search") return await search(context, request, options, policy, registry);
     if (GRAPH_TOOLS.has(request.tool)) return await graphQuery(context, request, options, policy, registry);
     if (request.tool === "sandbox.apply_patch") return await patch(context, request, options, policy, registry);
+    if (request.tool === "sandbox.edit") return await edit(context, request, options, policy, registry);
     return await recipe(context, request, options, recipes, policy);
   } catch (reason) {
     return response(request, false, toolFailureMessage(reason));
@@ -3764,8 +4342,8 @@ var runtimeErrorMessage = (value) => value instanceof Error ? value.message : St
 function codeRuntimeAcknowledgementGate(signal) {
   let settle;
   let settled = false;
-  const ready = new Promise((resolve7) => {
-    settle = resolve7;
+  const ready = new Promise((resolve8) => {
+    settle = resolve8;
   });
   const release = (run) => {
     if (settled) return;
@@ -3874,7 +4452,7 @@ var TheseusRuntimeEngine = class {
   async #start(command, resume) {
     if (this.#active.has(command.sessionId)) throw new TypeError("Code session is already active on this runtime");
     const metadata = codeCommandMetadata(command.payload, resume);
-    const { workspace, sourceDigest, localTrustedBaseDigest, requestedLocal } = await materializeCommandWorkspace({
+    const { workspace, sourceDigest, sourceDigests, localTrustedBaseDigest, requestedLocal } = await materializeCommandWorkspace({
       command,
       metadata,
       resume,
@@ -3895,7 +4473,7 @@ var TheseusRuntimeEngine = class {
       maxTokensPerInteraction: metadata.maxTokensPerInteraction,
       baseCommitSha: metadata.baseCommitSha,
       repository: metadata.repository,
-      sourceTreeDigest: metadata.sourceTreeDigest,
+      sourceTreeDigest: metadata.sourceTreeDigest ?? sourceDigest,
       trustedBaseDigest: requestedLocal ? localTrustedBaseDigest : await digestStagedWorkspace(workspace.baselineDir, {
         maxFiles: 2e4,
         maxBytes: 512 * 1024 * 1024
@@ -3921,7 +4499,11 @@ var TheseusRuntimeEngine = class {
       await this.#failure(command, active, detail);
       return null;
     });
-    return { status: "running", message: resume ? "Theseus resumed from a portable checkpoint" : "Theseus started" };
+    return {
+      status: "running",
+      message: resume ? "Theseus resumed from a portable checkpoint" : "Theseus started",
+      ...sourceDigests ? { sourceDigests } : {}
+    };
   }
   /**
    * Pursue a goal: attempt, judge with the clean verifier, re-prompt from what
@@ -4370,12 +4952,12 @@ function chooseStrategy(signals = {}) {
 var feedbackIsActionable = actionable;
 
 // src/code-recipe-dependencies.ts
-var import_promises12 = require("fs/promises");
-var import_node_path11 = require("path");
+var import_promises15 = require("fs/promises");
+var import_node_path13 = require("path");
 var RESERVED_MOUNTS = /* @__PURE__ */ new Set(["node_modules", "dist", "coverage"]);
 function withRecipeDependencies(executor, dependencies) {
   const mountAs = dependencies.mountAs ?? "node_modules";
-  if (!(0, import_node_path11.isAbsolute)(dependencies.source)) {
+  if (!(0, import_node_path13.isAbsolute)(dependencies.source)) {
     throw new TypeError("recipe dependency source must be an absolute path");
   }
   if (!RESERVED_MOUNTS.has(mountAs)) {
@@ -4383,24 +4965,24 @@ function withRecipeDependencies(executor, dependencies) {
   }
   return {
     run: async (input) => {
-      const target = (0, import_node_path11.join)(input.workspaceDir, mountAs);
+      const target = (0, import_node_path13.join)(input.workspaceDir, mountAs);
       let linked = false;
       try {
-        const existing = await (0, import_promises12.lstat)(target).catch(() => null);
+        const existing = await (0, import_promises15.lstat)(target).catch(() => null);
         if (!existing) {
-          await (0, import_promises12.symlink)(dependencies.source, target, "dir");
+          await (0, import_promises15.symlink)(dependencies.source, target, "dir");
           linked = true;
         }
         return await executor.run(input);
       } finally {
-        if (linked) await (0, import_promises12.rm)(target, { force: true, recursive: false }).catch(() => void 0);
+        if (linked) await (0, import_promises15.rm)(target, { force: true, recursive: false }).catch(() => void 0);
       }
     }
   };
 }
 async function installedDependencies(repoRoot) {
-  const source = (0, import_node_path11.join)(repoRoot, "node_modules");
-  const info = await (0, import_promises12.lstat)(source).catch(() => null);
+  const source = (0, import_node_path13.join)(repoRoot, "node_modules");
+  const info = await (0, import_promises15.lstat)(source).catch(() => null);
   return info?.isDirectory() ? { source } : null;
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -4441,6 +5023,7 @@ async function installedDependencies(repoRoot) {
   installedDependencies,
   integrateSubGoals,
   isCheckpointEffectCompleted,
+  materializeCodeRuntimeArchive,
   materializeCodeRuntimeSource,
   materializeCommandWorkspace,
   materializeGitTree,