@runuai/host 0.9.168 → 0.9.169

package/lib/agent-cli.ts

@@ -1,3 +1,4 @@
+import { TASK_PROJECT_ADD_WAIT_MS } from "../src/protocol";
 import { validateShareablePath, ENGINE_ACCOUNT_PATH_RULES } from "../src/workspace-path-policy";
 /**
  * In-container `uai` CLI materialisation (ADR-048).
@@ -321,11 +322,26 @@ function opLine(op) {
   }
   return "adding " + op.slug + " (" + op.state + "); check again with: uai task project status " + op.operationId;
 }
+function opProgress(op) {
+  const attempts = Number.isInteger(op.attempts) ? "; attempts: " + op.attempts : "";
+  const lastError = op.lastError || (op.error && op.error.message);
+  return "[" + op.operationId + "] " + opLine(op) + attempts +
+    (lastError && op.state !== "failed" ? "; last error: " + lastError : "");
+}
 async function waitForProjectOp(op) {
-  const deadline = Date.now() + 25 * 60 * 1000;
+  const deadline = Date.now() + ${TASK_PROJECT_ADD_WAIT_MS};
+  let progress = opProgress(op);
+  let reportedAt = Date.now();
+  console.error(progress);
   while (!op.done && Date.now() < deadline) {
-    await new Promise((resolve) => setTimeout(resolve, 2000));
+    await new Promise((resolve) => setTimeout(resolve, Math.min(2000, Math.max(0, deadline - Date.now()))));
     op = (await api("GET", "/api/agent/task/projects/operations/" + encodeURIComponent(op.operationId))).operation;
+    const next = opProgress(op);
+    if (!op.done && (next !== progress || Date.now() - reportedAt >= 30_000)) {
+      console.error(next);
+      progress = next;
+      reportedAt = Date.now();
+    }
   }
   return op;
 }
@@ -333,7 +349,11 @@ async function addProjectToTask(project, wait) {
   const started = await api("POST", "/api/agent/task/projects", { projectId: project, idempotencyKey: opKey() });
   const op = wait ? await waitForProjectOp(started.operation) : started.operation;
   if (op.state === "failed") { console.error("uai: " + opLine(op)); process.exit(1); }
-  out(opLine(op));
+  if (wait && !op.done) {
+    console.error("uai: timed out waiting; the add is still in progress. " + opProgress(op));
+    process.exit(1);
+  }
+  out(wait ? opLine(op) : opProgress(op));
 }
 
 // ADR-161 §1.3. UAI_FILES_ROOT and UAI_FILES_STATE_FILE exist so tests can
@@ -1278,7 +1298,9 @@ async function main() {
         break;
       }
       if (sub === "status" && words.length === 2) {
-        out(opLine((await api("GET", "/api/agent/task/projects/operations/" + encodeURIComponent(words[1]))).operation));
+        const op = (await api("GET", "/api/agent/task/projects/operations/" + encodeURIComponent(words[1]))).operation;
+        out(opProgress(op));
+        if (op.state === "failed") process.exit(1);
         break;
       }
       console.error("uai: task project add <projectId|slug> [--no-wait]  |  task project status <operationId>");

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/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",
     );
   }

package/lib/task-project-ops.ts

@@ -74,6 +74,7 @@ import type {
   TaskProjectStatusResult,
 } from "../src/protocol";
 import { RUNTIME_AUTHORITY_ENV } from "./runtime-authority";
+import { TaskEnvironmentRequestValidationError } from "./task-environment/types";
 import type {
   TaskEnvironmentExecRequest,
   TaskEnvironmentExecResult,
@@ -271,7 +272,7 @@ export class TaskProjectJournalStore {
 
 /**
  * $1 staging repo path, $2 target path, $3 repo URL, $4 task branch,
- * $5 activation id, $6 the project's fallback `.tool-versions` ("" for none).
+ * $5 activation id, optional $6 the project's fallback `.tool-versions`.
  * Exit 3: the target already exists. The last stdout line is the checked-out
  * commit, or `empty` for a repository with no commits.
  */
@@ -684,13 +685,13 @@ export class TaskProjectOps {
   }
 
   prepare(input: TaskProjectPrepareInput): Promise<TaskProjectPrepareResult> {
-    return this.serialized(input.taskId, async () => {
-      if (!OPERATION_ID.test(input.operationId)) throw new Error("invalid operation id");
-      if (!SLUG.test(input.project.slug)) throw new Error("invalid project slug");
+    return this.serialized<TaskProjectPrepareResult>(input.taskId, async () => {
+      if (!OPERATION_ID.test(input.operationId)) throw new TaskEnvironmentRequestValidationError("invalid operation id");
+      if (!SLUG.test(input.project.slug)) throw new TaskEnvironmentRequestValidationError("invalid project slug");
       if (!REPO_URL.test(input.project.repoUrl)) {
-        return refused<TaskProjectPrepareResult>("clone_failed", "the repository URL is not an HTTPS or SSH Git remote");
+        throw new TaskEnvironmentRequestValidationError("the repository URL is not an HTTPS or SSH Git remote");
       }
-      if (!BRANCH.test(input.branch)) throw new Error("invalid task branch");
+      if (!BRANCH.test(input.branch)) throw new TaskEnvironmentRequestValidationError("invalid task branch");
       const fenced = this.fenceFails(input);
       if (fenced) return refused<TaskProjectPrepareResult>(fenced.reason, fenced.message);
 
@@ -728,7 +729,9 @@ export class TaskProjectOps {
             input.project.repoUrl,
             input.branch,
             activationId,
-            input.project.toolVersions ?? "",
+            // The provider rejects empty argv elements. The script already
+            // defaults an absent final argument to no fallback (${6:-}).
+            ...(input.project.toolVersions ? [input.project.toolVersions] : []),
           ],
           { cwd: environment.descriptor.workspacePath, timeoutMs: TASK_PROJECT_CLONE_TIMEOUT_MS },
         ),
@@ -780,6 +783,13 @@ export class TaskProjectOps {
         updatedAt: Date.now(),
       });
       return { outcome: "prepared", head, envSchema };
+    }).catch((error: unknown) => {
+      if (error instanceof TaskEnvironmentRequestValidationError) {
+        return refused<TaskProjectPrepareResult>("invalid_request", error.message);
+      }
+      // Provider availability, rebuilds and journal I/O remain INTERNAL so
+      // the cloud can retry them; never classify an error by its message.
+      throw error;
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.168",
+  "version": "0.9.169",
   "description": "Uai host \u2014 runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

package/src/main.ts

@@ -2,6 +2,7 @@
 import type { AssignmentDelivery, DeliveryOrigin } from "./protocol";
 
 import "./load-env";
+import { sampleDiskPressure } from "../lib/disk-pressure";
 import { TASK_SECRETS_FEATURE, isTaskSecretStagingPut } from "./task-secrets";
 import { writeTaskSecretStaging } from "../lib/task-secret-staging";
 
@@ -1473,12 +1474,28 @@ async function startLocalUi(): Promise<void> {
   }
 }
 
+// Capacity fits the existing capability/status snapshot; no new messages.
+let diskSnapshot: HostCapabilities["disk"];
+let diskSampling = false;
+async function refreshDiskSnapshot(): Promise<void> {
+  if (diskSampling || sidecarMode()) return;
+  diskSampling = true;
+  try {
+    diskSnapshot = await sampleDiskPressure();
+    sendCapabilities();
+  } finally { diskSampling = false; }
+}
+void refreshDiskSnapshot();
+const diskTimer = setInterval(() => void refreshDiskSnapshot(), 60_000);
+diskTimer.unref?.();
+
 /** Build the current host capability advertisement (ADR-021). */
 function buildCapabilities(): HostCapabilities {
   const runtime = containerRuntimeCapabilityState();
   const projectEnvBindings = projectEnvBindingCapability();
   return {
     version: packageVersion(),
+    ...(diskSnapshot ? { disk: diskSnapshot } : {}),
     protocolFeatures: [
       "host-workspace-file-read-v1",
       ASSIGNMENT_EVIDENCE_PROTOCOL_FEATURE,

package/src/protocol.ts

@@ -4068,6 +4068,15 @@ export function isHostConfigAckFrame(
  * changes. The cloud caches it per hostId to drive the task-creation pickers.
  */
 export interface HostCapabilities {
+  /** Filesystem capacity, refreshed each minute. Null means unmeasurable
+   * (for example Docker in a VM); available excludes root-reserved blocks. */
+  disk?: {
+    sampledAt: number;
+    /** Cloud-only: overwritten on authenticated receipt, never trusted from the host. */
+    receivedAt?: number;
+    home: { totalBytes: number; availableBytes: number } | null;
+    docker: { totalBytes: number; availableBytes: number } | null;
+  };
   /** The host-agent package version — the cloud UI shows it on the host page
    *  and flags when npm has a newer release. Optional (older hosts omit it). */
   version?: string;
@@ -4337,6 +4346,15 @@ export interface TaskDiffInput {
   projects: Array<{ id: string; slug: string }>;
 }
 
+/** Cloud Prepare retry timing. */
+export const TASK_PROJECT_PREPARE_MAX_ATTEMPTS = 12;
+export const TASK_PROJECT_PREPARE_TIMEOUT_MS = 11 * 60_000;
+export function taskProjectRetryDelayMs(attempts: number): number {
+  return Math.min(5 * 60_000, 2_000 * 2 ** Math.min(attempts, 7));
+}
+/** Bound the CLI tool call; the durable cloud operation may outlast it. */
+export const TASK_PROJECT_ADD_WAIT_MS = 40 * 60_000;
+
 /**
  * ADR-161 §2.3: every live-project command names the task's run, the
  * operation, and the project-set revision the operation commits. The runner
@@ -4362,6 +4380,7 @@ export interface TaskProjectPrepareInput extends TaskProjectOpFence {
 /** Why a live-project command did nothing. `grant_not_installed` and
  *  `busy` are retryable; the rest are final for that operation. */
 export type TaskProjectRefusal =
+  | "invalid_request"
   | "repo_access_denied"
   | "clone_failed"
   | "workspace_path_taken"