@runuai/host 0.9.149 → 0.9.151

package/db/migrations/0027_cloud_credential_foundation.sql

@@ -0,0 +1,51 @@
+-- ADR-154 runner persistence foundation. A run epoch is non-secret
+-- assignment identity; cleanup rows contain paths and ids only, never values.
+ALTER TABLE `uai_host_tasks` ADD `run_epoch` integer NOT NULL DEFAULT 0
+  CONSTRAINT `uai_host_tasks_run_epoch` CHECK (`run_epoch` >= 0);
+--> statement-breakpoint
+CREATE TABLE `host_task_run_assignments` (
+	`task_id` text PRIMARY KEY NOT NULL,
+	`highest_run_epoch` integer NOT NULL,
+	`assignment_open` integer NOT NULL DEFAULT 1,
+	`created_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
+	`updated_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
+	CONSTRAINT `host_task_run_assignments_epoch` CHECK (`highest_run_epoch` >= 1),
+	CONSTRAINT `host_task_run_assignments_open` CHECK (`assignment_open` IN (0, 1)),
+	CONSTRAINT `host_task_run_assignments_task_id` CHECK (length(`task_id`) > 0)
+);
+--> statement-breakpoint
+CREATE TABLE `host_credential_cleanup_paths` (
+	`task_id` text NOT NULL,
+	`run_epoch` integer NOT NULL,
+	`runtime_locator` text NOT NULL,
+	`lane` text NOT NULL,
+	`path` text NOT NULL,
+	`credential_id` text NOT NULL,
+	`created_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
+	`updated_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
+	PRIMARY KEY(`task_id`, `run_epoch`, `runtime_locator`, `path`),
+	CONSTRAINT `host_credential_cleanup_paths_run_epoch` CHECK (`run_epoch` >= 1),
+	CONSTRAINT `host_credential_cleanup_paths_identity` CHECK (
+		length(`task_id`) > 0 AND length(`runtime_locator`) > 0 AND length(`credential_id`) > 0
+	),
+	CONSTRAINT `host_credential_cleanup_paths_lane` CHECK (
+		`lane` IN ('engine-auth', 'github', 'ssh', 'files-session')
+	),
+	CONSTRAINT `host_credential_cleanup_paths_absolute_path` CHECK (substr(`path`, 1, 1) = '/')
+);
+--> statement-breakpoint
+CREATE INDEX `host_credential_cleanup_paths_task_credential_idx`
+	ON `host_credential_cleanup_paths` (`task_id`, `run_epoch`, `credential_id`);
+--> statement-breakpoint
+CREATE TABLE `host_credential_cleanup_pending` (
+	`task_id` text PRIMARY KEY NOT NULL,
+	`run_epoch` integer NOT NULL,
+	`reason` text NOT NULL,
+	`created_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
+	`updated_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
+	CONSTRAINT `host_credential_cleanup_pending_run_epoch` CHECK (`run_epoch` >= 1),
+	CONSTRAINT `host_credential_cleanup_pending_reason` CHECK (
+		`reason` IN ('removed', 'denied', 'expired', 'assignment', 'restart', 'stop', 'park', 'teardown')
+	),
+	CONSTRAINT `host_credential_cleanup_pending_task_id` CHECK (length(`task_id`) > 0)
+);

package/db/migrations/0028_leased_engine_runtimes.sql

@@ -0,0 +1,11 @@
+CREATE TABLE `host_leased_engine_runtimes` (
+	`task_id` text NOT NULL,
+	`run_epoch` integer NOT NULL,
+	`runtime_locator` text NOT NULL,
+	`created_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
+	PRIMARY KEY(`task_id`, `run_epoch`, `runtime_locator`),
+	CONSTRAINT `host_leased_engine_runtimes_run_epoch` CHECK (`run_epoch` >= 1),
+	CONSTRAINT `host_leased_engine_runtimes_identity` CHECK (
+		length(`task_id`) > 0 AND length(`runtime_locator`) > 0
+	)
+);

package/db/migrations/meta/_journal.json

@@ -190,6 +190,20 @@
       "when": 1788900000008,
       "tag": "0026_project_env_replica",
       "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "6",
+      "when": 1791331200000,
+      "tag": "0027_cloud_credential_foundation",
+      "breakpoints": true
+    },
+    {
+      "idx": 28,
+      "version": "6",
+      "when": 1791331200001,
+      "tag": "0028_leased_engine_runtimes",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -21,6 +21,11 @@ export const hostTasks = sqliteTable(
   "uai_host_tasks",
   {
     taskId: text("task_id").primaryKey(),
+    // ADR-154: the v1 epoch whose runtime was successfully established.
+    // Admission's monotonic floor lives separately so deleting this recovery
+    // row can never make an older dispatch current again. 0 means no v1
+    // runtime has been proven for this row (including every legacy row).
+    runEpoch: integer("run_epoch").notNull().default(0),
     codeServerPort: integer("code_server_port"),
     previewPorts: text("preview_ports").notNull().default("[]"),
     composeProject: text("compose_project"),
@@ -57,6 +62,10 @@ export const hostTasks = sqliteTable(
       .default(sql`(unixepoch() * 1000)`),
   },
   (table) => ({
+    runEpochCheck: check(
+      "uai_host_tasks_run_epoch",
+      sql`${table.runEpoch} >= 0`,
+    ),
     environmentPair: check(
       "uai_host_tasks_environment_pair",
       sql`(${table.environmentProvider} IS NULL) = (${table.environmentLocator} IS NULL)`,
@@ -67,6 +76,185 @@ export const hostTasks = sqliteTable(
 export type HostTask = typeof hostTasks.$inferSelect;
 export type NewHostTask = typeof hostTasks.$inferInsert;
 
+// ADR-154's non-secret assignment authority. It intentionally has no foreign
+// key to uai_host_tasks: terminal-history retention and orphan GC may remove a
+// runtime row, but neither is allowed to erase the highest epoch this runner
+// has admitted or reopen a closed assignment.
+export const hostTaskRunAssignments = sqliteTable(
+  "host_task_run_assignments",
+  {
+    taskId: text("task_id").primaryKey(),
+    highestRunEpoch: integer("highest_run_epoch").notNull(),
+    assignmentOpen: integer("assignment_open", { mode: "boolean" })
+      .notNull()
+      .default(true),
+    createdAt: integer("created_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+    updatedAt: integer("updated_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+  },
+  (table) => ({
+    runEpochCheck: check(
+      "host_task_run_assignments_epoch",
+      sql`${table.highestRunEpoch} >= 1`,
+    ),
+    assignmentOpenCheck: check(
+      "host_task_run_assignments_open",
+      sql`${table.assignmentOpen} IN (0, 1)`,
+    ),
+    taskIdCheck: check(
+      "host_task_run_assignments_task_id",
+      sql`length(${table.taskId}) > 0`,
+    ),
+  }),
+);
+
+export type HostTaskRunAssignment =
+  typeof hostTaskRunAssignments.$inferSelect;
+export type NewHostTaskRunAssignment =
+  typeof hostTaskRunAssignments.$inferInsert;
+
+// ADR-154: values never land here. This is only the durable witness needed
+// to remove a task-local credential file after a runner crash. The exact
+// runtime locator is part of the key because a later run may recreate the
+// same task id on a different container or VM.
+export const hostCredentialCleanupPaths = sqliteTable(
+  "host_credential_cleanup_paths",
+  {
+    taskId: text("task_id").notNull(),
+    runEpoch: integer("run_epoch").notNull(),
+    runtimeLocator: text("runtime_locator").notNull(),
+    lane: text("lane", {
+      enum: ["engine-auth", "github", "ssh", "files-session"],
+    }).notNull(),
+    path: text("path").notNull(),
+    credentialId: text("credential_id").notNull(),
+    createdAt: integer("created_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+    updatedAt: integer("updated_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+  },
+  (table) => ({
+    pk: primaryKey({
+      columns: [
+        table.taskId,
+        table.runEpoch,
+        table.runtimeLocator,
+        table.path,
+      ],
+    }),
+    taskCredentialIdx: index(
+      "host_credential_cleanup_paths_task_credential_idx",
+    ).on(table.taskId, table.runEpoch, table.credentialId),
+    runEpochCheck: check(
+      "host_credential_cleanup_paths_run_epoch",
+      sql`${table.runEpoch} >= 1`,
+    ),
+    identityCheck: check(
+      "host_credential_cleanup_paths_identity",
+      sql`length(${table.taskId}) > 0 AND length(${table.runtimeLocator}) > 0 AND length(${table.credentialId}) > 0`,
+    ),
+    laneCheck: check(
+      "host_credential_cleanup_paths_lane",
+      sql`${table.lane} IN ('engine-auth', 'github', 'ssh', 'files-session')`,
+    ),
+    absolutePathCheck: check(
+      "host_credential_cleanup_paths_absolute_path",
+      sql`substr(${table.path}, 1, 1) = '/'`,
+    ),
+  }),
+);
+
+export type HostCredentialCleanupPath =
+  typeof hostCredentialCleanupPaths.$inferSelect;
+export type NewHostCredentialCleanupPath =
+  typeof hostCredentialCleanupPaths.$inferInsert;
+
+// A task remains fail-closed across a host crash even when cleanup has not yet
+// reached (or has already deleted) an inventoried path. This row contains no
+// credential value; it is cleared only after the entire cleanup procedure has
+// completed successfully through the recorded epoch.
+export const hostCredentialCleanupPending = sqliteTable(
+  "host_credential_cleanup_pending",
+  {
+    taskId: text("task_id").primaryKey(),
+    runEpoch: integer("run_epoch").notNull(),
+    reason: text("reason", {
+      enum: [
+        "removed",
+        "denied",
+        "expired",
+        "assignment",
+        "restart",
+        "stop",
+        "park",
+        "teardown",
+      ],
+    }).notNull(),
+    createdAt: integer("created_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+    updatedAt: integer("updated_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+  },
+  (table) => ({
+    runEpochCheck: check(
+      "host_credential_cleanup_pending_run_epoch",
+      sql`${table.runEpoch} >= 1`,
+    ),
+    reasonCheck: check(
+      "host_credential_cleanup_pending_reason",
+      sql`${table.reason} IN ('removed', 'denied', 'expired', 'assignment', 'restart', 'stop', 'park', 'teardown')`,
+    ),
+    taskIdCheck: check(
+      "host_credential_cleanup_pending_task_id",
+      sql`length(${table.taskId}) > 0`,
+    ),
+  }),
+);
+
+export type HostCredentialCleanupPending =
+  typeof hostCredentialCleanupPending.$inferSelect;
+export type NewHostCredentialCleanupPending =
+  typeof hostCredentialCleanupPending.$inferInsert;
+
+// ADR-154 §6: every runtime a leased engine of a task's run was started in,
+// recorded before it starts. An env-token engine leaves no credential file
+// for the cleanup inventory to name, yet the cleanup must prove it stopped
+// wherever it ran, an older runtime included. Value-free.
+export const hostLeasedEngineRuntimes = sqliteTable(
+  "host_leased_engine_runtimes",
+  {
+    taskId: text("task_id").notNull(),
+    runEpoch: integer("run_epoch").notNull(),
+    runtimeLocator: text("runtime_locator").notNull(),
+    createdAt: integer("created_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+  },
+  (table) => ({
+    pk: primaryKey({
+      columns: [table.taskId, table.runEpoch, table.runtimeLocator],
+    }),
+    runEpochCheck: check(
+      "host_leased_engine_runtimes_run_epoch",
+      sql`${table.runEpoch} >= 1`,
+    ),
+    identityCheck: check(
+      "host_leased_engine_runtimes_identity",
+      sql`length(${table.taskId}) > 0 AND length(${table.runtimeLocator}) > 0`,
+    ),
+  }),
+);
+
+export type HostLeasedEngineRuntime =
+  typeof hostLeasedEngineRuntimes.$inferSelect;
+
 // Singleton host-local settings row (ADR-100). Runtime switches that must be
 // visible before SQLite opens remain in `.env.local`; retention policy belongs
 // here because it governs owner-facing local history only. Correctness

package/lib/agent-cli.ts

@@ -12,7 +12,6 @@
  * (surfaced in the system preamble).
  */
 import {
-  chmodSync,
   lstatSync,
   mkdirSync,
   readFileSync,
@@ -30,6 +29,7 @@ import { signTaskToken } from "./task-token";
 import { assertSafeHostTaskId } from "./task-identity";
 import type { RosterAgent } from "./agents/types";
 import type { TaskEnvironmentAgentSessionSurface } from "./task-environment/types";
+import { makeContainedDirectoriesSync, writeContainedFile } from "./task-environment/workspace-files";
 
 /** Container path of the CLI — what the preamble tells agents to run. */
 export const CONTAINER_CLI_PATH = "/workspace/.uai/cli.mjs";
@@ -118,12 +118,12 @@ export function apiUrlFromCloudUrl(cloudUrl: string | undefined): string | null
  * dispatch). The latter is explicit rather than globally minting empty-power
  * tokens for every task.
  */
-export function writeAgentCli(
+export async function writeAgentCli(
   taskId: string,
   roster: RosterAgent[],
   apiUrl: string | null,
   allowPermissionless = false,
-): boolean {
+): Promise<boolean> {
   if (
     !apiUrl ||
     (rosterPermissions(roster).length === 0 && !allowPermissionless)
@@ -131,16 +131,14 @@ export function writeAgentCli(
     return false;
   }
   try {
-    const dir = resolve(taskWorkspaceDir(taskId), ".uai");
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(resolve(dir, "uai.json"), `${JSON.stringify({ apiUrl }, null, 2)}\n`);
-    const cliPath = resolve(dir, "cli.mjs");
-    writeFileSync(cliPath, CLI_SOURCE);
-    try {
-      chmodSync(cliPath, 0o755);
-    } catch {
-      // best-effort
-    }
+    // Into the task's own .uai, never through a link the task put there
+    // (#cb3j0z). The workspace root is the runner's own path; .uai, directly
+    // below it, is made if gone without following a link.
+    const workspace = taskWorkspaceDir(taskId);
+    mkdirSync(workspace, { recursive: true });
+    makeContainedDirectoriesSync(workspace, [".uai"]);
+    await writeContainedFile(workspace, [".uai", "uai.json"], Buffer.from(`${JSON.stringify({ apiUrl }, null, 2)}\n`));
+    await writeContainedFile(workspace, [".uai", "cli.mjs"], Buffer.from(CLI_SOURCE), { mode: 0o755 });
     return true;
   } catch {
     return false;

package/lib/agent.ts

@@ -16,6 +16,7 @@
  */
 
 import { spawn } from "node:child_process";
+import { chmodSync, existsSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
@@ -32,18 +33,63 @@ import { containerRuntimeStandardAssetsRoot } from "./container-runtime";
 import { getDecryptedForProject } from "./host-env";
 import { PreviewPortRuntimesSchema } from "./preview-ports";
 import { getHostTask } from "./runtime-state";
+import { ENGINE_CREDENTIAL_ENV_NAMES } from "./engine-credential-env";
 import { activeSecretsProxy } from "./secrets-proxy/host";
 import { closeTaskUpTrustSteps, finishTaskUpTrustSteps, writeTaskUpTrustSteps } from "./secrets-proxy/task-trust";
 import { removeTaskIdentity, writeTaskIdentity } from "./ssh";
+import type { TaskGitCredentialHold } from "./credential-consumers/github";
+import type { TaskWriteEnvironment } from "./credential-consumers/task-files";
+import { serveCloneCredentials, type CloneCredentialService } from "./git-clone-credentials";
 import { taskGatewayHost } from "./mcp-gateway";
 import type { ProjectEnvMode } from "./task-environment/types";
 import { isProjectEnvSchemaObservation, type ProjectEnvSchemaObservation, type TaskDownInput, type TaskLaunchInput } from "../src/protocol";
 
 export type { TaskLaunchInput } from "../src/protocol";
 
+/**
+ * ADR-154 §12: a start on cloud credentials. Only ever whole: the hold and
+ * the runtime-ready writes come together, so no such start reaches its
+ * runtime without what the runner writes into it.
+ */
+export interface LeasedTaskUp {
+  /**
+   * The owner's GitHub sign-in and SSH key, held for this start
+   * (`holdTaskGitCredentials`). The host-side clone reaches them only
+   * through this process's own sockets, for as long as task-up runs; a hold
+   * taken back aborts task-up. No key file is written and the runner's own
+   * store is never read.
+   */
+  clone: TaskGitCredentialHold;
+  /**
+   * The task's runtime exists and nothing in it has run yet (task-up pauses
+   * before uai-init, a machine before its clones): write what the runner
+   * writes into it, its owner's GitHub configuration and SSH key recorded
+   * for cleanup, before anything that may need them runs. A rejection stops
+   * the start.
+   */
+  runtimeReady: (environment: TaskWriteEnvironment, signal: AbortSignal) => Promise<void>;
+}
+
+/** Refuses a start on cloud credentials that is not whole, or not this
+ *  start's: before anything is provisioned, cloned or written. */
+export function assertLeasedTaskUp(
+  leased: LeasedTaskUp | undefined,
+  task: { id: string; runEpoch?: number },
+): void {
+  if (leased === undefined) return;
+  if (!leased.clone || typeof leased.runtimeReady !== "function") {
+    throw new Error("a start on cloud credentials needs its hold and its runtime-ready writes together");
+  }
+  if (leased.clone.assignment.taskId !== task.id || leased.clone.assignment.runEpoch !== task.runEpoch) {
+    throw new Error("the credentials held for this start are another task's or another run's");
+  }
+}
+
 export interface TaskUpCredentials {
   /** Path to the task owner's private, ephemeral Git credential cache. */
   githubCredentialSocket?: string;
+  /** ADR-154 §12: a task on cloud credentials. */
+  leased?: LeasedTaskUp;
   /** Fresh ADR-153 generation credential. The raw bytes are forwarded only
    * over stdin and are never serialized into a task row, argv, or env. */
   taskGateway?: {
@@ -156,6 +202,15 @@ export class AgentError extends Error {
 // Internal: run an agent script and parse the JSON envelope.
 // ---------------------------------------------------------------------------
 
+/** How long a withdrawn script has to end on SIGTERM before SIGKILL. */
+const WITHDRAWN_KILL_GRACE_MS = 5_000;
+
+/** What a start on cloud credentials says when they were withdrawn under it. */
+export const CREDENTIALS_WITHDRAWN_MESSAGE =
+  "The task's credentials were withdrawn while it was starting: removed, refused or replaced in the cloud. Start the task again.";
+/** How often task-up's handshake directory is looked at for its events. */
+const HANDSHAKE_POLL_MS = 100;
+
 async function runAgent<T extends z.ZodTypeAny>(
   scriptName: string,
   args: string[],
@@ -163,13 +218,25 @@ async function runAgent<T extends z.ZodTypeAny>(
   commandDbPath: string,
   extraEnv: Record<string, string> = {},
   stdinPayload?: string,
+  /** Aborted when what the script runs on is withdrawn (ADR-154): the
+   *  script and everything it started, its process group, end. */
+  withdrawn?: AbortSignal,
+  /** Names the script never inherits from the runner's own environment
+   *  (ADR-154: a start on cloud credentials gets none of the runner's). */
+  withoutRunnerEnv: ReadonlySet<string> = new Set(),
 ): Promise<z.infer<T>> {
   const scriptPath = resolve(agentDir(), scriptName);
+  const runnerEnv = Object.fromEntries(
+    Object.entries(process.env).filter(([name]) => !withoutRunnerEnv.has(name)),
+  );
 
   const child = spawn(scriptPath, args, {
+    // Its own process group when it may be withdrawn, so ending it ends
+    // every git and container CLI it started.
+    detached: withdrawn !== undefined,
     stdio: [stdinPayload === undefined ? "ignore" : "pipe", "pipe", "pipe"],
     env: {
-      ...process.env,
+      ...runnerEnv,
       UAI_DB_PATH: commandDbPath,
       UAI_DATA_DIR: env.dataDir,
       UAI_STANDARD_CONTAINER_ASSETS_DIR:
@@ -195,10 +262,35 @@ async function runAgent<T extends z.ZodTypeAny>(
     child.stdin.end(stdinPayload);
   }
 
-  const exitCode: number = await new Promise((res, rej) => {
-    child.on("error", rej);
-    child.on("close", (code) => res(code ?? 0));
-  });
+  let killTimer: ReturnType<typeof setTimeout> | undefined;
+  const endGroup = (signal: NodeJS.Signals): void => {
+    try {
+      if (child.pid !== undefined) process.kill(-child.pid, signal);
+    } catch {
+      // Already gone.
+    }
+  };
+  const onWithdrawn = (): void => {
+    endGroup("SIGTERM");
+    killTimer = setTimeout(() => endGroup("SIGKILL"), WITHDRAWN_KILL_GRACE_MS);
+  };
+  if (withdrawn?.aborted) onWithdrawn();
+  else withdrawn?.addEventListener("abort", onWithdrawn, { once: true });
+
+  let exitCode: number;
+  try {
+    exitCode = await new Promise((res, rej) => {
+      child.on("error", rej);
+      child.on("close", (code) => res(code ?? 0));
+    });
+  } finally {
+    withdrawn?.removeEventListener("abort", onWithdrawn);
+    clearTimeout(killTimer);
+  }
+  if (withdrawn?.aborted) {
+    endGroup("SIGKILL");
+    throw new AgentError("CREDENTIALS_WITHDRAWN", CREDENTIALS_WITHDRAWN_MESSAGE, { exitCode });
+  }
 
   // Try to parse whichever stream has the JSON. On failure the agent puts
   // its envelope on stderr; on success, on stdout.
@@ -321,11 +413,74 @@ export const agent = {
     input: TaskLaunchInput,
     credentials: TaskUpCredentials = {},
     envMode: ProjectEnvMode = "baked",
+    /** The task's runtime as the provider reaches it once task-up has
+     *  created it: where `credentials.leased.runtimeReady` writes. */
+    runtimeEnvironment?: () => TaskWriteEnvironment,
   ): Promise<TaskUpResult> {
+    const leased = credentials.leased;
+    if (leased && credentials.githubCredentialSocket) {
+      throw new Error("a task on cloud credentials never uses the runner's own GitHub credential");
+    }
+    assertLeasedTaskUp(leased, input.task);
+    if (leased && !runtimeEnvironment) {
+      throw new Error("this runtime cannot pause task-up for its runtime-ready writes");
+    }
     const commandDbPath = createTaskUpCommandDb(input);
     // Materialize the creator's per-user SSH key for commit signing and the
-    // explicit no-GitHub-connection transport fallback (ADR-029).
-    const identityDir = writeTaskIdentity(input.task.id, input.task.ownerUserId);
+    // explicit no-GitHub-connection transport fallback (ADR-029). A task on
+    // cloud credentials gets no key file: the runner writes the task's key
+    // itself, and serves the clone's from memory.
+    const identityDir = leased ? null : writeTaskIdentity(input.task.id, input.task.ownerUserId);
+    let cloneService: CloneCredentialService | null = null;
+    // ADR-154 §12: task-up says where it is with event files in a private
+    // directory (event-clone-done, then event-runtime-ready), never on the
+    // stderr its subprocesses share, and finds the runtime-ready answer
+    // there. Each event is taken once, in order. The runtime-ready writes
+    // are one operation, abortable by the hold, joined before task-up's
+    // outcome is returned whatever it is.
+    const handshakeDir = leased ? mkdtempSync(join("/tmp", "uai-task-handshake-")) : null;
+    if (handshakeDir) chmodSync(handshakeDir, 0o700);
+    let cloneDone = false;
+    let runtimeReadyWrites: Promise<void> | null = null;
+    const answer = (value: "continue" | "abort"): void => {
+      try {
+        const staged = join(handshakeDir!, ".runtime-ready");
+        writeFileSync(staged, `${value}\n`, { mode: 0o600 });
+        renameSync(staged, join(handshakeDir!, "runtime-ready"));
+      } catch {
+        // task-up already ended: nothing waits for the answer.
+      }
+    };
+    const takeEvents = (): void => {
+      if (!handshakeDir) return;
+      if (!cloneDone && existsSync(join(handshakeDir, "event-clone-done"))) {
+        cloneDone = true;
+        // The host's clones and fetches are over: stop serving them.
+        void cloneService?.close();
+      }
+      if (runtimeReadyWrites || !existsSync(join(handshakeDir, "event-runtime-ready"))) return;
+      if (!cloneDone) {
+        // Out of order: not task-up's.
+        runtimeReadyWrites = Promise.resolve();
+        answer("abort");
+        return;
+      }
+      runtimeReadyWrites = (async () => {
+        let value: "continue" | "abort" = "abort";
+        try {
+          const signal = leased!.clone.signal;
+          if (signal.aborted) throw new Error("the task's credentials were withdrawn");
+          await leased!.runtimeReady(runtimeEnvironment!(), signal);
+          value = "continue";
+        } catch (error) {
+          console.warn(
+            `[uai-agent] task ${input.task.id}: runtime-ready writes failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+        answer(value);
+      })();
+    };
+    const poller = handshakeDir ? setInterval(takeEvents, HANDSHAKE_POLL_MS) : null;
     try {
       // Per-(project, key) env values must NEVER enter task-up's host process
       // environment. Besides ordinary app names, projects can declare names such
@@ -348,6 +503,7 @@ export const agent = {
       const extraEnv: Record<string, string> = {
         UAI_PROJECT_ENV_MODE: envMode,
       };
+      if (handshakeDir) extraEnv.UAI_TASK_HANDSHAKE_DIR = handshakeDir;
       if (identityDir) extraEnv.UAI_TASK_IDENTITY_DIR = identityDir;
       // Only a non-secret socket path crosses into Bash. The token itself was
       // seeded over stdin and never enters argv, env, project data, Compose, or
@@ -356,6 +512,10 @@ export const agent = {
         extraEnv.UAI_GITHUB_CREDENTIAL_SOCKET =
           credentials.githubCredentialSocket;
       }
+      if (leased) {
+        cloneService = await serveCloneCredentials(leased.clone);
+        Object.assign(extraEnv, cloneService.env);
+      }
       let stdinPayload: string;
       if (envMode === "loader") {
         const gateway = credentials.taskGateway;
@@ -396,6 +556,10 @@ export const agent = {
           commandDbPath,
           extraEnv,
           stdinPayload,
+          leased?.clone.signal,
+          // ADR-154 §6: no default slot. A start on cloud credentials gets
+          // the runner's own engine sign-ins in neither its env nor files.
+          leased ? ENGINE_CREDENTIAL_ENV_NAMES : undefined,
         );
       } catch (error) {
         finishTaskUpTrustSteps(env.dataDir, input.task.id, null);
@@ -407,6 +571,12 @@ export const agent = {
       if (result.secretsProxyTrust === "failed") activeSecretsProxy()?.runtime.requestTrustDelivery();
       return result;
     } finally {
+      if (poller) clearInterval(poller);
+      // Joined, whatever task-up's outcome: nothing it began still writes
+      // into the task once this returns.
+      await runtimeReadyWrites;
+      await cloneService?.close();
+      if (handshakeDir) rmSync(handshakeDir, { recursive: true, force: true });
       closeTaskUpTrustSteps(env.dataDir, input.task.id);
       removeCommandDb(commandDbPath);
       removeTaskIdentity(input.task.id);