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

package/src/deadlines.ts

@@ -7,23 +7,29 @@ export class WorkflowCancelledError extends Error {
   }
 }
 
-/** Races `execute` against `signal` and `deadline`; losing the race does not stop `execute`. */
+/**
+ * Races `execute` against `signal` and `deadline`, if there is one; losing the race does not stop
+ * `execute`.
+ */
 export async function runUntilStopped<T>(
   execute: () => Promise<T>,
   signal: AbortSignal | undefined,
-  deadline: AbsoluteDeadline,
+  deadline: AbsoluteDeadline | undefined,
 ): Promise<T> {
   if (signal?.aborted) throw new WorkflowCancelledError(signal.reason);
-  if (Date.now() >= deadline.unixMilliseconds) throw new DeadlineExceededError(deadline);
+  if (deadline && Date.now() >= deadline.unixMilliseconds)
+    throw new DeadlineExceededError(deadline);
   let rejectStopped!: (error: Error) => void;
   const stopped = new Promise<never>((_resolve, reject) => {
     rejectStopped = reject;
   });
   const abort = () => rejectStopped(new WorkflowCancelledError(signal?.reason));
   signal?.addEventListener("abort", abort, { once: true });
-  const cancelDeadline = scheduleAt(deadline, () => {
-    rejectStopped(new DeadlineExceededError(deadline));
-  });
+  const cancelDeadline = deadline
+    ? scheduleAt(deadline, () => {
+        rejectStopped(new DeadlineExceededError(deadline));
+      })
+    : () => undefined;
   try {
     return await Promise.race([execute(), stopped]);
   } finally {
@@ -32,7 +38,11 @@ export async function runUntilStopped<T>(
   }
 }
 
-export function waitForDeadline<T>(promise: Promise<T>, deadline: AbsoluteDeadline): Promise<T> {
+export function waitForDeadline<T>(
+  promise: Promise<T>,
+  deadline: AbsoluteDeadline | undefined,
+): Promise<T> {
+  if (!deadline) return promise;
   let cancelTimer: (() => void) | undefined;
   const expired = new Promise<never>((_resolve, reject) => {
     cancelTimer = scheduleAt(deadline, () => reject(new DeadlineExceededError(deadline)));
@@ -60,7 +70,20 @@ export function scheduleAt(deadline: AbsoluteDeadline, action: () => void): () =
   };
 }
 
-export function earlierDeadline(left: AbsoluteDeadline, right: AbsoluteDeadline): AbsoluteDeadline {
+/** The earlier of two deadlines, an absent one being none. */
+export function earlierDeadline(
+  left: AbsoluteDeadline,
+  right: AbsoluteDeadline | undefined,
+): AbsoluteDeadline;
+export function earlierDeadline(
+  left: AbsoluteDeadline | undefined,
+  right: AbsoluteDeadline | undefined,
+): AbsoluteDeadline | undefined;
+export function earlierDeadline(
+  left: AbsoluteDeadline | undefined,
+  right: AbsoluteDeadline | undefined,
+): AbsoluteDeadline | undefined {
+  if (!left || !right) return left ?? right;
   return left.unixMilliseconds <= right.unixMilliseconds ? left : right;
 }
 
@@ -68,14 +91,18 @@ export function laterDeadline(left: AbsoluteDeadline, right: AbsoluteDeadline):
   return left.unixMilliseconds >= right.unixMilliseconds ? left : right;
 }
 
-export function deadlineWithin(milliseconds: number, ceiling: AbsoluteDeadline): AbsoluteDeadline {
+export function deadlineWithin(
+  milliseconds: number,
+  ceiling: AbsoluteDeadline | undefined,
+): AbsoluteDeadline {
   if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) {
     throw new Error("timeoutMs must be a positive safe integer");
   }
   return earlierDeadline({ unixMilliseconds: Date.now() + milliseconds }, ceiling);
 }
 
-export function assertDeadline(deadline: AbsoluteDeadline): void {
+export function assertDeadline(deadline: AbsoluteDeadline | undefined): void {
+  if (!deadline) return;
   assertDeadlineValue(deadline);
   if (Date.now() >= deadline.unixMilliseconds) {
     throw new DeadlineExceededError(deadline);
@@ -88,6 +115,16 @@ export function assertDeadlineValue(deadline: AbsoluteDeadline): void {
   }
 }
 
+/**
+ * What a harness bounds a run, an agent or a turn by when nothing else does. Workflow code sees no
+ * deadline then; a harness needs one, and a timer cannot wait past about 24.8 days.
+ */
+const HARNESS_BOUND_MS = 7 * 24 * 60 * 60_000;
+
+export function harnessDeadline(deadline: AbsoluteDeadline | undefined): AbsoluteDeadline {
+  return deadline ?? { unixMilliseconds: Date.now() + HARNESS_BOUND_MS };
+}
+
 /** Waits `milliseconds`, or until `signal` aborts, whichever is first. */
 export function abortableSleep(milliseconds: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve) => {

package/src/decisions/directory.ts

@@ -34,9 +34,9 @@ import {
 const MAX_ATTEMPTS = 3;
 const FIRST_BACKOFF_MILLISECONDS = 500;
 
-/** Where a call runs: its scope's deadline, and the scope's way of cancelling what it owns. */
+/** Where a call runs: its scope's deadline, if any, and the scope's way of cancelling what it owns. */
 export type DecisionScope = {
-  deadline: AbsoluteDeadline;
+  deadline: AbsoluteDeadline | undefined;
   /** Returns the removal. */
   add?(cancel: (reason: string) => Promise<unknown>): () => void;
   /** The workflow stage it is asked in. */
@@ -48,7 +48,7 @@ type PreparedCall = {
   ids: string[];
   resolved: { provider: string; model: string };
   provider: DecisionProvider;
-  deadline: AbsoluteDeadline;
+  deadline: AbsoluteDeadline | undefined;
   slot: number;
 };
 
@@ -165,7 +165,9 @@ export class RunDecisions {
       controller.abort(next.outcome);
     };
     const cancel = (reason: string) => end({ outcome: "cancelled", reason });
-    const cancelTimer = scheduleAt(deadline, () => end({ outcome: "timed-out", deadline }));
+    const cancelTimer = deadline
+      ? scheduleAt(deadline, () => end({ outcome: "timed-out", deadline }))
+      : () => undefined;
     this.#cancellers.add(cancel);
     const removeFromScope = scope.add?.(async (reason) => cancel(reason));
 
@@ -217,7 +219,7 @@ export class RunDecisions {
             thrown instanceof DecisionProviderError &&
             thrown.retryable &&
             attempts < MAX_ATTEMPTS &&
-            Date.now() + backoff < deadline.unixMilliseconds;
+            (!deadline || Date.now() + backoff < deadline.unixMilliseconds);
           if (!retry) break;
           await (this.options.sleep ?? abortableSleep)(backoff, controller.signal);
           if (ending) break;
@@ -291,7 +293,7 @@ export class RunDecisions {
     const { charged: _charged, ...returned } = settled;
 
     if (returned.outcome === "answered") return { answers: answers!, record: returned };
-    if (returned.outcome === "timed-out") throw new DeadlineExceededError(deadline);
+    if (returned.outcome === "timed-out") throw new DeadlineExceededError(deadline!);
     throw new DecisionError(`decision ${spec.key}: ${returned.error}`, returned);
   }
 }

package/src/duration.ts

@@ -10,3 +10,32 @@ export function parseDuration(value: string): number {
   if (!Number.isSafeInteger(milliseconds)) throw new Error(`duration is too large: ${value}`);
   return milliseconds;
 }
+
+/** `45s`, `6m40s`, `1h02m`. */
+export function duration(milliseconds: number): string {
+  const seconds = Math.max(0, Math.round(milliseconds / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
+  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
+}
+
+/**
+ * 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.
+ */
+export function parseWhen(when: unknown, now: number): { due: number; when: string } {
+  if (when instanceof Date) {
+    const due = when.getTime();
+    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 };
+}

package/src/emit-command.ts

@@ -0,0 +1,130 @@
+import type { EmitResultJson } from "@agentswf/contract/records";
+import { isEventWorkflow, type JsonValue } from "@agentswf/contract/workflow";
+import { EmitError, emitEvent } from "./emit";
+import { messageOf } from "./errors";
+import type { Out } from "./run-commands";
+import type { Launch } from "./wake";
+import { loadWorkflowFile } from "./workflow-loader";
+
+export const emitUsage = [
+  "usage: awf emit --target <file> --id <id> <event> [<json>] [--event-id <id>] [--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: nudged while it runs, continued when it is",
+  "parked or crashed. The run lives in the project of <file>, the nearest directory above it",
+  "holding .awf/, whoever sends. --event-id names the occurrence: the same id again is a duplicate.",
+  "",
+  "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 the run's attempt could not be",
+  "started (the event is kept, and the next event or awf tick tries again), 2 when the event is",
+  "wrong for its target: its name, its data, or its id.",
+].join("\n");
+
+export async function emitCommand(
+  argv: readonly string[],
+  shellCwd: string,
+  out: Out,
+  context: {
+    home: string;
+    environment: Readonly<Record<string, string | undefined>>;
+    launch?: Launch;
+  },
+): Promise<number> {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    out.stdout(emitUsage);
+    return 0;
+  }
+  let parsed: {
+    target: string;
+    run: string;
+    name: string;
+    data: JsonValue;
+    id?: string;
+    json: boolean;
+  };
+  try {
+    parsed = parse(argv);
+  } catch (error) {
+    out.stderr(`awf: ${messageOf(error)}\n\n${emitUsage}`);
+    return 2;
+  }
+  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;
+    }
+    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;
+  }
+  return printEmit(result, parsed.json, out);
+}
+
+/** Prints an emit's result, as `awf emit` and `awf send` do: 1 when the run's attempt didn't start. */
+export function printEmit(result: EmitResultJson, json: boolean, out: Out): number {
+  out.stdout(json ? JSON.stringify(result) : emitLine(result));
+  if (result.why !== "launch-failed") return 0;
+  out.stderr(`awf: the run's attempt did not start: ${result.error}`);
+  return 1;
+}
+
+/** `accepted dd-case/kombo: started`. */
+function emitLine(result: EmitResultJson): string {
+  const did = result.did === "none" ? result.why : result.did;
+  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;
+} {
+  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]!;
+    const value = () => {
+      const next = argv[++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");
+  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(" ")}`);
+  let data: JsonValue = null;
+  if (text !== undefined) {
+    try {
+      data = JSON.parse(text) as JsonValue;
+    } catch (error) {
+      throw new Error(`the event's data is not JSON: ${messageOf(error)}`);
+    }
+  }
+  return { target, run, name, data, ...(id === undefined ? {} : { id }), json };
+}

package/src/emit.ts

@@ -0,0 +1,246 @@
+import { randomBytes } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import { type EmitResultJson, MAILBOX_RECORD_VERSION } from "@agentswf/contract/records";
+import { parseJsonSchema, validate } from "@agentswf/contract/schema";
+import {
+  AWF_ID_PREFIX,
+  eventWorkflowProblem,
+  type JsonValue,
+  nameProblem,
+} from "@agentswf/contract/workflow";
+import { messageOf } from "./errors";
+import { exists } from "./files";
+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 WakeContext, type Woken, wake } from "./wake";
+import type { EventWorkflow } 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 {
+  constructor(message: string) {
+    super(message);
+    this.name = "EmitError";
+  }
+}
+
+export type EmitContext = Omit<WakeContext, "file"> & {
+  /** As `WorkflowEvent.from`: the sending run's ref, or `operator`. */
+  from: string;
+};
+
+/**
+ * A sender's way in: checks the event against its target and delivers it to the run it names. A wrong name,
+ * shape or id throws an `EmitError`; the run's state is the outcome.
+ */
+export async function emitEvent(
+  target: EventWorkflow,
+  event: { run: string; name: string; data: JsonValue; id?: string },
+  context: EmitContext,
+): Promise<EmitResultJson> {
+  const workflow = target.meta.name;
+  const { name, data } = event;
+  checkEvent(target, event);
+  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) => {
+    throw new EmitError(messageOf(error));
+  });
+  const starts = target.starts?.includes(name) ?? true;
+  return deliver(
+    {
+      runRoot: projectRunRoot(project),
+      workflow,
+      runId,
+      event: { id, name, data, from: context.from, at },
+      deduplicate: event.id !== undefined,
+      file: target.file,
+      ...(starts ? { start: { project, target } } : {}),
+    },
+    context,
+  );
+}
+
+/** An event for a run of a workflow with events, as `deliver` takes it. */
+export type Delivery = {
+  runRoot: string;
+  workflow: string;
+  runId: string;
+  event: { id: string; name: string; data: JsonValue; from: string; at: string };
+  /** False for an id awf made at random, which nothing repeats. */
+  deduplicate: boolean;
+  /** Given when the event may start the run: what a new run records, and the workflow it prepares. */
+  start?: { project: string; target: EventWorkflow };
+  /** The file a sender named, which a start or continue runs; absent, the run's last. */
+  file?: string;
+};
+
+/**
+ * The one way in, for every event a run of a workflow with events gets: a sender's, a participant's reply, or awf's
+ * own. Under the run's lock it finds a duplicate, refuses the event, or creates the run, appends
+ * the event and wakes the run.
+ */
+export async function deliver(
+  delivery: Delivery,
+  context: Omit<WakeContext, "file">,
+): Promise<EmitResultJson> {
+  const { runRoot, workflow, runId, event, start, file } = delivery;
+  const woken = { ...context, ...(file ? { file } : {}) };
+  const ref = `${workflow}/${runId}`;
+  return withRunLock(runLockFile(runRoot, workflow, runId), async () => {
+    let run: Run | undefined = (await exists(join(runRoot, workflow, runId, "run.json")))
+      ? await openRun(runRoot, workflow, runId)
+      : undefined;
+    // What was due is `awf tick`'s to say; an emit's caller knows it sent an event.
+    const result = (outcome: EmitResultJson["outcome"], { cause: _, ...woken }: Woken) =>
+      ({ v: 1, outcome, ref, eventId: event.id, ...woken }) satisfies EmitResultJson;
+    if (run) {
+      // Not appended again, but it still wakes the run: a sender retrying after a launch that failed
+      // sends the same id.
+      if (delivery.deduplicate && foldMailbox(await readMailbox(run.dir)).events.has(event.id))
+        return result("duplicate", await wake(run, { ...woken, nudgeLive: false }));
+      if ((await readAttempts(run)).at(-1)?.outcome === "completed")
+        return result("refused", { did: "none", why: "returned" });
+    }
+    const starts = !run;
+    if (!run) {
+      if (!start) return result("refused", { did: "none", why: "not-a-start" });
+      checkStartArgs(start.target, start.project);
+      run = await createEventRun(runRoot, workflow, runId, start.project, file, context);
+    }
+    await appendMailbox(run.dir, {
+      version: MAILBOX_RECORD_VERSION,
+      kind: "event",
+      ...event,
+      ...(starts ? { starts: true as const } : {}),
+    });
+    return result("accepted", await wake(run, woken));
+  });
+}
+
+/**
+ * A run an event starts has no argv: its args are what `prepare` makes of none, checked before the
+ * run is made, so a workflow that needs args refuses the sender and leaves no run.
+ */
+function checkStartArgs(target: EventWorkflow, project: string): void {
+  try {
+    prepareArgs(target, [], project);
+  } catch (error) {
+    throw new EmitError(
+      `${target.meta.name}: a run an event starts has no arguments, which its prepare refuses: ${messageOf(error)}`,
+    );
+  }
+}
+
+/** A new run of a workflow with events, in `project`, recorded so `awf tick` finds it. */
+async function createEventRun(
+  runRoot: string,
+  workflow: string,
+  id: string,
+  project: string,
+  file: string | undefined,
+  context: Pick<WakeContext, "home" | "environment">,
+  argv: readonly string[] = [],
+): Promise<Run> {
+  const run = await createRun(runRoot, {
+    id,
+    workflow,
+    argv: [...argv],
+    cwd: project,
+    sandbox: null,
+    events: true,
+    env: { PATH: context.environment.PATH ?? "" },
+    ...(file ? { file } : {}),
+  });
+  await recordProject(context.home, project);
+  return run;
+}
+
+/** What `awf run --id` did to a run of a workflow with events: started it, or found it there. */
+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.
+ */
+export async function openEventRun(
+  target: EventWorkflow,
+  id: string,
+  argv: readonly string[],
+  context: Omit<WakeContext, "file">,
+): 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) => {
+    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 };
+    if (await exists(join(runRoot, workflow, id, "run.json"))) {
+      const run = await openRun(runRoot, workflow, id);
+      if ((await readAttempts(run)).at(-1)?.outcome === "completed")
+        return { run: ref, created: false, did: "none", why: "returned" };
+      if (argv.length > 0 && JSON.stringify(argv) !== JSON.stringify(run.record.argv))
+        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`,
+        );
+      return { run: ref, created: false, ...(await wake(run, woken)) };
+    }
+    try {
+      prepareArgs(target, argv, project);
+    } catch (error) {
+      throw new EmitError(`prepare: ${messageOf(error)}`);
+    }
+    const run = await createEventRun(runRoot, workflow, id, project, target.file, context, argv);
+    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. */
+export function checkEvent(
+  target: EventWorkflow,
+  event: { name: string; data: JsonValue; id?: string },
+): void {
+  const workflow = target.meta.name;
+  const problem = eventWorkflowProblem(target);
+  if (problem) throw new EmitError(`${workflow}: ${problem}`);
+  if (!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)
+    throw new EmitError(
+      `${workflow} declares no event ${event.name}; its events are ${Object.keys(target.events).join(", ")}`,
+    );
+  let parsed: ReturnType<typeof parseJsonSchema>;
+  try {
+    parsed = parseJsonSchema(schema);
+  } catch (error) {
+    throw new EmitError(`${workflow}'s schema for ${event.name}: ${String(error)}`);
+  }
+  const errors = validate(parsed, event.data);
+  if (errors.length > 0)
+    throw new EmitError(
+      `${event.name}'s data does not fit its schema: ${errors.map((e) => `${e.path || "/"}: ${e.message}`).join("; ")}`,
+    );
+  const badId = event.id === undefined ? undefined : eventIdProblem(event.id);
+  if (badId) throw new EmitError(`the id ${JSON.stringify(event.id)}: ${badId}`);
+}
+
+/** What is wrong with an id a sender gives an event, if anything: ids starting `awf.` are awf's. */
+export function eventIdProblem(id: string): string | undefined {
+  return (
+    nameProblem(id) ??
+    (id.startsWith(AWF_ID_PREFIX) ? `ids starting ${AWF_ID_PREFIX} are awf's own` : undefined)
+  );
+}

package/src/files.ts

@@ -1,6 +1,16 @@
 import { randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { link, lstat, open, rename, unlink } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+
+/** `path` with its symlinks resolved, or only made absolute when it doesn't exist. */
+export function realPath(path: string): string {
+  try {
+    return realpathSync(resolve(path));
+  } catch {
+    return resolve(path);
+  }
+}
 
 /**
  * Writes `value` to `path` whole: a temp file beside it, synced, then renamed into place. A crash

package/src/here.ts

@@ -53,6 +53,12 @@ export async function startHere(
     stderr(`awf: ${ready.refused}`);
     return 2;
   }
+  if ("opens" in ready) {
+    stderr(
+      "awf: a workflow with events runs detached, in its project; awf run --id starts it, without --here",
+    );
+    return 2;
+  }
   for (const line of ready.prepared.continued?.warnings ?? []) notice(line);
   const env = environment.environment ?? process.env;
   const run = environment.herdr ?? runProcess;
@@ -99,7 +105,7 @@ export async function startHere(
       // Under codex this can be another pane's workspace (E8); the run's tab still works from it.
       workspace,
       cwd: command.shellCwd,
-      label: tabLabel(ready.loaded.executable.definition.meta.name, id),
+      label: tabLabel(ready.loaded.workflow.meta.name, id),
       argv: [
         ...self,
         "run",
@@ -125,7 +131,7 @@ export async function startHere(
       "Run the workflow from a shell with awf run instead.",
     );
   }
-  notice(startedLine(ready.loaded.executable.definition.meta.name, id, command));
+  notice(startedLine(ready.loaded.workflow.meta.name, id, command));
   stdout(
     [
       `awf: ${basename(ready.loaded.file)} is starting in Herdr tab ${started.tabId}. Once this turn ends it takes this session over: each of its steps arrives here as a prompt, and a last message hands the session back.`,

package/src/hold-run-lock.fixture.ts

@@ -0,0 +1,8 @@
+// Holds a run's lock from another process for `emit.test.ts`: `bun hold-run-lock.fixture.ts {file} {ms}`.
+import { withRunLock } from "./run-lock";
+
+const [file, ms] = process.argv.slice(2);
+await withRunLock(file!, async () => {
+  console.log("held");
+  await Bun.sleep(Number(ms));
+});