@runuai/host 0.9.149 → 0.9.151

package/lib/cloud-credential-leases.ts

@@ -0,0 +1,2544 @@
+/**
+ * ADR-154 task-scoped credential leases.
+ *
+ * This is deliberately separate from the ADR-133 singleton lease manager.
+ * A registry owns one in-memory bundle per live task assignment and never
+ * exposes a credentials session as a general-purpose AWS credential.  The
+ * only AWS operation a credentials session can perform here is an exact,
+ * version-pinned GetParameters request.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+
+import {
+  GetParametersCommand,
+  SSMClient,
+  type Parameter,
+} from "@aws-sdk/client-ssm";
+
+import {
+  canonicalManifestJson,
+  parseCredentialChangedFrame,
+  parseCredentialRefreshResultFrame,
+  parseLeaseGrantV1Frame,
+  parseLeaseParameterName,
+  parseLeaseStaleFrame,
+  parseLeaseUnavailableFrame,
+  parseLeasedValue,
+  taskLeaseV1ExpiresAt,
+  type CredentialChangedFrame,
+  type CredentialLocation,
+  type CredentialRefreshFrame,
+  type CredentialRefreshResultFrame,
+  type LeaseFiles,
+  type LeaseGrantV1Frame,
+  type LeaseManifestEngine,
+  type LeaseManifestMcp,
+  type LeaseManifestStatic,
+  type LeaseRequestV1Frame,
+  type LeaseSession,
+  type LeaseStaleFrame,
+  type LeaseUnavailableFrame,
+  type LeasedValue,
+  type TaskLeaseV1,
+} from "../src/cloud-credentials";
+import type { ProjectEnvValueRef } from "../src/protocol";
+
+export const LEASE_RENEW_LEAD_MS = 10 * 60_000;
+export const LEASE_REQUEST_TIMEOUT_MS = 20_000;
+export const LEASE_RETRY_MS = 30_000;
+export const LEASE_MIN_REVISION_GRACE_MS = 60_000;
+
+const MAX_SSM_GET_PARAMETERS = 10;
+const PROJECT_PATH_SEGMENT = /^[A-Za-z0-9_.-]+$/;
+const PROJECT_ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PROJECT_ENV_STAGING_ID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const OP_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const MAX_ERROR_CHARS = 512;
+
+type Timer = ReturnType<typeof setTimeout>;
+
+export interface TaskAssignment {
+  taskId: string;
+  runEpoch: number;
+}
+
+export type LeaseGateCloseReason =
+  | "starting"
+  | "recovery"
+  | "superseded"
+  | "minimum-revision"
+  | "manifest-narrowed"
+  | "denied"
+  | "expired"
+  | "stopped"
+  | "parked"
+  | "teardown"
+  | "cleanup-failed"
+  /** A launch slot of the run could not be retired in its runtime (§6):
+   *  only the run's full cleanup proves no launch of it runs. */
+  | "fence-failed"
+  /** The runner process is ending: no cleanup here, the next process's
+   *  recovery sweep runs it (§5, §6). */
+  | "shutdown";
+
+export type CredentialCleanupReason = LeaseGateCloseReason | "lease-replaced";
+
+export interface CredentialCleanupIdentity {
+  class: "engine" | "mcp" | "github" | "ssh";
+  credentialId: string;
+  revision: string | null;
+}
+
+export interface CredentialCleanupRequest {
+  assignment: TaskAssignment;
+  mode: "selective" | "full";
+  reason: CredentialCleanupReason;
+  /** Qualified old identities, never merely unscoped credential ids. */
+  removed: readonly CredentialCleanupIdentity[];
+  /** Full cleanup on a task machine must also remove `/run/uai` material. */
+  removeFilesSession: boolean;
+}
+
+export type EngineLeasedValue = Extract<
+  LeasedValue,
+  { class: "engine" }
+>;
+export type McpLeasedValue = Extract<LeasedValue, { class: "mcp" }>;
+export type GithubLeasedValue = Extract<LeasedValue, { class: "github" }>;
+export type SshLeasedValue = Extract<LeasedValue, { class: "ssh" }>;
+export type CredentialMaterialAvailability =
+  | "available"
+  | "access-denied"
+  | "not-required";
+
+export interface TaskEngineCredential {
+  manifest: Readonly<LeaseManifestEngine>;
+  availability: Exclude<CredentialMaterialAvailability, "not-required">;
+  material: Readonly<EngineLeasedValue> | null;
+  observedVersion: number | null;
+}
+
+export interface TaskMcpConnection {
+  manifest: Readonly<LeaseManifestMcp>;
+  availability: CredentialMaterialAvailability;
+  material: Readonly<McpLeasedValue> | null;
+  observedVersion: number | null;
+}
+
+export interface TaskStaticCredential<T extends LeasedValue> {
+  manifest: Readonly<LeaseManifestStatic>;
+  availability: Exclude<CredentialMaterialAvailability, "not-required">;
+  material: Readonly<T> | null;
+  observedVersion: number | null;
+}
+
+/** A task-facing view. It contains material, but never STS credentials. */
+export interface TaskCredentialView {
+  assignment: Readonly<TaskAssignment>;
+  leaseId: string;
+  manifestRevision: number;
+  manifestDigest: string;
+  expiresAt: number;
+  projectIds: readonly string[];
+  /** Preserves the manifest's try order exactly. */
+  engines: readonly TaskEngineCredential[];
+  mcp: readonly TaskMcpConnection[];
+  github: TaskStaticCredential<GithubLeasedValue> | null;
+  ssh: TaskStaticCredential<SshLeasedValue> | null;
+}
+
+/** The one deliberately narrow escape hatch for Mountpoint on task machines. */
+export interface TaskLeaseFilesAccess {
+  assignment: Readonly<TaskAssignment>;
+  region: string;
+  files: Readonly<LeaseFiles>;
+  credentials: Readonly<{
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    expiresAt: number;
+  }>;
+}
+
+export interface CredentialInstallRequest {
+  assignment: TaskAssignment;
+  /** The workspace and person the cloud granted this lease for: what the
+   *  env replica and consumers key on, never a guess from task input. */
+  owner: Readonly<{ orgId: string; userId: string }>;
+  previous: TaskCredentialView | null;
+  next: TaskCredentialView;
+  files: TaskLeaseFilesAccess | null;
+  reason: "grant" | "credential-change";
+  projectSetChanged: boolean;
+  /** This grant's project values, readable while it is being installed (the
+   *  env replica's snapshot, before the gate opens) and then while it is the
+   *  task's usable grant; never after it is abandoned or replaced. */
+  projectValues: ProjectEnvTaskValueReader;
+  /** False once this install can no longer commit (its grant withdrawn,
+   *  replaced, refused or ended): a long step, such as awaiting the env
+   *  snapshot, gives up then. */
+  isCurrent(): boolean;
+}
+
+export interface StructuredProjectValueRead {
+  projectId: string;
+  key: string;
+  valueRef: ProjectEnvValueRef;
+}
+
+export interface ProjectValueReadResult {
+  /** The exact authenticated envelope; the replica opens it independently. */
+  rawValue: string;
+  version: number;
+  parameter: string;
+}
+
+/** Adapter consumed by the v1 task-keyed env replica. */
+export interface ProjectEnvTaskValueReader {
+  readStaged(
+    projectId: string,
+    key: string,
+    stagingId: string,
+  ): Promise<string | null>;
+  readLegacy(
+    projectId: string,
+    key: string,
+    version: number,
+  ): Promise<{ value: string; version: number } | null>;
+}
+
+export interface ExactSsmParameter {
+  name: string;
+  type: string;
+  value: string;
+  version: number;
+}
+
+export interface ExactSsmParameterBatch {
+  parameters: readonly ExactSsmParameter[];
+  invalidParameters: readonly string[];
+}
+
+/** A testable, deliberately tiny surface over one explicitly credentialed client. */
+export interface CredentialSessionParameterReader {
+  getParameters(selectors: readonly string[]): Promise<ExactSsmParameterBatch>;
+  destroy?(): void | Promise<void>;
+}
+
+export type CredentialSessionReaderFactory = (args: {
+  region: string;
+  session: Readonly<LeaseSession>;
+  assignment: Readonly<TaskAssignment>;
+}) => CredentialSessionParameterReader;
+
+export interface TaskCredentialLeaseRegistryOptions {
+  runnerKind: "owned" | "task-machine";
+  send(frame: LeaseRequestV1Frame | CredentialRefreshFrame): boolean;
+  /**
+   * Must synchronously stop new consumers/spawns for this assignment.
+   * Throwing quarantines the assignment until a successful close is followed
+   * by full cleanup; callers must never treat an exception as a closed gate.
+   */
+  closeTaskGate(
+    assignment: Readonly<TaskAssignment>,
+    reason: LeaseGateCloseReason,
+  ): void;
+  /**
+   * A grant was accepted for the assignment (synchronously, before anything
+   * of it is read): what the returned function undoes ends when that grant's
+   * handling does. The env replica refuses the run's frames meanwhile, until
+   * the grant's own reader activates.
+   */
+  grantAccepted?(assignment: Readonly<TaskAssignment>): (() => void) | void;
+  /** Called only after all private reads and validation have succeeded. */
+  openTaskGate?(
+    assignment: Readonly<TaskAssignment>,
+    view: TaskCredentialView,
+  ): void;
+  cleanupExternal(request: CredentialCleanupRequest): Promise<void>;
+  /**
+   * Installs files/proxy/engine consumers transactionally.  The env-replica
+   * integration uses `projectSetChanged` to await an exact committed snapshot
+   * before returning; the registry does not open its gate before this resolves.
+   */
+  installExternal?(request: CredentialInstallRequest): Promise<void>;
+  createSessionReader?: CredentialSessionReaderFactory;
+  now?: () => number;
+  setTimer?: typeof setTimeout;
+  clearTimer?: typeof clearTimeout;
+  randomId?: () => string;
+  onError?(error: Error, assignment: Readonly<TaskAssignment>): void;
+}
+
+export interface LeaseDenyFrame {
+  kind: "lease.deny";
+  opId: string;
+  error: string;
+}
+
+type CredentialDescriptor = {
+  class: CredentialCleanupIdentity["class"];
+  credentialId: string;
+  revision: string | null;
+  parameter: string | null;
+  version: number | null;
+  sessionId: string | null;
+  authKind: "env" | "config-dir" | "oauth" | "token" | "none" | null;
+  location: CredentialLocation | null;
+};
+
+type CredentialRecord = {
+  descriptor: CredentialDescriptor;
+  availability: CredentialMaterialAvailability;
+  material: LeasedValue | null;
+  observedVersion: number | null;
+};
+
+class ManagedSessionReader {
+  readonly id: string;
+  readonly #reader: CredentialSessionParameterReader;
+  #sealed = false;
+  #inFlight = 0;
+  #drained: Array<() => void> = [];
+  #destroyed = false;
+
+  constructor(id: string, reader: CredentialSessionParameterReader) {
+    this.id = id;
+    this.#reader = reader;
+  }
+
+  async read(selectors: readonly string[]): Promise<ExactSsmParameterBatch> {
+    if (this.#sealed) throw new CredentialLeaseUnavailableError("credential reader is sealed");
+    this.#inFlight++;
+    try {
+      return await this.#reader.getParameters(selectors);
+    } finally {
+      this.#inFlight--;
+      if (this.#inFlight === 0) {
+        for (const resolve of this.#drained.splice(0)) resolve();
+      }
+    }
+  }
+
+  seal(): void {
+    this.#sealed = true;
+  }
+
+  async destroyWhenDrained(): Promise<void> {
+    this.seal();
+    if (this.#inFlight > 0) {
+      await new Promise<void>((resolve) => this.#drained.push(resolve));
+    }
+    if (this.#destroyed) return;
+    this.#destroyed = true;
+    await this.#reader.destroy?.();
+  }
+}
+
+type LeaseBundle = {
+  lease: TaskLeaseV1;
+  expiresAt: number;
+  readers: Map<string, ManagedSessionReader>;
+  records: Map<string, CredentialRecord>;
+  projectSessions: Map<string, string>;
+  view: TaskCredentialView;
+};
+
+type PendingLease = {
+  opId: string;
+  timer: Timer;
+  answering: boolean;
+};
+
+type RefreshPending = {
+  opId: string;
+  key: string;
+  assignment: TaskAssignment;
+  credentialId: string;
+  revision: string;
+  bundleGeneration: number;
+  timer: Timer;
+  resolve(result: CredentialRefreshResultFrame): void;
+};
+
+type ReadyWaiter = {
+  resolve(view: TaskCredentialView): void;
+  reject(error: Error): void;
+  signal?: AbortSignal;
+  abort?: () => void;
+};
+
+type TaskState = {
+  assignment: TaskAssignment;
+  phase: "recovering" | "waiting" | "usable" | "narrowing" | "lost" | "ended";
+  gateOpen: boolean;
+  gateCloseFailed: boolean;
+  bundle: LeaseBundle | null;
+  bundleGeneration: number;
+  wantedRevision: number;
+  minRevision: number;
+  /**
+   * Non-secret identities from the last installed bundle. A below-floor
+   * bundle is destroyed after its first selective cleanup, but the cloud may
+   * advance the floor again before a replacement grant arrives. Keep just
+   * enough identity to qualify those later accumulated removals.
+   */
+  identitiesByCredentialId: Map<string, CredentialCleanupIdentity>;
+  removed: Map<string, CredentialCleanupIdentity>;
+  cleaned: Set<string>;
+  pendingLease: PendingLease | null;
+  refreshByOp: Map<string, RefreshPending>;
+  refreshByCredential: Map<string, Promise<CredentialRefreshResultFrame>>;
+  renewalTimer: Timer | null;
+  retryTimer: Timer | null;
+  expiryTimer: Timer | null;
+  floorTimer: Timer | null;
+  /** A failed cleanup's retry. A full cleanup cancels the one pending when
+   *  it starts, and while it is under way or failed no selective one is
+   *  armed: a selective retry never masks a full cleanup's. */
+  cleanupRetryTimer: Timer | null;
+  floorDeadlineAt: number | null;
+  cleanupTail: Promise<void>;
+  fullCleanup: Promise<void> | null;
+  startup:
+    | { kind: "recovery" }
+    | { kind: "predecessor"; state: TaskState }
+    | null;
+  startupPromise: Promise<void> | null;
+  waiters: Set<ReadyWaiter>;
+  sequence: number;
+  /**
+   * Transitions that closed the gate to clean credentials up (a grant's
+   * narrowing, a refusal) and have not yet opened it on their own view.
+   * While one holds it, no other open may happen: a view committed before
+   * (a grant still draining its predecessor's readers) would otherwise
+   * reopen the gate on what is being cleaned up.
+   */
+  gateHolds: number;
+};
+
+export class CredentialLeaseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialLeaseError";
+  }
+}
+
+export class CredentialLeaseUnavailableError extends CredentialLeaseError {
+  constructor(message = "task credentials are not usable") {
+    super(message);
+    this.name = "CredentialLeaseUnavailableError";
+  }
+}
+
+function assignmentMatches(a: TaskAssignment, b: TaskAssignment): boolean {
+  return a.taskId === b.taskId && a.runEpoch === b.runEpoch;
+}
+
+function cloneAssignment(assignment: TaskAssignment): TaskAssignment {
+  return { taskId: assignment.taskId, runEpoch: assignment.runEpoch };
+}
+
+function validAssignment(assignment: TaskAssignment): boolean {
+  return (
+    typeof assignment.taskId === "string" &&
+    assignment.taskId.length > 0 &&
+    assignment.taskId.length <= 128 &&
+    !/[\u0000-\u001f\u007f]/.test(assignment.taskId) &&
+    Number.isSafeInteger(assignment.runEpoch) &&
+    assignment.runEpoch > 0
+  );
+}
+
+function digestManifest(lease: TaskLeaseV1): string {
+  return createHash("sha256")
+    .update(canonicalManifestJson(lease.manifest), "utf8")
+    .digest("hex");
+}
+
+function credentialKey(identity: CredentialCleanupIdentity): string {
+  return JSON.stringify([identity.class, identity.credentialId, identity.revision]);
+}
+
+function descriptorIdentity(descriptor: CredentialDescriptor): CredentialCleanupIdentity {
+  return {
+    class: descriptor.class,
+    credentialId: descriptor.credentialId,
+    revision: descriptor.revision,
+  };
+}
+
+function descriptorKey(descriptor: CredentialDescriptor): string {
+  return credentialKey(descriptorIdentity(descriptor));
+}
+
+function descriptorFromEngine(entry: LeaseManifestEngine): CredentialDescriptor {
+  return {
+    class: "engine",
+    credentialId: entry.credentialId,
+    revision: entry.revision,
+    parameter: entry.parameter,
+    version: entry.version,
+    sessionId: entry.sessionId,
+    authKind: entry.authKind,
+    location: parseLeaseParameterName(entry.parameter),
+  };
+}
+
+function descriptorFromMcp(entry: LeaseManifestMcp): CredentialDescriptor {
+  return {
+    class: "mcp",
+    credentialId: entry.credentialId,
+    revision: entry.revision,
+    parameter: entry.parameter,
+    version: entry.version,
+    sessionId: entry.sessionId,
+    authKind: entry.authKind,
+    location: entry.parameter === null ? null : parseLeaseParameterName(entry.parameter),
+  };
+}
+
+function descriptorFromStatic(
+  entry: LeaseManifestStatic,
+  credentialClass: "github" | "ssh",
+): CredentialDescriptor {
+  return {
+    class: credentialClass,
+    credentialId: entry.credentialId,
+    revision: entry.revision,
+    parameter: entry.parameter,
+    version: entry.version,
+    sessionId: entry.sessionId,
+    authKind: null,
+    location: parseLeaseParameterName(entry.parameter),
+  };
+}
+
+function manifestDescriptors(lease: TaskLeaseV1): CredentialDescriptor[] {
+  const out: CredentialDescriptor[] = [
+    ...lease.manifest.engines.map(descriptorFromEngine),
+    ...lease.manifest.mcp.map(descriptorFromMcp),
+  ];
+  if (lease.manifest.github) out.push(descriptorFromStatic(lease.manifest.github, "github"));
+  if (lease.manifest.ssh) out.push(descriptorFromStatic(lease.manifest.ssh, "ssh"));
+  return out;
+}
+
+function materialMatchesDescriptor(
+  material: LeasedValue,
+  descriptor: CredentialDescriptor,
+): boolean {
+  if (material.class !== descriptor.class) return false;
+  if (material.class === "engine") return material.authKind === descriptor.authKind;
+  if (material.class === "mcp") return material.authKind === descriptor.authKind;
+  return descriptor.authKind === null;
+}
+
+function freezeMaterial<T extends LeasedValue>(material: T): Readonly<T> {
+  Object.freeze(material.location);
+  if (material.class === "engine") {
+    if (material.authKind === "env") Object.freeze(material.env);
+    else Object.freeze(material.files);
+  } else if (material.class === "mcp" && material.authKind === "token") {
+    Object.freeze(material.header);
+  }
+  return Object.freeze(material);
+}
+
+function freezeView(
+  lease: TaskLeaseV1,
+  expiresAt: number,
+  records: ReadonlyMap<string, CredentialRecord>,
+): TaskCredentialView {
+  const requireRecord = (credentialId: string): CredentialRecord => {
+    const record = records.get(credentialId);
+    if (!record) throw new CredentialLeaseError("credential material is incomplete");
+    return record;
+  };
+  const engines = lease.manifest.engines.map((manifest) => {
+    const record = requireRecord(manifest.credentialId);
+    if (
+      record.availability === "not-required" ||
+      (record.availability === "available" &&
+        (record.material?.class !== "engine" || record.observedVersion === null)) ||
+      (record.availability === "access-denied" &&
+        (record.material !== null || record.observedVersion !== null))
+    ) {
+      throw new CredentialLeaseError("engine material is incomplete");
+    }
+    return Object.freeze({
+      manifest: Object.freeze({ ...manifest }),
+      availability: record.availability,
+      material: record.material as Readonly<EngineLeasedValue> | null,
+      observedVersion: record.observedVersion,
+    });
+  });
+  const mcp = lease.manifest.mcp.map((manifest) => {
+    const record = requireRecord(manifest.credentialId);
+    if (
+      (manifest.authKind === "none" &&
+        (record.availability !== "not-required" || record.material !== null)) ||
+      (manifest.authKind !== "none" && record.availability === "not-required") ||
+      (record.availability === "available" && record.material?.class !== "mcp") ||
+      (record.availability === "access-denied" && record.material !== null)
+    ) {
+      throw new CredentialLeaseError("MCP material is incomplete");
+    }
+    return Object.freeze({
+      manifest: Object.freeze({ ...manifest }),
+      availability: record.availability,
+      material: record.material as Readonly<McpLeasedValue> | null,
+      observedVersion: record.observedVersion,
+    });
+  });
+  const staticCredential = <T extends GithubLeasedValue | SshLeasedValue>(
+    manifest: LeaseManifestStatic | null,
+    credentialClass: T["class"],
+  ): TaskStaticCredential<T> | null => {
+    if (!manifest) return null;
+    const record = requireRecord(manifest.credentialId);
+    if (
+      record.availability === "not-required" ||
+      (record.availability === "available" &&
+        (record.material?.class !== credentialClass || record.observedVersion === null)) ||
+      (record.availability === "access-denied" &&
+        (record.material !== null || record.observedVersion !== null))
+    ) {
+      throw new CredentialLeaseError(`${credentialClass} material is incomplete`);
+    }
+    return Object.freeze({
+      manifest: Object.freeze({ ...manifest }),
+      availability: record.availability,
+      material: record.material as T | null,
+      observedVersion: record.observedVersion,
+    });
+  };
+  return Object.freeze({
+    assignment: Object.freeze({ taskId: lease.taskId, runEpoch: lease.runEpoch }),
+    leaseId: lease.leaseId,
+    manifestRevision: lease.manifestRevision,
+    manifestDigest: lease.manifestDigest,
+    expiresAt,
+    projectIds: Object.freeze(lease.manifest.projects.map((project) => project.projectId)),
+    engines: Object.freeze(engines),
+    mcp: Object.freeze(mcp),
+    github: staticCredential<GithubLeasedValue>(lease.manifest.github, "github"),
+    ssh: staticCredential<SshLeasedValue>(lease.manifest.ssh, "ssh"),
+  });
+}
+
+function projectSetKey(lease: TaskLeaseV1): string {
+  return JSON.stringify([...lease.manifest.projects.map((item) => item.projectId)].sort());
+}
+
+function validateProjectValueRead(request: StructuredProjectValueRead): void {
+  if (!PROJECT_PATH_SEGMENT.test(request.projectId) || !PROJECT_ENV_KEY.test(request.key)) {
+    throw new CredentialLeaseError("invalid project env identity");
+  }
+  if (request.valueRef.kind === "row") {
+    throw new CredentialLeaseError("a cloud lease cannot read a row-backed value");
+  }
+}
+
+function projectValueReaderOf(
+  read: (request: StructuredProjectValueRead) => Promise<ProjectValueReadResult | null>,
+): ProjectEnvTaskValueReader {
+  return {
+    readStaged: async (projectId, key, stagingId) =>
+      (await read({ projectId, key, valueRef: { kind: "staged", stagingId } }))?.rawValue ?? null,
+    readLegacy: async (projectId, key, version) => {
+      const result = await read({ projectId, key, valueRef: { kind: "legacy", ssmVersion: version } });
+      return result ? { value: result.rawValue, version: result.version } : null;
+    },
+  };
+}
+
+function defaultSessionReaderFactory(args: {
+  region: string;
+  session: Readonly<LeaseSession>;
+}): CredentialSessionParameterReader {
+  const client = new SSMClient({
+    region: args.region,
+    credentials: {
+      accessKeyId: args.session.accessKeyId,
+      secretAccessKey: args.session.secretAccessKey,
+      sessionToken: args.session.sessionToken,
+      expiration: new Date(args.session.expiresAt),
+    },
+  });
+  return {
+    async getParameters(selectors) {
+      const output = await client.send(
+        new GetParametersCommand({ Names: [...selectors], WithDecryption: true }),
+      );
+      const normalize = (parameter: Parameter): ExactSsmParameter => {
+        if (
+          typeof parameter.Name !== "string" ||
+          typeof parameter.Type !== "string" ||
+          typeof parameter.Value !== "string" ||
+          typeof parameter.Version !== "number"
+        ) {
+          throw new CredentialLeaseError("Parameter Store returned an incomplete parameter");
+        }
+        return {
+          name: parameter.Name,
+          type: parameter.Type,
+          value: parameter.Value,
+          version: parameter.Version,
+        };
+      };
+      return {
+        parameters: (output.Parameters ?? []).map(normalize),
+        invalidParameters: output.InvalidParameters ?? [],
+      };
+    },
+    destroy: () => client.destroy(),
+  };
+}
+
+function parseLeaseDenyFrame(value: unknown): LeaseDenyFrame | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const frame = value as Record<string, unknown>;
+  if (
+    Object.keys(frame).length !== 3 ||
+    !Object.hasOwn(frame, "kind") ||
+    !Object.hasOwn(frame, "opId") ||
+    !Object.hasOwn(frame, "error") ||
+    frame.kind !== "lease.deny" ||
+    typeof frame.opId !== "string" ||
+    !OP_ID.test(frame.opId) ||
+    typeof frame.error !== "string" ||
+    frame.error.length === 0 ||
+    frame.error.length > MAX_ERROR_CHARS
+  ) {
+    return null;
+  }
+  return { kind: "lease.deny", opId: frame.opId, error: frame.error };
+}
+
+function unavailableRefresh(opId: string): CredentialRefreshResultFrame {
+  return {
+    kind: "credential.refresh.result",
+    opId,
+    outcome: "unavailable",
+    version: null,
+    expiresAt: null,
+  };
+}
+
+function exactJsonObject(
+  raw: string,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): Record<string, unknown> | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const object = value as Record<string, unknown>;
+  const keys = Object.keys(object);
+  if (
+    required.some((key) => !Object.hasOwn(object, key)) ||
+    keys.some((key) => !required.includes(key) && !optional.includes(key))
+  ) {
+    return null;
+  }
+  return object;
+}
+
+function openProjectValue(args: {
+  raw: string;
+  lease: TaskLeaseV1;
+  projectId: string;
+  key: string;
+  valueRef: Exclude<ProjectEnvValueRef, { kind: "row" }>;
+}): string | null {
+  if (args.valueRef.kind === "staged") {
+    const object = exactJsonObject(args.raw, [
+      "v",
+      "kind",
+      "orgId",
+      "projectId",
+      "key",
+      "stagingId",
+      "value",
+    ]);
+    return object &&
+      object.v === 2 &&
+      object.kind === "project-env" &&
+      object.orgId === args.lease.orgId &&
+      object.projectId === args.projectId &&
+      object.key === args.key &&
+      object.stagingId === args.valueRef.stagingId &&
+      typeof object.value === "string"
+      ? object.value
+      : null;
+  }
+  const object = exactJsonObject(
+    args.raw,
+    ["v", "kind", "projectId", "key", "value", "updatedAt"],
+    ["orgId"],
+  );
+  return object &&
+    object.v === 1 &&
+    object.kind === "project-env" &&
+    object.projectId === args.projectId &&
+    object.key === args.key &&
+    typeof object.value === "string" &&
+    typeof object.updatedAt === "number" &&
+    Number.isFinite(object.updatedAt) &&
+    (object.orgId === undefined || object.orgId === args.lease.orgId)
+    ? object.value
+    : null;
+}
+
+export class TaskCredentialLeaseRegistry {
+  readonly #opts: TaskCredentialLeaseRegistryOptions & {
+    now: () => number;
+    setTimer: typeof setTimeout;
+    clearTimer: typeof clearTimeout;
+    randomId: () => string;
+    createSessionReader: CredentialSessionReaderFactory;
+  };
+  readonly #tasks = new Map<string, TaskState>();
+
+  constructor(options: TaskCredentialLeaseRegistryOptions) {
+    this.#opts = {
+      ...options,
+      now: options.now ?? Date.now,
+      setTimer: options.setTimer ?? setTimeout,
+      clearTimer: options.clearTimer ?? clearTimeout,
+      randomId: options.randomId ?? randomUUID,
+      createSessionReader: options.createSessionReader ?? defaultSessionReaderFactory,
+    };
+  }
+
+  async startAssignment(
+    assignment: TaskAssignment,
+    options: { recovery?: boolean } = {},
+  ): Promise<void> {
+    if (!validAssignment(assignment)) throw new CredentialLeaseError("invalid task assignment");
+    const current = this.#tasks.get(assignment.taskId);
+    if (current) {
+      if (assignment.runEpoch < current.assignment.runEpoch) {
+        throw new CredentialLeaseError("stale task assignment");
+      }
+      if (assignment.runEpoch === current.assignment.runEpoch) {
+        if (current.phase === "recovering") {
+          await this.#finishStartup(current);
+        } else if (current.phase !== "ended") {
+          this.#request(current);
+        }
+        return;
+      }
+      this.#endSynchronously(current, "superseded");
+    }
+
+    const needsStartupCleanup = Boolean(current || options.recovery);
+    const state = this.#newState(
+      assignment,
+      needsStartupCleanup ? "recovering" : "waiting",
+    );
+    state.startup = current
+      ? { kind: "predecessor", state: current }
+      : options.recovery
+        ? { kind: "recovery" }
+        : null;
+    this.#tasks.set(assignment.taskId, state);
+    const gateClosed = this.#closeGate(
+      state,
+      options.recovery ? "recovery" : "starting",
+    );
+
+    if (needsStartupCleanup) {
+      await this.#finishStartup(state);
+      if (!gateClosed) {
+        await this.#fullCleanupAndContinue(state, "cleanup-failed");
+      }
+    } else if (!gateClosed) {
+      await this.#fullCleanupAndContinue(state, "cleanup-failed");
+    } else {
+      this.#request(state);
+    }
+  }
+
+  /** Same-process authenticated reconnect: preserve safe bundles, replace requests. */
+  bridgeAuthenticated(): void {
+    for (const state of this.#tasks.values()) {
+      if (state.phase === "ended") continue;
+      this.#cancelPendingLease(state);
+      this.#request(state);
+    }
+  }
+
+  async handleGrant(value: unknown): Promise<void> {
+    const frame = parseLeaseGrantV1Frame(value);
+    if (!frame) return;
+    const state = this.#tasks.get(frame.lease.taskId);
+    if (
+      !state ||
+      state.assignment.runEpoch !== frame.lease.runEpoch ||
+      !state.pendingLease ||
+      state.pendingLease.opId !== frame.opId ||
+      state.pendingLease.answering
+    ) {
+      return;
+    }
+    state.pendingLease.answering = true;
+    this.#opts.clearTimer(state.pendingLease.timer);
+    // Accepted, synchronously: the reader this grant's install will read
+    // through is not active yet. What the hook arms ends with this grant's
+    // handling, whatever its outcome, and no other grant's.
+    let settle: (() => void) | void = undefined;
+    try {
+      settle = this.#opts.grantAccepted?.(cloneAssignment(state.assignment));
+    } catch (error) {
+      this.#report(error, state.assignment);
+    }
+    try {
+      await this.#answerGrant(state, frame);
+    } finally {
+      settle?.();
+    }
+  }
+
+  async #answerGrant(state: TaskState, frame: LeaseGrantV1Frame): Promise<void> {
+    const baseGeneration = state.bundleGeneration;
+    let candidate: LeaseBundle | null = null;
+    let externalInstallAttempted = false;
+    let installing = false;
+    let holding = false;
+    const release = (): void => {
+      if (!holding) return;
+      holding = false;
+      this.#releaseHold(state);
+    };
+    try {
+      this.#validateGrantBeforeRead(state, frame);
+      candidate = await this.#materializeBundle(state, frame.lease);
+      this.#assertCandidateCurrent(state, frame, baseGeneration, candidate);
+      await this.#preserveObservedVersions(
+        state,
+        frame,
+        baseGeneration,
+        candidate,
+      );
+      this.#assertCandidateCurrent(state, frame, baseGeneration, candidate);
+
+      const old = state.bundle;
+      // A credential that left the task goes before the candidate is
+      // installed, and so does one the task could read and now cannot
+      // (refused, §6): its files and whatever uses them.
+      const narrowed = old
+        ? [...this.#removedIdentities(old, candidate), ...this.#refusedIdentities(old, candidate)]
+        : [
+            ...this.#removedKnownIdentities(state, candidate),
+            ...this.#refusedKnownIdentities(state, candidate),
+          ];
+      if (narrowed.length > 0) {
+        this.#closeGate(state, "manifest-narrowed");
+        if (old) this.#sealBundle(old);
+        // Closed until this grant opens it on its own view.
+        state.gateHolds++;
+        holding = true;
+        await this.#runCleanup(state, {
+          assignment: cloneAssignment(state.assignment),
+          mode: "selective",
+          reason: "lease-replaced",
+          removed: narrowed,
+          removeFilesSession: false,
+        });
+        this.#assertCandidateCurrent(state, frame, baseGeneration, candidate);
+      }
+
+      this.#assertCandidateCurrent(state, frame, baseGeneration, candidate);
+      const previousView = old?.view ?? null;
+      const files = this.#filesAccess(candidate);
+      const granted = candidate;
+      // From its install until its own open: still this grant's candidate,
+      // or committed and not yet opened.
+      const installingNow = (): boolean =>
+        installing &&
+        this.#isActive(state) &&
+        !state.gateCloseFailed &&
+        state.fullCleanup === null &&
+        granted.expiresAt > this.#opts.now() &&
+        granted.lease.manifestRevision >= state.minRevision &&
+        (state.bundle === granted ||
+          (state.pendingLease?.opId === frame.opId && state.bundleGeneration === baseGeneration));
+      const installRequest: CredentialInstallRequest = {
+        assignment: cloneAssignment(state.assignment),
+        owner: { orgId: candidate.lease.orgId, userId: candidate.lease.userId },
+        previous: previousView,
+        next: candidate.view,
+        files,
+        reason: "grant",
+        projectSetChanged: !old || projectSetKey(old.lease) !== projectSetKey(candidate.lease),
+        projectValues: this.#grantProjectValueReader(state, granted, installingNow),
+        isCurrent: installingNow,
+      };
+      externalInstallAttempted = this.#opts.installExternal !== undefined;
+      installing = true;
+      await this.#runInstall(state, installRequest);
+      this.#assertCandidateCurrent(state, frame, baseGeneration, candidate);
+
+      state.pendingLease = null;
+      state.bundle = candidate;
+      candidate = null;
+      state.bundleGeneration++;
+      const installedBundle = state.bundle;
+      const installedGeneration = state.bundleGeneration;
+      state.identitiesByCredentialId = new Map(
+        [...installedBundle.records.values()].map((record) => [
+          record.descriptor.credentialId,
+          descriptorIdentity(record.descriptor),
+        ]),
+      );
+      state.wantedRevision = Math.max(
+        state.wantedRevision,
+        installedBundle.lease.manifestRevision,
+      );
+      if (installedBundle.lease.manifestRevision >= state.minRevision) {
+        this.#clearFloor(state);
+      }
+      this.#armBundleTimers(state);
+      if (old) await this.#destroyBundle(old);
+      // A narrowing's release opens the view committed now: this grant's, or
+      // a newer one whose own open its hold kept closed meanwhile.
+      try {
+        if (holding) release();
+        else this.#openGate(state, installedBundle, installedGeneration);
+      } finally {
+        installing = false;
+      }
+      if (
+        this.#isActive(state) &&
+        state.bundle &&
+        state.bundle.lease.manifestRevision < state.wantedRevision
+      ) {
+        this.#request(state);
+      }
+    } catch (error) {
+      installing = false;
+      // The callback may have written files before a concurrent stale/stop
+      // fence invalidated this candidate. Its serialized cleanup must run
+      // after that write; never assume a failed/aborted preparation was
+      // side-effect free. A narrowing that did not reach its own open takes
+      // the same path, and takes it before its hold goes: the full cleanup
+      // makes the assignment lost at once, so a view committed before the
+      // narrowing (a grant still draining its predecessor) cannot reopen the
+      // gate on credentials whose cleanup failed or never finished.
+      const escalation =
+        (holding || externalInstallAttempted || state.gateCloseFailed) && this.#isActive(state)
+          ? this.#fullCleanupAndContinue(state, "manifest-narrowed")
+          : null;
+      release();
+      if (state.pendingLease?.opId === frame.opId) state.pendingLease = null;
+      if (candidate) await this.#destroyBundle(candidate);
+      this.#report(error, state.assignment);
+      if (escalation) {
+        try {
+          await escalation;
+        } catch {
+          // The cleanup path has already closed the gate and armed its retry.
+        }
+      } else if (this.#isActive(state)) {
+        this.#armRetry(state);
+      }
+    }
+  }
+
+  handleUnavailable(value: unknown): void {
+    const frame = parseLeaseUnavailableFrame(value);
+    if (!frame) return;
+    const state = this.#stateForPending(frame.opId);
+    if (!state) return;
+    this.#cancelPendingLease(state);
+    this.#armRetry(state);
+  }
+
+  async handleDenied(value: unknown): Promise<void> {
+    const frame = parseLeaseDenyFrame(value);
+    if (!frame) return;
+    const state = this.#stateForPending(frame.opId);
+    if (!state) return;
+    this.#cancelPendingLease(state);
+    this.#closeGate(state, "denied");
+    await this.#fullCleanupAndContinue(state, "denied");
+  }
+
+  handleStale(value: unknown): void {
+    const frame = parseLeaseStaleFrame(value);
+    if (!frame) return;
+    const state = this.#tasks.get(frame.taskId);
+    if (!state || state.assignment.runEpoch !== frame.runEpoch || state.phase === "ended") {
+      return;
+    }
+    // Notice delivery and lease issuance are independent async paths on the
+    // cloud. A notice can therefore be read from the pending row, then arrive
+    // after a grant at or above its floor has already installed. That grant's
+    // replacement cleanup has dealt with what left; resolving `removed`
+    // against the new bundle would instead target a re-added/new revision.
+    const installedRevision = state.bundle?.lease.manifestRevision ?? 0;
+    const handledFloorRevision = Math.max(state.minRevision, installedRevision);
+    if (
+      frame.wantedRevision <= state.wantedRevision &&
+      (frame.minRevision ?? 0) <= handledFloorRevision
+    ) {
+      return;
+    }
+    state.wantedRevision = Math.max(state.wantedRevision, frame.wantedRevision);
+    if (frame.minRevision !== null) {
+      const floorAlreadyHandled = frame.minRevision <= handledFloorRevision;
+      state.minRevision = Math.max(state.minRevision, frame.minRevision);
+      if (!floorAlreadyHandled) {
+        for (const credentialId of frame.removed) {
+          const record = state.bundle?.records.get(credentialId);
+          const identity = record
+            ? descriptorIdentity(record.descriptor)
+            : state.identitiesByCredentialId.get(credentialId);
+          if (!identity) continue;
+          state.removed.set(credentialKey(identity), identity);
+        }
+        if (
+          (state.bundle && state.bundle.lease.manifestRevision < state.minRevision) ||
+          this.#hasUncleanedRemovals(state)
+        ) {
+          this.#beginNarrowing(state);
+        }
+      }
+    }
+    this.#cancelPendingLease(state);
+    this.#request(state);
+  }
+
+  async handleCredentialChanged(value: unknown): Promise<void> {
+    const frame = parseCredentialChangedFrame(value);
+    if (!frame) return;
+    const state = this.#tasks.get(frame.taskId);
+    if (!state || state.assignment.runEpoch !== frame.runEpoch) return;
+    try {
+      await this.#applyCredentialVersion(state, frame);
+    } catch (error) {
+      this.#report(error, state.assignment);
+      if (this.#isActive(state)) this.#request(state);
+    }
+  }
+
+  /**
+   * ADR-154 §6: a launch slot of `assignment`'s exact run could not be
+   * retired in its runtime, so a launch handed over before its retirement
+   * may still start there. The run's full cleanup runs: its gate closed at
+   * once, every engine of the run stopped in every runtime it ran in (or the
+   * runtime stopped), then a new grant. One that fails is retried, its gate
+   * closed meanwhile. Nothing for a run that is not the task's live one: its
+   * own cleanup covers it.
+   */
+  escalateLaunchFence(assignment: TaskAssignment): void {
+    const state = this.#tasks.get(assignment.taskId);
+    if (!state || !assignmentMatches(state.assignment, assignment) || !this.#isActive(state)) return;
+    this.#background(this.#fullCleanupAndContinue(state, "fence-failed"), state.assignment);
+  }
+
+  requestCredentialRefresh(
+    assignment: TaskAssignment,
+    credentialId: string,
+    revision: string,
+  ): Promise<CredentialRefreshResultFrame> {
+    const state = this.#requireUsableState(assignment);
+    const record = state.bundle!.records.get(credentialId);
+    if (!record || record.descriptor.revision !== revision || revision === null) {
+      return Promise.reject(new CredentialLeaseError("credential is not in the active manifest"));
+    }
+    const key = `${credentialId}\u0000${revision}`;
+    const existing = state.refreshByCredential.get(key);
+    if (existing) return existing;
+    const opId = this.#opId("refresh", state);
+    let pending!: RefreshPending;
+    const promise = new Promise<CredentialRefreshResultFrame>((resolve) => {
+      const timer = this.#opts.setTimer(() => {
+        state.refreshByOp.delete(opId);
+        state.refreshByCredential.delete(key);
+        resolve(unavailableRefresh(opId));
+      }, LEASE_REQUEST_TIMEOUT_MS);
+      timer.unref?.();
+      pending = {
+        opId,
+        key,
+        assignment: cloneAssignment(assignment),
+        credentialId,
+        revision,
+        bundleGeneration: state.bundleGeneration,
+        timer,
+        resolve,
+      };
+      state.refreshByOp.set(opId, pending);
+    });
+    state.refreshByCredential.set(key, promise);
+    const sent = this.#safeSend({
+      kind: "credential.refresh",
+      opId,
+      taskId: assignment.taskId,
+      runEpoch: assignment.runEpoch,
+      credentialId,
+      revision,
+    });
+    if (!sent) this.#settleRefresh(state, pending, unavailableRefresh(opId));
+    return promise;
+  }
+
+  async handleRefreshResult(value: unknown): Promise<void> {
+    const frame = parseCredentialRefreshResultFrame(value);
+    if (!frame) return;
+    let state: TaskState | null = null;
+    let pending: RefreshPending | null = null;
+    for (const candidate of this.#tasks.values()) {
+      const found = candidate.refreshByOp.get(frame.opId);
+      if (found) {
+        state = candidate;
+        pending = found;
+        break;
+      }
+    }
+    if (!state || !pending) return;
+    if (
+      !this.#isActive(state) ||
+      !assignmentMatches(state.assignment, pending.assignment) ||
+      state.bundleGeneration !== pending.bundleGeneration
+    ) {
+      this.#settleRefresh(state, pending, unavailableRefresh(frame.opId));
+      return;
+    }
+    if (frame.outcome === "refreshed" || frame.outcome === "fresh") {
+      try {
+        await this.#applyCredentialVersion(state, {
+          kind: "credential.changed",
+          taskId: state.assignment.taskId,
+          runEpoch: state.assignment.runEpoch,
+          credentialId: pending.credentialId,
+          revision: pending.revision,
+          version: frame.version!,
+        });
+      } catch (error) {
+        this.#report(error, state.assignment);
+        this.#request(state);
+      }
+    } else if (frame.outcome === "needs_sign_in") {
+      // The authoritative stale frame supplies any floor and removals.
+      this.#request(state);
+    }
+    this.#settleRefresh(state, pending, frame);
+  }
+
+  async closeAssignment(
+    assignment: TaskAssignment,
+    reason: "stop" | "park" | "teardown" | "superseded" = "stop",
+  ): Promise<void> {
+    const state = this.#tasks.get(assignment.taskId);
+    if (!state || !assignmentMatches(state.assignment, assignment)) return;
+    const gateReason: LeaseGateCloseReason =
+      reason === "stop"
+        ? "stopped"
+        : reason === "park"
+          ? "parked"
+          : reason === "teardown"
+            ? "teardown"
+            : "superseded";
+    this.#endSynchronously(state, gateReason);
+    await this.#completeEndedCleanup(state, gateReason);
+    if (this.#tasks.get(assignment.taskId) === state) this.#tasks.delete(assignment.taskId);
+  }
+
+  /**
+   * The runner process is ending. Every assignment ends now, synchronously:
+   * its gate closed, its timers cancelled, its waiters and refreshes
+   * answered, its readers sealed. No cleanup runs here: agents that survive
+   * the restart keep what they hold (§5), and the next process's recovery
+   * sweep cleans up before it reattaches them, as after a crash. Nothing
+   * that arrives later finds an assignment. Resolves once the readers in
+   * flight have drained.
+   */
+  async shutdown(): Promise<void> {
+    const states = [...this.#tasks.values()];
+    this.#tasks.clear();
+    for (const state of states) {
+      if (state.phase !== "ended") this.#endSynchronously(state, "shutdown");
+    }
+    await Promise.allSettled(
+      states.map((state) => (state.bundle ? this.#destroyBundle(state.bundle) : undefined)),
+    );
+  }
+
+  currentView(assignment: TaskAssignment): TaskCredentialView | null {
+    const state = this.#tasks.get(assignment.taskId);
+    if (!state || !assignmentMatches(state.assignment, assignment)) return null;
+    if (!this.#bundleIsUsable(state)) return null;
+    return state.bundle!.view;
+  }
+
+  filesAccess(assignment: TaskAssignment): TaskLeaseFilesAccess | null {
+    const state = this.#tasks.get(assignment.taskId);
+    if (!state || !assignmentMatches(state.assignment, assignment)) return null;
+    if (!this.#bundleIsUsable(state)) return null;
+    return this.#filesAccess(state.bundle!);
+  }
+
+  waitUntilUsable(
+    assignment: TaskAssignment,
+    signal?: AbortSignal,
+  ): Promise<TaskCredentialView> {
+    const current = this.currentView(assignment);
+    if (current) return Promise.resolve(current);
+    const state = this.#tasks.get(assignment.taskId);
+    if (!state || !assignmentMatches(state.assignment, assignment) || state.phase === "ended") {
+      return Promise.reject(new CredentialLeaseUnavailableError("task assignment is not active"));
+    }
+    if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("aborted"));
+    return new Promise<TaskCredentialView>((resolve, reject) => {
+      const waiter: ReadyWaiter = { resolve, reject, signal };
+      if (signal) {
+        waiter.abort = () => {
+          state.waiters.delete(waiter);
+          reject(signal.reason ?? new Error("aborted"));
+        };
+        signal.addEventListener("abort", waiter.abort, { once: true });
+      }
+      state.waiters.add(waiter);
+    });
+  }
+
+  async readProjectValue(
+    assignment: TaskAssignment,
+    request: StructuredProjectValueRead,
+  ): Promise<ProjectValueReadResult | null> {
+    validateProjectValueRead(request);
+    const state = this.#requireUsableState(assignment);
+    const bundle = state.bundle!;
+    const generation = state.bundleGeneration;
+    return this.#readProjectValueFrom(bundle, () => this.#assertReadFence(state, bundle, generation), request);
+  }
+
+  projectValueReader(assignment: TaskAssignment): ProjectEnvTaskValueReader {
+    const bound = cloneAssignment(assignment);
+    return projectValueReaderOf((request) => this.readProjectValue(bound, request));
+  }
+
+  /**
+   * One grant's project values: through its own sessions while its grant
+   * installs it (the env replica's snapshot is read then, before the gate
+   * opens on it), then while it is the task's usable grant (a credential
+   * change keeps the grant's lease and sessions). Never through another
+   * grant's, and never once the grant is abandoned, replaced or ended.
+   */
+  #grantProjectValueReader(
+    state: TaskState,
+    granted: LeaseBundle,
+    installing: () => boolean,
+  ): ProjectEnvTaskValueReader {
+    return projectValueReaderOf(async (request) => {
+      validateProjectValueRead(request);
+      if (state.bundle?.lease === granted.lease && this.#bundleIsUsable(state)) {
+        const bundle = state.bundle;
+        const generation = state.bundleGeneration;
+        return this.#readProjectValueFrom(bundle, () => this.#assertReadFence(state, bundle, generation), request);
+      }
+      if (!installing()) throw new CredentialLeaseUnavailableError();
+      return this.#readProjectValueFrom(
+        granted,
+        () => {
+          if (!installing()) {
+            throw new CredentialLeaseUnavailableError("credential read crossed an assignment fence");
+          }
+        },
+        request,
+      );
+    });
+  }
+
+  async #readProjectValueFrom(
+    bundle: LeaseBundle,
+    assertFence: () => void,
+    request: StructuredProjectValueRead,
+  ): Promise<ProjectValueReadResult | null> {
+    if (request.valueRef.kind === "row") {
+      throw new CredentialLeaseError("a cloud lease cannot read a row-backed value");
+    }
+    const sessionId = bundle.projectSessions.get(request.projectId);
+    if (!sessionId) throw new CredentialLeaseError("project is not in the active manifest");
+    const reader = bundle.readers.get(sessionId);
+    if (!reader) throw new CredentialLeaseError("project credentials session is missing");
+
+    let parameter: string;
+    let selector: string;
+    let expectedVersion: number | null;
+    if (request.valueRef.kind === "staged") {
+      if (!PROJECT_ENV_STAGING_ID.test(request.valueRef.stagingId)) {
+        throw new CredentialLeaseError("invalid project env staging id");
+      }
+      const keyDigest = createHash("sha256").update(request.key, "utf8").digest("hex");
+      parameter = `/uai/projects/${request.projectId}/env-values/${keyDigest}/${request.valueRef.stagingId}`;
+      selector = parameter;
+      expectedVersion = null;
+    } else {
+      if (!Number.isSafeInteger(request.valueRef.ssmVersion) || request.valueRef.ssmVersion <= 0) {
+        throw new CredentialLeaseError("invalid legacy project env version");
+      }
+      parameter = `/uai/projects/${request.projectId}/env/${request.key}`;
+      selector = `${parameter}:${request.valueRef.ssmVersion}`;
+      expectedVersion = request.valueRef.ssmVersion;
+    }
+    const result = await reader.read([selector]);
+    assertFence();
+    if (result.invalidParameters.length === 1 && result.invalidParameters[0] === selector) {
+      if (result.parameters.length !== 0) {
+        throw new CredentialLeaseError("Parameter Store returned conflicting project results");
+      }
+      return null;
+    }
+    if (result.invalidParameters.length !== 0 || result.parameters.length !== 1) {
+      throw new CredentialLeaseError("Parameter Store returned an inexact project result");
+    }
+    const observed = result.parameters[0]!;
+    if (
+      observed.name !== parameter ||
+      observed.type !== "SecureString" ||
+      !Number.isSafeInteger(observed.version) ||
+      observed.version <= 0 ||
+      (expectedVersion !== null && observed.version !== expectedVersion)
+    ) {
+      throw new CredentialLeaseError("Parameter Store returned the wrong project parameter");
+    }
+    const opened = openProjectValue({
+      raw: observed.value,
+      lease: bundle.lease,
+      projectId: request.projectId,
+      key: request.key,
+      valueRef: request.valueRef,
+    });
+    if (opened === null) {
+      throw new CredentialLeaseError("project value envelope does not match its reference");
+    }
+    return { rawValue: observed.value, version: observed.version, parameter };
+  }
+
+  #newState(assignment: TaskAssignment, phase: TaskState["phase"]): TaskState {
+    return {
+      assignment: cloneAssignment(assignment),
+      phase,
+      gateOpen: false,
+      gateCloseFailed: false,
+      bundle: null,
+      bundleGeneration: 0,
+      wantedRevision: 0,
+      minRevision: 0,
+      identitiesByCredentialId: new Map(),
+      removed: new Map(),
+      cleaned: new Set(),
+      pendingLease: null,
+      refreshByOp: new Map(),
+      refreshByCredential: new Map(),
+      renewalTimer: null,
+      retryTimer: null,
+      expiryTimer: null,
+      floorTimer: null,
+      cleanupRetryTimer: null,
+      floorDeadlineAt: null,
+      cleanupTail: Promise.resolve(),
+      fullCleanup: null,
+      startup: null,
+      startupPromise: null,
+      waiters: new Set(),
+      sequence: 0,
+      gateHolds: 0,
+    };
+  }
+
+  #isActive(state: TaskState): boolean {
+    return this.#tasks.get(state.assignment.taskId) === state && state.phase !== "ended";
+  }
+
+  #finishStartup(state: TaskState): Promise<void> {
+    if (!state.startup) {
+      if (this.#isActive(state)) {
+        state.phase = "waiting";
+        this.#request(state);
+      }
+      return Promise.resolve();
+    }
+    if (state.startupPromise) return state.startupPromise;
+    const startup = state.startup;
+    const operation = (async () => {
+      if (startup.kind === "predecessor") {
+        await this.#completeEndedCleanup(startup.state, "superseded");
+      } else {
+        await this.#runCleanup(state, {
+          assignment: cloneAssignment(state.assignment),
+          mode: "full",
+          reason: "recovery",
+          removed: [],
+          removeFilesSession: this.#opts.runnerKind === "task-machine",
+        });
+      }
+      state.startup = null;
+      if (!this.#isActive(state)) return;
+      state.phase = "waiting";
+      this.#request(state);
+    })();
+    state.startupPromise = operation;
+    return operation.finally(() => {
+      if (state.startupPromise === operation) state.startupPromise = null;
+    });
+  }
+
+  #stateForPending(opId: string): TaskState | null {
+    for (const state of this.#tasks.values()) {
+      if (state.pendingLease?.opId === opId) return state;
+    }
+    return null;
+  }
+
+  #opId(prefix: string, state: TaskState): string {
+    const random = this.#opts.randomId().replace(/[^A-Za-z0-9_-]/g, "").slice(0, 64);
+    const opId = `${prefix}-${++state.sequence}-${random || "op"}`;
+    if (!OP_ID.test(opId)) throw new CredentialLeaseError("could not create a safe operation id");
+    return opId;
+  }
+
+  #safeSend(frame: LeaseRequestV1Frame | CredentialRefreshFrame): boolean {
+    try {
+      return this.#opts.send(frame);
+    } catch {
+      return false;
+    }
+  }
+
+  #request(state: TaskState): void {
+    if (
+      !this.#isActive(state) ||
+      state.gateCloseFailed ||
+      state.phase === "recovering" ||
+      state.phase === "lost" ||
+      state.fullCleanup !== null ||
+      state.pendingLease
+    ) {
+      return;
+    }
+    if (state.retryTimer) {
+      this.#opts.clearTimer(state.retryTimer);
+      state.retryTimer = null;
+    }
+    if (state.renewalTimer) {
+      this.#opts.clearTimer(state.renewalTimer);
+      state.renewalTimer = null;
+    }
+    const opId = this.#opId("lease", state);
+    const timer = this.#opts.setTimer(() => {
+      if (state.pendingLease?.opId !== opId) return;
+      state.pendingLease = null;
+      this.#armRetry(state);
+    }, LEASE_REQUEST_TIMEOUT_MS);
+    timer.unref?.();
+    state.pendingLease = { opId, timer, answering: false };
+    const sent = this.#safeSend({
+      kind: "lease.request",
+      opId,
+      taskId: state.assignment.taskId,
+      runEpoch: state.assignment.runEpoch,
+    });
+    if (!sent) {
+      this.#cancelPendingLease(state);
+      this.#armRetry(state);
+    }
+  }
+
+  #armRetry(state: TaskState): void {
+    if (!this.#isActive(state) || state.retryTimer || state.pendingLease) return;
+    const timer = this.#opts.setTimer(() => {
+      if (state.retryTimer !== timer) return;
+      state.retryTimer = null;
+      this.#request(state);
+    }, LEASE_RETRY_MS);
+    timer.unref?.();
+    state.retryTimer = timer;
+  }
+
+  #cancelPendingLease(state: TaskState): void {
+    if (!state.pendingLease) return;
+    this.#opts.clearTimer(state.pendingLease.timer);
+    state.pendingLease = null;
+  }
+
+  #validateGrantBeforeRead(state: TaskState, frame: LeaseGrantV1Frame): void {
+    const { lease } = frame;
+    if (
+      state.phase === "recovering" ||
+      state.phase === "lost" ||
+      state.phase === "ended" ||
+      state.gateCloseFailed ||
+      state.fullCleanup !== null
+    ) {
+      throw new CredentialLeaseUnavailableError("task cleanup is in progress");
+    }
+    if (!assignmentMatches(state.assignment, lease)) {
+      throw new CredentialLeaseError("grant belongs to another task assignment");
+    }
+    if (digestManifest(lease) !== lease.manifestDigest) {
+      throw new CredentialLeaseError("grant manifest digest does not match");
+    }
+    if (lease.manifestRevision < state.minRevision) {
+      throw new CredentialLeaseError("grant is below the task's minimum revision");
+    }
+    if (state.bundle && lease.manifestRevision < state.bundle.lease.manifestRevision) {
+      throw new CredentialLeaseError("grant is older than the installed manifest");
+    }
+    if (
+      state.bundle &&
+      lease.manifestRevision === state.bundle.lease.manifestRevision &&
+      lease.manifestDigest !== state.bundle.lease.manifestDigest
+    ) {
+      throw new CredentialLeaseError(
+        "grant changed the manifest without advancing its revision",
+      );
+    }
+    if (taskLeaseV1ExpiresAt(lease) <= this.#opts.now()) {
+      throw new CredentialLeaseError("grant is expired");
+    }
+    const filesSessions = lease.sessions.filter((session) => session.purpose === "files");
+    if (this.#opts.runnerKind === "owned") {
+      if (filesSessions.length !== 0 || lease.files !== null) {
+        throw new CredentialLeaseError("owned runner received a Files session");
+      }
+    } else if (filesSessions.length !== 1 || lease.files === null) {
+      throw new CredentialLeaseError("task machine did not receive exactly one Files session");
+    }
+    const credentialIds = manifestDescriptors(lease).map((item) => item.credentialId);
+    if (new Set(credentialIds).size !== credentialIds.length) {
+      throw new CredentialLeaseError("credential ids are not unique across the manifest");
+    }
+    const parameters = manifestDescriptors(lease)
+      .map((item) => item.parameter)
+      .filter((item): item is string => item !== null);
+    if (new Set(parameters).size !== parameters.length) {
+      throw new CredentialLeaseError("credential parameters are not unique across the manifest");
+    }
+  }
+
+  async #materializeBundle(state: TaskState, lease: TaskLeaseV1): Promise<LeaseBundle> {
+    const readers = new Map<string, ManagedSessionReader>();
+    try {
+      for (const session of lease.sessions) {
+        if (session.purpose !== "credentials") continue;
+        readers.set(
+          session.id,
+          new ManagedSessionReader(
+            session.id,
+            this.#opts.createSessionReader({
+              region: lease.region,
+              session,
+              assignment: cloneAssignment(state.assignment),
+            }),
+          ),
+        );
+      }
+      const descriptors = manifestDescriptors(lease);
+      const records = new Map<string, CredentialRecord>();
+      const grouped = new Map<string, CredentialDescriptor[]>();
+      for (const descriptor of descriptors) {
+        if (descriptor.authKind === "none") {
+          records.set(descriptor.credentialId, {
+            descriptor,
+            availability: "not-required",
+            material: null,
+            observedVersion: null,
+          });
+          continue;
+        }
+        if (
+          !descriptor.parameter ||
+          !descriptor.version ||
+          !descriptor.sessionId ||
+          !descriptor.location
+        ) {
+          throw new CredentialLeaseError("manifest credential is incomplete");
+        }
+        const group = grouped.get(descriptor.sessionId) ?? [];
+        group.push(descriptor);
+        grouped.set(descriptor.sessionId, group);
+      }
+      for (const [sessionId, group] of grouped) {
+        const reader = readers.get(sessionId);
+        if (!reader) throw new CredentialLeaseError("manifest names a missing session");
+        for (let offset = 0; offset < group.length; offset += MAX_SSM_GET_PARAMETERS) {
+          const batch = group.slice(offset, offset + MAX_SSM_GET_PARAMETERS);
+          const selectors = batch.map((item) => `${item.parameter!}:${item.version!}`);
+          await this.#readMaterialBatch(reader, batch, selectors, records);
+        }
+      }
+      const projectSessions = new Map(
+        lease.manifest.projects.map((project) => [project.projectId, project.sessionId]),
+      );
+      const expiresAt = taskLeaseV1ExpiresAt(lease);
+      const view = freezeView(lease, expiresAt, records);
+      return { lease, expiresAt, readers, records, projectSessions, view };
+    } catch (error) {
+      await Promise.all([...readers.values()].map((reader) => reader.destroyWhenDrained()));
+      throw error;
+    }
+  }
+
+  #assertMaterialBatch(
+    descriptors: readonly CredentialDescriptor[],
+    selectors: readonly string[],
+    result: ExactSsmParameterBatch,
+    records: Map<string, CredentialRecord>,
+  ): void {
+    if (result.invalidParameters.length !== 0) {
+      throw new CredentialLeaseError("Parameter Store rejected a credential selector");
+    }
+    if (result.parameters.length !== descriptors.length) {
+      throw new CredentialLeaseError("Parameter Store omitted or added credential material");
+    }
+    const expected = new Map(descriptors.map((item) => [item.parameter!, item]));
+    const seen = new Set<string>();
+    for (const parameter of result.parameters) {
+      const descriptor = expected.get(parameter.name);
+      if (
+        !descriptor ||
+        seen.has(parameter.name) ||
+        parameter.type !== "SecureString" ||
+        parameter.version !== descriptor.version ||
+        typeof parameter.value !== "string"
+      ) {
+        throw new CredentialLeaseError("Parameter Store returned inexact credential material");
+      }
+      const selector = `${parameter.name}:${parameter.version}`;
+      if (!selectors.includes(selector)) {
+        throw new CredentialLeaseError("Parameter Store returned an unrequested credential version");
+      }
+      const material = parseLeasedValue(parameter.value, descriptor.location!);
+      if (!material || !materialMatchesDescriptor(material, descriptor)) {
+        throw new CredentialLeaseError("credential envelope does not match its manifest entry");
+      }
+      seen.add(parameter.name);
+      records.set(descriptor.credentialId, {
+        descriptor,
+        availability: "available",
+        material: freezeMaterial(material),
+        observedVersion: parameter.version,
+      });
+    }
+  }
+
+  async #readMaterialBatch(
+    reader: ManagedSessionReader,
+    descriptors: readonly CredentialDescriptor[],
+    selectors: readonly string[],
+    records: Map<string, CredentialRecord>,
+  ): Promise<void> {
+    try {
+      const result = await reader.read(selectors);
+      this.#assertMaterialBatch(descriptors, selectors, result, records);
+      return;
+    } catch (error) {
+      if (!this.#isAccessDenied(error)) throw error;
+    }
+
+    // A policy rollout can briefly leave one exact parameter unreadable. AWS
+    // rejects the complete batch in that case, so retry only exact singleton
+    // selectors to isolate it. No listing or broad fallback is ever used.
+    for (let index = 0; index < descriptors.length; index++) {
+      const descriptor = descriptors[index]!;
+      const selector = selectors[index]!;
+      try {
+        const result = await reader.read([selector]);
+        this.#assertMaterialBatch([descriptor], [selector], result, records);
+      } catch (error) {
+        if (!this.#isAccessDenied(error)) throw error;
+        records.set(descriptor.credentialId, {
+          descriptor,
+          availability: "access-denied",
+          material: null,
+          observedVersion: null,
+        });
+      }
+    }
+  }
+
+  #isAccessDenied(error: unknown): boolean {
+    if (!error || typeof error !== "object") return false;
+    const candidate = error as {
+      name?: unknown;
+      message?: unknown;
+      $metadata?: { httpStatusCode?: unknown };
+    };
+    return (
+      candidate.name === "AccessDenied" ||
+      candidate.name === "AccessDeniedException" ||
+      candidate.$metadata?.httpStatusCode === 403 ||
+      (typeof candidate.message === "string" && /\bAccessDenied\b/i.test(candidate.message))
+    );
+  }
+
+  #assertCandidateCurrent(
+    state: TaskState,
+    frame: LeaseGrantV1Frame,
+    baseGeneration: number,
+    candidate: LeaseBundle,
+  ): void {
+    if (
+      !this.#isActive(state) ||
+      state.gateCloseFailed ||
+      state.pendingLease?.opId !== frame.opId ||
+      state.bundleGeneration !== baseGeneration ||
+      candidate.lease.manifestRevision < state.minRevision ||
+      candidate.expiresAt <= this.#opts.now()
+    ) {
+      throw new CredentialLeaseUnavailableError("grant became stale while it was being read");
+    }
+  }
+
+  async #preserveObservedVersions(
+    state: TaskState,
+    frame: LeaseGrantV1Frame,
+    baseGeneration: number,
+    candidate: LeaseBundle,
+  ): Promise<void> {
+    const current = state.bundle;
+    if (!current) return;
+    let changed = false;
+    for (const oldRecord of current.records.values()) {
+      const nextRecord = candidate.records.get(oldRecord.descriptor.credentialId);
+      const oldKnownVersion = Math.max(
+        oldRecord.descriptor.version ?? 0,
+        oldRecord.observedVersion ?? 0,
+      );
+      const nextKnownVersion = Math.max(
+        nextRecord?.descriptor.version ?? 0,
+        nextRecord?.observedVersion ?? 0,
+      );
+      if (
+        !nextRecord ||
+        oldKnownVersion === 0 ||
+        oldKnownVersion <= nextKnownVersion ||
+        descriptorKey(oldRecord.descriptor) !== descriptorKey(nextRecord.descriptor) ||
+        !nextRecord.descriptor.parameter ||
+        !nextRecord.descriptor.sessionId
+      ) {
+        continue;
+      }
+      const reader = candidate.readers.get(nextRecord.descriptor.sessionId);
+      if (!reader) throw new CredentialLeaseError("candidate credential session is missing");
+      const descriptor = {
+        ...nextRecord.descriptor,
+        version: oldKnownVersion,
+      };
+      const selector = `${descriptor.parameter}:${descriptor.version}`;
+      await this.#readMaterialBatch(
+        reader,
+        [descriptor],
+        [selector],
+        candidate.records,
+      );
+      this.#assertCandidateCurrent(
+        state,
+        frame,
+        baseGeneration,
+        candidate,
+      );
+      changed = true;
+    }
+    if (changed) {
+      candidate.view = freezeView(candidate.lease, candidate.expiresAt, candidate.records);
+    }
+  }
+
+  #removedIdentities(old: LeaseBundle, next: LeaseBundle): CredentialCleanupIdentity[] {
+    const nextKeys = new Set(
+      [...next.records.values()].map((record) => descriptorKey(record.descriptor)),
+    );
+    return [...old.records.values()]
+      .filter((record) => !nextKeys.has(descriptorKey(record.descriptor)))
+      .map((record) => descriptorIdentity(record.descriptor));
+  }
+
+  #removedKnownIdentities(
+    state: TaskState,
+    next: LeaseBundle,
+  ): CredentialCleanupIdentity[] {
+    const nextKeys = new Set(
+      [...next.records.values()].map((record) => descriptorKey(record.descriptor)),
+    );
+    return [...state.identitiesByCredentialId.values()].filter((identity) => {
+      const key = credentialKey(identity);
+      return !nextKeys.has(key) && !state.cleaned.has(key);
+    });
+  }
+
+  /** Credentials `old` could read that `next` names the same way and cannot:
+   *  refused, so cleaned up like a removal before `next` is installed. */
+  #refusedIdentities(old: LeaseBundle, next: LeaseBundle): CredentialCleanupIdentity[] {
+    return [...old.records.values()]
+      .filter((record) => {
+        const replacement = next.records.get(record.descriptor.credentialId);
+        return (
+          record.availability === "available" &&
+          replacement !== undefined &&
+          replacement.availability === "access-denied" &&
+          descriptorKey(replacement.descriptor) === descriptorKey(record.descriptor)
+        );
+      })
+      .map((record) => descriptorIdentity(record.descriptor));
+  }
+
+  /**
+   * Without a bundle to compare (one below the floor was dropped after its
+   * selective cleanup, leaving the rest of its files), every known identity
+   * not yet cleaned that `next` names and cannot read is treated as refused:
+   * cleaning one that was never readable deletes nothing.
+   */
+  #refusedKnownIdentities(state: TaskState, next: LeaseBundle): CredentialCleanupIdentity[] {
+    return [...next.records.values()]
+      .filter((record) => {
+        if (record.availability !== "access-denied") return false;
+        const key = descriptorKey(record.descriptor);
+        const known = state.identitiesByCredentialId.get(record.descriptor.credentialId);
+        return known !== undefined && credentialKey(known) === key && !state.cleaned.has(key);
+      })
+      .map((record) => descriptorIdentity(record.descriptor));
+  }
+
+  #filesAccess(bundle: LeaseBundle): TaskLeaseFilesAccess | null {
+    if (!bundle.lease.files) return null;
+    const session = bundle.lease.sessions.find((item) => item.purpose === "files");
+    if (!session) throw new CredentialLeaseError("Files metadata has no Files session");
+    return Object.freeze({
+      assignment: Object.freeze({
+        taskId: bundle.lease.taskId,
+        runEpoch: bundle.lease.runEpoch,
+      }),
+      region: bundle.lease.region,
+      files: Object.freeze({ ...bundle.lease.files }),
+      credentials: Object.freeze({
+        accessKeyId: session.accessKeyId,
+        secretAccessKey: session.secretAccessKey,
+        sessionToken: session.sessionToken,
+        expiresAt: session.expiresAt,
+      }),
+    });
+  }
+
+  #bundleIsUsable(state: TaskState): boolean {
+    return Boolean(
+      !state.gateCloseFailed &&
+        state.gateOpen &&
+        state.bundle &&
+        state.bundle.expiresAt > this.#opts.now() &&
+        state.bundle.lease.manifestRevision >= state.minRevision &&
+        state.phase === "usable",
+    );
+  }
+
+  #requireUsableState(assignment: TaskAssignment): TaskState {
+    const state = this.#tasks.get(assignment.taskId);
+    if (!state || !assignmentMatches(state.assignment, assignment) || !this.#bundleIsUsable(state)) {
+      throw new CredentialLeaseUnavailableError();
+    }
+    return state;
+  }
+
+  #assertReadFence(state: TaskState, bundle: LeaseBundle, generation: number): void {
+    if (
+      !this.#isActive(state) ||
+      !state.gateOpen ||
+      state.bundle !== bundle ||
+      state.bundleGeneration !== generation ||
+      bundle.expiresAt <= this.#opts.now() ||
+      bundle.lease.manifestRevision < state.minRevision
+    ) {
+      throw new CredentialLeaseUnavailableError("credential read crossed an assignment fence");
+    }
+  }
+
+  /** A committed bundle may open only while this exact state still owns the
+   * assignment and no cleanup fence has made it unusable.  In particular,
+   * `handleGrant` can wait for the previous bundle's readers after committing
+   * its replacement; Stop, supersession, expiry or a revision floor may close
+   * the gate during that wait. */
+  #mayOpenGate(
+    state: TaskState,
+    bundle: LeaseBundle,
+    generation: number,
+  ): boolean {
+    return Boolean(
+      this.#isActive(state) &&
+        state.phase !== "recovering" &&
+        state.phase !== "lost" &&
+        state.gateHolds === 0 &&
+        state.fullCleanup === null &&
+        !state.gateCloseFailed &&
+        state.bundle === bundle &&
+        state.bundleGeneration === generation &&
+        bundle.lease.manifestRevision >= state.minRevision &&
+        bundle.expiresAt > this.#opts.now(),
+    );
+  }
+
+  /**
+   * A transition lets go of the gate. An open its hold kept closed is not
+   * lost: once no transition holds the gate, it opens on the view committed
+   * now, if it may. A transition that failed made the assignment lost before
+   * releasing, so nothing opens then.
+   */
+  #releaseHold(state: TaskState): void {
+    state.gateHolds--;
+    if (state.gateHolds > 0 || state.gateOpen || !state.bundle) return;
+    this.#openGate(state, state.bundle, state.bundleGeneration);
+  }
+
+  #openGate(state: TaskState, bundle: LeaseBundle, generation: number): void {
+    if (!this.#mayOpenGate(state, bundle, generation)) return;
+    try {
+      this.#opts.openTaskGate?.(cloneAssignment(state.assignment), bundle.view);
+    } catch (error) {
+      this.#closeGate(state, "cleanup-failed");
+      throw error;
+    }
+    // The callback is synchronous but may be re-entrant.  If it crossed a
+    // fence, undo the external open before returning; the transition that
+    // moved the fence owns any cleanup which follows.
+    if (!this.#mayOpenGate(state, bundle, generation)) {
+      if (!this.#closeGate(state, "cleanup-failed")) {
+        throw new CredentialLeaseUnavailableError(
+          "task gate reopened across a fence and could not be closed",
+        );
+      }
+      return;
+    }
+    state.gateOpen = true;
+    state.phase = "usable";
+    for (const waiter of state.waiters) {
+      if (waiter.signal && waiter.abort) {
+        waiter.signal.removeEventListener("abort", waiter.abort);
+      }
+      waiter.resolve(bundle.view);
+    }
+    state.waiters.clear();
+  }
+
+  #closeGate(state: TaskState, reason: LeaseGateCloseReason): boolean {
+    state.gateOpen = false;
+    try {
+      this.#opts.closeTaskGate(cloneAssignment(state.assignment), reason);
+      return true;
+    } catch (error) {
+      state.gateCloseFailed = true;
+      this.#report(error, state.assignment);
+      return false;
+    }
+  }
+
+  #armBundleTimers(state: TaskState): void {
+    if (!state.bundle) return;
+    if (state.renewalTimer) this.#opts.clearTimer(state.renewalTimer);
+    if (state.expiryTimer) this.#opts.clearTimer(state.expiryTimer);
+    const generation = state.bundleGeneration;
+    const renewDelay = Math.max(
+      1_000,
+      state.bundle.expiresAt - LEASE_RENEW_LEAD_MS - this.#opts.now(),
+    );
+    const renewal = this.#opts.setTimer(() => {
+      if (state.renewalTimer !== renewal || state.bundleGeneration !== generation) return;
+      state.renewalTimer = null;
+      this.#request(state);
+    }, renewDelay);
+    renewal.unref?.();
+    state.renewalTimer = renewal;
+
+    const expiryDelay = Math.max(0, state.bundle.expiresAt - this.#opts.now());
+    const expiry = this.#opts.setTimer(() => {
+      if (state.expiryTimer !== expiry || state.bundleGeneration !== generation) return;
+      state.expiryTimer = null;
+      this.#closeGate(state, "expired");
+      this.#background(this.#fullCleanupAndContinue(state, "expired"), state.assignment);
+    }, expiryDelay);
+    expiry.unref?.();
+    state.expiryTimer = expiry;
+  }
+
+  #beginNarrowing(state: TaskState): void {
+    // A full cleanup under way, or one that failed and is to be retried,
+    // takes everything a narrowing would: the run stays quarantined until it
+    // succeeds, never moved out of it by a narrowing.
+    if (state.phase === "lost" || state.fullCleanup !== null) return;
+    const belowFloor = Boolean(
+      state.bundle && state.bundle.lease.manifestRevision < state.minRevision,
+    );
+    const removed = [...state.removed.entries()]
+      .filter(([key]) => !state.cleaned.has(key))
+      .map(([, identity]) => identity);
+    if (!belowFloor && removed.length === 0) return;
+    state.phase = "narrowing";
+    const gateClosed = this.#closeGate(state, "minimum-revision");
+    if (state.bundle) this.#sealBundle(state.bundle);
+    if (!gateClosed) {
+      this.#background(
+        this.#fullCleanupAndContinue(state, "minimum-revision"),
+        state.assignment,
+      );
+      return;
+    }
+    if (state.floorDeadlineAt === null) {
+      state.floorDeadlineAt = this.#opts.now() + LEASE_MIN_REVISION_GRACE_MS;
+      const deadline = state.floorDeadlineAt;
+      const timer = this.#opts.setTimer(() => {
+        if (state.floorTimer !== timer || state.floorDeadlineAt !== deadline) return;
+        state.floorTimer = null;
+        if (
+          this.#isActive(state) &&
+          (!state.bundle || state.bundle.lease.manifestRevision < state.minRevision)
+        ) {
+          this.#background(
+            this.#fullCleanupAndContinue(state, "minimum-revision"),
+            state.assignment,
+          );
+        }
+      }, LEASE_MIN_REVISION_GRACE_MS);
+      timer.unref?.();
+      state.floorTimer = timer;
+    }
+    if (removed.length > 0) {
+      const bundle = state.bundle;
+      const cleanup = this.#runCleanup(state, {
+          assignment: cloneAssignment(state.assignment),
+          mode: "selective",
+          reason: "minimum-revision",
+          removed,
+          removeFilesSession: false,
+        })
+        .then(async () => {
+          for (const identity of removed) state.cleaned.add(credentialKey(identity));
+          // A below-floor bundle is no longer authority.  Once its external
+          // material is gone, drop all of its in-memory material and STS
+          // clients too; retaining unrelated values buys nothing while the
+          // task gate is closed.
+          if (
+            bundle &&
+            this.#isActive(state) &&
+            state.bundle === bundle &&
+            bundle.lease.manifestRevision < state.minRevision
+          ) {
+            state.bundle = null;
+            state.bundleGeneration++;
+            await this.#destroyBundle(bundle);
+          }
+        })
+        .catch((error: unknown) => {
+          this.#report(error, state.assignment);
+          this.#armSelectiveCleanupRetry(state);
+        });
+      // `cleanup` handles and schedules its own failure; keep it detached.
+      void cleanup;
+    }
+  }
+
+  #armSelectiveCleanupRetry(state: TaskState): void {
+    if (!this.#isActive(state) || state.cleanupRetryTimer) return;
+    // A full cleanup takes what this would.
+    if (state.phase === "lost" || state.fullCleanup !== null) return;
+    const timer = this.#opts.setTimer(() => {
+      if (state.cleanupRetryTimer !== timer) return;
+      state.cleanupRetryTimer = null;
+      if (
+        (state.bundle && state.bundle.lease.manifestRevision < state.minRevision) ||
+        this.#hasUncleanedRemovals(state)
+      ) {
+        this.#beginNarrowing(state);
+      }
+    }, LEASE_RETRY_MS);
+    timer.unref?.();
+    state.cleanupRetryTimer = timer;
+  }
+
+  #hasUncleanedRemovals(state: TaskState): boolean {
+    return [...state.removed.keys()].some((key) => !state.cleaned.has(key));
+  }
+
+  #clearFloor(state: TaskState): void {
+    if (state.floorTimer) this.#opts.clearTimer(state.floorTimer);
+    state.floorTimer = null;
+    state.floorDeadlineAt = null;
+    state.removed.clear();
+    state.cleaned.clear();
+  }
+
+  async #applyCredentialVersion(
+    state: TaskState,
+    frame: CredentialChangedFrame,
+  ): Promise<void> {
+    if (!this.#bundleIsUsable(state)) return;
+    const bundle = state.bundle!;
+    const generation = state.bundleGeneration;
+    const current = bundle.records.get(frame.credentialId);
+    if (
+      !current ||
+      current.descriptor.revision !== frame.revision ||
+      current.descriptor.authKind === "none" ||
+      !current.descriptor.parameter ||
+      !current.descriptor.sessionId ||
+      !current.descriptor.location ||
+      frame.version <=
+        Math.max(current.descriptor.version ?? 0, current.observedVersion ?? 0)
+    ) {
+      return;
+    }
+    const reader = bundle.readers.get(current.descriptor.sessionId);
+    if (!reader) throw new CredentialLeaseError("credential session is missing");
+    const selector = `${current.descriptor.parameter}:${frame.version}`;
+    const replacement = new Map(bundle.records);
+    const descriptor = { ...current.descriptor, version: frame.version };
+    await this.#readMaterialBatch(
+      reader,
+      [descriptor],
+      [selector],
+      replacement,
+    );
+    this.#assertReadFence(state, bundle, generation);
+    const next: LeaseBundle = {
+      ...bundle,
+      records: replacement,
+      view: freezeView(bundle.lease, bundle.expiresAt, replacement),
+    };
+    // A credential the task could read and now cannot was refused (§6): with
+    // the gate closed, its files and whatever uses them go before the view
+    // that holds it unreadable is installed, as for a removal. The gate is
+    // held closed until this transition opens it again on that view.
+    const refused =
+      current.availability === "available" &&
+      replacement.get(frame.credentialId)?.availability === "access-denied";
+    let holding = false;
+    const release = (): void => {
+      if (!holding) return;
+      holding = false;
+      this.#releaseHold(state);
+    };
+    if (refused) {
+      if (!this.#closeGate(state, "manifest-narrowed")) {
+        // A gate that cannot close is quarantined: the full cleanup owns it.
+        this.#background(this.#fullCleanupAndContinue(state, "manifest-narrowed"), state.assignment);
+        return;
+      }
+      state.gateHolds++;
+      holding = true;
+    }
+    let installAttempted = false;
+    try {
+      if (refused) {
+        await this.#runCleanup(state, {
+          assignment: cloneAssignment(state.assignment),
+          mode: "selective",
+          reason: "lease-replaced",
+          removed: [descriptorIdentity(current.descriptor)],
+          removeFilesSession: false,
+        });
+        this.#assertRefusalFence(state, bundle, generation);
+      }
+      const installRequest: CredentialInstallRequest = {
+        assignment: cloneAssignment(state.assignment),
+        owner: { orgId: bundle.lease.orgId, userId: bundle.lease.userId },
+        previous: bundle.view,
+        next: next.view,
+        files: this.#filesAccess(next),
+        reason: "credential-change",
+        projectSetChanged: false,
+        // The same grant: its values read while it is usable.
+        projectValues: this.#grantProjectValueReader(state, bundle, () => false),
+        // The fence this transition checks once the install is over, now:
+        // a floor, an expiry or a stop meanwhile ends it.
+        isCurrent: () => {
+          try {
+            if (refused) this.#assertRefusalFence(state, bundle, generation);
+            else this.#assertReadFence(state, bundle, generation);
+            return true;
+          } catch {
+            return false;
+          }
+        },
+      };
+      installAttempted = this.#opts.installExternal !== undefined;
+      await this.#runInstall(state, installRequest);
+      if (refused) this.#assertRefusalFence(state, bundle, generation);
+      else this.#assertReadFence(state, bundle, generation);
+      state.bundle = next;
+      state.bundleGeneration++;
+      this.#armBundleTimers(state);
+      // A refusal opens through its release, inside this boundary: an open
+      // that fails, its compensating close included, escalates below.
+      release();
+    } catch (error) {
+      // As for a grant, what a failed or aborted step may have done is never
+      // assumed undone: an attempted install, a gate that could not close,
+      // or a refusal that did not reach its own open goes to the full
+      // cleanup. That makes the assignment lost at once, before any hold
+      // goes, so a view committed before cannot reopen the gate either.
+      if ((holding || installAttempted || state.gateCloseFailed) && this.#isActive(state)) {
+        const escalation = this.#fullCleanupAndContinue(state, "manifest-narrowed");
+        release();
+        try {
+          await escalation;
+        } catch {
+          // Full cleanup remains closed and owns its retry.
+        }
+      }
+      throw error;
+    } finally {
+      release();
+    }
+  }
+
+  /** After a refused credential's cleanup, with the gate this transition
+   *  closed: the same bundle and generation, nothing else having taken over. */
+  #assertRefusalFence(state: TaskState, bundle: LeaseBundle, generation: number): void {
+    if (
+      !this.#isActive(state) ||
+      state.phase !== "usable" ||
+      state.gateCloseFailed ||
+      state.fullCleanup !== null ||
+      state.bundle !== bundle ||
+      state.bundleGeneration !== generation ||
+      bundle.expiresAt <= this.#opts.now() ||
+      bundle.lease.manifestRevision < state.minRevision
+    ) {
+      throw new CredentialLeaseUnavailableError("a refused credential's cleanup crossed an assignment fence");
+    }
+  }
+
+  #settleRefresh(
+    state: TaskState,
+    pending: RefreshPending,
+    result: CredentialRefreshResultFrame,
+  ): void {
+    if (state.refreshByOp.get(pending.opId) !== pending) return;
+    this.#opts.clearTimer(pending.timer);
+    state.refreshByOp.delete(pending.opId);
+    state.refreshByCredential.delete(pending.key);
+    pending.resolve(result);
+  }
+
+  #endSynchronously(state: TaskState, reason: LeaseGateCloseReason): void {
+    state.phase = "ended";
+    this.#closeGate(state, reason);
+    this.#cancelTimers(state);
+    if (state.bundle) this.#sealBundle(state.bundle);
+    for (const pending of [...state.refreshByOp.values()]) {
+      this.#settleRefresh(state, pending, unavailableRefresh(pending.opId));
+    }
+    for (const waiter of state.waiters) {
+      if (waiter.signal && waiter.abort) {
+        waiter.signal.removeEventListener("abort", waiter.abort);
+      }
+      waiter.reject(new CredentialLeaseUnavailableError("task assignment ended"));
+    }
+    state.waiters.clear();
+  }
+
+  async #completeEndedCleanup(
+    state: TaskState,
+    reason: LeaseGateCloseReason,
+  ): Promise<void> {
+    if (state.startup) await this.#finishStartup(state);
+    if (state.gateCloseFailed && this.#closeGate(state, reason)) {
+      state.gateCloseFailed = false;
+    }
+    const cleanupRequest: CredentialCleanupRequest = {
+      assignment: cloneAssignment(state.assignment),
+      mode: "full",
+      reason,
+      removed: [],
+      removeFilesSession: this.#opts.runnerKind === "task-machine",
+    };
+    await this.#runCleanup(state, cleanupRequest);
+    const bundle = state.bundle;
+    state.bundle = null;
+    state.bundleGeneration++;
+    if (bundle) await this.#destroyBundle(bundle);
+    state.identitiesByCredentialId.clear();
+    // A synchronous open callback can re-enter Stop/supersession and then
+    // fail its compensating close while this cleanup is awaiting consumers.
+    // Do not let the earlier successful close mask that later failure.  A
+    // successful retry must itself be followed by full cleanup: consumers
+    // could have admitted work while the external gate remained open.
+    while (state.gateCloseFailed) {
+      if (!this.#closeGate(state, reason)) {
+        throw new CredentialLeaseUnavailableError(
+          "task gate closure failed; assignment remains quarantined",
+        );
+      }
+      state.gateCloseFailed = false;
+      await this.#runCleanup(state, cleanupRequest);
+    }
+  }
+
+  async #fullCleanupAndContinue(
+    state: TaskState,
+    reason: Extract<
+      LeaseGateCloseReason,
+      | "denied"
+      | "expired"
+      | "minimum-revision"
+      | "manifest-narrowed"
+      | "cleanup-failed"
+      | "fence-failed"
+    >,
+  ): Promise<void> {
+    if (state.fullCleanup) return state.fullCleanup;
+    // Set the phase before invoking the synchronous gate callback below, so
+    // even a re-entrant reconnect cannot create a request during cleanup.
+    state.phase = "lost";
+    // It takes everything a pending cleanup retry would; should it fail, it
+    // arms its own.
+    this.#cancelCleanupRetry(state);
+    const operation = (async () => {
+      if (this.#closeGate(state, reason)) state.gateCloseFailed = false;
+      if (state.bundle) this.#sealBundle(state.bundle);
+      const cleanupRequest: CredentialCleanupRequest = {
+        assignment: cloneAssignment(state.assignment),
+        mode: "full",
+        reason,
+        removed: [],
+        removeFilesSession: this.#opts.runnerKind === "task-machine",
+      };
+      await this.#runCleanup(state, cleanupRequest);
+      if (!this.#isActive(state)) return;
+      const bundle = state.bundle;
+      state.bundle = null;
+      state.bundleGeneration++;
+      if (bundle) await this.#destroyBundle(bundle);
+      state.identitiesByCredentialId.clear();
+      while (state.gateCloseFailed) {
+        if (!this.#closeGate(state, reason)) {
+          throw new CredentialLeaseUnavailableError(
+            "task gate closure failed; assignment remains quarantined",
+          );
+        }
+        state.gateCloseFailed = false;
+        await this.#runCleanup(state, cleanupRequest);
+        if (!this.#isActive(state)) return;
+      }
+      if (!this.#isActive(state)) return;
+      state.phase = "waiting";
+      this.#clearFloor(state);
+    })();
+    state.fullCleanup = operation;
+    let completed = false;
+    try {
+      await operation;
+      completed = true;
+    } catch (error) {
+      this.#report(error, state.assignment);
+      if (this.#isActive(state)) {
+        state.phase = "lost";
+        this.#closeGate(state, "cleanup-failed");
+        this.#armCleanupRetry(state, reason);
+      }
+      throw error;
+    } finally {
+      if (state.fullCleanup === operation) state.fullCleanup = null;
+      if (completed) {
+        // 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);
+      }
+    }
+  }
+
+  #armCleanupRetry(
+    state: TaskState,
+    reason: Extract<
+      LeaseGateCloseReason,
+      | "denied"
+      | "expired"
+      | "minimum-revision"
+      | "manifest-narrowed"
+      | "cleanup-failed"
+      | "fence-failed"
+    >,
+  ): void {
+    if (!this.#isActive(state) || state.cleanupRetryTimer) return;
+    const timer = this.#opts.setTimer(() => {
+      if (state.cleanupRetryTimer !== timer) return;
+      state.cleanupRetryTimer = null;
+      this.#background(this.#fullCleanupAndContinue(state, reason), state.assignment);
+    }, LEASE_RETRY_MS);
+    timer.unref?.();
+    state.cleanupRetryTimer = timer;
+  }
+
+  #cancelCleanupRetry(state: TaskState): void {
+    if (!state.cleanupRetryTimer) return;
+    this.#opts.clearTimer(state.cleanupRetryTimer);
+    state.cleanupRetryTimer = null;
+  }
+
+  #runCleanup(state: TaskState, request: CredentialCleanupRequest): Promise<void> {
+    const operation = state.cleanupTail
+      .catch(() => undefined)
+      .then(() => this.#opts.cleanupExternal(request));
+    state.cleanupTail = operation;
+    return operation;
+  }
+
+  #runInstall(state: TaskState, request: CredentialInstallRequest): Promise<void> {
+    if (state.gateCloseFailed) {
+      return Promise.reject(
+        new CredentialLeaseUnavailableError("task gate closure is quarantined"),
+      );
+    }
+    if (!this.#opts.installExternal) return state.cleanupTail;
+    const operation = state.cleanupTail.then(() => this.#opts.installExternal!(request));
+    state.cleanupTail = operation;
+    return operation;
+  }
+
+  #cancelTimers(state: TaskState): void {
+    this.#cancelPendingLease(state);
+    for (const key of [
+      "renewalTimer",
+      "retryTimer",
+      "expiryTimer",
+      "floorTimer",
+      "cleanupRetryTimer",
+    ] as const) {
+      const timer = state[key];
+      if (timer) this.#opts.clearTimer(timer);
+      state[key] = null;
+    }
+  }
+
+  #sealBundle(bundle: LeaseBundle): void {
+    for (const reader of bundle.readers.values()) reader.seal();
+  }
+
+  async #destroyBundle(bundle: LeaseBundle): Promise<void> {
+    this.#sealBundle(bundle);
+    await Promise.all([...bundle.readers.values()].map((reader) => reader.destroyWhenDrained()));
+  }
+
+  #background(promise: Promise<unknown>, assignment: TaskAssignment): void {
+    void promise.catch((error: unknown) => this.#report(error, assignment));
+  }
+
+  #report(error: unknown, assignment: TaskAssignment): void {
+    const safe =
+      error instanceof CredentialLeaseError
+        ? new Error(error.message)
+        : new Error("credential lease operation failed");
+    this.#opts.onError?.(safe, cloneAssignment(assignment));
+  }
+}