@runuai/host 0.9.153 → 0.9.155

package/lib/agent-cli.ts

@@ -210,7 +210,14 @@ export function agentCliEnv(
   return {
     ...runtimeAuthority,
     UAI_TASK_TOKEN: signTaskToken(
-      { taskId, userId: ownerUserId, permissions, agentId: agent.id },
+      {
+        taskId,
+        userId: ownerUserId,
+        permissions,
+        agentId: agent.id,
+        // ADR-157 §3: binds the token to this agent, not merely its handle.
+        ...(agent.tokenGeneration ? { generation: agent.tokenGeneration } : {}),
+      },
       cliSecret,
     ),
     UAI_API_URL: apiUrl,
@@ -312,6 +319,58 @@ async function main() {
     }
     return;
   }
+  if (group === "crew") {
+    // ADR-157: the task's built-in Astronaut (the @astronaut Uai builds, never a
+    // persona) changes its own crew. One agent per call, always with a --why.
+    const handleOf = (v) => (typeof v === "string" && v.startsWith("@") ? v.slice(1) : v);
+    const launch = (a) => a.kind + (a.model ? "/" + a.model : "") + (a.effort ? "/" + a.effort : "");
+    if (action === "list") { out(await api("GET", "/api/agent/crew")); return; }
+    if (action === "add") {
+      const personaId = pos[0];
+      if (!personaId || !flags.why) {
+        console.error('uai: crew add needs a persona id (see crew list) and --why "<reason>"');
+        process.exit(1);
+      }
+      const body = { personaId, why: flags.why };
+      if (flags.as) body.handle = handleOf(flags.as);
+      if (flags.engine) body.kind = flags.engine;
+      if (flags.model) body.model = flags.model;
+      if (flags.effort) body.effort = flags.effort;
+      const r = await api("POST", "/api/agent/crew", body);
+      out("added @" + r.agent.id + " (" + r.agent.label + ") on " + launch(r.agent) + ". It stays idle until you dispatch work to it.");
+      return;
+    }
+    if (action === "model") {
+      const id = handleOf(pos[0] || "");
+      if (!id || !flags.why || !(flags.model || flags.engine || flags.effort)) {
+        console.error('uai: crew model needs @agent, at least one of --engine, --model and --effort, and --why "<reason>"');
+        process.exit(1);
+      }
+      // "default" clears the setting back to the engine's own default (null).
+      const cleared = (v) => (v === "default" ? null : v);
+      const body = { why: flags.why };
+      if (flags.engine) body.kind = flags.engine;
+      if (flags.model) body.model = cleared(flags.model);
+      if (flags.effort) body.effort = cleared(flags.effort);
+      const r = await api("PATCH", "/api/agent/crew/" + encodeURIComponent(id), body);
+      out(r.changed
+        ? "@" + id + " now runs on " + launch(r.agent) + "; its session restarts after its current turn"
+        : "@" + id + " already runs on " + launch(r.agent) + "; nothing changed");
+      return;
+    }
+    if (action === "remove") {
+      const id = handleOf(pos[0] || "");
+      if (!id || !flags.why) {
+        console.error('uai: crew remove needs @agent and --why "<reason>"');
+        process.exit(1);
+      }
+      await api("DELETE", "/api/agent/crew/" + encodeURIComponent(id), { why: flags.why });
+      out("removed @" + id);
+      return;
+    }
+    console.error("uai: crew commands are list, add, model and remove (Astronaut only)");
+    process.exit(1);
+  }
   const key = group + " " + (action || "");
   switch (key) {
     case "projects list": out((await api("GET", "/api/agent/projects")).projects); break;
@@ -497,6 +556,10 @@ async function main() {
         "  uai task history                   (list your past tasks)",
         "  uai task read <taskId>             (full chat of a past task you were on)",
         '  uai dispatch @agent [@agent…] "instruction"   (Secretary only)',
+        "  uai crew list                      (Astronaut only: personas, engines, models, limits, roster)",
+        '  uai crew add <personaId> [--as <handle>] [--engine <kind>] [--model <m>] [--effort <e>] --why "<reason>"',
+        '  uai crew model @agent [--engine <kind>] [--model <m|default>] [--effort <e|default>] --why "<reason>"   (at least one of the three)',
+        '  uai crew remove @agent --why "<reason>"',
         "  uai react <heart|check|x> [--msg #id]   (no --msg = the message you were last handed)",
         "  uai whoami",
       ].join("\\n"));

package/lib/agents/claude.ts

@@ -390,6 +390,17 @@ const CLAUDE_FULL_ACCESS_ARGS = [
   "--strict-mcp-config",
 ];
 
+/**
+ * ADR-157 Astronaut profile: the normal tool set, minus Claude Code's native
+ * subagents. An Astronaut's helpers must be crew agents the task can see and
+ * bill; a built-in Agent/Task subagent would run (and spend) outside the crew.
+ */
+const CLAUDE_ASTRONAUT_ARGS = [
+  ...CLAUDE_FULL_ACCESS_ARGS,
+  "--disallowedTools",
+  "Agent,Task",
+];
+
 /**
  * ADR-083 communicator profile. This is deliberately an engine-level tool
  * boundary, not prompt advice: setting sources, hooks, skills, workflows and
@@ -440,7 +451,7 @@ export class ClaudeSession implements AgentSession {
     agent: RosterAgent;
     environment: TaskEnvironmentAgentSessionSurface;
     systemPreamble: string;
-    executionProfile?: "communicator";
+    executionProfile?: "communicator" | "astronaut";
     attachCompatibilityKey?: string;
     agentEnv?: Record<string, string>;
   }) {
@@ -453,7 +464,9 @@ export class ClaudeSession implements AgentSession {
     const cliArgs = [
       ...(args.executionProfile === "communicator"
         ? CLAUDE_COMMUNICATOR_ARGS
-        : CLAUDE_FULL_ACCESS_ARGS),
+        : args.executionProfile === "astronaut"
+          ? CLAUDE_ASTRONAUT_ARGS
+          : CLAUDE_FULL_ACCESS_ARGS),
     ];
     if (process.env.UAI_CLAUDE_INCLUDE_PARTIAL_MESSAGES === "1") {
       cliArgs.push("--include-partial-messages");
@@ -704,6 +717,10 @@ register({
       defaultModel: CLAUDE_COMMUNICATOR_MODEL,
       defaultEffort: CLAUDE_COMMUNICATOR_EFFORT,
     },
+    {
+      id: "astronaut",
+      mechanism: "claude-disallowed-agent-task-v1",
+    },
   ],
   // Usable only when a Claude credential is in the env (injected into task
   // containers at task-up). Gates advertisement (ADR-044 P2).

package/lib/agents/codex.ts

@@ -391,6 +391,8 @@ export class CodexSession implements AgentSession {
     attachCompatibilityKey?: string;
     /** ADR-128: `-c key=value` overrides a delegating adapter prepends. */
     cliConfigOverrides?: string[];
+    /** ADR-157: the Astronaut runs without Codex's native multi-agent tools. */
+    executionProfile?: "communicator" | "astronaut";
   }) {
     this.agentId = args.agent.id;
     this.systemPreamble = args.systemPreamble;
@@ -425,8 +427,15 @@ export class CodexSession implements AgentSession {
       "shell_snapshot",
       "--disable",
       "shell_snapshot_v2",
-      "app-server",
     );
+    // ADR-157: an Astronaut's helpers must be crew agents the task can see and
+    // bill, so Codex's own subagents (spawn_agent; multi_agent is on by
+    // default in 0.157, multi_agent_v2 off) are disabled for it. Also after
+    // every override, so nothing can turn them back on.
+    if (args.executionProfile === "astronaut") {
+      codexArgs.push("--disable", "multi_agent", "--disable", "multi_agent_v2");
+    }
+    codexArgs.push("app-server");
     // ADR-061: the CLI is owned by an in-container runner (durable across
     // host restarts); legacy pipes behind UAI_DURABLE_SESSIONS=0. Codex
     // re-handshakes per host process (initialize + thread/start live in this
@@ -801,6 +810,9 @@ register({
   defaultModel: CODEX_DEFAULT_MODEL,
   supportedEfforts: () => [...CODEX_EFFORTS],
   defaultEffort: CODEX_DEFAULT_EFFORT,
+  // ADR-157: enforceable by construction (the --disable flags above). The
+  // communicator profile is Claude-only; Codex never declared it.
+  executionProfiles: [{ id: "astronaut", mechanism: "codex-disable-multi-agent-v1" }],
   // Usable only when the owner's ~/.codex login exists — task-up copies it into
   // each container from UAI_OWNER_HOME (default $HOME). Gates advertisement
   // (ADR-044 P2).
@@ -820,6 +832,7 @@ register({
     agentEnv,
     attachCompatibilityKey,
     cliConfigOverrides,
+    executionProfile,
   }) =>
     new CodexSession({
       taskId,
@@ -829,5 +842,6 @@ register({
       agentEnv,
       attachCompatibilityKey,
       cliConfigOverrides,
+      executionProfile,
     }),
 });

package/lib/agents/registry.ts

@@ -88,10 +88,11 @@ export function setAdvertisementFallback(
 }
 
 /**
- * ADR-154: on cloud credentials the runner holds no engine credential of its
- * own, so availability and the fallback above say nothing: the kinds the
- * cloud can lease an account for are advertised, and only those. Null while
- * the runner runs its tasks on its own credentials. Installed by main.ts.
+ * ADR-154 §10: on cloud credentials the runner holds no engine credential of
+ * its own, so availability and the fallback above say nothing: the kinds a
+ * leased task can run are advertised, and only those (`CLOUD_CREDENTIAL_KINDS`:
+ * the leased lanes and the Managed Engine). Null while the runner runs its
+ * tasks on its own credentials. Installed by main.ts.
  */
 let leasedKinds: () => ReadonlySet<string> | null = () => null;
 

package/lib/agents/types.ts

@@ -57,6 +57,9 @@ export const RosterAgent = z.object({
   // ADR-128: which upstream protocol a Uai-engine model speaks — resolved
   // cloud-side from the model catalog; selects the delegated adapter.
   uaiProvider: z.enum(["anthropic", "openai"]).optional(),
+  builtIn: z.literal("astronaut").optional(), // ADR-157: the cloud-built Astronaut only
+  // ADR-157 §3: signed into the agent's task token as `g` (see agentCliEnv).
+  tokenGeneration: z.string().min(1).max(64).optional(),
 });
 export type RosterAgent = z.infer<typeof RosterAgent>;
 
@@ -179,7 +182,7 @@ export interface AgentSessionFactory {
     systemPreamble: string;
     /** Host-derived restricted execution policy (ADR-083). Never supplied by
      *  the browser or stored on the roster entry. */
-    executionProfile?: "communicator";
+    executionProfile?: "communicator" | "astronaut";
     /** Durable runners are keyed by task+agent. Host-owned launch settings
      *  supply a compatibility key so restart recovery replaces, rather than
      *  attaches, a process launched with incompatible model/effort/policy. */

package/lib/agents/uai.ts

@@ -15,7 +15,7 @@
  * the request's `model`, and the gateway maps slug → upstream id.
  */
 
-import { factoryFor, register } from "./registry";
+import { factoryFor, register, supportsExecutionProfile } from "./registry";
 import type { AgentSession, AgentSessionFactory } from "./types";
 
 const DEFAULT_GATEWAY_URL = "https://inference.runuai.com";
@@ -80,6 +80,17 @@ const create: AgentSessionFactory["create"] = async (args): Promise<AgentSession
   if (!delegate) {
     throw new Error(`uai engine: no ${delegateKind} adapter registered to delegate to`);
   }
+  // ADR-157 §7: the runner checked the profile against the `uai` kind, but the
+  // delegate is what enforces it. Refuse rather than run an Astronaut on a
+  // delegate that would ignore the profile.
+  if (
+    args.executionProfile &&
+    !supportsExecutionProfile(delegateKind, args.executionProfile)
+  ) {
+    throw new Error(
+      `uai engine: the ${delegateKind} adapter cannot enforce execution profile "${args.executionProfile}"`,
+    );
+  }
   const taskToken = args.agentEnv?.UAI_TASK_TOKEN;
   if (!taskToken) {
     // agentCliEnv mints no token for a permissionless non-secretary agent;
@@ -110,5 +121,8 @@ register({
   // Always available: the engine needs no host-side credential — auth is
   // the per-agent task token, billing is the org's credits.
   available: () => true,
+  // ADR-157: `create` forwards the profile to the Claude or Codex delegate,
+  // and both enforce it.
+  executionProfiles: [{ id: "astronaut", mechanism: "uai-delegated-astronaut-v1" }],
   create,
 });

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
@@ -2279,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();

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 {
@@ -160,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
@@ -308,6 +382,13 @@ export class CloudCredentialRuntime {
   /** 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;
@@ -337,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
@@ -379,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.
@@ -418,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 (
@@ -441,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);
   }
@@ -776,41 +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(() => {
-          // Stop or a newer run can end recovery after the gate schedules
-          // this microtask but before it starts. Never enter task-machine
-          // setup with already-revoked authority: Files treats a current
-          // setup failure as terminal for the whole machine.
-          if (signal.aborted) return;
-          return setup(signal);
+        .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`);
+          }
         })
-        .catch((error: unknown) =>
-          console.warn(
-            `[credentials] task ${assignment.taskId} run ${String(assignment.runEpoch)}: recovered runtime setup failed: ${
-              error instanceof Error ? error.message : String(error)
-            }`,
-          ),
-        )
         .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);
         }),
     );
   }
@@ -983,10 +1082,72 @@ export class CloudCredentialRuntime {
     // 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);
@@ -1030,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")));
@@ -1134,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);