@agentswf/engine 0.1.0-beta.4 → 0.1.0

package/src/event-ids.ts

@@ -0,0 +1,31 @@
+import { AWF_ID_PREFIX } from "@agentswf/contract/workflow";
+import type { DerivedIds } from "./run-policy/waits";
+
+function hashed(kind: string, text: string): string {
+  const hash = new Bun.CryptoHasher("sha256").update(text).digest("hex");
+  return `${AWF_ID_PREFIX}${kind}.${hash.slice(0, 16)}`;
+}
+
+/** The id timer `name` is taken under: made from its name, so it fires once. */
+export function timerEventId(name: string): string {
+  return hashed("timer", name);
+}
+
+/**
+ * The id of branch `branch`'s time read from state, `due` an ISO time: made from both, so a time is
+ * returned once by a branch of that name, whichever loop reads it.
+ */
+export function atEventId(branch: string, due: string): string {
+  return hashed("at", `${branch}\n${due}`);
+}
+
+/**
+ * The id of the end of `agent`'s turn `turn`, begun in attempt `began`: made from the three, so it
+ * fits the grammar whatever each is, and is the same whoever writes it, so one end is ever kept.
+ */
+export function endIdOf(agent: string, turn: string, began: number): string {
+  return hashed("end", `${agent}\0${turn}\0${began}`);
+}
+
+/** The derived ids, as the waits' policy takes them. */
+export const DERIVED_IDS: DerivedIds = { timer: timerEventId, at: atEventId };

package/src/files.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
-import { realpathSync } from "node:fs";
+import { realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { link, lstat, open, rename, unlink } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
 /** `path` with its symlinks resolved, or only made absolute when it doesn't exist. */
 export function realPath(path: string): string {
@@ -32,14 +32,38 @@ export async function writeWhole(path: string, text: string): Promise<void> {
   }
 }
 
+/**
+ * `text` at `path` whole, synchronously, for a writer that must not wait between two steps: a temp
+ * file renamed into place, mode `0600`. Not synced: it needs only to exist and be whole.
+ */
+export function writeWholeSync(path: string, text: string): void {
+  const temporary = temporaryBeside(path);
+  try {
+    writeFileSync(temporary, text, { mode: 0o600, flag: "wx" });
+    renameSync(temporary, path);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // Never made, or gone already.
+    }
+    throw error;
+  }
+}
+
 /**
  * Links a complete file holding `value` to `path`, which fails when `path` exists: the first to
  * link holds it. False when it was taken.
  */
-export async function linkNew(path: string, value: unknown): Promise<boolean> {
+export function linkNew(path: string, value: unknown): Promise<boolean> {
+  return linkNewText(path, jsonText(value));
+}
+
+/** As `linkNew`, for text. */
+export async function linkNewText(path: string, text: string): Promise<boolean> {
   const temporary = temporaryBeside(path);
   try {
-    await writeSynced(temporary, jsonText(value));
+    await writeSynced(temporary, text);
     await link(temporary, path);
     return true;
   } catch (error) {
@@ -62,6 +86,22 @@ async function writeSynced(path: string, text: string): Promise<void> {
   }
 }
 
+/** Makes the entries of folder `dir`, a rename or link into it, durable. */
+export async function syncDir(dir: string): Promise<void> {
+  const handle = await open(dir, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Whether `path` is below `root`, not `root` itself; a child named `..x` is below it. */
+export function isInside(root: string, path: string): boolean {
+  const inside = relative(root, path);
+  return inside !== "" && inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside);
+}
+
 /** Whether `path` names anything, a dangling link included. */
 export async function exists(path: string): Promise<boolean> {
   return lstat(path).then(

package/src/hand-over.ts

@@ -0,0 +1,150 @@
+// The global `awf`'s first step, before the engine is imported: a project whose installed `agentswf`
+// is another version runs on that one (ADR 0015). Imports nothing of the engine, so a hand-over
+// costs a Bun start and no more, and the engine's own checks can share how a project's engine is
+// found.
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** The `agentswf` installed in a `node_modules` at or above a directory. */
+export type InstalledEngine = {
+  /** Its package's folder, its real path: what `AWF_ENGINE` names. */
+  dir: string;
+  /** The directory whose `node_modules` holds it: where its `awf` is run from. */
+  root: string;
+  /** Its `package.json`'s `version`, not the range a project declares. */
+  version: string;
+  /** Its `awf`, as its `package.json`'s `bin` gives it. */
+  bin: string;
+};
+
+/**
+ * A project's engine: installed, declared in the nearest `package.json` at or above it and not
+ * installed (or installed broken), or none, which any engine runs.
+ */
+export type ProjectEngine =
+  | ({ kind: "installed" } & InstalledEngine)
+  | { kind: "declared"; manifest: string }
+  | { kind: "none" };
+
+/**
+ * The `agentswf` found by walking up from `from` for `node_modules/agentswf/package.json`. Not
+ * Bun's resolver, whose auto-install answers with a cache copy where nothing is installed. One
+ * whose manifest gives no version or `awf` is broken, and its `package.json` is returned instead.
+ */
+export function installedEngine(from: string): InstalledEngine | undefined {
+  const found = findEngine(from);
+  return found && "version" in found ? found : undefined;
+}
+
+function findEngine(from: string): InstalledEngine | { broken: string } | undefined {
+  for (let dir = resolve(from); ; dir = dirname(dir)) {
+    const manifest = join(dir, "node_modules", "agentswf", "package.json");
+    if (existsSync(manifest)) {
+      const read = readManifest(manifest);
+      const bin = typeof read?.bin === "object" ? read.bin?.awf : read?.bin;
+      if (typeof read?.version !== "string" || typeof bin !== "string") return { broken: manifest };
+      const root = realpathSync(dirname(manifest));
+      return { dir: root, root: dir, version: read.version, bin: resolve(root, bin) };
+    }
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * `project`'s engine: the one installed above it, else one the nearest `package.json` at or above
+ * it declares.
+ */
+export function projectEngine(project: string): ProjectEngine {
+  const found = findEngine(project);
+  if (found && "broken" in found) return { kind: "declared", manifest: found.broken };
+  if (found) return { kind: "installed", ...found };
+  for (let dir = resolve(project); ; dir = dirname(dir)) {
+    const manifest = join(dir, "package.json");
+    if (existsSync(manifest)) {
+      const read = readManifest(manifest);
+      const declared = ["dependencies", "devDependencies", "optionalDependencies"].some((field) => {
+        const deps = read?.[field];
+        return typeof deps === "object" && deps !== null && "agentswf" in deps;
+      });
+      return declared ? { kind: "declared", manifest } : { kind: "none" };
+    }
+    if (dirname(dir) === dir) return { kind: "none" };
+  }
+}
+
+type Manifest = Record<string, unknown> & {
+  version?: unknown;
+  bin?: string | { awf?: unknown };
+};
+
+function readManifest(file: string): Manifest | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(file, "utf8"));
+    return typeof value === "object" && value !== null ? (value as Manifest) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Set on an `awf` a hand-over runs: the engine it is, so that one doesn't hand over again. */
+export const ENGINE_VARIABLE = "AWF_ENGINE";
+
+/**
+ * What the global `awf` does first: when the `agentswf` installed above the shell's directory is
+ * another version than its own, it warns, runs that one's `awf` with the same argv, and exits as
+ * it does. Returns when this `awf` runs the command itself. `init`, `help`, `--version` and
+ * `tick --all` name no project's runs, and are never handed over.
+ */
+export async function handOver(own: {
+  /** This `awf`'s `agentswf` folder. */
+  dir: string;
+  version: string;
+  argv?: readonly string[];
+  cwd?: string;
+  environment?: Readonly<Record<string, string | undefined>>;
+}): Promise<void> {
+  const argv = own.argv ?? process.argv.slice(2);
+  const environment = own.environment ?? process.env;
+  const target = handOverTarget(argv, own.cwd ?? process.cwd(), own.version);
+  if (!target) return;
+  // The child, walking from the same directory, finds itself; the guard is for a loop all the same.
+  if (environment[ENGINE_VARIABLE] === realpathSync(own.dir)) return;
+  process.stderr.write(
+    `awf: awf ${own.version} is not this project's ${target.version}; running the project's. Update one, or run bunx awf here.\n`,
+  );
+  const child = Bun.spawn({
+    cmd: [process.execPath, "--no-env-file", target.bin, ...argv],
+    env: { ...environment, [ENGINE_VARIABLE]: target.dir },
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+  const forward = (signal: NodeJS.Signals) => () => child.kill(signal);
+  // Each is forwarded, for a signal sent to this process alone. The terminal's Ctrl-C reaches the
+  // child twice, through the process group too, and a run takes a repeat within a second as one;
+  // the prompt comes back once the child has ended, not before.
+  const listeners: [NodeJS.Signals, () => void][] = [
+    ["SIGTERM", forward("SIGTERM")],
+    ["SIGHUP", forward("SIGHUP")],
+    ["SIGINT", forward("SIGINT")],
+  ];
+  for (const [signal, listener] of listeners) process.on(signal, listener);
+  const code = await child.exited;
+  for (const [signal, listener] of listeners) process.off(signal, listener);
+  if (child.signalCode) process.kill(process.pid, child.signalCode);
+  process.exit(code ?? 1);
+}
+
+/** The engine `argv`, typed in `cwd`, is handed over to; undefined when this one runs it. */
+export function handOverTarget(
+  argv: readonly string[],
+  cwd: string,
+  version: string,
+): InstalledEngine | undefined {
+  const [word] = argv;
+  if (word === undefined || NOT_HANDED_OVER.has(word)) return undefined;
+  if (word === "tick" && argv.includes("--all")) return undefined;
+  const installed = installedEngine(cwd);
+  return installed && installed.version !== version ? installed : undefined;
+}
+
+const NOT_HANDED_OVER = new Set(["init", "help", "-h", "--help", "--version"]);

package/src/help/allowance.txt

@@ -8,6 +8,7 @@ none is named: claude, codex, pi, cursor.
 A plan's monthly price is an estimate at the vendor's list price as of the table's date:
 plans 2026-10-05.
 
---json prints one document, the interface for scripts, with the plan as the
-harness names it and no price; what it prints otherwise is for reading. A harness that could
-not be read says why. Exits 0 once every harness was asked, 2 on a usage error.
+--json prints one document, the interface for scripts, with the plan as the harness names it and
+no price; what it prints otherwise is for reading. A harness that could not be read says why; a
+failure is a refusal whose code says why: usage or internal-error. Exits 0 once every harness
+was asked, 2 on a usage error.

package/src/help/emit.txt

@@ -1,13 +1,25 @@
-usage: awf emit --target <file> --id <id> <event> [<json>] [--event-id <id>] [--json]
+usage: awf emit --target <file> --id <id> <event> [<json>] [--event-id <id>] [--source <name>] [--json]
+       awf emit <run> <key>:reply '{"text": …, "author": …}' [--event-id <id>] [--source <name>] [--cwd <directory>] [--run-root <directory>] [--json]
 
 Sends an event to the run of a workflow with events that --id names. That run starts if it has
 none and the event is one that starts one, and is woken if it has one: told while it runs,
 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.
+again is a duplicate. --source names the integration that sent it, such as github, which the
+event a wait returns carries.
+
+The second form sends a participant's message to the code of a run that is there, <workflow>/<id>
+or an <id> only one workflow has, here or in a project awf knows: <key>:reply, which the workflow
+declares, checked against the file the run's last attempt ran. "author" is optional. Its
+--event-id is the message's own id, so a resend is a duplicate. It never starts a run, and may
+arrive before the run connects the participant: it waits for the run's next wait. The first form
+takes only the workflow's own events.
 
 Prints what became of the event, and what was done to the run: accepted, duplicate or refused.
---json prints one document. Exits 0 for any of the three; 1 when <file> could not be loaded, and
-nothing is kept, or when the run's attempt could not be started (the event is kept, and the next
-event or awf tick tries again); 2 on a usage error, for a workflow with no events, or when the
-event is wrong for its target: its name, its data, or its id.
+--json prints one document: the result, or a refusal whose code says why it failed: usage,
+no-run, ambiguous, id, file, event, prepare, project, no-engine, other-engine, unreachable or
+internal-error. Exits 0 for any of the three; 1 when <file> could not be loaded, or the run
+isn't found or can't be read, and nothing is kept, or when the run's attempt could not be
+started (the event is kept, and the next event or awf tick tries again); 2 on a usage error, for
+a workflow with no events, or when the event is wrong for its target: its name, its data, or its
+id.

package/src/help/inbox.txt

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

package/src/help/logs.txt

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

package/src/help/open.txt

@@ -0,0 +1,29 @@
+usage: awf open <run> <agent> [--no-fork] [--session <id>] [-p [<text>]]
+                [--cwd <directory>] [--run-root <directory>] [--json]
+
+A run is <workflow>/<id>, or an <id> only one workflow has, here or in a project awf knows.
+Without an agent, it prints the command that opens each of the run's agents.
+Opens a copy of an agent's latest session in its harness's own TUI, where the agent worked: its
+working directory, its home and skills, its sandbox, on the model and effort it ran on, with the
+harness's own permission prompts. The copy is made without asking the model, and is yours: the
+run and the agent's session are unchanged, and awf keeps no record of it.
+
+--no-fork opens the session itself: what you say stays with the agent, awf logs shows it, and the
+next attempt resumes it. It is refused while the run is live; while it is open, no attempt starts
+and an event waits, and once the harness exits a run with events is woken for it.
+--session opens another session in the agent's place: a copy an earlier awf open made, as it is;
+or one of the agent's earlier sessions, as its latest would be.
+-p asks one question headless and prints the answer; the text is its argument, or stdin without
+one. It runs as the agent's turns ran, without prompts, in its sandbox when it had one; on
+claude, billed per token headless, it is refused unless the agent ran metered.
+As the harness exits, awf prints the command that opens the same session again.
+
+With --json, -p prints {"v": 1, "session", "forkedFrom"?, "reply", "again"}, or a refusal whose
+code says why: usage, no-run, ambiguous, id, no-session, live, opened, unreachable, no-engine,
+other-engine or internal-error. no-session is an agent with no session or operation to open;
+live, --no-fork, or a sandboxed agent, on a running run, or a --no-fork whose session changed as
+it held the run; opened, a run another awf open --no-fork holds, or a sandbox another awf open
+has open; internal-error, a copy or a -p question that failed. A TUI has no JSON: --json without
+-p is a usage error. Exits with the TUI's exit code, or 0 once -p printed its answer; 1 when
+refused or failed; 2 on a usage error, or a -p or a TUI the agent's harness can't give; 3 when
+the run or the agent's place could not be read, or awf itself failed.

package/src/help/reply.txt

@@ -1,6 +1,5 @@
 usage: awf reply <run> <agent> [--to <id>] [--as <participant>] [<text>]
        awf send <run> <agent> [--as <participant>] [<text>]
-       awf send <run> --as <participant> --event-id <id> [--author <name>] [<text>]
 each takes [--cwd <directory>] [--run-root <directory>] [--json]
 
 A run is <workflow>/<id>, or an <id> only one workflow has, here or in a project awf knows.
@@ -8,11 +7,10 @@ Answers a question an agent asked a participant outside the run, or messages an
 over a route the workflow allowed. The text is the argument, or stdin without one. --to names
 the question, as awf inbox prints it; it may be left out when the agent has one open. --as
 names the participant when the workflow connects more than one. Neither waits for an answer:
-it comes back in awf inbox. With --event-id, send is a reply on a participant the run routes to its
-code: no agent, it reaches the run whether it runs or is parked, and the same id again is a
-duplicate. The id is one the run has not had from anyone, as a chat's message ids are. It prints
-as awf emit does, and exits 0 for whatever the run did with it (accepted, duplicate, or refused
-by a run that returned); 1 when the run or participant isn't found, or its attempt didn't start.
+it comes back in awf inbox. A message on a participant to the run's code is sent with awf emit
+<run> <participant>:reply '{"text":…,"author":…}' --event-id <id>.
 
-Exits 0 when delivered, 1 when refused (the code says why), 2 on a usage error, 3 when the run
-could not be reached.
+With --json, each prints {"v": 3, "id": …} when delivered, or a refusal whose code says why: the
+participant's, or usage, no-run, ambiguous, id, unreachable, no-engine, other-engine or
+internal-error. Exits 0 when delivered, 1 when refused (the code says why), 2 on a usage error,
+3 when the run could not be reached.

package/src/help/run.txt

@@ -2,35 +2,53 @@ usage: awf run [options] <workflow-file> [options] [-- workflow arguments...]
        awf run [options] <workflow-file> --id <id> --continue
 run options: --id <id>, --continue, --from-stage <stage>, --values <file>,
              --timeout <duration>, --run-root <directory>, --cwd <directory>, --sandbox <file>,
+             --workspace <run|origin|name>, --keep-panes <never|on-failure|always>,
              --json, --no-watch, --here
 
 Each awf run is an attempt of a run: a new run, with --id's id or a generated one, or, with
---continue, the run --id names, with the arguments, --cwd and --sandbox it was started with. A continue reuses
-the stages that succeeded, up to the first with no record or to --from-stage, and runs the rest.
+--continue, the run --id names, with the arguments, --cwd, --sandbox, --workspace and
+--keep-panes it was started with. A continue reuses the stages that succeeded, up to the first
+with no record or to --from-stage, and runs the rest.
 A new run with --from-stage starts there. A stage before it with no record to reuse takes its
 value from --values, a JSON object by stage name, checked by its result; one that returns
 nothing is passed. Without one the attempt stops, naming the stage and its schema.
 A run is kept in .awf/runs/<workflow>/<id> under --cwd, unless --run-root names another folder
-for .awf/runs.
-A run has no deadline unless --timeout gives it one, per attempt.
+for .awf/runs. A workflow that gives file: import.meta.path keeps its runs in its file's project
+unless --run-root names another folder: the nearest directory at or above the file holding .awf/,
+else the file's own, so --continue finds a run a program started there from anywhere.
+A run has no deadline unless --timeout gives it one, per attempt: a duration, a decimal and s, m,
+h or d, such as 20m or 1d.
 A workflow that knows how to present its result prints that; --json prints the full result instead.
-Either way the full result is kept as output.json in the run's folder, beside report.md
+Either way the full result is kept as out.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.
+out.json too, with what it spent and why it ended; --json prints it. When no run comes of it,
+--json prints a refusal whose code says why: usage, file, prepare, no-id, id, no-run,
+other-args, not-started, unreachable, project, no-engine, other-engine or internal-error;
+--here takes no --json, nor does opening a run of a workflow with events, which prints no
+document. A second Ctrl-C stops awf at once, without it; a continue then reads
+what its agents spent.
 --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": {}}, naming srt or docker, 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.
+--workspace says where each TUI agent's tab opens: run, the run's own Herdr workspace (the
+default); origin, the one awf run was typed in; or any other word, the workspace with that label,
+found or made. --keep-panes says whether an agent's pane stays once it is done: never (the
+default), on-failure, when its last turn wasn't answered, or always. A kept pane's harness is left
+running, and yours. Both are kept with the run for every attempt, a woken one too. A run an event
+started has neither, and takes the defaults. A continue may give either again with the run's
+value, or its default where the run had none, and no other.
 --here, run by an agent in a Herdr pane, starts the run in a new tab and has it take that agent's
 session over as one of its agents, from its next turn until the run ends. It prints a line for
 the agent to end its turn with, which is how the run finds the session.
-A run of a workflow with events is named by --id, or by the workflow's id(args). awf run starts it
-with its arguments and no event, detached in its project, as awf emit would, and the run waits at
-its first receive. A run already there is only woken. A run an event starts has no argv: its args
-are what prepare makes of none.
+A run of a workflow with events is named by --id, or by the workflow's id(args); one without
+starts may have an id made, as any run. awf run starts it with its arguments and no event,
+detached in its project, as awf emit would, and the run waits at its first receive. A run already
+there is only woken. A run an event starts has no argv: its args are what prepare makes of none.
+Its --continue takes --from-stage, as any run's does, and no --values. A --from-stage the attempt
+never reaches runs the attempt until it would park or return, and stops it there.
 Exits 0 when the run completed or parked, 1 when it failed or timed out, 2 on a usage error or
 when the run is refused, 3 when it stopped and can go on with --continue, and 128 plus the
 signal's number when it was interrupted.
@@ -40,5 +58,6 @@ Examples:
   awf run --timeout 20m examples/minimum-review/review-loop.ts
   awf run examples/minimum-review/review-loop.ts -- packages/engine/src
   awf run examples/minimum-review/review-loop.ts --cwd ../other-repo
+  awf run examples/pane-layout/workflow.ts --workspace origin --keep-panes on-failure
 
 Workflow files are trusted code and run with your filesystem and process authority.

package/src/help/runs.txt

@@ -7,5 +7,7 @@ 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.
+--json prints one document, the interface for scripts: when it fails, a refusal whose code says
+why: usage, no-run, ambiguous, id, unreachable, no-engine, other-engine or internal-error. 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.

package/src/help/tick.txt

@@ -5,8 +5,13 @@ Wakes every run of a workflow with events under --cwd's .awf/runs, or --run-root
 runs lists there, as an event would: continues a parked run whose wait's timer is due, and a
 crashed or failed one until it has failed three times in a row. Runs of other workflows are left
 as they are. --all wakes them in every project awf has started one in, as ~/.awf/projects lists
-them. Run it on any schedule; a run is continued once however many wakers come at once.
+them. A project's runs are woken by its own agentswf: one at another version than this awf runs
+its own awf tick for them. Run it on any schedule; a run is continued once however many wakers
+come at once.
 
-Prints a line for each run it woke, and nothing when it woke none. --json prints one document.
-Exits 0; 1 when a project is gone or a run could not be woken, the others still woken; 2 on a
-usage error.
+Prints a line for each run it woke, and nothing when it woke none, and one line on stderr
+counting runs with events it can't read, which it doesn't wake; --json prints one document,
+those runs under unreadable, on exit 1 too, or a refusal whose code says why it failed: usage or
+internal-error. Exits 0; 1 when a project is gone, declares agentswf without installing it, or
+its own agentswf failed, or a run could not be woken, the others still woken; 2 on a usage
+error.

package/src/herdr-placement.ts

@@ -2,46 +2,16 @@ import { createHash } from "node:crypto";
 import { mkdir, rename, rmdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { HERDR_VERSION, type RunProcess } from "@agentswf/harness";
-import { messageOf } from "./errors";
-import { ensureRunSession, parseSessions, type RunSessionDeps } from "./herdr-run-session";
+import { isCode } from "./files";
+import { parseSessions } from "./herdr-run-session";
 import { machinePaths } from "./machine";
 
-/** Where a layout may open a session awf does not otherwise use: one named `awf-…` it starts. */
-const OWN_SESSION = /^awf(-|$)/;
 const LOCK_POLL_MS = 100;
 /** Held inside a session's queue: a short wait, then made anyway. */
 const LOCK_WAIT_MS = 5_000;
 /** A lock older than this was left by a run that died holding it. */
 const LOCK_STALE_MS = 30_000;
 
-/**
- * Whether a session a layout names can be used: undefined when it can, else why not. One named
- * `awf-…` is started, swept and restarted as the run session is; any other must be running. Either
- * must answer, on the Herdr the adapter drives.
- */
-export async function namedSession(
-  name: string,
-  deps: RunSessionDeps,
-): Promise<string | undefined> {
-  if (OWN_SESSION.test(name)) {
-    try {
-      await ensureRunSession(name, deps);
-    } catch (error) {
-      return messageOf(error);
-    }
-  } else {
-    const listed = await deps.run({
-      argv: ["herdr", "session", "list", "--json"],
-      timeoutMs: 10_000,
-    });
-    const found = parseSessions(listed.stdout).find((session) => session.name === name);
-    if (!found?.running) {
-      return "it is not running, and awf starts only sessions named awf-…";
-    }
-  }
-  return wrongVersion(name, deps.run);
-}
-
 /** Why the session's server is not the Herdr the adapter drives; undefined when it is. */
 async function wrongVersion(session: string, run: RunProcess): Promise<string | undefined> {
   const status = await run({
@@ -154,7 +124,7 @@ export function workspaceLock(home: string) {
         await mkdir(lock);
         return () => rmdir(lock).catch(() => undefined);
       } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        if (!isCode(error, "EEXIST")) throw error;
       }
       const made = await stat(lock).then(
         (found) => found.mtimeMs,

package/src/herdr-run-session.ts

@@ -1,9 +1,9 @@
 import { spawn } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import { link, mkdir, unlink, writeFile } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { RunProcess } from "@agentswf/harness";
 import { messageOf } from "./errors";
+import { linkNewText } from "./files";
 import {
   liveness,
   type MarkedPane,
@@ -17,7 +17,7 @@ import { machinePaths } from "./machine";
 import { SESSION_NAME } from "./pane-layout";
 import type { ProcessProbe } from "./runs";
 
-/** Where a run's pane agents open when `AWF_HERDR_SESSION` names nowhere else. */
+/** Where a run's TUI agents open when `AWF_HERDR_SESSION` names nowhere else. */
 const DEFAULT_RUN_SESSION = "awf";
 
 /** What may start: the shared session is awf's by its name, since which run created it is not knowable. */
@@ -53,7 +53,7 @@ const READY_POLL_MS = 200;
 const READY_WITHIN_MS = 10_000;
 
 /** Starts a server that outlives this process; settles once it has started, or could not. */
-export type StartServer = (
+type StartServer = (
   argv: readonly string[],
   options: { cwd: string; env: Record<string, string> },
 ) => Promise<void>;
@@ -87,7 +87,7 @@ export type RunSession = {
   kept?: KeptPane[];
 };
 
-export type KeptPane = { run: string; session: string; paneId: string };
+type KeptPane = { run: string; session: string; paneId: string };
 
 /** `AWF_HERDR_SESSION`, else `awf`; refused when Herdr could not use it as a session name. */
 export function runSessionName(environment: Readonly<Record<string, string | undefined>>): string {
@@ -101,7 +101,7 @@ export function runSessionName(environment: Readonly<Record<string, string | und
 }
 
 /**
- * The Herdr session a run's pane agents open in, running and kept: started detached when down and
+ * The Herdr session a run's TUI agents open in, running and kept: started detached when down and
  * named `awf` or `awf-…`, from a minimal environment and a quiet config, so it outlives this run
  * for the next. Any other name that is down is refused: it may be an operator's stopped session,
  * and bringing it back headless is not awf's call. Then the workspaces of runs that ended are
@@ -431,15 +431,7 @@ export function serverEnvironment(
 async function quietConfig(home: string): Promise<string> {
   const file = join(machinePaths(home).herdr, "config.toml");
   await mkdir(dirname(file), { recursive: true });
-  const temporary = `${file}.${randomBytes(4).toString("hex")}.tmp`;
-  try {
-    await writeFile(temporary, QUIET_CONFIG, { flag: "wx" });
-    await link(temporary, file);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-  } finally {
-    await unlink(temporary).catch(() => undefined);
-  }
+  await linkNewText(file, QUIET_CONFIG);
   return file;
 }