@asteroidai/cli 1.9.115 → 1.9.123

package/dist/asteroid.js

@@ -1946,6 +1946,34 @@ var COMMANDS = [
     destructive: false,
     capability: "run_execution"
   },
+  {
+    command: "execution sync",
+    tool: "execution_sync",
+    title: "Wait for an execution to finish",
+    description: "Wait up to `timeoutSeconds` (1-25, default 25) for a running execution to finish. Returns the terminal `status` and `executionResult` when it finishes in time. Otherwise returns the current status: call it again to keep waiting. A paused or `awaiting_confirmation` execution returns at once, since it needs a person. Use it after `workflow_execute_post`, or after `workflow_execute_sync_post` timed out, instead of polling `execution_get`.",
+    method: "GET",
+    path: "/agents/v2/executions/{executionId}/sync",
+    args: [
+      {
+        name: "executionId",
+        flag: "execution-id",
+        type: "string",
+        required: true
+      }
+    ],
+    query: [
+      {
+        name: "timeoutSeconds",
+        flag: "timeout-seconds",
+        type: "integer",
+        required: false,
+        description: "Seconds to wait for the execution to finish before returning 202. Defaults to 25."
+      }
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
   {
     command: "insight get",
     tool: "insight_get",
@@ -4886,6 +4914,26 @@ var COMMANDS = [
     readOnly: false,
     destructive: false
   },
+  {
+    command: "workflow head validate",
+    tool: "workflow_head_validate",
+    title: "Validate workflow head",
+    description: 'Check the workflow\'s editable head the way publish and run do, without changing it. Returns blocking errors and advisory warnings, each with the path of the field it names, such as ["nodes", "Login", "model"]. Use after `workflow_files_patch` and before `workflow_head_publish`; an empty `issues` list means the head can publish and run. The same list comes back on every `workflow_files_patch` response.',
+    method: "POST",
+    path: "/agents/v2/workflows/{workflowId}/head/validate",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true
+      }
+    ],
+    query: [],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
   {
     command: "workflow list",
     tool: "workflow_list",
@@ -6200,6 +6248,85 @@ var COMMANDS = [
   }
 ];
 
+// src/sync/types.ts
+var MANIFEST = ".asteroid.json";
+function get(path, query = {}) {
+  return { method: "GET", path, query: new URLSearchParams(query) };
+}
+function statusOf(error) {
+  const status = error?.status;
+  return typeof status === "number" ? status : void 0;
+}
+
+// src/sync/execution-wait.ts
+var WAIT_TIMEOUT_SECONDS = 600;
+var WAIT_INTERVAL_SECONDS = 15;
+var MAX_WAIT_TIMEOUT_SECONDS = 3600;
+var MAX_WAIT_INTERVAL_SECONDS = 120;
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "cancelled", "failed"]);
+function isTerminalExecutionStatus(status) {
+  return TERMINAL.has(status);
+}
+var SYNC_TIMEOUT_SECONDS = 25;
+function pause(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function readStatus(sync, executionId2, timeoutMs) {
+  if (timeoutMs <= 0)
+    return await sync.remote.json(
+      get(`/agents/v2/executions/${executionId2}`)
+    );
+  const timeoutSeconds = Math.min(
+    SYNC_TIMEOUT_SECONDS,
+    Math.max(1, Math.ceil(timeoutMs / 1e3))
+  );
+  const response = await sync.remote.json(
+    get(`/agents/v2/executions/${executionId2}/sync`, {
+      timeoutSeconds: String(timeoutSeconds)
+    })
+  );
+  return {
+    id: response.executionId,
+    status: response.status,
+    executionResult: response.executionResult
+  };
+}
+async function waitForExecution(sync, options) {
+  const timeoutMs = (options.timeoutSeconds ?? WAIT_TIMEOUT_SECONDS) * 1e3;
+  const intervalMs = (options.intervalSeconds ?? WAIT_INTERVAL_SECONDS) * 1e3;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? pause;
+  const started = now();
+  let polls = 0;
+  for (; ; ) {
+    const called = now();
+    const execution = await readStatus(
+      sync,
+      options.executionId,
+      timeoutMs - (called - started)
+    );
+    polls++;
+    const elapsed = now() - started;
+    const waitedSeconds = Math.round(elapsed / 1e3);
+    if (isTerminalExecutionStatus(execution.status))
+      return { execution, terminal: true, waitedSeconds, polls };
+    const remaining = timeoutMs - elapsed;
+    if (remaining <= 0)
+      return { execution, terminal: false, waitedSeconds, polls };
+    const early = intervalMs - (now() - called);
+    if (early > 0) await sleep(Math.min(early, remaining));
+  }
+}
+function formatExecutionWait(result) {
+  const { execution } = result;
+  if (!result.terminal) {
+    return `Execution ${execution.id} still ${execution.status} after ${result.waitedSeconds}s. Wait again, or read what it has so far with \`asteroid execution pull ${execution.id}\`.`;
+  }
+  const line2 = `Execution ${execution.id} ${execution.status}.`;
+  const outcome = execution.executionResult;
+  return outcome ? `${line2} Result: ${outcome.outcome}: ${outcome.reasoning}` : line2;
+}
+
 // src/sync/commands.ts
 function option(name, type, description, extra = {}) {
   return { name, flag: name, type, required: false, description, ...extra };
@@ -6211,6 +6338,12 @@ var local = {
   destructive: false,
   local: true
 };
+var executionId = {
+  name: "executionId",
+  flag: "execution-id",
+  type: "string",
+  required: true
+};
 var SYNC_COMMANDS = [
   {
     ...local,
@@ -6219,14 +6352,7 @@ var SYNC_COMMANDS = [
     title: "Pull an execution to disk",
     description: "Write an execution to `<workflow-name>/executions/<id>/`: summary.json, activities.md (the step-by-step log), and the files the run produced.",
     readOnly: true,
-    args: [
-      {
-        name: "executionId",
-        flag: "execution-id",
-        type: "string",
-        required: true
-      }
-    ],
+    args: [executionId],
     query: [
       option(
         "files",
@@ -6252,6 +6378,54 @@ var SYNC_COMMANDS = [
         "Write here instead of `<workflow-name>/executions/<id>/` under the current directory."
       )
     ]
+  },
+  {
+    ...local,
+    command: "execution wait",
+    tool: "execution_wait",
+    title: "Wait for an execution to end",
+    description: "Poll an execution until it is completed, failed or cancelled, then print its status and, when the run produced one, its result. When the timeout passes first, print the status it still has, so you can wait again.",
+    readOnly: true,
+    args: [executionId],
+    query: [
+      option(
+        "timeout",
+        "integer",
+        `Give up after this many seconds, ${WAIT_TIMEOUT_SECONDS} unless set, ${MAX_WAIT_TIMEOUT_SECONDS} at most.`
+      ),
+      option(
+        "interval",
+        "integer",
+        `Poll every this many seconds, ${WAIT_INTERVAL_SECONDS} unless set, ${MAX_WAIT_INTERVAL_SECONDS} at most.`
+      )
+    ]
+  },
+  {
+    ...local,
+    command: "insight pull",
+    tool: "insight_pull",
+    title: "Pull insights to disk",
+    description: "Write insights to `insights/<name>.md`, one markdown file each with YAML frontmatter (id, type, status, name, next_steps). Name an insight to pull that one. A file another insight or an unpushed draft already holds keeps its name; the pulled one gets a -2, -3 suffix.",
+    readOnly: true,
+    args: [
+      {
+        name: "insightId",
+        flag: "insight-id",
+        type: "string",
+        required: false,
+        description: "One insight to pull. Without it, every insight, or one workflow's with --workflow-id."
+      }
+    ],
+    query: [
+      option("workflowId", "string", "Only this workflow's insights.", {
+        flag: "workflow-id"
+      }),
+      option(
+        "dir",
+        "string",
+        "Write here instead of `insights/` under the current directory."
+      )
+    ]
   }
 ];
 
@@ -6710,15 +6884,16 @@ function defineCommands(root, options, dotted2 = /* @__PURE__ */ new Map(), onIn
       (arg) => options.defaultArg?.(command, arg)
     );
     const defaulted = defaults[0] !== void 0;
+    const optional = (arg, i) => i === 0 && defaulted || !arg.required;
     command.args.forEach((arg) => {
       leaf.argument(
-        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
+        defaulted || !arg.required ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? ""
       );
     });
     if (defaulted) {
       const names = command.args.map(
-        (arg, i) => i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`
+        (arg, i) => optional(arg, i) ? `[${arg.flag}]` : `<${arg.flag}>`
       );
       leaf.usage(`[options] ${names.join(" ")}`);
     }
@@ -6735,8 +6910,9 @@ ${notes.join("\n")}`);
       if (positionals.length === command.args.length - 1 && defaults[0] !== void 0) {
         positionals = [defaults[0], ...positionals];
       }
-      if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a, i) => i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
+      const required = command.args.filter((arg) => arg.required).length;
+      if (positionals.length < required || positionals.length > command.args.length) {
+        const expected = command.args.map((a, i) => optional(a, i) ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`
         );
@@ -7258,7 +7434,7 @@ var ApiError = class extends Error {
   status;
   body;
 };
-var VERSION = "1.9.115";
+var VERSION = "1.9.123";
 function problem(status, body, fallback) {
   if (body && typeof body === "object") {
     const record2 = body;
@@ -8070,6 +8246,13 @@ function normalizeNodeName(name) {
   }
   return result;
 }
+function lossySlugOr(name, fallback) {
+  try {
+    return normalizeNodeName(name);
+  } catch {
+    return fallback;
+  }
+}
 function nodeDirName(name) {
   if (isNameCharsetConforming(name)) {
     return name.replaceAll(" ", "_");
@@ -8083,8 +8266,8 @@ function agentDirName(name) {
     return "agent";
   }
 }
-function executionDirName(executionId) {
-  return executionId.slice(0, 8);
+function executionDirName(executionId2) {
+  return executionId2.slice(0, 8);
 }
 function workflowDirName(workflowId, version, parentId, parentVersion) {
   const short = workflowId.slice(0, 8);
@@ -8132,16 +8315,6 @@ function matchesGlob(path, pattern) {
   return new RegExp(`^${source}$`).test(path);
 }
 
-// src/sync/types.ts
-var MANIFEST = ".asteroid.json";
-function get(path, query = {}) {
-  return { method: "GET", path, query: new URLSearchParams(query) };
-}
-function statusOf(error) {
-  const status = error?.status;
-  return typeof status === "number" ? status : void 0;
-}
-
 // src/sync/execution-pull.ts
 var DIRECTORIES = ["workspace", "downloads", "shared"];
 function relativeFilePath(file) {
@@ -8179,14 +8352,14 @@ async function writeActivities(sync, dir, execution) {
     return false;
   }
 }
-async function listFiles(sync, executionId) {
+async function listFiles(sync, executionId2) {
   const listing = await sync.remote.json(
-    get(`/agents/v2/executions/${executionId}/files`)
+    get(`/agents/v2/executions/${executionId2}/files`)
   );
   return DIRECTORIES.flatMap((name) => listing.directories[name] ?? []);
 }
-async function download(sync, executionId, file) {
-  const path = `/agents/v2/executions/${executionId}/files/${file.id}/signed-url`;
+async function download(sync, executionId2, file) {
+  const path = `/agents/v2/executions/${executionId2}/files/${file.id}/signed-url`;
   const { url } = await sync.remote.json(get(path));
   return sync.remote.download(url);
 }
@@ -8314,6 +8487,114 @@ ${result.skipped.map((s) => `  - ${s}`).join("\n")}` : null,
   ].filter(Boolean).join("\n");
 }
 
+// src/sync/insight-file.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)(?:\r?\n)?/;
+function serializeInsightFile(meta, body) {
+  const front = {};
+  if (meta.id) front.id = meta.id;
+  front.type = meta.type;
+  if (meta.status) front.status = meta.status;
+  front.name = meta.name;
+  if (meta.nextSteps) front.next_steps = meta.nextSteps;
+  const yaml = stringifyYaml(front).trimEnd();
+  return `---
+${yaml}
+---
+
+${body}`;
+}
+function insightFileId(text3) {
+  const match = FRONTMATTER.exec(text3);
+  if (!match) return void 0;
+  try {
+    const id = parseYaml(match[1])?.id;
+    return typeof id === "string" || typeof id === "number" ? String(id) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/sync/insight-pull.ts
+var INSIGHTS_DIR = "insights";
+var PAGE_SIZE = 100;
+async function listInsights(sync, workflowId) {
+  const all = [];
+  for (let page = 1; ; page++) {
+    const query = {
+      page: String(page),
+      pageSize: String(PAGE_SIZE)
+    };
+    if (workflowId) query.workflowId = workflowId;
+    const { items, total } = await sync.remote.json(
+      get("/astro/v2/insights", query)
+    );
+    all.push(...items);
+    if (items.length === 0 || all.length >= total) return all;
+  }
+}
+async function stemOwners(sync, dir) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const name of await sync.files.list(dir)) {
+    if (!name.endsWith(".md") || name.includes("/")) continue;
+    const bytes = await sync.files.read(join3(dir, name));
+    const text3 = bytes ? Buffer.from(bytes).toString("utf8") : "";
+    owners.set(name.slice(0, -".md".length).toLowerCase(), insightFileId(text3));
+  }
+  return owners;
+}
+function assignStems(owners, insights) {
+  const used = /* @__PURE__ */ new Set();
+  const heldByOther = (stem, id) => owners.has(stem) && owners.get(stem) !== id;
+  return insights.map((insight) => {
+    const base = lossySlugOr(insight.name, "insight");
+    let stem = base;
+    for (let n = 2; used.has(stem) || heldByOther(stem, insight.id); n++) {
+      stem = `${base}-${n}`;
+    }
+    used.add(stem);
+    return [insight, stem];
+  });
+}
+async function pullInsights(sync, options = {}) {
+  const dir = options.dir ?? INSIGHTS_DIR;
+  const insights = options.insightId ? [
+    await sync.remote.json(
+      get(`/astro/v2/insights/${options.insightId}`)
+    )
+  ] : await listInsights(sync, options.workflowId);
+  const pulled = [];
+  for (const [insight, stem] of assignStems(
+    await stemOwners(sync, dir),
+    insights
+  )) {
+    const path = join3(dir, `${stem}.md`);
+    const text3 = serializeInsightFile(
+      {
+        id: insight.id,
+        type: insight.type,
+        status: insight.status,
+        name: insight.name,
+        nextSteps: insight.nextSteps ?? void 0
+      },
+      insight.content
+    );
+    await sync.files.write(path, Buffer.from(text3, "utf8"));
+    const { id, name, type, status } = insight;
+    pulled.push({ id, name, type, status, path });
+  }
+  return { dir, insights: pulled };
+}
+function formatInsightPull(result) {
+  const count = result.insights.length;
+  return [
+    `Pulled ${count} insight${count === 1 ? "" : "s"} into ${result.dir}/.`,
+    ...result.insights.map(
+      (insight) => `  - ${insight.path}: ${insight.name} (${insight.type}, ${insight.status})`
+    )
+  ].join("\n");
+}
+
 // src/sync/node-files.ts
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname as dirname2, relative, resolve, sep } from "node:path";
@@ -8605,7 +8886,7 @@ function conflict(manifest) {
 }
 async function patch(sync, manifest, writes, deletes) {
   try {
-    await sync.remote.json({
+    const snapshot = await sync.remote.json({
       method: "PATCH",
       path: `/agents/v2/workflows/${manifest.workflowId}/head/files`,
       query: new URLSearchParams(),
@@ -8618,7 +8899,7 @@ async function patch(sync, manifest, writes, deletes) {
         deletes
       }
     });
-    return "applied";
+    return { issues: snapshot?.issues ?? [] };
   } catch (error) {
     if (statusOf(error) !== 409) throw error;
     return "conflict";
@@ -8688,14 +8969,20 @@ async function pushWorkflow(sync, dir, workflowId, options = {}) {
     if (writes.length === 0 && deletes.length === 0) {
       return { ...result, rev: manifest.rev, versionId: manifest.versionId };
     }
-    if (await patch(sync, manifest, writes, deletes) === "applied") {
+    const applied = await patch(sync, manifest, writes, deletes);
+    if (applied !== "conflict") {
       const next = await refresh2(
         sync,
         dir,
         manifest,
         new Map(writes.map((w) => [w.path, w.hash]))
       );
-      return { ...result, rev: next.rev, versionId: next.versionId };
+      return {
+        ...result,
+        rev: next.rev,
+        versionId: next.versionId,
+        issues: applied.issues
+      };
     }
     if (!options.rebase || attempt >= REBASE_ATTEMPTS) throw conflict(manifest);
     rebasedFrom ??= manifest.rev;
@@ -8711,9 +8998,23 @@ function formatWorkflowPush(result) {
     `Pushed to workflow ${result.workflowId}: ${result.written.length} written, ${result.deleted.length} deleted.${rebased}`,
     ...result.written.map((path) => `  + ${path}`),
     ...result.deleted.map((path) => `  - ${path}`),
-    `Head is now rev ${result.rev} (version ${result.versionId}).`
+    `Head is now rev ${result.rev} (version ${result.versionId}).`,
+    ...formatIssues(result.issues ?? [])
   ].join("\n");
 }
+function formatIssues(issues) {
+  if (issues.length === 0) return [];
+  const errors = issues.filter((issue) => issue.severity === "error").length;
+  const warnings = issues.length - errors;
+  const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+  const summary2 = errors === 0 ? `Validation: ${count(warnings, "warning")}, nothing blocks a publish.` : `Validation: ${count(errors, "error")}${warnings > 0 ? `, ${count(warnings, "warning")}` : ""}. Fix the errors before you publish.`;
+  return [
+    summary2,
+    ...issues.map(
+      (issue) => `  ${issue.severity === "error" ? "!" : "?"} ${issue.path.join("/") || "(workflow)"}: ${issue.message}`
+    )
+  ];
+}
 
 // src/sync/run.ts
 function flag(parsed, name) {
@@ -8726,6 +9027,35 @@ function integer(parsed, name) {
     throw new UsageError(`--${name} must be a whole number`);
   return Number(raw);
 }
+function bounded(parsed, name, min, max) {
+  const value2 = integer(parsed, name);
+  if (value2 === void 0) return void 0;
+  if (value2 < min || value2 > max)
+    throw new UsageError(`--${name} must be between ${min} and ${max}`);
+  return value2;
+}
+function executionWaitOptions(parsed) {
+  return {
+    executionId: parsed.positionals[0],
+    timeoutSeconds: bounded(parsed, "timeout", 0, MAX_WAIT_TIMEOUT_SECONDS),
+    intervalSeconds: bounded(parsed, "interval", 1, MAX_WAIT_INTERVAL_SECONDS)
+  };
+}
+function given(value2, name) {
+  if (value2 === void 0) return void 0;
+  if (value2 === "") throw new UsageError(`${name} must not be empty`);
+  return value2;
+}
+function insightPullOptions(parsed) {
+  const options = {};
+  const insightId = given(parsed.positionals[0], "<insight-id>");
+  if (insightId) options.insightId = insightId;
+  const workflowId = given(flag(parsed, "workflow-id"), "--workflow-id");
+  if (workflowId) options.workflowId = workflowId;
+  const dir = given(flag(parsed, "dir"), "--dir");
+  if (dir) options.dir = dir;
+  return options;
+}
 function executionOptions(parsed) {
   const summaryOnly = flag(parsed, "summary-only") === "true";
   const glob = flag(parsed, "files");
@@ -8787,6 +9117,20 @@ async function execute(command, parsed, sync, deps) {
     );
     return { result: result2, text: formatWorkflowPush(result2) };
   }
+  if (command.command === "execution wait") {
+    const result2 = await waitForExecution(sync, {
+      ...executionWaitOptions(parsed),
+      ...deps.executionWait
+    });
+    return { result: result2, text: formatExecutionWait(result2) };
+  }
+  if (command.command === "insight pull") {
+    const result2 = await pullInsights(sync, {
+      ...deps.insightPull,
+      ...insightPullOptions(parsed)
+    });
+    return { result: result2, text: formatInsightPull(result2) };
+  }
   if (command.command !== "execution pull")
     throw new UsageError(`unknown command ${command.command}`);
   const result = await pullExecution(sync, {

package/dist/core.js

@@ -1967,6 +1967,34 @@ var COMMANDS = [
     destructive: false,
     capability: "run_execution"
   },
+  {
+    command: "execution sync",
+    tool: "execution_sync",
+    title: "Wait for an execution to finish",
+    description: "Wait up to `timeoutSeconds` (1-25, default 25) for a running execution to finish. Returns the terminal `status` and `executionResult` when it finishes in time. Otherwise returns the current status: call it again to keep waiting. A paused or `awaiting_confirmation` execution returns at once, since it needs a person. Use it after `workflow_execute_post`, or after `workflow_execute_sync_post` timed out, instead of polling `execution_get`.",
+    method: "GET",
+    path: "/agents/v2/executions/{executionId}/sync",
+    args: [
+      {
+        name: "executionId",
+        flag: "execution-id",
+        type: "string",
+        required: true
+      }
+    ],
+    query: [
+      {
+        name: "timeoutSeconds",
+        flag: "timeout-seconds",
+        type: "integer",
+        required: false,
+        description: "Seconds to wait for the execution to finish before returning 202. Defaults to 25."
+      }
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
   {
     command: "insight get",
     tool: "insight_get",
@@ -4907,6 +4935,26 @@ var COMMANDS = [
     readOnly: false,
     destructive: false
   },
+  {
+    command: "workflow head validate",
+    tool: "workflow_head_validate",
+    title: "Validate workflow head",
+    description: 'Check the workflow\'s editable head the way publish and run do, without changing it. Returns blocking errors and advisory warnings, each with the path of the field it names, such as ["nodes", "Login", "model"]. Use after `workflow_files_patch` and before `workflow_head_publish`; an empty `issues` list means the head can publish and run. The same list comes back on every `workflow_files_patch` response.',
+    method: "POST",
+    path: "/agents/v2/workflows/{workflowId}/head/validate",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true
+      }
+    ],
+    query: [],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
   {
     command: "workflow list",
     tool: "workflow_list",
@@ -6580,15 +6628,16 @@ function defineCommands(root, options, dotted2 = /* @__PURE__ */ new Map(), onIn
       (arg) => options.defaultArg?.(command, arg)
     );
     const defaulted = defaults[0] !== void 0;
+    const optional = (arg, i) => i === 0 && defaulted || !arg.required;
     command.args.forEach((arg) => {
       leaf.argument(
-        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
+        defaulted || !arg.required ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? ""
       );
     });
     if (defaulted) {
       const names = command.args.map(
-        (arg, i) => i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`
+        (arg, i) => optional(arg, i) ? `[${arg.flag}]` : `<${arg.flag}>`
       );
       leaf.usage(`[options] ${names.join(" ")}`);
     }
@@ -6605,8 +6654,9 @@ ${notes.join("\n")}`);
       if (positionals.length === command.args.length - 1 && defaults[0] !== void 0) {
         positionals = [defaults[0], ...positionals];
       }
-      if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a, i) => i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
+      const required = command.args.filter((arg) => arg.required).length;
+      if (positionals.length < required || positionals.length > command.args.length) {
+        const expected = command.args.map((a, i) => optional(a, i) ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`
         );
@@ -6904,6 +6954,85 @@ function rejectUnknown(flags) {
   }
 }
 
+// src/sync/types.ts
+var MANIFEST = ".asteroid.json";
+function get(path, query = {}) {
+  return { method: "GET", path, query: new URLSearchParams(query) };
+}
+function statusOf(error) {
+  const status = error?.status;
+  return typeof status === "number" ? status : void 0;
+}
+
+// src/sync/execution-wait.ts
+var WAIT_TIMEOUT_SECONDS = 600;
+var WAIT_INTERVAL_SECONDS = 15;
+var MAX_WAIT_TIMEOUT_SECONDS = 3600;
+var MAX_WAIT_INTERVAL_SECONDS = 120;
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "cancelled", "failed"]);
+function isTerminalExecutionStatus(status) {
+  return TERMINAL.has(status);
+}
+var SYNC_TIMEOUT_SECONDS = 25;
+function pause(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function readStatus(sync, executionId2, timeoutMs) {
+  if (timeoutMs <= 0)
+    return await sync.remote.json(
+      get(`/agents/v2/executions/${executionId2}`)
+    );
+  const timeoutSeconds = Math.min(
+    SYNC_TIMEOUT_SECONDS,
+    Math.max(1, Math.ceil(timeoutMs / 1e3))
+  );
+  const response = await sync.remote.json(
+    get(`/agents/v2/executions/${executionId2}/sync`, {
+      timeoutSeconds: String(timeoutSeconds)
+    })
+  );
+  return {
+    id: response.executionId,
+    status: response.status,
+    executionResult: response.executionResult
+  };
+}
+async function waitForExecution(sync, options) {
+  const timeoutMs = (options.timeoutSeconds ?? WAIT_TIMEOUT_SECONDS) * 1e3;
+  const intervalMs = (options.intervalSeconds ?? WAIT_INTERVAL_SECONDS) * 1e3;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? pause;
+  const started = now();
+  let polls = 0;
+  for (; ; ) {
+    const called = now();
+    const execution = await readStatus(
+      sync,
+      options.executionId,
+      timeoutMs - (called - started)
+    );
+    polls++;
+    const elapsed = now() - started;
+    const waitedSeconds = Math.round(elapsed / 1e3);
+    if (isTerminalExecutionStatus(execution.status))
+      return { execution, terminal: true, waitedSeconds, polls };
+    const remaining = timeoutMs - elapsed;
+    if (remaining <= 0)
+      return { execution, terminal: false, waitedSeconds, polls };
+    const early = intervalMs - (now() - called);
+    if (early > 0) await sleep(Math.min(early, remaining));
+  }
+}
+function formatExecutionWait(result) {
+  const { execution } = result;
+  if (!result.terminal) {
+    return `Execution ${execution.id} still ${execution.status} after ${result.waitedSeconds}s. Wait again, or read what it has so far with \`asteroid execution pull ${execution.id}\`.`;
+  }
+  const line2 = `Execution ${execution.id} ${execution.status}.`;
+  const outcome = execution.executionResult;
+  return outcome ? `${line2} Result: ${outcome.outcome}: ${outcome.reasoning}` : line2;
+}
+
 // src/sync/commands.ts
 function option(name, type, description, extra = {}) {
   return { name, flag: name, type, required: false, description, ...extra };
@@ -6915,6 +7044,12 @@ var local = {
   destructive: false,
   local: true
 };
+var executionId = {
+  name: "executionId",
+  flag: "execution-id",
+  type: "string",
+  required: true
+};
 var SYNC_COMMANDS = [
   {
     ...local,
@@ -6923,14 +7058,7 @@ var SYNC_COMMANDS = [
     title: "Pull an execution to disk",
     description: "Write an execution to `<workflow-name>/executions/<id>/`: summary.json, activities.md (the step-by-step log), and the files the run produced.",
     readOnly: true,
-    args: [
-      {
-        name: "executionId",
-        flag: "execution-id",
-        type: "string",
-        required: true
-      }
-    ],
+    args: [executionId],
     query: [
       option(
         "files",
@@ -6956,6 +7084,54 @@ var SYNC_COMMANDS = [
         "Write here instead of `<workflow-name>/executions/<id>/` under the current directory."
       )
     ]
+  },
+  {
+    ...local,
+    command: "execution wait",
+    tool: "execution_wait",
+    title: "Wait for an execution to end",
+    description: "Poll an execution until it is completed, failed or cancelled, then print its status and, when the run produced one, its result. When the timeout passes first, print the status it still has, so you can wait again.",
+    readOnly: true,
+    args: [executionId],
+    query: [
+      option(
+        "timeout",
+        "integer",
+        `Give up after this many seconds, ${WAIT_TIMEOUT_SECONDS} unless set, ${MAX_WAIT_TIMEOUT_SECONDS} at most.`
+      ),
+      option(
+        "interval",
+        "integer",
+        `Poll every this many seconds, ${WAIT_INTERVAL_SECONDS} unless set, ${MAX_WAIT_INTERVAL_SECONDS} at most.`
+      )
+    ]
+  },
+  {
+    ...local,
+    command: "insight pull",
+    tool: "insight_pull",
+    title: "Pull insights to disk",
+    description: "Write insights to `insights/<name>.md`, one markdown file each with YAML frontmatter (id, type, status, name, next_steps). Name an insight to pull that one. A file another insight or an unpushed draft already holds keeps its name; the pulled one gets a -2, -3 suffix.",
+    readOnly: true,
+    args: [
+      {
+        name: "insightId",
+        flag: "insight-id",
+        type: "string",
+        required: false,
+        description: "One insight to pull. Without it, every insight, or one workflow's with --workflow-id."
+      }
+    ],
+    query: [
+      option("workflowId", "string", "Only this workflow's insights.", {
+        flag: "workflow-id"
+      }),
+      option(
+        "dir",
+        "string",
+        "Write here instead of `insights/` under the current directory."
+      )
+    ]
   }
 ];
 
@@ -7068,6 +7244,13 @@ function normalizeNodeName(name) {
   }
   return result;
 }
+function lossySlugOr(name, fallback) {
+  try {
+    return normalizeNodeName(name);
+  } catch {
+    return fallback;
+  }
+}
 function nodeDirName(name) {
   if (isNameCharsetConforming(name)) {
     return name.replaceAll(" ", "_");
@@ -7081,8 +7264,8 @@ function agentDirName(name) {
     return "agent";
   }
 }
-function executionDirName(executionId) {
-  return executionId.slice(0, 8);
+function executionDirName(executionId2) {
+  return executionId2.slice(0, 8);
 }
 function workflowDirName(workflowId, version, parentId, parentVersion) {
   const short = workflowId.slice(0, 8);
@@ -7130,16 +7313,6 @@ function matchesGlob(path, pattern) {
   return new RegExp(`^${source}$`).test(path);
 }
 
-// src/sync/types.ts
-var MANIFEST = ".asteroid.json";
-function get(path, query = {}) {
-  return { method: "GET", path, query: new URLSearchParams(query) };
-}
-function statusOf(error) {
-  const status = error?.status;
-  return typeof status === "number" ? status : void 0;
-}
-
 // src/sync/execution-pull.ts
 var DIRECTORIES = ["workspace", "downloads", "shared"];
 function relativeFilePath(file) {
@@ -7177,14 +7350,14 @@ async function writeActivities(sync, dir, execution) {
     return false;
   }
 }
-async function listFiles(sync, executionId) {
+async function listFiles(sync, executionId2) {
   const listing = await sync.remote.json(
-    get(`/agents/v2/executions/${executionId}/files`)
+    get(`/agents/v2/executions/${executionId2}/files`)
   );
   return DIRECTORIES.flatMap((name) => listing.directories[name] ?? []);
 }
-async function download(sync, executionId, file) {
-  const path = `/agents/v2/executions/${executionId}/files/${file.id}/signed-url`;
+async function download(sync, executionId2, file) {
+  const path = `/agents/v2/executions/${executionId2}/files/${file.id}/signed-url`;
   const { url } = await sync.remote.json(get(path));
   return sync.remote.download(url);
 }
@@ -7312,6 +7485,114 @@ ${result.skipped.map((s) => `  - ${s}`).join("\n")}` : null,
   ].filter(Boolean).join("\n");
 }
 
+// src/sync/insight-file.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)(?:\r?\n)?/;
+function serializeInsightFile(meta, body) {
+  const front = {};
+  if (meta.id) front.id = meta.id;
+  front.type = meta.type;
+  if (meta.status) front.status = meta.status;
+  front.name = meta.name;
+  if (meta.nextSteps) front.next_steps = meta.nextSteps;
+  const yaml = stringifyYaml(front).trimEnd();
+  return `---
+${yaml}
+---
+
+${body}`;
+}
+function insightFileId(text2) {
+  const match = FRONTMATTER.exec(text2);
+  if (!match) return void 0;
+  try {
+    const id = parseYaml(match[1])?.id;
+    return typeof id === "string" || typeof id === "number" ? String(id) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/sync/insight-pull.ts
+var INSIGHTS_DIR = "insights";
+var PAGE_SIZE = 100;
+async function listInsights(sync, workflowId) {
+  const all = [];
+  for (let page = 1; ; page++) {
+    const query = {
+      page: String(page),
+      pageSize: String(PAGE_SIZE)
+    };
+    if (workflowId) query.workflowId = workflowId;
+    const { items, total } = await sync.remote.json(
+      get("/astro/v2/insights", query)
+    );
+    all.push(...items);
+    if (items.length === 0 || all.length >= total) return all;
+  }
+}
+async function stemOwners(sync, dir) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const name of await sync.files.list(dir)) {
+    if (!name.endsWith(".md") || name.includes("/")) continue;
+    const bytes = await sync.files.read(join(dir, name));
+    const text2 = bytes ? Buffer.from(bytes).toString("utf8") : "";
+    owners.set(name.slice(0, -".md".length).toLowerCase(), insightFileId(text2));
+  }
+  return owners;
+}
+function assignStems(owners, insights) {
+  const used = /* @__PURE__ */ new Set();
+  const heldByOther = (stem, id) => owners.has(stem) && owners.get(stem) !== id;
+  return insights.map((insight) => {
+    const base = lossySlugOr(insight.name, "insight");
+    let stem = base;
+    for (let n = 2; used.has(stem) || heldByOther(stem, insight.id); n++) {
+      stem = `${base}-${n}`;
+    }
+    used.add(stem);
+    return [insight, stem];
+  });
+}
+async function pullInsights(sync, options = {}) {
+  const dir = options.dir ?? INSIGHTS_DIR;
+  const insights = options.insightId ? [
+    await sync.remote.json(
+      get(`/astro/v2/insights/${options.insightId}`)
+    )
+  ] : await listInsights(sync, options.workflowId);
+  const pulled = [];
+  for (const [insight, stem] of assignStems(
+    await stemOwners(sync, dir),
+    insights
+  )) {
+    const path = join(dir, `${stem}.md`);
+    const text2 = serializeInsightFile(
+      {
+        id: insight.id,
+        type: insight.type,
+        status: insight.status,
+        name: insight.name,
+        nextSteps: insight.nextSteps ?? void 0
+      },
+      insight.content
+    );
+    await sync.files.write(path, Buffer.from(text2, "utf8"));
+    const { id, name, type, status } = insight;
+    pulled.push({ id, name, type, status, path });
+  }
+  return { dir, insights: pulled };
+}
+function formatInsightPull(result) {
+  const count = result.insights.length;
+  return [
+    `Pulled ${count} insight${count === 1 ? "" : "s"} into ${result.dir}/.`,
+    ...result.insights.map(
+      (insight) => `  - ${insight.path}: ${insight.name} (${insight.type}, ${insight.status})`
+    )
+  ].join("\n");
+}
+
 // src/sync/manifest.ts
 async function loadManifest(sync, dir) {
   const bytes = await sync.files.read(join(dir, MANIFEST));
@@ -7603,7 +7884,7 @@ function conflict(manifest) {
 }
 async function patch(sync, manifest, writes, deletes) {
   try {
-    await sync.remote.json({
+    const snapshot = await sync.remote.json({
       method: "PATCH",
       path: `/agents/v2/workflows/${manifest.workflowId}/head/files`,
       query: new URLSearchParams(),
@@ -7616,7 +7897,7 @@ async function patch(sync, manifest, writes, deletes) {
         deletes
       }
     });
-    return "applied";
+    return { issues: snapshot?.issues ?? [] };
   } catch (error) {
     if (statusOf(error) !== 409) throw error;
     return "conflict";
@@ -7686,14 +7967,20 @@ async function pushWorkflow(sync, dir, workflowId, options = {}) {
     if (writes.length === 0 && deletes.length === 0) {
       return { ...result, rev: manifest.rev, versionId: manifest.versionId };
     }
-    if (await patch(sync, manifest, writes, deletes) === "applied") {
+    const applied = await patch(sync, manifest, writes, deletes);
+    if (applied !== "conflict") {
       const next = await refresh(
         sync,
         dir,
         manifest,
         new Map(writes.map((w) => [w.path, w.hash]))
       );
-      return { ...result, rev: next.rev, versionId: next.versionId };
+      return {
+        ...result,
+        rev: next.rev,
+        versionId: next.versionId,
+        issues: applied.issues
+      };
     }
     if (!options.rebase || attempt >= REBASE_ATTEMPTS) throw conflict(manifest);
     rebasedFrom ??= manifest.rev;
@@ -7709,9 +7996,23 @@ function formatWorkflowPush(result) {
     `Pushed to workflow ${result.workflowId}: ${result.written.length} written, ${result.deleted.length} deleted.${rebased}`,
     ...result.written.map((path) => `  + ${path}`),
     ...result.deleted.map((path) => `  - ${path}`),
-    `Head is now rev ${result.rev} (version ${result.versionId}).`
+    `Head is now rev ${result.rev} (version ${result.versionId}).`,
+    ...formatIssues(result.issues ?? [])
   ].join("\n");
 }
+function formatIssues(issues) {
+  if (issues.length === 0) return [];
+  const errors = issues.filter((issue) => issue.severity === "error").length;
+  const warnings = issues.length - errors;
+  const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+  const summary2 = errors === 0 ? `Validation: ${count(warnings, "warning")}, nothing blocks a publish.` : `Validation: ${count(errors, "error")}${warnings > 0 ? `, ${count(warnings, "warning")}` : ""}. Fix the errors before you publish.`;
+  return [
+    summary2,
+    ...issues.map(
+      (issue) => `  ${issue.severity === "error" ? "!" : "?"} ${issue.path.join("/") || "(workflow)"}: ${issue.message}`
+    )
+  ];
+}
 
 // src/sync/run.ts
 function flag(parsed, name) {
@@ -7724,6 +8025,35 @@ function integer(parsed, name) {
     throw new UsageError(`--${name} must be a whole number`);
   return Number(raw);
 }
+function bounded(parsed, name, min, max) {
+  const value2 = integer(parsed, name);
+  if (value2 === void 0) return void 0;
+  if (value2 < min || value2 > max)
+    throw new UsageError(`--${name} must be between ${min} and ${max}`);
+  return value2;
+}
+function executionWaitOptions(parsed) {
+  return {
+    executionId: parsed.positionals[0],
+    timeoutSeconds: bounded(parsed, "timeout", 0, MAX_WAIT_TIMEOUT_SECONDS),
+    intervalSeconds: bounded(parsed, "interval", 1, MAX_WAIT_INTERVAL_SECONDS)
+  };
+}
+function given(value2, name) {
+  if (value2 === void 0) return void 0;
+  if (value2 === "") throw new UsageError(`${name} must not be empty`);
+  return value2;
+}
+function insightPullOptions(parsed) {
+  const options = {};
+  const insightId = given(parsed.positionals[0], "<insight-id>");
+  if (insightId) options.insightId = insightId;
+  const workflowId = given(flag(parsed, "workflow-id"), "--workflow-id");
+  if (workflowId) options.workflowId = workflowId;
+  const dir = given(flag(parsed, "dir"), "--dir");
+  if (dir) options.dir = dir;
+  return options;
+}
 function executionOptions(parsed) {
   const summaryOnly = flag(parsed, "summary-only") === "true";
   const glob = flag(parsed, "files");
@@ -7785,6 +8115,20 @@ async function execute(command, parsed, sync, deps) {
     );
     return { result: result2, text: formatWorkflowPush(result2) };
   }
+  if (command.command === "execution wait") {
+    const result2 = await waitForExecution(sync, {
+      ...executionWaitOptions(parsed),
+      ...deps.executionWait
+    });
+    return { result: result2, text: formatExecutionWait(result2) };
+  }
+  if (command.command === "insight pull") {
+    const result2 = await pullInsights(sync, {
+      ...deps.insightPull,
+      ...insightPullOptions(parsed)
+    });
+    return { result: result2, text: formatInsightPull(result2) };
+  }
   if (command.command !== "execution pull")
     throw new UsageError(`unknown command ${command.command}`);
   const result = await pullExecution(sync, {
@@ -7807,15 +8151,20 @@ async function runSync(command, parsed, deps) {
 export {
   ALL_COMMANDS,
   COMMANDS,
+  INSIGHTS_DIR,
   MANIFEST,
   SYNC_COMMANDS,
   UsageError,
   buildRequest,
   formatActivitiesMarkdown,
   formatExecutionPull,
+  formatExecutionWait,
+  formatInsightPull,
   formatWorkflowPull,
   formatWorkflowPush,
   headFilesRequest,
+  insightFileId,
+  isTerminalExecutionStatus,
   leadingWords,
   loadManifest,
   matchCommand,
@@ -7823,12 +8172,15 @@ export {
   parseInvocation,
   pullDir,
   pullExecution,
+  pullInsights,
   pullWorkflow,
   pushWorkflow,
   readManifest,
   render,
   runSync,
   runsLocally,
+  serializeInsightFile,
+  waitForExecution,
   withSyncCommands,
   writeManifest
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteroidai/cli",
-  "version": "1.9.115",
+  "version": "1.9.123",
   "description": "The asteroid command-line interface for the Asteroid platform.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,8 @@
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0",
     "env-paths": "^4.0.0",
-    "proper-lockfile": "^4.1.2"
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
@@ -33,7 +34,6 @@
     "tsx": "^4.23.12",
     "typescript": "5.9.3",
     "vitest": "^4.1.11",
-    "yaml": "^2.9.0",
     "@asteroid/workflow-files": "0.1.0"
   },
   "scripts": {