@moondeck/station 0.0.1 → 1.0.1

package/lib/task-environment/machine-task-up.ts

@@ -0,0 +1,1227 @@
+/**
+ * ADR-121: the machine-backed task-up adapter.
+ *
+ * Bridges the host's task contract (TaskLaunchInput → TaskUpResult) onto the
+ * pure machine environment provider (MachineTaskInput → descriptor). This is
+ * where task semantics live for machines: project clones happen IN the
+ * machine's world with a one-shot credential over stdin, the task branch is
+ * created off the clone's default HEAD, and repo problems degrade into an
+ * initWarning system note instead of failing the task (a machine with an
+ * empty workspace and a clear message beats a respawn loop).
+ *
+ * Compose-era result fields are satisfied honestly rather than faked:
+ * `composeProject` carries the machine id (the one durable runtime name this
+ * task owns) and `worktreePath` carries the host-side task control dir (the
+ * 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 {
+  AgentError,
+  assertLeasedTaskUp,
+  type TaskDownResult,
+  type TaskLaunchInput,
+  type TaskUpCredentials,
+  type TaskUpResult,
+} from "../agent";
+import { injectCodexIntoMachine } from "../codex-auth";
+import {
+  ensureMachineGatewayTunnelReady,
+  MACHINE_GATEWAY_TUNNEL_PORT,
+  stopMachineGatewayTunnel,
+} from "../machine-gateway-tunnel";
+import {
+  installMachineProjectEnvLoader,
+  installMachineTaskForwarderAsset,
+} from "../machine-project-env-loader";
+import {
+  MACHINE_RUNTIME_AUTHORITY_ENV,
+  PROJECT_ENV_HOOK_PATH,
+} from "../runtime-authority";
+import { sharedRoot } from "../shared-files";
+import { launchTaskEnvForwarder } from "../task-env-forwarder";
+import { MAX_ENV_SCHEMA_BYTES } from "../env-schema";
+import {
+  captureTaskEnvSchemaFromClone,
+  captureTaskEnvSchemas,
+  taskEnvSchemaObservation,
+  type RemoteGit,
+} from "../project-env-schema-capture";
+import { activeSecretsProxy } from "../secrets-proxy/host";
+import { reconcileSidecarTaskProxy } from "../secrets-proxy/task-trust";
+import { TASK_FORWARDER_SECRET_BYTES } from "../task-gateway-protocol";
+import {
+  MACHINE_TASK_ENVIRONMENT_PROVIDER,
+  parseMachineTaskEnvironmentLocator,
+  type MachineTaskInput,
+} from "./machine";
+import type {
+  TaskEnvironmentCallOptions,
+  ProjectEnvMode,
+  TaskEnvironmentDescriptor,
+  TaskEnvironmentHandle,
+  TaskEnvironmentProcess,
+  TaskEnvironmentProvider,
+  TaskEnvironmentProvisionRequest,
+  TaskEnvironmentProvisioned,
+} from "./types";
+import { TASK_SSH_KEY_PATH } from "../credential-consumers/github";
+
+/** 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;
+
+export interface MachineHostTaskUpDeps {
+  /** The pure machine environment provider (createMachineTaskEnvironmentProvider). */
+  environment: TaskEnvironmentProvider<
+    MachineTaskInput,
+    void,
+    TaskEnvironmentDescriptor
+  >;
+  /** Host-side control dir for the task (holds the machine key). */
+  taskControlDir(taskId: string): string;
+  machineImage(): string;
+  machineCpus(): number;
+  machineMemoryMiB(): number;
+  /** macOS-local machines need loopback-published ssh; cloud machines don't. */
+  publishSsh(): boolean;
+  /** The task owner's GitHub access token, or null when GitHub is not
+   * connected (public/anonymous clone fallback). */
+  githubToken(userId: string): Promise<{ accessToken: string } | null>;
+  /** ADR-133: how this environment gets its shared files. Default = the
+   * point-in-time copy from the host's shared directory (machines over
+   * ssh); the sidecar mounts them from S3 instead. */
+  sharedFiles?: (
+    handle: TaskEnvironmentHandle<unknown>,
+    workspacePath: string,
+    task: { ownerOrgId?: string; ownerUserId: string; sharedFiles?: string },
+  ) => Promise<string | null>;
+  /** Test seam for the host-side persistent reverse-tunnel supervisor. */
+  ensureGatewayTunnel?: typeof ensureMachineGatewayTunnelReady;
+  /** How long a start that is not one waits for the stages it left running
+   *  (tests). */
+  abandonJoinMs?: number;
+}
+
+async function startMachineTaskForwarder(
+  taskId: string,
+  handle: TaskEnvironmentHandle<unknown>,
+  credentials: TaskUpCredentials,
+  ensureGatewayTunnel: typeof ensureMachineGatewayTunnelReady,
+): Promise<void> {
+  const gatewayTunnelSshArgs = handle.gatewayTunnelSshArgs?.bind(handle);
+  if (!gatewayTunnelSshArgs) {
+    // The sidecar gateway is in this root process and assigns loopback
+    // traffic to its one fixed task. Binding another listener would collide.
+    return;
+  }
+  const identity = credentials.taskGateway;
+  if (
+    !identity ||
+    !/^[A-Za-z0-9_-]{16,64}$/.test(identity.generation) ||
+    identity.secret.byteLength !== TASK_FORWARDER_SECRET_BYTES
+  ) {
+    throw new Error("machine task env gateway identity is unavailable");
+  }
+  await installMachineTaskForwarderAsset(handle);
+
+  await launchTaskEnvForwarder(
+    handle,
+    { taskId, generation: identity.generation },
+    Uint8Array.from(identity.secret),
+    {
+      gatewayHost: "127.0.0.1",
+      gatewayPort: MACHINE_GATEWAY_TUNNEL_PORT,
+      nodePath: "/usr/bin/node",
+    },
+  );
+
+  // Start this during task-up rather than waiting for the first agent. The
+  // editor can open a terminal before any roster process exists, and its
+  // first command must already be able to refresh through the forwarder.
+  await ensureGatewayTunnel(
+    taskId,
+    { gatewayTunnelSshArgs },
+    MACHINE_GATEWAY_TUNNEL_PORT,
+  );
+}
+
+/** Mirrors src/index.ts isGithubRepo — host-side predicate only. */
+export function isGithubRepoUrl(input: string): boolean {
+  const value = input.trim();
+  if (/^(?:[^@/]+@)?(?:www\.)?github\.com:/i.test(value)) return true;
+  if (/^[\w.-]+\/[\w.-]+(?:\.git)?\/?$/i.test(value)) return true;
+  try {
+    const url = new URL(value);
+    return /^(?:www\.)?github\.com$/i.test(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Canonical HTTPS form for GitHub repos (shorthand and ssh forms included);
+ * non-GitHub URLs pass through untouched. */
+export function machineCloneUrl(repoUrl: string): string {
+  const value = repoUrl.trim();
+  const ssh = /^(?:[^@/]+@)?(?:www\.)?github\.com:(.+)$/i.exec(value);
+  if (ssh?.[1]) {
+    return `https://github.com/${ssh[1].replace(/\.git$/i, "")}.git`;
+  }
+  if (/^[\w.-]+\/[\w.-]+(?:\.git)?\/?$/i.test(value)) {
+    return `https://github.com/${value.replace(/\/+$/, "").replace(/\.git$/i, "")}.git`;
+  }
+  return value;
+}
+
+/** Workspace-safe project directory name. The slug is cloud-normalized, but
+ * the machine path re-checks: a path-capable slug must never reach argv. */
+function projectDirectoryName(slug: string): string {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug) || slug.includes("..")) {
+    throw new Error(`unsafe project slug for machine clone: ${slug}`);
+  }
+  // Files v1 publishes the task's leased S3 roots at this fixed workspace
+  // entry.  Refuse a project with the same name before clone can follow the
+  // published link and write repository data into the Files bucket.
+  if (slug === "files") {
+    throw new Error("the project slug files is reserved for shared files");
+  }
+  return slug;
+}
+
+interface StepResult {
+  exitCode: number | null;
+  stderr: string;
+}
+
+/** One-shot exec with stdin: spawn, deliver the secret, drain, await exit.
+ * The secret rides the ssh stream only — never argv, never the persisted
+ * env, never machine disk. */
+async function execWithStdin(
+  handle: TaskEnvironmentHandle<unknown>,
+  argv: readonly [string, ...string[]],
+  stdin: string,
+  timeoutMs: number,
+  /** Aborted: the process is ended at once (ADR-154 §12, a withdrawn start). */
+  signal?: AbortSignal,
+  user?: string,
+): Promise<StepResult> {
+  if (signal?.aborted) throw new Error(WITHDRAWN);
+  const proc = await handle.spawn({
+    argv,
+    ...(user === undefined ? {} : { user }),
+    projectEnvProfile: "maintenance",
+    inheritEnv: [],
+    env: { GIT_TERMINAL_PROMPT: "0" },
+    timeoutMs,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  const onAbort = (): void => void proc.terminate("SIGKILL").catch(() => {});
+  if (signal?.aborted) onAbort();
+  else signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    return await drainStep(proc, stdin);
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+async function drainStep(proc: TaskEnvironmentProcess, stdin: string): Promise<StepResult> {
+  let stderr = "";
+  const drainOut = (async () => {
+    for await (const chunk of proc.stdout) {
+      void chunk; // drained; clone progress is not retained
+    }
+  })();
+  const drainErr = (async () => {
+    for await (const chunk of proc.stderr) {
+      stderr = (stderr + Buffer.from(chunk).toString("utf8")).slice(-8192);
+    }
+  })();
+  await proc.write(Buffer.from(stdin));
+  await proc.closeInput();
+  const exit = await proc.completion;
+  await Promise.allSettled([drainOut, drainErr]);
+  return { exitCode: exit.exitCode, stderr: stderr.trim() };
+}
+
+async function execStep(
+  handle: TaskEnvironmentHandle<unknown>,
+  argv: readonly [string, ...string[]],
+  timeoutMs: number,
+): Promise<StepResult> {
+  const result = await handle.exec({
+    argv,
+    projectEnvProfile: "maintenance",
+    env: { GIT_TERMINAL_PROMPT: "0" },
+    timeoutMs,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  return {
+    exitCode: result.exitCode,
+    stderr: Buffer.from(result.stderr).toString("utf8").trim().slice(-8192),
+  };
+}
+
+/** The remote clone script for the credentialed path. The token is read from
+ * stdin into the clone process env; /usr/local/bin/uai-git-askpass (baked in
+ * the machine image) answers git's prompts from it. */
+const CREDENTIALED_CLONE_SCRIPT =
+  'IFS= read -r UAI_GIT_TOKEN && export UAI_GIT_TOKEN GIT_ASKPASS=/usr/local/bin/uai-git-askpass GIT_TERMINAL_PROMPT=0 && exec git clone -- "$1" "$2"';
+
+const WITHDRAWN = "the task's credentials were withdrawn while it was starting; start the task again";
+
+/** The task's user on a machine, and in sidecar mode. */
+const MACHINE_TASK_USER = "node";
+
+/**
+ * ADR-154 §12: a task on cloud credentials clones by exactly the route its
+ * lease names, with nothing of the machine's own and nothing the task could
+ * have put in its own login:
+ * - the clone starts as root, whose login is not the task's: a profile the
+ *   task wrote could otherwise read the token off stdin before anything
+ *   else, or put its own `env`, `git`, `GIT_EXEC_PATH` or `LD_PRELOAD` in
+ *   the clone's way;
+ * - in an environment rebuilt from nothing (`env -i`): a fixed PATH and no
+ *   home (so no .netrc, ~/.gitconfig or ~/.ssh/config), no global or system
+ *   git configuration;
+ * - then as the task's user (`setpriv`, when root), in a shell that reads no
+ *   profile. It alone reads the token from stdin, and runs git and ssh by
+ *   absolute path, with no credential helper and no agent.
+ */
+const LEASED_CLONE_ENV = [
+  "PATH=/usr/bin:/bin",
+  "HOME=/nonexistent",
+  "XDG_CONFIG_HOME=/nonexistent",
+  "LC_ALL=C",
+  "GIT_CONFIG_NOSYSTEM=1",
+  "GIT_CONFIG_GLOBAL=/dev/null",
+  "GIT_TERMINAL_PROMPT=0",
+] as const;
+/** Root drops to the task's user; anyone else (a non-root dev sidecar, whose
+ *  user is the task's) stays. The route's script arrives as $1, never on
+ *  stdin, which only it reads. */
+const LEASED_CLONE_DROP =
+  'if [ "$(/usr/bin/id -u)" = 0 ]; then ' +
+  `exec /usr/bin/setpriv --reuid=${MACHINE_TASK_USER} --regid=${MACHINE_TASK_USER} --init-groups -- /bin/sh -c "$1" clone "$2" "$3"; ` +
+  'fi; exec /bin/sh -c "$1" clone "$2" "$3"';
+const LEASED_GIT = "exec /usr/bin/git -c credential.helper= -c core.hooksPath=/dev/null";
+const LEASED_TOKEN_CLONE_SCRIPT =
+  'IFS= read -r UAI_GIT_TOKEN && export UAI_GIT_TOKEN GIT_ASKPASS=/usr/local/bin/uai-git-askpass && ' +
+  `${LEASED_GIT} clone -- "$1" "$2"`;
+const LEASED_SSH_CLONE_SCRIPT =
+  `export GIT_SSH_COMMAND="/usr/bin/ssh -F /dev/null -i ${TASK_SSH_KEY_PATH} -o IdentitiesOnly=yes -o IdentityAgent=none -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=/home/node/.ssh/known_hosts" && ` +
+  `${LEASED_GIT} -c url.git@github.com:.insteadOf=https://github.com/ clone -- "$1" "$2"`;
+const LEASED_ANONYMOUS_CLONE_SCRIPT = `${LEASED_GIT} clone -- "$1" "$2"`;
+
+/** The leased clone's command, run as root (see above). */
+export function leasedCloneArgv(script: string, url: string, destination: string): [string, ...string[]] {
+  return ["/usr/bin/env", "-i", ...LEASED_CLONE_ENV, "/bin/sh", "-c", LEASED_CLONE_DROP, "drop", script, url, destination];
+}
+
+/** How a task on cloud credentials clones: its lease's token, its SSH key,
+ *  or neither (it names neither). */
+interface LeasedCloneRoute {
+  ssh: boolean;
+  signal: AbortSignal;
+}
+
+const DENIED =
+  /repository not found|permission denied|access rights|could not read username|authentication failed|invalid username or password|returned error: 40[134]|HTTP 40[134]/i;
+
+/**
+ * A fresh clone by a leased route that failed: the start fails and the
+ * machine goes (unlike the legacy route's warning, ADR-121), saying which of
+ * the owner's credentials GitHub refused and what to do about it.
+ */
+function leasedCloneFailure(repoUrl: string, route: "token" | "ssh" | "none", stderr: string): AgentError {
+  const step = "clone";
+  if (isGithubRepoUrl(repoUrl) && DENIED.test(stderr)) {
+    if (route === "token") {
+      return new AgentError(
+        "GITHUB_TOKEN_ACCESS_DENIED",
+        `GitHub denied the task owner's GitHub sign-in access to ${repoUrl}. Confirm that the Moondeck GitHub App is installed on the owning account or organization, this repository is included in its grant, and the owner can read it. Then start the task again.`,
+        { step },
+      );
+    }
+    if (route === "ssh") {
+      return new AgentError(
+        "GITHUB_SSH_ACCESS_DENIED",
+        `GitHub denied the task owner's SSH key access to ${repoUrl}. Register that key with an account that can read the repository (and authorize it for SAML SSO when required), or connect GitHub in Settings. Then start the task again.`,
+        { step },
+      );
+    }
+    return new AgentError(
+      "GITHUB_CONNECTION_REQUIRED",
+      `The task owner has neither a GitHub sign-in nor an SSH key in Moondeck that can read ${repoUrl}. Connect GitHub in Settings, then start the task again.`,
+      { step },
+    );
+  }
+  return new AgentError("CLONE_FAILED", `could not clone ${repoUrl}: ${stderr || "clone failed"}`, { step });
+}
+
+type ProjectEnvSchemaObservation = NonNullable<TaskUpResult["envSchemas"]>[number];
+
+/** What a project's clone step did: cloned it now, found the task's own
+ *  clone already there (a resume), or could not clone it; and what to say. */
+interface CloneOutcome {
+  clone: "fresh" | "existing" | "failed";
+  warning: string | null;
+}
+
+async function cloneProject(
+  handle: TaskEnvironmentHandle<unknown>,
+  destination: string,
+  project: { slug: string; repoUrl: string },
+  taskBranch: string,
+  owner: { name?: string; email?: string },
+  token: string | null,
+  /** A task on cloud credentials: its exact route, and its withdrawal. */
+  leased?: LeasedCloneRoute,
+): Promise<CloneOutcome> {
+  const url = machineCloneUrl(project.repoUrl);
+  const useToken = token !== null && isGithubRepoUrl(project.repoUrl);
+
+  // Resume/retry idempotency: a repository that already exists is the task's
+  // live work — never re-clone over it, and leave its branch state alone.
+  const already = await execStep(
+    handle,
+    ["/bin/sh", "-c", 'test -e "$1/.git"', "check", destination],
+    GIT_STEP_TIMEOUT_MS,
+  );
+  if (already.exitCode === 0) return { clone: "existing", warning: null };
+  // Withdrawn while the probe ran: the clone never starts.
+  if (leased?.signal.aborted) throw new Error(WITHDRAWN);
+
+  const route = useToken ? "token" : leased?.ssh && isGithubRepoUrl(project.repoUrl) ? "ssh" : "none";
+  const clone = leased
+    ? await execWithStdin(
+        handle,
+        leasedCloneArgv(
+          route === "token" ? LEASED_TOKEN_CLONE_SCRIPT : route === "ssh" ? LEASED_SSH_CLONE_SCRIPT : LEASED_ANONYMOUS_CLONE_SCRIPT,
+          url,
+          destination,
+        ),
+        useToken ? `${token}\n` : "",
+        CLONE_TIMEOUT_MS,
+        leased.signal,
+        "root",
+      )
+    : useToken
+      ? await execWithStdin(
+          handle,
+          ["/bin/sh", "-c", CREDENTIALED_CLONE_SCRIPT, "clone", url, destination],
+          `${token}\n`,
+          CLONE_TIMEOUT_MS,
+        )
+      : await execStep(
+          handle,
+          ["git", "clone", "--", url, destination],
+          CLONE_TIMEOUT_MS,
+        );
+  if (leased?.signal.aborted) throw new Error(WITHDRAWN);
+  if (clone.exitCode !== 0 && leased) throw leasedCloneFailure(project.repoUrl, route, clone.stderr);
+  if (clone.exitCode !== 0) {
+    // The commonest failure by far is an ANONYMOUS clone of a private GitHub
+    // repo because this host has no GitHub credential for the task owner —
+    // git's own message ("could not read Username … terminal prompts
+    // disabled") explains none of that. Say the actionable thing.
+    if (token === null && isGithubRepoUrl(project.repoUrl)) {
+      return {
+        clone: "failed",
+        warning:
+          `could not clone ${project.repoUrl} for ${project.slug}: GitHub is ` +
+          "not connected on this host. Connect GitHub on the host's page " +
+          "(Connections → GitHub), then Resume.",
+      };
+    }
+    return { clone: "failed", warning: `could not clone ${project.repoUrl} for ${project.slug}: ${clone.stderr || "clone failed"}` };
+  }
+
+  // Task branch off the clone's default HEAD (matches the compose path's
+  // `-b <branch> origin/<default>`). -B keeps an empty-repo clone (unborn
+  // HEAD) and a re-run both working; failure degrades, never fails the task.
+  const branch = await execStep(
+    handle,
+    ["git", "-C", destination, "checkout", "-B", taskBranch],
+    GIT_STEP_TIMEOUT_MS,
+  );
+  if (branch.exitCode !== 0) {
+    return { clone: "fresh", warning: `cloned ${project.slug} but could not create branch ${taskBranch}: ${branch.stderr}` };
+  }
+
+  // Repo-local commit identity so agent commits work out of the box.
+  if (owner.name) {
+    await execStep(
+      handle,
+      ["git", "-C", destination, "config", "user.name", owner.name],
+      GIT_STEP_TIMEOUT_MS,
+    );
+  }
+  if (owner.email) {
+    await execStep(
+      handle,
+      ["git", "-C", destination, "config", "user.email", owner.email],
+      GIT_STEP_TIMEOUT_MS,
+    );
+  }
+  return { clone: "fresh", warning: null };
+}
+
+/** Git, read-only, in a fresh clone on the machine, as the task's user (the
+ *  way the clone ran) but with nothing of that user's environment: no
+ *  profile variable, PATH entry or global config can point it elsewhere. */
+function gitInClone(handle: TaskEnvironmentHandle<unknown>, destination: string): RemoteGit {
+  return async (args) => {
+    for (let attempt = 1; ; attempt += 1) {
+      const result = await handle.exec({
+        argv: [
+          "/usr/bin/env",
+          "-i",
+          "PATH=/usr/bin:/bin",
+          "HOME=/nonexistent",
+          "LC_ALL=C",
+          "GIT_CONFIG_NOSYSTEM=1",
+          "GIT_CONFIG_GLOBAL=/dev/null",
+          "GIT_TERMINAL_PROMPT=0",
+          "/usr/bin/git",
+          "--no-replace-objects",
+          "-C",
+          destination,
+          "-c",
+          "core.hooksPath=/dev/null",
+          "-c",
+          "core.fsmonitor=false",
+          ...args,
+        ],
+        projectEnvProfile: "maintenance",
+        timeoutMs: GIT_STEP_TIMEOUT_MS,
+        maxOutputBytes: MAX_ENV_SCHEMA_BYTES + 64 * 1024,
+      });
+      // A process that did not run to its end says nothing about the clone.
+      if (result.exitCode !== null) {
+        return result.exitCode === 0 && !result.stdoutTruncated ? Buffer.from(result.stdout) : null;
+      }
+      if (attempt >= 3) return null;
+    }
+  };
+}
+
+/**
+ * ADR-153 §4, "Machine and sidecar": each project's schema observation,
+ * stored where the task cannot write before anything in it starts, and the
+ * same one reported by every task-up of the task (the cloud keeps the first).
+ * Only a clone made now, on a machine where nothing of the task has run, is
+ * read. A resumed clone is the task's live work, and a clone that failed is
+ * retried on a resume after the task's processes have run, so neither is
+ * ever read: with nothing stored, the base is missing, for the task's life.
+ * A failure here withholds that project's unbound keys, never fails the
+ * start.
+ */
+async function captureMachineEnvSchemas(
+  taskId: string,
+  handle: TaskEnvironmentHandle<unknown>,
+  clones: ReadonlyArray<{ projectId: string; destination: string; clone: CloneOutcome["clone"] }>,
+): Promise<ProjectEnvSchemaObservation[]> {
+  const observations: ProjectEnvSchemaObservation[] = [];
+  for (const { projectId, destination, clone } of clones) {
+    try {
+      const stored = taskEnvSchemaObservation(taskId, projectId);
+      observations.push(
+        stored ??
+          (clone === "fresh"
+            ? await captureTaskEnvSchemaFromClone(taskId, projectId, gitInClone(handle, destination))
+            : // No base is ever recorded on a machine: this stores it missing.
+              captureTaskEnvSchemas(taskId, [projectId])[0]!),
+      );
+    } catch (error) {
+      console.warn(
+        `[machine] task ${taskId}: .env.schema capture failed for ${projectId}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+      observations.push(captureTaskEnvSchemas(taskId, [projectId])[0]!);
+    }
+  }
+  return observations;
+}
+
+/** 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,
+    ],
+    projectEnvProfile: "maintenance",
+    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,
+        ],
+        projectEnvProfile: "maintenance",
+        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}/.moondeck/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. */
+export async function ensureCodeServer(
+  handle: TaskEnvironmentHandle<unknown>,
+  workspacePath: string,
+  editorTheme: string | undefined,
+  envMode: ProjectEnvMode = handle.descriptor.envMode ?? "baked",
+): 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',
+    ],
+    projectEnvProfile: "maintenance",
+    timeoutMs: GIT_STEP_TIMEOUT_MS,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  if (running.exitCode === 0) return;
+  // Editor processes are task processes, but code-server must not inherit a
+  // real project value that a fixed-task sidecar's outer login shell loaded.
+  // Start it from an explicit empty environment and give its descendants only
+  // the host-owned runtime baseline plus the loader controls editor terminals
+  // need. The maintenance profile also prevents the provider-added outer
+  // shell from fetching project env before `env -i` gets control.
+  const editorEnvironment = {
+    ...MACHINE_RUNTIME_AUTHORITY_ENV,
+    ...(envMode === "loader"
+      ? { BASH_ENV: PROJECT_ENV_HOOK_PATH, UAI_ENV_HOOK: "1" }
+      : {}),
+    LOGNAME: "node",
+    PLAYWRIGHT_BROWSERS_PATH: "/opt/pw-browsers",
+    SHELL: "/bin/bash",
+    USER: "node",
+  } as const;
+  const result = await handle.launchDetachedSession({
+    argv: [
+      "/usr/bin/env",
+      "-i",
+      ...Object.entries(editorEnvironment)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, value]) => `${name}=${value}`),
+      "/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}`,
+      workspacePath,
+    ],
+    inheritEnv: [],
+    env: {},
+    projectEnvProfile: "maintenance",
+    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()}`,
+    );
+  }
+}
+
+/** How long a start that is not one waits for the stages it left running. */
+const ABANDON_JOIN_MS = 15_000;
+
+/** Until every one of `work` is settled, or `ms` has passed. */
+async function joinBounded(work: readonly Promise<unknown>[], ms: number): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  await Promise.race([
+    Promise.allSettled(work),
+    new Promise<void>((resolve) => {
+      timer = setTimeout(resolve, ms);
+      timer.unref?.();
+    }),
+  ]);
+  if (timer) clearTimeout(timer);
+}
+
+/**
+ * A start's own view of its machine: every call through it, and every write
+ * to a process started through it, is refused once `over()` holds. Work the
+ * start left behind therefore never reaches the machine again, nor a
+ * replacement that reuses its name.
+ */
+function fencedHandle(handle: TaskEnvironmentHandle<unknown>, over: () => boolean): TaskEnvironmentHandle<unknown> {
+  const admit = (): void => {
+    if (over()) throw new Error(WITHDRAWN);
+  };
+  // Checked again by the provider at its last moment, after anything it
+  // awaits first (a machine looks up its address): a call admitted before
+  // the start ended never starts after it.
+  const lastly = (inner?: () => void) => (): void => {
+    admit();
+    inner?.();
+  };
+  const fenced = (proc: TaskEnvironmentProcess): TaskEnvironmentProcess => ({
+    stdout: proc.stdout,
+    stderr: proc.stderr,
+    completion: proc.completion,
+    write: async (chunk) => {
+      admit();
+      await proc.write(chunk);
+    },
+    closeInput: () => proc.closeInput(),
+    terminate: (signal) => proc.terminate(signal),
+  });
+  return {
+    descriptor: handle.descriptor,
+    durableIdentity: handle.durableIdentity,
+    ...(handle.anchors === undefined ? {} : { anchors: handle.anchors }),
+    ...(handle.credentialDelivery === undefined ? {} : { credentialDelivery: handle.credentialDelivery }),
+    readWorkspaceFile: async (path, options) => {
+      admit();
+      return handle.readWorkspaceFile(path, { ...options, admit: lastly(options?.admit) });
+    },
+    writeWorkspaceFile: async (path, bytes, options) => {
+      admit();
+      await handle.writeWorkspaceFile(path, bytes, { ...options, admit: lastly(options?.admit) });
+    },
+    exec: async (request) => {
+      admit();
+      return handle.exec({ ...request, admit: lastly(request.admit) });
+    },
+    spawn: async (request) => {
+      admit();
+      return fenced(await handle.spawn({ ...request, admit: lastly(request.admit) }));
+    },
+    spawnSession: async (request) => {
+      admit();
+      return fenced(await handle.spawnSession({ ...request, admit: lastly(request.admit) }));
+    },
+    launchDetachedSession: async (request) => {
+      admit();
+      return handle.launchDetachedSession({ ...request, admit: lastly(request.admit) });
+    },
+    copy: async (request) => {
+      admit();
+      await handle.copy({ ...request, admit: lastly(request.admit) });
+    },
+    ports: async () => {
+      admit();
+      return handle.ports();
+    },
+    status: async () => {
+      admit();
+      return handle.status();
+    },
+    recover: async (context) => {
+      admit();
+      return handle.recover(context);
+    },
+    stop: async () => {
+      admit();
+      await handle.stop();
+    },
+    teardown: async () => {
+      admit();
+      await handle.teardown();
+    },
+    ...(handle.inspectRoute
+      ? {
+          inspectRoute: async () => {
+            admit();
+            return handle.inspectRoute!();
+          },
+        }
+      : {}),
+    ...(handle.gatewayTunnelSshArgs
+      ? {
+          gatewayTunnelSshArgs: async (machinePort: number, hostPort: number, options?: TaskEnvironmentCallOptions) => {
+            admit();
+            return handle.gatewayTunnelSshArgs!(machinePort, hostPort, { ...options, admit: lastly(options?.admit) });
+          },
+        }
+      : {}),
+  };
+}
+
+/** The identity the host records for the task's runtime: the machine id for
+ * a machine over ssh (what recovery and orphan sweeps key on), the handle's
+ * durable identity for anything else (sidecar mode: `self:<task>`). */
+function environmentRuntimeIdentity(handle: TaskEnvironmentHandle<unknown>): string {
+  return handle.descriptor.locator.provider === MACHINE_TASK_ENVIRONMENT_PROVIDER
+    ? parseMachineTaskEnvironmentLocator(handle.descriptor.locator).machineId
+    : handle.durableIdentity;
+}
+
+/** Wrap the void-teardown machine handle so registry consumers get the
+ * TaskDownResult contract the compose providers speak. */
+function withTaskDownResult(
+  handle: TaskEnvironmentHandle<unknown>,
+): TaskEnvironmentHandle<TaskDownResult> {
+  // Explicit delegation, never Object.create: the machine handle is a class
+  // with private fields, and a prototype-borrowed method invoked on a foreign
+  // receiver throws on its first #member access.
+  return {
+    descriptor: handle.descriptor,
+    durableIdentity: handle.durableIdentity,
+    ...(handle.anchors === undefined ? {} : { anchors: handle.anchors }),
+    ...(handle.credentialDelivery === undefined ? {} : { credentialDelivery: handle.credentialDelivery }),
+    readWorkspaceFile: (path, options) => handle.readWorkspaceFile(path, options),
+    writeWorkspaceFile: (path, bytes, options) => handle.writeWorkspaceFile(path, bytes, options),
+    exec: (request) => handle.exec(request),
+    spawn: (request) => handle.spawn(request),
+    spawnSession: (request) => handle.spawnSession(request),
+    launchDetachedSession: (request) => handle.launchDetachedSession(request),
+    copy: (request) => handle.copy(request),
+    ports: () => handle.ports(),
+    status: () => handle.status(),
+    recover: (context) => handle.recover(context),
+    stop: () => handle.stop(),
+    teardown: async (): Promise<TaskDownResult> => {
+      await handle.teardown();
+      return { status: "terminated" };
+    },
+    ...(handle.inspectRoute
+      ? { inspectRoute: () => handle.inspectRoute!() }
+      : {}),
+    ...(handle.gatewayTunnelSshArgs
+      ? {
+          gatewayTunnelSshArgs: (machinePort: number, hostPort: number, options?: TaskEnvironmentCallOptions) =>
+            handle.gatewayTunnelSshArgs!(machinePort, hostPort, options),
+        }
+      : {}),
+  };
+}
+
+export function createMachineHostTaskEnvironmentProvider(
+  deps: MachineHostTaskUpDeps,
+): TaskEnvironmentProvider<
+  TaskLaunchInput,
+  TaskUpCredentials,
+  TaskUpResult,
+  TaskDownResult
+> {
+  return {
+    // The provider kind is whichever environment sits underneath: a machine
+    // over ssh, or this machine in sidecar mode (ADR-133).
+    kind: deps.environment.kind,
+
+    async provision(
+      request: TaskEnvironmentProvisionRequest<TaskLaunchInput, TaskUpCredentials>,
+    ): Promise<TaskEnvironmentProvisioned<TaskUpResult, TaskDownResult>> {
+      const { input } = request;
+      const envMode = request.envMode ?? "loader";
+      // Validate every task-controlled workspace directory before the
+      // provider is allowed to create a machine or a leased runtime-ready
+      // writer can publish anything into it.  Validating lazily in the clone
+      // loop is too late: an invalid later project would leave all of those
+      // earlier effects behind.
+      const projects = [...input.projects]
+        .sort((a, b) => a.position - b.position)
+        .map((project) => ({
+          project,
+          directoryName: projectDirectoryName(project.slug),
+        }));
+      // ADR-154 §12: a task on cloud credentials holds its grant for the
+      // whole start; withdrawn (its gate closed, a cleanup reached it), the
+      // start stops wherever it is, its clone included, and the machine goes.
+      const leased = request.credentials.leased;
+      assertLeasedTaskUp(leased, input.task);
+      const clone = leased?.clone;
+      const withdrawal = (): Error => new Error(WITHDRAWN);
+      if (clone?.signal.aborted) throw withdrawal();
+      const untilWithdrawn = <T>(work: Promise<T>): Promise<T> => {
+        if (!clone) return work;
+        return new Promise<T>((resolve, reject) => {
+          const onAbort = (): void => reject(withdrawal());
+          if (clone.signal.aborted) {
+            onAbort();
+            return;
+          }
+          clone.signal.addEventListener("abort", onAbort, { once: true });
+          work.then(
+            (value) => {
+              clone.signal.removeEventListener("abort", onAbort);
+              resolve(value);
+            },
+            (error: unknown) => {
+              clone.signal.removeEventListener("abort", onAbort);
+              reject(error);
+            },
+          );
+        });
+      };
+      const provisioning = deps.environment.provision({
+        taskId: request.taskId,
+        input: {
+          image: deps.machineImage(),
+          cpus: deps.machineCpus(),
+          memoryMiB: deps.machineMemoryMiB(),
+          ...(deps.publishSsh() ? { publishSsh: true } : {}),
+        },
+        credentials: undefined,
+        envMode,
+        onPrepared: request.onPrepared,
+      });
+      let provisioned: Awaited<typeof provisioning>;
+      try {
+        provisioned = await untilWithdrawn(provisioning);
+      } catch (error) {
+        if (clone?.signal.aborted) {
+          // Withdrawn while the machine came up: the start returns only once
+          // that is over and the machine is gone again (the provider's own
+          // timeouts bound the wait). A teardown left for later could take a
+          // replacement, which reuses the task's machine name.
+          const late = await provisioning.catch(() => null);
+          // A reused machine holds the task's work: stopped, never destroyed.
+          if (late) await (late.reused ? late.handle.stop() : late.handle.teardown()).catch(() => {});
+        }
+        throw error;
+      }
+      const handle = provisioned.handle;
+      const workspacePath = handle.descriptor.workspacePath;
+      const warnings: string[] = [];
+      const clones: Array<{ projectId: string; destination: string; clone: CloneOutcome["clone"] }> = [];
+      // The start's own view of the machine: once the start is withdrawn or
+      // failed, every call through it is refused, so work it began and left
+      // behind never reaches the machine again, nor the replacement that
+      // reuses its name: no exec, write, secret or teardown.
+      let over = false;
+      const own = fencedHandle(handle, () => over || clone?.signal.aborted === true);
+      // Every later stage races the withdrawal, through the start's last
+      // step: withdrawn, the start stops wherever it is. What it began is
+      // fenced off, the machine goes, and the stages still running get a
+      // bounded chance to end before the start returns.
+      const begun: Array<Promise<unknown>> = [];
+      const stage = <T>(work: Promise<T>): Promise<T> => {
+        begun.push(work);
+        work.catch(() => {});
+        return untilWithdrawn(work);
+      };
+      let abandoning: Promise<void> | null = null;
+      const abandon = (): Promise<void> => {
+        over = true;
+        abandoning ??= (async () => {
+          // Only a machine this start launched is destroyed. One it reused (a
+          // Resume of a stopped machine) holds the task's work on its disk, so
+          // a failed start stops it again and the next Resume tries afresh.
+          await (provisioned.reused ? handle.stop() : handle.teardown()).catch(() => {});
+          await joinBounded(begun, deps.abandonJoinMs ?? ABANDON_JOIN_MS);
+        })();
+        return abandoning;
+      };
+
+      try {
+        if (clone?.signal.aborted) throw withdrawal();
+        // ADR-154 §12: the runtime exists and nothing in it has run yet: the
+        // runner's writes (the owner's GitHub configuration and SSH key,
+        // recorded for cleanup) come first, so the clones below authenticate
+        // with them, over SSH too.
+        if (leased) {
+          const writes = leased.runtimeReady(own, leased.clone.signal);
+          try {
+            await untilWithdrawn(writes);
+          } catch (error) {
+            // Joined before anything else happens: nothing still writes into
+            // the machine once the start has stopped.
+            over = true;
+            await writes.catch(() => {});
+            throw error;
+          }
+        }
+        if (envMode === "loader") {
+          await stage(installMachineProjectEnvLoader(own));
+          // ADR-153, on a machine's own task (the sidecar's): the proxy's CA
+          // and pins before anything in the task loads its env. Never fails
+          // the start; its proxied keys stay withheld until they are in.
+          const proxyWarning = await stage(
+            reconcileSidecarTaskProxy(own, activeSecretsProxy()?.runtime ?? null, { start: true }),
+          );
+          if (proxyWarning !== null) console.warn(`[machine] task ${request.taskId}: ${proxyWarning}`);
+        }
+        const wantsGithub = projects.some(({ project }) =>
+          isGithubRepoUrl(project.repoUrl),
+        );
+        // ADR-154 §12: a task on cloud credentials clones with the token its
+        // lease holds for this start, never the runner's own store.
+        const token = !wantsGithub
+          ? null
+          : clone
+            ? clone.github && { accessToken: clone.github.token }
+            : await deps.githubToken(input.task.ownerUserId);
+        for (const { project, directoryName } of projects) {
+          if (clone?.signal.aborted) throw withdrawal();
+          const destination = `${workspacePath}/${directoryName}`;
+          const outcome = await untilWithdrawn(
+            cloneProject(
+              own,
+              destination,
+              project,
+              input.task.branch,
+              { name: input.ownerName, email: input.ownerEmail },
+              token?.accessToken ?? null,
+              clone ? { ssh: clone.ssh !== null, signal: clone.signal } : undefined,
+            ),
+          );
+          clones.push({ projectId: project.id, destination, clone: outcome.clone });
+          if (outcome.warning) warnings.push(outcome.warning);
+        }
+        if (clone?.signal.aborted) throw withdrawal();
+      } catch (error) {
+        // Provisioning-infrastructure failures (ssh died, unsafe slug) tear
+        // the machine down rather than stranding an orphan, and so does a
+        // leased clone that failed; a legacy route's per-repo problems were
+        // already converted to warnings above and do not land here.
+        await abandon();
+        throw error;
+      }
+      let envSchemas: ProjectEnvSchemaObservation[];
+      try {
+        // ADR-153 §4: right after the clones, before shared files, the
+        // forwarder, the editor or any agent.
+        envSchemas = await stage(captureMachineEnvSchemas(request.taskId, own, clones));
+
+        // ADR-062 shared files: point-in-time copy (see copySharedFiles).
+        const sharedWarning = leased?.filesV1
+          ? null
+          : await stage(
+              (deps.sharedFiles ?? copySharedFiles)(own, 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);
+
+        // Codex default-slot credentials: the legacy delivery paths are all
+        // docker grammar; machines get theirs over the transport. Best-effort
+        // — a failed inject degrades codex agents, never the task. A task on
+        // cloud credentials gets its accounts from its lease, never the
+        // runner's own (ADR-154 §6).
+        if (!clone && input.task.agents.some((agent) => agent.kind === "codex")) {
+          await injectCodexIntoMachine(own).catch((error: unknown) => {
+            console.warn(
+              `[machine] task ${request.taskId}: codex inject failed: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+            );
+          });
+        }
+
+        if (envMode === "loader") {
+          try {
+            await stage(
+              startMachineTaskForwarder(
+                request.taskId,
+                own,
+                request.credentials,
+                deps.ensureGatewayTunnel ?? ensureMachineGatewayTunnelReady,
+              ),
+            );
+          } catch (error) {
+            // Unlike editor/auth conveniences, the loader is the only project
+            // env delivery path. A task without it must not start and silently
+            // hand consumers an incomplete or legacy environment.
+            stopMachineGatewayTunnel(request.taskId);
+            await abandon();
+            throw error;
+          }
+        }
+
+        // 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 stage(
+          ensureCodeServer(own, workspacePath, input.task.previewEnv?.UAI_EDITOR_THEME, envMode).catch(
+            (error: unknown) => {
+              console.warn(
+                `[machine] task ${request.taskId}: code-server launch failed: ${
+                  error instanceof Error ? error.message : String(error)
+                }`,
+              );
+            },
+          ),
+        );
+
+        // Withdrawn while the rest came up: the start is not one.
+        if (clone?.signal.aborted) throw withdrawal();
+      } catch (error) {
+        if (clone?.signal.aborted) {
+          stopMachineGatewayTunnel(request.taskId);
+          await abandon();
+          throw withdrawal();
+        }
+        throw error;
+      }
+      return {
+        handle: withTaskDownResult(handle),
+        result: {
+          // Recorded as the task's runtime identity (the compose-project
+          // column): the machine id over ssh, `self:<task>` in sidecar mode.
+          composeProject: environmentRuntimeIdentity(handle),
+          worktreePath: deps.taskControlDir(request.taskId),
+          codeServerPort: MACHINE_CODE_SERVER_PORT,
+          ...(envSchemas.length > 0 ? { envSchemas } : {}),
+          ...(warnings.length > 0
+            ? { initWarning: warnings.join("\n") }
+            : {}),
+        },
+      };
+    },
+
+    async reconstruct(locator, envMode = "baked") {
+      return withTaskDownResult(
+        await deps.environment.reconstruct(locator, envMode),
+      );
+    },
+  };
+}