@runuai/host 0.9.150 → 0.9.151

package/lib/cloud-credential-cleanup-adapter.ts

@@ -0,0 +1,123 @@
+/**
+ * Fail-closed boundary between the in-memory lease registry and the durable
+ * task credential cleanup procedure.
+ *
+ * The registry describes why its gate closed and whether the cleanup is
+ * selective or whole-task. The durable coordinator uses a smaller audit
+ * vocabulary and represents selectivity solely by the presence of
+ * `credentialIds`. Keep that lossy conversion here so a new registry reason
+ * cannot accidentally become a whole-task cleanup (or vice versa).
+ */
+import type {
+  CredentialCleanupReason as LeaseCredentialCleanupReason,
+  CredentialCleanupRequest as LeaseCredentialCleanupRequest,
+} from "./cloud-credential-leases";
+import type {
+  TaskCredentialCleanupCoordinator,
+  TaskCredentialCleanupReason,
+  TaskCredentialCleanupRequest,
+} from "./task-credential-cleanup";
+
+export type CredentialCleanupRunnerKind = "owned" | "task-machine";
+
+type LeaseCleanupMode = LeaseCredentialCleanupRequest["mode"];
+type CleanupReasonByMode = Readonly<
+  Record<LeaseCleanupMode, TaskCredentialCleanupReason | null>
+>;
+
+/**
+ * `null` marks a reason/mode pair the registry must never emit. The `satisfies`
+ * clause makes additions to either the reason union or the mode union a
+ * compile-time decision at this boundary.
+ */
+const CLEANUP_REASON_BY_MODE = {
+  starting: { selective: null, full: null },
+  recovery: { selective: null, full: "restart" },
+  superseded: { selective: null, full: "assignment" },
+  "minimum-revision": { selective: "removed", full: "removed" },
+  "manifest-narrowed": { selective: null, full: "removed" },
+  denied: { selective: null, full: "denied" },
+  expired: { selective: null, full: "expired" },
+  stopped: { selective: null, full: "stop" },
+  parked: { selective: null, full: "park" },
+  teardown: { selective: null, full: "teardown" },
+  // The registry emits this fail-closed fallback when its synchronous gate
+  // callback throws during assignment start/recovery.  The durable vocabulary
+  // has no internal-callback-failure reason; `restart` is the conservative
+  // whole-task recovery category and, critically, lets the coordinator write
+  // its pending witness before retrying the quarantine.
+  "cleanup-failed": { selective: null, full: "restart" },
+  // A launch slot that could not be retired in its runtime (ADR-154 §6):
+  // the whole run's cleanup, in the same conservative category.
+  "fence-failed": { selective: null, full: "restart" },
+  // Shutdown ends assignments without a cleanup: the next process's
+  // recovery sweep runs it.
+  shutdown: { selective: null, full: null },
+  "lease-replaced": { selective: "removed", full: null },
+} as const satisfies Readonly<
+  Record<LeaseCredentialCleanupReason, CleanupReasonByMode>
+>;
+
+function mappedReason(
+  reason: LeaseCredentialCleanupReason,
+  mode: LeaseCleanupMode,
+): TaskCredentialCleanupReason {
+  const mapped = CLEANUP_REASON_BY_MODE[reason][mode];
+  if (mapped === null) {
+    throw new Error(`invalid ${mode} lease credential cleanup reason: ${reason}`);
+  }
+  return mapped;
+}
+
+/** Convert one registry callback into the coordinator's durable request. */
+export function adaptLeaseCredentialCleanupRequest(
+  request: Readonly<LeaseCredentialCleanupRequest>,
+  runnerKind: CredentialCleanupRunnerKind,
+): TaskCredentialCleanupRequest {
+  const reason = mappedReason(request.reason, request.mode);
+
+  if (request.mode === "selective") {
+    if (request.removeFilesSession) {
+      throw new Error("selective credential cleanup cannot remove the files session");
+    }
+    if (request.removed.length === 0) {
+      throw new Error("selective credential cleanup requires a removed credential");
+    }
+    // Several revisions of one stable credential can retire before a floor
+    // grant lands. Inventory is keyed by the stable id, so collapse those
+    // qualified identities rather than widening or rejecting the cleanup.
+    const credentialIds = [
+      ...new Set(request.removed.map((identity) => identity.credentialId)),
+    ];
+    return {
+      taskId: request.assignment.taskId,
+      runEpoch: request.assignment.runEpoch,
+      reason,
+      credentialIds,
+    };
+  }
+
+  if (request.removed.length !== 0) {
+    throw new Error("full credential cleanup cannot carry selective identities");
+  }
+  const expectedFilesSession = runnerKind === "task-machine";
+  if (request.removeFilesSession !== expectedFilesSession) {
+    throw new Error(
+      `${runnerKind} full credential cleanup has the wrong files-session scope`,
+    );
+  }
+  return {
+    taskId: request.assignment.taskId,
+    runEpoch: request.assignment.runEpoch,
+    reason,
+  };
+}
+
+/** Callback with the exact shape consumed by TaskCredentialLeaseRegistry. */
+export function createLeaseCredentialCleanupAdapter(
+  coordinator: Pick<TaskCredentialCleanupCoordinator, "cleanup">,
+  runnerKind: CredentialCleanupRunnerKind,
+): (request: LeaseCredentialCleanupRequest) => Promise<void> {
+  return (request) =>
+    coordinator.cleanup(adaptLeaseCredentialCleanupRequest(request, runnerKind));
+}

package/lib/cloud-credential-host.ts

@@ -0,0 +1,512 @@
+/**
+ * ADR-154 on this runner: whether its tasks run on cloud credentials, and
+ * the one composer that serves them.
+ *
+ * The mode comes from the runner's durable activation authority (three
+ * states, ADR-154 §13; lib/credentials-activation-authority.ts), and only
+ * moves forward:
+ * - `legacy`: the composer stays unused and every task runs as before;
+ * - `pending`: task starts are refused, neither the runner's own credentials
+ *   nor cloud ones may run;
+ * - `active`: every task runs on cloud credentials through the composer, and
+ *   no local fallback exists.
+ * Until main.ts installs that authority, the mode is `legacy`.
+ *
+ * Leaving `legacy` is a counted transition. Each start on the runner's own
+ * credentials holds a permit from its dispatch to its outcome, and checks it
+ * again inside each lifecycle slot before anything happens there; its
+ * permit's signal ends any wait for a legacy readiness the transition stops.
+ * Work on those credentials outside a start (a start's background GitHub
+ * sign-in, a scheduled re-injection) runs only through
+ * `whileOnOwnCredentials`, and workers register a stop. `leaveLegacy()`
+ * closes the permits, aborts their signals and stops the workers at once,
+ * then resolves when every start, every such work and every worker's work
+ * already under way has ended.
+ */
+
+import type { CloudCredentialRuntime } from "./cloud-credential-runtime";
+import { readTaskRunEpochState, runningTaskRuns } from "./runtime-state";
+
+export type CredentialsMode = "legacy" | "pending" | "active";
+
+let modeSource: () => CredentialsMode = () => "legacy";
+let runtime: CloudCredentialRuntime | null = null;
+
+/** The activation authority answers from here on. */
+export function setCredentialsModeSource(source: () => CredentialsMode): void {
+  modeSource = source;
+}
+
+export function credentialsMode(): CredentialsMode {
+  return modeSource();
+}
+
+export function setCloudCredentialRuntime(next: CloudCredentialRuntime | null): void {
+  runtime = next;
+}
+
+/** The composer, once constructed; null before (and in tests that run no
+ *  task on cloud credentials). */
+export function cloudCredentialRuntime(): CloudCredentialRuntime | null {
+  return runtime;
+}
+
+/** The composer while the runner's tasks run on cloud credentials; null
+ *  otherwise. Read where it is used, inside the task's lifecycle slot. */
+export function activeCloudCredentials(): CloudCredentialRuntime | null {
+  return credentialsMode() === "active" ? runtime : null;
+}
+
+// -- leaving legacy ------------------------------------------------------------
+
+/** One start on the runner's own credentials, from its dispatch to its
+ *  outcome. */
+export interface LegacyStartPermit {
+  /** Still on the runner's own credentials, with no transition begun. Once
+   *  false, never true again. */
+  valid(): boolean;
+  /** Aborted when the runner begins leaving its own credentials: a wait for
+   *  something the transition stops (the v0 lease's readiness) ends then. */
+  readonly signal: AbortSignal;
+  /** The start ended. Idempotent. */
+  release(): void;
+}
+
+/** Set first, before anything a worker's stop could run. */
+let left = false;
+/** The activation authority is retiring the runner's task runtimes: no new
+ *  start on its own credentials until it resumes them or leaves them. */
+let startsPaused = false;
+/** A runtime activation has asked the one-shot boot barrier for its
+ *  recovery (whatever came of it), or leaving the runner's own credentials
+ *  has begun: every pass from then on recovers afresh, its sweep pass and
+ *  that pass's own follow-ups alike. */
+let recoverAfresh = false;
+let leaving: Promise<void> | null = null;
+let legacyStarts = 0;
+let legacyDrained: Array<() => void> = [];
+const legacyWorkers = new Set<() => Promise<void> | void>();
+const legacyPermitSignals = new Set<AbortController>();
+const legacyWork = new Set<Promise<unknown>>();
+
+function stillLegacy(): boolean {
+  return !left && credentialsMode() === "legacy";
+}
+
+/** The runner is on its own credentials, and has not begun leaving them. */
+export function onOwnCredentials(): boolean {
+  return stillLegacy();
+}
+
+/** A permit for one start on the runner's own credentials; null once the
+ *  runner is leaving them (or has left), and while starts are paused. */
+export function admitLegacyStart(): LegacyStartPermit | null {
+  if (!stillLegacy() || startsPaused) return null;
+  legacyStarts += 1;
+  const controller = new AbortController();
+  legacyPermitSignals.add(controller);
+  let valid = true;
+  let released = false;
+  return {
+    valid: () => (valid &&= stillLegacy()),
+    signal: controller.signal,
+    release: () => {
+      if (released) return;
+      released = true;
+      legacyPermitSignals.delete(controller);
+      legacyStarts -= 1;
+      if (legacyStarts === 0) for (const drained of legacyDrained.splice(0)) drained();
+    },
+  };
+}
+
+/**
+ * ADR-154 §13, preparing: no new start on the runner's own credentials (each
+ * is answered as switching, which the cloud retries), while everything else
+ * on them goes on. `drained` resolves once the starts admitted before have
+ * ended, so every task runtime they create exists by then. `resume` admits
+ * starts again, for a preparation that failed; leaving the runner's own
+ * credentials needs no resume. Idempotent.
+ */
+export function pauseLegacyStarts(): { drained: Promise<void>; resume(): void } {
+  startsPaused = true;
+  const drained =
+    legacyStarts === 0 ? Promise.resolve() : new Promise<void>((resolve) => legacyDrained.push(resolve));
+  let resumed = false;
+  return {
+    drained,
+    resume: () => {
+      if (resumed) return;
+      resumed = true;
+      startsPaused = false;
+    },
+  };
+}
+
+/**
+ * Work on the runner's own credentials outside any start (a start's
+ * background GitHub sign-in, a scheduled re-injection, the write that ends
+ * either): `run` only while the runner is on them, and leaving them waits
+ * for it to end. Null, and `run` never called, once the runner is leaving
+ * them: the caller writes nothing.
+ */
+export function whileOnOwnCredentials<T>(run: () => Promise<T>): Promise<T> | null {
+  if (!stillLegacy()) return null;
+  const work = run();
+  legacyWork.add(work);
+  const forget = (): void => void legacyWork.delete(work);
+  work.then(forget, forget);
+  return work;
+}
+
+/**
+ * A hold on the runner's own credentials for work whose end is no single
+ * promise (an agent's creation through its binding, a pass that decides on
+ * them and then starts a process): leaving them waits until it is
+ * released. Null, and nothing held, once the runner is leaving them: the
+ * caller uses none. The release is idempotent.
+ */
+export function holdOwnCredentials(): (() => void) | null {
+  let release!: () => void;
+  const held = whileOnOwnCredentials(() => new Promise<void>((resolve) => (release = resolve)));
+  return held === null ? null : release;
+}
+
+/** A process on the runner's own credentials refused at its provider's
+ *  last moment: the runner has begun leaving them. */
+export class LeftOwnCredentialsError extends Error {
+  constructor() {
+    super("the runner is switching its tasks to cloud credentials");
+    this.name = "LeftOwnCredentialsError";
+  }
+}
+
+const LAUNCH_METHODS: ReadonlySet<PropertyKey> = new Set(["exec", "spawn", "spawnSession", "launchDetachedSession"]);
+
+/**
+ * `environment` (a task environment), for an agent on the runner's own
+ * credentials: every process it starts there, then or at any later turn,
+ * is admitted at the provider's last moment only while the runner is on
+ * them, so none starts once leaving them has begun, however long the
+ * provider took to get there (a machine looks up its address first).
+ */
+export function onOwnCredentialsEnvironment<T extends object>(environment: T): T {
+  return new Proxy(environment, {
+    get(target, property) {
+      const value: unknown = Reflect.get(target, property, target);
+      if (typeof value !== "function") return value;
+      const method = value as (...args: unknown[]) => unknown;
+      if (!LAUNCH_METHODS.has(property)) return method.bind(target);
+      return (request: { admit?: () => void }, ...rest: unknown[]) =>
+        method.call(
+          target,
+          {
+            ...request,
+            admit: () => {
+              if (!stillLegacy()) throw new LeftOwnCredentialsError();
+              request.admit?.();
+            },
+          },
+          ...rest,
+        );
+    },
+  });
+}
+
+/** Work on the runner's own credentials that must end before the runner
+ *  leaves them: `stop` stops it at once when called, and resolves once what
+ *  it had under way has ended. Returns the registration's removal. */
+export function onLeavingLegacy(stop: () => Promise<void> | void): () => void {
+  legacyWorkers.add(stop);
+  return () => void legacyWorkers.delete(stop);
+}
+
+/**
+ * The activation authority, as the runner leaves its own credentials (it
+ * enters `pending`): no start on them is admitted from here on, every
+ * registered worker stops now, synchronously, and this resolves once the
+ * starts admitted before and the workers' work under way have all ended.
+ * Rejects (after all of that) when a worker's stop failed: the runner stays
+ * `pending`. Idempotent: every call shares the first one's outcome.
+ */
+export function leaveLegacy(): Promise<void> {
+  if (leaving === null) {
+    left = true;
+    recoverAfresh = true;
+    for (const controller of legacyPermitSignals) {
+      controller.abort(new Error("the runner is switching its tasks to cloud credentials"));
+    }
+    leaving = drainLegacy();
+  }
+  return leaving;
+}
+
+async function drainLegacy(): Promise<void> {
+  const stopping: Array<Promise<void> | void> = [];
+  for (const stop of legacyWorkers) {
+    try {
+      stopping.push(stop());
+    } catch (error) {
+      stopping.push(Promise.reject(error));
+    }
+  }
+  const starts =
+    legacyStarts === 0 ? Promise.resolve() : new Promise<void>((resolve) => legacyDrained.push(resolve));
+  const results = await Promise.allSettled([...stopping, starts]);
+  // Work launched before leaving began ends too; none starts after.
+  while (legacyWork.size > 0) await Promise.allSettled([...legacyWork]);
+  const failures = results.flatMap((result) => (result.status === "rejected" ? [result.reason as unknown] : []));
+  if (failures.length > 0) {
+    throw new AggregateError(failures, "work on the runner's own credentials did not stop");
+  }
+}
+
+/** Tests: the runner back on its own credentials, nothing registered. */
+export function resetLegacyTransitionForTests(): void {
+  left = false;
+  startsPaused = false;
+  recoverAfresh = false;
+  leaving = null;
+  legacyStarts = 0;
+  legacyDrained = [];
+  legacyWorkers.clear();
+  legacyPermitSignals.clear();
+  legacyWork.clear();
+}
+
+// -- boot recovery -----------------------------------------------------------
+
+let recovering: Promise<void> | null = null;
+let markRecovered!: () => void;
+let recoveredSignal = new Promise<void>((resolve) => (markRecovered = resolve));
+let recovered = false;
+
+/**
+ * ADR-154 boot recovery (§5, §6): the composer's sweep of every task with
+ * cleanup left from the last process, before any surviving agent is
+ * reattached or any grant asked for. Once per process: after it succeeds,
+ * a call does nothing, so a later runtime re-activation never sweeps the
+ * credentials of tasks running now; concurrent calls share one sweep.
+ * Rejects, every task attempted, when any could not be cleaned up: the
+ * runner stays `pending`, and a later call tries again.
+ */
+export function recoverCloudCredentials(): Promise<void> {
+  if (recovered) return Promise.resolve();
+  if (recovering !== null) return recovering;
+  const composer = runtime;
+  if (composer === null) return Promise.reject(new Error("the runner has no cloud credentials composer"));
+  const sweep = composer
+    .recover((taskId) => readTaskRunEpochState(taskId)?.highestRunEpoch ?? 0)
+    .then(() => {
+      recovered = true;
+      markRecovered();
+    })
+    .finally(() => {
+      if (recovering === sweep) recovering = null;
+    });
+  recovering = sweep;
+  return sweep;
+}
+
+/**
+ * ADR-154: a runtime activation's currency, on the credentials it began on.
+ * One that began on the runner's own credentials stops being current the
+ * moment leaving them begins, through its last step, publication included:
+ * what its recovery reattached did so on their terms, and a new pass, which
+ * sweeps first, must take over (`leftLegacy()` says it was cut short so).
+ * One that began off them is current while its runtime generation is.
+ */
+export function credentialsActivationFence(isRuntimeCurrent: () => boolean): {
+  isCurrent(): boolean;
+  leftLegacy(): boolean;
+  /** Cut short by leaving, its runtime still current and not operational
+   *  (however it was suspended): another pass, which sweeps first. */
+  needsSweepPass(runtimeOperational: boolean): boolean;
+} {
+  const beganOnOwn = onOwnCredentials();
+  const leftLegacy = (): boolean => beganOnOwn && !onOwnCredentials();
+  return {
+    isCurrent: () => isRuntimeCurrent() && (!beganOnOwn || onOwnCredentials()),
+    leftLegacy,
+    needsSweepPass: (runtimeOperational) => leftLegacy() && isRuntimeCurrent() && !runtimeOperational,
+  };
+}
+
+/**
+ * ADR-154: a runtime's recovery on the runner's credentials as they are.
+ * Off its own, the boot sweep of every task's credential cleanup from the
+ * last process comes first (once per process), so no surviving agent is
+ * reattached before its task's cleanup; a failed sweep fails the recovery,
+ * and the runner stays pending. On its own, the recovery stops where
+ * leaving them begins and reports stale, so the next pass sweeps first.
+ */
+export async function recoverRuntimeOnCredentials(
+  recover: (isCurrent: () => boolean) => Promise<boolean>,
+  isCurrent: () => boolean,
+  sweep: () => Promise<void> = recoverCloudCredentials,
+): Promise<boolean> {
+  if (!onOwnCredentials()) {
+    try {
+      await sweep();
+    } catch (error) {
+      console.warn(
+        `[credentials] boot recovery failed; the runner stays pending: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return false;
+    }
+    if (!isCurrent()) return false;
+    return recover(isCurrent);
+  }
+  const recovered = await recover(() => isCurrent() && onOwnCredentials());
+  return recovered && onOwnCredentials();
+}
+
+type RuntimeRecovery = (isCurrent: () => boolean) => Promise<boolean>;
+
+/**
+ * ADR-154: one runtime activation pass on the runner's credentials as they
+ * change. `pass` runs the activation under the fence (its currency through
+ * publication) with the credentials-aware recovery. A pass that leaving the
+ * runner's own credentials cut short, however it ended (an exception
+ * included, reported to `onError` as the tail reports any other), asks for
+ * the sweep pass (`rerun`). `recover` is a one-shot boot barrier: it
+ * answers only the first recovery a pass asks for, before leaving begins.
+ * Once asked (whatever its outcome: false, or a throw) or once leaving has
+ * begun, every pass recovers afresh (`freshRecover`), never through a result
+ * that settled before a retry or before the sweep.
+ */
+export async function activationPassOnCredentials(options: {
+  isRuntimeCurrent: () => boolean;
+  runtimeOperational: () => boolean;
+  recover: RuntimeRecovery;
+  freshRecover: RuntimeRecovery;
+  pass: (isCurrent: () => boolean, recover: RuntimeRecovery) => Promise<"complete" | "retry" | "rerun">;
+  onError?: (error: unknown) => void;
+}): Promise<"complete" | "retry" | "rerun"> {
+  const fence = credentialsActivationFence(options.isRuntimeCurrent);
+  const recover: RuntimeRecovery = recoverAfresh
+    ? options.freshRecover
+    : (isCurrent) => {
+        recoverAfresh = true;
+        return options.recover(isCurrent);
+      };
+  const cutShort = (): boolean => {
+    if (!fence.needsSweepPass(options.runtimeOperational())) return false;
+    recoverAfresh = true;
+    return true;
+  };
+  let result: "complete" | "retry" | "rerun";
+  try {
+    result = await options.pass(
+      () => fence.isCurrent(),
+      (isCurrent) => recoverRuntimeOnCredentials(recover, isCurrent),
+    );
+  } catch (error) {
+    if (!cutShort()) throw error;
+    try {
+      options.onError?.(error);
+    } catch {
+      // A diagnostic must never cost the sweep pass.
+    }
+    return "rerun";
+  }
+  return cutShort() ? "rerun" : result;
+}
+
+/** Boot recovery has succeeded in this process. */
+export function cloudCredentialsSwept(): boolean {
+  return recovered;
+}
+
+/** Resolves once boot recovery has succeeded in this process. */
+export function cloudCredentialsRecovered(): Promise<void> {
+  return recoveredSignal;
+}
+
+let activated = false;
+/** The runs `cloudCredentialsActivated` has asked for again, by task and run. */
+const resumedRuns = new Set<string>();
+let recoveredRuntimeSetup:
+  | ((run: { taskId: string; runEpoch: number }, signal: AbortSignal) => Promise<void> | void)
+  | null = null;
+const activationFollowers = new Set<() => void>();
+
+/** What runs on a recovered task's runtime once its recovered grant opens
+ *  its gate, however late that grant comes (a task machine: its loader,
+ *  proxy and editor again); `signal` aborts when its run's recovery ends,
+ *  and nothing of it may start after. Set once, at boot. */
+export function setRecoveredRuntimeSetup(
+  setup: ((run: { taskId: string; runEpoch: number }, signal: AbortSignal) => Promise<void> | void) | null,
+): void {
+  recoveredRuntimeSetup = setup;
+}
+
+/** Calls `follower` once, when the runner's tasks first run on cloud
+ *  credentials in this process. Returns its removal. */
+export function onCloudCredentialsActivated(follower: () => void): () => void {
+  activationFollowers.add(follower);
+  return () => void activationFollowers.delete(follower);
+}
+
+/**
+ * The activation authority, the moment the runner's tasks run on cloud
+ * credentials (its mode `active`, after recovery): every running task that
+ * survived this process's start asks for its run's credentials again, as a
+ * recovered start, and its runtime is set up again once its gate opens.
+ * Once per process: a later call (a repeated activation) changes nothing,
+ * and never touches a grant that is live. Its requests go out once the
+ * bridge can send them. Done only once every surviving run was asked for:
+ * a call that throws on the way is done again by the next, which asks for
+ * each run the first one had not.
+ */
+export function cloudCredentialsActivated(): void {
+  const composer = activeCloudCredentials();
+  if (composer === null || !recovered || activated) return;
+  const setup = recoveredRuntimeSetup;
+  for (const run of runningTaskRuns()) {
+    const key = `${run.taskId}\0${String(run.runEpoch)}`;
+    if (resumedRuns.has(key)) continue;
+    composer.resumeRecovered(run, setup ? (signal) => setup(run, signal) : undefined);
+    resumedRuns.add(key);
+  }
+  activated = true;
+  for (const follower of activationFollowers) {
+    try {
+      follower();
+    } catch (error) {
+      console.warn(`[credentials] activation follower failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+
+/** Tests: no recovery or activation has run in this process. */
+export function resetCloudCredentialRecoveryForTests(): void {
+  recoverAfresh = false;
+  recovering = null;
+  recovered = false;
+  recoveredSignal = new Promise<void>((resolve) => (markRecovered = resolve));
+  activated = false;
+  resumedRuns.clear();
+  recoveredRuntimeSetup = null;
+  activationFollowers.clear();
+}
+
+/**
+ * A local operator's Stop of a task on cloud credentials: the start under
+ * way, as it is now, ends before Stop queues behind it (never one found
+ * later by task id, which could be a replacement). The run Stop closes has
+ * its credentials cleaned up inside the stop, by the composer as it is then.
+ * Null on a runner not on cloud credentials.
+ */
+export function localStopCredentials(taskId: string): { closeCredentials(runEpoch: number): Promise<void> } | null {
+  const credentials = activeCloudCredentials();
+  if (credentials === null) return null;
+  const start = credentials.currentStart(taskId);
+  if (start) credentials.interrupt(start);
+  // The task's recovery after a restart ends too.
+  credentials.interruptRecovery(taskId);
+  return {
+    closeCredentials: (runEpoch) =>
+      activeCloudCredentials()?.closeAssignment({ taskId, runEpoch }, "stop") ?? Promise.resolve(),
+  };
+}