@agentswf/engine 0.1.0-beta.2 → 0.1.0-beta.4

package/src/run-lock.ts

@@ -0,0 +1,123 @@
+import { mkdir, readFile, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isCode, linkNew } from "./files";
+import { probeProcess, processStart, sameStart } from "./runs";
+
+/**
+ * `{root}/{workflow}/{run id}.lock`: the lock on a run, beside its run's folder so it exists before
+ * the run does. Every append to the run's mailbox, and each decision made from it, holds it.
+ */
+export function runLockFile(runRoot: string, workflow: string, runId: string): string {
+  return join(runRoot, workflow, `${runId}.lock`);
+}
+
+type Holder = { pid: number; processStart: string; at: string };
+
+let own: string | undefined;
+/** This process's start, asked of `ps` once. */
+function ownStart(): string | undefined {
+  own ??= processStart(process.pid);
+  return own;
+}
+
+/** Callers in this process queue for a lock here before any of them links the file. */
+const queues = new Map<string, Promise<void>>();
+
+/** How long a caller tries before it gives up: a holder that never lets go is gone or wedged. */
+const GIVE_UP_MILLISECONDS = 120_000;
+
+/**
+ * Runs `work` holding the run's lock: claimed by linking its file into place, which fails while
+ * another holds it, and taken over when the process that holds it is gone. Callers in one process
+ * take it in turn. A lock is not reentrant: `work` that takes the same lock again waits on itself.
+ */
+export async function withRunLock<T>(file: string, work: () => Promise<T>): Promise<T> {
+  const previous = queues.get(file) ?? Promise.resolve();
+  const turn = Promise.withResolvers<void>();
+  const mine = previous.then(() => turn.promise);
+  queues.set(file, mine);
+  try {
+    await previous;
+    const held = await claim(file);
+    try {
+      return await work();
+    } finally {
+      // Ours to remove only while it is still ours: one taken over meanwhile is its taker's.
+      if (JSON.stringify(await readHolder(file)) === JSON.stringify(held))
+        await unlink(file).catch(() => undefined);
+    }
+  } finally {
+    turn.resolve();
+    if (queues.get(file) === mine) queues.delete(file);
+  }
+}
+
+async function claim(file: string): Promise<Holder> {
+  const started = ownStart();
+  if (started === undefined) throw new Error(`no start time for this process (${process.pid})`);
+  const mine: Holder = { pid: process.pid, processStart: started, at: new Date().toISOString() };
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  const giveUp = Date.now() + GIVE_UP_MILLISECONDS;
+  let wait = 5;
+  let lastLook = 0;
+  for (;;) {
+    if (await linkNew(file, mine)) return mine;
+    // Asking `ps` costs a process: whether the holder is gone is asked now and then, not each try.
+    if (Date.now() - lastLook > 250) {
+      lastLook = Date.now();
+      const holder = await readHolder(file);
+      if (holder === "gone") continue;
+      if (!holder || gone(holder)) {
+        await takeOver(file, holder);
+        continue;
+      }
+    }
+    if (Date.now() > giveUp)
+      throw new Error(`${file} is still held after ${GIVE_UP_MILLISECONDS / 1000} s`);
+    await Bun.sleep(wait);
+    wait = Math.min(wait * 2, 100);
+  }
+}
+
+/**
+ * Whether a holder's process is gone. Where `ps` can't be asked, it is taken as alive: taking a
+ * live holder's lock over would let two writers in.
+ */
+function gone(holder: Holder): boolean {
+  const now = probeProcess(holder.pid);
+  if (now === "unknown") return false;
+  return now === "gone" || !sameStart(now, holder.processStart);
+}
+
+/** The holder as its file says, `gone` when the file went meanwhile, undefined when it is torn. */
+async function readHolder(file: string): Promise<Holder | "gone" | undefined> {
+  let text: string;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (isCode(error, "ENOENT")) return "gone";
+    throw error;
+  }
+  try {
+    const value = JSON.parse(text) as Partial<Holder>;
+    return typeof value.pid === "number" && typeof value.processStart === "string"
+      ? (value as Holder)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Removes a lock its holder left behind, if it is still the one read: another taker may have
+ * replaced it since. The window between the second read and the unlink is the one race left; a
+ * holder that died is rare, and two takers at that instant rarer.
+ */
+async function takeOver(file: string, stale: Holder | undefined): Promise<void> {
+  const now = await readHolder(file);
+  if (now === "gone") return;
+  if (JSON.stringify(now) !== JSON.stringify(stale)) return;
+  await unlink(file).catch((error: unknown) => {
+    if (!isCode(error, "ENOENT")) throw error;
+  });
+}

package/src/run-prepare.ts

@@ -1,8 +1,10 @@
 import { statSync } from "node:fs";
+import { homedir } from "node:os";
 import { type AttemptRecord, RUN_EVENT_VERSIONS } from "@agentswf/contract/records";
-import type { ExecutableWorkflow, JsonValue } from "@agentswf/contract/workflow";
+import { isEventWorkflow, type JsonValue } from "@agentswf/contract/workflow";
 import { refusalMessage } from "./attempt-view";
 import { messageOf } from "./errors";
+import { projectOf, projectRunRoot } from "./projects";
 import type { RunCommand } from "./run-command";
 import {
   type Attempt,
@@ -14,13 +16,19 @@ import {
   endTurnsLine,
   idProblem,
   openRun,
+  previousGone,
   type Run,
   RunRefused,
   readAttempts,
   readStageRecords,
   readTurns,
 } from "./runs";
-import { assertJsonValue, type LoadedWorkflow, loadWorkflowFile } from "./workflow-loader";
+import {
+  type AnyWorkflow,
+  assertJsonValue,
+  type LoadedWorkflow,
+  loadWorkflowFile,
+} from "./workflow-loader";
 
 export type PreparedRun = {
   args: JsonValue;
@@ -35,17 +43,50 @@ export type PreparedRun = {
  * typed the command, before anything starts.
  */
 export async function loadAndPrepare(
-  command: RunCommand,
+  given: RunCommand,
   now: number,
-): Promise<{ loaded: LoadedWorkflow; prepared: PreparedRun } | { refused: string }> {
+  home: string = homedir(),
+): Promise<
+  | { loaded: LoadedWorkflow; prepared: PreparedRun; command: RunCommand }
+  | { refused: string }
+  | { opens: { loaded: LoadedWorkflow; id: string; argv: readonly string[] } }
+> {
   let loaded: LoadedWorkflow;
   try {
-    loaded = await loadWorkflowFile(command.workflowFile, command.shellCwd);
+    loaded = await loadWorkflowFile(given.workflowFile, given.shellCwd);
   } catch (error) {
     return { refused: `load: ${messageOf(error)}` };
   }
+  let command = given;
+  if (isEventWorkflow(loaded.workflow)) {
+    const refused = eventRunRefusal(command);
+    if (refused) return { refused };
+    // An event run lives and works in its file's project, whoever starts or continues it (Q15).
+    let project: string;
+    try {
+      project = await projectOf(loaded.file, home);
+    } catch (error) {
+      return { refused: messageOf(error) };
+    }
+    if (!command.runRootGiven) command = { ...command, runRoot: projectRunRoot(project) };
+    if (command.continueId === undefined) {
+      // A run --id names is prepared only if it is made: one already there is woken with its own args.
+      try {
+        const id =
+          command.id ??
+          derivedId(loaded.workflow, prepareArgs(loaded.workflow, command.workflowArgs, project));
+        if (id === undefined)
+          return {
+            refused: `a run of ${loaded.file} is named by its id, which --id or the workflow's id(args) gives: awf run --id {id} starts one, awf emit --target ${loaded.file} --id {id} {event} {json} starts one with an event`,
+          };
+        return { opens: { loaded, id, argv: command.workflowArgs } };
+      } catch (error) {
+        return { refused: `${error instanceof RunRefused ? "" : "prepare: "}${messageOf(error)}` };
+      }
+    }
+  }
   try {
-    return { loaded, prepared: await prepareRun(command, loaded, now) };
+    return { loaded, prepared: await prepareRun(command, loaded, now), command };
   } catch (error) {
     return { refused: `${error instanceof RunRefused ? "" : "prepare: "}${messageOf(error)}` };
   }
@@ -60,16 +101,12 @@ async function prepareRun(
   loaded: LoadedWorkflow,
   now: number,
 ): Promise<PreparedRun> {
-  const { executable, file } = loaded;
-  const { meta } = executable.definition;
-  const prepare = (argv: readonly string[], cwd: string) => {
-    const args = executable.prepare({ argv, cwd });
-    assertJsonValue(args, `${meta.name} arguments`);
-    return args;
-  };
+  const { workflow, file } = loaded;
+  const { meta } = workflow;
+  const prepare = (argv: readonly string[], cwd: string) => prepareArgs(workflow, argv, cwd);
   if (command.continueId === undefined) {
     const args = prepare(command.workflowArgs, command.cwd);
-    const id = command.id ?? derivedId(executable, args);
+    const id = command.id ?? derivedId(workflow, args);
     if (id !== undefined) await checkFree(command.runRoot, meta.name, id);
     return { args, ...(id === undefined ? {} : { id }) };
   }
@@ -107,15 +144,46 @@ async function prepareRun(
   return { args, continued: { run, attempts, warnings: unrecorded } };
 }
 
+/** The workflow's args from `argv`, as its `prepare` makes them, checked to be JSON. */
+export function prepareArgs(
+  workflow: AnyWorkflow,
+  argv: readonly string[],
+  cwd: string,
+): JsonValue {
+  const args = workflow.prepare({ argv, cwd });
+  assertJsonValue(args, `${workflow.meta.name} arguments`);
+  return args;
+}
+
+/**
+ * Why `awf run` doesn't take a workflow with `events` as asked: every attempt after the first is
+ * started by a wake, which passes on none of the flags a run would have to keep.
+ */
+function eventRunRefusal(command: RunCommand): string | undefined {
+  if (command.fromStage !== undefined || command.values !== undefined)
+    return "a run of a workflow with events takes no --from-stage or --values";
+  if (command.continueId !== undefined) {
+    if (command.workflowArgs.length > 0)
+      return "a continue takes no arguments: it goes on with those its run was started with";
+    return undefined;
+  }
+  const unkept = [
+    command.timeout === undefined ? undefined : "--timeout",
+    command.sandbox === undefined ? undefined : "--sandbox",
+    command.cwdGiven ? "--cwd" : undefined,
+    command.runRootGiven ? "--run-root" : undefined,
+  ].filter((flag) => flag !== undefined);
+  if (unkept.length > 0)
+    return `a run of a workflow with events runs in its file's project, as every wake starts it: it takes no ${unkept.join(", ")}`;
+  return undefined;
+}
+
 /** The id the workflow's `id(args)` gives a new run, checked; undefined when it has none. */
-function derivedId(
-  executable: ExecutableWorkflow<JsonValue, JsonValue>,
-  args: JsonValue,
-): string | undefined {
-  if (!executable.id) return undefined;
+function derivedId(workflow: AnyWorkflow, args: JsonValue): string | undefined {
+  if (!workflow.id) return undefined;
   let id: unknown;
   try {
-    id = executable.id(args);
+    id = workflow.id(args);
   } catch (error) {
     throw new RunRefused(`the workflow's id(args) failed: ${messageOf(error)}; --id gives one`);
   }
@@ -133,14 +201,14 @@ export async function claimNext(
   notice: (text: string) => void,
   now: number,
 ): Promise<Attempt> {
-  const { meta } = loaded.executable.definition;
+  const { meta } = loaded.workflow;
   const claimed = await claimAttempt(
     run,
     {
       file: loaded.file,
       ...(meta.version === undefined ? {} : { workflowVersion: meta.version }),
       flags: {
-        timeout: command.timeout,
+        ...(command.timeout === undefined ? {} : { timeout: command.timeout }),
         ...(command.fromStage === undefined ? {} : { fromStage: command.fromStage }),
       },
     },
@@ -149,6 +217,10 @@ export async function claimNext(
   if ("refused" in claimed) {
     throw new RunRefused(refusalMessage(run.record.id, claimed.refused, now));
   }
+  // An event run's: claimed first, which `wake` waits for holding the run's lock, then waited on
+  // before this attempt writes anything, so the attempt before it has finished its own records and
+  // two never share an agent's session.
+  if (run.record.events) await previousGone(run, claimed.attempt.record.attempt, notice);
   // A crash may have torn the last line an earlier attempt appended; this attempt's first line
   // must not be glued to it.
   await endTurnsLine(run.dir)

package/src/run-state.ts

@@ -1,7 +1,9 @@
 import { join } from "node:path";
-import type { AttemptRecord } from "@agentswf/contract/records";
+import type { AttemptRecord, MailboxRecord, WaitingJson } from "@agentswf/contract/records";
 import type { AttemptOutcome } from "@agentswf/contract/workflow";
 import { exists } from "./files";
+import { foldMailbox, nextTimer, readMailbox } from "./mailbox";
+import { listProjects, projectRunRoot } from "./projects";
 import {
   entries,
   idProblem,
@@ -20,7 +22,7 @@ export type ProcessStatus = (pid: number) => string | "gone" | "unknown";
  * `running`; open and its process gone, `interrupted`; or how its last attempt ended. Read from
  * `run.json` and the attempt files, never the event log, so a run an older awf wrote reads too.
  */
-export type RunState = "running" | "interrupted" | AttemptOutcome;
+export type RunState = "running" | "interrupted" | "stuck" | AttemptOutcome;
 
 export type RunStatus = {
   run: Run;
@@ -30,6 +32,8 @@ export type RunStatus = {
   state: RunState;
   /** False for a `running` whose process could not be asked about. */
   checked: boolean;
+  /** A run of a workflow with `events` at its wait, live or parked: what its mailbox says. */
+  waiting?: WaitingJson;
 };
 
 /** How long a run folder with no attempt yet may be an `awf run` still starting. */
@@ -40,7 +44,35 @@ export async function runStatus(
   probe: ProcessStatus = probeProcess,
   at = Date.now(),
 ): Promise<RunStatus> {
-  const attempts = await readAttempts(run);
+  const status = statusOf(run, await readAttempts(run), probe, at);
+  if (!run.record.events) return status;
+  const records = await readMailbox(run.dir);
+  const waiting = waitingOf(status, records);
+  const stuck = status.state !== "running" && stuckOf(status.attempts, records);
+  return { ...status, ...(waiting ? { waiting } : {}), ...(stuck ? { state: "stuck" } : {}) };
+}
+
+/** An event run's wait, while it is running or parked there: its label and `until`. */
+function waitingOf(status: RunStatus, records: readonly MailboxRecord[]): WaitingJson | undefined {
+  if (status.state !== "running" && status.state !== "parked") return undefined;
+  const state = foldMailbox(records);
+  const wait = state.lastWait;
+  // A wait an earlier attempt died in is not this one's.
+  if (!wait?.waiting || wait.attempt !== status.attempts.at(-1)?.attempt) return undefined;
+  const until = nextTimer(state, wait.takes);
+  return {
+    ...(wait.label === undefined ? {} : { label: wait.label }),
+    ...(until === undefined ? {} : { until: new Date(until).toISOString() }),
+  };
+}
+
+/** As `runStatus`, from its attempts as already read. */
+export function statusOf(
+  run: Run,
+  attempts: AttemptRecord[],
+  probe: ProcessStatus = probeProcess,
+  at = Date.now(),
+): RunStatus {
   const last = attempts.at(-1);
   const ref = `${run.record.workflow}/${run.record.id}`;
   // Between its folder and its first attempt's claim: an `awf run` starting, or, past a minute,
@@ -63,13 +95,19 @@ export class RunNotFound extends Error {}
 
 /**
  * Every run under `runRoot`, newest `created` first. A folder whose `run.json` cannot be read is
- * not a run this awf can show, and is passed over.
+ * not a run this awf can show, and is passed over. One `known` has, by its folder, is not read
+ * again: a run's record never changes.
  */
-export async function listRuns(runRoot: string): Promise<Run[]> {
+export async function listRuns(
+  runRoot: string,
+  known?: (dir: string) => Run | undefined,
+): Promise<Run[]> {
   const runs: Run[] = [];
   for (const workflow of await entries(runRoot).catch(() => [])) {
     for (const id of await entries(join(runRoot, workflow)).catch(() => [])) {
-      const run = await openRun(runRoot, workflow, id).catch(() => undefined);
+      const run =
+        known?.(join(runRoot, workflow, id)) ??
+        (await openRun(runRoot, workflow, id).catch(() => undefined));
       if (run) runs.push(run);
     }
   }
@@ -118,3 +156,84 @@ export async function findRun(
   }
   return { status: await runStatus(found[0]!, probe), alsoRunning: [] };
 }
+
+/** Failed or crashed attempts in a row, counted together, after which a run is `stuck` (Q13). */
+export const STUCK_AFTER = 3;
+
+/**
+ * Failed, timed-out or crashed attempts at the end of the run, and launches since the last attempt
+ * that never claimed one, counted together; any other ending resets them.
+ */
+function failuresInARow(
+  attempts: readonly AttemptRecord[],
+  records: readonly MailboxRecord[],
+): number {
+  const since = attempts.at(-1)?.started ?? "";
+  let n = records.filter((record) => record.kind === "launch-failed" && record.at > since).length;
+  for (const attempt of [...attempts].reverse()) {
+    const failed =
+      attempt.outcome === undefined ||
+      attempt.outcome === "failed" ||
+      attempt.outcome === "timed-out";
+    if (!failed) break;
+    n++;
+  }
+  return n;
+}
+
+/**
+ * Whether an event run is `stuck` (Q13): failed, crashed or failed to launch three times in a row,
+ * whatever its last ending says, short of one the operator or the code chose.
+ */
+export function stuckOf(
+  attempts: readonly AttemptRecord[],
+  records: readonly MailboxRecord[],
+): boolean {
+  const last = attempts.at(-1)?.outcome;
+  if (last === "completed" || last === "stopped" || last === "cancelled") return false;
+  return failuresInARow(attempts, records) >= STUCK_AFTER;
+}
+
+/**
+ * The run `ref` names, `{workflow}/{id}` or an `{id}` only one workflow has: under `--cwd`'s runs
+ * first, then in each project awf started an event run in (Q15). Every command that takes a run
+ * finds it here.
+ */
+export async function findRunByRef(
+  ref: string,
+  place: { runRoot: string },
+  home: string,
+): Promise<RunStatus> {
+  // Here first: what `--cwd` names wins.
+  let here: RunNotFound;
+  try {
+    return (await findRun(place.runRoot, ref)).status;
+  } catch (error) {
+    if (!(error instanceof RunNotFound)) throw error;
+    here = error;
+  }
+  const found: RunStatus[] = [];
+  for (const project of await listProjects(home)) {
+    try {
+      found.push((await findRun(projectRunRoot(project), ref)).status);
+    } catch (error) {
+      if (!(error instanceof RunNotFound)) throw error;
+    }
+  }
+  // Workflows of one name in two projects make the same ref: naming the project is the caller's.
+  if (found.length > 1)
+    throw new RunNotFound(
+      `${ref} is a run in ${found.length} projects, ${found.map((each) => each.run.record.cwd).join(" and ")}; --cwd names one`,
+    );
+  if (found[0]) return found[0];
+  // Nowhere: a ref that can't name a run, malformed or naming two workflows, says why.
+  if (malformedRef(ref) || here.message.includes("more than one workflow")) throw here;
+  throw new RunNotFound(`no run ${ref} under ${place.runRoot}, or in a project awf knows`);
+}
+
+/** Why `ref` can't name a run at all, whatever is on disk; undefined when it can. */
+function malformedRef(ref: string): string | undefined {
+  const slash = ref.indexOf("/");
+  if (slash < 0) return idProblem(ref);
+  return idProblem(ref.slice(0, slash)) ?? idProblem(ref.slice(slash + 1));
+}

package/src/run-usage.ts

@@ -31,7 +31,7 @@ export type AccountedAgent = {
   cwd: string;
   /** A sandboxed agent's own harness home, where its sessions are. */
   home?: string;
-  /** Every native session id seen for the agent so far, from its `wf` calls and its adapter. */
+  /** Every native session id seen for the agent so far, from its `wfa` calls and its adapter. */
   sessions(): readonly string[];
   /** When its host first prompted it, where that waits on the agent first; see `window`. */
   promptedAt?(): number | undefined;
@@ -83,7 +83,7 @@ export type RunLedger = {
   /** Every settled operation, with the sessions its agent has been seen with so far. */
   records(): OperationRecord[];
   /** Best effort: a turn still going at the deadline, or when the run is stopped, is killed. */
-  letFinish(runDeadline: AbsoluteDeadline, signal: AbortSignal): Promise<void>;
+  letFinish(runDeadline: AbsoluteDeadline | undefined, signal: AbortSignal): Promise<void>;
   /**
    * Every record, completed with what its agent spent. Called once the host has closed, because a
    * released turn still writes its last request after the engine has moved on (story 002,

package/src/run-view.ts

@@ -195,15 +195,6 @@ async function latestPhase(
   return (await readLines<OperationLivenessRecord>(file).catch(() => [])).at(-1);
 }
 
-/** `45s`, `6m40s`, `1h02m`. */
-export function duration(milliseconds: number): string {
-  const seconds = Math.max(0, Math.round(milliseconds / 1000));
-  if (seconds < 60) return `${seconds}s`;
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
-  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
-}
-
 /** An activity in a few words: `tool Bash bun test → exit 0`, `message 412 chars`. */
 export function describeActivity(activity: Activity): string {
   switch (activity.type) {

package/src/runs-command.ts

@@ -1,5 +1,8 @@
+import { homedir } from "node:os";
 import type { RunJson, RunsJson } from "@agentswf/contract/records";
+import { duration } from "./duration";
 import { messageOf } from "./errors";
+import help from "./help/runs.txt" with { type: "text" };
 import {
   clockTime,
   command,
@@ -18,20 +21,10 @@ import {
   stateWord,
 } from "./run-commands";
 import { encodeCursor } from "./run-read";
-import { findRun, listRuns, type RunStatus, runStatus } from "./run-state";
-import { type AgentView, describeActivity, duration, type RunView, viewRun } from "./run-view";
+import { findRunByRef, listRuns, type RunStatus, runStatus } from "./run-state";
+import { type AgentView, describeActivity, type RunView, viewRun } from "./run-view";
 
-export const runsUsage = [
-  "usage: awf runs [--all] [--cwd <directory>] [--run-root <directory>] [--json]",
-  "       awf runs <run> [--cwd <directory>] [--run-root <directory>] [--json]",
-  "",
-  "The runs here, newest first, or one run in depth: its attempts, the stages of the last, what",
-  "each agent is doing, and what to run next. A run is <workflow>/<id>, or an <id> only one",
-  "workflow here has. Runs are read under --cwd's .awf/runs, or --run-root, as awf run keeps them.",
-  "",
-  "--json prints one document, the interface for scripts. Exits 0 on any read that worked, 1 when",
-  "there is no such run, 2 on a usage error, 3 when the run's files could not be read.",
-].join("\n");
+export const runsUsage = help.trimEnd();
 
 const LISTED = 20;
 
@@ -40,31 +33,37 @@ export async function runsCommand(
   shellCwd: string,
   out: Out,
   now: number = Date.now(),
+  home: string = homedir(),
 ): Promise<number> {
   if (argv.includes("-h") || argv.includes("--help")) {
     out.stdout(runsUsage);
     return 0;
   }
   let parsed: ReturnType<typeof parsePlace>;
-  let all = false;
+  let limit: number | undefined;
   let ref: string | undefined;
   try {
     parsed = parsePlace(argv, shellCwd);
-    for (const arg of parsed.rest) {
-      if (arg === "--all") all = true;
-      else if (arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
+    for (let index = 0; index < parsed.rest.length; index++) {
+      const arg = parsed.rest[index]!;
+      if (arg === "--limit") {
+        limit = Number(parsed.rest[++index]);
+        if (!Number.isSafeInteger(limit) || limit < 1)
+          throw new Error("--limit needs a whole number");
+      } else if (arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
       else if (ref === undefined) ref = arg;
       else throw new Error(`one run at a time: ${ref} and ${arg}`);
     }
-    if (ref !== undefined && all) throw new Error("--all lists runs; it takes no run");
+    if (ref !== undefined && limit !== undefined)
+      throw new Error("--limit lists runs; it takes no run");
   } catch (error) {
     out.stderr(`awf: ${messageOf(error)}\n\n${runsUsage}`);
     return 2;
   }
   const { place, json } = parsed;
   try {
-    if (ref === undefined) return await list(place, all, json, out, now);
-    const view = await viewRun((await findRun(place.runRoot, ref)).status);
+    if (ref === undefined) return await list(place, limit ?? LISTED, json, out, now);
+    const view = await viewRun(await findRunByRef(ref, place, home));
     out.stdout(
       json ? JSON.stringify(runJson(view, place, now), null, 2) : describe(view, place, now),
     );
@@ -77,9 +76,9 @@ export async function runsCommand(
 /** A run listed, or why it could not be read: one bad run does not hide the others. */
 type Listed = { status: RunStatus } | { ref: string; unreadable: string };
 
-async function list(place: ReadPlace, all: boolean, json: boolean, out: Out, now: number) {
+async function list(place: ReadPlace, limit: number, json: boolean, out: Out, now: number) {
   const runs = await listRuns(place.runRoot);
-  const shown = all ? runs : runs.slice(0, LISTED);
+  const shown = runs.slice(0, limit);
   const listed: Listed[] = await Promise.all(
     shown.map((run) =>
       runStatus(run, undefined, now).then(
@@ -105,9 +104,14 @@ async function list(place: ReadPlace, all: boolean, json: boolean, out: Out, now
         started: new Date(started).toISOString(),
         ...(ended === undefined ? {} : { duration: ended - started }),
         ...(estimate === undefined ? {} : { estimate }),
+        ...(status.waiting ? { waiting: status.waiting } : {}),
       };
     });
-    const document: RunsJson = { v: 1, runs: runsJson, more: { older: older > 0 } };
+    const document: RunsJson = {
+      v: 1,
+      runs: runsJson,
+      ...(older > 0 ? { more: { older: true } } : {}),
+    };
     out.stdout(JSON.stringify(document, null, 2));
     return 0;
   }
@@ -124,21 +128,34 @@ async function list(place: ReadPlace, all: boolean, json: boolean, out: Out, now
     const { status } = each;
     const { started, ms } = span(status, now);
     const estimate = estimateOf(status.attempts);
+    const waiting = waitingText(status);
     return [
       status.ref.padEnd(width),
       states[index]!.padEnd(stateWidth),
       dayTime(started).padEnd(13),
       duration(ms).padEnd(8),
-      money(estimate).join(""),
+      money(estimate)
+        .join("")
+        .concat(waiting ? "  " : ""),
+      waiting,
     ]
       .join("")
       .trimEnd();
   });
-  if (older > 0) lines.push(`… ${older} older (--all)`);
+  if (older > 0) lines.push(`… ${older} older (--limit ${runs.length})`);
   out.stdout(lines.join("\n"));
   return 0;
 }
 
+/** A run at its wait: its label, and until when; a returned one, the events it never took. */
+function waitingText(status: RunStatus): string {
+  const { waiting } = status;
+  const never = status.attempts.at(-1)?.unacknowledged;
+  if (!waiting) return never ? `${never} event${never === 1 ? "" : "s"} never taken` : "";
+  const until = waiting.until ? `until ${dayTime(Date.parse(waiting.until))}` : "";
+  return [waiting.label, until].filter(Boolean).join(" · ") || "waiting";
+}
+
 function dayTime(at: number): string {
   const date = new Date(at);
   const two = (n: number) => String(n).padStart(2, "0");
@@ -300,6 +317,7 @@ function runJson(view: RunView, place: ReadPlace, now: number): RunJson {
       ...(view.stage ? { stage: view.stage } : {}),
       ...(status.state !== "running" && ended !== undefined ? { duration: ended - started } : {}),
       ...(view.estimate === undefined ? {} : { estimate: view.estimate }),
+      ...(status.waiting ? { waiting: status.waiting } : {}),
       dir: status.run.dir,
     },
     attempts: status.attempts.map(({ attempt, started, ended, outcome, stage, reason }) => ({