@runuai/host 0.9.71 → 0.9.72

package/lib/agent-cli.ts

@@ -130,6 +130,42 @@ export function writeAgentCli(
   }
 }
 
+/**
+ * ADR-121: the same CLI materialization, but through the environment's own
+ * transport — machine workspaces are not host-reachable via taskWorkspaceDir.
+ * Same no-token invariant: uai.json carries the apiUrl only.
+ */
+export async function writeAgentCliViaEnvironment(
+  environment: {
+    readonly descriptor: { workspacePath: string };
+    writeWorkspaceFile(path: string, bytes: Uint8Array): Promise<void>;
+  },
+  roster: RosterAgent[],
+  apiUrl: string | null,
+  allowPermissionless = false,
+): Promise<boolean> {
+  if (
+    !apiUrl ||
+    (rosterPermissions(roster).length === 0 && !allowPermissionless)
+  ) {
+    return false;
+  }
+  try {
+    const root = environment.descriptor.workspacePath;
+    await environment.writeWorkspaceFile(
+      `${root}/.uai/uai.json`,
+      Buffer.from(`${JSON.stringify({ apiUrl }, null, 2)}\n`),
+    );
+    await environment.writeWorkspaceFile(
+      `${root}/.uai/cli.mjs`,
+      Buffer.from(CLI_SOURCE),
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Per-agent env for the `docker exec` that spawns one agent (ADR-048): its OWN
  * task token (carrying only ITS permissions) + the API url. Empty when the agent

package/lib/agents/machine-durable.ts

@@ -0,0 +1,492 @@
+/**
+ * ADR-121 + ADR-061: durable agent sessions for MACHINE-backed tasks.
+ *
+ * The container path's DurableProcess polls the session files on a host
+ * bind mount — a machine shares no filesystem with the host, so this
+ * variant speaks the same runner protocol over the environment transport:
+ *
+ *   outbox   one long-lived `tail -c +<offset+1> -F` streamed over ssh;
+ *            byte offset = initial + bytes received (append-only file).
+ *            A dropped ssh stream is respawned from the current offset.
+ *   inbox    chained one-shot appends (`cat >> inbox.jsonl` with stdin).
+ *   liveness periodic heartbeat mtime probe via exec; the runner beats
+ *            every 5s, so >25s of silence without an exit meta = dead.
+ *
+ * The runner itself (runner.mjs) is dependency-free Node and runs on the
+ * machine unchanged; it is delivered per-session via writeWorkspaceFile so
+ * it can never skew against this host's version.
+ */
+
+import { readFileSync } from "node:fs";
+import { posix } from "node:path";
+
+import type {
+  TaskEnvironmentHandle,
+  TaskEnvironmentProcess,
+} from "../task-environment/types";
+import { runnerScriptPath } from "./durable-proc";
+import type { ExitHandler, LineHandler } from "./proc";
+import type { LineTransport } from "./transport";
+
+/** Runner beats every 5 s; 25 s of silence without an exit meta = dead. */
+const HEARTBEAT_STALE_MS = 25_000;
+const HEARTBEAT_PROBE_MS = 10_000;
+const CLOSE_GRACE_MS = 8_000;
+const STEP_TIMEOUT_MS = 30_000;
+const STEP_OUTPUT_BYTES = 64 * 1024;
+const TAIL_RESPAWN_DELAY_MS = 1_000;
+
+interface RunnerMeta {
+  __uai: string;
+  code?: number | null;
+  stderrTail?: string;
+}
+
+/** The handle ops this transport needs beyond the session surface. */
+export type MachineSessionEnvironment = Pick<
+  TaskEnvironmentHandle<unknown>,
+  | "descriptor"
+  | "exec"
+  | "spawnSession"
+  | "writeWorkspaceFile"
+  | "launchDetachedSession"
+>;
+
+async function execStep(
+  environment: MachineSessionEnvironment,
+  argv: readonly [string, ...string[]],
+  stdin?: Uint8Array,
+): Promise<{ exitCode: number | null; stdout: string; stderr: string }> {
+  const result = await environment.exec({
+    argv,
+    ...(stdin ? { stdin } : {}),
+    timeoutMs: STEP_TIMEOUT_MS,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  return {
+    exitCode: result.exitCode,
+    stdout: Buffer.from(result.stdout).toString("utf8"),
+    stderr: Buffer.from(result.stderr).toString("utf8"),
+  };
+}
+
+/** Append bytes to an environment file (creating parents), via exec stdin. */
+export async function appendEnvironmentFile(
+  environment: MachineSessionEnvironment,
+  path: string,
+  bytes: string,
+): Promise<void> {
+  const result = await execStep(
+    environment,
+    [
+      "/bin/sh",
+      "-c",
+      'mkdir -p "$(dirname "$1")" && cat >> "$1"',
+      "append",
+      path,
+    ],
+    Buffer.from(bytes),
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(`environment append to ${path} exited ${result.exitCode}`);
+  }
+}
+
+/** Heartbeat freshness of an environment-side session dir (attach check). */
+export async function machineHeartbeatFresh(
+  environment: MachineSessionEnvironment,
+  sessionDir: string,
+  freshMs: number,
+): Promise<boolean> {
+  try {
+    const result = await execStep(environment, [
+      "/bin/sh",
+      "-c",
+      'stat -c %Y "$1/heartbeat"',
+      "stat",
+      sessionDir,
+    ]);
+    if (result.exitCode !== 0) return false;
+    const mtimeSeconds = Number(result.stdout.trim());
+    if (!Number.isFinite(mtimeSeconds)) return false;
+    return Date.now() - mtimeSeconds * 1000 < freshMs;
+  } catch {
+    return false;
+  }
+}
+
+export interface MachineDurableOptions {
+  environment: MachineSessionEnvironment;
+  /** Environment-absolute session dir (inside the workspace). */
+  sessionDir: string;
+  /** Resume consumption from this outbox byte offset (attach path). */
+  initialOutboxOffset?: number;
+  onOffsetAdvance?: (offset: number) => void;
+  onCloseRequested?: () => void;
+  /** Provider-owned detached launch. Omit to attach to a live runner. */
+  launch?: () => Promise<{ exitCode: number | null; stderr: Uint8Array }>;
+  debugLabel?: string;
+}
+
+export class MachineDurableProcess implements LineTransport {
+  readonly #environment: MachineSessionEnvironment;
+  readonly #sessionDir: string;
+  readonly #outboxPath: string;
+  readonly #inboxPath: string;
+
+  readonly #lineHandlers = new Set<LineHandler>();
+  readonly #exitHandlers = new Set<ExitHandler>();
+
+  #offset: number;
+  #lineBuf = "";
+  #stderrBuf = "";
+  #closed = false;
+  #detached = false;
+  #sawSpawnMeta = false;
+  readonly #startedAt = Date.now();
+  #tail: TaskEnvironmentProcess | null = null;
+  #tailGeneration = 0;
+  #heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  #closeTimer: ReturnType<typeof setTimeout> | null = null;
+  #respawnTimer: ReturnType<typeof setTimeout> | null = null;
+  #probing = false;
+  #inboxChain: Promise<void> = Promise.resolve();
+  readonly #onOffsetAdvance: ((offset: number) => void) | null;
+  readonly #onCloseRequested: (() => void) | null;
+  readonly #debug: string | null;
+
+  constructor(opts: MachineDurableOptions) {
+    this.#environment = opts.environment;
+    this.#sessionDir = opts.sessionDir;
+    this.#outboxPath = posix.join(opts.sessionDir, "outbox.jsonl");
+    this.#inboxPath = posix.join(opts.sessionDir, "inbox.jsonl");
+    this.#offset = opts.initialOutboxOffset ?? 0;
+    this.#onOffsetAdvance = opts.onOffsetAdvance ?? null;
+    this.#onCloseRequested = opts.onCloseRequested ?? null;
+    this.#debug =
+      opts.debugLabel && process.env.UAI_DEBUG_AGENTS ? opts.debugLabel : null;
+
+    if (opts.launch) {
+      void opts.launch().then(
+        (result) => {
+          const stderr = Buffer.from(result.stderr).toString("utf8");
+          if (stderr) this.#stderrBuf = (this.#stderrBuf + stderr).slice(-8192);
+          if (result.exitCode !== 0) this.#finish(null);
+        },
+        (error: unknown) => {
+          this.#stderrBuf = (
+            this.#stderrBuf +
+            (error instanceof Error ? error.message : String(error))
+          ).slice(-8192);
+          this.#finish(null);
+        },
+      );
+    } else {
+      this.#sawSpawnMeta = true; // attach: the runner pre-exists
+      // The container path pre-checks heartbeat freshness with a sync stat;
+      // over ssh that check is async, so attach optimistically and probe
+      // NOW — a dead runner finishes within a round-trip instead of a
+      // full probe interval, and the orchestrator respawns fresh.
+      void this.#probeLiveness();
+    }
+
+    void this.#spawnTail();
+    this.#heartbeatTimer = setInterval(() => {
+      void this.#probeLiveness();
+    }, HEARTBEAT_PROBE_MS);
+  }
+
+  #log(message: string): void {
+    console.error(`[uai-agent ${this.#debug}] ${message}`);
+  }
+
+  // ---- outbox tail over ssh ------------------------------------------------
+
+  async #spawnTail(): Promise<void> {
+    if (this.#closed || this.#detached) return;
+    const generation = ++this.#tailGeneration;
+    let tail: TaskEnvironmentProcess;
+    try {
+      // spawnSession, deliberately: a session request carries NO timeoutMs,
+      // and the streaming runner only arms its kill timer when one exists —
+      // the tail must live as long as the runner does.
+      tail = await this.#environment.spawnSession({
+        // -c +N is 1-based (start AT byte N): resume just past the consumed
+        // prefix. -F survives the outbox not existing yet; its chatter goes
+        // to stderr, never the byte stream.
+        argv: [
+          "/bin/sh",
+          "-c",
+          'exec tail -c +"$1" -F "$2" 2>/dev/null',
+          "tail",
+          String(this.#offset + 1),
+          this.#outboxPath,
+        ],
+        maxOutputBytes: 8 * 1024 * 1024,
+      });
+    } catch {
+      this.#scheduleTailRespawn(generation);
+      return;
+    }
+    if (this.#closed || this.#detached || generation !== this.#tailGeneration) {
+      await tail.terminate().catch(() => {});
+      return;
+    }
+    this.#tail = tail;
+    void (async () => {
+      try {
+        for await (const chunk of tail.stdout) {
+          if (this.#closed || this.#detached) break;
+          if (generation !== this.#tailGeneration) break;
+          const text = Buffer.from(chunk);
+          this.#offset += text.byteLength;
+          this.#lineBuf += text.toString("utf8");
+          this.#drainLines();
+          if (this.#onOffsetAdvance && !this.#closed) {
+            try {
+              this.#onOffsetAdvance(this.#offset);
+            } catch {
+              // Persistence hiccup — the next batch retries larger.
+            }
+          }
+        }
+      } catch {
+        // Stream error — the respawn below re-establishes the tail.
+      }
+      // The ssh stream ended (drop, machine restart, terminate). If the
+      // session is still live, come back from the current offset.
+      if (!this.#closed && !this.#detached && generation === this.#tailGeneration) {
+        this.#scheduleTailRespawn(generation);
+      }
+    })();
+  }
+
+  #scheduleTailRespawn(generation: number): void {
+    if (this.#closed || this.#detached) return;
+    if (generation !== this.#tailGeneration) return;
+    if (this.#respawnTimer) return;
+    this.#respawnTimer = setTimeout(() => {
+      this.#respawnTimer = null;
+      void this.#spawnTail();
+    }, TAIL_RESPAWN_DELAY_MS);
+  }
+
+  #drainLines(): void {
+    let nl: number;
+    while ((nl = this.#lineBuf.indexOf("\n")) >= 0) {
+      const line = this.#lineBuf.slice(0, nl).trim();
+      this.#lineBuf = this.#lineBuf.slice(nl + 1);
+      if (line.length === 0) continue;
+      if (line.startsWith('{"__uai"')) {
+        this.#handleMeta(line);
+        continue;
+      }
+      if (this.#debug) this.#log(`<- ${line.slice(0, 1000)}`);
+      for (const handler of this.#lineHandlers) {
+        try {
+          handler(line);
+        } catch {
+          // A broken handler must not wedge the tail loop.
+        }
+      }
+    }
+  }
+
+  #handleMeta(line: string): void {
+    let meta: RunnerMeta;
+    try {
+      meta = JSON.parse(line) as RunnerMeta;
+    } catch {
+      return;
+    }
+    if (meta.__uai === "spawn") {
+      this.#sawSpawnMeta = true;
+    } else if (meta.__uai === "exit") {
+      if (typeof meta.stderrTail === "string" && meta.stderrTail) {
+        this.#stderrBuf = meta.stderrTail.slice(-8192);
+      }
+      if (this.#debug) this.#log(`exit meta: code ${meta.code ?? null}`);
+      this.#finish(typeof meta.code === "number" ? meta.code : null);
+    }
+  }
+
+  // ---- liveness ------------------------------------------------------------
+
+  async #probeLiveness(): Promise<void> {
+    if (this.#closed || this.#detached || this.#probing) return;
+    this.#probing = true;
+    try {
+      if (!this.#sawSpawnMeta) {
+        if (Date.now() - this.#startedAt > HEARTBEAT_STALE_MS) this.#finish(null);
+        return;
+      }
+      const fresh = await machineHeartbeatFresh(
+        this.#environment,
+        this.#sessionDir,
+        HEARTBEAT_STALE_MS,
+      );
+      if (this.#closed || this.#detached) return;
+      if (!fresh) this.#finish(null);
+    } finally {
+      this.#probing = false;
+    }
+  }
+
+  #finish(code: number | null): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#stopTimers();
+    const tail = this.#tail;
+    this.#tail = null;
+    if (tail) void tail.terminate().catch(() => {});
+    for (const handler of this.#exitHandlers) handler(code);
+  }
+
+  #stopTimers(): void {
+    if (this.#heartbeatTimer) clearInterval(this.#heartbeatTimer);
+    if (this.#closeTimer) clearTimeout(this.#closeTimer);
+    if (this.#respawnTimer) clearTimeout(this.#respawnTimer);
+    this.#heartbeatTimer = null;
+    this.#closeTimer = null;
+    this.#respawnTimer = null;
+  }
+
+  // ---- LineProcess-compatible surface ---------------------------------------
+
+  onLine(handler: LineHandler): void {
+    this.#lineHandlers.add(handler);
+  }
+
+  onExit(handler: ExitHandler): void {
+    this.#exitHandlers.add(handler);
+  }
+
+  /** `__uai` MUST stay the first key: both runner and host filter meta lines
+   * with a byte-prefix check, not a parse (see DurableProcess.writeLine). */
+  writeLine(value: unknown): void {
+    if (this.#closed || this.#detached) return;
+    const json = JSON.stringify(value);
+    const inputMeta = JSON.stringify({ __uai: "input", ts: Date.now() });
+    if (this.#debug) this.#log(`-> ${json.slice(0, 1000)}`);
+    this.#inboxChain = this.#inboxChain
+      .then(() =>
+        appendEnvironmentFile(
+          this.#environment,
+          this.#inboxPath,
+          `${inputMeta}\n${json}\n`,
+        ),
+      )
+      .catch(() => {
+        // Transport error — liveness probes will surface a dead session.
+      });
+  }
+
+  get stderrTail(): string {
+    return this.#stderrBuf;
+  }
+
+  get isClosed(): boolean {
+    return this.#closed;
+  }
+
+  get outboxOffset(): number {
+    return this.#offset;
+  }
+
+  /** Stop consuming WITHOUT touching the runner (host restart in miniature). */
+  detach(): void {
+    if (this.#detached || this.#closed) return;
+    this.#detached = true;
+    this.#stopTimers();
+    const tail = this.#tail;
+    this.#tail = null;
+    if (tail) void tail.terminate().catch(() => {});
+  }
+
+  /** Real teardown: ask the runner to stop its CLI, then observe the exit. */
+  async close(): Promise<void> {
+    if (this.#closed || this.#detached) return;
+    try {
+      this.#onCloseRequested?.();
+    } catch {
+      // Bookkeeping only.
+    }
+    try {
+      await this.#inboxChain;
+      await appendEnvironmentFile(
+        this.#environment,
+        this.#inboxPath,
+        '{"__uai":"stop"}\n',
+      );
+    } catch {
+      // Inbox unwritable — fall through to the grace timer.
+    }
+    this.#closeTimer = setTimeout(() => this.#finish(null), CLOSE_GRACE_MS);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Session-dir plumbing shared with the transport layer.
+// ---------------------------------------------------------------------------
+
+export function machineSessionDir(
+  workspacePath: string,
+  agentId: string,
+): string {
+  return posix.join(
+    workspacePath,
+    ".uai",
+    "sessions",
+    agentId,
+    `${String(Date.now())}-${process.pid}`,
+  );
+}
+
+/** Deliver this host's runner into the environment session dir. */
+export async function deployRunner(
+  environment: MachineSessionEnvironment,
+  sessionDir: string,
+): Promise<string> {
+  const runnerPath = posix.join(sessionDir, "runner.mjs");
+  await environment.writeWorkspaceFile(
+    runnerPath,
+    readFileSync(runnerScriptPath()),
+  );
+  return runnerPath;
+}
+
+/** Environment-side `current` pointer (agents read the path from their
+ * preamble). Best-effort: failure must never kill a session. */
+export async function publishMachineCurrentSession(
+  environment: MachineSessionEnvironment,
+  sessionDir: string,
+): Promise<void> {
+  try {
+    await execStep(environment, [
+      "/bin/sh",
+      "-c",
+      'ln -sfn "$(basename "$1")" "$(dirname "$1")/current"',
+      "publish",
+      sessionDir,
+    ]);
+  } catch {
+    // Diagnostic pointer only.
+  }
+}
+
+/** Ask a (possibly dead) predecessor runner to stop — same gesture as the
+ * host-FS append, over the transport, and just as harmless when it's gone. */
+export async function stopMachinePredecessor(
+  environment: MachineSessionEnvironment,
+  sessionDir: string,
+): Promise<void> {
+  try {
+    await appendEnvironmentFile(
+      environment,
+      posix.join(sessionDir, "inbox.jsonl"),
+      '{"__uai":"stop"}\n',
+    );
+  } catch {
+    // Dir gone / runner dead — nothing to stop.
+  }
+}

package/lib/agents/transport.ts

@@ -23,6 +23,7 @@
 
 import {
   copyFileSync,
+  readFileSync,
   mkdirSync,
   renameSync,
   rmSync,
@@ -39,6 +40,14 @@ import { taskWorkspaceDir } from "../env";
 import { requireContainerRuntimeOperational } from "../runtime-guard";
 import type { TaskEnvironmentAgentSessionSurface } from "../task-environment/types";
 import { DurableProcess, runnerScriptPath } from "./durable-proc";
+import {
+  MachineDurableProcess,
+  deployRunner,
+  machineSessionDir,
+  publishMachineCurrentSession,
+  stopMachinePredecessor,
+  type MachineSessionEnvironment,
+} from "./machine-durable";
 import {
   AGENT_SESSION_OUTPUT_BUFFER_BYTES,
   EnvironmentLineProcess,
@@ -93,9 +102,13 @@ const ATTACH_HEARTBEAT_FRESH_MS = 20_000;
  * the feed, multiplicity growing by one per errored turn. Enforcing the
  * invariant here covers every replacement path, including future ones.
  */
-const liveTails = new Map<string, DurableProcess>();
+interface DetachableTail extends LineTransport {
+  detach(): void;
+}
 
-function claimTail(key: string, proc: DurableProcess): DurableProcess {
+const liveTails = new Map<string, DetachableTail>();
+
+function claimTail<T extends DetachableTail>(key: string, proc: T): T {
   liveTails.get(key)?.detach();
   liveTails.set(key, proc);
   return proc;
@@ -106,14 +119,16 @@ function durableEnabled(): boolean {
 }
 
 export function createAgentTransport(opts: AgentTransportOptions): LineTransport {
-  // ADR-121: machine-backed sessions ride the environment's own transport
-  // (ssh streaming) directly. The container-runtime preflight is a
-  // docker/apple concern a machine task must not trip over, and durable
-  // sessions poll host-FS files a machine does not share — they return for
-  // machines with an ssh-tail backend.
+  // ADR-121: machine-backed sessions ride the environment's own transport —
+  // the container-runtime preflight is a docker/apple concern a machine task
+  // must not trip over, and the host-FS durable flow below polls files a
+  // machine does not share. Machine durability uses the ssh-tail backend.
   if (opts.environment.descriptor.locator.provider === "machine") {
-    clearCurrentSession(opts.taskId, opts.agentId);
-    return directEnvironmentTransport(opts);
+    if (!durableEnabled()) {
+      clearCurrentSession(opts.taskId, opts.agentId);
+      return directEnvironmentTransport(opts);
+    }
+    return machineDurableTransport(opts);
   }
   // Session creation can happen after channel/task lifecycle queues drain, well
   // after the command-level runtime preflight. Recheck at the actual attach or
@@ -286,6 +301,166 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
   return claimTail(tailKey, proc);
 }
 
+/**
+ * ADR-121: durable machine sessions. Same DB row + attach/replace semantics
+ * as the container flow; the session files live in the MACHINE's workspace
+ * and are reached over the environment transport (MachineDurableProcess).
+ * Degrades to direct pipes when the handle lacks the wider ops or the runner
+ * asset is missing — sessions work, they just don't survive host restarts.
+ */
+function machineDurableTransport(opts: AgentTransportOptions): LineTransport {
+  const surface = opts.environment;
+  const capable =
+    "exec" in surface && "spawnSession" in surface && "writeWorkspaceFile" in surface;
+  let runnerSource: Buffer | null = null;
+  if (capable) {
+    try {
+      runnerSource = readFileSync(runnerScriptPath());
+    } catch (err) {
+      console.warn(
+        `[transport] runner unavailable (${err instanceof Error ? err.message : err}) — falling back to direct pipes for ${opts.agentId}`,
+      );
+    }
+  }
+  if (!capable || runnerSource === null) {
+    clearCurrentSession(opts.taskId, opts.agentId);
+    return directEnvironmentTransport(opts);
+  }
+  const environment = surface as unknown as MachineSessionEnvironment &
+    TaskEnvironmentAgentSessionSurface;
+
+  const db = getDb();
+  const row = db
+    .select()
+    .from(schema.hostAgentSessions)
+    .where(
+      and(
+        eq(schema.hostAgentSessions.taskId, opts.taskId),
+        eq(schema.hostAgentSessions.agentId, opts.agentId),
+      ),
+    )
+    .get();
+  const persistOffset = (offset: number): void => {
+    db.update(schema.hostAgentSessions)
+      .set({ outboxOffset: offset, updatedAt: Date.now() })
+      .where(
+        and(
+          eq(schema.hostAgentSessions.taskId, opts.taskId),
+          eq(schema.hostAgentSessions.agentId, opts.agentId),
+        ),
+      )
+      .run();
+  };
+  const markClosed = (): void => {
+    db.update(schema.hostAgentSessions)
+      .set({ status: "closed", updatedAt: Date.now() })
+      .where(
+        and(
+          eq(schema.hostAgentSessions.taskId, opts.taskId),
+          eq(schema.hostAgentSessions.agentId, opts.agentId),
+        ),
+      )
+      .run();
+  };
+  const tailKey = `${opts.taskId}:${opts.agentId}`;
+
+  // ---- Attach: a previous host process left this machine's runner alive. --
+  // Freshness cannot be a sync stat over ssh; MachineDurableProcess probes
+  // the heartbeat immediately on attach and finishes fast when it is stale.
+  if (
+    opts.allowAttach &&
+    row &&
+    row.status === "running" &&
+    row.containerName === environment.durableIdentity &&
+    (row.attachCompatibilityKey ?? null) ===
+      (opts.attachCompatibilityKey ?? null)
+  ) {
+    const proc = new MachineDurableProcess({
+      environment,
+      sessionDir: row.sessionDir,
+      initialOutboxOffset: row.outboxOffset,
+      onOffsetAdvance: persistOffset,
+      onCloseRequested: markClosed,
+      debugLabel: opts.debugLabel,
+    });
+    proc.onExit(markClosed);
+    return claimTail(tailKey, proc);
+  }
+
+  // ---- Spawn a fresh runner, asking any predecessor to stop. --------------
+  const staleMachineSession =
+    row && row.containerName === environment.durableIdentity
+      ? row.sessionDir
+      : null;
+  const sessionDir = machineSessionDir(
+    environment.descriptor.workspacePath,
+    opts.agentId,
+  );
+  const proc = new MachineDurableProcess({
+    environment,
+    sessionDir,
+    onOffsetAdvance: persistOffset,
+    onCloseRequested: markClosed,
+    debugLabel: opts.debugLabel,
+    launch: async () => {
+      // Unconditional stop of a same-machine predecessor (see the container
+      // flow): a runner falsely marked closed may still be alive, and a stop
+      // appended to a dead session's inbox is harmless.
+      if (staleMachineSession) {
+        await stopMachinePredecessor(environment, staleMachineSession);
+      }
+      const runnerPath = await deployRunner(environment, sessionDir);
+      await publishMachineCurrentSession(environment, sessionDir);
+      const result = await environment.launchDetachedSession({
+        argv: [
+          "node",
+          runnerPath,
+          sessionDir,
+          "--",
+          opts.cli,
+          ...opts.cliArgs,
+        ],
+        inheritEnv: opts.passEnv ?? [],
+        env: opts.explicitEnv ?? {},
+        launchTimeoutMs: 30_000,
+        maxOutputBytes: 256 * 1024,
+      });
+      return { exitCode: result.exitCode, stderr: result.stderr };
+    },
+  });
+
+  const now = Date.now();
+  db.insert(schema.hostAgentSessions)
+    .values({
+      taskId: opts.taskId,
+      agentId: opts.agentId,
+      sessionDir,
+      containerName: environment.durableIdentity,
+      kind: opts.kind,
+      attachCompatibilityKey: opts.attachCompatibilityKey ?? null,
+      outboxOffset: 0,
+      status: "running",
+      createdAt: now,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [schema.hostAgentSessions.taskId, schema.hostAgentSessions.agentId],
+      set: {
+        sessionDir,
+        containerName: environment.durableIdentity,
+        kind: opts.kind,
+        attachCompatibilityKey: opts.attachCompatibilityKey ?? null,
+        outboxOffset: 0,
+        status: "running",
+        updatedAt: now,
+      },
+    })
+    .run();
+
+  proc.onExit(markClosed);
+  return claimTail(tailKey, proc);
+}
+
 function directEnvironmentTransport(opts: AgentTransportOptions): LineTransport {
   return new EnvironmentLineProcess({
     environment: opts.environment,

package/lib/orchestrator.ts

@@ -96,6 +96,7 @@ import {
   apiUrlFromCloudUrl,
   loadTaskCliSecret,
   writeAgentCli,
+  writeAgentCliViaEnvironment,
 } from "./agent-cli";
 import {
   DEFAULT_CODEX_HOME,
@@ -1370,6 +1371,13 @@ export class Orchestrator {
 
       for (const agent of missing) channel.spawning.add(agent.id);
       try {
+        // ADR-121: machine workspaces are only reachable through the
+        // environment handle — the docker-exec cold-start default would
+        // dial a container that does not exist. Settle the handle first.
+        if (task.environmentProvider === "machine") {
+          await this.agentEnvironment(channel).catch(() => {});
+          if (!this.isActiveChannel(channel)) return;
+        }
         // Same per-agent materialisation the initial start does. Browser setup
         // is awaited before EVERY missing-session spawn: that reasserts configs
         // clobbered by resume/auth injection and covers roster generation.
@@ -1402,8 +1410,8 @@ export class Orchestrator {
 
         const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
         const cliSecret = loadTaskCliSecret(channel.taskId);
-        const cliWritten = writeAgentCli(
-          channel.taskId,
+        const cliWritten = await materializeAgentCli(
+          task,
           roster,
           apiUrl,
           channel.mode === "secretary",
@@ -1698,6 +1706,14 @@ export class Orchestrator {
     // browser/MCP configuration, or runner creation can execute in Docker.
     await agentClisReady;
     if (!this.isActiveChannel(channel)) return false;
+    // ADR-121: machine workspaces are only reachable through the environment
+    // handle. Settle it before any materialization step below, so identity,
+    // skills, browser, and MCP writes all ride the provider surface instead
+    // of dialing a compose container that does not exist.
+    if (task.environmentProvider === "machine") {
+      await this.agentEnvironment(channel).catch(() => {});
+      if (!this.isActiveChannel(channel)) return false;
+    }
     // Freeze the generation before any slow docker work. A roster add while
     // setup awaits must reconcile under its own engine-aware browser pass,
     // not slip into this factory loop under the old generation's config.
@@ -1777,8 +1793,8 @@ export class Orchestrator {
     // are actually enforced. Best-effort, host-side.
     const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
     const cliSecret = loadTaskCliSecret(channel.taskId);
-    const cliWritten = writeAgentCli(
-      channel.taskId,
+    const cliWritten = await materializeAgentCli(
+      task,
       channel.roster,
       apiUrl,
       channel.mode === "secretary",
@@ -5619,6 +5635,35 @@ async function quarantineWritableAppleRuntimeContainers(options: {
 
 /** Dispatch one durable row through its provider. Generic boot orchestration
  * owns DB/lifecycle sequencing but never derives a Compose/container identity. */
+/**
+ * ADR-121: materialize the in-task uai CLI through whichever surface owns the
+ * workspace — host FS for container tasks, the environment transport for
+ * machine tasks (their workspace is not host-reachable). Best-effort like the
+ * host-side writer.
+ */
+async function materializeAgentCli(
+  task: typeof schema.hostTasks.$inferSelect,
+  roster: RosterAgent[],
+  apiUrl: string | null,
+  allowPermissionless: boolean,
+): Promise<boolean> {
+  if (task.environmentProvider === "machine") {
+    try {
+      const environment = await reconstructPersistedTaskEnvironment(task);
+      if (environment === null) return false;
+      return await writeAgentCliViaEnvironment(
+        environment,
+        roster,
+        apiUrl,
+        allowPermissionless,
+      );
+    } catch {
+      return false;
+    }
+  }
+  return writeAgentCli(task.taskId, roster, apiUrl, allowPermissionless);
+}
+
 async function recoverPersistedTaskEnvironment(
   task: typeof schema.hostTasks.$inferSelect,
   maintenanceReady: Promise<void>,

package/lib/runtime-state.ts

@@ -31,6 +31,11 @@ export function getHostTask(taskId: string): HostTask | null {
 
 /** Remove a provisional first-seen row when admission loses a lifecycle gate. */
 export function deleteHostTask(taskId: string): void {
+  // Row deletions are rare and load-bearing; a silent one cost a live
+  // machine-task forensic session (2026-08-27). Name the caller.
+  console.warn(
+    `[runtime-state] deleting host task row ${taskId}\n${(new Error().stack ?? "").split("\n").slice(2, 5).join("\n")}`,
+  );
   getDb()
     .delete(schema.hostTasks)
     .where(eq(schema.hostTasks.taskId, taskId))
@@ -41,6 +46,7 @@ export function deleteHostTask(taskId: string): void {
  * happen before this transaction; a SQLite failure leaves every task-owned
  * row intact rather than acknowledging a partial metadata deletion. */
 export function purgeHostTaskState(taskId: string): void {
+  console.warn(`[runtime-state] purging all host state for task ${taskId}`);
   getDb().transaction((tx) => {
     tx.delete(schema.hostAgentSessions)
       .where(eq(schema.hostAgentSessions.taskId, taskId))

package/lib/task-environment/index.ts

@@ -26,7 +26,10 @@ import { createAwsMachineProvider } from "../machine-provider-aws";
 import { createLocalMachineProvider } from "../machine-provider-local";
 import { ensureMachineKeyPair } from "../machine-keys";
 import { requestAccessToken } from "../github-tokens";
-import { createMachineTaskEnvironmentProvider } from "./machine";
+import {
+  createMachineTaskEnvironmentProvider,
+  MACHINE_TASK_ENVIRONMENT_PROVIDER,
+} from "./machine";
 import { createMachineHostTaskEnvironmentProvider } from "./machine-task-up";
 import { TaskEnvironmentRegistry } from "./registry";
 import {
@@ -307,6 +310,9 @@ export function persistedTaskEnvironmentsMatchMachine(
       };
     }
     if (locator === null) continue;
+    // ADR-121: machine locators name an ephemeral VM, not a container
+    // daemon — no container-runtime identity claim to verify.
+    if (locator.provider === MACHINE_TASK_ENVIRONMENT_PROVIDER) continue;
     try {
       const persisted = locatorMachineIdentity(locator);
       if (
@@ -375,6 +381,8 @@ export function hostTaskEnvironmentsAllowMachineSelection(
       if (locator.provider !== task.environmentProvider) {
         throw new Error("task environment provider does not match its locator");
       }
+      // ADR-121: machine rows make no container-runtime claim.
+      if (locator.provider === MACHINE_TASK_ENVIRONMENT_PROVIDER) continue;
       const persisted = locatorMachineIdentity(locator);
       if (
         persisted.backend !== machine.backend ||

package/lib/task-environment/legacy-adoption.ts

@@ -166,6 +166,12 @@ function legacyCandidate(
     // 2026-08-15): a crash-preserved prepared apple locator made adoption —
     // and with it runtime selection — fail closed, so the task could not
     // even be settled.
+    // ADR-121: machine-backed rows are not container-runtime residents at
+    // all — their locator names an ephemeral VM, not a docker/apple daemon.
+    // They must never wedge container-runtime selection (live 2026-08-27:
+    // the first machine task quarantined the whole VM runtime on reconnect,
+    // collapsing every host command into a retry storm).
+    if (locator.provider === "machine") return null;
     let persistedMachine: HostMachineIdentity;
     if (locator.provider === "docker-compose") {
       persistedMachine = parseDockerTaskEnvironmentLocator(locator).machine;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.71",
+  "version": "0.9.72",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

package/src/index.ts

@@ -957,6 +957,17 @@ export const hostCommands: HostCommands = {
       }
       const result = await wrapAgent(ctx, "taskDown", async () => {
         if (environment === null) return agent.taskDown(input);
+        // ADR-121: an ordinary stop of a machine task must keep the machine's
+        // disk — the workspace lives THERE, not on a host worktree the way
+        // compose teardown preserves it. Stop is the resumable gesture
+        // (provision restarts a stopped machine); only orphan GC terminates.
+        if (
+          !orphanGc &&
+          environment.descriptor.locator.provider === "machine"
+        ) {
+          await environment.stop();
+          return taskDownResultForInput(input, { status: "stopped" });
+        }
         return taskDownResultForInput(input, await environment.teardown());
       });
       if (result.ok) {