@runuai/host 0.8.12 → 0.8.16

package/lib/codex-auth.ts

@@ -9,12 +9,24 @@
  * re-login otherwise only helps NEW tasks. This re-copies the fresh `~/.codex`
  * into the running task containers so live tasks self-heal.
  *
- * Two triggers, covering both re-login paths:
+ * Three triggers, covering every path:
  *   - {@link watchCodexAuth} — fs.watch on `~/.codex`, for `codex login` run
  *     from a terminal while the host stays up.
  *   - {@link reinjectCodexRunningTasks} at host start — for the desktop
  *     "Connect Codex" flow, which writes `~/.codex` then restarts the host
  *     (durable sessions reattach to containers that still hold the old creds).
+ *     Sequenced AFTER boot recovery (main.ts awaits recoveryComplete()).
+ *   - {@link injectCodexIntoContainer} — recovery calls it right after
+ *     `docker start` of an exited container, before agents can respawn.
+ *
+ * Copies go ONLY into containers docker confirms are RUNNING. A DB-active row
+ * can be a stopped container (boot, pre-recovery), and `docker cp` into a
+ * stopped container SUCCEEDS while the `docker exec … chown` that follows
+ * cannot run — stranding auth.json/config.toml mode 0600 owned by the host
+ * uid (macOS 501:20), unreadable to the container's `node` (1000:1000), and
+ * Codex dies at startup. Every docker step's exit status is checked; failures
+ * surface as actionable errors (never credential contents — only file NAMES
+ * and docker stderr are logged).
  *
  * Codex auth is host-wide (the operator's single `~/.codex`, not per-user), so
  * this targets ALL running tasks — matching task-up, which copies it into every
@@ -43,8 +55,11 @@ const EXEC_TIMEOUT_MS = 15_000;
 /** Injectable seams (defaults hit the real DB / docker / fs) so the copy logic
  *  is testable without either. */
 export interface CodexDeps {
-  exec?: (args: string[]) => Promise<{ status: number | null; stderr: string }>;
-  runningContainers?: () => string[];
+  exec?: (
+    args: string[],
+  ) => Promise<{ status: number | null; stdout: string; stderr: string }>;
+  /** DB-active task containers — may include stopped ones; docker decides. */
+  activeTaskContainers?: () => string[];
   fileExists?: (path: string) => boolean;
 }
 
@@ -54,10 +69,10 @@ function ownerCodexDir(): string {
 
 const defaultExec: NonNullable<CodexDeps["exec"]> = async (args) => {
   const res = await dockerCli(args, { timeoutMs: EXEC_TIMEOUT_MS });
-  return { status: res.status, stderr: res.stderr };
+  return { status: res.status, stdout: res.stdout, stderr: res.stderr };
 };
 
-function defaultRunningContainers(): string[] {
+function defaultActiveTaskContainers(): string[] {
   return getDb()
     .select({ taskId: schema.hostTasks.taskId })
     .from(schema.hostTasks)
@@ -66,50 +81,119 @@ function defaultRunningContainers(): string[] {
     .map((r) => `task-${r.taskId}-app-1`);
 }
 
+/**
+ * The containers docker reports as RUNNING right now, or null when docker
+ * itself didn't answer — the caller must then skip injection rather than
+ * docker-cp into containers of unknown state.
+ */
+async function dockerRunningNames(
+  exec: NonNullable<CodexDeps["exec"]>,
+): Promise<Set<string> | null> {
+  const res = await exec(["ps", "--filter", "status=running", "--format", "{{.Names}}"]);
+  if (res.status !== 0) return null;
+  return new Set(
+    res.stdout
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean),
+  );
+}
+
 /**
  * Re-copy `~/.codex/<items>` into one container — mirrors task-up.sh exactly:
- * ensure the dir (root), cp each item that exists, chown back to node. Best
- * effort; a stopped/removed container makes the exec fail and is caught by the
- * caller.
+ * ensure the dir (root), cp each item that exists, chown back to node:node
+ * (docker cp preserves the HOST uid/gid, and 0600 files owned by macOS
+ * 501:20 are unreadable to the container's node). Any nonzero step throws
+ * with the step name and docker's stderr — never file contents.
  */
 async function copyCodexInto(container: string, deps: CodexDeps): Promise<void> {
   const exec = deps.exec ?? defaultExec;
   const exists = deps.fileExists ?? existsSync;
   const dir = ownerCodexDir();
-  await exec(["exec", "-u", "root", container, "mkdir", "-p", "/home/node/.codex"]);
+  const must = async (args: string[], step: string): Promise<void> => {
+    const res = await exec(args);
+    if (res.status !== 0) {
+      const detail = res.stderr.trim().slice(0, 200);
+      throw new Error(
+        `${step} failed (${res.status === null ? "docker timeout" : `exit ${res.status}`})` +
+          (detail ? `: ${detail}` : ""),
+      );
+    }
+  };
+  await must(
+    ["exec", "-u", "root", container, "mkdir", "-p", "/home/node/.codex"],
+    "mkdir /home/node/.codex",
+  );
   for (const item of CODEX_ITEMS) {
     const src = join(dir, item);
     if (!exists(src)) continue;
-    await exec(["cp", src, `${container}:/home/node/.codex/`]);
+    await must(["cp", src, `${container}:/home/node/.codex/`], `docker cp ${item}`);
   }
-  await exec([
-    "exec",
-    "-u",
-    "root",
-    container,
-    "chown",
-    "-R",
-    "node:node",
-    "/home/node/.codex",
-  ]);
+  await must(
+    ["exec", "-u", "root", container, "chown", "-R", "node:node", "/home/node/.codex"],
+    "chown -R node:node /home/node/.codex",
+  );
 }
 
 /**
- * Re-copy the freshly (re)logged-in `~/.codex` into every running task
- * container on this host. No-op when there is no `~/.codex/auth.json` (nothing
- * to inject) or no running tasks. Best-effort per container.
+ * Inject the owner's `~/.codex` into ONE container known to be running.
+ * Recovery calls this immediately after `docker start`, BEFORE uai-init and
+ * any agent respawn, so a recovered container never runs Codex against
+ * host-uid-owned credentials. Returns false after logging an actionable
+ * error (no secrets) — recovery of the task itself must not fail over Codex.
+ */
+export async function injectCodexIntoContainer(
+  container: string,
+  deps: CodexDeps = {},
+): Promise<boolean> {
+  const exists = deps.fileExists ?? existsSync;
+  if (!exists(join(ownerCodexDir(), "auth.json"))) return true; // nothing to inject
+  try {
+    await copyCodexInto(container, deps);
+    return true;
+  } catch (err) {
+    console.error(
+      `[codex] inject into ${container}: ${err instanceof Error ? err.message : err} — ` +
+        `Codex in this task will fail until fixed (run: docker exec -u root ${container} ` +
+        `chown -R node:node /home/node/.codex, or restart the host)`,
+    );
+    return false;
+  }
+}
+
+/**
+ * Re-copy the freshly (re)logged-in `~/.codex` into every task container that
+ * is both DB-active AND confirmed running by docker. No-op when there is no
+ * `~/.codex/auth.json` or no active tasks; skipped entirely (with a warning)
+ * when docker doesn't answer. Per-container failures are surfaced and don't
+ * stop the sweep.
  */
 export async function reinjectCodexRunningTasks(deps: CodexDeps = {}): Promise<void> {
   const exists = deps.fileExists ?? existsSync;
   if (!exists(join(ownerCodexDir(), "auth.json"))) return;
-  const containers = (deps.runningContainers ?? defaultRunningContainers)();
-  if (containers.length === 0) return;
-  console.log(`[codex] re-copying ~/.codex into ${containers.length} running task(s)`);
-  for (const container of containers) {
+  const active = (deps.activeTaskContainers ?? defaultActiveTaskContainers)();
+  if (active.length === 0) return;
+  const running = await dockerRunningNames(deps.exec ?? defaultExec);
+  if (running === null) {
+    console.warn(
+      "[codex] reinject skipped — docker didn't answer `docker ps`; will retry on the next trigger",
+    );
+    return;
+  }
+  const targets = active.filter((c) => running.has(c));
+  const stopped = active.length - targets.length;
+  if (stopped > 0) {
+    console.log(
+      `[codex] ${stopped} active task(s) not running — skipped (recovery injects them at docker start)`,
+    );
+  }
+  if (targets.length === 0) return;
+  console.log(`[codex] re-copying ~/.codex into ${targets.length} running task(s)`);
+  for (const container of targets) {
     try {
       await copyCodexInto(container, deps);
     } catch (err) {
-      console.warn(
+      console.error(
         `[codex] reinject into ${container} failed: ${err instanceof Error ? err.message : err}`,
       );
     }

package/lib/engines.ts

@@ -63,6 +63,7 @@ import {
   chmodSync,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   rmSync,
   writeFileSync,
@@ -88,6 +89,11 @@ export interface EngineCatalogEntry {
   apiKeyHint: string | null;
   /** Where to mint a key for the pasted-API-key alternative. */
   apiKeyUrl: string | null;
+  /**
+   * Human-readable install command the UI shows next to "Install & connect"
+   * when the CLI is missing (null = nothing to install, e.g. Cursor).
+   */
+  installHint: string | null;
 }
 
 interface EngineDescriptor {
@@ -184,8 +190,17 @@ function defaultSeams(): EngineSeams {
   return {
     spawn: (command, args, spawnEnv) =>
       nodeSpawn(command, args, {
-        // stdin stays open (pipe): the token flow answers "Press Enter" gates.
-        stdio: ["pipe", "pipe", "pipe"],
+        // macOS: stdin MUST be /dev/null ("ignore"), never a node pipe. Node's
+        // child pipes are SOCKETPAIRS, and Apple's BSD script(1) hard-exits on
+        // a socket stdin ("tcgetattr/ioctl: Operation not supported on
+        // socket") while tolerating /dev/null (ENOTTY → notty mode). The
+        // "Press Enter" auto-ack is therefore Linux-only; the real token flow
+        // needs no input before the token renders (verified empirically).
+        stdio: [
+          process.platform === "darwin" ? "ignore" : "pipe",
+          "pipe",
+          "pipe",
+        ],
         env: spawnEnv,
       }),
     envLocalPath: () => join(env.uaiHome, ".env.local"),
@@ -231,18 +246,43 @@ function defaultPtyWrap(bin: string, args: string[]): PtyCommand | null {
 }
 
 /**
- * The PATH the owner's login shell exports. Runs `/usr/bin/env` (not
+ * The PATH the owner's shell exports. Probes an INTERACTIVE login shell
+ * first: nvm/asdf/fnm put their PATH setup in `.zshrc`/`.bashrc`, which a
+ * plain login shell (`-lc`) never sources — that gap hid `npm i -g` installs
+ * from the probe. Falls back to `-lc` for profiles that misbehave when run
+ * interactively without a terminal. Null on failure of both; callers fall
+ * back to the inherited PATH.
+ *
+ * Cached (module-level, 5 min): the CLI-found statuses probe on every
+ * /api/engines poll and shelling out each time would be rude. Staleness is
+ * harmless — every installer this module runs lands in a candidate dir,
+ * which is checked before the probe.
+ */
+async function probeLoginShellPath(): Promise<string | null> {
+  const now = Date.now();
+  if (loginPathCache && now - loginPathCache.at < LOGIN_PATH_CACHE_MS) {
+    return loginPathCache.value;
+  }
+  const value = (await shellPath("-lic")) ?? (await shellPath("-lc"));
+  loginPathCache = { value, at: now };
+  return value;
+}
+
+let loginPathCache: { value: string | null; at: number } | null = null;
+const LOGIN_PATH_CACHE_MS = 5 * 60_000;
+
+/**
+ * Run `$SHELL <flags> /usr/bin/env` and pull PATH out. `/usr/bin/env` (not
  * `echo $PATH`) so the value is the real colon-joined exported PATH under any
- * shell — fish's `$PATH` is a list and would echo space-joined — and takes the
- * LAST `PATH=` line so profile echo noise can't spoof it. Null on any failure;
- * callers fall back to the inherited PATH.
+ * shell — fish's `$PATH` is a list and would echo space-joined — and the
+ * LAST `PATH=` line wins so profile echo noise can't spoof it.
  */
-function probeLoginShellPath(): Promise<string | null> {
+function shellPath(flags: string): Promise<string | null> {
   return new Promise((resolve) => {
     const shell = process.env.SHELL?.trim() || "/bin/zsh";
     nodeExecFile(
       shell,
-      ["-lc", "/usr/bin/env"],
+      [flags, "/usr/bin/env"],
       { timeout: 8_000 },
       (err, stdout) => {
         if (err) return resolve(null);
@@ -276,10 +316,22 @@ export function engineCatalog(): EngineCatalogEntry[] {
       getKeyUrl: d.getKeyUrl ?? null,
       apiKeyHint: d.apiKeyHint ?? null,
       apiKeyUrl: d.apiKeyUrl ?? null,
+      installHint:
+        kind === "codex" ? CODEX_INSTALL_HINT : (INSTALLERS[kind] ?? null),
     };
   });
 }
 
+/** kind → whether the engine's CLI is resolvable on this host right now. */
+export async function engineCliStatuses(
+  seams: Partial<EngineSeams> = {},
+): Promise<Record<EngineKind, boolean>> {
+  const s = withDefaults(seams);
+  const out = {} as Record<EngineKind, boolean>;
+  for (const kind of ORDER) out[kind] = await engineCliFound(kind, s);
+  return out;
+}
+
 /** kind → connected, for every engine. */
 export function engineStatuses(
   seams: Partial<EngineSeams> = {},
@@ -465,6 +517,209 @@ export function disconnectEngine(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Install a missing engine CLI (ADR-072).
+// ---------------------------------------------------------------------------
+
+/**
+ * Pinned installer one-liners — the same vendor installers the standard task
+ * image already trusts (host-agent/images/standard/Dockerfile), shown
+ * VERBATIM in the UI before running. Every one lands its binary in a
+ * candidateBins dir, so the next resolve finds it with no restart:
+ * claude → ~/.local/bin, kimi → ~/.kimi-code/bin, grok → ~/.grok/bin.
+ * Codex has no vendor script — resolved at run time (brew, then npm).
+ */
+const INSTALLERS: Partial<Record<EngineKind, string>> = {
+  claude: "curl -fsSL https://claude.ai/install.sh | bash",
+  kimi: "curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash",
+  grok: "curl -fsSL https://x.ai/cli/install.sh | bash",
+};
+
+const CODEX_INSTALL_HINT = "brew install codex — or: npm i -g @openai/codex";
+
+/** Installers can compile/download; give them real time. */
+const INSTALL_TIMEOUT_MS = 15 * 60_000;
+
+export interface InstallResult {
+  ok: boolean;
+  message: string;
+}
+
+/**
+ * Install an engine's CLI with its pinned installer, streaming output to
+ * `onLog`. Refuses when there's nothing to install (api-key engines) and
+ * short-circuits when the CLI is already resolvable. Success = the installer
+ * exits 0 AND the CLI resolves afterwards.
+ */
+export async function installEngineCli(
+  kind: EngineKind,
+  onLog: (line: string) => void,
+  seams: Partial<EngineSeams> = {},
+): Promise<InstallResult> {
+  const s = withDefaults(seams);
+  const d = DESCRIPTORS[kind];
+  if (d.authMode === "api-key") {
+    return {
+      ok: false,
+      message: `${d.label} doesn't use a CLI on the host — paste an API key instead.`,
+    };
+  }
+  if (await engineCliFound(kind, s)) {
+    return { ok: true, message: `${d.label} CLI is already installed.` };
+  }
+  const inv = await resolveInstaller(kind, s);
+  if (!inv) {
+    return {
+      ok: false,
+      message:
+        "No way to install Codex automatically: install Homebrew or Node.js first, then `brew install codex` or `npm i -g @openai/codex`.",
+    };
+  }
+  let child: ChildProcess;
+  try {
+    child = s.spawn(inv.command, inv.args, {
+      ...s.procEnv,
+      ...(inv.path ? { PATH: inv.path } : {}),
+    });
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer: NodeJS.Timeout | undefined;
+    const done = (r: InstallResult, kill = false): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (kill) {
+        try {
+          child.kill();
+        } catch {
+          /* already gone */
+        }
+      }
+      resolve(r);
+    };
+    const relay = createLineRelay(onLog);
+    child.stdout?.on("data", relay);
+    child.stderr?.on("data", relay);
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      done({ ok: false, message: err.message }),
+    );
+    child.on("exit", (code) => {
+      void (async () => {
+        if (code !== 0) {
+          done({
+            ok: false,
+            message: `Install failed (exit ${code ?? "?"}) — see the log above.`,
+          });
+          return;
+        }
+        done(
+          (await engineCliFound(kind, s))
+            ? { ok: true, message: `${d.label} CLI installed.` }
+            : {
+                ok: false,
+                message:
+                  "The installer finished but the CLI still isn't findable — install it manually, then try Connect.",
+              },
+        );
+      })();
+    });
+    timer = setTimeout(
+      () =>
+        done(
+          { ok: false, message: "The installer timed out — see the log above." },
+          true,
+        ),
+      INSTALL_TIMEOUT_MS,
+    );
+  });
+}
+
+interface InstallInvocation {
+  command: string;
+  args: string[];
+  /** Child PATH override (npm needs its own dir leading so node resolves). */
+  path?: string;
+}
+
+/** Vendor script via sh for most engines; brew-then-npm for Codex. */
+async function resolveInstaller(
+  kind: EngineKind,
+  s: EngineSeams,
+): Promise<InstallInvocation | null> {
+  if (kind !== "codex") {
+    const script = INSTALLERS[kind];
+    return script ? { command: "/bin/sh", args: ["-c", script] } : null;
+  }
+  const brew = s.systemBinDirs.map((dir) => join(dir, "brew")).find(existsSync);
+  if (brew) return { command: brew, args: ["install", "codex"] };
+  const npm = await findBinNamed("npm", s);
+  if (npm) {
+    return {
+      command: npm,
+      args: ["install", "-g", "@openai/codex"],
+      path: prependPath([dirname(npm)], s.procEnv.PATH ?? ""),
+    };
+  }
+  return null;
+}
+
+/** Find an arbitrary tool the same way engine CLIs are found. */
+async function findBinNamed(
+  name: string,
+  s: EngineSeams,
+): Promise<string | null> {
+  const home = s.ownerHome();
+  const dirs = [
+    join(home, ".local", "bin"),
+    ...nodeManagerBinDirs(home),
+    ...s.systemBinDirs,
+  ];
+  for (const dir of dirs) {
+    const file = join(dir, name);
+    if (existsSync(file)) return file;
+  }
+  const login = await s.loginShellPath();
+  const dir = login?.split(":").find((p) => p && existsSync(join(p, name)));
+  return dir ? join(dir, name) : null;
+}
+
+/** Whether an engine's CLI resolves right now (candidates, then login PATH). */
+async function engineCliFound(
+  kind: EngineKind,
+  s: EngineSeams,
+): Promise<boolean> {
+  if (DESCRIPTORS[kind].authMode === "api-key") return true; // never spawned
+  if (candidateBins(kind, s).some(existsSync)) return true;
+  const login = await s.loginShellPath();
+  return !!login
+    ?.split(":")
+    .some((dir) => dir.length > 0 && existsSync(join(dir, kind)));
+}
+
+/**
+ * Accumulate a child's output and forward each distinct, meaningful,
+ * COMPLETE line to `onLog` once — same discipline as the token flow's
+ * relay, for plain (non-PTY) installer output with \r progress noise.
+ */
+function createLineRelay(onLog: (line: string) => void): (b: Buffer) => void {
+  let raw = "";
+  const forwarded = new Set<string>();
+  return (b) => {
+    raw += b.toString("utf8");
+    if (raw.length > 262_144) raw = raw.slice(-131_072);
+    const text = sanitizeTerminalOutput(raw);
+    for (const line of significantLines(text.slice(0, text.lastIndexOf("\n") + 1))) {
+      if (!forwarded.has(line)) {
+        forwarded.add(line);
+        onLog(line);
+      }
+    }
+  };
+}
+
 /**
  * Flatten a PTY byte stream into plain text lines. Strips OSC sequences
  * (incl. OSC-8 hyperlink wrappers, keeping their visible text), CSI
@@ -562,14 +817,21 @@ function configPath(kind: EngineKind, s: EngineSeams): string {
  */
 function candidateBins(kind: EngineKind, s: EngineSeams): string[] {
   const home = s.ownerHome();
-  const common = [join(home, ".local", "bin"), ...s.systemBinDirs];
+  const common = [
+    join(home, ".local", "bin"),
+    ...nodeManagerBinDirs(home),
+    ...s.systemBinDirs,
+  ];
   switch (kind) {
     case "claude":
       // Native installer symlinks ~/.local/bin/claude (preferred); the older
       // "local install" migration keeps a wrapper at ~/.claude/local/claude.
-      return [join(home, ".local", "bin"), join(home, ".claude", "local"), ...s.systemBinDirs].map(
-        (d) => join(d, "claude"),
-      );
+      return [
+        join(home, ".local", "bin"),
+        join(home, ".claude", "local"),
+        ...nodeManagerBinDirs(home),
+        ...s.systemBinDirs,
+      ].map((d) => join(d, "claude"));
     case "codex":
       return common.map((d) => join(d, "codex"));
     case "kimi":
@@ -583,6 +845,50 @@ function candidateBins(kind: EngineKind, s: EngineSeams): string[] {
   }
 }
 
+/**
+ * Bin dirs of the common node version managers — `npm i -g` lands CLIs here,
+ * and none of these are on a GUI PATH or even in a NON-interactive login
+ * shell's PATH (their init lives in .zshrc/.bashrc), which is exactly how an
+ * installed `codex` still read "not found". Deterministic dirs beat shell
+ * probing: no subprocess, no profile side effects.
+ */
+function nodeManagerBinDirs(home: string): string[] {
+  const dirs = [
+    join(home, ".asdf", "shims"), // shims exec asdf by absolute path
+    join(home, ".volta", "bin"),
+    join(home, ".bun", "bin"),
+    join(home, ".npm-global", "bin"),
+    // fnm's stable default-alias bin — the per-shell multishell paths its
+    // shell init exports are ephemeral. macOS, XDG, and legacy layouts.
+    join(home, "Library", "Application Support", "fnm", "aliases", "default", "bin"),
+    join(home, ".local", "share", "fnm", "aliases", "default", "bin"),
+    join(home, ".fnm", "aliases", "default", "bin"),
+  ];
+  // nvm has no stable "current" symlink — enumerate installed versions,
+  // newest first (numeric compare: lexicographic would put v9 over v22).
+  // A version dir's bin also holds its `node`, so the shebang of whatever
+  // we find there resolves against the same dir once it leads PATH.
+  try {
+    const versions = join(home, ".nvm", "versions", "node");
+    dirs.push(
+      ...readdirSync(versions)
+        .sort(compareVersionDesc)
+        .map((v) => join(versions, v, "bin")),
+    );
+  } catch {
+    /* no nvm */
+  }
+  return dirs;
+}
+
+function compareVersionDesc(a: string, b: string): number {
+  const parts = (s: string): number[] =>
+    s.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+  const [a1 = 0, a2 = 0, a3 = 0] = parts(a);
+  const [b1 = 0, b2 = 0, b3 = 0] = parts(b);
+  return b1 - a1 || b2 - a2 || b3 - a3;
+}
+
 interface ResolvedBin {
   /** Command to spawn — absolute when found, else the bare name. */
   bin: string;

package/lib/orchestrator.ts

@@ -51,6 +51,7 @@ import {
   writeAgentCli,
 } from "./agent-cli";
 import { setupBrowserTesting } from "./browser-testing";
+import { injectCodexIntoContainer } from "./codex-auth";
 import { clearTaskGatewayAcl, setupMcpTaskConfig } from "./mcp-gateway";
 import { env } from "./env";
 import type {
@@ -1392,11 +1393,26 @@ export function getOrchestrator(): Orchestrator {
   if (!globalForOrchestrator.__uaiRecoverRan) {
     globalForOrchestrator.__uaiRecoverRan = true;
     // Fire-and-forget — the orchestrator is usable while recovery runs.
-    void recoverRunningTasks();
+    // The promise is kept so boot steps that must NOT race recovery (the
+    // Codex credential reinject) can sequence behind it via
+    // recoveryComplete(). recoverRunningTasks never rejects.
+    recoveryPromise = recoverRunningTasks();
+    void recoveryPromise;
   }
   return globalForOrchestrator.__uaiOrchestrator;
 }
 
+let recoveryPromise: Promise<void> = Promise.resolve();
+
+/**
+ * Resolves once boot-time recovery has finished (starting the orchestrator —
+ * and with it recovery — if that hasn't happened yet). Never rejects.
+ */
+export function recoveryComplete(): Promise<void> {
+  getOrchestrator();
+  return recoveryPromise;
+}
+
 // ---------------------------------------------------------------------------
 // Boot-time recovery
 //
@@ -1497,7 +1513,8 @@ async function dockerExec(
   return res.status === 0;
 }
 
-async function recoverRunningTasks(): Promise<void> {
+/** Exported for tests; production entry is the getOrchestrator() boot guard. */
+export async function recoverRunningTasks(): Promise<void> {
   try {
     const db = getDb();
     const rows = db
@@ -1601,6 +1618,12 @@ async function recoverOneTask(
     });
     return;
   }
+  // Correctly-owned Codex creds BEFORE uai-init / any agent respawn: the boot
+  // reinject sweep only targets containers already running, so a container
+  // recovered here would otherwise keep whatever it held when it exited —
+  // possibly host-uid-owned 0600 files Codex can't read. Failure is surfaced
+  // by the inject itself and must not abort the task's recovery.
+  await injectCodexIntoContainer(containerName);
   // uai-init reinstalls workspace deps (pnpm/npm install) — minutes on a big
   // repo. dockerCli's 30s default would SIGKILL it mid-install.
   if (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.8.12",
+  "version": "0.8.16",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/scripts/agent/task-up.sh

@@ -462,17 +462,25 @@ fi
 # Copy Codex credentials/config into a task-private /home/node/.codex.
 # Do not mount the host ~/.codex writable: Codex stores live SQLite state
 # there, and concurrent host/container access can corrupt it.
-docker exec -u root "$app_container" \
-  mkdir -p /home/node/.codex >/dev/null 2>&1 || true
-for codex_item in auth.json config.toml AGENTS.md version.json installation_id rules; do
-  if [ -e "$UAI_OWNER_HOME/.codex/$codex_item" ]; then
-    docker cp "$UAI_OWNER_HOME/.codex/$codex_item" \
-      "$app_container":/home/node/.codex/ >/dev/null 2>&1 \
-      || log "warning: docker cp of .codex/$codex_item failed; codex may need re-login"
-  fi
-done
-docker exec -u root "$app_container" \
-  chown -R node:node /home/node/.codex >/dev/null 2>&1 || true
+# Failures here are REAL errors (the container is running at task-up):
+# docker cp preserves the host uid/gid, so a skipped chown leaves 0600
+# files owned by e.g. macOS 501:20 that the container's node (1000:1000)
+# cannot read — Codex then dies at startup.
+if docker exec -u root "$app_container" \
+    mkdir -p /home/node/.codex >/dev/null; then
+  for codex_item in auth.json config.toml AGENTS.md version.json installation_id rules; do
+    if [ -e "$UAI_OWNER_HOME/.codex/$codex_item" ]; then
+      docker cp "$UAI_OWNER_HOME/.codex/$codex_item" \
+        "$app_container":/home/node/.codex/ >/dev/null \
+        || log "ERROR: docker cp of .codex/$codex_item failed; Codex in this task may not authenticate"
+    fi
+  done
+  docker exec -u root "$app_container" \
+      chown -R node:node /home/node/.codex >/dev/null \
+    || log "ERROR: chown of /home/node/.codex failed — 0600 credentials remain unreadable by node. Fix: docker exec -u root $app_container chown -R node:node /home/node/.codex"
+else
+  log "ERROR: mkdir /home/node/.codex failed in $app_container; Codex credentials were not injected"
+fi
 
 # Copy Kimi Code subscription/config into a task-private /home/node/.kimi-code.
 # The Linux `kimi` binary is baked into the image; here we copy ONLY the

package/src/main.ts

@@ -23,7 +23,7 @@ import {
   markReconnecting,
 } from "../lib/cloud-state";
 import { getHostTask } from "../lib/runtime-state";
-import { getOrchestrator } from "../lib/orchestrator";
+import { getOrchestrator, recoveryComplete } from "../lib/orchestrator";
 import {
   connectedUserIds,
   isTransientGithubError,
@@ -159,7 +159,13 @@ void ensureStandardImage();
 // token → `codex login`) otherwise reaches only NEW tasks — re-copy into
 // running tasks on start (covers the desktop "Connect Codex", which restarts
 // the host) and watch ~/.codex for future logins (a terminal `codex login`).
-void reinjectCodexRunningTasks();
+// Sequenced AFTER boot recovery: reinjecting while recovery was still
+// `docker start`ing exited containers raced — `docker cp` into a stopped
+// container succeeds but the ownership-fix exec can't run, stranding 0600
+// files owned by the host uid (macOS 501) that the container's node (1000)
+// can't read, and Codex died at startup. The post-recovery sweep also
+// self-heals such containers: it re-copies and chowns every running task.
+void recoveryComplete().then(() => reinjectCodexRunningTasks());
 watchCodexAuth();
 connect();
 // Local browser UI (ADR-028) — same single process, alongside the WSS client.

package/src/ui/server.ts

@@ -30,6 +30,8 @@ import { dockerCli } from "../../lib/docker-exec";
 import {
   connectEngine,
   disconnectEngine,
+  engineCliStatuses,
+  installEngineCli,
   engineCatalog,
   engineStatuses,
   isEngineKind,
@@ -151,6 +153,8 @@ async function handle(
       switch (path) {
         case "/api/engines/connect":
           return await handleEngineConnect(req, res, opts);
+        case "/api/engines/install":
+          return await handleEngineInstall(req, res);
         case "/api/engines/disconnect":
           return await handleEngineDisconnect(req, res, opts);
         case "/api/tasks/stop":
@@ -181,7 +185,7 @@ async function handle(
       case "/api/users":
         return sendJson(res, UsersResponse, usersBody(opts));
       case "/api/engines":
-        return sendJson(res, EnginesResponse, enginesBody());
+        return sendJson(res, EnginesResponse, await enginesBody());
     }
     if (path.startsWith("/api/")) {
       return sendError(res, 404, `no such endpoint: ${path}`);
@@ -194,8 +198,47 @@ async function handle(
 
 // --- engines ----------------------------------------------------------------
 
-function enginesBody(): EnginesResponse {
-  return { catalog: engineCatalog(), statuses: engineStatuses() };
+async function enginesBody(): Promise<EnginesResponse> {
+  return {
+    catalog: engineCatalog(),
+    statuses: engineStatuses(),
+    cli: await engineCliStatuses(),
+  };
+}
+
+/**
+ * POST /api/engines/install `{kind}` — run the engine's pinned installer,
+ * streaming NDJSON like connect: `{"line":…}` frames, then `{done,ok,message}`.
+ * No re-advertise or image rebuild here: installing a CLI connects nothing;
+ * that happens on the connect that follows.
+ */
+async function handleEngineInstall(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const kind = body?.kind;
+  if (!isEngineKind(kind)) {
+    return sendError(res, 400, "unknown or missing engine kind");
+  }
+  res.writeHead(200, {
+    "content-type": "application/x-ndjson; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  const emit = (obj: unknown): void => {
+    res.write(`${JSON.stringify(obj)}\n`);
+  };
+  let result: { ok: boolean; message: string };
+  try {
+    result = await installEngineCli(kind, (line) => emit({ line }));
+  } catch (err) {
+    result = {
+      ok: false,
+      message: err instanceof Error ? err.message : "install failed",
+    };
+  }
+  emit({ done: true, ok: result.ok, message: result.message });
+  res.end();
 }
 
 /**

package/src/ui/types.ts

@@ -84,12 +84,15 @@ export const EngineCatalogEntry = z.object({
   // Pasted-API-key alternative to the login/token flow (null = not offered).
   apiKeyHint: z.string().nullable(),
   apiKeyUrl: z.string().nullable(),
+  // Install command shown when the CLI is missing (null = nothing to install).
+  installHint: z.string().nullable(),
 });
 export type EngineCatalogEntry = z.infer<typeof EngineCatalogEntry>;
 
 export const EnginesResponse = z.object({
   catalog: z.array(EngineCatalogEntry),
   statuses: z.record(z.boolean()), // kind → connected
+  cli: z.record(z.boolean()), // kind → CLI resolvable on this host
 });
 export type EnginesResponse = z.infer<typeof EnginesResponse>;
 

package/ui/app.js

@@ -483,6 +483,11 @@ function commandForm(e) {
   log.className = "log";
   log.hidden = true;
 
+  const pushLine = (line) => {
+    log.textContent += (log.textContent ? "\n" : "") + line;
+    log.scrollTop = log.scrollHeight;
+  };
+
   const actions = document.createElement("div");
   actions.className = "setup-actions";
   const connect = document.createElement("button");
@@ -499,10 +504,7 @@ function commandForm(e) {
         : "Your browser will open to sign in…";
     log.hidden = false;
     log.textContent = "";
-    const result = await runConnect({ kind: e.kind }, (line) => {
-      log.textContent += (log.textContent ? "\n" : "") + line;
-      log.scrollTop = log.scrollHeight;
-    });
+    const result = await runConnect({ kind: e.kind }, pushLine);
     if (result.ok) {
       await poll();
       closeModal();
@@ -514,6 +516,47 @@ function commandForm(e) {
     }
   });
   actions.append(connect);
+
+  // CLI missing → offer the pinned installer first, chaining into connect on
+  // success. The command is shown verbatim; its output streams into the log.
+  const cliMissing =
+    !!latestEngines?.cli && latestEngines.cli[e.kind] === false && !!e.installHint;
+  if (cliMissing) {
+    connect.hidden = true;
+    const installNote = document.createElement("p");
+    installNote.className = "setup-note";
+    installNote.textContent = `The ${e.label} CLI isn't installed on this Mac. Install it with:`;
+    const installCmd = document.createElement("pre");
+    installCmd.className = "log";
+    installCmd.textContent = e.installHint;
+    const install = document.createElement("button");
+    install.className = "btn";
+    install.type = "button";
+    install.textContent = "Install & connect";
+    install.addEventListener("click", async () => {
+      install.disabled = true;
+      install.textContent = "Installing…";
+      status.className = "setup-status";
+      status.textContent = "Running the installer…";
+      log.hidden = false;
+      log.textContent = "";
+      const result = await runInstall({ kind: e.kind }, pushLine);
+      if (result.ok) {
+        await poll();
+        install.hidden = true;
+        connect.hidden = false;
+        connect.click();
+      } else {
+        install.disabled = false;
+        install.textContent = "Try again";
+        status.className = "setup-status err";
+        status.textContent = result.message || "Install failed.";
+      }
+    });
+    actions.prepend(install);
+    form.append(installNote, installCmd);
+  }
+
   form.append(actions, status, log);
 
   // Manual paste fallback for when the browser flow isn't possible: Claude
@@ -590,14 +633,24 @@ function commandForm(e) {
   return form;
 }
 
+/** POST /api/engines/connect and consume the NDJSON stream. */
+function runConnect(body, onLine) {
+  return runStream("/api/engines/connect", body, onLine);
+}
+
+/** POST /api/engines/install and consume the NDJSON stream. */
+function runInstall(body, onLine) {
+  return runStream("/api/engines/install", body, onLine);
+}
+
 /**
- * POST /api/engines/connect and consume the NDJSON stream: `{line}` frames feed
- * onLine; the final `{done,ok,message}` frame is the result.
+ * POST an NDJSON-streaming endpoint: `{line}` frames feed onLine; the final
+ * `{done,ok,message}` frame is the result.
  */
-async function runConnect(body, onLine) {
+async function runStream(path, body, onLine) {
   let res;
   try {
-    res = await fetch("/api/engines/connect", {
+    res = await fetch(path, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
@@ -606,7 +659,7 @@ async function runConnect(body, onLine) {
     return { ok: false, message: String(err) };
   }
   if (!res.ok || !res.body) {
-    return { ok: false, message: `connect failed (${res.status})` };
+    return { ok: false, message: `request failed (${res.status})` };
   }
   const reader = res.body.getReader();
   const dec = new TextDecoder();