@moondeck/station 0.0.1 → 1.0.1

package/lib/runtime-authority.ts

@@ -0,0 +1,166 @@
+import type {
+  ProjectEnvMode,
+  ProjectEnvProfile,
+} from "./task-environment/types";
+
+/**
+ * Host-owned runtime/cache authority for every command launched in a task
+ * container. Admission and recovery separately prove the container's fixed
+ * Config.Env; these values are reasserted for each managed exec so a caller
+ * cannot accidentally omit the policy or inherit project-controlled values.
+ */
+export const RUNTIME_AUTHORITY_ENV: Readonly<Record<string, string>> =
+  Object.freeze({
+    // Shared, host-maintained shims stay ahead of task-installed commands so
+    // `npm install -g claude/codex/node` cannot replace Uai's proved tools.
+    // Packages with new command names remain available from the private
+    // container-layer prefix at the final component, after every trusted
+    // control directory.
+    PATH: "/opt/asdf-data/shims:/opt/asdf/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/node/.local/share/uai-npm/bin",
+    HOME: "/home/node",
+    XDG_CONFIG_HOME: "/home/node/.config",
+    XDG_DATA_HOME: "/home/node/.local/share",
+    XDG_CACHE_HOME: "/home/node/.cache",
+    ASDF_DIR: "/opt/asdf",
+    ASDF_DATA_DIR: "/opt/asdf-data",
+    ASDF_CONFIG_FILE: "/dev/null",
+    ASDF_DEFAULT_TOOL_VERSIONS_FILENAME: ".tool-versions",
+    ASDF_NODEJS_VERSION: "",
+    ASDF_PYTHON_VERSION: "",
+    ASDF_GOLANG_VERSION: "",
+    ASDF_RUBY_VERSION: "",
+    ASDF_RUST_VERSION: "",
+    // asdf-nodejs wraps global npm installs with an automatic reshim. Task
+    // mounts are intentionally read-only and private bins are already on PATH;
+    // only host maintenance may mutate shared shims.
+    ASDF_SKIP_RESHIM: "1",
+    // Corepack selections are completely prepared by host maintenance. Task
+    // contexts see this path only through the read-only shared volume.
+    COREPACK_HOME: "/opt/asdf-data/corepack",
+    COREPACK_DEFAULT_TO_LATEST: "0",
+    COREPACK_ENV_FILE: "0",
+    COREPACK_NPM_REGISTRY: "https://registry.npmjs.org",
+    COREPACK_ENABLE_NETWORK: "0",
+    COREPACK_ENABLE_AUTO_PIN: "0",
+    COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
+    COREPACK_ENABLE_PROJECT_SPEC: "1",
+    COREPACK_ENABLE_STRICT: "1",
+    COREPACK_ENABLE_UNSAFE_CUSTOM_URLS: "0",
+    COREPACK_INTEGRITY_CHECK: "1",
+    // npm treats npm_config_* names case-insensitively and lifecycle scripts
+    // often receive the lowercase spelling. Pin both to task-private storage
+    // so image/project environment cannot turn an ordinary global install
+    // into a shared-cache writer.
+    NPM_CONFIG_PREFIX: "/home/node/.local/share/uai-npm",
+    npm_config_prefix: "/home/node/.local/share/uai-npm",
+    NPM_CONFIG_CACHE: "/home/node/.cache/uai-npm",
+    npm_config_cache: "/home/node/.cache/uai-npm",
+    NPM_CONFIG_LOGS_DIR: "/home/node/.cache/uai-npm/_logs",
+    npm_config_logs_dir: "/home/node/.cache/uai-npm/_logs",
+    NPM_CONFIG_UMASK: "0002",
+    npm_config_umask: "0002",
+    LD_PRELOAD: "",
+    LD_AUDIT: "",
+    LD_LIBRARY_PATH: "",
+    NODE_OPTIONS: "",
+    NODE_PATH: "",
+    // SHELLOPTS/BASHOPTS deliberately absent: present-in-env (even empty)
+    // makes bash export its live options into children — the Editor-terminal
+    // nounset poisoning of 2026-08-16.
+    PS4: "",
+    BASH_ENV: "",
+    ENV: "",
+  });
+
+/**
+ * ADR-121: the MACHINE flavor of the authority env. A machine is a
+ * single-task trust domain — the container constants above defend SHARED
+ * host resources (the read-only asdf/corepack volume, uai-npm prefixes)
+ * that do not exist on a machine, and carrying them anyway pinned corepack
+ * to an unwritable /opt path with the network off, so `pnpm install`
+ * failed out of the box (live 2026-08-27, first EC2 task — the agent had
+ * to hand-repair its own environment). Keep the hygiene (loader/env
+ * clearing, prompt-free corepack), drop the container-topology pins.
+ */
+export const MACHINE_RUNTIME_AUTHORITY_ENV: Readonly<Record<string, string>> =
+  Object.freeze({
+    PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/node/.local/bin",
+    HOME: "/home/node",
+    XDG_CONFIG_HOME: "/home/node/.config",
+    XDG_DATA_HOME: "/home/node/.local/share",
+    XDG_CACHE_HOME: "/home/node/.cache",
+    COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
+    LD_PRELOAD: "",
+    LD_AUDIT: "",
+    LD_LIBRARY_PATH: "",
+    NODE_OPTIONS: "",
+    NODE_PATH: "",
+    PS4: "",
+    BASH_ENV: "",
+    ENV: "",
+  });
+
+/** Root-owned loader paths installed in every PR2+ task environment. */
+export const PROJECT_ENV_HOOK_PATH = "/usr/local/share/uai/env-hook.sh";
+export const PROJECT_ENV_EXEC_PATH = "/usr/local/bin/uai-env-exec";
+
+/** Names that must reach a provider-added outer shell as well as the payload. */
+export const PROJECT_ENV_PROFILE_ENV_NAMES = Object.freeze([
+  "BASH_ENV",
+  "SHELL",
+  "UAI_ENV_HOOK",
+] as const);
+
+/**
+ * Apply the caller's classified project-env policy at the final provider
+ * boundary. The overlay is deliberately last, so inherited/caller env cannot
+ * opt a maintenance command into the hook or replace the task login shell.
+ * Legacy baked environments are a rollout no-op: their image has no loader.
+ */
+export function applyProjectEnvProfile<
+  T extends {
+    projectEnvProfile: ProjectEnvProfile;
+    env?: Readonly<Record<string, string>>;
+  },
+>(
+  request: T,
+  envMode: ProjectEnvMode,
+  taskShell: "/usr/bin/zsh" | "/bin/bash",
+): T {
+  if (envMode === "baked") return request;
+  const profileEnv =
+    request.projectEnvProfile === "maintenance"
+      ? { BASH_ENV: "", UAI_ENV_HOOK: "0" }
+      : {
+          BASH_ENV: PROJECT_ENV_HOOK_PATH,
+          SHELL: taskShell,
+          UAI_ENV_HOOK: "1",
+        };
+  return { ...request, env: { ...request.env, ...profileEnv } };
+}
+
+/** Rewrite a session env assembled for a CONTAINER into its machine form:
+ * every container-authority key is dropped, then the machine authority is
+ * overlaid. Non-authority keys (engine credentials, task tokens, preview
+ * env) pass through untouched. */
+export function machineSessionAuthorityEnv(
+  env: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env ?? {})) {
+    if (key in RUNTIME_AUTHORITY_ENV) continue;
+    out[key] = value;
+  }
+  return { ...out, ...MACHINE_RUNTIME_AUTHORITY_ENV };
+}
+
+/** Docker `exec` options for the fixed authority environment. Callers append
+ * this after every less-trusted `-e` option and immediately before the
+ * container name. Container admission additionally rejects noncanonical
+ * case/underscore/hyphen aliases for npm's host-owned path settings. */
+export function runtimeAuthorityDockerExecArgs(): string[] {
+  return Object.entries(RUNTIME_AUTHORITY_ENV).flatMap(([key, value]) => [
+    "-e",
+    `${key}=${value}`,
+  ]);
+}

package/lib/runtime-guard.ts

@@ -0,0 +1,36 @@
+/**
+ * Process-wide, dependency-light admission seam for background work that can
+ * reach Docker without entering through HostCommands. It defaults open so
+ * isolated library tests and non-daemon embeddings preserve their historical
+ * behavior; main.ts installs the authoritative ADR-101 readiness predicate.
+ */
+let containersOperational = (): boolean => true;
+
+/**
+ * A typed failure for work that reached its last Docker boundary after the
+ * process-wide runtime verdict was invalidated. Callers that otherwise use a
+ * boolean for an ordinary domain result (notably GitHub's disconnected state)
+ * must be able to keep infrastructure unavailability distinct.
+ */
+export class ContainerRuntimeUnavailableError extends Error {
+  constructor(message = "container runtime is not operational") {
+    super(message);
+    this.name = "ContainerRuntimeUnavailableError";
+  }
+}
+
+export function setContainerRuntimeOperationalCheck(
+  check: () => boolean,
+): void {
+  containersOperational = check;
+}
+
+export function backgroundContainerWorkAllowed(): boolean {
+  return containersOperational();
+}
+
+export function requireContainerRuntimeOperational(): void {
+  if (!backgroundContainerWorkAllowed()) {
+    throw new ContainerRuntimeUnavailableError();
+  }
+}

package/lib/runtime-provider-state.ts

@@ -0,0 +1,169 @@
+/**
+ * Crash-safe identity for a container backend that may hold task state.
+ *
+ * The marker is deliberately monotonic. Once a bundled-runtime task can create
+ * a container, image, or volume, `auto` must not silently move the host back
+ * to an ambient Docker Desktop/OrbStack daemon on the next service restart. An
+ * explicit `UAI_RUNTIME=docker` remains the operator's switch.
+ */
+
+import { randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+export type StatefulRuntimeProvider = "apple-container";
+
+export interface RuntimeProviderState {
+  readonly schemaVersion: 1;
+  readonly statefulProvider: StatefulRuntimeProvider;
+  readonly claimedAt: number;
+}
+
+export interface RuntimeProviderStateStore {
+  read(): RuntimeProviderState | null | Promise<RuntimeProviderState | null>;
+  claim(
+    provider: StatefulRuntimeProvider,
+  ): RuntimeProviderState | Promise<RuntimeProviderState>;
+}
+
+export function runtimeProviderStatePath(dataDir: string): string {
+  return join(dataDir, "container-runtime-provider.json");
+}
+
+export function fileRuntimeProviderStateStore(
+  file: string,
+): RuntimeProviderStateStore {
+  return {
+    read: () => readRuntimeProviderState(file),
+    claim: (provider) => claimRuntimeProviderState(file, provider),
+  };
+}
+
+export function readRuntimeProviderState(
+  file: string,
+): RuntimeProviderState | null {
+  if (!existsSync(file)) return null;
+  const stat = lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error("container runtime provider state must be a regular file");
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    throw new Error("container runtime provider state is malformed");
+  }
+  return validateRuntimeProviderState(value);
+}
+
+/**
+ * Durably claim the first stateful fallback provider without an overwrite
+ * race. The marker is written before task provisioning can mutate that
+ * provider. A false-positive after an interrupted task-up is safe (and only
+ * makes `auto` conservative); a missing marker after VM state was created is
+ * not.
+ */
+export function claimRuntimeProviderState(
+  file: string,
+  provider: StatefulRuntimeProvider,
+): RuntimeProviderState {
+  const existing = readRuntimeProviderState(file);
+  if (existing) {
+    if (existing.statefulProvider !== provider) {
+      throw new Error("container runtime provider is already claimed");
+    }
+    return existing;
+  }
+
+  const state: RuntimeProviderState = {
+    schemaVersion: 1,
+    statefulProvider: provider,
+    claimedAt: Date.now(),
+  };
+  const parent = dirname(file);
+  mkdirSync(parent, { recursive: true, mode: 0o700 });
+  const temporary = join(
+    parent,
+    `.${basename(file)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`,
+  );
+  try {
+    writeDurableFile(temporary, `${JSON.stringify(state, null, 2)}\n`);
+    try {
+      linkSync(temporary, file);
+      fsyncDirectory(parent);
+      return state;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const winner = readRuntimeProviderState(file);
+      if (!winner) throw new Error("container runtime provider claim disappeared");
+      if (winner.statefulProvider !== provider) {
+        throw new Error("container runtime provider was claimed concurrently");
+      }
+      return winner;
+    }
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}
+
+function validateRuntimeProviderState(value: unknown): RuntimeProviderState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("container runtime provider state is malformed");
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    Object.keys(record).length !== 3 ||
+    record.schemaVersion !== 1 ||
+    record.statefulProvider !== "apple-container" ||
+    typeof record.claimedAt !== "number" ||
+    !Number.isSafeInteger(record.claimedAt) ||
+    record.claimedAt <= 0
+  ) {
+    throw new Error("container runtime provider state is malformed");
+  }
+  return {
+    schemaVersion: 1,
+    statefulProvider: "apple-container",
+    claimedAt: record.claimedAt,
+  };
+}
+
+function writeDurableFile(file: string, body: string): void {
+  const descriptor = openSync(file, "wx", 0o600);
+  try {
+    writeFileSync(descriptor, body, "utf8");
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  chmodSync(file, 0o600);
+}
+
+function fsyncDirectory(directory: string): void {
+  let descriptor: number | null = null;
+  try {
+    descriptor = openSync(directory, "r");
+    fsyncSync(descriptor);
+  } catch {
+    // Some filesystems do not expose directory fsync. The marker itself was
+    // still fsync'd before the atomic hard-link publication.
+  } finally {
+    if (descriptor !== null) closeSync(descriptor);
+  }
+}

package/lib/runtime-reconnect.ts

@@ -0,0 +1,86 @@
+/**
+ * A known-ready container runtime revalidated when the bridge reconnects: a
+ * healthy daemon can still have restarted while the bridge was offline. One
+ * label scan keeps ordinary cloud/network flaps cheap; only a missing,
+ * exited or unknowable active app takes the full per-task recovery.
+ *
+ * ADR-154: it runs on the credentials it began on, as an activation does
+ * (credentialsActivationFence). Off the runner's own before this process's
+ * credential sweep has succeeded, or once leaving them begins, it neither
+ * recovers nor publishes: it hands the runtime to the credentials-aware
+ * activation, which sweeps first. Off them after the sweep, its recovery
+ * goes through the credentials wrapper (the sweep already done).
+ */
+
+import {
+  cloudCredentialsSwept,
+  credentialsActivationFence,
+  onOwnCredentials,
+  recoverRuntimeOnCredentials,
+} from "./cloud-credential-host";
+
+export interface RuntimeReconnectDeps {
+  /** Suspends a ready runtime for revalidation; its epoch, or null. */
+  suspend(): number | null;
+  /** Probes the daemon again: ready or not. */
+  probe(): Promise<boolean>;
+  /** The readiness epoch is still this one, and the daemon ready. */
+  epochIsCurrent(epoch: number): boolean;
+  /** The epoch is current and the runner is not stopping. */
+  activationIsCurrent(epoch: number): boolean;
+  persistedEnvironmentsMatch(): Promise<boolean>;
+  recoveryVerdict(): Promise<"clean" | "needed" | "unknown">;
+  /** The orchestrator's per-task recovery. */
+  recover(isCurrent: () => boolean): Promise<boolean>;
+  /** A bounded activation retry for the epoch. */
+  scheduleRetry(epoch: number): void;
+  /** A full, credentials-aware activation pass for the epoch. */
+  requestActivation(epoch: number): void;
+  /** Marks the runtime operational for the epoch, resumes deferred agent
+   *  work and re-advertises; false when it could not be marked. */
+  publish(epoch: number): boolean;
+}
+
+export async function revalidateRuntimeOnConnect(deps: RuntimeReconnectDeps): Promise<void> {
+  const epoch = deps.suspend();
+  if (epoch === null) return;
+  const fence = credentialsActivationFence(() => deps.activationIsCurrent(epoch));
+  const handOver = (): void => {
+    if (deps.activationIsCurrent(epoch)) deps.requestActivation(epoch);
+  };
+  /** Not current any more: leaving the runner's own credentials hands the
+   *  runtime to the activation; a stale epoch ends here. */
+  const stopped = (): boolean => {
+    if (fence.isCurrent()) return false;
+    if (fence.leftLegacy()) handOver();
+    return true;
+  };
+  try {
+    if (!(await deps.probe()) || !deps.epochIsCurrent(epoch)) return;
+    if (!onOwnCredentials() && !cloudCredentialsSwept()) {
+      handOver();
+      return;
+    }
+    if (!(await deps.persistedEnvironmentsMatch())) return;
+    if (stopped()) return;
+    let recovered = (await deps.recoveryVerdict()) === "clean";
+    if (!recovered) {
+      recovered = await recoverRuntimeOnCredentials(deps.recover, () => fence.isCurrent());
+    }
+    if (stopped()) return;
+    // Prove the daemon once more after recovery so a mid-sweep loss cannot
+    // reopen commands and tunnels on an unresolved backend.
+    if (!(await deps.probe()) || !deps.epochIsCurrent(epoch)) return;
+    if (stopped()) return;
+    if (!recovered) {
+      deps.scheduleRetry(epoch);
+      return;
+    }
+    deps.publish(epoch);
+  } catch (error) {
+    console.warn(
+      `[host-agent] container runtime reconnect validation failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    if (deps.activationIsCurrent(epoch)) deps.scheduleRetry(epoch);
+  }
+}