@moondeck/station 0.0.1 → 1.0.1

package/lib/agents/transport.ts

@@ -0,0 +1,741 @@
+/**
+ * Agent transport selection (ADR-061). Adapters call createAgentTransport()
+ * where they used to build a LineProcess directly; it returns either:
+ *
+ *  - provider-owned interactive pipes when
+ *    UAI_DURABLE_SESSIONS=0, or
+ *  - the durable path: an in-container runner owning the CLI, driven through
+ *    inbox/outbox files on the workspace mount (DurableProcess).
+ *
+ * Durable mode makes host restarts transparent WITHOUT orchestrator
+ * changes: the orchestrator's lazy respawn calls factory.create as always,
+ * and this helper quietly ATTACHES to a still-live runner (fresh heartbeat +
+ * a `running` host_agent_sessions row) at the persisted outbox offset
+ * instead of spawning a new CLI — the agent's in-memory context survives.
+ * Adapters that re-handshake per process (codex) pass allowAttach:false and
+ * get a fresh runner each create — the stale predecessor is asked to stop
+ * via its inbox first.
+ *
+ * The runner script is COPIED into each session dir (not bind-mounted):
+ * the task environment sees the workspace at its provider path, so each
+ * durable spawn ships the runner version matching this host.
+ */
+
+import { readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import { and, eq, isNull } from "drizzle-orm";
+
+import { getDb, schema, type Db } from "../db";
+import { taskWorkspaceDir } from "../env";
+import { machineSessionAuthorityEnv } from "../runtime-authority";
+import { requireContainerRuntimeOperational } from "../runtime-guard";
+import type { TaskEnvironmentAgentSessionSurface, TaskEnvironmentHandle } from "../task-environment/types";
+import {
+  appendContainedFile,
+  containedModifiedAt,
+  hostPathParts,
+  makeContainedDirectories,
+  makeContainedDirectoriesSync,
+  removeContainedEntry,
+  readContainedFrom,
+  replaceContainedLink,
+  runtimeNamespaceOf,
+  writeContainedFile,
+  writeContainedFileSync,
+  type RuntimeNamespace,
+} from "../task-environment/workspace-files";
+import { DurableProcess, runnerScriptPath } from "./durable-proc";
+import {
+  MachineDurableProcess,
+  deployRunner,
+  machineSessionDir,
+  publishMachineCurrentSession,
+  stopMachinePredecessor,
+  type MachineSessionEnvironment,
+} from "./machine-durable";
+import {
+  AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+  EnvironmentLineProcess,
+  type ExitHandler,
+  type LineHandler,
+} from "./proc";
+import { agentCliArgv } from "../agent-cli";
+import { isEnvironmentTransportProvider } from "../task-environment/types";
+import { attachCompatibilityKeysMatch } from "./attach-compatibility";
+
+/** The shared surface adapters program against (LineProcess's shape). */
+export interface LineTransport {
+  /** Exact durable row generation owned by this transport, when durable. */
+  readonly durableSessionDir?: string;
+  onLine(handler: LineHandler): void;
+  onExit(handler: ExitHandler): void;
+  writeLine(value: unknown): void;
+  readonly stderrTail: string;
+  readonly isClosed: boolean;
+  close(): Promise<void>;
+}
+
+export interface AgentTransportOptions {
+  taskId: string;
+  agentId: string;
+  environment: TaskEnvironmentAgentSessionSurface;
+  /** CLI + literal argv as observed inside the task environment. */
+  cli: string;
+  cliArgs: string[];
+  /** Env names forwarded from the host's own environment. */
+  passEnv?: string[];
+  /** Explicit per-session environment values. */
+  explicitEnv?: Record<string, string>;
+  /**
+   * Whether a live runner from a previous host process may be attached to.
+   * True for stateless adapters (claude); false for ones whose host-side
+   * protocol state can't outlive the host process (codex handshake).
+   */
+  allowAttach: boolean;
+  /** Host-owned launch-settings generation. Both absent remains compatible. */
+  attachCompatibilityKey?: string;
+  kind: string;
+  debugLabel?: string;
+  /** Restore adapter counters from already-consumed output, before an attach
+   * resumes delivery. No historical line is emitted again. */
+  restoreProtocolState?: {
+    accepts(line: string): boolean;
+    restore(lines: readonly string[], complete: boolean): void;
+  };
+}
+
+/** Bounded recovery: absence beyond this window is unknown, never zero. */
+export const PROTOCOL_HISTORY_BYTES = 8 * 1024 * 1024;
+
+function restoreProtocolWindow(
+  state: NonNullable<AgentTransportOptions["restoreProtocolState"]>,
+  bytes: Buffer | null,
+  offset: number,
+): void {
+  if (!bytes || !Number.isSafeInteger(offset) || offset < 0 ||
+      bytes.length !== Math.min(offset, PROTOCOL_HISTORY_BYTES) ||
+      (bytes.length > 0 && bytes.at(-1) !== 10)) {
+    state.restore([], false);
+    return;
+  }
+  const complete = offset <= PROTOCOL_HISTORY_BYTES;
+  let text = bytes.toString("utf8");
+  // The window may begin inside a line (or a UTF-8 code point).
+  if (!complete) text = text.slice(text.indexOf("\n") + 1);
+  // Rebuild counter state in order: the final raw result can itself be stale.
+  state.restore(text.split("\n").filter(line => state.accepts(line)), complete);
+}
+
+/** Linux machine workspace read, pinned to the saved checkpoint. Open every
+ * component relative to its directory fd, without following task-made links;
+ * read only the bounded suffix of the already-consumed prefix. */
+const MACHINE_PROTOCOL_HISTORY_READ = String.raw`
+const fs = require("node:fs"), path = require("node:path");
+const [root, file, offsetText, limitText] = process.argv.slice(1);
+const offset = Number(offsetText), limit = Number(limitText);
+const parts = path.relative(root, file).split(path.sep);
+if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 ||
+    parts.some(p => !p || p === ".." || p === ".")) process.exit(1);
+let fd;
+try {
+  fd = fs.openSync(root, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+  for (let i = 0; i < parts.length; i++) {
+    const next = fs.openSync("/proc/self/fd/" + fd + "/" + parts[i], fs.constants.O_RDONLY |
+      fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK | (i + 1 < parts.length ? fs.constants.O_DIRECTORY : 0));
+    fs.closeSync(fd); fd = next;
+  }
+  const stat = fs.fstatSync(fd);
+  if (!stat.isFile() || stat.size < offset) process.exitCode = 1;
+  else {
+    const start = Math.max(0, offset - limit), out = Buffer.alloc(offset - start);
+    let done = 0;
+    while (done < out.length) {
+      const n = fs.readSync(fd, out, done, out.length - done, start + done);
+      if (!n) throw new Error("short read");
+      done += n;
+    }
+    process.stdout.write(out);
+  }
+} catch { process.exitCode = 1; }
+finally { if (fd !== undefined) fs.closeSync(fd); }
+`;
+
+async function restoreMachineProtocolState(
+  opts: AgentTransportOptions,
+  environment: MachineSessionEnvironment,
+  sessionDir: string,
+  offset: number,
+): Promise<void> {
+  const state = opts.restoreProtocolState;
+  if (!state) return;
+  if (offset === 0) { state.restore([], true); return; }
+  let bytes: Buffer | null = null;
+  try {
+    const result = await environment.exec({
+      argv: ["node", "-e", MACHINE_PROTOCOL_HISTORY_READ, environment.descriptor.workspacePath,
+        join(sessionDir, "outbox.jsonl"), String(offset), String(PROTOCOL_HISTORY_BYTES)],
+      projectEnvProfile: "maintenance",
+      timeoutMs: 30_000,
+      maxOutputBytes: PROTOCOL_HISTORY_BYTES,
+    });
+    if (result.exitCode === 0 && !result.stdoutTruncated) bytes = Buffer.from(result.stdout);
+  } catch { /* Unknown history must not turn a cumulative total into a charge. */ }
+  restoreProtocolWindow(state, bytes, offset);
+}
+
+/** Runner heartbeat is 5 s; older than this = not attachable. */
+const ATTACH_HEARTBEAT_FRESH_MS = 20_000;
+
+/**
+ * ONE live outbox consumer per (task, agent) in this host process. A session
+ * dropped from the orchestrator's map without close()/detach() (e.g. the
+ * error-event path — a pipes-era "process is dead" assumption) leaves its
+ * DurableProcess polling FOREVER: its liveness check only trips when the
+ * RUNNER dies, and the runner is alive. The next channelEnsure then attaches
+ * a second tail to the same outbox, and every agent turn is emitted once per
+ * leaked tail — live incident 2026-07-20: one agent's messages posted ×5 to
+ * the feed, multiplicity growing by one per errored turn. Enforcing the
+ * invariant here covers every replacement path, including future ones.
+ */
+interface DetachableTail extends LineTransport {
+  detach(): void;
+}
+
+const liveTails = new Map<string, DetachableTail>();
+
+export function durableAgentSessionId(taskId: string, agentId: string): string | undefined {
+  const tail = liveTails.get(`${taskId}:${agentId}`);
+  return tail && !tail.isClosed ? tail.durableSessionDir : undefined;
+}
+
+function claimTail<T extends DetachableTail>(key: string, proc: T): T {
+  liveTails.get(key)?.detach();
+  liveTails.set(key, proc);
+  return proc;
+}
+
+function durableEnabled(): boolean {
+  return process.env.UAI_DURABLE_SESSIONS !== "0";
+}
+
+/** Durable rows are keyed by task + agent for lookup, but callbacks belong to
+ * one exact generation. A delayed offset/exit from the predecessor must never
+ * mutate the replacement row after its upsert. */
+function durableRowCallbacks(
+  db: Db,
+  taskId: string,
+  agentId: string,
+  sessionDir: string,
+): {
+  persistOffset(offset: number): void;
+  markClosed(): void;
+} {
+  const ownedRow = () =>
+    and(
+      eq(schema.hostAgentSessions.taskId, taskId),
+      eq(schema.hostAgentSessions.agentId, agentId),
+      eq(schema.hostAgentSessions.sessionDir, sessionDir),
+    );
+  return {
+    persistOffset(offset: number): void {
+      db.update(schema.hostAgentSessions)
+        .set({ outboxOffset: offset, updatedAt: Date.now() })
+        .where(ownedRow())
+        .run();
+    },
+    markClosed(): void {
+      db.update(schema.hostAgentSessions)
+        .set({ status: "closed", updatedAt: Date.now() })
+        .where(ownedRow())
+        .run();
+    },
+  };
+}
+
+/** Claim a compatible durable row and promote a one-release legacy key to the
+ * rich launch fingerprint. The exact generation/key fence prevents a stale
+ * host process from rewriting a replacement row after reading its snapshot. */
+function claimCompatibleAttachRow(
+  db: Db,
+  taskId: string,
+  agentId: string,
+  sessionDir: string,
+  stored: string | null | undefined,
+  desired: string | null | undefined,
+): boolean {
+  if (!attachCompatibilityKeysMatch(stored, desired)) return false;
+  const storedKey = stored ?? null;
+  const desiredKey = desired ?? null;
+  if (storedKey === desiredKey) return true;
+  if (desiredKey === null) return false;
+  const result = db
+    .update(schema.hostAgentSessions)
+    .set({ attachCompatibilityKey: desiredKey, updatedAt: Date.now() })
+    .where(
+      and(
+        eq(schema.hostAgentSessions.taskId, taskId),
+        eq(schema.hostAgentSessions.agentId, agentId),
+        eq(schema.hostAgentSessions.sessionDir, sessionDir),
+        storedKey === null
+          ? isNull(schema.hostAgentSessions.attachCompatibilityKey)
+          : eq(schema.hostAgentSessions.attachCompatibilityKey, storedKey),
+      ),
+    )
+    .run();
+  return result.changes === 1;
+}
+
+export function createAgentTransport(opts: AgentTransportOptions): LineTransport {
+  // Connection stderr/provider errors may contain arbitrary credentials.
+  if (opts.explicitEnv?.UAI_CUSTOM_CONNECTION === "1") opts = { ...opts, debugLabel: undefined };
+  // 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 (isEnvironmentTransportProvider(opts.environment.descriptor.locator.provider)) {
+    // The session env was assembled with the CONTAINER runtime authority
+    // (asdf/corepack pins to shared read-only volumes) — on a machine those
+    // paths do not exist and the pins actively break package managers.
+    // Swap in the machine authority; credentials and task env pass through.
+    const machineOpts: AgentTransportOptions = {
+      ...opts,
+      explicitEnv: machineSessionAuthorityEnv(opts.explicitEnv),
+    };
+    if (!durableEnabled()) {
+      clearCurrentSession(machineOpts.taskId, machineOpts.agentId, workspaceRuntime(machineOpts.environment));
+      return directEnvironmentTransport(machineOpts);
+    }
+    return machineDurableTransport(machineOpts);
+  }
+  // Session creation can happen after channel/task lifecycle queues drain, well
+  // after the command-level runtime preflight. Recheck at the actual attach or
+  // spawn boundary so a cached ready verdict cannot launch container work.
+  requireContainerRuntimeOperational();
+  if (!durableEnabled()) {
+    clearCurrentSession(opts.taskId, opts.agentId, workspaceRuntime(opts.environment));
+    return directEnvironmentTransport(opts);
+  }
+
+  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 tailKey = `${opts.taskId}:${opts.agentId}`;
+
+  const runtime = workspaceRuntime(opts.environment);
+  const rowFiles = row ? sessionFilesOf(opts.taskId, row.sessionDir) : null;
+
+  // ---- Attach: a previous host process left this agent's runner alive. ----
+  if (
+    opts.allowAttach &&
+    row &&
+    rowFiles &&
+    row.status === "running" &&
+    row.containerName === opts.environment.durableIdentity &&
+    row.kind === opts.kind &&
+    heartbeatFresh(rowFiles) &&
+    claimCompatibleAttachRow(
+      db,
+      opts.taskId,
+      opts.agentId,
+      row.sessionDir,
+      row.attachCompatibilityKey,
+      opts.attachCompatibilityKey,
+    )
+  ) {
+    if (opts.restoreProtocolState) {
+      let bytes: Buffer | null = null;
+      try {
+        const start = Math.max(0, row.outboxOffset - PROTOCOL_HISTORY_BYTES);
+        const prior = readContainedFrom(rowFiles.root, [...rowFiles.parts, "outbox.jsonl"], start,
+          row.outboxOffset - start);
+        if (prior && prior.size >= row.outboxOffset) bytes = prior.bytes;
+        else if (row.outboxOffset === 0) bytes = Buffer.alloc(0);
+      } catch { /* A missing/refused history remains unknown. */ }
+      restoreProtocolWindow(opts.restoreProtocolState, bytes, row.outboxOffset);
+    }
+    const { persistOffset, markClosed } = durableRowCallbacks(
+      db,
+      opts.taskId,
+      opts.agentId,
+      row.sessionDir,
+    );
+    const proc = new DurableProcess({
+      hostSessionDir: row.sessionDir,
+      sessionFiles: rowFiles,
+      initialOutboxOffset: row.outboxOffset,
+      onOffsetAdvance: persistOffset,
+      onCloseRequested: markClosed,
+      debugLabel: opts.debugLabel,
+    });
+    proc.onExit(markClosed);
+    publishCurrentSession(rowFiles, runtime);
+    return claimTail(tailKey, proc);
+  }
+
+  // ---- Spawn a fresh runner, asking any predecessor to stop. --------------
+  // Unconditional (not gated on row.status): a runner falsely marked closed
+  // by a stale-heartbeat verdict may still be alive, and a stop appended to
+  // a dead session's inbox is harmless — this is what guarantees one live
+  // CLI per (task, agent).
+  if (rowFiles) {
+    void appendContainedFile(rowFiles.root, [...rowFiles.parts, "inbox.jsonl"], Buffer.from('{"__uai":"stop"}\n')).catch(
+      () => {
+        // Dir already gone / runner already dead — nothing to stop.
+      },
+    );
+  }
+
+  const workspace = taskWorkspaceDir(opts.taskId);
+  const sessionFiles = {
+    root: workspace,
+    parts: [".moondeck", "sessions", opts.agentId, `${String(Date.now())}-${process.pid}`],
+  };
+  const sessionDir = join(workspace, ...sessionFiles.parts);
+  const environmentSessionDir = join(
+    opts.environment.descriptor.workspacePath,
+    ".moondeck",
+    "sessions",
+    opts.agentId,
+    basename(sessionDir),
+  );
+  const { persistOffset, markClosed } = durableRowCallbacks(
+    db,
+    opts.taskId,
+    opts.agentId,
+    sessionDir,
+  );
+  const runnerInEnvironment = join(environmentSessionDir, "runner.mjs");
+  let runnerSource: Buffer;
+  try {
+    runnerSource = readFileSync(runnerScriptPath());
+  } catch (err) {
+    // Runner asset missing (a packaging miss — the 0.3.0/0.3.1 desktop
+    // builds vendored the agent without runner/). Degrade to legacy pipes:
+    // sessions work, they just don't survive host restarts.
+    console.warn(
+      `[transport] station unavailable (${err instanceof Error ? err.message : err}) — falling back to direct pipes for ${opts.agentId}`,
+    );
+    clearCurrentSession(opts.taskId, opts.agentId, workspaceRuntime(opts.environment));
+    return directEnvironmentTransport(opts);
+  }
+
+  // Ship this host's runner with the session: works in containers created
+  // before this feature (the workspace is mounted at its host path) and
+  // never skews against the host version. Its directory and the runner are
+  // made in the task's workspace never through a link the task put there
+  // (#cb3j0z), before the runner launches.
+  // On Linux both are made at once; on macOS the directory is made through
+  // the task's runtime first.
+  let preparedNow = false;
+  let prepared: Promise<void>;
+  try {
+    if (makeContainedDirectoriesSync(workspace, sessionFiles.parts)) {
+      writeContainedFileSync(workspace, [...sessionFiles.parts, "runner.mjs"], runnerSource);
+      preparedNow = true;
+      prepared = Promise.resolve();
+    } else {
+      prepared = (async () => {
+        await makeContainedDirectories(workspace, sessionFiles.parts, runtime);
+        await writeContainedFile(workspace, [...sessionFiles.parts, "runner.mjs"], runnerSource);
+      })();
+    }
+  } catch (error) {
+    prepared = Promise.reject(error);
+  }
+  prepared.catch(() => {
+    // Reported through the launch, which awaits it.
+  });
+  const proc = new DurableProcess({
+    hostSessionDir: sessionDir,
+    sessionFiles,
+    ...(preparedNow ? {} : { ready: prepared }),
+    onOffsetAdvance: persistOffset,
+    onCloseRequested: markClosed,
+    debugLabel: opts.debugLabel,
+    launch: async () => {
+      await prepared;
+      const cliArgv = agentCliArgv(opts.environment, [opts.cli, ...opts.cliArgs]);
+      const result = await opts.environment.launchDetachedSession({
+        argv: [
+          "node",
+          runnerInEnvironment,
+          environmentSessionDir,
+          "--",
+          ...cliArgv,
+        ],
+        projectEnvProfile: "task",
+        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: opts.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: opts.environment.durableIdentity,
+        kind: opts.kind,
+        attachCompatibilityKey: opts.attachCompatibilityKey ?? null,
+        outboxOffset: 0,
+        status: "running",
+        updatedAt: now,
+      },
+    })
+    .run();
+
+  proc.onExit(markClosed);
+  if (preparedNow) publishCurrentSession(sessionFiles, runtime);
+  else void prepared.then(() => publishCurrentSession(sessionFiles, runtime), () => {});
+  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] station unavailable (${err instanceof Error ? err.message : err}) — falling back to direct pipes for ${opts.agentId}`,
+      );
+    }
+  }
+  if (!capable || runnerSource === null) {
+    clearCurrentSession(opts.taskId, opts.agentId, workspaceRuntime(opts.environment));
+    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 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.kind === opts.kind &&
+    claimCompatibleAttachRow(
+      db,
+      opts.taskId,
+      opts.agentId,
+      row.sessionDir,
+      row.attachCompatibilityKey,
+      opts.attachCompatibilityKey,
+    )
+  ) {
+    const { persistOffset, markClosed } = durableRowCallbacks(
+      db,
+      opts.taskId,
+      opts.agentId,
+      row.sessionDir,
+    );
+    const proc = new MachineDurableProcess({
+      environment,
+      sessionDir: row.sessionDir,
+      initialOutboxOffset: row.outboxOffset,
+      ...(opts.restoreProtocolState ? {
+        ready: restoreMachineProtocolState(opts, environment, row.sessionDir, 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 { persistOffset, markClosed } = durableRowCallbacks(
+    db,
+    opts.taskId,
+    opts.agentId,
+    sessionDir,
+  );
+  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 cliArgv = agentCliArgv(environment, [opts.cli, ...opts.cliArgs]);
+      const result = await environment.launchDetachedSession({
+        argv: [
+          "node",
+          runnerPath,
+          sessionDir,
+          "--",
+          ...cliArgv,
+        ],
+        projectEnvProfile: "task",
+        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,
+    request: {
+      argv: agentCliArgv(opts.environment, [opts.cli, ...opts.cliArgs]),
+      projectEnvProfile: "task",
+      inheritEnv: opts.passEnv ?? [],
+      env: opts.explicitEnv ?? {},
+      maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+    },
+    debugLabel: opts.debugLabel,
+  });
+}
+
+/** #cb3j0z: the task's runtime, where only it can make, remove or link an
+ *  entry in the task's workspace without following its links (macOS). */
+function workspaceRuntime(environment: TaskEnvironmentAgentSessionSurface): RuntimeNamespace | undefined {
+  return "exec" in environment
+    ? runtimeNamespaceOf(environment as unknown as Pick<TaskEnvironmentHandle, "exec" | "descriptor">)
+    : undefined;
+}
+
+/** A stored session directory as the task's workspace root and its parts
+ *  below it; null when it is not below the workspace root. */
+function sessionFilesOf(taskId: string, sessionDir: string): { root: string; parts: string[] } | null {
+  const root = taskWorkspaceDir(taskId);
+  try {
+    return { root, parts: hostPathParts(root, sessionDir) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Make the opaque generation directory discoverable from inside the task.
+ * The relative link resolves on both sides of the workspace bind mount. The
+ * pointer is diagnostic only: failure to publish it must not kill a session.
+ * Made beside the generation, never through a link the task put there.
+ */
+function publishCurrentSession(files: { root: string; parts: readonly string[] }, runtime?: RuntimeNamespace): void {
+  const generation = files.parts[files.parts.length - 1]!;
+  void replaceContainedLink(files.root, [...files.parts.slice(0, -1), "current"], generation, runtime).catch(() => {
+    // Best-effort navigation aid; the generation path remains authoritative.
+  });
+}
+
+/** A direct-pipe session must not leave an older durable inbox looking live. */
+function clearCurrentSession(taskId: string, agentId: string, runtime?: RuntimeNamespace): void {
+  void removeContainedEntry(taskWorkspaceDir(taskId), [".moondeck", "sessions", agentId, "current"], runtime).catch(() => {
+    // Same best-effort rule as publishCurrentSession.
+  });
+}
+
+function heartbeatFresh(files: { root: string; parts: readonly string[] }): boolean {
+  try {
+    const beat = containedModifiedAt(files.root, [...files.parts, "heartbeat"]);
+    return beat !== null && Date.now() - beat < ATTACH_HEARTBEAT_FRESH_MS;
+  } catch {
+    return false;
+  }
+}