@runuai/host 0.9.14 → 0.9.43

package/lib/task-environment/legacy-adoption.ts

@@ -0,0 +1,459 @@
+import path from "node:path";
+
+import { eq } from "drizzle-orm";
+
+import { dockerCli, type DockerResult } from "../docker-exec";
+import { getDb, schema, type HostTask } from "../db";
+import { parsePreviewPortRuntimes } from "../preview-ports";
+import { PREVIEW_SIDECAR_TASK_LABEL } from "../preview-sidecar";
+import { assertSafeHostTaskId } from "../task-identity";
+import {
+  APPLE_TASK_ENVIRONMENT_PROVIDER,
+  parseAppleTaskEnvironmentLocator,
+} from "./apple-container";
+import {
+  dockerTaskEnvironmentLocator,
+  parseDockerTaskEnvironmentLocator,
+  type DockerMachineIdentity,
+} from "./docker";
+import type { HostMachineIdentity } from "./index";
+import {
+  parseTaskEnvironmentLocator,
+  serializeTaskEnvironmentLocator,
+  type TaskEnvironmentLocator,
+} from "./types";
+
+const INSPECT_OUTPUT_LIMIT = 128 * 1024;
+const INVENTORY_OUTPUT_LIMIT = 128 * 1024;
+const LEGACY_INSPECT_FORMAT =
+  '{{json .Id}}\t{{json .Name}}\t{{json (index .Config.Labels "com.docker.compose.project")}}\t{{json (index .Config.Labels "com.docker.compose.service")}}\t{{json .State.Status}}\t{{json .Mounts}}';
+// The third column is the preview-sidecar marker: a sidecar can wear the
+// task's compose project/service labels (teardown finds it by project), so
+// the app-container census must see and skip it — counting one as an app
+// container failed the WHOLE runtime adoption closed (live 2026-08-18).
+const LEGACY_INVENTORY_FORMAT = `{{.ID}}\t{{.Names}}\t{{.Label "${PREVIEW_SIDECAR_TASK_LABEL}"}}`;
+
+type LegacyTaskRow = Pick<
+  HostTask,
+  | "taskId"
+  | "composeProject"
+  | "worktreePath"
+  | "environmentProvider"
+  | "environmentLocator"
+  | "codeServerPort"
+  | "previewPorts"
+>;
+
+interface LegacyCandidate {
+  row: LegacyTaskRow;
+  composeProject: string;
+  containerName: string;
+  workspaceSource: string;
+}
+
+interface LegacyProof {
+  containerId: string;
+  containerName: string;
+}
+
+interface LegacyAdoption {
+  snapshot: LegacyTaskRow;
+  locator: TaskEnvironmentLocator;
+}
+
+export interface LegacyTaskEnvironmentAdoptionVerdict {
+  ok: boolean;
+  detail?: string;
+}
+
+export interface LegacyTaskEnvironmentAdoptionDeps {
+  docker?: typeof dockerCli;
+  loadTasks?: () => ReadonlyArray<LegacyTaskRow>;
+  /** Must atomically re-probe and return the still-selected daemon identity. */
+  reprobeMachine: () => Promise<HostMachineIdentity | null>;
+  /** Test seam. Production uses one synchronous SQLite transaction. */
+  persist?: (adoptions: ReadonlyArray<LegacyAdoption>) => void;
+}
+
+/**
+ * Adopt pre-provider rows without guessing which daemon owns them.
+ *
+ * Every Docker operation here is read-only. No locator is written until all
+ * legacy resources have an exact container proof and a final atomic daemon-ID
+ * re-probe confirms that the inspected engine is still the selected engine.
+ */
+export async function adoptLegacyTaskEnvironments(
+  machine: HostMachineIdentity,
+  deps: LegacyTaskEnvironmentAdoptionDeps,
+): Promise<LegacyTaskEnvironmentAdoptionVerdict> {
+  const rows = [...(deps.loadTasks?.() ?? loadHostTasks())];
+  const candidates: LegacyCandidate[] = [];
+  try {
+    for (const row of rows) {
+      const candidate = legacyCandidate(row, machine);
+      if (candidate) candidates.push(candidate);
+    }
+  } catch (error) {
+    return failedAdoption(error);
+  }
+  if (candidates.length === 0) return { ok: true };
+  if (machine.backend !== "docker") {
+    // legacyCandidate already failed such rows; this narrows the type and
+    // stays fail-closed if that invariant ever changes.
+    return failedAdoption(
+      new Error(
+        `legacy ambient-Docker resources cannot move to ${machine.backend}`,
+      ),
+    );
+  }
+
+  const docker = deps.docker ?? dockerCli;
+  const adoptions: LegacyAdoption[] = [];
+  try {
+    for (const candidate of candidates) {
+      const proof = await inspectLegacyCandidate(docker, candidate);
+      await proveNoConflictingAppContainer(docker, candidate, proof);
+      const row = candidate.row;
+      const locator = dockerTaskEnvironmentLocator(
+        row.taskId,
+        {
+          composeProject: candidate.composeProject,
+          worktreePath: row.worktreePath!,
+          ...(row.codeServerPort === null
+            ? {}
+            : { codeServerPort: row.codeServerPort }),
+          previewPorts: parsePreviewPortRuntimes(row.previewPorts),
+        },
+        machine,
+      );
+      adoptions.push({ snapshot: row, locator });
+    }
+
+    const reproved = await deps.reprobeMachine();
+    if (!sameMachine(machine, reproved)) {
+      throw new Error(
+        "the Docker daemon identity changed during legacy resource inspection",
+      );
+    }
+    (deps.persist ?? persistLegacyAdoptions)(adoptions);
+    return { ok: true };
+  } catch (error) {
+    return failedAdoption(error);
+  }
+}
+
+function loadHostTasks(): LegacyTaskRow[] {
+  return getDb().select().from(schema.hostTasks).all();
+}
+
+function legacyCandidate(
+  row: LegacyTaskRow,
+  machine: HostMachineIdentity,
+): LegacyCandidate | null {
+  if ((row.environmentProvider === null) !== (row.environmentLocator === null)) {
+    throw new Error(`task ${row.taskId} has incomplete provider metadata`);
+  }
+  if (row.environmentProvider !== null) {
+    const locator = parseTaskEnvironmentLocator(row.environmentLocator!);
+    if (locator.provider !== row.environmentProvider) {
+      throw new Error(
+        `task ${row.taskId} provider does not match its persisted locator`,
+      );
+    }
+    // A row with provider metadata is already adopted, whatever its backend:
+    // it only needs to belong to the currently-selected machine. Hard-coding
+    // docker-compose here wedged the first fresh Apple host (live
+    // 2026-08-15): a crash-preserved prepared apple locator made adoption —
+    // and with it runtime selection — fail closed, so the task could not
+    // even be settled.
+    let persistedMachine: HostMachineIdentity;
+    if (locator.provider === "docker-compose") {
+      persistedMachine = parseDockerTaskEnvironmentLocator(locator).machine;
+    } else if (locator.provider === APPLE_TASK_ENVIRONMENT_PROVIDER) {
+      persistedMachine = parseAppleTaskEnvironmentLocator(locator).machine;
+    } else {
+      throw new Error(
+        `task ${row.taskId} belongs to unavailable environment provider ${locator.provider}`,
+      );
+    }
+    if (!sameMachine(machine, persistedMachine)) {
+      throw new Error(
+        `task ${row.taskId} belongs to a different container backend identity`,
+      );
+    }
+    return null;
+  }
+  if (row.composeProject === null && row.worktreePath === null) return null;
+  if (row.composeProject === null || row.worktreePath === null) {
+    throw new Error(`task ${row.taskId} has incomplete legacy runtime identity`);
+  }
+  if (machine.backend !== "docker") {
+    throw new Error(
+      `task ${row.taskId} has legacy ambient-Docker resources and cannot move to ${machine.backend}`,
+    );
+  }
+  assertSafeHostTaskId(row.taskId);
+  const composeProject = `task-${row.taskId}`;
+  if (row.composeProject !== composeProject) {
+    throw new Error(`task ${row.taskId} has an unexpected legacy Compose project`);
+  }
+  if (
+    row.worktreePath.length === 0 ||
+    row.worktreePath.length > 4_096 ||
+    !path.isAbsolute(row.worktreePath) ||
+    path.resolve(row.worktreePath) !== row.worktreePath ||
+    /[\0\r\n]/.test(row.worktreePath)
+  ) {
+    throw new Error(`task ${row.taskId} has an unsafe legacy worktree path`);
+  }
+  return {
+    row,
+    composeProject,
+    containerName: `${composeProject}-app-1`,
+    workspaceSource: path.join(row.worktreePath, "workspace"),
+  };
+}
+
+async function inspectLegacyCandidate(
+  docker: typeof dockerCli,
+  candidate: LegacyCandidate,
+): Promise<LegacyProof | null> {
+  const result = await docker(
+    [
+      "inspect",
+      "--type",
+      "container",
+      "--format",
+      LEGACY_INSPECT_FORMAT,
+      candidate.containerName,
+    ],
+    { timeoutMs: 30_000, maxOutputBytes: INSPECT_OUTPUT_LIMIT },
+  );
+  // Exact absence is a settleable answer, not a failure: a pruned container
+  // must not strand the host in a degraded runtime with teardown fenced off.
+  // Only Docker's literal not-found error qualifies — a daemon that cannot
+  // answer still fails adoption closed.
+  if (
+    result.status !== 0 &&
+    /No such (?:container|object)/i.test(result.stderr)
+  ) {
+    return null;
+  }
+  const fields = exactTabFields(result, 6, "legacy app inspect");
+  const [containerId, containerName, composeProject, service, status, mounts] =
+    fields.map(parseJsonField);
+  if (!isContainerId(containerId)) {
+    throw new Error(`task ${candidate.row.taskId} returned an invalid container ID`);
+  }
+  if (containerName !== `/${candidate.containerName}`) {
+    throw new Error(`task ${candidate.row.taskId} app container name does not match`);
+  }
+  if (composeProject !== candidate.composeProject || service !== "app") {
+    throw new Error(`task ${candidate.row.taskId} Compose labels do not match`);
+  }
+  if (
+    typeof status !== "string" ||
+    ![
+      "created",
+      "running",
+      "paused",
+      "restarting",
+      "removing",
+      "exited",
+      "dead",
+    ].includes(status)
+  ) {
+    throw new Error(`task ${candidate.row.taskId} container state is invalid`);
+  }
+  validateWorkspaceMount(candidate, mounts);
+  return { containerId, containerName: candidate.containerName };
+}
+
+function validateWorkspaceMount(candidate: LegacyCandidate, value: unknown): void {
+  if (!Array.isArray(value) || value.length > 256) {
+    throw new Error(`task ${candidate.row.taskId} container mounts are invalid`);
+  }
+  const workspaceMounts = value.filter((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+    const destination = (entry as Record<string, unknown>).Destination;
+    return (
+      typeof destination === "string" &&
+      path.posix.normalize(destination) === "/workspace"
+    );
+  });
+  if (workspaceMounts.length !== 1) {
+    throw new Error(
+      `task ${candidate.row.taskId} must have exactly one /workspace mount`,
+    );
+  }
+  const mount = workspaceMounts[0] as Record<string, unknown>;
+  if (
+    mount.Type !== "bind" ||
+    mount.Destination !== "/workspace" ||
+    mount.Source !== candidate.workspaceSource
+  ) {
+    throw new Error(`task ${candidate.row.taskId} workspace bind does not match`);
+  }
+}
+
+async function proveNoConflictingAppContainer(
+  docker: typeof dockerCli,
+  candidate: LegacyCandidate,
+  expected: LegacyProof | null,
+): Promise<void> {
+  const result = await docker(
+    [
+      "ps",
+      "--all",
+      "--no-trunc",
+      "--filter",
+      `label=com.docker.compose.project=${candidate.composeProject}`,
+      "--filter",
+      "label=com.docker.compose.service=app",
+      "--format",
+      LEGACY_INVENTORY_FORMAT,
+    ],
+    { timeoutMs: 30_000, maxOutputBytes: INVENTORY_OUTPUT_LIMIT },
+  );
+  if (
+    result.status !== 0 ||
+    result.outputTruncated === true ||
+    Buffer.byteLength(result.stdout) > INVENTORY_OUTPUT_LIMIT
+  ) {
+    throw new Error(`task ${candidate.row.taskId} app inventory failed`);
+  }
+  if (result.stdout !== "" && !result.stdout.endsWith("\n")) {
+    throw new Error(`task ${candidate.row.taskId} app inventory failed`);
+  }
+  const appRows: string[][] = [];
+  for (const line of result.stdout === ""
+    ? []
+    : result.stdout.slice(0, -1).split("\n")) {
+    const fields = line.split("\t");
+    if (fields.length !== 3) {
+      throw new Error(`task ${candidate.row.taskId} app inventory failed`);
+    }
+    // A preview sidecar wearing the task's compose labels is not an app
+    // container; counting one here failed the whole runtime adoption closed
+    // (live 2026-08-18, six labeled browser sidecars on the Studio).
+    if (fields[2] !== "") continue;
+    appRows.push(fields);
+  }
+  if (expected === null) {
+    // The exact container is proven absent; adoption is sound only if no
+    // same-project replacement exists either.
+    if (appRows.length !== 0) {
+      throw new Error(
+        `task ${candidate.row.taskId} has conflicting app containers`,
+      );
+    }
+    return;
+  }
+  if (appRows.length !== 1) {
+    throw new Error(`task ${candidate.row.taskId} has conflicting app containers`);
+  }
+  const fields = appRows[0]!;
+  if (
+    fields[0] !== expected.containerId ||
+    fields[1] !== expected.containerName
+  ) {
+    throw new Error(`task ${candidate.row.taskId} app inventory does not match`);
+  }
+}
+
+function exactTabFields(
+  result: DockerResult,
+  count: number,
+  operation: string,
+): string[] {
+  if (
+    result.status !== 0 ||
+    result.outputTruncated === true ||
+    Buffer.byteLength(result.stdout) > INSPECT_OUTPUT_LIMIT ||
+    !result.stdout.endsWith("\n") ||
+    result.stdout.slice(0, -1).includes("\n")
+  ) {
+    throw new Error(`${operation} failed`);
+  }
+  const fields = result.stdout.slice(0, -1).split("\t");
+  if (fields.length !== count || fields.some((field) => field.length === 0)) {
+    throw new Error(`${operation} output is malformed`);
+  }
+  return fields;
+}
+
+function parseJsonField(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new Error("legacy app inspect output is malformed");
+  }
+}
+
+function isContainerId(value: unknown): value is string {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+
+function sameMachine(
+  expected: HostMachineIdentity,
+  actual: HostMachineIdentity | null,
+): boolean {
+  return (
+    actual !== null &&
+    actual.backend === expected.backend &&
+    actual.endpoint === expected.endpoint &&
+    actual.engineId === expected.engineId
+  );
+}
+
+function persistLegacyAdoptions(
+  adoptions: ReadonlyArray<LegacyAdoption>,
+): void {
+  getDb().transaction((tx) => {
+    for (const adoption of adoptions) {
+      const current = tx
+        .select()
+        .from(schema.hostTasks)
+        .where(eq(schema.hostTasks.taskId, adoption.snapshot.taskId))
+        .get();
+      if (!current || !sameLegacySnapshot(current, adoption.snapshot)) {
+        throw new Error(
+          `task ${adoption.snapshot.taskId} changed during legacy adoption`,
+        );
+      }
+      tx.update(schema.hostTasks)
+        .set({
+          environmentProvider: adoption.locator.provider,
+          environmentLocator: serializeTaskEnvironmentLocator(adoption.locator),
+          updatedAt: Date.now(),
+        })
+        .where(eq(schema.hostTasks.taskId, adoption.snapshot.taskId))
+        .run();
+    }
+  });
+}
+
+function sameLegacySnapshot(current: LegacyTaskRow, expected: LegacyTaskRow): boolean {
+  return (
+    current.taskId === expected.taskId &&
+    current.composeProject === expected.composeProject &&
+    current.worktreePath === expected.worktreePath &&
+    current.environmentProvider === null &&
+    current.environmentLocator === null &&
+    current.codeServerPort === expected.codeServerPort &&
+    current.previewPorts === expected.previewPorts
+  );
+}
+
+function failedAdoption(error: unknown): LegacyTaskEnvironmentAdoptionVerdict {
+  const detail = (error instanceof Error ? error.message : String(error)).slice(
+    0,
+    512,
+  );
+  return {
+    ok: false,
+    detail:
+      `${detail}. Start the ambient Docker daemon that owns this task and run ` +
+      "`uai-host runtime recheck`, or settle/remove the task before switching runtimes.",
+  };
+}

package/lib/task-environment/registry.ts

@@ -0,0 +1,58 @@
+import type {
+  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) {
+    return this.provider(locator.provider).reconstruct(locator);
+  }
+
+  kinds(): string[] {
+    return [...this.#providers.keys()].sort();
+  }
+}