@agentswf/engine 0.1.0-beta.4 → 0.1.0

package/src/operator-runtime.ts

@@ -23,6 +23,7 @@ import {
   readClaudeBilling,
   readCodexBilling,
   readCursorLogin,
+  runAttached,
   runProcess,
   withholding,
 } from "@agentswf/harness";
@@ -37,7 +38,7 @@ import { createSrtProvider, findSrt } from "@agentswf/sandbox/srt";
 import { createOpenRouterProvider } from "./decisions/openrouter";
 import type { DecisionInstallation } from "./decisions/seam";
 import { messageOf } from "./errors";
-import { findOrigin, namedSession, workspaceLock } from "./herdr-placement";
+import { findOrigin, workspaceLock } from "./herdr-placement";
 import {
   ensureRunSession,
   parseSessions,
@@ -48,6 +49,7 @@ import { markWorkspace } from "./herdr-workspace-marks";
 
 export type { RunSession } from "./herdr-run-session";
 
+import type { Attach } from "./open-command";
 import { OPERATOR_ALIASES } from "./operator-aliases";
 
 export type OperatorRuntimeInstallation = {
@@ -75,12 +77,12 @@ export type OperatorRuntimeOptions = {
   shellCwd?: string;
   /** The operator's home. */
   home?: string;
-  /** Told once, when the first pane agent's session is ready. */
+  /** Told once, when the first TUI agent's session is ready. */
   onRunSession?: (session: RunSession) => void;
 };
 
 /**
- * One run host for every agent: a Herdr tab for a pane agent, a subprocess per turn for a
+ * One run host for every agent: a Herdr tab for a TUI agent, a subprocess per turn for a
  * headless one. `WITHHELD_ENVIRONMENT` is cleared from both.
  */
 export async function installOperatorRuntime(
@@ -98,7 +100,7 @@ export async function installOperatorRuntime(
   } = options;
   const unmetered = withholding(run, WITHHELD_ENVIRONMENT);
   refuseMeteredCredentials(environment);
-  // Checked now, before any stage spends anything; made ready only for the first pane agent.
+  // Checked now, before any stage spends anything; made ready only for the first TUI agent.
   const name = runSessionName(environment);
   const session = runSessionOnce(() => name, { run, environment, home }, onRunSession);
   const runConfig = (session: string): HerdrConfig => ({
@@ -119,9 +121,9 @@ export async function installOperatorRuntime(
   const host = loginChecked(
     unmetered,
     createPlacementHostFactory({
-      // The session is made ready when the first pane agent opens, so an all-headless run never
+      // The session is made ready when the first TUI agent opens, so an all-headless run never
       // calls Herdr.
-      pane: {
+      tui: {
         accounting: createSessionAccounting(unmetered),
         openRun: async (spec) => {
           const { name } = await session();
@@ -129,7 +131,6 @@ export async function installOperatorRuntime(
           const config: HerdrConfig = {
             ...runConfig(name),
             onRunWorkspace: mark.bind,
-            sessionFor: (named) => namedSession(named, { run, environment, home }),
             origin: () =>
               findOrigin({
                 run,
@@ -424,6 +425,27 @@ const WITHHELD_ENVIRONMENT = [
   "AWF_CALLER_SESSIONS",
 ];
 
+/**
+ * How `awf open` runs a harness on an agent's session: its fork and `-p` turn, and its TUI on this
+ * terminal, each withholding what no agent inherits (story 042).
+ */
+export function openRuntime(environment: Readonly<Record<string, string | undefined>>): {
+  run: RunProcess;
+  attach: Attach;
+  providers: () => Promise<SandboxProviders>;
+} {
+  const withheld = Object.fromEntries(WITHHELD_ENVIRONMENT.map((name) => [name, undefined]));
+  return {
+    run: withholding(runProcess, WITHHELD_ENVIRONMENT),
+    // A sandbox's command has exactly its own environment; on the host, the operator's less these.
+    attach: (input) =>
+      input.exact
+        ? runAttached(input, {})
+        : runAttached({ ...input, env: { ...input.env, ...withheld } }, environment),
+    providers: () => installSandboxes(environment),
+  };
+}
+
 /**
  * Unset in a run's panes besides: the config the run session's server starts with, which a `herdr`
  * started in a pane would otherwise read in place of the operator's.

package/src/ops.ts

@@ -0,0 +1,270 @@
+import { mkdirSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  type Candidate,
+  isKnownOpFile,
+  OP_FILE_VERSIONS,
+  type OpFile,
+  type OpRecord,
+  type ResultRecord,
+} from "@agentswf/contract/records";
+import { nameProblem } from "@agentswf/contract/workflow";
+import { messageOf } from "./errors";
+import { isCode, linkNew, writeWholeSync } from "./files";
+import { appendLine, readLines } from "./jsonl";
+
+/**
+ * A run's `ops/`: one folder per operation, `ops/{key}.{n}/`, the `n`th turn, message operation or
+ * compaction of the agent keyed `{key}`, or the `n`th asking of the decision keyed `{key}`. It holds
+ * `op.json`, `answers.jsonl`, `result.json`, `decision.json`, `spend.json`, `live.jsonl` and
+ * `screen.txt`. The only module that knows where they are.
+ */
+
+/** An operation's folder. */
+function opDir(runDir: string, op: string): string {
+  return join(runDir, "ops", op);
+}
+
+/** What the operation is: `OpRecord`. */
+export function opFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "op.json");
+}
+
+/** Its settled usage: billing, spend per model, reported cost. */
+export function spendFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "spend.json");
+}
+
+/** Its delivery and nudge diagnostics, `OperationLivenessRecord` lines. */
+export function liveFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "live.jsonl");
+}
+
+/** A decision's `DecisionArtifact`, relative to the run's folder, as `DecisionRecord.artifact` names it. */
+export function decisionArtifact(op: string): string {
+  return join("ops", op, "decision.json");
+}
+
+/**
+ * The keys earlier attempts numbered operations under: each one's last `n`, and whose it is when its
+ * `op.json` says.
+ */
+export type EarlierOps = ReadonlyMap<string, { last: number; of?: "agent" | "decision" }>;
+
+/**
+ * Lists `ops/` once, as an attempt claims its run: `n` is the digits after a folder's last `.`.
+ * Whose a key is is read from its highest-numbered `op.json` that can be read.
+ */
+export async function listOps(runDir: string): Promise<EarlierOps> {
+  let names: string[];
+  try {
+    names = await readdir(join(runDir, "ops"));
+  } catch (error) {
+    if (isCode(error, "ENOENT")) return new Map();
+    throw error;
+  }
+  const numbers = new Map<string, number[]>();
+  for (const name of names) {
+    const match = /^(.+)\.(\d+)$/.exec(name);
+    if (!match) continue;
+    const list = numbers.get(match[1]!) ?? [];
+    list.push(Number(match[2]));
+    numbers.set(match[1]!, list);
+  }
+  const earlier = new Map<string, { last: number; of?: "agent" | "decision" }>();
+  await Promise.all(
+    [...numbers].map(async ([key, list]) => {
+      const descending = list.sort((a, b) => b - a);
+      let kind: OpRecord["kind"] | undefined;
+      for (const n of descending) {
+        kind = (await readOpFile<OpRecord>(opFile(runDir, `${key}.${n}`), "op"))?.kind;
+        if (kind !== undefined) break;
+      }
+      earlier.set(key, {
+        last: descending[0]!,
+        ...(kind === undefined ? {} : { of: kind === "decision" ? "decision" : "agent" }),
+      });
+    }),
+  );
+  return earlier;
+}
+
+/**
+ * Why `key` can't be an agent's or a decision's: it names folders, so it is a name, as an event's
+ * or stage's is, and has no colon, which awf's own event names, `{key}:ended`, split at.
+ */
+function keyProblem(key: string): string | undefined {
+  if (key.includes(":"))
+    return `a colon is kept for awf's own event names, such as {key}:ended; take another key, such as ${key.replaceAll(":", "-")}`;
+  return nameProblem(key);
+}
+
+/**
+ * An attempt's operation ids, `{key}.{n}`, numbered on from the last `n` its claim listed, so no
+ * id is reused across attempts. Agents and decisions share the keys: `{key}.{n}` is one operation.
+ */
+export class OpIds {
+  readonly #last = new Map<string, number>();
+  readonly #agents = new Set<string>();
+  readonly #decisions = new Set<string>();
+
+  constructor(
+    readonly runDir: string,
+    readonly attempt: number,
+    earlier: EarlierOps,
+  ) {
+    for (const [key, { last, of }] of earlier) {
+      this.#last.set(key, last);
+      if (of) (of === "decision" ? this.#decisions : this.#agents).add(key);
+    }
+  }
+
+  /** Refuses a key that isn't a name, or that the other kind already holds in the run. */
+  claim(key: string, as: "agent" | "decision"): void {
+    const problem = keyProblem(key);
+    if (problem) throw new Error(`${as} key ${key} is not a name: ${problem}`);
+    const [mine, other] =
+      as === "agent" ? [this.#agents, this.#decisions] : [this.#decisions, this.#agents];
+    if (other.has(key))
+      throw new Error(
+        `${key} is ${as === "agent" ? "a decision's" : "an agent's"} key: agents and decisions share one set of names, as each operation's folder is ops/{key}.{n}; ${as === "agent" ? "an agent" : "a decision"} takes another key`,
+      );
+    mine.add(key);
+  }
+
+  /**
+   * The key's next operation id, its folder and `op.json` written at once, before any line names it,
+   * so a later claim numbers past it however the operation ends. Synchronous, so nothing waits
+   * between an operation's start and its cancellation being registered. `lost` says why `op.json`
+   * wasn't written, which fails the operation.
+   */
+  draw(key: string, what: OpStart): { id: string; lost?: string } {
+    const n = (this.#last.get(key) ?? 0) + 1;
+    this.#last.set(key, n);
+    const id = `${key}.${n}`;
+    const record = {
+      version: OP_FILE_VERSIONS.op,
+      id,
+      attempt: this.attempt,
+      at: new Date().toISOString(),
+      ...what,
+    } as OpRecord;
+    try {
+      mkdirSync(opDir(this.runDir, id), { recursive: true });
+      writeWholeSync(opFile(this.runDir, id), `${JSON.stringify(record, null, 2)}\n`);
+      return { id };
+    } catch (error) {
+      return { id, lost: `op.json not written: ${messageOf(error)}` };
+    }
+  }
+}
+
+/** What an operation is, as it is drawn: its `op.json` but its version, id, attempt and time. */
+type OpStart = OpRecord extends infer Each
+  ? Each extends OpRecord
+    ? Omit<Each, "version" | "id" | "attempt" | "at">
+    : never
+  : never;
+
+/** Appends an answer offered, accepted or not, to its operation's `answers.jsonl`. */
+export async function recordAnswer(runDir: string, op: string, answer: Candidate): Promise<void> {
+  await mkdir(opDir(runDir, op), { recursive: true });
+  await appendLine(answersFile(runDir, op), JSON.stringify(answer));
+}
+
+/** An operation's answers, as tests check them; a run never reads them back. */
+export async function readAnswers(runDir: string, op: string): Promise<Candidate[]> {
+  return readLines<Candidate>(answersFile(runDir, op));
+}
+
+/** Claims an operation's one accepted result with `value`; false when another holds it. */
+export async function writeAcceptedExclusive(
+  runDir: string,
+  op: string,
+  value: unknown,
+): Promise<boolean> {
+  await mkdir(opDir(runDir, op), { recursive: true });
+  const record = {
+    version: OP_FILE_VERSIONS.result,
+    value,
+    at: new Date().toISOString(),
+  } as ResultRecord;
+  return linkNew(join(opDir(runDir, op), "result.json"), record);
+}
+
+/**
+ * An operation's accepted result, as tests check it; a run never reads it back. Null
+ * distinguishes "no value yet" from an operation whose accepted value happens to be null. A
+ * result.json of another version throws: unlike a cost, an answer has no unknown to fall back on.
+ */
+export async function readAccepted(runDir: string, op: string): Promise<{ value: unknown } | null> {
+  let text: string;
+  try {
+    text = await readFile(join(opDir(runDir, op), "result.json"), "utf8");
+  } catch (error) {
+    if (isCode(error, "ENOENT")) return null;
+    throw error;
+  }
+  const record: unknown = JSON.parse(text);
+  if (!isKnownOpFile("result", record))
+    throw new Error(`${op}'s result.json is not version ${OP_FILE_VERSIONS.result}`);
+  return { value: (record as ResultRecord).value };
+}
+
+/**
+ * An operation's JSON `file` at `path`, or undefined when it is missing, can't be parsed, or has no
+ * version or one this reader doesn't know: each is read as a file that isn't there. With `refuse`,
+ * a file that parses at another version throws instead, for a reader whose figures it would
+ * otherwise leave looking complete.
+ */
+export async function readOpFile<T>(
+  path: string,
+  file: OpFile,
+  options: { refuse?: boolean } = {},
+): Promise<T | undefined> {
+  let value: unknown;
+  try {
+    value = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (isKnownOpFile(file, value)) return value as T;
+  if (options.refuse && typeof value === "object" && value !== null) {
+    const version = (value as { version?: unknown }).version;
+    throw new Error(
+      `${path} is ${version === undefined ? "of no version" : `version ${JSON.stringify(version)}`}; this awf reads version ${OP_FILE_VERSIONS[file]}`,
+    );
+  }
+  return undefined;
+}
+
+/** The most of a screen kept: its last lines, where a pane's scrollback came with it. */
+const SCREEN_BYTES = 64 * 1024;
+
+/** An operation's `screen.txt`: what its pane showed as it ended without an answer. */
+export function screenFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "screen.txt");
+}
+
+export async function writeScreen(runDir: string, op: string, screen: string): Promise<void> {
+  const bytes = Buffer.from(screen);
+  const kept = bytes.length <= SCREEN_BYTES ? screen : tailOf(bytes);
+  await mkdir(opDir(runDir, op), { recursive: true });
+  await writeFile(screenFile(runDir, op), kept, { mode: 0o600 });
+}
+
+/** Its last whole lines within the bound, or its last bytes where one line is longer. */
+function tailOf(bytes: Buffer): string {
+  const tail = bytes.subarray(bytes.length - SCREEN_BYTES);
+  const line = tail.indexOf(10);
+  const whole = line === -1 || line === tail.length - 1 ? tail : tail.subarray(line + 1);
+  // A cut inside a character drops its continuation bytes.
+  let start = 0;
+  while (start < whole.length && (whole[start]! & 0xc0) === 0x80) start += 1;
+  return whole.subarray(start).toString();
+}
+
+function answersFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "answers.jsonl");
+}

package/src/pane-layout.ts

@@ -1,58 +1,69 @@
-import type { KeepPane, PaneLayout, TurnOutcome } from "@agentswf/contract/workflow";
+import type { RunPanes } from "@agentswf/contract/records";
+import type {
+  KeepPane,
+  PaneLayout,
+  PaneSpec,
+  PaneWorkspace,
+  TurnOutcome,
+} from "@agentswf/contract/workflow";
 
 /** A terminal session's name: Herdr makes `sessions/{name}` from it, and a leading `-` reads as an option. */
 export const SESSION_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
 
 const SHARE = { min: 0.2, max: 0.8 };
-const NEW_TAB_FIELDS = new Set(["session", "workspace", "tab"]);
 const BESIDE_FIELDS = new Set(["beside", "side", "share"]);
-const KEEP: readonly KeepPane[] = ["never", "on-failure", "always"];
+export const KEEP_PANES: readonly KeepPane[] = ["never", "on-failure", "always"];
 
 /**
- * Refuses, before anything is placed, what the agent's own spec fixes about its pane: what a
- * workflow, untyped at run time, could get wrong in `layout` or `keepPane`, and either on an agent
- * with no pane of awf's to place (docs/design/pane-layout.md, "Refused at open").
+ * Refuses, before anything is placed, what a workflow, untyped at run time, could get wrong in an
+ * agent's `pane`, and a `pane` on an agent with no pane of awf's to place
+ * (docs/design/pane-layout.md, "Refused at open").
  */
 export function checkPaneOptions(
   key: string,
-  spec: { layout?: unknown; keepPane?: unknown },
+  spec: { pane?: unknown },
   agent: { headless: boolean; sandboxed: boolean },
 ): void {
   const refuse = (why: string): never => {
     throw new Error(`agent ${key}: ${why}`);
   };
-  if (spec.layout === undefined && spec.keepPane === undefined) return;
-  if (agent.headless) refuse("layout and keepPane place a pane, and a headless agent has none");
-  if (agent.sandboxed) {
+  // Removed in 0.1.0-beta.6; refused, as they would place or keep a pane otherwise than written.
+  const given = spec as { layout?: unknown; keepPane?: unknown };
+  if (given.layout !== undefined)
     refuse(
-      "layout and keepPane are not yet for an agent in a sandbox, whose pane is in its own Herdr",
+      "layout was removed: give pane: { tab } or pane: { beside, side }; the workspace is awf run --workspace",
     );
+  if (given.keepPane !== undefined)
+    refuse("keepPane was removed: keeping panes is the operator's, awf run --keep-panes");
+  const { pane } = spec;
+  if (pane === undefined) return;
+  if (agent.headless) refuse("pane places a pane, and a headless agent has none");
+  if (agent.sandboxed) {
+    refuse("pane is not yet for an agent in a sandbox, whose pane is in its own Herdr");
   }
-  if (spec.keepPane !== undefined && !KEEP.includes(spec.keepPane as KeepPane)) {
-    refuse(`keepPane is never, on-failure or always, not ${JSON.stringify(spec.keepPane)}`);
-  }
-  if (spec.layout === undefined) return;
-  const layout = spec.layout;
-  if (typeof layout !== "object" || layout === null || Array.isArray(layout)) {
-    refuse(`a layout is an object, not ${JSON.stringify(layout)}`);
+  if (typeof pane !== "object" || pane === null || Array.isArray(pane)) {
+    refuse(`a pane is an object, not ${JSON.stringify(pane)}`);
   }
-  const fields = Object.keys(layout as object).filter(
-    (field) => (layout as Record<string, unknown>)[field] !== undefined,
+  const shape = pane as Record<string, unknown>;
+  const fields = Object.keys(shape).filter(
+    (field) => shape[field] !== undefined && field !== "front",
   );
-  const given = layout as Record<string, unknown>;
-  if (given.beside !== undefined) {
+  if (shape.front !== undefined && typeof shape.front !== "boolean") {
+    refuse(`front is true or false, not ${JSON.stringify(shape.front)}`);
+  }
+  if (shape.beside !== undefined) {
     const others = fields.filter((field) => !BESIDE_FIELDS.has(field));
     if (others.length > 0) {
-      refuse(`a layout beside another pane takes side and share, not ${others.join(", ")}`);
+      refuse(`a pane beside another pane takes side and share, not ${others.join(", ")}`);
     }
-    if (typeof given.beside !== "string" || given.beside === "") {
-      refuse(`beside names an agent's key, not ${JSON.stringify(given.beside)}`);
+    if (typeof shape.beside !== "string" || shape.beside === "") {
+      refuse(`beside names an agent's key, not ${JSON.stringify(shape.beside)}`);
     }
-    if (given.beside === key) refuse("a pane cannot be placed beside itself");
-    if (given.side !== "right" && given.side !== "below") {
-      refuse(`side is right or below, not ${JSON.stringify(given.side)}`);
+    if (shape.beside === key) refuse("a pane cannot be placed beside itself");
+    if (shape.side !== "right" && shape.side !== "below") {
+      refuse(`side is right or below, not ${JSON.stringify(shape.side)}`);
     }
-    const share = given.share;
+    const share = shape.share;
     if (
       share !== undefined &&
       (typeof share !== "number" || !(share >= SHARE.min && share <= SHARE.max))
@@ -61,46 +72,29 @@ export function checkPaneOptions(
     }
     return;
   }
-  const others = fields.filter((field) => !NEW_TAB_FIELDS.has(field));
+  const others = fields.filter((field) => field !== "tab");
   if (others.length > 0) {
     refuse(
-      `a layout takes session, workspace and tab, or beside and side; not ${others.join(", ")}`,
-    );
-  }
-  const { session, workspace, tab } = given;
-  if (session !== undefined && (typeof session !== "string" || !SESSION_NAME.test(session))) {
-    refuse(
-      `session ${JSON.stringify(session)} is not a session name: lowercase letters, digits and -, up to 32, not starting with -`,
+      `a pane takes tab, or beside and side, and front; not ${others.join(", ")}${others.some((field) => field === "workspace" || field === "session") ? ": the workspace is the operator's, awf run --workspace" : ""}`,
     );
   }
-  if (session !== undefined && workspace === "origin") {
-    refuse('"origin" is a workspace in its own session, so it takes no session');
-  }
-  if (
-    workspace !== undefined &&
-    workspace !== "run" &&
-    workspace !== "origin" &&
-    !(
-      typeof workspace === "object" &&
-      workspace !== null &&
-      !Array.isArray(workspace) &&
-      Object.keys(workspace).join() === "name" &&
-      nonEmpty((workspace as { name?: unknown }).name)
-    )
-  ) {
-    refuse(`workspace is "run", "origin" or { name }, not ${JSON.stringify(workspace)}`);
+  if (shape.tab !== undefined && !nonEmpty(shape.tab)) {
+    refuse(`tab is a label, not ${JSON.stringify(shape.tab)}`);
   }
-  if (tab !== undefined && !nonEmpty(tab)) refuse(`tab is a label, not ${JSON.stringify(tab)}`);
 }
 
 /**
- * A checked layout as it is kept and compared: fields given as `undefined` dropped, so a reopen
- * that leaves one out matches.
+ * A checked `pane` as it is kept and compared: fields given as `undefined` dropped, and
+ * `front: false`, which is its absence, so a reopen that leaves one out matches.
  */
-export function storedLayout(layout: PaneLayout): PaneLayout {
+export function storedPane(pane: PaneSpec): PaneSpec {
+  // Not an object, it is left for `checkPaneOptions` to refuse by name.
+  if (typeof pane !== "object" || pane === null || Array.isArray(pane)) return pane;
   return Object.fromEntries(
-    Object.entries(structuredClone(layout)).filter(([, value]) => value !== undefined),
-  ) as PaneLayout;
+    Object.entries(structuredClone(pane)).filter(
+      ([field, value]) => value !== undefined && !(field === "front" && value === false),
+    ),
+  ) as PaneSpec;
 }
 
 function nonEmpty(value: unknown): value is string {
@@ -112,6 +106,52 @@ export function besideOf(layout: PaneLayout | undefined): string | undefined {
   return layout && "beside" in layout ? layout.beside : undefined;
 }
 
+/** What the host is asked for one agent's pane. */
+export type PaneAsked = {
+  layout?: PaneLayout;
+  front?: true;
+  keepPane?: KeepPane;
+  /** For a pane beside another: where its own tab opens if its target has no pane. */
+  fallbackWorkspace?: PaneWorkspace;
+};
+
+/**
+ * What the host is asked for an agent's pane: the workflow's tab or neighbour and `front`, in the
+ * operator's workspace and kept as the operator says. An agent with no pane of awf's, headless or
+ * in a sandbox, is asked nothing.
+ */
+export function paneAsked(
+  pane: PaneSpec | undefined,
+  run: RunPanes | undefined,
+  hasPane: boolean,
+): PaneAsked {
+  if (!hasPane) return {};
+  const keepPane = run?.keep;
+  const workspace = run?.workspace;
+  const layout = placedLayout(pane, workspace);
+  return {
+    ...(layout === undefined ? {} : { layout }),
+    ...(pane?.front ? { front: true as const } : {}),
+    ...(keepPane === undefined ? {} : { keepPane }),
+    ...(besideOf(layout) !== undefined && workspace !== undefined
+      ? { fallbackWorkspace: workspace }
+      : {}),
+  };
+}
+
+function placedLayout(
+  pane: PaneSpec | undefined,
+  workspace: PaneWorkspace | undefined,
+): PaneLayout | undefined {
+  if (pane?.beside !== undefined) {
+    const { beside, side, share } = pane;
+    return { beside, side, ...(share === undefined ? {} : { share }) };
+  }
+  const tab = pane?.tab;
+  if (workspace !== undefined) return { workspace, ...(tab === undefined ? {} : { tab }) };
+  return tab === undefined ? undefined : { tab };
+}
+
 /**
  * Whether a done agent's pane stays, by `keepPane` and how its last operation ended: `on-failure`
  * keeps it unless that was answered, or there was none.
@@ -123,3 +163,9 @@ export function keepsPane(
   if (keepPane === "always") return true;
   return keepPane === "on-failure" && last !== undefined && last !== "answered";
 }
+
+/** `--workspace`'s value: the two keywords, else a workspace's label. */
+export function parseWorkspace(value: string): PaneWorkspace {
+  if (value === "run" || value === "origin") return value;
+  return { name: value };
+}

package/src/progress-view.ts

@@ -40,7 +40,7 @@ export function renderProgress(
     paint: Paint;
     /** Once the run is over: what each stage's agents cost, by stage. */
     figures?: ReadonlyMap<string, string>;
-    /** The Herdr session pane agents opened in, once one has. */
+    /** The Herdr session TUI agents opened in, once one has. */
     herdrSession?: string;
   },
 ): string[] {
@@ -168,7 +168,7 @@ export function progressEvents(
         turn.phase === "waiting"
           ? `waiting (agent-reported): ${oneLine(turn.waitingReason ?? "")}${turn.checkInAt === undefined ? "" : ` · check-in at ${clock(turn.checkInAt - view.startedAt)}`}`
           : turn.phase === "awaiting-reply"
-            ? `awaiting ${oneLine(turn.waitingReason ?? "a reply")}${turn.checkInAt === undefined ? "" : ` · until ${clock(turn.checkInAt - view.startedAt)}`}`
+            ? `awaiting-reply${turn.waitingReason === undefined ? "" : ` from ${oneLine(turn.waitingReason)}`}${turn.checkInAt === undefined ? "" : ` · until ${clock(turn.checkInAt - view.startedAt)}`}`
             : oneLine(turn.phase.replaceAll("-", " "));
       add(view.now, "agent phase", `… ${oneLine(agent.key)} · ${note}`);
     }
@@ -316,7 +316,7 @@ const GAP = "   ";
 
 const HOUR_MS = 60 * 60_000;
 
-/** The attempt that recorded a reused stage, and its record's age once that may make it stale. */
+/** The attempt that ran a reused stage, and its line's age once that may make it stale. */
 function reusedTail(stage: StageProgress, now: number): string {
   const age = stage.recordedAt === undefined ? 0 : now - stage.recordedAt;
   return [
@@ -400,11 +400,11 @@ function agentState(
 function awaitingNote(turn: NonNullable<Agent["turn"]>, now: number): string {
   const since = turn.phaseAt ?? turn.startedAt;
   const of = turn.checkInAt === undefined ? "" : ` of ${duration(turn.checkInAt - since)}`;
-  return `awaiting ${oneLine(turn.waitingReason ?? "a reply")} · ${duration(Math.max(0, now - since))}${of}`;
+  return `awaiting-reply${turn.waitingReason === undefined ? "" : ` from ${oneLine(turn.waitingReason)}`} · ${duration(Math.max(0, now - since))}${of}`;
 }
 
 /** A message admitted: who to whom, its size, and whether it asks or answers. */
-export function messageLine(message: WorkflowRunSnapshot["messages"][number]): string {
+function messageLine(message: WorkflowRunSnapshot["messages"][number]): string {
   const size =
     message.bytes < 1024 ? `${message.bytes} B` : `${(message.bytes / 1024).toFixed(1)} KB`;
   const kind = [message.answers ? "reply" : "", message.asks ? "reply owed" : ""].filter(Boolean);
@@ -412,20 +412,20 @@ export function messageLine(message: WorkflowRunSnapshot["messages"][number]): s
 }
 
 /**
- * Where to see a pane agent Herdr read as blocked on a prompt: its session plays no sound, so this
+ * Where to see a TUI agent Herdr read as blocked on a prompt: its session plays no sound, so this
  * is the one sign. Not the calling session's, which is the operator's own pane.
  */
 function whereBlocked(agent: Agent, herdrSession: string | undefined): string {
   return agent.turn?.outcome === "blocked" &&
     herdrSession !== undefined &&
-    placementOf(agent.execution) === "pane" &&
+    placementOf(agent.execution) === "tui" &&
     !agent.execution.caller
     ? ` · herdr session attach ${herdrSession}`
     : "";
 }
 
 /**
- * Where a run's pane agents are, said once as the first opens; the workspace closes with the run.
+ * Where a run's TUI agents are, said once as the first opens; the workspace closes with the run.
  * A client inside Herdr can't attach to another session, so from there it says where to.
  */
 export function describeRunSession(
@@ -519,7 +519,7 @@ export function watchProgress(
   let handle: WorkflowRunHandle<JsonValue> | undefined;
   let last: WorkflowRunSnapshot | undefined;
   let herdrSession: string | undefined;
-  // A pane agent's session can be ready after the run has ended, as a cancel lands while it starts:
+  // A TUI agent's session can be ready after the run has ended, as a cancel lands while it starts:
   // nothing is said under the closing block.
   let stopped = false;
   let drawn = 0;
@@ -594,7 +594,7 @@ export function watchProgress(
       if (under) clear();
       else tick();
     },
-    /** The Herdr session pane agents opened in, which a blocked one's line names. */
+    /** The Herdr session TUI agents opened in, which a blocked one's line names. */
     placedIn(session: string) {
       if (!stopped) herdrSession = session;
     },