@runuai/host 0.9.167 → 0.9.168

package/lib/agent-cli.ts

@@ -1,3 +1,4 @@
+import { validateShareablePath, ENGINE_ACCOUNT_PATH_RULES } from "../src/workspace-path-policy";
 /**
  * In-container `uai` CLI materialisation (ADR-048).
  *
@@ -126,7 +127,7 @@ export async function writeAgentCli(
 ): Promise<boolean> {
   if (
     !apiUrl ||
-    (rosterPermissions(roster).length === 0 && !allowPermissionless)
+    (roster.length === 0 && !allowPermissionless)
   ) {
     return false;
   }
@@ -161,7 +162,7 @@ export async function writeAgentCliViaEnvironment(
 ): Promise<boolean> {
   if (
     !apiUrl ||
-    (rosterPermissions(roster).length === 0 && !allowPermissionless)
+    (roster.length === 0 && !allowPermissionless)
   ) {
     return false;
   }
@@ -199,6 +200,7 @@ export function agentCliEnv(
   ownerUserId: string | null,
   apiUrl: string | null,
   cliSecret: string | null,
+  leadRunId?: string | null,
 ): Record<string, string> {
   const runtimeAuthority = { ...AGENT_RUNTIME_AUTHORITY_ENV };
   const permissions = agent.permissions ?? [];
@@ -213,6 +215,7 @@ export function agentCliEnv(
         agentId: agent.id,
         // ADR-157 §3: binds the token to this agent, not merely its handle.
         ...(agent.tokenGeneration ? { generation: agent.tokenGeneration } : {}),
+        ...(leadRunId ? { leadRunId } : {}),
       },
       cliSecret,
     ),
@@ -227,9 +230,11 @@ export function agentCliEnv(
 
 export const CLI_SOURCE = `#!/usr/bin/env node
 // uai — in-task agent CLI (ADR-048). Talks to the cloud agent API as the task.
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep, basename } from "node:path";
 import { fileURLToPath } from "node:url";
+import { randomUUID, createHash } from "node:crypto";
 
 const here = dirname(fileURLToPath(import.meta.url));
 let cfg = {};
@@ -285,28 +290,529 @@ async function api(method, path, body) {
   return json;
 }
 function out(v) { console.log(typeof v === "string" ? v : JSON.stringify(v, null, 2)); }
+const NL = String.fromCharCode(10);
+function flagValue(v) { return typeof v === "string" && v !== "true" && v.length > 0; }
+// ADR-161 §3.2: setup fields read from files, so a brief or a .tool-versions
+// keeps its newlines and quotes without shell escaping.
+function readFlagFile(path) {
+  try { return path === "-" ? readFileSync(0, "utf8") : readFileSync(path, "utf8"); }
+  catch (error) { console.error("uai: cannot read " + path + ": " + error.message); process.exit(1); }
+}
+function projectSetupFields(flags) {
+  const fields = {};
+  if (flagValue(flags.slug)) fields.slug = flags.slug;
+  if (flagValue(flags["prompt-file"])) fields.defaultPrompt = readFlagFile(flags["prompt-file"]);
+  else if (flagValue(flags.prompt)) fields.defaultPrompt = flags.prompt;
+  if (flagValue(flags["previews-file"])) {
+    try { fields.previewPorts = JSON.parse(readFlagFile(flags["previews-file"])); }
+    catch { console.error("uai: --previews-file must hold a JSON array of preview declarations"); process.exit(1); }
+  }
+  if (flagValue(flags["tool-versions-file"])) fields.toolVersions = readFlagFile(flags["tool-versions-file"]);
+  return fields;
+}
+
+// ADR-161 §2: add a repository to the running task this agent is on. The add
+// is a durable operation; by default the CLI waits for its outcome.
+function opKey() { return "cli-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 12); }
+function opLine(op) {
+  if (op.state === "failed") return "could not add " + op.slug + ": " + (op.error ? op.error.code + " — " + op.error.message : "failed");
+  if (op.state === "ready" || op.state === "ready_with_warning") {
+    return "added " + op.slug + " at " + op.path + (op.warning ? " (warning: " + op.warning + ")" : "");
+  }
+  return "adding " + op.slug + " (" + op.state + "); check again with: uai task project status " + op.operationId;
+}
+async function waitForProjectOp(op) {
+  const deadline = Date.now() + 25 * 60 * 1000;
+  while (!op.done && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+    op = (await api("GET", "/api/agent/task/projects/operations/" + encodeURIComponent(op.operationId))).operation;
+  }
+  return op;
+}
+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));
+}
+
+// ADR-161 §1.3. UAI_FILES_ROOT and UAI_FILES_STATE_FILE exist so tests can
+// point at a temp dir; a task leaves them unset and uses the defaults.
+const FILES_CAP_COUNT = 500;
+const FILES_CAP_BYTES = 1024 * 1024 * 1024;
+const FILES_ROOT = process.env.UAI_FILES_ROOT || "/workspace/files";
+const FILES_STATE = process.env.UAI_FILES_STATE_FILE || "/workspace/.uai/files-state.json";
+
+function filesTarget(raw) {
+  if (raw === "org" || raw === "me") return { scope: raw, path: "" };
+  if (typeof raw === "string" && raw.startsWith("org/")) return { scope: "org", path: raw.slice(4) };
+  if (typeof raw === "string" && raw.startsWith("me/")) return { scope: "me", path: raw.slice(3) };
+  return null;
+}
+function filesQuery(scope, path, cursor) {
+  let q = "/api/agent/files?scope=" + encodeURIComponent(scope) + "&path=" + encodeURIComponent(path || "");
+  if (cursor) q += "&cursor=" + encodeURIComponent(cursor);
+  return q;
+}
+async function filesListFolder(scope, path, bounded) {
+  const entries = [];
+  let cursor = "";
+  let pages = 0;
+  do {
+    if (bounded && pages >= FILES_CAP_COUNT) {
+      console.error("uai: files get -r stops at 500 files");
+      process.exit(1);
+    }
+    pages += 1;
+    const page = await api("GET", filesQuery(scope, path, cursor));
+    for (const entry of page.entries || []) entries.push(entry);
+    cursor = page.cursor || "";
+  } while (cursor);
+  return entries;
+}
+function defaultFilesDest(scope, path) {
+  return FILES_ROOT + "/" + scope + (path ? "/" + path : "");
+}
+function filesRefuse(message) {
+  console.error("uai: " + message);
+  process.exit(1);
+}
+function legacyFilesMount(root) {
+  try {
+    lstatSync(join(dirname(root), ".uai", "files-mounted"));
+    return true;
+  } catch (err) {
+    if (err && err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+// Default destinations stay under FILES_ROOT. The directories are opened
+// with O_DIRECTORY|O_NOFOLLOW and held across the download; the temp file
+// is created and renamed relative to those descriptors. An explicit <dest>
+// uses prepareExplicitDest and is not contained.
+function closeFds(fds) {
+  for (const fd of fds) {
+    try { closeSync(fd); } catch (err) {}
+  }
+}
+function refuseHeld(fds, message) {
+  closeFds(fds);
+  filesRefuse(message);
+}
+function lstatChild(dirFd, name) {
+  try {
+    return lstatSync("/proc/self/fd/" + dirFd + "/" + name);
+  } catch (err) {
+    if (err && err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+function openDirAt(parentFd, name) {
+  const target = parentFd < 0 ? name : "/proc/self/fd/" + parentFd + "/" + name;
+  let fd = -1;
+  try {
+    fd = openSync(target, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  } catch (err) {
+    if (err && (err.code === "ELOOP" || err.code === "ENOTDIR" || err.code === "EPERM")) {
+      filesRefuse("files destination follows a symlink");
+    }
+    throw err;
+  }
+  const opened = fstatSync(fd);
+  const listed = lstatSync(target);
+  if (
+    listed.isSymbolicLink() ||
+    !listed.isDirectory() ||
+    opened.dev !== listed.dev ||
+    opened.ino !== listed.ino
+  ) {
+    closeSync(fd);
+    filesRefuse("files destination follows a symlink");
+  }
+  return fd;
+}
+function staysUnder(rootReal, fileReal) {
+  return fileReal === rootReal || fileReal.indexOf(rootReal + sep) === 0;
+}
+function openContainedDest(dest) {
+  const fds = [];
+  const root = resolve(FILES_ROOT);
+  let rootStat = null;
+  try {
+    rootStat = lstatSync(root);
+  } catch (err) {
+    if (!err || err.code !== "ENOENT") throw err;
+  }
+  if (rootStat && rootStat.isSymbolicLink()) filesRefuse("refusing a legacy shared-files mount");
+  if (legacyFilesMount(root)) filesRefuse("refusing a legacy shared-files mount");
+  const target = resolve(dest);
+  const rel = relative(root, target);
+  if (rel === "" || rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) {
+    filesRefuse("files destination must stay under /workspace/files");
+  }
+  if (!rootStat) {
+    const parent = dirname(root);
+    let parentStat = null;
+    try { parentStat = lstatSync(parent); } catch (err) {
+      if (!err || err.code !== "ENOENT") throw err;
+    }
+    if (!parentStat || parentStat.isSymbolicLink() || !parentStat.isDirectory()) {
+      filesRefuse("files destination follows a symlink");
+    }
+    mkdirSync(root);
+  } else if (!rootStat.isDirectory()) {
+    filesRefuse("files destination is not a directory");
+  }
+  const rootFd = openDirAt(-1, root);
+  fds.push(rootFd);
+  // The allowed root is the pathname at open time, not wherever the held
+  // directory descriptor points later. realOf(rootFd) follows a rename of
+  // /workspace/files itself, so both sides of the comparison would move and
+  // a download would land outside. Pin realpath once, before any await.
+  let rootReal = "";
+  try {
+    rootReal = realpathSync(root);
+  } catch (err) {
+    refuseHeld(fds, "files destination left /workspace/files");
+  }
+  const pinned = lstatSync(rootReal);
+  const openedRoot = fstatSync(rootFd);
+  if (
+    pinned.isSymbolicLink() ||
+    !pinned.isDirectory() ||
+    pinned.dev !== openedRoot.dev ||
+    pinned.ino !== openedRoot.ino
+  ) {
+    refuseHeld(fds, "files destination left /workspace/files");
+  }
+  const parts = rel.split(sep);
+  let dirFd = rootFd;
+  for (let i = 0; i < parts.length; i++) {
+    const name = parts[i];
+    if (!name || name === "." || name === "..") {
+      refuseHeld(fds, "files destination must stay under /workspace/files");
+    }
+    const last = i === parts.length - 1;
+    const st = lstatChild(dirFd, name);
+    if (st && st.isSymbolicLink()) refuseHeld(fds, "files destination follows a symlink");
+    if (last) {
+      if (st && !st.isFile()) refuseHeld(fds, "files destination is not a file");
+      return { rootFd: rootFd, dirFd: dirFd, name: name, fds: fds, rootReal: rootReal };
+    }
+    if (!st) {
+      try {
+        mkdirSync("/proc/self/fd/" + dirFd + "/" + name);
+      } catch (err) {
+        if (!err || err.code !== "EEXIST") {
+          closeFds(fds);
+          throw err;
+        }
+      }
+      const created = lstatChild(dirFd, name);
+      if (!created || created.isSymbolicLink()) refuseHeld(fds, "files destination follows a symlink");
+      if (!created.isDirectory()) refuseHeld(fds, "files destination is not a directory");
+    } else if (!st.isDirectory()) {
+      refuseHeld(fds, "files destination is not a directory");
+    }
+    try {
+      dirFd = openDirAt(dirFd, name);
+    } catch (err) {
+      closeFds(fds);
+      throw err;
+    }
+    fds.push(dirFd);
+  }
+  refuseHeld(fds, "files destination must stay under /workspace/files");
+}
+function prepareExplicitDest(dest) {
+  mkdirSync(dirname(dest), { recursive: true });
+  return dest;
+}
+let filesPartSeq = 0;
+function recordFileState(scope, path, etag) {
+  mkdirSync(dirname(FILES_STATE), { recursive: true });
+  const lock = FILES_STATE + ".lock";
+  let fd = -1;
+  const started = Date.now();
+  while (fd < 0) {
+    try {
+      fd = openSync(lock, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
+    } catch (err) {
+      if (!err || err.code !== "EEXIST") throw err;
+      if (Date.now() - started > 5000) throw new Error("files state is locked");
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+  }
+  try {
+    let state = {};
+    try { state = JSON.parse(readFileSync(FILES_STATE, "utf8")); } catch {}
+    if (!state || typeof state !== "object") state = {};
+    state[scope + "/" + path] = { etag: etag };
+    const tmp = FILES_STATE + ".tmp";
+    writeFileSync(tmp, JSON.stringify(state));
+    renameSync(tmp, FILES_STATE);
+  } finally {
+    closeSync(fd);
+    try { unlinkSync(lock); } catch {}
+  }
+}
+function procChild(dirFd, name) {
+  return "/proc/self/fd/" + dirFd + "/" + name;
+}
+function unlinkChild(dirFd, name) {
+  try { unlinkSync(procChild(dirFd, name)); } catch (unlinkErr) {}
+}
+function realOf(fd) {
+  return realpathSync("/proc/self/fd/" + fd);
+}
+function fileUnderRoot(rootReal, fd) {
+  try {
+    return staysUnder(rootReal, realOf(fd));
+  } catch (err) {
+    return false;
+  }
+}
+function refuseEscaped(dirFd, name, fd) {
+  if (fd >= 0) {
+    try { closeSync(fd); } catch (closeErr) {}
+  }
+  unlinkChild(dirFd, name);
+  filesRefuse("files destination left /workspace/files");
+}
+async function streamInto(fd, body, budget) {
+  const reader = body.getReader();
+  let accepted = 0;
+  while (true) {
+    const step = await reader.read();
+    if (step.done) break;
+    const buf = Buffer.from(step.value);
+    if (budget && accepted + buf.length > budget.remaining) {
+      try { await reader.cancel(); } catch (cancelErr) {}
+      const capErr = new Error("cap");
+      capErr.code = "FILES_CAP";
+      throw capErr;
+    }
+    writeSync(fd, buf);
+    accepted += buf.length;
+  }
+  return accepted;
+}
+function throwFilesCap(err) {
+  if (err && err.code === "FILES_CAP") {
+    console.error("uai: files get -r stops at 1 GB");
+    process.exit(1);
+  }
+  throw err;
+}
+// Explicit destinations are the caller's path. Default destinations are
+// created and renamed through the directory descriptors opened before the
+// link request, then checked to still sit under the files root.
+async function writePath(dest, res, budget) {
+  filesPartSeq += 1;
+  const tmp = dest + ".part-" + process.pid + "-" + filesPartSeq;
+  let fd = -1;
+  try {
+    fd = openSync(tmp, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW);
+    const accepted = await streamInto(fd, res.body, budget);
+    closeSync(fd);
+    fd = -1;
+    renameSync(tmp, dest);
+    if (budget) budget.remaining -= accepted;
+  } catch (err) {
+    if (fd >= 0) { try { closeSync(fd); } catch (closeErr) {} }
+    try { unlinkSync(tmp); } catch (unlinkErr) {}
+    throwFilesCap(err);
+  }
+}
+async function writeHeld(held, res, budget) {
+  const rootReal = held.rootReal;
+  if (typeof rootReal !== "string" || !rootReal || !staysUnder(rootReal, realOf(held.dirFd))) {
+    filesRefuse("files destination left /workspace/files");
+  }
+  const existing = lstatChild(held.dirFd, held.name);
+  if (existing && existing.isSymbolicLink()) filesRefuse("files destination follows a symlink");
+  if (existing && !existing.isFile()) filesRefuse("files destination is not a file");
+  filesPartSeq += 1;
+  const tmpName = ".part-" + process.pid + "-" + filesPartSeq;
+  const tmpPath = procChild(held.dirFd, tmpName);
+  const finalPath = procChild(held.dirFd, held.name);
+  let fd = -1;
+  try {
+    try {
+      fd = openSync(tmpPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW);
+    } catch (err) {
+      if (err && err.code === "ELOOP") filesRefuse("files destination follows a symlink");
+      throw err;
+    }
+    if (!fileUnderRoot(rootReal, fd)) refuseEscaped(held.dirFd, tmpName, fd);
+    const accepted = await streamInto(fd, res.body, budget);
+    if (!fileUnderRoot(rootReal, fd)) refuseEscaped(held.dirFd, tmpName, fd);
+    closeSync(fd);
+    fd = -1;
+    if (!staysUnder(rootReal, realOf(held.dirFd))) {
+      unlinkChild(held.dirFd, tmpName);
+      filesRefuse("files destination left /workspace/files");
+    }
+    renameSync(tmpPath, finalPath);
+    const placed = lstatChild(held.dirFd, held.name);
+    let placedReal = "";
+    try { placedReal = realpathSync(finalPath); } catch (err) { placedReal = ""; }
+    if (!placed || placed.isSymbolicLink() || !placed.isFile() || !staysUnder(rootReal, placedReal)) {
+      unlinkChild(held.dirFd, held.name);
+      filesRefuse("files destination left /workspace/files");
+    }
+    if (budget) budget.remaining -= accepted;
+  } catch (err) {
+    if (fd >= 0) { try { closeSync(fd); } catch (closeErr) {} }
+    unlinkChild(held.dirFd, tmpName);
+    throwFilesCap(err);
+  }
+}
+async function downloadFile(scope, path, dest, contained, budget) {
+  const held = contained ? openContainedDest(dest) : null;
+  try {
+    if (!contained) prepareExplicitDest(dest);
+    const link = await api(
+      "GET",
+      "/api/agent/files/link?scope=" + encodeURIComponent(scope) + "&path=" + encodeURIComponent(path),
+    );
+    let res;
+    try {
+      res = await fetch(link.url);
+    } catch {
+      console.error("uai: download failed");
+      process.exit(1);
+    }
+    if (!res.ok) {
+      console.error("uai: download failed (" + res.status + ")");
+      process.exit(1);
+    }
+    const etag = res.headers.get("etag");
+    if (!etag || (link.etag && etag !== link.etag)) {
+      if (res.body && res.body.cancel) {
+        try { await res.body.cancel(); } catch (cancelErr) {}
+      }
+      console.error(etag ? "uai: download etag does not match the inspected file" : "uai: download did not name an etag");
+      process.exit(1);
+    }
+    if (!res.body || !res.body.getReader) {
+      console.error("uai: download failed");
+      process.exit(1);
+    }
+    if (held) await writeHeld(held, res, budget);
+    else await writePath(dest, res, budget);
+    recordFileState(scope, path, etag);
+  } finally {
+    if (held) closeFds(held.fds);
+  }
+}
+
+// Explicit '-' only: omitted argv text never blocks waiting for a terminal.
+// Existing cloud schemas enforce the same instruction/prompt length limits.
+function stdinText(label) {
+  if (process.stdin.isTTY) {
+    console.error("uai: " + label + " stdin is a terminal; use a pipe or a quoted heredoc with - <<'EOF' (see uai --help)");
+    process.exit(1);
+  }
+  const text = readFileSync(0, "utf8").trim();
+  if (!text) { console.error("uai: " + label + " stdin is empty"); process.exit(1); }
+  return text;
+}
 
 const argv = process.argv.slice(2);
 const [group, action, ...rest] = argv;
 const { flags, rest: pos } = parseFlags(rest);
 
+const validateShareablePath = ${validateShareablePath.toString()};
+const assertShareablePath = (path) => validateShareablePath(path, ${JSON.stringify(ENGINE_ACCOUNT_PATH_RULES)});
 async function main() {
+  if (group === "secret") {
+    if (action !== "request" || pos.length !== 1 || !flags.why || Object.keys(flags).some(key => !["why", "proxy-domain", "no-wait"].includes(key))) { console.error('uai: secret request NAME --why "reason" [--proxy-domain host]… [--no-wait]'); process.exit(1); }
+    // Repeated domains retain order from argv; the generic flag parser intentionally keeps one value.
+    const domains = [];
+    for (let i = 0; i < rest.length; i++) if (rest[i] === "--proxy-domain" && rest[i + 1]) domains.push(rest[++i]);
+    const created = await api("POST", "/api/agent/secrets/requests", { name: pos[0], why: flags.why, domains });
+    let request = created.request;
+    out({ request });
+    if (flags["no-wait"] === "true") return;
+    while (request.status === "pending") {
+      await new Promise(resolve => setTimeout(resolve, 2000));
+      request = (await api("GET", "/api/agent/secrets/requests/" + encodeURIComponent(request.id))).request;
+    }
+    out({ request });
+    if (request.status !== "provided") process.exit(1);
+    return;
+  }
+  if (group === "artifacts") {
+    const rows = (await api("GET", "/api/agent/artifacts")).artifacts || [];
+    out(rows.length ? rows.map((a) => a.id + "  " + a.name + " (" + a.size + " bytes) " + API_URL + a.open).join("\\n") : "no shared files");
+    return;
+  }
+  if (group === "share") {
+    const parsed = parseFlags([action, ...rest].filter(Boolean));
+    if (parsed.rest.length !== 1 || Object.keys(parsed.flags).some((k) => k !== "title")) throw new Error("share <path> [--title <text>]");
+    const requestedPath = isAbsolute(parsed.rest[0]) ? parsed.rest[0] : process.cwd() + "/" + parsed.rest[0];
+    const lexical = assertShareablePath(requestedPath);
+    const sourcePath = assertShareablePath(await realpath(lexical));
+    const file = await open(sourcePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const stat = await file.stat();
+      if (!stat.isFile() || stat.size > 100 * 1024 * 1024) throw new Error("share needs a regular file of at most 100 MiB");
+      const hash = createHash("sha256");
+      for await (const chunk of file.createReadStream({ autoClose: false })) hash.update(chunk);
+      const created = await api("POST", "/api/agent/artifacts", { name: basename(sourcePath), size: stat.size, sha256: hash.digest("hex"), sourcePath, requestedPath, title: parsed.flags.title });
+      const uploaded = await fetch(created.upload.url, { method: "PUT", headers: created.upload.headers, body: file.createReadStream({ start: 0, autoClose: false }), duplex: "half" });
+      if (!uploaded.ok) throw new Error("staging upload refused (" + uploaded.status + "); retry share to make a new receipt");
+      let done;
+      for (let attempt = 0; attempt < 30; attempt++) {
+        done = await api("POST", "/api/agent/artifacts/" + encodeURIComponent(created.artifact.id) + "/complete");
+        if (done.result !== "pending") break;
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+      if (done?.result !== "published" || done.artifact.state !== "ready") throw new Error("artifact " + created.artifact.id + " is " + (done?.result || "recovering") + "; check uai artifacts shortly");
+      out(done.artifact.id + "  " + API_URL + done.artifact.open);
+    } finally { await file.close(); }
+    return;
+  }
   if (group === "dispatch") {
     const args = [action, ...rest].filter((value) => typeof value === "string");
     const recipientArgs = [];
     while (args.length && /^@[A-Za-z0-9_-]+$/.test(args[0])) {
       recipientArgs.push(args.shift().slice(1));
     }
-    const instruction = args.join(" ").trim();
-    if (!recipientArgs.length || !instruction) {
-      console.error('uai: dispatch needs one or more @agent ids and a quoted instruction');
+    if (!recipientArgs.length) {
+      console.error('uai: dispatch needs one or more @agent ids and a quoted instruction (or - for stdin)');
+      process.exit(1);
+    }
+    const tags = {};
+    while (args[0] && ["--kind", "--size", "--pr", "--request-id"].includes(args[0])) {
+      const key = args.shift().slice(2);
+      const value = args.shift();
+      if (!value || value === "-" || value.startsWith("--")) {
+        console.error("uai: dispatch --" + key + " needs a value"); process.exit(1);
+      }
+      tags[key === "request-id" ? "requestId" : key] = value;
+    }
+    if (tags.kind && !["build", "fix", "review", "research", "design", "docs", "ops"].includes(tags.kind)) {
+      console.error("uai: dispatch --kind must be build, fix, review, research, design, docs or ops"); process.exit(1);
+    }
+    if (tags.size && !["s", "m", "l"].includes(tags.size)) {
+      console.error("uai: dispatch --size must be s, m or l"); process.exit(1);
+    }
+    const instruction = args.length === 1 && args[0] === "-" ? stdinText("dispatch") : args.join(" ").trim();
+    if (!instruction) {
+      console.error('uai: dispatch needs one or more @agent ids and a quoted instruction (or - for stdin)');
       process.exit(1);
     }
     const result = await api("POST", "/api/agent/dispatch", {
       to: recipientArgs,
       instruction,
+      requestId: tags.requestId || randomUUID(),
+      ...tags,
     });
-    out("dispatched to " + result.recipients.map((id) => "@" + id).join(", "));
+    if (result.recipients.length) out("dispatched to " + result.recipients.map((id) => "@" + id).join(", "));
+    if (result.pendingRecipients && result.pendingRecipients.length) out("pending/in flight: " + result.pendingRecipients.map((id) => "@" + id).join(", "));
+    if (result.canceledRecipients && result.canceledRecipients.length) out("canceled: " + result.canceledRecipients.map((id) => "@" + id).join(", "));
     if (Array.isArray(result.failedRecipients) && result.failedRecipients.length) {
       console.error(
         "uai: could not wake " +
@@ -315,11 +821,29 @@ async function main() {
     }
     return;
   }
+  if (group === "review" && action === "report") {
+    const counts = ["must", "should", "nits"];
+    if (!flags.pr || !/^[0-9a-f]{40}$/.test(flags.head || "") || !["approve", "changes"].includes(flags.verdict) ||
+        counts.some(k => !/^[0-9]+$/.test(flags[k] || "") || Number(flags[k]) > 1000) ||
+        (flags.revision && !/^[0-9]+$/.test(flags.revision))) {
+      console.error("uai: review report --pr <number|URL> --head <full-sha> --must <0..1000> --should <0..1000> --nits <0..1000> --verdict approve|changes [--summary text] [--assignment id] [--revision n]"); process.exit(1);
+    }
+    out(await api("POST", "/api/agent/review/report", { pr: flags.pr, head: flags.head,
+      must: Number(flags.must), should: Number(flags.should), nits: Number(flags.nits), verdict: flags.verdict,
+      summary: flags.summary, assignmentId: flags.assignment, expectedRevision: Number(flags.revision || 0) })); return;
+  }
   if (group === "crew") {
     // ADR-157: the task's built-in Astronaut (the @astronaut Uai builds, never a
     // persona) changes its own crew. One agent per call, always with a --why.
     const handleOf = (v) => (typeof v === "string" && v.startsWith("@") ? v.slice(1) : v);
     const launch = (a) => a.kind + (a.model ? "/" + a.model : "") + (a.effort ? "/" + a.effort : "");
+    if (action === "outcome") {
+      if (!pos[0] || !["accepted", "reworked", "failed"].includes(pos[1]) || (flags.revision && !/^[0-9]+$/.test(flags.revision))) {
+        console.error("uai: crew outcome @agent accepted|reworked|failed [--assignment id] [--note text] [--revision n]"); process.exit(1);
+      }
+      out(await api("POST", "/api/agent/crew-outcome", { recipient: handleOf(pos[0]), outcome: pos[1],
+        assignmentId: flags.assignment, note: flags.note, expectedRevision: Number(flags.revision || 0) })); return;
+    }
     if (action === "list") { out(await api("GET", "/api/agent/crew")); return; }
     if (action === "status") { out(await api("GET", "/api/agent/crew-status")); return; }
     if (action === "store") { out(await api("GET", "/api/agent/crew-store")); return; }
@@ -393,6 +917,88 @@ async function main() {
     console.error("uai: crew commands are list, status, store, suggest, add, model and remove (Astronaut only)");
     process.exit(1);
   }
+  if (group === "files") {
+    const args = rest.filter((value) => typeof value === "string");
+    const recursive = args.indexOf("-r") !== -1;
+    const positional = args.filter((value) => value !== "-r");
+    if (action === "ls") {
+      if (positional.length > 1) {
+        console.error("uai: files ls [org|me[/prefix]]");
+        process.exit(1);
+      }
+      const target = filesTarget(positional[0] || "org");
+      if (!target) {
+        console.error("uai: files ls [org|me[/prefix]]");
+        process.exit(1);
+      }
+      out({ entries: await filesListFolder(target.scope, target.path) });
+      return;
+    }
+    if (action === "get") {
+      if (!positional.length || positional.length > 2) {
+        console.error("uai: files get <org|me>/<path> [<dest>] [-r]");
+        process.exit(1);
+      }
+      const target = filesTarget(positional[0]);
+      if (!target) {
+        console.error("uai: files get <org|me>/<path> [<dest>] [-r]");
+        process.exit(1);
+      }
+      if (!recursive) {
+        if (!target.path) {
+          console.error("uai: files get needs a file path (or -r for a folder)");
+          process.exit(1);
+        }
+        const dest = positional[1] || defaultFilesDest(target.scope, target.path);
+        await downloadFile(target.scope, target.path, dest, !positional[1], null);
+        out(dest);
+        return;
+      }
+      const root = target.path;
+      const pending = [root];
+      const files = [];
+      let bytes = 0;
+      let folders = 0;
+      while (pending.length) {
+        if (folders >= FILES_CAP_COUNT) {
+          console.error("uai: files get -r stops at 500 files");
+          process.exit(1);
+        }
+        folders += 1;
+        const dir = pending.shift();
+        const entries = await filesListFolder(target.scope, dir, true);
+        for (const entry of entries) {
+          const child = dir ? dir + "/" + entry.name : entry.name;
+          if (entry.dir) {
+            pending.push(child);
+            continue;
+          }
+          const size = entry.size || 0;
+          if (files.length >= FILES_CAP_COUNT) {
+            console.error("uai: files get -r stops at 500 files");
+            process.exit(1);
+          }
+          if (bytes + size > FILES_CAP_BYTES) {
+            console.error("uai: files get -r stops at 1 GB");
+            process.exit(1);
+          }
+          bytes += size;
+          files.push(child);
+        }
+      }
+      const budget = { remaining: FILES_CAP_BYTES };
+      const explicitRoot = positional[1] ? String(positional[1]).replace(/\\/+$/, "") : "";
+      for (const file of files) {
+        const rel = root && file.indexOf(root + "/") === 0 ? file.slice(root.length + 1) : file;
+        const dest = explicitRoot ? explicitRoot + "/" + rel : defaultFilesDest(target.scope, file);
+        await downloadFile(target.scope, file, dest, !explicitRoot, budget);
+      }
+      out({ files: files.length, dest: positional[1] || defaultFilesDest(target.scope, root) });
+      return;
+    }
+    console.error("uai: files commands are ls and get");
+    process.exit(1);
+  }
   const key = group + " " + (action || "");
   switch (key) {
     case "projects list": out((await api("GET", "/api/agent/projects")).projects); break;
@@ -438,23 +1044,79 @@ async function main() {
       break;
     }
     case "task create": {
-      out((await api("POST", "/api/agent/tasks", {
+      const prompt = flags.prompt === "-" ? stdinText("task create --prompt -") : flags.prompt;
+      let astronaut;
+      if (flags.astronaut) {
+        const parts = String(flags.astronaut).split("/");
+        if (parts.length < 2 || parts.some((part) => !part) || flags.astronaut === "true") {
+          console.error("uai: --astronaut needs engine/model[/effort]"); process.exit(1);
+        }
+        const kind = parts.shift();
+        const effort = parts.length > 1 ? parts.pop() : undefined;
+        const model = parts.join("/");
+        astronaut = { kind, ...(model !== "default" ? { model } : {}), ...(effort && effort !== "default" ? { effort } : {}) };
+      }
+      if (flags.start && flags.start !== "true") {
+        console.error("uai: --start is a flag; it takes no value"); process.exit(1);
+      }
+      if (flags.start && (!flags["request-id"] || flags["request-id"] === "true")) {
+        console.error("uai: --start requires --request-id <logical-run-id>; reuse it after a timeout"); process.exit(1);
+      }
+      const created = (await api("POST", "/api/agent/tasks", {
         name: flags.name,
-        prompt: flags.prompt,
+        prompt,
         projects: flags.projects ? String(flags.projects).split(",").map((s) => s.trim()).filter(Boolean) : [],
         team: flags.team || null,
         agents: flags.agents ? String(flags.agents).split(",").map((s) => s.trim()).filter(Boolean) : [],
         parent: flags.parent || null,
-      })).task);
+        start: flags.start === "true",
+        ...(astronaut ? { astronaut } : {}),
+        requestId: flags["request-id"] || randomUUID(),
+      })).task;
+      if (flags.start && (!created || typeof created.id !== "string" || !created.id || !["queued", "starting", "running"].includes(created.status))) {
+        console.error("uai: the cloud did not start the child" + (created?.id ? " " + created.id : "") + "; it may need updating. Reuse --request-id when retrying."); process.exit(1);
+      }
+      out(created);
+      break;
+    }
+    case "task watch":
+    case "task usage": {
+      if (pos.length !== 1) { console.error("uai: task " + action + " needs a child task id"); process.exit(1); }
+      const query = new URLSearchParams();
+      if (action === "watch") {
+        if (flags.after) query.set("after", String(flags.after));
+        if (flags.limit) query.set("limit", String(flags.limit));
+      }
+      out(await api("GET", "/api/agent/tasks/" + encodeURIComponent(pos[0]) + "/" + action + (query.size ? "?" + query.toString() : "")));
+      break;
+    }
+    case "task send": {
+      // The text is prose, not CLI flags. Preserve literal --options in it.
+      const [childId, ...words] = rest;
+      const text = words.join(" ").trim();
+      if (!childId || !text) { console.error("uai: task send needs a child task id and text"); process.exit(1); }
+      out(await api("POST", "/api/agent/tasks/" + encodeURIComponent(childId) + "/send", { text }));
+      break;
+    }
+    case "task answer": {
+      const [childId, cardId, ...words] = rest;
+      const option = words.join(" ").trim();
+      if (!childId || !cardId || !option) { console.error("uai: task answer needs a child task id, card id and option text"); process.exit(1); }
+      out(await api("POST", "/api/agent/tasks/" + encodeURIComponent(childId) + "/answer", { cardId, option }));
       break;
     }
     case "task close": {
-      const allowed = new Set(["status", "reason"]);
+      const allowed = new Set(["status", "reason", "child"]);
       const unknown = Object.keys(flags).filter((flag) => !allowed.has(flag));
-      if (pos.length || unknown.length) {
-        console.error("uai: task close accepts only --status and --reason");
+      const childMode = Object.prototype.hasOwnProperty.call(flags, "child");
+      if ((childMode && (flags.child === "true" || !String(flags.child).trim())) || (pos.length === 1 && !String(pos[0]).trim())) {
+        console.error("uai: --child requires a child task id"); process.exit(1);
+      }
+      if (pos.length > 1 || unknown.length || (childMode && pos.length)) {
+        console.error("uai: task close accepts --child <childId>, --status and --reason");
         process.exit(1);
       }
+      const childId = childMode ? flags.child : pos[0];
       const status = flags.status;
       if (status !== "finished" && status !== "canceled") {
         console.error("uai: task close needs --status finished|canceled");
@@ -464,7 +1126,8 @@ async function main() {
         console.error("uai: --reason needs text (quote multiword reasons)");
         process.exit(1);
       }
-      const closed = await api("POST", "/api/agent/tasks/close", {
+      const path = childId ? "/api/agent/tasks/" + encodeURIComponent(childId) + "/close" : "/api/agent/tasks/close";
+      const closed = await api("POST", path, {
         status,
         ...(flags.reason ? { reason: String(flags.reason) } : {}),
       });
@@ -538,13 +1201,89 @@ async function main() {
       if (!r.enabled && r.public) console.error("uai: it's public but off — it serves nothing until: uai preview enable " + r.name);
       break;
     }
+    case "project list": {
+      const projects = (await api("GET", "/api/agent/projects")).projects || [];
+      out(projects.length ? projects.map((p) => p.id + "  " + p.slug + "  " + p.name).join(NL) : "no repositories");
+      break;
+    }
+    case "project show": {
+      if (!pos[0]) { console.error("uai: project show <id|slug>"); process.exit(1); }
+      out((await api("GET", "/api/agent/projects/" + encodeURIComponent(pos[0]))).project);
+      break;
+    }
     case "project create": {
+      const attach = rest.includes("--attach");
       const name = flags.name || pos.join(" ");
-      if (!name || !flags.repo) { console.error("uai: project create --name <n> --repo <git-url> [--prompt <p>]"); process.exit(1); }
-      const p = (await api("POST", "/api/agent/projects", { name, repoUrl: flags.repo, defaultPrompt: flags.prompt || undefined })).project;
+      if (!name || !flags.repo || flags.repo === "true") { console.error("uai: project create --name <n> --repo <git-url> [--slug <s>] [--prompt <p> | --prompt-file <f>] [--previews-file <f>] [--tool-versions-file <f>] [--attach]"); process.exit(1); }
+      const body = { name, repoUrl: flags.repo, ...projectSetupFields(flags) };
+      const p = (await api("POST", "/api/agent/projects", body)).project;
       out("created project " + p.slug + " (" + p.id + ")");
+      if (attach) await addProjectToTask(p.id, true);
+      break;
+    }
+    case "project update": {
+      if (!pos[0]) { console.error("uai: project update <id|slug> [--name <n>] [--slug <s>] [--repo <url>] [--prompt <p> | --prompt-file <f>] [--previews-file <f>] [--tool-versions-file <f>]"); process.exit(1); }
+      const body = { ...(flagValue(flags.name) ? { name: flags.name } : {}), ...(flagValue(flags.repo) ? { repoUrl: flags.repo } : {}), ...projectSetupFields(flags) };
+      if (Object.keys(body).length === 0) { console.error("uai: project update needs at least one field"); process.exit(1); }
+      const r = await api("PATCH", "/api/agent/projects/" + encodeURIComponent(pos[0]), body);
+      const proposed = r.proposed || [];
+      out("updated " + r.project.slug + " (applies to the next task)");
+      for (const pr of proposed) out("proposed " + pr.field + " (proposal " + pr.id + "): it changes what later tasks clone or read, so a member must approve it in the repository's Settings.");
+      break;
+    }
+    case "project propose-extra": {
+      if (!pos[0] || !flagValue(flags["extra-file"])) { console.error("uai: project propose-extra <id|slug> --extra-file <file>"); process.exit(1); }
+      const r = await api("POST", "/api/agent/projects/" + encodeURIComponent(pos[0]) + "/extra-proposals", { extra: readFlagFile(flags["extra-file"]) });
+      out("proposed Dockerfile additions (proposal " + r.proposal.id + "). They run as root at image build, so a member must approve them in the repository's Settings before any task uses them.");
       break;
     }
+    case "project env": {
+      const sub = pos[0], project = pos[1], name = pos[2];
+      const base = "/api/agent/projects/" + encodeURIComponent(project || "") + "/env";
+      if (!project || (["add", "remove", "propose-proxy"].includes(sub) && !name)) {
+        console.error("uai: project env list|observed <id> | add <id> NAME --label <l> [--secret] | remove <id> NAME | propose-proxy <id> NAME --domain <d>[,<d>…] [--placeholder-prefix <p> --placeholder-length <n>]");
+        process.exit(1);
+      }
+      if (sub === "list") {
+        const keys = (await api("GET", base + "/keys")).keys || [];
+        out(keys.length ? keys.map((k) => k.key + (k.secret ? " (secret)" : "") + "  " + k.label).join(NL) : "no env keys declared");
+      } else if (sub === "observed") {
+        out((await api("GET", base + "/declarations")).latest);
+      } else if (sub === "add") {
+        const label = flagValue(flags.label) ? flags.label : undefined;
+        const r = await api("POST", base + "/keys", { key: name, ...(label ? { label } : {}), ...(rest.includes("--secret") ? { secret: true } : {}) });
+        out("declared " + r.key + ". It has no value: a member saves its value in the repository's Settings.");
+      } else if (sub === "remove") {
+        const r = await api("DELETE", base + "/keys", { key: name });
+        out("removed the declaration of " + r.key + ". No value was touched.");
+      } else if (sub === "propose-proxy") {
+        if (!flagValue(flags.domain)) { console.error("uai: project env propose-proxy <id> NAME --domain <d>[,<d>…]"); process.exit(1); }
+        const prefix = flags["placeholder-prefix"], length = flags["placeholder-length"];
+        if ((prefix === undefined) !== (length === undefined)) { console.error("uai: --placeholder-prefix and --placeholder-length go together"); process.exit(1); }
+        const placeholder = prefix === undefined ? null : { prefix: prefix === "true" ? "" : prefix, totalLength: Number(length) };
+        const domains = String(flags.domain).split(",").map((d) => d.trim()).filter(Boolean);
+        const r = await api("POST", base + "/proxy-proposals", { key: name, domains, placeholder });
+        out("proposed sending " + name + " only to " + r.proposal.domains.join(", ") + " (proposal " + r.proposal.id + "). A member must confirm it in the repository's Settings before the proxy uses it.");
+      } else {
+        console.error("uai: project env commands are list, add, remove, propose-proxy and observed");
+        process.exit(1);
+      }
+      break;
+    }
+    case "task project": {
+      const words = rest.filter((word) => word !== "--no-wait");
+      const sub = words[0];
+      if (sub === "add" && words.length === 2 && !words[1].startsWith("--")) {
+        await addProjectToTask(words[1], !rest.includes("--no-wait"));
+        break;
+      }
+      if (sub === "status" && words.length === 2) {
+        out(opLine((await api("GET", "/api/agent/task/projects/operations/" + encodeURIComponent(words[1]))).operation));
+        break;
+      }
+      console.error("uai: task project add <projectId|slug> [--no-wait]  |  task project status <operationId>");
+      process.exit(1);
+    }
     case "task search": {
       const q = pos.join(" ") || flags.q || "";
       if (!q) { console.error("uai: task search <query>"); process.exit(1); }
@@ -574,11 +1313,21 @@ async function main() {
     default:
       console.error([
         "uai — agent CLI. Commands:",
+        '  uai share <path> [--title "text"]   (share an immutable file with people; Files plan, workspace quota)',
+        '  uai secret request NAME --why "reason" [--proxy-domain host]… [--no-wait]',
+        "      Never paste secrets into chat. A person supplies them through the private dialog.",
+        "  uai artifacts",
         "  uai projects list",
+        "  uai files ls [org|me[/prefix]]     (one folder: names, sizes, mtimes, etags; defaults to org)",
+        "  uai files get <org|me>/<path> [<dest>]   (download; default /workspace/files/<org|me>/<path>; -r is a folder, capped at 500 files / 1 GB)",
         "  uai people list",
         "  uai task list",
-        "  uai task create --name <n> --prompt <p> [--projects id,id] [--team id] [--agents handle,handle]",
-        '  uai task close --status finished|canceled [--reason "final report"]',
+        "  uai task create --name <n> --prompt <text|-> [--projects id,id] [--team id] [--agents handle,handle] [--astronaut engine/model/effort] [--start --request-id <logical-run-id>]",
+        "  uai task watch <childId> [--after <cursor>] [--limit N]",
+        "  uai task usage <childId>",
+        '  uai task send <childId> "text"',
+        '  uai task answer <childId> <cardId> "option text"',
+        '  uai task close [--child <childId>] --status finished|canceled [--reason "final report"]',
         "  uai memory search <query> [--as handle] [--limit N|all]",
         "  uai memory save <text> [--project id] [--tags a,b]",
         "  uai memory delete <id>",
@@ -587,14 +1336,33 @@ async function main() {
         "  uai todo edit <#id> <text>",
         "  uai todo remove <#id>",
         "  uai todo claim|done|reopen|unclaim <#id>",
+        "  uai review report --pr <number|URL> --head <full-sha> --must <n> --should <n> --nits <n> --verdict approve|changes [--summary text] [--assignment id] [--revision n]",
+        "  uai crew outcome @agent accepted|reworked|failed [--note text] [--assignment id] [--revision n]",
+        "      Review reports require an authorized exact-head assignment. Outcomes are Secretary assessments, never human acceptance.",
         "  uai preview add <name> <containerPort>",
         "  uai preview enable|disable <name>      (turn it on; prints its URL)",
         "  uai preview public|private <name>      (public: a link anyone can open)",
-        "  uai project create --name <n> --repo <git-url> [--prompt <p>]",
+        "  uai project list | show <id|slug>",
+        "  uai project create --name <n> --repo <git-url> [--slug <s>] [--prompt <p> | --prompt-file <f>] [--previews-file <f>] [--tool-versions-file <f>] [--attach]   (--attach: also add it to this task)",
+        "  uai project update <id|slug> [--name <n>] [--slug <s>] [--repo <url>] [--prompt <p> | --prompt-file <f>] [--previews-file <f>] [--tool-versions-file <f>]   (applies to the next task; --repo and the brief are proposals unless you created the repository in this task)",
+        "  uai project propose-extra <id|slug> --extra-file <f>   (Dockerfile additions; a member approves them)",
+        "  uai project env list|observed <id|slug>",
+        "  uai project env add <id|slug> NAME [--label <l>] [--secret]   (declares a key; values are a member's)",
+        "  uai project env remove <id|slug> NAME   (drops a declaration with no value; never deletes a value; when the workspace allows it)",
+        "  uai project env propose-proxy <id|slug> NAME --domain <d>[,<d>…] [--placeholder-prefix <p> --placeholder-length <n>]   (a member confirms)",
+        "  uai task project add <projectId|slug> [--no-wait]   (clone a repository into this running task; waits until ready)",
+        "  uai task project status <operationId>",
         "  uai task search <query>            (your own past tasks)",
         "  uai task history                   (list your past tasks)",
         "  uai task read <taskId>             (full chat of a past task you were on)",
-        '  uai dispatch @agent [@agent…] "instruction"   (Secretary only)',
+        '  uai dispatch @agent [@agent…] [--kind build|fix|review|research|design|docs|ops] [--size s|m|l] [--pr URL|number] [--request-id key] <instruction|->   (Secretary only)',
+        '      Tags precede the instruction; --pr is a candidate link, not proof of contribution. Reuse --request-id to retry the same logical dispatch.',
+        "    Explicit - reads UTF-8 stdin, trimmed; terminal stdin and omitted text are refused.",
+        "    For multi-line text or shell syntax use a quoted heredoc (executes nothing):",
+        "      uai dispatch @agent - <<'EOF'",
+        "      Your literal instruction, including quotes and shell syntax.",
+        "      EOF",
+        "    uai task create --name <n> --prompt - reads stdin the same way.",
         "  uai crew list                      (Astronaut only: personas with summary, skills and permissions, engines, models, limits, roster)",
         "  uai crew status                    (Astronaut only: each agent's engine, model, account; account usage; credits)",
         "  uai crew store                     (Astronaut only: the Store's persona and skill templates, names and types only)",