@runuai/host 0.9.150 → 0.9.151

package/lib/credential-consumers/engines.ts

@@ -0,0 +1,773 @@
+/**
+ * ADR-154 §6, §8, §10 on the runner: a task's AI accounts, from its lease.
+ *
+ * - The registry installs each grant and credential change here, in memory
+ *   for the task's run only. A grant is a candidate: spawns use exactly the
+ *   accounts of the view the registry opened its gate on (`openEngineGate`),
+ *   in the manifest's order, which per engine kind is the owner's personal
+ *   accounts, then the workspace's (§10). A credential change within the run
+ *   updates an account already served that is otherwise the same
+ *   (credential, revision, kind): a refreshed token, or its material
+ *   becoming readable again or no longer readable.
+ * - A task on cloud credentials never falls back to the runner's own store.
+ *   It has a record here from the registry's first callback for its
+ *   assignment (the gate closing at its start), closed until a grant opens
+ *   it: `leasedEnginesFor` is undefined only for a task that is not on cloud
+ *   credentials. An account the manifest names but the lease could not read
+ *   is served as unavailable, never as absent.
+ * - Env-token engines (Claude, Cursor, pasted API keys) take their account
+ *   at spawn as exec env values (`engineSpawnEnv`).
+ * - Config-directory engines (Codex, Grok sign-ins, OpenCode) read a
+ *   temporary task-local file: only the lane's files the lease-readable
+ *   parameter carries (`auth.json`, its refresh token the broker's
+ *   placeholder), in the account's home (`/home/node/.<kind>-acct-<id>`),
+ *   owned by `node`, 0600. Each is written only by streaming over an exec's
+ *   stdin through the no-follow writer, every path and intermediate
+ *   inventoried first. A home derived from the account's (Codex's per-agent
+ *   copy) is written the same way, never copied from it.
+ * - Before an account is served at a newer version than the run has
+ *   served, its older versions are held back in every runtime of the run
+ *   (§6): a launch admitted on one of them that has not started never will.
+ * - A changed credential rewrites only its lane's files, atomically, in
+ *   every home this run wrote it to (`syncEngineHomes`). A removed or
+ *   refused one is deleted from all of them by the cleanup coordinator, from
+ *   the inventory; nothing here deletes.
+ * - Writes for one task run one at a time, and each exec is admitted at the
+ *   provider's last moment against the task's live state: the same run, the
+ *   gate open, the account served readable at the same revision and version.
+ *   A cleanup closes the gate (or drops the accounts it names), then waits
+ *   for every write under way to end, so nothing it is about to delete can
+ *   be written again after.
+ */
+
+import {
+  CredentialLeaseUnavailableError,
+  type CredentialCleanupRequest,
+  type CredentialInstallRequest,
+  type TaskAssignment,
+  type TaskCredentialLeaseRegistry,
+  type TaskCredentialView,
+  type TaskEngineCredential,
+} from "../cloud-credential-leases";
+import { rememberCredentialCleanupPath } from "../credential-cleanup-inventory";
+import { idPathSegment, type CredentialScope } from "../../src/cloud-credentials";
+import type { EngineAdmissionFloor } from "./engine-anchor";
+import {
+  assertTaskRuntime,
+  runInTask,
+  TASK_HOME,
+  withStaged,
+  writeTaskFileArgv,
+  type TaskWriteEnvironment,
+} from "./task-files";
+
+/**
+ * Where a config-directory engine's account lives in the task, the variable
+ * that points the engine at it, and whether the engine reads it again at
+ * every turn (a one-shot CLI) or only when it starts (Codex's app-server,
+ * which must respawn to see a rewritten file).
+ */
+export const ENGINE_ACCOUNT_HOMES: Readonly<
+  Record<string, { selectVar: string; prefix: string; readsEachTurn: boolean }>
+> = Object.freeze({
+  codex: { selectVar: "CODEX_HOME", prefix: `${TASK_HOME}/.codex-acct-`, readsEachTurn: false },
+  grok: { selectVar: "GROK_HOME", prefix: `${TASK_HOME}/.grok-acct-`, readsEachTurn: true },
+  opencode: {
+    selectVar: "OPENCODE_DATA_DIR",
+    prefix: `${TASK_HOME}/.local/share/opencode-acct-`,
+    readsEachTurn: true,
+  },
+});
+
+/** A derived home's suffix: `<home>-agent-<agent>`. */
+const DERIVED_HOME_SUFFIX = /^-agent-[A-Za-z0-9_-]{1,128}$/;
+
+/** An account the task may use, readable, as the lease read it. */
+export interface LeasedEngineAccount {
+  credentialId: string;
+  revision: string;
+  engineKind: string;
+  scope: CredentialScope;
+  label: string;
+  authKind: "env" | "config-dir";
+  /** The lease parameter's version this material was read at. */
+  version: number;
+  /** Env-token accounts: the variables the engine's spawn takes. */
+  env: Readonly<Record<string, string>> | null;
+  /** Config-directory accounts: the lane's files, by name. */
+  files: Readonly<Record<string, string>> | null;
+  /** Config-directory accounts: the account's home in the task. */
+  home: string | null;
+  expiresAt: number | null;
+}
+
+/** An account the manifest names but the lease could not read, under the
+ *  identity it was named with: never used, never "no such account". */
+export interface UnavailableEngineAccount {
+  credentialId: string;
+  revision: string;
+  engineKind: string;
+  scope: CredentialScope;
+  label: string;
+  authKind: "env" | "config-dir";
+  home: string | null;
+  unavailable: true;
+}
+
+export type ServedEngineAccount = LeasedEngineAccount | UnavailableEngineAccount;
+
+export interface TaskEngineLease {
+  assignment: TaskAssignment;
+  /** False while the registry's gate is closed: spawn nothing. */
+  open: boolean;
+  /** In try order; empty while the gate is closed. */
+  accounts: readonly ServedEngineAccount[];
+}
+
+/** The registry's answer to a reactive refresh (the frozen contract). */
+type RefreshResult = Awaited<ReturnType<TaskCredentialLeaseRegistry["requestCredentialRefresh"]>>;
+
+export type EngineCredentialRefresher = (
+  assignment: TaskAssignment,
+  credentialId: string,
+  revision: string,
+) => Promise<Pick<RefreshResult, "outcome">>;
+
+interface WrittenHome {
+  credentialId: string;
+  revision: string;
+  /** Null while a write is under way or after one failed: stale until a
+   *  write completes. */
+  version: number | null;
+}
+
+interface TaskEngineState {
+  assignment: TaskAssignment;
+  /** The accounts of the view the gate opened on; null while it is closed. */
+  served: ServedEngineAccount[] | null;
+  /** The writes for this task, one after another. */
+  queue: Promise<void>;
+  /** Writes queued or under way and not yet ended. */
+  writing: number;
+  drained: Array<() => void>;
+  /** Every home this run wrote an account's files to, and what it wrote. */
+  written: Map<string, WrittenHome>;
+  /** The newest version this run served of each account's revision: a
+   *  newer one needs the runtimes' floors raised first. */
+  exposed: Map<string, number>;
+  /** The version below which this run admits nothing of each account's
+   *  revision. It rises before the runtimes' floors do and stays risen if
+   *  they could not: the next install of that version raises them again. */
+  heldBack: Map<string, number>;
+}
+
+const tasks = new Map<string, TaskEngineState>();
+/** Every record with writes queued or under way, the replaced ones
+ *  included: a cleanup waits for those of its run and every older one. */
+const writers = new Set<TaskEngineState>();
+const listeners = new Set<(taskId: string) => void>();
+let refresher: EngineCredentialRefresher | null = null;
+
+/** Holds back older versions of accounts in every runtime of the task's
+ *  run, before a newer one is served (engine-anchor.ts). */
+export type EngineAdmissionFloorRaiser = (
+  assignment: TaskAssignment,
+  floors: readonly EngineAdmissionFloor[],
+) => Promise<void>;
+let floorRaiser: EngineAdmissionFloorRaiser | null = null;
+
+/** Escalates a launch slot of this exact run that could not be retired in
+ *  its runtime (ADR-154 §6): the run's full credential cleanup, which
+ *  closes its gate first and proves no launch of it runs (the lease
+ *  registry's). */
+export type EngineLaunchFenceEscalator = (assignment: TaskAssignment) => void;
+let fenceEscalator: EngineLaunchFenceEscalator | null = null;
+
+/** The account's home in the task: null for a kind that reads no file. */
+export function engineAccountHome(engineKind: string, credentialId: string): string | null {
+  const home = ENGINE_ACCOUNT_HOMES[engineKind];
+  return home ? `${home.prefix}${idPathSegment(credentialId)}` : null;
+}
+
+function accountOf(credential: TaskEngineCredential): ServedEngineAccount {
+  const { manifest, material } = credential;
+  const home = manifest.authKind === "config-dir" ? engineAccountHome(manifest.engineKind, manifest.credentialId) : null;
+  const identity = {
+    credentialId: manifest.credentialId,
+    revision: manifest.revision,
+    engineKind: manifest.engineKind,
+    scope: manifest.scope,
+    label: manifest.label,
+    authKind: manifest.authKind,
+    home,
+  };
+  if (
+    credential.availability !== "available" ||
+    !material ||
+    credential.observedVersion === null ||
+    material.authKind !== manifest.authKind ||
+    (manifest.authKind === "config-dir" && home === null)
+  ) {
+    return { ...identity, unavailable: true };
+  }
+  return material.authKind === "env"
+    ? { ...identity, version: credential.observedVersion, env: { ...material.env }, files: null, expiresAt: null }
+    : {
+        ...identity,
+        version: credential.observedVersion,
+        env: null,
+        files: { ...material.files },
+        expiresAt: material.expiresAt,
+      };
+}
+
+function accountsOf(view: TaskCredentialView): ServedEngineAccount[] {
+  return view.engines.map(accountOf);
+}
+
+export function isLeasedEngineAccount(account: ServedEngineAccount | undefined): account is LeasedEngineAccount {
+  return account !== undefined && !("unavailable" in account);
+}
+
+/** The same account, all but its material (or whether it could be read). */
+function sameAccount(a: ServedEngineAccount, b: ServedEngineAccount): boolean {
+  return (
+    a.credentialId === b.credentialId &&
+    a.revision === b.revision &&
+    a.engineKind === b.engineKind &&
+    a.authKind === b.authKind
+  );
+}
+
+function sameAssignment(a: TaskAssignment, b: TaskAssignment): boolean {
+  return a.taskId === b.taskId && a.runEpoch === b.runEpoch;
+}
+
+function notify(taskId: string): void {
+  for (const listener of [...listeners]) {
+    try {
+      listener(taskId);
+    } catch {
+      // A listener's failure is its own; the others still hear.
+    }
+  }
+}
+
+/** The record for this run: the current one, or a fresh, closed one when
+ *  this is a newer run (whatever the last run had is closed with it). */
+function stateFor(assignment: TaskAssignment): TaskEngineState {
+  const current = tasks.get(assignment.taskId);
+  if (current && sameAssignment(current.assignment, assignment)) return current;
+  if (current) current.served = null;
+  const fresh: TaskEngineState = {
+    assignment: { taskId: assignment.taskId, runEpoch: assignment.runEpoch },
+    served: null,
+    queue: Promise.resolve(),
+    writing: 0,
+    drained: [],
+    written: new Map(),
+    exposed: new Map(),
+    heldBack: new Map(),
+  };
+  tasks.set(assignment.taskId, fresh);
+  return fresh;
+}
+
+/** True when `assignment` is older than the run this runner now holds. */
+function olderRun(assignment: TaskAssignment): boolean {
+  const current = tasks.get(assignment.taskId);
+  return current !== undefined && current.assignment.runEpoch > assignment.runEpoch;
+}
+
+function exposureKey(account: { credentialId: string; revision: string }): string {
+  return `${account.credentialId}\u0000${account.revision}`;
+}
+
+/** Note the versions `accounts` serve as served this run. */
+function expose(state: TaskEngineState, accounts: readonly ServedEngineAccount[]): void {
+  for (const account of accounts) {
+    if (!isLeasedEngineAccount(account)) continue;
+    const key = exposureKey(account);
+    state.exposed.set(key, Math.max(state.exposed.get(key) ?? 0, account.version));
+  }
+}
+
+/**
+ * A grant's install is a candidate: nothing of it is served until the
+ * registry opens its gate on it. A credential change of this run takes
+ * effect now, on an account already served that is otherwise the same.
+ * Before either can serve an account at a newer version than this run has
+ * served, the account's older versions are held back in every runtime of
+ * the run (§6, `setEngineAdmissionFloorRaiser`): a launch admitted on an
+ * older version that has not started never will. One that cannot be held
+ * back fails the install, and none of it is served.
+ */
+export async function installEngineCredentials(request: CredentialInstallRequest): Promise<void> {
+  if (olderRun(request.assignment)) return;
+  const current = tasks.get(request.assignment.taskId);
+  if (request.reason === "credential-change" && current && !sameAssignment(current.assignment, request.assignment)) {
+    return;
+  }
+  // On cloud credentials from its first install, closed until opened: never
+  // the runner's own store.
+  const state = stateFor(request.assignment);
+  const next = accountsOf(request.next);
+  const floors = next.filter(isLeasedEngineAccount).flatMap((account) => {
+    const served = state.exposed.get(exposureKey(account));
+    return served !== undefined && account.version > served
+      ? [{ credentialId: account.credentialId, revision: account.revision, version: account.version }]
+      : [];
+  });
+  // From here nothing older is admitted on this runner (`engineVersionHeldBack`):
+  // a launch checked after this is refused, and the floors revoke in the
+  // runtimes what was admitted before. A failed raise leaves it so, and does
+  // not count as raised: until the newer version is served, every install of
+  // it raises the floors again.
+  for (const floor of floors) {
+    const key = exposureKey(floor);
+    state.heldBack.set(key, Math.max(state.heldBack.get(key) ?? 0, floor.version));
+  }
+  if (floors.length > 0) {
+    // Nobody to hold them back in the runtimes is a raise that failed.
+    if (!floorRaiser) throw new Error("an AI account's older version could not be held back: no runtime is reachable");
+    await floorRaiser({ ...request.assignment }, floors);
+    // The run moved on meanwhile: this install is no longer its.
+    if (tasks.get(request.assignment.taskId) !== state) return;
+  }
+  if (request.reason !== "credential-change" || !state.served) return;
+  state.served = state.served.flatMap((served) => {
+    const proposed = next.find((account) => account.credentialId === served.credentialId);
+    // Gone from the view: never served past it, gate or not.
+    if (!proposed) return [];
+    return [sameAccount(served, proposed) ? proposed : served];
+  });
+  expose(state, state.served);
+  notify(request.assignment.taskId);
+}
+
+/** The registry opened its gate on this committed view: serve exactly its
+ *  accounts, in its order. An older run's opening changes nothing. */
+export function openEngineGate(assignment: TaskAssignment, view: TaskCredentialView): void {
+  if (olderRun(assignment)) return;
+  const state = stateFor(assignment);
+  state.served = accountsOf(view);
+  expose(state, state.served);
+  notify(assignment.taskId);
+}
+
+/**
+ * The registry closed its gate: spawn and write nothing for the task until
+ * it opens again. The first close (at the start of the task's first run
+ * here) is what puts the task on cloud credentials. A newer run's close
+ * closes the record it finds and does not replace it: the previous run's
+ * cleanup, which comes after, still finds its record and waits for its
+ * writes. The newer run's record comes with its first install.
+ */
+export function closeEngineGate(assignment: TaskAssignment): void {
+  if (olderRun(assignment)) return;
+  const current = tasks.get(assignment.taskId);
+  if (current) current.served = null;
+  else stateFor(assignment);
+  notify(assignment.taskId);
+}
+
+/**
+ * A cleanup: a full one closes the gate and forgets every home this run
+ * wrote, a selective one drops the accounts it names and their homes; then
+ * it waits for every write under way for the task's run, and any older
+ * run's, to end. The coordinator deletes the files, from the inventory.
+ */
+export async function cleanupEngineCredentials(request: CredentialCleanupRequest): Promise<void> {
+  const { taskId, runEpoch } = request.assignment;
+  const current = tasks.get(taskId);
+  if (current && sameAssignment(current.assignment, request.assignment)) {
+    if (request.mode === "full") {
+      current.served = null;
+      current.written.clear();
+    } else {
+      const removed = new Set(
+        request.removed.filter((identity) => identity.class === "engine").map((identity) => identity.credentialId),
+      );
+      if (current.served) current.served = current.served.filter((account) => !removed.has(account.credentialId));
+      for (const [home, written] of current.written) {
+        if (removed.has(written.credentialId)) current.written.delete(home);
+      }
+    }
+    notify(taskId);
+  } else if (request.mode === "full" && (!current || current.assignment.runEpoch < runEpoch)) {
+    // A full cleanup for a run never opened here still puts the task on
+    // cloud credentials, closed.
+    closeEngineGate(request.assignment);
+  }
+  await Promise.all(
+    [...writers]
+      .filter((state) => state.assignment.taskId === taskId && state.assignment.runEpoch <= runEpoch)
+      .map(drain),
+  );
+}
+
+function drain(state: TaskEngineState): Promise<void> {
+  if (state.writing === 0) return Promise.resolve();
+  return new Promise((resolve) => state.drained.push(resolve));
+}
+
+/** Process shutdown: every engine-home write under way, for any task, over.
+ *  With every gate closed nothing new is admitted, so this ends. */
+export function drainLeasedEngineWrites(): Promise<void> {
+  return Promise.all([...writers].map(drain)).then(() => undefined);
+}
+
+/** The task is gone (teardown): forget its record, this run's or an older
+ *  one's. A newer run's record stays: a delayed teardown never takes it. */
+export function forgetLeasedEngines(assignment: TaskAssignment): void {
+  const state = tasks.get(assignment.taskId);
+  if (!state || state.assignment.runEpoch > assignment.runEpoch) return;
+  state.served = null;
+  tasks.delete(assignment.taskId);
+  notify(assignment.taskId);
+}
+
+/** Whether this run has moved `account` past that version (or is moving it):
+ *  nothing is admitted on it any more, served or not. */
+export function engineVersionHeldBack(
+  assignment: TaskAssignment,
+  account: { credentialId: string; revision: string; version: number },
+): boolean {
+  const state = tasks.get(assignment.taskId);
+  if (!state || !sameAssignment(state.assignment, assignment)) return true;
+  const key = exposureKey(account);
+  return account.version < Math.max(state.exposed.get(key) ?? 0, state.heldBack.get(key) ?? 0);
+}
+
+/** The task's AI accounts, or undefined for a task that is not on cloud
+ *  credentials. */
+export function leasedEnginesFor(taskId: string): TaskEngineLease | undefined {
+  const state = tasks.get(taskId);
+  if (!state) return undefined;
+  return { assignment: { ...state.assignment }, open: state.served !== null, accounts: [...(state.served ?? [])] };
+}
+
+/** The live, open record for this exact run, or a failure: never "none". */
+function openState(assignment: TaskAssignment): TaskEngineState {
+  const state = tasks.get(assignment.taskId);
+  if (!state || !state.served || !sameAssignment(state.assignment, assignment)) {
+    throw new CredentialLeaseUnavailableError("the task's AI accounts are not available for this run");
+  }
+  return state;
+}
+
+/** The accounts of `engineKind` the task may use now, in try order, the
+ *  unavailable ones included under their identity. Empty when the lease
+ *  names none of that kind; throws while the gate is closed. */
+export function leasedEngineAccounts(assignment: TaskAssignment, engineKind: string): ServedEngineAccount[] {
+  return openState(assignment).served!.filter((account) => account.engineKind === engineKind);
+}
+
+/**
+ * Wait, bounded, for this exact run's gate to be open, and resolve with its
+ * accounts. A record for an older run means the run's own record has not
+ * come yet: keep waiting. Rejects with `CredentialLeaseUnavailableError` once
+ * `timeoutMs` passes, the signal aborts, the task holds a newer run, or the
+ * task is not (or no longer) on cloud credentials: a wait never resolves with
+ * another run's accounts.
+ */
+export function waitForEngineGate(
+  assignment: TaskAssignment,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<TaskEngineLease> {
+  const check = (): TaskEngineLease | "closed" | Error => {
+    const state = tasks.get(assignment.taskId);
+    if (!state) return new CredentialLeaseUnavailableError("the task is not on cloud credentials");
+    if (state.assignment.runEpoch > assignment.runEpoch) {
+      return new CredentialLeaseUnavailableError("the task moved on to another run");
+    }
+    if (!sameAssignment(state.assignment, assignment) || !state.served) return "closed";
+    return { assignment: { ...state.assignment }, open: true, accounts: [...state.served] };
+  };
+  const now = check();
+  if (now instanceof Error) return Promise.reject(now);
+  if (now !== "closed") return Promise.resolve(now);
+  return new Promise((resolve, reject) => {
+    let unsubscribe = (): void => {};
+    const finish = (outcome: TaskEngineLease | Error): void => {
+      clearTimeout(timer);
+      unsubscribe();
+      signal?.removeEventListener("abort", onAbort);
+      if (outcome instanceof Error) reject(outcome);
+      else resolve(outcome);
+    };
+    const onAbort = (): void => finish(new CredentialLeaseUnavailableError("credentials unavailable"));
+    const timer = setTimeout(() => finish(new CredentialLeaseUnavailableError("credentials unavailable")), timeoutMs);
+    timer.unref?.();
+    unsubscribe = onLeasedEnginesChanged((changed) => {
+      if (changed !== assignment.taskId) return;
+      const state = check();
+      if (state !== "closed") finish(state);
+    });
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Hear every change to what a task's accounts are or whether its gate is
+ *  open; returns the unsubscribe. */
+export function onLeasedEnginesChanged(listener: (taskId: string) => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** `account`'s home or a home derived from it; anything else is refused. */
+function homeOf(account: LeasedEngineAccount, home: string | undefined): string {
+  if (account.home === null) throw new Error("the account reads no file");
+  if (home === undefined || home === account.home) return account.home;
+  if (home.startsWith(account.home) && DERIVED_HOME_SUFFIX.test(home.slice(account.home.length))) return home;
+  throw new Error("an engine home outside the account's");
+}
+
+/**
+ * What a spawn on `account` takes: an env-token account's variables, or the
+ * variable that points a config-directory engine at the account's home (or
+ * a home derived from it). Never the files' content.
+ */
+export function engineSpawnEnv(account: LeasedEngineAccount, home?: string): Record<string, string> {
+  if (account.authKind === "env") return { ...(account.env ?? {}) };
+  const selector = ENGINE_ACCOUNT_HOMES[account.engineKind];
+  if (!selector) throw new Error("the account's engine reads no file");
+  return { [selector.selectVar]: homeOf(account, home) };
+}
+
+/** The writer's step was refused: the run, the gate, the revision or the
+ *  version moved. */
+export class EngineCredentialWriteRefused extends Error {
+  constructor() {
+    super("the task's AI accounts changed or were cleaned up; the write was not made");
+    this.name = "EngineCredentialWriteRefused";
+  }
+}
+
+/**
+ * Queue one write for the task: it starts once the writes before it ended,
+ * counts as under way until it ends (a cleanup waits for it), and reads the
+ * task's live state through `current`, which refuses once the run moved on.
+ */
+function enqueueWrite<T>(assignment: TaskAssignment, write: (current: () => TaskEngineState) => Promise<T>): Promise<T> {
+  const state = openState(assignment);
+  state.writing += 1;
+  writers.add(state);
+  const settle = (): void => {
+    state.writing -= 1;
+    if (state.writing > 0) return;
+    writers.delete(state);
+    for (const resolve of state.drained.splice(0)) resolve();
+  };
+  const current = (): TaskEngineState => {
+    if (tasks.get(assignment.taskId) !== state || !state.served || !sameAssignment(state.assignment, assignment)) {
+      throw new EngineCredentialWriteRefused();
+    }
+    return state;
+  };
+  const result = state.queue.then(() => write(current));
+  state.queue = result.then(
+    () => undefined,
+    () => undefined,
+  );
+  return result.finally(settle);
+}
+
+/** The account as served now, readable, or a refusal. */
+function servedNow(state: TaskEngineState, credentialId: string): LeasedEngineAccount {
+  const account = state.served?.find((candidate) => candidate.credentialId === credentialId);
+  if (!account) throw new EngineCredentialWriteRefused();
+  if (!isLeasedEngineAccount(account)) throw new CredentialLeaseUnavailableError("the AI account could not be read");
+  return account;
+}
+
+/**
+ * Write `credentialId`'s lane files into its home in the task (or a home
+ * derived from it): every path and intermediate inventoried first, each file
+ * through the no-follow writer, owner-only, admitted only while the account
+ * is served readable at the revision and version it began with. Resolves to
+ * the version written. Throws `CredentialLeaseUnavailableError` when the
+ * account is named but unreadable, and `EngineCredentialWriteRefused` when it
+ * is not served, or the run, gate, revision or version moved under it.
+ */
+export function writeEngineHome(
+  environment: TaskWriteEnvironment,
+  assignment: TaskAssignment,
+  credentialId: string,
+  home?: string,
+): Promise<number> {
+  assertTaskRuntime(environment, assignment.taskId);
+  return enqueueWrite(assignment, async (current) => {
+    const account = servedNow(current(), credentialId);
+    if (account.authKind !== "config-dir" || !account.files) throw new Error("the account reads no file");
+    const target = homeOf(account, home);
+    const { revision, version } = account;
+    const admit = (): void => {
+      const live = servedNow(current(), credentialId);
+      if (live.revision !== revision || live.version !== version) throw new EngineCredentialWriteRefused();
+    };
+    const names = Object.keys(account.files).sort();
+    for (const path of withStaged(...names.map((name) => `${target}/${name}`))) {
+      rememberCredentialCleanupPath({
+        taskId: assignment.taskId,
+        runEpoch: assignment.runEpoch,
+        runtime: environment.descriptor.locator,
+        lane: "engine-auth",
+        path,
+        credentialId,
+      });
+    }
+    // Stale until this write completes: a refused or failed one is written
+    // again by the next sync.
+    current().written.set(target, { credentialId, revision, version: null });
+    for (const name of names) {
+      await runInTask(
+        environment,
+        writeTaskFileArgv(`${target}/${name}`, "600"),
+        account.files[name]!,
+        `writing the ${account.engineKind} account`,
+        admit,
+      );
+    }
+    // Each exec was admitted at its last moment, but the account can still
+    // have moved while the last one ran: the home holds what was written,
+    // and is current only if that is still what the task is served.
+    const live = current();
+    if (live.written.get(target)?.credentialId === credentialId) {
+      live.written.set(target, { credentialId, revision, version });
+    }
+    const now = servedNow(live, credentialId);
+    if (now.revision !== revision || now.version !== version) throw new EngineCredentialWriteRefused();
+    return version;
+  });
+}
+
+/**
+ * What a spawn on a config-directory account needs first: `credentialId`'s
+ * files in `home` (its home, or one derived from it) at the version served
+ * now. Writes them unless this run already did; resolves to that version.
+ */
+export async function ensureEngineHome(
+  environment: TaskWriteEnvironment,
+  assignment: TaskAssignment,
+  credentialId: string,
+  home?: string,
+): Promise<number> {
+  const state = openState(assignment);
+  const account = state.served!.find((candidate) => candidate.credentialId === credentialId);
+  if (isLeasedEngineAccount(account) && account.home !== null) {
+    const written = state.written.get(homeOf(account, home));
+    if (
+      written?.credentialId === credentialId &&
+      written.revision === account.revision &&
+      written.version === account.version
+    ) {
+      return account.version;
+    }
+  }
+  return writeEngineHome(environment, assignment, credentialId, home);
+}
+
+/**
+ * Write again, in every home this run wrote it to, each account whose
+ * material moved since (a refreshed token, a write that did not complete).
+ * Resolves to the accounts written again; an account served unreadable is
+ * left as it is. Throws on the first write that fails.
+ */
+export async function syncEngineHomes(environment: TaskWriteEnvironment, assignment: TaskAssignment): Promise<string[]> {
+  const state = openState(assignment);
+  const stale: Array<[string, string]> = [];
+  for (const [home, written] of state.written) {
+    const account = state.served!.find((candidate) => candidate.credentialId === written.credentialId);
+    if (!isLeasedEngineAccount(account)) continue;
+    if (account.revision !== written.revision || account.version !== written.version) {
+      stale.push([home, written.credentialId]);
+    }
+  }
+  const rewritten = new Set<string>();
+  for (const [home, credentialId] of stale) {
+    await writeEngineHome(environment, assignment, credentialId, home);
+    rewritten.add(credentialId);
+  }
+  return [...rewritten];
+}
+
+/** The homes this run wrote, with the account each holds; none for another
+ *  run. */
+export function writtenEngineHomes(assignment: TaskAssignment): Array<{ home: string; credentialId: string }> {
+  const state = tasks.get(assignment.taskId);
+  if (!state || !sameAssignment(state.assignment, assignment)) return [];
+  return [...state.written].map(([home, written]) => ({ home, credentialId: written.credentialId }));
+}
+
+export function setEngineCredentialRefresher(next: EngineCredentialRefresher | null): void {
+  refresher = next;
+}
+
+/** Who holds back an account's older versions in the task's runtimes
+ *  before a newer one is served (the orchestrator, which knows them). */
+export function setEngineAdmissionFloorRaiser(next: EngineAdmissionFloorRaiser | null): void {
+  floorRaiser = next;
+}
+
+/** Who escalates a launch slot that could not be retired in its runtime
+ *  (the runner's credentials runtime, through its lease registry). */
+export function setEngineLaunchFenceEscalator(next: EngineLaunchFenceEscalator | null): void {
+  fenceEscalator = next;
+}
+
+/**
+ * ADR-154 §6: a launch slot of `assignment`'s run could not be retired in
+ * its runtime, so a launch handed over before its retirement may still
+ * start: the run's full credential cleanup proves none does, its gate closed
+ * first (no runner on cloud credentials: nothing to escalate to). Returns
+ * whether it was asked for.
+ */
+export function escalateEngineLaunchFence(assignment: TaskAssignment): boolean {
+  if (!fenceEscalator) return false;
+  fenceEscalator({ taskId: assignment.taskId, runEpoch: assignment.runEpoch });
+  return true;
+}
+
+/**
+ * The reactive path (§7): an engine reported its credential invalid. Ask
+ * the cloud for a refresh of the account it ran on, for this exact run, and
+ * report whether the run now holds a newer version of it, readable
+ * ("refreshed"); "unchanged" when the answer brought nothing newer (busy,
+ * unavailable, a new sign-in needed, or the account moved on), "unavailable"
+ * when the run cannot ask: its gate closed, another run, no such account.
+ */
+export async function refreshLeasedEngineAccount(
+  assignment: TaskAssignment,
+  credentialId: string,
+): Promise<"refreshed" | "unchanged" | "unavailable"> {
+  const state = tasks.get(assignment.taskId);
+  if (!state || !sameAssignment(state.assignment, assignment) || !refresher) return "unavailable";
+  const used = state.served?.find((account) => account.credentialId === credentialId);
+  if (!isLeasedEngineAccount(used)) return "unavailable";
+  try {
+    const { outcome } = await refresher({ ...assignment }, credentialId, used.revision);
+    if (outcome !== "refreshed" && outcome !== "fresh") return "unchanged";
+  } catch {
+    return "unavailable";
+  }
+  if (tasks.get(assignment.taskId) !== state || !sameAssignment(state.assignment, assignment)) return "unavailable";
+  const now = state.served?.find((account) => account.credentialId === credentialId);
+  return isLeasedEngineAccount(now) && now.revision === used.revision && now.version > used.version
+    ? "refreshed"
+    : "unchanged";
+}
+
+/** Tests only. */
+export function resetLeasedEnginesForTests(): void {
+  tasks.clear();
+  writers.clear();
+  listeners.clear();
+  refresher = null;
+  floorRaiser = null;
+  fenceEscalator = null;
+}