impel-cli 0.20.2 → 0.20.4

package/src/remote/workspace.js

@@ -0,0 +1,482 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+
+import { runBuffer, runCapture } from "./process.js";
+
+export const WORKSPACE_SCHEMA_VERSION = 1;
+export const WORKSPACE_CONTENT_TYPE = "application/vnd.impel.workspace.v1+tar";
+const MAX_FILES = 20_000;
+const MAX_FILE_BYTES = 256 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 2 * 1024 * 1024 * 1024;
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+function git(root, args, options = {}) {
+  return runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", ["-C", root, ...args], options);
+}
+
+function gitBuffer(root, args, options = {}) {
+  return runBuffer(process.env.IMPEL_REMOTE_GIT_BIN || "git", ["-C", root, ...args], options).stdout;
+}
+
+function sha256Buffer(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function sha256File(filePath) {
+  const hash = crypto.createHash("sha256");
+  const descriptor = fs.openSync(filePath, "r");
+  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  try {
+    let offset = 0;
+    while (true) {
+      const read = fs.readSync(descriptor, buffer, 0, buffer.length, offset);
+      if (read === 0) break;
+      hash.update(buffer.subarray(0, read));
+      offset += read;
+    }
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  return hash.digest("hex");
+}
+
+function splitNul(buffer, label) {
+  if (buffer.length === 0) return [];
+  if (buffer.at(-1) !== 0) throw new Error(`${label} returned a malformed NUL-delimited path list`);
+  const paths = [];
+  let start = 0;
+  for (let index = 0; index < buffer.length; index += 1) {
+    if (buffer[index] !== 0) continue;
+    if (index > start) {
+      try { paths.push(utf8.decode(buffer.subarray(start, index))); }
+      catch { throw new Error(`${label} returned a path that is not valid UTF-8`); }
+    }
+    start = index + 1;
+  }
+  return paths;
+}
+
+function safeRelative(relative) {
+  const normalized = String(relative).replaceAll("\\", "/");
+  if (
+    !normalized || normalized.startsWith("/") || /^[A-Za-z]:\//u.test(normalized)
+    || normalized.split("/").some((segment) => !segment || segment === "." || segment === "..")
+    || normalized === ".git" || normalized.startsWith(".git/")
+    || normalized.includes("\0")
+  ) throw new Error(`unsafe workspace path ${JSON.stringify(relative)}`);
+  return normalized;
+}
+
+function effectiveGitConfig(root) {
+  const value = (key, fallback) => {
+    const result = git(root, ["config", "--get", key], { allowFailure: true });
+    return result.status === 0 ? result.stdout.trim().toLowerCase() : fallback;
+  };
+  const coreAutocrlf = value("core.autocrlf", "false");
+  const configuredEol = value("core.eol", "native");
+  const coreEol = configuredEol === "native" ? (process.platform === "win32" ? "crlf" : "lf") : configuredEol;
+  const coreFileMode = value("core.filemode", "false");
+  if (!new Set(["true", "false", "input"]).has(coreAutocrlf)
+    || !new Set(["native", "lf", "crlf"]).has(coreEol)
+    || !new Set(["true", "false"]).has(coreFileMode)) {
+    throw new Error("workspace snapshot has unsupported Git worktree settings");
+  }
+  return { coreAutocrlf, coreEol, coreFileMode: coreFileMode === "true" };
+}
+
+function applyGitConfig(root, config) {
+  if (!config || !new Set(["true", "false", "input"]).has(config.coreAutocrlf)
+    || !new Set(["native", "lf", "crlf"]).has(config.coreEol)
+    || typeof config.coreFileMode !== "boolean"
+    || Object.keys(config).some((key) => !new Set(["coreAutocrlf", "coreEol", "coreFileMode"]).has(key))) {
+    throw new Error("workspace manifest has invalid Git worktree settings");
+  }
+  git(root, ["config", "--local", "core.autocrlf", config.coreAutocrlf]);
+  git(root, ["config", "--local", "core.eol", config.coreEol]);
+  git(root, ["config", "--local", "core.filemode", String(config.coreFileMode)]);
+}
+
+function safeOrigin(value) {
+  const origin = String(value || "").trim();
+  if (!origin) return null;
+  if (/\s|[?&](?:access_token|token|key|signature)=/iu.test(origin)) return null;
+  if (/^[^/@:]+@[^:]+:/u.test(origin)) return origin.startsWith("git@") ? origin : null;
+  try {
+    const url = new URL(origin);
+    if (url.username || url.password || url.search || url.hash) return null;
+    if (!new Set(["https:", "ssh:", "git:"]).has(url.protocol)) return null;
+    return origin;
+  } catch {
+    return null;
+  }
+}
+
+function assertRepositorySupported(root, allPaths) {
+  if (gitBuffer(root, ["ls-files", "--unmerged", "-z"]).length > 0) {
+    throw new Error("workspace snapshot does not support unresolved merge index stages");
+  }
+  const submodules = gitBuffer(root, ["ls-files", "--stage", "-z"])
+    .toString("utf8").split("\0").filter((line) => line.startsWith("160000 "));
+  if (submodules.length > 0) {
+    throw new Error("workspace snapshot does not support submodules without explicit nested manifests");
+  }
+  const lfs = git(root, ["lfs", "ls-files", "--name-only"], { allowFailure: true });
+  if (lfs.status === 0 && lfs.stdout.trim()) {
+    throw new Error("workspace snapshot does not support Git LFS objects");
+  }
+  if (allPaths.length > 0) {
+    const attributeInput = Buffer.from(`${allPaths.join("\0")}\0`, "utf8");
+    const attributes = splitNul(gitBuffer(root, ["check-attr", "-z", "--stdin", "filter"], {
+      input: attributeInput,
+    }), "git check-attr");
+    for (let index = 0; index + 2 < attributes.length; index += 3) {
+      if (attributes[index + 1] === "filter" && attributes[index + 2] === "lfs") {
+        throw new Error(`workspace snapshot does not support Git LFS path ${JSON.stringify(attributes[index])}`);
+      }
+    }
+  }
+  const folded = new Map();
+  for (const relative of allPaths) {
+    const safe = safeRelative(relative);
+    const key = safe.normalize("NFC").toLocaleLowerCase("en-US");
+    const previous = folded.get(key);
+    if (previous && previous !== safe) {
+      throw new Error(`workspace snapshot has a destination case collision between ${JSON.stringify(previous)} and ${JSON.stringify(safe)}`);
+    }
+    folded.set(key, safe);
+  }
+}
+
+function inspectFiles(root, relatives) {
+  let totalBytes = 0;
+  const files = [];
+  if (relatives.length > MAX_FILES) throw new Error(`workspace snapshot exceeds ${MAX_FILES} files`);
+  for (const relative of relatives) {
+    const safe = safeRelative(relative);
+    const absolute = path.join(root, ...safe.split("/"));
+    const stat = fs.lstatSync(absolute, { throwIfNoEntry: false });
+    if (!stat) continue;
+    if (stat.isSymbolicLink()) throw new Error(`workspace snapshot refuses symbolic link ${JSON.stringify(safe)}`);
+    if (!stat.isFile()) throw new Error(`workspace snapshot refuses special file ${JSON.stringify(safe)}`);
+    if (stat.nlink !== 1) throw new Error(`workspace snapshot refuses hard-linked file ${JSON.stringify(safe)}`);
+    if (stat.size > MAX_FILE_BYTES) throw new Error(`workspace file ${JSON.stringify(safe)} exceeds ${MAX_FILE_BYTES} bytes`);
+    totalBytes += stat.size;
+    if (totalBytes > MAX_TOTAL_BYTES) throw new Error(`workspace snapshot exceeds ${MAX_TOTAL_BYTES} bytes`);
+    files.push({
+      path: safe,
+      mode: stat.mode & 0o111 ? "100755" : "100644",
+      length: stat.size,
+      sha256: sha256File(absolute),
+    });
+  }
+  return files;
+}
+
+function tarPathFields(relative) {
+  const value = Buffer.from(safeRelative(relative), "utf8");
+  if (value.length <= 100) return { name: value, prefix: Buffer.alloc(0) };
+  const parts = safeRelative(relative).split("/");
+  for (let index = parts.length - 1; index > 0; index -= 1) {
+    const prefix = Buffer.from(parts.slice(0, index).join("/"), "utf8");
+    const name = Buffer.from(parts.slice(index).join("/"), "utf8");
+    if (prefix.length <= 155 && name.length <= 100) return { name, prefix };
+  }
+  throw new Error(`workspace archive path is too long: ${JSON.stringify(relative)}`);
+}
+
+function writeField(header, offset, length, value) {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(String(value), "utf8");
+  if (bytes.length > length) throw new Error("tar header field overflow");
+  bytes.copy(header, offset);
+}
+
+function writeOctal(header, offset, length, value) {
+  const encoded = Math.max(0, value).toString(8).padStart(length - 1, "0");
+  writeField(header, offset, length, `${encoded}\0`);
+}
+
+function tarHeader(relative, size, mode) {
+  const header = Buffer.alloc(512);
+  const fields = tarPathFields(relative);
+  writeField(header, 0, 100, fields.name);
+  writeOctal(header, 100, 8, mode & 0o777);
+  writeOctal(header, 108, 8, 0);
+  writeOctal(header, 116, 8, 0);
+  writeOctal(header, 124, 12, size);
+  writeOctal(header, 136, 12, 0);
+  header.fill(0x20, 148, 156);
+  writeField(header, 156, 1, "0");
+  writeField(header, 257, 6, "ustar\0");
+  writeField(header, 263, 2, "00");
+  writeField(header, 345, 155, fields.prefix);
+  const checksum = header.reduce((sum, byte) => sum + byte, 0);
+  writeField(header, 148, 8, `${checksum.toString(8).padStart(6, "0")}\0 `);
+  return header;
+}
+
+function createTar(target, entries) {
+  const descriptor = fs.openSync(target, "w", 0o600);
+  const padding = Buffer.alloc(512);
+  try {
+    for (const entry of entries) {
+      const stat = fs.statSync(entry.source);
+      fs.writeSync(descriptor, tarHeader(entry.path, stat.size, entry.mode ?? stat.mode));
+      const input = fs.openSync(entry.source, "r");
+      try {
+        const buffer = Buffer.allocUnsafe(1024 * 1024);
+        let position = 0;
+        while (position < stat.size) {
+          const read = fs.readSync(input, buffer, 0, Math.min(buffer.length, stat.size - position), position);
+          if (read === 0) throw new Error(`workspace file changed during archive: ${entry.path}`);
+          fs.writeSync(descriptor, buffer, 0, read);
+          position += read;
+        }
+      } finally { fs.closeSync(input); }
+      const remainder = stat.size % 512;
+      if (remainder) fs.writeSync(descriptor, padding, 0, 512 - remainder);
+    }
+    fs.writeSync(descriptor, Buffer.alloc(1024));
+  } finally { fs.closeSync(descriptor); }
+}
+
+function writePrivate(target, contents) {
+  fs.writeFileSync(target, contents, { mode: 0o600 });
+  try { fs.chmodSync(target, 0o600); } catch { /* Best effort on Windows. */ }
+}
+
+function part(filePath) {
+  const stat = fs.statSync(filePath);
+  return { length: stat.size, sha256: sha256File(filePath) };
+}
+
+function snapshotFingerprint(root, allPaths) {
+  return inspectFiles(root, allPaths)
+    .map((file) => `${file.path}\0${file.mode}\0${file.length}\0${file.sha256}`)
+    .join("\n");
+}
+
+function indexMatchedFiles(root, tracked, presentPaths, intent) {
+  const changed = new Set(splitNul(gitBuffer(root, ["diff", "--name-only", "--no-ext-diff", "-z"]), "git diff"));
+  const present = new Set(presentPaths);
+  const intentSet = new Set(intent);
+  return tracked.filter((relative) => present.has(relative) && !changed.has(relative) && !intentSet.has(relative));
+}
+
+function refreshIndexStat(root, paths) {
+  if (paths.length === 0) return;
+  const before = gitBuffer(root, ["ls-files", "--stage", "-z"]);
+  for (let offset = 0; offset < paths.length; offset += 64) {
+    git(root, ["--literal-pathspecs", "add", "--", ...paths.slice(offset, offset + 64)]);
+  }
+  const after = gitBuffer(root, ["ls-files", "--stage", "-z"]);
+  if (!before.equals(after)) throw new Error("workspace index changed while refreshing restored file metadata");
+}
+
+export function createWorkspaceArtifact(repository, artifactRoot) {
+  fs.mkdirSync(artifactRoot, { recursive: true, mode: 0o700 });
+  const names = {
+    bundle: "repository.bundle",
+    staged: "staged.patch",
+    working: "working.patch",
+    untracked: "untracked.tar",
+    untrackedPaths: "untracked.paths",
+    intent: "intent-to-add.paths",
+    manifest: "manifest.json",
+    artifact: "workspace.tar",
+  };
+  const files = Object.fromEntries(Object.entries(names).map(([key, name]) => [key, path.join(artifactRoot, name)]));
+  const tracked = splitNul(gitBuffer(repository.root, ["ls-files", "--cached", "-z"]), "git ls-files");
+  const untracked = splitNul(gitBuffer(repository.root, ["ls-files", "--others", "--exclude-standard", "-z"]), "git ls-files");
+  const allPaths = [...new Set([...tracked, ...untracked])].sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+  assertRepositorySupported(repository.root, allPaths);
+  const statusBefore = gitBuffer(repository.root, ["status", "--porcelain=v2", "-z", "--untracked-files=all"]);
+  const fingerprintBefore = snapshotFingerprint(repository.root, allPaths);
+  const intent = splitNul(gitBuffer(repository.root, ["diff", "--name-only", "--diff-filter=A", "-z"]), "git diff")
+    .filter((relative) => tracked.includes(relative));
+  const indexMatchedBefore = indexMatchedFiles(repository.root, tracked, allPaths, intent);
+
+  const bundleRef = repository.branch ? `refs/heads/${repository.branch}` : "HEAD";
+  git(repository.root, ["bundle", "create", files.bundle, bundleRef]);
+  writePrivate(files.staged, gitBuffer(repository.root, ["diff", "--cached", "--binary", "--full-index", "--no-ext-diff"]));
+  writePrivate(files.working, gitBuffer(repository.root, ["diff", "--binary", "--full-index", "--no-ext-diff"]));
+  writePrivate(files.untrackedPaths, untracked.length ? Buffer.from(`${untracked.join("\0")}\0`, "utf8") : Buffer.alloc(0));
+  writePrivate(files.intent, intent.length ? Buffer.from(`${intent.join("\0")}\0`, "utf8") : Buffer.alloc(0));
+  const fileMetadata = inspectFiles(repository.root, allPaths);
+  const metadataByPath = new Map(fileMetadata.map((entry) => [entry.path, entry]));
+  const untrackedMetadata = untracked.map((relative) => metadataByPath.get(relative)).filter(Boolean);
+  createTar(files.untracked, fileMetadata.map((entry) => ({
+    source: path.join(repository.root, ...entry.path.split("/")),
+    path: entry.path,
+    mode: entry.mode === "100755" ? 0o755 : 0o644,
+  })));
+
+  const statusAfter = gitBuffer(repository.root, ["status", "--porcelain=v2", "-z", "--untracked-files=all"]);
+  const fingerprintAfter = snapshotFingerprint(repository.root, allPaths);
+  const indexMatchedAfter = indexMatchedFiles(repository.root, tracked, fileMetadata.map((entry) => entry.path), intent);
+  if (!statusBefore.equals(statusAfter) || fingerprintBefore !== fingerprintAfter
+    || JSON.stringify(indexMatchedBefore) !== JSON.stringify(indexMatchedAfter)) {
+    throw new Error("repository changed while the workspace snapshot was being captured; retry");
+  }
+
+  const manifestCore = {
+    schemaVersion: WORKSPACE_SCHEMA_VERSION,
+    contentType: WORKSPACE_CONTENT_TYPE,
+    repository: {
+      origin: safeOrigin(repository.origin),
+      head: repository.head,
+      branch: repository.branch,
+      detached: !repository.branch,
+      subdirectory: repository.relativeProjectPath,
+      gitVersion: git(repository.root, ["--version"]).stdout.trim(),
+      workingTreeConfig: effectiveGitConfig(repository.root),
+    },
+    sourceStatus: statusAfter.toString("base64"),
+    files: fileMetadata,
+    untrackedFiles: untrackedMetadata,
+    indexMatchedFiles: indexMatchedAfter,
+    intentToAdd: intent,
+    parts: {
+      bundle: { name: names.bundle, ...part(files.bundle) },
+      stagedPatch: { name: names.staged, ...part(files.staged) },
+      workingPatch: { name: names.working, ...part(files.working) },
+      untrackedArchive: { name: names.untracked, ...part(files.untracked) },
+      untrackedPaths: { name: names.untrackedPaths, ...part(files.untrackedPaths) },
+      intentToAddPaths: { name: names.intent, ...part(files.intent) },
+    },
+    closedAt: new Date().toISOString(),
+  };
+  const rootManifestHash = sha256Buffer(Buffer.from(JSON.stringify(manifestCore), "utf8"));
+  const manifest = { ...manifestCore, rootManifestHash };
+  writePrivate(files.manifest, `${JSON.stringify(manifest, null, 2)}\n`);
+  createTar(files.artifact, [
+    { source: files.manifest, path: names.manifest, mode: 0o600 },
+    ...Object.values(manifest.parts).map((entry) => ({
+      source: path.join(artifactRoot, entry.name), path: entry.name, mode: 0o600,
+    })),
+  ]);
+  const artifactStat = fs.statSync(files.artifact);
+  return {
+    path: files.artifact,
+    length: artifactStat.size,
+    sha256: sha256File(files.artifact),
+    manifestHash: rootManifestHash,
+    manifest,
+    files,
+  };
+}
+
+function parseOctal(buffer) {
+  const text = buffer.toString("ascii").replace(/\0.*$/u, "").trim();
+  return text ? Number.parseInt(text, 8) : 0;
+}
+
+function restoreTar(archive, destination, expectedFiles) {
+  const descriptor = fs.openSync(archive, "r");
+  let offset = 0;
+  const restored = [];
+  const archiveLength = fs.fstatSync(descriptor).size;
+  try {
+    while (true) {
+      const header = Buffer.alloc(512);
+      if (fs.readSync(descriptor, header, 0, 512, offset) !== 512) throw new Error("truncated workspace tar header");
+      offset += 512;
+      if (header.every((byte) => byte === 0)) {
+        const trailing = Buffer.alloc(archiveLength - offset);
+        if (trailing.length && fs.readSync(descriptor, trailing, 0, trailing.length, offset) !== trailing.length) {
+          throw new Error("truncated workspace tar trailer");
+        }
+        if (trailing.some((byte) => byte !== 0)) throw new Error("workspace tar contains data after its trailer");
+        break;
+      }
+      const checksumHeader = Buffer.from(header);
+      checksumHeader.fill(0x20, 148, 156);
+      const expectedChecksum = checksumHeader.reduce((sum, byte) => sum + byte, 0);
+      if (parseOctal(header.subarray(148, 156)) !== expectedChecksum) throw new Error("workspace tar header checksum mismatch");
+      let name;
+      let prefix;
+      try {
+        name = utf8.decode(header.subarray(0, 100)).replace(/\0.*$/u, "");
+        prefix = utf8.decode(header.subarray(345, 500)).replace(/\0.*$/u, "");
+      } catch {
+        throw new Error("workspace tar contains a path that is not valid UTF-8");
+      }
+      const relative = safeRelative(prefix ? `${prefix}/${name}` : name);
+      if (header[156] !== 0 && header[156] !== 0x30) throw new Error(`workspace tar contains unsupported entry ${relative}`);
+      const expected = expectedFiles[restored.length];
+      if (!expected || expected.path !== relative) throw new Error(`workspace tar contains unexpected entry ${relative}`);
+      const size = parseOctal(header.subarray(124, 136));
+      const mode = parseOctal(header.subarray(100, 108));
+      const expectedMode = expected.mode === "100755" ? 0o755 : 0o644;
+      if (!Number.isSafeInteger(size) || size < 0 || size !== expected.length || (mode & 0o777) !== expectedMode) {
+        throw new Error(`workspace tar metadata does not match the manifest for ${relative}`);
+      }
+      const target = path.resolve(destination, ...relative.split("/"));
+      const root = path.resolve(destination);
+      if (!target.startsWith(`${root}${path.sep}`)) throw new Error("workspace tar path escaped destination");
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      const prior = fs.lstatSync(target, { throwIfNoEntry: false });
+      if (prior && (!prior.isFile() || prior.isSymbolicLink() || prior.nlink !== 1)) {
+        throw new Error(`workspace tar refuses to replace unsafe file ${relative}`);
+      }
+      const output = fs.openSync(target, prior ? "w" : "wx", expectedMode);
+      try {
+        const opened = fs.fstatSync(output);
+        if (!opened.isFile() || opened.nlink !== 1) throw new Error(`workspace tar opened unsafe file ${relative}`);
+        const buffer = Buffer.allocUnsafe(1024 * 1024);
+        const hash = crypto.createHash("sha256");
+        let copied = 0;
+        while (copied < size) {
+          const read = fs.readSync(descriptor, buffer, 0, Math.min(buffer.length, size - copied), offset + copied);
+          if (read === 0) throw new Error("truncated workspace tar entry");
+          fs.writeSync(output, buffer, 0, read);
+          hash.update(buffer.subarray(0, read));
+          copied += read;
+        }
+        if (hash.digest("hex") !== expected.sha256) throw new Error(`workspace tar hash does not match the manifest for ${relative}`);
+        try { fs.fchmodSync(output, expectedMode); } catch {
+          if (process.platform !== "win32") throw new Error(`workspace tar could not restore the mode for ${relative}`);
+        }
+      } finally { fs.closeSync(output); }
+      offset += Math.ceil(size / 512) * 512;
+      restored.push(relative);
+    }
+  } finally { fs.closeSync(descriptor); }
+  if (restored.length !== expectedFiles.length) throw new Error("workspace tar is missing manifest files");
+  return restored;
+}
+
+export function restoreWorkspaceArtifact(snapshot, destination) {
+  const manifest = snapshot.manifest;
+  if (!manifest?.closedAt || manifest.schemaVersion !== WORKSPACE_SCHEMA_VERSION) throw new Error("workspace manifest is not closed");
+  const { rootManifestHash, ...core } = manifest;
+  if (sha256Buffer(Buffer.from(JSON.stringify(core), "utf8")) !== rootManifestHash) {
+    throw new Error("workspace root manifest hash mismatch");
+  }
+  for (const entry of Object.values(manifest.parts)) {
+    const filePath = path.join(path.dirname(snapshot.path), entry.name);
+    if (fs.statSync(filePath).size !== entry.length || sha256File(filePath) !== entry.sha256) {
+      throw new Error(`workspace part failed verification: ${entry.name}`);
+    }
+  }
+  runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", ["clone", "--no-checkout", snapshot.files.bundle, destination]);
+  applyGitConfig(destination, manifest.repository.workingTreeConfig);
+  git(destination, ["checkout", "--detach", manifest.repository.head]);
+  if (manifest.repository.branch) git(destination, ["checkout", "-B", manifest.repository.branch, manifest.repository.head]);
+  if (manifest.repository.origin) git(destination, ["remote", "set-url", "origin", manifest.repository.origin]);
+  if (manifest.parts.stagedPatch.length > 0) git(destination, ["apply", "--index", "--binary", snapshot.files.staged]);
+  if (manifest.parts.workingPatch.length > 0) git(destination, ["apply", "--binary", snapshot.files.working]);
+  restoreTar(snapshot.files.untracked, destination, manifest.files);
+  for (const relative of manifest.intentToAdd) git(destination, ["add", "-N", "--", relative]);
+  refreshIndexStat(destination, manifest.indexMatchedFiles);
+  const restoredStatus = gitBuffer(destination, ["status", "--porcelain=v2", "-z", "--untracked-files=all"]);
+  if (restoredStatus.toString("base64") !== manifest.sourceStatus) {
+    throw new Error("restored workspace Git status does not match the source snapshot");
+  }
+  const restoredFiles = inspectFiles(destination, manifest.files.map((entry) => entry.path));
+  if (JSON.stringify(restoredFiles) !== JSON.stringify(manifest.files)) {
+    throw new Error("restored workspace file hashes do not match the source snapshot");
+  }
+  return { destination, manifest };
+}

package/src/selfInvocation.js

@@ -98,20 +98,24 @@ export function impelNativeAgentMcpInvocation({
   agentId,
   scopeParam,
   policyFingerprint,
-  recoveryOnly = false,
+  mode = "durable",
 }, options = {}) {
   for (const [field, value] of Object.entries({ tenantId, agentId, scopeParam, policyFingerprint })) {
     if (typeof value !== "string" || !value.trim()) {
       throw new Error(`${field} is required for the managed native-agent MCP invocation`);
     }
   }
+  if (!new Set(["durable", "recovery", "answer"]).has(mode)) {
+    throw new Error("native-agent MCP mode must be durable, recovery, or answer");
+  }
   return impelMcpInvocation([
     "--target", IMPEL_NATIVE_AGENT_MCP_TARGET,
     "--tenant", tenantId,
     "--agent-id", agentId,
     "--scope-param", scopeParam,
     "--policy-fingerprint", policyFingerprint,
-    ...(recoveryOnly ? ["--recovery-only"] : []),
+    ...(mode === "recovery" ? ["--recovery-only"] : []),
+    ...(mode === "answer" ? ["--answer-only"] : []),
   ], options);
 }
 

package/src/verbatimRelay.js

@@ -0,0 +1,64 @@
+export const VERBATIM_RELAY_OPT_IN_MARKER = "verbatimRelay enabled";
+
+export const VERBATIM_SPAWN_REQUIREMENT = 'fork_turns="none"';
+
+export const VERBATIM_FINAL_TEXT_CONSTRAINTS =
+  "no preface, rewriting, Markdown changes, or independent synthesis";
+
+export function usesVerbatimRelay(agent) {
+  return agent?.verbatimRelay === true;
+}
+
+export function parentVerbatimRelayAppendix() {
+  return (
+    `When an explicit custom agent's catalog-derived description declares ${VERBATIM_RELAY_OPT_IN_MARKER}, ` +
+    `spawn it with ${VERBATIM_SPAWN_REQUIREMENT} and relay its finalText verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}; ` +
+    "preserve Sources sections and citations exactly. " +
+    "Custom agents without that declaration keep the default delegation behavior."
+  );
+}
+
+export function customAgentVerbatimDescriptionLead() {
+  return (
+    `Explicit custom agent with ${VERBATIM_RELAY_OPT_IN_MARKER}: ` +
+    `callers must use ${VERBATIM_SPAWN_REQUIREMENT} and relay its result verbatim`
+  );
+}
+
+export function adapterCallerSpawnGuidance(clientLabel) {
+  return (
+    `Callers must spawn this explicit custom ${clientLabel} agent with ${VERBATIM_SPAWN_REQUIREMENT} ` +
+    "and must relay your result verbatim; this is caller guidance and cannot enforce host spawn behavior."
+  );
+}
+
+export function adapterVerbatimCompletionGuidance() {
+  return (
+    `Return successful finalText verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
+    "A failure preserves the durable runId, output, and error."
+  );
+}
+
+export function adapterFaithfulCompletionGuidance() {
+  return (
+    "Return successful finalText faithfully as the answer. " +
+    "A failure preserves the durable runId, output, and error. " +
+    "Never invent or independently synthesize a replacement result."
+  );
+}
+
+export function claudeVerbatimCompletionGuidance() {
+  return (
+    `When it succeeds, return finalText verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
+    "When it fails, return the preserved runId, output, and error. " +
+    "Never invent or independently synthesize a replacement result."
+  );
+}
+
+export function claudeFaithfulCompletionGuidance() {
+  return (
+    "When it succeeds, return finalText faithfully as the answer. " +
+    "When it fails, return the preserved runId, output, and error. " +
+    "Never invent or independently synthesize a replacement result."
+  );
+}