@runuai/host 0.9.148 → 0.9.149

package/lib/project-env-schema-capture.ts

@@ -0,0 +1,342 @@
+/**
+ * ADR-153 §4, "One observation per task and project", on Docker and Apple.
+ *
+ * task-up records the commit each project's worktree branched from in the
+ * task's host control tree, which the container never sees, before anything
+ * in the task starts. From that commit alone, read in the host-only git cache
+ * (never in the worktree or its container-mounted repository), the runner
+ * reads `.env.schema`, parses it, and keeps the observation beside the
+ * record, written once. A resume, a retry or a restart reuses it, so editing
+ * `.env.schema` inside the task changes nothing for that task.
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+  closeSync,
+  fsyncSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import {
+  CURRENT_PROJECT_ENV_PARSER_EPOCH,
+  isProjectEnvSchemaObservation,
+  type ProjectEnvSchemaObservation,
+} from "../src/protocol";
+import { MAX_ENV_SCHEMA_BYTES, parseEnvSchemaDeclarations } from "./env-schema";
+import { projectDir, taskDir } from "./env";
+
+/** Where task-up records each project's base, and the runner its observation. */
+export function taskEnvSchemaDir(taskId: string): string {
+  return join(taskDir(taskId), ".uai", "env-schemas");
+}
+
+/** The host-only cache task-up fetches each project into. */
+function projectHostCache(projectId: string): string {
+  return join(projectDir(projectId), "host-cache.git");
+}
+
+// Ids name files here: anything else is never looked up.
+const SAFE_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+/** The base task-up recorded: a commit, a proven-empty repository, or none
+ *  (a task started before this was recorded, whose base cannot be told). */
+export type RecordedEnvSchemaBase = { kind: "commit"; oid: string } | { kind: "empty" } | null;
+
+function recordedBase(taskId: string, projectId: string): RecordedEnvSchemaBase {
+  let text: string;
+  try {
+    text = readFileSync(join(taskEnvSchemaDir(taskId), `${projectId}.base`), "utf8");
+  } catch {
+    return null;
+  }
+  const line = text.trim();
+  if (line === "empty") return { kind: "empty" };
+  const match = /^oid ([0-9a-f]+)$/.exec(line);
+  return match !== null && OID.test(match[1]!) ? { kind: "commit", oid: match[1]! } : null;
+}
+
+const UNSET_GIT_ENV = [
+  "GIT_ASKPASS",
+  "SSH_ASKPASS",
+  "SSH_AUTH_SOCK",
+  "GIT_CONFIG",
+  "GIT_CONFIG_PARAMETERS",
+  "GIT_TRACE",
+  "GIT_TRACE2",
+  "GIT_TRACE_CURL",
+  "GIT_TRACE_PACKET",
+  "GIT_TRACE_REDACT",
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+];
+
+/** Read-only plumbing in the host cache, with task-up's `git_host_control`
+ *  hardening: no system or global config, no hooks, no credentials. */
+function git(cache: string, args: string[]): Buffer | null {
+  const environment: NodeJS.ProcessEnv = { ...process.env };
+  for (const name of UNSET_GIT_ENV) delete environment[name];
+  Object.assign(environment, {
+    LC_ALL: "C",
+    GIT_CONFIG_GLOBAL: "/dev/null",
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_COUNT: "2",
+    GIT_CONFIG_KEY_0: "core.hooksPath",
+    GIT_CONFIG_VALUE_0: "/dev/null",
+    GIT_CONFIG_KEY_1: "core.fsmonitor",
+    GIT_CONFIG_VALUE_1: "false",
+    GIT_SSH_COMMAND: "/bin/false",
+    GIT_TERMINAL_PROMPT: "0",
+  });
+  // `--no-replace-objects`: a replace ref in the cache must not stand in for
+  // the commit or blob that was recorded.
+  const argv = ["--no-replace-objects", "--git-dir", cache, "-c", "credential.helper=", ...args];
+  // A process that could not run to its end (a timeout under load, a signal)
+  // says nothing about the repository: tried again before it counts.
+  for (let attempt = 1; ; attempt += 1) {
+    const result = spawnSync("git", argv, {
+      env: environment,
+      maxBuffer: MAX_ENV_SCHEMA_BYTES + 64 * 1024,
+      timeout: 15_000,
+    });
+    if (result.error === undefined && result.signal === null) {
+      return result.status === 0 && Buffer.isBuffer(result.stdout) ? result.stdout : null;
+    }
+    if (attempt >= GIT_ATTEMPTS) return null;
+  }
+}
+
+const GIT_ATTEMPTS = 3;
+
+/** A commit's committer time in seconds, from `rev-list --format=%ct`; null
+ *  for anything else, or a time milliseconds cannot hold exactly. */
+function committerTime(listed: Buffer | null): number | null {
+  if (listed === null) return null;
+  // `rev-list --format=%ct` prints the time on its own line, after a
+  // "commit <oid>" header on a git that still prints one.
+  const line = listed.toString("utf8").trim().split("\n").pop() ?? "";
+  if (!/^\d{1,15}$/.test(line)) return null;
+  const seconds = Number(line);
+  return Number.isSafeInteger(seconds * 1000) ? seconds : null;
+}
+const unreached = (projectId: string, reason: "base_commit_missing" | "schema_read_failed"): ProjectEnvSchemaObservation => ({
+  projectId,
+  status: "unavailable",
+  parserEpoch: CURRENT_PROJECT_ENV_PARSER_EPOCH,
+  baseOid: null,
+  baseCommitTimeMs: null,
+  reason,
+});
+
+/**
+ * The reading of one project's schema at a base, as the git commands it
+ * needs: each yield is a command's arguments, answered with its output (null
+ * when it failed). Written once, run where the repository is: in the host
+ * cache on an owned runner, in the fresh clone on a task machine.
+ */
+function* observationSteps(
+  projectId: string,
+  base: RecordedEnvSchemaBase,
+): Generator<string[], ProjectEnvSchemaObservation, Buffer | null> {
+  if (base === null) return unreached(projectId, "base_commit_missing");
+  if (base.kind === "empty") {
+    return {
+      projectId,
+      status: "resolved",
+      parserEpoch: CURRENT_PROJECT_ENV_PARSER_EPOCH,
+      baseOid: null,
+      baseCommitTimeMs: null,
+      declarations: [],
+      issues: [],
+    };
+  }
+  // Plumbing only: `rev-list` prints the committer time alone, so no
+  // repository setting (a signature check, a pager) runs anything, and a
+  // commit message of any size is never read.
+  const time = committerTime(yield ["rev-list", "--no-walk", "--format=%ct", base.oid]);
+  if (time === null) return unreached(projectId, "schema_read_failed");
+  const committed = {
+    projectId,
+    parserEpoch: CURRENT_PROJECT_ENV_PARSER_EPOCH,
+    baseOid: base.oid,
+    baseCommitTimeMs: time * 1000,
+  };
+  const unreadable = (reason: string): ProjectEnvSchemaObservation => ({ ...committed, status: "unavailable", reason });
+  const entry = yield ["ls-tree", "-z", base.oid, "--", ".env.schema"];
+  if (entry === null) return unreached(projectId, "schema_read_failed");
+  // A commit without the file declares nothing, which is a trusted answer.
+  if (entry.length === 0) return { ...committed, status: "resolved", declarations: [], issues: [] };
+  const match = /^(\d{6}) blob ([0-9a-f]+)\t\.env\.schema\0$/.exec(entry.toString("utf8"));
+  if (match === null || (match[1] !== "100644" && match[1] !== "100755")) return unreadable("schema_not_regular_file");
+  const blob = match[2]!;
+  const size = (yield ["cat-file", "-s", blob])?.toString("utf8").trim();
+  if (size === undefined || !/^\d+$/.test(size)) return unreached(projectId, "schema_read_failed");
+  if (Number(size) > MAX_ENV_SCHEMA_BYTES) return unreadable("schema_too_large");
+  const content = yield ["cat-file", "blob", blob];
+  if (content === null) return unreached(projectId, "schema_read_failed");
+  const parsed = parseEnvSchemaDeclarations(new Uint8Array(content));
+  if (!parsed.ok) return unreadable(parsed.reason);
+  return { ...committed, status: "resolved", declarations: parsed.declarations, issues: parsed.issues };
+}
+
+/** The observation of one project's schema at its recorded base, read in
+ *  the host cache. */
+export function observeEnvSchemaAt(
+  projectId: string,
+  base: RecordedEnvSchemaBase,
+  cache = projectHostCache(projectId),
+): ProjectEnvSchemaObservation {
+  const steps = observationSteps(projectId, base);
+  let next = steps.next();
+  while (!next.done) next = steps.next(git(cache, next.value));
+  return next.value;
+}
+
+/** Git run in a repository somewhere else: its output, or null if it failed. */
+export type RemoteGit = (args: string[]) => Promise<Buffer | null>;
+
+async function observeWith(projectId: string, base: RecordedEnvSchemaBase, run: RemoteGit): Promise<ProjectEnvSchemaObservation> {
+  const steps = observationSteps(projectId, base);
+  let next = steps.next();
+  while (!next.done) next = steps.next(await run(next.value));
+  return next.value;
+}
+
+function readObservation(taskId: string, projectId: string): ProjectEnvSchemaObservation | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(join(taskEnvSchemaDir(taskId), `${projectId}.json`), "utf8"));
+  } catch {
+    return null;
+  }
+  return isProjectEnvSchemaObservation(parsed) && parsed.projectId === projectId ? parsed : null;
+}
+
+/** Writes `body` at `path`, durably, unless something is there already,
+ *  which then stays. */
+function writeOnce(dir: string, path: string, body: string): void {
+  const temporary = join(dir, `.${randomBytes(8).toString("hex")}.tmp`);
+  const fd = openSync(temporary, "wx", 0o600);
+  try {
+    writeSync(fd, body);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    linkSync(temporary, path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  } finally {
+    unlinkSync(temporary);
+  }
+  const directory = openSync(dir, "r");
+  try {
+    fsyncSync(directory);
+  } finally {
+    closeSync(directory);
+  }
+}
+
+const cached = new Map<string, ProjectEnvSchemaObservation>();
+const MAX_CACHED = 512;
+
+/**
+ * Each project's observation for the task, in the order given: the one
+ * stored, or one read from its recorded base now and stored before it is
+ * returned.
+ *
+ * The first /env request of the task captures it this way, before any
+ * command in the task gets a value: task-up records the base before the
+ * container starts. With no base recorded, an observation is stored only
+ * once task-up has finished (`final`), since until then task-up may still be
+ * about to record it. A project id that cannot name a file, or a store that
+ * cannot be written, gets an unavailable observation that is not kept, so a
+ * later capture can still record one.
+ */
+export function captureTaskEnvSchemas(
+  taskId: string,
+  projectIds: readonly string[],
+  options: { final: boolean } = { final: true },
+): ProjectEnvSchemaObservation[] {
+  return projectIds.map((projectId) => {
+    if (!SAFE_ID.test(taskId) || !SAFE_ID.test(projectId)) return unreached(projectId, "schema_read_failed");
+    const stored = taskEnvSchemaObservation(taskId, projectId);
+    if (stored !== null) return stored;
+    const base = recordedBase(taskId, projectId);
+    const observation = observeEnvSchemaAt(projectId, base);
+    if (base === null && !options.final) return observation;
+    return storeObservation(taskId, projectId, observation);
+  });
+}
+
+/** Stores the task's observation of a project unless one is stored, and
+ *  answers whichever is stored then; the given one if none can be. */
+function storeObservation(taskId: string, projectId: string, observation: ProjectEnvSchemaObservation): ProjectEnvSchemaObservation {
+  try {
+    const dir = taskEnvSchemaDir(taskId);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeOnce(dir, join(dir, `${projectId}.json`), `${JSON.stringify(observation)}\n`);
+  } catch {
+    return observation;
+  }
+  // Whatever was there first is the task's: a concurrent capture may have won.
+  return taskEnvSchemaObservation(taskId, projectId) ?? observation;
+}
+
+/**
+ * A task machine's capture (ADR-153 §4, "Machine and sidecar"): right after
+ * a project's clone, before anything in the task starts, the clone's HEAD
+ * and the `.env.schema` at it, read by `git` run in the fresh clone, and
+ * stored once in the runner's control tree. A stored observation is reused.
+ * A clone with no commit at all is a proven-empty repository.
+ */
+export async function captureTaskEnvSchemaFromClone(
+  taskId: string,
+  projectId: string,
+  run: RemoteGit,
+): Promise<ProjectEnvSchemaObservation> {
+  if (!SAFE_ID.test(taskId) || !SAFE_ID.test(projectId)) return unreached(projectId, "schema_read_failed");
+  const stored = taskEnvSchemaObservation(taskId, projectId);
+  if (stored !== null) return stored;
+  const head = (await run(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]))?.toString("utf8").trim();
+  let base: RecordedEnvSchemaBase;
+  if (head !== undefined && OID.test(head)) {
+    base = { kind: "commit", oid: head };
+  } else {
+    const refs = await run(["for-each-ref", "--count=1", "--format=%(refname)"]);
+    if (refs === null || refs.length > 0) return storeObservation(taskId, projectId, unreached(projectId, "schema_read_failed"));
+    base = { kind: "empty" };
+  }
+  return storeObservation(taskId, projectId, await observeWith(projectId, base, run));
+}
+
+
+/** Forget what was read of a task's observations, when the task ends. */
+export function forgetTaskEnvSchemaObservations(taskId: string): void {
+  for (const key of [...cached.keys()]) if (key.startsWith(`${taskId}\u0000`)) cached.delete(key);
+}
+
+/** The task's stored observation of a project, or null when none is stored
+ *  yet (or what is stored is not one). Stored ones never change, so they are
+ *  kept in memory once read. */
+export function taskEnvSchemaObservation(taskId: string, projectId: string): ProjectEnvSchemaObservation | null {
+  if (!SAFE_ID.test(taskId) || !SAFE_ID.test(projectId)) return null;
+  const cacheKey = `${taskId}\u0000${projectId}`;
+  const hit = cached.get(cacheKey);
+  if (hit !== undefined) return hit;
+  const observation = readObservation(taskId, projectId);
+  if (observation === null) return null;
+  if (cached.size >= MAX_CACHED) cached.delete(cached.keys().next().value!);
+  cached.set(cacheKey, observation);
+  return observation;
+}

package/lib/project-env-staging.ts

@@ -0,0 +1,148 @@
+/**
+ * Immutable project-env staging writer (ADR-153).
+ *
+ * The sign-in box may create and tag the SecureString but may never read it.
+ * A deterministic envelope and a master-key HMAC in the create-time tags make
+ * an ambiguous retry recognizable without granting GetParameter or allowing
+ * an overwrite of somebody else's value.
+ */
+
+import { createHash, createHmac } from "node:crypto";
+
+import {
+  MAX_PROJECT_ENV_STAGED_ENVELOPE_BYTES,
+  isProjectEnvStagingPutFrame,
+  type ProjectEnvStagingPutFrame,
+} from "../src/protocol";
+import {
+  configuredCredentialStore,
+  credentialStorePrefix,
+  parameterName,
+  type CredentialStore,
+  type ImmutableParameterPutResult,
+} from "./credential-store";
+import { masterKey } from "./secrets";
+
+const STAGING_HMAC_DOMAIN = Buffer.from(
+  "uai.project_env.staging.v1\0",
+  "utf8",
+);
+
+export const PROJECT_ENV_STAGING_TAGS = {
+  org: "org",
+  project: "project",
+  mac: "uai_staging_mac",
+} as const;
+
+export class ProjectEnvStagingInvalidError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProjectEnvStagingInvalidError";
+  }
+}
+
+export interface StoredProjectEnvStagingEnvelope {
+  v: 2;
+  kind: "project-env";
+  orgId: string;
+  projectId: string;
+  key: string;
+  stagingId: string;
+  value: string;
+}
+
+export interface ProjectEnvStagingWriteOptions {
+  /** Tests/custom stores may inject the write-only implementation. */
+  store?: CredentialStore | null;
+  /** Tests may pin the process-local authentication key. */
+  hmacKey?: Buffer;
+  prefix?: string;
+}
+
+/** Exact JSON shared with the cloud-side reservation helper. */
+export function projectEnvStagingEnvelope(
+  frame: ProjectEnvStagingPutFrame,
+): string {
+  if (!isProjectEnvStagingPutFrame(frame)) {
+    throw new ProjectEnvStagingInvalidError(
+      "invalid immutable environment staging request",
+    );
+  }
+  const envelope: StoredProjectEnvStagingEnvelope = {
+    v: 2,
+    kind: "project-env",
+    orgId: frame.orgId,
+    projectId: frame.projectId,
+    key: frame.key,
+    stagingId: frame.stagingId,
+    value: frame.value,
+  };
+  const encoded = JSON.stringify(envelope);
+  if (
+    Buffer.byteLength(encoded, "utf8") >
+    MAX_PROJECT_ENV_STAGED_ENVELOPE_BYTES
+  ) {
+    throw new ProjectEnvStagingInvalidError(
+      "environment value exceeds the immutable staging limit",
+    );
+  }
+  return encoded;
+}
+
+export function projectEnvStagingParameterName(
+  frame: Pick<ProjectEnvStagingPutFrame, "projectId" | "key" | "stagingId">,
+  prefix = credentialStorePrefix(),
+): string {
+  const digest = createHash("sha256").update(frame.key, "utf8").digest("hex");
+  return parameterName(
+    prefix,
+    "projects",
+    frame.projectId,
+    "env-values",
+    digest,
+    frame.stagingId,
+  );
+}
+
+export function projectEnvStagingTags(
+  frame: Pick<ProjectEnvStagingPutFrame, "orgId" | "projectId">,
+  encodedEnvelope: string,
+  hmacKey: Buffer = masterKey(),
+): Record<string, string> {
+  const mac = createHmac("sha256", hmacKey)
+    .update(STAGING_HMAC_DOMAIN)
+    .update(encodedEnvelope, "utf8")
+    .digest("hex");
+  return {
+    [PROJECT_ENV_STAGING_TAGS.org]: frame.orgId,
+    [PROJECT_ENV_STAGING_TAGS.project]: frame.projectId,
+    [PROJECT_ENV_STAGING_TAGS.mac]: mac,
+  };
+}
+
+export async function writeProjectEnvStaging(
+  frame: ProjectEnvStagingPutFrame,
+  options: ProjectEnvStagingWriteOptions = {},
+): Promise<ImmutableParameterPutResult> {
+  const encoded = projectEnvStagingEnvelope(frame);
+  const store =
+    Object.prototype.hasOwnProperty.call(options, "store")
+      ? options.store
+      : configuredCredentialStore();
+  if (!store) {
+    throw new Error("the sign-in box has no credential store for environment staging");
+  }
+  if (!store.putImmutable) {
+    throw new Error("the credential store does not support immutable environment staging");
+  }
+  const name = projectEnvStagingParameterName(
+    frame,
+    options.prefix ?? credentialStorePrefix(),
+  );
+  const tags = projectEnvStagingTags(
+    frame,
+    encoded,
+    options.hmacKey ?? masterKey(),
+  );
+  return store.putImmutable(name, encoded, tags);
+}

package/lib/project-env-task-policy.ts

@@ -0,0 +1,176 @@
+/**
+ * ADR-153 §4 at runtime: what each stored key of a task's projects gives the
+ * task (its real value, a placeholder proxied to its domains, or nothing),
+ * and why a key is withheld. Pure: the caller reads the task's own,
+ * immutable schema observations and the runner's binding records; this
+ * decides, with the derivation the settings page shows (`projectEnvKeyPolicyAt`
+ * under each binding's own policy epoch).
+ *
+ * One authority unit per key: the first project, in task order, with a
+ * stored row for a key owns it, and only that project's observation, binding
+ * and placeholder apply. A later project's declaration never meets an
+ * earlier project's value.
+ */
+
+import { projectEnvKeyPolicyAt, type ProjectEnvSchemaEvidence } from "../src/project-env-policy";
+import { projectEnvWithheldReason } from "../src/project-env-wording";
+import {
+  isProjectEnvHead,
+  isProjectEnvSchemaObservation,
+  sameProjectEnvHead,
+  type ProjectEnvHead,
+  type ProjectEnvSchemaDeclaration,
+} from "../src/protocol";
+
+/** Whether two heads are the same, field by field (the contract's rule). */
+export const sameTaskEnvHead: (left: ProjectEnvHead, right: ProjectEnvHead) => boolean = sameProjectEnvHead;
+
+/** Which generation of a key's value a decision is for: the record's head,
+ *  as the contract defines it (ADR-153 §4, "Where bindings live"). */
+export type TaskEnvHead = ProjectEnvHead;
+
+/** A live head: one with a value. */
+export type TaskEnvLiveHead = Extract<ProjectEnvHead, { tombstone: false }>;
+
+/** A stored key and its binding record, as the runner holds them. */
+export interface TaskEnvRecord {
+  key: string;
+  /** The record's head. A tombstone has no value, so it owns nothing; a head
+   *  that is not one withholds the key, since its value cannot be told. */
+  head: unknown;
+  /** The binding, or null for an unbound key. Checked by the policy: one the
+   *  contract rejects withholds the key. */
+  binding: unknown;
+  /** The policy epoch the binding was written under. */
+  policyEpoch: unknown;
+}
+
+/** One of the task's projects, lead first. */
+export interface TaskEnvProject {
+  projectId: string;
+  /** The task's own observation of this project's schema. One the contract
+   *  rejects, or another project's, counts as a schema it could not read. */
+  observation: unknown;
+  /** Every live value of the project on this runner, with its record:
+   *  value, head, binding and epoch read from one snapshot of the store, so
+   *  a decision is never paired with another generation's value. */
+  records: readonly TaskEnvRecord[];
+}
+
+export type TaskEnvPlaceholderShape = NonNullable<ProjectEnvSchemaDeclaration["placeholder"]>;
+
+/** What a key gives the task. A delivered or proxied key names the head its
+ *  value must have: the value is used only at that head. */
+export type TaskEnvKeyPolicy =
+  | { projectId: string; key: string; kind: "deliver"; head: TaskEnvLiveHead }
+  | {
+      projectId: string;
+      key: string;
+      kind: "proxy";
+      head: TaskEnvLiveHead;
+      domains: string[];
+      placeholder: TaskEnvPlaceholderShape | null;
+    }
+  | { projectId: string; key: string; kind: "withhold"; reason: string };
+
+const headOf = (value: unknown): ProjectEnvHead | null => (isProjectEnvHead(value) ? value : null);
+
+/** What each stored key gives the task, in task order. */
+export function taskEnvKeyPolicies(projects: readonly TaskEnvProject[]): TaskEnvKeyPolicy[] {
+  const claimed = new Set<string>();
+  const policies: TaskEnvKeyPolicy[] = [];
+  for (const project of projects) {
+    const observation =
+      isProjectEnvSchemaObservation(project.observation) && project.observation.projectId === project.projectId
+        ? project.observation
+        : null;
+    for (const record of project.records) {
+      const head = headOf(record.head);
+      // A deleted value's record keeps its binding, but owns no key.
+      if (claimed.has(record.key) || head?.tombstone === true) continue;
+      claimed.add(record.key);
+      const ref = { projectId: project.projectId, key: record.key };
+      if (head === null) {
+        policies.push({ ...ref, kind: "withhold", reason: "binding_invalid" });
+        continue;
+      }
+      const declaration =
+        observation?.status === "resolved"
+          ? (observation.declarations.find((candidate) => candidate.key === record.key) ?? null)
+          : null;
+      const evidence: ProjectEnvSchemaEvidence =
+        observation?.status === "resolved" ? { status: "resolved", declaration } : { status: "unavailable" };
+      const { decision } = projectEnvKeyPolicyAt(record.policyEpoch, evidence, record.binding);
+      if (decision.kind === "deliver") {
+        policies.push({ ...ref, kind: "deliver", head });
+      } else if (decision.kind === "proxy") {
+        policies.push({ ...ref, kind: "proxy", head, domains: decision.domains, placeholder: declaration?.placeholder ?? null });
+      } else {
+        policies.push({ ...ref, kind: "withhold", reason: decision.reason });
+      }
+    }
+  }
+  return policies;
+}
+
+/** The task's one note about the keys it does not get, or null when it gets
+ *  every one. Names and reasons only, never a value. */
+export function taskEnvWithheldNote(policies: readonly TaskEnvKeyPolicy[]): string | null {
+  const withheld = policies.filter(
+    (policy): policy is Extract<TaskEnvKeyPolicy, { kind: "withhold" }> => policy.kind === "withhold",
+  );
+  if (withheld.length === 0) return null;
+  const lines = withheld.map((policy) => `${policy.key} (${projectEnvWithheldReason(policy.reason)})`);
+  return (
+    `Uai is withholding ${withheld.length === 1 ? "an env var" : `${withheld.length} env vars`} from this task: ` +
+    `${lines.join(", ")}. The repository's Settings → Environment says more, and is where a waiting key is approved.`
+  );
+}
+
+/**
+ * One consistent read of a task's projects from the runner's store: the
+ * records the decisions come from, and the values they name. The runner
+ * renders /env and the proxy reads a value only through one snapshot, so a
+ * decision is never paired with another generation's value or binding.
+ */
+export interface TaskEnvSnapshot {
+  projects: readonly TaskEnvProject[];
+  /** The value of a key's live row in this snapshot, only if that row is at
+   *  exactly this head; null otherwise. */
+  valueAt(projectId: string, key: string, head: TaskEnvHead): string | null;
+}
+
+/** What a task's /env and its proxy get from one snapshot. */
+export interface TaskEnvView {
+  /** Delivered keys, each with its value at the decision's head. */
+  values: Readonly<Record<string, string>>;
+  /** Every key the task does not get as its value: proxied and withheld. */
+  notDelivered: readonly string[];
+  /** Proxied keys, each with the value the proxy injects. */
+  proxied: ReadonlyArray<Extract<TaskEnvKeyPolicy, { kind: "proxy" }> & { value: string }>;
+  /** The decisions themselves, for the task's note. */
+  policies: readonly TaskEnvKeyPolicy[];
+}
+
+/** The task's view of one snapshot. A delivered or proxied key whose value is
+ *  not at its decision's head in that same snapshot is not delivered. */
+export function taskEnvView(snapshot: TaskEnvSnapshot): TaskEnvView {
+  const policies = taskEnvKeyPolicies(snapshot.projects);
+  const values: Record<string, string> = Object.create(null) as Record<string, string>;
+  const notDelivered: string[] = [];
+  const proxied: Array<Extract<TaskEnvKeyPolicy, { kind: "proxy" }> & { value: string }> = [];
+  for (const policy of policies) {
+    if (policy.kind === "withhold") {
+      notDelivered.push(policy.key);
+      continue;
+    }
+    const value = snapshot.valueAt(policy.projectId, policy.key, policy.head);
+    if (policy.kind === "deliver" && typeof value === "string") {
+      values[policy.key] = value;
+      continue;
+    }
+    notDelivered.push(policy.key);
+    if (policy.kind === "proxy" && typeof value === "string") proxied.push({ ...policy, value });
+  }
+  return { values, notDelivered, proxied, policies };
+}