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

package/src/operator-cli.ts

@@ -47,7 +47,13 @@ import { ANSI, describeRunSession, type Terminal, watchProgress } from "./progre
 import { parseCommand, type RunCommand, usage } from "./run-command";
 import { placeFlags, shellLine, startedLine } from "./run-commands";
 import { runLockFile, withRunLock } from "./run-lock";
-import { claimNext, loadAndPrepare, type PreparedRun, workspaceLabel } from "./run-prepare";
+import {
+  claimNext,
+  loadAndPrepare,
+  type OpensEventRun,
+  type PreparedRun,
+  workspaceLabel,
+} from "./run-prepare";
 import { findRun } from "./run-state";
 import { type Attempt, createRun, discardRun, endAttempt, type Run, RunRefused } from "./runs";
 import { runsCommand } from "./runs-command";
@@ -254,16 +260,22 @@ function help(
  * an event starts one, so it runs to its first wait and parks; one already there is only woken.
  */
 async function openRun(
-  { loaded, id, argv }: { loaded: LoadedWorkflow; id: string; argv: readonly string[] },
+  { loaded, id, argv, panes }: OpensEventRun,
   environment: OperatorEnvironment,
   { stdout, stderr }: Output,
 ): Promise<number> {
   try {
-    const opened = await openEventRun(loaded.workflow as EventWorkflow, id, argv, {
-      home: environment.home ?? homedir(),
-      environment: environment.environment ?? process.env,
-      ...(environment.launch ? { launch: environment.launch } : {}),
-    });
+    const opened = await openEventRun(
+      loaded.workflow as EventWorkflow,
+      id,
+      argv,
+      {
+        home: environment.home ?? homedir(),
+        environment: environment.environment ?? process.env,
+        ...(environment.launch ? { launch: environment.launch } : {}),
+      },
+      panes,
+    );
     const did = opened.did === "none" ? opened.why : opened.did;
     stdout(
       `${opened.run}${opened.created ? "" : " was there"}${did === undefined ? "" : `: ${did}`}`,
@@ -285,7 +297,7 @@ async function runCommand(
   const { stdout, stderr, notice, terminal, now } = output;
   let parsed: RunCommand | "help";
   try {
-    parsed = parseCommand(argv, environment.cwd ?? process.cwd());
+    parsed = parseCommand(argv, environment.cwd ?? process.cwd(), stderr);
   } catch (error) {
     stderr(`awf: ${messageOf(error)}\n\n${usage}`);
     return 2;
@@ -423,6 +435,7 @@ async function runAttempt(
         argv: command.workflowArgs,
         cwd: command.cwd,
         sandbox: (command.sandbox ?? null) as JsonValue,
+        ...(command.panes ? { panes: command.panes } : {}),
       }));
   } catch (error) {
     return refuse(
@@ -505,7 +518,7 @@ async function runAttempt(
     await handOver(toldOf(end, kept));
     return close(end, kept, cleanupAlso);
   };
-  // Relied on: the session is told only from a pane agent's `openRun`, inside `startWorkflow`, by
+  // Relied on: the session is told only from a TUI agent's `openRun`, inside `startWorkflow`, by
   // when `placed` says it on the progress.
   let placed: (session: RunSession) => void = () => undefined;
   let installed: OperatorRuntimeInstallation;
@@ -581,6 +594,7 @@ async function runAttempt(
         label: workspaceLabel(meta.name, id, n),
         ...(command.fromStage === undefined ? {} : { fromStage: command.fromStage }),
         ...(command.values === undefined ? {} : { values: command.values.stages }),
+        ...(run.record.panes ? { panes: run.record.panes } : {}),
         ...(!events
           ? {}
           : {

package/src/operator-runtime.ts

@@ -75,12 +75,12 @@ export type OperatorRuntimeOptions = {
   shellCwd?: string;
   /** The operator's home. */
   home?: string;
-  /** Told once, when the first pane agent's session is ready. */
+  /** Told once, when the first TUI agent's session is ready. */
   onRunSession?: (session: RunSession) => void;
 };
 
 /**
- * One run host for every agent: a Herdr tab for a pane agent, a subprocess per turn for a
+ * One run host for every agent: a Herdr tab for a TUI agent, a subprocess per turn for a
  * headless one. `WITHHELD_ENVIRONMENT` is cleared from both.
  */
 export async function installOperatorRuntime(
@@ -98,7 +98,7 @@ export async function installOperatorRuntime(
   } = options;
   const unmetered = withholding(run, WITHHELD_ENVIRONMENT);
   refuseMeteredCredentials(environment);
-  // Checked now, before any stage spends anything; made ready only for the first pane agent.
+  // Checked now, before any stage spends anything; made ready only for the first TUI agent.
   const name = runSessionName(environment);
   const session = runSessionOnce(() => name, { run, environment, home }, onRunSession);
   const runConfig = (session: string): HerdrConfig => ({
@@ -119,9 +119,9 @@ export async function installOperatorRuntime(
   const host = loginChecked(
     unmetered,
     createPlacementHostFactory({
-      // The session is made ready when the first pane agent opens, so an all-headless run never
+      // The session is made ready when the first TUI agent opens, so an all-headless run never
       // calls Herdr.
-      pane: {
+      tui: {
         accounting: createSessionAccounting(unmetered),
         openRun: async (spec) => {
           const { name } = await session();

package/src/pane-layout.ts

@@ -1,4 +1,11 @@
-import type { KeepPane, PaneLayout, TurnOutcome } from "@agentswf/contract/workflow";
+import type { RunPanes } from "@agentswf/contract/records";
+import type {
+  KeepPane,
+  PaneLayout,
+  PaneSpec,
+  PaneWorkspace,
+  TurnOutcome,
+} from "@agentswf/contract/workflow";
 
 /** A terminal session's name: Herdr makes `sessions/{name}` from it, and a leading `-` reads as an option. */
 export const SESSION_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
@@ -6,53 +13,75 @@ export const SESSION_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
 const SHARE = { min: 0.2, max: 0.8 };
 const NEW_TAB_FIELDS = new Set(["session", "workspace", "tab"]);
 const BESIDE_FIELDS = new Set(["beside", "side", "share"]);
-const KEEP: readonly KeepPane[] = ["never", "on-failure", "always"];
+export const KEEP_PANES: readonly KeepPane[] = ["never", "on-failure", "always"];
+
+type WrittenPane = { pane?: unknown; layout?: unknown; keepPane?: unknown };
 
 /**
  * Refuses, before anything is placed, what the agent's own spec fixes about its pane: what a
- * workflow, untyped at run time, could get wrong in `layout` or `keepPane`, and either on an agent
- * with no pane of awf's to place (docs/design/pane-layout.md, "Refused at open").
+ * workflow, untyped at run time, could get wrong in `pane`, `layout` or `keepPane`, and any of them
+ * on an agent with no pane of awf's to place (docs/design/pane-layout.md, "Refused at open").
  */
 export function checkPaneOptions(
   key: string,
-  spec: { layout?: unknown; keepPane?: unknown },
+  spec: WrittenPane,
   agent: { headless: boolean; sandboxed: boolean },
 ): void {
   const refuse = (why: string): never => {
     throw new Error(`agent ${key}: ${why}`);
   };
-  if (spec.layout === undefined && spec.keepPane === undefined) return;
-  if (agent.headless) refuse("layout and keepPane place a pane, and a headless agent has none");
+  if (spec.pane === undefined && spec.layout === undefined && spec.keepPane === undefined) return;
+  const old = spec.pane === undefined;
+  if (agent.headless) {
+    refuse(
+      `${old ? "layout and keepPane place" : "pane places"} a pane, and a headless agent has none`,
+    );
+  }
   if (agent.sandboxed) {
     refuse(
-      "layout and keepPane are not yet for an agent in a sandbox, whose pane is in its own Herdr",
+      `${old ? "layout and keepPane are" : "pane is"} not yet for an agent in a sandbox, whose pane is in its own Herdr`,
     );
   }
-  if (spec.keepPane !== undefined && !KEEP.includes(spec.keepPane as KeepPane)) {
+  if (spec.pane !== undefined && spec.layout !== undefined) {
+    refuse("give pane, not layout beside it: layout is deprecated");
+  }
+  if (spec.keepPane !== undefined && !KEEP_PANES.includes(spec.keepPane as KeepPane)) {
     refuse(`keepPane is never, on-failure or always, not ${JSON.stringify(spec.keepPane)}`);
   }
-  if (spec.layout === undefined) return;
-  const layout = spec.layout;
-  if (typeof layout !== "object" || layout === null || Array.isArray(layout)) {
-    refuse(`a layout is an object, not ${JSON.stringify(layout)}`);
+  if (spec.pane !== undefined) checkShape(key, "pane", spec.pane, refuse);
+  if (spec.layout !== undefined) checkShape(key, "layout", spec.layout, refuse);
+}
+
+function checkShape(
+  key: string,
+  named: "pane" | "layout",
+  given: unknown,
+  refuse: (why: string) => never,
+): void {
+  const a = named === "pane" ? "a pane" : "a layout";
+  if (typeof given !== "object" || given === null || Array.isArray(given)) {
+    refuse(`${a} is an object, not ${JSON.stringify(given)}`);
   }
-  const fields = Object.keys(layout as object).filter(
-    (field) => (layout as Record<string, unknown>)[field] !== undefined,
+  const layout = given as Record<string, unknown>;
+  const fields = Object.keys(layout).filter(
+    (field) => layout[field] !== undefined && !(named === "pane" && field === "front"),
   );
-  const given = layout as Record<string, unknown>;
-  if (given.beside !== undefined) {
+  if (named === "pane" && layout.front !== undefined && typeof layout.front !== "boolean") {
+    refuse(`front is true or false, not ${JSON.stringify(layout.front)}`);
+  }
+  if (layout.beside !== undefined) {
     const others = fields.filter((field) => !BESIDE_FIELDS.has(field));
     if (others.length > 0) {
-      refuse(`a layout beside another pane takes side and share, not ${others.join(", ")}`);
+      refuse(`${a} beside another pane takes side and share, not ${others.join(", ")}`);
     }
-    if (typeof given.beside !== "string" || given.beside === "") {
-      refuse(`beside names an agent's key, not ${JSON.stringify(given.beside)}`);
+    if (typeof layout.beside !== "string" || layout.beside === "") {
+      refuse(`beside names an agent's key, not ${JSON.stringify(layout.beside)}`);
     }
-    if (given.beside === key) refuse("a pane cannot be placed beside itself");
-    if (given.side !== "right" && given.side !== "below") {
-      refuse(`side is right or below, not ${JSON.stringify(given.side)}`);
+    if (layout.beside === key) refuse("a pane cannot be placed beside itself");
+    if (layout.side !== "right" && layout.side !== "below") {
+      refuse(`side is right or below, not ${JSON.stringify(layout.side)}`);
     }
-    const share = given.share;
+    const share = layout.share;
     if (
       share !== undefined &&
       (typeof share !== "number" || !(share >= SHARE.min && share <= SHARE.max))
@@ -61,13 +90,16 @@ export function checkPaneOptions(
     }
     return;
   }
-  const others = fields.filter((field) => !NEW_TAB_FIELDS.has(field));
+  const allowed = named === "pane" ? new Set(["tab"]) : NEW_TAB_FIELDS;
+  const others = fields.filter((field) => !allowed.has(field));
   if (others.length > 0) {
     refuse(
-      `a layout takes session, workspace and tab, or beside and side; not ${others.join(", ")}`,
+      named === "pane"
+        ? `a pane takes tab, or beside and side, and front; not ${others.join(", ")}${others.some((field) => field === "workspace" || field === "session") ? ": the workspace is the operator's, awf run --workspace" : ""}`
+        : `a layout takes session, workspace and tab, or beside and side; not ${others.join(", ")}`,
     );
   }
-  const { session, workspace, tab } = given;
+  const { session, workspace, tab } = layout;
   if (session !== undefined && (typeof session !== "string" || !SESSION_NAME.test(session))) {
     refuse(
       `session ${JSON.stringify(session)} is not a session name: lowercase letters, digits and -, up to 32, not starting with -`,
@@ -94,13 +126,17 @@ export function checkPaneOptions(
 }
 
 /**
- * A checked layout as it is kept and compared: fields given as `undefined` dropped, so a reopen
- * that leaves one out matches.
+ * A checked `pane` or `layout` as it is kept and compared: fields given as `undefined` dropped, and
+ * `front: false`, which is its absence, so a reopen that leaves one out matches.
  */
-export function storedLayout(layout: PaneLayout): PaneLayout {
+export function storedLayout<T extends PaneLayout | PaneSpec>(layout: T): T {
+  // Not an object, it is left for `checkPaneOptions` to refuse by name.
+  if (typeof layout !== "object" || layout === null || Array.isArray(layout)) return layout;
   return Object.fromEntries(
-    Object.entries(structuredClone(layout)).filter(([, value]) => value !== undefined),
-  ) as PaneLayout;
+    Object.entries(structuredClone(layout)).filter(
+      ([field, value]) => value !== undefined && !(field === "front" && value === false),
+    ),
+  ) as T;
 }
 
 function nonEmpty(value: unknown): value is string {
@@ -112,6 +148,57 @@ export function besideOf(layout: PaneLayout | undefined): string | undefined {
   return layout && "beside" in layout ? layout.beside : undefined;
 }
 
+/** What the host is asked for one agent's pane. */
+export type PaneAsked = {
+  layout?: PaneLayout;
+  front?: true;
+  keepPane?: KeepPane;
+  /** For a pane beside another: where its own tab opens if its target has no pane. */
+  fallbackWorkspace?: PaneWorkspace;
+};
+
+/**
+ * What the host is asked for an agent's pane: the workflow's tab or neighbour and `front`, in the
+ * operator's workspace and kept as the operator says. The operator's flags win over a deprecated
+ * `layout`'s session and workspace and a deprecated `keepPane`; absent, those apply as before. An
+ * agent with no pane of awf's, headless or in a sandbox, is asked nothing.
+ */
+export function paneAsked(
+  written: { pane?: PaneSpec; layout?: PaneLayout; keepPane?: KeepPane },
+  run: RunPanes | undefined,
+  hasPane: boolean,
+): PaneAsked {
+  if (!hasPane) return {};
+  const keepPane = run?.keep ?? written.keepPane;
+  const workspace = run?.workspace;
+  const layout = placedLayout(written, workspace);
+  return {
+    ...(layout === undefined ? {} : { layout }),
+    ...(written.pane?.front ? { front: true as const } : {}),
+    ...(keepPane === undefined ? {} : { keepPane }),
+    ...(besideOf(layout) !== undefined && workspace !== undefined
+      ? { fallbackWorkspace: workspace }
+      : {}),
+  };
+}
+
+function placedLayout(
+  { pane, layout }: { pane?: PaneSpec; layout?: PaneLayout },
+  workspace: PaneWorkspace | undefined,
+): PaneLayout | undefined {
+  const written = pane ?? layout;
+  if (written?.beside !== undefined) {
+    const { beside, side, share } = written;
+    return { beside, side, ...(share === undefined ? {} : { share }) };
+  }
+  const tab = written?.tab;
+  if (workspace !== undefined) {
+    return { workspace, ...(tab === undefined ? {} : { tab }) };
+  }
+  if (layout !== undefined) return layout;
+  return tab === undefined ? undefined : { tab };
+}
+
 /**
  * Whether a done agent's pane stays, by `keepPane` and how its last operation ended: `on-failure`
  * keeps it unless that was answered, or there was none.
@@ -123,3 +210,9 @@ export function keepsPane(
   if (keepPane === "always") return true;
   return keepPane === "on-failure" && last !== undefined && last !== "answered";
 }
+
+/** `--workspace`'s value: the two keywords, else a workspace's label. */
+export function parseWorkspace(value: string): PaneWorkspace {
+  if (value === "run" || value === "origin") return value;
+  return { name: value };
+}

package/src/progress-view.ts

@@ -40,7 +40,7 @@ export function renderProgress(
     paint: Paint;
     /** Once the run is over: what each stage's agents cost, by stage. */
     figures?: ReadonlyMap<string, string>;
-    /** The Herdr session pane agents opened in, once one has. */
+    /** The Herdr session TUI agents opened in, once one has. */
     herdrSession?: string;
   },
 ): string[] {
@@ -168,7 +168,7 @@ export function progressEvents(
         turn.phase === "waiting"
           ? `waiting (agent-reported): ${oneLine(turn.waitingReason ?? "")}${turn.checkInAt === undefined ? "" : ` · check-in at ${clock(turn.checkInAt - view.startedAt)}`}`
           : turn.phase === "awaiting-reply"
-            ? `awaiting ${oneLine(turn.waitingReason ?? "a reply")}${turn.checkInAt === undefined ? "" : ` · until ${clock(turn.checkInAt - view.startedAt)}`}`
+            ? `awaiting-reply${turn.waitingReason === undefined ? "" : ` from ${oneLine(turn.waitingReason)}`}${turn.checkInAt === undefined ? "" : ` · until ${clock(turn.checkInAt - view.startedAt)}`}`
             : oneLine(turn.phase.replaceAll("-", " "));
       add(view.now, "agent phase", `… ${oneLine(agent.key)} · ${note}`);
     }
@@ -400,7 +400,7 @@ function agentState(
 function awaitingNote(turn: NonNullable<Agent["turn"]>, now: number): string {
   const since = turn.phaseAt ?? turn.startedAt;
   const of = turn.checkInAt === undefined ? "" : ` of ${duration(turn.checkInAt - since)}`;
-  return `awaiting ${oneLine(turn.waitingReason ?? "a reply")} · ${duration(Math.max(0, now - since))}${of}`;
+  return `awaiting-reply${turn.waitingReason === undefined ? "" : ` from ${oneLine(turn.waitingReason)}`} · ${duration(Math.max(0, now - since))}${of}`;
 }
 
 /** A message admitted: who to whom, its size, and whether it asks or answers. */
@@ -412,20 +412,20 @@ export function messageLine(message: WorkflowRunSnapshot["messages"][number]): s
 }
 
 /**
- * Where to see a pane agent Herdr read as blocked on a prompt: its session plays no sound, so this
+ * Where to see a TUI agent Herdr read as blocked on a prompt: its session plays no sound, so this
  * is the one sign. Not the calling session's, which is the operator's own pane.
  */
 function whereBlocked(agent: Agent, herdrSession: string | undefined): string {
   return agent.turn?.outcome === "blocked" &&
     herdrSession !== undefined &&
-    placementOf(agent.execution) === "pane" &&
+    placementOf(agent.execution) === "tui" &&
     !agent.execution.caller
     ? ` · herdr session attach ${herdrSession}`
     : "";
 }
 
 /**
- * Where a run's pane agents are, said once as the first opens; the workspace closes with the run.
+ * Where a run's TUI agents are, said once as the first opens; the workspace closes with the run.
  * A client inside Herdr can't attach to another session, so from there it says where to.
  */
 export function describeRunSession(
@@ -519,7 +519,7 @@ export function watchProgress(
   let handle: WorkflowRunHandle<JsonValue> | undefined;
   let last: WorkflowRunSnapshot | undefined;
   let herdrSession: string | undefined;
-  // A pane agent's session can be ready after the run has ended, as a cancel lands while it starts:
+  // A TUI agent's session can be ready after the run has ended, as a cancel lands while it starts:
   // nothing is said under the closing block.
   let stopped = false;
   let drawn = 0;
@@ -594,7 +594,7 @@ export function watchProgress(
       if (under) clear();
       else tick();
     },
-    /** The Herdr session pane agents opened in, which a blocked one's line names. */
+    /** The Herdr session TUI agents opened in, which a blocked one's line names. */
     placedIn(session: string) {
       if (!stopped) herdrSession = session;
     },

package/src/run-command.ts

@@ -1,10 +1,12 @@
 import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
-import type { JsonValue } from "@agentswf/contract/workflow";
+import type { RunPanes } from "@agentswf/contract/records";
+import type { JsonValue, KeepPane } from "@agentswf/contract/workflow";
 import { parseDuration } from "./duration";
 import { messageOf } from "./errors";
 import help from "./help/run.txt" with { type: "text" };
 import { SESSION_CODE } from "./here";
+import { KEEP_PANES, parseWorkspace } from "./pane-layout";
 import { idProblem, runRootOf, stageNameProblem } from "./runs";
 
 export const usage = help.trimEnd();
@@ -37,6 +39,8 @@ export type RunCommand = {
   watch: boolean;
   /** The sandbox every agent runs in, as `--sandbox`'s file gave it. */
   sandbox?: unknown;
+  /** `--workspace` and `--keep-panes`, which the run records; absent, neither was given. */
+  panes?: RunPanes;
   /** Started from an agent's shell: start the run in a tab and take that session over. */
   here: boolean;
   /** The code the calling session replies with, which the run finds it by. */
@@ -44,7 +48,12 @@ export type RunCommand = {
 };
 
 /** `awf run`'s options and workflow; `"help"` for a `-h` or `--help` anywhere before `--`. */
-export function parseCommand(argv: readonly string[], cwd: string): RunCommand | "help" {
+export function parseCommand(
+  argv: readonly string[],
+  cwd: string,
+  /** Told each deprecated form given, once. */
+  deprecated: (line: string) => void = () => {},
+): RunCommand | "help" {
   if (argv[0] !== "run") throw new Error("expected the run command");
   const end = argv.indexOf("--");
   const own = end < 0 ? argv : argv.slice(0, end);
@@ -63,6 +72,7 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
   let sandbox: unknown;
   let here = false;
   let session: string | undefined;
+  const panes: RunPanes = {};
   let workflowFile: string | undefined;
   // awf's own options may come before or after the workflow file; only `--` ends them.
   let index = 1;
@@ -91,8 +101,8 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
     }
     const value = argv[index + 1];
     if (option === "--timeout") {
-      if (!value) throw new Error("--timeout needs a duration such as 30m");
-      timeoutMilliseconds = parseDuration(value);
+      if (!value) throw new Error("--timeout needs a duration such as 30m or 1d");
+      timeoutMilliseconds = parseDuration(value, "--timeout", deprecated);
       timeout = value;
     } else if (option === "--run-root") {
       if (!value) throw new Error("--run-root needs a directory");
@@ -122,6 +132,16 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
       if (!value || !SESSION_CODE.test(value))
         throw new Error("--session needs the code --here printed");
       session = value;
+    } else if (option === "--workspace") {
+      if (!value?.trim() || value.startsWith("-"))
+        throw new Error("--workspace needs run, origin or a workspace's name");
+      if (panes.workspace !== undefined) throw new Error("--workspace given twice");
+      panes.workspace = parseWorkspace(value);
+    } else if (option === "--keep-panes") {
+      if (!KEEP_PANES.includes(value as KeepPane))
+        throw new Error("--keep-panes needs never, on-failure or always");
+      if (panes.keep !== undefined) throw new Error("--keep-panes given twice");
+      panes.keep = value as KeepPane;
     } else if (option === "--sandbox") {
       if (!value) throw new Error("--sandbox needs a JSON file");
       if (sandbox !== undefined) throw new Error("--sandbox given twice");
@@ -160,6 +180,7 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
     here,
     ...(session === undefined ? {} : { session }),
     ...(sandbox === undefined ? {} : { sandbox }),
+    ...(Object.keys(panes).length === 0 ? {} : { panes }),
   };
 }
 

package/src/run-commands.ts

@@ -137,7 +137,7 @@ export function nextLogs(
     ...filters,
     "--after",
     encodeCursor(cursor),
-    ...(wait ? ["--wait", "90"] : []),
+    ...(wait ? ["--wait", "90s"] : []),
   ];
 }
 

package/src/run-prepare.ts

@@ -1,9 +1,11 @@
 import { statSync } from "node:fs";
 import { homedir } from "node:os";
-import { type AttemptRecord, RUN_EVENT_VERSIONS } from "@agentswf/contract/records";
+import { join } from "node:path";
+import { type AttemptRecord, RUN_EVENT_VERSIONS, type RunPanes } from "@agentswf/contract/records";
 import { isEventWorkflow, type JsonValue } from "@agentswf/contract/workflow";
 import { refusalMessage } from "./attempt-view";
 import { messageOf } from "./errors";
+import { exists } from "./files";
 import { projectOf, projectRunRoot } from "./projects";
 import type { RunCommand } from "./run-command";
 import {
@@ -14,6 +16,7 @@ import {
   checkFree,
   claimAttempt,
   endTurnsLine,
+  generateId,
   idProblem,
   openRun,
   previousGone,
@@ -38,6 +41,14 @@ export type PreparedRun = {
   continued?: { run: Run; attempts: AttemptRecord[]; warnings: string[] };
 };
 
+/** `awf run --id` of a workflow with events, which starts the run detached, or wakes it. */
+export type OpensEventRun = {
+  loaded: LoadedWorkflow;
+  id: string;
+  argv: readonly string[];
+  panes?: RunPanes;
+};
+
 /**
  * The command's workflow loaded and its run prepared, or why not, as awf says it: in the shell that
  * typed the command, before anything starts.
@@ -49,7 +60,7 @@ export async function loadAndPrepare(
 ): Promise<
   | { loaded: LoadedWorkflow; prepared: PreparedRun; command: RunCommand }
   | { refused: string }
-  | { opens: { loaded: LoadedWorkflow; id: string; argv: readonly string[] } }
+  | { opens: OpensEventRun }
 > {
   let loaded: LoadedWorkflow;
   try {
@@ -74,12 +85,23 @@ export async function loadAndPrepare(
       try {
         const id =
           command.id ??
-          derivedId(loaded.workflow, prepareArgs(loaded.workflow, command.workflowArgs, project));
+          derivedId(loaded.workflow, prepareArgs(loaded.workflow, command.workflowArgs, project)) ??
+          // Without starts no sender names its runs, so one may be generated, as a plain run's is.
+          (loaded.workflow.starts === undefined
+            ? await unusedId(command.runRoot, loaded.workflow.meta.name, now)
+            : undefined);
         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`,
+            refused: `a run of ${loaded.file}, which starts on events, 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 } };
+        return {
+          opens: {
+            loaded,
+            id,
+            argv: command.workflowArgs,
+            ...(command.panes ? { panes: command.panes } : {}),
+          },
+        };
       } catch (error) {
         return { refused: `${error instanceof RunRefused ? "" : "prepare: "}${messageOf(error)}` };
       }
@@ -115,6 +137,7 @@ async function prepareRun(
     argv: command.workflowArgs,
     ...(command.cwdGiven ? { cwd: command.cwd } : {}),
     ...(command.sandbox === undefined ? {} : { sandbox: command.sandbox }),
+    ...(command.panes === undefined ? {} : { panes: command.panes }),
   });
   const { id, argv, cwd } = run.record;
   if (!statSync(cwd, { throwIfNoEntry: false })?.isDirectory()) {
@@ -155,13 +178,28 @@ export function prepareArgs(
   return args;
 }
 
+/**
+ * A generated id no run of `workflow` holds: `awf run` of one already there would wake it. Taken
+ * between this and the open, by a run started the same minute with the same four digits, it is.
+ */
+async function unusedId(runRoot: string, workflow: string, now: number): Promise<string> {
+  for (let tries = 1; ; tries += 1) {
+    const id = generateId(new Date(now));
+    if (!(await exists(join(runRoot, workflow, id)))) return id;
+    if (tries >= 5) throw new RunRefused("every id generated was taken; --id gives one");
+  }
+}
+
 /**
  * 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.
+ * started by a wake, which passes on none of the flags a run would have to keep. A `--from-stage`
+ * is the one attempt's, and its records keep what it redid.
  */
 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.values !== undefined)
+    return "a run of a workflow with events takes no --values: before --from-stage, a stage with no record runs";
+  if (command.fromStage !== undefined && command.continueId === undefined)
+    return "a run of a workflow with events takes --from-stage only with --continue";
   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";

package/src/run-usage.ts

@@ -35,7 +35,7 @@ export type AccountedAgent = {
   sessions(): readonly string[];
   /** When its host first prompted it, where that waits on the agent first; see `window`. */
   promptedAt?(): number | undefined;
-  /** The caller handed back early by agents.stop. */
+  /** The caller handed back early by its close(). */
   releasedAt?(): number | undefined;
   /** When a fork's session was made: what it holds from before is its parent's (ADR 0009). */
   forkedAt?(): number | undefined;