@moondeck/station 0.0.0-stage → 1.0.0

package/lib/task-environment/types.ts

@@ -0,0 +1,642 @@
+/**
+ * Environment-level task boundary (ADR-101 Phase C).
+ *
+ * Providers own machine/container details. Generic orchestration receives an
+ * opaque, durable locator and a handle with bounded argv-based operations; it
+ * never receives a Docker socket, Compose project, or generic remote shell.
+ */
+
+export const TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION = 1 as const;
+
+/** Durable rollout generation for project environment delivery (ADR-153). */
+export type ProjectEnvMode = "baked" | "loader";
+
+/** Every process launch is explicitly classified at the type boundary. */
+export type ProjectEnvProfile = "maintenance" | "task";
+
+export interface TaskEnvironmentLocator {
+  schemaVersion: typeof TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION;
+  /** Stable provider registry key, for example `docker-compose`. */
+  provider: string;
+  /** Provider-owned, JSON-serializable reconstruction payload. */
+  value: unknown;
+}
+
+export interface TaskEnvironmentDescriptor {
+  taskId: string;
+  locator: TaskEnvironmentLocator;
+  /** Persisted independently from the provider locator for rollout safety. */
+  envMode?: ProjectEnvMode;
+  /** Absolute path as observed inside the environment. */
+  workspacePath: string;
+  codeServerPort?: number;
+  previewPorts?: Array<{ name: string; hostPort: number }>;
+  initWarning?: string;
+}
+
+export interface TaskEnvironmentExecRequest {
+  /** Executable followed by literal argv. Shell command strings are forbidden. */
+  argv: readonly [string, ...string[]];
+  cwd?: string;
+  user?: string;
+  /** Host environment names inherited by name, without copying values into argv. */
+  inheritEnv?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+  projectEnvProfile: ProjectEnvProfile;
+  stdin?: Uint8Array;
+  timeoutMs: number;
+  maxOutputBytes: number;
+  /**
+   * Run with every capability, as root only: the secrets proxy's NAT step
+   * needs NET_ADMIN, which a task container does not have (ADR-153). Docker
+   * only (`docker exec --privileged`, one process, the container keeps its
+   * default capabilities); every other provider refuses it.
+   */
+  privileged?: true;
+  /**
+   * ADR-154 §6: start the process under the engine supervisor, admitted by
+   * the runner and owned until a cleanup kills it. The provider runs, as
+   * root, the anchor's prefix, the task user the process would have run as
+   * (or "-" when the provider drops to it itself), "--", then the process
+   * as it would have run it; the supervisor drops to that user. A request
+   * that must run as root is never anchored.
+   */
+  anchor?: TaskEnvironmentAnchor;
+  /**
+   * Called by the provider at the last moment before the process starts,
+   * after anything it awaits first (a machine looks up its address);
+   * throwing refuses the exec unstarted. The secrets proxy's root-step
+   * fence rides on it, so a step's exec cannot start once its operation is
+   * no longer live, however long that lookup takes (ADR-153).
+   */
+  admit?: () => void;
+}
+
+export interface TaskEnvironmentExecResult {
+  exitCode: number | null;
+  signal: string | null;
+  stdout: Uint8Array;
+  stderr: Uint8Array;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+}
+
+export interface TaskEnvironmentSpawnRequest {
+  argv: readonly [string, ...string[]];
+  cwd?: string;
+  user?: string;
+  /** Host environment names inherited by name, without copying values into argv. */
+  inheritEnv?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+  projectEnvProfile: ProjectEnvProfile;
+  timeoutMs: number;
+  maxOutputBytes: number;
+  /** ADR-154 §6: see `TaskEnvironmentExecRequest.anchor`. */
+  anchor?: TaskEnvironmentAnchor;
+  /** See `TaskEnvironmentExecRequest.admit`. */
+  admit?: () => void;
+}
+
+/**
+ * ADR-154 §6: the engine supervisor a process starts under
+ * (credential-consumers/engine-anchor.ts): its argv up to the user it drops
+ * to.
+ */
+export interface TaskEnvironmentAnchor {
+  readonly prefix: readonly [string, ...string[]];
+  /**
+   * When the launch carries engine credentials in its admission: what a
+   * provider that drops to the task user itself (anchor user "-") runs
+   * right after that drop, before the process; it reads them from the
+   * supervisor's hand-off. A provider whose supervisor drops (a named user)
+   * ignores it: the supervisor hands them to the engine itself.
+   */
+  readonly injector?: readonly [string, ...string[]];
+}
+
+/**
+ * Long-lived process request used only by agent-session adapters. Its
+ * lifetime is owned by the session and therefore has no wall-clock timeout;
+ * unread stdout/stderr remains bounded by `maxOutputBytes`.
+ */
+export interface TaskEnvironmentSessionRequest {
+  argv: readonly [string, ...string[]];
+  cwd?: string;
+  user?: string;
+  inheritEnv?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+  projectEnvProfile: ProjectEnvProfile;
+  maxOutputBytes: number;
+  /** ADR-154 §6: see `TaskEnvironmentExecRequest.anchor`. */
+  anchor?: TaskEnvironmentAnchor;
+  /** See `TaskEnvironmentExecRequest.admit`. */
+  admit?: () => void;
+}
+
+/** A bounded control-plane launch of a detached durable-session runner. */
+export interface TaskEnvironmentDetachedSessionRequest
+  extends TaskEnvironmentSessionRequest {
+  launchTimeoutMs: number;
+}
+
+export interface TaskEnvironmentProcessExit {
+  exitCode: number | null;
+  signal: string | null;
+}
+
+/**
+ * Streaming process primitive used by durable agent sessions. Providers must
+ * keep output buffering within `maxOutputBytes`; AsyncIterable does not imply
+ * permission to retain an unbounded unread stream.
+ */
+export interface TaskEnvironmentProcess {
+  readonly stdout: AsyncIterable<Uint8Array>;
+  readonly stderr: AsyncIterable<Uint8Array>;
+  readonly completion: Promise<TaskEnvironmentProcessExit>;
+  write(chunk: Uint8Array): Promise<void>;
+  closeInput(): Promise<void>;
+  terminate(signal?: "SIGTERM" | "SIGKILL"): Promise<void>;
+}
+
+/**
+ * Provider-neutral surface handed to agent adapters. `durableIdentity` is an
+ * opaque diagnostic/persistence value; callers must never parse it as a
+ * container or machine identifier.
+ */
+export interface TaskEnvironmentAgentSessionSurface {
+  readonly descriptor: TaskEnvironmentDescriptor;
+  readonly durableIdentity: string;
+  /** ADR-154 §6: whether the provider starts a request's `anchor`. One that
+   *  does not never runs a leased engine. */
+  readonly anchors?: boolean;
+  /** ADR-154 §6: "admission" when a request's environment would reach a
+   *  command line (a machine's ssh command, a local shell line), so a leased
+   *  launch's engine credentials travel in its admission instead; absent
+   *  when the provider passes them by name (`--env NAME`). */
+  readonly credentialDelivery?: "admission";
+  spawnSession(
+    request: TaskEnvironmentSessionRequest,
+  ): Promise<TaskEnvironmentProcess>;
+  launchDetachedSession(
+    request: TaskEnvironmentDetachedSessionRequest,
+  ): Promise<TaskEnvironmentExecResult>;
+}
+
+export type TaskEnvironmentCopyRequest = (
+  | {
+      direction: "into";
+      /** Absolute host path. */
+      source: string;
+      /** Absolute environment path. */
+      destination: string;
+    }
+  | {
+      direction: "out";
+      /** Absolute environment path. */
+      source: string;
+      /** Absolute host path. */
+      destination: string;
+    }
+) &
+  TaskEnvironmentCallOptions;
+
+/** What every call into an environment may carry. */
+export interface TaskEnvironmentCallOptions {
+  /** See `TaskEnvironmentExecRequest.admit`: the provider's last word before
+   *  its process or transport starts, after anything it awaits first. */
+  admit?: () => void;
+}
+
+/** How much of a workspace file a read takes. The task controls its
+ *  workspace, so every read of it is bounded. */
+export interface TaskEnvironmentReadOptions extends TaskEnvironmentCallOptions {
+  /** At most this many bytes (default `WORKSPACE_READ_MAX_BYTES`). */
+  maxBytes?: number;
+  /** Which end of a longer file is read: its start (the default) or its
+   *  end. */
+  from?: "start" | "end";
+}
+
+/** The most a workspace read takes, unless it asks for less. */
+export const WORKSPACE_READ_MAX_BYTES = 64 * 1024 * 1024;
+/** How long a workspace read may take before it is given up. */
+export const WORKSPACE_READ_TIMEOUT_MS = 60_000;
+
+export interface TaskEnvironmentPort {
+  name?: string;
+  containerPort: number;
+  host: "127.0.0.1";
+  hostPort: number;
+}
+
+export type TaskEnvironmentStatus =
+  | {
+      state: "running" | "stopped" | "absent";
+      /** Provider-level runtime identities, mapped to the legacy wire's
+       * `containers` field while that protocol remains in service. */
+      instances: string[];
+      workspacePresent: boolean;
+      /** Not running, yet its processes still exist (a paused or
+       * restarting container): they run again without a new start. */
+      frozen?: true;
+    }
+  | { state: "unknown"; detail: string };
+
+/**
+ * Recovery is allowed to perform provider-private repair, but its caller owns
+ * the surrounding task/channel lifecycle. These callbacks keep that ordering
+ * explicit without exposing a Docker container, Compose project, or VM
+ * identity to generic orchestration.
+ */
+export interface TaskEnvironmentRecoveryContext {
+  /** One-way host maintenance latch (standard image, shared CLI state, etc.). */
+  maintenanceReady: Promise<void>;
+  /** Provider work must stop before every externally-visible side effect when
+   * this generation is no longer current. */
+  isCurrent(): boolean;
+  /** Drain/tombstone consumers before stopping or repairing a live writer. */
+  quarantineConsumers?: () => Promise<void>;
+  /** Reassert task-local security/runtime prerequisites before admission. */
+  prepareConsumers?: () => Promise<void>;
+  /** Re-open admission only after the environment is proven operational. */
+  allowConsumers?: () => void;
+  /** Recreate durable consumers after admission has reopened. */
+  ensureConsumersStarted?: () => Promise<void>;
+}
+
+export type TaskEnvironmentRecoveryResult =
+  | {
+      outcome: "recovered";
+      /** Optional fresh provider status. Recovery itself is the authoritative
+       * proof; callers must not issue a second inventory probe merely to fill
+       * this field. */
+      status?: TaskEnvironmentStatus;
+      descriptor?: TaskEnvironmentDescriptor;
+    }
+  | {
+      outcome: "deferred";
+      /** Bounded, operator-safe reason. Deferred recovery is retryable and
+       * must never be interpreted as absence. */
+      detail: string;
+    };
+
+export interface TaskEnvironmentHandle<TTeardownResult = void>
+  extends TaskEnvironmentAgentSessionSurface {
+  readonly descriptor: TaskEnvironmentDescriptor;
+  /** ADR-121 strangler ops: task-scoped file IO through the provider, so
+   * call sites stop knowing where the workspace physically lives. Paths are
+   * ENVIRONMENT-absolute and must sit inside the descriptor's workspace
+   * (assertWorkspaceScopedPath). Providers whose workspace is host-side
+   * (docker, apple) implement these as direct filesystem access — zero
+   * behavior change; machine providers reach over their transport. Read
+   * resolves null for a missing file and rejects for any other failure —
+   * absence and error are different facts. A read takes only a regular
+   * file, never waits on one it opens (a FIFO or device is refused), takes
+   * at most `maxBytes`, and is given up past its bound: what the task puts
+   * in its workspace never stalls the runner. */
+  readWorkspaceFile(path: string, options?: TaskEnvironmentReadOptions): Promise<Uint8Array | null>;
+  writeWorkspaceFile(path: string, bytes: Uint8Array, options?: TaskEnvironmentCallOptions): Promise<void>;
+  exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult>;
+  spawn(request: TaskEnvironmentSpawnRequest): Promise<TaskEnvironmentProcess>;
+  copy(request: TaskEnvironmentCopyRequest): Promise<void>;
+  ports(): Promise<TaskEnvironmentPort[]>;
+  status(): Promise<TaskEnvironmentStatus>;
+  recover(
+    context: TaskEnvironmentRecoveryContext,
+  ): Promise<TaskEnvironmentRecoveryResult>;
+  /** Resumable pause: halt the environment's processes while keeping every
+   * durable resource (worktree, volumes, container state) so a later
+   * provision/recovery can resume it. Idempotent for an already-stopped
+   * environment. */
+  stop(): Promise<void>;
+  /** Idempotent: success means provider-owned runtime resources are absent. */
+  teardown(): Promise<TTeardownResult>;
+  /**
+   * ADR-154 §6, the boot recovery sweep only (task-credential-cleanup.ts):
+   * run `work` in this exact runtime while it is stopped, by starting it
+   * for `work` alone and stopping it again after, whatever `work` did.
+   * Rejects, starting nothing, unless the runtime is provably this task's,
+   * stopped (not paused or restarting), idle by its own command, and starts
+   * nothing else of the project's either: no enabled healthcheck (its own or
+   * its image's), no restart policy, the runner's own init, no auto-remove.
+   * `oweStop` is called with the exact container's id before it starts; it
+   * must record durably that a stop is owed, and if it throws nothing
+   * starts. Rejects after `work` unless the container is proven stopped
+   * again. Never creates, recreates or removes anything. Providers that
+   * cannot do this omit it, and such a cleanup stays failed.
+   */
+  runStoppedForCleanup?<T>(
+    work: () => Promise<T>,
+    oweStop: (containerId: string) => void | Promise<void>,
+  ): Promise<T>;
+  /**
+   * An owed re-stop settled (`runStoppedForCleanup`): true only once the
+   * container with exactly this id is proven stopped (stopping it if it
+   * runs) or proven gone by a daemon that answered. A failed call is false,
+   * never gone.
+   */
+  settleCleanupStart?(containerId: string): Promise<boolean>;
+  /** Direct-route inspection for backends whose container IPs are
+   * host-routable (ADR-106 Apple vmnet). Providers that publish host ports
+   * instead simply omit it. The proof must bind the answer to this exact
+   * task's container (label check), not merely a name lookup. */
+  inspectRoute?(): Promise<
+    | { kind: "running"; ipv4Address: string }
+    | { kind: "unavailable" }
+    | { kind: "unknown"; detail: string }
+  >;
+  /** ADR-121, machine provider only: full ssh argv for the persistent
+   * REVERSE gateway tunnel that makes the host's MCP gateway answer on the
+   * environment's own loopback. Container providers omit it — their tasks
+   * route to the gateway via container topology instead. */
+  gatewayTunnelSshArgs?(
+    machinePort: number,
+    hostPort: number,
+    options?: TaskEnvironmentCallOptions,
+  ): Promise<string[]>;
+}
+
+export interface TaskEnvironmentProvisionRequest<TInput, TCredentials> {
+  taskId: string;
+  /** Omitted only by direct legacy/provider callers; new orchestration passes loader. */
+  envMode?: ProjectEnvMode;
+  input: TInput;
+  credentials: TCredentials;
+  /**
+   * Awaited after the provider has derived and validated its durable identity,
+   * but before it creates any external resources. A crash after this callback
+   * can therefore be recovered from the opaque locator alone.
+   */
+  onPrepared?: (locator: TaskEnvironmentLocator) => Promise<void>;
+}
+
+export interface TaskEnvironmentProvisioned<TResult, TTeardownResult = void> {
+  handle: TaskEnvironmentHandle<TTeardownResult>;
+  /** Provider launch result retained for rolling wire compatibility. */
+  result: TResult;
+  /** The provider reused an environment that already existed — a Resume's
+   *  stopped machine, whose disk holds the task's work — rather than creating
+   *  it. A failed start stops such an environment; it never destroys it. */
+  reused?: boolean;
+}
+
+export interface TaskEnvironmentProvider<
+  TInput,
+  TCredentials,
+  TResult,
+  TTeardownResult = void,
+> {
+  readonly kind: string;
+  provision(
+    request: TaskEnvironmentProvisionRequest<TInput, TCredentials>,
+  ): Promise<TaskEnvironmentProvisioned<TResult, TTeardownResult>>;
+  reconstruct(
+    locator: TaskEnvironmentLocator,
+    envMode?: ProjectEnvMode,
+  ): Promise<TaskEnvironmentHandle<TTeardownResult>>;
+}
+
+/** Workspace-scope guard for the strangler file ops: the path must be an
+ * absolute, NUL-free, dot-segment-free environment path inside the
+ * descriptor's workspace. Escaping the workspace through the file ops would
+ * hand callers the environment's whole filesystem. */
+export function assertWorkspaceScopedPath(
+  descriptor: TaskEnvironmentDescriptor,
+  path: string,
+): void {
+  if (!path.startsWith("/") || path.includes("\0")) {
+    throw new Error("workspace file path must be an absolute NUL-free path");
+  }
+  if (path.split("/").some((part) => part === "." || part === "..")) {
+    throw new Error("workspace file path must not contain dot segments");
+  }
+  const root = descriptor.workspacePath.endsWith("/")
+    ? descriptor.workspacePath
+    : `${descriptor.workspacePath}/`;
+  if (path !== descriptor.workspacePath && !path.startsWith(root)) {
+    throw new Error("workspace file path escapes the task workspace");
+  }
+}
+
+/** A malformed process request, distinct from provider/runtime failures. */
+export class TaskEnvironmentRequestValidationError extends Error {
+  override name = "TaskEnvironmentRequestValidationError";
+}
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Shared admission guard for provider implementations and fake providers. */
+/** A one-shot exec: the only request that may be privileged, and then only
+ *  as root. Providers pass the privilege on explicitly, never by reading the
+ *  request, so no other surface can carry it. */
+export function assertTaskEnvironmentExecRequest(request: TaskEnvironmentExecRequest): void {
+  const { privileged, ...unprivileged } = request;
+  if (privileged !== undefined && (privileged !== true || request.user !== "root")) {
+    throw new TaskEnvironmentRequestValidationError("a privileged task environment exec must run as root");
+  }
+  assertTaskEnvironmentProcessRequest(unprivileged);
+}
+
+export function assertTaskEnvironmentProcessRequest(
+  request: TaskEnvironmentExecRequest | TaskEnvironmentSpawnRequest,
+): void {
+  assertTaskEnvironmentSessionRequest(request);
+  if (!Number.isSafeInteger(request.timeoutMs) || request.timeoutMs <= 0) {
+    throw new TaskEnvironmentRequestValidationError("task environment timeout must be a positive integer");
+  }
+}
+
+/** For providers with no privileged exec: refuse it rather than run the
+ *  step without the capability it asked for. */
+export function refusePrivilegedExec(request: TaskEnvironmentExecRequest): void {
+  if (request.privileged === true) {
+    throw new TaskEnvironmentRequestValidationError("this task environment provider has no privileged exec");
+  }
+}
+
+export function assertTaskEnvironmentSessionRequest(
+  request:
+    | TaskEnvironmentSessionRequest
+    | TaskEnvironmentDetachedSessionRequest
+    | TaskEnvironmentExecRequest
+    | TaskEnvironmentSpawnRequest,
+): void {
+  // Only a one-shot exec may be privileged (assertTaskEnvironmentExecRequest
+  // strips it after checking); anywhere else it is refused outright.
+  if ("privileged" in request) {
+    throw new TaskEnvironmentRequestValidationError("only a one-shot task environment exec may be privileged");
+  }
+  if (
+    request.projectEnvProfile !== "maintenance" &&
+    request.projectEnvProfile !== "task"
+  ) {
+    throw new TaskEnvironmentRequestValidationError(
+      "task environment project env profile must be maintenance or task",
+    );
+  }
+  if (
+    !Array.isArray(request.argv) ||
+    request.argv.length === 0 ||
+    request.argv.some(
+      (part) => typeof part !== "string" || part.length === 0 || part.includes("\0"),
+    )
+  ) {
+    throw new TaskEnvironmentRequestValidationError("task environment argv must contain nonempty NUL-free strings");
+  }
+  if (
+    request.cwd !== undefined &&
+    (typeof request.cwd !== "string" || !request.cwd.startsWith("/") || request.cwd.includes("\0"))
+  ) {
+    throw new TaskEnvironmentRequestValidationError("task environment cwd must be an absolute NUL-free path");
+  }
+  if (
+    request.user !== undefined &&
+    (typeof request.user !== "string" || request.user.length === 0 || request.user.includes("\0"))
+  ) {
+    throw new TaskEnvironmentRequestValidationError("task environment user must be a nonempty NUL-free value");
+  }
+  if (
+    request.anchor !== undefined &&
+    (request.user === "root" ||
+      !Array.isArray(request.anchor.prefix) ||
+      request.anchor.prefix.length === 0 ||
+      request.anchor.prefix.some(
+        (part) => typeof part !== "string" || part.length === 0 || part.includes("\0"),
+      ))
+  ) {
+    throw new TaskEnvironmentRequestValidationError("a task environment anchor must be a NUL-free argv for a task user's process");
+  }
+  if (
+    request.inheritEnv !== undefined &&
+    (!Array.isArray(request.inheritEnv) ||
+      request.inheritEnv.length > 128 ||
+      new Set(request.inheritEnv).size !== request.inheritEnv.length ||
+      request.inheritEnv.some(
+        (name) => typeof name !== "string" || !ENV_NAME.test(name),
+      ))
+  ) {
+    throw new TaskEnvironmentRequestValidationError("task environment inherited env names are invalid");
+  }
+  for (const [name, value] of Object.entries(request.env ?? {})) {
+    if (
+      !ENV_NAME.test(name) ||
+      typeof value !== "string" ||
+      value.includes("\0")
+    ) {
+      throw new TaskEnvironmentRequestValidationError("task environment env must contain valid NUL-free entries");
+    }
+  }
+  if (
+    !Number.isSafeInteger(request.maxOutputBytes) ||
+    request.maxOutputBytes <= 0
+  ) {
+    throw new TaskEnvironmentRequestValidationError("task environment output limit must be a positive integer");
+  }
+  if (
+    "launchTimeoutMs" in request &&
+    (!Number.isSafeInteger(request.launchTimeoutMs) ||
+      request.launchTimeoutMs <= 0)
+  ) {
+    throw new TaskEnvironmentRequestValidationError(
+      "task environment detached launch timeout must be a positive integer",
+    );
+  }
+}
+
+export function serializeTaskEnvironmentLocator(
+  locator: TaskEnvironmentLocator,
+): string {
+  validateTaskEnvironmentLocator(locator);
+  return JSON.stringify(locator);
+}
+
+export function parseTaskEnvironmentLocator(raw: string): TaskEnvironmentLocator {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("task environment locator is not valid JSON");
+  }
+  return validateTaskEnvironmentLocator(parsed);
+}
+
+export function validateTaskEnvironmentLocator(
+  value: unknown,
+): TaskEnvironmentLocator {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("task environment locator must be an object");
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    Object.keys(record).sort().join("\0") !==
+    ["provider", "schemaVersion", "value"].sort().join("\0")
+  ) {
+    throw new Error("task environment locator has unexpected fields");
+  }
+  if (record.schemaVersion !== TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION) {
+    throw new Error("unsupported task environment locator schema");
+  }
+  if (
+    typeof record.provider !== "string" ||
+    !/^[a-z][a-z0-9-]{0,63}$/.test(record.provider)
+  ) {
+    throw new Error("task environment locator provider is invalid");
+  }
+  assertJsonValue(record.value, 0);
+  return {
+    schemaVersion: TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION,
+    provider: record.provider,
+    value: record.value,
+  };
+}
+
+function assertJsonValue(value: unknown, depth: number): void {
+  if (depth > 16) throw new Error("task environment locator is too deeply nested");
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("task environment locator contains a non-finite number");
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > 256) {
+      throw new Error("task environment locator array is too large");
+    }
+    for (const item of value) assertJsonValue(item, depth + 1);
+    return;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length > 256) {
+      throw new Error("task environment locator object is too large");
+    }
+    for (const [key, item] of entries) {
+      if (key.includes("\0")) {
+        throw new Error("task environment locator key contains NUL");
+      }
+      assertJsonValue(item, depth + 1);
+    }
+    return;
+  }
+  throw new Error("task environment locator is not JSON-serializable");
+}
+
+/**
+ * Providers whose workspace is reached only through the environment
+ * transport — a machine over ssh (ADR-121) or this very machine in sidecar
+ * mode (ADR-133) — as opposed to a container the host can `docker exec` into
+ * or bind-mount. Every "is this a machine task?" branch in the host means
+ * exactly this, so it asks here rather than comparing one provider name.
+ */
+export function isEnvironmentTransportProvider(
+  provider: string | null | undefined,
+): boolean {
+  return provider === "machine" || provider === "self";
+}