@runuai/host 0.9.151 → 0.9.153

package/lib/sidecar-resume.ts

@@ -37,6 +37,10 @@ export interface SidecarResumeDeps {
     workspacePath: string,
     task: { sharedFiles?: string },
   ) => Promise<string | null>;
+  /** ADR-154 Files v1: install and mount the exact recovered run's session
+   * from trusted host state.  Unlike the legacy marker path, failure is
+   * terminal for this recovery setup and is not converted to a warning. */
+  prepareFiles?: (handle: TaskEnvironmentHandle<unknown>) => Promise<void>;
   loader?: (handle: TaskEnvironmentHandle<unknown>) => Promise<void>;
   editor?: (handle: TaskEnvironmentHandle<unknown>, workspacePath: string) => Promise<void>;
   proxy?: typeof reconcileSidecarTaskProxy;
@@ -100,6 +104,11 @@ export async function resumeSidecarTask(
   const ended = (): boolean => deps.signal?.aborted === true;
   const interrupted = (): SidecarResumeResult => ({ outcome: "interrupted", warnings });
 
+  if (deps.prepareFiles) {
+    if (ended()) return interrupted();
+    await deps.prepareFiles(handle);
+  }
+
   if (task.envMode === "loader") {
     if (ended()) return interrupted();
     try {

package/lib/task-credential-cleanup.ts

@@ -50,8 +50,13 @@ export interface TaskCredentialCleanupHooks {
   refuseNewWork(request: TaskCredentialCleanupRequest): void;
   closeGate(request: TaskCredentialCleanupRequest): void;
   drainWriters(request: TaskCredentialCleanupRequest): Promise<void>;
-  closeConsumers(request: TaskCredentialCleanupRequest): Promise<void>;
   quiesceProcesses(request: TaskCredentialCleanupRequest): Promise<void>;
+  /** Retire process-backed consumers after leased engine agents have
+   * quiesced. Other task processes may still hold Files; a strict unmount
+   * which cannot prove them gone is terminal machine retirement. Their
+   * synchronous gate-close hook has already made Files unavailable to new
+   * work. */
+  closeConsumers(request: TaskCredentialCleanupRequest): Promise<void>;
   dropMemory(request: TaskCredentialCleanupRequest): void;
 }
 
@@ -403,8 +408,20 @@ export class TaskCredentialCleanupCoordinator {
 
   async #run(request: TaskCredentialCleanupRequest): Promise<void> {
     await this.#deps.hooks.drainWriters(request);
-    await this.#deps.hooks.closeConsumers(request);
     await this.#deps.hooks.quiesceProcesses(request);
+    let consumersFailed = false;
+    let consumerError: unknown;
+    try {
+      await this.#deps.hooks.closeConsumers(request);
+    } catch (error) {
+      // A strict Files unmount can fail (for example, EBUSY) after every gate
+      // and writer has closed. The root-only session material must still be
+      // removed below. Keep its inventory rows and the pending-cleanup row as
+      // durable mount witnesses, then return this original proof failure so a
+      // later process retries the unmount from the recorded runtime locator.
+      consumersFailed = true;
+      consumerError = error;
+    }
 
     const allRows = listCredentialCleanupPaths(request.taskId, this.#deps.db);
     const selectedRows = selectRows(allRows, request);
@@ -428,10 +445,19 @@ export class TaskCredentialCleanupCoordinator {
       forgetRow(row, this.#deps.db);
     }
     let failed: HostCredentialCleanupPath[] = [];
-    for (const row of rows) {
+    // A consumer failure means some non-Files process may still hold its
+    // credential. Preserve every such path and its witness for the retry.
+    // Files is the exception: its root-only session must be revoked even
+    // when the already-hidden mount cannot yet be proven absent.
+    const removableRows = consumersFailed
+      ? rows.filter((row) => row.lane === "files-session")
+      : rows;
+    for (const row of removableRows) {
       try {
         await (this.#deps.removePath ?? removeCredentialCleanupPath)(row);
-        forgetRow(row, this.#deps.db);
+        if (!consumersFailed || row.lane !== "files-session") {
+          forgetRow(row, this.#deps.db);
+        }
       } catch {
         failed.push(row);
       }
@@ -439,7 +465,11 @@ export class TaskCredentialCleanupCoordinator {
 
     // A whole-task cleanup may prove absence by destroying the exact writable
     // runtime instead. Selective removal must never take this broader action.
-    if (request.credentialIds === undefined && failed.length > 0) {
+    if (
+      !consumersFailed &&
+      request.credentialIds === undefined &&
+      failed.length > 0
+    ) {
       const byRuntime = new Map<string, HostCredentialCleanupPath[]>();
       for (const row of failed) {
         if (row.lane === "files-session") continue;
@@ -481,6 +511,7 @@ export class TaskCredentialCleanupCoordinator {
       }
       failed = failed.filter((row) => !proven.has(row));
     }
+    if (consumersFailed) throw consumerError;
     if (failed.length > 0) {
       throw new TaskCredentialCleanupError(
         request.taskId,

package/lib/task-environment/machine-task-up.ts

@@ -188,6 +188,12 @@ function projectDirectoryName(slug: string): string {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug) || slug.includes("..")) {
     throw new Error(`unsafe project slug for machine clone: ${slug}`);
   }
+  // Files v1 publishes the task's leased S3 roots at this fixed workspace
+  // entry.  Refuse a project with the same name before clone can follow the
+  // published link and write repository data into the Files bucket.
+  if (slug === "files") {
+    throw new Error("the project slug files is reserved for shared files");
+  }
   return slug;
 }
 
@@ -947,6 +953,17 @@ export function createMachineHostTaskEnvironmentProvider(
     ): Promise<TaskEnvironmentProvisioned<TaskUpResult, TaskDownResult>> {
       const { input } = request;
       const envMode = request.envMode ?? "loader";
+      // Validate every task-controlled workspace directory before the
+      // provider is allowed to create a machine or a leased runtime-ready
+      // writer can publish anything into it.  Validating lazily in the clone
+      // loop is too late: an invalid later project would leave all of those
+      // earlier effects behind.
+      const projects = [...input.projects]
+        .sort((a, b) => a.position - b.position)
+        .map((project) => ({
+          project,
+          directoryName: projectDirectoryName(project.slug),
+        }));
       // ADR-154 §12: a task on cloud credentials holds its grant for the
       // whole start; withdrawn (its gate closed, a cleanup reached it), the
       // start stops wherever it is, its clone included, and the machine goes.
@@ -1060,10 +1077,7 @@ export function createMachineHostTaskEnvironmentProvider(
           );
           if (proxyWarning !== null) console.warn(`[machine] task ${request.taskId}: ${proxyWarning}`);
         }
-        const projects = [...input.projects].sort(
-          (a, b) => a.position - b.position,
-        );
-        const wantsGithub = projects.some((project) =>
+        const wantsGithub = projects.some(({ project }) =>
           isGithubRepoUrl(project.repoUrl),
         );
         // ADR-154 §12: a task on cloud credentials clones with the token its
@@ -1073,9 +1087,9 @@ export function createMachineHostTaskEnvironmentProvider(
           : clone
             ? clone.github && { accessToken: clone.github.token }
             : await deps.githubToken(input.task.ownerUserId);
-        for (const project of projects) {
+        for (const { project, directoryName } of projects) {
           if (clone?.signal.aborted) throw withdrawal();
-          const destination = `${workspacePath}/${projectDirectoryName(project.slug)}`;
+          const destination = `${workspacePath}/${directoryName}`;
           const outcome = await untilWithdrawn(
             cloneProject(
               own,
@@ -1106,20 +1120,22 @@ export function createMachineHostTaskEnvironmentProvider(
         envSchemas = await stage(captureMachineEnvSchemas(request.taskId, own, clones));
 
         // ADR-062 shared files: point-in-time copy (see copySharedFiles).
-        const sharedWarning = await stage(
-          (deps.sharedFiles ?? copySharedFiles)(own, workspacePath, {
-            ...(input.task.ownerOrgId ? { ownerOrgId: input.task.ownerOrgId } : {}),
-            ownerUserId: input.task.ownerUserId,
-            ...(input.task.sharedFiles ? { sharedFiles: input.task.sharedFiles } : {}),
-          }).catch((error: unknown) => {
-            console.warn(
-              `[machine] task ${request.taskId}: shared files copy failed: ${
-                error instanceof Error ? error.message : String(error)
-              }`,
+        const sharedWarning = leased?.filesV1
+          ? null
+          : await stage(
+              (deps.sharedFiles ?? copySharedFiles)(own, workspacePath, {
+                ...(input.task.ownerOrgId ? { ownerOrgId: input.task.ownerOrgId } : {}),
+                ownerUserId: input.task.ownerUserId,
+                ...(input.task.sharedFiles ? { sharedFiles: input.task.sharedFiles } : {}),
+              }).catch((error: unknown) => {
+                console.warn(
+                  `[machine] task ${request.taskId}: shared files copy failed: ${
+                    error instanceof Error ? error.message : String(error)
+                  }`,
+                );
+                return null;
+              }),
             );
-            return null;
-          }),
-        );
         if (sharedWarning) warnings.push(sharedWarning);
 
         // Codex default-slot credentials: the legacy delivery paths are all

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

@@ -100,9 +100,19 @@ export interface RuntimeNamespace {
 /** macOS (11 and later): fail if any component of the path is a link. */
 const O_NOFOLLOW_ANY = 0x20000000;
 const DIRECTORY = constants.O_RDONLY | constants.O_DIRECTORY;
-/** macOS: a directory, a link nowhere in its path (the last component
- *  refused by O_NOFOLLOW as well). */
-const DIRECTORY_NOFOLLOW_ANY = DIRECTORY | O_NOFOLLOW_ANY | constants.O_NOFOLLOW;
+/** macOS: a directory, a link nowhere in its path, the last component
+ *  included. Never with O_NOFOLLOW: O_NOFOLLOW_ANY already refuses a final
+ *  link, and macOS 27 rejects the two together with EINVAL (live
+ *  2026-10-11: every workspace read and write failed on the Studio). */
+const DARWIN = process.platform === "darwin";
+/** Elsewhere (tests forcing this mode on Linux, where O_NOFOLLOW_ANY means
+ *  nothing) O_NOFOLLOW stays, so a final link is still refused there. */
+const DIRECTORY_NOFOLLOW_ANY = DIRECTORY | O_NOFOLLOW_ANY | (DARWIN ? 0 : constants.O_NOFOLLOW);
+/** The flags one file is opened with in this mode: on macOS `flags` without
+ *  O_NOFOLLOW, which O_NOFOLLOW_ANY covers and cannot be combined with. */
+function nofollowAnyFlags(flags: number): number {
+  return (DARWIN ? flags & ~constants.O_NOFOLLOW : flags) | O_NOFOLLOW_ANY;
+}
 
 type Containment = "proc-fd" | "nofollow-any" | "verify";
 let containment: Containment | null = null;
@@ -128,7 +138,9 @@ function probeContainment(): Containment {
     }
   }
   if (process.platform === "darwin") {
-    const scratch = mkdtempSync(join(tmpdir(), "uai-nofollow-any-"));
+    // Resolved: macOS's temporary directory is below /var, itself a link,
+    // which O_NOFOLLOW_ANY refuses on every path through it.
+    const scratch = realpathSync(mkdtempSync(join(tmpdir(), "uai-nofollow-any-")));
     try {
       mkdirSync(join(scratch, "real"));
       writeFileSync(join(scratch, "real", "file"), "");
@@ -138,8 +150,23 @@ function probeContainment(): Containment {
         // Opened through the link: the flag is not honored here.
         return "verify";
       } catch (error) {
-        return (error as NodeJS.ErrnoException).code === "ELOOP" ? "nofollow-any" : "verify";
+        if ((error as NodeJS.ErrnoException).code !== "ELOOP") return "verify";
+      }
+      // The exact flags the real opens use must work on a plain file and
+      // directory too: a flag the kernel refuses in combination would
+      // otherwise fail every workspace operation, not just links.
+      try {
+        closeSync(
+          openSync(
+            join(scratch, "real", "file"),
+            nofollowAnyFlags(constants.O_WRONLY | constants.O_APPEND | constants.O_NONBLOCK | constants.O_NOFOLLOW),
+          ),
+        );
+        closeSync(openSync(join(scratch, "real"), DIRECTORY_NOFOLLOW_ANY));
+      } catch {
+        return "verify";
       }
+      return "nofollow-any";
     } finally {
       rmSync(scratch, { recursive: true, force: true });
     }
@@ -255,7 +282,7 @@ function openWithin(root: string, parts: readonly string[], flags: number): numb
       }
     }
     if (mode === "nofollow-any") {
-      return openSync(join(base, ...parts), finalFlags | O_NOFOLLOW_ANY, 0o644);
+      return openSync(join(base, ...parts), nofollowAnyFlags(finalFlags), 0o644);
     }
     // Neither: a read verifies what it opened; nothing is written.
     if ((flags & (constants.O_WRONLY | constants.O_RDWR | constants.O_CREAT)) !== 0) {

package/lib/task-files-machine-retirement.ts

@@ -0,0 +1,88 @@
+import type { TaskAssignment } from "./cloud-credential-leases";
+
+export type TaskFilesMachineRetirementReason =
+  | "setup-unproven"
+  | "visibility-unproven"
+  | "mount-retirement-unproven";
+
+export interface TaskFilesMachineRetirementRequest {
+  assignment: Readonly<TaskAssignment>;
+  reason: TaskFilesMachineRetirementReason;
+  error: Error;
+}
+
+/**
+ * Cutover-owned terminal path for a one-task machine whose Files boundary
+ * cannot be proved closed. The handler must synchronously quarantine local
+ * task work, then durably retry an authenticated exact-run machine-retirement
+ * request until the cloud acknowledges it or the machine dies. Exiting only
+ * the sidecar is explicitly insufficient: its systemd unit uses
+ * KillMode=process and leaves the task processes alive.
+ */
+export type TaskFilesMachineRetirementHandler = (
+  request: TaskFilesMachineRetirementRequest,
+) => undefined;
+
+let handler: TaskFilesMachineRetirementHandler | null = null;
+let retiring: TaskFilesMachineRetirementRequest | null = null;
+let handedOff = false;
+
+export function setTaskFilesMachineRetirementHandler(
+  next: TaskFilesMachineRetirementHandler | null,
+): void {
+  handler = next;
+}
+
+/** Files v1 must not be advertised, or activation entered, without this. */
+export function taskFilesMachineRetirementReady(): boolean {
+  return handler !== null && retiring === null;
+}
+
+export function requestTaskFilesMachineRetirement(
+  request: TaskFilesMachineRetirementRequest,
+): void {
+  if (!handler) {
+    throw new Error("task-machine Files retirement is not installed", {
+      cause: request.error,
+    });
+  }
+  if (retiring === null) {
+    // First exact failure wins before any callback: a reconnect/capability
+    // pass in the callback's first await can no longer advertise this machine.
+    retiring = request;
+  } else if (
+    retiring.assignment.taskId !== request.assignment.taskId ||
+    retiring.assignment.runEpoch !== request.assignment.runEpoch
+  ) {
+    return;
+  }
+  if (handedOff) return;
+  // A synchronous handoff failure must be retryable without reopening the
+  // capability or letting a later assignment replace the first failure.
+  // Once this returns, the handler owns durable retries itself.
+  const result: unknown = handler(retiring);
+  if (result !== undefined) {
+    // A JavaScript caller can evade the type even though `undefined` (rather
+    // than `void`) rejects async handlers in TypeScript. Observe a returned
+    // promise so its later rejection is not unhandled, but never count an
+    // asynchronous callback as the required synchronous handoff.
+    if (
+      typeof result === "object" &&
+      result !== null &&
+      "then" in result &&
+      typeof (result as { then?: unknown }).then === "function"
+    ) {
+      void Promise.resolve(result).catch(() => {});
+    }
+    throw new Error("task-machine Files retirement must be handed off synchronously");
+  }
+  handedOff = true;
+}
+
+/** Tests model a fresh machine process without weakening the production
+ * one-way latch. */
+export function resetTaskFilesMachineRetirementForTests(): void {
+  handler = null;
+  retiring = null;
+  handedOff = false;
+}

package/lib/task-files-readiness.ts

@@ -0,0 +1,127 @@
+import {
+  accessSync,
+  chmodSync,
+  constants,
+  lstatSync,
+  mkdirSync,
+  statfsSync,
+} from "node:fs";
+
+export const TASK_FILES_MOUNT_S3_PATH = "/usr/bin/mount-s3";
+export const TASK_FILES_FUSE_PATH = "/dev/fuse";
+export const TASK_FILES_HELPER_PATHS = [
+  "/usr/bin/python3",
+  "/usr/bin/env",
+  "/usr/bin/mountpoint",
+  "/usr/bin/umount",
+  "/bin/sh",
+] as const;
+export const TASK_FILES_RUNTIME_ROOT = "/run";
+export const TASK_FILES_SESSION_ROOT = "/run/uai";
+
+// linux/magic.h: credentials may be written only to a memory-backed runtime.
+export const TMPFS_MAGIC = 0x01021994;
+
+export type TaskFilesV1Readiness =
+  | { ready: true }
+  | {
+      ready: false;
+      reason:
+        | "not-task-machine"
+        | "not-root"
+        | "mount-s3-unavailable"
+        | "fuse-unavailable"
+        | "helper-unavailable"
+        | "run-not-tmpfs"
+        | "session-root-unsafe";
+    };
+
+export interface TaskFilesV1ReadinessDeps {
+  getuid(): number;
+  access(path: string, mode: number): void;
+  prepareSessionRoot(): void;
+  statfs(path: string): { type: number | bigint };
+}
+
+function prepareSessionRoot(): void {
+  try {
+    mkdirSync(TASK_FILES_SESSION_ROOT, { mode: 0o700 });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  const info = lstatSync(TASK_FILES_SESSION_ROOT);
+  if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== 0) {
+    throw new Error("the Files session root is not a root-owned directory");
+  }
+  chmodSync(TASK_FILES_SESSION_ROOT, 0o700);
+}
+
+const DEFAULT_DEPS: TaskFilesV1ReadinessDeps = {
+  getuid: () => process.getuid?.() ?? -1,
+  access: accessSync,
+  prepareSessionRoot,
+  statfs: (path) => statfsSync(path),
+};
+
+/**
+ * Local half of the Files-v1 capability check. Cloud mode is irrelevant: a
+ * machine advertises what this process can safely do before activation. Keep
+ * this synchronous so the connect capability frame cannot race a later
+ * prerequisite probe.
+ */
+export function taskFilesV1Readiness(
+  taskMachine: boolean,
+  deps: TaskFilesV1ReadinessDeps = DEFAULT_DEPS,
+): TaskFilesV1Readiness {
+  if (!taskMachine) return { ready: false, reason: "not-task-machine" };
+
+  let uid: number;
+  try {
+    uid = deps.getuid();
+  } catch {
+    return { ready: false, reason: "not-root" };
+  }
+  if (uid !== 0) return { ready: false, reason: "not-root" };
+
+  try {
+    deps.access(TASK_FILES_MOUNT_S3_PATH, constants.X_OK);
+  } catch {
+    return { ready: false, reason: "mount-s3-unavailable" };
+  }
+
+  try {
+    deps.access(TASK_FILES_FUSE_PATH, constants.R_OK | constants.W_OK);
+  } catch {
+    return { ready: false, reason: "fuse-unavailable" };
+  }
+
+  try {
+    for (const path of TASK_FILES_HELPER_PATHS) {
+      deps.access(path, constants.X_OK);
+    }
+  } catch {
+    return { ready: false, reason: "helper-unavailable" };
+  }
+
+  try {
+    if (Number(deps.statfs(TASK_FILES_RUNTIME_ROOT).type) !== TMPFS_MAGIC) {
+      return { ready: false, reason: "run-not-tmpfs" };
+    }
+  } catch {
+    return { ready: false, reason: "run-not-tmpfs" };
+  }
+
+  try {
+    deps.prepareSessionRoot();
+    // `/run` being tmpfs is insufficient: an existing `/run/uai` may be a
+    // bind mount onto persistent storage. Capability advertisement proves
+    // the exact directory in which the session will be written.
+    if (Number(deps.statfs(TASK_FILES_SESSION_ROOT).type) !== TMPFS_MAGIC) {
+      return { ready: false, reason: "session-root-unsafe" };
+    }
+  } catch {
+    return { ready: false, reason: "session-root-unsafe" };
+  }
+
+  return { ready: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.151",
+  "version": "0.9.153",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

package/src/cloud-credentials.ts

@@ -21,6 +21,16 @@
 /** Advertised by a runner that reads credentials only through v1 leases. */
 export const HOST_CLOUD_CREDENTIALS_FEATURE = "host-cloud-credentials-v1";
 
+/**
+ * Advertised by a task machine only when it can install a task-scoped Files
+ * session and mount it from the v1 grant. This is deliberately separate from
+ * the general credentials feature: owned runners do not need Files-on-machine
+ * support to leave the legacy credential mode. The cloud must require both
+ * features for a task machine's activation, taskUp dispatch and v1 lease;
+ * this advertisement alone is not an admission check.
+ */
+export const HOST_TASK_FILES_LEASE_FEATURE = "host-task-files-lease-v1";
+
 // ---------------------------------------------------------------------------
 // Parameter layout
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -26,6 +26,7 @@ import { writeTaskGithub, writeTaskSshKey } from "../lib/credential-consumers/gi
 import { agentClisReady, ensureStandardImage } from "../lib/standard-image";
 import { cloneRepo } from "../lib/repo-clone";
 import { handleFilesOp } from "../lib/shared-files";
+import type { SharedFilesMode } from "../lib/shared-files-s3";
 import {
   getOrchestrator,
   inspectTaskRuntimeContainer,
@@ -79,6 +80,7 @@ import {
   recordTaskOwner,
   recordTaskProjectEnvSpec,
   recordTaskRuntimeEstablished,
+  recordTaskSharedFilesMode,
   recordTaskStarting,
   recordTaskUpResult,
   taskProjectEnvSpec,
@@ -293,17 +295,32 @@ interface CloudCredentialTaskStart {
 /** The start's lease for task-up: its whole grant's hold, and what the
  *  runner writes into the runtime once it exists (the owner's GitHub sign-in
  *  and SSH key, recorded for cleanup) before anything in it runs. */
-function leasedTaskUp(start: TaskCredentialStart, hold: TaskUpHold): LeasedTaskUp {
+function leasedTaskUp(
+  runtime: CloudCredentialRuntime,
+  start: TaskCredentialStart,
+  hold: TaskUpHold,
+  filesMode: SharedFilesMode,
+): LeasedTaskUp {
+  const filesV1 = runtime.taskFilesV1();
   return {
     // The whole grant's signal: its gate closing, a cleanup reaching it or
     // the start being interrupted all end task-up.
     clone: { ...hold.git, signal: hold.signal },
     runtimeReady: async (environment, signal) => {
+      if (filesV1) {
+        await runtime.prepareTaskFiles(
+          start.assignment,
+          environment as TaskEnvironmentHandle<unknown>,
+          filesMode,
+          signal,
+        );
+      }
       for (const write of [writeTaskGithub, writeTaskSshKey]) {
         if (signal.aborted) throw new CredentialLeaseUnavailableError("the task's credentials were withdrawn");
         await write(environment, start.assignment);
       }
     },
+    ...(filesV1 ? { filesV1: true as const } : {}),
   };
 }
 
@@ -1138,6 +1155,7 @@ async function taskUpOn(
             environmentLocator: existingTask.environmentLocator,
             envMode: existingTask.envMode,
             projectEnvSpec: existingTask.projectEnvSpec,
+            sharedFilesMode: existingTask.sharedFilesMode,
             runEpoch: existingTask.runEpoch,
           }
         : {
@@ -1149,6 +1167,7 @@ async function taskUpOn(
             environmentLocator: existingTask.environmentLocator,
             envMode: existingTask.envMode,
             projectEnvSpec: existingTask.projectEnvSpec,
+            sharedFilesMode: existingTask.sharedFilesMode,
             runEpoch: existingTask.runEpoch,
           }
       : {
@@ -1173,6 +1192,12 @@ async function taskUpOn(
     } else {
       recordTaskStarting(input.task.id, input.task.runEpoch);
     }
+    // Files-v1 recovery gets its mode only from a launch already admitted on
+    // cloud credentials, never from the task-writable marker. A legacy start
+    // must leave the column null so cutover can distinguish and retire it.
+    const sharedFilesMode = cloud
+      ? recordTaskSharedFilesMode(input.task.id, input.task)
+      : null;
     // Cross-process managed maintenance and task admission use a two-sided
     // handshake: update/uninstall writes its durable marker before checking
     // this DB row; task-up writes `starting` before checking admission again.
@@ -1318,7 +1343,18 @@ async function taskUpOn(
               input,
               {
                 taskGateway,
-                ...(cloud?.start && cloud.hold ? { leased: leasedTaskUp(cloud.start, cloud.hold) } : {}),
+                ...(cloud?.start && cloud.hold
+                  ? {
+                      leased: leasedTaskUp(
+                        cloud.runtime,
+                        cloud.start,
+                        cloud.hold,
+                        sharedFilesMode ?? (() => {
+                          throw new Error("a cloud-credential start has no trusted Files mode");
+                        })(),
+                      ),
+                    }
+                  : {}),
               },
               recordPrepared,
             );