@moondeck/station 0.0.1 → 1.0.1

package/lib/task-environment/registry.ts

@@ -0,0 +1,59 @@
+import type {
+  ProjectEnvMode,
+  TaskEnvironmentLocator,
+  TaskEnvironmentProvider,
+} from "./types";
+
+/**
+ * Provider registry kept instance-based for tests and future multi-provider
+ * hosts. Registration is explicit; reconstructing an unknown/newer provider
+ * fails closed rather than guessing Docker.
+ */
+export class TaskEnvironmentRegistry<
+  TInput,
+  TCredentials,
+  TResult,
+  TTeardownResult = void,
+> {
+  readonly #providers = new Map<
+    string,
+    TaskEnvironmentProvider<TInput, TCredentials, TResult, TTeardownResult>
+  >();
+
+  register(
+    provider: TaskEnvironmentProvider<
+      TInput,
+      TCredentials,
+      TResult,
+      TTeardownResult
+    >,
+  ): () => void {
+    if (this.#providers.has(provider.kind)) {
+      throw new Error(`task environment provider ${provider.kind} is already registered`);
+    }
+    this.#providers.set(provider.kind, provider);
+    return () => {
+      if (this.#providers.get(provider.kind) === provider) {
+        this.#providers.delete(provider.kind);
+      }
+    };
+  }
+
+  provider(
+    kind: string,
+  ): TaskEnvironmentProvider<TInput, TCredentials, TResult, TTeardownResult> {
+    const provider = this.#providers.get(kind);
+    if (!provider) {
+      throw new Error(`task environment provider ${kind} is unavailable`);
+    }
+    return provider;
+  }
+
+  reconstruct(locator: TaskEnvironmentLocator, envMode: ProjectEnvMode = "baked") {
+    return this.provider(locator.provider).reconstruct(locator, envMode);
+  }
+
+  kinds(): string[] {
+    return [...this.#providers.keys()].sort();
+  }
+}

package/lib/task-environment/self-identity.ts

@@ -0,0 +1,20 @@
+/**
+ * The `self` provider's fixed names: a Uai Cloud machine's own task, run by
+ * the sidecar on that machine (ADR-133). A module with no imports, so the
+ * secrets proxy can name them without loading the provider, which reaches it
+ * back through the agent.
+ */
+
+export const SELF_TASK_ENVIRONMENT_PROVIDER = "self";
+
+/** The task user every agent, editor, and shell runs as. */
+export const SELF_TASK_USER = "node";
+
+/**
+ * A task process's own view of the hosts on its machine (ADR-153): the
+ * machine's /etc/hosts plus the secrets proxy's pins, which the root
+ * sidecar's own processes must never resolve. Every process the sidecar
+ * starts as the task user gets it bind-mounted over /etc/hosts, in a mount
+ * namespace of its own that still follows the machine's mounts.
+ */
+export const TASK_HOSTS_VIEW_PATH = "/run/uai/task-hosts";

package/lib/task-environment/self.ts

@@ -0,0 +1,566 @@
+/**
+ * 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, readFileSync } from "node:fs";
+
+import { buildRemoteCommand } from "../machine-exec";
+import {
+  applyProjectEnvProfile,
+  PROJECT_ENV_PROFILE_ENV_NAMES,
+} from "../runtime-authority";
+import { capturedCliExec, streamingCliExec } from "./docker";
+import type { MachineTaskInput } from "./machine";
+import {
+  assertTaskEnvironmentExecRequest,
+  assertTaskEnvironmentProcessRequest,
+  refusePrivilegedExec,
+  assertTaskEnvironmentSessionRequest,
+  assertWorkspaceScopedPath,
+  type TaskEnvironmentCallOptions,
+  type TaskEnvironmentReadOptions,
+  type TaskEnvironmentCopyRequest,
+  type TaskEnvironmentDescriptor,
+  type TaskEnvironmentDetachedSessionRequest,
+  type TaskEnvironmentExecRequest,
+  type TaskEnvironmentExecResult,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentLocator,
+  type TaskEnvironmentPort,
+  type TaskEnvironmentProcess,
+  type ProjectEnvMode,
+  type TaskEnvironmentProvider,
+  type TaskEnvironmentProvisionRequest,
+  type TaskEnvironmentProvisioned,
+  type TaskEnvironmentRecoveryContext,
+  type TaskEnvironmentRecoveryResult,
+  type TaskEnvironmentSessionRequest,
+  type TaskEnvironmentSpawnRequest,
+  type TaskEnvironmentStatus,
+  TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION,
+} from "./types";
+import {
+  BASELINE_PATH,
+  ETC_ENVIRONMENT_PATH,
+  parseEtcEnvironment,
+  withoutEngineCredentials,
+  withoutLaunchSecrets,
+} from "./machine-environment";
+import { SELF_TASK_ENVIRONMENT_PROVIDER, SELF_TASK_USER, TASK_HOSTS_VIEW_PATH } from "./self-identity";
+import { readBoundedFile, workspacePathParts } from "./workspace-files";
+import { assertTaskFilesMachineProcessAllowed } from "../task-files-machine-retirement";
+
+export { ETC_ENVIRONMENT_PATH, parseEtcEnvironment, SELF_TASK_ENVIRONMENT_PROVIDER, SELF_TASK_USER, TASK_HOSTS_VIEW_PATH };
+
+/**
+ * A terminal Files failure latches before its synchronous handler runs. Check
+ * on both sides of a caller's own admission callback so that callback cannot
+ * trigger retirement and then let this launch repopulate the cgroup the
+ * handler just emptied. JavaScript runs the final check and node spawn in one
+ * turn, so no other callback can interleave between them.
+ */
+function admitTaskMachineCall(admit?: () => void): void {
+  assertTaskFilesMachineProcessAllowed();
+  admit?.();
+  assertTaskFilesMachineProcessAllowed();
+}
+
+/**
+ * Binds the view, then runs the rest of its argv. With no view yet (nothing
+ * pinned so far: a start whose CA failed, the proxy off), it first makes one,
+ * a copy of the machine's file, so every task process has the view bound
+ * from its start and a later pin, rewritten into it in place, reaches them
+ * all. Made whole under another name and linked in, so it never shows half
+ * written and never replaces one made meanwhile. A view that cannot be
+ * bound fails the start: the task never runs with the proxy half in place.
+ */
+const TASK_VIEW_SCRIPT = [
+  "PATH=/usr/sbin:/usr/bin:/sbin:/bin; view=$1; shift",
+  'if [ ! -f "$view" ]; then',
+  '  umask 022; dir=${view%/*}; mkdir -p "$dir"',
+  '  tmp=$(mktemp "$dir/.task-hosts.XXXXXX") || exit 126',
+  '  cat /etc/hosts > "$tmp" && chmod 0644 "$tmp" && ln "$tmp" "$view" 2>/dev/null; rm -f "$tmp"',
+  "fi",
+  'mount --bind "$view" /etc/hosts || exit 126',
+  'exec "$@"',
+].join("\n");
+
+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;
+  /** The machine-wide environment every request runs under (beneath its own
+   * `env`). Defaults to /etc/environment — see `readEtcEnvironment`. */
+  etcEnvironment?: () => Readonly<Record<string, string>>;
+  /** Tests only: start an anchored launch without the drop to the task
+   * user, so the supervisor and what it carries are the test user's own. No
+   * isolation boundary: never a runner's (ADR-154 §6). */
+  anchorWithoutIsolationForTests?: boolean;
+}
+
+/*
+ * /etc/environment (parseEtcEnvironment). The machine provider gets it for
+ * free — sshd applies pam_env to every session — but a local
+ * `setpriv --reset-env … sh -lc` sees neither pam nor the file, so
+ * `PLAYWRIGHT_BROWSERS_PATH` from the payload image never reached an agent
+ * on the sidecar and every task re-downloaded Chromium (2026-09-10, smoke 6).
+ */
+let etcEnvironmentCache: Record<string, string> | null = null;
+/** The parsed /etc/environment, read once per process (the image writes it
+ * at bake time; nothing edits it on a task machine). Empty when absent. */
+export function readEtcEnvironment(): Record<string, string> {
+  if (etcEnvironmentCache) return etcEnvironmentCache;
+  try {
+    etcEnvironmentCache = parseEtcEnvironment(readFileSync(ETC_ENVIRONMENT_PATH, "utf8"));
+  } catch {
+    etcEnvironmentCache = {};
+  }
+  return etcEnvironmentCache;
+}
+
+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) — except a leased engine's
+ * credentials, which its admission carries to the injector this line runs
+ * after its drop (ADR-154 §6).
+ */
+export function selfCommand(
+  request: {
+    argv: readonly string[];
+    cwd?: string;
+    user?: string;
+    inheritEnv?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+    anchor?: { readonly prefix: readonly [string, ...string[]]; readonly injector?: readonly string[] };
+  },
+  mode: "interactive" | "detached",
+  privileged: boolean,
+): { command: string; args: string[] } {
+  const line = buildRemoteCommand({ ...request, detached: mode === "detached" });
+  const outerProfileEnv = PROJECT_ENV_PROFILE_ENV_NAMES.flatMap((name) => {
+    const value = request.env?.[name];
+    return value === undefined ? [] : [`${name}=${value}`];
+  });
+  const shellCommand =
+    outerProfileEnv.length === 0
+      ? { command: "/bin/sh", args: ["-lc", line] }
+      : {
+          command: "/usr/bin/env",
+          args: [...outerProfileEnv, "/bin/sh", "-lc", line],
+        };
+  const user = request.user ?? SELF_TASK_USER;
+  // ADR-154 §6: an anchored process starts under the engine supervisor, as
+  // root inside the task's view, which then runs the drop to the task user
+  // itself ("-": setpriv drops it). What the launch carries is read by the
+  // injector right after that drop, into the environment setpriv reset.
+  const anchor = request.anchor ? [...request.anchor.prefix, "-", "--"] : [];
+  const injector = request.anchor?.injector ?? [];
+  if (request.anchor && user === "root") {
+    throw new Error("an anchored process runs as a task user, never as root");
+  }
+  if (privileged && user !== "root") {
+    return {
+      command: "/usr/bin/unshare",
+      args: [
+        "--mount",
+        "--propagation",
+        "slave",
+        "--",
+        "/bin/sh",
+        "-c",
+        TASK_VIEW_SCRIPT,
+        "uai-task-view",
+        TASK_HOSTS_VIEW_PATH,
+        ...anchor,
+        "/usr/bin/setpriv",
+        `--reuid=${user}`,
+        `--regid=${user}`,
+        "--init-groups",
+        "--reset-env",
+        "--",
+        ...injector,
+        shellCommand.command,
+        ...shellCommand.args,
+      ],
+    };
+  }
+  if (anchor.length > 0) {
+    return {
+      command: anchor[0]!,
+      args: [...anchor.slice(1), ...injector, shellCommand.command, ...shellCommand.args],
+    };
+  }
+  return shellCommand;
+}
+
+/**
+ * ADR-154 §6: what an anchored launch starts from, instead of this runner's
+ * own environment (its host credential, its AWS keys): neither the engine
+ * supervisor nor the engine it starts inherits anything of the runner's.
+ * The drop resets it again for the task user; the launch's own line and
+ * login shell give the engine the rest.
+ */
+const ANCHORED_LAUNCH_ENV: NodeJS.ProcessEnv = Object.freeze({ PATH: BASELINE_PATH });
+
+class SelfTaskEnvironmentHandle implements TaskEnvironmentHandle {
+  readonly descriptor: TaskEnvironmentDescriptor;
+  readonly durableIdentity: string;
+  /** ADR-154 §6: a request's environment rides a local shell line, so a
+   *  leased launch's engine credentials travel in its admission. */
+  readonly credentialDelivery = "admission";
+  readonly #value: SelfTaskEnvironmentLocatorValue;
+  readonly #spawn: typeof nodeSpawn;
+  readonly #privileged: () => boolean;
+  readonly #etcEnvironment: () => Readonly<Record<string, string>>;
+  readonly #anchorWithoutIsolation: boolean;
+
+  constructor(
+    locator: TaskEnvironmentLocator,
+    deps: SelfTaskEnvironmentDeps,
+    envMode: ProjectEnvMode,
+  ) {
+    this.#value = parseSelfTaskEnvironmentLocator(locator);
+    this.#spawn = deps.spawn ?? nodeSpawn;
+    this.#privileged =
+      deps.privileged ?? (() => typeof process.getuid === "function" && process.getuid() === 0);
+    this.#etcEnvironment = deps.etcEnvironment ?? readEtcEnvironment;
+    this.#anchorWithoutIsolation = deps.anchorWithoutIsolationForTests === true;
+    this.durableIdentity = `self:${this.#value.taskId}`;
+    this.descriptor = {
+      taskId: this.#value.taskId,
+      locator,
+      envMode,
+      workspacePath: this.#value.workspacePath,
+    };
+  }
+
+  async readWorkspaceFile(path: string, options?: TaskEnvironmentReadOptions): Promise<Uint8Array | null> {
+    assertWorkspaceScopedPath(this.descriptor, path);
+    admitTaskMachineCall(options?.admit);
+    return readBoundedFile(this.descriptor.workspacePath, workspacePathParts(this.descriptor, path), options);
+  }
+
+  async writeWorkspaceFile(path: string, bytes: Uint8Array, options?: TaskEnvironmentCallOptions): 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],
+      projectEnvProfile: "maintenance",
+      stdin: bytes,
+      timeoutMs: 120_000,
+      maxOutputBytes: 1024 * 1024,
+      ...(options?.admit ? { admit: options.admit } : {}),
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `workspace write failed: ${Buffer.from(result.stderr).toString("utf8").trim()}`,
+      );
+    }
+  }
+
+  /** ADR-154 §6: anchored requests start under the engine supervisor, only
+   * where it runs as root and the engine as the task user: otherwise the
+   * supervisor, and what a launch carries, would be the task user's own. */
+  get anchors(): boolean {
+    return this.#privileged() || this.#anchorWithoutIsolation;
+  }
+
+  /** The command for `request`, and the environment it starts with: an
+   *  anchored one starts from the explicit baseline, never this runner's,
+   *  and only where the supervisor is isolated from the task user. */
+  #command(
+    request: Parameters<typeof selfCommand>[0],
+    mode: "interactive" | "detached",
+  ): { command: string; args: string[]; env?: NodeJS.ProcessEnv } {
+    if (request.anchor && !this.anchors) {
+      throw new Error("an anchored launch needs the drop to the task user, as root");
+    }
+    const { command, args } = selfCommand(request, mode, this.#privileged());
+    return request.anchor ? { command, args, env: ANCHORED_LAUNCH_ENV } : { command, args };
+  }
+
+  /** The request with the machine-wide environment beneath its own: what an
+   * ssh session on a machine task gets from pam_env, applied here by hand,
+   * never an engine's credential (ADR-154 §6), and for an anchored launch,
+   * whose secrets come from its admission, no secret of the machine's at
+   * all: its environment rides the local command line. */
+  #withMachineEnv<
+    T extends {
+      env?: Readonly<Record<string, string>>;
+      projectEnvProfile: "maintenance" | "task";
+      anchor?: unknown;
+    },
+  >(request: T): T {
+    const etc = this.#etcEnvironment();
+    const base = request.anchor ? withoutLaunchSecrets(etc) : withoutEngineCredentials(etc);
+    const withMachineEnv =
+      Object.keys(base).length === 0
+        ? request
+        : { ...request, env: { ...base, ...request.env } };
+    return applyProjectEnvProfile(
+      withMachineEnv,
+      this.descriptor.envMode ?? "baked",
+      "/bin/bash",
+    );
+  }
+
+  async exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentExecRequest(request);
+    refusePrivilegedExec(request);
+    const scoped = this.#withMachineEnv(request);
+    const { command, args, env } = this.#command(scoped, "interactive");
+    admitTaskMachineCall(request.admit);
+    return capturedCliExec(this.#spawn, command, args, scoped, env);
+  }
+
+  async spawn(request: TaskEnvironmentSpawnRequest): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentProcessRequest(request);
+    const scoped = this.#withMachineEnv(request);
+    const { command, args, env } = this.#command(scoped, "interactive");
+    admitTaskMachineCall(request.admit);
+    return streamingCliExec(this.#spawn, command, args, scoped, env);
+  }
+
+  async spawnSession(request: TaskEnvironmentSessionRequest): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentSessionRequest(request);
+    const session = this.#withMachineEnv({
+      ...request,
+      cwd: request.cwd ?? this.#value.workspacePath,
+    });
+    const { command, args, env } = this.#command(session, "interactive");
+    admitTaskMachineCall(request.admit);
+    return streamingCliExec(this.#spawn, command, args, session, env);
+  }
+
+  async launchDetachedSession(
+    request: TaskEnvironmentDetachedSessionRequest,
+  ): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentSessionRequest(request);
+    const session = this.#withMachineEnv({
+      ...request,
+      cwd: request.cwd ?? this.#value.workspacePath,
+    });
+    const { command, args, env } = this.#command(session, "detached");
+    admitTaskMachineCall(request.admit);
+    return capturedCliExec(
+      this.#spawn,
+      command,
+      args,
+      {
+        ...session,
+        timeoutMs: session.launchTimeoutMs,
+      },
+      env,
+    );
+  }
+
+  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. A directory source lands as the
+    // destination's CONTENTS, the way the machine provider's tar stream
+    // does: engine-account provisioning pre-creates the destination, and a
+    // plain `cp -a dir dest` into an existing dest nests `dest/dir/…`, so
+    // CODEX_HOME / GROK_HOME pointed at a dir without auth.json and both
+    // engines ran signed out and silent (live 2026-09-10, first codex + grok
+    // agents on a task machine). A file source copies as before. The result
+    // is chowned to the task user when this process is root, so the agents
+    // can read what was copied in for them.
+    const copy =
+      'if [ -d "$1" ]; then mkdir -p "$2" && cp -a "$1/." "$2/"; ' +
+      'else mkdir -p "$(dirname "$2")" && cp -a "$1" "$2"; fi';
+    const script =
+      request.direction === "into" && this.#privileged()
+        ? `${copy} && chown -R ${SELF_TASK_USER}:${SELF_TASK_USER} "$2"`
+        : copy;
+    const result = await this.exec({
+      argv: ["/bin/sh", "-c", script, "copy", request.source, request.destination],
+      user: "root",
+      projectEnvProfile: "maintenance",
+      timeoutMs: 5 * 60_000,
+      maxOutputBytes: 64 * 1024,
+      ...(request.admit ? { admit: request.admit } : {}),
+    });
+    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" };
+    }
+    await context.prepareConsumers?.();
+    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,
+        request.envMode ?? "loader",
+      );
+      const prepare = await handle.exec({
+        argv: ["/bin/sh", "-c", 'mkdir -p "$1" && chown node:node "$1"', "prepare", workspacePath],
+        user: "root",
+        projectEnvProfile: "maintenance",
+        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,
+          ],
+          projectEnvProfile: "maintenance",
+          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,
+      envMode: ProjectEnvMode = "baked",
+    ): Promise<TaskEnvironmentHandle> {
+      return new SelfTaskEnvironmentHandle(locator, deps, envMode);
+    },
+  };
+}