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

package/src/operation-liveness.ts

@@ -506,7 +506,7 @@ export async function superviseOperation(options: Options): Promise<SupervisedOu
           deliveryUntil === undefined &&
           receiptUntil === undefined;
         const messages = options.messages;
-        // Before any check-in: what continues it goes now, cutting a `wf waiting` short, and an
+        // Before any check-in: what continues it goes now, cutting a `wfa waiting` short, and an
         // operation awaiting an answer waits for it with no check-in.
         if (messages && settledTurn) {
           if (messages.pending() === "continues") {

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

@@ -56,7 +56,7 @@ export type OperatorRuntimeInstallation = {
   sandboxes?: SandboxProviders;
   /** The decision models workflows may ask, and their aliases. */
   decisions?: DecisionInstallation;
-  /** How `workflow.allowance` reads a harness's plan, as `awf allowance` does. */
+  /** How `wf.allowance` reads a harness's plan, as `awf allowance` does. */
   allowance?: (harness: Harness) => Promise<HarnessAllowance>;
   cleanup(): Promise<void>;
 };
@@ -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();
@@ -181,7 +181,7 @@ export async function installOperatorRuntime(
     sandboxes: await installSandboxes(environment),
     decisions: installDecisions({ OPENROUTER_API_KEY: await openRouterKey(environment) }),
     allowance: allowanceReader(environment, run, undefined, home),
-    // Nothing to undo: the agent's `wf` is a launcher the control plane installs beside its own
+    // Nothing to undo: the agent's `wfa` is a launcher the control plane installs beside its own
     // socket, and the control plane removes both when the run closes.
     cleanup: async () => undefined,
   };
@@ -282,9 +282,8 @@ export function herdrConfig(session: string): HerdrConfig {
 
 /**
  * The sandbox providers this machine has: srt when its CLI is on `PATH`, docker when its CLI is;
- * its daemon is first asked when a sandbox opens. srt is the default when installed, as it runs
- * the project's own toolchain, which an image lacks (story 004), and when it is there but cannot
- * be set up: a spec naming none then fails saying why, rather than moving to docker unsaid.
+ * its daemon is first asked when a sandbox opens. There is no default: a spec names its provider,
+ * since the two give agents different machines, the host's toolchain or an image.
  */
 export async function installSandboxes(
   environment: Readonly<Record<string, string | undefined>>,
@@ -304,10 +303,8 @@ export async function installSandboxes(
     ...(srt ? { srt: createSrtProvider(srt) } : {}),
     ...(docker ? { docker: createDockerProvider(docker) } : {}),
   };
-  const fallback = srt || unavailable.srt ? "srt" : docker ? "docker" : undefined;
   return {
     installed,
-    ...(fallback ? { default: fallback } : {}),
     ...(Object.keys(unavailable).length > 0 ? { unavailable } : {}),
   };
 }

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/result-validation.ts

@@ -8,7 +8,7 @@ export type CandidateEvaluation =
   | { kind: "rejected"; error: string };
 
 /**
- * A result as `wf` sent it, validated without repairing or persisting; the result-slot transition
+ * A result as `wfa` sent it, validated without repairing or persisting; the result-slot transition
  * owns acceptance.
  */
 export async function evaluateGiven(

package/src/run-command.ts

@@ -1,54 +1,15 @@
 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 = [
-  "usage: awf run [options] <workflow-file> [options] [-- workflow arguments...]",
-  "       awf run [options] <workflow-file> --id <id> --continue",
-  "run options: --id <id>, --continue, --from-stage <stage>, --values <file>,",
-  "             --timeout <duration>, --run-root <directory>, --cwd <directory>, --sandbox <file>,",
-  "             --json, --no-watch, --here",
-  "",
-  "Each awf run is an attempt of a run: a new run, with --id's id or a generated one, or, with",
-  "--continue, the run --id names, with the arguments, --cwd and --sandbox it was started with. A continue reuses",
-  "the stages that succeeded, up to the first with no record or to --from-stage, and runs the rest.",
-  "A new run with --from-stage starts there. A stage before it with no record to reuse takes its",
-  "value from --values, a JSON object by stage name, checked by its result; one that returns",
-  "nothing is passed. Without one the attempt stops, naming the stage and its schema.",
-  "A stop exits 3. A run is kept in .awf/runs/<workflow>/<id> under --cwd, unless --run-root names",
-  "another folder for .awf/runs.",
-  "A run has no deadline unless --timeout gives it one, per attempt.",
-  "A workflow that knows how to present its result prints that; --json prints the full result instead.",
-  "Either way the full result is kept as output.json in the run's folder, beside report.md",
-  "when the workflow writes one. A run that fails or is cancelled once its agents have started keeps",
-  "output.json too, with what it spent and why it ended; --json prints it. A second Ctrl-C stops",
-  "awf at once, without it.",
-  "--cwd sets the directory the workflow and its agents work in; it defaults to the current one.",
-  "--sandbox puts every agent of the run in one sandbox, working in --cwd; the file is a JSON spec",
-  'such as {"read": ["/data/request.md"], "srt": {}}, whose relative paths are from --cwd. A',
-  "workflow that opens a sandbox of its own is refused.",
-  "A sandbox with its own Herdr, as a docker box has, gets a tab in the run's workspace showing its",
-  "panes; --no-watch leaves it out, and awf still prints the command that shows them.",
-  "--here, run by an agent in a Herdr pane, starts the run in a new tab and has it take that agent's",
-  "session over as one of its agents, from its next turn until the run ends. It prints a line for",
-  "the agent to end its turn with, which is how the run finds the session.",
-  "A run of a workflow with events is named by --id, or by the workflow's id(args). awf run starts it",
-  "with its arguments and no event, detached in its project, as awf emit would, and the run waits at",
-  "its first receive. A run already there is only woken. A run an event starts has no argv: its args",
-  "are what prepare makes of none.",
-  "",
-  "Examples:",
-  "  awf run examples/minimum-review/review-loop.ts",
-  "  awf run --timeout 20m examples/minimum-review/review-loop.ts",
-  "  awf run examples/minimum-review/review-loop.ts -- packages/engine/src",
-  "  awf run examples/minimum-review/review-loop.ts --cwd ../other-repo",
-  "",
-  "Workflow files are trusted code and run with your filesystem and process authority.",
-].join("\n");
+export const usage = help.trimEnd();
 
 export type RunCommand = {
   /** Where paths typed on the command line resolve. */
@@ -78,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. */
@@ -85,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);
@@ -104,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;
@@ -132,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");
@@ -163,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");
@@ -201,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"] : []),
   ];
 }