@runuai/host 0.9.150 → 0.9.152

package/lib/task-environment/workspace-files.ts

@@ -1,51 +1,676 @@
 /**
  * ADR-121 strangler ops: the host-filesystem implementation of the
  * workspace file operations, shared by every provider whose workspace
- * physically lives on the host (docker, apple-container). Behavior is
- * byte-identical to the direct fs access call sites used to perform — the
- * point of the strangler's first phase is that call sites stop KNOWING the
- * workspace is host-side, not that anything moves yet.
+ * physically lives on the host (docker, apple-container), by the self
+ * provider's reads, and by every runner-side writer of a task's `.uai`
+ * (transcript, skills, durable sessions, attachments, the agent CLI).
+ *
+ * A task controls its workspace, links and special files included, and on
+ * an owned runner that workspace sits on the owner's own disk. So nothing
+ * here follows a link anywhere below the workspace's root, or reads, writes
+ * or appends to anything but a regular file: whatever the task arranges, no
+ * read returns, and no write touches, anything outside its workspace
+ * (#cb3j0z).
+ * - Linux opens each path one component at a time, relative to the directory
+ *   already opened (through /proc/self/fd, the openat Node lacks), and makes,
+ *   removes and links entries the same way.
+ * - macOS opens with O_NOFOLLOW_ANY. It has no way to make, remove or link an
+ *   entry relative to a directory it opened, so those go through the task's
+ *   own runtime (`RuntimeNamespace`), where a link resolves inside the
+ *   runtime; without one they are refused. Only a directory directly below
+ *   the root is made by name: nothing above it is the task's.
+ * - A host that offers neither reads only what it verifies after opening,
+ *   and writes nothing.
  */
 
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import {
+  closeSync,
+  constants,
+  fchmodSync,
+  fstatSync,
+  ftruncateSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  read,
+  readSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, sep } from "node:path";
+import { promisify } from "node:util";
 
 import {
   assertWorkspaceScopedPath,
+  WORKSPACE_READ_MAX_BYTES,
+  WORKSPACE_READ_TIMEOUT_MS,
   type TaskEnvironmentDescriptor,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentReadOptions,
 } from "./types";
 
-/** Map an environment-absolute workspace path to its host location. */
-function hostPathFor(
-  descriptor: TaskEnvironmentDescriptor,
-  hostWorkspaceRoot: string,
-  path: string,
-): string {
-  assertWorkspaceScopedPath(descriptor, path);
-  const relative = path.slice(descriptor.workspacePath.length);
-  return join(hostWorkspaceRoot, ...relative.split("/").filter(Boolean));
+const readAt = promisify(read);
+
+/** A workspace path that is not a regular file: never read, written or
+ *  appended to, never waited on. */
+export class NotARegularFileError extends Error {
+  constructor() {
+    super("a workspace path that is not a regular file is never read or written");
+    this.name = "NotARegularFileError";
+  }
 }
 
-export function hostWorkspaceRead(
-  descriptor: TaskEnvironmentDescriptor,
-  hostWorkspaceRoot: string,
-  path: string,
-): Uint8Array | null {
+/** A workspace path through a link, or through something that is not a
+ *  directory: never followed. */
+export class WorkspacePathRefusedError extends Error {
+  constructor(message = "a workspace path through a link is never followed") {
+    super(message);
+    this.name = "WorkspacePathRefusedError";
+  }
+}
+
+/** A write below a workspace directory that does not exist: refused,
+ *  nothing made (a caller makes directories explicitly). */
+export class WorkspaceDirectoryMissingError extends WorkspacePathRefusedError {
+  constructor() {
+    super("a missing workspace directory is never made by a write");
+    this.name = "WorkspaceDirectoryMissingError";
+  }
+}
+
+/**
+ * What a runner-side writer may run in the task's own runtime, where a link
+ * resolves inside the runtime: making directories, removing an entry,
+ * replacing a link. Paths are the runtime's (below its workspace path).
+ */
+export interface RuntimeNamespace {
+  readonly workspacePath: string;
+  makeDirectories(path: string): Promise<void>;
+  remove(path: string): Promise<void>;
+  replaceLink(target: string, path: string): Promise<void>;
+}
+
+/** macOS (11 and later): fail if any component of the path is a link. */
+const O_NOFOLLOW_ANY = 0x20000000;
+const DIRECTORY = constants.O_RDONLY | constants.O_DIRECTORY;
+/** macOS: a directory, a link nowhere in its path, the last component
+ *  included. Never with O_NOFOLLOW: O_NOFOLLOW_ANY already refuses a final
+ *  link, and macOS 27 rejects the two together with EINVAL (live
+ *  2026-10-11: every workspace read and write failed on the Studio). */
+const DARWIN = process.platform === "darwin";
+/** Elsewhere (tests forcing this mode on Linux, where O_NOFOLLOW_ANY means
+ *  nothing) O_NOFOLLOW stays, so a final link is still refused there. */
+const DIRECTORY_NOFOLLOW_ANY = DIRECTORY | O_NOFOLLOW_ANY | (DARWIN ? 0 : constants.O_NOFOLLOW);
+/** The flags one file is opened with in this mode: on macOS `flags` without
+ *  O_NOFOLLOW, which O_NOFOLLOW_ANY covers and cannot be combined with. */
+function nofollowAnyFlags(flags: number): number {
+  return (DARWIN ? flags & ~constants.O_NOFOLLOW : flags) | O_NOFOLLOW_ANY;
+}
+
+type Containment = "proc-fd" | "nofollow-any" | "verify";
+let containment: Containment | null = null;
+
+/** How this host opens a path below a root without following a link
+ *  anywhere below it. Asked of the host once, by trying it. */
+function containmentMode(): Containment {
+  containment ??= probeContainment();
+  return containment;
+}
+
+function probeContainment(): Containment {
+  if (process.platform === "linux") {
+    let directory: number | null = null;
+    try {
+      directory = openSync(tmpdir(), DIRECTORY);
+      closeSync(openSync(`/proc/self/fd/${directory}/.`, DIRECTORY));
+      return "proc-fd";
+    } catch {
+      return "verify";
+    } finally {
+      if (directory !== null) closeSync(directory);
+    }
+  }
+  if (process.platform === "darwin") {
+    // Resolved: macOS's temporary directory is below /var, itself a link,
+    // which O_NOFOLLOW_ANY refuses on every path through it.
+    const scratch = realpathSync(mkdtempSync(join(tmpdir(), "uai-nofollow-any-")));
+    try {
+      mkdirSync(join(scratch, "real"));
+      writeFileSync(join(scratch, "real", "file"), "");
+      symlinkSync(join(scratch, "real"), join(scratch, "link"));
+      try {
+        closeSync(openSync(join(scratch, "link", "file"), constants.O_RDONLY | O_NOFOLLOW_ANY));
+        // Opened through the link: the flag is not honored here.
+        return "verify";
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ELOOP") return "verify";
+      }
+      // The exact flags the real opens use must work on a plain file and
+      // directory too: a flag the kernel refuses in combination would
+      // otherwise fail every workspace operation, not just links.
+      try {
+        closeSync(
+          openSync(
+            join(scratch, "real", "file"),
+            nofollowAnyFlags(constants.O_WRONLY | constants.O_APPEND | constants.O_NONBLOCK | constants.O_NOFOLLOW),
+          ),
+        );
+        closeSync(openSync(join(scratch, "real"), DIRECTORY_NOFOLLOW_ANY));
+      } catch {
+        return "verify";
+      }
+      return "nofollow-any";
+    } finally {
+      rmSync(scratch, { recursive: true, force: true });
+    }
+  }
+  return "verify";
+}
+
+/** Tests only: probe the host again, or pretend it offers `mode`. */
+export function setWorkspaceContainmentForTests(mode: Containment | null): void {
+  containment = mode;
+}
+
+function checkedParts(parts: readonly string[]): void {
+  if (
+    parts.length === 0 ||
+    parts.some((part) => part === "" || part === "." || part === ".." || part.includes("/") || part.includes("\0"))
+  ) {
+    throw new WorkspacePathRefusedError("a malformed workspace path");
+  }
+}
+
+function refusal(error: unknown): unknown {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "ELOOP" || code === "ENOTDIR" || code === "EMLINK" ? new WorkspacePathRefusedError() : error;
+}
+
+/** The root, resolved (it is the runner's own path); null when absent. */
+function resolvedRoot(root: string): string | null {
   try {
-    return readFileSync(hostPathFor(descriptor, hostWorkspaceRoot, path));
+    return realpathSync(root);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
     throw error;
   }
 }
 
+/**
+ * macOS: a directory directly below the resolved root, made by name. Nothing
+ * above it is the task's, and mkdir never follows a link in its own place;
+ * what is there is then opened without following one.
+ */
+function makeTopDirectory(base: string, name: string): void {
+  try {
+    mkdirSync(join(base, name));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  closeSync(openSync(join(base, name), DIRECTORY_NOFOLLOW_ANY));
+}
+
+/**
+ * Linux: the directory `parts` names below `base`, opened one component at
+ * a time, each relative to the one before, none a link. With `make`, a
+ * missing component is made in the directory already opened. Null when one
+ * is missing and not made.
+ */
+function walkDirectory(base: string, parts: readonly string[], make: boolean): number | null {
+  let directory = openSync(base, DIRECTORY);
+  try {
+    for (const part of parts) {
+      const at = `/proc/self/fd/${directory}/${part}`;
+      let next: number;
+      try {
+        next = openSync(at, DIRECTORY | constants.O_NOFOLLOW);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+        if (!make) return null;
+        try {
+          mkdirSync(at);
+        } catch (made) {
+          if ((made as NodeJS.ErrnoException).code !== "EEXIST") throw made;
+        }
+        next = openSync(at, DIRECTORY | constants.O_NOFOLLOW);
+      }
+      closeSync(directory);
+      directory = next;
+    }
+    const opened = directory;
+    directory = -1;
+    return opened;
+  } finally {
+    if (directory >= 0) closeSync(directory);
+  }
+}
+
+/**
+ * Open `parts` below `root` with `flags`, without following a link anywhere
+ * below it (O_NOFOLLOW and O_NONBLOCK are always added). Null when it does
+ * not exist and `flags` creates nothing, the root included. Never makes a
+ * directory.
+ */
+function openWithin(root: string, parts: readonly string[], flags: number): number | null {
+  checkedParts(parts);
+  const creates = (flags & constants.O_CREAT) !== 0;
+  const base = resolvedRoot(root);
+  if (base === null) {
+    if (creates) throw new WorkspacePathRefusedError("a workspace that does not exist is never written");
+    return null;
+  }
+  const finalFlags = flags | constants.O_NONBLOCK | constants.O_NOFOLLOW;
+  const mode = containmentMode();
+  try {
+    if (mode === "proc-fd") {
+      const directory = walkDirectory(base, parts.slice(0, -1), false);
+      if (directory === null) {
+        if (creates) throw new WorkspaceDirectoryMissingError();
+        return null;
+      }
+      try {
+        return openSync(`/proc/self/fd/${directory}/${parts[parts.length - 1]!}`, finalFlags, 0o644);
+      } finally {
+        closeSync(directory);
+      }
+    }
+    if (mode === "nofollow-any") {
+      return openSync(join(base, ...parts), nofollowAnyFlags(finalFlags), 0o644);
+    }
+    // Neither: a read verifies what it opened; nothing is written.
+    if ((flags & (constants.O_WRONLY | constants.O_RDWR | constants.O_CREAT)) !== 0) {
+      throw new WorkspacePathRefusedError("this host cannot write a task's workspace without following its links");
+    }
+    const path = join(base, ...parts);
+    const fd = openSync(path, finalFlags);
+    try {
+      const opened = fstatSync(fd);
+      const resolved = realpathSync(path);
+      const there = statSync(resolved);
+      if (!resolved.startsWith(base + sep) || there.dev !== opened.dev || there.ino !== opened.ino) {
+        throw new WorkspacePathRefusedError();
+      }
+      return fd;
+    } catch (error) {
+      closeSync(fd);
+      throw error;
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      if (creates) throw new WorkspaceDirectoryMissingError();
+      return null;
+    }
+    throw refusal(error);
+  }
+}
+
+/** Open a regular file below `root` (refused, and closed, if it is not
+ *  one); null when absent. */
+function openRegular(root: string, parts: readonly string[], flags: number): number | null {
+  const fd = openWithin(root, parts, flags);
+  if (fd === null) return null;
+  if (!fstatSync(fd).isFile()) {
+    closeSync(fd);
+    throw new NotARegularFileError();
+  }
+  return fd;
+}
+
+/**
+ * Read at most `maxBytes` of a regular file below `root` that a task
+ * controls, from its start or its end: opened non-blocking within `root`,
+ * refused unless the file it opened is a regular one, read off the event
+ * loop and given up past its bound. Null when it does not exist.
+ */
+export async function readBoundedFile(
+  root: string,
+  parts: readonly string[],
+  options: Pick<TaskEnvironmentReadOptions, "maxBytes" | "from"> & { timeoutMs?: number } = {},
+): Promise<Uint8Array | null> {
+  const maxBytes = Math.max(0, options.maxBytes ?? WORKSPACE_READ_MAX_BYTES);
+  const fd = openRegular(root, parts, constants.O_RDONLY);
+  if (fd === null) return null;
+  const reading = (async (): Promise<Uint8Array> => {
+    const size = fstatSync(fd).size;
+    const length = Math.min(size, maxBytes);
+    const position = options.from === "end" ? size - length : 0;
+    const buffer = Buffer.alloc(length);
+    let done = 0;
+    while (done < length) {
+      const { bytesRead } = await readAt(fd, buffer, done, length - done, position + done);
+      if (bytesRead === 0) break;
+      done += bytesRead;
+    }
+    return new Uint8Array(buffer.buffer, buffer.byteOffset, done);
+  })();
+  // Closed once the read has ended, however it ended.
+  void reading.then(
+    () => closeSync(fd),
+    () => closeSync(fd),
+  );
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const bound = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error("a workspace read did not finish in time")),
+      options.timeoutMs ?? WORKSPACE_READ_TIMEOUT_MS,
+    );
+  });
+  try {
+    return await Promise.race([reading, bound]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The bytes of a regular file below `root` from `offset`, at most
+ * `maxBytes`, and its size: for a reader that follows a file a task's
+ * runtime appends to. Null when it does not exist.
+ */
+export function readContainedFrom(
+  root: string,
+  parts: readonly string[],
+  offset: number,
+  maxBytes: number,
+): { bytes: Buffer; size: number } | null {
+  const fd = openRegular(root, parts, constants.O_RDONLY);
+  if (fd === null) return null;
+  try {
+    const size = fstatSync(fd).size;
+    const length = Math.max(0, Math.min(size - offset, maxBytes));
+    const bytes = Buffer.alloc(length);
+    let done = 0;
+    while (done < length) {
+      const bytesRead = readSync(fd, bytes, done, length - done, offset + done);
+      if (bytesRead <= 0) break;
+      done += bytesRead;
+    }
+    return { bytes: bytes.subarray(0, done), size };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** When a regular file below `root` was last modified; null when absent. */
+export function containedModifiedAt(root: string, parts: readonly string[]): number | null {
+  const fd = openRegular(root, parts, constants.O_RDONLY);
+  if (fd === null) return null;
+  try {
+    return fstatSync(fd).mtimeMs;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function writeAll(fd: number, bytes: Uint8Array, position: number | null): void {
+  let done = 0;
+  while (done < bytes.length) {
+    done += writeSync(fd, bytes, done, bytes.length - done, position === null ? null : position + done);
+  }
+}
+
+/**
+ * Write `bytes` as the whole of a regular file below `root`, made if
+ * missing in a directory that exists, never through a link: truncated and
+ * written only once the file opened is found to be a regular one, so a FIFO
+ * or device a task put in its place is never written.
+ */
+export function writeContainedFileSync(
+  root: string,
+  parts: readonly string[],
+  bytes: Uint8Array,
+  options: { mode?: number } = {},
+): void {
+  const fd = openRegular(root, parts, constants.O_WRONLY | constants.O_CREAT)!;
+  try {
+    ftruncateSync(fd, 0);
+    writeAll(fd, bytes, 0);
+    if (options.mode !== undefined) fchmodSync(fd, options.mode);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export async function writeContainedFile(
+  root: string,
+  parts: readonly string[],
+  bytes: Uint8Array,
+  options: { mode?: number } = {},
+): Promise<void> {
+  writeContainedFileSync(root, parts, bytes, options);
+}
+
+/** Append `bytes` to a regular file below `root`, made if missing in a
+ *  directory that exists, never through a link. */
+export function appendContainedFileSync(root: string, parts: readonly string[], bytes: Uint8Array): void {
+  const fd = openRegular(root, parts, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND)!;
+  try {
+    writeAll(fd, bytes, null);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export async function appendContainedFile(root: string, parts: readonly string[], bytes: Uint8Array): Promise<void> {
+  appendContainedFileSync(root, parts, bytes);
+}
+
+/**
+ * Make the directories `parts` names below `root` (each missing one), never
+ * through a link: on Linux relative to the directory already opened; on
+ * macOS one directly below the root by name, deeper ones through `runtime`,
+ * the task's own runtime, then checked from the host; refused without one.
+ * A link a task puts anywhere in the chain after is refused at the next open.
+ */
+export async function makeContainedDirectories(
+  root: string,
+  parts: readonly string[],
+  runtime?: RuntimeNamespace,
+): Promise<void> {
+  checkedParts(parts);
+  const base = resolvedRoot(root);
+  if (base === null) throw new WorkspacePathRefusedError("a workspace that does not exist is never written");
+  const mode = containmentMode();
+  try {
+    if (mode === "proc-fd") {
+      closeSync(walkDirectory(base, parts, true)!);
+      return;
+    }
+    if (mode === "nofollow-any") {
+      try {
+        closeSync(openSync(join(base, ...parts), DIRECTORY_NOFOLLOW_ANY));
+        return;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+      if (parts.length === 1) {
+        makeTopDirectory(base, parts[0]!);
+        return;
+      }
+      if (!runtime) throw new WorkspacePathRefusedError("a missing workspace directory is never made here");
+      await runtime.makeDirectories([runtime.workspacePath, ...parts].join("/"));
+      closeSync(openSync(join(base, ...parts), DIRECTORY_NOFOLLOW_ANY));
+      return;
+    }
+    throw new WorkspacePathRefusedError("this host cannot write a task's workspace without following its links");
+  } catch (error) {
+    throw refusal(error);
+  }
+}
+
+/** Make them synchronously (true): on Linux, and on macOS one directly
+ *  below the root; false where only the task's runtime can (deeper on
+ *  macOS) or nothing can. */
+export function makeContainedDirectoriesSync(root: string, parts: readonly string[]): boolean {
+  checkedParts(parts);
+  const base = resolvedRoot(root);
+  if (base === null) throw new WorkspacePathRefusedError("a workspace that does not exist is never written");
+  const mode = containmentMode();
+  try {
+    if (mode === "proc-fd") {
+      closeSync(walkDirectory(base, parts, true)!);
+      return true;
+    }
+    if (mode === "nofollow-any" && parts.length === 1) {
+      makeTopDirectory(base, parts[0]!);
+      return true;
+    }
+  } catch (error) {
+    throw refusal(error);
+  }
+  return false;
+}
+
+/** The task's runtime as a `RuntimeNamespace`: each operation an exec there,
+ *  as the task user, where a link resolves inside the runtime. */
+export function runtimeNamespaceOf(
+  environment: Pick<TaskEnvironmentHandle, "exec" | "descriptor">,
+): RuntimeNamespace {
+  const run = async (argv: [string, ...string[]], what: string): Promise<void> => {
+    const result = await environment.exec({
+      argv,
+      projectEnvProfile: "maintenance",
+      timeoutMs: 30_000,
+      maxOutputBytes: 4 * 1024,
+    });
+    if (result.exitCode !== 0) throw new Error(`the task runtime could not ${what} in its workspace`);
+  };
+  return {
+    workspacePath: environment.descriptor.workspacePath,
+    makeDirectories: (path) => run(["/bin/mkdir", "-p", "--", path], "make a directory"),
+    remove: (path) => run(["/bin/rm", "-f", "--", path], "remove an entry"),
+    replaceLink: (target, path) => run(["/bin/ln", "-sfn", "--", target, path], "replace a link"),
+  };
+}
+
+/**
+ * Remove the entry `parts` names below `root` (a file, or a link itself,
+ * never what it points to); nothing when absent. On Linux relative to its
+ * directory opened without following links; on macOS through `runtime`;
+ * refused without one.
+ */
+export async function removeContainedEntry(
+  root: string,
+  parts: readonly string[],
+  runtime?: RuntimeNamespace,
+): Promise<void> {
+  removeContainedEntrySyncOrRuntime(root, parts, runtime);
+  if (containmentMode() === "nofollow-any" && runtime) {
+    await runtime.remove([runtime.workspacePath, ...parts].join("/"));
+  }
+}
+
+function removeContainedEntrySyncOrRuntime(root: string, parts: readonly string[], runtime?: RuntimeNamespace): void {
+  checkedParts(parts);
+  const base = resolvedRoot(root);
+  if (base === null) return;
+  const mode = containmentMode();
+  if (mode === "nofollow-any" && runtime) return;
+  if (mode !== "proc-fd") {
+    throw new WorkspacePathRefusedError("this host cannot remove a task's workspace entry without following its links");
+  }
+  let directory: number | null;
+  try {
+    directory = walkDirectory(base, parts.slice(0, -1), false);
+  } catch (error) {
+    throw refusal(error);
+  }
+  if (directory === null) return;
+  try {
+    unlinkSync(`/proc/self/fd/${directory}/${parts[parts.length - 1]!}`);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw refusal(error);
+  } finally {
+    closeSync(directory);
+  }
+}
+
+/**
+ * Point the link `parts` names below `root` at `target` (a name in the same
+ * directory), replacing it whole: made beside it and renamed over it,
+ * relative to its directory opened without following links (Linux), or
+ * through `runtime` (macOS); refused without one.
+ */
+export async function replaceContainedLink(
+  root: string,
+  parts: readonly string[],
+  target: string,
+  runtime?: RuntimeNamespace,
+): Promise<void> {
+  checkedParts(parts);
+  checkedParts([target]);
+  const base = resolvedRoot(root);
+  if (base === null) throw new WorkspacePathRefusedError("a workspace that does not exist is never written");
+  const mode = containmentMode();
+  if (mode === "proc-fd") {
+    let directory: number | null;
+    try {
+      directory = walkDirectory(base, parts.slice(0, -1), false);
+    } catch (error) {
+      throw refusal(error);
+    }
+    if (directory === null) throw new WorkspacePathRefusedError("a missing workspace directory is never made here");
+    const name = parts[parts.length - 1]!;
+    const pending = `.${name}-${process.pid}-${Date.now()}`;
+    try {
+      symlinkSync(target, `/proc/self/fd/${directory}/${pending}`);
+      renameSync(`/proc/self/fd/${directory}/${pending}`, `/proc/self/fd/${directory}/${name}`);
+    } catch (error) {
+      try {
+        unlinkSync(`/proc/self/fd/${directory}/${pending}`);
+      } catch {
+        // Nothing was made.
+      }
+      throw refusal(error);
+    } finally {
+      closeSync(directory);
+    }
+    return;
+  }
+  if (mode === "nofollow-any" && runtime) {
+    await runtime.replaceLink(target, [runtime.workspacePath, ...parts].join("/"));
+    return;
+  }
+  throw new WorkspacePathRefusedError("this host cannot link in a task's workspace without following its links");
+}
+
+/** An environment-absolute workspace path's components below the
+ *  workspace root. */
+export function workspacePathParts(descriptor: TaskEnvironmentDescriptor, path: string): string[] {
+  assertWorkspaceScopedPath(descriptor, path);
+  return path.slice(descriptor.workspacePath.length).split("/").filter(Boolean);
+}
+
+/** A host path's components below `root`; refused if it is not below it. */
+export function hostPathParts(root: string, path: string): string[] {
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  if (!path.startsWith(prefix)) throw new WorkspacePathRefusedError("a path outside the task's workspace");
+  const parts = path.slice(prefix.length).split(sep).filter(Boolean);
+  checkedParts(parts);
+  return parts;
+}
+
+export function hostWorkspaceRead(
+  descriptor: TaskEnvironmentDescriptor,
+  hostWorkspaceRoot: string,
+  path: string,
+  options?: TaskEnvironmentReadOptions,
+): Promise<Uint8Array | null> {
+  return readBoundedFile(hostWorkspaceRoot, workspacePathParts(descriptor, path), options);
+}
+
 export function hostWorkspaceWrite(
   descriptor: TaskEnvironmentDescriptor,
   hostWorkspaceRoot: string,
   path: string,
   bytes: Uint8Array,
-): void {
-  const target = hostPathFor(descriptor, hostWorkspaceRoot, path);
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, bytes);
+): Promise<void> {
+  return writeContainedFile(hostWorkspaceRoot, workspacePathParts(descriptor, path), bytes);
 }