@runuai/host 0.9.148 → 0.9.150

package/lib/secrets-proxy/host.ts

@@ -0,0 +1,93 @@
+/**
+ * The secrets proxy as one runner starts it (ADR-153 §3): the kill switch,
+ * the runtime (CA, placeholders, engine, audit) under the runner's data dir,
+ * and the gateway's TLS handler, which is how connections a task's forwarder
+ * authenticated reach the engine.
+ *
+ * What a task may use comes from the policy source; where upstream names are
+ * resolved depends on where the runner sits (see `resolveWithSystem` and
+ * `resolverIgnoringHostsFile`). Both are the caller's, so this module holds
+ * no knowledge of tasks, runtimes or declarations.
+ */
+
+import type { Socket } from "node:net";
+
+import { openAesGcm, sealAesGcm } from "../secrets";
+import type { SealedText } from "./ca-store";
+import {
+  createSecretsProxyRuntime,
+  secretsProxyEnabled,
+  type SecretsProxyRuntime,
+  type TaskProxyPolicySource,
+} from "./runtime";
+
+/** The connection the gateway hands over: authenticated as one task's
+ *  generation, with the gateway's own check of whether it still is. */
+export interface AuthenticatedTaskConnection {
+  readonly taskId: string;
+  readonly socket: Socket;
+  readonly isCurrent: () => boolean;
+}
+
+export interface SecretsProxyHostDeps {
+  dataDir: string;
+  policy: TaskProxyPolicySource;
+  resolveHost: (hostname: string) => Promise<string[]>;
+  /** `registerTaskGatewayTlsHandler` from the gateway; returns the undo. */
+  registerTlsHandler: (handler: (connection: AuthenticatedTaskConnection) => void) => () => void;
+  env?: NodeJS.ProcessEnv;
+  log?: Pick<Console, "warn">;
+  /** Test seams; production seals with host-master.key. */
+  seal?: (plaintext: string) => SealedText;
+  open?: (ct: Buffer, nonce: Buffer) => string;
+}
+
+export interface SecretsProxyHost {
+  readonly runtime: SecretsProxyRuntime;
+  /** Unregisters from the gateway, then closes every connection. */
+  stop(): Promise<void>;
+}
+
+/**
+ * Starts the proxy, or returns null when `UAI_SECRETS_PROXY=off`. Off, no CA
+ * is created and nothing is registered with the gateway; the policy source
+ * must then withhold every proxied key (ADR-153: a proxied key is a
+ * placeholder or withheld, never its value).
+ */
+export function startSecretsProxyHost(deps: SecretsProxyHostDeps): SecretsProxyHost | null {
+  if (!secretsProxyEnabled(deps.env)) return null;
+  const runtime = createSecretsProxyRuntime({
+    dataDir: deps.dataDir,
+    policy: deps.policy,
+    seal: deps.seal ?? ((plaintext) => sealAesGcm(plaintext)),
+    open: deps.open ?? ((ct, nonce) => openAesGcm(ct, nonce)),
+    resolveHost: deps.resolveHost,
+    ...(deps.log ? { log: deps.log } : {}),
+  });
+  const unregister = deps.registerTlsHandler(({ taskId, socket, isCurrent }) =>
+    runtime.proxy.handleConnection({ taskId, socket, isCurrent }),
+  );
+  let stopping: Promise<void> | null = null;
+  return {
+    runtime,
+    stop() {
+      stopping ??= (async () => {
+        unregister();
+        await runtime.close();
+      })();
+      return stopping;
+    },
+  };
+}
+
+/** The runner's one proxy, set at startup and cleared at shutdown; null under
+ *  the kill switch. Task lifecycle code reads it, and never starts or stops it. */
+let active: SecretsProxyHost | null = null;
+
+export function setActiveSecretsProxy(host: SecretsProxyHost | null): void {
+  active = host;
+}
+
+export function activeSecretsProxy(): SecretsProxyHost | null {
+  return active;
+}

package/lib/secrets-proxy/hostname.ts

@@ -0,0 +1,60 @@
+/**
+ * Canonical DNS names for the secrets proxy (ADR-153 §3, rule 2).
+ *
+ * The SNI name, the Host header and an absolute-form authority are all
+ * compared against the task's declared domains in this one form: a lowercase
+ * A-label hostname with at most one trailing dot removed. Anything else —
+ * an IP literal, a U-label, a port, an empty label — is not a name we could
+ * have minted a certificate for, so it is refused rather than normalised.
+ */
+
+import { isIP } from "node:net";
+
+const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export function canonicalHostname(input: string): string | null {
+  if (typeof input !== "string") return null;
+  // ASCII is checked BEFORE lowercasing: `"K".toLowerCase()` is "k", so a
+  // U-label could otherwise lowercase into a declared A-label.
+  if (!/^[A-Za-z0-9.-]{1,254}$/.test(input)) return null;
+  let name = input.toLowerCase();
+  if (name.endsWith(".")) name = name.slice(0, -1);
+  if (name.length === 0 || name.length > 253) return null;
+  const labels = name.split(".");
+  if (!labels.every((label) => LABEL.test(label))) return null;
+  if (isIP(name) !== 0) return null;
+  // WHATWG URL parsers and inet_aton read a name whose last label is a number
+  // (`127.1`, `0x7f.1`) as IPv4; such a name is an IP literal in disguise.
+  const last = labels[labels.length - 1] ?? "";
+  if (/^[0-9]+$/.test(last) || /^0x[0-9a-f]*$/.test(last)) return null;
+  return name;
+}
+
+/**
+ * True when an authority (`host` or `host:port`, from a Host header or an
+ * absolute-form request target) names exactly `domain` on the HTTPS port.
+ * Bracketed IPv6 literals, userinfo and any port but 443 never match.
+ */
+export function authorityMatches(authority: string, domain: string): boolean {
+  const match = /^([^:@[\]]+)(?::([0-9]+))?$/.exec(authority);
+  if (match === null) return false;
+  const [, host = "", port] = match;
+  if (port !== undefined && port !== "443") return false;
+  return canonicalHostname(host) === domain;
+}
+
+/**
+ * Domains a key may never be proxied to (ADR-153 §4 "Fail closed"), checked
+ * on the canonical form. GitHub keeps its own credential path (the GH
+ * identity work), and Uai's own domains carry the runner's and the cloud's
+ * traffic. A name with no dot, or under `localhost`, can never hold a public
+ * certificate, so proxying to it could only ever fail upstream verification.
+ * A key declared for one of these is withheld, never delivered.
+ */
+const NEVER_PROXIED_SUFFIXES = ["github.com", "githubusercontent.com", "runuai.com", "localhost"] as const;
+
+export function isProxiableDomain(domain: string): boolean {
+  const name = canonicalHostname(domain);
+  if (name === null || name !== domain || !name.includes(".")) return false;
+  return !NEVER_PROXIED_SUFFIXES.some((suffix) => name === suffix || name.endsWith(`.${suffix}`));
+}

package/lib/secrets-proxy/placeholders.ts

@@ -0,0 +1,196 @@
+/**
+ * Placeholders for proxied keys (ADR-153 §4 "Placeholders").
+ *
+ * A placeholder stands for one (task, source project, key). It is random,
+ * so it names exactly one task and cannot be guessed from the key name, and
+ * it is stable for the task's life, so processes that started with it keep
+ * working through value rotations and runner restarts. The per-task map is
+ * persisted (0600) in the runner's data dir and dropped at teardown.
+ *
+ * A repo's `@placeholder` fixes the SHAPE, not the value: the parser keeps
+ * only its prefix (up to and including the last `_` or `-`) and its length,
+ * so SDKs that check a key's prefix accept it; the rest is always random
+ * letters and digits, at least 32 of them. A literal placeholder would be
+ * shared by every task of the project and could not tell them apart, so it
+ * never reaches the runner.
+ */
+
+import { randomInt } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+import { writeDurableFileAtomic } from "../env-file";
+import { isSafeHostTaskId } from "../task-identity";
+
+const STORE_VERSION = 1;
+const MIN_RANDOM_CHARS = 32;
+/** The longest placeholder minted: a declared shape that would mint a longer
+ *  one falls back to the default shape. */
+const MAX_PLACEHOLDER_CHARS = 256;
+const BASE62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const DEFAULT_PREFIX = "uai_proxied_";
+/** A declared prefix this code mints after: RFC 3986's unreserved
+ *  characters, ending in `_` or `-`, or none. A placeholder made only of
+ *  these reads the same raw, percent-encoded and JSON-escaped, so wherever
+ *  an upstream echoes it the task sees exactly its own placeholder; and
+ *  nothing in it can break a header, a URL, a JSON string or a shell value. */
+const SHAPE_PREFIX = /^(?:[A-Za-z0-9._~-]*[_-])?$/;
+
+/** The shape a repository's `@placeholder` declares, as the parser keeps it. */
+export interface PlaceholderShape {
+  prefix: string;
+  totalLength: number;
+}
+
+export interface PlaceholderRef {
+  taskId: string;
+  projectId: string;
+  key: string;
+  /** The repo's `@placeholder` shape, when it declared one. */
+  shape?: PlaceholderShape | null;
+}
+
+export interface PlaceholderEntry {
+  projectId: string;
+  key: string;
+  placeholder: string;
+}
+
+function randomFrom(alphabet: string, length: number): string {
+  let output = "";
+  for (let index = 0; index < length; index += 1) output += alphabet[randomInt(alphabet.length)];
+  return output;
+}
+
+/** A shape this code can mint: a safe prefix, and a length that leaves at
+ *  least 32 random characters within the cap. Anything else falls back to
+ *  the default shape. */
+function isMintableShape(shape: unknown): shape is PlaceholderShape {
+  if (shape === null || typeof shape !== "object") return false;
+  const { prefix, totalLength } = shape as Partial<PlaceholderShape>;
+  return (
+    typeof prefix === "string" &&
+    SHAPE_PREFIX.test(prefix) &&
+    typeof totalLength === "number" &&
+    Number.isSafeInteger(totalLength) &&
+    totalLength >= prefix.length + MIN_RANDOM_CHARS &&
+    totalLength <= MAX_PLACEHOLDER_CHARS
+  );
+}
+
+/** Exported for tests; the store is the only production caller. */
+export function mintPlaceholder(key: string, shape?: PlaceholderShape | null): string {
+  if (isMintableShape(shape)) return shape.prefix + randomFrom(BASE62, shape.totalLength - shape.prefix.length);
+  const name = key.replace(/[^A-Za-z0-9_]/g, "_").slice(0, 64);
+  return `${DEFAULT_PREFIX}${name}_${randomFrom(BASE62, MIN_RANDOM_CHARS)}`;
+}
+
+interface StoredTask {
+  v: number;
+  entries: PlaceholderEntry[];
+}
+
+/** A name that keys the per-task index: non-empty, and without the NUL the
+ *  index joins project and key with. */
+const isName = (value: unknown): value is string =>
+  typeof value === "string" && value.length > 0 && !value.includes("\u0000");
+
+/** What this code can mint: an optional prefix of safe characters ending in
+ *  `_` or `-`, then a random tail of at least 32 base62 characters (hex is
+ *  base62 too), within the cap. */
+const MINTED_SHAPE = new RegExp(`^(?:[A-Za-z0-9._~-]*[_-])?[A-Za-z0-9]{${MIN_RANDOM_CHARS},}$`);
+const isMintedShape = (value: unknown): value is string =>
+  typeof value === "string" && value.length <= MAX_PLACEHOLDER_CHARS && MINTED_SHAPE.test(value);
+
+function isEntry(value: unknown): value is PlaceholderEntry {
+  if (value === null || typeof value !== "object") return false;
+  const entry = value as Record<string, unknown>;
+  return isName(entry.projectId) && isName(entry.key) && isMintedShape(entry.placeholder);
+}
+
+export interface PlaceholderStore {
+  /** The task's placeholder for this key, minted and persisted on first use. */
+  placeholderFor(ref: PlaceholderRef): string;
+  /** Every placeholder the task holds. */
+  entries(taskId: string): readonly PlaceholderEntry[];
+  /** Forget the task (teardown). */
+  dropTask(taskId: string): void;
+}
+
+interface TaskPlaceholders {
+  readonly entries: readonly PlaceholderEntry[];
+  /** `${projectId}\0${key}` → placeholder, for O(1) lookups. */
+  readonly byKey: ReadonlyMap<string, string>;
+  readonly taken: ReadonlySet<string>;
+}
+
+/** Null when the entries are not a function both ways — two placeholders
+ *  for one key, or one placeholder for two keys — which this code never
+ *  writes and the engine could not route. */
+function indexed(entries: readonly PlaceholderEntry[]): TaskPlaceholders | null {
+  const byKey = new Map(entries.map((entry) => [`${entry.projectId}\u0000${entry.key}`, entry.placeholder]));
+  const taken = new Set(entries.map((entry) => entry.placeholder));
+  if (byKey.size !== entries.length || taken.size !== entries.length) return null;
+  return { entries, byKey, taken };
+}
+
+export function createPlaceholderStore(options: { dir: string }): PlaceholderStore {
+  const tasksDir = join(options.dir, "placeholders");
+  const cache = new Map<string, TaskPlaceholders>();
+
+  const pathFor = (taskId: string): string => {
+    // The id becomes a path component; an unsafe one never reaches disk.
+    if (!isSafeHostTaskId(taskId)) throw new Error("invalid host task identity");
+    return join(tasksDir, `${taskId}.json`);
+  };
+
+  const load = (taskId: string): TaskPlaceholders => {
+    const cached = cache.get(taskId);
+    if (cached !== undefined) return cached;
+    const path = pathFor(taskId);
+    let entries: PlaceholderEntry[] = [];
+    if (existsSync(path)) {
+      const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<StoredTask>;
+      if (parsed.v !== STORE_VERSION || !Array.isArray(parsed.entries) || !parsed.entries.every(isEntry)) {
+        // A torn or foreign file must not silently re-mint: processes may
+        // already hold the old placeholders, and new ones would fail for
+        // them without any sign why.
+        throw new Error("the task's placeholder store is not in a format this runner reads");
+      }
+      entries = parsed.entries.map(({ projectId, key, placeholder }) => ({ projectId, key, placeholder }));
+    }
+    const task = indexed(entries);
+    if (task === null) throw new Error("the task's placeholder store maps a key or a placeholder twice");
+    cache.set(taskId, task);
+    return task;
+  };
+
+  return {
+    placeholderFor(ref) {
+      if (!isName(ref.projectId) || !isName(ref.key)) throw new Error("invalid placeholder reference");
+      const task = load(ref.taskId);
+      const existing = task.byKey.get(`${ref.projectId}\u0000${ref.key}`);
+      if (existing !== undefined) return existing;
+      let placeholder = mintPlaceholder(ref.key, ref.shape);
+      // 190 random bits make a collision a practical impossibility; checking
+      // anyway keeps the task's map a function from placeholder to key.
+      while (task.taken.has(placeholder)) placeholder = mintPlaceholder(ref.key, ref.shape);
+      const entries = [...task.entries, { projectId: ref.projectId, key: ref.key, placeholder }];
+      const next = indexed(entries);
+      if (next === null) throw new Error("placeholder collision");
+      // Durable: processes already hold these placeholders, so a file lost to
+      // a crash would re-mint ones that fail for them.
+      writeDurableFileAtomic(pathFor(ref.taskId), `${JSON.stringify({ v: STORE_VERSION, entries } satisfies StoredTask)}\n`);
+      cache.set(ref.taskId, next);
+      return placeholder;
+    },
+    entries(taskId) {
+      return load(taskId).entries;
+    },
+    dropTask(taskId) {
+      cache.delete(taskId);
+      if (!isSafeHostTaskId(taskId)) return;
+      rmSync(pathFor(taskId), { force: true });
+    },
+  };
+}

package/lib/secrets-proxy/policy.ts

@@ -0,0 +1,141 @@
+/**
+ * Which keys each task has in proxy mode (ADR-153's effective policy: the
+ * owner's binding ∩ the task's schema observation), and what of that the
+ * task may use right now. The declarations work supplies the policy; until
+ * it lands no key is proxied, so a served task's policy is empty and the
+ * proxy, though running, intercepts nothing.
+ *
+ * The raw policy is what the engine learns first, before a key's pins go in.
+ * Using a key is gated, per key and per moment, on its readiness
+ * (`proxiedKeyDeliverable`): the placeholder in /env, the preamble, and the
+ * real value read for each injection. A key that fails the gate is withheld,
+ * never delivered.
+ */
+
+import { sameTaskEnvHead, taskEnvView, type TaskEnvSnapshot } from "../project-env-task-policy";
+import { activeSecretsProxy } from "./host";
+import { proxiedKeyDeliverable } from "./readiness";
+import type { ProxiedKeyPolicy, TaskProxyPolicySource } from "./runtime";
+
+/**
+ * The runner's policy: for a served task, what one snapshot of its env says
+ * (ADR-153 §4). Each call reads its own snapshot, and a value is given only
+ * for a key still proxied at exactly the head the caller learned with it, so
+ * a head that moved since withholds the key until the engine learns the new
+ * one. With no snapshot reader, or none for the task, nothing is proxied.
+ */
+export function createTaskProxyPolicySource(
+  isServed: (taskId: string) => boolean,
+  readSnapshot: (taskId: string) => TaskEnvSnapshot | null = () => null,
+): TaskProxyPolicySource {
+  const viewOf = (taskId: string) => {
+    if (!isServed(taskId)) return null;
+    const snapshot = readSnapshot(taskId);
+    return snapshot === null ? null : taskEnvView(snapshot);
+  };
+  return {
+    proxiedKeys: (taskId) => {
+      if (!isServed(taskId)) return null;
+      return (viewOf(taskId)?.proxied ?? []).map(({ projectId, key, domains, placeholder, head }) => ({
+        projectId,
+        key,
+        domains,
+        placeholder,
+        head,
+      }));
+    },
+    realValue: (taskId, ref) => {
+      const { head } = ref;
+      if (head === undefined) return null;
+      const proxied = viewOf(taskId)?.proxied.find((entry) => entry.projectId === ref.projectId && entry.key === ref.key);
+      return proxied !== undefined && sameTaskEnvHead(proxied.head, head) ? proxied.value : null;
+    },
+    notDelivered: (taskId) => viewOf(taskId)?.notDelivered ?? null,
+  };
+}
+
+function keyOf(source: TaskProxyPolicySource, taskId: string, ref: { projectId: string; key: string }): ProxiedKeyPolicy | null {
+  return source.proxiedKeys(taskId)?.find((key) => key.projectId === ref.projectId && key.key === ref.key) ?? null;
+}
+
+/**
+ * The policy the engine consults: its keys as given, and a key's real value
+ * only while that key is deliverable to the task. A placeholder a shell kept
+ * from an earlier, ready moment therefore stops injecting the moment the
+ * task's CA or pins are no longer in place.
+ */
+export function gateTaskProxyPolicy(source: TaskProxyPolicySource): TaskProxyPolicySource {
+  return {
+    proxiedKeys: (taskId) => source.proxiedKeys(taskId),
+    realValue: (taskId, ref) => {
+      const key = keyOf(source, taskId, ref);
+      if (key === null || !proxiedKeyDeliverable(taskId, key.domains)) return null;
+      return source.realValue(taskId, ref);
+    },
+    // What /env withholds passes through untouched: the gate only narrows
+    // what the proxy injects, never what the task is denied.
+    notDelivered: (taskId) => source.notDelivered?.(taskId) ?? null,
+  };
+}
+
+/** The runner's policy, set at startup whether or not the proxy runs: with
+ *  it off, proxy-mode keys must still be known, to be withheld. */
+let active: TaskProxyPolicySource | null = null;
+
+export function setActiveTaskProxyPolicy(policy: TaskProxyPolicySource | null): void {
+  active = policy;
+}
+
+export function activeTaskProxyPolicy(): TaskProxyPolicySource | null {
+  return active;
+}
+
+/** What a task's /env carries for its proxy-mode keys. */
+export interface TaskProxiedEnv {
+  /** Every proxy-mode name: never rendered from the project's values. */
+  readonly withheld: readonly string[];
+  /** Those of them the task may use now, with their placeholders. */
+  readonly placeholders: Readonly<Record<string, string>>;
+}
+
+const NOTHING_PROXIED: TaskProxiedEnv = Object.freeze({ withheld: [], placeholders: {} });
+
+function usable(policy: TaskProxyPolicySource, taskId: string, keys: readonly ProxiedKeyPolicy[]): ProxiedKeyPolicy[] {
+  return keys.filter((key) => proxiedKeyDeliverable(taskId, key.domains) && policy.realValue(taskId, key) !== null);
+}
+
+/**
+ * The task's proxy-mode keys it may use right now: each one the proxy would
+ * inject at this moment (deliverable, and with a value; null withholds). The
+ * placeholder in /env and the preamble's line both come from this, so
+ * neither ever offers a key the proxy would refuse.
+ */
+export function usableProxiedKeys(taskId: string): ProxiedKeyPolicy[] {
+  return active === null ? [] : usable(active, taskId, active.proxiedKeys(taskId) ?? []);
+}
+
+/**
+ * The /env view of a task's proxy-mode keys: withheld from the project
+ * values, and replaced by its placeholder where the key is usable now.
+ * Read per render; the renderer keys its cache on the result, so a change of
+ * readiness alone re-renders.
+ */
+export function taskProxiedEnv(taskId: string): TaskProxiedEnv {
+  const policy = active;
+  const keys = policy?.proxiedKeys(taskId) ?? [];
+  // Every name the task does not get as its value, withheld or proxied.
+  const notDelivered = policy?.notDelivered?.(taskId) ?? [];
+  if (policy === null || (keys.length === 0 && notDelivered.length === 0)) return NOTHING_PROXIED;
+  const runtime = activeSecretsProxy()?.runtime ?? null;
+  const placeholders: Record<string, string> = {};
+  if (runtime !== null) {
+    for (const key of usable(policy, taskId, keys)) {
+      try {
+        placeholders[key.key] = runtime.placeholderFor(taskId, key);
+      } catch {
+        // Not mintable now (a closing runtime, a stale policy): withheld.
+      }
+    }
+  }
+  return { withheld: [...new Set([...keys.map((key) => key.key), ...notDelivered])].sort(), placeholders };
+}

package/lib/secrets-proxy/readiness.ts

@@ -0,0 +1,148 @@
+/**
+ * How far each task is behind the secrets proxy (ADR-153 §3), and what that
+ * allows: the per-task readiness the runner records as its root steps land,
+ * the trust env it gives the task's shells, and the gate every proxied key
+ * passes before the task gets its placeholder or the engine reads its value.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { activeSecretsProxy } from "./host";
+import { TASK_CA_BUNDLE_PATH } from "./task-scripts";
+
+const SYSTEM_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
+
+/** The trust env every loader shell gets while the proxy runs: Node reads the
+ *  Uai bundle; OpenSSL, Python and the rest the system bundle the CA is
+ *  installed into. All three are reserved: no project value can set them. */
+export const TASK_TRUST_ENV: Readonly<Record<string, string>> = Object.freeze({
+  NODE_EXTRA_CA_CERTS: TASK_CA_BUNDLE_PATH,
+  SSL_CERT_FILE: SYSTEM_BUNDLE,
+  REQUESTS_CA_BUNDLE: SYSTEM_BUNDLE,
+});
+
+export type ProxyStepOutcome = "installed" | "failed" | "skipped";
+
+/** What the task's current container start, and every reconcile since,
+ *  actually put in place. */
+export interface TaskProxyReadiness {
+  /** The CA bundle in the task's trust store. */
+  readonly trust: ProxyStepOutcome;
+  /** The bundle installed, to notice a newer one. */
+  readonly bundle: string | null;
+  /** The NAT chain and the hosts block. */
+  readonly pins: ProxyStepOutcome;
+  /** The domains those pins currently cover. */
+  readonly pinnedDomains: readonly string[];
+  /** The task's forwarder is known to run: the start that recorded this
+   *  ended with it running, or a recovery launched it. Pins wait for it, so
+   *  no name ever points at a listener that is not there. */
+  readonly forwarder: boolean;
+}
+
+const NOTHING: TaskProxyReadiness = Object.freeze({
+  trust: "skipped",
+  bundle: null,
+  pins: "skipped",
+  pinnedDomains: [],
+  forwarder: false,
+});
+
+const recorded = new Map<string, TaskProxyReadiness>();
+
+/** A task-up under way: the directory it reports into, and what the runner
+ *  handed it. Read live, so readiness is exact while uai-init already runs. */
+export interface PendingStart {
+  readonly dir: string;
+  readonly bundle: string;
+  readonly domains: readonly string[];
+}
+const starting = new Map<string, PendingStart>();
+
+function outcomeIn(dir: string, name: "trust" | "pins"): ProxyStepOutcome {
+  try {
+    const text = readFileSync(join(dir, name), "utf8").trim();
+    return text === "installed" || text === "failed" ? text : "skipped";
+  } catch {
+    // Not reported yet: the step has not finished.
+    return "skipped";
+  }
+}
+
+export function taskProxyReadiness(taskId: string): TaskProxyReadiness {
+  const pending = starting.get(taskId);
+  if (pending !== undefined) {
+    const trust = outcomeIn(pending.dir, "trust");
+    const pins = outcomeIn(pending.dir, "pins");
+    return {
+      trust,
+      bundle: trust === "installed" ? pending.bundle : null,
+      pins,
+      pinnedDomains: pins === "installed" ? pending.domains : [],
+      // Known only once the start ends.
+      forwarder: false,
+    };
+  }
+  return recorded.get(taskId) ?? NOTHING;
+}
+
+export function recordTaskProxyReadiness(taskId: string, change: Partial<TaskProxyReadiness>): void {
+  recorded.set(taskId, { ...(recorded.get(taskId) ?? NOTHING), ...change });
+}
+
+/** The task's container is gone, or stopped: nothing of the proxy is in it. */
+export function forgetTaskProxyReadiness(taskId: string): void {
+  recorded.delete(taskId);
+}
+
+export function beginTaskStart(taskId: string, pending: PendingStart): void {
+  forgetTaskProxyReadiness(taskId);
+  starting.set(taskId, pending);
+}
+
+export function endTaskStart(taskId: string): PendingStart | undefined {
+  const pending = starting.get(taskId);
+  starting.delete(taskId);
+  return pending;
+}
+
+/** A task-up is under way: it alone writes the task's pins until it ends. */
+export function isTaskStarting(taskId: string): boolean {
+  return starting.has(taskId);
+}
+
+/** The runner's own env for the task's shells (see TASK_TRUST_ENV): only
+ *  once the CA is in its trust store, so Node never names a missing file. */
+export function taskTrustEnv(taskId: string): Readonly<Record<string, string>> {
+  return activeSecretsProxy() !== null && taskProxyReadiness(taskId).trust === "installed" ? TASK_TRUST_ENV : {};
+}
+
+const CERTIFICATE_END = "-----END CERTIFICATE-----";
+
+/** The certificate that signs now: the first in the current bundle. */
+function signerOf(bundle: string): string {
+  const end = bundle.indexOf(CERTIFICATE_END);
+  return end === -1 ? bundle : bundle.slice(0, end + CERTIFICATE_END.length);
+}
+
+/**
+ * Whether a proxy-mode key reaching `domains` may be used by the task right
+ * now: the proxy runs, the CA that signs now is in the task's trust store,
+ * and every one of those domains is pinned. Checked for the placeholder in
+ * /env, for the preamble, and again for every injection, so a placeholder a
+ * shell kept from an earlier, ready moment stops working as soon as the task
+ * is not ready.
+ */
+export function proxiedKeyDeliverable(taskId: string, domains: readonly string[]): boolean {
+  const proxy = activeSecretsProxy();
+  if (proxy === null || domains.length === 0) return false;
+  const ready = taskProxyReadiness(taskId);
+  return (
+    ready.trust === "installed" &&
+    ready.bundle !== null &&
+    ready.bundle.includes(signerOf(proxy.runtime.caBundlePem())) &&
+    ready.pins === "installed" &&
+    domains.every((domain) => ready.pinnedDomains.includes(domain))
+  );
+}