@agentswf/engine 0.1.0-beta.4 → 0.1.0

package/src/init-command.ts

@@ -1,13 +1,14 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import manifest from "../package.json" with { type: "json" };
+import { type Out, shellWord } from "./command-line";
 import { messageOf } from "./errors";
 import help from "./help/init.txt" with { type: "text" };
-import type { Out } from "./run-commands";
+import { NO_JSON, printRefusal } from "./refusals";
 
 export const initUsage = help.trimEnd();
 
-export type InitCommand = { dir: string; install: boolean };
+type InitCommand = { dir: string; install: boolean };
 
 /** `awf init`: a folder set up for writing workflows. */
 export async function initCommand(
@@ -15,17 +16,13 @@ export async function initCommand(
   cwd: string,
   io: Out & { install?: (dir: string) => Promise<number> },
 ): Promise<number> {
-  let command: InitCommand | "help";
+  let command: InitCommand;
   try {
     command = parseInitCommand(argv, cwd);
   } catch (error) {
-    io.stderr(`awf: ${messageOf(error)}\n\n${initUsage}`);
+    printRefusal(io, NO_JSON, error, "usage", initUsage);
     return 2;
   }
-  if (command === "help") {
-    io.stdout(initUsage);
-    return 0;
-  }
   try {
     return await runInit(command, cwd, io, io.install);
   } catch (error) {
@@ -34,11 +31,10 @@ export async function initCommand(
   }
 }
 
-export function parseInitCommand(argv: readonly string[], cwd: string): InitCommand | "help" {
+export function parseInitCommand(argv: readonly string[], cwd: string): InitCommand {
   let dir: string | undefined;
   let install = true;
   for (const option of argv) {
-    if (option === "-h" || option === "--help") return "help";
     if (option === "--no-install") install = false;
     else if (option.startsWith("-")) throw new Error(`unknown option: ${option}`);
     else if (dir !== undefined) throw new Error(`one directory only, not ${dir} and ${option}`);
@@ -86,7 +82,7 @@ function targetOf(dir: string, path: string): Target {
  * Writes what `awf init` writes into `dir`, and says what it did to each file. Everything that
  * would stop it, such as a package.json that isn't a JSON object, is found before it writes.
  */
-export function initFolder(dir: string): Change[] {
+function initFolder(dir: string): Change[] {
   for (const parent of new Set(COPIED.map(dirname))) {
     const stat = lstatSync(join(dir, parent), { throwIfNoEntry: false });
     if (stat !== undefined && !stat.isDirectory()) {
@@ -213,13 +209,8 @@ function indentOf(text: string): string | number {
   return /^\{\s*\r?\n([ \t]+)"/.exec(text)?.[1] ?? 2;
 }
 
-/** As a shell reads it: bare when that's safe, otherwise single-quoted. */
-function shellWord(word: string): string {
-  return /^[\w./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
-}
-
 /** `awf init`: writes the folder, installs unless told not to, and says what to run next. */
-export async function runInit(
+async function runInit(
   command: InitCommand,
   cwd: string,
   output: { stdout(text: string): void; stderr(text: string): void },

package/src/init-template/hello/workflow.test.ts.template

@@ -1,9 +1,9 @@
 import { expect, test } from "bun:test";
-import { answer, reply, testWorkflow } from "agentswf/testing";
+import { answer, noAnswer, testWorkflow } from "agentswf/testing";
 import hello, { ANSWER } from "./workflow";
 
 test("returns the agent's answer", async () => {
-  const run = await testWorkflow(hello, null, {
+  const run = await testWorkflow(hello, {
     agents: { hello: answer(ANSWER, { answer: 391 }) },
   });
   expect(run.value).toEqual({ answer: 391 });
@@ -11,7 +11,7 @@ test("returns the agent's answer", async () => {
 });
 
 test("an agent that never answers is nudged once, then the result says why", async () => {
-  const run = await testWorkflow(hello, null, { agents: { hello: reply.silent() } });
+  const run = await testWorkflow(hello, { agents: { hello: noAnswer.silent() } });
   expect(run.value).toHaveProperty("unanswered");
   expect(run.turnsOf("hello").map((turn) => turn.nudge)).toEqual([false, true]);
 });

package/src/init-template/hello/workflow.ts.template

@@ -1,21 +1,22 @@
+import { typed } from "agentswf/typebox";
 import { defineWorkflow } from "agentswf/workflow";
 import Type from "typebox";
 
-export const ANSWER = Type.Object({ answer: Type.Integer() }, { additionalProperties: false });
+export const ANSWER = typed(Type.Object({ answer: Type.Integer() }, { additionalProperties: false }));
 
 export default defineWorkflow({
   meta: { name: "hello", description: "Ask one agent a question with a known answer." },
   async run(wf) {
     // A headless agent needs neither Herdr nor a sandbox. Swap in any harness and model your
-    // account has: "claude" in a pane, the default placement, runs on a subscription.
+    // account has: "claude" in its TUI, the default placement, runs on a subscription.
     const agent = await wf.agents.open({
       key: "hello",
       runtime: { harness: "codex", model: "gpt-6-luna", placement: "headless" },
     });
-    const { outcome } = await agent.run<Type.Static<typeof ANSWER>>({
+    const { outcome } = await agent.run({
       prompt: "What is 17 multiplied by 23? Work it out yourself; do not run any code.",
       schema: ANSWER,
-      timeoutMs: 3 * 60_000,
+      timeout: "3m",
     });
     return outcome.answered ? outcome.value : { unanswered: outcome.reason };
   },

package/src/jsonl.ts

@@ -1,16 +1,20 @@
 import { open, readFile } from "node:fs/promises";
 import { isCode } from "./files";
 
-const appendQueues = new Map<string, Promise<void>>();
+const queues = new Map<string, Promise<void>>();
 
-export async function appendLine(path: string, line: string): Promise<void> {
-  const previous = appendQueues.get(path) ?? Promise.resolve();
-  const current = previous.catch(() => undefined).then(() => appendCompleteLine(path, line));
-  appendQueues.set(path, current);
+export function appendLine(path: string, line: string): Promise<void> {
+  return queued(path, () => appendCompleteLine(path, line));
+}
+
+/** Runs `work` once every earlier write queued on `path` has settled, failed or not. */
+export async function queued(path: string, work: () => Promise<void>): Promise<void> {
+  const current = (queues.get(path) ?? Promise.resolve()).catch(() => undefined).then(work);
+  queues.set(path, current);
   try {
     await current;
   } finally {
-    if (appendQueues.get(path) === current) appendQueues.delete(path);
+    if (queues.get(path) === current) queues.delete(path);
   }
 }
 

package/src/keep-alive.ts

@@ -1,7 +1,11 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { EventAgentOpenSpec } from "@agentswf/contract/workflow";
+import { type AgentOpenSpec, positiveDurationMilliseconds } from "@agentswf/contract/workflow";
 
-export type KeepAlive = NonNullable<EventAgentOpenSpec["keepAlive"]>;
+/** `keepAlive` as the engine keeps it: its window in milliseconds. */
+export type KeepAlive = {
+  windowMs?: number;
+  onTimeout?: NonNullable<AgentOpenSpec["keepAlive"]>["onTimeout"];
+};
 
 /** Claude's prompt cache lives an hour for the main conversation on a subscription. */
 export const DEFAULT_WINDOW_MS = 60 * 60_000;
@@ -20,21 +24,20 @@ export function asTimeoutHandler<T>(fn: () => T): T {
   return inHandler.run(true, fn);
 }
 
-/** `keepAlive` as an open gave it, checked: what a typed caller can't get wrong, a plain one can. */
+/** `keepAlive` as an open gave it, checked: a plain caller can get wrong what a typed one can't. */
 export function checkedKeepAlive(key: string, given: unknown): KeepAlive {
   if (typeof given !== "object" || given === null)
-    throw new Error(`agent ${key}: keepAlive is { timeoutMs?, onTimeout? }`);
-  const { timeoutMs, onTimeout } = given as Record<string, unknown>;
-  if (
-    timeoutMs !== undefined &&
-    (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0)
-  )
-    throw new Error(`agent ${key}: keepAlive's timeoutMs is a positive number of milliseconds`);
+    throw new Error(`agent ${key}: keepAlive is { window?, onTimeout? }`);
+  const { window, onTimeout } = given as Record<string, unknown>;
+  const windowMs =
+    window == null
+      ? undefined
+      : positiveDurationMilliseconds(window, `agent ${key}: keepAlive's window`);
   if (onTimeout !== undefined && typeof onTimeout !== "function")
     throw new Error(`agent ${key}: keepAlive's onTimeout is a function`);
   // A copy: a later change to the caller's object would skip this check.
   return {
-    ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    ...(windowMs === undefined ? {} : { windowMs }),
     ...(onTimeout === undefined ? {} : { onTimeout: onTimeout as KeepAlive["onTimeout"] }),
-  } as KeepAlive;
+  };
 }

package/src/logs-command.ts

@@ -1,22 +1,21 @@
 import { homedir } from "node:os";
 import type { LogEventJson, LogsJson, RouteEnds, RunLogLine } from "@agentswf/contract/records";
 import type { JsonObject } from "@agentswf/contract/workflow";
-import { duration } from "./duration";
+import { duration } from "./accounting/format";
+import { command, type Out, parsePlace, type ReadPlace, shellLine } from "./command-line";
+import { parseWait } from "./duration";
 import { messageOf } from "./errors";
+import { exists } from "./files";
 import help from "./help/logs.txt" with { type: "text" };
+import { screenFile } from "./ops";
+import { asksJson, printRefusal, refusalLine } from "./refusals";
 import {
-  clockTime,
-  command,
   continueOf,
   currentStage,
   failed,
-  masked,
+  MAX_WAIT_SECONDS,
   nextLogs,
-  type Out,
-  parsePlace,
-  type ReadPlace,
-  said,
-  shellLine,
+  POLL_MS,
   span,
   stateWord,
 } from "./run-commands";
@@ -30,11 +29,16 @@ import {
   type FileCache,
   type ReadEvent,
   readRun,
+  START,
   timeOf,
 } from "./run-read";
-import { findRun, findRunByRef, type RunStatus } from "./run-state";
+import { checkRunEngine, findRun, findRunByRef, type RunStatus } from "./run-state";
+import { clockTime, masked, said } from "./run-text";
 import { describeActivity } from "./run-view";
 
+/** `awf logs --json`'s `"v"`, which its refusals carry too. */
+export const LOGS_V = 1 satisfies LogsJson["v"];
+
 export const logsUsage = help.trimEnd();
 
 const DEFAULT_LIMIT = 40;
@@ -43,10 +47,8 @@ const DEFAULT_LIMIT = 40;
  * result or a message whole, short of a dumped file. `@{handle}` gives it whole.
  */
 const PAGE_TEXT = 50_000;
-const MAX_WAIT_SECONDS = 300;
 /** After a first new event, how long to wait for the rest of its burst. */
 const SETTLE_MS = 1_000;
-const POLL_MS = 1_000;
 
 type LogsOptions = {
   ref?: string;
@@ -74,10 +76,6 @@ export async function logsCommand(
   clock: LogsClock = REAL_CLOCK,
   home: string = homedir(),
 ): Promise<number> {
-  if (argv.includes("-h") || argv.includes("--help")) {
-    out.stdout(logsUsage);
-    return 0;
-  }
   let place: ReadPlace;
   let json: boolean;
   let options: LogsOptions;
@@ -88,7 +86,7 @@ export async function logsCommand(
     options = parseLogs(parsed.rest);
     if (options.follow && json) throw new Error("--follow is for reading; --json takes --wait");
   } catch (error) {
-    out.stderr(`awf: ${messageOf(error)}\n\n${logsUsage}`);
+    printRefusal(out, { json: asksJson(argv), v: LOGS_V }, error, "usage", logsUsage);
     return 2;
   }
   try {
@@ -96,6 +94,7 @@ export async function logsCommand(
       options.ref === undefined
         ? await findRun(place.runRoot, undefined)
         : { status: await findRunByRef(options.ref, place, home), alsoRunning: [] };
+    await checkRunEngine(status, home);
     const again = shellLine(command(place, "awf", "logs", status.ref));
     let after: Cursor | undefined;
     if (options.after !== undefined) {
@@ -107,18 +106,25 @@ export async function logsCommand(
     }
     const read = new Reader(status, after, clock, options.limit * 2, json);
     // Lines are numbered by their place in the file, past any that were skipped.
-    if (after && after.log > ((await read.next()).log.lines.at(-1)?.number ?? 0)) {
-      throw new DoesNotFit(`cursor ${options.after} does not fit this run; start again: ${again}`);
+    if (after) {
+      const { log } = await read.next();
+      const past = after.run > log.runLines && log.unreadSessions === undefined;
+      if (after.log > (log.lines.at(-1)?.number ?? 0) || past) {
+        throw new DoesNotFit(
+          `cursor ${options.after} does not fit this run; start again: ${again}`,
+        );
+      }
     }
     if (options.handle !== undefined) return await oneEvent(status, options, json, out, again);
     if (options.follow) return await follow(read, options, place, out, clock);
     return await page(read, alsoRunning, options, place, json, out, clock);
   } catch (error) {
     if (error instanceof DoesNotFit) {
+      if (json) out.stdout(refusalLine(LOGS_V, "cursor", error.message));
       out.stderr(error.message);
       return 1;
     }
-    return failed(error, place, out, messageOf(error));
+    return failed(error, place, out, messageOf(error), { json, v: LOGS_V });
   }
 }
 
@@ -147,11 +153,7 @@ function parseLogs(rest: readonly string[]): LogsOptions {
         throw new Error("--limit needs a whole number");
       options.limit = limit;
     } else if (arg === "--wait") {
-      const seconds = Number(value());
-      if (!Number.isFinite(seconds) || seconds < 0 || seconds > MAX_WAIT_SECONDS) {
-        throw new Error(`--wait needs seconds from 0 to ${MAX_WAIT_SECONDS}`);
-      }
-      options.waitSeconds = seconds;
+      options.waitSeconds = parseWait(value(), MAX_WAIT_SECONDS);
       waitGiven = true;
     } else if (arg === "--follow") options.follow = true;
     else if (arg === "--full") options.full = true;
@@ -228,8 +230,9 @@ function operationPlaces(lines: readonly { line: RunLogLine }[]): Places {
 
 function agentOf(event: ReadEvent, places: Places): string | undefined {
   if (event.source === "activity") return event.agent;
+  if (event.source === "run") return event.line.agent;
   if ("agent" in event.line && event.line.agent) return event.line.agent;
-  // A session a headless turn named names its operation, and so its agent.
+  // A line that names only its operation, such as a message's delivery, is its operation's agent's.
   return "operationId" in event.line && event.line.operationId
     ? places.agent.get(event.line.operationId)
     : undefined;
@@ -239,12 +242,15 @@ function stageOf(event: ReadEvent, places: Places): string | undefined {
   if (event.source === "activity") {
     return event.operation ? places.stage.get(event.operation) : undefined;
   }
+  if (event.source === "run") {
+    return event.line.operation ? places.stage.get(event.line.operation) : undefined;
+  }
   return "stage" in event.line ? event.line.stage : undefined;
 }
 
 /** The agents a messaging line is between, so `--agent` follows it from either side. */
 function sidesOf(event: ReadEvent): readonly string[] {
-  if (event.source === "activity") return [];
+  if (event.source !== "log") return [];
   const { line } = event;
   switch (line.kind) {
     case "route-opened":
@@ -262,14 +268,32 @@ function sidesOf(event: ReadEvent): readonly string[] {
   }
 }
 
+/**
+ * The `run.jsonl` lines text leaves out: an agent's first session, which its opening and first turn
+ * already stand for, unless it is a fork's, made apart from any turn.
+ */
+function quietSessions(read: Read): Set<number> {
+  const forked = new Set<string>();
+  for (const { line } of read.log.lines) if (line.kind === "agent-forked") forked.add(line.agent);
+  const quiet = new Set<number>();
+  const seen = new Set<string>();
+  for (const { number, line } of read.log.named) {
+    if (!seen.has(line.agent) && !forked.has(line.agent)) quiet.add(number);
+    seen.add(line.agent);
+  }
+  return quiet;
+}
+
 function kept(read: Read, options: LogsOptions, json = false) {
   const stages = operationPlaces(read.log.lines);
+  const quiet = json ? new Set<number>() : quietSessions(read);
   const events = read.events.filter(
     (event) =>
+      !(event.source === "run" && quiet.has(decodeHandleLine(event.handle))) &&
       // A call that has ended shows on its end's line, with its input; `--json` keeps both.
       !(
         !json &&
-        event.source !== "activity" &&
+        event.source === "log" &&
         event.line.kind === "tool-called" &&
         stages.calls.get(event.line.call)?.ended
       ) &&
@@ -281,6 +305,11 @@ function kept(read: Read, options: LogsOptions, json = false) {
   return { events, stages };
 }
 
+function decodeHandleLine(handle: string): number {
+  const decoded = decodeHandle(handle);
+  return decoded?.kind === "run" ? decoded.line : 0;
+}
+
 function sameLine(a: ReadEvent, b: ReadEvent): boolean {
   const first = decodeHandle(a.handle);
   const second = decodeHandle(b.handle);
@@ -348,6 +377,7 @@ async function page(
     }
   }
   const stage = currentStage(status, read.log.lines);
+  const screens = await keptScreens(status.run.dir, shown);
   const filters = [
     ...(options.agent ? ["--agent", options.agent] : []),
     ...(options.stage ? ["--stage", options.stage] : []),
@@ -359,7 +389,7 @@ async function page(
   if (json) {
     const { started, ended } = span(status, clock.now());
     const document: LogsJson = {
-      v: 1,
+      v: LOGS_V,
       run: {
         ref: status.ref,
         state: status.state,
@@ -368,7 +398,7 @@ async function page(
         ambiguous: alsoRunning.length > 0,
         ...(status.state !== "running" && ended !== undefined ? { duration: ended - started } : {}),
       },
-      events: shown.map((event) => publish(event, stages, PAGE_TEXT)),
+      events: shown.map((event) => publish(event, stages, screens, PAGE_TEXT)),
       cursor: encodeCursor(cursor),
       more: { ...(older ? { older: true } : {}), ...(newer ? { newer: true } : {}) },
       ...(next ? { next } : {}),
@@ -380,6 +410,11 @@ async function page(
   const lines: string[] = [
     header(status, stage, lastAt ? Date.parse(timeOf(lastAt.line)) : undefined),
   ];
+  if (read.log.unreadSessions !== undefined) {
+    lines.push(
+      `note: run.jsonl could not be read, so no agent's activity shows: ${said(read.log.unreadSessions)}`,
+    );
+  }
   if (alsoRunning.length > 0) {
     const count = alsoRunning.length + (status.state === "running" ? 1 : 0);
     lines.push(`note: ${count} runs running; also ${alsoRunning.join(", ")}`);
@@ -388,12 +423,12 @@ async function page(
     const of = options.agent ? ` for ${options.agent}` : "";
     // A cut read has more than any --limit reaches: paging from the start reads it all.
     const more = read.cut
-      ? `from the start: ${shellLine([...command(place, "awf", "logs", status.ref), ...filters, "--after", encodeCursor({ log: 0, files: {} })])}`
+      ? `from the start: ${shellLine([...command(place, "awf", "logs", status.ref), ...filters, "--after", encodeCursor(START)])}`
       : "raise --limit for more";
     const total = read.cut ? `the last ${events.length} read` : `${events.length}`;
     lines.push(`(showing ${shown.length} of ${total}${of}; ${more})`);
   }
-  lines.push(...shown.map((event) => describeEvent(event, stages)));
+  lines.push(...shown.map((event) => describeEvent(event, stages, screens)));
   lines.push(
     trailer(
       status,
@@ -422,7 +457,8 @@ async function follow(
     const { events, stages } = kept(read, options);
     // Without a cursor it starts from the last `--limit`, as a page would.
     const shown = first && !reader.from ? events.slice(-options.limit) : events;
-    for (const event of shown) out.stdout(describeEvent(event, stages));
+    const screens = await keptScreens(reader.status.run.dir, shown);
+    for (const event of shown) out.stdout(describeEvent(event, stages, screens));
     cursor = read.cursor;
     // A read that stopped short goes on at once.
     if (!read.more) {
@@ -449,34 +485,38 @@ async function oneEvent(
   const handle = decodeHandle(options.handle!);
   if (!handle) throw missing;
   // Read from where the handle points, and only its file.
+  const none = Number.MAX_SAFE_INTEGER;
   const read = await readRun(
     status.run.dir,
     status.run.record.cwd,
     handle.kind === "event"
-      ? { log: handle.line - 1, files: {} }
-      : { log: Number.MAX_SAFE_INTEGER, files: { [handle.file]: handle.offset } },
+      ? { log: handle.line - 1, run: none, files: {} }
+      : handle.kind === "run"
+        ? { log: none, run: handle.line - 1, files: {} }
+        : { log: none, run: none, files: { [handle.file]: handle.offset } },
     {
       ended: status.state !== "running",
       full: options.full || json,
-      only: handle.kind === "event" ? "" : handle.file,
+      only: handle.kind === "activity" ? handle.file : "",
     },
   );
   const stages = operationPlaces(read.log.lines);
   const event = read.events.find((each) => each.handle === encodeHandle(handle));
   if (!event) throw missing;
+  const screens = await keptScreens(status.run.dir, [event]);
   if (json) {
     const document: LogsJson = {
-      v: 1,
+      v: LOGS_V,
       run: { ref: status.ref, state: status.state, checked: status.checked },
-      events: [publish(event, stages)],
+      events: [publish(event, stages, screens)],
     };
     out.stdout(JSON.stringify(document, null, 2));
     return 0;
   }
-  const lines = [describeEvent(event, stages)];
+  const lines = [describeEvent(event, stages, screens)];
   if (options.full) {
     lines.unshift(
-      `(${event.source === "activity" ? "native text" : "the log's line"}; common credential shapes are masked)`,
+      `(${{ activity: "native text", log: "the log's line", run: "run.jsonl's line" }[event.source]}; common credential shapes are masked)`,
     );
     const text =
       event.source === "activity" ? event.text : JSON.stringify(masked(event.line), null, 2);
@@ -516,7 +556,12 @@ function trailer(
 }
 
 /** An event as `--json` publishes it: the line's own fields, or the activity, with its keys. */
-function publish(event: ReadEvent, stages: Places, limit = Number.POSITIVE_INFINITY): LogEventJson {
+function publish(
+  event: ReadEvent,
+  stages: Places,
+  screens: Screens,
+  limit = Number.POSITIVE_INFINITY,
+): LogEventJson {
   if (event.source === "activity") {
     const stage = event.operation ? stages.stage.get(event.operation) : undefined;
     return {
@@ -530,24 +575,60 @@ function publish(event: ReadEvent, stages: Places, limit = Number.POSITIVE_INFIN
       ...(event.text === undefined ? {} : { text: masked(event.text, limit) as string }),
     };
   }
+  if (event.source === "run") {
+    return { handle: event.handle, ...(masked(event.line, limit) as typeof event.line) };
+  }
   const { version: _version, ...fields } = event.line;
   return {
     handle: event.handle,
     at: event.at,
     ...(masked(fields, limit) as typeof fields),
     ...("operationId" in fields ? { operation: fields.operationId } : {}),
+    ...screenOf(event, screens),
   };
 }
 
-/** `@e216 09:27:02 fix  fixer  turn ended  answered  1m48s`. */
-function describeEvent(event: ReadEvent, stages: Places): string {
+/** The screens kept for the operations of the events shown, by operation id. */
+type Screens = ReadonlyMap<string, string>;
+
+/** A turn or compaction that ended without an answer, and the file its screen would be kept in. */
+function screenOf(event: ReadEvent, screens: Screens): { screen?: string } {
+  if (event.source !== "log") return {};
+  const { line } = event;
+  if (line.kind !== "turn" && line.kind !== "compact") return {};
+  const screen = screens.get(line.operationId);
+  return screen ? { screen } : {};
+}
+
+async function keptScreens(runDir: string, events: readonly ReadEvent[]): Promise<Screens> {
+  const screens = new Map<string, string>();
+  await Promise.all(
+    events.map(async (event) => {
+      if (event.source !== "log") return;
+      const { line } = event;
+      if (line.kind !== "turn" && line.kind !== "compact") return;
+      if (line.outcome === "answered" || line.outcome === "cancelled") return;
+      const file = screenFile(runDir, line.operationId);
+      if (await exists(file)) screens.set(line.operationId, file);
+    }),
+  );
+  return screens;
+}
+
+/** `@e216 09:27:02 fix  fixer  turn ended  answered  1m 48s`. */
+function describeEvent(event: ReadEvent, stages: Places, screens: Screens): string {
   const agent = agentOf(event, stages);
   const where = [stageOf(event, stages), agent && said(agent, 60)].filter(Boolean).join("  ");
   const what =
     event.source === "activity"
       ? describeActivity(event.activity)
-      : describeLine(event.line, stages);
-  return `@${event.handle} ${clockTime(event.at)} ${where ? `${where}  ` : ""}${what}`;
+      : event.source === "run"
+        ? `session ${event.line.harness} ${event.line.session}`
+        : describeLine(event.line, stages);
+  const { screen } = screenOf(event, screens);
+  return `@${event.handle} ${clockTime(event.at)} ${where ? `${where}  ` : ""}${what}${
+    screen ? `  screen: ${screen}` : ""
+  }`;
 }
 
 function describeLine(line: RunLogLine, places: Places): string {
@@ -573,8 +654,8 @@ function describeLine(line: RunLogLine, places: Places): string {
           : "";
       return `${operation(line.kind)} ended  ${line.outcome}${took}`;
     }
-    case "session-known":
-      return `session ${line.session.harness} ${line.session.id}`;
+    case "sandbox-opened":
+      return `sandbox ${said(line.key, 60)} opened  ${line.provider}`;
     case "agent-opened":
       return `opened  ${line.harness}${line.caller ? "  (the calling session)" : ""}`;
     case "agent-stopped":

package/src/message-operation.ts

@@ -31,12 +31,14 @@ export async function superviseMessageOperation(options: {
   event?(event: LivenessEvent): void;
   phase?(phase: OperationPhase, reason?: string, until?: number): void;
   delivered?(at: number): void;
+  /** Keeps what its turn shows when it ends without an answer, before the turn is released. */
+  keepScreen?(turn: HarnessTurn): Promise<void>;
   policy?: LivenessPolicy;
   now?: () => number;
 }): Promise<SupervisedOutcome> {
   const now = options.now ?? Date.now;
   const policy = options.policy ?? DEFAULT_LIVENESS_POLICY;
-  const charges: number[] = [];
+  const reportedCosts: number[] = [];
   let sequence = 0;
   let deliveredAt: number | undefined;
   let stop: OperationStop | undefined;
@@ -63,7 +65,7 @@ export async function superviseMessageOperation(options: {
     kind,
     reason,
     cleanupUnresolved: false,
-    charges,
+    reportedCosts,
     ...(deliveredAt === undefined ? {} : { deliveredAt }),
     settledAt:
       kind === "timed-out"
@@ -139,7 +141,7 @@ export async function superviseMessageOperation(options: {
     void turn.settled.then(
       (value) => {
         outcome = value;
-        charges.push(...value.chargesUsd);
+        reportedCosts.push(...value.reportedCostsUsd);
         changed();
       },
       (error: unknown) => {
@@ -251,6 +253,7 @@ export async function superviseMessageOperation(options: {
   emit("releasing");
   if (turn) {
     const answered = result.kind === "answered";
+    if (!answered && result.kind !== "cancelled") await options.keepScreen?.(turn);
     const until = bound(answered);
     const release = await Promise.race([
       turn.release(stop?.reason ?? result.reason, until, { answered }).catch(() => undefined),

package/src/messaging/limits.ts

@@ -12,14 +12,14 @@ export const MESSAGE_LIMITS: MessageLimits = {
 
 /**
  * Where an asker may wait for an answer, by harness and placement: on where M2 passed
- * (`docs/findings/messaging-m2.md`), off elsewhere. A pane that is `confirmed` waits only where it
+ * (`docs/findings/messaging-m2.md`), off elsewhere. A TUI that is `confirmed` waits only where it
  * confirms what it was sent, as `wfa waiting` needs. The fake harness always may. cursor is off:
  * its turns ran past their deadline in M2.
  */
-export const AWAIT_REPLY: Readonly<Record<string, { headless?: true; pane?: true | "confirmed" }>> =
+export const AWAIT_REPLY: Readonly<Record<string, { headless?: true; tui?: true | "confirmed" }>> =
   {
-    fake: { headless: true, pane: true },
-    claude: { headless: true, pane: "confirmed" },
+    fake: { headless: true, tui: true },
+    claude: { headless: true, tui: "confirmed" },
     codex: { headless: true },
     pi: { headless: true },
   };