@runuai/host 0.9.148 → 0.9.150

package/lib/secrets-proxy/scrub.ts

@@ -0,0 +1,559 @@
+/**
+ * Response scrubbing for the secrets proxy (ADR-153 §3, rule 7).
+ *
+ * Once a request carried a real value, anything the upstream sends back may
+ * echo it: an error message quoting the key, an echo endpoint, a redirect URL.
+ * Every header and body byte of that response is scanned and each value is
+ * replaced by its placeholder before the task sees it.
+ *
+ * A value is matched character by character, and each character in every
+ * form an upstream writes it in: raw (UTF-8); percent-encoded, in either
+ * case, so encodeURIComponent, RFC 3986, form encoding and every partial or
+ * mixed style are one rule rather than a list of library quirks; `+` for a
+ * space; and the JSON escapes (`\/`, `\"`, `\\`, `\n` and friends, `\uXXXX`
+ * in either case, surrogate pairs above the BMP). A replacement is written
+ * in the style of what it replaces, so a placeholder lands percent-encoded
+ * in a URL and raw in a body.
+ *
+ * Matching is leftmost-longest over raw bytes, whatever the MIME type, and
+ * streaming gives byte-for-byte the same result as scrubbing the whole body
+ * at once. A stream holds back only from the earliest position where a
+ * match could still be completing, so an SSE event that cannot be the start
+ * of a value is never delayed.
+ *
+ * A guard re-checks every output chunk (with enough of the previous output
+ * to catch a value straddling the boundary) before it is released.
+ * Replacement alone cannot always guarantee a value is gone — a very short
+ * value can occur inside its own placeholder — and in that case the
+ * response fails (502, or a torn-down stream) rather than going out.
+ */
+
+import { Transform, type TransformCallback } from "node:stream";
+
+const EMPTY = Buffer.alloc(0);
+
+/** One value to find (`from`, decoded) and what replaces it (`to`, raw). */
+export interface ScrubRule {
+  readonly from: string;
+  readonly to: string;
+}
+
+export interface InjectedValue {
+  readonly value: string;
+  readonly placeholder: string;
+}
+
+export class ScrubError extends Error {
+  constructor(
+    readonly code: "value_survived" | "too_large" | "too_complex",
+    message: string,
+  ) {
+    super(message);
+    this.name = "ScrubError";
+  }
+}
+
+/**
+ * The rules for one request: every injected value back to its placeholder,
+ * plus caller-built pairs such as a re-encoded Basic credential. Empty values
+ * are skipped (there is nothing to find), and when two keys share a value the
+ * first placeholder wins.
+ */
+export function scrubRules(
+  injected: readonly InjectedValue[],
+  extra: ReadonlyArray<{ from: string; to: string }> = [],
+): ScrubRule[] {
+  const rules = new Map<string, ScrubRule>();
+  const add = (from: string, to: string): void => {
+    if (from.length === 0 || rules.has(from)) return;
+    rules.set(from, { from, to });
+  };
+  for (const { value, placeholder } of injected) add(value, placeholder);
+  for (const { from, to } of extra) add(from, to);
+  return [...rules.values()];
+}
+
+// --- compiled rules -----------------------------------------------------------
+
+/** One position of an alternative: the bytes accepted there. */
+type ByteChoice = readonly number[];
+
+type Form = "raw" | "percent" | "plus" | "json";
+
+interface Alternative {
+  readonly form: Form;
+  readonly bytes: readonly ByteChoice[];
+}
+
+/** How a match was written, so its replacement is written the same way. */
+interface Style {
+  percent: boolean;
+  /** The case of the first hex letter seen in an escape, if any was. */
+  hexCase: "upper" | "lower" | null;
+  jsonSlash: boolean;
+}
+
+interface CompiledRule {
+  readonly to: string;
+  /** One unit per character of the value; each unit lists the forms that
+   *  character may take. */
+  readonly units: ReadonlyArray<readonly Alternative[]>;
+  readonly firstBytes: ReadonlySet<number>;
+  readonly maxEncodedLength: number;
+}
+
+const HEX = "0123456789ABCDEF";
+
+function exact(text: string): ByteChoice[] {
+  return [...Buffer.from(text, "latin1")].map((byte) => [byte]);
+}
+
+/** A hex digit in either case. */
+function hexDigit(nibble: number): ByteChoice {
+  const upper = HEX.charCodeAt(nibble);
+  const lower = HEX.toLowerCase().charCodeAt(nibble);
+  return upper === lower ? [upper] : [upper, lower];
+}
+
+function percentOf(byte: number): ByteChoice[] {
+  return [[0x25], hexDigit(byte >> 4), hexDigit(byte & 0x0f)];
+}
+
+function unicodeEscape(codeUnit: number): ByteChoice[] {
+  return [[0x5c], [0x75], hexDigit((codeUnit >> 12) & 0xf), hexDigit((codeUnit >> 8) & 0xf), hexDigit((codeUnit >> 4) & 0xf), hexDigit(codeUnit & 0xf)];
+}
+
+const JSON_SHORT: Readonly<Record<string, string>> = {
+  '"': '\\"',
+  "\\": "\\\\",
+  "/": "\\/",
+  "\b": "\\b",
+  "\f": "\\f",
+  "\n": "\\n",
+  "\r": "\\r",
+  "\t": "\\t",
+};
+
+function alternativesFor(character: string): Alternative[] {
+  const utf8 = [...Buffer.from(character, "utf8")];
+  const alternatives: Alternative[] = [
+    { form: "raw", bytes: utf8.map((byte) => [byte]) },
+    { form: "percent", bytes: utf8.flatMap(percentOf) },
+  ];
+  if (character === " ") alternatives.push({ form: "plus", bytes: [[0x2b]] });
+  const short = JSON_SHORT[character];
+  if (short !== undefined) alternatives.push({ form: "json", bytes: exact(short) });
+  const units: number[] = [];
+  for (let index = 0; index < character.length; index += 1) units.push(character.charCodeAt(index));
+  alternatives.push({ form: "json", bytes: units.flatMap(unicodeEscape) });
+  return alternatives;
+}
+
+function compile(rule: ScrubRule): CompiledRule {
+  const units = [...rule.from].map(alternativesFor);
+  const firstBytes = new Set<number>();
+  for (const alternative of units[0] ?? []) for (const byte of alternative.bytes[0] ?? []) firstBytes.add(byte);
+  const maxEncodedLength = units.reduce(
+    (total, alternatives) => total + Math.max(...alternatives.map((alternative) => alternative.bytes.length)),
+    0,
+  );
+  return { to: rule.to, units, firstBytes, maxEncodedLength };
+}
+
+/** Rules compiled once, then shared by every scrubber and guard one response
+ *  needs. */
+export class PreparedRules {
+  readonly rules: readonly CompiledRule[];
+  readonly firstBytes: ReadonlySet<number>;
+  /** The longest form any value can take: the guard's look-behind. */
+  readonly maxEncodedLength: number;
+
+  constructor(rules: readonly ScrubRule[]) {
+    this.rules = rules.filter((rule) => rule.from.length > 0).map(compile);
+    const firstBytes = new Set<number>();
+    for (const rule of this.rules) for (const byte of rule.firstBytes) firstBytes.add(byte);
+    this.firstBytes = firstBytes;
+    this.maxEncodedLength = Math.max(0, ...this.rules.map((rule) => rule.maxEncodedLength));
+  }
+}
+
+function prepared(rules: readonly ScrubRule[] | PreparedRules): PreparedRules {
+  return rules instanceof PreparedRules ? rules : new PreparedRules(rules);
+}
+
+interface MatchResult {
+  /** End of the longest complete match from the start, or -1. */
+  end: number;
+  style: Style | null;
+  /** Some way of matching ran out of input: more bytes might still make a
+   *  (longer) match here. */
+  partial: boolean;
+}
+
+/** Work allowed for one scan, counted in (state × alternative) steps and
+ *  proportional to the bytes scanned. Realistic values cost a handful of
+ *  steps per byte — every value has a JSON `\uXXXX` form, so each backslash
+ *  in a body is a candidate that dies a byte later. An adversarial pairing
+ *  (a value full of backslashes against a body full of them) costs steps
+ *  quadratic in the value's length per byte and runs out instead; running
+ *  out fails the response closed. */
+const SCRUB_STEPS_PER_BYTE = 64;
+const SCRUB_MIN_STEPS = 1_000_000;
+
+
+
+/** A stream's allowance: a floor once, then SCRUB_STEPS_PER_BYTE for every
+ *  byte that arrives. It never resets per chunk, so an upstream that dribbles
+ *  a body one byte at a time — each push rescanning the held-back tail —
+ *  cannot buy itself a fresh floor per byte. */
+class Budget {
+  private remaining = SCRUB_MIN_STEPS;
+  accrue(bytes: number): void {
+    this.remaining += SCRUB_STEPS_PER_BYTE * bytes;
+  }
+  spend(steps: number): void {
+    this.remaining -= steps;
+    if (this.remaining < 0) throw new ScrubError("too_complex", "the response is too costly to scrub");
+  }
+}
+
+/**
+ * Every way `rule` can match `input` from `start`, evaluated unit by unit
+ * over the set of input offsets reachable so far — iterative, so a long value
+ * cannot exhaust the stack, and deduplicated by offset, so values
+ * whose characters have overlapping forms (`\` raw or `\\` escaped) cost
+ * polynomially, never exponentially. The budget bounds what remains.
+ */
+function matchAt(rule: CompiledRule, input: Buffer, start: number, budget: Budget): MatchResult {
+  const result: MatchResult = { end: -1, style: null, partial: false };
+  // Offset → the style of the first way found to reach it. Style only shapes
+  // the replacement, so one per offset is enough, and keying by offset alone
+  // keeps the frontier no larger than the bytes a unit can span.
+  let frontier = new Map<number, Style>([[start, { percent: false, hexCase: null, jsonSlash: false }]]);
+  for (const alternatives of rule.units) {
+    const next = new Map<number, Style>();
+    for (const [at, style] of frontier) {
+      budget.spend(alternatives.length);
+      if (at === input.length) {
+        result.partial = true;
+        continue;
+      }
+      for (const alternative of alternatives) {
+        let position = at;
+        let matched = true;
+        for (const choice of alternative.bytes) {
+          if (position === input.length) {
+            result.partial = true;
+            matched = false;
+            break;
+          }
+          if (!choice.includes(input[position] ?? -1)) {
+            matched = false;
+            break;
+          }
+          position += 1;
+        }
+        if (!matched) continue;
+        const nextStyle: Style = { ...style };
+        if (alternative.form === "percent") {
+          nextStyle.percent = true;
+          // The first escape with a hex letter decides the replacement's case.
+          if (nextStyle.hexCase === null) {
+            const hex = input.subarray(at, position).toString("latin1");
+            if (/[a-f]/.test(hex)) nextStyle.hexCase = "lower";
+            else if (/[A-F]/.test(hex)) nextStyle.hexCase = "upper";
+          }
+        }
+        if (alternative.form === "json" && input[at + 1] === 0x2f) nextStyle.jsonSlash = true;
+        if (!next.has(position)) next.set(position, nextStyle);
+      }
+    }
+    frontier = next;
+    if (frontier.size === 0) return result;
+  }
+  for (const [at, style] of frontier) {
+    if (at > result.end) {
+      result.end = at;
+      result.style = style;
+    }
+  }
+  return result;
+}
+
+const UNRESERVED = /^[A-Za-z0-9._~-]$/;
+
+/** The replacement, written the way the match was. */
+function encodeLike(to: string, style: Style | null): Buffer {
+  if (style === null || (!style.percent && !style.jsonSlash)) return Buffer.from(to, "utf8");
+  let output = "";
+  for (const character of to) {
+    if (UNRESERVED.test(character)) {
+      output += character;
+    } else if (style.percent) {
+      for (const byte of Buffer.from(character, "utf8")) {
+        const hex = byte.toString(16).padStart(2, "0");
+        output += `%${style.hexCase === "lower" ? hex : hex.toUpperCase()}`;
+      }
+    } else if (character === "/") {
+      output += "\\/";
+    } else {
+      output += character;
+    }
+  }
+  return Buffer.from(output, "utf8");
+}
+
+/** Leftmost-longest streaming replacer. `push` returns what is safe to emit;
+ *  `end` releases the held-back tail. */
+export class Scrubber {
+  private readonly prepared: PreparedRules;
+  private readonly budget = new Budget();
+  private carry: Buffer = EMPTY;
+
+  constructor(rules: readonly ScrubRule[] | PreparedRules) {
+    this.prepared = prepared(rules);
+  }
+
+  push(chunk: Buffer): Buffer {
+    this.budget.accrue(chunk.length);
+    const input = this.carry.length === 0 ? chunk : Buffer.concat([this.carry, chunk]);
+    const { output, held } = this.scan(input, false);
+    // Copy: `held` is a view that would pin the whole input buffer.
+    this.carry = held.length === 0 ? EMPTY : Buffer.from(held);
+    return output;
+  }
+
+  end(): Buffer {
+    const { output } = this.scan(this.carry, true);
+    this.carry = EMPTY;
+    return output;
+  }
+
+  private scan(input: Buffer, final: boolean): { output: Buffer; held: Buffer } {
+    const { rules, firstBytes } = this.prepared;
+    if (rules.length === 0) return { output: input, held: EMPTY };
+    const budget = this.budget;
+    // Every byte scanned (and copied in with the held-back tail) costs a step,
+    // so rescanning a tail is paid for, not free.
+    budget.spend(input.length);
+    const pieces: Buffer[] = [];
+    let cursor = 0;
+    let position = 0;
+    while (position < input.length) {
+      if (!firstBytes.has(input[position] ?? -1)) {
+        position += 1;
+        continue;
+      }
+      let best: { end: number; rule: CompiledRule; style: Style | null } | null = null;
+      let pending = false;
+      for (const rule of rules) {
+        if (!rule.firstBytes.has(input[position] ?? -1)) continue;
+        const match = matchAt(rule, input, position, budget);
+        if (match.partial && !final) pending = true;
+        if (match.end > position && (best === null || match.end > best.end)) {
+          best = { end: match.end, rule, style: match.style };
+        }
+      }
+      // A match still arriving here may beat (or extend) one already
+      // complete: everything from here waits for more bytes.
+      if (pending) break;
+      if (best !== null) {
+        pieces.push(input.subarray(cursor, position), encodeLike(best.rule.to, best.style));
+        cursor = best.end;
+        position = best.end;
+        continue;
+      }
+      position += 1;
+    }
+    pieces.push(input.subarray(cursor, position));
+    return {
+      output: pieces.length === 1 ? (pieces[0] ?? EMPTY) : Buffer.concat(pieces),
+      held: input.subarray(position),
+    };
+  }
+}
+
+/** Whether any rule matches completely anywhere in `input`, and the earliest
+ *  position from which a match could still be forming when more bytes
+ *  arrive (input.length when none). */
+function inspect(input: Buffer, ready: PreparedRules, budget: Budget): { found: boolean; pendingFrom: number } {
+  let pendingFrom = input.length;
+  for (let position = 0; position < input.length; position += 1) {
+    if (!ready.firstBytes.has(input[position] ?? -1)) continue;
+    for (const rule of ready.rules) {
+      if (!rule.firstBytes.has(input[position] ?? -1)) continue;
+      const match = matchAt(rule, input, position, budget);
+      if (match.end > position) return { found: true, pendingFrom };
+      if (match.partial && position < pendingFrom) pendingFrom = position;
+    }
+  }
+  return { found: false, pendingFrom };
+}
+
+/**
+ * Refuses output containing any value in any form, including across the
+ * boundary with what was already released. Stateful: it keeps only the suffix
+ * from which a value could still be forming — the scrubber's own hold-back
+ * rule — not a fixed look-behind, so released bytes that cannot begin a
+ * value are never scanned twice and a harmless stream costs a step a byte.
+ */
+class ScrubGuard {
+  private readonly ready: PreparedRules;
+  private readonly budget = new Budget();
+  private pending: Buffer = EMPTY;
+
+  constructor(rules: readonly ScrubRule[] | PreparedRules) {
+    this.ready = prepared(rules);
+  }
+
+  accepts(output: Buffer): boolean {
+    if (output.length === 0 || this.ready.rules.length === 0) return true;
+    const window = this.pending.length === 0 ? output : Buffer.concat([this.pending, output]);
+    this.budget.accrue(output.length);
+    let result: { found: boolean; pendingFrom: number };
+    try {
+      this.budget.spend(window.length);
+      result = inspect(window, this.ready, this.budget);
+    } catch {
+      // Could not prove the output clean: refuse it.
+      return false;
+    }
+    if (result.found) return false;
+    this.pending = result.pendingFrom >= window.length ? EMPTY : Buffer.from(window.subarray(result.pendingFrom));
+    return true;
+  }
+}
+
+/** Whole-buffer scrub; null when a value would survive (answer 502). */
+export function scrubBuffer(input: Buffer, rules: readonly ScrubRule[] | PreparedRules): Buffer | null {
+  const ready = prepared(rules);
+  try {
+    const scrubber = new Scrubber(ready);
+    const output = Buffer.concat([scrubber.push(input), scrubber.end()]);
+    return new ScrubGuard(ready).accepts(output) ? output : null;
+  } catch {
+    // A budget exhausted (or any matcher failure) is a scrub that did not
+    // happen: the caller answers 502, never the unscanned bytes.
+    return null;
+  }
+}
+
+/** Header and status-line scrub. Node hands header bytes over as latin1
+ *  strings, so a latin1 round trip compares the exact bytes on the wire.
+ *  Pass PreparedRules when scrubbing many headers of one response. */
+export function scrubHeaderText(text: string, rules: readonly ScrubRule[] | PreparedRules): string | null {
+  const output = scrubBuffer(Buffer.from(text, "latin1"), rules);
+  return output === null ? null : output.toString("latin1");
+}
+
+/** A stream scans once this many bytes have gathered, or after
+ *  COALESCE_MS, whichever comes first. Every scan rereads the held-back tail
+ *  and the guard's look-behind, so scanning per arriving chunk would let an
+ *  upstream that dribbles a body a byte at a time multiply the work by the
+ *  tail's length; gathering bounds scans by bytes and by time, at the cost
+ *  of at most COALESCE_MS of added latency on a stream of small events. */
+const COALESCE_BYTES = 4_096;
+const COALESCE_MS = 5;
+
+/**
+ * The streaming form. Errors with ScrubError when a value would survive, when
+ * scrubbing would cost more than the stream's allowance, or when more than
+ * `maxInputBytes` arrive (the bound on decoding a compressed body that was
+ * chosen for buffering).
+ */
+export function createScrubStream(
+  rules: readonly ScrubRule[] | PreparedRules,
+  options: { maxInputBytes?: number } = {},
+): Transform {
+  const ready = prepared(rules);
+  const scrubber = new Scrubber(ready);
+  const guard = new ScrubGuard(ready);
+  let seen = 0;
+  let gathered: Buffer[] = [];
+  let gatheredBytes = 0;
+  let timer: NodeJS.Timeout | null = null;
+
+  const stopTimer = (): void => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+  /** Scans what has gathered. Returns what may be released, or the error
+   *  that ends the stream. A throw never leaves here: inside _transform it
+   *  would escape the stream machinery and take the runner down. */
+  const scanGathered = (): Buffer | ScrubError => {
+    const input = gathered.length === 1 ? (gathered[0] ?? EMPTY) : Buffer.concat(gathered);
+    gathered = [];
+    gatheredBytes = 0;
+    let output: Buffer;
+    try {
+      output = scrubber.push(input);
+    } catch (error) {
+      return error instanceof ScrubError ? error : new ScrubError("too_complex", "scrubbing failed");
+    }
+    return guard.accepts(output) ? output : new ScrubError("value_survived", "a proxied value survived scrubbing");
+  };
+
+  const stream: Transform = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      seen += chunk.length;
+      if (options.maxInputBytes !== undefined && seen > options.maxInputBytes) {
+        stopTimer();
+        callback(new ScrubError("too_large", "body exceeds the scrub limit"));
+        return;
+      }
+      gathered.push(chunk);
+      gatheredBytes += chunk.length;
+      // Gathering acknowledges a write without pushing, and Node completes
+      // such a write at once even when the readable side is full; the timer's
+      // later push would then grow that buffer without bound behind a slow
+      // reader. Once the reader is behind, scan now through the callback,
+      // whose push lets Node hold the write — and the upstream — back.
+      const readerBehind = stream.readableLength >= stream.readableHighWaterMark;
+      if (gatheredBytes >= COALESCE_BYTES || readerBehind) {
+        stopTimer();
+        const result = scanGathered();
+        if (result instanceof ScrubError) callback(result);
+        else callback(null, result.length > 0 ? result : undefined);
+        return;
+      }
+      if (timer === null) {
+        timer = setTimeout(() => {
+          timer = null;
+          if (gatheredBytes === 0) return;
+          const result = scanGathered();
+          if (result instanceof ScrubError) stream.destroy(result);
+          else if (result.length > 0) stream.push(result);
+        }, COALESCE_MS);
+      }
+      callback();
+    },
+    flush(callback) {
+      stopTimer();
+      const result = gatheredBytes > 0 ? scanGathered() : EMPTY;
+      if (result instanceof ScrubError) {
+        callback(result);
+        return;
+      }
+      let tail: Buffer;
+      try {
+        tail = scrubber.end();
+      } catch (error) {
+        callback(error instanceof ScrubError ? error : new ScrubError("too_complex", "scrubbing failed"));
+        return;
+      }
+      if (!guard.accepts(tail)) {
+        callback(new ScrubError("value_survived", "a proxied value survived scrubbing"));
+        return;
+      }
+      if (result.length > 0) stream.push(result);
+      callback(null, tail.length > 0 ? tail : undefined);
+    },
+    destroy(error, callback) {
+      stopTimer();
+      callback(error);
+    },
+  });
+  return stream;
+}

package/lib/secrets-proxy/sidecar-view.ts

@@ -0,0 +1,139 @@
+/**
+ * Whether every process of a Uai Cloud machine's own task sees the task's
+ * hosts view (ADR-153 "Machines"), so its pins can count. Kept as a record
+ * per task rather than read off its processes: a process can sit in a mount
+ * namespace of its own and still see the machine's file, or hand itself off
+ * to a child mid-look, so no look at them proves they all see it.
+ *
+ * Only a fresh admission proves a task: task-up for a task with no row yet,
+ * so that nothing of it can have run before, recorded before its row and so
+ * before its first process. The task stays proven in that boot and every
+ * boot after. A task with a row and no record (a runner without the view
+ * started it, whether or not it ever came up) is held instead: its
+ * processes may run outside the view until its machine boots again, which
+ * none of them survives.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { env } from "../env";
+import { isSafeHostTaskId } from "../task-identity";
+
+/** The kernel's boot ids are lowercase UUIDs; nothing else is one. */
+const BOOT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+interface ViewRecord {
+  /** A boot in which every process of the task came through the wrapper. */
+  readonly viewBoot?: string;
+  /** The boot in which the task was held: its processes may predate the view. */
+  readonly preViewBoot?: string;
+}
+
+export interface SidecarViewDeps {
+  bootId(): string;
+  /** The stored record, as parsed; null when there is none. */
+  read(taskId: string): unknown;
+  write(taskId: string, record: ViewRecord): void;
+}
+
+function recordPath(taskId: string): string {
+  if (!isSafeHostTaskId(taskId)) throw new Error("invalid host task identity");
+  return join(env.dataDir, "secrets-proxy", "task-views", `${taskId}.json`);
+}
+
+const defaults: SidecarViewDeps = {
+  bootId: () => readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim(),
+  read: (taskId) => {
+    try {
+      return JSON.parse(readFileSync(recordPath(taskId), "utf8")) as unknown;
+    } catch {
+      // Missing or unreadable: no record.
+      return null;
+    }
+  },
+  write: (taskId, record) => {
+    const path = recordPath(taskId);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(`${path}.tmp`, JSON.stringify(record), { mode: 0o600 });
+    renameSync(`${path}.tmp`, path);
+  },
+};
+
+let deps: SidecarViewDeps = defaults;
+
+/** Test seam: the boot id and the record store; what is left out keeps its
+ *  default. */
+export function setSidecarViewDeps(next: Partial<SidecarViewDeps> | null): void {
+  deps = next === null ? defaults : { ...defaults, ...next };
+}
+
+function remember(taskId: string, record: ViewRecord): void {
+  try {
+    deps.write(taskId, record);
+  } catch {
+    // Not kept: the next look decides again, from the same facts.
+  }
+}
+
+/** This boot's id; null when it cannot be read, or what is read is not one. */
+function currentBoot(): string | null {
+  try {
+    const boot = deps.bootId();
+    return BOOT_ID.test(boot) ? boot : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The task's record, if it is one this module writes: a single boot id
+ *  under one of its two names. Anything else counts as no record. */
+function recordOf(taskId: string): ViewRecord | null {
+  const stored = deps.read(taskId);
+  if (stored === null || typeof stored !== "object" || Array.isArray(stored)) return null;
+  const entries = Object.entries(stored);
+  if (entries.length !== 1) return null;
+  const [name, boot] = entries[0]!;
+  if (typeof boot !== "string" || !BOOT_ID.test(boot)) return null;
+  if (name === "viewBoot") return { viewBoot: boot };
+  if (name === "preViewBoot") return { preViewBoot: boot };
+  return null;
+}
+
+/**
+ * Task-up for a task with no row yet: nothing of it has run on this machine,
+ * so everything it runs from here comes through the wrapper. Called before
+ * task-up records the task, and so before its first process. Never lifts a
+ * hold in this boot, and records nothing without a boot id.
+ */
+export function admitFreshTaskView(taskId: string): void {
+  const boot = currentBoot();
+  if (boot === null) return;
+  if (recordOf(taskId)?.preViewBoot === boot) return;
+  remember(taskId, { viewBoot: boot });
+}
+
+/** Whether every process of the task sees its hosts view now. Never true on
+ *  a doubt: no boot id, or a task held in this boot. A task without a record
+ *  is held from here on, for this boot. */
+export function taskViewProven(taskId: string): boolean {
+  const boot = currentBoot();
+  if (boot === null) return false;
+  const record = recordOf(taskId);
+  if (record?.viewBoot !== undefined) {
+    // Admitted fresh in this boot, or rebooted since: every process running
+    // now came through the wrapper.
+    if (record.viewBoot !== boot) remember(taskId, { viewBoot: boot });
+    return true;
+  }
+  if (record?.preViewBoot !== undefined && record.preViewBoot !== boot) {
+    // Held in an earlier boot: none of those processes survived the reboot.
+    remember(taskId, { viewBoot: boot });
+    return true;
+  }
+  // Never admitted fresh: a runner without the view started the task, and
+  // its processes may still run. Remembered, so a runner restart in this
+  // boot does not forget it.
+  if (record?.preViewBoot !== boot) remember(taskId, { preViewBoot: boot });
+  return false;
+}