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

package/src/duration.ts

@@ -1,18 +1,48 @@
-/** A duration such as `500ms`, `30s`, `20m` or `2h`, in milliseconds. */
-export function parseDuration(value: string): number {
-  const matched = /^(\d+)(ms|s|m|h)$/.exec(value);
-  if (!matched) throw new Error(`invalid duration: ${value}`);
-  const amount = Number(matched[1]);
-  if (!Number.isSafeInteger(amount) || amount <= 0) throw new Error(`invalid duration: ${value}`);
-  const unit = matched[2];
-  const multiplier = unit === "ms" ? 1 : unit === "s" ? 1_000 : unit === "m" ? 60_000 : 3_600_000;
-  const milliseconds = amount * multiplier;
-  if (!Number.isSafeInteger(milliseconds)) throw new Error(`duration is too large: ${value}`);
+import { durationMilliseconds, positiveDurationMilliseconds } from "@agentswf/contract/workflow";
+import { deprecationLine } from "./deprecations";
+import { messageOf } from "./errors";
+
+/**
+ * A flag's duration in milliseconds, longer than none: the one grammar, `"90s"`, `"1.5h"`, `"1d"`.
+ * A whole number of `ms`, which the CLI took before, is read until 0.1.0 and `deprecated` told.
+ */
+export function parseDuration(
+  value: string,
+  flag: string,
+  deprecated: (line: string) => void,
+): number {
+  const ms = /^(\d+)ms$/.exec(value);
+  if (!ms) return positiveDurationMilliseconds(value, flag);
+  const milliseconds = Number(ms[1]);
+  if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0)
+    throw new Error(`${flag} is a positive duration: not ${value}`);
+  deprecated(deprecationLine("duration-ms", value));
   return milliseconds;
 }
 
+/**
+ * `--wait`, in seconds from none to `maxSeconds`: a duration, `"90s"`. A bare number of seconds,
+ * which it took before, is read until 0.1.0 and `deprecated` told.
+ */
+export function parseWait(
+  value: string,
+  maxSeconds: number,
+  deprecated: (line: string) => void,
+): number {
+  const bare = /^\d+(\.\d+)?$/.test(value);
+  let seconds: number;
+  try {
+    seconds = bare ? Number(value) : durationMilliseconds(value) / 1000;
+  } catch (error) {
+    throw new Error(`--wait takes a duration up to ${maxSeconds}s: ${messageOf(error)}`);
+  }
+  if (seconds > maxSeconds) throw new Error(`--wait takes a duration up to ${maxSeconds}s`);
+  if (bare) deprecated(deprecationLine("wait-seconds", value));
+  return seconds;
+}
+
 /** `45s`, `6m40s`, `1h02m`. */
-export function duration(milliseconds: number): string {
+export function formatDuration(milliseconds: number): string {
   const seconds = Math.max(0, Math.round(milliseconds / 1000));
   if (seconds < 60) return `${seconds}s`;
   const minutes = Math.floor(seconds / 60);
@@ -22,8 +52,8 @@ export function duration(milliseconds: number): string {
 
 /**
  * When a timer given `when` is due, epoch ms, from `now`, and `when` as its record keeps it: a
- * duration of days, hours or minutes as given, or a `Date` as an ISO time. A workflow's grammar,
- * apart from the CLI's `parseDuration`: a wait is days long, and `1.5h` reads as written.
+ * `Duration` as given, or a `Date` as an ISO time. A workflow's grammar, apart from the CLI's
+ * `parseDuration`: a wait is days long, and `1.5h` reads as written.
  */
 export function parseWhen(when: unknown, now: number): { due: number; when: string } {
   if (when instanceof Date) {
@@ -31,11 +61,11 @@ export function parseWhen(when: unknown, now: number): { due: number; when: stri
     if (!Number.isFinite(due)) throw new Error("a timer's time is a valid Date");
     return { due, when: when.toISOString() };
   }
-  const matched = typeof when === "string" ? /^(\d+(?:\.\d+)?)(d|h|m)$/.exec(when) : null;
-  if (!matched)
-    throw new Error(
-      `a timer is due in days, hours or minutes, "14d", "4h", "1.5h", or at a Date; not ${String(when)}`,
-    );
-  const unit = matched[2] === "d" ? 86_400_000 : matched[2] === "h" ? 3_600_000 : 60_000;
-  return { due: now + Math.round(Number(matched[1]) * unit), when: when as string };
+  let milliseconds: number;
+  try {
+    milliseconds = durationMilliseconds(when);
+  } catch (error) {
+    throw new Error(`a timer is due in a duration or at a Date: ${messageOf(error)}`);
+  }
+  return { due: now + milliseconds, when: when as string };
 }

package/src/emit-command.ts

@@ -1,14 +1,23 @@
 import type { EmitResultJson } from "@agentswf/contract/records";
 import { isEventWorkflow, type JsonValue } from "@agentswf/contract/workflow";
-import { EmitError, emitEvent } from "./emit";
+import { EmitError, emitEvent, emitToRun } from "./emit";
 import { messageOf } from "./errors";
 import help from "./help/emit.txt" with { type: "text" };
-import type { Out } from "./run-commands";
+import { type Out, parsePlace, type ReadPlace } from "./run-commands";
+import { findRunByRef } from "./run-state";
 import type { Launch } from "./wake";
 import { loadWorkflowFile } from "./workflow-loader";
 
 export const emitUsage = help.trimEnd();
 
+type Event = { name: string; data: JsonValue; id?: string };
+
+/** `--target {file} --id {id}`, which may start the run; or a run that is there, by its ref. */
+type Parsed = Event & { json: boolean } & (
+    | { target: string; run: string; ref?: undefined }
+    | { ref: string; place: ReadPlace; target?: undefined }
+  );
+
 export async function emitCommand(
   argv: readonly string[],
   shellCwd: string,
@@ -23,37 +32,35 @@ export async function emitCommand(
     out.stdout(emitUsage);
     return 0;
   }
-  let parsed: {
-    target: string;
-    run: string;
-    name: string;
-    data: JsonValue;
-    id?: string;
-    json: boolean;
-  };
+  let parsed: Parsed;
   try {
-    parsed = parse(argv);
+    parsed = parse(argv, shellCwd);
   } catch (error) {
     out.stderr(`awf: ${messageOf(error)}\n\n${emitUsage}`);
     return 2;
   }
+  const event = {
+    name: parsed.name,
+    data: parsed.data,
+    ...(parsed.id === undefined ? {} : { id: parsed.id }),
+  };
   let result: EmitResultJson;
   try {
-    const loaded = await loadWorkflowFile(parsed.target, shellCwd);
-    if (!isEventWorkflow(loaded.workflow)) {
-      out.stderr(`awf: ${loaded.file} declares no events; awf run starts it`);
-      return 2;
+    if (parsed.ref !== undefined) {
+      const status = await findRunByRef(parsed.ref, parsed.place, context.home);
+      result = await emitToRun(status, event, context);
+    } else {
+      const loaded = await loadWorkflowFile(parsed.target, shellCwd);
+      if (!isEventWorkflow(loaded.workflow)) {
+        out.stderr(`awf: ${loaded.file} declares no events; awf run starts it`);
+        return 2;
+      }
+      result = await emitEvent(
+        loaded.workflow,
+        { run: parsed.run, ...event },
+        { from: "operator", ...context },
+      );
     }
-    result = await emitEvent(
-      loaded.workflow,
-      {
-        run: parsed.run,
-        name: parsed.name,
-        data: parsed.data,
-        ...(parsed.id === undefined ? {} : { id: parsed.id }),
-      },
-      { from: "operator", ...context },
-    );
   } catch (error) {
     out.stderr(`awf: ${messageOf(error)}`);
     return error instanceof EmitError ? 2 : 1;
@@ -75,35 +82,42 @@ function emitLine(result: EmitResultJson): string {
   return `${result.outcome} ${result.ref}${did === undefined ? "" : `: ${did}`}`;
 }
 
-function parse(argv: readonly string[]): {
-  target: string;
-  run: string;
-  name: string;
-  data: JsonValue;
-  id?: string;
-  json: boolean;
-} {
+function parse(argv: readonly string[], shellCwd: string): Parsed {
+  const { place, json, rest } = parsePlace(argv, shellCwd);
   let target: string | undefined;
   let run: string | undefined;
   let id: string | undefined;
-  let json = false;
   const words: string[] = [];
-  for (let i = 0; i < argv.length; i++) {
-    const word = argv[i]!;
+  for (let i = 0; i < rest.length; i++) {
+    const word = rest[i]!;
     const value = () => {
-      const next = argv[++i];
+      const next = rest[++i];
       if (next === undefined) throw new Error(`${word} needs a value`);
       return next;
     };
     if (word === "--target") target = value();
     else if (word === "--id") run = value();
     else if (word === "--event-id") id = value();
-    else if (word === "--json") json = true;
     else if (word.startsWith("--")) throw new Error(`unknown option ${word}`);
     else words.push(word);
   }
-  if (target === undefined) throw new Error("--target names the workflow file the event is for");
-  if (run === undefined) throw new Error("--id names the run the event is for, by its id");
+  let form: { target: string; run: string } | { ref: string; place: ReadPlace };
+  if (target !== undefined) {
+    if (run === undefined) throw new Error("--id names the run the event is for, by its id");
+    if (place.repeat.length > 0)
+      throw new Error(
+        "--cwd and --run-root find a run by its ref; --target's file names its project",
+      );
+    form = { target, run };
+  } else {
+    if (run !== undefined) throw new Error("--id goes with --target; a run's ref names it alone");
+    const ref = words.shift();
+    if (ref === undefined)
+      throw new Error(
+        "name the run, <workflow>/<id> or <id>, or the workflow by --target and --id",
+      );
+    form = { ref, place };
+  }
   const [name, text, ...more] = words;
   if (name === undefined) throw new Error("the event's name is missing");
   if (more.length > 0) throw new Error(`one event at a time; also given: ${more.join(" ")}`);
@@ -115,5 +129,5 @@ function parse(argv: readonly string[]): {
       throw new Error(`the event's data is not JSON: ${messageOf(error)}`);
     }
   }
-  return { target, run, name, data, ...(id === undefined ? {} : { id }), json };
+  return { ...form, name, data, ...(id === undefined ? {} : { id }), json };
 }

package/src/emit.ts

@@ -1,12 +1,19 @@
 import { randomBytes } from "node:crypto";
 import { isAbsolute, join } from "node:path";
-import { type EmitResultJson, MAILBOX_RECORD_VERSION } from "@agentswf/contract/records";
+import {
+  type EmitResultJson,
+  MAILBOX_RECORD_VERSION,
+  type RunPanes,
+} from "@agentswf/contract/records";
 import { parseJsonSchema, validate } from "@agentswf/contract/schema";
 import {
   AWF_ID_PREFIX,
+  awfEventOf,
   eventWorkflowProblem,
+  isEventWorkflow,
   type JsonValue,
   nameProblem,
+  ParticipantReply,
 } from "@agentswf/contract/workflow";
 import { messageOf } from "./errors";
 import { exists } from "./files";
@@ -14,9 +21,10 @@ import { appendMailbox, foldMailbox, readMailbox } from "./mailbox";
 import { projectOf, projectRunRoot, recordProject } from "./projects";
 import { runLockFile, withRunLock } from "./run-lock";
 import { prepareArgs } from "./run-prepare";
-import { createRun, idProblem, openRun, type Run, readAttempts } from "./runs";
+import type { RunStatus } from "./run-state";
+import { createRun, idProblem, openRun, panesChanged, type Run, readAttempts } from "./runs";
 import { type WakeContext, type Woken, wake } from "./wake";
-import type { EventWorkflow } from "./workflow-loader";
+import { type EventWorkflow, loadWorkflowFile } from "./workflow-loader";
 
 /** An event awf refuses to take at all: a name, shape or id no run of the target could have. */
 export class EmitError extends Error {
@@ -43,12 +51,13 @@ export async function emitEvent(
   const workflow = target.meta.name;
   const { name, data } = event;
   checkEvent(target, event);
+  const file = fileOf(target);
   const id = event.id ?? `${AWF_ID_PREFIX}${randomBytes(8).toString("hex")}`;
   const at = new Date(context.now?.() ?? Date.now()).toISOString();
   const runId = event.run;
   const problem = idProblem(runId);
   if (problem) throw new EmitError(`the run's id: ${problem}`);
-  const project = await projectOf(target.file, context.home).catch((error: unknown) => {
+  const project = await projectOf(file, context.home).catch((error: unknown) => {
     throw new EmitError(messageOf(error));
   });
   const starts = target.starts?.includes(name) ?? true;
@@ -59,13 +68,69 @@ export async function emitEvent(
       runId,
       event: { id, name, data, from: context.from, at },
       deduplicate: event.id !== undefined,
-      file: target.file,
+      file,
       ...(starts ? { start: { project, target } } : {}),
     },
     context,
   );
 }
 
+/**
+ * `awf emit {ref} {key}:reply …`: a participant's message to the code of a run that is there,
+ * checked against the definition in the file a wake would run, its last attempt's, and delivered.
+ * It never starts a run, and doesn't ask whether the participant has connected: one sent before
+ * the run connects it waits in the mailbox for the run's next wait.
+ */
+export async function emitToRun(
+  status: RunStatus,
+  event: { name: string; data: JsonValue; id?: string },
+  context: Omit<WakeContext, "file">,
+): Promise<EmitResultJson> {
+  const { run, ref } = status;
+  const reply = awfEventOf(event.name);
+  if (reply?.kind !== "reply")
+    throw new EmitError(
+      `awf emit {run} sends a participant's message to the code, {key}:reply, not ${event.name}; the workflow's own events go by --target {file} --id {id}`,
+    );
+  if (!run.record.events) throw new EmitError(`${ref} is a run of a workflow without events`);
+  // A returned run takes nothing, so its file, since moved or changed, is not read: a late reply is
+  // refused as returned, not failed for a retry that never ends.
+  if (status.attempts.at(-1)?.outcome === "completed")
+    return deliverReply(status, reply.key, event, context);
+  const file = status.attempts.at(-1)?.file ?? run.record.file;
+  if (file === undefined) throw new Error(`${ref} has no file to check the event against`);
+  const { workflow } = await loadWorkflowFile(file, run.record.cwd);
+  if (!isEventWorkflow(workflow) || workflow.meta.name !== run.record.workflow)
+    throw new Error(`${file} is no longer ${run.record.workflow} with events, which ${ref} ran`);
+  checkEvent(workflow, event, true);
+  return deliverReply(status, reply.key, event, context);
+}
+
+/**
+ * `{key}:reply` appended to a run that is there, and the run woken: a duplicate id is a duplicate.
+ * The caller has checked it.
+ */
+export function deliverReply(
+  status: RunStatus,
+  key: string,
+  event: { data: JsonValue; id?: string },
+  context: Omit<WakeContext, "file">,
+): Promise<EmitResultJson> {
+  const { run } = status;
+  const at = new Date(context.now?.() ?? Date.now()).toISOString();
+  const id = event.id ?? `${AWF_ID_PREFIX}${randomBytes(8).toString("hex")}`;
+  return deliver(
+    {
+      runRoot: run.root,
+      workflow: run.record.workflow,
+      runId: run.record.id,
+      event: replyRecord(key, id, event.data, at),
+      deduplicate: event.id !== undefined,
+    },
+    context,
+  );
+}
+
 /** An event for a run of a workflow with events, as `deliver` takes it. */
 export type Delivery = {
   runRoot: string;
@@ -146,6 +211,7 @@ async function createEventRun(
   file: string | undefined,
   context: Pick<WakeContext, "home" | "environment">,
   argv: readonly string[] = [],
+  panes?: RunPanes,
 ): Promise<Run> {
   const run = await createRun(runRoot, {
     id,
@@ -156,6 +222,7 @@ async function createEventRun(
     events: true,
     env: { PATH: context.environment.PATH ?? "" },
     ...(file ? { file } : {}),
+    ...(panes ? { panes } : {}),
   });
   await recordProject(context.home, project);
   return run;
@@ -167,24 +234,27 @@ export type Opened = { run: string; created: boolean } & Woken;
 /**
  * `awf run --id` for a workflow with events: creates the run with no event, under its lock, and
  * starts it, so it runs to its first wait and parks there. One already there is only woken, as
- * `awf tick` would; one that returned is refused, as its events are.
+ * `awf tick` would; one that returned is refused, as its events are. `panes`, the operator's
+ * `--workspace` and `--keep-panes`, are recorded with a new run, and may not change one there.
  */
 export async function openEventRun(
   target: EventWorkflow,
   id: string,
   argv: readonly string[],
   context: Omit<WakeContext, "file">,
+  panes?: RunPanes,
 ): Promise<Opened> {
   const workflow = target.meta.name;
   const problem = idProblem(id);
   if (problem) throw new EmitError(problem);
-  const project = await projectOf(target.file, context.home).catch((error: unknown) => {
+  const file = fileOf(target);
+  const project = await projectOf(file, context.home).catch((error: unknown) => {
     throw new EmitError(messageOf(error));
   });
   const runRoot = projectRunRoot(project);
   const ref = `${workflow}/${id}`;
   return withRunLock(runLockFile(runRoot, workflow, id), async () => {
-    const woken = { ...context, file: target.file };
+    const woken = { ...context, file };
     if (await exists(join(runRoot, workflow, id, "run.json"))) {
       const run = await openRun(runRoot, workflow, id);
       if ((await readAttempts(run)).at(-1)?.outcome === "completed")
@@ -193,6 +263,8 @@ export async function openEventRun(
         throw new EmitError(
           `${ref} is there already, started with ${run.record.argv.length > 0 ? "arguments of its own" : "none"}; awf run --id ${id} with none wakes it`,
         );
+      const changed = panesChanged(run.record, panes);
+      if (changed) throw new EmitError(changed);
       return { run: ref, created: false, ...(await wake(run, woken)) };
     }
     try {
@@ -200,28 +272,65 @@ export async function openEventRun(
     } catch (error) {
       throw new EmitError(`prepare: ${messageOf(error)}`);
     }
-    const run = await createEventRun(runRoot, workflow, id, project, target.file, context, argv);
+    const run = await createEventRun(runRoot, workflow, id, project, file, context, argv, panes);
     return { run: ref, created: true, ...(await wake(run, woken)) };
   });
 }
 
-/** The event's name, shape and id, as the target declares them; an `EmitError` when they don't fit. */
+/**
+ * The target's file, which says which project its runs live in and which a start or wake runs:
+ * `file`, or the path awf loaded it from. Only a sender holding the workflow itself, as `wf.emit`
+ * does, can be without one.
+ */
+function fileOf(target: EventWorkflow): string {
+  if (target.file === undefined)
+    throw new EmitError(
+      `${target.meta.name} gives no file, by which a sender holding it finds it: file: import.meta.path`,
+    );
+  return target.file;
+}
+
+/**
+ * `{key}:reply`'s event as the mailbox records it: `participant:reply` from its key, whatever the
+ * workflow declares it as, so a wait takes it by one name.
+ */
+export function replyRecord(
+  key: string,
+  id: string,
+  data: JsonValue,
+  at: string,
+): Delivery["event"] {
+  return { id, name: "participant:reply", data, from: key, at };
+}
+
+/**
+ * The event's name, shape and id, as the target declares them; an `EmitError` when they don't fit.
+ * A name with a colon is awf's: only `{key}:reply`, from the operator (`replies`), is sent.
+ */
 export function checkEvent(
   target: EventWorkflow,
   event: { name: string; data: JsonValue; id?: string },
+  replies = false,
 ): void {
   const workflow = target.meta.name;
   const problem = eventWorkflowProblem(target);
   if (problem) throw new EmitError(`${workflow}: ${problem}`);
-  if (!isAbsolute(target.file))
+  if (target.file !== undefined && !isAbsolute(target.file))
     throw new EmitError(`${workflow}: its file, ${target.file}, is import.meta.path, absolute`);
-  if (event.name.includes(":"))
-    throw new EmitError(`${event.name}: a name with a colon is awf's own, and not sent`);
-  const schema = target.events[event.name];
-  if (!schema)
+  const reply = awfEventOf(event.name)?.kind === "reply";
+  if (event.name.includes(":") && !(replies && reply))
+    throw new EmitError(
+      reply
+        ? `${event.name}: a participant's message goes to a run that is there, awf emit ${workflow}/{id} ${event.name} '{"text":…}'`
+        : `${event.name}: a name with a colon is awf's own, and not sent`,
+    );
+  const declared = target.events[event.name];
+  if (!declared)
     throw new EmitError(
       `${workflow} declares no event ${event.name}; its events are ${Object.keys(target.events).join(", ")}`,
     );
+  // A reply is checked against awf's own schema, not the workflow's copy, which may be older.
+  const schema = reply ? ParticipantReply : declared;
   let parsed: ReturnType<typeof parseJsonSchema>;
   try {
     parsed = parseJsonSchema(schema);

package/src/help/emit.txt

@@ -1,4 +1,5 @@
 usage: awf emit --target <file> --id <id> <event> [<json>] [--event-id <id>] [--json]
+       awf emit <run> <key>:reply '{"text": …, "author": …}' [--event-id <id>] [--cwd <directory>] [--run-root <directory>] [--json]
 
 Sends an event to the run of a workflow with events that --id names. That run starts if it has
 none and the event is one that starts one, and is woken if it has one: told while it runs,
@@ -6,8 +7,15 @@ continued when it is parked or crashed. The run lives in the project of <file>,
 directory above it holding .awf/, whoever sends. --event-id names the occurrence: the same id
 again is a duplicate.
 
+The second form sends a participant's message to the code of a run that is there, <workflow>/<id>
+or an <id> only one workflow has, here or in a project awf knows: <key>:reply, which the workflow
+declares, checked against the file the run's last attempt ran. "author" is optional. Its
+--event-id is the message's own id, so a resend is a duplicate. It never starts a run, and may
+arrive before the run connects the participant: it waits for the run's next wait. The first form
+takes only the workflow's own events.
+
 Prints what became of the event, and what was done to the run: accepted, duplicate or refused.
---json prints one document. Exits 0 for any of the three; 1 when <file> could not be loaded, and
-nothing is kept, or when the run's attempt could not be started (the event is kept, and the next
-event or awf tick tries again); 2 on a usage error, for a workflow with no events, or when the
-event is wrong for its target: its name, its data, or its id.
+--json prints one document. Exits 0 for any of the three; 1 when <file> could not be loaded, or
+the run isn't found, and nothing is kept, or when the run's attempt could not be started (the
+event is kept, and the next event or awf tick tries again); 2 on a usage error, for a workflow
+with no events, or when the event is wrong for its target: its name, its data, or its id.

package/src/help/inbox.txt

@@ -1,11 +1,11 @@
-usage: awf inbox [<run>] [--open] [--workflow <name>] [--as <key>] [--after <cursor>] [--wait <seconds>]
+usage: awf inbox [<run>] [--open] [--workflow <name>] [--as <key>] [--after <cursor>] [--wait <duration>]
                  [--cwd <directory>] [--run-root <directory>] [--json]
 
 What agents said to a participant outside the run, and what it said back: routes, messages,
 answers, questions that closed unanswered, and each attempt's end, oldest first. Without a run,
 every run here that connected one; --workflow narrows that. A run is <workflow>/<id>, or an <id>
 only one workflow has. --after reads on from a cursor the last answer gave; --wait
-waits up to that many seconds, at most 300, when nothing is new. --open lists the questions
+waits up to that long, at most 5m, when nothing is new. --open lists the questions
 still waiting for an answer, a snapshot. --json prints one item per line.
 
 Exits 0 on a read that worked, 1 when there is no such run, it has no participant, or the

package/src/help/logs.txt

@@ -1,13 +1,14 @@
 usage: awf logs [<run>] [@<handle>] [--agent <key>] [--stage <name>] [--after <cursor>]
-                [--limit <n>] [--wait <seconds> | --follow] [--full] [--cwd <directory>]
+                [--limit <n>] [--wait <duration> | --follow] [--full] [--cwd <directory>]
                 [--run-root <directory>] [--json]
 
 What a run did and is doing: its events and what its agents did, read from their own session
 files, merged by time. With no run, the newest here. Without --after, the last 40 events; with
 it, what came after, oldest first. Every answer ends with the command that gets only what is
-new. --wait: with nothing to show yet, wait for the first event, at most that many seconds, up
-to 300; --follow prints each event as it comes until the run ends. @<handle> names one event,
-and --full prints its text, with common credential shapes masked; --json carries it always.
+new. --wait: with nothing to show yet, wait for the first event, at most that long, up to 5m,
+such as 90s (a bare number, seconds, is deprecated); --follow prints each event as it comes until
+the run ends. @<handle> names one event, and --full prints its text, with common credential
+shapes masked; --json carries it always.
 
 Exits 0 on any read that worked, 1 when there is no such run or the cursor or handle does not
 fit it, 2 on a usage error, 3 when the run's files could not be read.

package/src/help/reply.txt

@@ -8,11 +8,11 @@ Answers a question an agent asked a participant outside the run, or messages an
 over a route the workflow allowed. The text is the argument, or stdin without one. --to names
 the question, as awf inbox prints it; it may be left out when the agent has one open. --as
 names the participant when the workflow connects more than one. Neither waits for an answer:
-it comes back in awf inbox. With --event-id, send is a reply on a participant the run routes to its
-code: no agent, it reaches the run whether it runs or is parked, and the same id again is a
-duplicate. The id is one the run has not had from anyone, as a chat's message ids are. It prints
-as awf emit does, and exits 0 for whatever the run did with it (accepted, duplicate, or refused
-by a run that returned); 1 when the run or participant isn't found, or its attempt didn't start.
+it comes back in awf inbox. send --event-id is deprecated: awf emit <run> <participant>:reply
+'{"text":…,"author":…}' --event-id <id> replaces it, and it forwards there. It still sends a
+message on a participant to the run's code, the id the message's own, and prints as awf emit
+does; it exits 0 for whatever the run did with it (accepted, duplicate, or refused by a run that
+returned); 1 when the run or participant isn't found, or its attempt didn't start.
 
 Exits 0 when delivered, 1 when refused (the code says why), 2 on a usage error, 3 when the run
 could not be reached.

package/src/help/run.txt

@@ -2,17 +2,20 @@ 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>,
+             --workspace <run|origin|name>, --keep-panes <never|on-failure|always>,
              --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.
+--continue, the run --id names, with the arguments, --cwd, --sandbox, --workspace and
+--keep-panes 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 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 run has no deadline unless --timeout gives it one, per attempt: a duration, a decimal and s, m,
+h or d, such as 20m or 1d.
 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
@@ -24,13 +27,23 @@ such as {"read": ["/data/request.md"], "srt": {}}, naming srt or docker, whose r
 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.
+--workspace says where each TUI agent's tab opens: run, the run's own Herdr workspace (the
+default); origin, the one awf run was typed in; or any other word, the workspace with that label,
+found or made. --keep-panes says whether an agent's pane stays once it is done: never (the
+default), on-failure, when its last turn wasn't answered, or always. A kept pane's harness is left
+running, and yours. Both are kept with the run for every attempt, a woken one too, and win over a
+workflow's deprecated layout and keepPane. A run an event started has neither, and takes the
+defaults. A continue may give either again with the run's value, or its default where the run had
+none, and no other.
 --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.
+A run of a workflow with events is named by --id, or by the workflow's id(args); one without
+starts may have an id made, as any run. 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.
+Its --continue takes --from-stage, as any run's does, and no --values. A --from-stage the attempt
+never reaches runs the attempt until it would park or return, and stops it there.
 Exits 0 when the run completed or parked, 1 when it failed or timed out, 2 on a usage error or
 when the run is refused, 3 when it stopped and can go on with --continue, and 128 plus the
 signal's number when it was interrupted.
@@ -40,5 +53,6 @@ Examples:
   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
+  awf run examples/pane-layout/workflow.ts --workspace origin --keep-panes on-failure
 
 Workflow files are trusted code and run with your filesystem and process authority.

package/src/herdr-run-session.ts

@@ -17,7 +17,7 @@ import { machinePaths } from "./machine";
 import { SESSION_NAME } from "./pane-layout";
 import type { ProcessProbe } from "./runs";
 
-/** Where a run's pane agents open when `AWF_HERDR_SESSION` names nowhere else. */
+/** Where a run's TUI agents open when `AWF_HERDR_SESSION` names nowhere else. */
 const DEFAULT_RUN_SESSION = "awf";
 
 /** What may start: the shared session is awf's by its name, since which run created it is not knowable. */
@@ -101,7 +101,7 @@ export function runSessionName(environment: Readonly<Record<string, string | und
 }
 
 /**
- * The Herdr session a run's pane agents open in, running and kept: started detached when down and
+ * The Herdr session a run's TUI agents open in, running and kept: started detached when down and
  * named `awf` or `awf-…`, from a minimal environment and a quiet config, so it outlives this run
  * for the next. Any other name that is down is refused: it may be an operator's stopped session,
  * and bringing it back headless is not awf's call. Then the workspaces of runs that ended are