@moondeck/station 0.0.0-stage → 1.0.0

package/lib/credential-consumers/mcp.ts

@@ -0,0 +1,389 @@
+/**
+ * ADR-154 §11 on the runner: the MCP gateway serves a task's connections from
+ * its lease, inject-only.
+ *
+ * - The gateway serves exactly what the registry committed: the connections
+ *   of the view its gate opened on (`openMcpGate`), never a grant's candidate
+ *   before that, open gate or not. Closing the gate (`closeMcpGate`) stops
+ *   every request under way for the task, streams and bodies still uploading
+ *   included, and the gateway answers 503 until the gate opens again, never
+ *   falling back to anything else.
+ * - A credential change within the run updates a connection that is
+ *   otherwise the same (credential, revision, URL and kind): a refreshed
+ *   token, or its material becoming readable again or no longer readable.
+ *   Anything else waits for the gate.
+ * - Every request under way stays bound to the exact connection it began on:
+ *   when what is served changes (a credential change, or the gate opening on
+ *   a committed view), a request whose connection is no longer served as it
+ *   was, readable, is stopped at once, streams included. A refreshed token of
+ *   the same connection keeps it.
+ * - Every request is bound to its task's run, its connection's credential,
+ *   revision and URL when it begins: a request that finds any of them
+ *   changed after a refresh is refused, never sent under another run's or
+ *   another account's credential to another server.
+ * - The gateway attaches the connection's header (a static key, or an OAuth
+ *   access token as a bearer). It never calls a token endpoint and never sees
+ *   a refresh token or a client secret: on a 401, or once the token's expiry
+ *   has passed, it asks the registry for a reactive refresh (§7) and tries
+ *   once more only when that installed a newer token.
+ * - A cleanup closes the task's gate, waits for every request under way to
+ *   end, and drops what it names.
+ */
+
+import type {
+  CredentialCleanupRequest,
+  CredentialInstallRequest,
+  TaskAssignment,
+  TaskCredentialLeaseRegistry,
+  TaskCredentialView,
+  TaskMcpConnection,
+} from "../cloud-credential-leases";
+
+/** The registry's typed refresh answer (`credential.refresh.result`). */
+type RefreshResult = Awaited<ReturnType<TaskCredentialLeaseRegistry["requestCredentialRefresh"]>>;
+
+export interface LeasedMcpConnection {
+  credentialId: string;
+  slug: string;
+  url: string;
+  authKind: "none" | "token" | "oauth";
+  revision: string | null;
+  /** What the gateway attaches; null for a connection that needs nothing. */
+  header: { name: string; value: string } | null;
+  /** An OAuth access token's expiry, when known. */
+  expiresAt: number | null;
+  /** The lease parameter's version this material was read at. */
+  version: number | null;
+}
+
+/**
+ * A connection the manifest names but whose material could not be read is
+ * kept as unavailable, under the identity it was named with: the gateway
+ * answers 503 for it, never "no such connection", and never calls it
+ * unauthenticated.
+ */
+export type ServedMcpConnection =
+  | LeasedMcpConnection
+  | {
+      slug: string;
+      credentialId: string;
+      url: string;
+      authKind: "token" | "oauth";
+      revision: string | null;
+      unavailable: true;
+    };
+
+export interface TaskMcpLease {
+  assignment: TaskAssignment;
+  /** False while the registry's gate is closed: serve nothing. */
+  open: boolean;
+  connections: ReadonlyMap<string, ServedMcpConnection>;
+}
+
+/** The registry's answer to a reactive refresh (the frozen contract). */
+export type McpCredentialRefresher = (
+  assignment: TaskAssignment,
+  credentialId: string,
+  revision: string,
+) => Promise<Pick<RefreshResult, "outcome" | "version" | "expiresAt">>;
+
+interface TaskMcpState {
+  assignment: TaskAssignment;
+  /** Null while the gate is closed. */
+  served: Map<string, ServedMcpConnection> | null;
+  /** Requests under way, each with the connection it began on: aborted when
+   *  the gate closes, or once that connection is no longer served as it
+   *  was, readable. */
+  requests: Map<AbortController, LeasedMcpConnection>;
+  drained: Array<() => void>;
+}
+
+const tasks = new Map<string, TaskMcpState>();
+let refresher: McpCredentialRefresher | null = null;
+
+function connectionOf(connection: TaskMcpConnection): ServedMcpConnection {
+  const { manifest, material } = connection;
+  if (manifest.authKind === "none") {
+    return {
+      credentialId: manifest.credentialId,
+      slug: manifest.slug,
+      url: manifest.url,
+      authKind: "none",
+      revision: null,
+      header: null,
+      expiresAt: null,
+      version: null,
+    };
+  }
+  if (connection.availability !== "available" || !material) {
+    return {
+      slug: manifest.slug,
+      credentialId: manifest.credentialId,
+      url: manifest.url,
+      authKind: manifest.authKind,
+      revision: manifest.revision,
+      unavailable: true,
+    };
+  }
+  return {
+    credentialId: manifest.credentialId,
+    slug: manifest.slug,
+    url: manifest.url,
+    authKind: manifest.authKind,
+    revision: manifest.revision,
+    header:
+      material.authKind === "token"
+        ? { name: material.header.name, value: material.header.value }
+        : { name: "Authorization", value: `Bearer ${material.accessToken}` },
+    expiresAt: material.authKind === "oauth" ? material.expiresAt : null,
+    version: connection.observedVersion,
+  };
+}
+
+function connectionsOf(view: TaskCredentialView): Map<string, ServedMcpConnection> {
+  return new Map(view.mcp.map((connection) => [connection.manifest.slug, connectionOf(connection)]));
+}
+
+function isLeased(connection: ServedMcpConnection | undefined): connection is LeasedMcpConnection {
+  return connection !== undefined && !("unavailable" in connection);
+}
+
+/** The same connection, all but its material (or whether it could be read):
+ *  a credential change. */
+function sameConnection(a: ServedMcpConnection, b: ServedMcpConnection): boolean {
+  return a.credentialId === b.credentialId && a.revision === b.revision && a.url === b.url && a.authKind === b.authKind;
+}
+
+function stateFor(assignment: TaskAssignment): TaskMcpState {
+  const current = tasks.get(assignment.taskId);
+  if (current && sameAssignment(current.assignment, assignment)) return current;
+  // Another run: whatever the last one had is closed and stopped first.
+  if (current) stopRequests(current);
+  const fresh: TaskMcpState = { assignment: { ...assignment }, served: null, requests: new Map(), drained: [] };
+  tasks.set(assignment.taskId, fresh);
+  return fresh;
+}
+
+/**
+ * A grant's install is a candidate: nothing of it is served until the
+ * registry commits it and opens its gate on it (`openMcpGate`), even with the
+ * gate open on the run's previous grant. A credential change of this run
+ * takes effect now, on a connection already served that is otherwise the
+ * same (credential, revision, URL, kind): a refreshed token, or its material
+ * becoming readable again, or no longer readable, which stops the requests
+ * under way on it.
+ */
+export function installMcpConnections(request: CredentialInstallRequest): void {
+  const current = tasks.get(request.assignment.taskId);
+  // An install for an older run, or a change for another run than the one
+  // served, changes nothing.
+  if (current && current.assignment.runEpoch > request.assignment.runEpoch) return;
+  if (request.reason === "credential-change" && current && !sameAssignment(current.assignment, request.assignment)) {
+    return;
+  }
+  // On cloud credentials from its first install, gate closed until opened:
+  // never the runner's own store.
+  const state = stateFor(request.assignment);
+  if (request.reason !== "credential-change" || !state.served) return;
+  const next = connectionsOf(request.next);
+  for (const [slug, served] of state.served) {
+    const proposed = next.get(slug);
+    if (!proposed) {
+      // Gone from the view: never served past it, gate or not.
+      state.served.delete(slug);
+    } else if (sameConnection(served, proposed)) {
+      state.served.set(slug, proposed);
+    }
+  }
+  stopUnserved(state);
+}
+
+/** The registry opened its gate on this committed view: serve exactly it,
+ *  and stop what is under way on a connection it no longer serves as it
+ *  was. An older run's opening changes nothing. */
+export function openMcpGate(assignment: TaskAssignment, view: TaskCredentialView): void {
+  const current = tasks.get(assignment.taskId);
+  if (current && current.assignment.runEpoch > assignment.runEpoch) return;
+  const state = stateFor(assignment);
+  state.served = connectionsOf(view);
+  stopUnserved(state);
+}
+
+/** The registry closed its gate: serve nothing, and stop what is under way. */
+export function closeMcpGate(assignment: TaskAssignment): void {
+  const state = tasks.get(assignment.taskId);
+  if (!state || !sameAssignment(state.assignment, assignment)) return;
+  state.served = null;
+  stopRequests(state);
+}
+
+function stopRequests(state: TaskMcpState): void {
+  for (const controller of state.requests.keys()) controller.abort();
+}
+
+/** Stop every request under way whose connection the task no longer serves
+ *  as it began, readable: gone, unreadable, or another credential, revision,
+ *  URL or kind. A refreshed token of the same connection keeps it. */
+function stopUnserved(state: TaskMcpState): void {
+  for (const [controller, began] of state.requests) {
+    const now = state.served?.get(began.slug);
+    if (!isLeased(now) || !sameConnection(now, began)) controller.abort();
+  }
+}
+
+/** The promise's outcome, or a rejection once `signal` aborts first. */
+function untilAborted<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(new Error("aborted"));
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(new Error("aborted"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/** A cleanup: the gate closes, every request under way ends, and the task's
+ *  record stays, closed (a full cleanup) until a new grant opens it. */
+export async function cleanupMcpConnections(request: CredentialCleanupRequest): Promise<void> {
+  const state = tasks.get(request.assignment.taskId);
+  if (!state || !sameAssignment(state.assignment, request.assignment)) {
+    if (request.mode === "full") stateFor(request.assignment);
+    return;
+  }
+  state.served = null;
+  stopRequests(state);
+  if (state.requests.size > 0) await new Promise<void>((resolve) => state.drained.push(resolve));
+}
+
+/** The task is gone (teardown): forget its record entirely. */
+export function forgetLeasedMcp(taskId: string): void {
+  const state = tasks.get(taskId);
+  if (state) stopRequests(state);
+  tasks.delete(taskId);
+}
+
+/** The task's leased MCP connections, or undefined for a task that is not on
+ *  cloud credentials. */
+export function leasedMcpFor(taskId: string): TaskMcpLease | undefined {
+  const state = tasks.get(taskId);
+  if (!state) return undefined;
+  return { assignment: { ...state.assignment }, open: state.served !== null, connections: state.served ?? new Map() };
+}
+
+/** The (id, slug) pairs the task's gateway ACL and MCP configs list. */
+export function leasedMcpAclEntries(taskId: string): Array<{ id: string; slug: string }> {
+  const served = tasks.get(taskId)?.served;
+  if (!served) return [];
+  // Membership follows the committed manifest, not whether its material was
+  // readable on this pass. A named-but-unreadable connection remains in agent
+  // config so the gateway can distinguish the temporary 503 from an absent
+  // connection's 404, and so a later material refresh needs no process
+  // restart just to make the tool visible again.
+  return [...served.values()].map((connection) => ({ id: connection.credentialId, slug: connection.slug }));
+}
+
+export function setMcpCredentialRefresher(next: McpCredentialRefresher | null): void {
+  refresher = next;
+}
+
+/**
+ * One gateway request's hold on its task: bound to the run and the
+ * connection it began with, aborted when the gate closes, counted until it
+ * ends (a cleanup waits for it).
+ */
+export interface McpRequestHold {
+  signal: AbortSignal;
+  /** The connection this request began with. */
+  connection: LeasedMcpConnection;
+  /** The same connection as now served, with whatever material it has now;
+   *  null when it changed (another run, credential, revision or URL), the
+   *  gate closed, or the request ended. */
+  current(): LeasedMcpConnection | null;
+  /** Ask for a newer token after `used` failed: the connection as served
+   *  then, only when it carries a newer token than `used` that is not past
+   *  its expiry; null otherwise (busy, unavailable, needs a new sign-in,
+   *  expired, or the connection moved). */
+  refresh(used: LeasedMcpConnection): Promise<LeasedMcpConnection | null>;
+  end(): void;
+}
+
+/** Hold a served connection for one request; null when the gate is closed
+ *  or the task serves no such leased connection now. */
+export function holdLeasedMcp(taskId: string, slug: string): McpRequestHold | null {
+  const state = tasks.get(taskId);
+  const connection = state?.served?.get(slug);
+  if (!state || !isLeased(connection)) return null;
+  const controller = new AbortController();
+  state.requests.set(controller, connection);
+  const assignment = { ...state.assignment };
+  let ended = false;
+  const current = (): LeasedMcpConnection | null => {
+    const live = tasks.get(taskId);
+    if (ended || controller.signal.aborted || live !== state || !sameAssignment(live.assignment, assignment)) return null;
+    const now = live.served?.get(slug);
+    return isLeased(now) && sameConnection(now, connection) ? now : null;
+  };
+  return {
+    signal: controller.signal,
+    connection,
+    current,
+    async refresh(used) {
+      if (!refresher || used.authKind !== "oauth" || used.revision === null) return null;
+      let outcome: Awaited<ReturnType<McpCredentialRefresher>>["outcome"];
+      try {
+        // A gate that closes meanwhile ends the wait: the registry's refresh
+        // carries on for the next request, this one does not hold a cleanup.
+        ({ outcome } = await untilAborted(refresher(assignment, used.credentialId, used.revision), controller.signal));
+      } catch {
+        return null;
+      }
+      if (outcome !== "refreshed" && outcome !== "fresh") return null;
+      const now = current();
+      // Only a newer token is worth sending again, and never one already
+      // past its expiry.
+      if (!now || (now.version ?? 0) <= (used.version ?? 0)) return null;
+      if (now.authKind === "oauth" && now.expiresAt !== null && now.expiresAt <= Date.now()) return null;
+      return now;
+    },
+    end() {
+      if (ended) return;
+      ended = true;
+      state.requests.delete(controller);
+      if (state.requests.size === 0) for (const resolve of state.drained.splice(0)) resolve();
+    },
+  };
+}
+
+/** Process shutdown: every request under way, for any task, ended. A closed
+ *  gate has aborted them; each ends as its request does. */
+export function drainLeasedMcpRequests(): Promise<void> {
+  return Promise.all(
+    [...tasks.values()].map((state) =>
+      state.requests.size === 0 ? undefined : new Promise<void>((resolve) => state.drained.push(resolve)),
+    ),
+  ).then(() => undefined);
+}
+
+/** Tests only. */
+export function resetLeasedMcpForTests(): void {
+  for (const state of tasks.values()) stopRequests(state);
+  tasks.clear();
+  refresher = null;
+}
+
+function sameAssignment(a: TaskAssignment, b: TaskAssignment): boolean {
+  return a.taskId === b.taskId && a.runEpoch === b.runEpoch;
+}
+
+/** Tests only: requests under way for a task. */
+export function leasedMcpRequestsForTests(taskId: string): number {
+  return tasks.get(taskId)?.requests.size ?? 0;
+}

package/lib/credential-consumers/task-files.ts

@@ -0,0 +1,127 @@
+/**
+ * ADR-154 §6: how a credential file gets into a task. Shared by the
+ * consumers that write one (GitHub and SSH, engine accounts).
+ *
+ * - Only by streaming the content over an exec's stdin, never staged on the
+ *   runner's disk, in a clean environment (`env -i`, absolute paths, the
+ *   sanitized overlay for anything a provider adds before it).
+ * - Under the task's home only, through the no-follow writer: each directory
+ *   opened from its parent's descriptor, the content written to an
+ *   intermediate created exclusively and renamed into place, so the file
+ *   never lands anywhere the cleanup inventory does not name.
+ * - Each exec is admitted at the provider's last moment by the caller's
+ *   `admit`, against the task's live state.
+ * - A failure is a fixed message: nothing a subprocess printed rides it.
+ */
+
+import { CLEAN_CONTAINER_ENV, SANITIZED_CONTAINER_ENV } from "../github-tokens";
+import { RUNTIME_AUTHORITY_ENV } from "../runtime-authority";
+import type { TaskEnvironmentHandle } from "../task-environment/types";
+
+export const TASK_HOME = "/home/node";
+/** Where a file is written before it is renamed into place. */
+export const STAGED_SUFFIX = ".uai-tmp";
+
+const EXEC_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_BYTES = 64 * 1024;
+
+export type TaskWriteEnvironment = Pick<TaskEnvironmentHandle, "exec" | "descriptor">;
+
+/**
+ * Run `argv` in the task with nothing inherited (`env -i`, absolute paths,
+ * the sanitized overlay for anything a provider adds before it), admitted
+ * at the provider's last moment by `admit`. A failure is a fixed message:
+ * nothing a subprocess printed rides the error.
+ */
+export async function runInTask(
+  environment: TaskWriteEnvironment,
+  argv: readonly [string, ...string[]],
+  stdin: string | null,
+  what: string,
+  admit: () => void,
+  user: "node" | "root" = "node",
+): Promise<Uint8Array> {
+  const [first, ...rest] = [...CLEAN_CONTAINER_ENV, ...argv];
+  const result = await environment.exec({
+    argv: [first!, ...rest],
+    user,
+    env: { ...SANITIZED_CONTAINER_ENV, ...RUNTIME_AUTHORITY_ENV },
+    projectEnvProfile: "maintenance",
+    ...(stdin !== null ? { stdin: Buffer.from(stdin, "utf8") } : {}),
+    timeoutMs: EXEC_TIMEOUT_MS,
+    maxOutputBytes: MAX_OUTPUT_BYTES,
+    admit,
+  });
+  if (result.exitCode !== 0 || result.stdoutTruncated) {
+    throw new Error(`${what} failed in the task (exit ${result.exitCode ?? result.signal ?? "unknown"})`);
+  }
+  return result.stdout;
+}
+
+/**
+ * Write stdin to one file under the task's home without following anything
+ * the task could have put in the way: each directory is opened from its
+ * parent's descriptor with O_NOFOLLOW (created owner-only when missing), the
+ * content goes to `<name>.uai-tmp` created exclusively, and a rename relative
+ * to that same directory puts it in place. The rename replaces whatever entry
+ * is there, a symlink included, and fails on a directory: the file never
+ * lands anywhere the inventory does not name.
+ */
+export const TASK_FILE_WRITE_HELPER = String.raw`
+import os
+import sys
+
+root, relative, mode = sys.argv[1], sys.argv[2], int(sys.argv[3], 8)
+parts = relative.split("/")
+if any(part in ("", ".", "..") for part in parts):
+    raise SystemExit(2)
+data = sys.stdin.buffer.read()
+directory = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
+fd = os.open(root, directory)
+try:
+    for part in parts[:-1]:
+        try:
+            os.mkdir(part, 0o700, dir_fd=fd)
+        except FileExistsError:
+            pass
+        child = os.open(part, directory, dir_fd=fd)
+        os.close(fd)
+        fd = child
+    name = parts[-1]
+    staged = name + ".uai-tmp"
+    try:
+        os.unlink(staged, dir_fd=fd)
+    except FileNotFoundError:
+        pass
+    out = os.open(staged, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600, dir_fd=fd)
+    try:
+        os.fchmod(out, mode)
+        view = memoryview(data)
+        while view:
+            view = view[os.write(out, view):]
+        os.fsync(out)
+    finally:
+        os.close(out)
+    os.rename(staged, name, src_dir_fd=fd, dst_dir_fd=fd)
+finally:
+    os.close(fd)
+`;
+
+/** The exec that writes `path` from stdin (`TASK_FILE_WRITE_HELPER`). */
+export function writeTaskFileArgv(path: string, mode: "600" | "644"): [string, ...string[]] {
+  if (!path.startsWith(`${TASK_HOME}/`)) throw new Error("a task credential path is outside the task home");
+  return ["/usr/bin/python3", "-I", "-c", TASK_FILE_WRITE_HELPER, TASK_HOME, path.slice(TASK_HOME.length + 1), mode];
+}
+
+/** A credential is written only into the runtime of the task it belongs to:
+ *  the cleanup that must delete it refuses any other task's runtime. */
+export function assertTaskRuntime(environment: TaskWriteEnvironment, taskId: string): void {
+  if (environment.descriptor.taskId !== taskId) {
+    throw new Error("a task credential would be written into another task's runtime");
+  }
+}
+
+/** A path and the intermediate it is written through. */
+export function withStaged(...paths: string[]): string[] {
+  return paths.flatMap((path) => [path, `${path}${STAGED_SUFFIX}`]);
+}

package/lib/credential-consumers/task-secrets.ts

@@ -0,0 +1,10 @@
+import type { TaskAssignment, TaskCredentialView } from "../cloud-credential-leases";
+const served = new Map<string, TaskCredentialView>();
+export function openTaskSecrets(assignment: Readonly<TaskAssignment>, view: TaskCredentialView): void { if (view.assignment.taskId !== assignment.taskId || view.assignment.runEpoch !== assignment.runEpoch) throw new Error("task secret assignment mismatch"); served.set(assignment.taskId, view); }
+export function closeTaskSecrets(assignment: Readonly<TaskAssignment>): void { const view = served.get(assignment.taskId); if (view && view.assignment.runEpoch <= assignment.runEpoch) served.delete(assignment.taskId); }
+export function taskSecretsView(taskId: string, runEpoch?: number | null) { const view = served.get(taskId); return view && (runEpoch == null || view.assignment.runEpoch === runEpoch) ? view.taskSecrets ?? [] : []; }
+export function deliveredTaskSecrets(taskId: string, runEpoch?: number | null): { revision: string; withheld: string[]; values: Record<string, string> } {
+ const entries = taskSecretsView(taskId, runEpoch); const values: Record<string,string> = Object.create(null) as Record<string,string>;
+ for (const e of entries) if (e.manifest.mode === "delivered" && e.material) values[e.manifest.name] = e.material.value;
+ return { revision: JSON.stringify(entries.map(e => [e.manifest.name, e.manifest.generation, e.material !== null])), withheld: entries.map(e => e.manifest.name), values };
+}

package/lib/credential-store-pickup.ts

@@ -0,0 +1,149 @@
+/**
+ * Uai-operated hosts: pick up credentials the broker Lambda refreshed
+ * (ADR-135). Every 15 minutes list the engine parameters under this host's
+ * scopes — names and versions only, no decryption — and re-import whatever
+ * moved, then re-push brokered copies of that kind into running tasks. The
+ * reactive path calls `pickupNow` right after a forced refresh.
+ *
+ * Never refreshes anything: on a Uai-operated host the Lambda is the one
+ * refresher. Owned hosts never run this (no store).
+ */
+
+import { onOwnCredentials } from "./cloud-credential-host";
+import { configuredCredentialStore, credentialStorePrefix } from "./credential-store";
+import { engineAccountListPaths } from "./credential-store-scope";
+import {
+  applyStoredEngineAccount,
+  engineAccountHostId,
+  parseEngineAccountParameterName,
+} from "./engine-accounts";
+import { setPickupNow } from "./token-broker-local";
+
+const PICKUP_INTERVAL_MS = 15 * 60_000;
+
+let timer: ReturnType<typeof setInterval> | null = null;
+let known: Map<string, number> | null = null;
+let inflight: Promise<PickupSummary> | null = null;
+let repushHook: ((kind: string) => Promise<void>) | null = null;
+
+export interface PickupSummary {
+  skipped: boolean;
+  listed: number;
+  changed: number;
+  applied: number;
+  errors: number;
+}
+
+function log(line: string): void {
+  console.log(`[credential-pickup] ${line}`);
+}
+
+/**
+ * One pass. The first pass records the baseline (the start-up reconcile
+ * already imported current values); later passes apply changed versions.
+ */
+export async function pickupChangedCredentials(): Promise<PickupSummary> {
+  const store = configuredCredentialStore();
+  const summary: PickupSummary = { skipped: false, listed: 0, changed: 0, applied: 0, errors: 0 };
+  if (!store) return { ...summary, skipped: true };
+  const prefix = credentialStorePrefix();
+  const paths = engineAccountListPaths(prefix, engineAccountHostId());
+  if (paths === null) return { ...summary, skipped: true };
+  const current = new Map<string, number>();
+  for (const path of paths) {
+    try {
+      for (const entry of await store.listVersions(path)) {
+        if (parseEngineAccountParameterName(entry.name, prefix)) current.set(entry.name, entry.version);
+      }
+    } catch (err) {
+      summary.errors++;
+      log(`listing ${path} failed: ${err instanceof Error ? err.message : String(err)}`);
+      // An incomplete listing must not look like deletions; keep the baseline.
+      return summary;
+    }
+  }
+  summary.listed = current.size;
+  if (known === null) {
+    known = current;
+    return summary;
+  }
+  const kinds = new Set<string>();
+  for (const [name, version] of current) {
+    if (known.get(name) === version) continue;
+    summary.changed++;
+    try {
+      const value = await store.get(name);
+      if (value === null) continue;
+      const applied = applyStoredEngineAccount(name, value);
+      if (applied) {
+        summary.applied++;
+        kinds.add(applied.kind);
+      }
+    } catch (err) {
+      summary.errors++;
+      log(`applying ${name} failed: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    known.set(name, version);
+  }
+  for (const name of [...known.keys()]) if (!current.has(name)) known.delete(name);
+  for (const kind of kinds) {
+    try {
+      await repushHook?.(kind);
+    } catch (err) {
+      log(`re-push of ${kind} copies failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (summary.changed > 0) {
+    log(`${summary.changed} parameter(s) changed, ${summary.applied} applied, ${summary.errors} errors`);
+  }
+  return summary;
+}
+
+async function pickupSerialized(): Promise<PickupSummary> {
+  if (inflight) return inflight;
+  // ADR-154: no copy picked up once the runner leaves its own credentials.
+  if (!onOwnCredentials()) return { skipped: true, listed: 0, changed: 0, applied: 0, errors: 0 };
+  inflight = pickupChangedCredentials().finally(() => {
+    inflight = null;
+  });
+  return inflight;
+}
+
+/** Uai-operated hosts on their own credentials only: baseline now, then
+ *  poll every 15 minutes. */
+export function startCredentialStorePickup(hooks: { repush: (kind: string) => Promise<void> }): void {
+  if (timer || !configuredCredentialStore() || !onOwnCredentials()) return;
+  repushHook = hooks.repush;
+  setPickupNow(async () => {
+    await pickupSerialized();
+  });
+  void pickupSerialized().catch((err) =>
+    log(`baseline failed: ${err instanceof Error ? err.message : String(err)}`),
+  );
+  timer = setInterval(() => {
+    void pickupSerialized().catch((err) =>
+      log(`poll failed: ${err instanceof Error ? err.message : String(err)}`),
+    );
+  }, PICKUP_INTERVAL_MS);
+  timer.unref?.();
+}
+
+/** Stop polling (ADR-154: the runner leaves its own credentials); resolves
+ *  once a pickup under way has ended. */
+export async function stopCredentialStorePickup(): Promise<void> {
+  if (timer) clearInterval(timer);
+  timer = null;
+  setPickupNow(null);
+  await inflight?.catch(() => undefined);
+}
+
+/** Tests. */
+export function resetCredentialStorePickup(): void {
+  if (timer) clearInterval(timer);
+  timer = null;
+  known = null;
+  inflight = null;
+  repushHook = null;
+  setPickupNow(null);
+}