@moondeck/station 0.0.0-stage → 1.0.0

package/src/index.ts

@@ -0,0 +1,2899 @@
+import { assertShareablePath, normalizedWorkspacePath } from "./workspace-path-policy";
+import { readBoundedFile } from "../lib/task-environment/workspace-files";
+import {
+  agent,
+  AgentError,
+  CREDENTIALS_WITHDRAWN_MESSAGE,
+  toolStderrDetail,
+  type LeasedTaskUp,
+  type TaskDownResult,
+} from "../lib/agent";
+import {
+  activeCloudCredentials,
+  admitLegacyStart,
+  cloudCredentialRuntime,
+  credentialsMode,
+  onOwnCredentials,
+  whileOnOwnCredentials,
+  type LegacyStartPermit,
+} from "../lib/cloud-credential-host";
+import type { TaskAssignment } from "../lib/cloud-credential-leases";
+import {
+  StartInterruptedError,
+  type CloudCredentialRuntime,
+  type TaskCredentialStart,
+  type TaskUpHold,
+} from "../lib/cloud-credential-runtime";
+import { writeTaskPersonCredentials } from "../lib/credential-consumers/github";
+import { agentClisReady, ensureStandardImage } from "../lib/standard-image";
+import { cloneRepo } from "../lib/repo-clone";
+import { handleFilesOp } from "../lib/shared-files";
+import type { SharedFilesMode } from "../lib/shared-files-s3";
+import {
+  getOrchestrator,
+  inspectTaskRuntimeContainer,
+  proveAppleTaskRuntimeContract,
+  quarantineTaskRuntimeContainer,
+} from "../lib/orchestrator";
+import {
+  removeTaskCliSecretStrict,
+  storeTaskCliSecret,
+} from "../lib/agent-cli";
+import { stopMachineGatewayTunnel } from "../lib/machine-gateway-tunnel";
+import {
+  clearRefresh,
+  injectIntoContainer,
+  reconcileTaskGitAuth,
+  requestAccessToken,
+} from "../lib/github-tokens";
+import {
+  prepareTaskGithubGitCredential,
+  type TaskGithubGitCredential,
+} from "../lib/github-git-auth";
+import { readAttachment, writeAttachment } from "../lib/attachments";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { env, taskProjectWorktree, taskWorkspaceDir } from "../lib/env";
+import { getDecryptedForProject } from "../lib/host-env";
+import {
+  envSchemaNote,
+  missingRequiredKeys,
+  parseEnvSchema,
+} from "../lib/env-schema";
+import {
+  appendTranscript as writeTranscript,
+  appendTranscriptViaEnvironment,
+} from "../lib/transcript";
+import { buildTaskDiff } from "../lib/task-diff";
+import { taskProjectOps } from "../lib/task-project-ops-host";
+import { stoppedTaskDiff } from "../lib/task-diff-sandbox";
+import {
+  admitTaskRunEpoch,
+  canReuseTaskRuntimeForRun,
+  closeTaskRunAssignment,
+  closeTaskRunAssignmentForStop,
+  deleteHostTask,
+  getHostTask,
+  hostTaskEnvMode,
+  readTaskRunEpochState,
+  recordHostEvent,
+  recordTaskDown,
+  recordTaskEnvironmentPrepared,
+  recordTaskError,
+  recordTaskOwner,
+  recordTaskProjectEnvSpec,
+  recordTaskRuntimeEstablished,
+  recordTaskSharedFilesMode,
+  recordTaskStarting,
+  recordTaskUpResult,
+  taskProjectEnvSpec,
+  purgeHostTaskState,
+  upsertHostTask,
+} from "../lib/runtime-state";
+import {
+  clearTaskGatewayAcl,
+  clearTaskGatewayAclStrict,
+  waitForMcpGatewayReady,
+} from "../lib/mcp-gateway";
+import {
+  recoverTaskGatewayTask,
+  registerTaskGatewayTask,
+  reactivateTaskGatewayTask,
+  removeTaskGatewayTask,
+  suspendTaskGatewayTask,
+  taskGatewayForwarderSecretInput,
+} from "../lib/task-gateway-state";
+import { captureTaskEnvSchemas, forgetTaskEnvSchemaObservations } from "../lib/project-env-schema-capture";
+import { forgetTaskEnvSnapshot, taskEnvResolver, taskEnvWithheldNoteNow } from "../lib/task-env-source";
+import { activeSecretsProxy } from "../lib/secrets-proxy/host";
+import { secretsProxyEnabled } from "../lib/secrets-proxy/runtime";
+import { forgetTaskProxyReadiness } from "../lib/secrets-proxy/readiness";
+import { admitFreshTaskView } from "../lib/secrets-proxy/sidecar-view";
+import {
+  invalidateTaskWrites,
+  reconcileTaskProxyState,
+} from "../lib/secrets-proxy/task-trust";
+import { parsePreviewPortRuntimes } from "../lib/preview-ports";
+import { dockerCli } from "../lib/docker-exec";
+import {
+  claimContainerRuntimeForTask,
+  containerRuntimeGenerationOperational,
+  containerRuntimeProblem,
+  containerRuntimeReadinessEpoch,
+  containerRuntimeTeardownProblem,
+  ensureContainerRuntimeForTask,
+  initializeContainerRuntime,
+  pinnedContainerRuntimeProvider,
+  reprobeContainerRuntimeMachineIdentity,
+  suspendContainerRuntime,
+  waitForContainerRuntimeOperational,
+} from "../lib/container-runtime";
+import { vnodeAdmissionProblem } from "../lib/vnode-pressure";
+import { reclaimUnusedUaiComposeNetworks } from "../lib/compose-network-recovery";
+import {
+  machineTasksEnabled,
+  provisionTaskEnvironment,
+  reconstructPersistedTaskEnvironment,
+} from "../lib/task-environment";
+import { appleTaskContainerName } from "../lib/task-environment/apple-container";
+import type {
+  TaskEnvironmentHandle,
+  TaskEnvironmentLocator,
+  TaskEnvironmentStatus,
+} from "../lib/task-environment/types";
+import {
+  ensurePreviewSidecar,
+  stopPreviewSidecars,
+} from "../lib/preview-sidecar";
+import { inspectTunnelContainer } from "../lib/tunnel-runtime";
+import { ContainerRuntimeUnavailableError } from "../lib/runtime-guard";
+import {
+  managedRuntimeAdmissionBlocker,
+  reclaimAbandonedMaintenanceCheck,
+} from "../lib/managed-runtime";
+import { retireTaskSshIdentityEnsures } from "../lib/git-identity";
+import { removeTaskIdentityStrict } from "../lib/ssh";
+import { proveOrphanTaskResourcesAbsent } from "../lib/task-inventory";
+import {
+  HostErrorCode,
+  type CommandContext,
+  type ChannelEnsureInput,
+  type HostCommandResult,
+  type HostCommands,
+  type HostEventStream,
+  type PermissionDecision,
+  type TaskDiffInput,
+  type TaskDownInput,
+  type TaskLaunchInput,
+} from "./protocol";
+
+export type {
+  TaskDownResult,
+  TaskStatusResult,
+  TaskUpResult,
+} from "../lib/agent";
+
+import {
+  removeEngineAccount,
+  renameEngineAccount,
+  reorderEngineAccounts,
+} from "../lib/engine-accounts";
+import { disconnectEngine } from "../lib/engines";
+
+export {
+  parseMentions,
+  resolveAddressing,
+  buildSystemPreamble,
+} from "../lib/orchestrator";
+
+export {
+  AgentKind,
+  Roster,
+  RosterAgent,
+  parseRoster,
+} from "../lib/agents/types";
+export type {
+  AgentEvent,
+  AgentEventHandler,
+  AgentSession,
+  AgentSessionFactory,
+} from "../lib/agents/types";
+
+export {
+  capabilities as agentCapabilities,
+  factoryFor as agentFactoryFor,
+  list as listAgentAdapters,
+  register as registerAgentAdapter,
+  supportsExecutionProfile,
+} from "../lib/agents/registry";
+export type {
+  AgentKindCapability,
+  RegisteredAdapter,
+} from "../lib/agents/registry";
+
+export {
+  ASDF_DATA_VOLUME,
+  STANDARD_IMAGE_TAG,
+  STANDARD_RUNTIMES,
+  ensureStandardImage,
+  standardRuntimes,
+} from "../lib/standard-image";
+
+export { cloneRepo } from "../lib/repo-clone";
+export type { CloneRepoInput, CloneRepoResult } from "../lib/repo-clone";
+
+export { parseGitDiff } from "../lib/git-diff";
+export type { DiffFile, DiffHunk, DiffLine, DiffStatus } from "../lib/git-diff";
+
+export {
+  PREVIEW_PORT_NAME_RE,
+  PreviewPortDeclarationSchema,
+  PreviewPortDeclarationsSchema,
+  PreviewPortRuntimeSchema,
+  PreviewPortRuntimesSchema,
+  parsePreviewPortDeclarations,
+  parsePreviewPortRuntimes,
+} from "../lib/preview-ports";
+export type {
+  PreviewPortDeclaration,
+  PreviewPortRuntime,
+} from "../lib/preview-ports";
+import { isEnvironmentTransportProvider } from "../lib/task-environment/types";
+import { awaitSidecarReady, sidecarMode } from "../lib/sidecar";
+import { guardSidecarMachine } from "../lib/sidecar-guard";
+import { projectEnvBindingCapability } from "../lib/project-env-feature";
+import { awaitProjectEnvReplicaReady } from "../lib/project-env-replica";
+
+export const hostEvents: HostEventStream = {
+  subscribe(handler) {
+    return getOrchestrator().subscribeHostEvents(handler);
+  },
+};
+
+/** Set by main.ts at boot: the drain-then-supervisor-respawn used for
+ * staged activation. A hook (not an import) because main imports this
+ * module. */
+let managedHostRestartHook: (() => void) | null = null;
+export function setManagedHostRestartHook(hook: () => void): void {
+  managedHostRestartHook = hook;
+}
+
+/**
+ * ADR-133: a task machine's runner is pinned by the cloud at launch and its
+ * unit's cgroup holds the task itself — the S3 mounts, the display, the
+ * editor, the agent sessions. An in-place update or restart replaces
+ * nothing (the prepare step reinstalls the pin) and killed all of those
+ * (live 2026-09-10, smoke 10). Both verbs are refused here; a new task gets
+ * a fresh machine with the current runner.
+ */
+function sidecarRunnerIsPinned(): HostCommandResult<never> | null {
+  if (!sidecarMode()) return null;
+  return {
+    ok: false,
+    code: HostErrorCode.Internal,
+    message:
+      "a task machine's station is pinned for the task's life — it neither updates nor restarts in place; close the task and start another for the current station",
+    retryable: false,
+  };
+}
+
+type TaskUpCommand = HostCommands["taskUp"];
+type TaskUpOutcome = Awaited<ReturnType<TaskUpCommand>>;
+
+/**
+ * ADR-154: a start on cloud credentials, as task-up carries it. It begins in
+ * the short admission slot (the run's startup; every older start of the task
+ * interrupted), is awaited outside every slot, holds its installed grant
+ * through the long slot (the clone, provisioning and the runtime-ready
+ * writes), publishes its success only while it is still the task's current
+ * start with its credentials open, and is settled after: ended, or abandoned
+ * with its hold let go first.
+ */
+interface CloudCredentialTaskStart {
+  readonly runtime: CloudCredentialRuntime;
+  readonly assignment: TaskAssignment;
+  start: TaskCredentialStart | null;
+  hold: TaskUpHold | null;
+}
+
+/** The start's lease for task-up: its whole grant's hold, and what the
+ *  runner writes into the runtime once it exists (the owner's GitHub sign-in
+ *  and SSH key, recorded for cleanup) before anything in it runs. */
+function leasedTaskUp(
+  runtime: CloudCredentialRuntime,
+  start: TaskCredentialStart,
+  hold: TaskUpHold,
+  filesMode: SharedFilesMode,
+): LeasedTaskUp {
+  const filesV1 = runtime.taskFilesV1();
+  return {
+    // The whole grant's signal: its gate closing, a cleanup reaching it or
+    // the start being interrupted all end task-up.
+    clone: { ...hold.git, signal: hold.signal },
+    runtimeReady: async (environment, signal) => {
+      if (filesV1) {
+        await runtime.prepareTaskFiles(
+          start.assignment,
+          environment as TaskEnvironmentHandle<unknown>,
+          filesMode,
+          signal,
+        );
+      }
+      await writeTaskPersonCredentials(environment, start.assignment, undefined, signal);
+    },
+    ...(filesV1 ? { filesV1: true as const } : {}),
+  };
+}
+
+/** `wait`, given up (rejecting) as soon as the runner begins leaving its own
+ *  credentials, when what it waits for may never come. */
+function untilLeavingLegacy<T>(legacy: LegacyStartPermit | null, wait: Promise<T>): Promise<T> {
+  if (legacy === null) return wait;
+  const signal = legacy.signal;
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(signal.reason);
+    if (signal.aborted) onAbort();
+    else signal.addEventListener("abort", onAbort, { once: true });
+    wait.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/** A start the runner does not take while it switches its tasks to cloud
+ *  credentials: the cloud starts it again shortly. */
+function switchingToCloudCredentials(): HostCommandResult<never> {
+  return {
+    ok: false,
+    code: HostErrorCode.HostUnavailable,
+    message: "This host is switching its tasks to cloud credentials; the task starts once it is done.",
+    retryable: true,
+    retryReason: "managed_restart",
+  };
+}
+
+/** What a start reports when Stop, teardown, a newer run or shutdown
+ *  interrupted it, in place of its own outcome; null when none did. The
+ *  interruption that won decides: shutdown asks the cloud to start the
+ *  task again once the runner is back, anything else leaves a run that is
+ *  no longer current. */
+function interruptedStartResult(cloud: CloudCredentialTaskStart | null): TaskUpOutcome | null {
+  if (!cloud?.start?.signal.aborted) return null;
+  const reason: unknown = cloud.start.signal.reason;
+  if (reason instanceof StartInterruptedError && reason.by === "shutdown") {
+    return {
+      ok: false,
+      code: HostErrorCode.HostUnavailable,
+      message: "This host is restarting; the task starts once it is back.",
+      retryable: true,
+      retryReason: "managed_restart",
+    };
+  }
+  return {
+    ok: false,
+    code: HostErrorCode.TaskAlreadyRunning,
+    message: `task ${cloud.assignment.taskId} run ${String(cloud.assignment.runEpoch)} is no longer current: Stop, teardown or a newer run took over its start`,
+  };
+}
+
+/** The start's credentials closed for its run without an interruption:
+ *  removed, refused or replaced in the cloud. */
+function withdrawnStart(): TaskUpOutcome {
+  return { ok: false, code: HostErrorCode.Internal, message: CREDENTIALS_WITHDRAWN_MESSAGE };
+}
+
+/** The last word before a start publishes its success: null while it may.
+ *  Otherwise what it reports instead (`interrupted` when Stop, teardown, a
+ *  newer run or shutdown took over): its interruption's result, or a
+ *  withdrawn start's failure once its credentials are no longer open for
+ *  its run. */
+function cloudStartCannotPublish(
+  cloud: CloudCredentialTaskStart | null,
+): { result: TaskUpOutcome; interrupted: boolean } | null {
+  if (!cloud?.start) return null;
+  const interrupted = interruptedStartResult(cloud);
+  if (interrupted) return { result: interrupted, interrupted: true };
+  try {
+    cloud.start.assertCurrent();
+    return null;
+  } catch {
+    return { result: withdrawnStart(), interrupted: false };
+  }
+}
+
+/** The long slot's operation, the start's hold let go as it ends: a hold
+ *  never outlives the slot it was taken in, so a Stop or teardown queued
+ *  behind it never waits on it. */
+function releasingHold(
+  cloud: CloudCredentialTaskStart | null,
+  operation: () => Promise<TaskUpOutcome>,
+): () => Promise<TaskUpOutcome> {
+  return async () => {
+    try {
+      return await operation();
+    } finally {
+      cloud?.hold?.release();
+    }
+  };
+}
+
+async function taskUpOn(
+  ctx: Parameters<TaskUpCommand>[0],
+  input: Parameters<TaskUpCommand>[1],
+  cloud: CloudCredentialTaskStart | null,
+  legacy: LegacyStartPermit | null,
+): ReturnType<TaskUpCommand> {
+  const orchestrator = getOrchestrator();
+  let runEpochAdmission: ReturnType<typeof admitTaskRunEpoch>;
+  try {
+    if (input.task.runEpoch === undefined) {
+      // ADR-154: a start on the runner's own credentials only while the
+      // runner is still on them.
+      if (legacy?.valid() === false) return switchingToCloudCredentials();
+      // Preserve the v0 path exactly during the rolling window. It has no
+      // assignment floor to serialize and must keep failing cheap host
+      // preflights before entering the runtime lifecycle queue.
+      runEpochAdmission = admitTaskRunEpoch(input.task.id, undefined);
+    } else {
+      const admitted = await orchestrator.runTaskLifecycle(
+        input.task.id,
+        async () => {
+          // ADR-154: a start on the runner's own credentials is admitted
+          // only while the runner is still on them.
+          if (legacy?.valid() === false) {
+            return { ok: false as const, result: switchingToCloudCredentials() };
+          }
+          const admission = admitTaskRunEpoch(
+            input.task.id,
+            input.task.runEpoch,
+          );
+          if (admission.kind === "stale") {
+            return {
+              ok: false as const,
+              result: {
+                ok: false as const,
+                code: HostErrorCode.TaskAlreadyRunning,
+                message:
+                  `task ${input.task.id} run ${String(input.task.runEpoch)} is stale; ` +
+                  `this station has already admitted run ${String(admission.currentRunEpoch)}`,
+              },
+            };
+          }
+          // ADR-154: the run's credential startup begins in this short slot;
+          // its predecessor's cleanup and its grant are awaited outside it.
+          if (cloud !== null) {
+            try {
+              cloud.start = cloud.runtime.beginStart(cloud.assignment);
+            } catch (error) {
+              return {
+                ok: false as const,
+                result: {
+                  ok: false as const,
+                  code: HostErrorCode.HostUnavailable,
+                  message: `task ${input.task.id} could not begin on its cloud credentials: ${
+                    error instanceof Error ? error.message : String(error)
+                  }`,
+                  retryable: true,
+                  ...(error instanceof StartInterruptedError ? { retryReason: "managed_restart" as const } : {}),
+                },
+              };
+            }
+          }
+          return { ok: true as const, admission };
+        },
+      );
+      if (!admitted.ok) return admitted.result;
+      runEpochAdmission = admitted.admission;
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      code: HostErrorCode.Internal,
+      message:
+        error instanceof Error
+          ? error.message
+          : "the task run epoch is invalid",
+    };
+  }
+  // Admission alone never proves a runtime belongs to this assignment. A
+  // failed prior start can leave an open floor beside the older runtime.
+  const mayReuseRuntime = canReuseTaskRuntimeForRun(
+    input.task.id,
+    input.task.runEpoch,
+  );
+  const admissionFailure = managedMaintenanceUnavailable();
+  if (admissionFailure) return admissionFailure;
+  const runtimePreparationFailure = await prepareContainerRuntimeForTask();
+  if (runtimePreparationFailure) return runtimePreparationFailure;
+  const runtimeFailure = runtimeUnavailable();
+  if (runtimeFailure) return runtimeFailure;
+  // The boot reconcile briefly replaces CLI shims in the shared volume.
+  // Do not create local lifecycle/channel state until its one-way latch has
+  // settled (success or best-effort failure), then revalidate both mutable
+  // admission authorities after the await.
+  await agentClisReady;
+  const readyAdmissionFailure = managedMaintenanceUnavailable();
+  if (readyAdmissionFailure) return readyAdmissionFailure;
+  const readyRuntimeFailure = runtimeUnavailable();
+  if (readyRuntimeFailure) return readyRuntimeFailure;
+  try {
+    await waitForMcpGatewayReady();
+  } catch (error) {
+    console.warn(
+      `[task-gateway] refusing task ${input.task.id} before provisioning: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    return {
+      ok: false,
+      code: HostErrorCode.HostUnavailable,
+      message:
+        "The task environment gateway is not ready on this host. Retry the task; if it persists, check the host service log.",
+      retryable: true,
+    };
+  }
+  // A task machine's own guards first: its runner's data directory root's
+  // alone, and the metadata service closed to the task's user. Without
+  // them the task does not start: it could read the sidecar's host token.
+  if (sidecarMode()) {
+    const guard = guardSidecarMachine({ dataDir: env.dataDir });
+    if (!guard.ok) {
+      console.warn(`[sidecar] refusing task ${input.task.id}: ${guard.reason}`);
+      return {
+        ok: false,
+        code: HostErrorCode.Internal,
+        message: `This task machine is not safe to run the task on: ${guard.reason}. Close the task and start it again on a new machine.`,
+        retryable: false,
+      };
+    }
+  }
+  // A bindings-capable task sidecar must activate and commit its exact
+  // replica before any task state, /env generation or process can exist.
+  // Otherwise the source's intentional pre-activation legacy fallback
+  // could expose stored plaintext during the first reconciliation.
+  if (sidecarMode()) {
+    try {
+      // ADR-154: on cloud credentials the start's own grant is what readies
+      // it (awaited below); the v0 lease that readies the machine's stores
+      // never runs there.
+      if (cloud === null) await untilLeavingLegacy(legacy, awaitSidecarReady());
+      // ADR-154: and its env is the composer's, never the machine's replica.
+      if (cloud === null && projectEnvBindingCapability() !== null) {
+        await untilLeavingLegacy(legacy, awaitProjectEnvReplicaReady());
+      }
+    } catch (error) {
+      // ADR-154: the runner began leaving its own credentials, and with them
+      // the v0 lease this readiness comes from: the cloud starts the task
+      // again on cloud credentials.
+      if (legacy?.signal.aborted) return switchingToCloudCredentials();
+      console.warn(
+        `[task-env] refusing task ${input.task.id} before provisioning: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+      return {
+        ok: false,
+        code: HostErrorCode.HostUnavailable,
+        message:
+          "This task machine is still synchronizing its environment. Retry shortly.",
+        retryable: true,
+      };
+    }
+  }
+  // ADR-118 follow-up: each apple-container task is its own VM, and each
+  // VM pins host vnodes for its life. Refuse to start ANOTHER one when the
+  // table is nearly full — a clear, retryable refusal now beats ENFILE
+  // storms (and the suspected panic path) for the whole machine later.
+  if (pinnedContainerRuntimeProvider() === "apple-container") {
+    const vnodeProblem = await vnodeAdmissionProblem();
+    if (vnodeProblem) {
+      return {
+        ok: false,
+        code: HostErrorCode.HostUnavailable,
+        message: vnodeProblem,
+        retryable: true,
+      };
+    }
+  }
+  // ADR-154: the grant installed and its gate open, its env snapshot exact:
+  // awaited outside every lifecycle slot, and bounded.
+  if (cloud?.start) {
+    try {
+      await cloud.runtime.waitForLaunchReady(cloud.start);
+    } catch (error) {
+      return (
+        interruptedStartResult(cloud) ?? {
+          ok: false,
+          code: HostErrorCode.HostUnavailable,
+          message: `The task's cloud credentials did not become usable (${
+            error instanceof Error ? error.message : String(error)
+          }). Retry the task.`,
+          retryable: true,
+        }
+      );
+    }
+  }
+  // Every local Docker task consumes one daemon address-pool subnet. A task
+  // that failed after Compose created its network can retain an empty subnet
+  // while it waits for Resume. Reclaim only networks whose trusted host row,
+  // exact Docker identity and two empty-container inventories all agree. The
+  // sweep runs before this task's lifecycle slot and never waits on another
+  // task's: a candidate whose slot is busy is skipped, so concurrent starts
+  // neither deadlock nor queue behind one another's provisioning.
+  if (
+    !sidecarMode() &&
+    !machineTasksEnabled() &&
+    pinnedContainerRuntimeProvider() === "docker"
+  ) {
+    try {
+      const networkRecovery = await reclaimUnusedUaiComposeNetworks(
+        orchestrator,
+      );
+      if (networkRecovery.removed > 0) {
+        console.warn(
+          `[host-agent] reclaimed ${String(networkRecovery.removed)} empty UAI task ` +
+            `network(s) before starting ${input.task.id}`,
+        );
+      } else if (networkRecovery.inventory === "invalid") {
+        console.warn(
+          "[host-agent] skipped task-network recovery because Docker returned an invalid network inventory",
+        );
+      }
+      if (networkRecovery.busy > 0) {
+        console.log(
+          `[host-agent] task-network recovery left ${String(networkRecovery.busy)} ` +
+            `network(s) alone while their task was busy`,
+        );
+      }
+    } catch (error) {
+      // Best-effort capacity recovery must not block a task when Docker still
+      // has room. `docker compose up` remains the authoritative allocation.
+      console.warn(
+        `[host-agent] task-network recovery was unavailable: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+  return orchestrator.runTaskLifecycle(input.task.id, releasingHold(cloud, async () => {
+    // A direct duplicate teardown may still be draining operations that
+    // target this task's stable compose/container names. Never recreate
+    // those names until every close caller has crossed the shared fence.
+    await orchestrator.waitForChannelClose(input.task.id);
+    // Admission is a short lifecycle transaction before the long host
+    // preflights above. A newer dispatch may have advanced the durable
+    // floor while this command was waiting; once this command owns the
+    // lifecycle slot, reject it before it can observe or mutate a newer
+    // assignment's runtime.
+    const assignmentState = readTaskRunEpochState(input.task.id);
+    const assignmentCurrent =
+      input.task.runEpoch === undefined
+        ? assignmentState === null
+        : assignmentState !== null &&
+          assignmentState.assignmentOpen &&
+          assignmentState.highestRunEpoch === input.task.runEpoch;
+    if (!assignmentCurrent) {
+      const currentRunEpoch = assignmentState?.highestRunEpoch ?? 0;
+      return {
+        ok: false,
+        code: HostErrorCode.TaskAlreadyRunning,
+        message:
+          `task ${input.task.id} run ${String(input.task.runEpoch)} is no longer current; ` +
+          `this station has admitted run ${String(currentRunEpoch)}`,
+      };
+    }
+    const inSlotAdmissionFailure = managedMaintenanceUnavailable();
+    if (inSlotAdmissionFailure) return inSlotAdmissionFailure;
+    const inSlotRuntimeFailure = runtimeUnavailable();
+    if (inSlotRuntimeFailure) return inSlotRuntimeFailure;
+    // ADR-154: nothing of a start on the runner's own credentials happens
+    // once the runner has begun leaving them.
+    if (legacy?.valid() === false) return switchingToCloudCredentials();
+    // ADR-154: the start holds its installed grant from here through the
+    // clone, provisioning and the runtime-ready writes; without it nothing
+    // starts.
+    if (cloud?.start) {
+      try {
+        cloud.hold = cloud.runtime.tryAcquireTaskUpHold(cloud.start);
+      } catch (error) {
+        return {
+          ok: false,
+          code: HostErrorCode.HostUnavailable,
+          message: `The task's lease names credentials that could not be read (${
+            error instanceof Error ? error.message : String(error)
+          }). Retry the task.`,
+          retryable: true,
+        };
+      }
+      if (cloud.hold === null) return interruptedStartResult(cloud) ?? withdrawnStart();
+    }
+    // A command retry that arrives after the original start completed must
+    // not rerender/compose-up/uai-init underneath live agent sessions. Treat
+    // that lost-response retry as the successful operation it already was:
+    // every cloud caller records a non-ok taskUp as an errored task.
+    const existingTask = getHostTask(input.task.id);
+    const incomingEnvSpec = taskProjectEnvSpec(input);
+    let existingGatewayReady = true;
+    if (existingTask && hostTaskEnvMode(existingTask) === "loader") {
+      // A lost-response retry is also the repair path after a host process
+      // restart: reattach the live resolver before any task process can be
+      // treated as reusable. Missing/corrupt durable identity forces normal
+      // recreation, which mints a generation and restarts its forwarder.
+      recordTaskProjectEnvSpec(input.task.id, input);
+      existingGatewayReady =
+        recoverTaskGatewayTask(input.task.id, {
+          // The generation serves the run its runtime was established for.
+          resolveEnv: taskEnvResolver(input.task.id, incomingEnvSpec, existingTask.runEpoch > 0 ? existingTask.runEpoch : null),
+          runEpoch: existingTask.runEpoch > 0 ? existingTask.runEpoch : null,
+        }) !== null;
+    }
+    let runtimeQuarantinedForRecreate = false;
+    let channelClosedForRecreate = false;
+    if (
+      existingTask?.statusMirror === "running" &&
+      existingTask.environmentProvider === "apple-container"
+    ) {
+      // ADR-106/round-4: the lost-response fast path must speak the
+      // provider's language — the Docker branch below ENOENTs on a
+      // Docker-free Mac and suspended the generation instead of returning
+      // the persisted success.
+      if (!existingTask.composeProject || !existingTask.worktreePath) {
+        return {
+          ok: false,
+          code: HostErrorCode.Internal,
+          message:
+            `task ${input.task.id} is running but its persisted runtime ` +
+            "metadata is incomplete",
+        };
+      }
+      // Round 5: every await below can outlive the runtime generation
+      // (bridge revalidation, forced recheck). A superseded pass must
+      // observe only — never reopen consumers or mutate the container —
+      // the same discipline apple recovery applies.
+      // Round 6: the fence requires the OPERATIONAL generation, not merely
+      // the epoch — plain suspension (connection revalidation) keeps the
+      // epoch and ready status while the daemon is unverified.
+      const fastEpoch = containerRuntimeReadinessEpoch();
+      const fastStale = (): boolean =>
+        !containerRuntimeGenerationOperational(fastEpoch);
+      const staleRetry = {
+        ok: false as const,
+        code: HostErrorCode.HostUnavailable,
+        message:
+          `the container runtime generation changed while verifying task ${input.task.id}; retry`,
+        retryable: true,
+      };
+      const environment = await reconstructPersistedTaskEnvironment(
+        existingTask,
+      );
+      if (fastStale()) return staleRetry;
+      if (environment === null) {
+        // The persisted locator no longer reconstructs (e.g. an engine
+        // identity change) — recreate through the normal path.
+        suspendTaskGatewayTask(input.task.id);
+        await orchestrator.closeChannel(input.task.id);
+        // Session drain can outlive the generation too: a superseded pass
+        // must not reach recordTaskStarting/provisioning below.
+        if (fastStale()) return staleRetry;
+        channelClosedForRecreate = true;
+      } else {
+        const appleStatus = await environment.status();
+        if (fastStale()) return staleRetry;
+        if (appleStatus.state === "unknown") {
+          return {
+            ok: false,
+            code: HostErrorCode.HostUnavailable,
+            message:
+              `could not verify runtime state for task ${input.task.id}: ` +
+              appleStatus.detail,
+            retryable: true,
+          };
+        }
+        if (appleStatus.state === "running") {
+          const verdict = await proveAppleTaskRuntimeContract({
+            taskId: input.task.id,
+            containerName: appleTaskContainerName(input.task.id),
+            // The row's worktreePath is task-up's $task_dir — the same
+            // directory the apple locator records as hostWorktreePath.
+            hostWorktreePath: existingTask.worktreePath,
+          });
+          if (fastStale()) return staleRetry;
+          if (verdict.kind === "unreachable") {
+            return {
+              ok: false,
+              code: HostErrorCode.HostUnavailable,
+              message:
+                `could not prove the exact runtime contract for task ${input.task.id}: ` +
+                verdict.detail,
+              retryable: true,
+            };
+          }
+          let projectsHealthy = true;
+          for (const project of verdict.kind === "holds"
+            ? input.projects
+            : []) {
+            const gitHealth = await environment.exec({
+              projectEnvProfile: "maintenance",
+              argv: [
+                "/usr/bin/env",
+                "-i",
+                "HOME=/home/node",
+                "PATH=/usr/bin:/bin",
+                "/usr/bin/git",
+                "rev-parse",
+                "--is-inside-work-tree",
+              ],
+              user: "node",
+              cwd: `/workspace/${project.slug}`,
+              env: {},
+              timeoutMs: 10_000,
+              maxOutputBytes: 64 * 1024,
+            });
+            if (fastStale()) return staleRetry;
+            if (gitHealth.exitCode === null || gitHealth.signal !== null) {
+              return {
+                ok: false,
+                code: HostErrorCode.HostUnavailable,
+                message:
+                  `could not verify Git state for task ${input.task.id} ` +
+                  `project ${project.id}: the runtime did not answer`,
+                retryable: true,
+              };
+            }
+            if (
+              gitHealth.exitCode !== 0 ||
+              Buffer.from(gitHealth.stdout).toString("utf8").trim() !==
+                "true"
+            ) {
+              projectsHealthy = false;
+              console.warn(
+                `[host-agent] task ${input.task.id}: project ${project.id} Git health check failed; rebuilding the running task`,
+              );
+              break;
+            }
+          }
+          if (
+            verdict.kind === "holds" &&
+            projectsHealthy &&
+            existingGatewayReady &&
+            mayReuseRuntime
+          ) {
+            if (fastStale()) return staleRetry;
+            const cannotPublish = cloudStartCannotPublish(cloud);
+            if (cannotPublish) return cannotPublish.result;
+            orchestrator.allowChannel(input.task.id);
+            return {
+              ok: true,
+              value: {
+                composeProject: existingTask.composeProject,
+                worktreePath: existingTask.worktreePath,
+                codeServerPort: existingTask.codeServerPort ?? undefined,
+                previewPorts: parsePreviewPortRuntimes(
+                  existingTask.previewPorts,
+                ),
+                envMode: hostTaskEnvMode(existingTask),
+              },
+            };
+          }
+          // Violated contract or broken project repo: drain, stop, and
+          // prove before task-up recreates the same stable name.
+          if (fastStale()) return staleRetry;
+          suspendTaskGatewayTask(input.task.id);
+          await orchestrator.closeChannel(input.task.id);
+          channelClosedForRecreate = true;
+          if (fastStale()) return staleRetry;
+          await environment.stop();
+          const after = await environment.status();
+          if (fastStale()) return staleRetry;
+          if (after.state === "running" || after.state === "unknown") {
+            return {
+              ok: false,
+              code: HostErrorCode.HostUnavailable,
+              message:
+                `task ${input.task.id} has a non-current runtime contract and ` +
+                "could not be proven stopped; retry after the runtime is healthy",
+              retryable: true,
+            };
+          }
+          // Round 5: the container is PHYSICALLY stopped now, whatever the
+          // reason (violated contract or a broken project repo). A failed
+          // recreation must roll the mirror back to stopped — restoring
+          // "running" would advertise a container proven not to run.
+          runtimeQuarantinedForRecreate = true;
+        } else {
+          // Provider proved the container absent/stopped: normal self-heal
+          // recreate — and the rollback state must say stopped for the
+          // same reason as above.
+          if (fastStale()) return staleRetry;
+          suspendTaskGatewayTask(input.task.id);
+          await orchestrator.closeChannel(input.task.id);
+          // Fence AFTER the drain as well: provisioning must never start
+          // under a generation this pass no longer owns.
+          if (fastStale()) return staleRetry;
+          channelClosedForRecreate = true;
+          runtimeQuarantinedForRecreate = true;
+        }
+      }
+    } else if (
+      existingTask?.statusMirror === "running" &&
+      isEnvironmentTransportProvider(existingTask.environmentProvider)
+    ) {
+      // ADR-121: a machine-backed task revalidates through its own
+      // provider — the compose fast path below speaks docker and would
+      // misread a machine row. Running machine → persisted success;
+      // anything else falls through to provisionTaskEnvironment, whose
+      // machine provider owns recovery semantics.
+      try {
+        const environment = await reconstructPersistedTaskEnvironment(
+          existingTask,
+        );
+        if (environment) {
+          const machineStatus = await environment.status();
+          if (
+            machineStatus.state === "running" &&
+            existingGatewayReady &&
+            mayReuseRuntime
+          ) {
+            const cannotPublish = cloudStartCannotPublish(cloud);
+            if (cannotPublish) return cannotPublish.result;
+            orchestrator.allowChannel(input.task.id);
+            return {
+              ok: true,
+              value: {
+                composeProject: existingTask.composeProject ?? "",
+                worktreePath: existingTask.worktreePath ?? "",
+                codeServerPort: existingTask.codeServerPort ?? undefined,
+                envMode: hostTaskEnvMode(existingTask),
+              },
+            };
+          }
+        }
+      } catch (error) {
+        console.warn(
+          `[machine] task ${input.task.id}: running-row revalidation failed, continuing to provision: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    } else if (existingTask?.statusMirror === "running") {
+      if (!existingTask.composeProject || !existingTask.worktreePath) {
+        return {
+          ok: false,
+          code: HostErrorCode.Internal,
+          message:
+            `task ${input.task.id} is running but its persisted runtime ` +
+            "metadata is incomplete",
+        };
+      }
+      // The mirror may be stale after a manual `docker compose down`.
+      // Confirm the app itself is live before treating this as a lost-response
+      // retry; otherwise fall through to the normal taskUp self-heal.
+      const appRuntime = await dockerCli(
+        [
+          "ps",
+          "-a",
+          "--filter",
+          `label=com.docker.compose.project=${existingTask.composeProject}`,
+          "--filter",
+          "label=com.docker.compose.service=app",
+          "--format",
+          "{{.State}}",
+        ],
+        { timeoutMs: 10_000 },
+      );
+      if (appRuntime.status !== 0) {
+        return dockerUnavailableResult(
+          `could not verify runtime state for task ${input.task.id}: ` +
+            (appRuntime.stderr.trim().slice(0, 200) ||
+              "docker did not answer"),
+        );
+      }
+      if (
+        appRuntime.stdout
+          .split(/\r?\n/)
+          .some((state) => state.trim() === "running")
+      ) {
+        const appContainer = `${existingTask.composeProject}-app-1`;
+        const runtimeContract = await inspectTaskRuntimeContainer(
+          input.task.id,
+          existingTask.composeProject,
+        );
+        if (runtimeContract.kind === "unreachable") {
+          return dockerUnavailableResult(
+            `could not inspect the exact runtime mount for task ${input.task.id}`,
+          );
+        }
+        if (runtimeContract.kind === "failed") {
+          return {
+            ok: false,
+            code: HostErrorCode.HostUnavailable,
+            message:
+              `could not prove the exact runtime contract for task ${input.task.id}: ` +
+              runtimeContract.detail,
+            retryable: true,
+          };
+        }
+        const reusable =
+          runtimeContract.running &&
+          !runtimeContract.restarting &&
+          !runtimeContract.paused &&
+          runtimeContract.sharedMount === "read-only" &&
+          runtimeContract.taskEnvironment === "current" &&
+          existingGatewayReady &&
+          mayReuseRuntime;
+        if (!reusable) {
+          // Drain/tombstone before touching the exact container. task-up's
+          // pre-materialization cleanup then removes this stopped immutable
+          // generation, so Compose must create the current RO/private-prefix
+          // contract rather than `docker start`ing it again.
+          suspendTaskGatewayTask(input.task.id);
+          await orchestrator.closeChannel(input.task.id);
+          channelClosedForRecreate = true;
+          const quarantined = await quarantineTaskRuntimeContainer({
+            taskId: input.task.id,
+            composeProject: existingTask.composeProject,
+            expectedContainerId: runtimeContract.containerId,
+          });
+          if (quarantined === "unreachable") {
+            return dockerUnavailableResult(
+              `Docker became unavailable while quarantining task ${input.task.id}`,
+            );
+          }
+          if (quarantined === "failed") {
+            return {
+              ok: false,
+              code: HostErrorCode.HostUnavailable,
+              message:
+                `task ${input.task.id} has a non-current runtime contract and ` +
+                "could not be proven stopped; retry after Docker is healthy",
+              retryable: true,
+            };
+          }
+          runtimeQuarantinedForRecreate = true;
+        }
+        // Docker being up is not enough to prove a lost-response retry is
+        // healthy. The worktree's `.git` file contains an absolute pointer
+        // into the task-private repository; after a host workspace-root
+        // migration the old container can keep running while every agent
+        // sees `fatal: not a git repository`. Probe from INSIDE the live
+        // container, which is the filesystem view the agents actually use.
+        // Scratchpads have no projects, so this remains an O(1) fast path.
+        let projectsHealthy = true;
+        for (const project of reusable ? input.projects : []) {
+          const gitHealth = await dockerCli(
+            [
+              "exec",
+              "-u",
+              "node",
+              // docker exec inherits the Compose/project environment. Clear
+              // loader and Git controls before the first executable, then
+              // give Git a minimal environment of its own. Keep this aligned
+              // with task-up.sh's managed container operations.
+              "-e",
+              "HOME=/home/node",
+              "-e",
+              "PATH=/usr/bin:/bin",
+              "-e",
+              "LD_PRELOAD=",
+              "-e",
+              "LD_LIBRARY_PATH=",
+              "-e",
+              "DYLD_INSERT_LIBRARIES=",
+              "-e",
+              "DYLD_LIBRARY_PATH=",
+              "-e",
+              "BASH_ENV=",
+              "-e",
+              "ENV=",
+              "-e",
+              "GIT_CONFIG=",
+              "-e",
+              "GIT_CONFIG_GLOBAL=",
+              "-e",
+              "GIT_CONFIG_SYSTEM=",
+              "-e",
+              "GIT_CONFIG_NOSYSTEM=",
+              "-e",
+              "GIT_CONFIG_COUNT=0",
+              "-e",
+              "GIT_EXEC_PATH=",
+              "-e",
+              "GIT_SSH=",
+              "-e",
+              "GIT_SSH_COMMAND=",
+              "-e",
+              "GIT_ASKPASS=",
+              "-e",
+              "SSH_ASKPASS=",
+              "-w",
+              `/workspace/${project.slug}`,
+              appContainer,
+              "/usr/bin/env",
+              "-i",
+              "HOME=/home/node",
+              "PATH=/usr/bin:/bin",
+              "/usr/bin/git",
+              "rev-parse",
+              "--is-inside-work-tree",
+            ],
+            { timeoutMs: 10_000 },
+          );
+          // A timeout/spawn error is not proof that the repository is
+          // broken. Preserve the running task and let the caller retry once
+          // Docker can answer, just as the runtime-state probe above does.
+          if (gitHealth.status === null) {
+            return dockerUnavailableResult(
+              `could not verify Git state for task ${input.task.id} ` +
+                `project ${project.id}: ` +
+                (gitHealth.stderr.trim().slice(0, 200) ||
+                  "docker did not answer"),
+            );
+          }
+          if (
+            gitHealth.status !== 0 ||
+            gitHealth.stdout.trim() !== "true"
+          ) {
+            if (gitHealth.status !== 0) {
+              const unavailable = await runtimeFailureIfDaemonUnavailable(
+                `could not verify Git state for task ${input.task.id} ` +
+                  `project ${project.id}: ` +
+                  (gitHealth.stderr.trim().slice(0, 200) ||
+                    `git exited ${String(gitHealth.status)}`),
+              );
+              if (unavailable) return unavailable;
+            }
+            projectsHealthy = false;
+            console.warn(
+              `[host-agent] task ${input.task.id}: project ${project.id} Git health check failed; rebuilding the running task (${gitHealth.stderr.trim().slice(0, 200) || `git exited ${String(gitHealth.status)}`})`,
+            );
+            break;
+          }
+        }
+        if (reusable && projectsHealthy) {
+          // waitForChannelClose crossed the teardown fence above. A completed
+          // close-only teardown may have left this running task tombstoned,
+          // so the idempotent-success transition must reopen delivery just
+          // like a fresh successful taskUp does.
+          const cannotPublish = cloudStartCannotPublish(cloud);
+          if (cannotPublish) return cannotPublish.result;
+          orchestrator.allowChannel(input.task.id);
+          return {
+            ok: true,
+            value: {
+              composeProject: existingTask.composeProject,
+              worktreePath: existingTask.worktreePath,
+              codeServerPort: existingTask.codeServerPort ?? undefined,
+              previewPorts: parsePreviewPortRuntimes(
+                existingTask.previewPorts,
+              ),
+              envMode: hostTaskEnvMode(existingTask),
+            },
+          };
+        }
+      }
+      // Docker positively proved the mirrored app is absent/stopped, or the
+      // live container proved one of its project repositories is broken.
+      // Drain and invalidate any stale in-memory channel before taskUp
+      // recreates the same stable compose/container names and repairs Git.
+      if (!channelClosedForRecreate) {
+        suspendTaskGatewayTask(input.task.id);
+        await orchestrator.closeChannel(input.task.id);
+      }
+    }
+    const priorRuntimeState = existingTask
+      ? runtimeQuarantinedForRecreate
+        ? {
+            statusMirror: "stopped",
+            codeServerPort: null,
+            previewPorts: "[]",
+            lockedAt: null,
+            startedAt: existingTask.startedAt,
+            endedAt: existingTask.endedAt,
+            environmentProvider: existingTask.environmentProvider,
+            environmentLocator: existingTask.environmentLocator,
+            envMode: existingTask.envMode,
+            projectEnvSpec: existingTask.projectEnvSpec,
+            sharedFilesMode: existingTask.sharedFilesMode,
+            runEpoch: existingTask.runEpoch,
+          }
+        : {
+            statusMirror: existingTask.statusMirror,
+            lockedAt: existingTask.lockedAt,
+            startedAt: existingTask.startedAt,
+            endedAt: existingTask.endedAt,
+            environmentProvider: existingTask.environmentProvider,
+            environmentLocator: existingTask.environmentLocator,
+            envMode: existingTask.envMode,
+            projectEnvSpec: existingTask.projectEnvSpec,
+            sharedFilesMode: existingTask.sharedFilesMode,
+            runEpoch: existingTask.runEpoch,
+          }
+      : {
+          statusMirror: input.task.status,
+          lockedAt: null,
+          startedAt: null,
+          endedAt: null,
+        };
+    // ADR-153 machines: a task with no row has never run on this machine,
+    // so everything it runs comes through its hosts view. Recorded before
+    // the row, and so before the task's first process; a task with a row
+    // (a start driven again, a start after a stop) stands as recorded.
+    const taskWasKnownBeforeAssignment =
+      runEpochAdmission.kind === "accepted"
+        ? runEpochAdmission.hadTask
+        : existingTask !== null;
+    if (sidecarMode() && !taskWasKnownBeforeAssignment) {
+      admitFreshTaskView(input.task.id);
+    }
+    if (input.task.runEpoch === undefined) {
+      recordTaskStarting(input.task.id);
+    } else {
+      recordTaskStarting(input.task.id, input.task.runEpoch);
+    }
+    // Files-v1 recovery gets its mode only from a launch already admitted on
+    // cloud credentials, never from the task-writable marker. A legacy start
+    // must leave the column null so cutover can distinguish and retire it.
+    const sharedFilesMode = cloud
+      ? recordTaskSharedFilesMode(input.task.id, input.task)
+      : null;
+    // Cross-process managed maintenance and task admission use a two-sided
+    // handshake: update/uninstall writes its durable marker before checking
+    // this DB row; task-up writes `starting` before checking admission again.
+    // Whichever arrives second observes the first, so a runtime cannot be
+    // swapped or removed while an unrecorded task enters Docker side effects.
+    const admittedMaintenanceFailure = managedMaintenanceUnavailable();
+    if (admittedMaintenanceFailure) {
+      if (existingTask) upsertHostTask(input.task.id, priorRuntimeState);
+      else deleteHostTask(input.task.id);
+      if (!runtimeQuarantinedForRecreate) {
+        orchestrator.allowChannel(input.task.id);
+      }
+      return admittedMaintenanceFailure;
+    }
+    recordTaskOwner(
+      input.task.id,
+      input.task.ownerUserId,
+      input.ownerEmail ?? null,
+      input.ownerName ?? null,
+      input.projects.map((p) => p.slug),
+      // ADR-131 D3: persisted so recovery re-provisions the same scope.
+      input.task.engineAccountScope ?? null,
+      // Lead project first (position 0 wins env collisions, as in task-up).
+      [...input.projects]
+        .sort((a, b) => a.position - b.position)
+        .map((p) => p.id),
+    );
+    recordTaskProjectEnvSpec(input.task.id, input);
+    // ADR-048: persist the cloud-issued per-task cli secret (host-private) so the
+    // `uai` CLI's per-agent tokens can be minted now + after a host restart.
+    if (input.task.cliSecret) {
+      storeTaskCliSecret(input.task.id, input.task.cliSecret);
+    }
+    recordHostEvent(input.task.id, "task.created");
+    let environmentLocator: TaskEnvironmentLocator | undefined;
+    // The locator of everything this start may create, recorded before any
+    // of it exists: once set, the row must keep it.
+    let runtimePrepared = false;
+    const recordPrepared = async (locator: TaskEnvironmentLocator): Promise<void> => {
+      recordTaskEnvironmentPrepared(input.task.id, locator, "loader");
+      runtimePrepared = true;
+    };
+    let registeredTaskGatewayGeneration: string | null = null;
+    let result: TaskUpOutcome = await wrapAgent(ctx, "taskUp", async () => {
+      // Self-heal the standard base image before task-up needs it. The
+      // boot-time build is best-effort + one-shot: a host that started before
+      // Docker was ready (common on Docker Desktop) never built
+      // moondeck-standard:dev, so every task-up died on a doomed registry pull
+      // (live 2026-07-22). This is idempotent — a fast inspect when present,
+      // a real build only when missing/stale (Docker is definitely up now, a
+      // task just arrived). On a build FAILURE, surface WHY to the cloud (not
+      // just the host log — the operator can't read a remote user's machine).
+      // A pass that succeeded within the hour is reused (2026-09-09: the
+      // re-check cost 16 s of every task start); the hourly schedule in
+      // main.ts and the boot pass keep it fresh.
+      const img = await ensureStandardImage({ maxAgeMs: 60 * 60_000 });
+      if (!img.ok) {
+        throw new AgentError(
+          "STANDARD_IMAGE_UNAVAILABLE",
+          img.error
+            ? `could not prepare the host base image moondeck-standard:dev — the build failed. ${toolStderrDetail(img.error)}`
+            : "could not prepare the host base image moondeck-standard:dev — see the host log.",
+          {},
+        );
+      }
+      let gitCredential: TaskGithubGitCredential | null;
+      try {
+        // ADR-154: a start on cloud credentials clones with its lease's,
+        // never the runner's own store.
+        gitCredential = cloud === null && input.projects.some((project) =>
+          isGithubRepo(project.repoUrl),
+        )
+          ? await prepareTaskGithubGitCredential(input.task.ownerUserId)
+          : null;
+      } catch {
+        throw new AgentError(
+          "GITHUB_AUTH_UNAVAILABLE",
+          "GitHub is connected on this host, but Moondeck could not prepare its credential for Git. Retry the task; if it persists, reconnect GitHub on this host.",
+        );
+      }
+      if (sidecarMode() && cloud === null) {
+        // ADR-133: project env lives under /uai/projects/<id>, readable by
+        // the lease only for parameters tagged with this org, and only the
+        // task's own projects are worth listing — their ids are known here,
+        // not at the first grant (docs/credential-store.md).
+        const { reconcileProjectEnvFromStore } = await import("../lib/user-credentials-store");
+        const projectIds = input.projects.map((project) => project.id);
+        const env = await reconcileProjectEnvFromStore({ projectIds }).catch((error: unknown) => {
+          console.warn(
+            `[project-env] task ${input.task.id}: credential store read failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+          return null;
+        });
+        if (env && !env.skipped) {
+          console.log(
+            `[project-env] task ${input.task.id}: credential store reconciled for ${projectIds.length} project(s): ${env.imported} imported, ${env.removed} removed, ${env.errors} errors`,
+          );
+        }
+      }
+      // Mint the authenticated task generation before its environment
+      // starts. The declarations are pinned; values remain live DB reads.
+      const gatewayRegistration = registerTaskGatewayTask(input.task.id, {
+        resolveEnv: taskEnvResolver(input.task.id, incomingEnvSpec, input.task.runEpoch ?? null),
+        runEpoch: input.task.runEpoch ?? null,
+      });
+      registeredTaskGatewayGeneration = gatewayRegistration.generation;
+      const gatewaySecret = taskGatewayForwarderSecretInput(
+        input.task.id,
+        gatewayRegistration.generation,
+      );
+      if (gatewaySecret === null) {
+        removeTaskGatewayTask(
+          input.task.id,
+          gatewayRegistration.generation,
+        );
+        registeredTaskGatewayGeneration = null;
+        throw new Error("could not export the task gateway generation secret");
+      }
+      // Launch screen: the first stage boundary. A machine-backed task
+      // spends the next minute launching an EC2 instance; a container
+      // task goes straight to preparing its workspace.
+      orchestrator.emitTaskStage(
+        input.task.id,
+        machineTasksEnabled() ? "machine" : "workspace",
+      );
+      try {
+        const taskGateway = {
+          generation: gatewayRegistration.generation,
+          secret: gatewaySecret,
+        };
+        const provisioned = gitCredential
+          ? await gitCredential.run(() =>
+              provisionTaskEnvironment(
+                input,
+                {
+                  githubCredentialSocket: gitCredential.socketPath,
+                  taskGateway,
+                },
+                recordPrepared,
+              ),
+            )
+          : await provisionTaskEnvironment(
+              input,
+              {
+                taskGateway,
+                ...(cloud?.start && cloud.hold
+                  ? {
+                      leased: leasedTaskUp(
+                        cloud.runtime,
+                        cloud.start,
+                        cloud.hold,
+                        sharedFilesMode ?? (() => {
+                          throw new Error("a cloud-credential start has no trusted Files mode");
+                        })(),
+                      ),
+                    }
+                  : {}),
+              },
+              recordPrepared,
+            );
+        environmentLocator = provisioned.handle.descriptor.locator;
+        // ADR-153 §4: the task's own schema observations, read from the
+        // bases task-up recorded before its container started (a machine
+        // captures its own). Stored once; a resume reuses them.
+        const envSchemas = isEnvironmentTransportProvider(getHostTask(input.task.id)?.environmentProvider)
+          ? undefined
+          : captureTaskEnvSchemas(
+              input.task.id,
+              incomingEnvSpec.projects.map((project) => project.projectId),
+            );
+        // ADR-153: before any consumer is let in, bring the task to now:
+        // a CA successor minted while it started, and the domains its
+        // policy has now rather than those task-up was handed. A failure
+        // leaves those keys withheld, and the trust watcher retries.
+        const secretsProxy = activeSecretsProxy();
+        if (secretsProxy !== null) {
+          await reconcileTaskProxyState(provisioned.handle, secretsProxy.runtime).catch((error: unknown) => {
+            console.warn(
+              `[secrets-proxy] task ${input.task.id}: could not bring the task's trust and pins up to date: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+            );
+            secretsProxy.runtime.requestTrustDelivery();
+          });
+        }
+        return envSchemas === undefined || envSchemas.length === 0
+          ? { ...provisioned.result, envMode: "loader" as const }
+          : { ...provisioned.result, envMode: "loader" as const, envSchemas };
+      } finally {
+        gatewaySecret.fill(0);
+        await gitCredential?.close().catch((error: unknown) => {
+          // Cleanup must not replace the actual task-up result/error. The
+          // credential is short-lived and close() also removes its private
+          // directory in a finally block; retain diagnostics for operators.
+          console.warn(
+            `[github] task ${input.task.id}: credential cleanup failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        });
+      }
+    });
+    // ADR-154: the last word before the start publishes its outcome. A
+    // success needs the start still the task's current one, its credentials
+    // open for its run; an interrupted start reports its interruption, never
+    // what it failed of. Nothing it made is destroyed here: a teardown would
+    // delete a resumed task's workspace, and whoever took over acts on the
+    // runtime itself.
+    const interrupted = interruptedStartResult(cloud);
+    const replaced = result.ok
+      ? cloudStartCannotPublish(cloud)
+      : interrupted
+        ? { result: interrupted, interrupted: true }
+        : null;
+    if (replaced) result = replaced.result;
+    if (!result.ok && registeredTaskGatewayGeneration !== null) {
+      forgetTaskEnvSnapshot(input.task.id);
+      try {
+        removeTaskGatewayTask(
+          input.task.id,
+          registeredTaskGatewayGeneration,
+        );
+      } catch (error) {
+        // The in-process authority is revoked before durable deletion is
+        // attempted. Preserve the task-up error while retaining a cleanup
+        // diagnostic; a leftover file loads inactive after restart.
+        console.warn(
+          `[task-gateway] task ${input.task.id}: failed to remove the rejected generation: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+    if (result.ok) {
+      orchestrator.allowChannel(input.task.id);
+      if (environmentLocator === undefined) {
+        throw new Error("task environment provision returned no locator");
+      }
+      recordTaskUpResult(
+        input.task.id,
+        result.value,
+        environmentLocator,
+        "loader",
+      );
+      if (input.task.runEpoch !== undefined) {
+        recordTaskRuntimeEstablished(
+          input.task.id,
+          input.task.runEpoch,
+        );
+      }
+      recordHostEvent(input.task.id, "task.started");
+      // ADR-153: with the proxy off, every start says so, since the task's
+      // proxied keys are withheld rather than delivered.
+      if (activeSecretsProxy() === null) {
+        orchestrator.emitSystemNote(
+          input.task.id,
+          secretsProxyEnabled()
+            ? "The secrets proxy could not start on this host, so this task's proxied env vars are withheld. See the host log."
+            : "The secrets proxy is off on this host (UAI_SECRETS_PROXY=off), so this task's proxied env vars are withheld.",
+        );
+      }
+      // ADR-153 §4: one note naming the keys this task does not get, and
+      // why, so nobody hunts for a value Uai withholds on purpose.
+      try {
+        const withheld = taskEnvWithheldNoteNow(input.task.id, incomingEnvSpec, input.task.runEpoch ?? null);
+        if (withheld !== null) orchestrator.emitSystemNote(input.task.id, withheld);
+      } catch (error) {
+        console.warn(
+          `[project-env] task ${input.task.id}: withheld-keys note failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+      // Degraded start (uai-init failed twice): the task is up, but say so
+      // in the feed — a silent half-start reads as a broken product.
+      if (result.value.initWarning) {
+        orchestrator.emitSystemNote(
+          input.task.id,
+          result.value.initWarning,
+        );
+      }
+      // ADR-122 phase 1: a project that declares @required env keys with
+      // no value on this host gets ONE visible note now — not a blank 500
+      // hours later (live 2026-08-25). Best-effort by design: a schema
+      // read hiccup must never fail a completed task-up.
+      void noteMissingRequiredEnvKeys(input).catch((err) =>
+        console.warn(
+          `[env-schema] task ${input.task.id}: validation note failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        ),
+      );
+      // GitHub auth for the container is best-effort (ADR-027) and runs in the
+      // background — it must never block or fail task-up. Awaiting it here would
+      // couple the command result to a network token-exchange: a slow/hung
+      // exchange (e.g. cloud mid-deploy) would trip the cloud's command timeout
+      // and mark a running task as errored. The reconciler injects + schedules
+      // (or emits a system note on failure) on its own; the agents come up
+      // regardless and the token lands well before the first `gh` call.
+      // ADR-121: machine-backed tasks take a direct environment injection —
+      // the compose reconciler would probe for an app container, find none,
+      // and silently skip. Reconnect re-injection for machines is a
+      // follow-up alongside the machine recovery pass.
+      if (cloud !== null) {
+        // ADR-154: the runtime-ready writes put the lease's GitHub sign-in
+        // and SSH key in; the runner's own store has nothing to add.
+      } else if (isEnvironmentTransportProvider(getHostTask(input.task.id)?.environmentProvider)) {
+        void machineTaskGithubAuth(
+          input.task.id,
+          input.task.ownerUserId,
+        ).catch((err) =>
+          console.warn(
+            `[github] machine task ${input.task.id}: auth injection failed: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          ),
+        );
+      } else {
+        void reconcileTaskGitAuth(
+          input.task.id,
+          input.task.ownerUserId,
+        ).catch((err) =>
+          console.warn(
+            `[github] task ${input.task.id}: post-start reconciliation failed: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          ),
+        );
+      }
+    } else if (replaced?.interrupted) {
+      // ADR-154: Stop, teardown, a newer run or shutdown took over, and the
+      // channel stays closed for it. A start that recorded its runtime's
+      // locator (before any of that runtime existed) keeps it exactly, so
+      // whoever took over stops, destroys or starts again that runtime and
+      // nothing that may exist is forgotten; its credentials are cleaned up
+      // while it still runs. A start that recorded none made nothing, and
+      // leaves no trace.
+      if (runtimePrepared) recordTaskError(input.task.id);
+      else if (existingTask) upsertHostTask(input.task.id, priorRuntimeState);
+      else deleteHostTask(input.task.id);
+    } else if (result.code === HostErrorCode.HostUnavailable) {
+      // A daemon outage is retryable infrastructure state, not proof that
+      // the task itself failed. Undo the optimistic local `starting` mirror
+      // and normally reopen delivery; a runtime already proven stopped for
+      // L5 recreation stays stopped/tombstoned for the cloud's retry.
+      if (existingTask) upsertHostTask(input.task.id, priorRuntimeState);
+      else deleteHostTask(input.task.id);
+      if (!runtimeQuarantinedForRecreate) {
+        orchestrator.allowChannel(input.task.id);
+      }
+    } else {
+      recordTaskError(input.task.id);
+    }
+    return result;
+  }));
+}
+
+export const hostCommands: HostCommands = {
+  // The hostId argument is cloud-side routing (host-scoped commands carry
+  // their target in args, like filesOp); this process IS the target.
+  async hostUpdate(ctx, _hostId) {
+    logCommand(ctx, "hostUpdate");
+    const pinned = sidecarRunnerIsPinned();
+    if (pinned) return pinned;
+    try {
+      const { updateManagedRuntime } = await import("../lib/managed-runtime");
+      const outcome = await updateManagedRuntime();
+      if (outcome.status === "not-managed") {
+        return {
+          ok: false,
+          code: HostErrorCode.Internal,
+          message:
+            "this host is not a managed install — update it where it runs",
+          retryable: false,
+        };
+      }
+      if (outcome.status === "deferred") {
+        // A rollback hold is an operator verdict that the newer release is
+        // unsafe on this host; a remote click must not override it.
+        return {
+          ok: true,
+          value: { version: outcome.version, staged: false, deferred: true },
+        };
+      }
+      if (outcome.status === "current") {
+        return { ok: true, value: { version: outcome.version, staged: false } };
+      }
+      managedHostRestartHook?.();
+      return { ok: true, value: { version: outcome.version, staged: true } };
+    } catch (error) {
+      return {
+        ok: false,
+        code: HostErrorCode.Internal,
+        message: `update failed: ${
+          error instanceof Error ? error.message : "unknown error"
+        }`,
+        retryable: true,
+      };
+    }
+  },
+  async hostRestart(ctx, _hostId) {
+    logCommand(ctx, "hostRestart");
+    const pinned = sidecarRunnerIsPinned();
+    if (pinned) return pinned;
+    if (!managedHostRestartHook) {
+      return {
+        ok: false,
+        code: HostErrorCode.Internal,
+        message: "restart is unavailable in this process",
+        retryable: false,
+      };
+    }
+    // The result frame flushes before exit: shutdown drains in-flight
+    // commands (this one included) before the process terminates.
+    managedHostRestartHook();
+    return { ok: true, value: undefined };
+  },
+  async taskUp(ctx, input) {
+    logCommand(ctx, "taskUp", input.task.id);
+    // ADR-154: on cloud credentials every start goes through the composer,
+    // and none starts while the runner's activation is pending.
+    const mode = credentialsMode();
+    if (mode === "pending") return switchingToCloudCredentials();
+    // On the runner's own credentials, a counted permit from here to the
+    // outcome: leaving them waits for it.
+    let legacy: LegacyStartPermit | null = null;
+    if (mode === "legacy") {
+      legacy = admitLegacyStart();
+      if (legacy === null) return switchingToCloudCredentials();
+    }
+    let cloud: CloudCredentialTaskStart | null = null;
+    if (mode === "active") {
+      const runtime = cloudCredentialRuntime();
+      if (runtime === null || input.task.runEpoch === undefined) {
+        return {
+          ok: false,
+          code: HostErrorCode.Internal,
+          message: "This host runs tasks only on cloud credentials, and could not start this one on them.",
+          retryable: false,
+        };
+      }
+      cloud = { runtime, assignment: { taskId: input.task.id, runEpoch: input.task.runEpoch }, start: null, hold: null };
+      // A newer run's start ends an older one's before it queues behind it.
+      runtime.interruptStarts(input.task.id, { below: input.task.runEpoch });
+    }
+    let outcome: TaskUpOutcome | undefined;
+    try {
+      outcome = await taskUpOn(ctx, input, cloud, legacy);
+      return outcome;
+    } finally {
+      legacy?.release();
+      // Its hold already let go with the long slot: the cleanup an abandon
+      // runs never waits on it.
+      if (cloud?.start) {
+        if (outcome?.ok === true) cloud.runtime.endStart(cloud.start);
+        else await cloud.runtime.abandonStart(cloud.start, cloud.hold);
+      }
+    }
+  },
+
+  async taskDown(ctx, input) {
+    logCommand(ctx, "taskDown", input.taskId);
+    const orphanGc = input.cleanup?.kind === "orphan-gc";
+    // ADR-154: teardown ends its run's start (orphan GC: every start of the
+    // task) before it queues behind it.
+    const interrupting = activeCloudCredentials();
+    if (interrupting) {
+      if (orphanGc) interrupting.interruptStarts(input.taskId);
+      else if (input.task.runEpoch !== undefined) interrupting.interruptStarts(input.taskId, { exact: input.task.runEpoch });
+    }
+    // A GC command is already authoritative evidence that this cloud task is
+    // gone. Enter the lifecycle slot and tombstone its channel even when the
+    // runtime is temporarily unavailable; the durable cloud intent will retry
+    // destruction later. Ordinary teardown retains its fast preflight.
+    if (!orphanGc) {
+      // Teardown-specific admission: `checking` with a pinned backend ADMITS
+      // teardown. Gating kills on `operational` created the 2026-08-16 ring —
+      // a task holding the shared volume blocked the very maintenance whose
+      // completion the kill was waiting on. Removing load is how a degraded
+      // host heals.
+      const runtimeFailure = teardownRuntimeUnavailable();
+      if (runtimeFailure) return runtimeFailure;
+    }
+    const orchestrator = getOrchestrator();
+    return orchestrator.runTaskLifecycle(input.taskId, async () => {
+      // Preserve ordinary teardown's runtime-race behavior: if the daemon was
+      // lost while waiting for the lifecycle slot, leave its channel open.
+      if (!orphanGc) {
+        const inSlotRuntimeFailure = teardownRuntimeUnavailable();
+        if (inSlotRuntimeFailure) return inSlotRuntimeFailure;
+      }
+      let environment: TaskEnvironmentHandle<TaskDownResult> | null;
+      if (!orphanGc) {
+        try {
+          environment = await reconstructHostTaskEnvironment(input.taskId);
+        } catch (error) {
+          return failFromUnknown(error);
+        }
+      } else {
+        environment = null;
+      }
+      // Close the exact v1 assignment before any terminal side effect. A
+      // delayed teardown for an older run must never tombstone or destroy the
+      // newer run. Orphan GC is authoritative for the task id and therefore
+      // closes whichever assignment still survives locally.
+      let v1AssignmentClosed = false;
+      let closedRunEpoch: number | null = null;
+      const assignmentState = readTaskRunEpochState(input.taskId);
+      if (assignmentState !== null || input.task.runEpoch !== undefined) {
+        const requestedRunEpoch = orphanGc
+          ? assignmentState?.highestRunEpoch
+          : input.task.runEpoch;
+        if (assignmentState === null || requestedRunEpoch === undefined) {
+          return {
+            ok: false,
+            code: HostErrorCode.TaskAlreadyRunning,
+            message:
+              `task ${input.taskId} teardown does not name its current run`,
+          };
+        }
+        const closed = closeTaskRunAssignment(
+          input.taskId,
+          requestedRunEpoch,
+        );
+        if (closed.kind === "missing" || closed.kind === "mismatch") {
+          return {
+            ok: false,
+            code: HostErrorCode.TaskAlreadyRunning,
+            message:
+              `task ${input.taskId} run ${String(requestedRunEpoch)} is no longer current`,
+          };
+        }
+        v1AssignmentClosed = true;
+        closedRunEpoch = requestedRunEpoch;
+      }
+      // Tombstone + close before container destruction. A concurrent cloud
+      // ensure cannot reopen the channel while teardown is awaiting Docker.
+      const suspendedTaskGateway = suspendTaskGatewayTask(input.taskId);
+      // ADR-153: the suspended generation is no longer served; end the
+      // proxy connections it already had, too.
+      activeSecretsProxy()?.runtime.stopTask(input.taskId);
+      await orchestrator.closeChannel(input.taskId);
+      if (orphanGc) {
+        const inSlotRuntimeFailure = runtimeUnavailable();
+        if (inSlotRuntimeFailure) return inSlotRuntimeFailure;
+        try {
+          environment = await reconstructHostTaskEnvironment(input.taskId);
+        } catch (error) {
+          return failFromUnknown(error);
+        }
+        // Channel startup and runtime recovery launch SSH reconciliation in
+        // the background. Fence every future launch and join the exact older
+        // ensure before container destruction; otherwise a paused health probe
+        // could materialize the private key after localStatePruned was sent.
+        await retireTaskSshIdentityEnsures(input.taskId);
+      }
+      // Ad-hoc preview proxies share this task's compose network and stable
+      // names. Remove them inside the same lifecycle slot before compose down.
+      try {
+        await stopPreviewSidecars(input.taskId);
+      } catch (err) {
+        console.warn(
+          `[host-agent] task ${input.taskId}: preview cleanup failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      }
+      // ADR-154 §6: the closed run's credentials cleaned up, every path
+      // proven gone (or the runtime destroyed), before the runtime goes; by
+      // the composer as it is now, in the slot.
+      const credentials = activeCloudCredentials();
+      if (credentials && closedRunEpoch !== null) {
+        try {
+          await credentials.closeAssignment({ taskId: input.taskId, runEpoch: closedRunEpoch }, "teardown");
+        } catch (error) {
+          return failFromUnknown(error);
+        }
+      }
+      const result = await wrapAgent(ctx, "taskDown", async () => {
+        if (environment === null) return agent.taskDown(input);
+        // taskDown is TERMINAL — its only cloud callers are task close and
+        // failed-occurrence/orphan cleanup; pause rides the separate stopTask
+        // command. Machines therefore TERMINATE here: a closed task can never
+        // be resumed, so a stopped-but-kept machine is a per-month disk leak
+        // with no consumer (owner, 2026-08-29 — 16 parked disks after one
+        // evening of testing). The task branch lives on the remote; the
+        // machine's disk is not a preservation surface once the task ends.
+        if (isEnvironmentTransportProvider(environment.descriptor.locator.provider)) {
+          stopMachineGatewayTunnel(input.taskId);
+        }
+        return taskDownResultForInput(input, await environment.teardown());
+      });
+      if (result.ok) {
+        if (orphanGc) {
+          try {
+            // task-down.sh is destructive but its exit alone is not the proof:
+            // independently re-query every exact Docker label and the one
+            // derived task directory before deleting the remaining authority.
+            await proveOrphanTaskResourcesAbsent(input.taskId);
+            clearTaskGatewayAclStrict(input.taskId);
+            removeTaskCliSecretStrict(input.taskId);
+            removeTaskIdentityStrict(input.taskId);
+            removeTaskGatewayTask(input.taskId);
+            // No longer served: the proxy forgets its placeholders, and no
+            // write still queued for the task may land or record.
+            activeSecretsProxy()?.runtime.dropTask(input.taskId);
+            invalidateTaskWrites(input.taskId);
+            forgetTaskProxyReadiness(input.taskId);
+            forgetTaskEnvSnapshot(input.taskId);
+            forgetTaskEnvSchemaObservations(input.taskId);
+            clearRefresh(input.taskId);
+            // Last, atomically. Do not record taskDown/task.ended first: both
+            // would recreate the very inventory evidence being pruned.
+            purgeHostTaskState(input.taskId);
+            return ok({ ...result.value, localStatePruned: true as const });
+          } catch (error) {
+            console.warn(
+              `[host-agent] task ${input.taskId}: orphan cleanup proof failed: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+            );
+            return failFromUnknown(error);
+          }
+        }
+        // The live generation was suspended before channel drain. Delete its
+        // durable state only after destruction succeeds; on failure the task
+        // is reopened below with the same on-disk MCP definitions.
+        try {
+          removeTaskGatewayTask(input.taskId);
+        } catch (error) {
+          // Destruction succeeded and the live authority was already revoked,
+          // but keep the lifecycle retryable until the durable identity is
+          // gone. Never reopen a channel onto the destroyed runtime.
+          recordTaskError(input.taskId);
+          return failFromUnknown(error);
+        }
+        // No longer served: the proxy forgets its placeholders, and no write
+        // still queued for the task may land or record.
+        activeSecretsProxy()?.runtime.dropTask(input.taskId);
+        invalidateTaskWrites(input.taskId);
+        forgetTaskProxyReadiness(input.taskId);
+        forgetTaskEnvSnapshot(input.taskId);
+        forgetTaskEnvSchemaObservations(input.taskId);
+        clearTaskGatewayAcl(input.taskId);
+        recordTaskDown(input.taskId, result.value.status);
+        recordHostEvent(input.taskId, "task.ended");
+        clearRefresh(input.taskId);
+      } else {
+        // Destruction failed; let a subsequent ensure restore the still-running
+        // task instead of leaving it permanently tombstoned.
+        if (!orphanGc && !v1AssignmentClosed) {
+          if (suspendedTaskGateway) {
+            reactivateTaskGatewayTask(suspendedTaskGateway);
+          }
+          orchestrator.allowChannel(input.taskId);
+        }
+      }
+      return result;
+    });
+  },
+
+  async taskStop(ctx, taskId, input) {
+    logCommand(ctx, "taskStop", taskId, input.reason);
+    const orchestrator = getOrchestrator();
+    // ADR-154: a manual Stop ends its run's start before it queues behind
+    // it; an idle Stop never does, since a start vetoes it in the slot.
+    const interrupting = activeCloudCredentials();
+    if (interrupting && input.reason !== "idle" && input.runEpoch !== undefined) {
+      interrupting.interruptStarts(taskId, { exact: input.runEpoch });
+    }
+    const result = await orchestrator.stopTask(taskId, {
+      // ADR-154: the run Stop closes, cleaned up by the composer as it is
+      // when Stop gets there, in the slot.
+      closeCredentials: (runEpoch: number) =>
+        activeCloudCredentials()?.closeAssignment({ taskId, runEpoch }, "stop") ?? Promise.resolve(),
+      // Resolve legacy versus v1 only after Stop owns the task lifecycle slot.
+      // Otherwise task-up can admit v1 between an outside read and the stop.
+      admitAssignment: () => {
+        if (input.runEpoch === undefined) {
+          return readTaskRunEpochState(taskId) === null
+            ? { kind: "legacy" }
+            : { kind: "stale" };
+        }
+        const closed = closeTaskRunAssignmentForStop(taskId, input.runEpoch);
+        return closed.kind === "closed" || closed.kind === "already_closed"
+          ? { kind: "closed", runEpoch: input.runEpoch }
+          : { kind: "stale" };
+      },
+      // ADR-125: idle stops are the cloud's judgment from what it can see;
+      // only the host can see a turn that is mid-flight RIGHT NOW. Evaluate
+      // immediately before assignment closure. Manual pause has no veto.
+      shouldVeto:
+        input.reason === "idle"
+          ? () => {
+              const activeAt = orchestrator.lastChannelActivity(taskId);
+              return (
+                activeAt !== null && Date.now() - activeAt < IDLE_STOP_VETO_MS
+              );
+            }
+          : undefined,
+    });
+    if (result.ok && result.vetoed) {
+      return { ok: true, value: { vetoed: "active" as const } };
+    }
+    if (!result.ok) {
+      return {
+        ok: false,
+        code: result.assignmentStale
+          ? HostErrorCode.TaskAlreadyRunning
+          : HostErrorCode.Internal,
+        message: result.error ?? "stop failed",
+        ...(result.assignmentStale ? {} : { retryable: true }),
+      };
+    }
+    return { ok: true, value: {} };
+  },
+  async taskStatus(ctx, taskId) {
+    logCommand(ctx, "taskStatus", taskId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    const result = await wrapAgent(ctx, "taskStatus", async () => {
+      const environment = await reconstructHostTaskEnvironment(taskId);
+      if (environment === null) {
+        return {
+          composeRunning: false,
+          containers: [],
+          worktreePresent: false,
+        };
+      }
+      return taskEnvironmentStatusResult(await environment.status());
+    });
+    // ADR-051: attach the published preview ports from the host DB so the
+    // cloud can backfill its mirror on reconcile (tasks launched before the
+    // cloud started recording them at task-up).
+    if (result.ok) {
+      const ports = parsePreviewPortRuntimes(
+        getHostTask(taskId)?.previewPorts,
+      );
+      if (ports.length > 0) {
+        return { ...result, value: { ...result.value, previewPorts: ports } };
+      }
+    }
+    return result;
+  },
+
+  async channelEnsure(ctx, input) {
+    logCommand(ctx, "channelEnsure", input.taskId);
+    if (credentialsMode() === "pending") {
+      return switchingToCloudCredentials();
+    }
+    const admissionFailure = managedMaintenanceUnavailable();
+    if (admissionFailure) return admissionFailure;
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    await agentClisReady;
+    if (credentialsMode() === "pending") {
+      return switchingToCloudCredentials();
+    }
+    const readyAdmissionFailure = managedMaintenanceUnavailable();
+    if (readyAdmissionFailure) return readyAdmissionFailure;
+    const readyRuntimeFailure = runtimeUnavailable();
+    if (readyRuntimeFailure) return readyRuntimeFailure;
+    try {
+      getOrchestrator().registerChannelSpec(normalizeChannelSpec(input));
+      const ready = await getOrchestrator().ensureStarted(input.taskId);
+      // Open mode historically treats ensure as best-effort: a stopped task or
+      // transient spawn failure still acknowledges the idempotent command.
+      // Secretary mode is different because its CLI is the only delegation
+      // path, so starting without it would create a human-facing agent that
+      // cannot hand work to the crew.
+      if (!ready && input.mode === "secretary") {
+        return {
+          ok: false,
+          code: HostErrorCode.TaskNotRunning,
+          message:
+            "Secretary channel could not start; verify the task CLI and token were materialized",
+          retryable: false,
+        };
+      }
+      return ok(undefined);
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async channelTeardown(ctx, taskId) {
+    logCommand(ctx, "channelTeardown", taskId);
+    const orchestrator = getOrchestrator();
+    return orchestrator.runTaskLifecycle(taskId, async () => {
+      try {
+        await orchestrator.closeChannel(taskId);
+        // ADR-057: the task's gateway routes die with the channel.
+        clearTaskGatewayAcl(taskId);
+        return ok(undefined);
+      } catch (err) {
+        return failFromUnknown(err);
+      }
+    });
+  },
+
+  async channelDeliver(ctx, taskId, agentId, text, origin, assignment) {
+    logCommand(ctx, "channelDeliver", taskId, agentId);
+    if (credentialsMode() === "pending") {
+      return switchingToCloudCredentials();
+    }
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      // An inbound turn is activity: the idle veto must cover the gap between
+      // this delivery landing and the agent's first output event.
+      getOrchestrator().markChannelActivity(taskId);
+      const result = await getOrchestrator().deliver(taskId, agentId, text, origin, assignment);
+      if (!result.ok) {
+        return {
+          ok: false,
+          code: mapDeliverError(result.error),
+          message: result.error,
+        };
+      }
+      return ok(undefined);
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async previewEnsure(ctx, taskId, name, containerPort) {
+    logCommand(ctx, "previewEnsure", taskId, name);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    const orchestrator = getOrchestrator();
+    return orchestrator.runTaskLifecycle(taskId, async () => {
+      try {
+        const inSlotRuntimeFailure = runtimeUnavailable();
+        if (inSlotRuntimeFailure) return inSlotRuntimeFailure;
+        const task = getHostTask(taskId);
+        if (!task) {
+          return {
+            ok: false as const,
+            code: HostErrorCode.TaskNotFound,
+            message: `no such task: ${taskId}`,
+          };
+        }
+        if (task.statusMirror !== "running") {
+          return ok({ hostPort: null });
+        }
+        if (!task.composeProject) return ok({ hostPort: null });
+        const declared = parsePreviewPortRuntimes(task.previewPorts).find(
+          (port) => port.name === name,
+        );
+        // A stored host port is never routing truth after an unnoticed daemon
+        // restart. Prove the exact app container and current mapping before
+        // either returning a declared port or creating an ad-hoc sidecar.
+        const appProof = await inspectTunnelContainer(
+          `${task.composeProject}-app-1`,
+          containerPort,
+        );
+        if (appProof.kind === "daemon-unavailable") {
+          return dockerUnavailableResult(
+            `could not verify preview runtime for task ${taskId}: ${appProof.detail}`,
+          );
+        }
+        // The proof awaited Docker. A concurrent runtime recheck can invalidate
+        // its generation before this continuation resumes, so fence the result
+        // again before returning any route to the cloud.
+        const postInspectRuntimeFailure = runtimeUnavailable();
+        if (postInspectRuntimeFailure) return postInspectRuntimeFailure;
+        if (appProof.kind !== "running") return ok({ hostPort: null });
+        // Task-up published port (preview enabled at launch) wins, but use the
+        // mapping Docker just proved rather than the persisted hostPort.
+        if (declared) {
+          return ok({ hostPort: appProof.published?.port ?? null });
+        }
+        // Else start (or find) the node-proxy sidecar NOW — the same one the
+        // tunnel lazy-starts on first access — and hand back its host port.
+        const hostPort = await ensurePreviewSidecar({
+          taskId,
+          composeProject: task.composeProject,
+          name,
+          containerPort,
+        });
+        const postSidecarRuntimeFailure = runtimeUnavailable();
+        if (postSidecarRuntimeFailure) return postSidecarRuntimeFailure;
+        if (hostPort === null) {
+          const unavailable = await runtimeFailureIfDaemonUnavailable(
+            `could not prepare preview runtime for task ${taskId}`,
+          );
+          if (unavailable) return unavailable;
+        }
+        return ok({ hostPort });
+      } catch (err) {
+        return failFromUnknown(err);
+      }
+    });
+  },
+
+  // ADR-116: remove a labeled engine account. Delegates to the same internals
+  // the local UI uses; `default:*` refusal and idempotency live there. The
+  // dispatcher re-advertises capabilities after an ok result.
+  async engineAccountRemove(ctx, input) {
+    logCommand(ctx, "engineAccountRemove", input.id);
+    try {
+      const result = removeEngineAccount(input.id, input.scope);
+      if (!result.ok) {
+        return ok({ removed: false, message: result.message });
+      }
+      return ok({ removed: true });
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async engineAccountRename(ctx, input) {
+    logCommand(ctx, "engineAccountRename", input.id);
+    try {
+      const result = renameEngineAccount(input.id, input.label, input.scope);
+      return ok(
+        result.ok
+          ? { renamed: true }
+          : { renamed: false, message: result.message },
+      );
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async engineAccountReorder(ctx, input) {
+    logCommand(ctx, "engineAccountReorder", input.kind);
+    try {
+      const result = reorderEngineAccounts(input.kind, input.ids, input.scope);
+      return ok(
+        result.ok
+          ? { reordered: true }
+          : { reordered: false, message: result.message },
+      );
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async engineDisconnect(ctx, input) {
+    logCommand(ctx, "engineDisconnect", input.engine);
+    try {
+      disconnectEngine(input.engine);
+      return ok({ disconnected: true });
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async channelResolvePermission(ctx, taskId, agentId, requestId, decision) {
+    logCommand(ctx, "channelResolvePermission", taskId, agentId, requestId);
+    try {
+      const okResolved = await getOrchestrator().resolvePermission(
+        taskId,
+        agentId,
+        requestId,
+        toLegacyDecision(decision),
+      );
+      if (!okResolved) {
+        return {
+          ok: false,
+          code: HostErrorCode.NoSuchPermission,
+          message: "no live session for that permission request",
+        };
+      }
+      return ok(undefined);
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async cloneRepo(ctx, input) {
+    logCommand(ctx, "cloneRepo", input.projectId);
+    try {
+      return ok(cloneRepo(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async taskDiff(ctx, input) {
+    logCommand(ctx, "taskDiff", input.taskId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      const task = getHostTask(input.taskId);
+      // #cb3j0z: Git never runs on the host against a task's repositories;
+      // what a task configured there would run as the runner's user. A
+      // running task must reconstruct its exact persisted provider identity
+      // (malformed/foreign metadata is not permission to run Git against a
+      // different filesystem view) and diffs there; a stopped one diffs in
+      // a throwaway sandbox of its retained worktree.
+      if (task?.statusMirror !== "running") {
+        return ok(
+          await stoppedTaskDiff(input, task ? { environmentProvider: task.environmentProvider ?? null } : null),
+        );
+      }
+      const environment = await reconstructPersistedTaskEnvironment(task);
+      if (environment === null) {
+        throw new Error(
+          `running task ${input.taskId} has no persisted task environment`,
+        );
+      }
+      return ok(await buildTaskDiff(input, environment));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  // ADR-161 §2.3: add a repository to a running task. Each command runs in
+  // the task's live-project queue; the publication steps take its lifecycle
+  // slot (lib/task-project-ops.ts).
+  async taskProjectPrepare(ctx, input) {
+    logCommand(ctx, "taskProjectPrepare", input.taskId, input.operationId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      return ok(await taskProjectOps().prepare(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async taskProjectActivate(ctx, input) {
+    logCommand(ctx, "taskProjectActivate", input.taskId, input.operationId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      return ok(await taskProjectOps().activate(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async taskProjectCompensate(ctx, input) {
+    logCommand(ctx, "taskProjectCompensate", input.taskId, input.operationId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      return ok(await taskProjectOps().compensate(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async taskProjectStatus(ctx, input) {
+    logCommand(ctx, "taskProjectStatus", input.taskId, input.operationId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      return ok(await taskProjectOps().status(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async attachmentWrite(ctx, input) {
+    logCommand(ctx, "attachmentWrite", input.taskId, input.filename);
+    try {
+      // ADR-121 strangler: attachments go through the environment's file
+      // ops, so this call site no longer knows where the workspace lives —
+      // host-side providers implement them as the exact direct fs access
+      // this used to be; machine providers reach over their transport. A
+      // row without a reconstructible environment (legacy) keeps the
+      // host-FS path unchanged.
+      const environment = await reconstructHostTaskEnvironment(input.taskId);
+      if (environment) {
+        await environment.writeWorkspaceFile(
+          attachmentEnvironmentPath(environment, input.filename),
+          Buffer.from(input.dataBase64, "base64"),
+        );
+        return ok(undefined);
+      }
+      await writeAttachment(
+        input.taskId,
+        input.filename,
+        Buffer.from(input.dataBase64, "base64"),
+      );
+      return ok(undefined);
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async workspaceFileRead(ctx, input) {
+    try {
+      const path = normalizedWorkspacePath(assertShareablePath(input.path));
+      const maxBytes = Math.min(8 * 1024 * 1024, Math.max(0, input.maxBytes));
+      const environment = await reconstructHostTaskEnvironment(input.taskId);
+      const bytes = environment ? await environment.readWorkspaceFile(`${environment.descriptor.workspacePath}/${path.slice("/workspace/".length)}`, { maxBytes: maxBytes + 1 }) :
+        await readBoundedFile(taskWorkspaceDir(input.taskId), path.slice("/workspace/".length).split("/"), { maxBytes: maxBytes + 1 });
+      if (!bytes) return { ok: false, code: HostErrorCode.TaskNotFound, message: "no such workspace file" };
+      if (bytes.byteLength > maxBytes) return { ok: false, code: HostErrorCode.PayloadTooLarge, message: "Ask the agent to uai share this file (live preview is limited to 8 MiB)." };
+      return ok({ dataBase64: Buffer.from(bytes).toString("base64"), size: bytes.byteLength });
+    } catch { return { ok: false, code: HostErrorCode.TaskNotFound, message: "no such workspace file" }; }
+  },
+
+  async attachmentRead(ctx, input) {
+    logCommand(ctx, "attachmentRead", input.taskId, input.filename);
+    try {
+      const environment = await reconstructHostTaskEnvironment(input.taskId);
+      const bytes = environment
+        ? await environment.readWorkspaceFile(
+            attachmentEnvironmentPath(environment, input.filename),
+          )
+        : await readAttachment(input.taskId, input.filename);
+      if (!bytes) {
+        return {
+          ok: false,
+          code: HostErrorCode.TaskNotFound,
+          message: `no such attachment: ${input.filename}`,
+        };
+      }
+      return ok({ dataBase64: Buffer.from(bytes).toString("base64") });
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async filesOp(ctx, input) {
+    logCommand(ctx, "filesOp", input.op, `${input.scope}:${input.path}`);
+    try {
+      return ok(await handleFilesOp(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async sidecarAssign(ctx, input) {
+    logCommand(ctx, "sidecarAssign", input.taskId);
+    try {
+      const { applySidecarAssign } = await import("../lib/sidecar-assign");
+      applySidecarAssign(input.taskId);
+      return ok(undefined);
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async channelInterrupt(ctx, taskId, agentId) {
+    logCommand(ctx, "channelInterrupt", taskId, agentId);
+    try {
+      const result = await getOrchestrator().interrupt(taskId, agentId);
+      if (!result.ok) {
+        return {
+          ok: false,
+          code: HostErrorCode.TaskNotRunning,
+          message: result.error,
+        };
+      }
+      return ok(undefined);
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async appendTranscript(_ctx, taskId, author, text, targets) {
+    // Per-message + high-frequency, so no logCommand (avoid log spam).
+    try {
+      // ADR-121: a machine-backed workspace lives in the machine's world —
+      // the append must travel over the environment transport. Container
+      // tasks keep the direct host-FS write (their workspace is a bind
+      // mount and the sync path is cheaper than a docker exec per message).
+      const task = getHostTask(taskId);
+      if (isEnvironmentTransportProvider(task?.environmentProvider)) {
+        const environment = await reconstructHostTaskEnvironment(taskId);
+        if (environment) {
+          await appendTranscriptViaEnvironment(
+            taskId,
+            environment,
+            author,
+            text,
+            targets,
+          );
+          return ok(undefined);
+        }
+      }
+      writeTranscript(taskId, author, text, targets);
+      return ok(undefined);
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+};
+
+function normalizeChannelSpec(input: ChannelEnsureInput): ChannelEnsureInput {
+  return { ...input, workspacePath: "/workspace" };
+}
+
+/**
+ * ADR-121: gh auth for a machine-backed task, injected over the environment
+ * transport (token via exec stdin — same `gh auth login --with-token` +
+ * `setup-git` gesture as containers, no compose probing). Best-effort like
+ * the compose reconciler: absence of a GitHub connection is a quiet no-op.
+ */
+/** ADR-154: only while the runner is on its own credentials. Leaving them
+ *  waits for one under way, and the write is fenced on them: none starts
+ *  once leaving has begun. */
+async function machineTaskGithubAuth(
+  taskId: string,
+  userId: string,
+): Promise<void> {
+  await whileOnOwnCredentials(async () => {
+    const environment = await reconstructHostTaskEnvironment(taskId);
+    if (!environment) return;
+    const token = await requestAccessToken(userId);
+    if (!token || !onOwnCredentials()) return;
+    // Machine work is not container work: no docker/apple runtime admission.
+    await injectIntoContainer(
+      taskId,
+      token.accessToken,
+      undefined,
+      () => {},
+      environment,
+    );
+  });
+}
+
+async function reconstructHostTaskEnvironment(
+  taskId: string,
+): Promise<TaskEnvironmentHandle<TaskDownResult> | null> {
+  const task = getHostTask(taskId);
+  return task === null ? null : reconstructPersistedTaskEnvironment(task);
+}
+
+function taskEnvironmentStatusResult(status: TaskEnvironmentStatus) {
+  if (status.state === "unknown") {
+    throw new Error(`task environment status is unknown: ${status.detail}`);
+  }
+  return {
+    composeRunning: status.state === "running",
+    containers: [...status.instances],
+    worktreePresent: status.workspacePresent,
+  };
+}
+
+function taskDownResultForInput(
+  input: TaskDownInput,
+  providerResult: TaskDownResult,
+): TaskDownResult {
+  const status = input.task.status;
+  return {
+    ...providerResult,
+    status: status === "shipped" || status === "error" ? status : "killed",
+  };
+}
+
+/** Attachment location inside the environment — same shape every provider
+ * serves (`<workspace>/.moondeck/attachments/<name>`), basename-hardened exactly
+ * like the legacy host-side safePath. */
+function attachmentEnvironmentPath(
+  environment: { descriptor: { workspacePath: string } },
+  filename: string,
+): string {
+  const name = filename.split("/").pop() ?? "";
+  if (name === "" || name === "." || name === ".." || name.includes("\0")) {
+    throw new Error("invalid attachment filename");
+  }
+  return `${environment.descriptor.workspacePath}/.moondeck/attachments/${name}`;
+}
+
+/** ADR-122 phase 1: read each project's committed .env.schema from the
+ * fresh workspace, compare @required keys against the union of values this
+ * host actually injected (env is merged across projects, so any project's
+ * value covers the key), and post one note naming what's missing. */
+async function noteMissingRequiredEnvKeys(
+  input: TaskLaunchInput,
+): Promise<void> {
+  const provided = new Set<string>();
+  for (const project of input.projects) {
+    for (const key of Object.keys(getDecryptedForProject(project.id))) {
+      provided.add(key);
+    }
+  }
+  const perProject: Array<{ slug: string; missing: string[] }> = [];
+  for (const project of input.projects) {
+    let content: string;
+    try {
+      content = readFileSync(
+        resolve(taskProjectWorktree(input.task.id, project.slug), ".env.schema"),
+        "utf8",
+      );
+    } catch {
+      continue; // No schema, no opinion — today's behavior, unchanged.
+    }
+    perProject.push({
+      slug: project.slug,
+      missing: missingRequiredKeys(parseEnvSchema(content), provided),
+    });
+  }
+  const note = envSchemaNote(perProject);
+  if (note) getOrchestrator().emitSystemNote(input.task.id, note);
+}
+
+function logCommand(
+  ctx: CommandContext,
+  command: keyof HostCommands,
+  ...parts: string[]
+): void {
+  console.log(`[host-agent] ${ctx.commandId} ${command} ${parts.join(" ")}`);
+}
+
+async function wrapAgent<T>(
+  _ctx: CommandContext,
+  _command: keyof HostCommands,
+  fn: () => Promise<T>,
+): Promise<HostCommandResult<T>> {
+  try {
+    return ok(await fn());
+  } catch (err) {
+    if (AgentError.is(err) && isRuntimeSensitiveAgentError(err.code)) {
+      if (err.code === "DOCKER_PS_FAILED") {
+        return dockerUnavailableResult(err.message);
+      }
+      const unavailable = await runtimeFailureIfDaemonUnavailable(err.message);
+      if (unavailable) return unavailable;
+    }
+    return failFromUnknown(err);
+  }
+}
+
+function ok<T>(value: T): HostCommandResult<T> {
+  return { ok: true, value };
+}
+
+/** Docker-dependent commands must not reinterpret an unavailable or
+ * half-recovered backend as an absent task/container. */
+function runtimeUnavailable(): HostCommandResult<never> | null {
+  const message = containerRuntimeProblem();
+  if (!message) return null;
+  return {
+    ok: false,
+    code: HostErrorCode.HostUnavailable,
+    message,
+    retryable: true,
+  };
+}
+
+function teardownRuntimeUnavailable(): HostCommandResult<never> | null {
+  const message = containerRuntimeTeardownProblem();
+  if (!message) return null;
+  return {
+    ok: false,
+    code: HostErrorCode.HostUnavailable,
+    message,
+    retryable: true,
+  };
+}
+
+/** ADR-125: an idle stop is vetoed when the channel showed any activity
+ * this recently — a delivery landing or any session event. */
+const IDLE_STOP_VETO_MS = 120_000;
+
+const RUNTIME_TASK_ADMISSION_WAIT_MS = 3_000;
+
+/**
+ * Runtime activation is intentionally detached from one cloud command's
+ * 15-minute deadline. A first attempt joins for a few seconds, then returns a
+ * narrowly-tagged retry while the single detection/activation promise keeps
+ * running. Every retry rechecks the exact generation and durable provider
+ * claim before task-owned side effects begin.
+ */
+async function prepareContainerRuntimeForTask(): Promise<
+  HostCommandResult<never> | null
+> {
+  // ADR-133 sidecar mode: the task runs on this machine; there is no
+  // container runtime to prepare (live 2026-09-10, hostless smoke 3: this
+  // step answered with the no-runtime message before the gated check ran).
+  if (sidecarMode()) return null;
+  let prepared:
+    | Awaited<ReturnType<typeof ensureContainerRuntimeForTask>>
+    | null;
+  try {
+    prepared = await settleWithin(
+      ensureContainerRuntimeForTask(),
+      RUNTIME_TASK_ADMISSION_WAIT_MS,
+    );
+  } catch (error) {
+    return runtimeSetupRetry(
+      `container runtime setup failed: ${boundedFailureMessage(error)}`,
+    );
+  }
+  if (prepared === null) {
+    return runtimeSetupRetry(
+      "The bundled container runtime is still being provisioned on this host.",
+    );
+  }
+  if (prepared.status !== "ready") {
+    return {
+      ok: false,
+      code: HostErrorCode.HostUnavailable,
+      message:
+        prepared.status === "no-runtime"
+          ? prepared.message
+          : "The container runtime is still being detected on this host.",
+      retryable: true,
+    };
+  }
+  const epoch = containerRuntimeReadinessEpoch();
+  const operational = await waitForContainerRuntimeOperational(
+    epoch,
+    RUNTIME_TASK_ADMISSION_WAIT_MS,
+  );
+  if (!operational) {
+    const failure = runtimeUnavailable();
+    if (failure && !failure.ok && !failure.message.includes("still preparing")) {
+      return failure;
+    }
+    return runtimeSetupRetry(
+      "The container runtime is completing image maintenance and task recovery.",
+    );
+  }
+  try {
+    if (await claimContainerRuntimeForTask(epoch)) return null;
+  } catch (error) {
+    return runtimeSetupRetry(
+      `The container runtime could not persist its task-state claim: ${boundedFailureMessage(error)}`,
+    );
+  }
+  return runtimeSetupRetry(
+    "The container runtime changed while task admission was being prepared.",
+  );
+}
+
+function runtimeSetupRetry(message: string): HostCommandResult<never> {
+  return {
+    ok: false,
+    code: HostErrorCode.HostUnavailable,
+    message,
+    retryable: true,
+    retryReason: "runtime_setup",
+  };
+}
+
+function settleWithin<T>(promise: Promise<T>, timeoutMs: number): Promise<T | null> {
+  return new Promise<T | null>((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve(null);
+    }, timeoutMs);
+    timer.unref?.();
+    void promise.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+function boundedFailureMessage(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 512);
+}
+
+/** Managed installation, activation, and uninstall drain instead of admitting work. */
+let lastAdmissionRefusalLogAt = 0;
+let lastAdmissionReclaimAt = 0;
+let admissionReclaimInFlight: Promise<"cleared" | "kept" | "none"> | null =
+  null;
+function managedMaintenanceUnavailable(): HostCommandResult<never> | null {
+  const blocker = managedRuntimeAdmissionBlocker();
+  if (blocker === null) return null;
+  const now = Date.now();
+  // Mid-run self-heal (the abandoned-uninstall marker recurred WHILE the
+  // service was up, 2026-08-19 — boot-time reclaim alone cannot cover a
+  // writer on a schedule). Reclaim only ever touches a provably-untorn
+  // "checking" marker, under the operation lock; rate-limited so the
+  // cloud's retry hammer cannot churn the lock. The command that observed
+  // the marker still refuses — the NEXT retry finds admission open.
+  if (now - lastAdmissionReclaimAt > 30_000 && !admissionReclaimInFlight) {
+    lastAdmissionReclaimAt = now;
+    admissionReclaimInFlight = reclaimAbandonedMaintenanceCheck();
+    void admissionReclaimInFlight
+      .then((verdict) => {
+        if (verdict === "cleared") {
+          console.warn(
+            "[host-agent] cleared an abandoned maintenance marker mid-run (a managed uninstall/update died before any teardown); task admission reopened",
+          );
+        }
+      })
+      .catch((error) => {
+        console.warn(
+          `[host-agent] mid-run maintenance-marker reclaim failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      })
+      .finally(() => {
+        admissionReclaimInFlight = null;
+      });
+  }
+  // A refusal must NAME its gate somewhere an operator can find it. Three
+  // stacked silent refusals cost hours live (2026-08-18); rate-limited so a
+  // retrying cloud cannot flood the log.
+  if (now - lastAdmissionRefusalLogAt > 60_000) {
+    lastAdmissionRefusalLogAt = now;
+    console.warn(
+      `[host-agent] refusing task admission: managed-maintenance marker present at ${blocker}`,
+    );
+  }
+  return {
+    ok: false,
+    code: HostErrorCode.HostUnavailable,
+    message: "managed host maintenance is waiting for this runtime to restart",
+    retryable: true,
+    retryReason: "managed_restart",
+  };
+}
+
+function dockerUnavailableResult<T = never>(
+  message: string,
+): HostCommandResult<T> {
+  // Invalidate synchronously so a second command in this event-loop turn
+  // cannot touch the daemon under a stale ready verdict. Detection/recovery is
+  // asynchronous and deliberately does not delay the retryable response.
+  suspendContainerRuntime(true);
+  void initializeContainerRuntime();
+  return {
+    ok: false,
+    code: HostErrorCode.HostUnavailable,
+    message,
+    retryable: true,
+  };
+}
+
+async function runtimeFailureIfDaemonUnavailable<T = never>(
+  message: string,
+): Promise<HostCommandResult<T> | null> {
+  return (await reprobeContainerRuntimeMachineIdentity()) !== null
+    ? null
+    : dockerUnavailableResult(message);
+}
+
+function isRuntimeSensitiveAgentError(code: string): boolean {
+  return (
+    code === "STANDARD_IMAGE_UNAVAILABLE" ||
+    code === "STANDARD_IMAGE_MISSING" ||
+    code === "COMPOSE_UP_FAILED" ||
+    code === "COMPOSE_DOWN_FAILED" ||
+    code === "CONTAINER_INIT_FAILED" ||
+    code === "DOCKER_PS_FAILED"
+  );
+}
+
+function failFromUnknown<T = never>(err: unknown): HostCommandResult<T> {
+  if (err instanceof ContainerRuntimeUnavailableError) {
+    return {
+      ok: false,
+      code: HostErrorCode.HostUnavailable,
+      message: err.message,
+      retryable: true,
+    };
+  }
+  if (AgentError.is(err)) {
+    return {
+      ok: false,
+      code: mapAgentError(err.code),
+      message: err.message,
+      retryable: isRetryableAgentError(err.code),
+    };
+  }
+  return {
+    ok: false,
+    code: HostErrorCode.Internal,
+    message: err instanceof Error ? err.message : String(err),
+  };
+}
+
+function mapAgentError(code: string): HostErrorCode {
+  switch (code) {
+    case "TASK_NOT_FOUND":
+      return HostErrorCode.TaskNotFound;
+    case "PROJECT_NOT_FOUND":
+      return HostErrorCode.ProjectNotFound;
+    case "TEMPLATE_NOT_FOUND":
+      return HostErrorCode.TemplateNotFound;
+    case "COMPOSE_UP_FAILED":
+      return HostErrorCode.ComposeUpFailed;
+    case "COMPOSE_DOWN_FAILED":
+      return HostErrorCode.ComposeDownFailed;
+    case "WORKTREE_FAILED":
+      return HostErrorCode.WorktreeFailed;
+    case "CLONE_FAILED":
+      return HostErrorCode.CloneFailed;
+    case "GITHUB_SSH_ACCESS_DENIED":
+      return HostErrorCode.GitHubSshAccessDenied;
+    case "GITHUB_TOKEN_ACCESS_DENIED":
+      return HostErrorCode.GitHubTokenAccessDenied;
+    case "GITHUB_AUTH_UNAVAILABLE":
+      return HostErrorCode.GitHubAuthUnavailable;
+    case "GITHUB_CONNECTION_REQUIRED":
+      return HostErrorCode.GitHubConnectionRequired;
+    case "FETCH_FAILED":
+      return HostErrorCode.FetchFailed;
+    case "RENDER_FAILED":
+      return HostErrorCode.RenderFailed;
+    case "CONTAINER_INIT_FAILED":
+      return HostErrorCode.ContainerInitFailed;
+    case "DB_FAILED":
+      return HostErrorCode.DbFailed;
+    case "DOCKER_PS_FAILED":
+      return HostErrorCode.HostUnavailable;
+    default:
+      return HostErrorCode.Internal;
+  }
+}
+
+/** Host-side predicate only; API-boundary normalization already canonicalizes
+ * normal GitHub projects. Keep scratchpads/GitLab/local remotes independent of
+ * an unrelated broken GitHub connection on the same host. */
+function isGithubRepo(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;
+  }
+}
+
+function mapDeliverError(message: string): HostErrorCode {
+  if (message.includes("not found")) return HostErrorCode.TaskNotFound;
+  if (message.includes("not running")) return HostErrorCode.TaskNotRunning;
+  if (message.includes("no such agent")) return HostErrorCode.NoSuchAgent;
+  return HostErrorCode.Internal;
+}
+
+function isRetryableAgentError(code: string): boolean {
+  return (
+    code === "FETCH_FAILED" ||
+    code === "CONTAINER_INIT_FAILED" ||
+    code === "GITHUB_AUTH_UNAVAILABLE" ||
+    code === "DOCKER_PS_FAILED"
+  );
+}
+
+function toLegacyDecision(decision: PermissionDecision): "accept" | "decline" {
+  return decision.kind;
+}
+
+export type {
+  ChannelEnsureInput,
+  TaskDiffInput,
+  TaskDownInput,
+  TaskLaunchInput,
+};