@runuai/host 0.9.167 → 0.9.169

package/lib/task-secret-staging.ts

@@ -0,0 +1,16 @@
+/** Immutable write-only task secret writer. Never return a value or provider error. */
+import { createHash, createHmac } from "node:crypto";
+import { isTaskSecretStagingPut, type TaskSecretStagingPut } from "../src/task-secrets";
+import { configuredCredentialStore, type CredentialStore } from "./credential-store";
+import { masterKey } from "./secrets";
+export function taskSecretParameter(taskId: string, name: string, stagingId: string): string {
+  return `/uai/lease/tasks/${taskId}/secrets/${createHash("sha256").update(name).digest("hex")}/${stagingId}`;
+}
+export async function writeTaskSecretStaging(frame: TaskSecretStagingPut, options: { store?: CredentialStore | null; hmacKey?: Buffer } = {}): Promise<void> {
+  if (!isTaskSecretStagingPut(frame)) throw new Error("invalid task secret staging request");
+  const store = Object.hasOwn(options, "store") ? options.store : configuredCredentialStore();
+  if (!store?.putImmutable) throw new Error("task secret writer unavailable");
+  const envelope = JSON.stringify({ v: 1, kind: "task-secret", orgId: frame.orgId, taskId: frame.taskId, name: frame.name, stagingId: frame.stagingId, value: frame.value });
+  const mac = createHmac("sha256", options.hmacKey ?? masterKey()).update("uai.task-secret.staging.v1\0").update(envelope).digest("hex");
+  await store.putImmutable(taskSecretParameter(frame.taskId, frame.name, frame.stagingId), envelope, { org: frame.orgId, task: frame.taskId, uai_staging_mac: mac });
+}

package/lib/task-token.ts

@@ -13,6 +13,8 @@ export interface TaskTokenPayload {
   agentId?: string;
   /** ADR-157 §3: the agent's roster generation; the cloud requires it to match. */
   generation?: string;
+  /** Server-issued lead context, frozen into a lead process token by the host. */
+  leadRunId?: string;
 }
 
 const PREFIX = "uai_";
@@ -34,6 +36,7 @@ export function signTaskToken(payload: TaskTokenPayload, secret: string): string
         p: payload.permissions,
         ...(payload.agentId ? { a: payload.agentId } : {}),
         ...(payload.generation ? { g: payload.generation } : {}),
+        ...(payload.leadRunId ? { l: payload.leadRunId } : {}),
         iat: Math.floor(Date.now() / 1000),
       }),
     ),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.167",
-  "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
+  "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>",
   "homepage": "https://github.com/runuai/uai#readme",
@@ -80,6 +80,18 @@
     "./engine-usage": {
       "types": "./src/engine-usage.ts",
       "default": "./src/engine-usage.ts"
+    },
+    "./workspace-path-policy": {
+      "types": "./src/workspace-path-policy.ts",
+      "default": "./src/workspace-path-policy.ts"
+    },
+    "./task-secrets": {
+      "types": "./src/task-secrets.ts",
+      "default": "./src/task-secrets.ts"
+    },
+    "./task-env-names": {
+      "types": "./src/task-env-names.ts",
+      "default": "./src/task-env-names.ts"
     }
   },
   "scripts": {

package/src/cloud-credentials.ts

@@ -1,3 +1,5 @@
+import { MAX_TASK_SECRETS, TASK_SECRET_NAME, TASK_SECRET_STAGING_ID, type TaskSecretManifestEntry } from "./task-secrets";
+
 /**
  * ADR-154 — the shared contract for cloud-only credentials.
  *
@@ -31,6 +33,15 @@ export const HOST_CLOUD_CREDENTIALS_FEATURE = "host-cloud-credentials-v1";
  */
 export const HOST_TASK_FILES_LEASE_FEATURE = "host-task-files-lease-v1";
 
+/**
+ * Advertised by a runner whose in-task `uai files` reads cloud links instead
+ * of a bind-mounted shared folder (ADR-161 §1.11). A task machine that still
+ * installs a Files session advertises the lease feature as well; the cloud
+ * treats "both" as a legacy session plus cloud links, and it does not mount
+ * the legacy folder into that container.
+ */
+export const HOST_AGENT_FILES_FEATURE = "host-agent-files-v1";
+
 /**
  * Set to `1` in a Uai Cloud task machine's root-only launch state
  * (`/etc/uai/sidecar.env`) when the cloud launched it on cloud credentials
@@ -752,6 +763,8 @@ export interface LeaseManifestStatic {
 
 /** What a task may read, by name and version — never a value. */
 export interface CredentialManifest {
+  /** Omitted on older peers and when empty, preserving old digests. */
+  taskSecrets?: TaskSecretManifestEntry[];
   /** The task's projects, lead first. */
   projects: LeaseManifestProject[];
   /** Per engine kind: the owner's personal accounts, then the workspace's. */
@@ -946,12 +959,13 @@ type WireObject = Record<string, unknown>;
 function exactObject(
   value: unknown,
   required: readonly string[],
+  optional: readonly string[] = [],
 ): WireObject | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const object = value as WireObject;
   const keys = Object.keys(object);
   if (
-    keys.length !== required.length ||
+    keys.some(key => !required.includes(key) && !optional.includes(key)) ||
     required.some((key) => !Object.hasOwn(object, key))
   ) {
     return null;
@@ -1226,10 +1240,10 @@ function parseStatic(
 
 function parseManifest(
   value: unknown,
-  grant: { orgId: string; userId: string },
+  grant: { orgId: string; userId: string; taskId: string },
   credentialSessions: ReadonlySet<string>,
 ): CredentialManifest | null {
-  const o = exactObject(value, ["projects", "engines", "mcp", "github", "ssh"]);
+  const o = exactObject(value, ["projects", "engines", "mcp", "github", "ssh"], ["taskSecrets"]);
   if (
     !o ||
     !Array.isArray(o.projects) ||
@@ -1281,6 +1295,29 @@ function parseManifest(
   ) {
     return null;
   }
+  if (o.taskSecrets !== undefined) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(grant.taskId) || !Array.isArray(o.taskSecrets) || !o.taskSecrets.length || o.taskSecrets.length > MAX_TASK_SECRETS) return null;
+    const entries: TaskSecretManifestEntry[] = [];
+    for (const item of o.taskSecrets) {
+      const e = exactObject(item, ["credentialId", "name", "stagingId", "generation", "parameter", "version", "mode", "domains", "placeholder", "sessionId"]);
+      if (!e || typeof e.name !== "string" || !TASK_SECRET_NAME.test(e.name) ||
+        typeof e.credentialId !== "string" || e.credentialId !== `task-secret:${e.name}` ||
+        typeof e.stagingId !== "string" || !TASK_SECRET_STAGING_ID.test(e.stagingId) || !isPositiveInteger(e.generation) || e.version !== 1 ||
+        typeof e.parameter !== "string" || (!e.parameter.startsWith(`/uai/lease/tasks/${grant.taskId}/secrets/`) || !/^[0-9a-f]{64}\/[0-9a-f-]{36}$/.test(e.parameter.slice(`/uai/lease/tasks/${grant.taskId}/secrets/`.length)) || !e.parameter.endsWith(`/${e.stagingId}`)) ||
+        (e.mode !== "proxied" && e.mode !== "delivered") || !Array.isArray(e.domains) || e.domains.length > 16 ||
+        !e.domains.every(d => typeof d === "string" && /^[a-z0-9.-]+\.[a-z]{2,}$/.test(d)) ||
+        (e.mode === "proxied" && !e.domains.length) || (e.mode === "delivered" && e.domains.length) ||
+        typeof e.sessionId !== "string" || !credentialSessions.has(e.sessionId)) return null;
+      if (e.placeholder !== null) {
+        const shape = exactObject(e.placeholder, ["prefix", "totalLength"]);
+        if (!shape || typeof shape.prefix !== "string" || !/^(?:[A-Za-z0-9._~-]*[_-])?$/.test(shape.prefix) ||
+          !isPositiveInteger(shape.totalLength) || shape.totalLength < shape.prefix.length + 32 || shape.totalLength > 256) return null;
+      }
+      entries.push(e as unknown as TaskSecretManifestEntry);
+    }
+    if (!uniqueBy(entries, e => e.name)) return null;
+    return { projects, engines, mcp, github, ssh, taskSecrets: entries };
+  }
   return { projects, engines, mcp, github, ssh };
 }
 
@@ -1359,7 +1396,7 @@ export function parseTaskLeaseV1(value: unknown): TaskLeaseV1 | null {
   }
   const files = o.files === null ? null : parseFiles(o.files);
   if (o.files !== null && !files) return null;
-  const grant = { orgId: o.orgId, userId: o.userId };
+  const grant = { orgId: o.orgId, userId: o.userId, taskId: o.taskId };
   const manifest = parseManifest(o.manifest, grant, credentialSessions);
   if (!manifest) return null;
   return {

package/src/engine-account-paths.ts

@@ -0,0 +1,11 @@
+/** Secret-free paths shared by account provisioning and credential safeguards. */
+export const ENGINE_ACCOUNT_PATHS = {
+  grok: { defaultContainerDir: "/home/node/.grok", containerDirPrefix: "/home/node/.grok-acct-" },
+  codex: { defaultContainerDir: "/home/node/.codex", containerDirPrefix: "/home/node/.codex-acct-" },
+  opencode: { defaultContainerDir: "/home/node/.local/share/opencode", containerDirPrefix: "/home/node/.local/share/opencode-acct-" },
+} as const;
+/** Relative to the home, so safeguards cover relocated homes and symlinks too. */
+export const ENGINE_ACCOUNT_PATH_RULES = Object.values(ENGINE_ACCOUNT_PATHS).flatMap((path) => [
+  { components: path.defaultContainerDir.split("/").slice(3), prefix: false },
+  { components: path.containerDirPrefix.split("/").slice(3), prefix: true },
+]);

package/src/index.ts

@@ -1,3 +1,5 @@
+import { assertShareablePath, normalizedWorkspacePath } from "./workspace-path-policy";
+import { readBoundedFile } from "../lib/task-environment/workspace-files";
 import {
   agent,
   AgentError,
@@ -51,7 +53,7 @@ import {
 import { readAttachment, writeAttachment } from "../lib/attachments";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { env, taskProjectWorktree } from "../lib/env";
+import { env, taskProjectWorktree, taskWorkspaceDir } from "../lib/env";
 import { getDecryptedForProject } from "../lib/host-env";
 import {
   envSchemaNote,
@@ -63,6 +65,7 @@ import {
   appendTranscriptViaEnvironment,
 } from "../lib/transcript";
 import { buildTaskDiff } from "../lib/task-diff";
+import { taskProjectOps } from "../lib/task-project-ops-host";
 import { stoppedTaskDiff } from "../lib/task-diff-sandbox";
 import {
   admitTaskRunEpoch,
@@ -2036,7 +2039,7 @@ export const hostCommands: HostCommands = {
     });
   },
 
-  async channelDeliver(ctx, taskId, agentId, text, origin) {
+  async channelDeliver(ctx, taskId, agentId, text, origin, assignment) {
     logCommand(ctx, "channelDeliver", taskId, agentId);
     if (credentialsMode() === "pending") {
       return switchingToCloudCredentials();
@@ -2047,7 +2050,7 @@ export const hostCommands: HostCommands = {
       // An inbound turn is activity: the idle veto must cover the gap between
       // this delivery landing and the agent's first output event.
       getOrchestrator().markChannelActivity(taskId);
-      const result = await getOrchestrator().deliver(taskId, agentId, text, origin);
+      const result = await getOrchestrator().deliver(taskId, agentId, text, origin, assignment);
       if (!result.ok) {
         return {
           ok: false,
@@ -2245,6 +2248,53 @@ export const hostCommands: HostCommands = {
     }
   },
 
+  // ADR-161 §2.3: add a repository to a running task. Each command runs in
+  // the task's live-project queue; the publication steps take its lifecycle
+  // slot (lib/task-project-ops.ts).
+  async taskProjectPrepare(ctx, input) {
+    logCommand(ctx, "taskProjectPrepare", input.taskId, input.operationId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      return ok(await taskProjectOps().prepare(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async taskProjectActivate(ctx, input) {
+    logCommand(ctx, "taskProjectActivate", input.taskId, input.operationId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      return ok(await taskProjectOps().activate(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async taskProjectCompensate(ctx, input) {
+    logCommand(ctx, "taskProjectCompensate", input.taskId, input.operationId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      return ok(await taskProjectOps().compensate(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
+  async taskProjectStatus(ctx, input) {
+    logCommand(ctx, "taskProjectStatus", input.taskId, input.operationId);
+    const runtimeFailure = runtimeUnavailable();
+    if (runtimeFailure) return runtimeFailure;
+    try {
+      return ok(await taskProjectOps().status(input));
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
   async attachmentWrite(ctx, input) {
     logCommand(ctx, "attachmentWrite", input.taskId, input.filename);
     try {
@@ -2273,6 +2323,19 @@ export const hostCommands: HostCommands = {
     }
   },
 
+  async workspaceFileRead(ctx, input) {
+    try {
+      const path = normalizedWorkspacePath(assertShareablePath(input.path));
+      const maxBytes = Math.min(8 * 1024 * 1024, Math.max(0, input.maxBytes));
+      const environment = await reconstructHostTaskEnvironment(input.taskId);
+      const bytes = environment ? await environment.readWorkspaceFile(`${environment.descriptor.workspacePath}/${path.slice("/workspace/".length)}`, { maxBytes: maxBytes + 1 }) :
+        await readBoundedFile(taskWorkspaceDir(input.taskId), path.slice("/workspace/".length).split("/"), { maxBytes: maxBytes + 1 });
+      if (!bytes) return { ok: false, code: HostErrorCode.TaskNotFound, message: "no such workspace file" };
+      if (bytes.byteLength > maxBytes) return { ok: false, code: HostErrorCode.PayloadTooLarge, message: "Ask the agent to uai share this file (live preview is limited to 8 MiB)." };
+      return ok({ dataBase64: Buffer.from(bytes).toString("base64"), size: bytes.byteLength });
+    } catch { return { ok: false, code: HostErrorCode.TaskNotFound, message: "no such workspace file" }; }
+  },
+
   async attachmentRead(ctx, input) {
     logCommand(ctx, "attachmentRead", input.taskId, input.filename);
     try {

package/src/main.ts

@@ -1,6 +1,10 @@
 #!/usr/bin/env tsx
+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";
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import {
@@ -113,6 +117,7 @@ import {
   parseLeaseGrantV1Frame,
   parseLeaseStaleFrame,
   parseLeaseUnavailableFrame,
+  HOST_AGENT_FILES_FEATURE,
   HOST_TASK_FILES_LEASE_FEATURE,
 } from "./cloud-credentials";
 import { captureEngineAccount } from "../lib/capture-flow";
@@ -301,6 +306,7 @@ import {
   HOST_ENGINE_DISCONNECT_PROTOCOL_FEATURE,
   HOST_ENGINE_LOGIN_PROTOCOL_FEATURE,
   LIVE_ROSTER_EDIT_PROTOCOL_FEATURE,
+  LIVE_TASK_PROJECTS_PROTOCOL_FEATURE,
   AGENT_TOKEN_GENERATION_PROTOCOL_FEATURE,
   isEngineAccountScope,
   isTaskMachineRetireAckFrame,
@@ -318,6 +324,8 @@ import {
   MAX_REMOTE_HOST_MESSAGE_BYTES,
   MCP_GATEWAY_HEALTH_PROTOCOL_FEATURE,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
+  ASSIGNMENT_EVIDENCE_PROTOCOL_FEATURE,
+  LEAD_EVIDENCE_PROTOCOL_FEATURE,
   TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
   type CloudToHost,
   type McpOp,
@@ -364,6 +372,10 @@ import {
   type TaskCommandProject,
   type TaskCommandTask,
   type TaskDiffInput,
+  type TaskProjectActivateInput,
+  type TaskProjectOpFence,
+  type TaskProjectPrepareInput,
+  type TaskProjectStatusInput,
   type TaskDownInput,
   type TaskLaunchInput,
   type TaskStopInput,
@@ -1462,13 +1474,32 @@ 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,
+  LEAD_EVIDENCE_PROTOCOL_FEATURE,
       TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
       EVENT_REPLAY_PROTOCOL_FEATURE,
       GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
@@ -1489,6 +1520,8 @@ function buildCapabilities(): HostCapabilities {
       HOST_ENGINE_DISCONNECT_PROTOCOL_FEATURE,
       ENGINE_USAGE_PROTOCOL_FEATURE,
       LIVE_ROSTER_EDIT_PROTOCOL_FEATURE,
+      LIVE_TASK_PROJECTS_PROTOCOL_FEATURE,
+      ...(credentialsMode() === "active" || signInBoxMode() ? [TASK_SECRETS_FEATURE] : []),
       AGENT_TOKEN_GENERATION_PROTOCOL_FEATURE,
       // The echo adapter cannot execute the in-task CLI. Advertising typed
       // dispatch in mock mode would let the composer create a Secretary that
@@ -1504,6 +1537,9 @@ function buildCapabilities(): HostCapabilities {
         taskFilesMachineRetirementReady()
         ? [HOST_TASK_FILES_LEASE_FEATURE]
         : []),
+      // ADR-161 §1.11: this image's `uai files` reads cloud links. The cloud
+      // captures the advertisement at container creation.
+      HOST_AGENT_FILES_FEATURE,
       // ADR-154: only the sign-in box writes cloud credentials.
       ...(signInBoxMode()
         ? [
@@ -3624,6 +3660,18 @@ async function connect(): Promise<void> {
         );
         break;
       }
+      case "task.secret.staging.put": {
+        if (!signInBoxMode() || !isTaskSecretStagingPut(frame)) break;
+        void managedMutationDrain.track(async () => {
+          try {
+            await writeTaskSecretStaging(frame);
+            send(socket, { kind: "task.secret.staging.ack", opId: frame.opId, stagingId: frame.stagingId, ok: true });
+          } catch {
+            send(socket, { kind: "task.secret.staging.ack", opId: frame.opId, stagingId: frame.stagingId, ok: false });
+          }
+        });
+        break;
+      }
       case "env.staging.put": {
         // Only the write-only sign-in box owns immutable staging paths. An
         // owned runner or task sidecar must never accept plaintext here.
@@ -4502,6 +4550,8 @@ async function dispatchCommand(
         expectString(args, 0),
         expectString(args, 1),
         expectString(args, 2),
+        args[3] as DeliveryOrigin | undefined,
+        args[4] as AssignmentDelivery | undefined,
       );
     case "channelResolvePermission":
       return hostCommands.channelResolvePermission(
@@ -4515,11 +4565,23 @@ async function dispatchCommand(
       return hostCommands.cloneRepo(ctx, expectCloneRepoInput(args, 0));
     case "taskDiff":
       return hostCommands.taskDiff(ctx, expectTaskDiffInput(args, 0));
+    case "taskProjectPrepare":
+      return hostCommands.taskProjectPrepare(ctx, expectTaskProjectPrepareInput(args, 0));
+    case "taskProjectActivate":
+      return hostCommands.taskProjectActivate(ctx, expectTaskProjectActivateInput(args, 0));
+    case "taskProjectCompensate":
+      return hostCommands.taskProjectCompensate(ctx, expectTaskProjectFence(args[0], "task project compensate input"));
+    case "taskProjectStatus":
+      return hostCommands.taskProjectStatus(ctx, expectTaskProjectStatusInput(args, 0));
     case "attachmentWrite":
       return hostCommands.attachmentWrite(
         ctx,
         expectAttachmentWriteInput(args, 0),
       );
+    case "workspaceFileRead": {
+      const input = expectRecord(args[0], "workspace file read input");
+      return hostCommands.workspaceFileRead(ctx, { taskId: expectStringValue(input.taskId, "taskId"), path: expectStringValue(input.path, "path"), maxBytes: expectNumberArg([input.maxBytes], 0) });
+    }
     case "attachmentRead":
       return hostCommands.attachmentRead(
         ctx,
@@ -4969,6 +5031,7 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
   ) {
     return frame;
   }
+  if (isTaskSecretStagingPut(frame)) return frame;
   if (isProjectEnvStagingPutFrame(frame)) return frame;
   // Sidecar replica authority has a separate durable store and apply lane.
   // Exact guards keep every attempt, cursor and immutable value reference;
@@ -5265,6 +5328,7 @@ function rejectFrameDuringShutdown(
       return true;
     case "env.var.remove":
     case "env.binding.set":
+    case "task.secret.staging.put":
     case "env.staging.put":
     case "env.reconcile.begin":
     case "env.reconciled":
@@ -5431,6 +5495,7 @@ function rejectCredentialFrameOffOwnCredentials(socket: WebSocket, frame: CloudT
       return true;
     case "env.var.remove":
     case "env.binding.set":
+    case "task.secret.staging.put":
     case "env.staging.put":
     case "env.reconcile.begin":
     case "env.reconciled":
@@ -5496,8 +5561,13 @@ const HOST_COMMAND_NAMES = {
   channelResolvePermission: true,
   cloneRepo: true,
   taskDiff: true,
+  taskProjectPrepare: true,
+  taskProjectActivate: true,
+  taskProjectCompensate: true,
+  taskProjectStatus: true,
   attachmentWrite: true,
   attachmentRead: true,
+  workspaceFileRead: true,
   filesOp: true,
   sidecarAssign: true,
   channelInterrupt: true,
@@ -5683,6 +5753,77 @@ function expectTaskDiffInput(args: unknown[], index: number): TaskDiffInput {
   };
 }
 
+function expectPositiveSafeInteger(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 1) {
+    throw new Error(`invalid command args: expected positive integer ${label}`);
+  }
+  return value as number;
+}
+
+function expectTaskProjectFence(value: unknown, label: string): TaskProjectOpFence {
+  const input = expectRecord(value, label);
+  return {
+    taskId: expectStringValue(input.taskId, "taskId"),
+    runEpoch: expectPositiveSafeInteger(input.runEpoch, "runEpoch"),
+    operationId: expectStringValue(input.operationId, "operationId"),
+    projectSetRevision: expectPositiveSafeInteger(input.projectSetRevision, "projectSetRevision"),
+  };
+}
+
+function expectTaskProjectPrepareInput(args: unknown[], index: number): TaskProjectPrepareInput {
+  const input = expectRecord(args[index], "task project prepare input");
+  const project = expectRecord(input.project, "task project");
+  return {
+    ...expectTaskProjectFence(input, "task project prepare input"),
+    branch: expectStringValue(input.branch, "branch"),
+    project: {
+      id: expectStringValue(project.id, "project.id"),
+      slug: expectStringValue(project.slug, "project.slug"),
+      repoUrl: expectStringValue(project.repoUrl, "project.repoUrl"),
+      ...(typeof project.toolVersions === "string" ? { toolVersions: project.toolVersions } : {}),
+    },
+  };
+}
+
+function expectTaskProjectActivateInput(args: unknown[], index: number): TaskProjectActivateInput {
+  const input = expectRecord(args[index], "task project activate input");
+  let grant: TaskProjectActivateInput["grant"] = null;
+  if (input.grant !== null) {
+    const row = expectRecord(input.grant, "task project grant");
+    grant = {
+      manifestRevision: expectPositiveSafeInteger(row.manifestRevision, "grant.manifestRevision"),
+      manifestDigest: expectStringValue(row.manifestDigest, "grant.manifestDigest"),
+      targetGeneration: expectPositiveSafeInteger(row.targetGeneration, "grant.targetGeneration"),
+    };
+  }
+  return {
+    ...expectTaskProjectFence(input, "task project activate input"),
+    project: expectTaskCommandProject(input.project),
+    previewEnv: expectStringRecord(input.previewEnv ?? {}, "previewEnv"),
+    grant,
+  };
+}
+
+function expectStringRecord(value: unknown, label: string): Record<string, string> {
+  const record = expectRecord(value, label);
+  const out: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`invalid command args: ${label} name ${key}`);
+    out[key] = expectStringValue(entry, `${label}.${key}`);
+  }
+  return out;
+}
+
+function expectTaskProjectStatusInput(args: unknown[], index: number): TaskProjectStatusInput {
+  const input = expectRecord(args[index], "task project status input");
+  return {
+    taskId: expectStringValue(input.taskId, "taskId"),
+    runEpoch: expectPositiveSafeInteger(input.runEpoch, "runEpoch"),
+    operationId: expectStringValue(input.operationId, "operationId"),
+    projectId: expectStringValue(input.projectId, "projectId"),
+  };
+}
+
 function expectAttachmentWriteInput(
   args: unknown[],
   index: number,
@@ -5768,6 +5909,7 @@ function expectChannelEnsureInput(
   // Both are optional for wire compatibility with older clouds.
   const mode = parseChannelMode(input.mode);
   if (mode !== undefined) out.mode = mode;
+  if (typeof input.leadRunId === "string") out.leadRunId = input.leadRunId;
   if (typeof input.secretaryAgentId === "string") {
     out.secretaryAgentId = input.secretaryAgentId;
   }