foldrun 2.2.0 → 2.4.0

package/src/commands.mjs

@@ -440,20 +440,34 @@ async function remoteListCmd(kind, flags, layout) {
   const url = platformFor(flags, `${one} ls`);
   const ws = platformWorkspace(flags, layout, `${one} ls`);
   const r = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/${kind}`);
-  const list = r[kind] ?? [];
+  let list = r[kind] ?? [];
+  // --stale [days]: the agents nobody has run lately — with a number, not
+  // run in that many days (never run included); bare, the ones past the
+  // workspace's alerts: stale_days, as the platform counts them.
+  if (kind === "agents" && flags.stale !== undefined) {
+    const days = flags.stale === true ? null : Number(flags.stale);
+    if (days !== null && !(Number.isInteger(days) && days > 0)) throw new Error(`--stale takes a whole number of days, e.g. --stale 30 — not "${flags.stale}"`);
+    list = list.filter((x) => (days === null ? x.stale === true : !x.lastRunAt || Date.now() - Date.parse(x.lastRunAt) >= days * 86_400_000));
+  }
   if (flags.json === true) {
     console.log(JSON.stringify(list, null, 2));
     return 0;
   }
   if (!list.length) {
-    console.log(`\n  ${c.dim(`no ${kind} in ${ws} on ${url} — \`foldrun ${one} new <name> --platform --to ${ws}\` makes one`)}\n`);
+    console.log(`\n  ${c.dim(flags.stale !== undefined ? `no stale agents in ${ws}` : `no ${kind} in ${ws} on ${url} — \`foldrun ${one} new <name> --platform --to ${ws}\` makes one`)}\n`);
     return 0;
   }
   const w = Math.max(...list.map((x) => x.name.length));
+  // Who answers for each one (owner:, or the workspace's, or the account's);
+  // the column only when someone is named, so a list with none is unchanged.
+  const ow = kind === "agents" ? Math.max(0, ...list.map((x) => (x.owner ?? "").length)) : 0;
   console.log();
   for (const x of list) {
     if (kind === "agents") {
-      console.log(`  ${c.bold(pad(x.name, w))}  ${pad(x.model ?? "", 8)} ${c.dim(firstLine(x.description ?? "", 80))}`);
+      const owner = ow ? `${pad(x.owner ?? "—", Math.max(ow, 1))}  ` : "";
+      // When it last ran, from a platform that says (lastRunAt is absent before it did).
+      const ran = "lastRunAt" in x ? `${pad(x.lastRunAt ? `${Math.floor((Date.now() - Date.parse(x.lastRunAt)) / 86_400_000)}d ago` : "never", 7)} ` : "";
+      console.log(`  ${c.bold(pad(x.name, w))}  ${pad(x.model ?? "", 8)} ${ran}${owner}${x.stale ? c.amber("stale ") : ""}${c.dim(firstLine(x.description ?? "", 80))}`);
     } else {
       const when = x.trigger === "schedule" && x.schedule ? `schedule ${x.schedule}${x.timezone ? ` ${x.timezone}` : ""}` : (x.trigger ?? "manual");
       console.log(`  ${c.bold(pad(x.name, w))}  ${c.dim(when)}`);
@@ -973,7 +987,7 @@ async function checkWorkspace(workspace, flags, opts) {
     let accountNetwork;
     try {
       const md = path.join(accountRoot, "AGENTS.md");
-      if (md !== path.join(workspace, "AGENTS.md") && fs.existsSync(md)) accountNetwork = (await import("gray-matter")).default(fs.readFileSync(md, "utf8")).data?.network;
+      if (md !== path.join(workspace, "AGENTS.md") && fs.existsSync(md)) accountNetwork = (await import("gray-matter")).default(fs.readFileSync(md, "utf8"), {}).data?.network;
     } catch {
       // an unreadable account AGENTS.md is reported by its own check
     }
@@ -1228,12 +1242,17 @@ async function checkProblems(workspace, flags = {}) {
     if (webWarnings) {
       try {
         const matter = (await import("gray-matter")).default;
-        const front = matter(fs.readFileSync(path.join(workspace, "agents", a.name, "agent.md"), "utf8")).data ?? {};
+        // `{}`: gray-matter caches a failed parse as an empty success without it.
+        const front = matter(fs.readFileSync(path.join(workspace, "agents", a.name, "agent.md"), "utf8"), {}).data ?? {};
         for (const w of webWarnings(front, runnerBrowsers)) note("warn", `agents/${a.name}`, w);
       } catch {
         // an unreadable agent.md is already reported by the loader
       }
     }
+    // agent.md whose YAML does not parse: core lists it with defaults and the
+    // reason (core 2.5) rather than throwing; the file is unreadable to a run.
+    const frontmatterError = /** @type {{ frontmatterError?: string }} */ (a).frontmatterError;
+    if (frontmatterError) note("error", `agents/${a.name}`, frontmatterError);
     // `schedule:` on an agent fires nothing — only a flow has a clock.
     if (a.scheduleProblem) note("error", `agents/${a.name}`, a.scheduleProblem);
     // `language:` that is not a tag — "Persian" where `fa` was meant.
@@ -5250,10 +5269,11 @@ async function rerunCmd(runId, flags, layout) {
   const ws = await workspaceOfRun(url, flags, layout, runId);
   const body = await remoteCall(url, flags, `/api/workspaces/${ws}/runs/${runId}/rerun`, {
     method: "POST",
-    body: JSON.stringify(agent ? { agent } : { step: from }),
+    // --instruction: what that step is told this once (FOL-72 step 6).
+    body: JSON.stringify({ ...(agent ? { agent } : { step: from }), ...(typeof flags.instruction === "string" ? { instruction: flags.instruction } : {}) }),
   });
   const id = body.runId ?? body.id;
-  console.log(`\n  ${c.green("✓")} ${c.bold(id)}  ${c.dim(`${ws} · again from ${agent ? `agent ${agent}` : `step ${from}`} of ${runId} · ${body.steps ?? "?"} steps`)}`);
+  console.log(`\n  ${c.green("✓")} ${c.bold(id)}  ${c.dim(`${ws} · again from ${agent ? `agent ${agent}` : `step ${from}`} of ${runId} · ${body.steps ?? "?"} steps${typeof flags.instruction === "string" ? " · with your instruction for that step" : ""}`)}`);
   console.log(`  ${c.dim(`foldrun logs ${id} --to ${ws}${flags.wait === true ? "" : " · --wait follows it"}`)}\n`);
   if (flags.wait !== true) return 0;
   return logsCmd([id], { ...flags, follow: true, to: ws }, layout);
@@ -5573,6 +5593,234 @@ function printDefaults(d) {
   console.log(`  notify       ${notify}`);
   console.log(`  budget       ${d.budget ? `$${d.budget.usd} per ${d.budget.period}` : c.dim("no cap")}`);
   console.log(`  concurrency  ${d.concurrency ?? c.dim("the plan's number")}`);
+  console.log(`  deploy_block ${d.deployBlock && d.deployBlock !== "none" ? `${d.deployBlock} ${c.dim(d.deployBlock === "secrets" ? "— a written-in key refuses a deploy" : "— any security finding refuses a deploy")}` : c.dim("none — security findings only warn")}`);
+  console.log(`  network      ${networkEnforceText(d.networkEnforce, "the install")}`);
+}
+
+/** network_enforce: as a person reads it. Off is never "allowed" outright:
+ *  the level above (the account, or the install's own switch) may refuse
+ *  anyway, and this file cannot see either, so off says what it leaves to. */
+function networkEnforceText(on, above) {
+  return on ? `refused ${c.dim("— a site off an agent's network: list gets a 403")}` : c.dim(`${above}'s — this file does not ask to refuse`);
+}
+
+/** `on`/`off` (or true/false, yes/no) for network_enforce, or an error. */
+function onOff(key, value, how) {
+  const v = String(value ?? "").toLowerCase();
+  if (["on", "true", "yes"].includes(v)) return true;
+  if (["off", "false", "no"].includes(v)) return false;
+  throw new Error(`${key} is on or off — e.g. \`${how}\` — not "${value ?? ""}"`);
+}
+
+/**
+ * `foldrun account telemetry` — where each finished run goes as an
+ * OpenTelemetry trace (the account's `telemetry:`). `set <url> --header
+ * authorization=\${OTEL_TOKEN}`, `clear`, `test` (POST …/telemetry/test:
+ * one made-up run, and what the collector answered).
+ */
+async function telemetryCmd(url, args, flags) {
+  const [sub, endpoint] = args;
+  if (!sub) {
+    const { defaults } = await remoteCall(url, flags, "/api/account");
+    const t = defaults?.telemetry;
+    if (!t) {
+      console.log(`\n  ${c.dim("runs are not sent anywhere — foldrun account telemetry set https://<collector>/v1/traces --header authorization=\${OTEL_TOKEN}")}\n`);
+      return 0;
+    }
+    console.log(`\n  ${c.bold("telemetry")}  ${t.endpoint}`);
+    for (const [k, v] of Object.entries(t.headers ?? {})) console.log(`  ${c.dim(k)}  ${v}`);
+    console.log();
+    return 0;
+  }
+  if (sub === "test") {
+    const r = await remoteCall(url, flags, "/api/account/telemetry/test", { method: "POST", body: "{}" });
+    if (r.ok) console.log(`\n  ${c.green("✓")} ${r.endpoint} took it — ${r.spans} spans, HTTP ${r.status}. Look for the trace "run foldrun-telemetry-test".\n`);
+    else console.log(`\n  ${c.red("✗")} not delivered to ${r.endpoint} — ${r.error}\n`);
+    return r.ok ? 0 : 1;
+  }
+  if (sub === "clear") {
+    await remoteCall(url, flags, "/api/account", { method: "PATCH", body: JSON.stringify({ telemetry: null }) });
+    console.log(`\n  ${c.green("✓")} runs are no longer sent\n`);
+    return 0;
+  }
+  if (sub !== "set") throw new Error(`unknown telemetry verb "${sub}" — set <url> [--header name=\${SECRET}], clear, test (bare: show it)`);
+  if (!endpoint) throw new Error("`foldrun account telemetry set https://<collector>/v1/traces --header authorization=${OTEL_TOKEN}`");
+  const headers = {};
+  for (const h of [flags.header].flat().filter((x) => typeof x === "string")) {
+    const i = h.indexOf("=");
+    if (i < 1) throw new Error(`--header is name=value, e.g. --header authorization='\${OTEL_TOKEN}' — not "${h}"`);
+    headers[h.slice(0, i).trim().toLowerCase()] = h.slice(i + 1).trim();
+  }
+  const r = await remoteCall(url, flags, "/api/account", { method: "PATCH", body: JSON.stringify({ telemetry: { otlp: endpoint, ...(Object.keys(headers).length ? { headers } : {}) } }) });
+  console.log(`\n  ${c.green("✓")} every run that finishes is sent to ${r.defaults?.telemetry?.endpoint ?? endpoint} — \`foldrun account telemetry test\` proves it arrives\n`);
+  return 0;
+}
+
+// ---------------------------------------------------------- the four jobs
+//
+// governance, guardrail, observability, evaluation — what each AGENTS.md
+// field does, as the platform maps it (GET /api/account/jobs). The CLI reads
+// the map from the platform rather than from @foldrun/core, so it always
+// matches the platform it is talking to.
+
+/** GET /api/account/jobs, for the account or one workspace. */
+function jobsOf(url, flags, workspace) {
+  return remoteCall(url, flags, `/api/account/jobs${workspace ? `?workspace=${enc(workspace)}` : ""}`);
+}
+
+/**
+ * `governance.deploy_block` → `deploy_block`, checked against the map: a
+ * field written under the wrong job is refused with the right one named.
+ * A bare key comes back as it was, with no request.
+ */
+async function jobKey(url, flags, key, workspace) {
+  if (typeof key !== "string" || !key.includes(".")) return { key, view: null };
+  const job = key.slice(0, key.indexOf("."));
+  const field = key.slice(key.indexOf(".") + 1);
+  const view = await jobsOf(url, flags, workspace);
+  const j = view.jobs.find((x) => x.name === job);
+  if (!j) throw new Error(`"${job}" is not one of the four jobs — governance, guardrail, observability, evaluation`);
+  const f = j.fields.find((x) => x.key === field);
+  if (!f) {
+    const right = view.jobs.find((x) => x.fields.some((y) => y.key === field));
+    throw new Error(right ? `${field} is a ${right.name} setting, not a ${job} one — \`${right.name}.${field}\`` : `${job} has no setting "${field}" — it holds ${j.fields.map((y) => y.key).join(", ")}`);
+  }
+  // `writable` says what this scope's settings can write; the rest live in
+  // AGENTS.md itself. A server too old to say leaves it to the PATCH.
+  if (f.writable === false) {
+    throw new Error(`${job}.${field} is not set from here — write \`${field}:\` in ${workspace ? `workspaces/${workspace}/AGENTS.md` : "the account's AGENTS.md"} (under \`${job}:\` or at the top) and deploy`);
+  }
+  return { key: field, view };
+}
+
+/** The value a field has at one level (the account's, or the workspace's). */
+async function jobValue(url, flags, key, workspace, view) {
+  const v = view ?? (await jobsOf(url, flags, workspace));
+  for (const j of v.jobs) {
+    const f = j.fields.find((x) => x.key === key);
+    if (f) return workspace ? f.workspace : f.account;
+  }
+  return null;
+}
+
+/**
+ * `set alerts <threshold> <value>` and `set judge model|effort <value>` —
+ * one entry merged into the block as it stands (the platform replaces a
+ * block whole). `off` removes the entry. A workspace's alerts, once its own,
+ * stay its own: the last threshold removed leaves `{}` ("none here"), and
+ * `new_host off` is written as false so the account's `on` does not apply;
+ * `clear alerts` goes back to the account's.
+ */
+async function mergedEntry(url, flags, key, args, workspace, view, how) {
+  const [entry, ...words] = args;
+  const raw = words.join(" ").trim();
+  const allowed = key === "alerts"
+    ? ["failure_rate", "min_runs", "credits_day", "run_minutes", "stale_days", "cost_spike", "runs_per_hour", "new_host"]
+    : ["model", "effort"];
+  if (!allowed.includes(entry)) throw new Error(`${how} <${allowed.join("|")}> <value> — not "${entry ?? ""}"`);
+  if (!raw) throw new Error(`${how} ${entry} <value> — or \`${entry} off\` to remove it`);
+  const current = { ...((await jobValue(url, flags, key, workspace, view)) ?? {}) };
+  if (raw === "off") delete current[entry];
+  else if (entry === "new_host") current.new_host = onOff("new_host", raw, `${how} new_host on`);
+  else current[entry] = key === "alerts" && entry !== "failure_rate" && /^\d+(\.\d+)?$/.test(raw) ? Number(raw) : raw;
+  const own = key === "alerts" && workspace;
+  // A workspace's `new_host: false` is an opt-out from the account's on —
+  // kept whatever else is edited; at the account false is just unset.
+  if (own && entry === "new_host" && raw === "off") current.new_host = false;
+  else if (!own && current.new_host === false) delete current.new_host;
+  if (own) return current;
+  return Object.keys(current).length ? current : null;
+}
+
+/** A setting's value as one short line. */
+function shortValue(v) {
+  if (v === null || v === undefined) return null;
+  return typeof v === "object" ? JSON.stringify(v).replace(/"([a-z_]+)":/g, "$1: ").replace(/,/g, ", ") : String(v);
+}
+
+/**
+ * `foldrun jobs [--to <workspace>]` — the four jobs and every AGENTS.md
+ * field of each: the account's value, the workspace's, and how the two
+ * combine (they do not all simply override — network_enforce is on if
+ * either turns it on, both budgets apply).
+ */
+async function jobsCmd(flags, layout) {
+  const url = platformFor(flags, "jobs");
+  const ws = typeof flags.to === "string" ? flags.to : null;
+  const view = await jobsOf(url, flags, ws);
+  if (flags.json === true) {
+    console.log(JSON.stringify(view, null, 2));
+    return 0;
+  }
+  console.log(`\n  ${c.bold("The four jobs")}  ${c.dim(ws ? `workspace ${ws}, over the account's` : "the account — every workspace inherits these")}`);
+  for (const j of view.jobs) {
+    console.log(`\n  ${c.bold(j.title)}  ${c.dim(j.what)}`);
+    const w = Math.max(...j.fields.map((f) => f.key.length));
+    for (const f of j.fields) {
+      const account = shortValue(f.account);
+      if (!ws) {
+        console.log(`    ${pad(f.key, w)}  ${account ?? c.dim("unset")}`);
+        continue;
+      }
+      const here = shortValue(f.workspace);
+      const how = f.combine ? c.dim(`  · ${f.combine}`) : "";
+      console.log(`    ${pad(f.key, w)}  ${here ?? c.dim("unset")}${c.dim(`  account: ${account ?? "unset"}`)}${how}`);
+    }
+  }
+  console.log(`\n  ${c.dim(`set one: foldrun ${ws ? `workspace set <job>.<field> … --to ${ws}` : "account set <job>.<field> …"} — e.g. governance.deploy_block secrets`)}\n`);
+  return 0;
+}
+
+/** A GET …/pause, or null from a platform older than the kill switch —
+ *  the settings still print, without the line. */
+async function pauseState(request) {
+  try {
+    return await request;
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) return null;
+    throw err;
+  }
+}
+
+/** One pause mark as a line: since when, by whom, why. */
+function pauseLine(m) {
+  return `${m.at.slice(0, 16).replace("T", " ")} UTC by ${m.by}${m.reason ? ` — ${m.reason}` : ""}`;
+}
+
+/**
+ * `foldrun account pause|resume`, `foldrun workspace pause|resume` — the
+ * kill switch (POST / DELETE …/pause). Pausing is undone by a resume, so it
+ * asks nothing; --stop also stops the runs going now, which nothing undoes,
+ * so that asks.
+ */
+async function pauseCmd(flags, verb, what, { post, del }) {
+  if (verb === "resume") {
+    const r = await del();
+    const still = r.paused;
+    // An account resume leaves a workspace paused on its own paused.
+    const own = Object.keys(r.workspaces ?? {});
+    const held = still
+      ? c.amber(` — but still held: ${still.scope === "account" ? "the account" : "this workspace"} is paused (${pauseLine(still)})`)
+      : own.length
+        ? c.amber(` — but ${own.join(", ")} ${own.length === 1 ? "is" : "are"} paused on ${own.length === 1 ? "its" : "their"} own (\`foldrun workspace resume --to <name>\`)`)
+        : " — runs start again";
+    console.log(`\n  ${c.green("✓")} resumed ${what}${held}\n`);
+    return 0;
+  }
+  const stop = flags.stop === true;
+  if (stop && !(await confirmed(flags, "pause --stop", `Pause ${what} and stop every run going now? [y/N] `))) {
+    console.log(`\n  ${c.dim("nothing paused, nothing stopped")}\n`);
+    return 1;
+  }
+  const body = { ...(typeof flags.reason === "string" && flags.reason.trim() ? { reason: flags.reason.trim() } : {}), ...(stop ? { stop: true } : {}) };
+  const r = await post(JSON.stringify(body));
+  console.log(`\n  ${c.green("✓")} paused ${what} — no new run starts until \`resume\``);
+  if (stop) console.log(`  ${c.dim(`${r.stopped?.length ?? 0} run(s) stopped`)}`);
+  // A stop that failed is a run that may still be going: named, and the
+  // exit says so, rather than assumed to have finished on its own.
+  for (const f of r.failed ?? []) console.log(`  ${c.red("✗")} ${f.workspace}/${f.runId} not stopped — ${f.error}`);
+  console.log();
+  return r.failed?.length ? 1 : 0;
 }
 
 /**
@@ -5595,25 +5843,43 @@ async function accountCmd(positional, flags) {
   if (!verb) {
     const { defaults } = await remoteCall(url, flags, "/api/account");
     printDefaults(defaults ?? {});
+    const halt = await pauseState(remoteCall(url, flags, "/api/account/pause"));
+    const own = Object.keys(halt?.workspaces ?? {});
+    if (halt) console.log(`  paused       ${halt.account ? c.red(pauseLine(halt.account)) : c.dim("no")}${own.length ? c.dim(` · on their own: ${own.join(", ")}`) : ""}`);
     console.log(`\n  ${c.dim("foldrun account set timezone Australia/Sydney · set notify email you@example.com · set budget 60/month · clear budget")}\n`);
     return 0;
   }
   if (verb === "providers") return providersCmd(url, flags);
+  if (verb === "telemetry") return telemetryCmd(url, positional.slice(1), flags);
+  if (verb === "pause" || verb === "resume") {
+    return pauseCmd(flags, verb, "every workspace in the account", {
+      post: (body) => remoteCall(url, flags, "/api/account/pause", { method: "POST", body }),
+      del: () => remoteCall(url, flags, "/api/account/pause", { method: "DELETE" }),
+    });
+  }
   if (verb === "model") return accountModelCmd(url, positional.slice(1), flags);
   if (verb === "export") return accountExportCmd(url, flags);
   if (verb !== "set" && verb !== "clear") {
-    throw new Error(`unknown account verb "${verb}" — \`foldrun account\` shows them, \`set\` and \`clear\` change one, \`model\` is the account's own model key, \`providers\` checks the model keys, \`export\` downloads everything`);
+    throw new Error(`unknown account verb "${verb}" — \`foldrun account\` shows them, \`set\` and \`clear\` change one, \`model\` is the account's own model key, \`providers\` checks the model keys, \`export\` downloads everything, \`pause\`/\`resume\` the kill switch`);
   }
 
-  const key = positional[1];
-  const KEYS = ["timezone", "notify", "budget", "concurrency"];
+  // `governance.deploy_block` names the job; checked, then sent as the field.
+  const { key, view } = await jobKey(url, flags, positional[1], null);
+  // telemetry: is set with its own verb (an endpoint and headers, not one
+  // value); `clear` works here as for any other key.
+  if (key === "telemetry" && verb === "set") {
+    throw new Error("telemetry has its own verb — `foldrun account telemetry set <otlp-url> [--header name=value]`; `foldrun account clear telemetry` turns it off");
+  }
+  const KEYS = ["timezone", "notify", "budget", "concurrency", "deploy_block", "network_enforce", "owner", "alerts", "judge", ...(verb === "clear" ? ["telemetry"] : [])];
   if (!KEYS.includes(key)) {
-    throw new Error(`which setting? \`foldrun account ${verb} <${KEYS.join("|")}> …\``);
+    throw new Error(`which setting? \`foldrun account ${verb} <${KEYS.join("|")}> …\` — or <job>.<field>, e.g. governance.owner (\`foldrun jobs\` lists them)`);
   }
 
   let patch;
   if (verb === "clear") {
     patch = { [key]: null };
+  } else if (key === "alerts" || key === "judge") {
+    patch = { [key]: await mergedEntry(url, flags, key, positional.slice(2), null, view, `foldrun account set ${key}`) };
   } else if (key === "notify") {
     // `set notify email you@example.com` / `set notify url https://…`, and
     // --events to change what is notified on.
@@ -5647,7 +5913,13 @@ async function accountCmd(positional, flags) {
     if (key === "concurrency" && !/^\d+$/.test(value)) {
       throw new Error(`concurrency is a whole number of runs at once, e.g. \`foldrun account set concurrency 4\` — not "${value}"`);
     }
-    patch = { [key]: key === "concurrency" ? Number(value) : value };
+    // deploy_block (FOL-58): none | secrets | security.
+    if (key === "deploy_block" && !["none", "secrets", "security"].includes(value)) {
+      throw new Error(`deploy_block is none, secrets or security — e.g. \`foldrun account set deploy_block secrets\` — not "${value}"`);
+    }
+    patch = {
+      [key]: key === "concurrency" ? Number(value) : key === "network_enforce" ? onOff(key, value, "foldrun account set network_enforce on") : value,
+    };
   }
 
   const answer = await remoteCall(url, flags, "/api/account", { method: "PATCH", body: JSON.stringify(patch) });
@@ -5929,6 +6201,127 @@ const eventSteps = (run) =>
  * steps in one group is two decisions, and a list that folded them into one
  * line named one agent and asked neither question.
  */
+/** `foldrun runs views` — your saved run searches (FOL-72 step 9). */
+async function runViewsCmd(flags) {
+  const url = platformFor(flags, "runs");
+  const { runViews = [] } = await remoteCall(url, flags, "/api/me/preferences");
+  if (flags.json === true) return console.log(JSON.stringify(runViews, null, 2)), 0;
+  if (!runViews.length) return console.log(`\n  ${c.dim("no saved views — save one from the runs page's search")}\n`), 0;
+  console.log();
+  for (const v of runViews) console.log(`  ${c.bold(v.name)}  ${c.dim(v.query)}`);
+  console.log(`\n  ${c.dim("foldrun runs --view <name> opens one")}\n`);
+  return 0;
+}
+
+// ---------------------------------------------------------------- insights
+
+/** `foldrun insights` (FOL-72 step 8): recurring problems found in the runs,
+ *  with evidence, what they cost and what to do — GET /api/insights. */
+async function insightsCmd(flags) {
+  const url = platformFor(flags, "insights");
+  const qs = new URLSearchParams({ ...(flags.days !== undefined ? { days: String(flags.days) } : {}), ...(typeof flags.to === "string" ? { workspace: flags.to } : {}) });
+  const { insights = [], days = 7 } = await remoteCall(url, flags, `/api/insights${qs.size ? `?${qs}` : ""}`);
+  if (flags.json === true) return console.log(JSON.stringify(insights, null, 2)), 0;
+  if (!insights.length) {
+    console.log(`\n  ${c.dim(`nothing recurring in the last ${days} days`)}\n`);
+    return 0;
+  }
+  console.log();
+  for (const i of insights) {
+    const cost = i.credits ? ` · about ${i.credits.toLocaleString()} credits` : "";
+    console.log(`  ${c.amber("◆")} ${c.bold(i.title)}  ${c.dim(`${i.workspace} · ${i.steps} step${i.steps === 1 ? "" : "s"}${cost}`)}`);
+    for (const line of wrap(i.why, 84)) console.log(`      ${c.dim(line)}`);
+    for (const [k, line] of wrap(i.fix, 80).entries()) console.log(`      ${k === 0 ? "→ " : "  "}${line}`);
+    console.log(`      ${c.dim(i.evidence.map((e) => `${e.runId}#${e.step}`).join("  "))}`);
+    console.log();
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------- issues
+
+const ISSUE_VERBS = { ack: "acknowledge", acknowledge: "acknowledge", snooze: "snooze", resolve: "resolve", reopen: "reopen" };
+
+/** What the run doctor reads for an issue: its newest run, that run's
+ *  workspace, and the question the run page's Doctor asks — core's
+ *  issueDoctor (issues.ts), repeated here as the cache note is until the
+ *  next core release. Null for a missed schedule, which has no run. */
+function issueDoctor(issue) {
+  const run = (issue.runs ?? []).find((r) => !r.missed);
+  if (!run || issue.kind === "missed") return null;
+  const ended = issue.kind === "blocked" ? "end BLOCKED" : issue.kind === "bad" ? "end BAD" : "fail";
+  return { workspace: run.workspace, runId: run.id, prompt: `Doctor: why did run ${run.id} ${ended}, and how do I fix it?` };
+}
+
+/** `foldrun issues` (FOL-54 step 3): what went wrong, grouped, open until a
+ *  person resolves it; `foldrun issues ack|snooze|resolve|reopen <id>` acts
+ *  on one — the dashboard's Issues page and its buttons, same route.
+ *  `foldrun issues doctor <id>` is the card's Doctor: the run doctor on the
+ *  issue's newest run, in that run's workspace. */
+async function issuesCmd(positional, flags, layout) {
+  const url = platformFor(flags, "issues");
+  const [verb, id] = positional;
+  if (verb === "doctor") {
+    if (!id || !/^iss_[a-z0-9]{2,32}$/.test(id)) throw new Error("`foldrun issues doctor <issue-id>` — the id is the iss_… on each line of `foldrun issues`");
+    const { issue } = await remoteCall(url, flags, `/api/issues/${id}`);
+    const doc = issueDoctor(issue);
+    if (!doc) throw new Error(`${id} is a missed schedule: no run started, so there is nothing for the doctor to read — open the flow's schedule instead`);
+    return assistantCmd([doc.prompt], { ...flags, to: doc.workspace }, layout);
+  }
+  if (verb && verb !== "show") {
+    const action = ISSUE_VERBS[verb];
+    if (!action) throw new Error(`\`foldrun issues\` lists them; its verbs are show, doctor, ack, snooze, resolve, reopen — not ${verb}`);
+    if (!id || !/^iss_[a-z0-9]{2,32}$/.test(id)) throw new Error(`\`foldrun issues ${verb} <issue-id>\` — the id is the iss_… on each line of \`foldrun issues\``);
+    if (action === "snooze" && typeof flags.for !== "string" && typeof flags.until !== "string" && flags.times === undefined) throw new Error("a snooze takes --for 30m|4h|1d|1w, --until <ISO time>, or --times <n> (until it happens n more times)");
+    const body = {
+      action,
+      ...(typeof flags.for === "string" ? { for: flags.for } : {}),
+      ...(typeof flags.until === "string" ? { until: flags.until } : {}),
+      ...(flags.times !== undefined ? { times: Number(flags.times) } : {}),
+      ...(typeof flags.note === "string" ? { note: flags.note } : {}),
+    };
+    const { issue } = await remoteCall(url, flags, `/api/issues/${id}`, { method: "POST", body: JSON.stringify(body) });
+    if (flags.json === true) return console.log(JSON.stringify(issue, null, 2)), 0;
+    console.log(`\n  ${c.green("✓")} ${issue.id} is ${issue.status}${issue.snoozedUntil ? ` until ${when(issue.snoozedUntil)}` : ""}${issue.snoozedFor ? ` for ${issue.snoozedFor} more` : ""} — ${issue.what}\n`);
+    return 0;
+  }
+  if (verb === "show") {
+    if (!id) throw new Error("`foldrun issues show <issue-id>`");
+    const { issue } = await remoteCall(url, flags, `/api/issues/${id}`);
+    if (flags.json === true) return console.log(JSON.stringify(issue, null, 2)), 0;
+    printIssue(issue, true);
+    return 0;
+  }
+  const status = typeof flags.status === "string" ? flags.status : flags.all === true ? "all" : "active";
+  const qs = new URLSearchParams({ status, ...(typeof flags.to === "string" ? { workspace: flags.to } : {}) });
+  const { issues = [] } = await remoteCall(url, flags, `/api/issues?${qs}`);
+  if (flags.json === true) return console.log(JSON.stringify(issues, null, 2)), 0;
+  if (!issues.length) {
+    console.log(`\n  ${c.dim(status === "active" ? "no open issues" : `no ${status} issues`)}\n`);
+    return 0;
+  }
+  console.log();
+  for (const i of issues) printIssue(i, false);
+  console.log(`  ${c.dim("foldrun issues show <id> for its runs and history; doctor <id> asks the run doctor why; ack, snooze --for 1d, resolve or reopen <id> act on one; --all lists resolved too")}\n`);
+  return 0;
+}
+
+function printIssue(i, full) {
+  const mark = i.kind === "platform" ? c.bold("▲") : i.kind === "failed" ? c.red("✗") : i.kind === "blocked" ? c.red("⛔") : i.kind === "missed" ? c.amber("◷") : c.amber("!");
+  const where = i.kind === "platform" ? i.workspaces.join(", ") : `${i.workspace} · ${i.what}${i.agent ? ` at ${i.agent}` : ""}`;
+  const label = i.kind === "missed" ? "missed schedule" : i.kind;
+  const state = (i.status === "open" ? "" : c.dim(` [${i.status}${i.snoozedUntil ? ` until ${when(i.snoozedUntil)}` : ""}${i.snoozedFor ? ` for ${i.snoozedFor} more` : ""}${i.resolved?.by?.startsWith("auto:") ? ", auto" : ""}]`)) + (i.regressed ? ` ${c.red(`regressed${i.sinceRevision ? ` since ${String(i.sinceRevision).slice(0, 7)}` : ""}`)}` : "");
+  console.log(`  ${mark} ${c.bold(i.kind === "platform" ? i.what : label)}  ${where}${state}  ${c.dim(i.id)}`);
+  console.log(`      ${c.dim(`${i.count}× · first ${ago(i.firstSeen)} ago · latest ${ago(i.lastSeen)} ago${i.recoveredAt ? ` · fine for ${ago(i.recoveredAt)}` : ""}`)}`);
+  for (const line of wrap(i.reason, 84).slice(0, full ? 20 : 2)) console.log(`      ${line}`);
+  console.log(`      ${c.dim("→")} ${i.action}`);
+  if (full) {
+    console.log(`      ${c.dim(`runs: ${i.runs.map((r) => `${r.workspace}/${r.id}`).join(", ")}`)}`);
+    for (const e of i.history) console.log(`      ${c.dim(`${when(e.at)} ${e.action} by ${e.by}${e.until ? ` until ${when(e.until)}` : ""}${e.note ? ` — ${e.note}` : ""}`)}`);
+  }
+  console.log();
+}
+
 async function approvalsCmd(flags, layout) {
   const url = platformFor(flags, "approvals");
   const only = typeof flags.to === "string" ? flags.to : null;
@@ -6151,6 +6544,23 @@ async function stopCmd(runId, flags, layout) {
  */
 async function runsCmd(flags, layout) {
   const url = platformFor(flags, "runs");
+  // --view <name>: a saved search (the dashboard's) read first, so every
+  // filter in it — status, since, workspace, flow, q and the search's own —
+  // applies as if typed; a flag typed too wins (Codex review).
+  if (typeof flags.view === "string") {
+    const { runViews = [] } = await remoteCall(url, flags, "/api/me/preferences");
+    const view = runViews.find((v) => v.name === flags.view);
+    if (!view) throw new Error(`no saved view called ${flags.view}${runViews.length ? ` — yours: ${runViews.map((v) => v.name).join(", ")}` : " — save one on the runs page"}`);
+    const as = { workspace: "to", min_tokens: "min-tokens", min_secs: "min-secs" };
+    const fromView = {};
+    for (const [k, v] of new URLSearchParams(view.query)) {
+      if (k === "tool_error") fromView["tool-error"] = v === "1" || v === "true";
+      // The dashboard's Today chip is its 24-hour window (Codex review).
+      else if (k === "since" && v === "today") fromView.since = "24h";
+      else fromView[as[k] ?? k] = v;
+    }
+    flags = { ...fromView, ...flags };
+  }
   const names = typeof flags.to === "string" ? [flags.to] : await remoteWorkspaceNames(url, flags);
   if (!names.length) {
     console.log(`\n  ${c.dim(`no workspaces on ${url}`)}\n`);
@@ -6162,6 +6572,17 @@ async function runsCmd(flags, layout) {
     typeof flags.status === "string" ? new Set(flags.status.split(",").map((s) => s.trim()).filter(Boolean)) : null;
   const verdicts =
     typeof flags.verdict === "string" ? new Set(flags.verdict.split(",").map((s) => s.trim().toUpperCase()).filter(Boolean)) : null;
+  // --outcome (FOL-54): the one word every surface shows — needs-you is the
+  // dashboard's name for waiting. A platform from before it sends none.
+  const OUTCOME_WORDS = ["running", "queued", "waiting", "good", "done", "quiet", "blocked", "bad", "failed", "stopped"];
+  const outcomes =
+    typeof flags.outcome === "string"
+      ? new Set(flags.outcome.split(",").map((s) => s.trim().toLowerCase().replace(/^needs-?you$/, "waiting")).filter(Boolean))
+      : null;
+  if (outcomes) {
+    const unknown = [...outcomes].filter((o) => !OUTCOME_WORDS.includes(o));
+    if (unknown.length) throw new Error(`--outcome takes ${OUTCOME_WORDS.join(", ")} (or needs-you) — not ${unknown.join(", ")}`);
+  }
 
   // Each desk is asked for its own newest rows before the merge, so one
   // busy workspace cannot crowd every quiet one out of the answer. With a
@@ -6169,11 +6590,23 @@ async function runsCmd(flags, layout) {
   // the filter runs here, after the fetch, and a desk with twenty recent
   // successes was hiding its older failures from `--status failed` because
   // only its newest twenty of any status ever arrived.
-  const perWorkspace = wanted || verdicts || cutoff !== null ? 500 : limit;
+  // Search (FOL-72 step 9): by what happened inside a run, filtered by the
+  // platform; --view <name> starts from a saved search (the dashboard's).
+  const search = new URLSearchParams();
+  for (const [flag, key] of [["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"]]) {
+    if (flags[flag] !== undefined && flags[flag] !== true) search.set(key, String(flags[flag]));
+  }
+  if (flags["tool-error"] === true) search.set("tool_error", "1");
+  const searching = [...search.keys()].some((k) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k));
+  // A view's flow or text filters here, after the fetch: ask for the ceiling
+  // as for a status, or matches past the newest few go missing (Codex review).
+  const localText = typeof flags.flow === "string" || typeof flags.q === "string";
+  const perWorkspace = wanted || verdicts || outcomes || cutoff !== null || searching || localText ? 500 : limit;
   const unreachable = [];
   const lists = await pool(names, 8, async (ws) => {
     try {
-      const { runs = [] } = await remoteCall(url, flags, `/api/workspaces/${ws}/runs?limit=${perWorkspace}`);
+      const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k)));
+      const { runs = [] } = await remoteCall(url, flags, `/api/workspaces/${ws}/runs?limit=${perWorkspace}${forApi.size ? `&${forApi}` : ""}`);
       return runs.map((r) => ({ ...r, workspace: ws }));
     } catch (err) {
       unreachable.push([ws, explain(err)]);
@@ -6183,14 +6616,34 @@ async function runsCmd(flags, layout) {
 
   const rows = lists
     .flat()
-    .filter((r) => (wanted ? wanted.has(r.status) : true))
+    // The status the dashboard shows: a stopped run is "stopped", not the
+    // "failed" its record says (Codex review — a saved status=stopped view).
+    .filter((r) => (wanted ? wanted.has(r.outcome === "stopped" ? "stopped" : r.status) : true))
     .filter((r) => (verdicts ? r.status === "completed" && verdicts.has(verdictOf(r)) : true))
+    .filter((r) => (outcomes ? typeof r.outcome === "string" && outcomes.has(r.outcome) : true))
+    // A view's flow and free text (the runs page's): "agent: x" is a direct run.
+    // The dashboard names a run by what ran (whatRan): a direct agent run's
+    // or an eval's own name, without adhoc:/eval: (Codex review).
+    .filter((r) => (typeof flags.flow === "string" ? r.flow === flags.flow || r.flow.replace(/^(adhoc|eval):/, "") === flags.flow : true))
+    // The runs page's text search, field for field (its runSearchText): every
+    // word, any order, across id, what ran, workspace, the status it shows,
+    // verdict, summary and the failure (Codex review).
+    .filter((r) => {
+      if (typeof flags.q !== "string") return true;
+      const words = flags.q.toLowerCase().replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+      const shown = r.outcome === "stopped" ? "stopped" : r.status;
+      const hay = [r.id, r.flow.replace(/^(adhoc|eval):/, ""), r.workspace, shown, verdictOf(r) ?? "", r.summary ?? "", r.failure ? `${r.failure.agent} ${r.failure.reason}` : ""]
+        .join(" ")
+        .toLowerCase()
+        .replace(/\s+/g, " ");
+      return words.every((w) => hay.includes(w));
+    })
     .filter((r) => (cutoff === null ? true : Date.parse(r.startedAt) >= cutoff))
     .sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1))
     .slice(0, limit);
 
   if (!rows.length) {
-    const how = [wanted ? `status ${[...wanted].join(", ")}` : null, verdicts ? `verdict ${[...verdicts].join(", ")}` : null, flags.since ? `the last ${flags.since}` : null]
+    const how = [wanted ? `status ${[...wanted].join(", ")}` : null, verdicts ? `verdict ${[...verdicts].join(", ")}` : null, outcomes ? `outcome ${[...outcomes].join(", ")}` : null, flags.since ? `the last ${flags.since}` : null]
       .filter(Boolean)
       .join(" in ");
     console.log(`\n  ${c.dim(`no runs${how ? ` matching ${how}` : ""}${flags.to ? ` in ${flags.to}` : ""}`)}\n`);
@@ -6210,7 +6663,9 @@ async function runsCmd(flags, layout) {
       verdictWidth: (r.status === "completed" ? verdictOf(r) ?? "" : "").length,
       steps: `${done}/${(r.steps ?? []).length}`,
       took: runDuration(r),
-      cost: `$${runCost(r).toFixed(2)}`,
+      // FOL-54: credits charged, as the dashboard shows; a run not settled
+      // yet (or a platform from before chargedUsd) shows its token cost, in dollars.
+      cost: typeof r.chargedUsd === "number" ? `${Math.round(r.chargedUsd * 100)} credits` : `$${runCost(r).toFixed(2)}`,
       id: r.id,
       summary: firstLine(r.summary, 110),
     };
@@ -6354,6 +6809,28 @@ function measuredShare(list) {
   return all > 0 ? read / all : null;
 }
 const cachedLabel = (rate) => (rate == null ? null : `${Math.round(rate * 100)}% cached`);
+/** Why a step's prompt cache missed — core's rule (tokens.ts promptCacheNote),
+ *  repeated here as `cachedShare` is: a step that wrote a fifth or more of its
+ *  input to the cache says which layer of its prompt changed since the same
+ *  agent's previous step in the run. Nothing for a step without layers on
+ *  record (before 20 Oct 2026) or one the cache served. */
+function promptCacheNote(steps, index) {
+  const step = steps[index];
+  const t = step?.tokens;
+  if (!step?.promptLayers || !t || t.cacheWrite === undefined || !(t.input > 0)) return null;
+  const share = t.cacheWrite / t.input;
+  if (share < 0.2) return null;
+  const head = `${Math.round(share * 100)}% of input written to the cache`;
+  let prev = -1;
+  for (let j = index - 1; j >= 0; j--) if (steps[j].agent === step.agent && steps[j].promptLayers) { prev = j; break; }
+  if (prev < 0) return `${head} — the agent's first step in this run`;
+  const before = new Map(steps[prev].promptLayers.map((l) => [l.name, l.hash]));
+  const after = new Map(step.promptLayers.map((l) => [l.name, l.hash]));
+  const changed = [...after].filter(([name, hash]) => before.get(name) !== hash).map(([name]) => name);
+  for (const name of before.keys()) if (!after.has(name)) changed.push(name);
+  if (!changed.length) return `${head} — the same prompt as step ${prev + 1}; the entry had expired or was still being written`;
+  return `${head} — ${changed.join(", ")} changed since step ${prev + 1}`;
+}
 function sumTokens(list) {
   const out = { input: 0, output: 0 };
   for (const t of list) {
@@ -6368,10 +6845,86 @@ function sumTokens(list) {
   return out;
 }
 
+/** `foldrun report <run-id> call <call-id>` — one tool call's recorded input
+ *  and output, secrets masked (FOL-54 step 4). */
+async function reportCallCmd(runId, callId, flags, layout) {
+  const url = platformFor(flags, "report");
+  if (!runId || !callId) throw new Error("`foldrun report <run-id> call <call-id>` — `foldrun report <run-id> --calls` lists the recorded calls");
+  const ws = await workspaceOfRun(url, flags, layout, runId);
+  const { call } = await remoteCall(url, flags, `/api/workspaces/${ws}/runs/${runId}/calls/${encodeURIComponent(callId)}`);
+  if (flags.json === true) return console.log(JSON.stringify(call, null, 2)), 0;
+  console.log(`\n  ${c.bold(call.tool)}  ${c.dim(call.id)}`);
+  for (const [label, text, whole, wasCut] of [["input", call.input, call.inputChars, call.inputCut], ["output", call.output, call.outputChars, call.outputCut]]) {
+    if (text === undefined) continue;
+    const cut = wasCut === true && typeof whole === "number" && whole > text.length ? c.dim(` (the first ${text.length.toLocaleString()} of ${whole.toLocaleString()} characters)`) : "";
+    console.log(`\n  ${c.dim(label)}${cut}`);
+    for (const line of String(text).split("\n")) console.log(`    ${line}`);
+  }
+  console.log();
+  return 0;
+}
+
+/** `foldrun report <run-id> --tree` — the run as one tree, run → step →
+ *  model call → tool call, from GET …/runs/<id>/trace (FOL-72 step 5). */
+async function reportTreeCmd(url, flags, ws, runId) {
+  const { tree, failure = [] } = await remoteCall(url, flags, `/api/workspaces/${ws}/runs/${runId}/trace`);
+  if (flags.json === true) return console.log(JSON.stringify({ tree, failure }, null, 2)), 0;
+  // The deepest span on the way to the failure is the one to point at.
+  const culprit = failure.length ? failure[failure.length - 1] : null;
+  const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(n >= 100_000 ? 0 : 1)}k` : String(n));
+  const mark = { run: "▣", step: "◆", model: "✦", tool: "→", error: "✗" };
+  const lines = [];
+  const walk = (s, prefix, last, root) => {
+    const dur = s.start != null && s.end != null ? humanDuration(Math.max(0, s.end - s.start)) : "";
+    const facts = [
+      s.kind === "model" && s.tokens ? `${k(s.tokens.input)} in · ${k(s.tokens.output)} out` : null,
+      s.stop ?? null,
+      s.subagent ? `↳ ${s.subagent}` : null,
+      s.kind === "tool" && s.captured && s.call ? s.call : null,
+    ].filter(Boolean);
+    const text = s.kind === "error" ? firstLine(s.text ?? "", 90) : s.label;
+    const head = `${root ? "" : `${prefix}${last ? "└ " : "├ "}`}${mark[s.kind] ?? "·"} ${s.status === "error" ? c.red(text) : s.kind === "step" || s.kind === "run" ? c.bold(text) : text}`;
+    lines.push(`  ${head}${facts.length ? `  ${c.dim(facts.join(" · "))}` : ""}${dur && s.kind !== "error" ? `  ${c.dim(dur)}` : ""}${s.id === culprit ? `  ${c.red("← what went wrong")}` : ""}`);
+    const kids = s.children ?? [];
+    kids.forEach((ch, i) => walk(ch, root ? "" : `${prefix}${last ? "  " : "│ "}`, i === kids.length - 1, false));
+  };
+  walk(tree, "", true, true);
+  console.log(`\n${lines.join("\n")}\n`);
+  if ((tree.children ?? []).some((s) => (s.children ?? []).some((ch) => (ch.children ?? []).some((t) => t.captured)))) console.log(`  ${c.dim(`\`foldrun report ${runId} call <id>\` shows a call's input and output`)}\n`);
+  return 0;
+}
+
+/** `foldrun report <run-id> --compare [<other>]` — this run beside the flow's
+ *  last good run (or the one named), from GET …/compare (FOL-72 step 6). */
+async function reportCompareCmd(url, flags, ws, runId) {
+  const other = typeof flags.compare === "string" ? flags.compare : null;
+  const { comparison: cmp, chosen } = await remoteCall(url, flags, `/api/workspaces/${ws}/runs/${runId}/compare${other ? `?with=${encodeURIComponent(other)}` : ""}`);
+  if (flags.json === true) return console.log(JSON.stringify({ comparison: cmp, chosen }, null, 2)), 0;
+  console.log(`\n  ${c.bold(runId)} ${c.dim(`(${cmp.run.status})`)} beside ${c.bold(cmp.base.id)} ${c.dim(`(${chosen}, ${cmp.base.status})`)}`);
+  const files = !cmp.revisionChanged
+    ? "both ran the same version of the files"
+    : cmp.changedFiles === null
+      ? "they ran different versions of the files"
+      : cmp.changedFiles.length
+        ? `files changed between them: ${cmp.changedFiles.slice(0, 8).join(", ")}${cmp.changedFiles.length > 8 ? ` and ${cmp.changedFiles.length - 8} more` : ""}`
+        : "different revisions, no file changes between them";
+  console.log(`  ${c.dim(files)}\n`);
+  const changed = cmp.steps.filter((s) => s.changes.length);
+  if (!changed.length) console.log(`  ${c.dim("no step differs in status, instruction, model, tools, errors, time or tokens")}`);
+  for (const s of changed) {
+    console.log(`  ${c.bold(`step ${s.step} · ${s.agent}`)}`);
+    for (const ch of s.changes) console.log(`    ${/^(status|new error|tool errors)/.test(ch) ? c.red("•") : c.dim("•")} ${ch}`);
+  }
+  console.log();
+  return 0;
+}
+
 async function reportCmd(runId, flags, layout) {
   const url = platformFor(flags, "report");
   if (!runId) throw new Error("which run? `foldrun report <run-id>` — `foldrun runs` lists them");
   const ws = await workspaceOfRun(url, flags, layout, runId);
+  if (flags.tree === true) return reportTreeCmd(url, flags, ws, runId);
+  if (flags.compare !== undefined) return reportCompareCmd(url, flags, ws, runId);
   const run = await remoteCall(url, flags, `/api/workspaces/${ws}/runs/${runId}`);
 
   if (flags.json === true) {
@@ -6391,6 +6944,9 @@ async function reportCmd(runId, flags, layout) {
     console.log(`  ${c.dim(`${tokens.input.toLocaleString()} in / ${tokens.output.toLocaleString()} out tokens${cached ? ` · ${cached}` : ""}`)}`);
   }
   if (run.budgetUsd) console.log(`  ${c.dim(`budget $${Number(run.budgetUsd).toFixed(2)}`)}`);
+  // Which files it ran and how long it waited for a worker (FOL-54 step 4).
+  const ranOn = [run.revision ? `ran on ${String(run.revision).slice(0, 7)}` : null, run.drivenAt ? `queued ${humanDuration(Math.max(0, Date.parse(run.drivenAt) - Date.parse(run.startedAt)))}` : null].filter(Boolean);
+  if (ranOn.length) console.log(`  ${c.dim(ranOn.join(" · "))}`);
   if (run.summary) {
     console.log();
     for (const line of wrap(run.summary, 84)) console.log(`  ${line}`);
@@ -6413,6 +6969,10 @@ async function reportCmd(runId, flags, layout) {
     console.log(
       `  ${statusMark(step.status)} ${pad(`${i + 1}.`, 4)}${c.dim(`g${step.group ?? 1}`)} ${c.bold(step.agent)}  ${c.dim(bits.join(" · "))}`,
     );
+    // A step the prompt cache did not serve says why — which layer of its
+    // prompt changed since the agent's last step — the way the run page does.
+    const cacheNote = promptCacheNote(run.steps ?? [], i);
+    if (cacheNote) console.log(`      ${c.dim("·")} ${c.dim(`prompt cache: ${cacheNote}`)}`);
     if (step.verify) {
       // A step that completed with a verify held it — the runtime fails the
       // step otherwise, so status IS the verdict, and saying it out loud is
@@ -6433,6 +6993,26 @@ async function reportCmd(runId, flags, layout) {
     if (step.status === "awaiting-approval") {
       console.log(`      ${c.amber("⏸")} ${c.dim(step.waitFor === "event" ? "waiting on an event" : `waiting on a person: ${firstLine(step.ask ?? step.instruction, 70)}`)}`);
     }
+    // Each model call (FOL-54 step 4): one line, or every call with --calls,
+    // and the tool calls whose input and output were recorded.
+    const calls = Array.isArray(step.calls) ? step.calls : [];
+    if (calls.length) {
+      const slowest = Math.max(...calls.map((m) => m.ms ?? 0));
+      console.log(`      ${c.dim(`${calls.length} model call${calls.length === 1 ? "" : "s"} · slowest ${humanDuration(slowest)} · largest ${Math.max(...calls.map((m) => m.tokens?.input ?? 0)).toLocaleString()} in`)}`);
+      if (flags.calls === true) {
+        for (const m of calls) {
+          const t = m.tokens ?? {};
+          const cached = t.input > 0 && t.cacheRead > 0 ? ` (${Math.round((100 * t.cacheRead) / t.input)}% cached)` : "";
+          console.log(`        ${c.dim(`${m.n}. ${m.model ?? "model"}${m.subagent ? ` ↳ ${m.subagent}` : ""} · ${humanDuration(m.ms ?? 0)} · ${(t.input ?? 0).toLocaleString()} in${cached} · ${(t.output ?? 0).toLocaleString()} out${m.stop ? ` · ${m.stop}` : ""}${m.tools ? ` · ${m.tools} tool${m.tools === 1 ? "" : "s"}` : ""}`)}`);
+        }
+      }
+    }
+    if (flags.calls === true) {
+      // Either half recorded counts, once per call.
+      const recorded = [...new Map((step.events ?? []).filter((e) => e.type === "tool" && e.captured && e.call).map((e) => [e.call, e])).values()];
+      for (const e of recorded) console.log(`        ${c.dim(`→ ${e.text}  ${e.call}`)}`);
+      if (recorded.length) console.log(`        ${c.dim(`\`foldrun report ${run.id} call <id>\` shows one call's input and output`)}`);
+    }
     const said = firstLine(step.conclusion ?? step.result, 96);
     if (said) console.log(`      ${said}`);
     const err = stepError(step);
@@ -6634,6 +7214,38 @@ async function agentRunCmd(positional, flags, layout) {
   return reportCmd(runId, { ...flags, to: ws }, layout);
 }
 
+/**
+ * `foldrun check --to <ws> --online` (FOL-58): the network checks, from the
+ * platform — known vulnerabilities for exact runtime pins (OSV) and what
+ * remote MCP servers tell the model about their tools — and, as loudly,
+ * what could not be checked. Exit 1 on a finding at --fail-on or above
+ * (warn under --security), as the local check does.
+ */
+async function checkOnline(url, flags, ws) {
+  const answer = await remoteCall(
+    url,
+    flags,
+    `/api/workspaces/${enc(ws)}/check?online=1&rule=supply-chain/known-vulnerability,content/mcp-tool-text`,
+    {},
+    { seconds: Math.max(timeoutSeconds(flags), 120) },
+  );
+  // --rule narrows these as it narrows the offline ones (Codex review).
+  const { rules } = checkOptions(flags);
+  const want = new Set(rules);
+  const findings = (answer.findings ?? []).filter(
+    (f) => !rules.length || want.has(f.rule) || want.has(f.rule.split("/")[0]) || want.has(categoryOf(f.rule)),
+  );
+  const problems = answer.online?.problems ?? [];
+  console.log(`  ${c.bold("online checks")}  ${c.dim("OSV for exact runtime pins · remote MCP servers' tool text")}`);
+  for (const f of findings) console.log(`  ${c.amber(" warn")}  ${c.bold(`${f.file}${f.line ? `:${f.line}` : ""}`)}  ${f.message}  ${c.dim(`[${f.rule}]`)}`);
+  if (!findings.length) console.log(`  ${c.green("✓")} ${c.dim(problems.length ? "nothing found in what could be checked" : "nothing found")}`);
+  for (const p of problems) console.log(`  ${c.amber("!")} ${c.dim("not checked:")} ${p}`);
+  if (answer.rescan?.checkedAt) console.log(`  ${c.dim(`the daily rescan last ran ${answer.rescan.checkedAt}`)}`);
+  console.log();
+  const { failOn } = checkOptions(flags);
+  return findings.some((f) => (RANK[f.level] ?? 0) >= FAIL_ON[failOn]) ? 1 : 0;
+}
+
 /**
  * `foldrun check --to <workspace>` — validate the copy that is DEPLOYED.
  *
@@ -6679,6 +7291,7 @@ async function checkRemote(flags, layout) {
     // The baseline belongs to the folder it was written in, not to a temp copy.
     const code = await check(dir, { ...flags, "no-baseline": true });
     say(`  ${c.dim(`checked what is deployed, not this folder — ${ws} · ${url}`)}\n`);
+    if (flags.online === true) return Math.max(code, await checkOnline(url, flags, ws));
     return code;
   } finally {
     if (before.workspace === undefined) delete process.env.FOLDRUN_WORKSPACE;
@@ -7950,9 +8563,50 @@ function printEvalResult(result) {
  * run there. Each run waits for its verdict: an eval is something you wait
  * for, and the platform answers when every case has.
  */
+/**
+ * One eval on the platform, started and polled (POST …/run { async: true },
+ * then GET …/run) — a long eval outlives the proxy in front of the platform,
+ * which cut the old waiting request at 100 s. A platform that answers the
+ * POST with the result itself (older ones) is read as before.
+ */
+async function remoteEvalRun(url, flags, ws, name) {
+  const path = `/api/workspaces/${enc(ws)}/evals/${enc(name)}/run`;
+  const started = await remoteCall(url, flags, path, { method: "POST", body: JSON.stringify({ async: true }) }, { seconds: explicitTimeout(flags) ?? 900 });
+  if (!started?.started) return started;
+  console.log(`  ${c.dim(`run ${started.runId}`)}`);
+  const deadline = Date.now() + (explicitTimeout(flags) ?? 900) * 1000;
+  for (;;) {
+    if (Date.now() > deadline) {
+      throw new Error(`${name} is still running after ${explicitTimeout(flags) ?? 900}s — \`foldrun eval ${name} --to ${ws} --run ${started.runId}\` reads this run's verdict when it is done, without running it again`);
+    }
+    await new Promise((r) => setTimeout(r, Number(process.env.FOLDRUN_EVAL_POLL_MS) || 4000));
+    const view = await remoteEvalRunView(url, flags, path, started.runId);
+    if (view.state === "running") continue;
+    return evalRunVerdict(name, view);
+  }
+}
+
+/** GET …/run?run=<id> — that one run's state, and nothing else's. */
+function remoteEvalRunView(url, flags, path, runId) {
+  return remoteCall(url, flags, `${path}?run=${encodeURIComponent(runId)}`);
+}
+
+/** A run's view as the result printEvalResult reads — a failure, a lost
+ *  lease or an unknown id are an error, never a pass. */
+function evalRunVerdict(name, view) {
+  if (view.state === "done" && view.result) return view.result;
+  return { eval: name, passed: 0, failed: 0, cases: [], error: view.error ?? `the run ended as ${view.state ?? "unknown"}, with no result` };
+}
+
 async function remoteEvalsCmd(name, flags, layout) {
   const url = platformFor(flags, "eval --to <workspace>");
   const ws = platformWorkspace(flags, layout, "eval");
+  // --run reads one run of one eval: a bare --run, or one with no eval
+  // named, would otherwise start runs or read the id against every eval.
+  if (flags.run !== undefined) {
+    if (typeof flags.run !== "string" || !flags.run.trim()) throw new Error("--run takes the run id the eval printed — `foldrun eval <name> --to <ws> --run <id>`");
+    if (!name) throw new Error("--run reads one eval's run — name it: `foldrun eval <name> --to <ws> --run <id>`");
+  }
   const { evals = [] } = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals`);
   const all = evals.filter((e) => !name || e.name === name);
   if (!all.length) {
@@ -7961,7 +8615,36 @@ async function remoteEvalsCmd(name, flags, layout) {
   let failed = 0;
   for (const info of all) {
     console.log(`\n  ${c.bold(info.name)} ${c.dim(`${info.cases?.length ?? "?"} cases · ${ws}`)}`);
-    const result = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals/${enc(info.name)}/run`, { method: "POST" }, { seconds: explicitTimeout(flags) ?? 900 });
+    // --run <id>: that run's verdict, run nothing (GET …/run?run=).
+    if (typeof flags.run === "string") {
+      const view = await remoteEvalRunView(url, flags, `/api/workspaces/${enc(ws)}/evals/${enc(info.name)}/run`, flags.run);
+      if (view.state === "running") {
+        console.log(`  ${c.dim(`run ${flags.run} is still running, since ${view.startedAt}`)}`);
+        failed++;
+        continue;
+      }
+      const result = evalRunVerdict(info.name, view);
+      printEvalResult(result);
+      failed += Number(result.failed ?? 0) + (result.error ? 1 : 0);
+      continue;
+    }
+    // --last: what the platform has, run nothing (GET …/run).
+    if (flags.last === true) {
+      const state = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals/${enc(info.name)}/run`);
+      if (state.running) console.log(`  ${c.dim(`running since ${state.startedAt} — no result yet`)}`);
+      if (state.error) {
+        console.log(`  ${c.red("✗")} the last run could not finish — ${state.error}`);
+        failed++;
+      }
+      if (!state.result) {
+        if (!state.running && !state.error) console.log(`  ${c.dim("never run")}`);
+        continue;
+      }
+      printEvalResult(state.result);
+      failed += Number(state.result.failed ?? 0) + (state.result.error ? 1 : 0);
+      continue;
+    }
+    const result = await remoteEvalRun(url, flags, ws, info.name);
     printEvalResult(result);
     failed += Number(result.failed ?? 0) + (result.error ? 1 : 0);
   }
@@ -7984,6 +8667,8 @@ async function promoteCmd(runId, flags, layout) {
       ...(typeof flags.eval === "string" ? { evalName: flags.eval } : {}),
       ...(typeof flags.case === "string" ? { caseName: flags.case } : {}),
       ...(expect.length ? { expect } : {}),
+      // A run that went wrong: what it should have done (FOL-72 step 10).
+      ...(typeof flags.should === "string" ? { should: flags.should } : {}),
     }),
   });
   const evalName = path.basename(String(r.file ?? ""), ".md");
@@ -8573,8 +9258,10 @@ async function workspaceDefaults(url, flags, ws) {
 async function workspaceCmd(positional, flags, layout) {
   const url = platformFor(flags, "workspace");
   const ws = platformWorkspace(flags, layout, "workspace");
-  const [verb, key, ...rest] = positional;
-  const KEYS = ["name", "description", "timezone", "budget", "notify"];
+  const [verb, written, ...rest] = positional;
+  // `observability.notify` names the job; checked, then sent as the field.
+  const { key, view } = verb === "set" || verb === "clear" ? await jobKey(url, flags, written, ws) : { key: written, view: null };
+  const KEYS = ["name", "description", "timezone", "budget", "notify", "network_enforce", "owner", "alerts", "judge"];
   const show = (d, title) => {
     const notify = d.notify ? [d.notify.email, d.notify.url].filter(Boolean).join(", ") + c.dim(` on ${(d.notify.events ?? []).join(", ") || "nothing"}`) : c.dim("the account's");
     const budget = d.budget == null ? c.dim("the account's") : typeof d.budget === "object" ? `$${d.budget.usd} per ${d.budget.period}` : String(d.budget).includes("/") ? `$${String(d.budget).replace("/", " per ")}` : `$${d.budget} per month`;
@@ -8583,15 +9270,24 @@ async function workspaceCmd(positional, flags, layout) {
     console.log(`  timezone     ${d.timezone ?? c.dim("the account's")}`);
     console.log(`  notify       ${notify}`);
     console.log(`  budget       ${budget}`);
+    if (d.networkEnforce !== undefined) console.log(`  network      ${networkEnforceText(d.networkEnforce, "the account")}`);
   };
 
   if (!verb) {
     const d = await workspaceDefaults(url, flags, ws);
-    show({ description: typeof d.description === "string" ? d.description : "", timezone: d.timezone ?? null, budget: d.budget ?? null, notify: d.notify ?? null }, ws);
+    show({ description: typeof d.description === "string" ? d.description : "", timezone: d.timezone ?? null, budget: d.budget ?? null, notify: d.notify ?? null, networkEnforce: d.network_enforce === true }, ws);
+    const halt = await pauseState(remoteCall(url, flags, `/api/workspaces/${enc(ws)}/pause`));
+    if (halt) console.log(`  paused       ${halt.paused ? c.red(`${halt.paused.scope === "account" ? "by the account: " : ""}${pauseLine(halt.paused)}`) : c.dim("no")}`);
     console.log(`\n  ${c.dim(`foldrun workspace set timezone Australia/Sydney --to ${ws} · set budget 20/week · set notify email you@example.com · set name <new> · clear budget`)}\n`);
     return 0;
   }
-  if (verb !== "set" && verb !== "clear") throw new Error(`unknown workspace verb "${verb}" — set <key> <value>, clear <key> (bare: show them)`);
+  if (verb === "pause" || verb === "resume") {
+    return pauseCmd(flags, verb, `workspace ${ws}`, {
+      post: (body) => remoteCall(url, flags, `/api/workspaces/${enc(ws)}/pause`, { method: "POST", body }),
+      del: () => remoteCall(url, flags, `/api/workspaces/${enc(ws)}/pause`, { method: "DELETE" }),
+    });
+  }
+  if (verb !== "set" && verb !== "clear") throw new Error(`unknown workspace verb "${verb}" — set <key> <value>, clear <key>, pause, resume (bare: show them)`);
   if (!KEYS.includes(key) || (verb === "clear" && key === "name")) {
     throw new Error(`which setting? \`foldrun workspace ${verb} <${(verb === "clear" ? KEYS.filter((k) => k !== "name") : KEYS).join("|")}> … --to <workspace>\``);
   }
@@ -8599,7 +9295,9 @@ async function workspaceCmd(positional, flags, layout) {
   /** @type {Record<string, any>} */
   let patch;
   if (verb === "clear") patch = { [key]: key === "description" ? "" : null };
-  else if (key === "notify") {
+  else if (key === "alerts" || key === "judge") {
+    patch = { [key]: await mergedEntry(url, flags, key, rest, ws, view, `foldrun workspace set ${key}`) };
+  } else if (key === "notify") {
     const [channel, value] = rest;
     if (channel !== "email" && channel !== "url") throw new Error("`foldrun workspace set notify email <address>` or `set notify url <https://…>` — and --events failed,awaiting-approval,completed");
     if (!value && flags.events === undefined) throw new Error(`\`foldrun workspace set notify ${channel} <value>\` — or --events alone to change only what is notified on`);
@@ -8612,7 +9310,7 @@ async function workspaceCmd(positional, flags, layout) {
   } else {
     const value = rest.join(" ").trim();
     if (!value) throw new Error(`\`foldrun workspace set ${key} <value> --to ${ws}\`${key === "name" ? "" : ` — or \`clear ${key}\``}`);
-    patch = { [key]: value };
+    patch = { [key]: key === "network_enforce" ? onOff(key, value, `foldrun workspace set network_enforce on --to ${ws}`) : value };
   }
 
   if (key === "name" && verb === "set") {
@@ -9286,6 +9984,7 @@ async function flowDraftCmd(positional, flags, layout) {
   const existing = typeof flags.flow === "string" ? flags.flow : undefined;
   console.log(`\n  ${c.dim(`drafting in ${ws}${existing ? ` (redraft of ${existing})` : ""} — one model call, charged like a step…`)}`);
   const d = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/flows/draft`, { method: "POST", body: JSON.stringify({ description, ...(existing ? { flow: existing } : {}) }) }, { seconds: Math.max(timeoutSeconds(flags), 180) });
+  /** @type {{ path: string, content: string, before: string | null, sha256?: string | null }[]} */
   const files = d.files ?? [];
   if (d.notes) console.log(`\n  ${d.notes}`);
   console.log();
@@ -9656,11 +10355,14 @@ async function historyRestoreCmd(positional, flags, layout) {
     return 0;
   }
   // The dashboard's own message, so the two read alike in the history.
-  await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/source`, {
+  // A restore is an exact version someone picked: saved unchecked, and it
+  // says so when today's checks would refuse it, as the dashboard does (FOL-57).
+  const saved = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/source`, {
     method: "PUT",
     body: JSON.stringify({ path: file, content: f.after, message: `restored ${label} from history`, ifMatch: current.sha256 ?? null }),
   });
   console.log(`  ${c.green("✓")} ${file} ${c.dim(`reads as it did at ${label} — a new revision; what it said before is still in the history`)}\n`);
+  for (const i of (saved?.issues ?? []).filter((x) => x.level === "error")) console.log(`  ${c.amber("!")} ${c.dim("does not pass today's checks:")} ${i.where} — ${i.message}`);
   return 0;
 }
 
@@ -10175,12 +10877,13 @@ async function evalNewCmd(name, flags, layout) {
 /**
  * `foldrun team` — who is in the account, their role and which workspaces
  * they may open (GET /api/team). Read-only on purpose: inviting, changing a
- * role, removing someone and transferring the account are a person's acts,
- * and the platform refuses them from a key.
+ * role or workspace access, removing someone and transferring the account are
+ * a person's acts, and the platform refuses them from a key (requirePerson,
+ * server/api.ts) — so there is nothing for a key-holding CLI to send.
  */
 async function teamCmd(positional, flags) {
   if (positional[0]) {
-    throw new Error("`foldrun team` lists the members — invites, role changes, removals and transfer are done by a signed-in person in Settings → Team; the platform refuses them from a key");
+    throw new Error("`foldrun team` lists the members — inviting, changing a role or workspace access, removing a member and transferring the account are a signed-in person's acts, done in Settings → Team; the platform refuses them from a key");
   }
   const url = platformFor(flags, "team");
   const { members = [] } = await remoteCall(url, flags, "/api/team");
@@ -10402,6 +11105,14 @@ export async function run(command, positional, flags, workspace, layout) {
         say(`  ${c.dim(`coding-agent rules written for ${codingAgent()} — AGENTS.md ${r.agentsMd}, CLAUDE.md ${r.claudeMd}; read \`foldrun docs\` before editing`)}`);
       }
       if (flags.rules === true) return checkRulesCmd(flags);
+      // --online (FOL-58): the network checks run on the platform, which has
+      // the guarded fetch and the deployed copy — so it needs --to.
+      if (flags.online === true && typeof flags.to !== "string") {
+        throw new Error("`foldrun check --to <workspace> --online` — the online checks (OSV, remote MCP tool text) run on the platform, against the deployed copy");
+      }
+      if (flags.online === true && (flags.json === true || (typeof flags.format === "string" && flags.format !== "text"))) {
+        throw new Error("--online prints text; for JSON ask the API: GET /api/workspaces/<ws>/check?online=1");
+      }
       // --to names a workspace on a PLATFORM, so there is nothing local to
       // check and the folder this terminal stands in is beside the point.
       return typeof flags.to === "string"
@@ -10434,6 +11145,9 @@ export async function run(command, positional, flags, workspace, layout) {
       if (positional[0] === "new" && positional[1]) return evalNewCmd(positional[1], flags, layout);
       // --to names a deployed workspace: its evals run there.
       if (typeof flags.to === "string") return remoteEvalsCmd(positional[0], flags, layout);
+      // --last reads the platform's results; a local eval has none to read,
+      // and running the cases instead would break its promise to run nothing.
+      if (flags.last === true || flags.run !== undefined) throw new Error("--last and --run read a deployed workspace's results — add --to <workspace>");
       needsOne(layout, "eval");
       return runEvals(positional[0], flags);
     case "promote":
@@ -10485,14 +11199,28 @@ export async function run(command, positional, flags, workspace, layout) {
       // the local store has no table to draw across workspaces, because a
       // folder on a laptop is one workspace.
       if (positional[0] === "rm") return runRmCmd(positional[1], flags, layout);
+      if (positional[0] === "views") return runViewsCmd(flags);
+      // The run doctor (FOL-22): the assistant reads the run and its files,
+      // says why it failed and proposes the fix as diffs — saved on yes.
+      if (positional[0] === "doctor") {
+        if (positional.length !== 2 || !/^[A-Za-z0-9_.-]{1,80}$/.test(positional[1])) {
+          throw new Error("`foldrun runs doctor <run-id> --to <workspace>` — the run doctor reads that run and proposes the fix");
+        }
+        return assistantCmd([`Doctor: why did run ${positional[1]} fail, and how do I fix it?`], flags, layout);
+      }
       return flags.local === true ? logsCmd(positional, flags, layout) : runsCmd(flags, layout);
     case "approvals":
       return approvalsCmd(flags, layout);
+    case "issues":
+      return issuesCmd(positional, flags, layout);
+    case "insights":
+      return insightsCmd(flags);
     case "approve":
     case "reject":
       return decideCmd(command, positional[0], flags, layout);
     case "report":
       if (positional[1] === "live") return reportLiveCmd(positional[0], flags, layout);
+      if (positional[1] === "call") return reportCallCmd(positional[0], positional[2], flags, layout);
       return positional[1] === "get" ? reportGetCmd(positional[0], positional[2], flags, layout) : reportCmd(positional[0], flags, layout);
     case "stop":
       // No run id and a filter: every run the filter matches (runs/bulk).
@@ -10507,6 +11235,8 @@ export async function run(command, positional, flags, workspace, layout) {
       return rerunCmd(positional[0], flags, layout);
     case "account":
       return accountCmd(positional, flags);
+    case "jobs":
+      return jobsCmd(flags, layout);
     case "schedule":
       if (positional[0] === "tick") return scheduleTickCmd(flags);
       return scheduleCmd(flags);