@runuai/host 0.9.168 → 0.9.170

package/lib/disk-pressure.ts

@@ -0,0 +1,42 @@
+import { execFile } from "node:child_process";
+import { statfs } from "node:fs/promises";
+import { homedir } from "node:os";
+import type { HostCapabilities } from "../src/protocol";
+
+type DiskSample = NonNullable<HostCapabilities["disk"]>;
+const dockerInfo = (args: string[]): Promise<string | null> => new Promise(resolve => {
+  execFile("docker", args, { timeout: 5_000, maxBuffer: 4096 }, (error, stdout) => {
+    resolve(error ? null : stdout.trim());
+  });
+});
+async function dockerRoot(): Promise<string | null> {
+  // A remote daemon (including Docker Desktop's VM) has no local filesystem
+  // we can measure. Never report a coincidentally matching local path.
+  if (process.platform !== "linux") return null;
+  const endpoint = process.env.DOCKER_HOST && !process.env.DOCKER_CONTEXT
+    ? process.env.DOCKER_HOST
+    : await dockerInfo(["context", "inspect", "--format", "{{.Endpoints.docker.Host}}"]);
+  if (!endpoint?.startsWith("unix://")) return null;
+  // Do not guess /var/lib/docker: data-root can be configured elsewhere.
+  const root = await dockerInfo(["info", "--format", "{{.DockerRootDir}}"]);
+  return root?.startsWith("/") ? root : null;
+}
+
+async function measure(path: string | null): Promise<DiskSample["home"]> {
+  if (!path) return null;
+  try {
+    const fs = await statfs(path);
+    const totalBytes = fs.blocks * fs.bsize;
+    // bavail (not bfree) accounts for root-reserved blocks: the host's
+    // unprivileged updater cannot use those even though root can.
+    const availableBytes = Math.max(0, fs.bavail * fs.bsize);
+    if (!Number.isSafeInteger(totalBytes) || totalBytes <= 0 || !Number.isSafeInteger(availableBytes) || availableBytes < 0 || availableBytes > totalBytes) return null;
+    return { totalBytes, availableBytes };
+  } catch { return null; }
+}
+
+export async function sampleDiskPressure(): Promise<DiskSample> {
+  const [home, docker] = await Promise.all([measure(homedir()), dockerRoot().then(measure)]);
+  // No local paths are sent to the cloud; an unavailable probe is unknown.
+  return { sampledAt: Date.now(), home, docker };
+}

package/lib/orchestrator.ts

@@ -40,6 +40,7 @@ import { inArray } from "drizzle-orm";
 
 import { getDb, schema } from "./db";
 import { newId } from "./ulid";
+import { agentErrorMessage, reportAgentError } from "./agent-errors";
 import { mockAgentFactory } from "./agents/mock";
 import { realAgentFactory } from "./agents/factory";
 import { resolveAgentMode } from "./agents/mode";
@@ -50,6 +51,7 @@ import {
 } from "./agents/session-state";
 import {
   type AgentEvent,
+  type AgentEventHandler,
   type AgentSession,
   type AgentSessionFactory,
   type Roster,
@@ -709,7 +711,11 @@ const BROWSER_RETRY_COOLDOWN_MS = 60_000;
  * poisons the runtime generation synchronously; normal detection/recovery owns
  * the eventual ready edge and deferred-prompt replay.
  */
-async function agentTerminationLostContainerRuntime(): Promise<boolean> {
+async function agentTerminationLostContainerRuntime(channel: Channel): Promise<boolean> {
+  // Machine/self tasks have no Docker/Apple daemon. A failed Docker probe
+  // there would turn a real engine failure into silent runtime recovery.
+  if (isEnvironmentTransportProvider(channel.agentHandle?.descriptor.locator.provider) ||
+    isEnvironmentTransportProvider(getHostTask(channel.taskId)?.environmentProvider)) return false;
   if (!backgroundContainerWorkAllowed()) return true;
   let reachable = false;
   try {
@@ -809,6 +815,7 @@ export interface OrchestratorTaskStopResult {
 }
 
 export class Orchestrator {
+  private readonly sessionEventHandlers = new WeakMap<AgentSession, AgentEventHandler>();
   private readonly channels = new Map<string, Channel>();
   private readonly channelSpecs = new Map<string, ChannelEnsureInput>();
   /** Teardown tombstones prevent a cloud ensure from reopening a task between
@@ -2915,7 +2922,7 @@ export class Orchestrator {
     // transport emission order across that await; otherwise the later boundary
     // can consume/reorder prompt state while the earlier error still owns it.
     let eventTail: Promise<void> = Promise.resolve();
-    session.onEvent((event) => {
+    const onEvent: AgentEventHandler = (event) => {
       this.markChannelActivity(channel.taskId);
       // Recycle/teardown deletes the old session before calling close().
       // Adapters deliberately emit a final exit event; without this identity
@@ -2957,7 +2964,9 @@ export class Orchestrator {
         () => channel.eventOperations.delete(operation),
         () => channel.eventOperations.delete(operation),
       );
-    });
+    };
+    this.sessionEventHandlers.set(session, onEvent);
+    session.onEvent(onEvent);
   }
 
   /**
@@ -4616,11 +4625,11 @@ export class Orchestrator {
     }
   }
 
-  /** Consume one queued/active turn and report how many remain. */
-  private decrementActiveTurns(channel: Channel, agentId: string): number {
+  /** Consume deliveries settled by one provider boundary. */
+  private decrementActiveTurns(channel: Channel, agentId: string, settles = 1): number {
     const remaining = Math.max(
       0,
-      (channel.activeTurns.get(agentId) ?? 1) - 1,
+      (channel.activeTurns.get(agentId) ?? 1) - settles,
     );
     if (remaining === 0) channel.activeTurns.delete(agentId);
     else channel.activeTurns.set(agentId, remaining);
@@ -4759,26 +4768,29 @@ export class Orchestrator {
     this.incrementActiveTurns(channel, agentId);
     void session.send(text).catch((err: unknown) => {
       if (turn) journal?.failed(sessionId, turn.turnId);
+      const diagnosticMessage = `Could not send the message to ${agentId}: ${err instanceof Error ? err.message : String(err)}`;
+      reportAgentError(diagnosticMessage, { taskId: channel.taskId, agentId, engine: session.kind },
+        { capture: !(err instanceof ContainerRuntimeUnavailableError) });
       if (channel.sessions.get(agentId) === session) {
-        this.removeAcceptedPrompt(channel, agentId, accepted);
-        const remaining = this.decrementActiveTurns(channel, agentId);
-        if (
-          remaining === 0 &&
-          channel.lastPrompt.get(agentId) === accepted
-        ) {
-          channel.lastPrompt.delete(agentId);
-        }
         if (err instanceof ContainerRuntimeUnavailableError) {
+          this.removeAcceptedPrompt(channel, agentId, accepted);
+          const remaining = this.decrementActiveTurns(channel, agentId);
+          if (remaining === 0 && channel.lastPrompt.get(agentId) === accepted) {
+            channel.lastPrompt.delete(agentId);
+          }
           this.deferPromptUntilRuntimeReady(channel, agentId, accepted);
         } else {
-          this.startNextPendingPrompt(channel, agentId);
+          // Share the ordered terminal-event path with adapter failures. It
+          // retires the active count and publishes the error/aborted boundary;
+          // a concurrent adapter error or exit can consume it only once.
+          this.sessionEventHandlers.get(session)?.({
+            type: "error",
+            message: agentErrorMessage(diagnosticMessage),
+            diagnosticMessage,
+            aborted: true,
+          });
         }
       }
-      console.warn(
-        `[orchestrator] ${channel.taskId}/${agentId}: send failed: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
     });
   }
 
@@ -4794,13 +4806,14 @@ export class Orchestrator {
     if (prompts.length === 0) channel.acceptedPrompts.delete(agentId);
   }
 
-  private completeNextAcceptedPrompt(
+  private completeAcceptedPrompts(
     channel: Channel,
     agentId: string,
+    settles = 1,
   ): void {
     const prompts = channel.acceptedPrompts.get(agentId);
     if (!prompts) return;
-    prompts.shift();
+    prompts.splice(0, settles);
     if (prompts.length === 0) channel.acceptedPrompts.delete(agentId);
   }
 
@@ -5257,8 +5270,13 @@ export class Orchestrator {
         });
         break;
       }
+      case "notice": {
+        this.emitSystemNote(channel.taskId, agentErrorMessage(`${agentId}: ${event.message}`));
+        break;
+      }
       case "error": {
-        if (await agentTerminationLostContainerRuntime()) {
+        const diagnosticMessage = event.diagnosticMessage ?? event.message;
+        if (await agentTerminationLostContainerRuntime(channel)) {
           // `error` and `exit` can arrive back-to-back while the daemon probe
           // is pending. Only the first terminal event still owns this session.
           if (channel.sessions.get(agentId) !== session) break;
@@ -5272,7 +5290,7 @@ export class Orchestrator {
         if (channel.sessions.get(agentId) !== session) break;
         // The turn died with the session — drop its turn-state flags so a
         // respawned session starts clean.
-        const abortBoundaryOnRosterChange =
+        let abortBoundaryOnRosterChange =
           this.needsAbortedTurnBoundary(channel, agentId);
         this.retainRetiredTurnBoundary(
           channel,
@@ -5280,6 +5298,14 @@ export class Orchestrator {
           abortBoundaryOnRosterChange,
         );
         this.retireRunnerGeneration(channel, agentId);
+        if (event.aborted) {
+          this.emitRetiredTurnAbort(channel, agentId);
+          const change = channel.rosterSessionChanges.get(agentId);
+          if (change) change.abortPublished = true;
+          // A recovery may replay the prompt, but the failed turn already
+          // ended. Do not publish a second boundary for this generation.
+          abortBoundaryOnRosterChange = false;
+        }
         // Claude under load (especially Docker Desktop macOS) occasionally
         // unlinks ~/.claude.json mid-write during atomic config rewrites,
         // and a concurrent claude spawn lands during the gap and exits 0
@@ -5325,7 +5351,7 @@ export class Orchestrator {
         if (
           agent &&
           agent.kind !== "claude" &&
-          isCredentialInvalidSignal(agent.kind, event.message)
+          isCredentialInvalidSignal(agent.kind, diagnosticMessage)
         ) {
           console.warn(
             `[orchestrator] ${channel.taskId}/${agentId}: ${agent.kind} credential-invalid pattern matched: ${event.message.slice(0, 300)}`,
@@ -5407,7 +5433,7 @@ export class Orchestrator {
           }
         }
         const isClaude = agent?.kind === "claude";
-        if (isClaude && agent && isClaudeAuthRevoked(event.message)) {
+        if (isClaude && agent && isClaudeAuthRevoked(diagnosticMessage)) {
           // Token revoked/expired: the env-injected credential only changes on
           // a fresh runner. Re-spawn on the re-resolved account (picks up a
           // reconnected token); bounded so a still-bad token can't loop.
@@ -5424,7 +5450,7 @@ export class Orchestrator {
           break;
         }
         const configMissing = CLAUDE_CONFIG_MISSING_PATTERNS.some((re) =>
-          re.test(event.message),
+          re.test(diagnosticMessage),
         );
         if (isClaude && configMissing) {
           // This recovery path deliberately starts the next queued turn rather
@@ -5439,7 +5465,7 @@ export class Orchestrator {
           break;
         }
         channel.lastPrompt.delete(agentId);
-        channel.retiredTurnBoundaries.delete(agentId);
+        this.emitRetiredTurnAbort(channel, agentId);
         this.emitHost({
           kind: "agent.exit",
           taskId: channel.taskId,
@@ -5469,9 +5495,11 @@ export class Orchestrator {
         // turn's messages and wakes the mentioned peers with the full turn.
         // An interrupted (ESC'd) turn goes out `aborted`: it's a half-turn, so
         // the cloud discards the buffer instead of handing it to peers.
-        const aborted = channel.interrupted.delete(agentId);
-        this.completeNextAcceptedPrompt(channel, agentId);
-        const remainingTurns = this.decrementActiveTurns(channel, agentId);
+        const aborted = channel.interrupted.delete(agentId) || event.aborted === true;
+        const settles = event.settles !== undefined && Number.isSafeInteger(event.settles) && event.settles > 0
+          ? event.settles : 1;
+        this.completeAcceptedPrompts(channel, agentId, settles);
+        const remainingTurns = this.decrementActiveTurns(channel, agentId, settles);
         channel.openTurns.delete(agentId);
         // ADR-076: a turn that completed means the current account is healthy —
         // reset its rotation budget so a LATER rate-limit gets a fresh failover.
@@ -5522,7 +5550,15 @@ export class Orchestrator {
         break;
       }
       case "exit":
-        if (await agentTerminationLostContainerRuntime()) {
+        if (event.code === 0 && this.needsAbortedTurnBoundary(channel, agentId)) {
+          await this.handleAgentEvent(channel, agentId, session, {
+            type: "error",
+            message: `${session.kind} stopped before replying to the message. Please try again.`,
+            aborted: true,
+          });
+          break;
+        }
+        if (await agentTerminationLostContainerRuntime(channel)) {
           if (channel.sessions.get(agentId) !== session) break;
           await this.retireSessionForRuntimeLoss(
             channel,
@@ -7319,7 +7355,10 @@ export function buildSystemPreamble(
         `${taskBranch}\` from inside the project, then open a PR with \`gh pr`,
         "create` (the container has gh authenticated). For multi-project",
         "tasks, each project's PR is independent — open one per project whose",
-        "worktree you actually changed.",
+        "worktree you actually changed. For a separate branch, create it in",
+        "this task's namespace — `git switch -c \"$(uai branch name fix-foo)\"`",
+        "makes `uai/<taskId>/fix-foo`. Only task-branch and namespace PRs link to",
+        "this task (reviews, `--pr`, Usage); a PR from any other branch does not.",
         "",
         "The `.uai/` directory under each task is uai's own scaffolding",
         "(rendered Dockerfile, compose file, container scripts) — it is NOT",

package/lib/standard-image-cleanup.ts

@@ -0,0 +1,117 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { CONTEXT_HASH_LABEL } from "./standard-image-pin";
+
+type Result = { code: number | null; stdout: string; stderr: string };
+export type DockerCommand = (command: string, args: string[], timeoutMs?: number) => Promise<Result>;
+const IMAGE_ID = /^sha256:[a-f0-9]{64}$/;
+const SWEEP_LIMIT = 16;
+const HISTORY_LIMIT = 128;
+const HISTORY_BYTES = 16 * 1024;
+
+/** Context labels are inherited by task images. Authority to delete comes
+ * from observing this exact id under the standard tag, never from a scan. */
+export class StandardImageCleanup {
+  private readonly observed = new Set<string>();
+  private loading: Promise<void> | undefined;
+  private statePath: string | undefined;
+
+  constructor(private readonly stateFile?: () => Promise<string>) {}
+
+  private async load(): Promise<void> {
+    if (!this.stateFile) return;
+    try {
+      this.statePath = await this.stateFile();
+      const fd = openSync(this.statePath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > HISTORY_BYTES) return;
+        const bytes = Buffer.alloc(HISTORY_BYTES + 1);
+        const length = readSync(fd, bytes, 0, bytes.length, 0);
+        if (length > HISTORY_BYTES) return;
+        const value = JSON.parse(bytes.subarray(0, length).toString("utf8")) as { version?: unknown; ids?: unknown };
+        if (value?.version !== 1 || !Array.isArray(value.ids) || value.ids.length > HISTORY_LIMIT || !value.ids.every(id => typeof id === "string" && IMAGE_ID.test(id))) return;
+        for (const id of value.ids) this.observed.add(id as string);
+      } finally { closeSync(fd); }
+    } catch { /* Missing, corrupt or unreadable history authorizes nothing. */ }
+  }
+
+  private save(): void {
+    if (!this.statePath) return;
+    const temporary = `${this.statePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      mkdirSync(dirname(this.statePath), { recursive: true, mode: 0o700 });
+      writeFileSync(temporary, JSON.stringify({ version: 1, ids: [...this.observed] }), { flag: "wx", mode: 0o600 });
+      renameSync(temporary, this.statePath);
+    } catch {
+      // ENOSPC must not block a build or safe cleanup using in-memory proof.
+      console.warn("[host-agent] could not persist standard-image history");
+    } finally {
+      try { unlinkSync(temporary); } catch { /* Renamed or never created. */ }
+    }
+  }
+
+  async observe(run: DockerCommand, ref = "uai-standard:dev"): Promise<string | null> {
+    await (this.loading ??= this.load());
+    const result = await run("docker", ["image", "inspect", "--format", "{{json .}}", ref]);
+    if (result.code !== 0) return null;
+    try {
+      const image = JSON.parse(result.stdout) as { Id?: string; Config?: { Labels?: Record<string, string> } };
+      if (!IMAGE_ID.test(image.Id ?? "") || !/^[a-f0-9]{32}$/.test(image.Config?.Labels?.[CONTEXT_HASH_LABEL] ?? "")) return null;
+      if (ref === "uai-standard:dev") {
+        this.observed.delete(image.Id!);
+        this.observed.add(image.Id!);
+        if (this.observed.size > HISTORY_LIMIT) this.observed.delete(this.observed.values().next().value!);
+        this.save();
+      }
+      return image.Id!;
+    } catch { return null; }
+  }
+
+  async sweep(run: DockerCommand, previousId: string | null): Promise<void> {
+    const deadline = Date.now() + 30_000;
+    const boundedRun: DockerCommand = (command, args) => run(command, args, 5_000);
+    const currentId = await this.observe(boundedRun);
+    if (!currentId) return;
+    const history = await boundedRun("docker", ["image", "history", "--quiet", "--no-trunc", currentId]);
+    if (history.code !== 0) return;
+    const currentChain = new Set([currentId, ...history.stdout.trim().split(/\s+/)]);
+    const candidates = new Set([...(previousId ? [previousId] : []), ...this.observed]);
+    for (const id of [...candidates].filter(id => this.observed.has(id) && !currentChain.has(id)).slice(0, SWEEP_LIMIT)) {
+      if (Date.now() >= deadline) break;
+      // Round-robin retained/in-use ids so a busy prefix cannot starve later ids.
+      this.observed.delete(id);
+      this.observed.add(id);
+      const tags = await boundedRun("docker", ["image", "inspect", "--format", "{{json .RepoTags}}", id]);
+      if (tags.code !== 0) continue;
+      try { const parsed: unknown = JSON.parse(tags.stdout); if (parsed !== null && (!Array.isArray(parsed) || parsed.length !== 0)) continue; } catch { continue; }
+      const containers = await boundedRun("docker", ["ps", "--all", "--quiet", "--filter", `ancestor=${id}`]);
+      if (containers.code !== 0 || containers.stdout.trim()) continue;
+      // Normal Docker removal reclaims otherwise-unused untagged parents.
+      // Shared ancestors of the current image (or any other child/container)
+      // remain protected by the daemon. Never force or target a parent id.
+      const removed = await boundedRun("docker", ["image", "rm", id]);
+      if (removed.code === 0) {
+        this.observed.delete(id);
+        console.log("[host-agent] removed unused previous standard image", id);
+      }
+    }
+    this.save();
+  }
+}
+
+/** Per-process exponential retry, keyed by the desired content/configuration.
+ * A new host payload/engine configuration retries immediately. A restart also
+ * retries once; repeated failures back off 2h, 4h, …, 24h instead of hourly. */
+export class StandardImageBuildBackoff {
+  private state: { key: string; failures: number; retryAt: number; error: string } | null = null;
+  remaining(key: string, now = Date.now()): { delay: number; retryAt: number; error: string } | null {
+    return this.state?.key === key && this.state.retryAt > now ? { delay: this.state.retryAt - now, retryAt: this.state.retryAt, error: this.state.error } : null;
+  }
+  failed(key: string, error: string, now = Date.now()): void {
+    const failures = this.state?.key === key ? this.state.failures + 1 : 1;
+    this.state = { key, failures, retryAt: now + Math.min(24, 2 ** Math.min(failures, 5)) * 3_600_000, error };
+  }
+  clear(): void { this.state = null; }
+}

package/lib/standard-image.ts

@@ -2,7 +2,8 @@
  * Standard-image build pipeline (ADR-022 / docs/runtime.md).
  *
  * Every host builds exactly one standard image (`uai-standard:dev`) and
- * caches it. `ensureStandardImage()` is called once at host startup:
+ * caches it. `ensureStandardImage()` runs at startup and on the owned-host
+ * hourly maintenance schedule (local build failures back off):
  *
  *   1. `docker volume create uai-asdf-data` — the host-wide asdf data volume
  *      that caches lazily-installed runtime versions across tasks (idempotent;
@@ -52,6 +53,7 @@ import {
   standardImagePullDigest,
 } from "./standard-image-pin";
 import { sidecarMode } from "./sidecar";
+import { StandardImageCleanup, StandardImageBuildBackoff } from "./standard-image-cleanup";
 
 /** Pinned, host-wide constants (must match task-up.sh and the compose gen). */
 export const STANDARD_IMAGE_TAG = "uai-standard:dev";
@@ -1296,8 +1298,15 @@ export type ActivationIsCurrent = () => boolean;
 /** Tests: forget every remembered pass. */
 export function resetStandardImageMemo(): void {
   lastOkByKey.clear();
+  buildBackoff.clear();
 }
 
+const buildBackoff = new StandardImageBuildBackoff();
+const imageCleanup = new StandardImageCleanup(async () => {
+  const { env } = await import("./env");
+  return resolve(env.dataDir, "standard-image-seen.json");
+});
+
 /** The owned-host schedule (docs/agent-notes.md, "image maintenance"). */
 export const MAINTENANCE_INTERVAL_MS = 60 * 60_000;
 
@@ -1418,6 +1427,7 @@ async function ensureStandardImageInner(
   // hash, not this host's per-config hash, which would disagree by design
   // and rebuild forever). Any pull-path failure falls through to the local
   // build below, so offline and registry-down hosts behave exactly as today.
+  const previousImageId = engine.apple ? null : await imageCleanup.observe(run);
   const pin = await readStandardImagePin();
   if (pin !== null) {
     if (inspect.code === 0 && labeledHash === pin.contextHash) {
@@ -1473,13 +1483,18 @@ async function ensureStandardImageInner(
     imageReady = true;
   } else {
     const context = standardImageDir();
-    console.log(
-      inspect.code === 0
-        ? `[host-agent] standard image ${STANDARD_IMAGE_TAG} stale (context changed) — rebuilding from ${context}`
-        : `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
-    );
-    const build = await run(engine.command, [
+    const buildKey = `${contextHash ?? "unavailable"}:${JSON.stringify(engines)}:${pin?.contextHash ?? "local"}`;
+    const deferred = engine.apple || labeledHash === null ? null : buildBackoff.remaining(buildKey);
+    if (!deferred) {
+      console.log(
+        inspect.code === 0
+          ? `[host-agent] standard image ${STANDARD_IMAGE_TAG} stale (context changed) — rebuilding from ${context}`
+          : `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
+      );
+    }
+    const build = deferred ? { code: 1, stdout: "", stderr: `${deferred.error}\nStandard image build deferred until ${new Date(deferred.retryAt).toISOString()}.` } : await run(engine.command, [
       "build",
+      ...(engine.apple ? [] : ["--force-rm"]),
       "-t",
       STANDARD_IMAGE_TAG,
       ...engineArgs,
@@ -1491,11 +1506,14 @@ async function ensureStandardImageInner(
     if (build.code === 0) {
       console.log(`[host-agent] built standard image ${STANDARD_IMAGE_TAG}`);
       imageReady = true;
+      buildBackoff.clear();
     } else {
       buildError =
         build.stderr.trim() ||
         `docker build exited ${build.code ?? "spawn error"}`;
+      if (!deferred && !engine.apple) buildBackoff.failed(buildKey, buildError);
       console.warn(
+        deferred ? `[host-agent] ${buildError}` :
         `[host-agent] standard image build failed (exit ${build.code ?? "spawn"}); ` +
           "continuing. Tasks needing the image will surface this error.\n" +
           buildError,
@@ -1505,6 +1523,10 @@ async function ensureStandardImageInner(
     }
   }
 
+  // Revisit ids durably observed under the standard tag across restarts.
+  // Inherited labels never authorize sweeping task/compose images.
+  if (imageReady && !engine.apple) await imageCleanup.sweep(run, previousImageId);
+
   // 3. Reconcile every Uai-owned writer under the volume-global flock. Lock
   //    bootstrap/permission repair precedes the single upgrade→repair→proof
   //    transaction so node-run task materializers can acquire legacy volumes.
@@ -1648,7 +1670,7 @@ async function ensureStandardImageInner(
       }
       return {
         ok: false,
-        error: `Could not prepare shared runtime maintenance lock ${ASDF_MAINTENANCE_LOCK_PATH}.`,
+        error: `${buildError ? `${buildError} ` : ""}Could not prepare shared runtime maintenance lock ${ASDF_MAINTENANCE_LOCK_PATH}.`,
       };
     }
     if (!(await reconcileVolumeAgentClis(activation))) {
@@ -1661,7 +1683,7 @@ async function ensureStandardImageInner(
       return {
         ok: false,
         error:
-          "Shared runtime maintenance failed; agent CLIs or Corepack did not pass execution proof.",
+          `${buildError ? `${buildError} ` : ""}Shared runtime maintenance failed; agent CLIs or Corepack did not pass execution proof.`,
       };
     }
     return { ok: true };

package/lib/task-environment/types.ts

@@ -393,6 +393,11 @@ export function assertWorkspaceScopedPath(
   }
 }
 
+/** A malformed process request, distinct from provider/runtime failures. */
+export class TaskEnvironmentRequestValidationError extends Error {
+  override name = "TaskEnvironmentRequestValidationError";
+}
+
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 /** Shared admission guard for provider implementations and fake providers. */
@@ -402,7 +407,7 @@ const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 export function assertTaskEnvironmentExecRequest(request: TaskEnvironmentExecRequest): void {
   const { privileged, ...unprivileged } = request;
   if (privileged !== undefined && (privileged !== true || request.user !== "root")) {
-    throw new Error("a privileged task environment exec must run as root");
+    throw new TaskEnvironmentRequestValidationError("a privileged task environment exec must run as root");
   }
   assertTaskEnvironmentProcessRequest(unprivileged);
 }
@@ -412,7 +417,7 @@ export function assertTaskEnvironmentProcessRequest(
 ): void {
   assertTaskEnvironmentSessionRequest(request);
   if (!Number.isSafeInteger(request.timeoutMs) || request.timeoutMs <= 0) {
-    throw new Error("task environment timeout must be a positive integer");
+    throw new TaskEnvironmentRequestValidationError("task environment timeout must be a positive integer");
   }
 }
 
@@ -420,7 +425,7 @@ export function assertTaskEnvironmentProcessRequest(
  *  step without the capability it asked for. */
 export function refusePrivilegedExec(request: TaskEnvironmentExecRequest): void {
   if (request.privileged === true) {
-    throw new Error("this task environment provider has no privileged exec");
+    throw new TaskEnvironmentRequestValidationError("this task environment provider has no privileged exec");
   }
 }
 
@@ -434,13 +439,13 @@ export function assertTaskEnvironmentSessionRequest(
   // Only a one-shot exec may be privileged (assertTaskEnvironmentExecRequest
   // strips it after checking); anywhere else it is refused outright.
   if ("privileged" in request) {
-    throw new Error("only a one-shot task environment exec may be privileged");
+    throw new TaskEnvironmentRequestValidationError("only a one-shot task environment exec may be privileged");
   }
   if (
     request.projectEnvProfile !== "maintenance" &&
     request.projectEnvProfile !== "task"
   ) {
-    throw new Error(
+    throw new TaskEnvironmentRequestValidationError(
       "task environment project env profile must be maintenance or task",
     );
   }
@@ -451,19 +456,19 @@ export function assertTaskEnvironmentSessionRequest(
       (part) => typeof part !== "string" || part.length === 0 || part.includes("\0"),
     )
   ) {
-    throw new Error("task environment argv must contain nonempty NUL-free strings");
+    throw new TaskEnvironmentRequestValidationError("task environment argv must contain nonempty NUL-free strings");
   }
   if (
     request.cwd !== undefined &&
-    (!request.cwd.startsWith("/") || request.cwd.includes("\0"))
+    (typeof request.cwd !== "string" || !request.cwd.startsWith("/") || request.cwd.includes("\0"))
   ) {
-    throw new Error("task environment cwd must be an absolute NUL-free path");
+    throw new TaskEnvironmentRequestValidationError("task environment cwd must be an absolute NUL-free path");
   }
   if (
     request.user !== undefined &&
-    (request.user.length === 0 || request.user.includes("\0"))
+    (typeof request.user !== "string" || request.user.length === 0 || request.user.includes("\0"))
   ) {
-    throw new Error("task environment user must be a nonempty NUL-free value");
+    throw new TaskEnvironmentRequestValidationError("task environment user must be a nonempty NUL-free value");
   }
   if (
     request.anchor !== undefined &&
@@ -474,7 +479,7 @@ export function assertTaskEnvironmentSessionRequest(
         (part) => typeof part !== "string" || part.length === 0 || part.includes("\0"),
       ))
   ) {
-    throw new Error("a task environment anchor must be a NUL-free argv for a task user's process");
+    throw new TaskEnvironmentRequestValidationError("a task environment anchor must be a NUL-free argv for a task user's process");
   }
   if (
     request.inheritEnv !== undefined &&
@@ -485,7 +490,7 @@ export function assertTaskEnvironmentSessionRequest(
         (name) => typeof name !== "string" || !ENV_NAME.test(name),
       ))
   ) {
-    throw new Error("task environment inherited env names are invalid");
+    throw new TaskEnvironmentRequestValidationError("task environment inherited env names are invalid");
   }
   for (const [name, value] of Object.entries(request.env ?? {})) {
     if (
@@ -493,21 +498,21 @@ export function assertTaskEnvironmentSessionRequest(
       typeof value !== "string" ||
       value.includes("\0")
     ) {
-      throw new Error("task environment env must contain valid NUL-free entries");
+      throw new TaskEnvironmentRequestValidationError("task environment env must contain valid NUL-free entries");
     }
   }
   if (
     !Number.isSafeInteger(request.maxOutputBytes) ||
     request.maxOutputBytes <= 0
   ) {
-    throw new Error("task environment output limit must be a positive integer");
+    throw new TaskEnvironmentRequestValidationError("task environment output limit must be a positive integer");
   }
   if (
     "launchTimeoutMs" in request &&
     (!Number.isSafeInteger(request.launchTimeoutMs) ||
       request.launchTimeoutMs <= 0)
   ) {
-    throw new Error(
+    throw new TaskEnvironmentRequestValidationError(
       "task environment detached launch timeout must be a positive integer",
     );
   }