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

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

@@ -31,11 +31,11 @@ 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;
-  /** 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;

package/src/run-view.ts

@@ -1,11 +1,13 @@
 import { join } from "node:path";
 import type {
   Activity,
+  AgentStateJson,
   AttemptRecord,
   OperationLivenessRecord,
   RunLogLine,
+  StageStateJson,
 } from "@agentswf/contract/records";
-import type { AgentKey, HarnessKind, StageOutcome } from "@agentswf/contract/workflow";
+import type { AgentKey, HarnessKind } from "@agentswf/contract/workflow";
 import { readLines } from "./jsonl";
 import { currentStage, estimateOf } from "./run-commands";
 import { type Cursor, type FileCache, readRun, timeOf } from "./run-read";
@@ -14,7 +16,7 @@ import type { RunStatus } from "./run-state";
 /** A stage of the attempt shown: running, reused or given from an earlier one, or how it ended. */
 export type StageView = {
   stage: string;
-  state: "running" | "interrupted" | "reused" | "provided" | StageOutcome;
+  state: StageStateJson;
   startedAt?: number;
   endedAt?: number;
 };
@@ -29,7 +31,7 @@ export type AgentView = {
   caller: boolean;
   /** The stage its last operation ran in. */
   stage?: string;
-  state: string;
+  state: AgentStateJson;
   turns: number;
   /** When its current operation, or its last, started. */
   since?: number;
@@ -137,7 +139,7 @@ export async function viewRun(status: RunStatus): Promise<RunView> {
   const stage = currentStage(status, read.log.lines);
   // A run whose process is gone left what it was doing undone.
   if (status.state === "interrupted") {
-    for (const each of agents.values()) if (each.state === "working") each.state = "was working";
+    for (const each of agents.values()) if (each.state === "working") each.state = "interrupted";
     for (const each of stages) if (each.state === "running") each.state = "interrupted";
   }
   if (status.state === "running") {
@@ -153,6 +155,9 @@ export async function viewRun(status: RunStatus): Promise<RunView> {
       } else if (phase?.kind === "awaiting-reply" && phase.peer !== undefined) {
         agent(key).live = { phase: "awaiting-reply", peer: phase.peer, ...until };
       }
+      // One word with `wfa peers`: the phase is the state; `live` keeps its detail.
+      const { live } = agent(key);
+      if (live && agent(key).state === "working") agent(key).state = live.phase;
     }
   }
   const since = attempt ? Date.parse(attempt.started) : Number.NEGATIVE_INFINITY;

package/src/runs-command.ts

@@ -1,7 +1,8 @@
 import { homedir } from "node:os";
 import type { RunJson, RunsJson } from "@agentswf/contract/records";
-import { duration } from "./duration";
+import { formatDuration } from "./duration";
 import { messageOf } from "./errors";
+import help from "./help/runs.txt" with { type: "text" };
 import {
   clockTime,
   command,
@@ -23,19 +24,7 @@ import { encodeCursor } from "./run-read";
 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 [--limit <n>] [--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. The list shows 20 unless --limit says another",
-  "number. A run is <workflow>/<id>, or an <id> only one",
-  "workflow has. Runs are listed under --cwd's .awf/runs, or --run-root, as awf run keeps them; a",
-  "run named is found there first, then in each project awf has started a run with events in.",
-  "",
-  "--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;
 
@@ -144,7 +133,7 @@ async function list(place: ReadPlace, limit: number, json: boolean, out: Out, no
       status.ref.padEnd(width),
       states[index]!.padEnd(stateWidth),
       dayTime(started).padEnd(13),
-      duration(ms).padEnd(8),
+      formatDuration(ms).padEnd(8),
       money(estimate)
         .join("")
         .concat(waiting ? "  " : ""),
@@ -173,13 +162,15 @@ function dayTime(at: number): string {
   return `${two(date.getMonth() + 1)}-${two(date.getDate())} ${clockTime(at).slice(0, 5)}`;
 }
 
-const busy = (agent: AgentView) => agent.state === "working" || agent.state === "was working";
+const inTurn = (agent: AgentView) =>
+  agent.state === "working" || agent.state === "waiting" || agent.state === "awaiting-reply";
+const busy = (agent: AgentView) => inTurn(agent) || agent.state === "interrupted";
 
 function agentLine(agent: AgentView, indent: string, now: number, width: number): string {
   const { live } = agent;
   const parts = [
     said(agent.key, 60).padEnd(width),
-    (live?.phase === "waiting" ? "waiting" : live ? "awaiting" : agent.state).padEnd(11),
+    agent.state.padEnd(14),
     busy(agent) ? `turn ${agent.turns + 1}` : `${agent.turns} turn${agent.turns === 1 ? "" : "s"}`,
     ...(live?.phase === "waiting"
       ? [
@@ -192,10 +183,10 @@ function agentLine(agent: AgentView, indent: string, now: number, width: number)
         ]
       : live
         ? [
-            `${said(live.peer, 60)}'s reply${live.until ? ` (until ${clockTime(live.until).slice(0, 5)})` : ""}`,
+            `from ${said(live.peer, 60)}${live.until ? ` (until ${clockTime(live.until).slice(0, 5)})` : ""}`,
           ]
         : []),
-    ...(agent.since && agent.state === "working" ? [duration(now - agent.since)] : []),
+    ...(agent.since && inTurn(agent) ? [formatDuration(now - agent.since)] : []),
     ...(agent.last
       ? [`last: ${describeActivity(agent.last.activity)} (${clockTime(agent.last.at)})`]
       : []),
@@ -247,13 +238,13 @@ function describe(view: RunView, place: ReadPlace, now: number): string {
       ...(view.stage ? [`stage ${view.stage}`] : []),
       status.state === "interrupted" && view.lastEventAt
         ? `last event ${clockTime(view.lastEventAt)}`
-        : duration(span(status, now).ms),
+        : formatDuration(span(status, now).ms),
       ...money(view.estimate),
     ].join("  "),
   ];
   for (const earlier of status.attempts.slice(0, -1)) {
     const took = earlier.ended
-      ? `  ${duration(Date.parse(earlier.ended) - Date.parse(earlier.started))}`
+      ? `  ${formatDuration(Date.parse(earlier.ended) - Date.parse(earlier.started))}`
       : "";
     const how = `${earlier.outcome ?? "interrupted"}${earlier.stage ? ` in ${earlier.stage}` : ""}`;
     lines.push(`  attempt ${earlier.attempt}  ${how}${took}`);
@@ -265,7 +256,7 @@ function describe(view: RunView, place: ReadPlace, now: number): string {
     const took =
       stage.state === "reused" || stage.state === "provided" || stage.startedAt === undefined
         ? ""
-        : duration((stage.endedAt ?? now) - stage.startedAt);
+        : formatDuration((stage.endedAt ?? now) - stage.startedAt);
     lines.push(
       `${indent}  stage ${stage.stage.padEnd(8)} ${stage.state.padEnd(10)} ${took}`.trimEnd(),
     );
@@ -320,7 +311,7 @@ function runJson(view: RunView, place: ReadPlace, now: number): RunJson {
       ? undefined
       : continueOf(status, view.lines, place);
   return {
-    v: 1,
+    v: 2,
     run: {
       ref: status.ref,
       state: status.state,

package/src/runs.ts

@@ -1,6 +1,17 @@
 import { randomBytes } from "node:crypto";
-import { mkdir, open, readdir, readFile, rename, rm, stat, unlink } from "node:fs/promises";
+import {
+  copyFile,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  unlink,
+} from "node:fs/promises";
 import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import {
   ATTEMPT_RECORD_VERSION,
   type AttemptRecord,
@@ -8,6 +19,7 @@ import {
   type Candidate,
   RUN_RECORD_VERSION,
   type RunLogLine,
+  type RunPanes,
   type RunRecord,
   runLogLine,
   STAGE_RECORD_VERSION,
@@ -190,13 +202,15 @@ export async function openRun(root: string, workflow: string, id: string): Promi
 
 /**
  * What a continue may be given: nothing that changes the run. argv is the run's, and its working
- * directory and sandbox are those it was started with.
+ * directory, sandbox and panes are those it was started with.
  */
 export function checkContinue(
   run: Run,
-  given: { argv: readonly string[]; cwd?: string; sandbox?: unknown },
+  given: { argv: readonly string[]; cwd?: string; sandbox?: unknown; panes?: RunPanes },
 ): void {
   const { id, cwd, sandbox } = run.record;
+  const panes = panesChanged(run.record, given.panes);
+  if (panes) throw new RunRefused(panes);
   if (given.argv.length > 0) {
     throw new RunRefused(
       `${id} keeps the arguments it was started with; a run with others is a new run (--id)`,
@@ -210,11 +224,32 @@ export function checkContinue(
   }
 }
 
+/**
+ * Why `given` would change the panes `record`'s run was started with; a flag given again with its
+ * value, or with its default where the run was started without it, changes nothing.
+ */
+export function panesChanged(record: RunRecord, given: RunPanes | undefined): string | undefined {
+  const flags = [
+    ["--workspace", "workspace", "run"],
+    ["--keep-panes", "keep", "never"],
+  ] as const;
+  for (const [flag, field, byDefault] of flags) {
+    const value = given?.[field];
+    const recorded = record.panes?.[field];
+    if (value === undefined || isDeepStrictEqual(value, recorded ?? byDefault)) continue;
+    // A run an event or an older awf started has none, and keeps the defaults.
+    return recorded === undefined
+      ? `${record.id} was started without ${flag}, so with ${flag} ${byDefault}; leave it out`
+      : `${record.id} keeps the ${flag} it was started with; leave ${flag} out`;
+  }
+  return undefined;
+}
+
 /**
  * The run's attempts, in order. One that doesn't parse, or is newer than this awf, refuses; one
  * gone since the folder was listed was a refused attempt removing its own claim.
  */
-export async function readAttempts(run: Run): Promise<AttemptRecord[]> {
+export async function readAttempts(run: Pick<Run, "dir">): Promise<AttemptRecord[]> {
   const dir = attemptsDir(run.dir);
   const numbered = await attemptNames(run);
   const records = await Promise.all(
@@ -405,9 +440,10 @@ export async function replaceStale(
 /**
  * Moves a stage's record, unchanged, to `replaced/{stage}.{attempt}.json`, or, for a stage by
  * content replaced again in the same attempt, `{stage}.{attempt}+{n}.json` from 2: no name has a
- * `+`, so neither reads as another stage's.
+ * `+`, so neither reads as another stage's. `copy` leaves it in `stages/` for the new record to
+ * overwrite, so an attempt that dies between the two leaves the old one, not none.
  */
-export async function replaceRecord(runDir: string, stage: string): Promise<void> {
+export async function replaceRecord(runDir: string, stage: string, copy = false): Promise<void> {
   const file = join(stagesDir(runDir), `${stage}.json`);
   const record = await readRecord<StageRecord>(file, STAGE_RECORD_VERSION);
   const replaced = join(runDir, "replaced");
@@ -416,7 +452,7 @@ export async function replaceRecord(runDir: string, stage: string): Promise<void
   for (let n = 2; await exists(target); n++) {
     target = join(replaced, `${stage}.${record.attempt}+${n}.json`);
   }
-  await rename(file, target);
+  await (copy ? copyFile(file, target) : rename(file, target));
 }
 
 /** Appends a line to the run's event log, `turns.jsonl`, which only the live attempt writes. */
@@ -501,7 +537,7 @@ export async function logSize(runDir: string): Promise<number> {
   return (await stat(turnsFile(runDir)).catch(() => undefined))?.size ?? 0;
 }
 
-async function attemptNames(run: Run): Promise<string[]> {
+async function attemptNames(run: Pick<Run, "dir">): Promise<string[]> {
   return (await entries(attemptsDir(run.dir))).filter((name) => /^[1-9]\d*\.json$/.test(name));
 }
 

package/src/sandboxes.ts

@@ -7,6 +7,7 @@ import type { SandboxRecord } from "@agentswf/contract/records";
 import type {
   AbsoluteDeadline,
   AgentExecution,
+  SandboxEnvironment,
   SandboxEnvironmentKey,
   SandboxRef,
 } from "@agentswf/contract/workflow";
@@ -141,7 +142,7 @@ export class RunSandboxes {
     return this.options.sandboxes?.run !== undefined;
   }
 
-  /** `workflow.sandboxes.open`. */
+  /** `wf.sandboxes.open`. */
   async open(spec: unknown): Promise<SandboxRef> {
     if (this.hasRunSandbox) throw new Error(RUN_SANDBOX_ONLY);
     const key = (spec as { key?: unknown } | null)?.key;
@@ -306,7 +307,7 @@ export class RunSandboxes {
           network: [...resolved.network],
           ...(resolved.sockets.length > 0 ? { sockets: [...resolved.sockets] } : {}),
           ...(resolved.webSearch ? { webSearch: true } : {}),
-          [provider]: resolved.environment,
+          ...({ [provider]: resolved.environment } as SandboxEnvironment),
         },
         directory,
         gitdirs: resolved.gitdirs.map((gitdir) => ({ ...gitdir })),

package/src/simple-input.ts

@@ -19,10 +19,18 @@ type Kind =
   | { type: "boolean" }
   | { type: "enum"; values: string[] };
 
-/** Said once in a prompt, under the first block taught with flags, and with every refusal of them. */
+/**
+ * Said once in a prompt, under the first block with a free-text flag, and with every refusal of
+ * flags that take text. Enum, number and boolean values are shell words as they stand.
+ */
 export const QUOTING_RULE =
   "Put every value in single quotes; a ' inside a value is written '\\''.";
 
+/** Whether a flag takes free text, the only value the shell can break. */
+export function takesText(simple: Simple): boolean {
+  return simple.some(({ kind }) => kind.type === "string");
+}
+
 const MAX_PROPERTIES = 6;
 const NAME = /^[a-z][a-z0-9_]*$/;
 /** An enum value the usage line can show between `|`s and the agent can type as it stands. */
@@ -137,7 +145,7 @@ export type ReadFlags = { ok: true; value: JsonObject } | { ok: false; error: st
 export type ReadGiven = { ok: true; value: unknown } | { ok: false; error: string };
 
 /**
- * An input as `wf` sent it, as a value: JSON parsed, flags read by the schema, nothing as `{}`.
+ * An input as `wfa` sent it, as a value: JSON parsed, flags read by the schema, nothing as `{}`.
  * The schema's own check comes after, in `checkGiven`.
  */
 export function readGiven(schema: JsonSchema | undefined, given: GivenInput): ReadGiven {
@@ -181,7 +189,9 @@ export function checkGiven(
 }
 
 function expected(simple: Simple): string {
-  return `expected: ${usageLine(simple)}\n${QUOTING_RULE}`;
+  return [`expected: ${usageLine(simple)}`, ...(takesText(simple) ? [QUOTING_RULE] : [])].join(
+    "\n",
+  );
 }
 
 /**

package/src/sources.ts

@@ -1,9 +1,12 @@
 import type { WaitTake } from "@agentswf/contract/records";
-import type { JsonValue, WorkflowEvent } from "@agentswf/contract/workflow";
+import { awfEventOf, type JsonValue, type WorkflowEvent } from "@agentswf/contract/workflow";
 
 /** What each source the run issued takes: only awf makes a source, so only these are. */
 const takes = new WeakMap<object, WaitTake>();
 
+/** Signals: a branch on one hands back the whole event, not its data. */
+const signals = new WeakSet<object>();
+
 /** Marks `value` as a source that takes `take`, and returns it. */
 export function asSource<T extends object>(value: T, take: WaitTake): T {
   takes.set(value, take);
@@ -18,8 +21,40 @@ export function source<T extends object>(
   return asSource(Object.freeze({ ...fields, is: (event: Looked) => matches(event, take) }), take);
 }
 
+/** As `source`, for a signal. */
+export function signalOf<T extends object>(fields: T, take: WaitTake): T {
+  const made = source(fields, take);
+  signals.add(made);
+  return made;
+}
+
+/** Whether `value` is a signal, whose branch hands back the whole event. */
+export function isSignal(value: unknown): boolean {
+  return typeof value === "object" && value !== null && signals.has(value);
+}
+
 type Looked = { name: string; from: string; data?: unknown };
 
+/**
+ * The name the mailbox records an event under: awf's keep `agent:ended` and `participant:reply`,
+ * from their key, whatever name the workflow declares and is handed, `{key}:ended` or `{key}:reply`.
+ */
+export function recordName(event: { name: string; from: string }): string {
+  const awf = awfEventOf(event.name);
+  if (!awf || awf.key !== event.from) return event.name;
+  return awf.kind === "ended" ? "agent:ended" : "participant:reply";
+}
+
+/** `event` under the name the workflow declares for it, where it declares one. */
+export function presented<E extends WorkflowEvent<string, JsonValue>>(
+  event: E,
+  declared: ReadonlySet<string>,
+): E {
+  const kind = { "agent:ended": "ended", "participant:reply": "reply" }[event.name as string];
+  if (kind === undefined || !declared.has(`${event.from}:${kind}`)) return event;
+  return Object.freeze({ ...event, name: `${event.from}:${kind}` });
+}
+
 /** The first of `branches` that takes `event`. */
 export function branchOf(
   branches: readonly (readonly [string, WaitTake])[],
@@ -33,12 +68,12 @@ export function takeOf(value: unknown): WaitTake | undefined {
   return typeof value === "object" && value !== null ? takes.get(value) : undefined;
 }
 
-/** Whether a wait that takes `take` takes `event`. */
+/** Whether a wait that takes `take` takes `event`, under its recorded name or its declared one. */
 export function matches(
   event: { name: string; from: string; data?: unknown },
   take: WaitTake,
 ): boolean {
-  if (event.name !== take.name) return false;
+  if (recordName(event) !== take.name) return false;
   if (take.from !== undefined && event.from !== take.from) return false;
   if (take.turn === undefined) return true;
   const data = event.data as { turn?: unknown } | null | undefined;
@@ -55,10 +90,11 @@ export function wouldTake(
 
 /**
  * What a branch hands back of the event it took: awf's own events as their data with the event's id
- * and arrival, and a workflow's own event whole.
+ * and arrival, and a workflow's own event, or any a signal takes, whole.
  */
-export function branchValue(event: WorkflowEvent<string, JsonValue>): unknown {
-  switch (event.name) {
+export function branchValue(event: WorkflowEvent<string, JsonValue>, whole = false): unknown {
+  if (whole) return event;
+  switch (recordName(event)) {
     case "timer:due":
     case "at:due":
     case "participant:reply":

package/src/stage-ledger.ts

@@ -8,7 +8,7 @@ import type { JsonSchema } from "@agentswf/contract/schema";
 import type { JsonValue, StageOutcome, StageSummary } from "@agentswf/contract/workflow";
 import type { RunEventBody } from "./run-event-log";
 import { replaceRecord, replaceStale, stageNameProblem, writeStageRecord } from "./runs";
-import { planStage, planStageByContent } from "./stage-plan";
+import { planStage, planStageByContent, type StageRedo } from "./stage-plan";
 import { placeholderOf } from "./stage-schema";
 import { primaryFailure, WorkflowStopped } from "./stopped";
 
@@ -89,6 +89,11 @@ export class StageLedger {
   /** The run's stage records as they stand, this attempt's included: what a stage by content reuses. */
   readonly #records: Map<string, StageRecord>;
 
+  /** The redo stale records are judged by: the options', then this attempt's own. */
+  #redo: StageRedo | undefined;
+  /** Whether this attempt has entered the redo's stage, after which a stale record reruns. */
+  #afterRedo = false;
+
   constructor(
     private readonly options: {
       runDir: string;
@@ -102,9 +107,11 @@ export class StageLedger {
       fromStage?: string;
       /** `--values`: the values of stages before `fromStage` that have no record to reuse. */
       values?: ReadonlyMap<string, JsonValue>;
+      /** A run of a workflow with `events`: the last `--from-stage` an attempt redid. */
+      redo?: StageRedo;
       /**
        * A run of a workflow with `events`: a stage runs once ever, reused wherever it is entered,
-       * as `planStageByContent` says; no start point, and no `fromStage` or `values`.
+       * as `planStageByContent` says, and no `values`. Its start point is `fromStage` alone.
        */
       byContent?: boolean;
       /** Writes the run's event log. */
@@ -113,6 +120,7 @@ export class StageLedger {
     },
   ) {
     this.#records = new Map(options.records);
+    this.#redo = options.redo;
   }
 
   /** The stage open now, if one is. */
@@ -174,7 +182,7 @@ export class StageLedger {
   }
 
   /**
-   * `workflow.stop`, called in `stage` or between stages: what to throw. The first stop is kept,
+   * `wf.stop`, called in `stage` or between stages: what to throw. The first stop is kept,
    * and any later stop throws it again; once it was found caught, that instead. After the
    * workflow's body ended, a stop ends nothing.
    */
@@ -313,10 +321,23 @@ export class StageLedger {
 
   /**
    * Enters a stage by content: reused from its succeeded record, this attempt's included, run when
-   * it has none or a failed one, which its own record then replaces.
+   * it has none or a failed one, which its own record then replaces. After the redo's stage in this
+   * attempt, a record older than the redo is stale and runs again: see `StageRedo`.
    */
   async #enterByContent(name: string, entry: StageEntry, at: number): Promise<EnteredStage> {
-    const decision = planStageByContent(this.#records.get(name), entry.result);
+    if (!this.#started && name === this.options.fromStage) return this.#startByContent(name, at);
+    const record = this.#records.get(name);
+    const redo = this.#redo;
+    // Entered already in this attempt, it has its value here: one stage, one value.
+    const stale =
+      redo !== undefined &&
+      this.#afterRedo &&
+      record !== undefined &&
+      record.attempt < redo.attempt &&
+      !this.#stages.has(name);
+    if (name === redo?.stage) this.#afterRedo = true;
+    if (stale) return { kind: "run", stage: this.#opened(name, at) };
+    const decision = planStageByContent(record, entry.result);
     if (decision.kind === "stop") {
       this.#stopped = new WorkflowStopped(decision.reason, name, true);
       this.#stoppedAt(name, at);
@@ -347,6 +368,20 @@ export class StageLedger {
     return { kind: "run", stage: this.#opened(name, at) };
   }
 
+  /**
+   * `--from-stage` reached by content: it runs, and this attempt is the redo. Its old record moves to
+   * `replaced/` only as its new one is written, as a failed record's does, so an attempt that dies
+   * while it runs leaves the old one, and the redo, which nothing then shows, is issued again. The
+   * stages after it rerun as they are entered, not all at once: one never entered keeps its record.
+   */
+  #startByContent(name: string, at: number): EnteredStage {
+    const stage = this.#opened(name, at);
+    this.#started = true;
+    this.#redo = { stage: name, attempt: this.options.attempt };
+    this.#afterRedo = true;
+    return { kind: "run", stage };
+  }
+
   /** A stage the plan stopped as it was entered: shown stopped, though it ran nothing. */
   #stoppedAt(name: string, at: number): void {
     this.options.event?.({ kind: "stage-ended", stage: name, outcome: "stopped" }, at);
@@ -506,14 +541,9 @@ export class StageLedger {
       });
       // By content, a failed record this one replaces is kept, as a redone stage's is.
       const replacing = this.options.byContent && this.#records.has(name);
-      ended = (
-        replacing
-          ? replaceRecord(this.options.runDir, name).then(() => {
-              // Moved: a write that fails now leaves nothing in `stages/` to move again.
-              this.#records.delete(name);
-            })
-          : Promise.resolve()
-      )
+      // Copied, then overwritten: dying between the two leaves the old record, as dying while the
+      // stage runs does, never a redo's stage without one and stale records after it.
+      ended = (replacing ? replaceRecord(this.options.runDir, name, true) : Promise.resolve())
         .then(() => writeStageRecord(this.options.runDir, record))
         .then(
           () => {