@llm4ts/runner 2.22.2 → 2.24.0

package/src/Profile.ts

@@ -3,7 +3,9 @@ import * as Schema from "effect/Schema"
 import type { FlowError } from "@llm4ts/flow/FlowError"
 import type { FlowEvent, Timed } from "@llm4ts/flow/FlowEvents"
 import { readTrace } from "@llm4ts/flow/Replay"
-import { treeInputsOfTrace, type TreeInput } from "./AgentTree.ts"
+import { duration, treeInputsOfTrace, type TreeInput } from "./AgentTree.ts"
+
+export { duration }
 import { formatCount } from "./Terminal.ts"
 import {
   resolveTraceTarget,
@@ -47,7 +49,11 @@ export const TurnStats = Schema.Struct({
   lastPrompt: Schema.optionalKey(Schema.Int),
   maxPrompt: Schema.optionalKey(Schema.Int),
   /** The last prompt is more than three times the first. */
-  promptGrowth: Schema.Boolean
+  promptGrowth: Schema.Boolean,
+  /** Tool calls per finished turn: each is a model round trip. */
+  avgSteps: Schema.Number,
+  /** The model's own time per round trip: a turn's time less its tools, over its steps + 1. */
+  avgStepMs: Ms
 })
 export type TurnStats = typeof TurnStats.Type
 
@@ -118,6 +124,8 @@ export const ProfileReport = Schema.Struct({
   models: Schema.Array(ModelRow),
   gates: Schema.Array(GateRow),
   tools: Schema.Array(CountRow),
+  /** Coder tool time by kind of work: explore, edit, test, build, install, git, other. */
+  toolCategories: Schema.Array(CountRow),
   waits: Schema.Array(CountRow),
   /** Timed on the run's events, in no story: the run's own planning, or a seat no story owns. */
   outside: Schema.Array(CountRow),
@@ -450,7 +458,20 @@ export const profileOf = (inputs: ReadonlyArray<TreeInput>): ProfileReport => {
       ms: sum(items.map((item) => item.event.ms))
     }))
   const tools = counted("tool")
+  const toolCategories = [
+    ...groupBy(
+      allTimed.filter((item) => item.event.kind === "tool" && item.event.category !== undefined),
+      (item) => item.event.category ?? ""
+    ).entries()
+  ]
+    .map(([label, items]) => ({
+      label,
+      count: items.length,
+      ms: sum(items.map((item) => item.event.ms))
+    }))
+    .sort((left, right) => right.ms - left.ms)
   const waits = counted("wait")
+  const steps = stepStats(estimated ? [] : [...lanes.values()].flatMap(turnSteps))
   const outside = [
     ...groupBy(
       allTimed.filter((item) => item.event.lane === undefined),
@@ -485,12 +506,49 @@ export const profileOf = (inputs: ReadonlyArray<TreeInput>): ProfileReport => {
     models,
     gates,
     tools,
+    toolCategories,
     waits,
     outside,
-    findings: findingsOf({ stories, models, gates, tools, waits, merges, storyTime, estimated })
+    findings: findingsOf({
+      steps,
+      toolCategories,
+      stories,
+      models,
+      gates,
+      tools,
+      waits,
+      merges,
+      storyTime,
+      estimated
+    })
   }
 }
 
+const stepStats = (
+  turns: ReadonlyArray<{ readonly steps: number; readonly stepMs: number }>
+): { readonly avgSteps: number; readonly avgStepMs: number } => ({
+  avgSteps: average(turns.map((turn) => turn.steps)) ?? 0,
+  avgStepMs: average(turns.map((turn) => turn.stepMs)) ?? 0
+})
+
+/** Each finished coder turn's steps (its tool calls) and model time per step. */
+const turnSteps = (
+  lane: Lane
+): ReadonlyArray<{ readonly steps: number; readonly stepMs: number }> => {
+  const tools = lane.timed.filter((item) => item.event.kind === "tool")
+  return lane.timed
+    .filter((item) => item.event.kind === "model" && item.event.label === "coder")
+    .map((turn) => {
+      const start = turn.at - turn.event.ms
+      const inside = tools.filter((tool) => tool.at > start && tool.at <= turn.at)
+      const toolMs = sum(inside.map((tool) => tool.event.ms))
+      return {
+        steps: inside.length,
+        stepMs: Math.max(0, turn.event.ms - toolMs) / (inside.length + 1)
+      }
+    })
+}
+
 const storyProfile = (
   lane: Lane,
   lastAt: number,
@@ -540,6 +598,7 @@ const storyProfile = (
       ...(firstPrompt === undefined ? {} : { firstPrompt }),
       ...(lastPrompt === undefined ? {} : { lastPrompt }),
       ...(maxPrompt === undefined ? {} : { maxPrompt }),
+      ...stepStats(estimated ? [] : turnSteps(lane)),
       promptGrowth:
         firstPrompt !== undefined &&
         lastPrompt !== undefined &&
@@ -551,24 +610,16 @@ const storyProfile = (
 
 // ── words ───────────────────────────────────────────────────────────────────
 
-/** `20s`, `4m00s`, `1h02m`. */
-export const duration = (ms: number): string => {
-  const seconds = Math.round(ms / 1_000)
-  if (seconds < 60) {
-    return `${seconds}s`
-  }
-  const minutes = Math.floor(seconds / 60)
-  if (minutes < 60) {
-    return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`
-  }
-  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`
-}
+const stepsText = (steps: number): string =>
+  `${Number.isInteger(steps) ? steps : steps.toFixed(1)} step${steps === 1 ? "" : "s"}`
 
 const share = (ms: number, of: number): string => (of <= 0 ? "" : `${Math.round((ms / of) * 100)}%`)
 
 const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? "" : "s"}`
 
 const findingsOf = (facts: {
+  readonly steps: { readonly avgSteps: number; readonly avgStepMs: number }
+  readonly toolCategories: ReadonlyArray<CountRow>
   readonly stories: ReadonlyArray<StoryProfile>
   readonly models: ReadonlyArray<ModelRow>
   readonly gates: ReadonlyArray<GateRow>
@@ -589,7 +640,11 @@ const findingsOf = (facts: {
       ms,
       text:
         role === "coder"
-          ? `coder turns: ${calls}, ${ofStories(ms)}, avg ${duration(ms / calls)}${first}`
+          ? `coder turns: ${calls}, ${ofStories(ms)}, avg ${duration(ms / calls)}${first}${
+              facts.steps.avgSteps > 0
+                ? `, ${stepsText(facts.steps.avgSteps)} per turn, ${duration(facts.steps.avgStepMs)} of model per step`
+                : ""
+            }`
           : `${role} calls: ${calls}, ${ofStories(ms)}, avg ${duration(ms / calls)}${first}`
     }
   })
@@ -601,10 +656,16 @@ const findingsOf = (facts: {
         row.failed === 0 ? "" : `, ${row.failed} failed`
       }`
     })),
-    ...facts.tools.map((row) => ({
-      ms: row.ms,
-      text: `coder tool \`${row.label}\`: ${plural(row.count, "call")}, ${ofStories(row.ms)}`
-    })),
+    // By kind of work when the trace has it (2.23), else by tool name.
+    ...(facts.toolCategories.length > 0
+      ? facts.toolCategories.map((row) => ({
+          ms: row.ms,
+          text: `coder tools, ${row.label}: ${plural(row.count, "call")}, ${ofStories(row.ms)}`
+        }))
+      : facts.tools.map((row) => ({
+          ms: row.ms,
+          text: `coder tool \`${row.label}\`: ${plural(row.count, "call")}, ${ofStories(row.ms)}`
+        }))),
     ...facts.waits.map((row) => ({
       ms: row.ms,
       text: `waiting for the ${row.label}: ${row.count}×, ${ofStories(row.ms)}`
@@ -708,6 +769,8 @@ export const renderProfile = (report: ProfileReport): string => {
         "other",
         "turns",
         "avg turn",
+        "steps/turn",
+        "model/step",
         "prompt ×"
       ],
       report.stories.map((story) => [
@@ -723,6 +786,8 @@ export const renderProfile = (report: ProfileReport): string => {
         duration(story.time.unaccounted),
         String(story.turns.count),
         duration(story.turns.avgMs),
+        story.turns.avgSteps === 0 ? "" : story.turns.avgSteps.toFixed(1),
+        story.turns.avgSteps === 0 ? "" : duration(story.turns.avgStepMs),
         story.turns.firstPrompt !== undefined &&
         story.turns.lastPrompt !== undefined &&
         story.turns.firstPrompt > 0
@@ -797,6 +862,21 @@ export const renderProfile = (report: ProfileReport): string => {
               String(row.failed)
             ])
           )
+        ]),
+    ...(report.toolCategories.length === 0
+      ? []
+      : [
+          "",
+          "Coder tools by kind",
+          ...table(
+            ["kind", "calls", "total", "avg"],
+            report.toolCategories.map((row) => [
+              row.label,
+              String(row.count),
+              duration(row.ms),
+              duration(row.ms / row.count)
+            ])
+          )
         ])
   ].join("\n")
 }

package/src/Transcripts.ts

@@ -0,0 +1,274 @@
+import { appendFileSync, mkdirSync, readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { summariseToolArgs } from "@llm4ts/flow/Activity"
+import { TranscriptEntry, type TranscriptSink } from "@llm4ts/flow/Transcript"
+import { duration } from "./AgentTree.ts"
+
+/**
+ * Transcripts on disk (`llm4ts run --transcript`): one JSON line per entry,
+ * one file per story (`<lane>.jsonl`) and `run.jsonl` for the rest, under
+ * `.llm4ts/transcripts/<run-id>/`. They hold the customer's code and the
+ * model's replies, so only their owner can read them, and a write that fails
+ * never fails the run.
+ */
+
+/** `LLM4TS_TRANSCRIPT=on` (what `--transcript` sets); also `1`, `true`, `yes`. */
+export const transcriptsWanted = (
+  environment: Readonly<Record<string, string | undefined>>
+): boolean => /^(on|1|true|yes)$/iu.test(environment.LLM4TS_TRANSCRIPT?.trim() ?? "")
+
+export const transcriptFileOf = (lane: string | undefined): string =>
+  `${(lane ?? "run").replace(/[^A-Za-z0-9._-]/gu, "_")}.jsonl`
+
+const encode = Schema.encodeSync(Schema.fromJsonString(TranscriptEntry))
+
+export const nodeTranscriptSink = (directory: string): TranscriptSink => {
+  let made = false
+  return {
+    write: (lane, entry) =>
+      Effect.sync(() => {
+        try {
+          if (!made) {
+            mkdirSync(directory, { recursive: true, mode: 0o700 })
+            made = true
+          }
+          appendFileSync(join(directory, transcriptFileOf(lane)), `${encode(entry)}\n`, {
+            mode: 0o600
+          })
+        } catch {
+          // A transcript is a window on the run, never a reason to stop it.
+        }
+      })
+  }
+}
+
+// ── reading ─────────────────────────────────────────────────────────────────
+
+export interface TranscriptView {
+  readonly width: number
+  /** Only calls made in this role (coder, reviewer, judge, …). */
+  readonly role?: string
+  /** Only calls served by this executor. */
+  readonly executor?: string
+  /** Keep the last lines only. */
+  readonly last?: number
+  /** Where the clock in the headers starts; the first entry's time by default. */
+  readonly since?: number
+}
+
+const clockOf = (ms: number): string => {
+  const seconds = Math.max(0, Math.floor(ms / 1_000))
+  return [Math.floor(seconds / 3_600), Math.floor(seconds / 60) % 60, seconds % 60]
+    .map((part) => String(part).padStart(2, "0"))
+    .join(":")
+}
+
+const cut = (line: string, width: number): string =>
+  [...line].length <= width ? line : `${[...line].slice(0, Math.max(0, width - 1)).join("")}…`
+
+/** `text` as lines of at most `width`, the first after `prefix`, the rest indented. */
+const wrapped = (prefix: string, text: string, width: number, limit = Infinity): Array<string> => {
+  const room = Math.max(10, width - prefix.length)
+  const lines: Array<string> = []
+  for (const paragraph of text.split("\n")) {
+    let line = ""
+    for (const word of paragraph.split(/\s+/u).filter((part) => part.length > 0)) {
+      if (line.length > 0 && line.length + 1 + word.length > room) {
+        lines.push(line)
+        line = ""
+      }
+      line = line.length === 0 ? cut(word, room) : `${line} ${word}`
+    }
+    lines.push(line)
+  }
+  const kept = lines.filter((line, index) => line.length > 0 || index < lines.length - 1)
+  const shown = kept.slice(0, limit)
+  const more = kept.length - shown.length
+  return [
+    ...shown.map((line, index) => `${index === 0 ? prefix : " ".repeat(prefix.length)}${line}`),
+    ...(more > 0 ? [`${" ".repeat(prefix.length)}… (${more} more lines)`] : [])
+  ]
+}
+
+const inputLines = 12
+
+/**
+ * A transcript as the tail pane and `watch --tail` show it: each call under
+ * a header (when, who), its input, the reply as one text, every tool with
+ * the gist of its result, and how long the call took.
+ */
+export const renderTranscript = (
+  entries: ReadonlyArray<TranscriptEntry>,
+  view: TranscriptView
+): ReadonlyArray<string> => {
+  const { width } = view
+  const start = view.since ?? entries[0]?.at ?? 0
+  const wanted = new Set(
+    entries.flatMap((entry) =>
+      entry._tag === "Call" &&
+      (view.role === undefined || entry.role === view.role) &&
+      (view.executor === undefined || entry.executor === view.executor)
+        ? [entry.call]
+        : []
+    )
+  )
+  const lines: Array<string> = []
+  let reply: { call: string; text: string } | undefined
+  const flushReply = () => {
+    if (reply !== undefined && reply.text.trim().length > 0) {
+      lines.push(...wrapped("◀ ", reply.text.trim(), width))
+    }
+    reply = undefined
+  }
+  // Only a filter needs the calls' headers; without one every entry shows,
+  // even one passed alone (the tail prints entries as they arrive).
+  const filtering = view.role !== undefined || view.executor !== undefined
+  for (const entry of entries) {
+    if (filtering && !wanted.has(entry.call)) {
+      continue
+    }
+    if (entry._tag !== "Reply") {
+      flushReply()
+    }
+    switch (entry._tag) {
+      case "Call": {
+        const title = `── ${clockOf(entry.at - start)} ${entry.role}${
+          entry.executor === undefined ? "" : ` · ${entry.executor}`
+        } `
+        lines.push(cut(title.padEnd(width, "─"), width))
+        if (entry.system !== undefined) {
+          const [first = "", ...more] = entry.system.split("\n")
+          lines.push(
+            cut(
+              `▶ system: ${first}${more.length === 0 ? "" : ` … (${more.length + 1} lines)`}`,
+              width
+            )
+          )
+        }
+        if (entry.earlier !== undefined && entry.earlier > 0) {
+          lines.push(`▶ (${entry.earlier} earlier messages)`)
+        }
+        lines.push(...wrapped("▶ ", entry.input, width, inputLines))
+        break
+      }
+      case "Reply":
+        reply =
+          reply?.call === entry.call
+            ? { call: entry.call, text: reply.text + entry.text }
+            : { call: entry.call, text: entry.text }
+        break
+      case "Tool":
+        lines.push(cut(`⚙ ${entry.tool} ${summariseToolArgs(entry.args)}`.trimEnd(), width))
+        break
+      case "ToolResult": {
+        const outputLines = entry.output
+          .split("\n")
+          .map((line) => line.trim())
+          .filter((line) => line.length > 0)
+        const gist = outputLines.slice(0, 3).join(" · ")
+        lines.push(
+          cut(
+            `  ↳ ${entry.failed === true ? "failed" : "ok"}${gist.length === 0 ? "" : `: ${gist}`}${
+              outputLines.length > 3 ? " …" : ""
+            }`,
+            width
+          )
+        )
+        break
+      }
+      case "End":
+        lines.push(`  (${duration(entry.ms)}${entry.failed === true ? ", failed" : ""})`)
+        break
+    }
+  }
+  flushReply()
+  return view.last === undefined ? lines : lines.slice(-view.last)
+}
+
+/** How a host reaches a run's transcript files. */
+export interface TranscriptFiles {
+  readonly read: (path: string) => Effect.Effect<string | undefined>
+  /** File names in a directory; none when it does not exist. */
+  readonly list: (directory: string) => ReadonlyArray<string>
+}
+
+const decodeEntry = Schema.decodeUnknownOption(Schema.fromJsonString(TranscriptEntry))
+
+/** A transcript file's entries; a torn last line (a write in progress) is skipped. */
+export const parseTranscript = (text: string): ReadonlyArray<TranscriptEntry> =>
+  text
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .flatMap((line) => {
+      const decoded = decodeEntry(line)
+      return decoded._tag === "Some" ? [decoded.value] : []
+    })
+
+export type TailTarget = { readonly lane: string } | { readonly executor: string }
+
+/**
+ * The entries a tail shows: a story's file, or every file for an executor
+ * (in time order). `undefined` when the run kept no transcript at all.
+ */
+export const loadTranscript = (
+  files: TranscriptFiles,
+  directory: string,
+  target: TailTarget
+): Effect.Effect<ReadonlyArray<TranscriptEntry> | undefined> =>
+  Effect.gen(function* () {
+    const names = files.list(directory).filter((name) => name.endsWith(".jsonl"))
+    if (names.length === 0) {
+      return undefined
+    }
+    const wanted = "lane" in target ? [transcriptFileOf(target.lane)] : names
+    const all: Array<TranscriptEntry> = []
+    for (const name of wanted) {
+      const text = yield* files.read(join(directory, name))
+      all.push(...parseTranscript(text ?? ""))
+    }
+    return "lane" in target ? all : [...all].sort((left, right) => left.at - right.at)
+  })
+
+/**
+ * `rows` lines of a tail, ending `back` lines before its end (scrolled), or
+ * `undefined` when the run has no transcript.
+ */
+export const tailLinesOf = (
+  entries: ReadonlyArray<TranscriptEntry> | undefined,
+  target: TailTarget,
+  role: string | undefined,
+  width: number,
+  rows: number,
+  back = 0
+): ReadonlyArray<string> | undefined => {
+  if (entries === undefined) {
+    return undefined
+  }
+  const lines = renderTranscript(entries, {
+    width,
+    ...(role === undefined ? {} : { role }),
+    ...("executor" in target ? { executor: target.executor } : {})
+  })
+  const end = Math.max(Math.min(rows, lines.length), lines.length - back)
+  return lines.slice(Math.max(0, end - rows), end)
+}
+
+export const nodeTranscriptFiles: TranscriptFiles = {
+  read: (path) =>
+    Effect.sync(() => {
+      try {
+        return readFileSync(path, "utf8")
+      } catch {
+        return undefined
+      }
+    }),
+  list: (directory) => {
+    try {
+      return readdirSync(directory)
+    } catch {
+      return []
+    }
+  }
+}

package/src/Watch.ts

@@ -18,12 +18,22 @@ import {
   onTreeKey,
   reduceTree,
   renderTree,
+  tailTargetOf,
   treeInputsOfTrace,
   type TreeInput,
   type TreeState,
   type TreeView
 } from "./AgentTree.ts"
 import { enterScreen, leaveScreen, makeScreenPainter, nodeTreeKeys } from "./AgentTreeSurface.ts"
+import {
+  loadTranscript,
+  nodeTranscriptFiles,
+  renderTranscript,
+  tailLinesOf,
+  transcriptFileOf,
+  type TailTarget,
+  type TranscriptFiles
+} from "./Transcripts.ts"
 import { nodeListTraces, TraceDirectoryName } from "./Costs.ts"
 import { nodePlainFileStore } from "./NodePlainFileStore.ts"
 
@@ -45,6 +55,8 @@ export interface WatchOptions {
   readonly speed?: number
   /** A live lane with no event for this long is marked idle (`LLM4TS_IDLE_AFTER`). */
   readonly idleAfterMs?: number
+  /** Print this story's or executor's transcript as it grows, instead of the tree. */
+  readonly tail?: string
 }
 
 export interface WatchOutput {
@@ -64,6 +76,8 @@ export interface WatchDependencies {
   readonly output: WatchOutput
   /** Key names as `onTreeKey` reads them: "up", "enter", "q", … */
   readonly keys: Stream.Stream<string>
+  /** A run's transcript files (`--transcript`); the disk by default. */
+  readonly transcripts?: TranscriptFiles
 }
 
 export class WatchTargetMissing extends Schema.TaggedError<WatchTargetMissing>()(
@@ -184,20 +198,42 @@ const readInputs = (
 const pollInterval = Duration.millis(500)
 const replayGapCap = 2_000
 
-const draw = (state: TreeState, view: TreeView, output: WatchOutput, height?: number): string =>
+const draw = (
+  state: TreeState,
+  view: TreeView,
+  output: WatchOutput,
+  height?: number,
+  tail?: ReadonlyArray<string>
+): string =>
   renderTree(state, {
     width: Math.max(90, output.columns() ?? 90),
     colour: output.colour,
     view,
-    ...(height === undefined ? {} : { height })
+    ...(height === undefined ? {} : { height }),
+    ...(tail === undefined ? {} : { tail })
   }).join("\n")
 
 /** A full-screen frame: no taller than the terminal. */
 const screenLines = (
   state: TreeState,
   view: TreeView,
-  output: WatchOutput
-): ReadonlyArray<string> => draw(state, view, output, output.rows()).split("\n")
+  output: WatchOutput,
+  tail?: ReadonlyArray<string>
+): ReadonlyArray<string> => draw(state, view, output, output.rows(), tail).split("\n")
+
+/** Rows the tail pane shows. */
+const tailRows = 16
+
+/** Where a trace's run kept its transcript: `.llm4ts/transcripts/<run-id>/`. */
+const transcriptDirOf = (
+  repo: string,
+  target: WatchTarget,
+  files: PlainFileStoreShape
+): Effect.Effect<string | undefined, FlowError> =>
+  Effect.map(readTrace(files, target.tracePath), (lines) => {
+    const runId = lines[0]?.runId
+    return runId === undefined ? undefined : join(repo, TraceDirectoryName, "transcripts", runId)
+  })
 
 export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function* (
   options: WatchOptions,
@@ -210,6 +246,39 @@ export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function*
       inputs.reduce(reduceTree, start)
     )
 
+  const transcripts = dependencies.transcripts ?? nodeTranscriptFiles
+  const transcriptDir = yield* transcriptDirOf(options.repo, target, files)
+
+  if (options.tail !== undefined) {
+    if (transcriptDir === undefined || transcripts.list(transcriptDir).length === 0) {
+      return yield* WatchTargetMissing.make({
+        message: "no transcript for this run — start it with llm4ts run … --transcript"
+      })
+    }
+    return yield* followTail(options.tail, transcriptDir, transcripts, output, () =>
+      Effect.map(readInputs(target, files), (inputs) =>
+        inputs.some((input) => input._tag === "RunEnded")
+      )
+    )
+  }
+
+  /** The open tail's lines, for the view's selection. */
+  const tailFor = (view: TreeView): Effect.Effect<ReadonlyArray<string> | undefined> => {
+    const selected = tailTargetOf(view)
+    return !view.tail || selected === undefined || transcriptDir === undefined
+      ? Effect.succeed(undefined)
+      : Effect.map(loadTranscript(transcripts, transcriptDir, selected), (entries) =>
+          tailLinesOf(
+            entries,
+            selected,
+            view.tailRole,
+            Math.max(90, output.columns() ?? 90) - 32,
+            tailRows,
+            view.tailBack
+          )
+        )
+  }
+
   if (!output.interactive) {
     const state = yield* Effect.flatMap(readInputs(target, files), fold)
     return yield* output.write(`${draw(state, initialView, output)}\n`)
@@ -264,7 +333,7 @@ export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function*
               ? reduceTree(folded, { _tag: "Tick", at: yield* Clock.currentTimeMillis })
               : folded
           const text = yield* painter.paint(
-            screenLines(state, yield* Ref.get(view), output),
+            screenLines(state, yield* Ref.get(view), output, yield* tailFor(yield* Ref.get(view))),
             `${output.columns()}x${output.rows()}`
           )
           if (text.length > 0) {
@@ -322,3 +391,55 @@ export const nodeWatchDependencies = (
     keys: nodeTreeKeys("detach")
   }
 }
+
+// ── tail ────────────────────────────────────────────────────────────────────
+
+/**
+ * `llm4ts watch --tail <story|executor>`: the transcript printed as it grows,
+ * like `tail -f` — a call's reply streams in as written — until the run ends.
+ * A name with its own file is a story; any other is an executor.
+ */
+const followTail = (
+  name: string,
+  directory: string,
+  transcripts: TranscriptFiles,
+  output: WatchOutput,
+  ended: () => Effect.Effect<boolean, FlowError>
+): Effect.Effect<void, FlowError> =>
+  Effect.gen(function* () {
+    const target: TailTarget = transcripts.list(directory).includes(transcriptFileOf(name))
+      ? { lane: name }
+      : { executor: name }
+    const width = Math.max(60, output.columns() ?? 100)
+    let shown = 0
+    let start: number | undefined
+    const wanted = new Set<string>()
+    let replying: string | undefined
+    while (true) {
+      const done = yield* ended()
+      const entries = (yield* loadTranscript(transcripts, directory, target)) ?? []
+      for (const entry of entries.slice(shown)) {
+        start = start ?? entry.at
+        if (entry._tag === "Call" && ("lane" in target || entry.executor === target.executor)) {
+          wanted.add(entry.call)
+        }
+        if (!wanted.has(entry.call)) {
+          continue
+        }
+        if (entry._tag === "Reply") {
+          // A reply streams: its text as it arrived, on one growing paragraph.
+          yield* output.write(`${replying === entry.call ? "" : "◀ "}${entry.text}`)
+          replying = entry.call
+          continue
+        }
+        const lines = renderTranscript([entry], { width, since: start })
+        yield* output.write(`${replying === undefined ? "" : "\n"}${lines.join("\n")}\n`)
+        replying = undefined
+      }
+      shown = entries.length
+      if (done) {
+        return
+      }
+      yield* Effect.sleep(pollInterval)
+    }
+  })