@runuai/host 0.9.152 → 0.9.154

package/db/migrations/0029_task_shared_files_mode.sql

@@ -0,0 +1,5 @@
+-- ADR-154 Files v1: persist the cloud-issued mode for crash recovery. The
+-- task-owned `.uai/files-mounted` marker is an observation, never authority.
+ALTER TABLE `uai_host_tasks` ADD `shared_files_mode` text
+	CONSTRAINT `uai_host_tasks_shared_files_mode`
+	CHECK (`shared_files_mode` IS NULL OR `shared_files_mode` IN ('off', 'ro', 'rw'));

package/db/migrations/meta/_journal.json

@@ -204,6 +204,13 @@
       "when": 1791331200001,
       "tag": "0028_leased_engine_runtimes",
       "breakpoints": true
+    },
+    {
+      "idx": 29,
+      "version": "6",
+      "when": 1791590400000,
+      "tag": "0029_task_shared_files_mode",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -39,6 +39,12 @@ export const hostTasks = sqliteTable(
     // Value-free resolver metadata for rebuilding the project-env gateway
     // after a runner restart, before the cloud re-sends task-up.
     projectEnvSpec: text("project_env_spec"),
+    // ADR-154 Files v1: the normalized mode from the cloud's task launch.
+    // Recovery must never trust the task-writable `.uai/files-mounted`
+    // marker as authority for what may be mounted.
+    sharedFilesMode: text("shared_files_mode", {
+      enum: ["off", "ro", "rw"],
+    }),
     statusMirror: text("status_mirror"),
     // Owner + project slugs — received in TaskLaunchInput at task-up and
     // persisted here so the local UI (ADR-028) can show "who/what" without a
@@ -70,6 +76,10 @@ export const hostTasks = sqliteTable(
       "uai_host_tasks_environment_pair",
       sql`(${table.environmentProvider} IS NULL) = (${table.environmentLocator} IS NULL)`,
     ),
+    sharedFilesModeCheck: check(
+      "uai_host_tasks_shared_files_mode",
+      sql`${table.sharedFilesMode} IS NULL OR ${table.sharedFilesMode} IN ('off', 'ro', 'rw')`,
+    ),
   }),
 );
 

package/lib/agent.ts

@@ -68,6 +68,10 @@ export interface LeasedTaskUp {
    * the start.
    */
   runtimeReady: (environment: TaskWriteEnvironment, signal: AbortSignal) => Promise<void>;
+  /** This exact start carries a task-machine Files session.  Machine task-up
+   * skips its legacy copy/mount path only in this case; owned leased tasks do
+   * not receive a Files session and keep their normal Files behavior. */
+  filesV1?: true;
 }
 
 /** Refuses a start on cloud credentials that is not whole, or not this

package/lib/browser-testing.ts

@@ -1390,11 +1390,16 @@ export async function setupBrowserTesting(
       }
     }
 
-    // Grok registers its servers through its own CLI (project scope, see
-    // GROK_BROWSER_ADD_CMD) rather than a file we own; a failure here leaves
-    // the task configured-false so the next ensure retries.
+    // Grok registers through its own read-modify-write CLI (user scope,
+    // see grokBrowserAddCommand), under the same lock as gateway reconciliation
+    // so two successful CLI processes cannot silently lose each other's entry.
+    // A failure leaves the task configured-false so the next ensure retries.
     if (hasGrok) {
       const grokArgv = [
+        "flock",
+        "-w",
+        "10",
+        MCP_CONFIG_LOCK_PATH,
         "sh",
         "-lc",
         selectedGrokHomes.map(grokBrowserAddCommand).join(" && "),

package/lib/cloud-credential-leases.ts

@@ -257,6 +257,12 @@ export interface TaskCredentialLeaseRegistryOptions {
     assignment: Readonly<TaskAssignment>,
     view: TaskCredentialView,
   ): void;
+  /** A material update committed while the existing gate stayed open.
+   * Followers may reconcile runtime files from this authoritative view. */
+  credentialMaterialChanged?(
+    assignment: Readonly<TaskAssignment>,
+    view: TaskCredentialView,
+  ): void;
   cleanupExternal(request: CredentialCleanupRequest): Promise<void>;
   /**
    * Installs files/proxy/engine consumers transactionally.  The env-replica
@@ -1126,7 +1132,10 @@ export class TaskCredentialLeaseRegistry {
       await this.#applyCredentialVersion(state, frame);
     } catch (error) {
       this.#report(error, state.assignment);
-      if (this.#isActive(state)) this.#request(state);
+      // A failed consumer install may already have completed full cleanup
+      // and armed the bounded retry which owns what comes next. Do not cancel
+      // that backoff by immediately requesting the same refused manifest.
+      if (this.#isActive(state) && !state.retryTimer) this.#request(state);
     }
   }
 
@@ -1226,7 +1235,7 @@ export class TaskCredentialLeaseRegistry {
         });
       } catch (error) {
         this.#report(error, state.assignment);
-        this.#request(state);
+        if (this.#isActive(state) && !state.retryTimer) this.#request(state);
       }
     } else if (frame.outcome === "needs_sign_in") {
       // The authoritative stale frame supplies any floor and removals.
@@ -2276,6 +2285,9 @@ export class TaskCredentialLeaseRegistry {
       state.bundle = next;
       state.bundleGeneration++;
       this.#armBundleTimers(state);
+      if (!refused) {
+        this.#opts.credentialMaterialChanged?.(cloneAssignment(state.assignment), next.view);
+      }
       // A refusal opens through its release, inside this boundary: an open
       // that fails, its compensating close included, escalates below.
       release();
@@ -2452,8 +2464,16 @@ export class TaskCredentialLeaseRegistry {
         // A permanent revocation answers every request with another denial.
         // Keep asking, but do not turn that into a tight
         // deny/cleanup/request loop against the cloud.
-        if (reason === "denied") this.#armRetry(state);
-        else this.#request(state);
+        // A denial is stable until cloud state changes, and a consumer which
+        // refused a grant can keep refusing the same manifest (for example
+        // while a task-owned workspace entry is being repaired).  Neither is
+        // allowed to become a cleanup/request loop which repeatedly mints STS
+        // sessions and reads Parameter Store without delay.
+        if (reason === "denied" || reason === "manifest-narrowed") {
+          this.#armRetry(state);
+        } else {
+          this.#request(state);
+        }
       }
     }
   }

package/lib/cloud-credential-runtime.ts

@@ -63,9 +63,11 @@ import {
   cleanupPersonCredentials,
   closePersonCredentialGate,
   drainPersonCredentialWrites,
+  holdPersonCredentialGate,
   holdTaskGitCredentials,
   installPersonCredentials,
   openPersonCredentialGate,
+  type PersonCredentialLane,
   type TaskGitCredentialHold,
 } from "./credential-consumers/github";
 import {
@@ -79,6 +81,8 @@ import {
   setMcpCredentialRefresher,
 } from "./credential-consumers/mcp";
 import type { ProjectEnvTaskReplicaManager, ProjectEnvTaskReplicaSnapshot } from "./project-env-task-replica";
+import type { SharedFilesMode } from "./shared-files-s3";
+import type { TaskEnvironmentHandle } from "./task-environment/types";
 import {
   TaskCredentialCleanupCoordinator,
   type TaskCredentialCleanupDeps,
@@ -95,6 +99,17 @@ const ENV_READY_POLL_MS = 50;
  *  way; the next process's recovery sweep finishes what is left. */
 export const SHUTDOWN_DRAIN_MS = 30_000;
 
+/** The only MCP state an agent config exposes. Material, provider URL,
+ * revision and availability stay behind the task gateway, so changing any of
+ * them must not churn a long-lived agent process. */
+function mcpAgentMembershipFingerprint(view: TaskCredentialView): string {
+  return JSON.stringify(
+    view.mcp
+      .map((connection) => connection.manifest.slug)
+      .sort((left, right) => left.localeCompare(right)),
+  );
+}
+
 /** The task's Files (ADR-154 §12): installed, opened and closed with the
  *  rest. `close` is synchronous: no new Files admission after it. */
 export interface TaskFilesConsumer {
@@ -102,6 +117,32 @@ export interface TaskFilesConsumer {
   open(assignment: Readonly<TaskAssignment>, view: TaskCredentialView): void;
   close(assignment: Readonly<TaskAssignment>): void;
   closeConsumers(request: TaskCredentialCleanupRequest): Promise<void>;
+  /** A trusted task-machine runtime could not establish its Files boundary.
+   * This run cannot be reopened on the same machine. */
+  retire(assignment: Readonly<TaskAssignment>, error: unknown): void;
+  /** Optional only so owned runners can use the same composer without a
+   * task-machine Files implementation. */
+  runtimeReady?(
+    assignment: Readonly<TaskAssignment>,
+    environment: TaskEnvironmentHandle<unknown>,
+    mode: SharedFilesMode,
+    signal: AbortSignal,
+  ): Promise<void>;
+  /** Drop secrets at process shutdown without starting cleanup. */
+  shutdown?(): void;
+}
+
+/** A Files implementation proved that the runtime-ready operation which
+ * failed still owns the exact open run and requested terminal retirement of
+ * its one-task machine; a stale operation throws its ordinary error. */
+export class AuthoritativeTaskFilesFailure extends Error {
+  override readonly cause: unknown;
+
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : "the task's Files boundary failed");
+    this.name = "AuthoritativeTaskFilesFailure";
+    this.cause = cause;
+  }
 }
 
 export interface CloudCredentialRuntimeDeps {
@@ -121,18 +162,90 @@ export interface CloudCredentialRuntimeDeps {
    *  on a grant's snapshot, or closed): whoever follows the task's env
    *  (the proxy's trust delivery) looks again. */
   envServedChanged?(taskId: string): void;
+  /** Reconcile the owner's GitHub/SSH files in an already-running task.
+   * The signal closes with the exact person-credential gate, and the caller
+   * retries a transient rejection while that gate and material stay current. */
+  personCredentialsReady?(
+    assignment: Readonly<TaskAssignment>,
+    lanes: readonly PersonCredentialLane[],
+    signal: AbortSignal,
+  ): Promise<void>;
   files?: TaskFilesConsumer | null;
   launchDeadlineMs?: number;
   envReadyTimeoutMs?: number;
   shutdownDrainMs?: number;
   /** The first retry's delay for a recovered start whose startup failed. */
   recoveryRetryBaseMs?: number;
+  /** The first retry's delay for task-runtime person-credential writes. */
+  personReconcileRetryBaseMs?: number;
   registry?: Partial<
     Pick<TaskCredentialLeaseRegistryOptions, "createSessionReader" | "now" | "setTimer" | "clearTimer" | "randomId" | "onError">
   >;
   cleanup?: Pick<TaskCredentialCleanupDeps, "db" | "removePath" | "destroyRuntime">;
 }
 
+interface PersonCredentialStamp {
+  /** Stable without retaining another copy of any credential material. */
+  identity: string;
+  available: boolean;
+}
+
+interface PersonCredentialSnapshot {
+  runEpoch: number;
+  github: PersonCredentialStamp;
+  ssh: PersonCredentialStamp;
+}
+
+function personCredentialStamp(
+  credential: TaskCredentialView["github"] | TaskCredentialView["ssh"],
+): PersonCredentialStamp {
+  if (credential === null) return { identity: "absent", available: false };
+  return {
+    identity: [
+      credential.manifest.credentialId,
+      credential.manifest.revision,
+      credential.availability,
+      credential.observedVersion ?? "unreadable",
+    ].join("\u0000"),
+    available: credential.availability === "available",
+  };
+}
+
+function personCredentialSnapshot(view: TaskCredentialView): PersonCredentialSnapshot {
+  return {
+    runEpoch: view.assignment.runEpoch,
+    github: personCredentialStamp(view.github),
+    ssh: personCredentialStamp(view.ssh),
+  };
+}
+
+function samePersonCredentialSnapshot(
+  left: PersonCredentialSnapshot | undefined,
+  right: PersonCredentialSnapshot,
+): boolean {
+  return Boolean(
+    left &&
+      left.runEpoch === right.runEpoch &&
+      left.github.identity === right.github.identity &&
+      left.ssh.identity === right.ssh.identity,
+  );
+}
+
+/** What must be rewritten for `next`. GitHub and SSH transport are coupled:
+ * when GitHub leaves, the surviving SSH key must select SSH again. */
+function changedPersonCredentialLanes(
+  previous: PersonCredentialSnapshot | undefined,
+  next: PersonCredentialSnapshot,
+): PersonCredentialLane[] {
+  if (samePersonCredentialSnapshot(previous, next)) return [];
+  // The pair shares Git transport configuration. Reconcile both available
+  // lanes, including a write interrupted by the other lane changing.
+  const lanes: PersonCredentialLane[] = [];
+  if (next.github.available) lanes.push("github");
+  if (next.ssh.available) lanes.push("ssh");
+  return lanes;
+}
+
 /**
  * Why a start was interrupted, as its signal's reason: Stop, teardown or a
  * newer run took it over, or the runner is shutting down. The first
@@ -266,6 +379,16 @@ export class CloudCredentialRuntime {
   /** Work accepted and not yet over (startups, frames, installs, holds not
    *  yet released, closes): what shutdown joins. */
   readonly #work = new Set<Promise<unknown>>();
+  /** Last agent-facing MCP membership published for each task. Kept across a
+   *  gate close/renewal because the config remains in the task runtime. */
+  readonly #publishedMcpMembership = new Map<string, string>();
+  /** Person material last opened or installed for each task. Only identities,
+   * availability and observed versions: never another copy of a secret. */
+  readonly #personCredentialSnapshots = new Map<string, PersonCredentialSnapshot>();
+  readonly #personReconciles = new Map<string, { runEpoch: number; controller: AbortController }>();
+  /** Stop fences work before it can acquire the lifecycle slot or close the
+   * lease. A late grant cannot restart writes in that interval. */
+  readonly #personInterrupted = new Map<string, number>();
   readonly #setTimer: typeof setTimeout;
   readonly #clearTimer: typeof clearTimeout;
   #shutDown = false;
@@ -295,6 +418,7 @@ export class CloudCredentialRuntime {
       send: (frame) => deps.send(frame),
       closeTaskGate: (assignment) => this.#close(assignment),
       openTaskGate: (assignment, view) => this.#openGate(assignment, view),
+      credentialMaterialChanged: (assignment, view) => this.#personCredentialsChanged(assignment, view),
       installExternal: (request) => this.#track(this.#install(request)),
       // From a grant's acceptance until its own reader is active, the env
       // replica refuses the run's frames for the cloud to retry: none is
@@ -337,6 +461,7 @@ export class CloudCredentialRuntime {
       throw new CredentialLeaseUnavailableError("a newer run of this task has begun");
     }
     this.#floors.set(assignment.taskId, assignment.runEpoch);
+    if (!options.recovery) this.#personInterrupted.delete(assignment.taskId);
     this.#interruptTokens(assignment.taskId, {});
     // A newer run's start ends an older run's recovery; an ordinary start of
     // the run being recovered takes its startup over.
@@ -376,6 +501,11 @@ export class CloudCredentialRuntime {
    */
   interruptStarts(taskId: string, which: { exact?: number; below?: number } = {}): void {
     this.#interruptTokens(taskId, which);
+    const assignment = this.#assignments.get(taskId);
+    if (assignment && (which.exact === undefined || assignment.runEpoch === which.exact) &&
+        (which.below === undefined || assignment.runEpoch < which.below)) {
+      this.#interruptPersonCredentials(assignment);
+    }
     // A recovery of the run ends with it, ended start token or not.
     const recovered = this.#recovered.get(taskId);
     if (
@@ -399,6 +529,8 @@ export class CloudCredentialRuntime {
   /** A local Stop: the task's recovery, whatever its run, ends now. One
    *  only exists for the run this runner owned at its start. */
   interruptRecovery(taskId: string): void {
+    const assignment = this.#assignments.get(taskId);
+    if (assignment) this.#interruptPersonCredentials(assignment);
     const recovered = this.#recovered.get(taskId);
     if (recovered) this.#endRecovery(taskId, recovered.runEpoch);
   }
@@ -500,6 +632,69 @@ export class CloudCredentialRuntime {
     };
   }
 
+  /** Whether this process has the task-machine Files-v1 consumer wired. */
+  taskFilesV1(): boolean {
+    return typeof this.#deps.files?.runtimeReady === "function";
+  }
+
+  /** Runtime-ready half of Files v1.  It is tracked with the composer's
+   * accepted work so shutdown joins a write/mount already admitted. */
+  prepareTaskFiles(
+    assignment: Readonly<TaskAssignment>,
+    environment: TaskEnvironmentHandle<unknown>,
+    mode: SharedFilesMode,
+    signal: AbortSignal,
+  ): Promise<void> {
+    const ready = this.#deps.files?.runtimeReady;
+    if (!ready) return Promise.reject(new Error("task-machine Files v1 is unavailable"));
+    return this.#track(
+      ready.call(this.#deps.files, assignment, environment, mode, signal).catch((error: unknown) => {
+        if (error instanceof AuthoritativeTaskFilesFailure) {
+          // Never reopen this run on the same machine. The consumer already
+          // proved this is authoritative; centrally latch/request exact-run
+          // terminal retirement too, so an implementation cannot turn this
+          // into an ordinary cleanup/regrant by omission.
+          let retirementError: unknown = null;
+          try {
+            this.#deps.files!.retire(assignment, error.cause);
+          } catch (failure) {
+            retirementError = failure;
+          }
+          void this.closeAssignment({ ...assignment }, "stop").catch(() => {});
+          if (retirementError !== null) throw retirementError;
+          throw error.cause;
+        }
+        throw error;
+      }),
+    );
+  }
+
+  /** A recovered task whose trusted Files metadata is absent or invalid has
+   * failed the same boundary before the consumer can be called. Request its
+   * terminal machine retirement, close its gate synchronously, and run the
+   * run's full cleanup. */
+  failTaskFilesSetup(
+    assignment: Readonly<TaskAssignment>,
+    error: unknown = new Error("the recovered task has no trusted Files-v1 metadata"),
+  ): void {
+    try {
+      this.#deps.files?.retire(assignment, error);
+    } catch (retirementError) {
+      console.warn(
+        `[credentials] task ${assignment.taskId} run ${String(assignment.runEpoch)}: Files machine retirement could not be requested: ${
+          retirementError instanceof Error ? retirementError.message : String(retirementError)
+        }`,
+      );
+    }
+    void this.closeAssignment({ ...assignment }, "stop").catch((error: unknown) => {
+      console.warn(
+        `[credentials] task ${assignment.taskId} run ${String(assignment.runEpoch)}: Files recovery cleanup failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    });
+  }
+
   /** The start is over, successful or not: its token has no authority left,
    *  and it is no longer the task's newest. */
   endStart(start: TaskCredentialStart): void {
@@ -671,34 +866,50 @@ export class CloudCredentialRuntime {
     if (recovered.running === null) this.#recovered.delete(taskId);
   }
 
-  /** A recovered run's gate opened: its recovery is done, and its setup
-   *  runs, once, in the background, its failure its own. */
+  /** A recovered runtime is ready only after setup succeeds. Transient
+   * reconstruction/exec failures retry; Stop, cleanup and takeover fence
+   * every attempt and its retry delay. */
   #runRecoveredSetup(assignment: Readonly<TaskAssignment>): void {
     const recovered = this.#recovered.get(assignment.taskId);
     if (!recovered || recovered.runEpoch !== assignment.runEpoch || recovered.running !== null) return;
-    if (recovered.controller.signal.aborted) return;
+    if (recovered.controller.signal.aborted || this.#open.get(assignment.taskId) !== assignment.runEpoch) return;
     if (recovered.retry !== null) this.#clearTimer(recovered.retry);
     recovered.retry = null;
     const setup = recovered.setup;
-    recovered.setup = null;
     if (setup === null) {
       this.#recovered.delete(assignment.taskId);
       return;
     }
-    const signal = recovered.controller.signal;
+    const hold = holdPersonCredentialGate(assignment);
+    const signal = AbortSignal.any([recovered.controller.signal, hold.signal]);
+    let complete = false;
     recovered.running = this.#track(
       Promise.resolve()
-        .then(() => setup(signal))
-        .catch((error: unknown) =>
-          console.warn(
-            `[credentials] task ${assignment.taskId} run ${String(assignment.runEpoch)}: recovered runtime setup failed: ${
-              error instanceof Error ? error.message : String(error)
-            }`,
-          ),
-        )
+        .then(async () => {
+          signal.throwIfAborted();
+          await setup(signal);
+          signal.throwIfAborted();
+          complete = true;
+        })
+        .catch(() => {
+          if (!signal.aborted) {
+            console.warn(`[credentials] task ${assignment.taskId} run ${String(assignment.runEpoch)}: recovered runtime setup failed; retrying`);
+          }
+        })
         .finally(() => {
+          hold.release();
           recovered.running = null;
-          if (this.#recovered.get(assignment.taskId) === recovered) this.#recovered.delete(assignment.taskId);
+          if (this.#recovered.get(assignment.taskId) !== recovered) return;
+          if (complete || recovered.controller.signal.aborted || this.#shutDown) {
+            this.#recovered.delete(assignment.taskId);
+            return;
+          }
+          const base = this.#deps.recoveryRetryBaseMs ?? RECOVERY_RETRY_BASE_MS;
+          const delay = Math.min(RECOVERY_RETRY_MAX_MS, base * 2 ** Math.min(recovered.attempts++, 20));
+          recovered.retry = this.#setTimer(() => {
+            recovered.retry = null;
+            this.#runRecoveredSetup(assignment);
+          }, delay);
         }),
     );
   }
@@ -830,6 +1041,7 @@ export class CloudCredentialRuntime {
     setEngineCredentialRefresher(null);
     setEngineLaunchFenceEscalator(null);
     setMcpCredentialRefresher(null);
+    this.#deps.files?.shutdown?.();
   }
 
   // -- the registry's gate and install --------------------------------------------
@@ -860,16 +1072,82 @@ export class CloudCredentialRuntime {
     openEngineGate(assignment, view);
     openMcpGate(assignment, view);
     openPersonCredentialGate(assignment, view);
-    this.#deps.files?.open(assignment, view);
     this.#open.set(assignment.taskId, assignment.runEpoch);
     const generation = this.#generations.get(view);
     if (generation === undefined) this.#served.delete(assignment.taskId);
     else this.#served.set(assignment.taskId, generation);
-    this.#deps.mcpServedChanged?.(assignment.taskId);
     this.#envServedChanged(assignment.taskId);
+    // Last throwing boundary: a recovered runtime's mounts stay staged and
+    // root-inaccessible until every other consumer accepted this exact view.
+    // Nothing which follows publishes work synchronously. If Files itself
+    // fails, the registry compensates by closing the earlier gates.
+    this.#deps.files?.open(assignment, view);
+    this.#personCredentialsChanged(assignment, view);
+    this.#publishMcpMembership(assignment.taskId, view);
     this.#runRecoveredSetup(assignment);
   }
 
+  #personCredentialsChanged(assignment: Readonly<TaskAssignment>, view: TaskCredentialView): void {
+    const reconcile = this.#deps.personCredentialsReady;
+    if (!reconcile || this.#shutDown || this.#open.get(assignment.taskId) !== assignment.runEpoch) return;
+    if ((this.#personInterrupted.get(assignment.taskId) ?? -1) >= assignment.runEpoch) return;
+    const previous = this.#personCredentialSnapshots.get(assignment.taskId);
+    const snapshot = personCredentialSnapshot(view);
+    if (samePersonCredentialSnapshot(previous, snapshot)) return;
+    this.#personCredentialSnapshots.set(assignment.taskId, snapshot);
+    this.#personReconciles.get(assignment.taskId)?.controller.abort();
+    const lanes = changedPersonCredentialLanes(previous, snapshot);
+    if (lanes.length === 0) return;
+    const entry = { runEpoch: assignment.runEpoch, controller: new AbortController() };
+    const hold = holdPersonCredentialGate(assignment);
+    const signal = AbortSignal.any([entry.controller.signal, hold.signal]);
+    this.#personReconciles.set(assignment.taskId, entry);
+    this.#background(
+      Promise.resolve().then(async () => {
+        let attempts = 0;
+        while (!signal.aborted) {
+          try {
+            await reconcile(assignment, lanes, signal);
+            signal.throwIfAborted();
+            return;
+          } catch {
+            if (signal.aborted) return;
+            if (attempts === 0) {
+              console.warn(`[credentials] task ${assignment.taskId} run ${String(assignment.runEpoch)}: person credential files not ready; retrying`);
+            }
+            const base = this.#deps.personReconcileRetryBaseMs ?? RECOVERY_RETRY_BASE_MS;
+            await this.#retryDelay(Math.min(RECOVERY_RETRY_MAX_MS, base * 2 ** Math.min(attempts++, 20)), signal);
+          }
+        }
+      }).finally(() => {
+        hold.release();
+        if (this.#personReconciles.get(assignment.taskId) === entry) this.#personReconciles.delete(assignment.taskId);
+      }),
+    );
+  }
+
+  #interruptPersonCredentials(assignment: Readonly<TaskAssignment>): void {
+    this.#personInterrupted.set(assignment.taskId, Math.max(assignment.runEpoch, this.#personInterrupted.get(assignment.taskId) ?? -1));
+    const snapshot = this.#personCredentialSnapshots.get(assignment.taskId);
+    if (snapshot && snapshot.runEpoch <= assignment.runEpoch) this.#personCredentialSnapshots.delete(assignment.taskId);
+    const reconcile = this.#personReconciles.get(assignment.taskId);
+    if (reconcile && reconcile.runEpoch <= assignment.runEpoch) reconcile.controller.abort();
+  }
+
+  /** A retry never holds cleanup for its backoff interval. */
+  #retryDelay(delay: number, signal: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      const finish = (): void => {
+        this.#clearTimer(timer);
+        signal.removeEventListener("abort", finish);
+        resolve();
+      };
+      const timer = this.#setTimer(finish, delay);
+      signal.addEventListener("abort", finish, { once: true });
+      if (signal.aborted) finish();
+    });
+  }
+
   #envServedChanged(taskId: string): void {
     try {
       this.#deps.envServedChanged?.(taskId);
@@ -878,6 +1156,21 @@ export class CloudCredentialRuntime {
     }
   }
 
+  /** Publish only a normalized change visible to agent configuration. A
+   * renewed lease, a refreshed OAuth token, and available/unavailable
+   * transitions all keep the same named gateway route and therefore do not
+   * rewrite config or restart agents; an unavailable route answers 503. */
+  #publishMcpMembership(taskId: string, view: TaskCredentialView): void {
+    const fingerprint = mcpAgentMembershipFingerprint(view);
+    if (this.#publishedMcpMembership.get(taskId) === fingerprint) return;
+    this.#publishedMcpMembership.set(taskId, fingerprint);
+    try {
+      this.#deps.mcpServedChanged?.(taskId);
+    } catch {
+      // The gateway gate is authoritative even when its config follower fails.
+    }
+  }
+
   /**
    * Synchronous and idempotent: every consumer of this run (and older)
    * stops being served, env and Files included, and every start holding its
@@ -898,8 +1191,11 @@ export class CloudCredentialRuntime {
     if (open !== undefined && open <= assignment.runEpoch) {
       this.#open.delete(assignment.taskId);
       this.#served.delete(assignment.taskId);
+      this.#personCredentialSnapshots.delete(assignment.taskId);
       this.#envServedChanged(assignment.taskId);
     }
+    const person = this.#personReconciles.get(assignment.taskId);
+    if (person && person.runEpoch <= assignment.runEpoch) person.controller.abort();
     for (const entry of this.#holds.get(assignment.taskId) ?? []) {
       if (entry.runEpoch <= assignment.runEpoch) {
         attempt(() => entry.controller.abort(new CredentialLeaseUnavailableError("the task's credentials were withdrawn")));
@@ -947,6 +1243,12 @@ export class CloudCredentialRuntime {
     installPersonCredentials(request);
     await this.#deps.files?.install(request);
     this.#assertInstallCurrent(request);
+    // Credential changes normally affect material or availability only. Keep
+    // this normalized comparison at the install boundary so even a future
+    // same-run membership change publishes exactly once.
+    if (request.reason === "credential-change") {
+      this.#publishMcpMembership(request.assignment.taskId, request.next);
+    }
   }
 
   #assertInstallCurrent(request: CredentialInstallRequest): void {
@@ -996,7 +1298,9 @@ export class CloudCredentialRuntime {
     const recovered = this.#recovered.get(request.taskId);
     const setups: Promise<void>[] = [];
     if (request.credentialIds === undefined && recovered && recovered.runEpoch <= request.runEpoch && recovered.running) {
-      recovered.controller.abort(new StartInterruptedError("takeover"));
+      // The gate hold already cancelled this attempt. A transient full
+      // cleanup may reacquire the same run's lease, so retain its setup for
+      // that next open. Stop/takeover cancel recovery at their own boundary.
       setups.push(recovered.running);
     }
     const consumer = consumerCleanupRequest(request);
@@ -1019,6 +1323,7 @@ export class CloudCredentialRuntime {
     if (request.credentialIds !== undefined) return;
     this.#deps.envReplica?.dropAssignment(request.taskId, request.runEpoch);
     if (request.reason !== "teardown") return;
+    this.#publishedMcpMembership.delete(request.taskId);
     forgetLeasedEngines({ taskId: request.taskId, runEpoch: request.runEpoch });
     const mcp = leasedMcpFor(request.taskId);
     if (mcp && mcp.assignment.runEpoch <= request.runEpoch) forgetLeasedMcp(request.taskId);

package/lib/credential-cleanup-inventory.ts

@@ -165,7 +165,9 @@ const SSH_PATHS = new Set(
 );
 const FILES_SESSION_PATHS = new Set([
   LEASE_CREDENTIALS_FILE,
+  `${LEASE_CREDENTIALS_FILE}.uai-tmp`,
   LEASE_AWS_CONFIG_FILE,
+  `${LEASE_AWS_CONFIG_FILE}.uai-tmp`,
 ]);
 
 /** Destructive cleanup accepts only lane-owned files. The executor repeats