@moondeck/station 0.0.0-stage → 1.0.0

package/lib/agent-cli.ts

@@ -0,0 +1,1507 @@
+import { TASK_PROJECT_ADD_WAIT_MS } from "../src/protocol";
+import { validateShareablePath, ENGINE_ACCOUNT_PATH_RULES } from "../src/workspace-path-policy";
+/**
+ * In-container `moondeck` CLI materialisation (ADR-048; Moondeck plan §5 row 7).
+ *
+ * At task-up the host writes two files into the task workspace (bind-mounted at
+ * /workspace, like skills — no docker cp/exec needed):
+ *   - `.moondeck/cli.mjs`      — the self-contained agent CLI (Node ESM, fetch-only).
+ *   - `.moondeck/moondeck.json` — shared, tokenless { apiUrl } config the CLI reads.
+ *
+ * A token is minted here per agent (host-side), carrying the task id, its owner
+ * user, that agent's identity, and only that agent's permissions; the cloud
+ * verifies it. Agents invoke the CLI as `moondeck <cmd>` (the task's
+ * `/usr/local/bin/moondeck` runs `node /workspace/.moondeck/cli.mjs`), as
+ * the system preamble says.
+ */
+import {
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+
+import { env, taskWorkspaceDir } from "./env";
+import {
+  PROJECT_ENV_EXEC_PATH,
+  RUNTIME_AUTHORITY_ENV,
+} from "./runtime-authority";
+import { signTaskToken } from "./task-token";
+import { assertSafeHostTaskId } from "./task-identity";
+import type { RosterAgent } from "./agents/types";
+import type { TaskEnvironmentAgentSessionSurface, TaskEnvironmentHandle } from "./task-environment/types";
+import { makeContainedDirectoriesSync, writeContainedFile } from "./task-environment/workspace-files";
+import { STATION_AGENT_CLI } from "../src/station-identity";
+import { isProxiableDomain } from "./secrets-proxy/hostname";
+
+/** Container path of the CLI — what the preamble tells agents to run. */
+export const CONTAINER_CLI_PATH = STATION_AGENT_CLI.cliPath;
+
+/**
+ * The `moondeck` command: scripts/agent/moondeck-cli.sh, byte for byte (a
+ * test checks). Containers get that file mounted at /usr/local/bin/moondeck
+ * (task-up.sh); a machine task gets these bytes at MACHINE_AGENT_COMMAND_PATH,
+ * on its agents' PATH (MACHINE_RUNTIME_AUTHORITY_ENV).
+ */
+export const MOONDECK_COMMAND_SOURCE = `#!/bin/sh
+# moondeck — this task's agent CLI (Moondeck plan §5 row 7). task-up.sh mounts
+# it read-only at /usr/local/bin/moondeck; lib/agent-cli.ts writes the same
+# bytes (MOONDECK_COMMAND_SOURCE) on task machines. There is no \`uai\` command.
+exec node ${STATION_AGENT_CLI.cliPath} "$@"
+`;
+export const MACHINE_AGENT_COMMAND_PATH = `/home/node/.local/bin/${STATION_AGENT_CLI.command}`;
+
+/**
+ * Whether this build may advertise AGENT_CLI_MOONDECK_PROTOCOL_FEATURE. The
+ * cloud reads that feature as "a station" for more than wording: it mints
+ * user-content previews on moondeckapp.com only for such hosts (#713), and
+ * those are safe only where no key is ever proxied there (#680's list). So a
+ * build whose never-proxy list lacks moondeckapp.com never claims it.
+ */
+export function stationAgentCliAdvertisable(): boolean {
+  return !isProxiableDomain("preview.moondeckapp.com");
+}
+
+/** Runtime/cache authority for every agent docker exec, including preserved
+ * pre-L4 containers whose Config.Env may still contain project-controlled
+ * PATH/asdf/Corepack/loader values. Callers merge engine-account credentials
+ * underneath this object so those credentials cannot replace host policy. */
+export const AGENT_RUNTIME_AUTHORITY_ENV = RUNTIME_AUTHORITY_ENV;
+
+/**
+ * One rollout-aware argv policy for every agent CLI. The wrapper is installed
+ * only in PR2+ environments; legacy baked tasks must launch exactly as before.
+ */
+export function agentCliArgv(
+  environment: Pick<TaskEnvironmentAgentSessionSurface, "descriptor">,
+  argv: readonly [string, ...string[]],
+): [string, ...string[]] {
+  return environment.descriptor.envMode === "loader"
+    ? [PROJECT_ENV_EXEC_PATH, ...argv]
+    : [...argv];
+}
+
+// The task's cli secret lives HOST-PRIVATE (never the container), so it survives
+// host restarts without a DB migration. The cloud re-sends it on each task-up.
+function taskSecretPath(taskId: string): string {
+  return resolve(env.dataDir, "task-secrets", taskId);
+}
+
+/** Persist the cloud-issued per-task cli secret (ADR-048). Best-effort. */
+export function storeTaskCliSecret(taskId: string, secret: string): void {
+  try {
+    mkdirSync(resolve(env.dataDir, "task-secrets"), { recursive: true });
+    writeFileSync(taskSecretPath(taskId), secret, { mode: 0o600 });
+  } catch {
+    // best-effort — the CLI is simply unavailable if we can't persist it
+  }
+}
+
+/** Read the per-task cli secret, or null if we don't have it. */
+export function loadTaskCliSecret(taskId: string): string | null {
+  try {
+    return readFileSync(taskSecretPath(taskId), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Orphan GC is an authority deletion, not best-effort housekeeping. */
+export function removeTaskCliSecretStrict(taskId: string): void {
+  assertSafeHostTaskId(taskId);
+  const path = taskSecretPath(taskId);
+  rmSync(path, { force: true });
+  try {
+    lstatSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  throw new Error("task CLI secret remains after removal");
+}
+
+/** The union used only to decide whether this task needs the shared CLI file. */
+export function rosterPermissions(roster: RosterAgent[]): string[] {
+  return Array.from(new Set(roster.flatMap((a) => a.permissions ?? [])));
+}
+
+/** Derive the cloud HTTPS API base from the host's cloud WSS url. */
+export function apiUrlFromCloudUrl(cloudUrl: string | undefined): string | null {
+  if (!cloudUrl) return null;
+  try {
+    const u = new URL(cloudUrl);
+    const proto = u.protocol === "wss:" ? "https:" : u.protocol === "ws:" ? "http:" : u.protocol;
+    return `${proto}//${u.host}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the CLI script + shared config (apiUrl only — NO token) into the task
+ * workspace. Each agent's OWN token is injected per-agent via its docker exec
+ * env (agentCliEnv), so no shared file ever holds a token. Best-effort +
+ * idempotent. No-op (false) if there's no api url, or if the roster has zero
+ * permissions and the task has no permissionless role action (Secretary
+ * dispatch). The latter is explicit rather than globally minting empty-power
+ * tokens for every task.
+ */
+export async function writeAgentCli(
+  taskId: string,
+  roster: RosterAgent[],
+  apiUrl: string | null,
+  allowPermissionless = false,
+): Promise<boolean> {
+  if (
+    !apiUrl ||
+    (roster.length === 0 && !allowPermissionless)
+  ) {
+    return false;
+  }
+  try {
+    // Into the task's own .moondeck, never through a link the task put there
+    // (#cb3j0z). The workspace root is the runner's own path; .moondeck,
+    // directly below it, is made if gone without following a link.
+    const workspace = taskWorkspaceDir(taskId);
+    mkdirSync(workspace, { recursive: true });
+    makeContainedDirectoriesSync(workspace, [STATION_AGENT_CLI.stateDir]);
+    await writeContainedFile(workspace, [STATION_AGENT_CLI.stateDir, STATION_AGENT_CLI.configFile], Buffer.from(`${JSON.stringify({ apiUrl }, null, 2)}\n`));
+    await writeContainedFile(workspace, [STATION_AGENT_CLI.stateDir, "cli.mjs"], Buffer.from(CLI_SOURCE), { mode: 0o755 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * ADR-121: the same CLI materialization, but through the environment's own
+ * transport — machine workspaces are not host-reachable via taskWorkspaceDir.
+ * Same no-token invariant: moondeck.json carries the apiUrl only.
+ */
+export async function writeAgentCliViaEnvironment(
+  environment: {
+    readonly descriptor: { workspacePath: string };
+    writeWorkspaceFile(path: string, bytes: Uint8Array): Promise<void>;
+    /** When the environment can run commands (a machine), the `moondeck`
+     *  command is installed through it too. */
+    exec?: TaskEnvironmentHandle<unknown>["exec"];
+  },
+  roster: RosterAgent[],
+  apiUrl: string | null,
+  allowPermissionless = false,
+): Promise<boolean> {
+  if (
+    !apiUrl ||
+    (roster.length === 0 && !allowPermissionless)
+  ) {
+    return false;
+  }
+  try {
+    const root = environment.descriptor.workspacePath;
+    await environment.writeWorkspaceFile(
+      `${root}/${STATION_AGENT_CLI.stateDir}/${STATION_AGENT_CLI.configFile}`,
+      Buffer.from(`${JSON.stringify({ apiUrl }, null, 2)}\n`),
+    );
+    await environment.writeWorkspaceFile(
+      `${root}/${STATION_AGENT_CLI.stateDir}/cli.mjs`,
+      Buffer.from(CLI_SOURCE),
+    );
+    if (environment.exec) {
+      // Atomic, as the agent user, into a directory on its PATH.
+      const installed = await environment.exec({
+        argv: [
+          "/bin/sh",
+          "-c",
+          'mkdir -p "$(dirname "$1")" && cat > "$1.tmp" && chmod 0755 "$1.tmp" && mv -f "$1.tmp" "$1"',
+          "moondeck-command",
+          MACHINE_AGENT_COMMAND_PATH,
+        ],
+        projectEnvProfile: "maintenance",
+        stdin: Buffer.from(MOONDECK_COMMAND_SOURCE),
+        timeoutMs: 30_000,
+        maxOutputBytes: 8_192,
+      });
+      if (installed.exitCode !== 0) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Per-agent env for the `docker exec` that spawns one agent (ADR-048): its OWN
+ * task token (carrying only ITS permissions) + the API url. Every agent gets
+ * one, permissions or not: it is the agent's identity — the Uai Managed
+ * Engine's gateway authenticates and bills by it (ADR-128), and the
+ * Secretary's dispatch is role-gated on it. Until 2026-10-20 an agent with no
+ * CLI permissions got none, so such a persona could not run on the managed
+ * engine at all. An empty-permission token cannot borrow anyone else's powers:
+ * every permissioned route refuses it, and the self-scoped ones
+ * (`requireAnyPersonaPermission`) do too. Empty only when the task has no
+ * owner, API url or CLI secret.
+ */
+export function agentCliEnv(
+  taskId: string,
+  agent: RosterAgent,
+  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 ?? [];
+  if (!ownerUserId || !apiUrl || !cliSecret) return runtimeAuthority;
+  return {
+    ...runtimeAuthority,
+    UAI_TASK_TOKEN: signTaskToken(
+      {
+        taskId,
+        userId: ownerUserId,
+        permissions,
+        agentId: agent.id,
+        // ADR-157 §3: binds the token to this agent, not merely its handle.
+        ...(agent.tokenGeneration ? { generation: agent.tokenGeneration } : {}),
+        ...(leadRunId ? { leadRunId } : {}),
+      },
+      cliSecret,
+    ),
+    UAI_API_URL: apiUrl,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The CLI itself — kept as a self-contained ESM string so the host writes ONE
+// file with no dependencies (Node 22 in the image provides global fetch).
+// ---------------------------------------------------------------------------
+
+export const CLI_SOURCE = `#!/usr/bin/env node
+// moondeck — in-task agent CLI (ADR-048). Talks to the cloud agent API as the task.
+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";
+import { spawnSync } from "node:child_process";
+
+const here = dirname(fileURLToPath(import.meta.url));
+let cfg = {};
+try { cfg = JSON.parse(readFileSync(join(here, "moondeck.json"), "utf8")); } catch {}
+// Per-agent token comes from the env (each agent's docker exec carries only its
+// own — ADR-048); apiUrl from env or the shared config file.
+const TOKEN = process.env.UAI_TASK_TOKEN || cfg.token;
+const API_URL = process.env.UAI_API_URL || cfg.apiUrl;
+if (!TOKEN || !API_URL) {
+  console.error("moondeck: not available for this agent — no permissions granted (or not inside a task).");
+  process.exit(1);
+}
+
+/** The task this agent's token names: its unsigned body, read for display
+ *  only; the cloud verifies the token and resolves the id itself. */
+function tokenTaskId() {
+  if (!TOKEN.startsWith("uai_")) return null;
+  try { return JSON.parse(Buffer.from(TOKEN.slice(4).split(".")[0], "base64url").toString("utf8")).t || null; }
+  catch { return null; }
+}
+
+function parseFlags(args) {
+  const flags = {}; const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) { const k = a.slice(2); const v = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "true"; flags[k] = v; }
+    else rest.push(a);
+  }
+  return { flags, rest };
+}
+
+// A punchlist item's text is prose, and prose written in THIS repo contains
+// --id and --text. parseFlags is global and greedy, so routing todo text
+// through it silently rewrote the request: "todo edit aaaaaa the --id flag"
+// resolved to { ref: "flag", text: "aaaaaa the" } and edited a different item,
+// and a valueless --text became the literal string "true" — an item
+// overwritten with garbage, or worse, the wrong item overwritten at all. Todo
+// text is therefore read from the raw argv tail and never flag-parsed. The
+// --id <ref> form survives only in leading position, where it cannot be
+// mistaken for prose.
+function todoRef(args) {
+  return args[0] === "--id"
+    ? { ref: args[1], tail: args.slice(2) }
+    : { ref: args[0] && !args[0].startsWith("--") ? args[0] : "", tail: args.slice(1) };
+}
+function todoText(args) { return args.join(" ").trim(); }
+
+async function api(method, path, body) {
+  const res = await fetch(API_URL + path, {
+    method,
+    headers: { authorization: "Bearer " + TOKEN, "content-type": "application/json" },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json; try { json = JSON.parse(text); } catch { json = text; }
+  if (!res.ok) {
+    const msg = (json && json.error && json.error.message) || text || res.statusText;
+    console.error("moondeck: " + res.status + " " + msg);
+    process.exit(1);
+  }
+  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("moondeck: 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("moondeck: --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: moondeck 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() + ${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, 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;
+}
+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("moondeck: " + opLine(op)); process.exit(1); }
+  if (wait && !op.done) {
+    console.error("moondeck: 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
+// 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/.moondeck/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("moondeck: 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("moondeck: " + message);
+  process.exit(1);
+}
+function legacyFilesMount(root) {
+  try {
+    lstatSync(join(dirname(root), ".moondeck", "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("moondeck: 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("moondeck: download failed");
+      process.exit(1);
+    }
+    if (!res.ok) {
+      console.error("moondeck: 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 ? "moondeck: download etag does not match the inspected file" : "moondeck: download did not name an etag");
+      process.exit(1);
+    }
+    if (!res.body || !res.body.getReader) {
+      console.error("moondeck: 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("moondeck: " + label + " stdin is a terminal; use a pipe or a quoted heredoc with - <<'EOF' (see moondeck --help)");
+    process.exit(1);
+  }
+  const text = readFileSync(0, "utf8").trim();
+  if (!text) { console.error("moondeck: " + 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('moondeck: 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 moondeck 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));
+    }
+    if (!recipientArgs.length) {
+      console.error('moondeck: 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("moondeck: 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("moondeck: 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("moondeck: 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('moondeck: 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,
+    });
+    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(
+        "moondeck: could not wake " +
+          result.failedRecipients.map((id) => "@" + id).join(", "),
+      );
+    }
+    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("moondeck: 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 === "branch" && action === "name") {
+    // uai/<taskId>/<name>: this task's server-issued branch namespace. A PR
+    // from it links to this task exactly like one from the task branch.
+    const name = pos[0] || "";
+    const valid = name.length > 0 && name.length <= 150 && !name.includes("..") &&
+      name.split("/").every(part => /^[A-Za-z0-9_][A-Za-z0-9._-]*$/.test(part) && !part.endsWith(".lock") && !part.endsWith("."));
+    if (pos.length !== 1 || Object.keys(flags).length || !valid) {
+      console.error("moondeck: branch name <name>   (letters, digits, '.', '_', '-' and '/'; no leading '-' or '.')"); process.exit(1);
+    }
+    const taskId = tokenTaskId();
+    if (!taskId || !/^[0-9a-hjkmnp-tv-z]{26}$/.test(taskId)) { console.error("moondeck: branch name: this task's id is unavailable"); process.exit(1); }
+    const branch = "uai/" + taskId + "/" + name;
+    // git's own rule, when git is here to ask.
+    const git = spawnSync("git", ["check-ref-format", "--branch", branch], { encoding: "utf8" });
+    if (!git.error && git.status !== 0) { console.error("moondeck: branch name: git refuses " + branch); process.exit(1); }
+    out(branch); 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("moondeck: 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; }
+    if (action === "suggest") {
+      // The Astronaut suggests a persona; a person creates it (ADR-157 addendum).
+      // From the Store (--template) or from scratch (--name and --brief).
+      if (!flags.why || !(flags.template || flags.name)) {
+        console.error('moondeck: crew suggest needs --template <slug> (see crew store), or --name and --brief for a new one, and --why "<reason>"');
+        process.exit(1);
+      }
+      // --skill repeats, and parseFlags keeps only the last, so read them off the raw argv.
+      const skills = [];
+      for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === "--skill" && rest[i + 1]) skills.push(...rest[++i].split(",").filter(Boolean));
+      }
+      const body = { why: flags.why };
+      if (flags.template) body.template = flags.template;
+      for (const k of ["name", "role", "summary", "brief", "model", "effort"]) if (flags[k]) body[k] = flags[k];
+      if (flags.handle) body.handle = handleOf(flags.handle);
+      if (flags.engine) body.engine = flags.engine;
+      if (skills.length) body.skills = skills;
+      const r = await api("POST", "/api/agent/crew-suggest", body);
+      out("suggested " + r.suggestion.name + " (@" + r.suggestion.handle + "). " + r.message);
+      return;
+    }
+    if (action === "add") {
+      const personaId = pos[0];
+      if (!personaId || !flags.why) {
+        console.error('moondeck: crew add needs a persona id (see crew list) and --why "<reason>"');
+        process.exit(1);
+      }
+      const body = { personaId, why: flags.why };
+      if (flags.as) body.handle = handleOf(flags.as);
+      if (flags.engine) body.kind = flags.engine;
+      if (flags.model) body.model = flags.model;
+      if (flags.effort) body.effort = flags.effort;
+      if (flags.account) body.account = flags.account === "default" ? null : flags.account;
+      const r = await api("POST", "/api/agent/crew", body);
+      out("added @" + r.agent.id + " (" + r.agent.label + ") on " + launch(r.agent) + ". It stays idle until you dispatch work to it.");
+      return;
+    }
+    if (action === "model") {
+      const id = handleOf(pos[0] || "");
+      if (!id || !flags.why || !(flags.model || flags.engine || flags.effort || flags.account)) {
+        console.error('moondeck: crew model needs @agent, at least one of --engine, --model, --effort and --account, and --why "<reason>"');
+        process.exit(1);
+      }
+      // "default" clears the setting back to the engine's own default (null).
+      const cleared = (v) => (v === "default" ? null : v);
+      const body = { why: flags.why };
+      if (flags.engine) body.kind = flags.engine;
+      if (flags.model) body.model = cleared(flags.model);
+      if (flags.effort) body.effort = cleared(flags.effort);
+      if (flags.account) body.account = cleared(flags.account);
+      const r = await api("PATCH", "/api/agent/crew/" + encodeURIComponent(id), body);
+      out(r.changed
+        ? "@" + id + " now runs on " + launch(r.agent) + "; its session restarts after its current turn"
+        : "@" + id + " already runs on " + launch(r.agent) + "; nothing changed");
+      return;
+    }
+    if (action === "remove") {
+      const id = handleOf(pos[0] || "");
+      if (!id || !flags.why) {
+        console.error('moondeck: crew remove needs @agent and --why "<reason>"');
+        process.exit(1);
+      }
+      await api("DELETE", "/api/agent/crew/" + encodeURIComponent(id), { why: flags.why });
+      out("removed @" + id);
+      return;
+    }
+    console.error("moondeck: 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("moondeck: files ls [org|me[/prefix]]");
+        process.exit(1);
+      }
+      const target = filesTarget(positional[0] || "org");
+      if (!target) {
+        console.error("moondeck: 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("moondeck: files get <org|me>/<path> [<dest>] [-r]");
+        process.exit(1);
+      }
+      const target = filesTarget(positional[0]);
+      if (!target) {
+        console.error("moondeck: files get <org|me>/<path> [<dest>] [-r]");
+        process.exit(1);
+      }
+      if (!recursive) {
+        if (!target.path) {
+          console.error("moondeck: 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("moondeck: 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("moondeck: files get -r stops at 500 files");
+            process.exit(1);
+          }
+          if (bytes + size > FILES_CAP_BYTES) {
+            console.error("moondeck: 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("moondeck: 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;
+    case "people list": out(await api("GET", "/api/agent/people")); break;
+    case "task list": out((await api("GET", "/api/agent/tasks")).tasks); break;
+    case "memory search": {
+      const q = pos.join(" ") || flags.q || "";
+      const author = flags.as ? "&author=" + encodeURIComponent(flags.as) : "";
+      const limit = flags.limit ? "&limit=" + encodeURIComponent(String(flags.limit)) : "";
+      const res = await api(
+        "GET",
+        "/api/agent/memory?q=" + encodeURIComponent(q) + author + limit,
+      );
+      out(res.memories);
+      // Truncation goes to stderr so it cannot corrupt piped JSON, and it is
+      // stated rather than implied: recalling across tasks means reading the
+      // WHOLE store, and a short page that says nothing reads as all there is.
+      // NOTE: this file is a template literal. No backticks, no \${} in here.
+      if (res.truncated) {
+        console.error(
+          "moondeck: showing " + res.memories.length + " of " + res.total +
+            " — re-run with --limit all for every row.",
+        );
+      }
+      break;
+    }
+    case "memory save": {
+      const text = pos.join(" ") || flags.text || "";
+      if (!text) { console.error("moondeck: memory save needs text"); process.exit(1); }
+      out((await api("POST", "/api/agent/memory", {
+        text,
+        author: flags.as || null,
+        projectId: flags.project || null,
+        tags: flags.tags ? String(flags.tags).split(",").map((s) => s.trim()).filter(Boolean) : [],
+      })).memory);
+      break;
+    }
+    case "memory delete": {
+      const id = pos[0] || flags.id;
+      if (!id) { console.error("moondeck: memory delete needs an id"); process.exit(1); }
+      await api("DELETE", "/api/agent/memory/" + encodeURIComponent(id));
+      out("deleted " + id);
+      break;
+    }
+    case "task create": {
+      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("moondeck: --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("moondeck: --start is a flag; it takes no value"); process.exit(1);
+      }
+      if (flags.start && (!flags["request-id"] || flags["request-id"] === "true")) {
+        console.error("moondeck: --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,
+        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,
+        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("moondeck: 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("moondeck: 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("moondeck: 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("moondeck: 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", "child"]);
+      const unknown = Object.keys(flags).filter((flag) => !allowed.has(flag));
+      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("moondeck: --child requires a child task id"); process.exit(1);
+      }
+      if (pos.length > 1 || unknown.length || (childMode && pos.length)) {
+        console.error("moondeck: 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("moondeck: task close needs --status finished|canceled");
+        process.exit(1);
+      }
+      if (flags.reason === "true") {
+        console.error("moondeck: --reason needs text (quote multiword reasons)");
+        process.exit(1);
+      }
+      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) } : {}),
+      });
+      out("task closed as " + closed.status);
+      break;
+    }
+    case "todo list": {
+      const todos = (await api("GET", "/api/agent/todos")).todos || [];
+      if (!todos.length) { out("punchlist is empty"); break; }
+      const done = todos.filter((t) => t.status === "done").length;
+      const lines = todos.map((t) => {
+        const box = t.status === "done" ? "[x]" : t.claimedBy ? "[~]" : "[ ]";
+        const who = t.status === "done"
+          ? (t.claimedBy ? " — done by @" + t.claimedBy : " — done")
+          : t.claimedBy ? " — @" + t.claimedBy + " working" : "";
+        return "  #" + t.shortId + "  " + box + " " + t.text + who;
+      });
+      out("Punchlist (" + done + "/" + todos.length + " done):\\n" + lines.join("\\n"));
+      break;
+    }
+    case "todo add": {
+      const text = todoText(rest);
+      if (!text) { console.error("moondeck: todo add needs text"); process.exit(1); }
+      const t = (await api("POST", "/api/agent/todos", { op: "add", text })).todo;
+      out("added #" + t.shortId + ": " + t.text);
+      break;
+    }
+    case "todo edit": {
+      const { ref, tail } = todoRef(rest);
+      const text = todoText(tail);
+      if (!ref) { console.error("moondeck: todo edit needs an item id (see 'moondeck todo list')"); process.exit(1); }
+      if (!text) { console.error("moondeck: todo edit needs replacement text"); process.exit(1); }
+      const t = (await api("POST", "/api/agent/todos", { op: "edit", ref, text })).todo;
+      out("edited #" + t.shortId + ": " + t.text);
+      break;
+    }
+    case "todo remove": {
+      const { ref } = todoRef(rest);
+      if (!ref) { console.error("moondeck: todo remove needs an item id (see 'moondeck todo list')"); process.exit(1); }
+      await api("POST", "/api/agent/todos", { op: "remove", ref });
+      out("removed #" + String(ref).replace(/^#/, ""));
+      break;
+    }
+    case "todo claim": case "todo done": case "todo reopen": case "todo unclaim": {
+      const { ref } = todoRef(rest);
+      if (!ref) { console.error("moondeck: todo " + action + " needs an item id (see 'moondeck todo list')"); process.exit(1); }
+      const t = (await api("POST", "/api/agent/todos", { op: action, ref })).todo;
+      out(action + " #" + t.shortId + ": " + t.text);
+      break;
+    }
+    case "preview add": {
+      const name = pos[0] || flags.name;
+      const port = Number(pos[1] || flags.port);
+      if (!name || !Number.isInteger(port)) { console.error("moondeck: preview add <name> <containerPort>"); process.exit(1); }
+      const r = await api("POST", "/api/agent/previews", { name, containerPort: port });
+      out("preview '" + r.name + "' on port " + r.containerPort + " — turn it on with: moondeck preview enable " + r.name);
+      break;
+    }
+    case "preview enable":
+    case "preview disable":
+    case "preview public":
+    case "preview private": {
+      const name = pos[0] || flags.name;
+      if (!name) { console.error("moondeck: preview " + action + " <name>"); process.exit(1); }
+      const body = action === "enable" || action === "disable"
+        ? { enabled: action === "enable" }
+        : { public: action === "public" };
+      const r = await api("PATCH", "/api/agent/previews/" + encodeURIComponent(name), body);
+      const state = (r.enabled ? "on" : "off") + ", " + (r.public ? "public (anyone with the link)" : "private (sign-in)");
+      out("preview '" + r.name + "' is " + state + (r.url ? " — " + r.url : ""));
+      if (!r.enabled && r.public) console.error("moondeck: it's public but off — it serves nothing until: moondeck 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("moondeck: 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 || flags.repo === "true") { console.error("moondeck: 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("moondeck: 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("moondeck: 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("moondeck: 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("moondeck: 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("moondeck: 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("moondeck: --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("moondeck: 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) {
+        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("moondeck: task project add <projectId|slug> [--no-wait]  |  task project status <operationId>");
+      process.exit(1);
+    }
+    case "task rename": {
+      // The name is prose, not flags: read the raw tail, like todo text.
+      const name = rest.join(" ").trim();
+      if (!name || name.length > 120) { console.error('moondeck: task rename "<new name>"   (1-120 characters)'); process.exit(1); }
+      const r = await api("PATCH", "/api/agent/task", { name });
+      out(r.changed ? "renamed the task to " + r.task.name + " (branch stays " + r.task.branch + ")" : "the task is already named " + r.task.name);
+      break;
+    }
+    case "task label": {
+      const sub = rest[0];
+      // One shell argument is one label, literally: commas are valid in label
+      // names, so "bug, urgent" is a single label and bug urgent is two.
+      const names = rest.slice(1).map((n) => String(n).trim()).filter(Boolean);
+      if ((sub !== "add" && sub !== "remove") || !names.length) { console.error('moondeck: task label add <name> [<name>…]  |  task label remove <name> [<name>…]   (quote a name with spaces or commas)'); process.exit(1); }
+      const r = await api(sub === "add" ? "POST" : "DELETE", "/api/agent/task/labels", { names });
+      const changed = sub === "add" ? r.added : r.removed;
+      out((changed.length ? (sub === "add" ? "added " : "removed ") + changed.join(", ") : "no change") + " — labels: " + (r.labels.map((l) => l.name).join(", ") || "none"));
+      break;
+    }
+    case "task delete": {
+      if (pos.length !== 1 || Object.keys(flags).length) { console.error("moondeck: task delete <childId>   (a draft you created; close a started child instead)"); process.exit(1); }
+      const r = await api("DELETE", "/api/agent/tasks/" + encodeURIComponent(pos[0]));
+      out("deleted draft " + r.deleted);
+      break;
+    }
+    case "task search": {
+      const q = pos.join(" ") || flags.q || "";
+      if (!q) { console.error("moondeck: task search <query>"); process.exit(1); }
+      const hits = (await api("GET", "/api/agent/history?q=" + encodeURIComponent(q))).messages || [];
+      if (!hits.length) { out("no matches in your past tasks"); break; }
+      out(hits.map((h) => "[" + h.taskName + "] @" + h.author + ": " + h.snippet).join("\\n"));
+      break;
+    }
+    case "task read": {
+      const id = pos[0] || flags.id;
+      if (!id) { console.error("moondeck: task read <taskId>  (see 'moondeck task history')"); process.exit(1); }
+      const chat = await api("GET", "/api/agent/history?taskId=" + encodeURIComponent(id));
+      out("# " + chat.taskName + "\\n" + (chat.messages || []).map((m) => "@" + m.author + ": " + m.snippet).join("\\n"));
+      break;
+    }
+    case "task history": {
+      const tasks = (await api("GET", "/api/agent/history")).tasks || [];
+      out(tasks.length ? tasks.map((t) => t.taskId + "  " + t.taskName + " (" + t.status + ")").join("\\n") : "no past tasks");
+      break;
+    }
+    case "whoami ": case "whoami undefined": out({ apiUrl: API_URL }); break;
+    case "react heart": case "react check": case "react x": {
+      const r = await api("POST", "/api/agent/react", { emoji: action, msg: flags.msg || undefined });
+      out((r.reacted ? "reacted to " : "un-reacted from ") + r.messageId);
+      break;
+    }
+    default:
+      console.error([
+        "moondeck — agent CLI. Commands:",
+        '  moondeck share <path> [--title "text"]   (share an immutable file with people; Files plan, workspace quota)',
+        '  moondeck secret request NAME --why "reason" [--proxy-domain host]… [--no-wait]',
+        "      Never paste secrets into chat. A person supplies them through the private dialog.",
+        "  moondeck artifacts",
+        "  moondeck projects list",
+        "  moondeck files ls [org|me[/prefix]]     (one folder: names, sizes, mtimes, etags; defaults to org)",
+        "  moondeck files get <org|me>/<path> [<dest>]   (download; default /workspace/files/<org|me>/<path>; -r is a folder, capped at 500 files / 1 GB)",
+        "  moondeck people list",
+        "  moondeck task list",
+        "  moondeck task create --name <n> --prompt <text|-> [--projects id,id] [--team id] [--agents handle,handle] [--astronaut engine/model/effort] [--start --request-id <logical-run-id>]",
+        "  moondeck task watch <childId> [--after <cursor>] [--limit N]",
+        "  moondeck task usage <childId>",
+        '  moondeck task send <childId> "text"',
+        '  moondeck task answer <childId> <cardId> "option text"',
+        '  moondeck task close [--child <childId>] --status finished|canceled [--reason "final report"]',
+        "  moondeck task delete <childId>          (delete a draft you created for this task; started children are closed instead)",
+        '  moondeck task rename "<new name>"       (rename this running task; its branch keeps its name)',
+        '  moondeck task label add <name> [<name>…]   (label this running task; one argument per label, quote "a, b" to keep it whole; missing labels are created)',
+        "  moondeck task label remove <name> [<name>…]",
+        "  moondeck memory search <query> [--as handle] [--limit N|all]",
+        "  moondeck memory save <text> [--project id] [--tags a,b]",
+        "  moondeck memory delete <id>",
+        "  moondeck todo list",
+        "  moondeck todo add <text>",
+        "  moondeck todo edit <#id> <text>",
+        "  moondeck todo remove <#id>",
+        "  moondeck todo claim|done|reopen|unclaim <#id>",
+        '  moondeck branch name <name>   (prints uai/<taskId>/<name>; a PR from it links to this task: git switch -c "$(moondeck branch name fix-foo)")',
+        "  moondeck review report --pr <number|URL> --head <full-sha> --must <n> --should <n> --nits <n> --verdict approve|changes [--summary text] [--assignment id] [--revision n]",
+        "  moondeck 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.",
+        "  moondeck preview add <name> <containerPort>",
+        "  moondeck preview enable|disable <name>      (turn it on; prints its URL)",
+        "  moondeck preview public|private <name>      (public: a link anyone can open)",
+        "  moondeck project list | show <id|slug>",
+        "  moondeck 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)",
+        "  moondeck 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)",
+        "  moondeck project propose-extra <id|slug> --extra-file <f>   (Dockerfile additions; a member approves them)",
+        "  moondeck project env list|observed <id|slug>",
+        "  moondeck project env add <id|slug> NAME [--label <l>] [--secret]   (declares a key; values are a member's)",
+        "  moondeck project env remove <id|slug> NAME   (drops a declaration with no value; never deletes a value; when the workspace allows it)",
+        "  moondeck project env propose-proxy <id|slug> NAME --domain <d>[,<d>…] [--placeholder-prefix <p> --placeholder-length <n>]   (a member confirms)",
+        "  moondeck task project add <projectId|slug> [--no-wait]   (clone a repository into this running task; waits until ready)",
+        "  moondeck task project status <operationId>",
+        "  moondeck task search <query>            (your own past tasks)",
+        "  moondeck task history                   (list your past tasks)",
+        "  moondeck task read <taskId>             (full chat of a past task you were on)",
+        '  moondeck 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):",
+        "      moondeck dispatch @agent - <<'EOF'",
+        "      Your literal instruction, including quotes and shell syntax.",
+        "      EOF",
+        "    moondeck task create --name <n> --prompt - reads stdin the same way.",
+        "  moondeck crew list                      (Astronaut only: personas with summary, skills and permissions, engines, models, limits, roster)",
+        "  moondeck crew status                    (Astronaut only: each agent's engine, model, account; account usage; credits)",
+        "  moondeck crew store                     (Astronaut only: the Store's persona and skill templates, names and types only)",
+        '  moondeck crew suggest --template <slug> --why "<reason>"   (Astronaut only: propose a persona from the Store; a person creates it)',
+        '  moondeck crew suggest --name <n> --brief <text> [--role <r>] [--summary <s>] [--handle <h>] [--engine <kind>] [--model <m>] [--effort <e>] [--skill <slug|id>]... --why "<reason>"',
+        '  moondeck crew add <personaId> [--as <handle>] [--engine <kind>] [--model <m>] [--effort <e>] [--account <id|label|default>] --why "<reason>"',
+        '  moondeck crew model @agent [--engine <kind>] [--model <m|default>] [--effort <e|default>] [--account <id|label|default>] --why "<reason>"',
+        '  moondeck crew remove @agent --why "<reason>"',
+        "  moondeck react <heart|check|x> [--msg #id]   (no --msg = the message you were last handed)",
+        "  moondeck whoami",
+      ].join("\\n"));
+      process.exit(argv.length ? 1 : 0);
+  }
+}
+main().catch((e) => { console.error("moondeck: " + (e && e.message ? e.message : e)); process.exit(1); });
+`;