@runuai/host 0.9.45 → 0.9.47

package/lib/release-trust.ts

@@ -17,12 +17,29 @@ export const STABLE_RELEASE_MANIFEST_URL =
  * Provisioning a key is necessary but not sufficient to advertise or serve
  * the one-line installer. The release coordinator flips this only in the same
  * reviewed change that publishes the complete, version-matched four-platform
- * release. Keeping it false while this stack is under review makes accidental
- * key/feed provisioning fail closed.
+ * release. Flipped 2026-08-19 in the change that provisioned
+ * `uai-release-2026-a` and wired auto-release to sign and publish the
+ * four-platform feed on every host version bump.
  */
-export const HOST_INSTALLER_RELEASE_PROMOTED = false;
+export const HOST_INSTALLER_RELEASE_PROMOTED = true;
 
+/**
+ * `uai-release-2026-a`: minted by the operator 2026-08-19 (Ed25519; private
+ * key lives in Infisical and reaches CI as UAI_RELEASE_SIGNING_KEY). Rotation
+ * is additive: pin the successor key beside this one, publish releases signed
+ * by it, and retire this entry only after every supported host updated past
+ * a release that pins both.
+ */
 export const PINNED_RELEASE_MANIFEST_KEYS: ReadonlyMap<
   string,
   PinnedReleaseManifestKey
-> = new Map();
+> = new Map([
+  [
+    "uai-release-2026-a",
+    {
+      publicKey: `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAeCBzaLTNYNGkI59T+vNu2M/DMTeTsmfABDtwN9IDejY=
+-----END PUBLIC KEY-----`,
+    },
+  ],
+]);

package/lib/standard-image-pin.ts

@@ -0,0 +1,159 @@
+/**
+ * ADR-114: the standard image is prebuilt in CI and pulled by digest.
+ *
+ * This module is the shared identity/grammar core, deliberately free of any
+ * host runtime import so the release-side identity script and the unit tests
+ * can load it without dragging the container-runtime graph along. Everything
+ * here is consumed from three places:
+ *
+ *   - CI (`host-agent/scripts/release/standard-image-identity.ts`) computes
+ *     the superset context hash and the registry tag to build/push.
+ *   - Release packaging (`scripts/host-runtime/stage.mjs`) embeds a validated
+ *     pin file in the signed payload (its .mjs copy of the grammar cites this
+ *     module as authoritative).
+ *   - The host (`standard-image.ts`) reads the packaged pin and pulls by
+ *     digest instead of building, falling back to the local build.
+ */
+
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Image label carrying the build-context content hash (rebuild trigger). */
+export const CONTEXT_HASH_LABEL = "com.runuai.context-hash";
+
+/** The public registry repository CI publishes the prebuilt image to. */
+export const STANDARD_IMAGE_RELEASE_REF = "ghcr.io/runuai/uai-standard";
+
+/** Pin file basename; packaged at `agent/images/<basename>` in the payload,
+ * one directory above the build context so it never perturbs the hash. */
+export const STANDARD_IMAGE_PIN_BASENAME = "standard-image.pin.json";
+
+/**
+ * The prebuilt image is the SUPERSET: every optional engine baked in. The
+ * layers are additive and non-fatal, a disabled engine is simply never
+ * invoked, and superset-vs-config means one published image serves every
+ * host — and toggling an engine on stops forcing a host-side rebuild.
+ */
+export const STANDARD_IMAGE_SUPERSET_EXTRA =
+  "kimi=1;grok=1;cursor=1;opencode=1";
+
+export const STANDARD_IMAGE_SUPERSET_BUILD_ARGS: readonly string[] = [
+  "INSTALL_KIMI=1",
+  "INSTALL_GROK=1",
+  "INSTALL_CURSOR=1",
+  "INSTALL_OPENCODE=1",
+];
+
+export interface StandardImagePin {
+  readonly ref: string;
+  readonly digest: string;
+  readonly contextHash: string;
+}
+
+// The pin arrives inside a signature-verified payload; this grammar is
+// defense-in-depth so no parsed field can smuggle registry ports, tags,
+// or shell-significant bytes into an engine command line.
+const REF_PATTERN = /^[a-z0-9]+(?:[a-z0-9._-]*[a-z0-9])?(?:\/[a-z0-9]+(?:[a-z0-9._-]*[a-z0-9])?)+$/;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const CONTEXT_HASH_PATTERN = /^[a-f0-9]{32}$/;
+
+/** Strict parse of a pin document; null on ANY deviation. */
+export function parseStandardImagePin(raw: string): StandardImagePin | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const { ref, digest, contextHash } = parsed as Record<string, unknown>;
+  if (
+    typeof ref !== "string" ||
+    typeof digest !== "string" ||
+    typeof contextHash !== "string" ||
+    !REF_PATTERN.test(ref) ||
+    !DIGEST_PATTERN.test(digest) ||
+    !CONTEXT_HASH_PATTERN.test(contextHash)
+  ) {
+    return null;
+  }
+  return { ref, digest, contextHash };
+}
+
+/** The exact engine argv for pulling and tagging the pinned image. Docker
+ * and the Apple `container` CLI differ only in the `image` subcommand prefix. */
+export function standardImagePullCommands(
+  pin: StandardImagePin,
+  targetTag: string,
+  apple: boolean,
+): { pull: string[]; tag: string[] } {
+  const source = `${pin.ref}@${pin.digest}`;
+  return apple
+    ? {
+        pull: ["image", "pull", source],
+        tag: ["image", "tag", source, targetTag],
+      }
+    : { pull: ["pull", source], tag: ["tag", source, targetTag] };
+}
+
+/**
+ * Content-hash a standard-image build context: every file under the context
+ * dir, sorted by relative path, plus an `extra` string carrying the build-arg
+ * configuration (part of the image identity). Null when the context can't be
+ * read — callers keep whatever image exists.
+ */
+export async function hashStandardImageContext(
+  contextDir: string,
+  extra = "",
+): Promise<string | null> {
+  try {
+    const files: string[] = [];
+    const walk = async (dir: string, prefix: string): Promise<void> => {
+      for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) await walk(join(dir, entry.name), rel);
+        else files.push(rel);
+      }
+    };
+    await walk(contextDir, "");
+    files.sort();
+    const hash = createHash("sha256");
+    for (const rel of files) {
+      hash.update(rel);
+      hash.update("\0");
+      hash.update(await readFile(join(contextDir, rel)));
+      hash.update("\0");
+    }
+    hash.update(extra);
+    hash.update("\0");
+    return hash.digest("hex").slice(0, 32);
+  } catch {
+    return null;
+  }
+}
+
+/** Everything CI needs to build/push/pin one release image, or null when the
+ * context is unreadable (a broken checkout must fail the release loudly). */
+export async function standardImageReleaseIdentity(
+  contextDir: string,
+): Promise<{
+  ref: string;
+  tag: string;
+  contextHash: string;
+  label: string;
+  buildArgs: readonly string[];
+} | null> {
+  const contextHash = await hashStandardImageContext(
+    contextDir,
+    STANDARD_IMAGE_SUPERSET_EXTRA,
+  );
+  if (contextHash === null) return null;
+  return {
+    ref: STANDARD_IMAGE_RELEASE_REF,
+    tag: `ctx-${contextHash}`,
+    contextHash,
+    label: `${CONTEXT_HASH_LABEL}=${contextHash}`,
+    buildArgs: STANDARD_IMAGE_SUPERSET_BUILD_ARGS,
+  };
+}

package/lib/standard-image.ts

@@ -17,9 +17,8 @@
  */
 
 import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
 import { readFileSync, writeFileSync } from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -36,6 +35,14 @@ import {
   pinnedContainerRuntimeProvider,
 } from "./container-runtime";
 import { KeyedPromiseTail } from "./keyed-promise-tail";
+import {
+  CONTEXT_HASH_LABEL,
+  hashStandardImageContext,
+  parseStandardImagePin,
+  STANDARD_IMAGE_PIN_BASENAME,
+  type StandardImagePin,
+  standardImagePullCommands,
+} from "./standard-image-pin";
 
 /** Pinned, host-wide constants (must match task-up.sh and the compose gen). */
 export const STANDARD_IMAGE_TAG = "uai-standard:dev";
@@ -90,14 +97,6 @@ export function standardRuntimes(): Array<{
   }));
 }
 
-/** Image label carrying the build-context content hash (rebuild trigger). */
-const CONTEXT_HASH_LABEL = "com.runuai.context-hash";
-
-/**
- * Content-hash the build context (every file under images/standard, sorted
- * by relative path). Null when the context can't be read — the caller then
- * keeps whatever image exists.
- */
 /**
  * Which OPTIONAL agent CLIs the operator has actually configured — so the
  * image installs only those, not every engine on every host. Delegates to
@@ -130,34 +129,36 @@ function optionalEngineConfigurationKey(
   return JSON.stringify(engines);
 }
 
-async function hashBuildContext(extra = ""): Promise<string | null> {
+// Build args (which optional engines are installed) are part of the image
+// identity — a config change must invalidate the label so it rebuilds. The
+// walk-and-hash itself lives in standard-image-pin.ts so CI computes the
+// identical identity (ADR-114).
+function hashBuildContext(extra = ""): Promise<string | null> {
+  return hashStandardImageContext(standardImageDir(), extra);
+}
+
+/** The packaged digest pin (ADR-114) at `agent/images/standard-image.pin.json`,
+ * one level above the build context so it never perturbs the context hash.
+ * Absent in dev checkouts and npm installs — those keep the local build.
+ * `UAI_IMAGE_PULL=0` is the operator kill switch back to local semantics. */
+async function readStandardImagePin(): Promise<StandardImagePin | null> {
+  if (process.env.UAI_IMAGE_PULL === "0") return null;
+  let raw: string;
   try {
-    const root = standardImageDir();
-    const files: string[] = [];
-    const walk = async (dir: string, prefix: string): Promise<void> => {
-      for (const entry of await readdir(dir, { withFileTypes: true })) {
-        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) await walk(join(dir, entry.name), rel);
-        else files.push(rel);
-      }
-    };
-    await walk(root, "");
-    files.sort();
-    const hash = createHash("sha256");
-    for (const rel of files) {
-      hash.update(rel);
-      hash.update("\0");
-      hash.update(await readFile(join(root, rel)));
-      hash.update("\0");
-    }
-    // Build args (which optional engines are installed) are part of the image
-    // identity — a config change must invalidate the label so it rebuilds.
-    hash.update(extra);
-    hash.update("\0");
-    return hash.digest("hex").slice(0, 32);
+    raw = await readFile(
+      resolve(standardImageDir(), "..", STANDARD_IMAGE_PIN_BASENAME),
+      "utf8",
+    );
   } catch {
     return null;
   }
+  const pin = parseStandardImagePin(raw);
+  if (pin === null) {
+    console.warn(
+      "[host-agent] packaged standard-image pin is malformed; using the local build path",
+    );
+  }
+  return pin;
 }
 
 /** Absolute path to the standard image build context. */
@@ -201,7 +202,18 @@ interface RunResult {
 
 const SHORT_DOCKER_TIMEOUT_MS = 30_000;
 const CLI_MAINTENANCE_TIMEOUT_MS = 10 * 60_000;
-const IMAGE_BUILD_TIMEOUT_MS = 15 * 60_000;
+// Overridable ceiling: the hard-coded 15 minutes looped a fanless Air forever
+// (live 2026-08-19 — every attempt died at 15:00 and the activation driver
+// silently restarted it). Slow hardware needs a bigger window, not a loop.
+const IMAGE_BUILD_TIMEOUT_MS = imageBuildTimeoutMs();
+function imageBuildTimeoutMs(): number {
+  const minutes = Number(process.env.UAI_IMAGE_BUILD_TIMEOUT_MINUTES ?? "");
+  if (Number.isFinite(minutes) && minutes >= 1) {
+    return Math.min(minutes, 240) * 60_000;
+  }
+  return 15 * 60_000;
+}
+const IMAGE_PULL_TIMEOUT_MS = 15 * 60_000;
 const TERMINATE_GRACE_MS = 5_000;
 export const ASDF_MAINTENANCE_LOCK_PATH =
   "/opt/asdf-data/.uai-maintenance.lock";
@@ -1233,7 +1245,58 @@ async function ensureStandardImageInner(
     };
   }
   if (inspect.code !== 0) labeledHash = null;
-  if (inspect.code === 0 && contextHash !== null && labeledHash === contextHash) {
+
+  // ADR-114: when the payload pins a prebuilt digest, the pin decides image
+  // identity — the label must equal the PIN's context hash (the CI superset
+  // hash, not this host's per-config hash, which would disagree by design
+  // and rebuild forever). Any pull-path failure falls through to the local
+  // build below, so offline and registry-down hosts behave exactly as today.
+  const pin = await readStandardImagePin();
+  if (pin !== null) {
+    if (inspect.code === 0 && labeledHash === pin.contextHash) {
+      console.log(
+        `[host-agent] standard image ${STANDARD_IMAGE_TAG} current (pinned)`,
+      );
+      imageReady = true;
+    } else {
+      console.log(
+        `[host-agent] pulling standard image ${pin.ref}@${pin.digest}`,
+      );
+      const commands = standardImagePullCommands(
+        pin,
+        STANDARD_IMAGE_TAG,
+        engine.apple,
+      );
+      const pulled = await run(
+        engine.command,
+        commands.pull,
+        IMAGE_PULL_TIMEOUT_MS,
+      );
+      if (pulled.code === 0) {
+        const tagged = await run(engine.command, commands.tag);
+        if (tagged.code === 0) {
+          console.log(
+            `[host-agent] pulled standard image ${STANDARD_IMAGE_TAG} (${pin.digest.slice(0, 19)}…)`,
+          );
+          imageReady = true;
+        } else {
+          console.warn(
+            "[host-agent] pulled standard image could not be tagged; " +
+              `falling back to a local build. ${tagged.stderr.trim()}`,
+          );
+        }
+      } else {
+        console.warn(
+          "[host-agent] standard image pull failed; falling back to a " +
+            `local build. ${pulled.stderr.trim()}`,
+        );
+      }
+    }
+  }
+
+  if (imageReady) {
+    // Pinned image adopted — skip the local-hash decision entirely.
+  } else if (inspect.code === 0 && contextHash !== null && labeledHash === contextHash) {
     console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} current`);
     imageReady = true;
   } else if (inspect.code === 0 && contextHash === null) {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.45",
-  "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
+  "version": "0.9.47",
+  "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
-  "author": "Diogo Perillo <diogo.perillo@gmail.com>",
+  "author": "Uai Tech <team@runuai.com>",
   "homepage": "https://github.com/runuai/uai#readme",
   "repository": {
     "type": "git",