@moondeck/station 0.0.1 → 1.0.0

package/lib/shared-files-s3.ts

@@ -0,0 +1,976 @@
+/**
+ * ADR-133 shared files on a task machine: S3 prefixes mounted with Mountpoint
+ * for Amazon S3 (`mount-s3`) at /workspace/files/{org,me}.
+ *
+ * Containers bind-mount a host directory; a machine over ssh got a
+ * point-in-time tar copy; the sidecar mounts the live prefix, so any number
+ * of task machines see one workspace's files at once and writes land in the
+ * bucket as they happen. Credentials come from the task lease through the
+ * `credential_process` config lib/lease.ts maintains — a refreshed lease
+ * reaches a mount that is already up.
+ *
+ * Mountpoint's semantics (whole-file writes, no rename) are the documented
+ * 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
+ * and a hard-coded 1000 handed every mount to the wrong user (2026-09-10,
+ * smoke 6). */
+export const SHARED_FILES_USER = "node";
+/** What the lookup falls back to (the standard container image's ids). */
+export const SHARED_FILES_FALLBACK_UID = 1000;
+export const SHARED_FILES_FALLBACK_GID = 1000;
+
+export interface TaskUserIds {
+  uid: number;
+  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 {
+    const result = await handle.exec({
+      projectEnvProfile: "maintenance",
+      argv: ["/bin/sh", "-c", 'id -u "$1" && id -g "$1"', "ids", user],
+      user: "root",
+      timeoutMs: 10_000,
+      maxOutputBytes: 1024,
+      ...(options.admit ? { admit: options.admit } : {}),
+    });
+    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) {
+      if (options.failOnExecError) {
+        throw new Error("could not resolve the task user's ids");
+      }
+      return fallback;
+    }
+    return { uid: uid!, gid: gid! };
+  } catch (error) {
+    if (options.failOnExecError) throw error;
+    return fallback;
+  }
+}
+
+export type SharedFilesMode = "off" | "ro" | "rw";
+
+export interface SharedFilesMountPlan {
+  bucket: string;
+  prefix: string;
+  directory: string;
+  mode: "ro" | "rw";
+  region: string;
+}
+
+/** The mount-s3 argv for one prefix. Exported for the test that pins it. */
+export function mountS3Argv(plan: SharedFilesMountPlan, owner: TaskUserIds): [string, ...string[]] {
+  return [
+    MOUNT_S3_BIN,
+    "--prefix",
+    plan.prefix,
+    "--region",
+    plan.region,
+    // Owned by the task user so agents and the editor can use it; the mount
+    // is performed by the root sidecar.
+    "--allow-other",
+    "--uid",
+    String(owner.uid),
+    "--gid",
+    String(owner.gid),
+    "--dir-mode",
+    "0755",
+    "--file-mode",
+    "0644",
+    ...(plan.mode === "ro" ? ["--read-only"] : ["--allow-delete", "--allow-overwrite"]),
+    plan.bucket,
+    plan.directory,
+  ];
+}
+
+/** The mounts a task wants, from its shared-files mode and lease. */
+export function sharedFilesMountPlans(
+  workspacePath: string,
+  mode: SharedFilesMode,
+  lease: { region: string; files: { bucket: string; orgPrefix: string | null; userPrefix: string } },
+): SharedFilesMountPlan[] {
+  if (mode === "off") return [];
+  const plans: SharedFilesMountPlan[] = [];
+  if (lease.files.orgPrefix) {
+    plans.push({
+      bucket: lease.files.bucket,
+      prefix: lease.files.orgPrefix,
+      directory: `${workspacePath}/files/org`,
+      mode,
+      region: lease.region,
+    });
+  }
+  plans.push({
+    bucket: lease.files.bucket,
+    prefix: lease.files.userPrefix,
+    directory: `${workspacePath}/files/me`,
+    mode,
+    region: lease.region,
+  });
+  return plans;
+}
+
+/**
+ * Mount the task's shared files. Returns a warning string when something
+ * could not be mounted (the task still starts, like the machine copy path),
+ * null when clean or when there is nothing to mount.
+ */
+/** One mount pass per workspace at a time. Task-up (the cloud's wake) and
+ *  the sidecar's own resume pass both mount on a runner restart, and the
+ *  shell's `mountpoint -q` guard is not atomic across two racers: live
+ *  2026-09-12 both ran in the same second — /files/org got two stacked
+ *  mounts and the loser on /files/me failed with "fuse: mountpoint is not
+ *  empty", surfaced to the human as a warning although the files were
+ *  mounted. The second pass now waits and finds the healthy mount. */
+const mountPasses = new Map<string, Promise<unknown>>();
+
+async function serializedByWorkspace<T>(workspacePath: string, run: () => Promise<T>): Promise<T> {
+  const previous = mountPasses.get(workspacePath) ?? Promise.resolve();
+  const next = previous.catch(() => undefined).then(run);
+  mountPasses.set(workspacePath, next);
+  try {
+    return await next;
+  } finally {
+    if (mountPasses.get(workspacePath) === next) mountPasses.delete(workspacePath);
+  }
+}
+
+export async function mountSharedFilesFromLease(
+  handle: TaskEnvironmentHandle<unknown>,
+  workspacePath: string,
+  task: { sharedFiles?: string },
+): Promise<string | null> {
+  return serializedByWorkspace(workspacePath, () =>
+    mountSharedFilesFromLeaseNow(handle, workspacePath, task),
+  );
+}
+
+async function mountSharedFilesFromLeaseNow(
+  handle: TaskEnvironmentHandle<unknown>,
+  workspacePath: string,
+  task: { sharedFiles?: string },
+): Promise<string | null> {
+  const mode: SharedFilesMode =
+    task.sharedFiles === "rw" ? "rw" : task.sharedFiles === "off" ? "off" : "ro";
+  if (mode === "off") return null;
+  const lease = currentLease();
+  if (!lease) {
+    return "shared files: no lease yet — /workspace/files is not mounted";
+  }
+  const warnings: string[] = [];
+  let mountedAny = false;
+  const owner = await resolveTaskUserIds(handle);
+  for (const plan of sharedFilesMountPlans(workspacePath, mode, lease)) {
+    const result = await handle.exec({
+      projectEnvProfile: "maintenance",
+      argv: [
+        "/bin/sh",
+        "-c",
+        // Idempotent: a healthy mount is left alone. A mount whose daemon is
+        // gone still shows as mounted but every access fails with "Transport
+        // endpoint is not connected" (a sidecar restart SIGKILLs mount-s3 —
+        // live 2026-09-10, smoke 10); it is lazily unmounted and mounted
+        // again. The mkdir/chown tolerate the broken mount too.
+        'mkdir -p "$1" 2>/dev/null; chown "$2:$3" "$1" 2>/dev/null; ' +
+          'if mountpoint -q "$1" 2>/dev/null; then if ls "$1" >/dev/null 2>&1; then exit 0; fi; ' +
+          'umount -l "$1" 2>/dev/null || true; chown "$2:$3" "$1" 2>/dev/null; fi; ' +
+          'shift 3; exec "$@"',
+        "mount",
+        plan.directory,
+        String(owner.uid),
+        String(owner.gid),
+        ...mountS3Argv(plan, owner),
+      ],
+      user: "root",
+      env: { AWS_CONFIG_FILE: LEASE_AWS_CONFIG_FILE },
+      timeoutMs: 60_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    if (result.exitCode === 0) {
+      mountedAny = true;
+    } else {
+      warnings.push(
+        `shared files: could not mount ${plan.directory}: ${Buffer.from(result.stderr).toString("utf8").trim() || `exit ${result.exitCode}`}`,
+      );
+    }
+  }
+  if (mountedAny) {
+    // The same marker the container and machine paths write: it gates the
+    // "## Shared files" briefing in every agent's preamble. The sidecar
+    // writes the MODE into it so a restart can mount again the same way
+    // (lib/sidecar-resume.ts); readers only test for the file.
+    await handle
+      .writeWorkspaceFile(`${workspacePath}/.moondeck/files-mounted`, Buffer.from(mode))
+      .catch(() => {});
+  }
+  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>,
+  workspacePath: string,
+): Promise<void> {
+  for (const directory of [`${workspacePath}/files/org`, `${workspacePath}/files/me`]) {
+    await handle
+      .exec({
+        argv: ["/bin/sh", "-c", 'mountpoint -q "$1" && umount "$1" || true', "umount", directory],
+        projectEnvProfile: "maintenance",
+        user: "root",
+        timeoutMs: 30_000,
+        maxOutputBytes: 4 * 1024,
+      })
+      .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(".moondeck", 0o700, dir_fd=directory)
+        os.chown(".moondeck", 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 .moondeck, a wrong owner, or a non-regular
+    # marker must not turn a successfully hidden root into machine retirement.
+    try:
+        uai = os.open(".moondeck", 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(".moondeck", 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(".moondeck", 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))
+`;