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

package/src/progress-view.ts

@@ -62,7 +62,7 @@ export function renderProgress(
     const shown =
       agents.length <= MAX_LISTED
         ? agents
-        : agents.filter((a) => isRunning(a) || isFailed(a) || a.stopped);
+        : agents.filter((a) => isRunning(a) || isFailed(a) || a.stopped || a.liveUntil);
     lines.push(...shown.slice(0, MAX_LISTED).map(agentLine));
     const hidden = agents.length - Math.min(shown.length, MAX_LISTED);
     if (hidden > 0) lines.push(paint.dim(`    … ${hidden} more`));
@@ -96,7 +96,9 @@ export function renderProgress(
   });
   // Agents opened outside any labelled parallel.
   const loose = snapshot.agents.filter((agent) => agent.group === undefined && !inStage(agent));
-  if (loose.some((agent) => isRunning(agent) || isFailed(agent) || agent.stopped))
+  if (
+    loose.some((agent) => isRunning(agent) || isFailed(agent) || agent.stopped || agent.liveUntil)
+  )
     listAgents(loose);
   return lines;
 }
@@ -105,7 +107,13 @@ export function renderProgress(
 export function progressEvents(
   before: WorkflowRunSnapshot | undefined,
   after: WorkflowRunSnapshot,
-  view: { startedAt: number; now: number; herdrSession?: string },
+  view: {
+    startedAt: number;
+    now: number;
+    herdrSession?: string;
+    /** Messages another view shows already, which get no line here. */
+    shown?: (message: WorkflowRunSnapshot["messages"][number]) => boolean;
+  },
 ): string[] {
   // Each stamped and ordered by when it happened; at the same instant, what ends goes before what
   // starts, and the inner before the outer as each ends, the outer before the inner as each starts.
@@ -141,6 +149,8 @@ export function progressEvents(
         `■ ${agent.key} stopped: ${oneLine(agent.stopped.reason)}`,
       );
     }
+    if (agent.liveUntil !== undefined && agent.liveUntil !== earlier?.liveUntil)
+      add(view.now, "agent phase", `… ${agent.key} · ${liveNote(agent.liveUntil)}`);
     if (!turn) continue;
     const fresh = earlier?.turns !== agent.turns;
     if (fresh && (turn.outcome === undefined || agent.stopped))
@@ -175,6 +185,7 @@ export function progressEvents(
     }
   }
   for (const message of after.messages.slice(before?.messages.length ?? 0)) {
+    if (view.shown?.(message)) continue;
     add(message.at, "message", messageLine(message));
   }
   after.stages.forEach((stage, index) => {
@@ -340,7 +351,7 @@ function stageAgentLine(
   const turn = agent.turn!;
   const [mark, note] =
     turn.outcome === "answered" && !agent.stopped
-      ? [paint.dim("·"), paint.dim("waiting")]
+      ? [paint.dim("·"), paint.dim(agent.liveUntil ? liveNote(agent.liveUntil) : "waiting")]
       : agentState(agent, now, paint, herdrSession);
   const took = duration((turn.settledAt ?? now) - turn.startedAt);
   const label = turn.label ?? (turn.kind === "turn" ? undefined : turn.kind);
@@ -375,7 +386,8 @@ function agentState(
     const queued = agent.queued ? `${agent.queued} queued` : "";
     return [paint.busy(spin(now)), [note, queued].filter(Boolean).join(" · ")];
   }
-  if (turn.outcome === "answered") return [paint.ok("✓"), ""];
+  if (turn.outcome === "answered")
+    return [paint.ok("✓"), agent.liveUntil ? paint.dim(liveNote(agent.liveUntil)) : ""];
   return [
     paint.bad("✗"),
     paint.bad(
@@ -465,6 +477,13 @@ function isFailed(agent: Agent): boolean {
   return agent.turn.outcome !== undefined && agent.turn.outcome !== "answered";
 }
 
+/** Kept alive: the run stays live, rather than parked, to this agent's window's end. */
+function liveNote(until: number): string {
+  const date = new Date(until);
+  const two = (n: number) => String(n).padStart(2, "0");
+  return `live until ${two(date.getHours())}:${two(date.getMinutes())}`;
+}
+
 function spin(now: number): string {
   return SPINNER[Math.floor(now / 100) % SPINNER.length]!;
 }
@@ -504,6 +523,10 @@ export function watchProgress(
   // nothing is said under the closing block.
   let stopped = false;
   let drawn = 0;
+  /** While a prompt waits for a line: the block is not drawn, and lines go above the prompt. */
+  let above: ((line: string) => void) | undefined;
+  /** Messages another view shows already, which get no line here. */
+  let shown: (message: WorkflowRunSnapshot["messages"][number]) => boolean = () => false;
   const clear = () => {
     if (terminal && drawn > 0) terminal.write(`\x1b[${drawn}F\x1b[0J`);
     drawn = 0;
@@ -513,7 +536,14 @@ export function watchProgress(
     const snapshot = handle.inspect();
     if (terminal) {
       // A message is an event: a line above the block, as a log line is.
-      const sent = snapshot.messages.slice(last?.messages.length ?? 0);
+      const sent = snapshot.messages
+        .slice(last?.messages.length ?? 0)
+        .filter((message) => !shown(message));
+      if (above && !final) {
+        for (const message of sent) above(messageLine(message));
+        last = snapshot;
+        return;
+      }
       if (sent.length > 0) {
         clear();
         for (const message of sent) stderr(messageLine(message));
@@ -533,7 +563,7 @@ export function watchProgress(
       if (lines.length > 0) terminal.write(`${lines.join("\n")}\n`);
       drawn = lines.length;
     } else {
-      const view = { startedAt, now: now(), ...(herdrSession ? { herdrSession } : {}) };
+      const view = { startedAt, now: now(), shown, ...(herdrSession ? { herdrSession } : {}) };
       for (const line of progressEvents(last, snapshot, view)) stderr(line);
     }
     last = snapshot;
@@ -548,10 +578,22 @@ export function watchProgress(
     },
     log(text: string) {
       if (stopped) return;
+      if (above) return above(text);
       clear();
       stderr(text);
       if (terminal) tick();
     },
+    /** Messages the prompt shows itself, with their text: no size line for them here. */
+    showsMessages(by: (message: WorkflowRunSnapshot["messages"][number]) => boolean) {
+      shown = by;
+    },
+    /** A prompt opened, writing lines through `under`, or closed with none. */
+    hold(under: ((line: string) => void) | undefined) {
+      if (stopped || !terminal) return;
+      above = under;
+      if (under) clear();
+      else tick();
+    },
     /** The Herdr session pane agents opened in, which a blocked one's line names. */
     placedIn(session: string) {
       if (!stopped) herdrSession = session;

package/src/projects.ts

@@ -0,0 +1,57 @@
+import { stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { realPath } from "./files";
+import { appendLine } from "./jsonl";
+import { withRunLock } from "./run-lock";
+
+/**
+ * The project a workflow with `events` runs in: the nearest directory at or above its file that
+ * holds `.awf/`, or else the file's own directory. Every sender names the file, so every sender,
+ * wherever it runs, finds the same runs (Q15). `{home}/.awf` is awf's own, not a project's.
+ */
+export async function projectOf(file: string, home: string): Promise<string> {
+  // The real path, so a sender naming the file through a link finds the same runs.
+  const start = realPath(dirname(resolve(file)));
+  const ownHome = realPath(home);
+  if (start === ownHome)
+    throw new Error(
+      `${file} is directly in home, where awf keeps its own .awf: move it into a directory`,
+    );
+  for (let dir = start; ; dir = dirname(dir)) {
+    if (dir === ownHome) return start;
+    const found = await stat(join(dir, ".awf")).then(
+      (info) => info.isDirectory(),
+      () => false,
+    );
+    if (found) return dir;
+    if (dirname(dir) === dir) return start;
+  }
+}
+
+/** Where a project's runs are kept. */
+export function projectRunRoot(project: string): string {
+  return join(project, ".awf", "runs");
+}
+
+/** `~/.awf/projects`: each project awf has started an event run in, one absolute path a line. */
+export function projectsFile(home: string): string {
+  return join(home, ".awf", "projects");
+}
+
+/** The projects awf has started an event run in, each once, in the order first started. */
+export async function listProjects(home: string): Promise<string[]> {
+  const text = await Bun.file(projectsFile(home))
+    .text()
+    .catch(() => "");
+  return [...new Set(text.split("\n").filter((line) => line.startsWith("/")))];
+}
+
+/** Adds `project` to `~/.awf/projects`, once. */
+export async function recordProject(home: string, project: string): Promise<void> {
+  const file = projectsFile(home);
+  if ((await listProjects(home)).includes(project)) return;
+  await withRunLock(`${file}.lock`, async () => {
+    if ((await listProjects(home)).includes(project)) return;
+    await appendLine(file, project);
+  });
+}

package/src/result-slots.ts

@@ -1,10 +1,10 @@
 import { acceptAny, type SemanticCheck } from "@agentswf/contract";
 import type { CandidateSource } from "@agentswf/contract/records";
 import type { JsonSchema } from "@agentswf/contract/schema";
-import type { ResultSubmitCode } from "@agentswf/contract/wire";
+import type { GivenInput, ResultSubmitCode } from "@agentswf/contract/wire";
 import type { AbsoluteDeadline } from "@agentswf/contract/workflow";
 import { scheduleAt } from "./deadlines";
-import { evaluateResult } from "./result-validation";
+import { evaluateGiven } from "./result-validation";
 import { recordCandidate, writeAcceptedExclusive, writeCall } from "./runs";
 
 export type ResultRejectionCode = ResultSubmitCode;
@@ -19,7 +19,7 @@ export type ResultSlotAccepted = {
 };
 type Rejected = { kind: "rejected"; code: ResultRejectionCode; error: string };
 export type ResultSubmission = ResultSlotAccepted | Rejected;
-export type WaitingGrant = { kind: "waiting"; waitUntil: number; deadline: number };
+export type WaitingGrant = { kind: "waiting"; waitUntil: number; deadline?: number };
 export type ResultSlotSettlement =
   | ResultSlotAccepted
   | { kind: "closed" }
@@ -36,7 +36,8 @@ export type ResultSlotSpec = {
   question: string;
   schema?: JsonSchema;
   semantic?: SemanticCheck;
-  deadline: AbsoluteDeadline;
+  /** Absent when nothing bounds the operation. */
+  deadline?: AbsoluteDeadline;
   allowWaiting?: boolean;
   onEvent?(event: ResultSlotEvent): void;
 };
@@ -58,9 +59,8 @@ interface ResultSlotPersistence {
 type SubmissionInput = {
   operationId: string;
   agentId: string;
-  raw: string;
   source: CandidateSource;
-};
+} & GivenInput;
 export interface ResultSlotRegistry {
   open(spec: ResultSlotSpec): Promise<ResultSlotBinding>;
   submit(input: SubmissionInput): Promise<ResultSubmission>;
@@ -71,6 +71,8 @@ export interface ResultSlotRegistry {
     timeoutMs?: number;
   }): Promise<WaitingGrant | Rejected>;
   close(operationId: string): Promise<boolean>;
+  /** Its operation's deadline moved, out by a wait that did not count, or to none. */
+  extend(operationId: string, deadline: AbsoluteDeadline | undefined): void;
 }
 type Slot = ResultSlotSpec & {
   state: "open" | "committing" | "accepted" | "closed" | "expired" | "failed";
@@ -107,7 +109,8 @@ export function createResultSlotRegistry(options: ResultSlotRegistryOptions): Re
           persistence.recordCandidate(options.runDir, slot.operationId, {
             at: new Date(now()).toISOString(),
             source: input.source,
-            raw: input.raw,
+            // Flags as given, whether or not they convert, so the record shows what the agent typed.
+            raw: input.raw ?? JSON.stringify(input.args ?? []),
             accepted,
             ...(error === undefined ? {} : { error }),
           }),
@@ -160,13 +163,7 @@ export function createResultSlotRegistry(options: ResultSlotRegistryOptions): Re
         } else slots.delete(spec.operationId);
         throw error;
       }
-      if (slot.state === "open") {
-        if (now() >= spec.deadline.unixMilliseconds) closeSlot(slot, "expired");
-        else
-          slot.cancelExpiry = schedule(spec.deadline.unixMilliseconds - now(), () => {
-            if (slot.state === "open") closeSlot(slot, "expired");
-          });
-      }
+      if (slot.state === "open") expireAt(slot);
       return { operationId: spec.operationId, settled };
     },
 
@@ -190,7 +187,7 @@ export function createResultSlotRegistry(options: ResultSlotRegistryOptions): Re
       )
         return rejected("invalid-request", "waiting timeout must be a positive safe integer");
       const at = now();
-      const remaining = slot.deadline.unixMilliseconds - at;
+      const remaining = (slot.deadline?.unixMilliseconds ?? Number.POSITIVE_INFINITY) - at;
       if (remaining <= 0) {
         closeSlot(slot, "expired");
         return rejected("expired-operation");
@@ -204,7 +201,11 @@ export function createResultSlotRegistry(options: ResultSlotRegistryOptions): Re
         at,
         revision: ++slot.revision,
       });
-      return { kind: "waiting", waitUntil, deadline: slot.deadline.unixMilliseconds };
+      return {
+        kind: "waiting",
+        waitUntil,
+        ...(slot.deadline ? { deadline: slot.deadline.unixMilliseconds } : {}),
+      };
     },
 
     async submit(input) {
@@ -213,7 +214,7 @@ export function createResultSlotRegistry(options: ResultSlotRegistryOptions): Re
       if (input.agentId !== slot.agentId) return rejected("wrong-agent");
       const unavailable = unavailableCode(slot, now());
       if (unavailable) return rejectKnown(slot, input, unavailable);
-      const evaluated = await evaluateResult(slot, input.raw, slot.semantic ?? acceptAny);
+      const evaluated = await evaluateGiven(slot, input, slot.semantic ?? acceptAny);
       const admittedAt = now();
       const late = unavailableCode(slot, admittedAt);
       if (late) return rejectKnown(slot, input, late);
@@ -281,16 +282,39 @@ export function createResultSlotRegistry(options: ResultSlotRegistryOptions): Re
     async close(operationId) {
       const slot = slots.get(operationId);
       if (!slot || (slot.state !== "open" && slot.state !== "committing")) return false;
-      closeSlot(slot, now() >= slot.deadline.unixMilliseconds ? "expired" : "closed");
+      closeSlot(
+        slot,
+        slot.deadline && now() >= slot.deadline.unixMilliseconds ? "expired" : "closed",
+      );
       return true;
     },
+
+    extend(operationId, deadline) {
+      const slot = slots.get(operationId);
+      if (slot?.state !== "open") return;
+      slot.cancelExpiry();
+      slot.cancelExpiry = () => {};
+      if (deadline) slot.deadline = deadline;
+      else delete slot.deadline;
+      expireAt(slot);
+    },
   };
+
+  function expireAt(slot: Slot): void {
+    const { deadline } = slot;
+    if (!deadline) return;
+    if (now() >= deadline.unixMilliseconds) closeSlot(slot, "expired");
+    else
+      slot.cancelExpiry = schedule(deadline.unixMilliseconds - now(), () => {
+        if (slot.state === "open") closeSlot(slot, "expired");
+      });
+  }
 }
 
 function unavailableCode(slot: Slot, now: number): ResultRejectionCode | null {
   if (slot.state === "expired") return "expired-operation";
   if (slot.state !== "open") return "closed-operation";
-  if (now >= slot.deadline.unixMilliseconds) {
+  if (slot.deadline && now >= slot.deadline.unixMilliseconds) {
     closeSlot(slot, "expired");
     return "expired-operation";
   }

package/src/result-validation.ts

@@ -1,37 +1,32 @@
 import { acceptAny, type SemanticCheck } from "@agentswf/contract";
 import type { CallSpec } from "@agentswf/contract/records";
-import { formatErrors, validate } from "@agentswf/contract/schema";
-import { messageOf } from "./errors";
+import type { GivenInput } from "@agentswf/contract/wire";
+import { checkGiven, readGiven } from "./simple-input";
 
 export type CandidateEvaluation =
   | { kind: "accepted"; value: unknown }
   | { kind: "rejected"; error: string };
 
-/** Validates without repairing or persisting; the result-slot transition owns acceptance. */
-export async function evaluateResult(
+/**
+ * A result as `wfa` sent it, validated without repairing or persisting; the result-slot transition
+ * owns acceptance.
+ */
+export async function evaluateGiven(
   call: Pick<CallSpec, "question" | "schema">,
-  raw: string,
+  given: GivenInput,
   semantic: SemanticCheck = acceptAny,
 ): Promise<CandidateEvaluation> {
-  let value: unknown;
-  try {
-    value = JSON.parse(raw);
-  } catch (error) {
-    const reason = messageOf(error);
-    return {
-      kind: "rejected",
-      error: [
-        `the value is not valid JSON: ${reason}`,
-        `expected: ${expectedShape(call)}`,
-        "send one JSON value, quoted as a single shell argument.",
-      ].join("\n"),
-    };
-  }
-
-  if (call.schema) {
-    const errors = validate(call.schema, value);
-    if (errors.length > 0) return { kind: "rejected", error: formatErrors(errors) };
+  const read = readGiven(call.schema, given);
+  if (!read.ok) {
+    const advice =
+      given.raw === undefined
+        ? ""
+        : "\nsend one JSON value in a quoted heredoc, as the request shows.";
+    return { kind: "rejected", error: `${read.error}${advice}` };
   }
+  const value = read.value;
+  const invalid = call.schema ? checkGiven(call.schema, given, value) : undefined;
+  if (invalid) return { kind: "rejected", error: invalid };
 
   const verdict = await semantic({ question: call.question, value: structuredClone(value) });
   return verdict.kind === "accepted"
@@ -41,7 +36,3 @@ export async function evaluateResult(
         error: `the value does not answer what was asked: ${verdict.reason}`,
       };
 }
-
-function expectedShape(call: Pick<CallSpec, "schema">): string {
-  return call.schema ? JSON.stringify(call.schema) : "any JSON value";
-}

package/src/run-command.ts

@@ -3,56 +3,11 @@ import { resolve } from "node:path";
 import type { JsonValue } 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 { idProblem, runRootOf, stageNameProblem } from "./runs";
 
-const DEFAULT_TIMEOUT = "1h";
-
-export const usage = [
-  "usage: awf run [options] <workflow-file> [options] [-- workflow arguments...]",
-  "       awf run [options] <workflow-file> --continue <id>",
-  "       awf init [dir] [--no-install]",
-  "       awf test [paths...] [-t <pattern>] [--watch] [--timeout <duration>]",
-  "       awf allowance [harness...] [--json]",
-  "       awf runs [<run>] [--json]          (awf runs -h)",
-  "       awf logs [<run>] [--after <cursor>] [--wait <seconds>] [--json]   (awf logs -h)",
-  "       awf --version",
-  "run options: --id <id>, --continue <id>, --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 the run",
-  "--continue 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.",
-  "The deadline defaults to 1h, 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.",
-  "",
-  "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. */
@@ -65,13 +20,13 @@ export type RunCommand = {
   runRootGiven: boolean;
   workflowFile: string;
   workflowArgs: string[];
-  /** As typed, for the attempt's record. */
-  timeout: string;
-  timeoutMilliseconds: number;
+  /** As typed, for the attempt's record; absent, the run has no deadline. */
+  timeout?: string;
+  timeoutMilliseconds?: number;
   runRoot: string;
   /** A new run's id, as `--id` gave it. */
   id?: string;
-  /** The run `--continue` adds an attempt to. */
+  /** The run `--id` names, which `--continue` adds an attempt to. */
   continueId?: string;
   /** The stage the attempt starts at, reusing those before it. */
   fromStage?: string;
@@ -88,13 +43,17 @@ export type RunCommand = {
   session?: string;
 };
 
-export function parseCommand(argv: readonly string[], cwd: string): 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" {
   if (argv[0] !== "run") throw new Error("expected the run command");
-  let timeout = DEFAULT_TIMEOUT;
-  let timeoutMilliseconds = parseDuration(DEFAULT_TIMEOUT);
+  const end = argv.indexOf("--");
+  const own = end < 0 ? argv : argv.slice(0, end);
+  if (own.includes("-h") || own.includes("--help")) return "help";
+  let timeout: string | undefined;
+  let timeoutMilliseconds: number | undefined;
   let runRoot: string | undefined;
-  let id: string | undefined;
-  let continueId: string | undefined;
+  let named: string | undefined;
+  let continuing = false;
   let fromStage: string | undefined;
   let values: RunCommand["values"];
   let cwdGiven = false;
@@ -126,6 +85,10 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand {
       here = true;
       continue;
     }
+    if (option === "--continue") {
+      continuing = true;
+      continue;
+    }
     const value = argv[index + 1];
     if (option === "--timeout") {
       if (!value) throw new Error("--timeout needs a duration such as 30m");
@@ -141,12 +104,11 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand {
       if (!statSync(workCwd, { throwIfNoEntry: false })?.isDirectory()) {
         throw new Error(`--cwd: not a directory: ${workCwd}`);
       }
-    } else if (option === "--id" || option === "--continue") {
-      if (!value) throw new Error(`${option} needs a run's id`);
+    } else if (option === "--id") {
+      if (!value) throw new Error("--id needs a run's id");
       const problem = idProblem(value);
-      if (problem) throw new Error(`${option}: ${problem}`);
-      if (option === "--id") id = value;
-      else continueId = value;
+      if (problem) throw new Error(`--id: ${problem}`);
+      named = value;
     } else if (option === "--from-stage") {
       if (!value) throw new Error("--from-stage needs a stage's name");
       const problem = stageNameProblem(value);
@@ -171,9 +133,10 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand {
   }
   if (!workflowFile) throw new Error("run needs one workflow file");
   if (here && session !== undefined) throw new Error("--here and --session do not go together");
-  if (id !== undefined && continueId !== undefined) {
-    throw new Error("--id names a new run and --continue an existing one; give one");
-  }
+  if (continuing && named === undefined)
+    throw new Error("--continue goes on with the run --id names");
+  const id = continuing ? undefined : named;
+  const continueId = continuing ? named : undefined;
   if (values !== undefined && fromStage === undefined) {
     throw new Error("--values goes with --from-stage: it gives the stages before it");
   }
@@ -185,8 +148,8 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand {
     runRootGiven: runRoot !== undefined,
     workflowFile,
     workflowArgs,
-    timeout,
-    timeoutMilliseconds,
+    ...(timeout === undefined ? {} : { timeout }),
+    ...(timeoutMilliseconds === undefined ? {} : { timeoutMilliseconds }),
     runRoot: runRoot ?? runRootOf(workCwd),
     ...(id === undefined ? {} : { id }),
     ...(continueId === undefined ? {} : { continueId }),

package/src/run-commands.ts

@@ -26,6 +26,11 @@ export function parsePlace(
   const rest: string[] = [];
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index]!;
+    // What follows is the command's own, a message's text included.
+    if (arg === "--") {
+      rest.push(...argv.slice(index));
+      break;
+    }
     if (arg === "--json") json = true;
     else if (arg === "--cwd" || arg === "--run-root") {
       const value = argv[index + 1];
@@ -106,11 +111,17 @@ export function startedLine(
   run: Pick<RunCommand, "cwd" | "cwdGiven" | "runRoot" | "runRootGiven">,
 ): string {
   const ref = `${workflow}/${id}`;
-  const repeat = [
+  return `awf: ${ref} started · watch: ${shellLine(["awf", "logs", ref, ...placeFlags(run)])}`;
+}
+
+/** The flags that find this run again from another command: the folder or run root given. */
+export function placeFlags(
+  run: Pick<RunCommand, "cwd" | "cwdGiven" | "runRoot" | "runRootGiven">,
+): string[] {
+  return [
     ...(run.cwdGiven ? ["--cwd", run.cwd] : []),
     ...(run.runRootGiven ? ["--run-root", run.runRoot] : []),
   ];
-  return `awf: ${ref} started · watch: ${shellLine(["awf", "logs", ref, ...repeat])}`;
 }
 
 /** `awf logs` from `cursor`: with `--wait` unless the page stopped short of the newest. */