@runuai/host 0.9.120 → 0.9.121

package/lib/task-environment/self.ts

@@ -0,0 +1,346 @@
+/**
+ * ADR-133 sidecar mode: the task environment IS this machine.
+ *
+ * The runner runs on the task's own EC2 machine (`uai-host run --task`), so
+ * there is no container to exec into and no ssh hop to make: every request
+ * runs as a local child process, as user `node` (the runner itself is root
+ * so it can drop privileges, mount S3, and own the workspace), in the same
+ * shape the machine provider sends over ssh. `machine-task-up.ts` (clone,
+ * editor, browser) and `agents/machine-durable.ts` (durable agent sessions)
+ * take a handle, not a transport, so they run unchanged on top of this one.
+ *
+ * What is deliberately NOT here: launch/stop/terminate. The cloud owns the
+ * machine's lifecycle (hostless-implementation.md §7); `stop` and `teardown`
+ * are no-ops because a parked or closed task ends with the cloud stopping or
+ * terminating the instance this process lives on.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { buildRemoteCommand } from "../machine-exec";
+import { capturedCliExec, streamingCliExec } from "./docker";
+import type { MachineTaskInput } from "./machine";
+import {
+  assertTaskEnvironmentProcessRequest,
+  assertTaskEnvironmentSessionRequest,
+  assertWorkspaceScopedPath,
+  type TaskEnvironmentCopyRequest,
+  type TaskEnvironmentDescriptor,
+  type TaskEnvironmentDetachedSessionRequest,
+  type TaskEnvironmentExecRequest,
+  type TaskEnvironmentExecResult,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentLocator,
+  type TaskEnvironmentPort,
+  type TaskEnvironmentProcess,
+  type TaskEnvironmentProvider,
+  type TaskEnvironmentProvisionRequest,
+  type TaskEnvironmentProvisioned,
+  type TaskEnvironmentRecoveryContext,
+  type TaskEnvironmentRecoveryResult,
+  type TaskEnvironmentSessionRequest,
+  type TaskEnvironmentSpawnRequest,
+  type TaskEnvironmentStatus,
+  TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION,
+} from "./types";
+
+export const SELF_TASK_ENVIRONMENT_PROVIDER = "self";
+
+/** The task user every agent, editor, and shell runs as. */
+export const SELF_TASK_USER = "node";
+
+const SAFE_TASK_ID = /^[a-z0-9]{1,32}$/i;
+
+export interface SelfTaskEnvironmentLocatorValue {
+  taskId: string;
+  /** Absolute workspace path on this machine. */
+  workspacePath: string;
+}
+
+export interface SelfTaskEnvironmentDeps {
+  spawn?: typeof nodeSpawn;
+  /** Whether this process may drop privileges with setpriv (root). Tests and
+   * a non-root dev run keep everything as the current user. */
+  privileged?: () => boolean;
+}
+
+export function selfTaskEnvironmentLocator(
+  value: SelfTaskEnvironmentLocatorValue,
+): TaskEnvironmentLocator {
+  return {
+    schemaVersion: TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION,
+    provider: SELF_TASK_ENVIRONMENT_PROVIDER,
+    value: { taskId: value.taskId, workspacePath: value.workspacePath },
+  };
+}
+
+export function parseSelfTaskEnvironmentLocator(
+  locator: TaskEnvironmentLocator,
+): SelfTaskEnvironmentLocatorValue {
+  if (
+    locator.schemaVersion !== TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION ||
+    locator.provider !== SELF_TASK_ENVIRONMENT_PROVIDER ||
+    typeof locator.value !== "object" ||
+    locator.value === null
+  ) {
+    throw new Error("not a self task environment locator");
+  }
+  const value = locator.value as Record<string, unknown>;
+  if (
+    typeof value.taskId !== "string" ||
+    !SAFE_TASK_ID.test(value.taskId) ||
+    typeof value.workspacePath !== "string" ||
+    !value.workspacePath.startsWith("/") ||
+    value.workspacePath.includes("\0")
+  ) {
+    throw new Error("malformed self task environment locator");
+  }
+  return { taskId: value.taskId, workspacePath: value.workspacePath };
+}
+
+/**
+ * The local command for a request: the same `cd … && exec env … argv` shell
+ * line the machine provider ships over ssh, run through setpriv when this
+ * process is root and the request wants a task user. Values ride argv here
+ * exactly as they ride the ssh command line on a machine task — the machine
+ * is one task's trust domain (machine-exec.ts).
+ */
+export function selfCommand(
+  request: {
+    argv: readonly string[];
+    cwd?: string;
+    user?: string;
+    inheritEnv?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+  },
+  mode: "interactive" | "detached",
+  privileged: boolean,
+): { command: string; args: string[] } {
+  const line = buildRemoteCommand({ ...request, detached: mode === "detached" });
+  const user = request.user ?? SELF_TASK_USER;
+  if (privileged && user !== "root") {
+    return {
+      command: "/usr/bin/setpriv",
+      args: [
+        `--reuid=${user}`,
+        `--regid=${user}`,
+        "--init-groups",
+        "--reset-env",
+        "--",
+        "/bin/sh",
+        "-lc",
+        line,
+      ],
+    };
+  }
+  return { command: "/bin/sh", args: ["-lc", line] };
+}
+
+class SelfTaskEnvironmentHandle implements TaskEnvironmentHandle {
+  readonly descriptor: TaskEnvironmentDescriptor;
+  readonly durableIdentity: string;
+  readonly #value: SelfTaskEnvironmentLocatorValue;
+  readonly #spawn: typeof nodeSpawn;
+  readonly #privileged: () => boolean;
+
+  constructor(locator: TaskEnvironmentLocator, deps: SelfTaskEnvironmentDeps) {
+    this.#value = parseSelfTaskEnvironmentLocator(locator);
+    this.#spawn = deps.spawn ?? nodeSpawn;
+    this.#privileged =
+      deps.privileged ?? (() => typeof process.getuid === "function" && process.getuid() === 0);
+    this.durableIdentity = `self:${this.#value.taskId}`;
+    this.descriptor = {
+      taskId: this.#value.taskId,
+      locator,
+      workspacePath: this.#value.workspacePath,
+    };
+  }
+
+  async readWorkspaceFile(path: string): Promise<Uint8Array | null> {
+    assertWorkspaceScopedPath(this.descriptor, path);
+    try {
+      return new Uint8Array(await readFile(path));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+  }
+
+  async writeWorkspaceFile(path: string, bytes: Uint8Array): Promise<void> {
+    assertWorkspaceScopedPath(this.descriptor, path);
+    // Through the task user, so the file is owned like everything else the
+    // agents touch (a root-owned file inside the workspace is a trap).
+    const result = await this.exec({
+      argv: ["/bin/sh", "-c", 'mkdir -p "$(dirname "$1")" && cat > "$1"', "write", path],
+      stdin: bytes,
+      timeoutMs: 120_000,
+      maxOutputBytes: 1024 * 1024,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `workspace write failed: ${Buffer.from(result.stderr).toString("utf8").trim()}`,
+      );
+    }
+  }
+
+  async exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentProcessRequest(request);
+    const { command, args } = selfCommand(request, "interactive", this.#privileged());
+    return capturedCliExec(this.#spawn, command, args, request);
+  }
+
+  async spawn(request: TaskEnvironmentSpawnRequest): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentProcessRequest(request);
+    const { command, args } = selfCommand(request, "interactive", this.#privileged());
+    return streamingCliExec(this.#spawn, command, args, request);
+  }
+
+  async spawnSession(request: TaskEnvironmentSessionRequest): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentSessionRequest(request);
+    const session = { ...request, cwd: request.cwd ?? this.#value.workspacePath };
+    const { command, args } = selfCommand(session, "interactive", this.#privileged());
+    return streamingCliExec(this.#spawn, command, args, session);
+  }
+
+  async launchDetachedSession(
+    request: TaskEnvironmentDetachedSessionRequest,
+  ): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentSessionRequest(request);
+    const session = { ...request, cwd: request.cwd ?? this.#value.workspacePath };
+    const { command, args } = selfCommand(session, "detached", this.#privileged());
+    return capturedCliExec(this.#spawn, command, args, {
+      ...session,
+      timeoutMs: session.launchTimeoutMs,
+    });
+  }
+
+  async copy(request: TaskEnvironmentCopyRequest): Promise<void> {
+    if (
+      !request.source.startsWith("/") ||
+      !request.destination.startsWith("/") ||
+      request.source.includes("\0") ||
+      request.destination.includes("\0")
+    ) {
+      throw new Error("self copy paths must be absolute and NUL-free");
+    }
+    // Both sides are this machine. `cp -a` keeps directory trees intact
+    // (engine-account homes), and the result is chowned to the task user so
+    // the agents can read what was copied in for them.
+    const script =
+      request.direction === "into"
+        ? 'mkdir -p "$(dirname "$2")" && cp -a "$1" "$2" && chown -R node:node "$2"'
+        : 'mkdir -p "$(dirname "$2")" && cp -a "$1" "$2"';
+    const result = await this.exec({
+      argv: ["/bin/sh", "-c", script, "copy", request.source, request.destination],
+      user: "root",
+      timeoutMs: 5 * 60_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `self copy failed: ${Buffer.from(result.stderr).toString("utf8").trim()}`,
+      );
+    }
+  }
+
+  async ports(): Promise<TaskEnvironmentPort[]> {
+    return [];
+  }
+
+  /** Every tunnel dials loopback: the editor and preview servers listen on
+   * this machine, and the runner that answers the tunnel is this process. */
+  async inspectRoute(): Promise<{ kind: "running"; ipv4Address: string }> {
+    return { kind: "running", ipv4Address: "127.0.0.1" };
+  }
+
+  async status(): Promise<TaskEnvironmentStatus> {
+    return {
+      state: "running",
+      instances: [this.durableIdentity],
+      workspacePresent: existsSync(this.#value.workspacePath),
+    };
+  }
+
+  async recover(
+    context: TaskEnvironmentRecoveryContext,
+  ): Promise<TaskEnvironmentRecoveryResult> {
+    await context.maintenanceReady;
+    if (!context.isCurrent()) {
+      return { outcome: "deferred", detail: "runtime generation superseded" };
+    }
+    context.allowConsumers?.();
+    await context.ensureConsumersStarted?.();
+    if (!context.isCurrent()) {
+      await context.quarantineConsumers?.();
+      return { outcome: "deferred", detail: "runtime generation superseded" };
+    }
+    return { outcome: "recovered", status: await this.status() };
+  }
+
+  /** Parking is the cloud stopping this instance; nothing to do locally. */
+  async stop(): Promise<void> {}
+
+  /** Closing is the cloud terminating this instance; the workspace dies
+   * with it. Nothing is deleted here so a close that races a late read (a
+   * final diff, a transcript flush) still finds the files. */
+  async teardown(): Promise<void> {}
+}
+
+export function createSelfTaskEnvironmentProvider(
+  deps: SelfTaskEnvironmentDeps = {},
+): TaskEnvironmentProvider<MachineTaskInput, void, TaskEnvironmentDescriptor> {
+  return {
+    kind: SELF_TASK_ENVIRONMENT_PROVIDER,
+
+    // Takes the machine input shape so `createMachineHostTaskEnvironmentProvider`
+    // can sit on top unchanged; image/cpus/memory describe a machine the cloud
+    // already launched and are ignored here.
+    async provision(
+      request: TaskEnvironmentProvisionRequest<MachineTaskInput, void>,
+    ): Promise<TaskEnvironmentProvisioned<TaskEnvironmentDescriptor>> {
+      const { taskId, input } = request;
+      if (!SAFE_TASK_ID.test(taskId)) {
+        throw new Error("self provisioning refused an unsafe task id");
+      }
+      const workspacePath = input.workspacePath ?? "/workspace";
+      const locator = selfTaskEnvironmentLocator({ taskId, workspacePath });
+      await request.onPrepared?.(locator);
+      const handle = new SelfTaskEnvironmentHandle(locator, deps);
+      const prepare = await handle.exec({
+        argv: ["/bin/sh", "-c", 'mkdir -p "$1" && chown node:node "$1"', "prepare", workspacePath],
+        user: "root",
+        timeoutMs: 30_000,
+        maxOutputBytes: 64 * 1024,
+      });
+      if (prepare.exitCode !== 0) {
+        throw new Error(
+          `workspace preparation failed: ${Buffer.from(prepare.stderr).toString("utf8").trim()}`,
+        );
+      }
+      if (input.repo) {
+        const clone = await handle.exec({
+          argv: [
+            "/usr/bin/git",
+            "clone",
+            ...(input.repo.branch ? ["--branch", input.repo.branch] : []),
+            input.repo.url,
+            workspacePath,
+          ],
+          timeoutMs: 10 * 60_000,
+          maxOutputBytes: 4 * 1024 * 1024,
+        });
+        if (clone.exitCode !== 0) {
+          throw new Error(
+            `clone failed: ${Buffer.from(clone.stderr).toString("utf8").trim()}`,
+          );
+        }
+      }
+      return { handle, result: handle.descriptor };
+    },
+
+    async reconstruct(locator: TaskEnvironmentLocator): Promise<TaskEnvironmentHandle> {
+      return new SelfTaskEnvironmentHandle(locator, deps);
+    },
+  };
+}

package/lib/task-environment/types.ts

@@ -446,3 +446,16 @@ function assertJsonValue(value: unknown, depth: number): void {
   }
   throw new Error("task environment locator is not JSON-serializable");
 }
+
+/**
+ * Providers whose workspace is reached only through the environment
+ * transport — a machine over ssh (ADR-121) or this very machine in sidecar
+ * mode (ADR-133) — as opposed to a container the host can `docker exec` into
+ * or bind-mount. Every "is this a machine task?" branch in the host means
+ * exactly this, so it asks here rather than comparing one provider name.
+ */
+export function isEnvironmentTransportProvider(
+  provider: string | null | undefined,
+): boolean {
+  return provider === "machine" || provider === "self";
+}

package/package.json

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

package/src/cli.ts

@@ -132,7 +132,7 @@ async function main(): Promise<void> {
   const follow = rest.includes("--follow") || rest.includes("-f");
   switch (cmd) {
     case "run":
-      return cmdRun();
+      return cmdRun(rest);
     case "status":
       return cmdStatus();
     case "open":
@@ -190,7 +190,12 @@ function timestampServiceLogs(): void {
   }
 }
 
-async function cmdRun(): Promise<void> {
+async function cmdRun(rest: string[] = []): Promise<void> {
+  // ADR-133 sidecar mode: `uai-host run --task <id>` on the task's own
+  // machine. The flag becomes the environment the rest of the process asks
+  // (lib/sidecar.ts) — set before main.ts loads, since its boot reads it.
+  const sidecarTask = flagValue(rest, "--task");
+  if (sidecarTask) process.env.UAI_SIDECAR_TASK = sidecarTask;
   // Timestamped service logs: the ADR-106 live smoke burned an hour dating
   // undated scrollback. Applies to the service process only, not one-shot CLI
   // commands.

package/src/index.ts

@@ -184,6 +184,7 @@ export type {
   PreviewPortDeclaration,
   PreviewPortRuntime,
 } from "../lib/preview-ports";
+import { isEnvironmentTransportProvider } from "../lib/task-environment/types";
 
 export const hostEvents: HostEventStream = {
   subscribe(handler) {
@@ -479,7 +480,7 @@ export const hostCommands: HostCommands = {
         }
       } else if (
         existingTask?.statusMirror === "running" &&
-        existingTask.environmentProvider === "machine"
+        isEnvironmentTransportProvider(existingTask.environmentProvider)
       ) {
         // ADR-121: a machine-backed task revalidates through its own
         // provider — the compose fast path below speaks docker and would
@@ -894,7 +895,7 @@ export const hostCommands: HostCommands = {
         // the compose reconciler would probe for an app container, find none,
         // and silently skip. Reconnect re-injection for machines is a
         // follow-up alongside the machine recovery pass.
-        if (getHostTask(input.task.id)?.environmentProvider === "machine") {
+        if (isEnvironmentTransportProvider(getHostTask(input.task.id)?.environmentProvider)) {
           void machineTaskGithubAuth(
             input.task.id,
             input.task.ownerUserId,
@@ -1005,7 +1006,7 @@ export const hostCommands: HostCommands = {
         // with no consumer (owner, 2026-08-29 — 16 parked disks after one
         // evening of testing). The task branch lives on the remote; the
         // machine's disk is not a preservation surface once the task ends.
-        if (environment.descriptor.locator.provider === "machine") {
+        if (isEnvironmentTransportProvider(environment.descriptor.locator.provider)) {
           stopMachineGatewayTunnel(input.taskId);
         }
         return taskDownResultForInput(input, await environment.teardown());
@@ -1437,7 +1438,7 @@ export const hostCommands: HostCommands = {
       // tasks keep the direct host-FS write (their workspace is a bind
       // mount and the sync path is cheaper than a docker exec per message).
       const task = getHostTask(taskId);
-      if (task?.environmentProvider === "machine") {
+      if (isEnvironmentTransportProvider(task?.environmentProvider)) {
         const environment = await reconstructHostTaskEnvironment(taskId);
         if (environment) {
           await appendTranscriptViaEnvironment(

package/src/main.ts

@@ -248,6 +248,10 @@ import {
   isEngineAccountLabel,
   isEngineConnectKind,
 } from "./protocol";
+import { isEnvironmentTransportProvider } from "../lib/task-environment/types";
+import { LeaseManager } from "../lib/lease";
+import { sidecarMode, sidecarTaskId } from "../lib/sidecar";
+import { declareAgentClisReady } from "../lib/standard-image";
 
 setContainerRuntimeOperationalCheck(() => containerRuntimeProblem() === null);
 
@@ -457,24 +461,53 @@ migrateHostDb();
 // credential store. Import what this host lacks and upload what was never
 // mirrored, off the startup path — task-up resolves locally either way.
 configureEngineAccountStore({ hostId });
-void reconcileEngineAccountsFromStore({ hostId })
-  .then((r) => {
-    if (r.skipped) return;
-    console.log(
-      `[engine-accounts] credential store reconciled: ${r.imported} imported, ${r.uploaded} uploaded, ${r.removed} removed, ${r.errors} errors`,
-    );
-  })
-  .catch((error: unknown) => {
-    console.warn(
-      `[engine-accounts] credential store reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  });
+/** The credential-store reconciles. At boot on a host with its own AWS
+ * identity; after the first lease on a sidecar (ADR-133), which has no
+ * credentials before that. */
+function reconcileStores(): void {
+  void reconcileEngineAccountsFromStore({ hostId })
+    .then((r) => {
+      if (r.skipped) return;
+      console.log(
+        `[engine-accounts] credential store reconciled: ${r.imported} imported, ${r.uploaded} uploaded, ${r.removed} removed, ${r.errors} errors`,
+      );
+    })
+    .catch((error: unknown) => {
+      console.warn(
+        `[engine-accounts] credential store reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    });
+  void reconcileUserCredentialsFromStore()
+    .then((r) => {
+      if (r.skipped) return;
+      console.log(
+        `[user-credentials] credential store reconciled: ${r.imported} imported, ${r.uploaded} uploaded, ${r.removed} removed, ${r.errors} errors`,
+      );
+    })
+    .catch((error: unknown) => {
+      console.warn(
+        `[user-credentials] credential store reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    });
+  void reconcileProjectEnvFromStore()
+    .then((r) => {
+      if (r.skipped) return;
+      console.log(
+        `[project-env] credential store reconciled: ${r.imported} imported, ${r.uploaded} uploaded, ${r.removed} removed, ${r.errors} errors`,
+      );
+    })
+    .catch((error: unknown) => {
+      console.warn(
+        `[project-env] credential store reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    });
+}
 // Image + agent-CLI maintenance runs where the compute is owned: an owned
 // host keeps its own image current on an hourly schedule (a task-up reuses
 // the last pass instead of blocking on one); a Uai-operated host sets
 // UAI_IMAGE_MAINTENANCE=external — a cloud job keeps the payload AMI fresh —
-// and reconciles only once, at start.
-if (env.UAI_IMAGE_MAINTENANCE === "host") {
+// and reconciles only once, at start. A sidecar (ADR-133) has no image.
+if (env.UAI_IMAGE_MAINTENANCE === "host" && !sidecarMode()) {
   const maintenanceTimer = setInterval(() => {
     void ensureStandardImage().catch(() => undefined);
   }, MAINTENANCE_INTERVAL_MS);
@@ -489,38 +522,50 @@ const repushBrokeredCopies = async (kind: string): Promise<void> => {
   await getOrchestrator().refreshEngineAccountCopies(kind);
 };
 configureTokenBroker({ repush: repushBrokeredCopies });
-startTokenBrokerLoop();
-startCredentialStorePickup({ repush: repushBrokeredCopies });
-void reconcileUserCredentialsFromStore()
-  .then((r) => {
-    if (r.skipped) return;
-    console.log(
-      `[user-credentials] credential store reconciled: ${r.imported} imported, ${r.uploaded} uploaded, ${r.removed} removed, ${r.errors} errors`,
-    );
-  })
-  .catch((error: unknown) => {
-    console.warn(
-      `[user-credentials] credential store reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  });
-void reconcileProjectEnvFromStore()
-  .then((r) => {
-    if (r.skipped) return;
-    console.log(
-      `[project-env] credential store reconciled: ${r.imported} imported, ${r.uploaded} uploaded, ${r.removed} removed, ${r.errors} errors`,
-    );
-  })
-  .catch((error: unknown) => {
-    console.warn(
-      `[project-env] credential store reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  });
+// ADR-133: a sidecar never refreshes sign-ins (the broker Lambda does), and
+// reads the store only once it holds a lease — see leaseManager below.
+if (!sidecarMode()) {
+  startTokenBrokerLoop();
+  startCredentialStorePickup({ repush: repushBrokeredCopies });
+  reconcileStores();
+}
+/**
+ * ADR-133 sidecar: the task-scoped AWS lease. Requested when the bridge is
+ * ready, refreshed before expiry; the first grant is what lets the store
+ * reconciles and the S3 file mounts run. A denial means the task is no
+ * longer ours to run — exit 3 and let the cloud's sweep reclaim the machine.
+ */
+const leaseManager: LeaseManager | null = sidecarMode()
+  ? new LeaseManager({
+      taskId: sidecarTaskId()!,
+      send: (frame) => {
+        if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+        send(ws, frame);
+        return true;
+      },
+      onFirstGrant: () => {
+        console.log("[lease] granted — reconciling the credential store");
+        reconcileStores();
+        startCredentialStorePickup({ repush: repushBrokeredCopies });
+      },
+      onGrant: (lease) => {
+        console.log(
+          `[lease] holds until ${new Date(lease.expiresAt).toISOString()}`,
+        );
+      },
+      onDenied: (error) => {
+        console.error(`[lease] denied: ${error} — this machine no longer runs its task`);
+        process.exit(3);
+      },
+    })
+  : null;
+if (sidecarMode()) declareAgentClisReady();
 // Reconcile a durable retention-off setting before recovery/connect can make
 // crash-left owner-facing terminal history observable again. Correctness
 // tombstones remain intact inside applyTerminalHistoryRetention.
 applyTerminalHistoryRetention();
 try {
-  await configureBundledContainerRuntime();
+  if (!sidecarMode()) await configureBundledContainerRuntime();
 } catch {
   // A malformed/tampered active generation must never fall back to PATH or an
   // inferred asset layout. Keep Docker-first operation available and surface
@@ -529,7 +574,17 @@ try {
     "[host-agent] signed bundled runtime validation failed; the bundled runtime is disabled",
   );
 }
-const initialRuntime = await initializeContainerRuntime();
+const initialRuntime: Awaited<ReturnType<typeof initializeContainerRuntime>> =
+  sidecarMode()
+    ? // ADR-133: a task machine runs its agents directly; nothing here ever
+      // dials a container runtime.
+      {
+        status: "no-runtime",
+        preference: "auto",
+        message: "sidecar mode — no container runtime on a task machine",
+        action: "none: a task machine runs its agents directly",
+      }
+    : await initializeContainerRuntime();
 // Do not touch the selected daemon merely because detection succeeded. The
 // activation gate below must first prove that every durable TaskEnvironment
 // belongs to this exact provider/endpoint. The manager's first admitted login
@@ -612,12 +667,16 @@ const stopAgentClisReadySubscription = onAgentClisReady(() =>
 void connect();
 // Local browser UI (ADR-028) — same single process, alongside the WSS client.
 // Best-effort: a UI bind failure must not take the host service down.
-void startLocalUi();
+// A task machine has no operator sitting at it (ADR-133): no local UI, no
+// Mac vnode watch.
+if (!sidecarMode()) void startLocalUi();
 // ADR-118 follow-up: vnode-pressure observability (macOS/apple-container
 // hosts). Logs only on band transitions; the sensor caches its sysctl read.
-const vnodePressureTimer = setInterval(() => void logVnodePressure(), 60_000);
-vnodePressureTimer.unref?.();
-void logVnodePressure();
+if (!sidecarMode()) {
+  const vnodePressureTimer = setInterval(() => void logVnodePressure(), 60_000);
+  vnodePressureTimer.unref?.();
+  void logVnodePressure();
+}
 
 async function startLocalUi(): Promise<void> {
   try {
@@ -717,6 +776,7 @@ function buildCapabilities(): HostCapabilities {
           },
         }
       : {}),
+    ...(sidecarTaskId() ? { sidecar: { taskId: sidecarTaskId()! } } : {}),
     maintenanceReady: areAgentClisReady(),
     mcpGateway: mcpGateway.state(),
     engineLogins: engineLoginManager.capabilities(),
@@ -1206,6 +1266,7 @@ async function connect(): Promise<void> {
     reconnectAttempt = 0;
     markConnected();
     console.log(`[host-agent] connected as ${hostId}`);
+    leaseManager?.reconnected();
     setHostObsTag(hostId);
     addHostBreadcrumb("bridge", "connected");
 
@@ -1405,6 +1466,10 @@ async function connect(): Promise<void> {
       case "tunnel.close":
         closeTunnel(socket, frame.tunnelId, frame.reason);
         break;
+      case "lease.grant":
+      case "lease.deny":
+        leaseManager?.handle(frame);
+        break;
       case "gh.connect.set": {
         const runtimeProblem = containerRuntimeProblem();
         if (runtimeProblem) {
@@ -2141,7 +2206,7 @@ async function resolveTunnelTarget(
   // 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") {
+  if (machineTask && isEnvironmentTransportProvider(machineTask.environmentProvider)) {
     // 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
@@ -3100,6 +3165,9 @@ function rejectFrameDuringShutdown(
     case "tunnel.data":
     case "tunnel.requestEnd":
     case "tunnel.close":
+    // A lease answer is housekeeping the sidecar still wants during a drain.
+    case "lease.grant":
+    case "lease.deny":
       return false;
   }
 }