@runuai/host 0.9.14 → 0.9.42

package/src/index.ts

@@ -1,9 +1,22 @@
-import { agent, AgentError, toolStderrDetail } from "../lib/agent";
-import { ensureStandardImage } from "../lib/standard-image";
+import {
+  agent,
+  AgentError,
+  toolStderrDetail,
+  type TaskDownResult,
+} from "../lib/agent";
+import { agentClisReady, ensureStandardImage } from "../lib/standard-image";
 import { cloneRepo } from "../lib/repo-clone";
 import { handleFilesOp } from "../lib/shared-files";
-import { getOrchestrator } from "../lib/orchestrator";
-import { storeTaskCliSecret } from "../lib/agent-cli";
+import {
+  getOrchestrator,
+  inspectTaskRuntimeContainer,
+  proveAppleTaskRuntimeContract,
+  quarantineTaskRuntimeContainer,
+} from "../lib/orchestrator";
+import {
+  removeTaskCliSecretStrict,
+  storeTaskCliSecret,
+} from "../lib/agent-cli";
 import {
   clearRefresh,
   reconcileTaskGitAuth,
@@ -16,21 +29,56 @@ import { readAttachment, writeAttachment } from "../lib/attachments";
 import { appendTranscript as writeTranscript } from "../lib/transcript";
 import { buildTaskDiff } from "../lib/task-diff";
 import {
+  deleteHostTask,
   getHostTask,
   recordHostEvent,
   recordTaskDown,
+  recordTaskEnvironmentPrepared,
   recordTaskError,
   recordTaskOwner,
   recordTaskStarting,
   recordTaskUpResult,
+  purgeHostTaskState,
+  upsertHostTask,
 } from "../lib/runtime-state";
-import { clearTaskGatewayAcl } from "../lib/mcp-gateway";
+import {
+  clearTaskGatewayAcl,
+  clearTaskGatewayAclStrict,
+} from "../lib/mcp-gateway";
 import { parsePreviewPortRuntimes } from "../lib/preview-ports";
 import { dockerCli } from "../lib/docker-exec";
+import {
+  claimContainerRuntimeForTask,
+  containerRuntimeGenerationOperational,
+  containerRuntimeProblem,
+  containerRuntimeReadinessEpoch,
+  containerRuntimeTeardownProblem,
+  ensureContainerRuntimeForTask,
+  initializeContainerRuntime,
+  reprobeContainerRuntimeMachineIdentity,
+  suspendContainerRuntime,
+  waitForContainerRuntimeOperational,
+} from "../lib/container-runtime";
+import {
+  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 { managedRuntimeAdmissionPending } 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,
@@ -118,18 +166,212 @@ export const hostEvents: HostEventStream = {
 export const hostCommands: HostCommands = {
   async taskUp(ctx, input) {
     logCommand(ctx, "taskUp", input.task.id);
+    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;
     const orchestrator = getOrchestrator();
     return orchestrator.runTaskLifecycle(input.task.id, 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);
+      const inSlotAdmissionFailure = managedMaintenanceUnavailable();
+      if (inSlotAdmissionFailure) return inSlotAdmissionFailure;
+      const inSlotRuntimeFailure = runtimeUnavailable();
+      if (inSlotRuntimeFailure) return inSlotRuntimeFailure;
       // 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);
-      if (existingTask?.statusMirror === "running") {
+      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.
+          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({
+                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) {
+              if (fastStale()) return staleRetry;
+              orchestrator.allowChannel(input.task.id);
+              return {
+                ok: true,
+                value: {
+                  composeProject: existingTask.composeProject,
+                  worktreePath: existingTask.worktreePath,
+                  codeServerPort: existingTask.codeServerPort ?? undefined,
+                  previewPorts: parsePreviewPortRuntimes(
+                    existingTask.previewPorts,
+                  ),
+                },
+              };
+            }
+            // Violated contract or broken project repo: drain, stop, and
+            // prove before task-up recreates the same stable name.
+            if (fastStale()) return staleRetry;
+            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;
+            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") {
         if (!existingTask.composeProject || !existingTask.worktreePath) {
           return {
             ok: false,
@@ -156,21 +398,72 @@ export const hostCommands: HostCommands = {
           { timeoutMs: 10_000 },
         );
         if (appRuntime.status !== 0) {
-          return {
-            ok: false,
-            code: HostErrorCode.HostUnavailable,
-            message:
-              `could not verify runtime state for task ${input.task.id}: ` +
+          return dockerUnavailableResult(
+            `could not verify runtime state for task ${input.task.id}: ` +
               (appRuntime.stderr.trim().slice(0, 200) ||
                 "docker did not answer"),
-            retryable: true,
-          };
+          );
         }
         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";
+          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.
+            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
@@ -178,9 +471,8 @@ export const hostCommands: HostCommands = {
           // 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.
-          const appContainer = `${existingTask.composeProject}-app-1`;
           let projectsHealthy = true;
-          for (const project of input.projects) {
+          for (const project of reusable ? input.projects : []) {
             const gitHealth = await dockerCli(
               [
                 "exec",
@@ -243,21 +535,26 @@ export const hostCommands: HostCommands = {
             // 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 {
-                ok: false,
-                code: HostErrorCode.HostUnavailable,
-                message:
-                  `could not verify Git state for task ${input.task.id} ` +
+              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"),
-                retryable: true,
-              };
+              );
             }
             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)}`})`,
@@ -265,7 +562,7 @@ export const hostCommands: HostCommands = {
               break;
             }
           }
-          if (projectsHealthy) {
+          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
@@ -288,9 +585,51 @@ export const hostCommands: HostCommands = {
         // 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.
-        await orchestrator.closeChannel(input.task.id);
+        if (!channelClosedForRecreate) {
+          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,
+            }
+          : {
+              statusMirror: existingTask.statusMirror,
+              lockedAt: existingTask.lockedAt,
+              startedAt: existingTask.startedAt,
+              endedAt: existingTask.endedAt,
+              environmentProvider: existingTask.environmentProvider,
+              environmentLocator: existingTask.environmentLocator,
+            }
+        : {
+            statusMirror: input.task.status,
+            lockedAt: null,
+            startedAt: null,
+            endedAt: null,
+          };
       recordTaskStarting(input.task.id);
+      // 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,
@@ -304,6 +643,7 @@ export const hostCommands: HostCommands = {
         storeTaskCliSecret(input.task.id, input.task.cliSecret);
       }
       recordHostEvent(input.task.id, "task.created");
+      let environmentLocator: TaskEnvironmentLocator | undefined;
       const result = 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
@@ -337,13 +677,21 @@ export const hostCommands: HostCommands = {
           );
         }
         try {
-          return gitCredential
+          const provisioned = gitCredential
             ? await gitCredential.run(() =>
-                agent.taskUp(input, {
-                  githubCredentialSocket: gitCredential.socketPath,
-                }),
+                provisionTaskEnvironment(
+                  input,
+                  { githubCredentialSocket: gitCredential.socketPath },
+                  async (locator) => {
+                    recordTaskEnvironmentPrepared(input.task.id, locator);
+                  },
+                ),
               )
-            : await agent.taskUp(input);
+            : await provisionTaskEnvironment(input, {}, async (locator) => {
+                recordTaskEnvironmentPrepared(input.task.id, locator);
+              });
+          environmentLocator = provisioned.handle.descriptor.locator;
+          return provisioned.result;
         } finally {
           await gitCredential?.close().catch((error: unknown) => {
             // Cleanup must not replace the actual task-up result/error. The
@@ -357,7 +705,10 @@ export const hostCommands: HostCommands = {
       });
       if (result.ok) {
         orchestrator.allowChannel(input.task.id);
-        recordTaskUpResult(input.task.id, result.value);
+        if (environmentLocator === undefined) {
+          throw new Error("task environment provision returned no locator");
+        }
+        recordTaskUpResult(input.task.id, result.value, environmentLocator);
         recordHostEvent(input.task.id, "task.started");
         // 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.
@@ -384,6 +735,16 @@ export const hostCommands: HostCommands = {
             }`,
           ),
         );
+      } 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);
       }
@@ -393,11 +754,55 @@ export const hostCommands: HostCommands = {
 
   async taskDown(ctx, input) {
     logCommand(ctx, "taskDown", input.taskId);
+    const orphanGc = input.cleanup?.kind === "orphan-gc";
+    // 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;
+      }
       // Tombstone + close before container destruction. A concurrent cloud
       // ensure cannot reopen the channel while teardown is awaiting Docker.
       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 {
@@ -409,10 +814,34 @@ export const hostCommands: HostCommands = {
           }`,
         );
       }
-      const result = await wrapAgent(ctx, "taskDown", () =>
-        agent.taskDown(input),
-      );
+      const result = await wrapAgent(ctx, "taskDown", async () => {
+        if (environment === null) return agent.taskDown(input);
+        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);
+            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);
+          }
+        }
         // Revoke only after destruction succeeds. On failure the task is
         // reopened below and its on-disk MCP definitions must retain the same
         // gateway token; deleting it early would make those exact definitions
@@ -424,7 +853,7 @@ export const hostCommands: HostCommands = {
       } else {
         // Destruction failed; let a subsequent ensure restore the still-running
         // task instead of leaving it permanently tombstoned.
-        orchestrator.allowChannel(input.taskId);
+        if (!orphanGc) orchestrator.allowChannel(input.taskId);
       }
       return result;
     });
@@ -432,9 +861,19 @@ export const hostCommands: HostCommands = {
 
   async taskStatus(ctx, taskId) {
     logCommand(ctx, "taskStatus", taskId);
-    const result = await wrapAgent(ctx, "taskStatus", () =>
-      agent.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).
@@ -451,6 +890,15 @@ export const hostCommands: HostCommands = {
 
   async channelEnsure(ctx, input) {
     logCommand(ctx, "channelEnsure", input.taskId);
+    const admissionFailure = managedMaintenanceUnavailable();
+    if (admissionFailure) return admissionFailure;
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    await agentClisReady;
+    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);
@@ -491,6 +939,8 @@ export const hostCommands: HostCommands = {
 
   async channelDeliver(ctx, taskId, agentId, text) {
     logCommand(ctx, "channelDeliver", taskId, agentId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
     try {
       const result = await getOrchestrator().deliver(taskId, agentId, text);
       if (!result.ok) {
@@ -508,9 +958,13 @@ export const hostCommands: HostCommands = {
 
   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 {
@@ -522,20 +976,49 @@ export const hostCommands: HostCommands = {
         if (task.statusMirror !== "running") {
           return ok({ hostPort: null });
         }
-        // Task-up published port (preview enabled at launch) wins.
+        if (!task.composeProject) return ok({ hostPort: null });
         const declared = parsePreviewPortRuntimes(task.previewPorts).find(
           (port) => port.name === name,
         );
-        if (declared) return ok({ hostPort: declared.hostPort });
+        // 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.
-        if (!task.composeProject) return ok({ hostPort: null });
         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);
@@ -576,8 +1059,24 @@ export const hostCommands: HostCommands = {
 
   async taskDiff(ctx, input) {
     logCommand(ctx, "taskDiff", input.taskId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
     try {
-      return ok(await buildTaskDiff(input));
+      const task = getHostTask(input.taskId);
+      // A stopped/terminal task retains its host worktree, so preserve the
+      // historical host-side fallback there. A running task must reconstruct
+      // its exact persisted provider identity: malformed/foreign metadata is
+      // not permission to run Git against a different filesystem view.
+      const environment =
+        task?.statusMirror === "running"
+          ? await reconstructPersistedTaskEnvironment(task)
+          : null;
+      if (task?.statusMirror === "running" && 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);
     }
@@ -655,6 +1154,35 @@ function normalizeChannelSpec(input: ChannelEnsureInput): ChannelEnsureInput {
   return { ...input, workspacePath: "/workspace" };
 }
 
+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",
+  };
+}
+
 function logCommand(
   ctx: CommandContext,
   command: keyof HostCommands,
@@ -671,6 +1199,13 @@ async function wrapAgent<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);
   }
 }
@@ -679,7 +1214,193 @@ 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,
+  };
+}
+
+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
+> {
+  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. */
+function managedMaintenanceUnavailable(): HostCommandResult<never> | null {
+  if (!managedRuntimeAdmissionPending()) return null;
+  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,
@@ -727,6 +1448,8 @@ function mapAgentError(code: string): HostErrorCode {
       return HostErrorCode.ContainerInitFailed;
     case "DB_FAILED":
       return HostErrorCode.DbFailed;
+    case "DOCKER_PS_FAILED":
+      return HostErrorCode.HostUnavailable;
     default:
       return HostErrorCode.Internal;
   }
@@ -758,7 +1481,8 @@ function isRetryableAgentError(code: string): boolean {
   return (
     code === "FETCH_FAILED" ||
     code === "CONTAINER_INIT_FAILED" ||
-    code === "GITHUB_AUTH_UNAVAILABLE"
+    code === "GITHUB_AUTH_UNAVAILABLE" ||
+    code === "DOCKER_PS_FAILED"
   );
 }