@agentswf/engine 0.0.0-stage → 0.1.0-beta.1

package/src/attempt-ending.ts

@@ -0,0 +1,198 @@
+import { constants } from "node:os";
+import type { StageNeed, StageRecord } from "@agentswf/contract/records";
+import {
+  type AbsoluteDeadline,
+  type AttemptOutcome,
+  DeadlineExceededError,
+  type Ending,
+  type JsonValue,
+  type StageSummary,
+  type UnfinishedOutcome,
+} from "@agentswf/contract/workflow";
+import { PUBLISHED_PRICES } from "./accounting/prices";
+import { summarizeRun } from "./accounting/summary";
+import { messageOf } from "./errors";
+import type { Paint } from "./progress-view";
+import { FromStageUnreached, primaryFailure, WorkflowStopped } from "./stopped";
+import {
+  type SettledRun,
+  WorkflowCancelledError,
+  WorkflowRunError,
+  type WorkflowRunResult,
+} from "./workflow-runner";
+
+/**
+ * How an attempt ended, decided once: every record, message and exit code of it follows this.
+ * `settled` is what the run left, absent when it failed before it started.
+ */
+export type AttemptEnd = {
+  ending: Ending<JsonValue>;
+  settled?: SettledRun;
+  exitCode: number;
+  /** What else failed beside a stop, which its reason leaves out. */
+  alsoFailed?: string;
+  /**
+   * Given when the attempt never reached its `--from-stage`, which no one command goes on from:
+   * the run's stages to choose from.
+   */
+  choose?: readonly StageRecord[];
+  /** The stages whose values `--values` gives, to start at a later one. */
+  needs?: readonly StageNeed[];
+};
+
+/** What a started run came to: the result it returned, or what it threw. */
+export type Finished = { result: WorkflowRunResult<JsonValue> } | { error: unknown };
+
+/**
+ * Each outcome: its word as awf reports it and as the calling session is told it, its mark, as its
+ * last stage's would be, and its exit code, but for a cancellation's, which is its signal's. A
+ * stop's is apart from a failure's: the run can go on with `--continue`.
+ */
+export const OUTCOMES: Record<
+  AttemptOutcome,
+  { word: string; told: string; mark: (paint: Paint) => string; exitCode?: number }
+> = {
+  completed: { word: "completed", told: "completed", mark: (p) => p.ok("✓"), exitCode: 0 },
+  stopped: { word: "stopped", told: "stopped", mark: (p) => p.busy("■"), exitCode: 3 },
+  cancelled: { word: "cancelled", told: "was cancelled", mark: (p) => p.busy("■") },
+  "timed-out": { word: "timed out", told: "timed out", mark: (p) => p.bad("✗"), exitCode: 1 },
+  failed: { word: "failed", told: "failed", mark: (p) => p.bad("✗"), exitCode: 1 },
+};
+
+/** The command that goes on from an attempt, given the stop that ended it and the stages it entered. */
+export type GoOn = (stop: WorkflowStopped | undefined, entered: readonly StageSummary[]) => string;
+
+/** The ending of a run that returned or threw. */
+export function decideEnding(run: Finished, deadline: AbsoluteDeadline, goOn: GoOn): AttemptEnd {
+  if ("result" in run) {
+    const { result } = run;
+    return {
+      ending: { kind: "completed", value: result.value, stages: result.stages ?? [] },
+      settled: result,
+      exitCode: OUTCOMES.completed.exitCode!,
+    };
+  }
+  const { error } = run;
+  const settled = error instanceof WorkflowRunError ? error : undefined;
+  const { kind, stop, cancellation } = runOutcome(error, deadline);
+  const cause = unwrapped(error);
+  const beside =
+    stop && cause instanceof AggregateError
+      ? cause.errors.slice(1).map(errorDetail).join("; ")
+      : "";
+  const stages = settled?.stages ?? [];
+  return {
+    ending: {
+      kind,
+      ...(settled?.endedIn === undefined ? {} : { stage: settled.endedIn }),
+      // A stop's own, which the next attempt compares with its own stop's.
+      reason: stop?.reason ?? errorDetail(error),
+      stages,
+      continue: goOn(stop, stages),
+    },
+    ...(settled ? { settled } : {}),
+    exitCode: cancellation ? signalExitCode(cancellation.reason) : OUTCOMES[kind].exitCode!,
+    ...(beside ? { alsoFailed: beside } : {}),
+    ...(stop instanceof FromStageUnreached ? { choose: stop.recorded } : {}),
+    ...(stop?.needs ? { needs: stop.needs } : {}),
+  };
+}
+
+/**
+ * The ending of an attempt whose run never started, from what stopped it: it settled nothing, so
+ * what it cost is nothing but the time from `run.startedAt` to `run.endedAt`.
+ */
+export function endedBeforeStart(
+  error: unknown,
+  deadline: AbsoluteDeadline,
+  run: { runId: string; startedAt: number; endedAt: number },
+  goOn: GoOn,
+): AttemptEnd & { ending: Exclude<Ending<JsonValue>, { kind: "completed" }> } {
+  const { kind, cancellation } = runOutcome(error, deadline);
+  const times = {
+    startedAt: new Date(run.startedAt).toISOString(),
+    finishedAt: new Date(run.endedAt).toISOString(),
+  };
+  return {
+    ending: {
+      kind,
+      reason: cancellation ? "cancelled before it started" : errorDetail(error),
+      stages: [],
+      continue: goOn(undefined, []),
+    },
+    settled: {
+      runId: run.runId,
+      usage: [],
+      ...times,
+      accounting: summarizeRun([], PUBLISHED_PRICES, times, []),
+    },
+    exitCode: cancellation ? signalExitCode(cancellation.reason) : OUTCOMES[kind].exitCode!,
+  };
+}
+
+/**
+ * A completed attempt whose runtime then failed to clean up is failed: no record of it may say it
+ * completed. Any other ending stands, the cleanup's failure said beside it.
+ */
+export function cleanupFailed(end: AttemptEnd, error: unknown, goOn: string): AttemptEnd {
+  if (end.ending.kind !== "completed") return end;
+  return {
+    ...end,
+    ending: {
+      kind: "failed",
+      reason: `runtime cleanup failed: ${messageOf(error)}`,
+      stages: end.ending.stages,
+      continue: goOn,
+    },
+    exitCode: OUTCOMES.failed.exitCode!,
+  };
+}
+
+/**
+ * How a run that did not succeed ended, with the stop or the cancellation that decided it. The
+ * operator cancelling wins. It timed out when its own deadline ended it: the body's failure, or the
+ * first error of its aggregate, is a deadline error carrying the run's deadline. A deadline the
+ * workflow set and let escape is its own failure.
+ */
+export function runOutcome(
+  error: unknown,
+  deadline: AbsoluteDeadline,
+): { kind: UnfinishedOutcome; stop?: WorkflowStopped; cancellation?: WorkflowCancelledError } {
+  const cancellation = findCancellation(error);
+  const failure = primaryFailure(unwrapped(error));
+  const stop = failure instanceof WorkflowStopped ? failure : undefined;
+  const timedOut =
+    failure instanceof DeadlineExceededError &&
+    failure.deadline.unixMilliseconds === deadline.unixMilliseconds;
+  const kind = cancellation ? "cancelled" : stop ? "stopped" : timedOut ? "timed-out" : "failed";
+  return { kind, ...(stop ? { stop } : {}), ...(cancellation ? { cancellation } : {}) };
+}
+
+/** What the run threw, out of the wrapping that carries what it settled. */
+function unwrapped(error: unknown): unknown {
+  return error instanceof WorkflowRunError ? error.cause : error;
+}
+
+function findCancellation(error: unknown): WorkflowCancelledError | undefined {
+  if (error instanceof WorkflowCancelledError) return error;
+  if (error instanceof WorkflowRunError) return findCancellation(error.cause);
+  if (!(error instanceof AggregateError)) return undefined;
+  for (const nested of error.errors) {
+    const cancellation = findCancellation(nested);
+    if (cancellation) return cancellation;
+  }
+  return undefined;
+}
+
+function errorDetail(error: unknown): string {
+  if (error instanceof WorkflowRunError) return errorDetail(error.cause);
+  return error instanceof AggregateError
+    ? error.errors.map(errorDetail).join("; ")
+    : messageOf(error);
+}
+
+/** A shell's code for a process ended by `reason`, as if the signal had killed it. */
+export function signalExitCode(reason: unknown): number {
+  const number = constants.signals[reason as keyof typeof constants.signals];
+  return 128 + (number ?? constants.signals.SIGINT);
+}

package/src/attempt-output.ts

@@ -0,0 +1,132 @@
+import { rm } from "node:fs/promises";
+import {
+  OUTPUT_RECORD_VERSION,
+  type OutputRecord,
+  RUN_EVENT_VERSIONS,
+} from "@agentswf/contract/records";
+import type { Ending, ExecutableWorkflow, JsonValue } from "@agentswf/contract/workflow";
+import { attemptAccounting } from "./accounting/summary";
+import type { AttemptEnd } from "./attempt-ending";
+import { messageOf } from "./errors";
+import { writeJson, writeWhole } from "./files";
+import { type Attempt, appendEvent, endAttempt, outputFile, reportFile } from "./runs";
+import { withoutValue } from "./stage-ledger";
+
+/** Where an attempt's records went, and its output record as `--json` prints it. */
+export type Kept = {
+  /** Absent when the run never settled, so there is nothing to record but its ending. */
+  json?: string;
+  /** output.json, once written. */
+  output?: string;
+  report?: string;
+};
+
+/**
+ * Writes an attempt's records, each from its one ending: report.md, output.json, then the ending in
+ * its attempt file. The ending goes last: an ended attempt lets the next start, whose report and
+ * output this one's must not overwrite. A record that fails to write is said, and costs no other.
+ */
+export async function keepRecords(
+  end: AttemptEnd,
+  context: {
+    attempt: Attempt;
+    executable: ExecutableWorkflow<JsonValue, JsonValue>;
+    workflow: { name: string; file: string };
+    stderr: (text: string) => void;
+  },
+): Promise<Kept> {
+  const { attempt, stderr } = context;
+  const { ending, settled } = end;
+  const dir = attempt.run.dir;
+  const report = await writeReport(context.executable, ending, dir, stderr);
+  const stages = settled?.stages?.map(withoutValue);
+  const at =
+    ending.kind !== "completed" && ending.stage !== undefined ? { stage: ending.stage } : {};
+  const ended =
+    ending.kind === "completed"
+      ? { outcome: "completed" as const, value: ending.value }
+      : {
+          outcome: ending.kind,
+          reason: ending.reason,
+          ...at,
+          ...(end.needs ? { needs: [...end.needs] } : {}),
+        };
+  const kept: Kept = report ? { report } : {};
+  const output = outputFile(dir);
+  if (!settled) {
+    // An earlier attempt's output is gone with it, as its report is.
+    await rm(output, { force: true }).catch((error) =>
+      stderr(`awf: output.json: ${messageOf(error)}`),
+    );
+  } else {
+    const record: OutputRecord = {
+      version: OUTPUT_RECORD_VERSION,
+      runId: settled.runId,
+      attempt: attempt.record.attempt,
+      workflow: context.workflow,
+      accounting: settled.accounting,
+      usage: settled.usage,
+      artifacts: dir,
+      ...(settled.sandboxes ? { sandboxes: settled.sandboxes } : {}),
+      ...(settled.skills ? { skills: settled.skills } : {}),
+      ...(settled.panes ? { panes: settled.panes } : {}),
+      ...(settled.decisions ? { decisions: settled.decisions } : {}),
+      ...(stages ? { stages } : {}),
+      ...(report ? { report } : {}),
+      ...ended,
+    };
+    kept.json = JSON.stringify(record, null, 2);
+    try {
+      await writeJson(output, record);
+      kept.output = output;
+    } catch (error) {
+      stderr(`awf: output.json: ${messageOf(error)}`);
+    }
+  }
+  // Before the ending: once the attempt has ended, the next may start appending.
+  await appendEvent(dir, {
+    version: RUN_EVENT_VERSIONS["attempt-ended"],
+    attempt: attempt.record.attempt,
+    at: new Date().toISOString(),
+    kind: "attempt-ended",
+    outcome: ending.kind,
+  }).catch((error) => stderr(`awf: the run's event log was not written: ${messageOf(error)}`));
+  try {
+    await endAttempt(attempt, {
+      outcome: ending.kind,
+      ...(ending.kind === "completed" ? {} : { reason: ending.reason }),
+      ...at,
+      ...(stages ? { stages } : {}),
+      ...(settled ? { accounting: attemptAccounting(settled.accounting) } : {}),
+    });
+  } catch (error) {
+    stderr(`awf: the attempt's ending was not written to ${attempt.file}: ${messageOf(error)}`);
+  }
+  return kept;
+}
+
+async function writeReport(
+  executable: ExecutableWorkflow<JsonValue, JsonValue>,
+  ending: Ending<JsonValue>,
+  dir: string,
+  stderr: (text: string) => void,
+): Promise<string | undefined> {
+  const file = reportFile(dir);
+  // An earlier attempt's report is gone with it: report.md is the last ended attempt's.
+  const none = () => rm(file, { force: true }).then(() => undefined);
+  if (!executable.report) return none();
+  // The result is still in output.json; a report that cannot be rendered or saved should not fail
+  // the run, nor cost it its record.
+  try {
+    const markdown = executable.report(
+      ending.kind === "completed" ? ending.value : undefined,
+      ending,
+    );
+    if (markdown === undefined) return await none();
+    await writeWhole(file, `${markdown.trimEnd()}\n`);
+    return file;
+  } catch (error) {
+    stderr(`awf: report: ${messageOf(error)}; see output.json instead`);
+    return undefined;
+  }
+}

package/src/attempt-view.ts

@@ -0,0 +1,362 @@
+import type {
+  AgentPaneRecord,
+  AttemptRecord,
+  RunAccounting,
+  StageNeed,
+  StageRecord,
+} from "@agentswf/contract/records";
+import type {
+  Ending,
+  ExecutableWorkflow,
+  JsonValue,
+  StageSummary,
+} from "@agentswf/contract/workflow";
+import { ago, describeAccounting, describeAttempts } from "./accounting/format";
+import { sumAttempts } from "./accounting/summary";
+import { type AttemptEnd, OUTCOMES } from "./attempt-ending";
+import type { Kept } from "./attempt-output";
+import { pathFrom } from "./display-path";
+import { messageOf } from "./errors";
+import { ANSI, type Paint, PLAIN } from "./progress-view";
+import type { RunCommand } from "./run-command";
+import type { AttemptRefusal } from "./runs";
+import { schemaLines } from "./stage-schema";
+import { FromStageUnreached, type WorkflowStopped } from "./stopped";
+
+/**
+ * Prints how the attempt ended, and returns its exit code. A completed one's result goes to stdout;
+ * otherwise stdout stays empty but for the record `--json` asks for, since a caller reading it
+ * without checking the exit code would take it for a result.
+ */
+export function printEnding(
+  end: AttemptEnd,
+  kept: Kept,
+  context: {
+    executable: ExecutableWorkflow<JsonValue, JsonValue>;
+    /** The run's id and folder. */
+    run: { id: string; dir: string };
+    n: number;
+    earlier: readonly AttemptRecord[];
+    json: boolean;
+    /** Whether the attempt redid from a stage, which no repeated stop then hints at. */
+    fromStage: boolean;
+    now: number;
+    shellCwd: string;
+    home: string;
+    cleanupAlso?: string;
+    /** Given when the stages and their cost were drawn on a terminal, not written as a log. */
+    terminal?: { color: boolean };
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    /** For what is said beside a problem, not one. */
+    notice: (text: string) => void;
+  },
+): number {
+  const { stdout, stderr, shellCwd } = context;
+  const { ending, settled } = end;
+  const presented =
+    ending.kind === "completed" && !context.json
+      ? present(context.executable, ending, stderr)
+      : undefined;
+  if (end.alsoFailed) stderr(`awf: also failed: ${end.alsoFailed}`);
+  const again =
+    ending.kind !== "completed" && !context.fromStage
+      ? sameStop(ending, context.earlier)
+      : undefined;
+  if (again) context.notice(again);
+  if (context.cleanupAlso) stderr(`awf: runtime cleanup also failed: ${context.cleanupAlso}`);
+  // Beside the result rather than in it: stdout stays the workflow's report or the JSON.
+  const lines = describeEnding(ending, {
+    named: `${context.executable.definition.meta.name} ${context.run.id}`,
+    n: context.n,
+    ...(settled ? { accounting: settled.accounting } : {}),
+    earlier: context.earlier,
+    stages: context.terminal === undefined,
+    records: pathFrom(shellCwd, context.run.dir, { home: context.home }),
+    ...(kept.report ? { report: pathFrom(shellCwd, kept.report, { home: context.home }) } : {}),
+    ...(end.choose?.length ? { choose: listRecorded(end.choose, context.now) } : {}),
+    ...(end.needs ? { needs: end.needs } : {}),
+    ...(settled?.panes ? { panes: settled.panes } : {}),
+    // As the run's Herdr workspace is labelled.
+    runWorkspace: `awf ${context.executable.definition.meta.name} ${context.run.id} #${context.n}`,
+    paint: context.terminal?.color ? ANSI : PLAIN,
+  });
+  for (const line of ["", ...lines]) stderr(line);
+  if (ending.kind === "completed") stdout(presented ?? kept.json ?? JSON.stringify(ending.value));
+  else if (context.json && kept.json !== undefined) stdout(kept.json);
+  return end.exitCode;
+}
+
+/** What the calling session is told of how the run ended, and where its record is. */
+export function toldOf(end: AttemptEnd, kept: Kept): string {
+  const { ending } = end;
+  const told = `${OUTCOMES[ending.kind].told}${kept.output ? `; its record is ${kept.output}` : ""}`;
+  return ending.kind === "completed" ? told : `${told}: ${ending.reason}`;
+}
+
+/**
+ * How an attempt ended, once, after its stages: the outcome, where and why; the run and what the
+ * attempt cost, and for a later attempt the whole run, counting the attempts whose cost is
+ * unknown; then the value it stopped for, the command that goes on, or the stages to choose from,
+ * and where the records are. `stages` lists what each stage cost, where no view beside them did.
+ */
+function describeEnding(
+  ending: Ending<JsonValue>,
+  context: {
+    /** The workflow's name and the run's id. */
+    named: string;
+    n: number;
+    accounting?: RunAccounting;
+    earlier: readonly AttemptRecord[];
+    stages: boolean;
+    records: string;
+    report?: string;
+    /** The recorded stages, a line each, one of which the go-on's `{stage}` needs. */
+    choose?: readonly string[];
+    /** The stages whose values `--values` gives, and their schemas. */
+    needs?: readonly StageNeed[];
+    panes?: readonly AgentPaneRecord[];
+    runWorkspace: string;
+    paint: Paint;
+  },
+): string[] {
+  const { accounting, n } = context;
+  const mark = OUTCOMES[ending.kind].mark(context.paint);
+  const [totals, ...figures] = accounting
+    ? describeAccounting(accounting, { stages: context.stages })
+    : [];
+  const run = [
+    context.named,
+    ...(n > 1 ? [`attempt ${n}`] : []),
+    ...(totals === undefined ? [] : [totals]),
+    ...(n > 1 && accounting ? [runTotal(n, accounting, context.earlier)] : []),
+  ].join(" · ");
+  const word = OUTCOMES[ending.kind].word;
+  if (ending.kind === "completed") {
+    return [`${mark} ${word} · ${run}`, ...figures, ...rows([], context)];
+  }
+  // A reason's later lines, such as a schema's problems, sit under it, apart from the rows.
+  const [first, ...more] = ending.reason.split("\n");
+  const goOn = context.choose
+    ? [ending.continue, `${STAGE} one of:`, ...context.choose]
+    : [ending.continue];
+  return [
+    `${mark} ${word}${ending.stage === undefined ? "" : ` in ${ending.stage}`}: ${first}`,
+    ...more.map((line) => `    ${line.trim()}`),
+    `  ${run}`,
+    ...figures,
+    ...rows(goOn, context),
+  ];
+}
+
+/**
+ * The rows under an ending: the value it stopped for, the command that goes on, its lines given,
+ * the report, the records.
+ */
+function rows(
+  goOn: readonly string[],
+  context: {
+    records: string;
+    report?: string;
+    needs?: readonly StageNeed[];
+    panes?: readonly AgentPaneRecord[];
+    runWorkspace: string;
+  },
+): string[] {
+  const row = (key: string, value: string) => `  ${key.padEnd(7)}  ${value}`;
+  const under = (line: string) => `${" ".repeat(11)}${line}`;
+  const [command, ...choices] = goOn;
+  // A stage a line, and a schema with branches a line per branch under it.
+  const [first, ...needs] = (context.needs ?? []).flatMap(({ stage, schema }) => {
+    const [only, ...more] = schemaLines(schema);
+    return more.length === 0
+      ? [`${stage}: ${only}`]
+      : [`${stage}, one of:`, ...[only!, ...more].map((line) => `  ${line}`)];
+  });
+  return [
+    ...(first === undefined ? [] : [row("needs", first), ...needs.map(under)]),
+    ...(command === undefined ? [] : [row("go on", command)]),
+    ...choices.map(under),
+    ...paneRows(context.panes ?? [], context.runWorkspace).map(([key, value]) => row(key, value)),
+    ...(context.report ? [row("report", context.report)] : []),
+    row("records", context.records),
+  ];
+}
+
+/**
+ * Each pane that fell back from its layout, and why, and each kept one, with where to find it:
+ * once each, as nothing else says them.
+ */
+export function paneRows(
+  panes: readonly AgentPaneRecord[],
+  /** The run's own workspace's label. */
+  runWorkspace: string,
+): [string, string][] {
+  return panes.flatMap(({ agent, placed }): [string, string][] => [
+    ...(placed.fallback === undefined
+      ? []
+      : [["pane", `${agent} in a tab of its own: ${placed.fallback}`] as [string, string]]),
+    ...(placed.notKept === undefined
+      ? []
+      : [["pane", `${agent} closed, not kept: ${placed.notKept}`] as [string, string]]),
+    ...(placed.kept
+      ? [["kept", `${agent} · ${whereKept(placed, runWorkspace)}`] as [string, string]]
+      : []),
+  ]);
+}
+
+/** Sessions awf starts, headless, and an operator attaches to from a terminal outside Herdr. */
+const OWN_SESSION = /^awf(-|$)/;
+
+function whereKept(
+  { session, workspace, tab, beside }: AgentPaneRecord["placed"],
+  runWorkspace: string,
+): string {
+  const pane = beside === undefined ? `tab "${tab}"` : `beside ${beside}`;
+  if (workspace === "origin") return `${pane}, where awf run was typed`;
+  const label = workspace === "run" ? runWorkspace : workspace.name;
+  return OWN_SESSION.test(session)
+    ? `${pane} in workspace "${label}" · herdr session attach ${session}`
+    : `${pane} in workspace "${label}" of herdr session ${session}`;
+}
+
+function runTotal(n: number, current: RunAccounting, earlier: readonly AttemptRecord[]): string {
+  const before = earlier.filter((record) => record.attempt < n);
+  const recorded = [...before.flatMap((record) => record.accounting ?? []), current];
+  const unknown = before.filter((record) => record.accounting === undefined);
+  const interrupted = unknown.filter((record) => record.ended === undefined).length;
+  return describeAttempts(sumAttempts(recorded), n, {
+    interrupted,
+    ended: unknown.length - interrupted,
+  });
+}
+
+/** A completed attempt's value as the workflow presents it; undefined to print the JSON. */
+function present(
+  executable: ExecutableWorkflow<JsonValue, JsonValue>,
+  ending: Extract<Ending<JsonValue>, { kind: "completed" }>,
+  stderr: (text: string) => void,
+): string | undefined {
+  if (!executable.present) return undefined;
+  try {
+    return executable.present(ending.value, ending)?.trimEnd();
+  } catch (error) {
+    stderr(`awf: present: ${messageOf(error)}; printing the full result instead`);
+    return undefined;
+  }
+}
+
+/**
+ * A plain continue that ran no stage and stopped between stages as the attempt before did: the
+ * check on a reused stage's value belongs inside that stage, which a continue would redo.
+ */
+function sameStop(
+  ending: Ending<JsonValue>,
+  earlier: readonly AttemptRecord[],
+): string | undefined {
+  if (ending.kind !== "stopped" || ending.stage !== undefined) return undefined;
+  const reused = ending.stages.at(-1)?.stage;
+  // No stage ran, and one was reused: its value is what the check between stages saw.
+  if (reused === undefined || ending.stages.some((entered) => entered.source === "ran")) {
+    return undefined;
+  }
+  const before = earlier.at(-1);
+  if (
+    before?.outcome !== "stopped" ||
+    before.stage !== undefined ||
+    before.reason !== ending.reason
+  ) {
+    return undefined;
+  }
+  return `awf: the same stop as attempt ${before.attempt}; if a stage's value caused it, --from-stage ${reused}, and move the check into that stage`;
+}
+
+/** Why a run takes no attempt now, as awf says it, at time `now`. */
+export function refusalMessage(id: string, refusal: AttemptRefusal, now: number): string {
+  if (refusal.kind === "running") {
+    return `attempt ${refusal.attempt.attempt} of ${id} is still running, as process ${refusal.attempt.pid}`;
+  }
+  if (refusal.stages.length === 0) return `${id} completed; there is nothing to continue`;
+  return `${id} completed; to redo from a stage, --from-stage one of:\n${listRecorded(refusal.stages, now).join("\n")}`;
+}
+
+/** Stage records, a line each, in the order given: summary, attempt, and how long ago. */
+function listRecorded(records: readonly StageRecord[], now: number): string[] {
+  const name = Math.max(0, ...records.map((record) => record.stage.length));
+  const summary = Math.max(0, ...records.map((record) => record.summary?.length ?? 0));
+  return records.map((record) =>
+    [
+      `  ${record.stage.padEnd(name)}`,
+      ...(summary > 0 ? [(record.summary ?? "").padEnd(summary)] : []),
+      [
+        ...(record.outcome === "succeeded" ? [] : [record.outcome]),
+        `attempt ${record.attempt}`,
+        ago(now - Date.parse(record.ended)),
+      ].join(" · "),
+    ].join("   "),
+  );
+}
+
+/**
+ * The command that goes on from an attempt that didn't complete: the same file and run root, and
+ * `--from-stage` when a plain continue would stop at the same record again, or would drop the redo
+ * this attempt asked for and never reached. A `--from-stage` the body returned without reaching
+ * has no one command: it names `{stage}`, for one of the run's stages, and isn't runnable as is.
+ * Going on from that start point repeats `--values`, or names `{file}` for a value it stopped for.
+ */
+export function continueCommand(
+  command: Pick<
+    RunCommand,
+    | "shellCwd"
+    | "cwd"
+    | "cwdGiven"
+    | "runRoot"
+    | "runRootGiven"
+    | "workflowFile"
+    | "fromStage"
+    | "values"
+  >,
+  id: string,
+  stop: WorkflowStopped | undefined,
+  entered: readonly Pick<StageSummary, "stage">[],
+): string {
+  const { fromStage } = command;
+  const redo =
+    stop instanceof FromStageUnreached
+      ? STAGE
+      : stop?.redo && stop.stage !== undefined
+        ? stop.stage
+        : fromStage !== undefined && !entered.some(({ stage }) => stage === fromStage)
+          ? fromStage
+          : undefined;
+  const values =
+    redo === undefined || redo !== fromStage
+      ? undefined
+      : command.values
+        ? pathFrom(command.shellCwd, command.values.file)
+        : stop?.needs
+          ? FILE
+          : undefined;
+  return [
+    "awf",
+    "run",
+    ...(command.runRootGiven ? ["--run-root", command.runRoot] : []),
+    ...(command.cwdGiven ? ["--cwd", command.cwd] : []),
+    pathFrom(command.shellCwd, command.workflowFile),
+    "--continue",
+    id,
+    ...(redo === undefined ? [] : ["--from-stage", redo]),
+    ...(values === undefined ? [] : ["--values", values]),
+  ]
+    .map((word) => (word === STAGE || word === FILE ? word : shellWord(word)))
+    .join(" ");
+}
+
+/** The placeholder a go-on names when the operator chooses the stage. */
+const STAGE = "{stage}";
+/** The placeholder for the file of values a go-on needs and none was given. */
+const FILE = "{file}";
+
+export function shellWord(word: string): string {
+  return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`;
+}