@runuai/host 0.9.152 → 0.9.154

package/lib/shared-files-s3.ts

@@ -13,10 +13,20 @@
  * caveat of hostless-implementation.md decision 4; EFS is the swap if they
  * bite, and this module is the only place that would change.
  */
+import type { TaskLeaseFilesAccess } from "./cloud-credential-leases";
 import type { TaskEnvironmentHandle } from "./task-environment/types";
 import { LEASE_AWS_CONFIG_FILE, currentLease } from "./lease";
+import { spawnSync } from "node:child_process";
 
 export const MOUNT_S3_BIN = "/usr/bin/mount-s3";
+/** Files v1 mounts only below this root-owned machine path. The task sees it
+ * through an atomic `/workspace/files` symlink. Root mount/umount operations
+ * therefore never resolve a component the task can replace. */
+export const TASK_FILES_V1_MOUNT_ROOT = "/mnt/uai-files";
+/** Boot-local, root-only latch armed before the first v1 Mountpoint process
+ * can start. Once armed, only retiring/rebooting the one-task machine can
+ * prove that no private namespace or detached descriptor retains Files. */
+export const TASK_FILES_V1_MOUNT_ATTEMPTED = "/run/uai/files-mount-attempted";
 /** The task user the mounts are owned by. Its ids are looked up on the
  * machine, never assumed: the Debian cloud image the payload AMI is built
  * from ships an `admin` user at uid 1000, so `node` lands on 1001 there
@@ -32,10 +42,29 @@ export interface TaskUserIds {
   gid: number;
 }
 
+export interface SharedFilesV1Options {
+  /**
+   * The exact run's last-moment admission fence. It rides on every call into
+   * the task environment, including the marker write, so a withdrawn run
+   * cannot start its next mount step after an awaited provider lookup.
+   */
+  admit?: () => void;
+  /** Stage the mounts behind the root-only fixed directory without exposing
+   * them in the workspace. The Files consumer publishes synchronously from
+   * its exact gate-open callback. */
+  publish?: boolean;
+}
+
+interface ResolveTaskUserIdsOptions extends SharedFilesV1Options {
+  /** A v1 admission refusal is an error, never a reason to use fallback ids. */
+  failOnExecError?: boolean;
+}
+
 /** `id -u`/`id -g` of the task user on this machine, through the root exec. */
 export async function resolveTaskUserIds(
   handle: Pick<TaskEnvironmentHandle, "exec">,
   user: string = SHARED_FILES_USER,
+  options: ResolveTaskUserIdsOptions = {},
 ): Promise<TaskUserIds> {
   const fallback = { uid: SHARED_FILES_FALLBACK_UID, gid: SHARED_FILES_FALLBACK_GID };
   try {
@@ -45,16 +74,28 @@ export async function resolveTaskUserIds(
       user: "root",
       timeoutMs: 10_000,
       maxOutputBytes: 1024,
+      ...(options.admit ? { admit: options.admit } : {}),
     });
-    if (result.exitCode !== 0) return fallback;
+    if (result.exitCode !== 0) {
+      if (options.failOnExecError) {
+        throw new Error(`could not resolve the task user's ids (exit ${result.exitCode})`);
+      }
+      return fallback;
+    }
     const [uid, gid] = Buffer.from(result.stdout)
       .toString("utf8")
       .trim()
       .split(/\s+/)
       .map((part) => Number.parseInt(part, 10));
-    if (!Number.isInteger(uid) || !Number.isInteger(gid) || uid! < 0 || gid! < 0) return fallback;
+    if (!Number.isInteger(uid) || !Number.isInteger(gid) || uid! < 0 || gid! < 0) {
+      if (options.failOnExecError) {
+        throw new Error("could not resolve the task user's ids");
+      }
+      return fallback;
+    }
     return { uid: uid!, gid: gid! };
-  } catch {
+  } catch (error) {
+    if (options.failOnExecError) throw error;
     return fallback;
   }
 }
@@ -217,6 +258,200 @@ async function mountSharedFilesFromLeaseNow(
   return warnings.length > 0 ? warnings.join("\n") : null;
 }
 
+/**
+ * Mount shared files from the exact task/run's v1 Files session.
+ *
+ * Unlike the transitional lease path above, this function never consults
+ * `currentLease`, never turns a requested mount failure into a warning, and
+ * does not publish the workspace marker until every requested prefix is up.
+ * The Files consumer owns writing the session's credential_process files;
+ * mount-s3 learns only their fixed config path here.
+ */
+export async function mountSharedFilesFromAccess(
+  handle: Pick<TaskEnvironmentHandle<unknown>, "exec">,
+  workspacePath: string,
+  mode: SharedFilesMode,
+  access: TaskLeaseFilesAccess,
+  options: SharedFilesV1Options = {},
+): Promise<void> {
+  if (workspacePath !== "/workspace") {
+    throw new Error("shared files: task-machine workspace is not canonical");
+  }
+  return serializedByWorkspace(TASK_FILES_V1_MOUNT_ROOT, () =>
+    mountSharedFilesFromAccessNow(handle, workspacePath, mode, access, options),
+  );
+}
+
+async function mountSharedFilesFromAccessNow(
+  handle: Pick<TaskEnvironmentHandle<unknown>, "exec">,
+  workspacePath: string,
+  mode: SharedFilesMode,
+  access: TaskLeaseFilesAccess,
+  options: SharedFilesV1Options,
+): Promise<void> {
+  if (mode === "off") return;
+  const owner = await resolveTaskUserIds(handle, SHARED_FILES_USER, {
+    ...options,
+    failOnExecError: true,
+  });
+  // The legacy planner takes a workspace and appends `files/{org,me}`.
+  // Files v1's argument is already the fixed mount root, so rewrite only the
+  // resulting directory: `/workspace/files` exposes these exact children.
+  const plans = sharedFilesMountPlans(TASK_FILES_V1_MOUNT_ROOT, mode, access).map(
+    (plan) => ({
+      ...plan,
+      directory: `${TASK_FILES_V1_MOUNT_ROOT}/${plan.directory.endsWith("/org") ? "org" : "me"}`,
+    }),
+  );
+  const scopes = plans.map((plan) => plan.directory.slice(`${TASK_FILES_V1_MOUNT_ROOT}/`.length));
+  const prepared = await handle.exec({
+    projectEnvProfile: "maintenance",
+    argv: [
+      "/usr/bin/python3",
+      "-I",
+      "-c",
+      TASK_FILES_V1_PREPARE_HELPER,
+      TASK_FILES_V1_MOUNT_ROOT,
+      scopes.join(","),
+    ],
+    user: "root",
+    env: {},
+    timeoutMs: 10_000,
+    maxOutputBytes: 4 * 1024,
+    ...(options.admit ? { admit: options.admit } : {}),
+  });
+  if (prepared.exitCode !== 0) {
+    throw new Error(`shared files: could not prepare the fixed mount root (exit ${prepared.exitCode})`);
+  }
+  for (const plan of plans) {
+    const result = await handle.exec({
+      projectEnvProfile: "maintenance",
+      argv: [
+        "/usr/bin/env",
+        "-i",
+        "PATH=/usr/bin:/bin",
+        `AWS_CONFIG_FILE=${LEASE_AWS_CONFIG_FILE}`,
+        "AWS_EC2_METADATA_DISABLED=true",
+        "/bin/sh",
+        "-c",
+        'if /usr/bin/mountpoint -q "$1" 2>/dev/null; then exit 40; fi; shift; exec "$@"',
+        "mount-fixed",
+        plan.directory,
+        ...mountS3Argv(plan, owner),
+      ],
+      user: "root",
+      env: {},
+      timeoutMs: 60_000,
+      maxOutputBytes: 64 * 1024,
+      ...(options.admit ? { admit: options.admit } : {}),
+    });
+    if (result.exitCode !== 0) {
+      const detail = Buffer.from(result.stderr).toString("utf8").trim();
+      throw new Error(
+        `shared files: could not mount ${plan.directory}: ${detail || `exit ${result.exitCode}`}`,
+      );
+    }
+  }
+
+  if (options.publish === false) return;
+  const linked = await handle.exec({
+    projectEnvProfile: "maintenance",
+    argv: [
+      "/usr/bin/python3",
+      "-I",
+      "-c",
+      TASK_FILES_V1_LINK_HELPER,
+      workspacePath,
+      TASK_FILES_V1_MOUNT_ROOT,
+      mode,
+      scopes.join(","),
+    ],
+    user: "root",
+    env: {},
+    timeoutMs: 10_000,
+    maxOutputBytes: 4 * 1024,
+    ...(options.admit ? { admit: options.admit } : {}),
+  });
+  if (linked.exitCode !== 0) {
+    throw new Error(`shared files: could not publish the fixed mount root (exit ${linked.exitCode})`);
+  }
+
+}
+
+/** Publish already-staged v1 mounts from the synchronous registry gate-open
+ * callback. Files v1 exists only on a root sidecar/self runtime, so this
+ * local fixed-interpreter operation is the final boundary before any other
+ * consumer gate opens. */
+export function publishSharedFilesV1Sync(
+  workspacePath: string,
+  mode: SharedFilesMode,
+  scopes: readonly ("org" | "me")[],
+): void {
+  if (mode === "off") return;
+  if (workspacePath !== "/workspace") {
+    throw new Error("shared files: task-machine workspace is not canonical");
+  }
+  const result = spawnSync(
+    "/usr/bin/python3",
+    [
+      "-I",
+      "-c",
+      TASK_FILES_V1_LINK_HELPER,
+      workspacePath,
+      TASK_FILES_V1_MOUNT_ROOT,
+      mode,
+      scopes.join(","),
+    ],
+    {
+      cwd: "/",
+      env: {},
+      encoding: "utf8",
+      timeout: 10_000,
+      maxBuffer: 4 * 1024,
+    },
+  );
+  if (result.error || result.status !== 0 || result.signal !== null) {
+    const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+    throw new Error(
+      `shared files: could not publish the fixed mount root${
+        stderr ? `: ${stderr}` : ""
+      }`,
+    );
+  }
+}
+
+/** Synchronous half of gate close: make the fixed root non-traversable and
+ * remove the task-visible link/marker before any asynchronous cleanup. Open
+ * file descriptors still require process quiescence + ordinary unmount. */
+export function hideSharedFilesV1Sync(workspacePath: string): void {
+  if (workspacePath !== "/workspace") {
+    throw new Error("shared files: task-machine workspace is not canonical");
+  }
+  const result = spawnSync(
+    "/usr/bin/python3",
+    [
+      "-I",
+      "-c",
+      TASK_FILES_V1_HIDE_HELPER,
+      workspacePath,
+      TASK_FILES_V1_MOUNT_ROOT,
+    ],
+    {
+      cwd: "/",
+      env: {},
+      encoding: "utf8",
+      timeout: 10_000,
+      maxBuffer: 4 * 1024,
+    },
+  );
+  if (result.error || result.status !== 0 || result.signal !== null) {
+    const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+    throw new Error(
+      `shared files: could not hide the fixed mount root${stderr ? `: ${stderr}` : ""}`,
+    );
+  }
+}
+
 /** Unmount both directories; tolerant of never-mounted paths. */
 export async function unmountSharedFiles(
   handle: TaskEnvironmentHandle<unknown>,
@@ -234,3 +469,508 @@ export async function unmountSharedFiles(
       .catch(() => {});
   }
 }
+
+/**
+ * Strict v1 cleanup. Both mountpoints are attempted even when one fails, and
+ * success proves that neither remains mounted. It shares the mount queue, so
+ * cleanup cannot overtake a mount/marker pass for the same workspace.
+ */
+export async function unmountSharedFilesStrict(
+  handle: Pick<TaskEnvironmentHandle<unknown>, "exec">,
+  workspacePath: string,
+  options: SharedFilesV1Options = {},
+): Promise<void> {
+  if (workspacePath !== "/workspace") {
+    throw new Error("shared files: task-machine workspace is not canonical");
+  }
+  return serializedByWorkspace(TASK_FILES_V1_MOUNT_ROOT, async () => {
+    const result = await handle.exec({
+      argv: [
+        "/usr/bin/python3",
+        "-I",
+        "-c",
+        TASK_FILES_V1_UNMOUNT_HELPER,
+        workspacePath,
+        TASK_FILES_V1_MOUNT_ROOT,
+      ],
+      projectEnvProfile: "maintenance",
+      user: "root",
+      env: {},
+      timeoutMs: 30_000,
+      maxOutputBytes: 4 * 1024,
+      ...(options.admit ? { admit: options.admit } : {}),
+    });
+    if (result.exitCode !== 0) {
+      const detail = Buffer.from(result.stderr).toString("utf8").trim();
+      throw new Error(
+        `shared files: could not prove the fixed mounts absent: ${detail || `exit ${result.exitCode}`}`,
+      );
+    }
+  });
+}
+
+/** Create only the fixed, root-controlled mount directories. Neither the
+ * workspace nor any task-owned path is resolved here. */
+export const TASK_FILES_V1_PREPARE_HELPER = String.raw`
+import os
+import stat
+import sys
+
+root, encoded = sys.argv[1:3]
+if root != "/mnt/uai-files":
+    raise RuntimeError("unexpected Files mount root")
+scopes = [part for part in encoded.split(",") if part]
+if any(part not in ("org", "me") for part in scopes) or "me" not in scopes:
+    raise RuntimeError("invalid Files mount scope")
+flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
+
+def arm_mount_attempt():
+    runtime = os.open("/run/uai", flags)
+    try:
+        runtime_info = os.fstat(runtime)
+        if runtime_info.st_uid != 0:
+            raise RuntimeError("the Files runtime directory is not root-owned")
+        try:
+            attempted = os.open(
+                "files-mount-attempted",
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC,
+                0o600,
+                dir_fd=runtime,
+            )
+        except FileExistsError:
+            raise RuntimeError("a Files mount was already attempted in this boot; retire this task machine")
+        try:
+            marker_info = os.fstat(attempted)
+            if marker_info.st_uid != 0 or not stat.S_ISREG(marker_info.st_mode) or stat.S_IMODE(marker_info.st_mode) != 0o600:
+                raise RuntimeError("the Files mount-attempt marker is unsafe")
+            os.write(attempted, b"1\n")
+            os.fsync(attempted)
+        finally:
+            os.close(attempted)
+    finally:
+        os.close(runtime)
+
+def decode_mount_path(value):
+    result = bytearray()
+    index = 0
+    while index < len(value):
+        if value[index:index + 1] == b"\\" and index + 3 < len(value) and all(48 <= part <= 55 for part in value[index + 1:index + 4]):
+            result.append(int(value[index + 1:index + 4], 8))
+            index += 4
+        else:
+            result.append(value[index])
+            index += 1
+    return os.fsdecode(bytes(result))
+
+with open("/proc/self/mountinfo", "rb") as stream:
+    for line in stream:
+        before = line.rstrip(b"\n").split(b" - ", 1)[0].split(b" ")
+        path = decode_mount_path(before[4])
+        if path == root or path.startswith(root + "/"):
+            arm_mount_attempt()
+            raise RuntimeError("the Files mount root is not empty")
+
+parent_path, root_name = os.path.split(root)
+if not parent_path or not root_name:
+    raise RuntimeError("invalid Files mount root")
+parent = os.open(parent_path, flags)
+try:
+    try:
+        os.mkdir(root_name, 0o755, dir_fd=parent)
+    except FileExistsError:
+        pass
+    directory = os.open(root_name, flags, dir_fd=parent)
+finally:
+    os.close(parent)
+try:
+    info = os.fstat(directory)
+    if info.st_uid != 0:
+        raise RuntimeError("Files mount root is not root-owned")
+    # Staged mounts are deliberately unreachable to the task until the exact
+    # registry open publishes them.
+    os.fchmod(directory, 0o700)
+    for scope in scopes:
+        try:
+            os.mkdir(scope, 0o755, dir_fd=directory)
+        except FileExistsError:
+            pass
+        child = os.open(scope, flags, dir_fd=directory)
+        try:
+            if os.fstat(child).st_uid != 0:
+                raise RuntimeError("Files mountpoint is not root-owned")
+            os.fchmod(child, 0o755)
+        finally:
+            os.close(child)
+    for unused in set(("org", "me")) - set(scopes):
+        try:
+            os.rmdir(unused, dir_fd=directory)
+        except FileNotFoundError:
+            pass
+finally:
+    os.close(directory)
+
+# Arm the one-way boot latch only after the fixed root is ready, but before
+# the caller can spawn mount-s3. A lost helper response is deliberately
+# terminal: the caller cannot distinguish it from a mount launch that raced
+# ahead in another attempt.
+arm_mount_attempt()
+`;
+
+/** Publish the fixed root without ever asking root to follow the task's
+ * `files` entry. A stray task entry is atomically moved aside, never read or
+ * recursively deleted. */
+export const TASK_FILES_V1_LINK_HELPER = String.raw`
+import os
+import stat
+import sys
+
+workspace, target, mode, encoded = sys.argv[1:5]
+if workspace != "/workspace" or target != "/mnt/uai-files" or mode not in ("ro", "rw"):
+    raise RuntimeError("invalid Files link")
+scopes = [part for part in encoded.split(",") if part]
+if any(part not in ("org", "me") for part in scopes) or "me" not in scopes or len(set(scopes)) != len(scopes):
+    raise RuntimeError("invalid Files scopes")
+flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
+
+def decode_mount_path(value):
+    result = bytearray()
+    index = 0
+    while index < len(value):
+        if value[index:index + 1] == b"\\" and index + 3 < len(value) and all(48 <= part <= 55 for part in value[index + 1:index + 4]):
+            result.append(int(value[index + 1:index + 4], 8))
+            index += 4
+        else:
+            result.append(value[index])
+            index += 1
+    return os.fsdecode(bytes(result))
+
+expected = {(target + "/" + scope, "fuse", "mountpoint-s3") for scope in scopes}
+
+def exact_topology():
+    observed = []
+    with open("/proc/self/mountinfo", "rb") as stream:
+        for line in stream:
+            before, after = line.rstrip(b"\n").split(b" - ", 1)
+            fields = before.split(b" ")
+            tail = after.split(b" ")
+            path = decode_mount_path(fields[4])
+            if path == target or path.startswith(target + "/"):
+                observed.append((path, tail[0].decode("ascii"), tail[1].decode("ascii")))
+    return len(observed) == len(expected) and set(observed) == expected
+
+if not exact_topology():
+    raise RuntimeError("the staged Files mount topology is not exact")
+
+mount_root = os.open(target, flags)
+directory = os.open(workspace, flags)
+try:
+    workspace_owner = os.fstat(directory)
+    # The files entry belongs to the task until this exact publication. Preserve any
+    # stray entry by moving it aside in the same directory; never traverse or
+    # recursively remove it. The bounded loop also prevents a task racing the
+    # name from holding the root helper forever.
+    for attempt in range(64):
+        try:
+            info = os.stat("files", dir_fd=directory, follow_symlinks=False)
+        except FileNotFoundError:
+            info = None
+        if info is not None and stat.S_ISLNK(info.st_mode):
+            try:
+                if os.readlink("files", dir_fd=directory) == target:
+                    break
+            except OSError:
+                pass
+        if info is not None:
+            quarantine = ".uai-files-stray-" + os.urandom(16).hex()
+            try:
+                os.mkdir(quarantine, 0o700, dir_fd=directory)
+            except FileExistsError:
+                continue
+            quarantine_fd = os.open(quarantine, flags, dir_fd=directory)
+            try:
+                try:
+                    os.rename("files", "entry", src_dir_fd=directory, dst_dir_fd=quarantine_fd)
+                except FileNotFoundError:
+                    os.close(quarantine_fd)
+                    quarantine_fd = None
+                    os.rmdir(quarantine, dir_fd=directory)
+                    continue
+                os.fchown(quarantine_fd, workspace_owner.st_uid, workspace_owner.st_gid)
+                os.fchmod(quarantine_fd, 0o700)
+            finally:
+                if quarantine_fd is not None:
+                    os.close(quarantine_fd)
+        try:
+            os.symlink(target, "files", dir_fd=directory)
+            break
+        except FileExistsError:
+            continue
+    else:
+        raise RuntimeError("workspace Files link could not be published")
+    if os.readlink("files", dir_fd=directory) != target:
+        raise RuntimeError("workspace Files link was replaced")
+    try:
+        os.mkdir(".uai", 0o700, dir_fd=directory)
+        os.chown(".uai", workspace_owner.st_uid, workspace_owner.st_gid, dir_fd=directory, follow_symlinks=False)
+    except FileExistsError:
+        pass
+    # The marker is advisory task metadata, not part of the visibility proof.
+    # A task-controlled non-directory .uai, a wrong owner, or a non-regular
+    # marker must not turn a successfully hidden root into machine retirement.
+    try:
+        uai = os.open(".uai", flags, dir_fd=directory)
+    except OSError:
+        uai = None
+    if uai is not None:
+        try:
+            uai_owner = os.fstat(uai)
+            if (uai_owner.st_uid, uai_owner.st_gid) == (workspace_owner.st_uid, workspace_owner.st_gid):
+                try:
+                    descriptor = os.open(
+                        "files-mounted",
+                        os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC,
+                        0o600,
+                        dir_fd=uai,
+                    )
+                except OSError:
+                    descriptor = None
+                if descriptor is not None:
+                    try:
+                        marker_info = os.fstat(descriptor)
+                        if stat.S_ISREG(marker_info.st_mode):
+                            os.ftruncate(descriptor, 0)
+                            os.write(descriptor, mode.encode("ascii"))
+                            os.fchmod(descriptor, 0o600)
+                            os.fchown(descriptor, uai_owner.st_uid, uai_owner.st_gid)
+                    finally:
+                        os.close(descriptor)
+        finally:
+            os.close(uai)
+    # The workspace mutations above are task-controlled and may take time.
+    # Prove every expected mount again at the final visibility boundary.
+    if not exact_topology():
+        raise RuntimeError("the staged Files mount topology changed before publish")
+    # Last: only now can the task traverse the fixed root, after the link and
+    # any safe advisory marker work are complete.
+    os.fchmod(mount_root, 0o755)
+finally:
+    os.close(directory)
+    os.close(mount_root)
+`;
+
+/** Path visibility only. Physical mount retirement deliberately remains in
+ * the asynchronous strict helper, which quiesces exact task-user holders. */
+export const TASK_FILES_V1_HIDE_HELPER = String.raw`
+import os
+import stat
+import sys
+
+workspace, root = sys.argv[1:3]
+if workspace != "/workspace" or root != "/mnt/uai-files":
+    raise RuntimeError("invalid Files hide root")
+flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
+try:
+    mount_root = os.open(root, flags)
+except FileNotFoundError:
+    mount_root = None
+if mount_root is not None:
+    try:
+        os.fchmod(mount_root, 0o700)
+    finally:
+        os.close(mount_root)
+try:
+    directory = os.open(workspace, flags)
+except FileNotFoundError:
+    directory = None
+if directory is not None:
+    try:
+        try:
+            info = os.stat("files", dir_fd=directory, follow_symlinks=False)
+        except OSError:
+            info = None
+        if info is not None and stat.S_ISLNK(info.st_mode):
+            try:
+                if os.readlink("files", dir_fd=directory) == root:
+                    os.unlink("files", dir_fd=directory)
+            except OSError:
+                pass
+        try:
+            uai = os.open(".uai", flags, dir_fd=directory)
+        except OSError:
+            uai = None
+        if uai is not None:
+            try:
+                try:
+                    os.unlink("files-mounted", dir_fd=uai)
+                except OSError:
+                    pass
+            finally:
+                os.close(uai)
+    finally:
+        os.close(directory)
+`;
+
+/** Detach only the fixed root-owned mounts. The workspace operation is an
+ * exact symlink unlink through its opened parent; no root unmount ever sees
+ * task-controlled path components. */
+export const TASK_FILES_V1_UNMOUNT_HELPER = String.raw`
+import os
+import stat
+import subprocess
+import sys
+
+workspace, root = sys.argv[1:3]
+if workspace != "/workspace" or root != "/mnt/uai-files":
+    raise RuntimeError("invalid Files cleanup root")
+flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
+# Hide the staged root before any awaited unmount. Open handles are dealt with
+# by the ordinary unmount proof below; no lazy detach is accepted as cleanup.
+try:
+    mount_root = os.open(root, flags)
+except FileNotFoundError:
+    mount_root = None
+if mount_root is not None:
+    try:
+        os.fchmod(mount_root, 0o700)
+    finally:
+        os.close(mount_root)
+try:
+    directory = os.open(workspace, flags)
+except FileNotFoundError:
+    directory = None
+if directory is not None:
+    try:
+        try:
+            info = os.stat("files", dir_fd=directory, follow_symlinks=False)
+        except OSError:
+            info = None
+        if info is not None and stat.S_ISLNK(info.st_mode):
+            try:
+                if os.readlink("files", dir_fd=directory) == root:
+                    os.unlink("files", dir_fd=directory)
+            except OSError:
+                pass
+        try:
+            uai = os.open(".uai", flags, dir_fd=directory)
+        except OSError:
+            uai = None
+        if uai is not None:
+            try:
+                try:
+                    os.unlink("files-mounted", dir_fd=uai)
+                except OSError:
+                    pass
+            finally:
+                os.close(uai)
+    finally:
+        os.close(directory)
+
+def decode_mount_path(value):
+    result = bytearray()
+    index = 0
+    while index < len(value):
+        if value[index:index + 1] == b"\\" and index + 3 < len(value) and all(48 <= part <= 55 for part in value[index + 1:index + 4]):
+            result.append(int(value[index + 1:index + 4], 8))
+            index += 4
+        else:
+            result.append(value[index])
+            index += 1
+    return os.fsdecode(bytes(result))
+
+def mounts(path="/proc/self/mountinfo"):
+    found = []
+    with open(path, "rb") as stream:
+        for line in stream:
+            before, after = line.rstrip(b"\n").split(b" - ", 1)
+            fields = before.split(b" ")
+            tail = after.split(b" ")
+            found.append((
+                int(fields[0]),
+                decode_mount_path(fields[4]),
+                tail[0].decode("ascii"),
+                tail[1].decode("ascii"),
+                tuple(int(part) for part in fields[2].split(b":")),
+            ))
+    return found
+
+targets = {root + "/org", root + "/me"}
+legacy = {workspace.rstrip("/") + "/files/org", workspace.rstrip("/") + "/files/me"}
+
+def mount_attempted(create=False):
+    runtime = os.open("/run/uai", flags)
+    try:
+        runtime_info = os.fstat(runtime)
+        if runtime_info.st_uid != 0:
+            raise RuntimeError("the Files runtime directory is not root-owned")
+        try:
+            info = os.stat("files-mount-attempted", dir_fd=runtime, follow_symlinks=False)
+        except FileNotFoundError:
+            if not create:
+                return False
+            try:
+                descriptor = os.open(
+                    "files-mount-attempted",
+                    os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC,
+                    0o600,
+                    dir_fd=runtime,
+                )
+            except FileExistsError:
+                # Another strict-cleanup attempt armed the same one-way latch.
+                # Revalidate its directory entry and continue best-effort
+                # unmounting rather than losing the retirement witness.
+                info = os.stat("files-mount-attempted", dir_fd=runtime, follow_symlinks=False)
+            else:
+                try:
+                    info = os.fstat(descriptor)
+                    os.write(descriptor, b"1\n")
+                    os.fsync(descriptor)
+                finally:
+                    os.close(descriptor)
+        if info.st_uid != 0 or not stat.S_ISREG(info.st_mode) or stat.S_IMODE(info.st_mode) != 0o600:
+            raise RuntimeError("the Files mount-attempt marker is unsafe")
+        return True
+    finally:
+        os.close(runtime)
+
+initial = mounts()
+under_root = [(path, fs_type, source) for _mid, path, fs_type, source, _device in initial if path == root or path.startswith(root + "/")]
+counts = {path: sum(1 for observed, _fs_type, _source in under_root if observed == path) for path in targets}
+unexpected = [
+    path for path, fs_type, source in under_root
+    if path not in targets or fs_type != "fuse" or source != "mountpoint-s3"
+]
+unexpected += [path for path, count in counts.items() if count > 1]
+unexpected += [
+    path for _mid, path, fs_type, source, _device in initial
+    if path in legacy or (fs_type == "fuse" and source == "mountpoint-s3" and path not in targets)
+]
+attempted = mount_attempted()
+if unexpected or any(counts.values()):
+    # An older/lost attempt may have reached mount-s3 before its marker was
+    # observed. Latch retirement before changing the local mount topology.
+    attempted = mount_attempted(create=True)
+if unexpected:
+    raise RuntimeError("legacy or unexpected Files mount remains; retire this task machine")
+
+failures = []
+for path in sorted(targets):
+    records = [record for record in mounts() if record[1] == path]
+    if not records:
+        continue
+    if len(records) != 1 or records[0][2:4] != ("fuse", "mountpoint-s3"):
+        failures.append(path + ":identity-changed")
+        continue
+    ended = subprocess.run(["/usr/bin/umount", path], env={}, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    if ended.returncode != 0:
+        failures.append(path + ":unmount")
+    if any(mount_path == path for _mid, mount_path, _fs_type, _source, _device in mounts()):
+        failures.append(path + ":still-mounted")
+if attempted:
+    # A /proc scan cannot prove every private mount namespace or detached fd
+    # gone: a task can fork during the scan, retain a namespace fd, or become
+    # root through the task image's sudo. The boot-local latch makes runtime
+    # destruction the sole success proof once mount-s3 could have started.
+    failures.append("task-machine-retirement-required")
+if failures:
+    raise RuntimeError(";".join(failures))
+`;