@runuai/host 0.9.71 → 0.9.73

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,507 @@
+/**
+ * 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, `launch exited ${result.exitCode}`);
+          }
+        },
+        (error: unknown) => {
+          this.#stderrBuf = (
+            this.#stderrBuf +
+            (error instanceof Error ? error.message : String(error))
+          ).slice(-8192);
+          this.#finish(null, "launch threw");
+        },
+      );
+    } 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,
+        "runner exit meta",
+      );
+    }
+  }
+
+  // ---- 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, "no spawn meta within grace");
+        }
+        return;
+      }
+      const fresh = await machineHeartbeatFresh(
+        this.#environment,
+        this.#sessionDir,
+        HEARTBEAT_STALE_MS,
+      );
+      if (this.#closed || this.#detached) return;
+      if (!fresh) this.#finish(null, "heartbeat stale");
+    } finally {
+      this.#probing = false;
+    }
+  }
+
+  #finish(code: number | null, reason = "unspecified"): void {
+    if (this.#closed) return;
+    // Session deaths are load-bearing and were undiagnosable without this
+    // (live 2026-08-27: a 65s recycle loop with no trace). Always log.
+    console.warn(
+      `[machine-durable] session ${this.#sessionDir} finished (code ${code ?? "null"}): ${reason}`,
+    );
+    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 elapsed"),
+      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/machine-exec.ts

@@ -84,12 +84,20 @@ export function buildRemoteCommand(request: {
   const command = request.argv.map(shellQuote).join(" ");
   if (request.detached) {
     // Detached durable sessions manage their own transcript IO (runner.mjs);
-    // the launch just needs the process to survive this ssh connection:
-    // setsid detaches the controlling terminal, streams are severed, and the
-    // remote shell exits immediately with the launch verdict.
-    parts.push(`${envPrefix}setsid ${command} </dev/null >/dev/null 2>&1 &`);
-    parts.push("exit 0");
-    return parts.join(" ");
+    // the launch just needs the process to survive this ssh connection AND
+    // the connection to close immediately. The redirects must cover the
+    // WHOLE background job and the job must `exec` into the payload: with
+    // redirects on the inner command only, the waiting shell kept the ssh
+    // channel's stdout/stderr open until the runner died, so sshd never saw
+    // EOF and every launch rode its timeout into a false spawn failure
+    // (live 2026-08-27: a 65s session recycle loop on the second machine
+    // task; the first machine's stable session was an accident of its host
+    // dying seconds before the timeout could mark the row closed).
+    const body = [
+      ...(request.cwd ? [`cd ${shellQuote(request.cwd)} &&`] : []),
+      `exec ${envPrefix}setsid ${command}`,
+    ].join(" ");
+    return `{ ${body}; } </dev/null >/dev/null 2>&1 & exit 0`;
   }
   parts.push(`exec ${envPrefix}${command}`);
   return parts.join(" ");

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/lib/task-environment/machine-task-up.ts

@@ -15,12 +15,19 @@
  * directory that really does hold this task's host-side state — its machine
  * key). Consumers that need the workspace go through the environment handle.
  */
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
 import type {
   TaskDownResult,
   TaskLaunchInput,
   TaskUpCredentials,
   TaskUpResult,
 } from "../agent";
+import { sharedRoot } from "../shared-files";
 import {
   MACHINE_TASK_ENVIRONMENT_PROVIDER,
   parseMachineTaskEnvironmentLocator,
@@ -36,6 +43,9 @@ import type {
 
 /** In-machine clone budget per project. */
 const CLONE_TIMEOUT_MS = 10 * 60_000;
+/** The machine port code-server listens on (dialed directly by the editor
+ * tunnel via inspectRoute; never published). */
+export const MACHINE_CODE_SERVER_PORT = 8080;
 const GIT_STEP_TIMEOUT_MS = 60_000;
 const STEP_OUTPUT_BYTES = 256 * 1024;
 
@@ -223,6 +233,191 @@ async function cloneProject(
   return null;
 }
 
+/** The curated code-server defaults (slim chrome, telemetry off, trust
+ * off) — the SAME seed the standard image bakes; resolved from this package
+ * so machine and container editors can never diverge. Machines adjust two
+ * keys host-side: the task's ADR-091 theme, and bash for the terminal (the
+ * machine payload carries no zsh). */
+function editorSettingsSeed(editorTheme: string | undefined): string {
+  const seedPath = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "images",
+    "standard",
+    "container",
+    "code-server-settings.json",
+  );
+  const seed = JSON.parse(readFileSync(seedPath, "utf8")) as Record<
+    string,
+    unknown
+  >;
+  if (editorTheme) seed["workbench.colorTheme"] = editorTheme;
+  seed["terminal.integrated.defaultProfile.linux"] = "bash";
+  return `${JSON.stringify(seed, null, 2)}\n`;
+}
+
+/** Seed the editor settings exactly once (an existing settings.json is the
+ * user's own state and is never touched — same contract as uai-init). */
+async function seedEditorSettings(
+  handle: TaskEnvironmentHandle<unknown>,
+  editorTheme: string | undefined,
+): Promise<void> {
+  const destination =
+    "/home/node/.local/share/code-server/User/settings.json";
+  await handle.exec({
+    argv: [
+      "/bin/sh",
+      "-c",
+      '[ -e "$1" ] && exit 0; mkdir -p "$(dirname "$1")" && cat > "$1"',
+      "seed",
+      destination,
+    ],
+    stdin: Buffer.from(editorSettingsSeed(editorTheme)),
+    timeoutMs: GIT_STEP_TIMEOUT_MS,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+}
+
+const execFileAsync = promisify(execFile);
+/** Shared-files snapshots are reference docs, not repos; a tree past this
+ * is skipped with a warning rather than ballooning host memory. */
+const SHARED_FILES_TAR_MAX_BYTES = 256 * 1024 * 1024;
+
+/**
+ * ADR-062 shared files on machines: containers get live bind mounts at
+ * /workspace/files/{org,me}; a machine shares no filesystem, so it gets a
+ * POINT-IN-TIME COPY at provision (tar streamed over the transport). The
+ * managed-hosting answer for live semantics is EFS (ADR-121); until then a
+ * snapshot with an honest note beats silently absent files.
+ * Returns a warning string when rw mode was requested (writes cannot sync
+ * back) or a scope was skipped; null when clean.
+ */
+async function copySharedFiles(
+  handle: TaskEnvironmentHandle<unknown>,
+  workspacePath: string,
+  task: { ownerOrgId?: string; ownerUserId: string; sharedFiles?: string },
+): Promise<string | null> {
+  const mode = task.sharedFiles ?? "ro";
+  if (mode === "off") return null;
+  const scopes: Array<{ host: string; destination: string }> = [];
+  if (task.ownerOrgId) {
+    scopes.push({
+      host: sharedRoot("org", task.ownerOrgId, task.ownerUserId),
+      destination: `${workspacePath}/files/org`,
+    });
+  }
+  scopes.push({
+    host: sharedRoot("me", task.ownerOrgId ?? "", task.ownerUserId),
+    destination: `${workspacePath}/files/me`,
+  });
+  const warnings: string[] = [];
+  let copiedAny = false;
+  for (const scope of scopes) {
+    if (!existsSync(scope.host) || readdirSync(scope.host).length === 0) {
+      continue;
+    }
+    try {
+      const tarball = await execFileAsync(
+        "tar",
+        ["-C", scope.host, "-cf", "-", "."],
+        { encoding: "buffer", maxBuffer: SHARED_FILES_TAR_MAX_BYTES },
+      );
+      const result = await handle.exec({
+        argv: [
+          "/bin/sh",
+          "-c",
+          'mkdir -p "$1" && tar -C "$1" -xf -',
+          "shared",
+          scope.destination,
+        ],
+        stdin: tarball.stdout,
+        timeoutMs: 5 * 60_000,
+        maxOutputBytes: STEP_OUTPUT_BYTES,
+      });
+      if (result.exitCode !== 0) {
+        throw new Error(
+          `extract exited ${result.exitCode}: ${Buffer.from(result.stderr).toString("utf8").trim()}`,
+        );
+      }
+      copiedAny = true;
+    } catch (error) {
+      warnings.push(
+        `shared files: could not copy ${scope.destination}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+  if (copiedAny || warnings.length === 0) {
+    // Marker gates the "## Shared files" preamble briefing, mirroring the
+    // container path's task-up marker.
+    await handle
+      .writeWorkspaceFile(`${workspacePath}/.uai/files-mounted`, Buffer.from(""))
+      .catch(() => {});
+  }
+  if (mode === "rw") {
+    warnings.push(
+      "shared files on this machine task are a point-in-time copy — " +
+        "changes under /workspace/files will NOT sync back to the host yet",
+    );
+  }
+  return warnings.length > 0 ? warnings.join("\n") : null;
+}
+
+/** Launch code-server for the Editor pane, exactly once. The pgrep guard
+ * makes re-provision and resume idempotent; the exec chain leaves only
+ * code-server holding the detached job. */
+async function ensureCodeServer(
+  handle: TaskEnvironmentHandle<unknown>,
+  workspacePath: string,
+  editorTheme: string | undefined,
+): Promise<void> {
+  // Settings before process: code-server reads them at startup. A failed
+  // seed still launches — a themed editor is worth less than one that starts.
+  await seedEditorSettings(handle, editorTheme).catch((error: unknown) => {
+    console.warn(
+      `[machine] editor settings seed failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  });
+  // The guard and the launch are SEPARATE execs on purpose: any guard that
+  // shares a cmdline with the launch text matches itself — the bracketed
+  // pattern alone did not save the first combined script, because the plain
+  // launch line later in the same argv still contained code-server +
+  // --bind-addr (live 2026-08-27, second silent skip).
+  const running = await handle.exec({
+    argv: [
+      "/bin/sh",
+      "-c",
+      'pgrep -f "[c]ode-server.*--bind-addr" >/dev/null 2>&1',
+    ],
+    timeoutMs: GIT_STEP_TIMEOUT_MS,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  if (running.exitCode === 0) return;
+  const script =
+    "mkdir -p /home/node/.local/share/code-server && " +
+    "exec /home/node/.local/bin/code-server " +
+    "--user-data-dir /home/node/.local/share/code-server " +
+    "--disable-workspace-trust --auth none --disable-telemetry " +
+    `--disable-update-check --bind-addr 0.0.0.0:${MACHINE_CODE_SERVER_PORT} ` +
+    '"$1" >/tmp/code-server.log 2>&1';
+  const result = await handle.launchDetachedSession({
+    argv: ["/bin/sh", "-c", script, "code-server", workspacePath],
+    inheritEnv: [],
+    env: {},
+    launchTimeoutMs: 30_000,
+    maxOutputBytes: 64 * 1024,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `code-server launch exited ${result.exitCode}: ${Buffer.from(result.stderr).toString("utf8").trim()}`,
+    );
+  }
+}
+
 /** Wrap the void-teardown machine handle so registry consumers get the
  * TaskDownResult contract the compose providers speak. */
 function withTaskDownResult(
@@ -249,6 +444,9 @@ function withTaskDownResult(
       await handle.teardown();
       return { status: "terminated" };
     },
+    ...(handle.inspectRoute
+      ? { inspectRoute: () => handle.inspectRoute!() }
+      : {}),
   };
 }
 
@@ -311,6 +509,36 @@ export function createMachineHostTaskEnvironmentProvider(
         throw error;
       }
 
+      // ADR-062 shared files: point-in-time copy (see copySharedFiles).
+      const sharedWarning = await copySharedFiles(handle, workspacePath, {
+        ...(input.task.ownerOrgId ? { ownerOrgId: input.task.ownerOrgId } : {}),
+        ownerUserId: input.task.ownerUserId,
+        ...(input.task.sharedFiles ? { sharedFiles: input.task.sharedFiles } : {}),
+      }).catch((error: unknown) => {
+        console.warn(
+          `[machine] task ${request.taskId}: shared files copy failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+        return null;
+      });
+      if (sharedWarning) warnings.push(sharedWarning);
+
+      // Editor pane: code-server on the machine (same flags as uai-init's
+      // container launch), idempotent across provision re-runs and resume.
+      // Best-effort — a missing binary degrades the Editor tab, never the task.
+      await ensureCodeServer(
+        handle,
+        workspacePath,
+        input.task.previewEnv?.UAI_EDITOR_THEME,
+      ).catch((error: unknown) => {
+        console.warn(
+          `[machine] task ${request.taskId}: code-server launch failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      });
+
       const machineId = parseMachineTaskEnvironmentLocator(
         handle.descriptor.locator,
       ).machineId;
@@ -319,6 +547,7 @@ export function createMachineHostTaskEnvironmentProvider(
         result: {
           composeProject: machineId,
           worktreePath: deps.taskControlDir(request.taskId),
+          codeServerPort: MACHINE_CODE_SERVER_PORT,
           ...(warnings.length > 0
             ? { initWarning: warnings.join("\n") }
             : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.71",
+  "version": "0.9.73",
   "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

@@ -475,6 +475,7 @@ export const hostCommands: HostCommands = {
                 value: {
                   composeProject: existingTask.composeProject ?? "",
                   worktreePath: existingTask.worktreePath ?? "",
+                  codeServerPort: existingTask.codeServerPort ?? undefined,
                 },
               };
             }
@@ -957,6 +958,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) {

package/src/main.ts

@@ -1966,6 +1966,26 @@ async function resolveTunnelTarget(
   // Persisted ports are meaningful only while the selected runtime is known
   // operational. After a daemon restart an unrelated local process could bind
   // a stale port before recovery refreshes the task's mappings.
+  const machineTask = getHostTask(frame.taskId);
+  if (machineTask?.environmentProvider === "machine") {
+    // ADR-121: a machine's address is orchestrator-routable (bridge IP on
+    // the Linux guinea pig, VPC-private on EC2) — editor and previews dial
+    // it straight via the handle's ownership-proven route, independent of
+    // the container runtime's health. macOS-local machines need a published
+    // fallback (bridge IPs are not host-routable there) — recorded ADR-121
+    // follow-up, not silently misrouted: the connect simply fails.
+    const environment = await reconstructPersistedTaskEnvironment(machineTask);
+    const route = environment?.inspectRoute
+      ? await environment.inspectRoute()
+      : null;
+    if (!route || route.kind !== "running") return null;
+    const port =
+      frame.target === "editor"
+        ? (machineTask.codeServerPort ?? null)
+        : (frame.containerPort ?? null);
+    if (!port) return null;
+    return { host: route.ipv4Address, port };
+  }
   if (containerRuntimeProblem()) return null;
   const task = getHostTask(frame.taskId);
   if (!task) return null;