@runuai/host 0.9.152 → 0.9.154

package/lib/credential-consumers/files.ts

@@ -0,0 +1,934 @@
+/**
+ * ADR-154 Files v1 on task machines.
+ *
+ * A Files session is deliberately unlike the other leased credentials: the
+ * Mountpoint process needs a renewable credential_process file for the whole
+ * life of the mount.  The cloud still remains the only authority.  A grant is
+ * kept in memory until its exact gate opens; only then may task-up put the
+ * session in the task machine's root-only tmpfs and mount the prefixes named
+ * by that grant.
+ */
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  renameSync,
+  rmSync,
+  statfsSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+import type {
+  CredentialInstallRequest,
+  TaskAssignment,
+  TaskCredentialView,
+  TaskLeaseFilesAccess,
+} from "../cloud-credential-leases";
+import {
+  AuthoritativeTaskFilesFailure,
+  type TaskFilesConsumer,
+} from "../cloud-credential-runtime";
+import {
+  listCredentialCleanupPaths,
+  rememberCredentialCleanupPath,
+} from "../credential-cleanup-inventory";
+import {
+  LEASE_AWS_CONFIG_FILE,
+  LEASE_CREDENTIALS_FILE,
+  leaseAwsConfig,
+} from "../lease";
+import {
+  hideSharedFilesV1Sync,
+  mountSharedFilesFromAccess,
+  publishSharedFilesV1Sync,
+  type SharedFilesMode,
+  unmountSharedFilesStrict,
+} from "../shared-files-s3";
+import { reconstructTaskEnvironment } from "../task-environment";
+import {
+  parseTaskEnvironmentLocator,
+  serializeTaskEnvironmentLocator,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentLocator,
+} from "../task-environment/types";
+import type { TaskCredentialCleanupRequest } from "../task-credential-cleanup";
+import type {
+  TaskFilesMachineRetirementReason,
+  TaskFilesMachineRetirementRequest,
+} from "../task-files-machine-retirement";
+import { TMPFS_MAGIC, taskFilesV1Readiness } from "../task-files-readiness";
+
+export const FILES_SESSION_CREDENTIAL_ID = "files-session";
+export const FILES_SESSION_STAGED_SUFFIX = ".uai-tmp";
+export const FILES_SESSION_MANAGED_PATHS = [
+  LEASE_CREDENTIALS_FILE,
+  `${LEASE_CREDENTIALS_FILE}${FILES_SESSION_STAGED_SUFFIX}`,
+  LEASE_AWS_CONFIG_FILE,
+  `${LEASE_AWS_CONFIG_FILE}${FILES_SESSION_STAGED_SUFFIX}`,
+] as const;
+
+type RuntimeEnvironment = Pick<
+  TaskEnvironmentHandle<unknown>,
+  "descriptor" | "exec" | "writeWorkspaceFile"
+>;
+
+interface FilesCandidate {
+  view: TaskCredentialView;
+  readonly access: TaskLeaseFilesAccess;
+  /** Valid only for the install transaction which created this candidate.
+   * After open, the consumer's exact served candidate + abort fence is the
+   * authority; the registry deliberately makes this callback false. */
+  installCurrent: () => boolean;
+  readonly controller: AbortController;
+}
+
+interface FilesBinding {
+  readonly locator: TaskEnvironmentLocator;
+  readonly workspacePath: string;
+  readonly mode: SharedFilesMode;
+  /** Present in the process which established/recovered the runtime. */
+  environment: RuntimeEnvironment | null;
+  /** The exact prefixes are mounted below the root-only fixed directory. */
+  mounted: boolean;
+  /** The workspace link has been atomically published for this run. A
+   * replacement grant can stage a remount while this remains false; the
+   * registry's synchronous open is the only operation which flips it. */
+  published: boolean;
+  /** Non-secret identity of the prefixes which are physically mounted. */
+  mountIdentity: string | null;
+}
+
+interface FilesState {
+  readonly assignment: TaskAssignment;
+  candidate: FilesCandidate | null;
+  served: FilesCandidate | null;
+  binding: FilesBinding | null;
+  gateOpen: boolean;
+  tail: Promise<void>;
+}
+
+export interface TaskFilesV1Consumer extends TaskFilesConsumer {
+  /** Put the exact open grant into this runtime and mount its Files roots. */
+  runtimeReady(
+    assignment: Readonly<TaskAssignment>,
+    environment: RuntimeEnvironment,
+    mode: SharedFilesMode,
+    signal: AbortSignal,
+  ): Promise<void>;
+  /** Forget values and refuse new work at process shutdown; leave mounts and
+   * files for the next process's recovery cleanup. */
+  shutdown(): void;
+}
+
+export interface TaskFilesV1ConsumerDeps {
+  rememberPath?: typeof rememberCredentialCleanupPath;
+  listPaths?: typeof listCredentialCleanupPaths;
+  writeSession?: (access: TaskLeaseFilesAccess) => void | Promise<void>;
+  mount?: typeof mountSharedFilesFromAccess;
+  publish?: typeof publishSharedFilesV1Sync;
+  hide?: typeof hideSharedFilesV1Sync;
+  unmount?: typeof unmountSharedFilesStrict;
+  reconstruct?: (
+    locator: TaskEnvironmentLocator,
+  ) => Promise<TaskEnvironmentHandle<unknown>>;
+  /** A runtime which survived this process is bound before its first
+   * recovered grant installs. This lets install stage the mount while the
+   * gate is still closed, rather than exposing a credential-less interval
+   * to processes which survived the restart. */
+  recoveredBinding?: (
+    assignment: Readonly<TaskAssignment>,
+  ) =>
+    | {
+        locator: TaskEnvironmentLocator;
+        workspacePath: string;
+        mode: SharedFilesMode;
+      }
+    | null;
+  ready?: () => boolean;
+  /** A task machine whose Files boundary cannot be hidden or retired must
+   * leave service. The cutover installs a handler which quarantines the
+   * local task and durably asks the cloud to retire this exact run's machine;
+   * tests may observe the request and let the original error throw. */
+  retireMachine?: (request: TaskFilesMachineRetirementRequest) => void;
+}
+
+function sameAssignment(
+  left: Readonly<TaskAssignment>,
+  right: Readonly<TaskAssignment>,
+): boolean {
+  return left.taskId === right.taskId && left.runEpoch === right.runEpoch;
+}
+
+function sameFilesAccess(
+  left: Readonly<TaskLeaseFilesAccess>,
+  right: Readonly<TaskLeaseFilesAccess>,
+): boolean {
+  return (
+    sameAssignment(left.assignment, right.assignment) &&
+    left.region === right.region &&
+    left.files.bucket === right.files.bucket &&
+    left.files.orgPrefix === right.files.orgPrefix &&
+    left.files.userPrefix === right.files.userPrefix &&
+    left.credentials.accessKeyId === right.credentials.accessKeyId &&
+    left.credentials.secretAccessKey === right.credentials.secretAccessKey &&
+    left.credentials.sessionToken === right.credentials.sessionToken &&
+    left.credentials.expiresAt === right.credentials.expiresAt
+  );
+}
+
+function filesScopes(access: TaskLeaseFilesAccess): Array<"org" | "me"> {
+  return access.files.orgPrefix === null ? ["me"] : ["org", "me"];
+}
+
+function filesMountIdentity(
+  mode: SharedFilesMode,
+  access: TaskLeaseFilesAccess,
+): string {
+  return JSON.stringify({
+    mode,
+    region: access.region,
+    bucket: access.files.bucket,
+    orgPrefix: access.files.orgPrefix,
+    userPrefix: access.files.userPrefix,
+  });
+}
+
+function assertCanonicalTaskMachineRuntime(
+  assignment: Readonly<TaskAssignment>,
+  environment: RuntimeEnvironment,
+): void {
+  const { descriptor } = environment;
+  const locator = descriptor.locator;
+  const value = locator.value;
+  if (
+    descriptor.taskId !== assignment.taskId ||
+    descriptor.workspacePath !== "/workspace" ||
+    locator.provider !== "self" ||
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    (value as Record<string, unknown>).taskId !== assignment.taskId ||
+    (value as Record<string, unknown>).workspacePath !== "/workspace"
+  ) {
+    throw new Error("the Files session requires the exact canonical task-machine runtime");
+  }
+}
+
+function filesCredentialProcessOutput(access: TaskLeaseFilesAccess): string {
+  return JSON.stringify({
+    Version: 1,
+    AccessKeyId: access.credentials.accessKeyId,
+    SecretAccessKey: access.credentials.secretAccessKey,
+    SessionToken: access.credentials.sessionToken,
+    Expiration: new Date(access.credentials.expiresAt).toISOString(),
+  });
+}
+
+function ensurePrivateRunDirectory(): void {
+  const root = dirname(LEASE_CREDENTIALS_FILE);
+  if (!existsSync(root)) mkdirSync(root, { mode: 0o700 });
+  const info = lstatSync(root);
+  if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== 0) {
+    throw new Error("the Files session directory is not a root-owned directory");
+  }
+  chmodSync(root, 0o700);
+  // `/run` being tmpfs is not enough: a pre-existing `/run/uai` could be a
+  // bind mount onto persistent storage. Prove the directory which will hold
+  // the bytes immediately before every atomic write pass.
+  if (Number(statfsSync(root).type) !== TMPFS_MAGIC) {
+    throw new Error("the Files session directory is not memory-backed");
+  }
+}
+
+function atomicRootFile(path: string, contents: string): void {
+  const staged = `${path}${FILES_SESSION_STAGED_SUFFIX}`;
+  // An interrupted older write is itself inventoried.  Removing its directory
+  // entry cannot follow it if it was somehow replaced by a symlink.
+  rmSync(staged, { force: true });
+  const noFollow = constants.O_NOFOLLOW ?? 0;
+  const descriptor = openSync(
+    staged,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow,
+    0o600,
+  );
+  try {
+    writeFileSync(descriptor, contents, { encoding: "utf8" });
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  renameSync(staged, path);
+  chmodSync(path, 0o600);
+  const written = statSync(path);
+  if (!written.isFile() || written.uid !== 0 || (written.mode & 0o777) !== 0o600) {
+    throw new Error("a Files session file is not a root-owned regular file");
+  }
+}
+
+/** Atomic root-only write.  The caller has already proved `/run` is tmpfs
+ * and inventoried both final and staged names. */
+export function writeTaskFilesSession(access: TaskLeaseFilesAccess): void {
+  if (!taskFilesV1Readiness(true).ready) {
+    throw new Error("the host cannot safely persist a Files session");
+  }
+  ensurePrivateRunDirectory();
+  atomicRootFile(LEASE_CREDENTIALS_FILE, filesCredentialProcessOutput(access));
+  atomicRootFile(LEASE_AWS_CONFIG_FILE, leaseAwsConfig({ region: access.region }));
+}
+
+function abortError(signal?: AbortSignal): Error {
+  return signal?.reason instanceof Error
+    ? signal.reason
+    : new Error("the task's Files session was withdrawn");
+}
+
+/** One serialized Files consumer per task-machine process. */
+export function createTaskFilesV1Consumer(
+  deps: TaskFilesV1ConsumerDeps = {},
+): TaskFilesV1Consumer {
+  const states = new Map<string, FilesState>();
+  let stopped = false;
+  const remember = deps.rememberPath ?? rememberCredentialCleanupPath;
+  const list = deps.listPaths ?? listCredentialCleanupPaths;
+  const writeSession = deps.writeSession ?? writeTaskFilesSession;
+  const mount = deps.mount ?? mountSharedFilesFromAccess;
+  const publish = deps.publish ?? publishSharedFilesV1Sync;
+  const hide = deps.hide ?? hideSharedFilesV1Sync;
+  const unmount = deps.unmount ?? unmountSharedFilesStrict;
+  const reconstruct =
+    deps.reconstruct ??
+    ((locator: TaskEnvironmentLocator) => reconstructTaskEnvironment(locator, "loader"));
+  const recoveredBinding = deps.recoveredBinding ?? (() => null);
+  const ready = deps.ready ?? (() => taskFilesV1Readiness(true).ready);
+  let retirementRequested = false;
+  const retireMachine =
+    deps.retireMachine ??
+    ((request: TaskFilesMachineRetirementRequest): void => {
+      throw new Error("task-machine Files retirement is not installed", {
+        cause: request.error,
+      });
+    });
+
+  const terminalFailure = (
+    assignment: Readonly<TaskAssignment>,
+    reason: TaskFilesMachineRetirementReason,
+    error: unknown,
+    message: string,
+  ): Error => {
+    const failure = error instanceof Error ? error : new Error(message, { cause: error });
+    // Terminal is one-way for this process. No retry or later grant may
+    // republish Files while the cutover-owned retirement is pending.
+    stopped = true;
+    for (const state of states.values()) {
+      state.gateOpen = false;
+      state.candidate?.controller.abort(failure);
+      if (state.served !== state.candidate) state.served?.controller.abort(failure);
+    }
+    // Re-attempt the local visibility fence before handing off. The handler
+    // owns the stronger task-process quarantine and durable cloud request.
+    for (const workspacePath of new Set(
+      [...states.values()].flatMap((state) =>
+        state.binding ? [state.binding.workspacePath] : [],
+      ),
+    )) {
+      try {
+        hide(workspacePath);
+      } catch {
+        // The terminal handler receives the original proof failure and must
+        // contain the whole task even when HIDE remains unprovable.
+      }
+    }
+    if (!retirementRequested) {
+      retireMachine({ assignment: { ...assignment }, reason, error: failure });
+      retirementRequested = true;
+    }
+    return failure;
+  };
+
+  const throwAuthoritativeFailure = (
+    assignment: Readonly<TaskAssignment>,
+    reason: TaskFilesMachineRetirementReason,
+    error: unknown,
+    message: string,
+  ): never => {
+    try {
+      terminalFailure(assignment, reason, error, message);
+    } catch (retirementError) {
+      throw new AuthoritativeTaskFilesFailure(retirementError);
+    }
+    throw new AuthoritativeTaskFilesFailure(error);
+  };
+
+  const publishBoundary = (
+    assignment: Readonly<TaskAssignment>,
+    binding: FilesBinding,
+    access: TaskLeaseFilesAccess,
+    afterPublish?: () => void,
+  ): void => {
+    try {
+      publish(binding.workspacePath, binding.mode, filesScopes(access));
+      binding.published = true;
+      afterPublish?.();
+    } catch (error) {
+      // A lost spawnSync result can mean LINK made the root traversable
+      // before its caller saw an error. Hide without relying on the success
+      // bit. This also compensates a fence which fails just after LINK.
+      try {
+        hide(binding.workspacePath);
+        binding.published = false;
+      } catch (hideError) {
+        const failure = new AggregateError(
+          [error, hideError],
+          "the task's Files boundary could not be hidden after publication failed",
+        );
+        throwAuthoritativeFailure(
+          assignment,
+          "visibility-unproven",
+          failure,
+          "the task's Files boundary could not be hidden after publication failed",
+        );
+      }
+      throw error;
+    }
+  };
+
+  const assertCandidate = (
+    state: FilesState,
+    candidate: FilesCandidate,
+    signal?: AbortSignal,
+    requireOpen = false,
+  ): void => {
+    if (
+      stopped ||
+      states.get(state.assignment.taskId) !== state ||
+      (requireOpen ? state.served !== candidate : state.candidate !== candidate) ||
+      candidate.controller.signal.aborted ||
+      signal?.aborted ||
+      (!requireOpen && !candidate.installCurrent()) ||
+      (requireOpen && !state.gateOpen)
+    ) {
+      throw abortError(signal ?? candidate.controller.signal);
+    }
+  };
+
+  const queue = (state: FilesState, work: () => Promise<void>): Promise<void> => {
+    const next = state.tail.catch(() => undefined).then(work);
+    state.tail = next;
+    return next;
+  };
+
+  const inventory = (state: FilesState, binding: FilesBinding): void => {
+    for (const path of FILES_SESSION_MANAGED_PATHS) {
+      remember({
+        taskId: state.assignment.taskId,
+        runEpoch: state.assignment.runEpoch,
+        runtime: binding.locator,
+        lane: "files-session",
+        path,
+        credentialId: FILES_SESSION_CREDENTIAL_ID,
+      });
+    }
+  };
+
+  const materialize = async (
+    state: FilesState,
+    candidate: FilesCandidate,
+    binding: FilesBinding,
+    signal: AbortSignal | undefined,
+    requireOpen: boolean,
+  ): Promise<void> => {
+    let environment = binding.environment;
+    if (!environment) {
+      const recovered = await reconstruct(binding.locator);
+      if (
+        recovered.descriptor.taskId !== state.assignment.taskId ||
+        recovered.descriptor.workspacePath !== binding.workspacePath
+      ) {
+        throw new Error("the recovered Files runtime does not match its assignment");
+      }
+      binding.environment = recovered;
+      environment = recovered;
+    }
+    assertCandidate(state, candidate, signal, requireOpen);
+    // Never accept a healthy-looking mount inherited from v0 or from a
+    // crashed process as this grant's.  The first pass in this process
+    // removes and proves both endpoints before it puts any session on disk.
+    const establish = !binding.mounted;
+    const mountIdentity = filesMountIdentity(binding.mode, candidate.access);
+    if (!establish && binding.mountIdentity !== mountIdentity) {
+      throw new Error("the Files mount authority changed and requires full cleanup");
+    }
+    if (establish) {
+      await unmount(environment, binding.workspacePath, {
+        admit: () => assertCandidate(state, candidate, signal, requireOpen),
+      });
+      assertCandidate(state, candidate, signal, requireOpen);
+    }
+    if (binding.mode === "off") {
+      binding.mounted = true;
+      binding.published = true;
+      binding.mountIdentity = mountIdentity;
+      return;
+    }
+    // Durable witnesses precede the first byte of either final or staged
+    // file.  They remain if anything after this point fails.
+    inventory(state, binding);
+    assertCandidate(state, candidate, signal, requireOpen);
+    await writeSession(candidate.access);
+    assertCandidate(state, candidate, signal, requireOpen);
+    if (establish) {
+      await mount(
+        environment as TaskEnvironmentHandle<unknown>,
+        binding.workspacePath,
+        binding.mode,
+        candidate.access,
+        {
+          admit: () => assertCandidate(state, candidate, signal, requireOpen),
+          publish: false,
+        },
+      );
+      binding.mounted = true;
+      binding.published = false;
+      binding.mountIdentity = mountIdentity;
+    }
+    assertCandidate(state, candidate, signal, requireOpen);
+    if (requireOpen && !binding.published) {
+      publishBoundary(state.assignment, binding, candidate.access, () =>
+        assertCandidate(state, candidate, signal, requireOpen),
+      );
+    }
+  };
+
+  const compensateRuntimeReadyFailure = async (
+    state: FilesState,
+    candidate: FilesCandidate,
+    binding: FilesBinding,
+    environment: RuntimeEnvironment,
+    signal: AbortSignal,
+    error: unknown,
+  ): Promise<never> => {
+    // A helper which already failed its visibility proof has performed the
+    // one-way retirement transition. Preserve that authoritative cause.
+    if (error instanceof AuthoritativeTaskFilesFailure) throw error;
+    // A stale setup must never hide or unmount a winner which took ownership
+    // while this one was suspended.
+    assertCandidate(state, candidate, signal, true);
+
+    // LINK or mount(2) may have succeeded before a provider result was lost.
+    // Ignore both success bits: hide first, then prove the fixed mounts gone.
+    try {
+      hide(binding.workspacePath);
+      binding.published = false;
+    } catch (hideError) {
+      throwAuthoritativeFailure(
+        state.assignment,
+        "visibility-unproven",
+        new AggregateError(
+          [error, hideError],
+          "the task's Files boundary could not be hidden after setup failed",
+        ),
+        "the task's Files boundary could not be hidden after setup failed",
+      );
+    }
+
+    try {
+      await unmount(environment, binding.workspacePath, {
+        admit: () => assertCandidate(state, candidate, signal, true),
+      });
+    } catch (unmountError) {
+      // A close or replacement which won while compensation was awaiting the
+      // provider owns the remaining cleanup. Never retire it for this stale
+      // setup attempt.
+      assertCandidate(state, candidate, signal, true);
+      throwAuthoritativeFailure(
+        state.assignment,
+        "mount-retirement-unproven",
+        new AggregateError(
+          [error, unmountError],
+          "the task's Files mounts could not be proven absent after setup failed",
+        ),
+        "the task's Files mounts could not be proven absent after setup failed",
+      );
+    }
+
+    binding.mounted = false;
+    binding.published = false;
+    binding.mountIdentity = null;
+    assertCandidate(state, candidate, signal, true);
+    throw error;
+  };
+
+  return {
+    async install(request): Promise<void> {
+      if (stopped) throw new Error("the Files consumer is shut down");
+      if (!ready()) throw new Error("task-machine Files v1 is unavailable on this host");
+      if (!request.files || !sameAssignment(request.assignment, request.files.assignment)) {
+        throw new Error("a task-machine grant has no Files session for its assignment");
+      }
+      const existing = states.get(request.assignment.taskId);
+      if (existing && existing.assignment.runEpoch > request.assignment.runEpoch) {
+        throw new Error("an older run cannot install a Files session");
+      }
+      // A credential.changed frame changes an engine or MCP record inside the
+      // same lease. It does not replace the Files session, remount anything,
+      // or abort runtimeReady already under way. Retarget only the view used
+      // by a gate which the registry may reopen after a refused credential.
+      if (request.reason === "credential-change") {
+        const prior = [existing?.candidate, existing?.served].find(
+          (candidate): candidate is FilesCandidate => candidate?.view === request.previous,
+        );
+        if (
+          !existing ||
+          !sameAssignment(existing.assignment, request.assignment) ||
+          !prior ||
+          !sameFilesAccess(prior.access, request.files)
+        ) {
+          throw new Error("a Files credential change does not match its grant");
+        }
+        if (existing.gateOpen && !prior.controller.signal.aborted) {
+          // The normal case: preserve the exact candidate so a Files setup
+          // already in flight remains authoritative.
+          assertCandidate(existing, prior, undefined, prior === existing.served);
+          prior.view = request.next;
+          prior.installCurrent = request.isCurrent;
+          return;
+        }
+        // A refused credential closes the gate before its selective cleanup.
+        // Its candidate was aborted by that close, so give the same Files
+        // session a fresh authority which the registry can open afterwards.
+        const replacement: FilesCandidate = {
+          view: request.next,
+          access: request.files,
+          installCurrent: request.isCurrent,
+          controller: new AbortController(),
+        };
+        existing.candidate = replacement;
+        assertCandidate(existing, replacement);
+        return;
+      }
+      const controller = new AbortController();
+      const candidate: FilesCandidate = {
+        view: request.next,
+        access: request.files,
+        installCurrent: request.isCurrent,
+        controller,
+      };
+      let state: FilesState;
+      if (!existing || existing.assignment.runEpoch < request.assignment.runEpoch) {
+        if (existing?.candidate && existing.candidate !== existing.served) {
+          existing.candidate.controller.abort(abortError());
+        }
+        let recovered: ReturnType<typeof recoveredBinding>;
+        try {
+          recovered = recoveredBinding(request.assignment);
+        } catch (error) {
+          if (request.isCurrent()) {
+            terminalFailure(
+              request.assignment,
+              "setup-unproven",
+              error,
+              "the recovered task's Files boundary could not be reconstructed",
+            );
+          }
+          throw error;
+        }
+        state = {
+          assignment: { ...request.assignment },
+          candidate,
+          served: null,
+          binding: recovered
+            ? {
+                ...recovered,
+                environment: null,
+                mounted: false,
+                published: false,
+                mountIdentity: null,
+              }
+            : null,
+          gateOpen: false,
+          tail: Promise.resolve(),
+        };
+        states.set(request.assignment.taskId, state);
+      } else {
+        if (existing.candidate && existing.candidate !== existing.served) {
+          existing.candidate.controller.abort(abortError());
+        }
+        existing.candidate = candidate;
+        state = existing;
+      }
+      // A running/recovered runtime refreshes its credential_process session
+      // before the replacement grant can open.  A first grant has no binding
+      // yet and remains memory-only until runtimeReady.
+      if (state.binding) {
+        const binding = state.binding;
+        await queue(state, () => materialize(state, candidate, binding, undefined, false));
+      }
+      assertCandidate(state, candidate);
+    },
+
+    open(assignment, view): void {
+      const state = states.get(assignment.taskId);
+      if (
+        stopped ||
+        !state ||
+        !sameAssignment(state.assignment, assignment) ||
+        !state.candidate ||
+        state.candidate.view !== view ||
+        state.candidate.controller.signal.aborted
+      ) {
+        throw new Error("the Files gate cannot open on this grant");
+      }
+      const next = state.candidate;
+      const previous = state.served;
+      const binding = state.binding;
+      if (binding?.mounted && !binding.published) {
+        publishBoundary(state.assignment, binding, next.access);
+      }
+      state.served = next;
+      state.gateOpen = true;
+      if (previous && previous !== next) previous.controller.abort(abortError());
+    },
+
+    close(assignment): void {
+      const state = states.get(assignment.taskId);
+      if (!state || state.assignment.runEpoch > assignment.runEpoch) return;
+      state.gateOpen = false;
+      const served = state.served;
+      served?.controller.abort(abortError());
+      if (state.candidate !== served) state.candidate?.controller.abort(abortError());
+      if (state.binding) {
+        try {
+          // Do not trust `published`: a LINK helper may have crossed its
+          // final chmod before its caller lost the result. HIDE is
+          // idempotent and only removes the exact fixed-root link.
+          hide(state.binding.workspacePath);
+          state.binding.published = false;
+        } catch (error) {
+          throw terminalFailure(
+            state.assignment,
+            "visibility-unproven",
+            error,
+            "the task's Files boundary could not be hidden while its gate closed",
+          );
+        }
+      }
+    },
+
+    async runtimeReady(assignment, environment, mode, signal): Promise<void> {
+      const state = states.get(assignment.taskId);
+      if (!state || !sameAssignment(state.assignment, assignment)) {
+        throw new Error("the task has no Files session for this run");
+      }
+      const candidate = state.served;
+      if (!candidate || !state.gateOpen) {
+        throw new Error("the task's Files session is not open");
+      }
+      let binding: FilesBinding;
+      try {
+        assertCanonicalTaskMachineRuntime(assignment, environment);
+        const existing = state.binding;
+        const locator = serializeTaskEnvironmentLocator(environment.descriptor.locator);
+        if (existing) {
+          if (
+            serializeTaskEnvironmentLocator(existing.locator) !== locator ||
+            existing.workspacePath !== environment.descriptor.workspacePath ||
+            existing.mode !== mode
+          ) {
+            throw new Error("the run's Files runtime changed without cleanup");
+          }
+          // A lost-response task-up retry may hand over a newly fenced wrapper
+          // for the same runtime. Keep the established mount; only refresh the
+          // exact session and replace the callable handle.
+          existing.environment = environment;
+          binding = existing;
+        } else {
+          binding = {
+            locator: environment.descriptor.locator,
+            workspacePath: environment.descriptor.workspacePath,
+            mode,
+            environment,
+            mounted: false,
+            published: false,
+            mountIdentity: null,
+          };
+          state.binding = binding;
+        }
+      } catch (error) {
+        // This check and callback are deliberately synchronous. A lost-response
+        // retry may abort an older start for this same run, or a renewal may
+        // replace the candidate while setup is suspended; neither stale
+        // rejection is allowed to close the winner's grant.
+        let authoritative = false;
+        try {
+          assertCandidate(state, candidate, signal, true);
+          authoritative = true;
+        } catch {
+          // Stale/withdrawn setup: its owner performs no broader cleanup.
+        }
+        if (!authoritative) throw error;
+        // A runtime which did not pass the canonical identity checks cannot
+        // safely be used to prove the fixed mounts absent. This is an
+        // invariant failure rather than an ordinary provider/setup error.
+        throwAuthoritativeFailure(
+          assignment,
+          "setup-unproven",
+          error,
+          "the task's Files boundary could not be established",
+        );
+      }
+      await queue(state, async () => {
+        try {
+          await materialize(state, candidate, binding, signal, true);
+        } catch (error) {
+          // Compensation belongs to the serialized operation too. A retry
+          // queued behind this failure must not begin its mount while the
+          // failed attempt is still hiding or unmounting.
+          await compensateRuntimeReadyFailure(
+            state,
+            candidate,
+            binding,
+            environment,
+            signal,
+            error,
+          );
+        }
+      });
+    },
+
+    retire(assignment, error): void {
+      terminalFailure(
+        assignment,
+        "setup-unproven",
+        error,
+        "the task's Files boundary could not be established",
+      );
+    },
+
+    async closeConsumers(request: TaskCredentialCleanupRequest): Promise<void> {
+      const state = states.get(request.taskId);
+      // A selective credential cleanup never owns the Files session, but it
+      // still joins a write admitted before its gate closed.
+      if (request.credentialIds !== undefined) {
+        if (state && state.assignment.runEpoch <= request.runEpoch) {
+          await state.tail.catch(() => undefined);
+        }
+        return;
+      }
+      if (state && state.assignment.runEpoch <= request.runEpoch) {
+        state.gateOpen = false;
+        const served = state.served;
+        served?.controller.abort(abortError());
+        if (state.candidate !== served) state.candidate?.controller.abort(abortError());
+        await state.tail.catch(() => undefined);
+      }
+
+      const rows = list(request.taskId).filter(
+        (row) => row.lane === "files-session" && row.runEpoch <= request.runEpoch,
+      );
+      const newer = list(request.taskId).filter(
+        (row) => row.lane === "files-session" && row.runEpoch > request.runEpoch,
+      );
+      const newerLocators = new Set(newer.map((row) => row.runtimeLocator));
+      const locators = new Map<string, TaskEnvironmentLocator>();
+      for (const row of rows) {
+        if (!newerLocators.has(row.runtimeLocator)) {
+          locators.set(row.runtimeLocator, parseTaskEnvironmentLocator(row.runtimeLocator));
+        }
+      }
+      if (state?.binding && state.assignment.runEpoch <= request.runEpoch) {
+        const serialized = rows.find(
+          (row) => row.runtimeLocator === serializeTaskEnvironmentLocator(state.binding!.locator),
+        );
+        // The inventory normally supplies it.  Keep the live binding as a
+        // fallback for injected test stores that intentionally omit rows.
+        if (!serialized && newerLocators.size === 0) {
+          locators.set(serializeTaskEnvironmentLocator(state.binding.locator), state.binding.locator);
+        }
+      }
+      const failures: unknown[] = [];
+      for (const [serialized, locator] of locators) {
+        const stillOwnedByCleanup = (): boolean => {
+          const current = states.get(request.taskId);
+          if (current && current.assignment.runEpoch > request.runEpoch) return false;
+          return !list(request.taskId).some(
+            (row) =>
+              row.lane === "files-session" &&
+              row.runEpoch > request.runEpoch &&
+              row.runtimeLocator === serialized,
+          );
+        };
+        if (!stillOwnedByCleanup()) continue;
+        try {
+          // The runtime-ready handle is fenced by the task-up hold and is
+          // deliberately unusable once this cleanup closes the gate.  Rebuild
+          // an unfenced cleanup handle from the durable locator instead.
+          const environment = await reconstruct(locator);
+          if (environment.descriptor.taskId !== request.taskId) {
+            throw new Error("the Files cleanup runtime belongs to another task");
+          }
+          if (!stillOwnedByCleanup()) continue;
+          await unmount(environment, environment.descriptor.workspacePath, {
+            admit: () => {
+              if (!stillOwnedByCleanup()) {
+                throw new Error("a newer run owns the task's Files mounts");
+              }
+            },
+          });
+        } catch (error) {
+          // Ownership may transfer while the provider resolves the runtime.
+          // In that case the newer run's own setup/cleanup owns both fixed
+          // mountpoints; the obsolete cleanup must neither touch nor block it.
+          if (stillOwnedByCleanup()) failures.push(error);
+        }
+      }
+      if (failures.length > 0) {
+        throw terminalFailure(
+          { taskId: request.taskId, runEpoch: request.runEpoch },
+          "mount-retirement-unproven",
+          new AggregateError(failures, "the task's Files mounts could not be proven absent"),
+          "the task's Files mounts could not be proven absent",
+        );
+      }
+      if (state && state.assignment.runEpoch <= request.runEpoch) {
+        const continuingReason = request.lease?.reason;
+        const continues =
+          state.assignment.runEpoch === request.runEpoch &&
+          (continuingReason === "denied" ||
+            continuingReason === "expired" ||
+            continuingReason === "minimum-revision" ||
+            continuingReason === "manifest-narrowed" ||
+            continuingReason === "cleanup-failed" ||
+            continuingReason === "fence-failed");
+        if (continues && state.binding) {
+          // The registry asks for another grant after these cleanups. Keep
+          // only non-secret runtime identity, and force its next install to
+          // reconstruct and establish the fixed mounts before the gate opens.
+          state.binding.environment = null;
+          state.binding.mounted = false;
+          state.binding.published = false;
+          state.binding.mountIdentity = null;
+          state.candidate = null;
+          state.served = null;
+        } else {
+          states.delete(request.taskId);
+        }
+      }
+    },
+
+    shutdown(): void {
+      stopped = true;
+      for (const state of states.values()) {
+        state.candidate?.controller.abort(abortError());
+        if (state.served !== state.candidate) state.served?.controller.abort(abortError());
+      }
+      states.clear();
+    },
+  };
+}